@andco/protocol

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

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

Scopes y errores

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

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

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

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

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

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