SDKs

SDK Python, TypeScript, CLI e Go

Attesto espone quattro developer surfaces first-class: Python, TypeScript, Go e Attesto CLI. Condividono lo stesso Proofstream protocol, golden vectors, verifier matrix, production origin e regole di secret-handling.

Supporto Article 13 ed evidenza Article 12 con una riga di integrazione

Per sistemi AI high-risk, l'Article 12 riguarda capacità tecnica di logging e tracciabilità, mentre l'Article 13 riguarda trasparenza e informazioni utili per deployer e utenti. In termini Attesto, la riga esatta di integrazione è export OPENAI_BASE_URL=http://localhost:8765/v1: indirizza le chiamate OpenAI-compatible all'Attesto Gateway così la capture automatica di evidence può iniziare. Il report Article 12 deterministico spiega cosa è stato registrato e verificabile indipendentemente, e la stessa traccia receipt-backed può supportare la documentazione Article 13. È supporto probatorio, non una dichiarazione di conformità legale.

La concreta integrazione gateway in una riga che rende questo possibile è:

export OPENAI_BASE_URL=http://localhost:8765/v1

In produzione, sostituisci localhost con l'host gateway distribuito e conserva sia la provider key sia la Attesto system key in secret storage server-side.

Usa questo pattern quando controlli il confine di una funzione Python. Il decorator registra commitments su argomenti, valore di ritorno, timing, source reference e failures; il report riassume la coverage senza LLM.

from attesto import AttestoV2Client, attest, article12
import os

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as capture:
    @attest(capture, stream_id="str_...")
    def score_case(case: dict) -> dict:
        return {"decision": "manual_review", "policy_id": "policy-2026-01"}

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

Il percorso di capture usa una system API key; il percorso di report legge tenant stream events e quindi richiede un tenant/operator bearer token.

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

Cosa gestisce l'SDK

Gli SDKs sono volutamente client server-side sottili. Non nascondono l'evidence model, ma rimuovono il lavoro ripetitivo di trasporto così la tua applicazione può concentrarsi sulla scelta dell'event shape corretta e sulla verifica dell'evidence restituita.

Capability matrix

Python

pip install attesto

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="inference",
    status="verified",
    ts=datetime.now(UTC),
    payload={
        "model": "risk-service-v4",
        "score": 0.91,
        "policy_id": "policy-2026-01",
    },
)
print(ack.id)

Python async

import os
from datetime import UTC, datetime
from attesto import AsyncAttestoClient

async with AsyncAttestoClient(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    ack = await attesto.log_event(
        type="ai.decision",
        status="verified",
        ts=datetime.now(UTC),
        payload={"decision": "manual_review", "score": 91},
    )
    print(ack.id)

TypeScript

npm install @attesto/sdk

import { AttestoClient } from "@attesto/sdk";

const attesto = new AttestoClient({
  apiKey: process.env.ATTESTO_API_KEY!,
});

const ack = await attesto.logEvent({
  type: "inference",
  status: "verified",
  ts: new Date(),
  payload: {
    model: "risk-service-v4",
    score: 0.91,
    policy_id: "policy-2026-01",
  },
});
console.log(ack.id);

TypeScript attestedFetch

Usa attestedFetch quando un SDK o framework OpenAI-compatible accetta una custom fetch implementation. Registra solo commitments, mai raw prompts o completions. strict: true fallisce chiuso quando l’evidence non può essere inviata; la modalità fail-open deve essere monitorata.

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

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

Client Proofstream v2

Usa AttestoV2Client quando ti servono stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles e offline verification helpers.

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",
    )
    receipt = attesto.log_event(
        stream_id=stream.stream_id,
        source_ref="source-event-001",
        event_type="decision",
        occurred_at=datetime.now(UTC),
        payload={"decision": "review", "score": 91},
    )
    stored = attesto.get_receipt(receipt.stream_event_id)
    report = attesto.verify_receipt(
        receipt=stored.receipt,
        public_key_hex=os.environ["ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"],
        stream_event_id=receipt.stream_event_id,
    )
    assert report.ok

TypeScript Proofstream:

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

const attesto = new AttestoV2Client({
  apiKey: process.env.ATTESTO_API_KEY!,
});

const stream = await attesto.createStream({
  useCase: "ai-decision-history",
  policyId: "policy-2026-01",
});

const receipt = await attesto.logEvent(stream.streamId, {
  sourceRef: "case-2026-0001:decision-1",
  eventType: "ai.decision",
  occurredAt: new Date(),
  payload: { decision: "manual_review", score: 91 },
});

const report = await attesto.verifyReceipt({
  receipt: receipt.receipt,
  streamEventId: receipt.streamEventId,
  publicKeyHex: process.env.ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX!,
});
if (!report.ok) throw new Error(report.problems.join("; "));

Go

Usa Go per infrastructure automation, security tooling, cloud workers e verifier services. Il Go SDK attualmente usa solo la Go standard library ed è risolto dal module path pubblico go.attesto.eu/sdk.

go get go.attesto.eu/sdk

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  attesto "go.attesto.eu/sdk"
)

func main() {
  client, err := attesto.NewClient(os.Getenv("ATTESTO_API_KEY"))
  if err != nil {
    log.Fatal(err)
  }

  stream, err := client.CreateStream(context.Background(), attesto.StreamCreateInput{
    UseCase: "ai-decision-history",
    PolicyID: "policy-2026-01",
  })
  if err != nil {
    log.Fatal(err)
  }

  receipt, err := client.LogEvent(context.Background(), stream.StreamID, attesto.EventInput{
    SourceRef: "case-2026-0001:decision-1",
    EventType: "ai.decision",
    Payload: attesto.M{"decision": "manual_review", "score": 91},
  })
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(receipt.StreamEventID, receipt.EventHash)
}

CLI

Attesto CLI è la operator e verifier surface per scripted workflows. Supporta JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault e release-readiness evidence checks. Non stampa mai API keys salvate, tenant tokens o connector secrets.

Installa la CLI firmata da get.attesto.eu. Gli installer verificano la checksum SHA256 della release prima di installare qualsiasi cosa, e la firma del manifest può essere verificata con cosign. La formula Homebrew e i pacchetti Linux nativi reimpacchettano gli stessi binari del canale: i loro hash provengono dal manifest SHA256SUMS firmato con cosign, mai da una build separata:

# Linux / macOS
curl -fsSL https://get.attesto.eu | sh

# Windows (PowerShell; user-level install, no admin rights)
irm https://get.attesto.eu/install.ps1 | iex

# macOS / Linux (Homebrew)
brew tap attesto/attesto https://git.attesto.eu/attesto/homebrew-attesto.git
brew trust attesto/attesto
brew install attesto

# Native Linux packages: verify the signed manifest first
curl -fsSLO https://get.attesto.eu/0.5.0/SHA256SUMS
curl -fsSLO https://get.attesto.eu/0.5.0/SHA256SUMS.sig
cosign verify-blob --key https://get.attesto.eu/cosign.pub --insecure-ignore-tlog --signature SHA256SUMS.sig SHA256SUMS

# Debian / Ubuntu (run the install as root; arm64 debs and aarch64 rpms
# are on the same channel)
curl -fsSLO https://get.attesto.eu/0.5.0/attesto_0.5.0-1_amd64.deb
sha256sum -c --ignore-missing SHA256SUMS
apt install ./attesto_0.5.0-1_amd64.deb

# Fedora / RHEL (run the install as root)
curl -fsSLO https://get.attesto.eu/0.5.0/attesto-0.5.0-1.x86_64.rpm
sha256sum -c --ignore-missing SHA256SUMS
dnf install ./attesto-0.5.0-1.x86_64.rpm

I pacchetti arm64/aarch64 sono verificati a livello di metadati contro il manifest firmato, ma non sono stati eseguiti su hardware arm.

CLI command reference

cd sdk/go
go run ./cmd/attesto --json version

go run ./cmd/attesto --json \
  --api-key-env ATTESTO_API_KEY \
  streams create \
  --use-case ai-decision-history \
  --policy-id policy-2026-01

Offline receipt verification:

go run ./cmd/attesto --json receipts verify \
  --file receipt.json \
  --public-key-hex "$ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"

Production readiness evidence check:

go run ./cmd/attesto --json readiness lifecycle
go run ./cmd/attesto --json readiness fork-defense
go run ./cmd/attesto --json readiness production

Marketplace publisher automation:

go run ./cmd/attesto --json marketplace init \
  --output attesto.connector.json \
  --slug signed-webhook-evidence \
  --name "Generic Signed Webhook Evidence" \
  --version 1.0.0 \
  --category compliance \
  --summary "Produces Attesto evidence for signed webhook events." \
  --description "Produces verifiable Proofstream events for signed webhook payloads." \
  --publisher-slug attesto \
  --publisher-name Attesto \
  --repository-url https://git.rotz.ai/attesto/attesto-v1/src/branch/attesto-2.0/connectors/webhook \
  --docs-url https://docs.attesto.eu/manuals/connectors.html#signed \
  --provider-url https://docs.attesto.eu/manuals/connectors.html#signed \
  --auth-mode signed-webhook \
  --auth-scopes webhook:read \
  --sync-modes webhook \
  --event-types webhook.event.received \
  --canary-ref release/attesto-2.0-connector-assurance-readiness/result.json \
  --capabilities proofstream,offline-verification

go run ./cmd/attesto --json marketplace validate \
  --manifest-file attesto.connector.json

go run ./cmd/attesto --json \
  --token-env ATTESTO_TENANT_TOKEN \
  marketplace submit \
  --manifest-file attesto.connector.json \
  --source-ref https://git.rotz.ai/attesto/attesto-v1/src/branch/attesto-2.0/connectors/webhook \
  --visibility public \
  --pricing-model free

Operator endpoints

Gli endpoints tenant/operator richiedono bearer-token mode. Usalo solo in trusted operator automation e mai in public clients.

from attesto import AttestoV2Client

operator = AttestoV2Client.with_bearer_token(
    os.environ["ATTESTO_TENANT_TOKEN"],
)
streams = operator.list_tenant_streams()
forks = operator.list_fork_evidence(streams[0]["streamId"])

const operator = new AttestoV2Client({
  apiKey: process.env.ATTESTO_TENANT_TOKEN!,
  authMode: "bearer",
});

const streams = await operator.listTenantStreams();
const forks = await operator.listForkEvidence(String(streams[0].streamId));

operator, err := attesto.NewBearerClient(os.Getenv("ATTESTO_TENANT_TOKEN"))
if err != nil { log.Fatal(err) }
streams, err := operator.ListTenantStreams(context.Background(), "", 100, 0)
if err != nil { log.Fatal(err) }

Offline e online verify helpers

I metodi SDK verification sono utili nei servizi che ricevono Attesto receipts o bundles e devono fail-closed prima di accettarli.

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

with AttestoV2Client(api_key=os.environ["ATTESTO_API_KEY"]) as attesto:
    report = attesto.verify_object(
        kind="bundle",
        proof_object=bundle_object,
    )
    if not report.ok:
        raise RuntimeError(report.problems)

const report = await attesto.verifyObject({
  kind: "bundle",
  object: bundleObject,
});

if (!report.ok) {
  throw new Error(report.problems.join("; "));
}

Verifica della provenienza (Attesto 3)

Gli SDK 0.5.0 aggiungono un client di verifica per la provenance lane di Attesto 3: provenance streams commitment-only alimentati da un Local Vault controllato dal cliente. Il Rust edge core fissato del vault costruisce capsules, commitments e firme; l'SDK li ricava di nuovo e li controlla, e deliberatamente non può costruire una capsule né un randomizer. Ogni funzione di questa sezione gira offline, senza chiamate ad Attesto, e ogni report porta una lista not_claimed che una schermata di verifica deve mostrare accanto al risultato. Protocolli: ATTESTO-PROVENANCE-001, ATTESTO-DISCLOSURE-001, ATTESTO-ZK-RANGE-001 e la bundle provenance binding di ATTESTO-PROOFSTREAM-001. La conformità è fissata dal corpus condiviso di golden vectors in tutti e tre i linguaggi.

Verificare una disclosure presentation offline

Il Local Vault di un titolare emette una selective-disclosure presentation: le leaves rivelate con i loro randomizers, two-hop inclusion proofs fino alla capsule root e una firma Ed25519 dell'installazione emittente. Il verificatore apre ogni commitment rivelato e ripete ogni proof fino alla capsule_root presentata. I problemi vengono raccolti, non sollevati, così che il chiamante veda tutto ciò che non va. Passa il nonce che hai emesso per la modalità challenge; senza di esso la presentation è limitata solo dal suo expires_at e il report dice bounded_lifetime invece di suggerire una freschezza che non ha verificato. Non-claim: la disclosure dimostra che le leaves rivelate sono nella capsule; non è un'affermazione che la capsule non contenga altro.

from attesto.provenance import verify_disclosure

report = verify_disclosure(
    presentation,
    expected_nonce=challenge,
    subject_commitment=asset_commitment,
)
report.ok               # every leaf opened and every proof folded to capsule_root
report.verified_leaves  # ({"subtree": "claims", "leaf_role": "c2pa_manifest_valid", "value": ...},)
report.freshness        # "challenge" | "bounded_lifetime"
report.subject_checked  # True only when subject_commitment matched
report.problems         # () or every problem found
report.not_claimed      # ({"id": "undisclosed_facts_absent", "statement": ...},)

import { verifyDisclosure } from "@attesto/sdk";

const report = await verifyDisclosure(presentation, {
  expectedNonce: challenge,
  subjectCommitment: assetCommitment,
});
report.ok; report.verified_leaves; report.freshness;
report.subject_checked; report.problems; report.not_claimed;

report := attesto.VerifyDisclosure(presentation,
	attesto.WithExpectedNonce(challenge),
	attesto.WithSubjectCommitment(assetCommitment),
)
report.Ok; report.VerifiedLeaves; report.Freshness
report.SubjectChecked; report.Problems; report.NotClaimed

Verificare offline una bundle provenance inclusion e una key revocation

Un verifier bundle su un provenance stream porta provenance_root, provenance_event_count e vault_key_lifecycle dentro il suo payload hashato. Un inclusion object, restituito da GET /v2/streams/{streamId}/provenance-events/{sourceRef}/bundle-inclusion?from_checkpoint_id=...&to_checkpoint_id=... o trasportato come provenance_inclusions accanto al bundle, dimostra una capsule root sotto quella root. Il verificatore ricalcola il bundle hash, ri-hasha la leaf dai suoi campi, ripete il proof, prende il receipt time del seq_no della leaf dai receipts del bundle stesso e applica la regola di revoca congelata all'installazione che la leaf nomina. inclusion e key_status restano separati: una capsule root può essere dimostrabilmente sotto il bundle mentre la sua chiave è stata revocata prima della ricezione, e not_evaluated non è mai un esito positivo. La revoca viene valutata rispetto al platform receipt time, mai rispetto all'occurred_at dichiarato dal vault, con un confine inclusivo; una dichiarazione antecedente alla revoca riceve il flag suspect_backdated. Non-claims: la root dimostra che la capsule root esisteva sotto il bundle e nulla sul contenuto della capsule; il key lifecycle è quello del momento in cui il bundle è stato costruito, quindi una revoca successiva non è nel bundle.

from attesto.provenance import evaluate_key_revocation, verify_bundle_provenance

report = verify_bundle_provenance(bundle, inclusion)
report.ok          # bundle hash holds, inclusion VALID, key live at receipt
report.inclusion   # "VALID" | "INVALID"
report.key_status  # "valid" | "revoked_at_receipt" | "unknown_installation" | "not_evaluated"
report.flags       # e.g. ("revoked_at_receipt", "suspect_backdated")
report.not_claimed # three statements

verdict = evaluate_key_revocation(
    revoked_at=key_status["revokedAt"],          # None when never revoked
    receipt_time=receipt["payload"]["issued_at"],
    claimed_occurred_at=envelope["occurred_at"],
    reason=key_status["revocationReason"],
)
verdict.accepted   # status == "valid"

import { evaluateKeyRevocation, verifyBundleProvenance } from "@attesto/sdk";

const report = await verifyBundleProvenance(bundle, inclusion);
report.ok; report.inclusion; report.key_status; report.flags; report.not_claimed;

const verdict = evaluateKeyRevocation(
  keyStatus.revokedAt,
  receipt.payload.issued_at,
  envelope.occurred_at,
  keyStatus.revocationReason,
);
verdict.accepted;

report := attesto.VerifyBundleProvenance(bundle, inclusion)
report.Ok; report.Inclusion; report.KeyStatus; report.Flags; report.NotClaimed

verdict := attesto.EvaluateKeyRevocation(revokedAt, receiptTime, claimedOccurredAt, reason)
verdict.Accepted()

Derivare l'effective assurance (L3 è derivato, mai firmato)

Un vault firma nel suo envelope L0 (chiave software), L1 (chiave in un token PKCS#11 non estraibile) o L2 (L1 più un quote TPM 2.0 sulla misurazione del vault), e la piattaforma rifiuta un envelope L1/L2 che non può sostanziare con un'attestation registrata. L3 non ha rappresentazione sul filo: il verificatore lo deriva da L2 più un witness quorum raggiunto sul checkpoint che lo contiene, e un envelope che dichiara L3 viene rifiutato. Lo stato dell'anchor è riportato accanto e non promuove mai un livello. Il report mantiene vault assurance, witness quorum, stato dell'anchor e livello derivato come quattro fatti separati. Come si ottengono i livelli è descritto nella guida Local Vault.

from attesto.provenance import effective_assurance

report = effective_assurance("L2", witness_quorum_met=True, anchor_confirmed=True)
report.effective  # "L3"
report.derived    # True: derived here, signed by nobody
report.reasons    # ("anchor confirmed; anchoring does not promote assurance", "L3 derived from L2 plus a met witness quorum")
effective_assurance("L2").effective  # "L2": quorum not evaluated withholds L3
effective_assurance("L3")            # raises AttestoProvenanceError

import { effectiveAssurance } from "@attesto/sdk";

const report = effectiveAssurance("L2", { witnessQuorumMet: true, anchorConfirmed: true });
report.effective; // "L3"
report.derived;   // true
report.reasons;

met := true
report, err := attesto.EffectiveAssurance("L2", &met, &met)
report.Effective // "L3"
report.Derived   // true
report.Reasons

Verificare l'apertura esatta di un private numeric

Un private numeric claim impegna il suo valore codificato come Pedersen commitment su ristretto255. Quando un titolare rivela valore e blinding, il verificatore ricalcola il commitment e lo confronta byte per byte. L'aritmetica di curva è opzionale perché il resto della verifica è lavoro SHA-256 e Merkle: Python richiede attesto[zk], TypeScript la peer dependency @noble/curves e Go il modulo separato go.attesto.eu/sdk/zk. Un client che ne è privo riporta not_checked. Il descriptor deve aver già aperto la sua claim leaf sotto la capsule root, altrimenti una coppia coerente può essere fabbricata per intero. Un valore esattamente zero è un'apertura valida. Questo non verifica un range proof.

from attesto.provenance import pedersen_available, verify_pedersen_opening

opened = (
    verify_pedersen_opening(descriptor, encoded_value, blinding_scalar)
    if pedersen_available()
    else None  # report "not_checked"
)

import { pedersenAvailable, verifyPedersenOpening } from "@attesto/sdk";

const opened = (await pedersenAvailable())
  ? await verifyPedersenOpening(descriptor, encodedValue, blindingScalar)
  : null; // report "not_checked"

import "go.attesto.eu/sdk/zk"

opened, err := zk.VerifyOpening(descriptor, encodedValue, blindingScalar)

Ispezionare un ZK range result

La selective disclosure v2 dimostra che la misurazione di un rilevatore nominato è caduta in un intervallo senza rivelarla. Nessun SDK verifica il range proof in sé; resta compito del Rust core. L'SDK riporta zk_predicate: not_checked sotto verified_here, conserva ciò che l'emittente ha dichiarato sotto reported_by_issuer e rifiuta un risultato che omette uno dei tre non-claims obbligatori o porta un campo a forma di verdetto come authentic, score o probability. Un limite dimostrato non dice nulla sul fatto che il contenuto sia generato da una macchina. La capsule evidence di un provider AttestoMark Image, Audio o Video è un oggetto ATTESTO-PROVIDER-RESULT-001/0.2 il cui campo presented_matches_record riporta se i byte presentati erano esattamente l'asset marcato; una discrepanza è un'osservazione che produce anche una transcodifica onesta, mai un rifiuto.

from attesto.provenance import inspect_predicate_result, validate_range_statement

report = inspect_predicate_result(result)
report["verified_here"]       # {"zk_predicate": "not_checked", "capsule_inclusion": "not_checked"}
report["reported_by_issuer"]
report["not_claimed"]         # detector_correctness_not_proven, content_truth_not_proven, ai_generation_not_proven
width = validate_range_statement(statement)  # 8 | 16 | 32 | 64

import { inspectPredicateResult, validateRangeStatement } from "@attesto/sdk";

const report = inspectPredicateResult(result);
report.verified_here; report.reported_by_issuer; report.not_claimed;
const width = validateRangeStatement(statement);

report, err := attesto.InspectPredicateResult(result, nil)
report.VerifiedHere; report.ReportedByIssuer; report.NotClaimed
width, err := attesto.ValidateRangeStatement(statement)

Non negli SDK: la costruzione delle capsule, la generazione dei randomizer e la firma degli envelope vivono nell'edge core del Local Vault; i range proofs sono verificati solo dal Rust core; non esiste ancora un client wrapper per POST /v2/provenance/streams; e la CLI attesto in 0.5.0 non verifica disclosures né bundle provenance.

MockAttesto per test locali

attesto.testing.MockAttesto è un Python test harness per CI locale e test di integrazione. Usa gli stessi canonical hashing e receipt shapes dell'SDK, ma firma con una per-instance throwaway mock key e marca gli oggetti come mock evidence. Usalo per testare il tuo application flow senza rete o account Attesto; non usare mock receipts in production evidence o customer bundles.

MockAttesto è intenzionalmente fail-closed contro veri trust roots: verification con una production witness key deve rifiutare mock evidence. Così i test restano veloci senza creare un percorso in cui synthetic evidence possa passare come production proof.

Package companion e superfici edge

I core SDKs restano piccoli. Package separati coprono edge relay, MCP tooling, workflow nodes e il futuro independent witness node. Questi package non devono mai diventare dipendenze transitive nascoste dei core SDKs.

pip install attesto-mcp
pipx install attesto-local-vault
npm install n8n-nodes-attesto

Specificato come privacy-preserving observation node package. Il comportamento customer-operated witness attuale è disponibile tramite Local Vault witness mode; standalone attesto-witness, @attesto/witness e go.attesto.eu/witness devono essere installati solo dopo che la release evidence marca quel package verde.

Security rules

• Usa gli SDKs solo da codice server-side.
• Conserva system keys nel tuo secret manager e iniettale at runtime.
• Non inserire system keys in frontend bundles, mobile apps, query strings o logs.
• Usa la production origin di default salvo che il tuo tenant abbia una private deployment origin.
• Mantieni idempotency abilitata per ogni write path.