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.

Instale la CLI firmada desde get.attesto.eu. Los installers verifican la checksum SHA256 de la release antes de instalar nada, y la firma del manifest puede verificarse con cosign. La formula de Homebrew y los paquetes nativos de Linux reempaquetan los mismos binarios del canal: sus hashes provienen del manifest SHA256SUMS firmado con cosign, nunca de un build separado:

# Linux / macOS
curl -fsSL https://get.attesto.eu | sh

# Windows (PowerShell; user-level install, no admin rights)
irm https://get.attesto.eu/install.ps1 | iex

# macOS / Linux (Homebrew)
brew tap attesto/attesto https://git.attesto.eu/attesto/homebrew-attesto.git
brew trust attesto/attesto
brew install attesto

# Native Linux packages: verify the signed manifest first
curl -fsSLO https://get.attesto.eu/0.5.0/SHA256SUMS
curl -fsSLO https://get.attesto.eu/0.5.0/SHA256SUMS.sig
cosign verify-blob --key https://get.attesto.eu/cosign.pub --insecure-ignore-tlog --signature SHA256SUMS.sig SHA256SUMS

# Debian / Ubuntu (run the install as root; arm64 debs and aarch64 rpms
# are on the same channel)
curl -fsSLO https://get.attesto.eu/0.5.0/attesto_0.5.0-1_amd64.deb
sha256sum -c --ignore-missing SHA256SUMS
apt install ./attesto_0.5.0-1_amd64.deb

# Fedora / RHEL (run the install as root)
curl -fsSLO https://get.attesto.eu/0.5.0/attesto-0.5.0-1.x86_64.rpm
sha256sum -c --ignore-missing SHA256SUMS
dnf install ./attesto-0.5.0-1.x86_64.rpm

Los paquetes arm64/aarch64 están verificados a nivel de metadatos contra el manifest firmado, pero no se han ejecutado en hardware arm.

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/attesto/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/attesto/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("; "));
}

Verificación de procedencia (Attesto 3)

Los SDKs 0.5.0 añaden un cliente de verificación para la provenance lane de Attesto 3: provenance streams commitment-only alimentados por un Local Vault controlado por el cliente. El Rust edge core fijado del vault construye capsules, commitments y firmas; el SDK los vuelve a derivar y los comprueba, y deliberadamente no puede construir una capsule ni un randomizer. Cada función de esta sección se ejecuta offline, sin llamar a Attesto, y cada informe lleva una lista not_claimed que una pantalla de verificación debe mostrar junto al resultado. Protocolos: ATTESTO-PROVENANCE-001, ATTESTO-DISCLOSURE-001, ATTESTO-ZK-RANGE-001 y la bundle provenance binding de ATTESTO-PROOFSTREAM-001. La conformidad queda fijada por el corpus compartido de golden vectors en los tres lenguajes.

Verificar una disclosure presentation offline

El Local Vault de un titular emite una selective-disclosure presentation: las leaves reveladas con sus randomizers, two-hop inclusion proofs hasta la capsule root y una firma Ed25519 de la instalación emisora. El verificador abre cada commitment revelado y reproduce cada proof hasta la capsule_root presentada. Los problemas se recopilan, no se lanzan, para que quien llama vea todo lo que está mal. Pase el nonce que emitió para el modo challenge; sin él la presentation solo está acotada por su expires_at y el informe dice bounded_lifetime en lugar de sugerir una frescura que no comprobó. Non-claim: la disclosure demuestra que las leaves reveladas están en la capsule; no afirma que la capsule no contenga nada más.

from attesto.provenance import verify_disclosure

report = verify_disclosure(
    presentation,
    expected_nonce=challenge,
    subject_commitment=asset_commitment,
)
report.ok               # every leaf opened and every proof folded to capsule_root
report.verified_leaves  # ({"subtree": "claims", "leaf_role": "c2pa_manifest_valid", "value": ...},)
report.freshness        # "challenge" | "bounded_lifetime"
report.subject_checked  # True only when subject_commitment matched
report.problems         # () or every problem found
report.not_claimed      # ({"id": "undisclosed_facts_absent", "statement": ...},)

import { verifyDisclosure } from "@attesto/sdk";

const report = await verifyDisclosure(presentation, {
  expectedNonce: challenge,
  subjectCommitment: assetCommitment,
});
report.ok; report.verified_leaves; report.freshness;
report.subject_checked; report.problems; report.not_claimed;

report := attesto.VerifyDisclosure(presentation,
	attesto.WithExpectedNonce(challenge),
	attesto.WithSubjectCommitment(assetCommitment),
)
report.Ok; report.VerifiedLeaves; report.Freshness
report.SubjectChecked; report.Problems; report.NotClaimed

Verificar offline una bundle provenance inclusion y una key revocation

Un verifier bundle sobre un provenance stream lleva provenance_root, provenance_event_count y vault_key_lifecycle dentro de su payload hasheado. Un inclusion object, devuelto por GET /v2/streams/{streamId}/provenance-events/{sourceRef}/bundle-inclusion?from_checkpoint_id=...&to_checkpoint_id=... o transportado como provenance_inclusions junto al bundle, demuestra una capsule root bajo esa root. El verificador recalcula el bundle hash, vuelve a hashear la leaf a partir de sus campos, reproduce el proof, toma el receipt time del seq_no de la leaf de los propios receipts del bundle y aplica la regla de revocación congelada a la instalación que la leaf nombra. inclusion y key_status se mantienen separados: una capsule root puede estar demostrablemente bajo el bundle mientras su clave fue revocada antes de la recepción, y not_evaluated nunca es un aprobado. La revocación se evalúa contra el platform receipt time, nunca contra el occurred_at reclamado por el vault, con un límite inclusivo; una reclamación anterior a la revocación recibe la marca suspect_backdated. Non-claims: la root demuestra que la capsule root existía bajo el bundle y nada sobre el contenido de la capsule; el key lifecycle es el del momento de construir el bundle, así que una revocación posterior no está en el bundle.

from attesto.provenance import evaluate_key_revocation, verify_bundle_provenance

report = verify_bundle_provenance(bundle, inclusion)
report.ok          # bundle hash holds, inclusion VALID, key live at receipt
report.inclusion   # "VALID" | "INVALID"
report.key_status  # "valid" | "revoked_at_receipt" | "unknown_installation" | "not_evaluated"
report.flags       # e.g. ("revoked_at_receipt", "suspect_backdated")
report.not_claimed # three statements

verdict = evaluate_key_revocation(
    revoked_at=key_status["revokedAt"],          # None when never revoked
    receipt_time=receipt["payload"]["issued_at"],
    claimed_occurred_at=envelope["occurred_at"],
    reason=key_status["revocationReason"],
)
verdict.accepted   # status == "valid"

import { evaluateKeyRevocation, verifyBundleProvenance } from "@attesto/sdk";

const report = await verifyBundleProvenance(bundle, inclusion);
report.ok; report.inclusion; report.key_status; report.flags; report.not_claimed;

const verdict = evaluateKeyRevocation(
  keyStatus.revokedAt,
  receipt.payload.issued_at,
  envelope.occurred_at,
  keyStatus.revocationReason,
);
verdict.accepted;

report := attesto.VerifyBundleProvenance(bundle, inclusion)
report.Ok; report.Inclusion; report.KeyStatus; report.Flags; report.NotClaimed

verdict := attesto.EvaluateKeyRevocation(revokedAt, receiptTime, claimedOccurredAt, reason)
verdict.Accepted()

Derivar la effective assurance (L3 se deriva, nunca se firma)

Un vault firma L0 (clave de software), L1 (clave en un token PKCS#11 no extraíble) o L2 (L1 más un quote TPM 2.0 sobre la medición del vault) en su envelope, y la plataforma rechaza una envelope L1/L2 que no puede sustentar con una attestation registrada. L3 no tiene representación en el cable: el verificador lo deriva de L2 más un witness quorum alcanzado en el checkpoint que lo contiene, y una envelope que reclama L3 se rechaza. El estado del anchor se informa al lado y nunca promueve un nivel. El informe mantiene vault assurance, witness quorum, estado del anchor y el nivel derivado como cuatro hechos separados. Cómo se obtienen los niveles se describe en la guía de Local Vault.

from attesto.provenance import effective_assurance

report = effective_assurance("L2", witness_quorum_met=True, anchor_confirmed=True)
report.effective  # "L3"
report.derived    # True: derived here, signed by nobody
report.reasons    # ("anchor confirmed; anchoring does not promote assurance", "L3 derived from L2 plus a met witness quorum")
effective_assurance("L2").effective  # "L2": quorum not evaluated withholds L3
effective_assurance("L3")            # raises AttestoProvenanceError

import { effectiveAssurance } from "@attesto/sdk";

const report = effectiveAssurance("L2", { witnessQuorumMet: true, anchorConfirmed: true });
report.effective; // "L3"
report.derived;   // true
report.reasons;

met := true
report, err := attesto.EffectiveAssurance("L2", &met, &met)
report.Effective // "L3"
report.Derived   // true
report.Reasons

Verificar la apertura exacta de un private numeric

Un private numeric claim compromete su valor codificado como un Pedersen commitment sobre ristretto255. Cuando un titular revela el valor y el blinding, el verificador recalcula el commitment y lo compara byte a byte. La aritmética de curva es opcional porque el resto de la verificación es trabajo SHA-256 y Merkle: Python necesita attesto[zk], TypeScript la peer dependency @noble/curves y Go el módulo separado go.attesto.eu/sdk/zk. Un cliente sin ella informa not_checked. El descriptor debe haber abierto ya su claim leaf bajo la capsule root; de lo contrario un par coincidente puede fabricarse por completo. Un valor de exactamente cero es una apertura válida. Esto no verifica un range proof.

from attesto.provenance import pedersen_available, verify_pedersen_opening

opened = (
    verify_pedersen_opening(descriptor, encoded_value, blinding_scalar)
    if pedersen_available()
    else None  # report "not_checked"
)

import { pedersenAvailable, verifyPedersenOpening } from "@attesto/sdk";

const opened = (await pedersenAvailable())
  ? await verifyPedersenOpening(descriptor, encodedValue, blindingScalar)
  : null; // report "not_checked"

import "go.attesto.eu/sdk/zk"

opened, err := zk.VerifyOpening(descriptor, encodedValue, blindingScalar)

Inspeccionar un ZK range result

La selective disclosure v2 demuestra que la medición de un detector nombrado cayó dentro de un intervalo sin revelarla. Ningún SDK verifica el range proof en sí; eso sigue siendo tarea del Rust core. El SDK informa zk_predicate: not_checked bajo verified_here, conserva lo que el emisor afirmó bajo reported_by_issuer y rechaza un resultado que omita uno de los tres non-claims obligatorios o lleve un campo con forma de veredicto como authentic, score o probability. Un límite demostrado no dice nada sobre si el contenido fue generado por una máquina. La capsule evidence de un provider AttestoMark Image, Audio o Video es un objeto ATTESTO-PROVIDER-RESULT-001/0.2 cuyo campo presented_matches_record informa si los bytes presentados eran exactamente el asset marcado; una discrepancia es una observación que también produce una transcodificación honesta, nunca un rechazo.

from attesto.provenance import inspect_predicate_result, validate_range_statement

report = inspect_predicate_result(result)
report["verified_here"]       # {"zk_predicate": "not_checked", "capsule_inclusion": "not_checked"}
report["reported_by_issuer"]
report["not_claimed"]         # detector_correctness_not_proven, content_truth_not_proven, ai_generation_not_proven
width = validate_range_statement(statement)  # 8 | 16 | 32 | 64

import { inspectPredicateResult, validateRangeStatement } from "@attesto/sdk";

const report = inspectPredicateResult(result);
report.verified_here; report.reported_by_issuer; report.not_claimed;
const width = validateRangeStatement(statement);

report, err := attesto.InspectPredicateResult(result, nil)
report.VerifiedHere; report.ReportedByIssuer; report.NotClaimed
width, err := attesto.ValidateRangeStatement(statement)

No está en los SDKs: la construcción de capsules, la generación de randomizers y la firma de envelopes viven en el edge core del Local Vault; los range proofs solo los verifica el Rust core; todavía no hay client wrapper para POST /v2/provenance/streams; y la CLI attesto no verifica disclosures ni bundle provenance en 0.5.0.

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.