@xid-kit/backend

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

ランタイムサポート

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

authenticateRequest

受信 Request から bearer token またはセッション cookie を抽出し、署名とクレームを検証して、サインイン済みまたはサインアウト状態のオブジェクトを返します。

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

低レベルの 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 event = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})

エクスポートされた API

エクスポート	種別	目的
`authenticateRequest`	function	bearer token またはセッション cookie を抽出して検証します。RequestState 判別ユニオンを返します
`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 取得失敗、無効なオプション）でスローされます
`BACKEND_ERROR_CODES`	as const タプル	BackendErrorCode の全値：missing_jwt_key、jwks_fetch_failed、invalid_options
`PACKAGE`	文字列定数	パッケージ名識別子 ‘@xid-kit/backend’

型

種別	説明
`JwtKey`	受け付ける公開鍵形式：PublicJwk、Jwks、または { alg, publicKey: CryptoKey }
`JwksCacheOptions`	JwksCache のコンストラクターオプション：jwksUri、ttlSec、fetchFn
`VerifyTokenOptions`	verifyToken のオプション：jwtKey、issuer、audience、clockSkewSec、signal
`VerifyTokenError`	トークン検証失敗時に返される構造化エラー（想定される失敗。スローされません）
`AuthenticateRequestOptions`	authenticateRequest のオプション：jwtKey、issuer、audience、cookieName
`RequestState`	SignedInState と SignedOutState の判別ユニオン
`SignedInState`	有効なセッショントークンが見つかりました。クレームアクセス用の toAuth() が含まれます
`SignedOutState`	有効なトークンが存在しません。reason フィールドに原因が示されます
`VerifyWebhookOptions`	verifyWebhook のオプション：secret、tolerance（リプレイウィンドウ秒数）
`WebhookVerifyError`	webhook 署名が無効またはリプレイされた場合の構造化エラー
`VerifiedWebhook`	解析および検証済みの webhook ペイロード
`BackendErrorCode`	BACKEND_ERROR_CODES 値のユニオン

セキュリティ境界

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