Skip to Content

SDK de JavaScript (@auris/js)

@auris/js v0.1.0

@auris/js es el SDK base para Auris. Es una librería sin dependencias que funciona en navegadores, Node.js 18+ y edge runtimes (Cloudflare Workers, Vercel Edge, Deno). Se incluyen tanto builds ESM (import) como CJS (require), junto con declaraciones TypeScript completas.

Los SDK de React y Next.js son envoltorios ligeros alrededor de @auris/js. Si estás construyendo una aplicación agnóstica de framework o necesitas la API de más bajo nivel, usa este paquete directamente.

Instalación

npm install @auris/js

AurisClient

AurisClient es el punto de entrada principal. Crea una instancia por aplicación.

Constructor

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.tudominio.com',       // Tu dominio de tenant de Auris (requerido)
  clientId: 'app_xxxxx',              // Client ID de la aplicación desde la Consola (requerido)
  redirectUri: 'http://localhost:3000/callback', // Debe coincidir con una URL de callback registrada (requerido para flujos PKCE)
  tenant: 'mi-tenant',                // Identificador del tenant enviado como encabezado x-tenant (opcional)
  storage: 'localStorage',            // Almacenamiento de tokens: 'localStorage' | 'sessionStorage' | 'memory' | instancia TokenStore
  autoRefresh: true,                  // Refrescar access tokens automáticamente antes de que expiren (predeterminado: true)
  scope: 'openid profile email',      // Scopes OAuth2 a solicitar (predeterminado: 'openid profile email')
})

Métodos de autenticación

loginWithRedirect(options?)

Inicia el flujo OAuth2 Authorization Code con PKCE. Genera un code verifier y challenge, almacena el verifier y redirige el navegador a la página de login alojada de Auris.

await auris.loginWithRedirect({
  redirectUri: 'http://localhost:3000/callback', // Sobrescribe la opción de constructor
  scope: 'openid profile email offline_access',
  state: { returnTo: '/dashboard' },
})

handleRedirectCallback()

Llama a este método en tu página de callback. Intercambia el código de autorización por tokens y restaura el estado guardado.

const result = await auris.handleRedirectCallback()
console.log(result.appState) // { returnTo: '/dashboard' }

loginWithMagicLink(options)

Envía un email de magic link al usuario. No redirige al navegador.

await auris.loginWithMagicLink({
  email: '[email protected]',
  redirectUri: 'http://localhost:3000/callback',
})

logout(options?)

Cierra la sesión del usuario localmente y opcionalmente redirige a la URL de cierre de sesión de Auris.

await auris.logout({
  returnTo: 'http://localhost:3000',
  federated: true, // También cierra la sesión en Keycloak
})

Métodos de tokens

getAccessToken()

Devuelve el access token actual. Si el token ha expirado y autoRefresh está habilitado, lo refresca automáticamente.

const token = await auris.getAccessToken()
// Úsalo en solicitudes a la API:
fetch('/api/data', {
  headers: { Authorization: `Bearer ${token}` }
})

getUser()

Devuelve la información del usuario actual desde el ID token almacenado en caché.

const user = await auris.getUser()
console.log(user?.email, user?.roles)

Comprobación de permisos

hasPermission(permission)

const canEdit = await auris.hasPermission('documents:write')

checkFga(params)

Comprueba una relación de autorización de grano fino:

const result = await auris.checkFga({
  user: `user:${userId}`,
  relation: 'editor',
  object: 'document:readme',
})
if (result.allowed) { /* ... */ }

Tokens M2M (client_credentials)

const aurisM2M = new AurisClient({
  domain: 'auth.tudominio.com',
  clientId: 'app_xxxxx',
  // No se necesita redirectUri para M2M
})
 
const token = await aurisM2M.getM2MToken({
  clientSecret: process.env.AURIS_CLIENT_SECRET,
  scope: 'manage:users',
})

Verificación de webhooks

const isValid = auris.verifyWebhookSignature({
  payload: req.body,
  signature: req.headers['x-auris-signature'],
  secret: process.env.WEBHOOK_SECRET,
})

En entornos edge y Node.js sin localStorage, el SDK recurre automáticamente al almacenamiento en memoria. Pasa storage: 'memory' explícitamente si quieres activar este comportamiento en entornos de navegador.

Arquitectura