@yobekasbah/receipts

Signed, portable, offline-verifiable receipts for AI agent actions.

Your AI agents do hundreds of things a day — tool calls, file writes, API requests, payments. When something goes wrong (a dispute, an audit, a billing fight), you need to prove what the agent did, when, and what policy allowed it. A Kasbah receipt is that proof:

• Signed — Ed25519 (RFC 8032) or post-quantum ML-DSA (FIPS 204)
• Portable — a short string + a base64 payload; goes in a header, a log line, a database column
• Offline-verifiable — anyone with the issuer's public key can verify it forever, with no API call and no trust in the issuer's continued existence
• Model-agnostic — the same receipt format whether the action came from GPT, Claude, Grok, Qwen, or a local model
• Chainable — receipts link parent→child to form verifiable multi-agent decision trees, and batch into Merkle trees for high-throughput audit

Zero runtime dependencies. Pure Node ≥ 16 crypto. Post-quantum signing is an optional peer dependency (@noble/post-quantum).

Install

npm install @yobekasbah/receipts

Sign

const { sign, generateKeyPair } = require('@yobekasbah/receipts');

const keys = generateKeyPair(); // or load your own Ed25519 key

const { receipt, payload } = sign({
  verdict: 'ALLOW',          // ALLOW | WARN | DENY
  risk: 0.12,                // 0.0–1.0
  requestId: 'req_8f3a',     // your correlation id
  subject: sha256OfInput,    // hash of the governed input (or null)
  passportId: null,          // agent identity, if any
  action: 'tool_call',
  surface: 'mcp',
}, { privateKey: keys.privateKeyPem });

// receipt → "kasbah_receipt:v3:ed25519:5f9b247e2a654719:Hk7q…"
// payload → base64url(canonical JSON) — store or transmit both

Verify — no network, no SDK lock-in

const { verify } = require('@yobekasbah/receipts');

const result = verify(receipt, payload, publicKeyPem);
// { valid: true, decoded: { verdict: 'ALLOW', risk: 0.12, ts: …, … }, keyId, algorithm }

Or from the command line:

npx kasbah-verify "kasbah_receipt:v3:ed25519:…" "<payloadB64>" --key public.pem
npx kasbah-verify "…" "…" --issuer https://your-gateway.example.com   # fetches /.well-known/kasbah-keys.json

Tampering with a single byte of the payload — the verdict, the risk score, the timestamp — invalidates the signature.

Multi-agent chains

When a parent agent spawns children, link their receipts into a verifiable tree:

const root  = sign({ …, chainId: 'wf_abc' }, keys);
const child = sign({ …, chainId: 'wf_abc', parentReceipt: root.receipt }, keys);

const { verifyChain } = require('@yobekasbah/receipts');
verifyChain([child, root], publicKeyPem);
// { valid: true, depth: 2, chainId: 'wf_abc' }

Tampering with any receipt invalidates it and every descendant.

High-throughput batches

Verify any receipt in a batch of thousands against one published root hash:

const { merkleBatch, verifyMerkleProof } = require('@yobekasbah/receipts');

const { root, proofs } = merkleBatch(receipts); // [{ receipt, payload }, …]
verifyMerkleProof(r.receipt, r.payload, proofs.get(r.receipt), root);
// { valid: true }

Post-quantum signing

npm install @noble/post-quantum

const { ml_dsa65 } = require('@noble/post-quantum/ml-dsa.js');
const kp = ml_dsa65.keygen();

sign(payload, { secretKey: kp.secretKey, publicKey: kp.publicKey },
     { algorithm: 'dilithium3' });   // ML-DSA-65, FIPS 204

The spec

The full wire format, canonical JSON rules, key distribution, chaining, and Merkle construction are specified in SPEC.md. The spec is implementation-independent: anyone can build a verifier from the document alone — that's the point. Receipts must remain verifiable even if this package, or its issuer, disappears.

Why this exists

Gateways, observability tools, and agent frameworks all log what AI does. Logs are mutable, vendor-locked, and worthless in a dispute. A receipt is a log line you can hand to the other side. As agents start delegating to other agents and spending real money, "show me the signed receipt" becomes the ground truth for liability — whichever vendor, model, or framework was involved.

License

MIT