Ricette di implementazione

Costruire con Attesto senza indovinare.

Attesto è più semplice da adottare quando scegli prima la superficie di evidenza: un evento SDK diretto, uno stream Proofstream, un webhook in ingresso, un connettore, un relay Local Vault oppure un workflow verifier-only. Questa pagina collega queste scelte a passi concreti.

Scegli un percorso

Ricetta: registra un evento di produzione

Usa questo quando la tua applicazione conosce già la decisione o azione che deve diventare evidenza. Invia solo da codice server-side. Conserva la system key nel tuo secret manager, preserva le idempotency keys tra i retry e registra source references stabili che il team può tracciare.

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

Ricetta: supporta Article 13 con una riga e genera l'Article 12 report

Quando diciamo "Voldoe aan Artikel 13 met 1 regel code", intendiamo: aggiungi una riga di integrazione Attesto che trasforma un workflow AI in evidenza receipt-backed e verifier-ready per trasparenza e instructions-for-use. Il comando CLI deterministico resta attesto report article12, perché il report collega la traccia tecnica di logging a evidenza di logging in stile Article 12. Il supporto Article 13 dipende da come il cliente usa quell'evidenza in documentazione, informazioni agli utenti, oversight e interpretazione legale. Attesto fornisce supporto probatorio; non certifica da solo la conformità legale.

Usa il decorator quando controlli il confine della funzione, attestedFetch quando controlli il trasporto HTTP in TypeScript, e l'Inference Gateway quando vuoi un proxy neutrale rispetto a linguaggio e framework per chiamate 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_..."))

Il percorso di capture può usare una system API key. Il percorso di report legge tenant stream events, quindi genera il report finale da un contesto tenant/operator oppure passa un tenant token alla 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

Ricetta: crea uno stream Proofstream

Usa Proofstream quando l'ordine conta. Uno stream è normalmente limitato a tenant, sistema, use case e policy. Ogni evento riceve un sequence number e una receipt firmata. Windows, checkpoints, witnesses, anchors e bundles successivi si costruiscono su quella sequenza 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)

Ricetta: verifica l'evidenza prima di fidarti

La verifica deve far parte del workflow ricevente. Se il tuo sistema riceve una Attesto receipt o un bundle, verificalo prima di accettarlo in un audit file, data room, assurance report o pacchetto regolatore.

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

Anche un report fallito è evidenza utile. Indica se l'oggetto era malformed, incompleto, cambiato, stale, senza witness quorum, con signature errata, legato all'anchor sbagliato o portatore di fork evidence.

Ricetta: ricevi webhook Attesto

I webhook servono per notifiche. Non sostituiscono la verifica. Verifica la signature sul raw request body, deduplica il delivery ID, rispondi rapidamente e recupera o verifica l'oggetto di evidenza referenziato nel tuo 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"));
}

Ricetta: usa i connettori in sicurezza

I connettori traducono cambiamenti nei sistemi sorgente in evidenza Attesto. Usa signed webhook connectors per sistemi personalizzati, connettori GitHub/GitLab per repository change references e S3/R2 commitments per object evidence. Ogni connettore deve avere autenticazione reale, comportamento di replay, diagnostics e revocation.

Ricetta: distribuisci Local Vault al customer edge

Local Vault è per ambienti enterprise dove connector secrets, source attestations e outage spooling devono restare lato cliente. Effettua relay outbound verso Attesto e può opzionalmente agire da customer witness in una 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

• Conserva i connector secrets cifrati localmente.
• Firma le source attestations prima del relay.
• Spoola quando la rete outbound non è disponibile.
• Riproduci con idempotency stabile quando torna la connettività.
• Esponi lo stato witness al tenant e al verifier bundle.

Ricetta: instrada chiamate AI tramite Attesto Inference Gateway

Usa il gateway quando i team chiamano già API provider OpenAI-compatible e vogliono evidence senza riscrivere ogni applicazione. Il gateway inoltra requests al provider configurato e registra commitments, receipt references e metadata sicura. Raw prompts, completions, API keys e provider secrets restano nel processo gateway e non vengono scritti in 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

Usa la modalità commitments per production evidence. Usa none solo quando un deployment disabilita intenzionalmente la capture evidence per uno specifico ambiente. Il gateway è fail-open di default con warning visibili agli operatori e un dead-letter spool fsync; aggiungi --strict quando la policy richiede che receipt creation riesca prima che il lavoro upstream continui. Monitora /healthz e /metrics sull'admin listener, ed esegui attesto-gateway replay-spool dopo outages.

Il gateway attesta chiamate OpenAI-compatible /v1/chat/completions, /v1/completions, /v1/embeddings e /v1/responses come model-decision evidence. I percorsi upstream sconosciuti vengono proxati e registrati come eventi generici di commitment HTTP-call, invece di essere ignorati silenziosamente.

Ricetta: esponi Attesto agli agent tools tramite MCP

Il server Attesto MCP dà ai sistemi agentic un set ristretto e deterministico di tool: log action, get receipt, verify receipt offline, inspect stream head e check completeness. Non è una surface admin generale e rifiuta valori che sembrano secret prima che possano diventare evidence payload.

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

Mantieni le credenziali MCP nel secret store dell'agent runtime. Non passare dashboard cookies, admin credentials, private keys, provider API keys o raw customer secrets tramite argomenti dei tool MCP.

Ricetta: aggiungi Attesto evidence ai workflow n8n

Usa il nodo Attesto n8n quando un workflow step deve produrre un evidence receipt. L'action node registra typed compliance events, recupera receipts e verifica receipts offline. Il trigger node valida signed Attesto webhooks con timestamp tolerance prima che il workflow continui.

npm install n8n-nodes-attesto

• Conserva le credenziali Attesto in n8n credentials, non in workflow JSON.
• Usa workflow execution IDs stabili come source references.
• Verifica incoming webhook signatures prima di diramare in base al contenuto.
• Registra failure events per automation steps rifiutati o incompleti.

Checklist di rollout produzione