@xid-kit/backend

Verificación JWT sin llamadas de red, autenticación de solicitudes y validación de firma de webhooks para entornos edge y servidor.

Compatibilidad de entorno de ejecución

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

Cloudflare Workers (destino principal)
Entornos de ejecución Vercel Edge Runtime y Node.js
Cualquier entorno compatible con Web Crypto (Bun, Deno)

authenticateRequest

Verifica un JWT Bearer o explícito de la aplicación en una Request entrante. Una sesión de navegador Core del mismo origen se intercambia primero mediante /v1/sessions/token; la cookie de renovación opaca nunca se verifica localmente.

import { authenticateRequest } from '@xid-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
})
if (state.isSignedIn) {
  console.log(state.userId)
}

verifyToken

Verificación de token de acceso de bajo nivel. Pasa jwtKey desde JWKS para omitir ida y vuelta de red en arranque en frío. Los fallos esperados devuelven un tipo Result, no una excepción.

import { verifyToken } from '@xid-kit/backend'

const result = await verifyToken(token, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
  audience: 'my-api',
})
if (!result.ok) return new Response('Unauthorized', { status: 401 })

verifyWebhook

Valida firmas de webhook estilo Svix (svix-id, svix-timestamp, svix-signature) con una ventana de reproducción de cinco minutos.

import { verifyWebhook } from '@xid-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload

API exportada

Exportar	Tipo	Propósito
`authenticateRequest`	function	Verifica credenciales JWT Bearer o explícitas de la aplicación, con exchange opcional de sesión Core del mismo origen
`exchangeSessionToken`	function	Reenvía las cookies opacas de Core solo a un endpoint session-token del mismo origen exacto; el valor nunca se verifica localmente
`verifyToken`	function	Verificación de token de acceso de bajo nivel: signature, exp, nbf, iss, aud, azp
`verifyWebhook`	function	Validación de firma de webhook HMAC-SHA256 estilo Svix con ventana de reproducción de 5 minutos
`toVerifyKeySet`	function	Convierte JwtKey (JWK, JWKS o CryptoKey) en VerifyKeySet para verificación
`JwksCache`	class	Caché JWKS con obtención de red opcional y TTL configurable (predeterminado 3600 s); úsalo solo cuando jwtKey no esté precargado
`AppError`	class	Se lanza para errores irrecuperables del SDK: clave JWT faltante, fallo al obtener JWKS, opciones inválidas, fallo del intercambio session-token
`BACKEND_ERROR_CODES`	tupla as const	Todos los valores de BackendErrorCode: missing_jwt_key, jwks_fetch_failed, invalid_options, session_token_exchange_failed
`PACKAGE`	constante de cadena	Identificador de nombre de paquete ‘@xid-kit/backend’

Tipos

Tipo	Descripción
`JwtKey`	Formatos de clave pública aceptados: PublicJwk, Jwks, o { alg, publicKey: CryptoKey }
`JwksCacheOptions`	Opciones del constructor para JwksCache: jwksUri, ttlSec, fetchFn
`VerifyTokenOptions`	Opciones de verifyToken: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now
`VerifyTokenError`	Error estructurado devuelto cuando la verificación del token falla (fallo esperado; no se lanza)
`AuthenticateRequestOptions`	Opciones de authenticateRequest: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange
`RequestState`	Unión discriminada de SignedInState y SignedOutState
`SignedInState`	Estado JWT firmado válido con userId, sessionId opcional y claims verificados
`SignedOutState`	No hay token válido presente; el campo reason indica la causa
`VerifyWebhookOptions`	Opciones de verifyWebhook: secret, toleranceSec (ventana de replay en segundos)
`WebhookVerifyError`	Error estructurado por encabezados faltantes, firmas no válidas, reproducción o cargas útiles no válidas
`VerifiedWebhook`	Metadatos de mensaje verificados y un sobre tipado para el payload type/data
`BackendErrorCode`	Unión de valores de BACKEND_ERROR_CODES

Límites de seguridad

Usa únicamente JWKS público. Nunca carga claves privadas de firma de la instancia.
La verificación usa Web Crypto a través de @xid-kit/crypto.
Los fallos esperados devuelven tipos Result; los errores inesperados lanzan AppError.