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 inviano requests al gateway; il gateway inoltra al provider upstream configurato e scrive Attesto evidence prima di restituire la risposta del provider. Usalo quando i team non possono aggiungere chiamate SDK in ogni applicazione, oppure quando servono policy centrale e model routing.

export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"
export OPENAI_BASE_URL=http://127.0.0.1:8765/v1

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --attesto-base-url https://verify.attesto.eu \
  --upstream https://api.openai.com/v1 \
  --stream-id "$ATTESTO_STREAM_ID" \
  --capture commitments

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

• Capture mode: committa metadati di request e response, non raw secrets o provider credentials.
• Modalità consentite: commitments e none sono le uniche capture modes; la cattura raw di prompt/response deliberatamente non esiste.
• Percorsi compatibili OpenAI: /v1/chat/completions, /v1/completions, /v1/embeddings e /v1/responses creano eventi attesto.model_decision. Gli altri percorsi vengono proxati senza modifiche e attestati come eventi commitment generici http_call.
• Streaming: le response SSE passano byte-for-byte con flush immediato; il gateway ricompone lo stream dopo la conclusione solo per calcolare i commitments.
• Source time: preserva il timestamp del caller quando fornito; altrimenti registra gateway receive time con timezone.
• Idempotency: usa request id o source reference così i retry non creano una storia conflittuale.
• Delivery: gli eventi usano una queue limitata e batch in background. Outage di Attesto o overflow della queue finiscono in un dead-letter spool NDJSON con fsync, riprodotto automaticamente o con attesto-gateway replay-spool. --spool-max-bytes è l'unico punto di drop ed è contato e loggato in modo evidente.
• 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.
• Fail behavior: il gateway è fail-open di default con warning e fsynced spool; aggiungi --strict quando la policy richiede che receipt creation riesca prima che il lavoro upstream continui.
• Routing e TLS: mantieni attiva la verifica TLS dell'upstream e usa entry --route esplicite per deploy multi-upstream.
• Operations: monitora /healthz e /metrics su --admin-listen, e usa attesto-gateway replay-spool dopo outages.

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.