---
title: "@xid-kit/backend"
description: "Verificação JWT sem rede, autenticação de requisições e validação de assinatura de webhook para runtimes de borda e servidor."
locale: "pt-BR"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/pt-br/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/backend

## 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.

```ts
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.

```ts
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.

```ts
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.

Source: https://xid.dev/pt-br/sdks/backend/index.mdx