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

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ko/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을 갖춘 선택적 네트워크 fetching JWKS 캐시 (기본값 3600초); jwtKey가 미리 로드되지 않은 경우에만 사용하세요 |
| `AppError` | class | 복구 불가능한 SDK 오류 시 던집니다: JWT 키 없음, JWKS fetch 실패, 잘못된 옵션, 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의 판별 union |
| `SignedInState` | userId, 선택적 sessionId 및 검증된 claims를 포함하는 유효한 서명 JWT 상태 |
| `SignedOutState` | 유효한 token이 없습니다; reason 필드에 원인이 표시됩니다 |
| `VerifyWebhookOptions` | verifyWebhook 옵션: secret, toleranceSec(재생 방지 윈도우, 초) |
| `WebhookVerifyError` | 헤더 누락, 잘못된 서명, 재생 공격 또는 잘못된 페이로드에 대한 구조화된 오류 |
| `VerifiedWebhook` | 검증된 메시지 메타데이터와 형식이 지정된 type/data 페이로드 봉투 |
| `BackendErrorCode` | BACKEND\_ERROR\_CODES 값의 union |

## 보안 경계

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

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