@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

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

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

authenticateRequest

Verifica um JWT Bearer ou explícito da aplicação em uma Request recebida. Uma sessão de navegador Core da mesma origem é primeiro trocada por /v1/sessions/token; o cookie de refresh opaco nunca é verificado localmente.

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

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 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 exportada

Exportar	Tipo	Finalidade
`authenticateRequest`	function	Verifica credenciais JWT Bearer ou explícitas da aplicação, com exchange opcional de sessão Core da mesma origem
`exchangeSessionToken`	function	Encaminha cookies opacos do Core somente a um endpoint session-token da mesma origem exata; o valor nunca é verificado localmente
`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, falha no exchange de session-token
`BACKEND_ERROR_CODES`	tupla as const	Todos os valores de BackendErrorCode: missing_jwt_key, jwks_fetch_failed, invalid_options, session_token_exchange_failed
`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 de verifyToken: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now
`VerifyTokenError`	Erro estruturado retornado quando a verificação do token falha (falha esperada; não lançado)
`AuthenticateRequestOptions`	Opções de authenticateRequest: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange
`RequestState`	União discriminada de SignedInState e SignedOutState
`SignedInState`	Estado JWT assinado válido com userId, sessionId opcional e claims verificados
`SignedOutState`	Nenhum token válido presente; o campo reason indica a causa
`VerifyWebhookOptions`	Opções de verifyWebhook: secret, toleranceSec (janela de replay em segundos)
`WebhookVerifyError`	Erro estruturado para cabeçalhos ausentes, assinaturas inválidas, reprodução ou cargas inválidas
`VerifiedWebhook`	Metadados de mensagem verificados e um envelope tipado para o payload type/data
`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.