agent-toolprint

Double-signed receipts for every tool invocation by an AI agent. Portable, hash-binding, byte-canonical, verifiable offline by any third party.

agent-toolprint is the format that answers one audit question, cleanly: "yes, agent X called tool Y with these args at time T, and both sides agree." The agent signs. The tool counter-signs. Anyone with their public keys can verify — no host, no service, no chain.

It is a TypeScript library, a small spec, and a conformance suite other implementations validate against.

┌────────┐                                  ┌───────┐
│ agent  │ ── call(args) ──────────────────►│ tool  │
│        │ ◄── response ─────────────────── │       │
└───┬────┘                                  └───┬───┘
    │                                           │
    │  signAgent(receipt, agentSk)              │
    │  ─────────────────────────────────────────►
    │            envelope (1 sig)               │
    │                                           │ countersignTool(env, toolSk)
    │  ◄─────────────────────────────────────────
    │            envelope (2 sigs)              │
    ▼
verify(envelope, resolver) ──► { ok: true, receipt } | { ok: false, error }

Quickstart

git clone <repo-url> agent-toolprint
cd agent-toolprint
bun install
bun run demo

Expected: verify: { ok: true, ... } followed by verify (after 1-byte tamper): { ok: false, ... }. Under five minutes from git clone to verified receipt. The same Quickstart runs in CI on every PR — see .github/workflows/ci.yml.

30-second example

import {
  signAgent,
  countersignTool,
  verify,
  didKeyFromEd25519Pubkey,
  didKeyResolver,
  sha256Hash,
  type Receipt,
} from "agent-toolprint";
import { ed25519 } from "@noble/curves/ed25519.js";
import { randomUUID } from "node:crypto";
import { base64 } from "@scure/base";

const agentSk = ed25519.utils.randomSecretKey();
const toolSk = ed25519.utils.randomSecretKey();
const args = { query: "bun docs" };
const response = { results: ["https://bun.sh/docs"] };

const receipt: Receipt = {
  v: "tp/0.1",
  id: randomUUID(),
  ts: new Date().toISOString(),
  agent: { did: didKeyFromEd25519Pubkey(ed25519.getPublicKey(agentSk)), key_id: "agent" },
  tool:  { did: didKeyFromEd25519Pubkey(ed25519.getPublicKey(toolSk)),  key_id: "tool"  },
  call:   { name: "search", args_hash: sha256Hash(args) },
  result: { status: "ok", response_hash: sha256Hash(response) },
  nonce:  base64.encode(crypto.getRandomValues(new Uint8Array(32))),
};

const envelope = countersignTool(signAgent(receipt, agentSk), toolSk);
const result = await verify(envelope, { resolver: didKeyResolver, plaintext: { args, response } });
// → { ok: true, receipt }

Why agent-toolprint?

• Both sides on record. Agent and tool sign the same canonical bytes. Neither can later claim "that wasn't me" or "that wasn't them".
• Verifies offline. A public key and the envelope are enough — no calls to a host, ledger, or central service.
• Plays with what you have. DSSE wire format, Ed25519 signatures, JCS canonical JSON, did:key identities. No new crypto.

Compared to alternatives

| | Tool-call audit? | Both sides sign? | Offline verify? | Wire format | |---|---|---|---|---| | agent-toolprint | ✓ | ✓ | ✓ | DSSE + JCS | | MCP | invocation only — defers audit | — | — | JSON-RPC | | OTel GenAI | observability — trusted telemetry | — | — | spans | | SigStore / in-toto / SLSA | build provenance | one signer per step | ✓ | DSSE | | EAS off-chain | attestation | single signer | requires EVM | EIP-712 | | Biscuit / Macaroons | authorization, not audit | — | ✓ | bearer token |

agent-toolprint does not replace MCP — it captures what happened on top of any transport. It does not replace OTel — it adds non-repudiation OTel doesn't claim to provide.

Public API

The library exports four functions and a small surface of helpers:

| | Signature | What it does | |---|---|---| | signAgent | (receipt, sk) → Envelope | Validates receipt, JCS-canonicalizes, returns DSSE envelope with the agent signature | | countersignTool | (envelope, sk) → Envelope | Verifies the envelope is well-formed, appends the tool signature | | verify | (envelope, opts) → Promise<{ok, ...}> | Runs all five SPEC §4 checks | | chain | (parent, child) → boolean | Returns child.parent === parent.id | | didKeyResolver | Resolver | Bundled did:key resolver — pluggable | | didKeyFromEd25519Pubkey | (pk) → string | Encode an Ed25519 pubkey as a did:key | | parseDidKey | (did) → Uint8Array | Decode a did:key to its Ed25519 pubkey | | sha256Hash | (value) → "sha256:<hex>" | SHA-256 over JCS-canonical bytes | | canonical / canonicalBytes | (value) → string \| bytes | RFC 8785 JCS | | ReceiptSchema / EnvelopeSchema | Zod | Strict validators for both shapes | | PAYLOAD_TYPE, PROTOCOL_VERSION | constants | DSSE payloadType and the v field value |

verify options

type VerifyOptions = {
  resolver: Resolver;                 // pluggable DID resolver — required
  now?: Date;                         // default: new Date()
  maxClockSkewMs?: number;            // default: 24h
  skipTimestampCheck?: boolean;       // default: false
  plaintext?: { args?: unknown; response?: unknown };  // optional re-hash check
};

Receipt grammar (excerpt)

Full normative grammar in SPEC.md. The shape:

{
  "v":  "tp/0.1",
  "id": "<RFC 4122 UUID>",
  "ts": "<RFC 3339>",
  "agent":  { "did": "did:key:z…", "key_id": "…" },
  "tool":   { "did": "did:key:z…", "key_id": "…" },
  "call":   { "name": "search", "args_hash":     "sha256:…" },
  "result": { "status": "ok",   "response_hash": "sha256:…" },
  "nonce":  "<base64 32-byte random>",
  "parent": "<receipt id, optional>"
}

Wrapped in a DSSE envelope with exactly two Ed25519 signatures (agent first, tool second), over the same canonical payload bytes.

Conformance

bun run conformance
# 15/15 passed in ~0.2s

The vectors in conformance/vectors/ are the contract with other implementations. Cover all four SPEC §6 clauses:

• (C1) byte-identical canonical encoding across implementations (3 vectors)
• (C2) mutation of any field fails verify (7 vectors — payload byte-flip, agent/tool sig flip, swap-sigs, agent/tool keyid mismatch, non-canonical payload)
• (C3) single-signed envelope rejected (2 vectors)
• (C4) parent.id == child.parent enforced (3 vectors)

Each vector is JSON, language-agnostic, runs standalone. See conformance/README.md for the format and how to add new vectors.

Project layout

src/                                  # 8 files, each <200 LoC, 314 total
├── index.ts        public API re-exports
├── types.ts        Receipt + Envelope Zod schemas (strict)
├── canonical.ts    JCS + sha256
├── did-key.ts      bundled did:key resolver + Resolver type
├── envelope.ts     DSSE PAE encoding + envelope helpers
├── sign.ts         signAgent + countersignTool
├── verify.ts       5-check verifier
└── chain.ts        chain(parent, child)

examples/demo.ts                      the 20-line demo
conformance/                          12 JSON vectors + runner
tests/                                bun:test, 57 tests across 11 files
docs/superpowers/plans/               internal — implementation history

SPEC.md                               normative grammar
SCOPE.md                              v0.1 feature decisions
ROADMAP.md                            what's next, what triggers v0.2
CHANGELOG.md                          release notes
CONTRIBUTING.md                       setup + workflow + spec discipline

Security

• Replay is caller-side. The library is stateless. Consumers track (id, nonce) themselves to detect replays. See tests/security-replay.test.ts.
• Revocation is out-of-band. A receipt remains cryptographically valid even after a party repudiates it; consumers consult an external revocation list.
• Plaintext is out-of-band. Receipts carry only sha256:<hex> of JCS-canonical args/responses. Pass plaintext to verify ({ plaintext: { args, response } }) to re-hash and compare.
• Key rotation on did:key is a no-op. The verification key is derived from the DID itself.

Roadmap & versioning

Current: v0.1.0. See ROADMAP.md for what's deferred to v0.2 and the trigger conditions for promoting each item. v0.1 is did:key-only, JCS-only, hash-only payloads. No CBOR, no inline bytes, no extension points — by design (SCOPE.md explains why).

Contributing

See CONTRIBUTING.md. Short version: TDD only, Biome handles style, every code change is either a SPEC refinement or brings the impl in line with SPEC.

License

Apache 2.0 — see LICENSE.