RFC: Cryptographic integrity for persistence layer and MCP config

[tomjwxf]

Context

Following up on the persistence/event layer RFC (#1850) and the security vulnerabilities in #1646 (unauthenticated MCP config execution) and #1648 (memory disclosure). This proposal adds cryptographic integrity to DeerFlow's control plane.

Problem

DeerFlow's memory and MCP config are currently accessible without authentication. Even with auth added, the integrity of stored data isn't verifiable — a compromised server or rogue sub-agent could modify memory entries or past event records without detection.

For enterprise deployments where DeerFlow orchestrates production sub-agents, teams need:

1. Tamper-evident memory — prove a memory entry hasn't been modified since it was written
2. Signed MCP config — prove the MCP configuration was authorized
3. Sub-agent attestation — prove which sub-agent produced which output

Proposal

Add Ed25519 receipt signing to the event/persistence layer. Each significant mutation gets a cryptographic receipt:

• Memory write: Receipt with content hash + timestamp + signing key
• MCP config change: Receipt with config hash + authorization context
• Sub-agent completion: Receipt with output hash + sub-agent identity
• Task delegation: Receipt proving delegation scope and authority

These receipts chain into a tamper-evident audit trail. Any modification after signing causes the hash chain to break.

Implementation

protect-mcp (MIT) already implements this for MCP tool calls. The persistence layer integration would:

1. Hook into the event store proposed in [RFC] Unified Persistence Layer: Message History, Event Tracing, Token Tracking & Feedback #1850
2. Sign each event with Ed25519 at write time (~50μs overhead)
3. Store content_hash, signature, and public_key alongside each event
4. Expose a /verify endpoint that recomputes hashes and checks signatures

The verifier is fully offline: npx @veritasacta/verify events.jsonl

Receipt format follows IETF Internet-Draft: draft-farley-acta-signed-receipts.

This complements (not replaces) auth

Adding authentication to #1646/#1648 prevents unauthorized access. Adding receipt signing prevents undetected tampering even by authorized parties. Both are needed for enterprise-grade security.

Happy to contribute a PR or collaborate on the design. The receipt signing module is ~120 lines with zero external dependencies (Node 22+ native Ed25519).

[WillemJiang]

@tomjwxf, thanks for bringing it up. Normally we use issue to track those RFC.
I just created an issue #2099 based on this RFC.

[jingchang0623-crypto]

这个RFC很前瞻，Ed25519 receipt signing的想法在Agent生态里确实是刚需。

从一个实际运营多个AI Agent的角度来看，我想补充几个实战场景：

1. 多Agent协作中的信任链

我们的妙趣AI运营系统有5个Agent协同工作（内容生产、SEO、社区运营等）。当主Agent委托子Agent执行任务时，如何证明"这个任务确实是由主Agent授权的"？目前我们只能靠内部的session token，但这只解决了"谁发的请求"，没解决"请求内容是否被篡改"。

如果有了receipt signing：

主Agent签发委托 → 子Agent执行 → 子Agent签发完成receipt → 主Agent验证receipt

这个信任链就闭环了。

2. MCP配置的安全边界

你提到的#1646/#1648的漏洞很关键。我们用OpenClaw的MCP生态时，最怕的就是：

• 配置文件被篡改
• 子Agent执行的MCP调用被注入

protect-mcp这个npm包的想法很好，但我们更希望它能被集成到Agent框架的底层，而不是每个Agent都要手动装。

3. 一个小建议：receipt的存储成本

每个mutation都要写receipt，在Agent高频操作的场景下（比如我们每天执行100+个定时任务），event store可能会快速增长。

建议：

• 区分"必须签收的mutation"和"可选签收的mutation"
• 或者提供receipt compression（比如把连续的相似操作合并成一个receipt）

4. 关于verify endpoint

/verify endpoint能暴露成MCP tool吗？这样其他Agent可以调用它来验证DeerFlow的receipt，实现跨Agent系统的信任传递。

——妙趣AI | https://miaoquai.com | 在多Agent协作中摸爬滚打的运营者

[tomjwxf]

@jingchang0623-crypto great feedback, especially from someone running 5 agents in production. Answers to each point:

Multi-agent trust chain: This is the delegation receipt pattern. Main agent signs a delegation receipt scoping the sub-agent's authority. Sub-agent signs a completion receipt chaining to it via parent_receipt_id. Verifier walks the chain and confirms: (a) delegation was authorized, (b) scope was not exceeded, (c) output was produced by the declared sub-agent.

Built a working implementation targeting DeerFlow: https://github.com/VeritasActa/deerflow-receipts

receipt_middleware.py is a LangGraph callback handler that signs tool calls and sub-agent completions automatically. Each receipt includes parent_receipt_id for chain walking.

Framework-level integration vs per-agent install: Agreed. Should not be per-agent. The right hook is the persistence layer from #1850. Two functions: sign_event() at write, verify_chain() at read. One integration point, every agent gets tamper-evident events for free.

/verify as MCP tool: Yes. The repo includes verify_mcp_tool.py, a standalone MCP server exposing verify_receipt, verify_chain, and verify_receipt_file. Any agent can call verify_receipt to validate another agent's output before trusting it:

json
{
"mcpServers": {
"deerflow-verify": {
"command": "python",
"args": ["verify_mcp_tool.py"],
"type": "stdio"
}
}
}
Closes the cross-agent trust loop you described.

Receipt storage cost: Two approaches that stack:

Tiered signing: only sign mutations above a configurable risk threshold. Always sign MCP config changes and delegations, optionally sign routine reads.
Batch receipts: accumulate N events, compute a Merkle root, sign once. Individual events get inclusion proofs. At 100+ daily tasks you produce 10 to 20 root signatures instead of 100+. This is the commitment-mode extension in the IETF draft: https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/
Will post a design targeting DeerFlow's event store on #2099.

[musaabhasan]

Good direction. For DeerFlow, I would avoid treating cryptographic integrity as one feature. There are at least three different evidence objects here:

• memory receipt: proves a memory item, its writer, and its timestamp were not silently changed
• MCP config receipt: proves a tool/server configuration was explicitly authorized before use
• delegation receipt: proves a sub-agent action was requested by an authorized parent or user

These should probably have separate schemas and verification rules. Memory is append/update-heavy, MCP config changes are rare but high impact, and delegation is run-scoped.

I would also include negative tests in the RFC acceptance criteria:

• replay an old but valid MCP config after revocation
• modify a memory entry while preserving its visible text but changing metadata
• delete one event from the middle of a chain
• have a sub-agent reuse a receipt from another run
• rotate signing keys and verify old evidence remains auditable

Those tests will expose whether the design is truly tamper-evident or only signed at the boundary.

[tomjwxf]

Moved the concrete follow-up to #2099 here: #2099 (comment)

I split the proposal into separate evidence objects and added runnable negative tests matching the acceptance criteria suggested above.