attestproto — Agent Work Attestation Protocol

Cryptographic proof your AI agent did the work — auto-mapped to the regulations you actually have to comply with.

Open-source per-decision attestation toolkit. Self-hosted, MIT-licensed, no telemetry. Free for SMBs, free forever for self-hosted use.

Try in browser (no install): docs.attestproto.aitoolerylab.com/try Read the spec: docs.attestproto.aitoolerylab.com/spec Live demo + niche landings: attestproto.aitoolerylab.com

Pick your compliance stack

AttestProto's compliance engine ships rules for three regulatory wedges where there's no equivalent tool today:

Regulation	Deadline	Toolkit
EU AI Act Article 12 + 13 + 14 + 17 + 19	Aug 2, 2026 — €15M / 3% global revenue penalty	docs-site/eu-ai-act
FCRA + ECOA Reg B + CFPB Circular 2022-03 (AI lending)	enforced today	docs-site/lending-ai-compliance
NYC Local Law 144 § 20-871 AEDT bias audit	enforced; ramped Dec 2025	docs-site/ll144

Each comes with auto-mapped findings, per-decision attestation schema, and example evidence packages.

Why

Three regulations, all with different deadlines, all needing the same underlying primitive: a per-decision cryptographic record of what the AI agent did, what data it saw, what it concluded, and which compliance obligations were satisfied.

1. EU AI Act Article 12 mandates automatic logging for high-risk AI systems; Article 19 retains them ≥ 6 months. Effective Aug 2, 2026.
2. CFPB Circular 2022-03 + 2023-03 require specific-reasons disclosure for AI/ML credit decisions. Enforced today.
3. NYC Local Law 144 § 20-871 requires annual independent bias audit for every AEDT. Penalty $500-1,500 per violation per day; enforcement ramped up after the December 2025 NYC Comptroller report.

Today every platform — OpenAI, Anthropic, Google, Stripe — ships its own logging. Cross-vendor compliance is impossible without a neutral attestation layer. This protocol fills that gap.

What's in this repo

spec/                  Normative specification + JSON Schema + test vectors
lib/
  python/              Reference Python lib (sign + verify + canonical + CLI)
  node/                Reference Node.js lib (cross-language interop)
  ledger/              Postgres + SQLite ledger schema + migration tool
  api/                 FastAPI ledger service (REST surface)
  mcp_server/          MCP server (stdio) wrapping the ledger for LLM agents
docs-site/             Astro static site (docs.attestproto.aitoolerylab.com)
examples/              Turn-key python-agent + node-agent demos
docs/                  Operations playbook + SLA notes

Quick start

Fastest path: 30-second product demo (no ledger, no setup)

git clone https://github.com/Aispotlightlab/attestproto.git
cd attestproto/lib/python && python3 -m venv .venv && source .venv/bin/activate
pip install -e .
attestproto demo

attestproto demo runs the full lifecycle in-memory: ephemeral keypair → build sample attestation → canonicalise (RFC 8785) → Ed25519 sign → verify → compliance auto-map. Six numbered steps, all stdout. Best first impression of what the protocol produces.

Run the ledger (Docker, fastest path)

docker compose up --build -d
curl http://localhost:8765/healthz   # → {"status":"ok"}

The ledger persists data to a named volume; docker compose down keeps it, docker compose down -v wipes it. See docs/OPERATIONS.md for the production hardening checklist.

Run the ledger (no Docker)

cd lib/python && python3 -m venv .venv && source .venv/bin/activate
pip install -U pip && pip install -e ".[dev]"
pip install fastapi 'uvicorn[standard]'
cd ../api && PYTHONPATH=. uvicorn app.main:app --port 8765
# OpenAPI docs at http://localhost:8765/docs

One-command bootstrap

attestproto init my-agent
cd my-agent
python example.py     # emits + signs an attestation
python verify.py      # verifies it

From git clone to first verified attestation in under 2 minutes.

Python lib — sign + verify a single attestation

cd lib/python && source .venv/bin/activate

attestproto keygen ./keys
attestproto example ./keys/verify_key.hex > att.json
attestproto sign --in-place att.json ./keys/signing_key.hex
attestproto verify att.json ./keys/verify_key.hex
# → OK

Run a complete agent → ledger demo

The examples/python-agent/ walk-through generates a key, registers it with the running ledger, then signs and posts a fresh attestation:

cd examples/python-agent
attestproto keygen ./keys
python register_key.py
python agent.py
# → attestation accepted: att_...

A Node.js parallel example is at examples/node-agent/.

Node.js — sign + verify

cd lib/node
npm install
node src/cli.js keygen ./keys
node src/cli.js sign --in-place att.json ./keys/signing_key.hex
node src/cli.js verify att.json ./keys/verify_key.hex

Translate a competitor's attestation

# Convert ARIA Protocol AID, ERC-8004 registry entry, or Google AP2 /
# Mastercard Verifiable Intent into Mediator schema for a single
# multi-protocol audit pass.
attestproto bridge --from aria aria-doc.json > mediator-att.json
attestproto bridge --from erc8004 erc-record.json > mediator-att.json
attestproto bridge --from ap2 ap2-intent.json > mediator-att.json

Plain-English compliance findings

attestproto compliance att.json    # citation table
attestproto explain    att.json    # severity-sorted with rationale per finding

Cross-language interop

A Python-signed attestation verifies under Node.js (and vice-versa) because both implementations canonicalize via RFC 8785 JCS and sign with deterministic Ed25519. See spec/test-vectors/ for the five public conformance vectors that pass identically in both lang impls.

MCP server (Claude Desktop, Cursor, etc.)

See lib/mcp_server/README.md for the claude_desktop_config.json snippet that wires the four MCP tools (attest_create, attest_verify, agent_score, chain_walk) into your agent harness.

Spec coverage status

Spec §	Component	Status
§3 Attestation object	structured JSON object	✅ stable
§4 Canonicalization	RFC 8785 JCS	✅ stable
§5 Hashes	SHA-256 with sha256: prefix	✅ stable
§6 Identity resolution	DNS / DID-web / HTTPS / fingerprint	✅ stable
§7 Multi-hop delegation	chain-of-proof + Merkle envelope	✅ stable
§8 Confidential mode	Zero-knowledge proofs	🚧 v0.2 (Q3 2026)
§9 Co-signatures	independent attestor endorsements	✅ stable
§11 Reference ledger	epochs + Merkle batcher + reputation	✅ stable
§12 Revocation list	controller-key signed entries	📐 design draft
Compliance mapping	EU AI Act / NIST AI RMF / SOC 2 / HIPAA / ISO 42001	✅ stable
Insurance underwriting feed	per-agent actuarial metrics	✅ stable

Tests

The reference implementations carry their own test suites — 153 tests total at v0.1.0. To run all:

# Python lib (47 tests: 26 unit + 5 e2e resolver + 16 CLI + edge cases)
(cd lib/python && source .venv/bin/activate && python -m pytest tests/)

# API ledger (91 tests: 59 functional + 14 adversarial + 13 hardening + 5 concurrency)
(cd lib/api && source ../python/.venv/bin/activate && \
    MEDIATOR_RATELIMIT_OFF=1 PYTHONPATH=. python -m pytest tests/)

# Node.js (15 tests)
(cd lib/node && npm test)

# Cross-language conformance — 5 shared vectors verify under both impls.
(cd lib/python && source .venv/bin/activate && \
    python ../../spec/test-vectors/run_conformance_python.py)
(cd lib/node && node ../../spec/test-vectors/run_conformance_node.js)

License

• Spec (spec/): CC0 / public domain.
• Reference implementations (lib/): MIT.

Status

Active early-stage protocol design. Breaking changes possible until v1.0. File issues for spec ambiguities, implementation bugs, or compatibility concerns.

Contributing

See CONTRIBUTING.md. Core spec changes require an issue and at least one reference implementation update before merge.