@xid-kit/backend

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

런타임 지원

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는 로컬에서 검증하지 않습니다.

import { authenticateRequest } from '@xid-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.XID_JWKS_PUBLIC_KEY,
  issuer: 'https://xid.dev',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
})
if (state.isSignedIn) {
  console.log(state.userId)
}

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 result = await verifyWebhook(request, {
  secret: env.XID_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`	문자열 상수	패키지 이름 식별자 ‘@xid-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만 사용합니다. 인스턴스 서명 개인 키를 로드하지 않습니다.
@xid-kit/crypto를 통해 Web Crypto로 검증합니다.
예상된 실패는 Result 타입을 반환하고, 예상치 못한 오류는 AppError를 던집니다.