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

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

# @vonvon-kit/backend

## 运行时支持

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 永远不会在本地验证。

```ts
import { authenticateRequest } from '@vonvon-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
})
if (state.isSignedIn) {
  console.log(state.userId)
}
```

## verifyToken

底层访问 token 验证。传入来自 JWKS 的 `jwtKey` 可在冷启动时跳过网络往返。预期失败返回 Result 类型，而非抛出异常。

```ts
import { verifyToken } from '@vonvon-kit/backend'

const result = await verifyToken(token, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  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 '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_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` | 字符串常量 | 包名标识符 '@vonvon-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。从不加载实例签名私钥。
- 验证通过 @vonvon-kit/crypto 使用 Web Crypto 完成。
- 预期失败返回 Result 类型；意外错误抛出 AppError。

Source: https://vonvon.id/zh-hans/sdks/backend/index.mdx