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.

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/rotzmediagroup/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/rotzmediagroup/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("; "));
}

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.