---
title: "@xid-kit/backend"
description: "edge 및 서버 런타임을 위한 네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증입니다."
locale: "ko"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/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 판별 union을 반환합니다 |
| `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을 갖춘 선택적 네트워크 fetching JWKS 캐시 (기본값 3600초); jwtKey가 미리 로드되지 않은 경우에만 사용하세요 |
| `AppError` | class | 복구 불가능한 SDK 오류 시 던집니다: JWT 키 없음, JWKS fetch 실패, 잘못된 옵션 |
| `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의 판별 union |
| `SignedInState` | 유효한 세션 token이 확인됨; 클레임 접근을 위한 toAuth() 포함 |
| `SignedOutState` | 유효한 token이 없습니다; reason 필드에 원인이 표시됩니다 |
| `VerifyWebhookOptions` | verifyWebhook 옵션: secret, tolerance (재사용 방지 창 초) |
| `WebhookVerifyError` | webhook 서명이 유효하지 않거나 재사용 공격이 감지될 때의 구조화된 오류 |
| `VerifiedWebhook` | 파싱 및 검증된 webhook 페이로드 |
| `BackendErrorCode` | BACKEND\_ERROR\_CODES 값의 union |

## 보안 경계

- 공개 JWKS만 사용합니다. 인스턴스 서명 개인 키를 로드하지 않습니다.
- @xid-kit/crypto를 통해 Web Crypto로 검증합니다.
- 예상된 실패는 Result 타입을 반환하고, 예상치 못한 오류는 AppError를 던집니다.

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