---
title: "@vonvon-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 relevant documentation index at: https://vonvon.id/fr/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/backend

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

```ts
import { authenticateRequest } from '@vonvon-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  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.

```ts
import { verifyToken } from '@vonvon-kit/backend'

const result = await verifyToken(token, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  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 '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_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 '@vonvon-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 @vonvon-kit/crypto.
- Les échecs attendus retournent des types Result ; les erreurs inattendues lèvent AppError.

Source: https://vonvon.id/fr/sdks/backend/index.mdx