@xid-kit/backend

Vérification JWT sans réseau, authentification de requête et validation de signature de webhook pour les runtimes edge et serveur.

Prise en charge des runtimes

Cloudflare Workers (cible principale)
Runtimes Vercel Edge Runtime et Node.js serveur
Tout runtime compatible Web Crypto (Bun, Deno)

authenticateRequest

Extrait un bearer token ou un cookie de session d’une Request entrante, vérifie la signature et les revendications, et retourne un objet d’état connecté ou déconnecté.

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

Vérification bas niveau du token d’accès. Passez jwtKey depuis JWKS pour éviter les allers-retours réseau au démarrage à froid. Les échecs attendus retournent un type Result, pas une exception.

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

Valide les signatures webhook de style Svix (svix-id, svix-timestamp, svix-signature) avec une fenêtre de relecture de cinq minutes.

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

const event = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})

API exportée

Exporter	Type	Objectif
`authenticateRequest`	function	Extrait et vérifie le bearer token ou le cookie de session ; retourne une union discriminée RequestState
`verifyToken`	function	Vérification bas niveau du token d’accès : signature, exp, nbf, iss, aud, azp
`verifyWebhook`	function	Validation de signature webhook HMAC-SHA256 de style Svix avec fenêtre de relecture de 5 minutes
`toVerifyKeySet`	function	Convertit JwtKey (JWK, JWKS ou CryptoKey) en VerifyKeySet pour la vérification
`JwksCache`	class	Cache JWKS avec récupération réseau optionnelle et TTL configurable (défaut 3600 s) ; utiliser uniquement si jwtKey n’est pas préchargé
`AppError`	class	Levée pour les erreurs SDK irrécupérables : clé JWT manquante, échec de récupération JWKS, options invalides
`BACKEND_ERROR_CODES`	tuple as const	Valeurs de BackendErrorCode : missing_jwt_key, jwks_fetch_failed, invalid_options
`PACKAGE`	constante string	Identifiant du nom de package ‘@xid-kit/backend’

Types

Type	Description
`JwtKey`	Formes de clé publique acceptées : PublicJwk, Jwks, ou { alg, publicKey: CryptoKey }
`JwksCacheOptions`	Options du constructeur de JwksCache : jwksUri, ttlSec, fetchFn
`VerifyTokenOptions`	Options pour verifyToken : jwtKey, issuer, audience, clockSkewSec, signal
`VerifyTokenError`	Erreur structurée retournée lorsque la vérification du token échoue (échec attendu ; non levée)
`AuthenticateRequestOptions`	Options pour authenticateRequest : jwtKey, issuer, audience, cookieName
`RequestState`	Union discriminée de SignedInState et SignedOutState
`SignedInState`	Jeton de session valide trouvé ; inclut toAuth() pour l’accès aux revendications
`SignedOutState`	Aucun jeton valide présent ; le champ reason indique la cause
`VerifyWebhookOptions`	Options pour verifyWebhook : secret, tolerance (secondes de fenêtre de relecture)
`WebhookVerifyError`	Erreur structurée lorsque la signature webhook est invalide ou rejouée
`VerifiedWebhook`	Payload webhook analysé et vérifié
`BackendErrorCode`	Union des valeurs de BACKEND_ERROR_CODES

Limites de sécurité

Utilise uniquement le JWKS public. Ne charge jamais les clés privées de signature de l’instance.
La vérification utilise Web Crypto via @xid-kit/crypto.
Les échecs attendus retournent des types Result ; les erreurs inattendues lèvent AppError.