SDKs

Python-, TypeScript-, CLI- en Go-SDKs

Attesto biedt vier first-class developer surfaces: Python, TypeScript, Go en de Attesto CLI. Ze delen hetzelfde Proofstream protocol, dezelfde golden vectors, verifier matrix, production origin en regels voor secret-handling.

Article 13 support en Article 12 evidence met één integratieregel

Voor high-risk AI-systemen gaat Article 12 over technische logging-capability en traceerbaarheid, terwijl Article 13 transparantie en bruikbare informatie richting deployers en gebruikers raakt. In Attesto-termen is de exacte integratieregel export OPENAI_BASE_URL=http://localhost:8765/v1: daarmee wijs je OpenAI-compatible calls naar de Attesto Gateway en kan automatische evidence capture starten. Het deterministische Article 12 report legt uit wat is vastgelegd en onafhankelijk verifieerbaar is, en dezelfde receipt-backed trail kan Article 13-documentatie ondersteunen. Dit is bewijs-ondersteuning, geen juridische conformiteitsverklaring.

De concrete one-line gateway-integratie die dit waar maakt is:

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

Vervang localhost in productie door de gedeployde gateway host en bewaar zowel de provider key als de Attesto system key in server-side secret storage.

Gebruik dit patroon wanneer je een Python function boundary beheert. De decorator legt commitments over argumenten, return value, timing, source reference en failures vast; het report vat coverage samen zonder 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_..."))

De capture path gebruikt een system API key; de report path leest tenant stream events en vereist daarom een tenant/operator bearer token.

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

Wat de SDK afhandelt

De SDKs zijn bewust dunne server-side clients. Ze verbergen het evidence model niet, maar verwijderen repetitief transportwerk zodat je applicatie zich kan richten op de juiste event shape en het verifiëren van teruggegeven evidence.

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

Gebruik attestedFetch wanneer een OpenAI-compatible SDK of framework een custom fetch implementation accepteert. Het registreert alleen commitments, nooit raw prompts of completions. strict: true faalt gesloten wanneer evidence niet kan worden ingestuurd; fail-open mode moet gemonitord worden.

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,
});

Proofstream v2 client

Gebruik AttestoV2Client wanneer je stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles en offline verification helpers nodig hebt.

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

Gebruik Go voor infrastructure automation, security tooling, cloud workers en verifier services. De Go SDK gebruikt momenteel alleen de Go standard library en wordt resolved vanaf het publieke go.attesto.eu/sdk module path.

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

De Attesto CLI is de operator- en verifier surface voor scripted workflows. De CLI ondersteunt JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault en release-readiness evidence checks. De CLI print nooit opgeslagen API keys, tenant tokens of 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

Tenant/operator endpoints vereisen bearer-token mode. Gebruik dit alleen in trusted operator automation en nooit in publieke 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 en online verify helpers

SDK verification methods zijn nuttig in services die Attesto receipts of bundles ontvangen en fail-closed moeten werken voordat ze deze accepteren.

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 voor lokale tests

attesto.testing.MockAttesto is een Python test harness voor lokale CI en integratietests. Het gebruikt dezelfde canonical hashing en receipt shapes als de SDK, maar tekent met een per-instance throwaway mock key en markeert objecten als mock evidence. Gebruik het om je applicatieflow zonder netwerktoegang of Attesto-account te testen; gebruik mock receipts nooit in production evidence of customer bundles.

MockAttesto is bewust fail-closed tegen echte trust roots: verificatie met een production witness key moet mock evidence verwerpen. Zo blijven tests snel zonder dat synthetic evidence als production proof kan doorgaan.

Companion packages en edge-surfaces

De core SDKs blijven klein. Aparte packages dekken edge relay, MCP tooling, workflow nodes en de toekomstige independent witness node. Deze packages mogen nooit verborgen transitieve dependencies van de core SDKs worden.

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

Gespecificeerd als privacy-preserving observation node package. Huidig customer-operated witness gedrag is beschikbaar via Local Vault witness mode; standalone attesto-witness, @attesto/witness en go.attesto.eu/witness mogen alleen worden geïnstalleerd nadat release evidence dat package groen markeert.

Security rules

• Gebruik SDKs alleen vanuit server-side code.
• Bewaar system keys in je secret manager en injecteer ze at runtime.
• Plaats system keys niet in frontend bundles, mobile apps, query strings of logs.
• Gebruik de standaard production origin tenzij je tenant een private deployment origin heeft.
• Houd idempotency ingeschakeld voor ieder write path.