@xid-kit/backend

edge 및 서버 런타임을 위한 네트워크 호출 없는 JWT 검증, 요청 인증, webhook 서명 검증입니다.

런타임 지원

Cloudflare Workers (기본 대상)
Vercel Edge Runtime 및 Node.js 서버 런타임
Web Crypto 호환 런타임 (Bun, Deno)

authenticateRequest

수신 Request에서 bearer token 또는 세션 cookie를 추출하고, 서명과 클레임을 검증하여 로그인 또는 로그아웃 상태 객체를 반환합니다.

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 타입을 반환합니다.

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)을 검증합니다.

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를 던집니다.