@xid-kit/backend

エッジおよびサーバーランタイム向けのネットワーク不要 JWT 検証、リクエスト認証、webhook 署名検証。

ランタイムサポート

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

Cloudflare Workers（主要ターゲット）
Vercel Edge Runtime および Node.js サーバーランタイム
Web Crypto 互換の任意ランタイム（Bun、Deno）

authenticateRequest

受信 Request の Bearer または明示的なアプリケーション JWT を検証します。同一オリジンの Core ブラウザーセッションは最初に /v1/sessions/token で交換され、opaque refresh Cookie がローカルで検証されることはありません。

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

低レベルの access token 検証。コールドスタート時のネットワーク往復をスキップするには JWKS の jwtKey を渡してください。想定される失敗は例外ではなく Result 型を返します。

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

5 分間のリプレイウィンドウで Svix スタイルの webhook 署名（svix-id、svix-timestamp、svix-signature）を検証します。

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

エクスポート	種別	目的
`authenticateRequest`	function	Bearer または明示的なアプリケーション JWT credential を検証し、任意で同一オリジン Core セッションを交換します
`exchangeSessionToken`	function	Core の opaque cookie は exact same-origin の session-token endpoint にのみ転送され、その値をローカルで検証することはありません
`verifyToken`	function	低レベルの access token 検証：signature、exp、nbf、iss、aud、azp
`verifyWebhook`	function	5 分間のリプレイウィンドウ付きの Svix スタイル HMAC-SHA256 webhook 署名検証
`toVerifyKeySet`	function	JwtKey（JWK、JWKS、または CryptoKey）を検証用の VerifyKeySet に変換します
`JwksCache`	class	設定可能な TTL（デフォルト 3600 秒）付きのオプションネットワーク取得 JWKS キャッシュ。jwtKey が事前ロードされていない場合にのみ使用してください
`AppError`	class	回復不能な SDK エラー（JWT キーの欠落、JWKS 取得失敗、無効なオプション、session-token exchange の失敗）でスローされます
`BACKEND_ERROR_CODES`	as const タプル	BackendErrorCode の全値：missing_jwt_key、jwks_fetch_failed、invalid_options、session_token_exchange_failed
`PACKAGE`	文字列定数	パッケージ名識別子 ‘@xid-kit/backend’

型

種別	説明
`JwtKey`	受け付ける公開鍵形式：PublicJwk、Jwks、または { alg, publicKey: CryptoKey }
`JwksCacheOptions`	JwksCache のコンストラクターオプション：jwksUri、ttlSec、fetchFn
`VerifyTokenOptions`	verifyToken のオプション: jwtKey、issuer、audience、authorizedParties、clockToleranceSec、now
`VerifyTokenError`	トークン検証失敗時に返される構造化エラー（想定される失敗。スローされません）
`AuthenticateRequestOptions`	authenticateRequest のオプション: jwtKey、issuer、audience、authorizedParties、clockToleranceSec、now、jwtCookieName、sessionTokenExchange
`RequestState`	SignedInState と SignedOutState の判別ユニオン
`SignedInState`	userId、任意の sessionId、検証済み claims を含む有効な署名済み JWT 状態
`SignedOutState`	有効なトークンが存在しません。reason フィールドに原因が示されます
`VerifyWebhookOptions`	verifyWebhook のオプション: secret、toleranceSec（リプレイウィンドウの秒数）
`WebhookVerifyError`	ヘッダーの欠落、無効な署名、リプレイ、または無効なペイロードによる構造化エラー
`VerifiedWebhook`	検証されたメッセージメタデータと型付きタイプ/データペイロードエンベロープ
`BackendErrorCode`	BACKEND_ERROR_CODES 値のユニオン

セキュリティ境界

公開 JWKS のみを使用します。インスタンス署名の秘密鍵は読み込みません。
検証は @xid-kit/crypto 経由で Web Crypto を使用します。
想定される失敗は Result 型を返します。予期しないエラーは AppError をスローします。