@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

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

authenticateRequest

Extrae un token bearer o cookie de sesión de una Request entrante, verifica la firma y las declaraciones, y devuelve un objeto de estado con sesión iniciada o cerrada.

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

const state = await authenticateRequest(request, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
})
if (state.status === 'signed-in') {
  const { userId } = state.toAuth()
}

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 event = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})

API exportada

Exportar	Tipo	Propósito
`authenticateRequest`	function	Extrae y verifica el token bearer o cookie de sesión; devuelve la unión discriminada RequestState
`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	Lanzado para errores irrecuperables del SDK: clave JWT faltante, fallo al obtener JWKS, opciones inválidas
`BACKEND_ERROR_CODES`	tupla as const	Todos los valores de BackendErrorCode: missing_jwt_key, jwks_fetch_failed, invalid_options
`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 para verifyToken: jwtKey, issuer, audience, clockSkewSec, signal
`VerifyTokenError`	Error estructurado devuelto cuando la verificación del token falla (fallo esperado; no se lanza)
`AuthenticateRequestOptions`	Opciones para authenticateRequest: jwtKey, issuer, audience, cookieName
`RequestState`	Unión discriminada de SignedInState y SignedOutState
`SignedInState`	Token de sesión válido encontrado; incluye toAuth() para acceso a declaraciones
`SignedOutState`	No hay token válido presente; el campo reason indica la causa
`VerifyWebhookOptions`	Opciones para verifyWebhook: secret, tolerance (segundos de ventana de reproducción)
`WebhookVerifyError`	Error estructurado cuando la firma del webhook es inválida o reproducida
`VerifiedWebhook`	Payload de webhook analizado y verificado
`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.