---
title: "@xid-kit/backend"
description: "Vérification JWT sans réseau, authentification de requête et validation de signature de webhook pour les runtimes edge et serveur."
locale: "fr"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/fr/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/backend

## 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é.

```ts
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.

```ts
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.

```ts
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.

Source: https://xid.dev/fr/sdks/backend/index.mdx