---
title: "@vonvon-kit/backend"
description: "Verificación JWT sin llamadas de red, autenticación de solicitudes y validación de firma de webhooks para entornos edge y servidor."
locale: "es"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/es/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/backend

## Compatibilidad de entorno de ejecución

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

- Cloudflare Workers (destino principal)
- Entornos de ejecución Vercel Edge Runtime y Node.js
- Cualquier entorno compatible con Web Crypto (Bun, Deno)

## authenticateRequest

Verifica un JWT Bearer o explícito de la aplicación en una `Request` entrante. Una sesión de navegador Core del mismo origen se intercambia primero mediante `/v1/sessions/token`; la cookie de renovación opaca nunca se verifica 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

Verificación de token de acceso de bajo nivel. Pasa `jwtKey` desde JWKS para omitir ida y vuelta de red en arranque en frío. Los fallos esperados devuelven un tipo Result, no una excepción.

```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 firmas de webhook estilo Svix (`svix-id`, `svix-timestamp`, `svix-signature`) con una ventana de reproducción 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 | Propósito |
| --- | --- | --- |
| `authenticateRequest` | function | Verifica credenciales JWT Bearer o explícitas de la aplicación, con exchange opcional de sesión Core del mismo origen |
| `exchangeSessionToken` | function | Reenvía las cookies opacas de Core solo a un endpoint session-token del mismo origen exacto; el valor nunca se verifica localmente |
| `verifyToken` | function | Verificación de token de acceso de bajo nivel: signature, exp, nbf, iss, aud, azp |
| `verifyWebhook` | function | Validación de firma de webhook HMAC-SHA256 estilo Svix con ventana de reproducción de 5 minutos |
| `toVerifyKeySet` | function | Convierte JwtKey (JWK, JWKS o CryptoKey) en VerifyKeySet para verificación |
| `JwksCache` | class | Caché JWKS con obtención de red opcional y TTL configurable (predeterminado 3600 s); úsalo solo cuando jwtKey no esté precargado |
| `AppError` | class | Se lanza para errores irrecuperables del SDK: clave JWT faltante, fallo al obtener JWKS, opciones inválidas, fallo del intercambio session-token |
| `BACKEND_ERROR_CODES` | tupla as const | Todos los valores de BackendErrorCode: missing\_jwt\_key, jwks\_fetch\_failed, invalid\_options, session\_token\_exchange\_failed |
| `PACKAGE` | constante de cadena | Identificador de nombre de paquete '@vonvon-kit/backend' |

## Tipos

| Tipo | Descripción |
| --- | --- |
| `JwtKey` | Formatos de clave pública aceptados: PublicJwk, Jwks, o { alg, publicKey: CryptoKey } |
| `JwksCacheOptions` | Opciones del constructor para JwksCache: jwksUri, ttlSec, fetchFn |
| `VerifyTokenOptions` | Opciones de verifyToken: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now |
| `VerifyTokenError` | Error estructurado devuelto cuando la verificación del token falla (fallo esperado; no se lanza) |
| `AuthenticateRequestOptions` | Opciones de authenticateRequest: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange |
| `RequestState` | Unión discriminada de SignedInState y SignedOutState |
| `SignedInState` | Estado JWT firmado válido con userId, sessionId opcional y claims verificados |
| `SignedOutState` | No hay token válido presente; el campo reason indica la causa |
| `VerifyWebhookOptions` | Opciones de verifyWebhook: secret, toleranceSec (ventana de replay en segundos) |
| `WebhookVerifyError` | Error estructurado por encabezados faltantes, firmas no válidas, reproducción o cargas útiles no válidas |
| `VerifiedWebhook` | Metadatos de mensaje verificados y un sobre tipado para el payload type/data |
| `BackendErrorCode` | Unión de valores de BACKEND\_ERROR\_CODES |

## Límites de seguridad

- Usa únicamente JWKS público. Nunca carga claves privadas de firma de la instancia.
- La verificación usa Web Crypto a través de @vonvon-kit/crypto.
- Los fallos esperados devuelven tipos Result; los errores inesperados lanzan AppError.

Source: https://vonvon.id/es/sdks/backend/index.mdx