---
title: "@vonvon-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 relevant documentation index at: https://vonvon.id/pt-br/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/backend

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

```ts
import { authenticateRequest } from '@vonvon-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  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.

```ts
import { verifyToken } from '@vonvon-kit/backend'

const result = await verifyToken(token, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  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 '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_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 '@vonvon-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 @vonvon-kit/crypto.
- Falhas esperadas retornam tipos Result; erros inesperados lançam AppError.

Source: https://vonvon.id/pt-br/sdks/backend/index.mdx