SDKs

Python-, TypeScript-, CLI- und Go-SDKs

Attesto stellt vier first-class Developer Surfaces bereit: Python, TypeScript, Go und die Attesto CLI. Sie teilen dasselbe Proofstream Protocol, dieselben Golden Vectors, die Verifier Matrix, den Production Origin und die Regeln für Secret Handling.

Article 13 Support und Article 12 Evidence mit einer Integrationszeile

Für high-risk AI-Systeme geht es bei Article 12 um technische Logging-Fähigkeit und Traceability, während Article 13 Transparenz und nutzbare Informationen für Deployer und Nutzer betrifft. In Attesto-Begriffen lautet die exakte Integrationszeile export OPENAI_BASE_URL=http://localhost:8765/v1: damit werden OpenAI-compatible Calls an das Attesto Gateway gerichtet und automatische Evidence Capture kann starten. Der deterministische Article 12 Report erklärt, was aufgezeichnet und unabhängig verifizierbar ist, und derselbe receipt-backed Trail kann Article-13-Dokumentation unterstützen. Das ist Nachweisunterstützung, keine rechtliche Konformitätserklärung.

Die konkrete One-line Gateway-Integration, die das ermöglicht, ist:

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

Ersetzen Sie localhost in Produktion durch den bereitgestellten Gateway Host und speichern Sie sowohl Provider Key als auch Attesto System Key in serverseitiger Secret Storage.

Nutzen Sie dieses Muster, wenn Sie eine Python-Funktionsgrenze kontrollieren. Der Decorator erfasst Commitments über Argumente, Rückgabewert, Timing, Source Reference und Failures; der Report fasst Coverage ohne LLM zusammen.

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

Der Capture Path nutzt einen System API Key; der Report Path liest Tenant Stream Events und benötigt daher einen Tenant/operator Bearer Token.

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

Was die SDK übernimmt

Die SDKs sind bewusst schlanke server-side Clients. Sie verbergen das Evidence Model nicht, sondern entfernen repetitive Transportarbeit, damit Ihre Anwendung sich auf die richtige Event Shape und die Verifikation der zurückgegebenen Evidence konzentrieren kann.

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

Nutzen Sie attestedFetch, wenn ein OpenAI-compatible SDK oder Framework eine custom fetch implementation akzeptiert. Es zeichnet nur Commitments auf, niemals raw prompts oder completions. strict: true schlägt geschlossen fehl, wenn Evidence nicht gesendet werden kann; Fail-open Mode muss überwacht werden.

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

Verwenden Sie AttestoV2Client, wenn Sie stream-level Receipts, Checkpoint Consistency, Witness Policy Visibility, Verifier Bundles und Offline Verification Helpers benötigen.

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

Verwenden Sie Go für Infrastructure Automation, Security Tooling, Cloud Workers und Verifier Services. Die Go SDK nutzt derzeit nur die Go Standard Library und wird über den öffentlichen go.attesto.eu/sdk Module Path aufgelöst.

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

Die Attesto CLI ist die Operator- und Verifier Surface für scripted Workflows. Sie unterstützt JSON Output, Local Config, Stream/Event Actions, Receipt Verification, Bundle Verification, Fork Evidence, Quorum Evidence, Connectors, Local Vault und Release-readiness Evidence Checks. Sie gibt niemals gespeicherte API Keys, Tenant Tokens oder Connector Secrets aus.

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 erfordern Bearer-token Mode. Verwenden Sie das nur in trusted Operator Automation und niemals in öffentlichen 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 und Online Verify Helpers

SDK Verification Methods sind nützlich in Services, die Attesto Receipts oder Bundles empfangen und fail-closed arbeiten müssen, bevor sie diese akzeptieren.

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 für lokale Tests

attesto.testing.MockAttesto ist ein Python Test Harness für lokale CI und Integrationstests. Es verwendet dieselben canonical hashing und receipt shapes wie das SDK, signiert aber mit einem per-instance throwaway mock key und markiert Objekte als mock evidence. Verwenden Sie es, um Ihren Application Flow ohne Netzwerk oder Attesto Account zu testen; verwenden Sie mock receipts niemals in production evidence oder customer bundles.

MockAttesto ist bewusst fail-closed gegenüber echten trust roots: Verification mit einem production witness key muss mock evidence ablehnen. So bleiben Tests schnell, ohne dass synthetic evidence als production proof durchgehen kann.

Companion Packages und Edge-Oberflächen

Die Core SDKs bleiben klein. Separate Packages decken Edge Relay, MCP Tooling, Workflow Nodes und den zukünftigen independent witness node ab. Diese Packages dürfen niemals versteckte transitive Dependencies der Core SDKs werden.

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

Spezifiziert als privacy-preserving observation node package. Aktuelles customer-operated witness Verhalten ist über Local Vault witness mode verfügbar; standalone attesto-witness, @attesto/witness und go.attesto.eu/witness sollten nur installiert werden, nachdem Release Evidence dieses Package grün markiert.

Security Rules

• Verwenden Sie SDKs nur aus server-side Code.
• Speichern Sie System Keys in Ihrem Secret Manager und injizieren Sie sie at runtime.
• Legen Sie System Keys nicht in Frontend Bundles, Mobile Apps, Query Strings oder Logs ab.
• Verwenden Sie den Standard Production Origin, außer Ihr Tenant hat einen Private Deployment Origin.
• Lassen Sie Idempotency für jeden Write Path aktiviert.