---
title: "@vonvon-kit/backend"
description: "Netzwerklose JWT-Prüfung, Anfrage-Authentifizierung und Webhook-Signaturvalidierung für Edge- und Server-Laufzeitumgebungen."
locale: "de"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/de/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/backend

## Laufzeitunterstützung

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

- Cloudflare Workers (primäres Ziel)
- Vercel Edge Runtime und Node.js Server-Laufzeitumgebungen
- Jede mit Web Crypto kompatible Laufzeitumgebung (Bun, Deno)

## authenticateRequest

Prüft ein Bearer- oder explizites Anwendungs-JWT aus einer eingehenden `Request`. Eine gleichursprüngliche Core-Browsersitzung wird zuerst über `/v1/sessions/token` ausgetauscht; das undurchsichtige Refresh-Cookie wird nie lokal geprüft.

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

Niedrigstufige Access-Token-Prüfung. `jwtKey` aus JWKS übergeben, um Netzwerkumlauf beim Kaltstart zu überspringen. Erwartete Fehler geben einen Result-Typ zurück, keine Ausnahme.

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

Validiert Svix-artige Webhook-Signaturen (`svix-id`, `svix-timestamp`, `svix-signature`) mit einem Fünf-Minuten-Wiedergabefenster.

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

## Exportierte API

| Exportieren | Art | Zweck |
| --- | --- | --- |
| `authenticateRequest` | function | Prüft Bearer- oder explizite Anwendungs-JWT-Anmeldedaten mit optionalem gleichursprünglichem Core-Sitzungsaustausch |
| `exchangeSessionToken` | function | Leitet opaque Core-Cookies nur an einen Session-Token-Endpoint mit exakt gleicher Origin weiter; der Wert wird nie lokal geprüft |
| `verifyToken` | function | Niedrigstufige Access-Token-Prüfung: signature, exp, nbf, iss, aud, azp |
| `verifyWebhook` | function | Svix-artiger HMAC-SHA256-Webhook-Signatur-Validierung mit 5-Minuten-Wiedergabefenster |
| `toVerifyKeySet` | function | JwtKey (JWK, JWKS oder CryptoKey) in VerifyKeySet zur Verifizierung umwandeln |
| `JwksCache` | class | Optionaler netzwerkbasierter JWKS-Cache mit konfigurierbarer TTL (Standard 3600 s); nur verwenden, wenn jwtKey nicht vorgeladen ist |
| `AppError` | class | Wird für nicht behebbare SDK-Fehler geworfen: fehlender JWT-Schlüssel, JWKS-Abruffehler, ungültige Optionen, fehlgeschlagener Session-Token-Austausch |
| `BACKEND_ERROR_CODES` | as const Tupel | Alle BackendErrorCode-Werte: missing\_jwt\_key, jwks\_fetch\_failed, invalid\_options, session\_token\_exchange\_failed |
| `PACKAGE` | Zeichenkettenkonstante | Paketkennzeichner '@vonvon-kit/backend' |

## Typen

| Typ | Beschreibung |
| --- | --- |
| `JwtKey` | Akzeptierte öffentliche Schlüsselformate: PublicJwk, Jwks oder { alg, publicKey: CryptoKey } |
| `JwksCacheOptions` | Konstruktoroptionen für JwksCache: jwksUri, ttlSec, fetchFn |
| `VerifyTokenOptions` | Optionen für verifyToken: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now |
| `VerifyTokenError` | Strukturierter Fehler bei fehlgeschlagener Token-Prüfung (erwarteter Fehler; wird nicht geworfen) |
| `AuthenticateRequestOptions` | Optionen für authenticateRequest: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange |
| `RequestState` | Diskriminierte Vereinigung von SignedInState und SignedOutState |
| `SignedInState` | Gültiger signierter JWT-Zustand mit userId, optionaler sessionId und geprüften claims |
| `SignedOutState` | Kein gültiges Token vorhanden; das Ursachenfeld gibt den Grund an |
| `VerifyWebhookOptions` | Optionen für verifyWebhook: secret, toleranceSec (Replay-Fenster in Sekunden) |
| `WebhookVerifyError` | Strukturierter Fehler für fehlende Header, ungültige Signaturen, Wiedergabe oder ungültige Nutzlasten |
| `VerifiedWebhook` | Verifizierte Nachrichtenmetadaten und eine typisierte Payload-Hülle für type und data |
| `BackendErrorCode` | Vereinigung der BACKEND\_ERROR\_CODES-Werte |

## Sicherheitsgrenzen

- Verwendet ausschließlich öffentliche JWKS. Lädt niemals private Instanz-Signaturschlüssel.
- Verifizierung verwendet Web Crypto über @vonvon-kit/crypto.
- Erwartete Fehler geben Result-Typen zurück; unerwartete Fehler werfen AppError.

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