@xid-kit/backend

适用于边缘和服务端运行时的无网络 JWT 验证、请求认证和 webhook 签名校验。

运行时支持

Cloudflare Workers（主要目标平台）
Vercel Edge Runtime 和 Node.js 服务端运行时
任何兼容 Web Crypto 的运行时（Bun、Deno）

authenticateRequest

从传入的 Request 中提取 bearer token 或会话 cookie，验证签名和 claims，并返回已登录或未登录的状态对象。

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

底层访问 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 event = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})

导出的 API

导出	类型	用途
`authenticateRequest`	function	提取并验证 bearer token 或会话 cookie；返回 RequestState 判别联合类型
`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 获取失败、选项无效
`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`	token 验证失败时返回的结构化错误（预期失败；不抛出异常）
`AuthenticateRequestOptions`	authenticateRequest 的选项：jwtKey、issuer、audience、cookieName
`RequestState`	SignedInState 和 SignedOutState 的判别联合类型
`SignedInState`	找到有效会话 token；包含用于访问 claims 的 toAuth()
`SignedOutState`	没有有效 token；reason 字段说明原因
`VerifyWebhookOptions`	verifyWebhook 的选项：secret、tolerance（重放窗口秒数）
`WebhookVerifyError`	webhook 签名无效或被重放时的结构化错误
`VerifiedWebhook`	已解析并验证的 webhook payload
`BackendErrorCode`	BACKEND_ERROR_CODES 取值的联合类型

安全边界

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