@xid-kit/backend

Verificação JWT sem rede, autenticação de requisições e validação de assinatura de webhook para runtimes de borda e servidor.

Suporte a runtimes

Cloudflare Workers (alvo principal)
Runtimes de servidor Vercel Edge Runtime e Node.js
Qualquer runtime compatível com Web Crypto (Bun, Deno)

authenticateRequest

Extrai um bearer token ou cookie de sessão de uma Request recebida, verifica a assinatura e as declarações e retorna um objeto de estado autenticado ou não autenticado.

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

Verificação de access token de baixo nível. Passe jwtKey do JWKS para pular round-trips de rede na inicialização a frio. Falhas esperadas retornam um tipo Result, não uma exceção.

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

Valida assinaturas de webhook no estilo Svix (svix-id, svix-timestamp, svix-signature) com janela de replay de cinco minutos.

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

const event = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})

API exportada

Exportar	Tipo	Finalidade
`authenticateRequest`	function	Extrai e verifica bearer token ou cookie de sessão; retorna a união discriminada RequestState
`verifyToken`	function	Verificação de access token de baixo nível: signature, exp, nbf, iss, aud, azp
`verifyWebhook`	function	Validação de assinatura de webhook HMAC-SHA256 no estilo Svix com janela de replay de 5 minutos
`toVerifyKeySet`	function	Converte JwtKey (JWK, JWKS ou CryptoKey) em VerifyKeySet para verificação
`JwksCache`	class	Cache JWKS com busca de rede opcional e TTL configurável (padrão 3600 s); use apenas quando jwtKey não estiver pré-carregado
`AppError`	class	Lançado para erros irrecuperáveis do SDK: chave JWT ausente, falha ao buscar JWKS, opções inválidas
`BACKEND_ERROR_CODES`	tupla as const	Todos os valores de BackendErrorCode: missing_jwt_key, jwks_fetch_failed, invalid_options
`PACKAGE`	constante de string	Identificador de nome de pacote ‘@xid-kit/backend’

Tipos

Tipo	Descrição
`JwtKey`	Formatos de chave pública aceitos: PublicJwk, Jwks ou { alg, publicKey: CryptoKey }
`JwksCacheOptions`	Opções do construtor de JwksCache: jwksUri, ttlSec, fetchFn
`VerifyTokenOptions`	Opções para verifyToken: jwtKey, issuer, audience, clockSkewSec, signal
`VerifyTokenError`	Erro estruturado retornado quando a verificação do token falha (falha esperada; não lançado)
`AuthenticateRequestOptions`	Opções para authenticateRequest: jwtKey, issuer, audience, cookieName
`RequestState`	União discriminada de SignedInState e SignedOutState
`SignedInState`	Token de sessão válido encontrado; inclui toAuth() para acesso às declarações
`SignedOutState`	Nenhum token válido presente; o campo reason indica a causa
`VerifyWebhookOptions`	Opções para verifyWebhook: secret, tolerance (segundos da janela de replay)
`WebhookVerifyError`	Erro estruturado quando a assinatura do webhook é inválida ou repetida
`VerifiedWebhook`	Payload de webhook analisado e verificado
`BackendErrorCode`	União dos valores de BACKEND_ERROR_CODES

Limites de segurança

Usa apenas JWKS público. Nunca carrega as chaves privadas de assinatura da instância.
A verificação usa Web Crypto via @xid-kit/crypto.
Falhas esperadas retornam tipos Result; erros inesperados lançam AppError.