Implementierungsrezepte

Mit Attesto bauen, ohne zu raten.

Attesto lässt sich am einfachsten einführen, wenn Sie zuerst die Evidence-Oberfläche wählen: ein direktes SDK-Event, einen Proofstream-Stream, einen eingehenden Webhook, einen Connector, einen Local-Vault-Relay oder einen verifier-only Workflow. Diese Seite ordnet diese Entscheidungen konkreten Umsetzungsschritten zu.

Einen Pfad wählen

Rezept: ein Produktions-Event protokollieren

Verwenden Sie dies, wenn Ihre Anwendung die Entscheidung oder Aktion bereits kennt, die Evidence werden muss. Senden Sie nur aus serverseitigem Code. Halten Sie den System-Key im Secret Manager, bewahren Sie Idempotency Keys über Retries hinweg und protokollieren Sie stabile Source References, die Ihr Team nachvollziehen kann.

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

Rezept: Article 13 mit einer Zeile unterstützen und den Article 12 Report erzeugen

Wenn wir "Voldoe aan Artikel 13 met 1 regel code" sagen, meinen wir: Fügen Sie eine Attesto-Integrationszeile hinzu, die einen AI-Workflow in receipt-backed, verifier-ready Evidence für Transparenz und Instructions-for-use-Arbeit überführt. Der deterministische CLI-Befehl bleibt attesto report article12, weil der Report den technischen Logging Trail mit Article-12-artiger Logging Evidence verbindet. Article-13-Support hängt davon ab, wie der Kunde diese Evidence in Dokumentation, Nutzerinformation, Oversight und rechtlicher Bewertung verwendet. Attesto unterstützt mit Nachweisen; Attesto zertifiziert rechtliche Compliance nicht eigenständig.

Nutzen Sie den Decorator, wenn Sie die Funktionsgrenze kontrollieren, attestedFetch, wenn Sie in TypeScript den HTTP-Transport kontrollieren, und das Inference Gateway, wenn Sie einen sprach- und framework-neutralen Proxy für OpenAI-compatible Calls wollen.

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_..."))

Der Capture Path kann mit einem System API Key laufen. Der Report Path liest Tenant Stream Events, daher erzeugen Sie den finalen Report aus einem Tenant/operator Kontext oder übergeben Sie der CLI einen Tenant Token.

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

Rezept: einen Proofstream-Stream erstellen

Nutzen Sie Proofstream, wenn Reihenfolge wichtig ist. Ein Stream ist normalerweise auf Tenant, System, Use Case und Policy begrenzt. Jedes Event erhält eine Sequence Number und eine signierte Receipt. Spätere Windows, Checkpoints, Witnesses, Anchors und Bundles bauen auf dieser append-only Sequence auf.

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)

Rezept: Evidence vor Vertrauen verifizieren

Verifikation sollte Teil Ihres empfangenden Workflows sein. Wenn Ihr System eine Attesto Receipt oder ein Bundle erhält, verifizieren Sie es, bevor es in Audit File, Data Room, Assurance Report oder Regulator Package übernommen wird.

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

Ein fehlgeschlagener Report ist ebenfalls nützliche Evidence. Er sagt, ob das Objekt malformed, unvollständig, geändert, stale, ohne Witness Quorum, mit falscher Signature, an einen falschen Anchor gebunden oder mit Fork Evidence versehen ist.

Rezept: Attesto webhooks empfangen

Webhooks dienen Benachrichtigungen. Sie ersetzen Verifikation nicht. Verifizieren Sie die Signature über den Raw Request Body, deduplizieren Sie die Delivery ID, antworten Sie schnell und holen oder verifizieren Sie das referenzierte Evidence-Objekt im eigenen 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"));
}

Rezept: Connectors sicher verwenden

Connectors übersetzen Änderungen in Quellsystemen in Attesto Evidence. Verwenden Sie signed webhook connectors für eigene Systeme, GitHub/GitLab-Connectors für Repository Change References und S3/R2 Commitments für Object Evidence. Jeder Connector braucht echte Authentifizierung, Replay-Verhalten, Diagnostics und Revocation.

Rezept: Local Vault am Customer Edge deployen

Local Vault ist für Enterprise-Umgebungen gedacht, in denen Connector Secrets, Source Attestations und Outage Spooling kundenseitig bleiben sollen. Er relayed outbound zu Attesto und kann optional als Customer Witness in einer Quorum Policy dienen.

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

• Connector secrets lokal verschlüsselt speichern.
• Source attestations vor dem Relay signieren.
• Spoolen, wenn das ausgehende Netzwerk nicht verfügbar ist.
• Mit stabiler Idempotency replayen, wenn die Verbindung zurückkehrt.
• Witness-Status im Tenant und Verifier Bundle anzeigen.

Rezept: AI Calls über das Attesto Inference Gateway routen

Nutzen Sie das Gateway, wenn Teams bereits OpenAI-compatible Provider APIs aufrufen und Evidence wollen, ohne jede Anwendung umzuschreiben. Das Gateway leitet Requests an den konfigurierten Provider weiter und erfasst Commitments, Receipt References und sichere Metadata. Raw Prompts, Completions, API Keys und Provider Secrets bleiben im Gateway-Prozess und werden nicht an Attesto geschrieben.

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

Verwenden Sie commitments mode für Production Evidence. Verwenden Sie none nur, wenn ein Deployment Evidence Capture für eine bestimmte Umgebung bewusst deaktiviert. Das Gateway ist standardmäßig fail-open mit operator-visible Warnungen und einem fsynced Dead-letter Spool; ergänzen Sie --strict, wenn die Policy verlangt, dass Receipt Creation vor Upstream-Arbeit gelingt. Überwachen Sie /healthz und /metrics auf dem Admin Listener, und führen Sie attesto-gateway replay-spool nach Ausfällen aus.

Das Gateway attestiert OpenAI-kompatible /v1/chat/completions, /v1/completions, /v1/embeddings und /v1/responses Calls als Model-decision Evidence. Unbekannte Upstream Paths werden proxied und als generische HTTP-call Commitment Events erfasst, statt still verworfen zu werden.

Rezept: Attesto über MCP für Agent Tools bereitstellen

Der Attesto MCP Server gibt agentischen Systemen ein schmales, deterministisches Toolset: Aktion loggen, Receipt abrufen, Receipt offline verifizieren, Stream Head prüfen und Completeness checken. Er ist keine allgemeine Admin Surface und verweigert secret-looking Werte, bevor sie Evidence Payloads werden können.

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

Speichern Sie MCP Credentials im Secret Store der Agent Runtime. Übergeben Sie keine Dashboard Cookies, Admin Credentials, Private Keys, Provider API Keys oder raw Customer Secrets in MCP Tool Arguments.

Rezept: Attesto Evidence zu n8n Workflows hinzufügen

Verwenden Sie den Attesto n8n Node, wenn ein Workflow Step ein Evidence Receipt erzeugen soll. Der Action Node loggt typed Compliance Events, ruft Receipts ab und verifiziert Receipts offline. Der Trigger Node validiert signierte Attesto Webhooks mit Timestamp Tolerance, bevor ein Workflow weiterläuft.

npm install n8n-nodes-attesto

• Speichern Sie Attesto Credentials in n8n Credentials, nicht in Workflow JSON.
• Verwenden Sie stabile Workflow Execution IDs als Source References.
• Verifizieren Sie eingehende Webhook Signatures, bevor Sie auf Inhalte verzweigen.
• Erfassen Sie Failure Events für abgelehnte oder unvollständige Automation Steps.

Produktions-Rollout-Checkliste