XRP Identity Auth SDK (@xrpl-commons/auth-sdk)

📦 Quick Start (Nuxt)

1. Install

bun add @xrpl-commons/auth-sdk
# or: npm i @xrpl-commons/auth-sdk

2. Configure

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['@xrpl-commons/auth-sdk'],

    xrpIdentity: {
        baseUrl: 'http://localhost:4000', // Your XRP Identity server
        clientId: 'myapp', // Your OAuth client ID
    },
});

3. Use

<script setup>
const { user, login, logout } = useXRPLAuth();
// OR use useAuth() - compatible with @sidebase/nuxt-auth
</script>

<template>
    <div v-if="user">
        <p>{{ user.name }}</p>
        <button @click="logout()">Logout</button>
    </div>
    <button v-else @click="login()">Login</button>
</template>

4. Protect Routes

<script setup>
definePageMeta({
    middleware: 'auth', // or 'admin' for admin-only
});
</script>

That's it! Your app is now connected to XRP Identity.

📚 API Reference

useXRPLAuth() / useAuth()

const {
  // State
  user,              // XRPIdentityUser | null
  status,            // 'loading' | 'authenticated' | 'unauthenticated'
  data,              // Compatible with @sidebase/nuxt-auth
  isAuthenticated,   // boolean
  isAdmin,           // boolean
  loading,           // boolean

  // Actions
  login(returnUrl?),      // Redirect to login
  logout(returnUrl?),     // Logout and redirect
  signIn,                 // Alias for login
  signOut,                // Alias for logout
  refresh(),              // Refresh user data
  apiCall(endpoint, opts), // Make authenticated API call

  // Helpers
  hasRole(role),          // Check single role
  hasAnyRole([roles]),    // Check any role
  hasAllRoles([roles])    // Check all roles
} = useXRPLAuth()

Middleware

// Require authentication
definePageMeta({ middleware: 'auth' });

// Require admin role
definePageMeta({ middleware: 'admin' });

Making API Calls

const { apiCall } = useXRPLAuth()

// Automatically includes auth token
const users = await apiCall('/admin/users')
const client = await apiCall('/admin/clients', { method: 'POST', body: {...} })

🎨 For React / Next.js / Vue

Use the core client directly:

import { createXRPIdentityClient } from '@xrpl-commons/auth-sdk/core';

const auth = createXRPIdentityClient({
    baseUrl: 'http://localhost:4000',
    clientId: 'myapp',
});

// Login
window.location.href = auth.login();

// Get user
const user = await auth.getUser();

// Logout
window.location.href = auth.logout();

// API calls
const data = await auth.apiCall('/admin/users', { accessToken: token });

React Hook Example:

function useAuth() {
  const [user, setUser] = useState(null)
  const client = createXRPIdentityClient({ ... })

  useEffect(() => {
    client.getUser().then(setUser)
  }, [])

  return {
    user,
    login: () => window.location.href = client.login(),
    logout: () => window.location.href = client.logout()
  }
}

🔒 How It Works

┌──────────────┐         ┌──────────────────┐         ┌──────────────┐
│   Your App   │────────▶│ xrp-identity-    │────────▶│ XRP Identity │
│ (Nuxt/React) │         │ connect (SDK)    │   HTTP  │   Backend    │
└──────────────┘         └──────────────────┘         └──────────────┘
                         Just redirects                Does everything:
                         and fetches!                  - OAuth flows
                                                       - Sessions
                                                       - Tokens
                                                       - User data

Backend does: OAuth, PKCE, sessions, tokens, user management
Package does: Redirect to backend + fetch user

Single source of truth. Zero code duplication.

🚀 Publishing / Updating on npm (Maintainers)

This repo includes an interactive publisher that reads your npm token from env and writes auth to a temporary .npmrc (it does not modify repo files).

Prereqs

• Set an npm token in your shell:
  • export NPM_TOKEN=... (preferred), or export NODE_AUTH_TOKEN=...
• Ensure you're logged into the right npm org (if applicable) and have publish rights for @xrpl-commons/auth-sdk.

Publish a new version

From the repo root:

NPM_TOKEN=... bun run publish:auth-sdk

It will:

• Ask which version bump to apply (patch/minor/major/custom) and optionally sync versions across this monorepo
• Run the SDK build
• Publish with an npm dist-tag (latest for stable, next for prereleases)

CI / non-interactive publish

NPM_TOKEN=... bun run publish:auth-sdk -- --yes --tag latest

Verify on npm

npm view @xrpl-commons/auth-sdk version
npm view @xrpl-commons/auth-sdk dist-tags