SDKs

SDKs de Python, TypeScript, CLI y Go

Attesto ofrece cuatro developer surfaces first-class: Python, TypeScript, Go y Attesto CLI. Comparten el mismo protocolo Proofstream, golden vectors, verifier matrix, production origin y reglas de secret-handling.

Soporte Article 13 y evidencia Article 12 con una línea de integración

Para sistemas AI high-risk, Article 12 trata de capacidad técnica de logging y trazabilidad, mientras Article 13 trata transparencia e información útil para deployers y usuarios. En términos de Attesto, la línea exacta de integración es export OPENAI_BASE_URL=http://localhost:8765/v1: dirige las llamadas OpenAI-compatible al Attesto Gateway para que pueda comenzar la captura automática de evidencia. El Article 12 report determinista explica qué se registró y qué es verificable de forma independiente, y la misma traza receipt-backed puede apoyar documentación Article 13. Es soporte de evidencia, no una declaración de conformidad legal.

La integración gateway concreta de una línea que hace esto posible es:

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

En producción, sustituya localhost por el host gateway desplegado y mantenga tanto la provider key como la Attesto system key en almacenamiento de secretos server-side.

Use este patrón cuando controla un límite de función Python. El decorador registra commitments sobre argumentos, valor de retorno, timing, source reference y failures; el report resume coverage sin 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_..."))

La ruta de captura usa una system API key; la ruta de report lee tenant stream events y por eso requiere un tenant/operator bearer token.

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

Qué gestiona el SDK

Los SDKs son clientes server-side deliberadamente delgados. No ocultan el evidence model, pero eliminan trabajo repetitivo de transporte para que su aplicación se centre en elegir la event shape correcta y en verificar la evidence devuelta.

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

Use attestedFetch cuando un SDK o framework OpenAI-compatible acepta una custom fetch implementation. Registra solo commitments, nunca raw prompts ni completions. strict: true falla cerrado cuando no puede enviarse evidencia; el modo fail-open debe ser monitoreado.

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

Cliente Proofstream v2

Use AttestoV2Client cuando necesite stream-level receipts, checkpoint consistency, witness policy visibility, verifier bundles y 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

Use Go para infrastructure automation, security tooling, cloud workers y verifier services. El SDK Go actualmente usa solo la Go standard library y se resuelve desde el module path del repositorio 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 es la operator y verifier surface para workflows scriptados. Soporta JSON output, local config, stream/event actions, receipt verification, bundle verification, fork evidence, quorum evidence, connectors, Local Vault y release-readiness evidence checks. Nunca imprime API keys almacenadas, tenant tokens ni 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 de operador

Los endpoints tenant/operator requieren bearer-token mode. Use esto solo en trusted operator automation y nunca en clientes públicos.

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 de verify offline y online

Los métodos SDK de verification son útiles en servicios que reciben Attesto receipts o bundles y necesitan fallar cerrado antes de aceptarlos.

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 para pruebas locales

attesto.testing.MockAttesto es un Python test harness para CI local y pruebas de integración. Usa el mismo canonical hashing y receipt shapes que el SDK, pero firma con una per-instance throwaway mock key y marca los objetos como mock evidence. Úselo para probar el application flow sin red ni cuenta de Attesto; no use mock receipts en production evidence ni customer bundles.

MockAttesto es intencionalmente fail-closed frente a trust roots reales: la verificación con una production witness key debe rechazar mock evidence. Así las pruebas siguen siendo rápidas sin crear un camino para que synthetic evidence pase como production proof.

Packages complementarios y superficies edge

Los core SDKs permanecen pequeños. Packages separados cubren edge relay, MCP tooling, workflow nodes y el futuro independent witness node. Estos packages nunca deben convertirse en dependencias transitivas ocultas de los core SDKs.

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

Especificado como privacy-preserving observation node package. El comportamiento customer-operated witness actual está disponible mediante Local Vault witness mode; standalone attesto-witness, @attesto/witness y go.attesto.eu/witness solo deben instalarse cuando release evidence marque ese package en verde.

Reglas de seguridad

• Use SDKs solo desde código server-side.
• Guarde system keys en su secret manager e inyéctelas at runtime.
• No coloque system keys en frontend bundles, mobile apps, query strings ni logs.
• Use la production origin por defecto salvo que su tenant tenga una private deployment origin.
• Mantenga idempotency habilitada para cada write path.