Recettes d'implémentation

Construire avec Attesto sans deviner.

Attesto s'adopte plus facilement lorsque vous choisissez d'abord la surface de preuve : un événement SDK direct, un stream Proofstream, un webhook entrant, un connecteur, un relais Local Vault ou un workflow verifier-only. Cette page relie ces choix à des étapes d'implémentation concrètes.

Choisir un parcours

Recette : journaliser un événement de production

Utilisez ceci lorsque votre application connaît déjà la décision ou l'action qui doit devenir une preuve. Envoyez uniquement depuis du code côté serveur. Conservez la clé système dans votre secret manager, préservez les idempotency keys entre retries et journalisez des source references stables que votre équipe peut tracer.

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

Recette : soutenir l'Article 13 avec une ligne et générer le rapport Article 12

Quand nous disons "Voldoe aan Artikel 13 met 1 regel code", cela signifie : ajouter une ligne d'intégration Attesto qui transforme un workflow AI en preuve receipt-backed et verifier-ready pour la transparence et les instructions d'utilisation. La commande CLI déterministe reste attesto report article12, car le rapport relie la trace technique de journalisation à une preuve de logging de type Article 12. Le support Article 13 dépend de la manière dont le client utilise cette preuve dans la documentation, l'information utilisateur, l'oversight et l'analyse juridique. Attesto fournit un support de preuve; il ne certifie pas la conformité juridique à lui seul.

Utilisez le décorateur lorsque vous contrôlez la frontière de fonction, attestedFetch lorsque vous contrôlez le transport HTTP en TypeScript, et l'Inference Gateway lorsque vous voulez un proxy neutre en langage et framework pour les appels OpenAI-compatible.

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

Le chemin de capture peut utiliser une system API key. Le chemin de rapport lit les tenant stream events; générez donc le rapport final depuis un contexte tenant/operator ou transmettez un tenant token à la 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

Recette : créer un stream Proofstream

Utilisez Proofstream lorsque l'ordre compte. Un stream est généralement limité à un tenant, un système, un cas d'usage et une policy. Chaque événement reçoit un sequence number et une receipt signée. Les windows, checkpoints, witnesses, anchors et bundles ultérieurs s'appuient sur cette séquence append-only.

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)

Recette : vérifier la preuve avant de s'y fier

La vérification doit faire partie de votre workflow récepteur. Si votre système reçoit une Attesto receipt ou un bundle, vérifiez-le avant de l'accepter dans un dossier d'audit, une data room, un rapport d'assurance ou un package régulateur.

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

Un rapport en échec est aussi une preuve utile. Il indique si l'objet était malformed, incomplet, modifié, stale, sans witness quorum, avec une mauvaise signature, lié à un mauvais anchor ou porteur de fork evidence.

Recette : recevoir des webhooks Attesto

Les webhooks servent aux notifications. Ils ne remplacent pas la vérification. Vérifiez la signature sur le raw request body, dédupliquez le delivery ID, répondez vite, puis récupérez ou vérifiez l'objet de preuve référencé dans votre propre 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"));
}

Recette : utiliser les connecteurs en sécurité

Les connecteurs traduisent les changements des systèmes source en preuve Attesto. Utilisez des signed webhook connectors pour les systèmes personnalisés, les connecteurs GitHub/GitLab pour les repository change references et les S3/R2 commitments pour la preuve d'objet. Chaque connecteur doit avoir une authentification réelle, un comportement de replay, des diagnostics et une révocation.

Recette : déployer Local Vault côté client

Local Vault s'adresse aux environnements enterprise où les connector secrets, source attestations et outage spooling doivent rester côté client. Il relaie en sortie vers Attesto et peut optionnellement agir comme customer witness dans une quorum policy.

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

• Stocker les connector secrets chiffrés localement.
• Signer les source attestations avant le relay.
• Spooler lorsque le réseau sortant est indisponible.
• Rejouer avec une idempotency stable lorsque la connectivité revient.
• Exposer le statut witness au tenant et au verifier bundle.

Recette : router les appels AI via Attesto Inference Gateway

Utilisez le gateway lorsque les équipes appellent déjà des APIs provider OpenAI-compatible et veulent de l'evidence sans réécrire chaque application. Le gateway transmet les requêtes au provider configuré et enregistre commitments, receipt references et metadata sûre. Les raw prompts, completions, API keys et provider secrets restent dans le processus gateway et ne sont pas écrits dans Attesto.

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

Utilisez le mode commitments pour l'evidence de production. Utilisez none uniquement lorsqu'un déploiement désactive volontairement la capture d'evidence pour un environnement précis. La gateway est fail-open par défaut avec des avertissements visibles par l'opérateur et un dead-letter spool fsync; ajoutez --strict lorsque la politique exige que la création du receipt réussisse avant de continuer vers l'upstream. Surveillez /healthz et /metrics sur l'admin listener, et exécutez attesto-gateway replay-spool après une panne.

Le gateway atteste les appels OpenAI-compatible /v1/chat/completions, /v1/completions, /v1/embeddings et /v1/responses comme evidence de model decision. Les chemins upstream inconnus sont proxifiés et enregistrés comme événements génériques de commitment HTTP-call au lieu d'être ignorés silencieusement.

Recette : exposer Attesto aux agent tools via MCP

Le serveur MCP Attesto donne aux systèmes agentiques un ensemble d'outils étroit et déterministe: journaliser une action, récupérer un receipt, vérifier un receipt offline, inspecter un stream head et contrôler la completeness. Ce n'est pas une surface admin générale et il refuse les valeurs qui ressemblent à des secrets avant qu'elles ne deviennent des payloads d'evidence.

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

Gardez les credentials MCP dans le secret store de l'agent runtime. Ne transmettez pas de dashboard cookies, admin credentials, private keys, provider API keys ou raw customer secrets dans les arguments d'outils MCP.

Recette : ajouter Attesto evidence aux workflows n8n

Utilisez le node Attesto n8n lorsqu'une étape de workflow doit produire un evidence receipt. Le node action journalise des typed compliance events, récupère des receipts et vérifie des receipts offline. Le node trigger valide les signed Attesto webhooks avec timestamp tolerance avant que le workflow continue.

npm install n8n-nodes-attesto

• Stockez les credentials Attesto dans les credentials n8n, pas dans le JSON du workflow.
• Utilisez des workflow execution IDs stables comme source references.
• Vérifiez les incoming webhook signatures avant de brancher sur leur contenu.
• Enregistrez des failure events pour les étapes d'automation rejetées ou incomplètes.

Checklist de rollout production