SDKs

SDK Python, TypeScript, CLI i Go

Attesto udostępnia cztery first-class developer surfaces: Python, TypeScript, Go oraz Attesto CLI. Współdzielą ten sam Proofstream protocol, golden vectors, verifier matrix, production origin oraz zasady secret-handling.

Wsparcie Article 13 i evidence Article 12 jedną linią integracji

Dla systemów AI high-risk Article 12 dotyczy technicznej zdolności loggingu i traceability, a Article 13 dotyczy transparentności oraz użytecznych informacji dla deployers i użytkowników. W terminach Attesto dokładna linia integracji to export OPENAI_BASE_URL=http://localhost:8765/v1: kieruje wywołania OpenAI-compatible do Attesto Gateway, aby automatyczne zbieranie evidence mogło się rozpocząć. Deterministyczny Article 12 report wyjaśnia, co zostało zapisane i co jest niezależnie weryfikowalne, a ten sam receipt-backed trail może wspierać dokumentację Article 13. To wsparcie dowodowe, nie deklaracja zgodności prawnej.

Konkretna jednowierszowa integracja gateway, która to umożliwia, to:

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

W produkcji zastąp localhost wdrożonym hostem gateway i trzymaj zarówno provider key, jak i Attesto system key w server-side secret storage.

Użyj tego wzorca, gdy kontrolujesz granicę funkcji Python. Dekorator zapisuje commitments dla argumentów, wartości zwrotnej, timingu, source reference i failures; report podsumowuje coverage bez 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_..."))

Capture path używa system API key; report path czyta tenant stream events i dlatego wymaga tenant/operator bearer token.

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

Co obsługuje SDK

SDKs są celowo cienkimi server-side clients. Nie ukrywają evidence model, ale usuwają powtarzalną pracę transportową, aby aplikacja mogła skupić się na wyborze właściwego event shape i weryfikacji zwróconej 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

Użyj attestedFetch, gdy SDK lub framework OpenAI-compatible akceptuje custom fetch implementation. Rejestruje tylko commitments, nigdy raw prompts ani completions. strict: true failuje zamknięcie, gdy evidence nie może zostać wysłane; tryb fail-open musi być monitorowany.

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

Użyj AttestoV2Client, gdy potrzebujesz stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles i 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

Użyj Go do infrastructure automation, security tooling, cloud workers i verifier services. Go SDK używa obecnie wyłącznie Go standard library i jest rozwiązywany z module path repozytorium Attesto.

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 to operator i verifier surface dla scripted workflows. Obsługuje JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault i release-readiness evidence checks. Nigdy nie wypisuje zapisanych API keys, tenant tokens ani 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 wymagają bearer-token mode. Używaj tego tylko w trusted operator automation i nigdy w 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 i online verify helpers

SDK verification methods są użyteczne w usługach, które otrzymują Attesto receipts lub bundles i muszą fail-closed przed ich akceptacją.

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 do testów lokalnych

attesto.testing.MockAttesto to Python test harness dla lokalnego CI i testów integracyjnych. Używa tego samego canonical hashing i receipt shapes co SDK, ale podpisuje per-instance throwaway mock key i oznacza obiekty jako mock evidence. Używaj go do testowania application flow bez sieci i bez konta Attesto; nie używaj mock receipts w production evidence ani customer bundles.

MockAttesto celowo fail-closed wobec prawdziwych trust roots: verification z production witness key musi odrzucić mock evidence. Dzięki temu testy są szybkie, ale synthetic evidence nie może przejść jako production proof.

Pakiety companion i powierzchnie edge

Core SDKs pozostają małe. Osobne pakiety pokrywają edge relay, MCP tooling, workflow nodes i przyszły independent witness node. Te pakiety nigdy nie mogą stać się ukrytymi zależnościami transitive core SDKs.

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

Określony jako privacy-preserving observation node package. Obecne customer-operated witness behavior jest dostępne przez Local Vault witness mode; standalone attesto-witness, @attesto/witness i go.attesto.eu/witness powinny być instalowane tylko po tym, jak release evidence oznaczy ten package jako zielony.

Security rules

• Używaj SDKs tylko z kodu server-side.
• Przechowuj system keys w swoim secret manager i wstrzykuj je at runtime.
• Nie umieszczaj system keys w frontend bundles, mobile apps, query strings ani logs.
• Używaj domyślnego production origin, chyba że twój tenant ma private deployment origin.
• Utrzymuj idempotency włączone dla każdego write path.