# @andco/protocol

> El Protocol Contract: esquemas, validadores, constantes y ayudantes puros.


```bash
npm install @andco/protocol
```

El acuerdo de cable que ambos lados de una integración comparten: esquemas, validadores, constantes de error y de protocolo, guardas de mensajes y ayudantes puros.

No guarda estado de sesión y no toca el navegador. Esa restricción es lo que permite que la Plataforma dependa de él sin depender del SDK, y es la razón de que exista como paquete separado.

Normalmente no lo instalas: `@andco/sdk` ya lo trae. Lo instalas directo cuando escribes un servidor que valida webhooks o que habla el protocolo sin usar el cliente.

## Firma de webhooks

```ts
import { ANDCO_WEBHOOK_HEADERS, andCoWebhookVerify } from "@andco/protocol";

const trusted = await andCoWebhookVerify({
  body: raw,
  signature: headers.get(ANDCO_WEBHOOK_HEADERS.signature),
  eventId: headers.get(ANDCO_WEBHOOK_HEADERS.eventId),
  timestamp: headers.get(ANDCO_WEBHOOK_HEADERS.timestamp),
  secret: process.env.ANDCO_WEBHOOK_SECRET!,
});
```

La firma cubre `{timestamp}.{eventId}.{body}`, lo que ata el contenido a una entrega y a un momento: un cuerpo viejo reenviado con marca de tiempo nueva no verifica, y una firma válida no sirve para otro evento.

Dos detalles fáciles de equivocar están resueltos aquí: la comparación es de tiempo constante, y una entrega fuera de la ventana de tolerancia se rechaza aunque su firma sea correcta.

`body` tiene que ser los bytes crudos. Un framework que parsea el JSON antes de tu manejador ya destruyó lo que se firmó.

| Exportación | Qué es |
| --- | --- |
| `andCoWebhookVerify(input)` | la verificación |
| `ANDCO_WEBHOOK_HEADERS` | los nombres de las cabeceras |
| `ANDCO_WEBHOOK_TOLERANCE_SECONDS` | la tolerancia por omisión, cinco minutos |

## Scopes y errores

```ts
import { ANDCO_ERROR_CODES, ANDCO_SCOPE_REGEX, type AndCoScope } from "@andco/protocol";
```

`AndCoScope` sugiere los scopes conocidos y acepta cualquier cadena válida. `ANDCO_SCOPE_REGEX` valida la sintaxis de un token de scope. `ANDCO_ERROR_CODES` es el vocabulario de errores del protocolo, distinto del vocabulario del SDK.

## Mensajes del puente

```ts
import { isAndCoBridgeMessage, isAndCoPopupResult } from "@andco/protocol";
```

Guardas y esquemas de todo lo que viaja entre la superficie hospedada, la ventana emergente y el SDK: `ready`, `click`, `error`, `oauth.authorization_code`, `oauth.complete`, `oauth.dismiss`, `oauth.error`, `intent.complete`, `intent.dismiss`.

`oauth.error` existe aparte de `oauth.dismiss` a propósito: un fallo del servidor de autorización no es una decisión de la persona, y presentarlo como cancelación inventa algo que nadie hizo.

## Autorización

```ts
import { resolveAndCoAuthorization } from "@andco/protocol";
import { resolveAndCoConfidentialAuthorization } from "@andco/protocol/server";
```

Aplican la política de transporte —petición directa o PAR— a una autorización que otro armó. Existen para integraciones que generan su propia petición OAuth, como Better Auth o Passport, y aun así necesitan esa decisión. Sin ellas cada integración la reimplementaba, que es como llegaron a existir tres versiones distintas.

## URLs, opciones y constantes

```ts
import { ANDCO_AUTH_ORIGIN, ANDCO_RELEASE, ANDCO_URL_FROM } from "@andco/protocol";
```

Orígenes por omisión, la versión inmutable de la superficie hospedada y análisis estricto de URLs.

## Manifiesto de Miniapp

```ts
import { safeParseMiniappManifest } from "@andco/protocol";
```

Esquemas del descriptor de Miniapp y del puente nativo, para un Host que resuelve e incrusta Miniapps.