@xid-kit/backend

Netzwerklose JWT-Prüfung, Anfrage-Authentifizierung und Webhook-Signaturvalidierung für Edge- und Server-Laufzeitumgebungen.

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.

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

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.

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

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

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

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 ‘@xid-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 @xid-kit/crypto.
Erwartete Fehler geben Result-Typen zurück; unerwartete Fehler werfen AppError.