@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

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

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

authenticateRequest

Vérifie un JWT Bearer ou applicatif explicite dans une Request entrante. Une session navigateur Core de même origine est d’abord échangée via /v1/sessions/token ; le cookie de renouvellement opaque n’est jamais vérifié localement.

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

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 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 exportée

Exporter	Type	Objectif
`authenticateRequest`	function	Vérifie des identifiants JWT Bearer ou applicatifs explicites, avec échange de session Core de même origine facultatif
`exchangeSessionToken`	function	Transmet les cookies opaques Core uniquement à un endpoint session-token de la même origine exacte ; la valeur n’est jamais vérifiée localement
`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, échec de l’échange session-token
`BACKEND_ERROR_CODES`	tuple as const	Valeurs de BackendErrorCode : missing_jwt_key, jwks_fetch_failed, invalid_options, session_token_exchange_failed
`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 de verifyToken : jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now
`VerifyTokenError`	Erreur structurée retournée lorsque la vérification du token échoue (échec attendu ; non levée)
`AuthenticateRequestOptions`	Options de authenticateRequest : jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange
`RequestState`	Union discriminée de SignedInState et SignedOutState
`SignedInState`	État JWT signé valide avec userId, sessionId facultatif et claims vérifiés
`SignedOutState`	Aucun jeton valide présent ; le champ reason indique la cause
`VerifyWebhookOptions`	Options de verifyWebhook : secret, toleranceSec (fenêtre de replay en secondes)
`WebhookVerifyError`	Erreur structurée pour les en-têtes manquants, les signatures non valides, la relecture ou les charges utiles non valides
`VerifiedWebhook`	Métadonnées de message vérifiées et enveloppe typée pour le payload type/data
`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.