@xid-kit/core

Cliente de navegador para estado de sesión, acceso JWT de corta duración y utilidades de la API de administración.

Instalar y configurar

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

Para una aplicación de desarrollador en otro origen, configure mode: 'oidc' con issuer, clientId y una redirectUri exacta. Use el modo same-origin únicamente cuando la aplicación enrute los endpoints de autenticación de Core en su origen exacto. XID no tiene credenciales de publishable key.

import { XidClient } from '@xid-kit/core'

const xid = new XidClient({
  mode: 'oidc',
  issuer: 'https://xid.dev',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await xid.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)

Ciclo de vida de la sesión

load() lee /v1/me e hidrata el usuario, la sesión y la organización activa.
signInPassword() establece una sesión con cookie a través del flujo de contraseña de Hosted Auth.
getToken() devuelve un JWT de corta duración para llamadas a la API. Verifícalo sin llamadas de red en tu servidor con JWKS.
setActiveOrganization() cambia el contexto de organización y limpia el caché de tokens antes de recargar el estado.
signOut() revoca la cookie de sesión del navegador.

Utilidades de la API de administración

Los helpers de Management API son exclusivos del servidor o de un origen exactamente igual. Cree un cliente independiente con sk_live_* o sk_test_* en el servidor; el modo OIDC del navegador rechaza estas operaciones.

const management = new XidClient({
  apiUrl: 'https://xid.dev',
  secretKey: process.env.XID_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)

API exportada

Exportar	Tipo	Propósito
`XidClient`	class	Cliente de navegador de nivel superior: load, signIn, getToken, setActiveOrganization, signOut y utilidades de la API de administración
`XidStore`	class	Store reactivo independiente del framework; suscríbete con useSyncExternalStore en los vínculos del framework
`TokenManager`	class	Caché JWT de corta duración y refresco programado (uso avanzado y pruebas)
`XidApiClient`	class	Cliente HTTP para los endpoints /v1/me y de tokens
`XidNetworkError`	class	Lanzado en fallos de transporte: error de red, respuesta no JSON, 5xx sin cuerpo estructurado
`makeXidError`	function	Construye un XidError estructurado para fallos de validación locales sin ida y vuelta de red
`isXidErrorShape`	function	Protector de tipo: verifica si un valor desconocido se ajusta a la forma XidError del wire
`decodeTokenClaims`	function	Decodifica las declaraciones del payload JWT solo para programación de expiración; no verifica la firma
`isTokenExpiring`	function	Devuelve true cuando el token expira dentro de la ventana de tolerancia (predeterminado 10 s)
`SESSION_STATUS`	tupla as const	Valores válidos de estado de sesión: active, pending, expired, removed, ended, revoked
`CLIENT_STATUS`	tupla as const	Valores válidos de estado del cliente: loading, ready, degraded, error
`PACKAGE`	constante de cadena	Identificador de nombre de paquete ‘@xid-kit/core’

Tipos

Tipo	Descripción
`XidUser`	Vista de solo lectura del usuario autenticado (sin secretos ni hashes)
`XidOrganization`	Vista pública de la organización
`XidOrganizationMembership`	Membresía de usuario en una organización con rol y permisos
`XidSession`	Vista de sesión con estado, expiración y organización activa
`XidApiKey`	Clave API sin secreto (vista de lista)
`XidApiKeyWithSecret`	Clave API devuelta una sola vez al crearla; incluye el campo key
`XidPage<T>`	Envoltorio de respuesta con paginación por cursor
`CreateApiKeyInput`	Entrada para createApiKey
`SignInPasswordInput`	Entrada para signInPassword
`SignInResult`	Resultado de signInPassword: siguiente paso o URL de redirección
`SessionStatus`	Unión de valores de SESSION_STATUS
`ClientStatus`	Unión de valores de CLIENT_STATUS
`XidState`	Instantánea completa del estado del SDK suscrita desde XidStore
`XidStateListener`	Tipo de callback para escucha de cambios de estado
`Unsubscribe`	Tipo de retorno de XidStore.subscribe
`GetTokenOptions`	Opciones para getToken: skipCache, leewaySeconds, signal
`XidClientOptions`	Opciones discriminadas del constructor de XidClient: same-origin acepta apiUrl, secretKey, fetcher y now; oidc requiere issuer, clientId y redirectUri.
`TokenResponse`	Forma de la respuesta bruta del endpoint de token
`ClientStateResponse`	Forma de la respuesta bruta de /v1/me
`DecodedTokenClaims`	Declaraciones del payload JWT devueltas por decodeTokenClaims

Documentación relacionada

Vínculos de framework: @xid-kit/react. Verificación en servidor: @xid-kit/backend.