Implementatierecepten

Bouw met Attesto zonder te gokken.

Attesto is het makkelijkst te adopteren wanneer je eerst het evidence-oppervlak kiest: een direct SDK-event, een Proofstream-stream, een inkomende webhook, een connector, een Local Vault-relay of een verifier-only workflow. Deze pagina koppelt die keuzes aan concrete implementatiestappen.

Kies een pad

Recept: log een productie-event

Gebruik dit wanneer je applicatie de beslissing of actie al kent die evidence moet worden. Verstuur alleen vanuit server-side code. Bewaar de systeemkey in je secret manager, behoud idempotency keys over retries heen en log stabiele source references die je team kan herleiden.

pip install attesto

python - <<'PY'
import os
from datetime import UTC, datetime
from attesto import AttestoClient

attesto = AttestoClient(api_key=os.environ["ATTESTO_API_KEY"])
ack = attesto.log_event(
    type="ai.decision",
    status="verified",
    ts=datetime.now(UTC),
    payload={
        "decision": "manual_review",
        "score": 91,
        "policy_id": "policy-2026-01",
        "model": "risk-service-v4"
    },
)
print(ack.id)
PY

Recept: ondersteun Article 13 met één regel en genereer het Article 12 report

Wanneer we zeggen "Voldoe aan Artikel 13 met 1 regel code", bedoelen we: voeg één Attesto-integratieregel toe die een AI-workflow omzet in receipt-backed, verifier-ready evidence voor transparantie en instructions-for-use werk. Het deterministische CLI-commando blijft attesto report article12, omdat het report de technische logging trail koppelt aan Article 12-achtige logging evidence. Article 13-support hangt af van hoe de klant dat bewijs gebruikt in documentatie, gebruikersinformatie, oversight en juridische interpretatie. Attesto levert bewijs-ondersteuning; het certificeert juridische compliance niet zelfstandig.

Gebruik de decorator wanneer je de function boundary beheert, attestedFetch wanneer je in TypeScript de HTTP-transportlaag beheert, en de Inference Gateway wanneer je een taal- en framework-neutrale proxy wilt voor OpenAI-compatible calls.

from attesto import AttestoClient, AttestoV2Client, attest, article12
import os

capture = AttestoClient(api_key=os.environ["ATTESTO_API_KEY"])

@attest(capture, stream_id="str_...")
def decide(payload: dict) -> dict:
    return {"decision": "manual_review", "policy_id": "policy-2026-01"}

result = decide({"case_id": "case-2026-0001"})
operator = AttestoV2Client.with_bearer_token(os.environ["ATTESTO_TENANT_TOKEN"])
print(article12(operator, "str_..."))

De capture path kan met een system API key draaien. De report path leest tenant stream events, dus genereer het finale report vanuit een tenant/operator context of geef een tenant token door aan de CLI.

import { AttestoV2Client, attestedFetch } from "@attesto/sdk";

const attesto = new AttestoV2Client({ apiKey: process.env.ATTESTO_API_KEY! });
const fetchWithEvidence = attestedFetch(attesto, { streamId: "str_...", strict: true });

attesto --token-env ATTESTO_TENANT_TOKEN \
  report article12 --stream str_... --output report.md

Recept: maak een Proofstream-stream

Gebruik Proofstream wanneer volgorde belangrijk is. Een stream is normaal scoped op tenant, systeem, use case en policy. Elk event krijgt een sequence number en een gesigneerde receipt. Latere windows, checkpoints, witnesses, anchors en bundles bouwen voort op die append-only sequence.

from attesto import AttestoV2Client
from datetime import UTC, datetime
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    stream = attesto.create_stream(
        use_case="ai-decision-history",
        policy_id="policy-2026-01",
        metadata={"owner": "risk-platform", "environment": "production"},
    )
    receipt = attesto.log_event(
        stream_id=stream.stream_id,
        source_ref="case-2026-0001:decision-1",
        event_type="ai.decision",
        occurred_at=datetime.now(UTC),
        payload={"decision": "manual_review", "score": 91},
    )
    print(receipt.stream_event_id, receipt.seq_no)

Recept: verifieer evidence voordat je erop vertrouwt

Verificatie hoort onderdeel te zijn van je ontvangende workflow. Als je systeem een Attesto receipt of bundle ontvangt, verifieer die dan voordat je hem opneemt in een auditdossier, data room, assurance-rapport of regulatorpakket.

curl -X POST https://verify.attesto.eu/v2/verify \
  -H "Content-Type: application/json" \
  --data-binary @attesto-bundle.json

attesto --json bundles verify \
  --file ./attesto-bundle.json > ./verification-report.json

Een falend rapport is ook nuttige evidence. Het vertelt of het object malformed, incompleet, gewijzigd, stale, zonder witness quorum, met verkeerde signature, aan een verkeerde anchor gebonden of voorzien van fork evidence is.

Recept: ontvang Attesto webhooks

Webhooks zijn voor notificaties. Ze vervangen verificatie niet. Verifieer de signature over de raw request body, dedupliceer de delivery ID, antwoord snel en fetch of verifieer het gerefereerde evidence-object in je eigen worker.

import crypto from "node:crypto";

function verifyAttestoWebhook({ rawBody, timestamp, signature, secret }) {
  const message = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(message)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));
}

Recept: gebruik connectors veilig

Connectors vertalen wijzigingen in bronsystemen naar Attesto evidence. Gebruik signed webhook connectors voor maatwerksystemen, GitHub/GitLab-connectors voor repository references en S3/R2 commitments voor object-evidence. Elke connector moet echte authenticatie, replaygedrag, diagnostics en revocation hebben.

Recept: deploy Local Vault aan de klant-edge

Local Vault is bedoeld voor enterprise-omgevingen waar connector secrets, source attestations en outage spooling klantzijdig moeten blijven. Het relayed outbound naar Attesto en kan optioneel als customer witness in een quorum policy werken.

pipx install attesto-local-vault

export ATTESTO_LOCAL_VAULT_SPOOL_DB=/var/lib/attesto/local-vault.sqlite3
export ATTESTO_LOCAL_VAULT_INSTALLATION_ID="$ATTESTO_LOCAL_VAULT_INSTALLATION_ID"
export ATTESTO_LOCAL_VAULT_RELAY_URL="https://verify.attesto.eu/v2/local-vault/installations/$ATTESTO_LOCAL_VAULT_INSTALLATION_ID/events"

attesto-local-vault drain-loop

• Sla connector secrets lokaal versleuteld op.
• Sign source attestations voordat relay plaatsvindt.
• Spool wanneer outbound netwerk niet beschikbaar is.
• Replay met stabiele idempotency wanneer connectiviteit terugkomt.
• Toon witness-status in de tenant en verifier bundle.

Recept: route AI-calls via de Attesto Inference Gateway

Gebruik de gateway wanneer teams al OpenAI-compatible provider APIs aanroepen en evidence willen zonder elke applicatie te herschrijven. De gateway forwardt requests naar de geconfigureerde provider en legt commitments, receipt references en veilige metadata vast. Raw prompts, completions, API keys en provider secrets blijven in het gateway proces en worden niet naar Attesto geschreven.

export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"
export ATTESTO_BASE_URL=https://verify.attesto.eu
export OPENAI_BASE_URL=http://localhost:8765/v1

attesto-gateway --listen 127.0.0.1:8765 \
  --admin-listen 127.0.0.1:8766 \
  --attesto-base-url "$ATTESTO_BASE_URL" \
  --upstream "$AI_PROVIDER_BASE_URL" \
  --stream-id "$ATTESTO_STREAM_ID" \
  --capture commitments

Gebruik commitments mode voor production evidence. Gebruik none alleen wanneer een deployment evidence capture bewust uitschakelt voor een specifieke omgeving. De gateway is standaard fail-open met operator-visible waarschuwingen en een fsynced dead-letter spool; voeg --strict toe wanneer beleid vereist dat receipt creation slaagt voordat upstream werk doorgaat. Monitor /healthz en /metrics op de admin listener, en draai attesto-gateway replay-spool na storingen.

De gateway attesteert OpenAI-compatible /v1/chat/completions, /v1/completions, /v1/embeddings en /v1/responses calls als model-decision evidence. Onbekende upstream paths worden geproxied en vastgelegd als generieke HTTP-call commitment events, in plaats van stil te worden genegeerd.

Recept: stel Attesto beschikbaar aan agent tools via MCP

De Attesto MCP server geeft agentic systemen een smalle, deterministische set tools: actie loggen, receipt ophalen, receipt offline verifiëren, stream head inspecteren en completeness checken. Het is geen algemeen admin surface en weigert secret-looking waarden voordat ze evidence payload kunnen worden.

pip install attesto-mcp

{
  "mcpServers": {
    "attesto": {
      "command": "attesto-mcp",
      "env": {
        "ATTESTO_API_KEY": "${ATTESTO_SYSTEM_KEY}",
        "ATTESTO_BASE_URL": "https://verify.attesto.eu"
      }
    }
  }
}

export ATTESTO_BASE_URL=https://verify.attesto.eu
export ATTESTO_API_KEY="$ATTESTO_SYSTEM_KEY"

attesto-mcp --stdio

Bewaar MCP credentials in de secret store van de agent runtime. Geef geen dashboard cookies, admin credentials, private keys, provider API keys of raw customer secrets door via MCP tool arguments.

Recept: voeg Attesto evidence toe aan n8n workflows

Gebruik de Attesto n8n node wanneer een workflow step een evidence receipt moet produceren. De action node logt typed compliance events, haalt receipts op en verifieert receipts offline. De trigger node valideert signed Attesto webhooks met timestamp tolerance voordat een workflow verdergaat.

npm install n8n-nodes-attesto

• Bewaar Attesto credentials in n8n credentials, niet in workflow JSON.
• Gebruik stabiele workflow execution IDs als source references.
• Verifieer incoming webhook signatures voordat je op de inhoud brancht.
• Leg failure events vast voor geweigerde of incomplete automation steps.

Productie-rollout checklist