Developer surfaces

Gateway, MCP, OTel e n8n

Gli SDK principali di Attesto coprono l'integrazione diretta nelle applicazioni. Gateway, MCP, OpenTelemetry e n8n coprono i sistemi che stanno intorno alle applicazioni: proxy dei modelli, strumenti per agenti, trace di osservabilità e automazione dei workflow. Ogni superficie deve emettere vera Proofstream evidence, rispettare i source timestamps e tenere i secrets fuori da payloads, receipts, bundles, logs e codice browser.

Scope

Questa pagina è per developer e operatori tecnici che integrano Attesto in AI gateways, agent hosts, telemetry pipelines e strumenti di automazione. Non documenta operazioni interne di staff e non sostituisce i manuali SDK, API, connectors o Local Vault. Usala per scegliere la superficie corretta e capire quale evidence produce ciascuna.

Quando usare ogni superficie

Inference Gateway

Attesto Inference Gateway è un proxy server-side per chiamate modello compatibili OpenAI. Le applicazioni gli inviano requests e cambiano solo la base URL. Usalo quando non è possibile aggiungere chiamate SDK in ogni applicazione o quando la policy di evidence dei modelli deve risiedere su un unico confine controllato.

Il provenance mode di produzione comprende due servizi locali. Local Vault controlla capsule signing, encrypted storage, rilevamento indipendente della marca e coda durevole dei commitment envelopes. Il gateway controlla solo la connessione modello esplicitamente consentita e, in transform, i ruoli separati delle chiavi di embedding. Genera le chiavi in file protetti; i key bytes non sono mai argomenti.

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"}]}'

• Confine locale: prompt, completion, model, upstream host, path, usage, finish reason, provider request id, status e latency non lasciano mai provenance come plaintext. Local Vault cifra il recovery state e invia solo commitment roots randomizzati.
• Provider misurato: il gateway deve mantenere un lease Class D autenticato attivo per binary digest esatto, versione, UID del sistema operativo e upstream allowlist. Una registrazione assente o scaduta rifiuta l'inference prima dell'upstream call.
• Streaming: observe SSE è byte-exact. Transform inoltra subito il primo content, preserva framing/control events e trattiene solo il mark delta limitato e il terminal tail finché Local Vault non ha journaled, finalizzato e accodato durevolmente la capsule.
• AttestoMark Text: il testo idoneo usa lo schema keyed versionato attesto.text.v1.x25519-aesgcm-ed25519-vs16. Un output corto resta invariato con not_embedded_too_short; stream malformed, cancelled, over-limit o multi-output non possono mai dichiarare completed embedding.
• Separazione chiavi: il gateway riceve i ruoli embedding-private e detection-public. Local Vault riceve detection-private e embedding-public. Nessuna parte riceve il ruolo privato dell'altra; sono chiavi diverse da IPC, capsule, queue e signing keys.
• Idempotency e recovery: ogni call riceve una source reference randomizzata. Un replay durevole esatto restituisce lo stesso risultato capsule; evidence modificata sotto una reference viene rifiutata. Un outage piattaforma è gestito dalla finalized-envelope queue di Local Vault senza rielaborare il content.
• Header redaction: Authorization, Proxy-Authorization, Cookie, Set-Cookie, api-key, x-api-key e header che corrispondono a token|secret|key non appaiono mai in eventi, log, spool entries o messaggi di errore.
• Routing e TLS: il dialer dedicato ignora environment proxies, nega redirects, valida certificati HTTPS e risolve solo host esatti in --upstream-allow-host.
• Operations: monitora /healthz e /metrics sull'admin listener separato. Un errore di provenance health è fail-closed e non torna mai a legacy submission.

MCP server

Attesto MCP server espone un set ristretto di tools Attesto deterministici agli agent hosts compatibili MCP. La tool surface attuale è log_action, get_receipt, verify_receipt, get_stream_head e verify_completeness. Il server logga actions, recupera receipts, verifica receipts offline, ispeziona stream heads e dimostra che un sequence range è gap-free senza dare all'agente credenziali backend ampie. Il MCP server dovrebbe girare server-side nell'ambiente runtime dell'agente. Non contiene un modello AI, import di AI vendor o logica decisionale nascosta; è un wrapper deterministico di tools sopra l'Attesto SDK.

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

• Conserva le credenziali MCP nel secret store del runtime agente.
• Non passare tenant API keys, provider API keys o raw customer secrets tramite MCP tool arguments.
• Verifica locale: verify_receipt e verify_completeness girano localmente; il trust anchor è la witness public key pinnata, non una risposta backend di Attesto.
• Leak guard: i payloads vengono rifiutati quando contengono il valore di una environment variable che termina con _KEY, _TOKEN, _SECRET o _PASSWORD.
• Mantieni gli output dei tools deterministici e orientati ai receipts, così gli agent logs restano verificabili più tardi.
• La package default base URL è volutamente overrideable; imposta esplicitamente ATTESTO_BASE_URL=https://verify.attesto.eu per il servizio pubblico Attesto.
• Limita i tools disponibili per agent role; non ogni agente necessita bundle export o stream creation.

OpenTelemetry bridge

OpenTelemetry bridge trasforma spans selezionati in Attesto events. È utile quando la source of truth è già una trace pipeline: spans di model gateway, policy evaluation, connector sync o incident handling. Il bridge deve filtrare in modo rigoroso; non inviare ogni span di default.

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: ogni span terminato diventa un commitment event attesto.otel_span.
• Source reference: gli spans usano source references deterministici otel:{trace_id}:{span_id}, quindi reinviare lo stesso span è idempotente.
• Payload discipline: redigi attributes che possono contenere secrets o dati personali prima che il processor li veda; Python usa attribute_allowlist e TypeScript usa attributeAllowlist.
• Commitment-only attributes: solo gli attributes allowlisted vengono committati, come attributes_commitment più attribute_keys; i valori non allowlisted non vengono scritti in Attesto. Disattiva del tutto gli attribute commitments con commit_attributes=False o commitAttributes: false.
• Host safety: i processor failures non interrompono la host app di default; usa strict=True o strict: true quando un evidence capture failure deve far fallire la request, e on_error/onError per observability.
• Sampling: allinea OTel sampling alla evidence policy; gli spans campionati fuori non possono diventare evidence più tardi.
• Verification: i receipt IDs dovrebbero essere riscritti in logs o trace attributes quando possibile.

n8n node

Attesto n8n node è per automazione workflow che richiede step evidence verificabile. Usalo per approval workflows, connector handoffs, incident triage, policy checks e automazione customer-facing dove un auditor deve poter vedere più tardi cosa è successo e quando.

npm install n8n-nodes-attesto

• Conserva le credenziali Attesto in n8n credentials, non nel workflow JSON.
• Usa l'action node per Log Event, Log Typed Compliance Event, Get Receipt e Verify Receipt (Offline).
• Offline receipt verification: Verify Receipt ricalcola localmente il canonical hash e la firma Ed25519 contro la witness key pinnata nella credenziale n8n; i server Attesto non vengono consultati.
• Webhook trigger: usa il trigger node solo per webhooks Attesto signature-verified. Verifica HMAC su timestamp.body con constant-time comparison e tolleranza clock-skew di 300 s; deliveries stale o forged ricevono 401 e non avviano workflows.
• Imposta source object id e source timestamp esplicitamente per sistemi esterni.
• Non pubblicare workflows con tenant keys, provider tokens o raw regulated payloads incorporati.

Evidence model

Tutte e quattro le superfici dovrebbero emettere evidence tramite la stessa semantica Proofstream degli SDKs. Un gateway request, MCP tool call, OTel span o n8n workflow step non è speciale: è un source event con source reference, timestamp, normalized commitment, receipt e inclusione opzionale successiva in windows, checkpoints, witnesses e anchors.

Security boundaries

• Esegui Gateway e MCP solo server-side; non mettere mai Attesto API keys nei browser bundles.
• Mantieni gli upstream provider secrets nel secret store del runtime proprietario.
• Preferisci Local Vault quando connector o edge credentials devono restare lato cliente.
• Maschera prompts, responses, trace attributes e workflow variables quando contengono dati personali o secrets.
• Usa API keys scoped al tenant e revocale quando gateway, agent host, telemetry collector o workflow viene ritirato.

Operations

Tratta queste superfici come integrazioni di produzione. Servono health checks, retry policy, rate-limit handling, idempotency, validazione source-time e failure states osservabili. Una superficie può essere installata da un package registry, ma non è production-ready per un tenant finché non ha una vera Attesto API key, uno stream reale e una successful receipt/verify canary.

Failure modes

Rollout checklist

• Scegli una superficie e uno stream di produzione; non abilitare tutte le superfici insieme.
• Conserva credentials solo in server-side secret stores o n8n credentials.
• Esegui una vera canary event → receipt → verify prima di invitare utenti.
• Documenta source timestamps, source references e retention policy.
• Aggiungi dashboards o alerts per receipt failures, retry conflicts e secret-scan rejections.
• Aggiorna tenant docs e changelog quando abiliti una nuova superficie.