Developer surfaces

Gateway, MCP, OTel y n8n

Los SDK principales de Attesto cubren la integración directa en aplicaciones. Gateway, MCP, OpenTelemetry y n8n cubren los sistemas alrededor de las aplicaciones: proxy de modelos, herramientas de agentes, trazas de observabilidad y automatización de workflows. Cada superficie debe emitir evidencia Proofstream real, respetar source timestamps y mantener secretos fuera de payloads, receipts, bundles, logs y código de navegador.

Scope

Esta página es para desarrolladores y operadores técnicos que integran Attesto en AI gateways, agent hosts, telemetry pipelines y herramientas de automatización. No documenta operaciones internas de staff y no sustituye los manuales de SDK, API, conectores o Local Vault. Úsala para elegir la superficie correcta y entender qué evidencia crea cada una.

Cuándo usar cada superficie

Inference Gateway

Attesto Inference Gateway es un proxy server-side para llamadas de modelos compatibles con OpenAI. Las aplicaciones le envían requests y solo cambian su URL base. Úsalo cuando no se puedan añadir llamadas SDK en cada aplicación o cuando la política de evidencia de modelos deba residir en un límite controlado.

El modo provenance de producción tiene dos servicios locales. Local Vault controla la firma de cápsulas, el almacenamiento cifrado, la detección independiente de marcas y la cola durable de commitment envelopes. El gateway solo controla la conexión de modelo permitida y, en transform, sus roles separados de claves de embedding. Genera las claves en archivos protegidos; sus bytes nunca son argumentos.

attesto-local-vault providers serve-daemons \
  --manifest-dir /opt/attesto/providers \
  --socket /var/lib/attesto/run/providers.sock \
  --auth-key-file /run/secrets/attesto-provider-ipc-key \
  --allowed-uid 10001 \
  --provenance-socket /var/lib/attesto/run/gateway-provenance.sock \
  --provenance-auth-key-file /run/secrets/attesto-gateway-provenance-key \
  --attestomark-detection-private-key-file /run/secrets/attestomark-detection-private \
  --attestomark-embedding-public-key-file /run/secrets/attestomark-embedding-public \
  --provenance-stream-id "$ATTESTO_STREAM_ID"

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --mode provenance-transform \
  --upstream https://api.openai.com \
  --upstream-allow-host api.openai.com \
  --provider-ipc-socket /var/lib/attesto/run/providers.sock \
  --provider-ipc-key-file /run/secrets/attesto-provider-ipc-key \
  --provenance-ipc-socket /var/lib/attesto/run/gateway-provenance.sock \
  --provenance-ipc-key-file /run/secrets/attesto-gateway-provenance-key \
  --attestomark-embedding-private-key-file /run/secrets/attestomark-embedding-private \
  --attestomark-detection-public-key-file /etc/attesto/attestomark-detection-public.hex

export OPENAI_BASE_URL=http://127.0.0.1:8765/v1

curl -sS "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer ${PROVIDER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Summarize this policy"}]}'

• Límite local: prompt, completion, modelo, host upstream, path, usage, finish reason, provider request id, status y latencia nunca salen de provenance en texto claro. Local Vault cifra el estado de recuperación y envía solo raíces de commitment aleatorizadas.
• Provider medido: el gateway debe mantener un lease Class D autenticado y activo para su binary digest exacto, versión, UID del sistema operativo y upstream allowlist. Una inscripción ausente o caducada rechaza la inferencia antes del upstream.
• Streaming: observe SSE es byte-exacto. Transform entrega de inmediato el primer contenido, conserva framing/control events y retiene solo el mark delta acotado y el terminal tail hasta que Local Vault haya journaled, finalizado y encolado la cápsula de forma durable.
• AttestoMark Text: el texto apto usa el esquema keyed versionado attesto.text.v1.x25519-aesgcm-ed25519-vs16. Una salida corta queda intacta con not_embedded_too_short; streams malformed, cancelled, over-limit o multi-output nunca pueden declarar embedding completado.
• Separación de claves: el gateway recibe roles embedding-private y detection-public. Local Vault recibe detection-private y embedding-public. Ninguna parte recibe el rol privado de la otra; son claves distintas de IPC, cápsula, queue y signing.
• Idempotency y recuperación: cada llamada recibe una source reference aleatorizada. Un replay durable exacto devuelve el mismo resultado de cápsula; se rechaza evidencia cambiada bajo una referencia. La caída de plataforma se gestiona en la finalized-envelope queue de Local Vault sin reprocesar contenido.
• Header redaction: Authorization, Proxy-Authorization, Cookie, Set-Cookie, api-key, x-api-key y headers que coincidan con token|secret|key nunca aparecen en eventos, logs, spool entries ni mensajes de error.
• Routing y TLS: el dialer dedicado ignora environment proxies, deniega redirects, valida certificados HTTPS y solo resuelve hosts exactos de --upstream-allow-host.
• Operations: monitoriza /healthz y /metrics en el admin listener separado. Un fallo de salud provenance es fail-closed y nunca vuelve a submission legacy.

MCP server

El Attesto MCP server expone un conjunto estrecho de herramientas Attesto deterministas a agent hosts compatibles con MCP. La superficie actual de herramientas es log_action, get_receipt, verify_receipt, get_stream_head y verify_completeness. El servidor registra acciones, obtiene receipts, verifica receipts offline, inspecciona stream heads y prueba que un rango de secuencia está gap-free sin entregar credenciales amplias del backend al agente. El MCP server debe ejecutarse server-side en el entorno runtime del agente. No contiene ningún modelo de AI, ningún import de proveedor AI ni lógica de decisión oculta; es un wrapper determinista de herramientas sobre el SDK de Attesto.

pip install attesto-mcp

{
  "mcpServers": {
    "attesto": {
      "command": "attesto-mcp",
      "args": ["--stdio"],
      "env": {
        "ATTESTO_BASE_URL": "https://verify.attesto.eu",
        "ATTESTO_API_KEY": "${ATTESTO_API_KEY}",
        "ATTESTO_STREAM_ID": "${ATTESTO_STREAM_ID}"
      }
    }
  }
}

attesto-mcp --stdio

• Guarda las credenciales MCP en el secret store del runtime del agente.
• No pases tenant API keys, provider API keys ni secretos raw del cliente mediante MCP tool arguments.
• Verificación local: verify_receipt y verify_completeness se ejecutan localmente; el trust anchor es la witness public key fijada, no una respuesta del backend de Attesto.
• Leak guard: los payloads se rechazan cuando contienen el valor de una environment variable que termina en _KEY, _TOKEN, _SECRET o _PASSWORD.
• Mantén los outputs de herramientas deterministas y orientados a receipts para que los logs de agentes se puedan verificar después.
• La package default base URL es overrideable a propósito; define explícitamente ATTESTO_BASE_URL=https://verify.attesto.eu para el servicio público de Attesto.
• Restringe las herramientas disponibles por rol de agente; no todos los agentes necesitan bundle export o stream creation.

OpenTelemetry bridge

El OpenTelemetry bridge convierte spans seleccionados en events Attesto. Es útil cuando la fuente de verdad ya es una trace pipeline: spans de model gateway, evaluación de políticas, sync de conectores o gestión de incidentes. El bridge debe filtrar con rigor; no envíes cada span por defecto.

pip install attesto opentelemetry-sdk

import os
from attesto import AttestoClient
from attesto.otel import AttestoSpanProcessor
from opentelemetry.sdk.trace import TracerProvider

provider = TracerProvider()
provider.add_span_processor(
    AttestoSpanProcessor(
        client=AttestoClient(api_key=os.environ["ATTESTO_API_KEY"]),
        stream_id=os.environ["ATTESTO_STREAM_ID"],
    )
)

• Event type: cada span finalizado se convierte en un evento commitment attesto.otel_span.
• Source reference: los spans usan source references deterministas otel:{trace_id}:{span_id}, así reenviar el mismo span es idempotente.
• Payload discipline: redacta attributes que puedan contener secretos o datos personales antes de que el processor los vea; Python usa attribute_allowlist y TypeScript usa attributeAllowlist.
• Commitment-only attributes: solo los attributes allowlisted se comprometen, como attributes_commitment más attribute_keys; los valores no allowlisted no se escriben en Attesto. Desactiva los attribute commitments por completo con commit_attributes=False o commitAttributes: false.
• Host safety: los failures del processor no rompen la aplicación host por defecto; usa strict=True o strict: true cuando un fallo de evidence capture deba fallar la request, y on_error/onError para observability.
• Sampling: alinea el sampling OTel con la política de evidencia; los spans descartados por sampling no pueden convertirse en evidencia después.
• Verification: los receipt IDs deben escribirse de vuelta en logs o trace attributes cuando sea posible.

n8n node

El Attesto n8n node es para automatización de workflows que necesita step evidence verificable. Úsalo para approval workflows, connector handoffs, triage de incidentes, policy checks y automatización orientada al cliente donde un auditor debe ver después qué ocurrió y cuándo.

npm install n8n-nodes-attesto

• Guarda las credenciales Attesto en n8n credentials, no en workflow JSON.
• Usa el action node para Log Event, Log Typed Compliance Event, Get Receipt y Verify Receipt (Offline).
• Offline receipt verification: Verify Receipt recalcula localmente el canonical hash y la firma Ed25519 contra la witness key fijada en la credencial n8n; los servidores de Attesto no se consultan.
• Webhook trigger: usa el trigger node solo para webhooks Attesto signature-verified. Verifica HMAC sobre timestamp.body con comparación constant-time y tolerancia de clock-skew de 300 s; las deliveries stale o forged reciben 401 y no inician workflows.
• Define explícitamente source object id y source timestamp para sistemas externos.
• No publiques workflows con tenant keys, provider tokens o payloads regulados raw incrustados.

Evidence model

Las cuatro superficies deben emitir evidencia con la misma semántica Proofstream que los SDKs. Un gateway request, MCP tool call, OTel span o n8n workflow step no es especial: es un source event con source reference, timestamp, normalized commitment, receipt e inclusión opcional posterior en windows, checkpoints, witnesses y anchors.

Security boundaries

• Ejecuta Gateway y MCP solo server-side; nunca pongas Attesto API keys en bundles de navegador.
• Mantén los secretos del upstream provider en el secret store del runtime propietario.
• Prefiere Local Vault cuando las credenciales de connector o edge deben permanecer del lado del cliente.
• Enmascara prompts, responses, trace attributes y workflow variables cuando contengan datos personales o secretos.
• Usa API keys scoped al tenant y revócalas cuando se retire un gateway, agent host, telemetry collector o workflow.

Operations

Trata estas superficies como integraciones de producción. Necesitan health checks, retry policy, rate-limit handling, idempotency, validación de source time y estados de fallo observables. Una superficie puede instalarse desde un package registry, pero no está production-ready para un tenant hasta que tenga una Attesto API key real, un stream real y un receipt/verify canary correcto.

Failure modes

Rollout checklist

• Elige una superficie y un production stream; no habilites todas las superficies a la vez.
• Guarda credenciales solo en secret stores server-side o en n8n credentials.
• Ejecuta un canary real event → receipt → verify antes de invitar usuarios.
• Documenta source timestamps, source references y retention policy.
• Añade dashboards o alertas para receipt failures, retry conflicts y secret-scan rejections.
• Actualiza tenant docs y changelog al habilitar una nueva superficie.