---
title: "@vonvon-kit/backend"
description: "エッジおよびサーバーランタイム向けのネットワーク不要 JWT 検証、リクエスト認証、webhook 署名検証。"
locale: "ja"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ja/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 ブラウザーセッションは最初に `/v1/sessions/token` で交換され、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

低レベルの access 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

5 分間のリプレイウィンドウで 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 セッションを交換します |
| `exchangeSessionToken` | function | Core の opaque cookie は exact same-origin の session-token endpoint にのみ転送され、その値をローカルで検証することはありません |
| `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 取得失敗、無効なオプション、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` | トークン検証失敗時に返される構造化エラー（想定される失敗。スローされません） |
| `AuthenticateRequestOptions` | authenticateRequest のオプション: jwtKey、issuer、audience、authorizedParties、clockToleranceSec、now、jwtCookieName、sessionTokenExchange |
| `RequestState` | SignedInState と SignedOutState の判別ユニオン |
| `SignedInState` | userId、任意の sessionId、検証済み claims を含む有効な署名済み JWT 状態 |
| `SignedOutState` | 有効なトークンが存在しません。reason フィールドに原因が示されます |
| `VerifyWebhookOptions` | verifyWebhook のオプション: secret、toleranceSec（リプレイウィンドウの秒数） |
| `WebhookVerifyError` | ヘッダーの欠落、無効な署名、リプレイ、または無効なペイロードによる構造化エラー |
| `VerifiedWebhook` | 検証されたメッセージ メタデータと型付きタイプ/データ ペイロード エンベロープ |
| `BackendErrorCode` | BACKEND\_ERROR\_CODES 値のユニオン |

## セキュリティ境界

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

Source: https://vonvon.id/ja/sdks/backend/index.mdx