---
title: "@xid-kit/backend"
description: "适用于边缘和服务端运行时的无网络 JWT 验证、请求认证和 webhook 签名校验。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/backend

## 运行时支持

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

## authenticateRequest

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

```ts
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 类型，而非抛出异常。

```ts
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`），重放窗口为五分钟。

```ts
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。

Source: https://xid.dev/zh-hans/sdks/backend/index.mdx