@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 浏览器 session 会先通过 /v1/sessions/token exchange；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

底层访问 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

验证 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 session exchange
`exchangeSessionToken`	function	仅将 Core opaque cookie 转发到 exact same-origin session-token endpoint；绝不在本地验证其值
`verifyToken`	function	底层访问 token 验证：signature、exp、nbf、iss、aud、azp
`verifyWebhook`	function	Svix 风格 HMAC-SHA256 webhook 签名校验，5 分钟重放窗口
`toVerifyKeySet`	function	将 JwtKey（JWK、JWKS 或 CryptoKey）转换为用于验证的 VerifyKeySet
`JwksCache`	class	可选的网络 JWKS 缓存，TTL 可配置（默认 3600 秒）；仅在 jwtKey 未预加载时使用
`AppError`	class	在不可恢复的 SDK 错误时抛出：缺少 JWT key、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`	token 验证失败时返回的结构化错误（预期失败；不抛出异常）
`AuthenticateRequestOptions`	authenticateRequest 的选项：jwtKey、issuer、audience、authorizedParties、clockToleranceSec、now、jwtCookieName、sessionTokenExchange
`RequestState`	SignedInState 和 SignedOutState 的判别联合类型
`SignedInState`	有效的已签名 JWT 状态，包含 userId、可选 sessionId 和已验证的 claims
`SignedOutState`	没有有效 token；reason 字段说明原因
`VerifyWebhookOptions`	verifyWebhook 选项：secret、toleranceSec（重放窗口秒数）
`WebhookVerifyError`	用于 header 缺失、签名无效、重放或负载无效的结构化错误
`VerifiedWebhook`	已验证的消息元数据，以及带类型的 type/data 负载封装
`BackendErrorCode`	BACKEND_ERROR_CODES 取值的联合类型

安全边界

仅使用公开 JWKS。从不加载实例签名私钥。
验证通过 @xid-kit/crypto 使用 Web Crypto 完成。
预期失败返回 Result 类型；意外错误抛出 AppError。