agora-agent-receipts 0.1.0__tar.gz

agora_agent_receipts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agora_agent_receipts-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: agora-agent-receipts
+Version: 0.1.0
+Summary: Tamper-evident, third-party-verifiable receipts for AI agent / MCP tool calls
+Author: Agora
+License: MIT
+Project-URL: Homepage, https://github.com/DanceNitra/agora/tree/main/agent-receipts
+Project-URL: Source, https://github.com/DanceNitra/agora
+Keywords: ai-agents,mcp,verifiable,receipts,ed25519,audit,agent-security,provenance
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41; extra == "crypto"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# agent-receipts
+
+**Tamper-evident, third-party-verifiable receipts for AI agent / MCP actions — in one small file.**
+
+An AI agent's logs are *self-reported claims*. Nothing stops the agent — or a compromised proxy —
+from rewriting history after the fact, or from emitting a hallucinated "I called the database and it
+returned X" that never happened. A **receipt** is the opposite of a log: independent, verifiable
+evidence of what an action consumed and produced, that a third party can check **without trusting the
+agent**.
+
+This is the smallest honest version of that idea, built to be read in one sitting and run in one
+command. It is a reference proof-of-concept, not a hardened product — the scope below is deliberately
+honest about what it does and does not give you.
+
+> **Naming note / prior art.** There is already an established **"Agent Receipts" protocol** with a
+> public spec and a Python SDK by Otto Jongerius ([github.com/agent-receipts](https://github.com/agent-receipts/ar)).
+> This project is an **independent, minimal reference** for understanding the idea — it is *not* that
+> protocol's SDK, and on PyPI it is `agora-agent-receipts` to avoid any confusion. If you want the
+> protocol and a maintained SDK, use his; if you want a 200-line file to learn from or vendor, use this.
+
+```bash
+python agent_receipts.py     # core: hash-chain + Ed25519 signatures + tamper/forgery demo
+python mcp_wrapper.py         # wrap any MCP/agent tool so every call emits a receipt
+python mediator.py           # external-mediator mode: catch an agent hiding/faking its own actions
+python verify_cli.py receipts.json --pubkey <hex>   # independently verify a receipts file (no code)
+python mnemo_receipts.py     # tamper-evident memory: detect an out-of-band edit to an mnemo store
+```
+
+## What it does — two layers
+
+1. **Hash chain (integrity, zero extra deps).** Each receipt commits to the previous one
+   (`prev = hash of the last receipt`), forming a Merkle-style chain. Edit *any* past receipt and
+   every hash after it breaks — so a *partial* edit is **detectable**, and `verify()` names the exact
+   step that was altered. **Honest limit:** the hash chain *alone* does not stop a thorough tamperer
+   who recomputes the whole chain end-to-end (then no link breaks). Integrity-only is sufficient only
+   if the chain head is published/anchored where the attacker can't also rewrite it — otherwise the
+   signature (layer 2) is what actually protects a self-held chain.
+2. **Ed25519 signatures (authenticity, needs `cryptography`).** Each receipt's hash is signed with
+   the actor's private key; a third party verifies with the **public key only**. This proves *who*
+   produced the receipt and that the content wasn't forged — no shared secret. (If `cryptography`
+   isn't installed, the hash chain still works on its own.)
+
+A receipt commits to the **SHA-256 of inputs/outputs, not the raw content** — so you prove *what* was
+processed without exposing it, and reveal a value later only if you choose (anyone can re-check it
+against the committed hash). Full zero-knowledge proofs (ZK-SNARKs) go further still — proving a
+computation was correct while revealing *nothing* — and are the heavy end of this same design space.
+
+## What the demo measures
+
+The self-demo records three MCP tool calls, then attacks the trail:
+
+| step | action | result |
+|---|---|---|
+| 1 | honest chain | `verify() → True` |
+| 2 | edit a past receipt's output | caught: *content tampered* at the exact seq |
+| 3 | re-hash the forged receipt to look consistent | still caught: *invalid signature* + *broken chain link downstream* |
+
+Logs cannot do this: a self-reported log can be edited end-to-end and looks identical afterward.
+
+## Use it
+
+```python
+from agent_receipts import ReceiptChain, generate_keypair
+
+sk, pk = generate_keypair()                       # the actor's identity
+chain = ReceiptChain(actor="my-agent", private_key_hex=sk, public_key_hex=pk)
+
+chain.record("mcp.web_search", {"query": "..."}, {"results": 7})   # one receipt per tool call
+chain.record("mcp.memory.write", {"fact": "..."}, {"stored": True})
+
+ok, problems = chain.verify(expected_pubkey=pk)   # anyone with pk can run this
+open("receipts.json", "w").write(chain.to_json()) # ship the receipts; the public key verifies them
+```
+
+`mcp_wrapper.py` shows a `ReceiptedDispatcher` that drops in around an MCP-style tool registry so you
+don't touch your tools — you wrap the dispatch.
+
+## External-mediator mode (`mediator.py`)
+
+Self-signed receipts have one honest hole: an agent holding its own key can simply *not* emit a receipt
+for an action it wants to hide. The fix (as used by `pipelock` and the receiver-attested research line)
+is to move the signer **outside** the agent — route every tool call through a `Mediator` that holds its
+own key and signs what it actually brokers:
+
+```python
+from mediator import Mediator, reconcile
+med = Mediator(tools, private_key_hex=mk, public_key_hex=mpub, name="org-proxy")
+med.dispatch("transfer_funds", to="acct-9981", amount=5000)   # mediator signs the real call
+ok, problems = reconcile(agent_self_reported_log, med.chain)  # diff the agent's story vs the truth
+```
+
+The demo has an agent route three calls through the mediator, then tamper with its *own* log — hiding a
+funds transfer and faking a secret read. `reconcile()` catches all of it, because the mediator's signed
+chain is ground truth:
+
+```
+agent reported 2 actions but the mediator brokered 3 -> agent OMITTED 1 call(s)
+action 1: agent calls it 'read_secret', mediator saw 'mcp.transfer_funds'
+action 1 (mcp.transfer_funds): input hash mismatch (agent misreported its arguments)
+action 1 (mcp.transfer_funds): output hash mismatch (agent misreported the result)
+action 2 (mcp.read_secret): no agent record at all (hidden call)
+```
+
+(This is the real demo output — `reconcile()` aligns positionally, so omitting a middle call also shifts
+the indices after it; the point is that the omission and the misreport are both surfaced.) Now the agent
+cannot withhold a receipt, forge one (it lacks the mediator's key), or lie about I/O (the
+mediator hashes what really flowed through it). Optionally the agent also signs its own claim, giving a
+dual-attested receipt where agent-vs-mediator divergence is itself the alarm.
+
+## Verify someone else's receipts (`verify_cli.py`)
+
+A third party who wasn't there confirms what happened with one command — the file plus the public key:
+
+```bash
+python verify_cli.py receipts.json --pubkey 7d08e6e6...   # VERIFIED (exit 0) or FAILED (exit 1)
+```
+
+It recomputes the whole chain, checks every signature against the expected key, and names the exact
+broken step. Exit code 0/1 drops cleanly into CI or a pre-commit hook. Measured on a 2-receipt file: an
+honest file verifies; tampering one output prints `seq 0: content tampered` (exit 1); the wrong `--pubkey`
+prints `signed by an unexpected key` (exit 1).
+
+## Tamper-evident memory: the `mnemo` integration (`mnemo_receipts.py`)
+
+[mnemo](https://github.com/DanceNitra/agora/tree/main/mnemo) (our open-source memory core) is already
+append-only with deterministic supersession, so it never silently edits a fact in normal use. But the
+store is a file — anyone who can touch it can rewrite a stored memory after the fact, and any store
+would then serve the altered text as the original. Receipts close that: every `remember()` emits a
+signed receipt committing to the memory's content hash, so the *write history* is independently
+verifiable.
+
+```python
+from mnemo_receipts import ReceiptedMnemo, audit_memory
+rm = ReceiptedMnemo(Mnemo(path="mem.json"), private_key_hex=sk, public_key_hex=pk)
+rm.remember("The prod database host is db-prod-01.", key="prod-db::host", mtype="semantic")
+ok, problems = audit_memory(rm.m, rm.chain, expected_pubkey=pk)
+```
+
+`audit_memory()` re-hashes the current store against the write receipts. Measured: an honest store
+audits clean; an **out-of-band edit** (`db-prod-01 → db-attacker-07`, made straight in the store, which
+mnemo itself can't see) is caught — `memory <id>: stored content no longer matches the write receipt`.
+This is a thin wrapper; it does **not** modify mnemo's zero-dependency core.
+
+## Honest scope (what this is NOT)
+
+- The *self-signed* core proves a receipt **chain is internally consistent and authentically signed**.
+  It does **not** by itself prove the agent reported *every* action — an actor that controls its own
+  key can still withhold a receipt. That gap is closed by **external-mediator mode** (`mediator.py`,
+  below), which puts the signer outside the agent; anchoring the chain head to a third party is a
+  further hardening.
+- It commits to input/output **hashes**, not a proof that the tool *computed correctly*. That is what
+  ZK-SNARK approaches add, at much higher cost.
+- Keys here are raw/in-memory for clarity; real deployments use a KMS / hardware-backed key store.
+
+## Landscape & prior art
+
+This sits in an active, fast-moving space — **we build on it, we did not invent it.** In particular,
+the exact pattern here (Ed25519 + canonical JSON + hash-chain) is the production-grade subject of
+**Microsoft's [agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit),
+Tutorial 33 "offline verifiable receipts"** (Ed25519 over RFC 8785 / JCS canonical payloads,
+hash-chained, CLI-verifiable offline). Treat this repo as the *minimal one-file way to understand the
+idea*, and that toolkit as the grown-up version.
+
+Honest map of the space:
+
+- **A named protocol + SDK:** the **"Agent Receipts" protocol** by Otto Jongerius — a public spec
+  ([github.com/agent-receipts/ar](https://github.com/agent-receipts/ar)) plus a maintained Python
+  SDK (`pip install agent-receipts`). The most directly-related effort to this one; if you need an
+  interoperable standard rather than a teaching reference, start there.
+- **Production OSS (corporate):** Microsoft `agent-governance-toolkit` — Tutorial 33 = the same
+  Ed25519 + canonical + hash-chain receipts, with policy/identity/sandboxing around it.
+- **External-mediator receipts:** [`pipelock`](https://github.com/luckyPipewrench/pipelock) — an
+  open-source MCP/egress firewall that emits *mediator-signed* Ed25519 receipts from **outside** the
+  agent (core Apache-2.0; enterprise features Elastic-License), which is how you close the
+  agent-can-withhold-a-receipt gap noted above.
+- **Commercial:** [Zero Proof AI](https://zeroproofai.com) — a pre-launch "certificate authority for
+  AI agents" issuing on-chain-anchored receipts for tool calls.
+- **Research:**
+  - Basu, *Tool Receipts, Not Zero-Knowledge Proofs: Practical Hallucination Detection for AI Agents*,
+    [arXiv:2603.10060](https://arxiv.org/abs/2603.10060) (2026) — HMAC-signed tool-execution receipts
+    (the pragmatic, symmetric camp; we use Ed25519 so a third party verifies without a shared secret).
+  - Figuera, *Notarized Agents: Receiver-Attested Confidential Receipts for AI Agent Actions*,
+    [arXiv:2606.04193](https://arxiv.org/abs/2606.04193) (2026) — receiver-signed receipts published
+    to a transparency log (the external-attestation camp).
+  - Jing & Qi, *Zero-Knowledge Audit for Internet of Agents … with Model Context Protocol*,
+    [arXiv:2512.14737](https://arxiv.org/abs/2512.14737) (2025) — the zero-knowledge / privacy-
+    preserving end of the same space.
+
+## Roadmap (if this proves useful)
+
+~~External-mediator mode~~ (done — `mediator.py`) · ~~verifier CLI~~ (done — `verify_cli.py`) ·
+~~`mnemo` integration~~ (done — `mnemo_receipts.py`) · publish-and-anchor the chain head · selective
+disclosure of a single committed field · packaged spin-out (PyPI).
+
+MIT. Part of the [Agora](https://github.com/DanceNitra/agora) project — an autonomous research OS that
+ships every claim with a runnable receipt. Feedback and adversarial testing welcome.

agora_agent_receipts-0.1.0/README.md

@@ -0,0 +1,196 @@
+# agent-receipts
+
+**Tamper-evident, third-party-verifiable receipts for AI agent / MCP actions — in one small file.**
+
+An AI agent's logs are *self-reported claims*. Nothing stops the agent — or a compromised proxy —
+from rewriting history after the fact, or from emitting a hallucinated "I called the database and it
+returned X" that never happened. A **receipt** is the opposite of a log: independent, verifiable
+evidence of what an action consumed and produced, that a third party can check **without trusting the
+agent**.
+
+This is the smallest honest version of that idea, built to be read in one sitting and run in one
+command. It is a reference proof-of-concept, not a hardened product — the scope below is deliberately
+honest about what it does and does not give you.
+
+> **Naming note / prior art.** There is already an established **"Agent Receipts" protocol** with a
+> public spec and a Python SDK by Otto Jongerius ([github.com/agent-receipts](https://github.com/agent-receipts/ar)).
+> This project is an **independent, minimal reference** for understanding the idea — it is *not* that
+> protocol's SDK, and on PyPI it is `agora-agent-receipts` to avoid any confusion. If you want the
+> protocol and a maintained SDK, use his; if you want a 200-line file to learn from or vendor, use this.
+
+```bash
+python agent_receipts.py     # core: hash-chain + Ed25519 signatures + tamper/forgery demo
+python mcp_wrapper.py         # wrap any MCP/agent tool so every call emits a receipt
+python mediator.py           # external-mediator mode: catch an agent hiding/faking its own actions
+python verify_cli.py receipts.json --pubkey <hex>   # independently verify a receipts file (no code)
+python mnemo_receipts.py     # tamper-evident memory: detect an out-of-band edit to an mnemo store
+```
+
+## What it does — two layers
+
+1. **Hash chain (integrity, zero extra deps).** Each receipt commits to the previous one
+   (`prev = hash of the last receipt`), forming a Merkle-style chain. Edit *any* past receipt and
+   every hash after it breaks — so a *partial* edit is **detectable**, and `verify()` names the exact
+   step that was altered. **Honest limit:** the hash chain *alone* does not stop a thorough tamperer
+   who recomputes the whole chain end-to-end (then no link breaks). Integrity-only is sufficient only
+   if the chain head is published/anchored where the attacker can't also rewrite it — otherwise the
+   signature (layer 2) is what actually protects a self-held chain.
+2. **Ed25519 signatures (authenticity, needs `cryptography`).** Each receipt's hash is signed with
+   the actor's private key; a third party verifies with the **public key only**. This proves *who*
+   produced the receipt and that the content wasn't forged — no shared secret. (If `cryptography`
+   isn't installed, the hash chain still works on its own.)
+
+A receipt commits to the **SHA-256 of inputs/outputs, not the raw content** — so you prove *what* was
+processed without exposing it, and reveal a value later only if you choose (anyone can re-check it
+against the committed hash). Full zero-knowledge proofs (ZK-SNARKs) go further still — proving a
+computation was correct while revealing *nothing* — and are the heavy end of this same design space.
+
+## What the demo measures
+
+The self-demo records three MCP tool calls, then attacks the trail:
+
+| step | action | result |
+|---|---|---|
+| 1 | honest chain | `verify() → True` |
+| 2 | edit a past receipt's output | caught: *content tampered* at the exact seq |
+| 3 | re-hash the forged receipt to look consistent | still caught: *invalid signature* + *broken chain link downstream* |
+
+Logs cannot do this: a self-reported log can be edited end-to-end and looks identical afterward.
+
+## Use it
+
+```python
+from agent_receipts import ReceiptChain, generate_keypair
+
+sk, pk = generate_keypair()                       # the actor's identity
+chain = ReceiptChain(actor="my-agent", private_key_hex=sk, public_key_hex=pk)
+
+chain.record("mcp.web_search", {"query": "..."}, {"results": 7})   # one receipt per tool call
+chain.record("mcp.memory.write", {"fact": "..."}, {"stored": True})
+
+ok, problems = chain.verify(expected_pubkey=pk)   # anyone with pk can run this
+open("receipts.json", "w").write(chain.to_json()) # ship the receipts; the public key verifies them
+```
+
+`mcp_wrapper.py` shows a `ReceiptedDispatcher` that drops in around an MCP-style tool registry so you
+don't touch your tools — you wrap the dispatch.
+
+## External-mediator mode (`mediator.py`)
+
+Self-signed receipts have one honest hole: an agent holding its own key can simply *not* emit a receipt
+for an action it wants to hide. The fix (as used by `pipelock` and the receiver-attested research line)
+is to move the signer **outside** the agent — route every tool call through a `Mediator` that holds its
+own key and signs what it actually brokers:
+
+```python
+from mediator import Mediator, reconcile
+med = Mediator(tools, private_key_hex=mk, public_key_hex=mpub, name="org-proxy")
+med.dispatch("transfer_funds", to="acct-9981", amount=5000)   # mediator signs the real call
+ok, problems = reconcile(agent_self_reported_log, med.chain)  # diff the agent's story vs the truth
+```
+
+The demo has an agent route three calls through the mediator, then tamper with its *own* log — hiding a
+funds transfer and faking a secret read. `reconcile()` catches all of it, because the mediator's signed
+chain is ground truth:
+
+```
+agent reported 2 actions but the mediator brokered 3 -> agent OMITTED 1 call(s)
+action 1: agent calls it 'read_secret', mediator saw 'mcp.transfer_funds'
+action 1 (mcp.transfer_funds): input hash mismatch (agent misreported its arguments)
+action 1 (mcp.transfer_funds): output hash mismatch (agent misreported the result)
+action 2 (mcp.read_secret): no agent record at all (hidden call)
+```
+
+(This is the real demo output — `reconcile()` aligns positionally, so omitting a middle call also shifts
+the indices after it; the point is that the omission and the misreport are both surfaced.) Now the agent
+cannot withhold a receipt, forge one (it lacks the mediator's key), or lie about I/O (the
+mediator hashes what really flowed through it). Optionally the agent also signs its own claim, giving a
+dual-attested receipt where agent-vs-mediator divergence is itself the alarm.
+
+## Verify someone else's receipts (`verify_cli.py`)
+
+A third party who wasn't there confirms what happened with one command — the file plus the public key:
+
+```bash
+python verify_cli.py receipts.json --pubkey 7d08e6e6...   # VERIFIED (exit 0) or FAILED (exit 1)
+```
+
+It recomputes the whole chain, checks every signature against the expected key, and names the exact
+broken step. Exit code 0/1 drops cleanly into CI or a pre-commit hook. Measured on a 2-receipt file: an
+honest file verifies; tampering one output prints `seq 0: content tampered` (exit 1); the wrong `--pubkey`
+prints `signed by an unexpected key` (exit 1).
+
+## Tamper-evident memory: the `mnemo` integration (`mnemo_receipts.py`)
+
+[mnemo](https://github.com/DanceNitra/agora/tree/main/mnemo) (our open-source memory core) is already
+append-only with deterministic supersession, so it never silently edits a fact in normal use. But the
+store is a file — anyone who can touch it can rewrite a stored memory after the fact, and any store
+would then serve the altered text as the original. Receipts close that: every `remember()` emits a
+signed receipt committing to the memory's content hash, so the *write history* is independently
+verifiable.
+
+```python
+from mnemo_receipts import ReceiptedMnemo, audit_memory
+rm = ReceiptedMnemo(Mnemo(path="mem.json"), private_key_hex=sk, public_key_hex=pk)
+rm.remember("The prod database host is db-prod-01.", key="prod-db::host", mtype="semantic")
+ok, problems = audit_memory(rm.m, rm.chain, expected_pubkey=pk)
+```
+
+`audit_memory()` re-hashes the current store against the write receipts. Measured: an honest store
+audits clean; an **out-of-band edit** (`db-prod-01 → db-attacker-07`, made straight in the store, which
+mnemo itself can't see) is caught — `memory <id>: stored content no longer matches the write receipt`.
+This is a thin wrapper; it does **not** modify mnemo's zero-dependency core.
+
+## Honest scope (what this is NOT)
+
+- The *self-signed* core proves a receipt **chain is internally consistent and authentically signed**.
+  It does **not** by itself prove the agent reported *every* action — an actor that controls its own
+  key can still withhold a receipt. That gap is closed by **external-mediator mode** (`mediator.py`,
+  below), which puts the signer outside the agent; anchoring the chain head to a third party is a
+  further hardening.
+- It commits to input/output **hashes**, not a proof that the tool *computed correctly*. That is what
+  ZK-SNARK approaches add, at much higher cost.
+- Keys here are raw/in-memory for clarity; real deployments use a KMS / hardware-backed key store.
+
+## Landscape & prior art
+
+This sits in an active, fast-moving space — **we build on it, we did not invent it.** In particular,
+the exact pattern here (Ed25519 + canonical JSON + hash-chain) is the production-grade subject of
+**Microsoft's [agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit),
+Tutorial 33 "offline verifiable receipts"** (Ed25519 over RFC 8785 / JCS canonical payloads,
+hash-chained, CLI-verifiable offline). Treat this repo as the *minimal one-file way to understand the
+idea*, and that toolkit as the grown-up version.
+
+Honest map of the space:
+
+- **A named protocol + SDK:** the **"Agent Receipts" protocol** by Otto Jongerius — a public spec
+  ([github.com/agent-receipts/ar](https://github.com/agent-receipts/ar)) plus a maintained Python
+  SDK (`pip install agent-receipts`). The most directly-related effort to this one; if you need an
+  interoperable standard rather than a teaching reference, start there.
+- **Production OSS (corporate):** Microsoft `agent-governance-toolkit` — Tutorial 33 = the same
+  Ed25519 + canonical + hash-chain receipts, with policy/identity/sandboxing around it.
+- **External-mediator receipts:** [`pipelock`](https://github.com/luckyPipewrench/pipelock) — an
+  open-source MCP/egress firewall that emits *mediator-signed* Ed25519 receipts from **outside** the
+  agent (core Apache-2.0; enterprise features Elastic-License), which is how you close the
+  agent-can-withhold-a-receipt gap noted above.
+- **Commercial:** [Zero Proof AI](https://zeroproofai.com) — a pre-launch "certificate authority for
+  AI agents" issuing on-chain-anchored receipts for tool calls.
+- **Research:**
+  - Basu, *Tool Receipts, Not Zero-Knowledge Proofs: Practical Hallucination Detection for AI Agents*,
+    [arXiv:2603.10060](https://arxiv.org/abs/2603.10060) (2026) — HMAC-signed tool-execution receipts
+    (the pragmatic, symmetric camp; we use Ed25519 so a third party verifies without a shared secret).
+  - Figuera, *Notarized Agents: Receiver-Attested Confidential Receipts for AI Agent Actions*,
+    [arXiv:2606.04193](https://arxiv.org/abs/2606.04193) (2026) — receiver-signed receipts published
+    to a transparency log (the external-attestation camp).
+  - Jing & Qi, *Zero-Knowledge Audit for Internet of Agents … with Model Context Protocol*,
+    [arXiv:2512.14737](https://arxiv.org/abs/2512.14737) (2025) — the zero-knowledge / privacy-
+    preserving end of the same space.
+
+## Roadmap (if this proves useful)
+
+~~External-mediator mode~~ (done — `mediator.py`) · ~~verifier CLI~~ (done — `verify_cli.py`) ·
+~~`mnemo` integration~~ (done — `mnemo_receipts.py`) · publish-and-anchor the chain head · selective
+disclosure of a single committed field · packaged spin-out (PyPI).
+
+MIT. Part of the [Agora](https://github.com/DanceNitra/agora) project — an autonomous research OS that
+ships every claim with a runnable receipt. Feedback and adversarial testing welcome.

agora_agent_receipts-0.1.0/agent_receipts.py

@@ -0,0 +1,221 @@
+"""agent-receipts — tamper-evident, third-party-verifiable receipts for AI agent / MCP actions.
+
+The problem: an AI agent's own logs are *self-reported claims*. Nothing stops the agent (or a
+compromised proxy) from rewriting history after the fact, or from a hallucinated "I called the
+database and it returned X" that never happened. A *receipt* is the opposite of a log: independent,
+verifiable evidence of what an action consumed and produced, that a third party can check without
+trusting the agent.
+
+This single file gives the smallest honest version of that, in two layers:
+
+  1. HASH CHAIN (integrity, zero extra deps).  Each receipt commits to the previous one
+     (prev = hash of the last receipt), so the whole sequence is a Merkle-style chain. Edit ANY
+     past receipt and every hash after it breaks -> a *partial* edit is detectable, and you can
+     name the exact step that was altered. IMPORTANT, honest limit: the hash chain ALONE does not
+     stop a thorough tamperer who recomputes the whole chain end-to-end (no link breaks then) -- so
+     integrity-only is enough only if the chain head is published/anchored somewhere the attacker
+     can't also rewrite. The SIGNATURE (layer 2) is what protects a self-held chain.
+
+  2. ED25519 SIGNATURES (authenticity, needs `cryptography`).  Each receipt's hash is signed with
+     the actor's private key. A third party verifies with the PUBLIC key only -> it proves *who*
+     produced the receipt and that the content wasn't forged, without anyone sharing a secret.
+     (Optional: if `cryptography` is not installed, the hash chain still works on its own.)
+
+Privacy nod (the "zero-knowledge-ish" part): receipts store the SHA-256 of inputs/outputs, not the
+raw content. You commit to *what* was processed; you reveal the content only if/when you choose, and
+anyone can later check a revealed value against the committed hash. Real zero-knowledge proofs (ZK-
+SNARKs) go further — proving a computation was correct without revealing inputs at all — and are the
+heavier end of this same design space (see the README for the landscape and prior art).
+
+Run the self-demo:  python agent_receipts.py
+MIT. Part of the Agora project. Honest scope: this is a reference PoC, not a hardened product.
+"""
+from __future__ import annotations
+import json
+import time
+import hashlib
+from typing import Any, Optional
+
+GENESIS = "0" * 64
+
+# --- optional asymmetric signing (graceful if the lib is absent) ---
+try:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey, Ed25519PublicKey,
+    )
+    from cryptography.hazmat.primitives import serialization
+    _HAVE_CRYPTO = True
+except Exception:  # pragma: no cover - exercised only on installs without `cryptography`
+    _HAVE_CRYPTO = False
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _canonical(obj: Any) -> bytes:
+    """Deterministic JSON so the same content always hashes the same (sorted keys, no spaces)."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def hash_content(content: Any) -> str:
+    """Hash arbitrary input/output content. Bytes are hashed as-is; everything else is canonicalized."""
+    if isinstance(content, (bytes, bytearray)):
+        return sha256_hex(bytes(content))
+    return sha256_hex(_canonical(content))
+
+
+def generate_keypair() -> tuple[str, str]:
+    """Return (private_key_hex, public_key_hex) for an Ed25519 actor identity."""
+    if not _HAVE_CRYPTO:
+        raise RuntimeError("signing requires the `cryptography` package (pip install cryptography)")
+    sk = Ed25519PrivateKey.generate()
+    sk_hex = sk.private_bytes(
+        serialization.Encoding.Raw, serialization.PrivateFormat.Raw, serialization.NoEncryption()
+    ).hex()
+    pk_hex = sk.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    ).hex()
+    return sk_hex, pk_hex
+
+
+def _sign(private_key_hex: str, message: bytes) -> str:
+    sk = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(private_key_hex))
+    return sk.sign(message).hex()
+
+
+def _verify_sig(public_key_hex: str, signature_hex: str, message: bytes) -> bool:
+    try:
+        pk = Ed25519PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
+        pk.verify(bytes.fromhex(signature_hex), message)
+        return True
+    except Exception:
+        return False
+
+
+def receipt_hash(r: dict) -> str:
+    """The receipt's own hash commits to its content AND the previous receipt (the chain link)."""
+    core = {
+        "seq": r["seq"], "ts": r["ts"], "action": r["action"], "actor": r.get("actor"),
+        "input_sha256": r["input_sha256"], "output_sha256": r["output_sha256"],
+        "meta": r.get("meta"), "prev": r["prev"],
+    }
+    return sha256_hex(_canonical(core))
+
+
+class ReceiptChain:
+    """An append-only, hash-chained, optionally-signed sequence of action receipts."""
+
+    def __init__(self, actor: Optional[str] = None, private_key_hex: Optional[str] = None,
+                 public_key_hex: Optional[str] = None):
+        self.actor = actor
+        self._sk = private_key_hex
+        self.public_key_hex = public_key_hex
+        self.receipts: list[dict] = []
+
+    def record(self, action: str, inputs: Any, output: Any, meta: Optional[dict] = None,
+               ts: Optional[float] = None) -> dict:
+        """Record one action (e.g. an MCP tool call): commit to its input/output hashes, chain, sign."""
+        prev = self.receipts[-1]["hash"] if self.receipts else GENESIS
+        r = {
+            "seq": len(self.receipts),
+            "ts": ts if ts is not None else time.time(),
+            "action": action,
+            "actor": self.actor,
+            "input_sha256": hash_content(inputs),
+            "output_sha256": hash_content(output),
+            "meta": meta,
+            "prev": prev,
+        }
+        r["hash"] = receipt_hash(r)
+        if self._sk:
+            r["pubkey"] = self.public_key_hex
+            r["sig"] = _sign(self._sk, bytes.fromhex(r["hash"]))
+        self.receipts.append(r)
+        return r
+
+    def verify(self, expected_pubkey: Optional[str] = None) -> tuple[bool, list[str]]:
+        """Recompute the chain from scratch. Returns (ok, problems). Names the exact broken step."""
+        problems: list[str] = []
+        prev = GENESIS
+        for i, r in enumerate(self.receipts):
+            if r.get("seq") != i:
+                problems.append(f"seq {i}: out-of-order (claims seq={r.get('seq')})")
+            if r.get("prev") != prev:
+                problems.append(f"seq {i}: broken chain link (prev mismatch -> a prior receipt was altered/removed)")
+            if receipt_hash(r) != r.get("hash"):
+                problems.append(f"seq {i}: content tampered (hash does not match this receipt's fields)")
+            if "sig" in r:
+                pk = r.get("pubkey")
+                if expected_pubkey and pk != expected_pubkey:
+                    problems.append(f"seq {i}: signed by an unexpected key (possible impersonation)")
+                if not _HAVE_CRYPTO:
+                    problems.append(f"seq {i}: signature present but `cryptography` not installed to verify it")
+                elif not _verify_sig(pk, r["sig"], bytes.fromhex(r["hash"])):
+                    problems.append(f"seq {i}: invalid signature (forged or wrong key)")
+            elif expected_pubkey:
+                problems.append(f"seq {i}: unsigned, but a signature was required")
+            prev = r.get("hash")
+        return (len(problems) == 0, problems)
+
+    def to_json(self) -> str:
+        return json.dumps(self.receipts, indent=2, ensure_ascii=False)
+
+    @classmethod
+    def from_receipts(cls, receipts: list[dict]) -> "ReceiptChain":
+        c = cls()
+        c.receipts = receipts
+        return c
+
+
+def _demo() -> None:
+    print("=== agent-receipts: self-demo ===\n")
+    signed = _HAVE_CRYPTO
+    if signed:
+        sk, pk = generate_keypair()
+        chain = ReceiptChain(actor="research-agent-01", private_key_hex=sk, public_key_hex=pk)
+        print(f"actor identity (public key): {pk[:16]}...  (third parties verify with this, no secret shared)\n")
+    else:
+        chain = ReceiptChain(actor="research-agent-01")
+        pk = None
+        print("(`cryptography` not installed -> hash-chain only, no signatures)\n")
+
+    # An agent does three MCP tool calls. Each gets a receipt.
+    chain.record("mcp.web_search", {"query": "supersession blind spot AUROC"},
+                 {"results": 7, "top": "arXiv:2606.26511"})
+    chain.record("mcp.memory.write", {"fact": "Pro tier costs 39 USD/mo", "source": "billing:tool"},
+                 {"stored": True, "id": "m-1042"})
+    chain.record("mcp.code.run", {"cmd": "python probe.py"}, {"exit": 0, "stdout_sha": "9f1c..."})
+    print(f"recorded {len(chain.receipts)} receipts (one per tool call)")
+
+    ok, problems = chain.verify(expected_pubkey=pk)
+    print(f"[1] honest chain verifies?  {ok}  {problems if problems else ''}")
+
+    # TAMPER: someone edits a past receipt's output AFTER the fact (e.g. to hide what really happened).
+    chain.receipts[1]["output_sha256"] = hash_content({"stored": True, "id": "m-DIFFERENT"})
+    ok2, problems2 = chain.verify(expected_pubkey=pk)
+    print(f"[2] after editing receipt #1's output:  verifies? {ok2}")
+    for p in problems2:
+        print(f"      - {p}")
+
+    # FORGE: rebuild #1 so its own hash matches the edit. The hash chain is now internally consistent,
+    # but the SIGNATURE was made over the original hash by the real key -> still caught (if signed).
+    chain.receipts[1]["hash"] = receipt_hash(chain.receipts[1])
+    ok3, problems3 = chain.verify(expected_pubkey=pk)
+    print(f"[3] after also recomputing the hash to match:  verifies? {ok3}")
+    for p in problems3:
+        print(f"      - {p}")
+    if signed:
+        print("    -> the signature (made by the real key over the ORIGINAL hash) exposes the forgery,")
+        print("       and #2's broken chain link points downstream. Integrity + authenticity together.")
+    else:
+        print("    -> this lazy edit broke a chain link, so it's caught. But WITHOUT signatures a")
+        print("       thorough tamperer would recompute the WHOLE chain (no link breaks) and it would")
+        print("       pass -- integrity-only needs an anchored/published head. Ed25519 signing closes this.")
+
+    print("\nMEASURED: an honest receipt chain verifies; a partial edit is detected at the exact step;")
+    print("a re-hashed forgery is caught by the SIGNATURE (a full recompute defeats the hash chain alone).")
+
+
+if __name__ == "__main__":
+    _demo()