Developer surfaces

Gateway, MCP, OTel en n8n

De kern-SDKs van Attesto dekken directe applicatie-integratie. Gateway, MCP, OpenTelemetry en n8n dekken de systemen rondom applicaties: modelproxying, agent tools, observability-traces en workflowautomatisering. Elk oppervlak moet echte Proofstream-evidence schrijven, source timestamps respecteren en secrets buiten payloads, receipts, bundles, logs en browsercode houden.

Scope

Deze pagina is voor developers en technische operators die Attesto integreren in AI-gateways, agent hosts, telemetry pipelines en automatiseringstools. De pagina documenteert geen interne staff-operaties en vervangt de SDK-, API-, connector- of Local Vault-handleidingen niet. Gebruik hem om het juiste oppervlak te kiezen en te begrijpen welke evidence elk oppervlak maakt.

Wanneer gebruik je welk oppervlak

Inference Gateway

De Attesto Inference Gateway is een server-side proxy voor OpenAI-compatible model calls. Applicaties sturen requests naar de gateway en wijzigen alleen hun base URL. Gebruik hem wanneer teams niet in elke applicatie SDK-calls kunnen toevoegen, of wanneer het evidencebeleid voor modellen op één gecontroleerde grens hoort.

Production provenance mode bestaat uit twee lokale services. Local Vault beheert capsule signing, encrypted storage, onafhankelijke mark-detectie en de duurzame queue voor commitment envelopes. De gateway beheert alleen de expliciet toegestane modelverbinding en, in transform mode, zijn gescheiden embedding-keyrollen. Genereer keys naar beschermde bestanden; keybytes zijn nooit command-linewaarden.

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

• Lokale grens: prompt, completion, model, upstream host, path, usage, finish reason, provider request id, status en latency verlaten provenance mode nooit als plaintext. Local Vault versleutelt recovery state en verstuurt uitsluitend gerandomiseerde commitment roots.
• Gemeten provider: de gateway moet een live authenticated Class D lease hebben voor zijn exacte binary digest, versie, operating-system UID en upstream allowlist. Ontbrekende of verlopen registratie weigert inference vóór de upstream call.
• Streaming: observe SSE is byte-exact. Transform stuurt de eerste content direct door, bewaart framing/control events en houdt alleen de begrensde mark delta plus terminal tail vast totdat Local Vault de capsule duurzaam heeft gejournaled, gefinaliseerd en gequeued.
• AttestoMark Text: geschikte tekst gebruikt het versioned keyed schema attesto.text.v1.x25519-aesgcm-ed25519-vs16. Korte output blijft ongewijzigd met not_embedded_too_short; malformed, cancelled, over-limit of multi-output streams kunnen nooit completed embedding claimen.
• Keyscheiding: de gateway ontvangt embedding-private en detection-public rollen. Local Vault ontvangt detection-private en embedding-public rollen. Geen van beide krijgt de andere private rol en deze keys verschillen van IPC-, capsule-, queue- en signing keys.
• Idempotency en recovery: elke call krijgt een gerandomiseerde source reference. Exacte duurzame replay levert hetzelfde capsule-resultaat; gewijzigde evidence onder één reference wordt geweigerd. Platformuitval wordt afgehandeld door de Local Vault finalized-envelope queue zonder content opnieuw te verwerken.
• Header redaction: Authorization, Proxy-Authorization, Cookie, Set-Cookie, api-key, x-api-key en headers die matchen op token|secret|key verschijnen nooit in events, logs, spool entries of foutmeldingen.
• Routing en TLS: de custom dialer negeert environment proxies, weigert redirects, valideert HTTPS-certificaten en resolveert alleen exacte hosts uit --upstream-allow-host.
• Operations: monitor /healthz en /metrics op de aparte admin listener. Een provenance health failure is fail-closed en valt nooit terug op legacy submission.

MCP server

De Attesto MCP server biedt een smalle set deterministische Attesto tools aan MCP-compatible agent hosts. De huidige tool surface is log_action, get_receipt, verify_receipt, get_stream_head en verify_completeness. De server logt acties, haalt receipts op, verifieert receipts offline, inspecteert stream heads en bewijst dat een sequence range gap-free is zonder de agent brede backend credentials te geven. De MCP server hoort server-side in de agent-runtimeomgeving te draaien. Hij bevat geen AI-model, geen AI-vendor imports en geen verborgen beslislogica; het is een deterministische tool-wrapper rond de 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

• Bewaar MCP credentials in de secret store van de agent-runtime.
• Geef geen tenant API keys, provider API keys of raw customer secrets door via MCP tool arguments.
• Lokale verificatie: verify_receipt en verify_completeness draaien lokaal; de trust anchor is de gepinde witness public key, niet een Attesto backend response.
• Leak guard: payloads worden geweigerd wanneer ze de waarde bevatten van een environment variable die eindigt op _KEY, _TOKEN, _SECRET of _PASSWORD.
• Houd tool outputs deterministisch en receipt-georiënteerd zodat agent logs later verifieerbaar blijven.
• De package default base URL is bewust overrideable; zet ATTESTO_BASE_URL=https://verify.attesto.eu expliciet voor de publieke Attesto-service.
• Beperk beschikbare tools per agent role; niet elke agent heeft bundle export of stream creation nodig.

OpenTelemetry bridge

De OpenTelemetry bridge zet geselecteerde spans om in Attesto events. Dit is nuttig wanneer de trace pipeline al de bron van waarheid is: model-gateway spans, policy-evaluatie spans, connector-sync spans of incidentafhandelingsspans. De bridge moet agressief filteren; stuur niet standaard elke span door.

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: elke beëindigde span wordt één attesto.otel_span commitment event.
• Source reference: spans gebruiken deterministische otel:{trace_id}:{span_id} source references, zodat dezelfde span opnieuw sturen idempotent is.
• Payload discipline: redacteer attributes die secrets of persoonsgegevens kunnen bevatten voordat de processor ze ziet; Python gebruikt attribute_allowlist en TypeScript gebruikt attributeAllowlist.
• Commitment-only attributes: alleen allowlisted attributes worden vastgelegd, als attributes_commitment plus attribute_keys; niet-allowlisted waarden worden niet naar Attesto geschreven. Schakel attribute commitments helemaal uit met commit_attributes=False of commitAttributes: false.
• Host safety: processor failures breken de host app standaard niet; gebruik strict=True of strict: true wanneer evidence-capture failure de request moet laten falen, en gebruik on_error/onError voor observability.
• Sampling: stem OTel sampling af op evidencebeleid; spans die zijn weggesampled kunnen later geen evidence worden.
• Verification: receipt IDs moeten waar mogelijk teruggeschreven worden naar logs of trace attributes.

n8n node

De Attesto n8n node is bedoeld voor workflowautomatisering die verifieerbare step evidence nodig heeft. Gebruik hem voor approvals, connector-handoffs, incidenttriage, policy checks en klantgerichte automatisering waarbij een auditor later moet kunnen zien wat er gebeurde en wanneer.

npm install n8n-nodes-attesto

• Bewaar Attesto credentials in n8n credentials, niet in workflow JSON.
• Gebruik de action node voor Log Event, Log Typed Compliance Event, Get Receipt en Verify Receipt (Offline).
• Offline receipt verification: Verify Receipt berekent de canonical hash en Ed25519 signature lokaal opnieuw tegen de witness key die in de n8n credential is gepind; Attesto servers worden niet geraadpleegd.
• Webhook trigger: gebruik de trigger node alleen voor signature-verified Attesto webhooks. Hij verifieert HMAC over timestamp.body met constant-time comparison en 300 s clock-skew tolerance; stale of forged deliveries krijgen 401 en starten geen workflow.
• Zet source object id en source timestamp expliciet voor externe systemen.
• Publiceer geen workflows met embedded tenant keys, provider tokens of raw regulated payloads.

Evidence model

Alle vier oppervlakken horen evidence uit te sturen via dezelfde Proofstream-semantiek als de SDKs. Een gateway request, MCP tool call, OTel span of n8n workflow step is niet speciaal: het is een source event met een source reference, timestamp, normalized commitment, receipt en optionele inclusion in latere windows, checkpoints, witnesses en anchors.

Security boundaries

• Draai Gateway en MCP alleen server-side; plaats nooit Attesto API keys in browser bundles.
• Houd upstream provider secrets in de secret store van de runtime die eigenaar is.
• Gebruik bij voorkeur Local Vault wanneer connector- of edge-credentials klantzijdig moeten blijven.
• Mask prompts, responses, trace attributes en workflow variables wanneer ze persoonsgegevens of secrets bevatten.
• Gebruik tenant-scoped API keys en revoke ze wanneer een gateway, agent host, telemetry collector of workflow buiten gebruik gaat.

Operations

Behandel deze oppervlakken als productie-integraties. Ze hebben health checks, retry policy, rate-limit handling, idempotency, source-time-validatie en observeerbare failure states nodig. Een oppervlak kan uit een package registry geïnstalleerd zijn, maar is pas production-ready voor een tenant wanneer het een echte Attesto API key, een echte stream en een succesvolle receipt/verify canary heeft.

Failure modes

Rollout checklist

• Kies één oppervlak en één production stream; activeer niet alles tegelijk.
• Bewaar credentials alleen in server-side secret stores of n8n credentials.
• Draai één echt event → receipt → verify canary voordat je gebruikers uitnodigt.
• Documenteer source timestamps, source references en retention policy.
• Voeg dashboards of alerts toe voor receipt failures, retry conflicts en secret-scan rejections.
• Werk tenant docs en changelog bij wanneer je een nieuw oppervlak activeert.