SDKs

SDKs Python, TypeScript, CLI et Go

Attesto expose quatre developer surfaces first-class: Python, TypeScript, Go et l'Attesto CLI. Elles partagent le même protocole Proofstream, les mêmes golden vectors, la verifier matrix, la production origin et les règles de gestion des secrets.

Support Article 13 et preuve Article 12 avec une seule ligne d'intégration

Pour les systèmes AI high-risk, l'Article 12 concerne la capacité technique de journalisation et la traçabilité, tandis que l'Article 13 concerne la transparence et les informations utiles pour les deployers et les utilisateurs. En termes Attesto, la ligne d'intégration exacte est export OPENAI_BASE_URL=http://localhost:8765/v1 : elle dirige les appels OpenAI-compatible vers l'Attesto Gateway afin que la capture automatique de preuve puisse démarrer. Le rapport Article 12 déterministe explique ce qui a été enregistré et vérifiable indépendamment, et la même trace receipt-backed peut soutenir la documentation Article 13. C'est un support de preuve, pas une déclaration de conformité juridique.

La ligne d'intégration gateway concrète qui rend cela possible est :

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

En production, remplacez localhost par l'hôte gateway déployé et gardez la provider key ainsi que la system key Attesto dans un secret storage server-side.

Utilisez ce modèle lorsque vous contrôlez une frontière de fonction Python. Le décorateur enregistre des commitments sur les arguments, la valeur de retour, le timing, la source reference et les failures; le rapport résume la couverture sans 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_..."))

Le chemin de capture utilise une system API key; le chemin de rapport lit les tenant stream events et nécessite donc un tenant/operator bearer token.

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

Ce que le SDK prend en charge

Les SDKs sont volontairement des clients server-side fins. Ils ne cachent pas le modèle de preuve, mais retirent le transport répétitif afin que votre application puisse se concentrer sur le bon event shape et sur la vérification de l'evidence retournée.

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

Utilisez attestedFetch lorsqu’un SDK ou framework OpenAI-compatible accepte une custom fetch implementation. Il enregistre uniquement des commitments, jamais les raw prompts ni completions. strict: true échoue fermé lorsque la preuve ne peut pas être envoyée; le mode fail-open doit être surveillé.

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

Utilisez AttestoV2Client lorsque vous avez besoin de stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles et 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

Utilisez Go pour l'infrastructure automation, le security tooling, les cloud workers et les verifier services. Le SDK Go utilise actuellement uniquement la Go standard library et se résout depuis le module public 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

L'Attesto CLI est la surface opérateur et verifier pour les workflows scriptés. Elle prend en charge JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault et release-readiness evidence checks. Elle n'affiche jamais les API keys stockées, tenant tokens ou 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

Endpoints opérateur

Les endpoints tenant/operator exigent le mode bearer-token. Utilisez cela uniquement dans une operator automation fiable et jamais dans des clients publics.

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

Helpers verify offline et online

Les méthodes de vérification SDK sont utiles dans les services qui reçoivent des receipts ou bundles Attesto et doivent fail-closed avant de les accepter.

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 pour les tests locaux

attesto.testing.MockAttesto est un Python test harness pour CI locale et tests d'intégration. Il utilise les mêmes canonical hashing et receipt shapes que le SDK, mais signe avec une per-instance throwaway mock key et marque les objets comme mock evidence. Utilisez-le pour tester votre application flow sans accès réseau ni compte Attesto; n'utilisez jamais de mock receipts dans production evidence ou customer bundles.

MockAttesto est volontairement fail-closed contre les vrais trust roots: la vérification avec une production witness key doit rejeter mock evidence. Les tests restent rapides sans créer de chemin où synthetic evidence passerait pour production proof.

Packages compagnons et surfaces edge

Les core SDKs restent petits. Des packages séparés couvrent edge relay, MCP tooling, workflow nodes et le futur independent witness node. Ces packages ne doivent jamais devenir des dépendances transitives cachées des core SDKs.

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

Spécifié comme privacy-preserving observation node package. Le comportement customer-operated witness actuel est disponible via Local Vault witness mode; les packages standalone attesto-witness, @attesto/witness et go.attesto.eu/witness ne doivent être installés qu’après que la release evidence marque ce package vert.

Règles de sécurité

• Utilisez les SDKs uniquement depuis du code server-side.
• Stockez les system keys dans votre secret manager et injectez-les at runtime.
• Ne placez pas de system keys dans les frontend bundles, mobile apps, query strings ou logs.
• Utilisez la production origin par défaut sauf si votre tenant dispose d'une private deployment origin.
• Gardez l'idempotency activée pour chaque write path.