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

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ja/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 を抽出し、署名とクレームを検証して、サインイン済みまたはサインアウト状態のオブジェクトを返します。

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

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

5 分間のリプレイウィンドウで 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 | 低レベルの 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 取得失敗、無効なオプション）でスローされます |
| `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` | トークン検証失敗時に返される構造化エラー（想定される失敗。スローされません） |
| `AuthenticateRequestOptions` | authenticateRequest のオプション：jwtKey、issuer、audience、cookieName |
| `RequestState` | SignedInState と SignedOutState の判別ユニオン |
| `SignedInState` | 有効なセッショントークンが見つかりました。クレームアクセス用の toAuth() が含まれます |
| `SignedOutState` | 有効なトークンが存在しません。reason フィールドに原因が示されます |
| `VerifyWebhookOptions` | verifyWebhook のオプション：secret、tolerance（リプレイウィンドウ秒数） |
| `WebhookVerifyError` | webhook 署名が無効またはリプレイされた場合の構造化エラー |
| `VerifiedWebhook` | 解析および検証済みの webhook ペイロード |
| `BackendErrorCode` | BACKEND\_ERROR\_CODES 値のユニオン |

## セキュリティ境界

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

Source: https://xid.dev/ja/sdks/backend/index.mdx