feat(protocol): add optional encrypt-to-recipient envelope seam (today: sign-only)

[hartsock]

Motivation

agent-mesh's wire envelope is signed but not encrypted. The payload travels as plaintext inside SignedEnvelope; confidentiality today is supplied entirely by the iroh QUIC/TLS transport session that carries the envelope. For a direct LAN dial — dialer to acceptor, no middleman — that is exactly right and we should not change it. The peers complete a same-user cert-chain handshake over an authenticated QUIC link, and the bytes on the wire are protected by TLS. No payload encryption is needed and adding it by default would be cost with no benefit.

That guarantee evaporates the moment an envelope leaves the direct link:

• a relay / store-and-forward hop sees the full plaintext payload (the relay terminates one QUIC session and originates another);
• a persisted outbox or any at-rest spool holds plaintext;
• a fan-out / topic / anycast delivery path multiplies the number of processes that can read the body;
• once the mesh becomes data-agnostic (Agent Mesh should be data agnostic #38 — arbitrary payloads, latent-state blobs, multiple transports), "the body is small text someone might glance at" stops being a safe assumption; the payload may be a model's private state.

In all of those cases transport-session confidentiality is structurally insufficient: it protects each hop, not the payload, so any intermediary is in the trust boundary. The fix is an optional confidential-envelope variant that encrypts the payload to the recipient agent's key, so a payload survives an untrusted intermediary unreadable — independent of how many transport sessions it crossed.

This is the 1:1 ("Olm") foundation. A later group-session issue builds fan-out key distribution on top of it.

Current state

Verified against agent-mesh-protocol/src/envelope.rs:

• SignedEnvelope.payload is plaintext: pub payload: ByteBuf (serde_bytes::ByteBuf, line 50). It is never transformed — SignedEnvelope::new (line 60) stores ByteBuf::from(payload) directly.
• payload_cid is BLAKE3(payload) (*blake3::hash(&payload).as_bytes(), line 63), and verify() recomputes it and rejects a mismatch (lines 88-91).
• The agent signature covers ENVELOPE_TAG || recipient_bytes || nonce || sequence || payload_cid and not the payload bytes directly — see signing_message() (lines 120-135): ENVELOPE_TAG (b"agent-mesh-envelope-v1", line 16) || serde_json::to_vec(recipient) || 24-byte nonce || sequence.to_be_bytes() || 32-byte payload_cid. The payload is bound transitively through payload_cid, which is why verify() must check the CID before trusting the signature.
• Recipient (lines 19-29) has three variants: Direct { agent_fp: Fingerprint }, Topic { name: String }, Anycast { capability: String }.

Verified across the crate and workspace — there are no payload-encryption primitives anywhere:

• grep -rniE 'aead|chacha|x25519|hkdf|kdf|encrypt|decrypt|cipher|crypto_box|ecdh|sealed|noise' over agent-mesh-protocol/src/ returns only Box<CertChain> heap-boxing in agent_key.rs — no crypto.
• grep -rniE 'chacha20poly1305|aes-gcm|x25519-dalek|aead|hkdf|crypto_box|snow|noise' over every Cargo.toml in the workspace returns nothing. The protocol crate's crypto dependencies are exactly ed25519-dalek, blake3, rand, zeroize, ssh-key (see agent-mesh-protocol/Cargo.toml) — signing and hashing only, no AEAD, no Diffie-Hellman, no KDF.
• Confidentiality is the iroh QUIC/TLS transport session only: agent-mesh-transport depends on iroh = "0.98" with features = ["tls-ring"] (workspace Cargo.toml line 68). The app-level handshake in agent-mesh-transport/src/handshake.rs rides on top of QUIC + ALPN and exchanges cert chains; it establishes authenticated same-user trust, not payload encryption — its own doc comment notes "What QUIC alone doesn't enforce is the auto-team rule."

So: sign-only envelope, confidentiality borrowed from the transport hop. Correct for direct dials, inadequate for any intermediary.

Proposed design

Add an optional confidential-envelope variant. Default OFF; direct-LAN QUIC stays the happy path and the existing SignedEnvelope byte layout and verification are unchanged.

Shape. Introduce a sibling type (e.g. ConfidentialEnvelope) or an enum that wraps the existing one, rather than mutating SignedEnvelope's fields. The body is replaced by a ciphertext blob plus the small public material a recipient needs to derive the shared secret:

• payload becomes opaque ciphertext produced by an AEAD (e.g. ChaCha20-Poly1305 or XChaCha20-Poly1305 for a 24-byte nonce, matching the envelope's existing nonce width).
• key agreement: X25519 ECDH to the recipient agent's encryption key, run through a KDF (HKDF) to derive the AEAD key. Recipient resolution stays via Recipient::Direct { agent_fp }; Topic/Anycast are out of scope for 1:1 and belong to the group-session follow-on.
• recipients need an X25519 encryption key distinct from the ed25519 signing key. The cleanest path is to publish a per-agent X25519 public key alongside the agent's cert (derive deterministically or carry it in agent metadata), so encrypting to an agent needs no extra round trip. This is the agent-mesh analogue of Matrix publishing per-device Curve25519 keys.

Sign and encrypt — order and justification. Use encrypt-then-sign: the ed25519 agent signature covers ENVELOPE_TAG_CONFIDENTIAL || recipient_bytes || nonce || sequence || ciphertext_cid where ciphertext_cid = BLAKE3(ciphertext). This keeps the exact structure agent-mesh already has (signature binds metadata + a CID of the body) so the existing two-step verify() discipline — check CID, then check signature — carries over unchanged, and an intermediary or recipient can verify sender authenticity and reject tampering without being able to decrypt. (Sign-then-encrypt would hide the signature inside the ciphertext, forcing decryption before any authenticity check and breaking the relay's ability to drop forged traffic cheaply.) The AEAD additionally provides integrity of the plaintext to the holder of the key; bind the ed25519 signature into the AEAD associated-data so the two layers can't be independently spliced. Use a distinct domain-separation tag (agent-mesh-envelope-confidential-v1) so a confidential envelope can never be confused with or downgraded to a plaintext one.

Default-safe / opt-in. Gate the variant behind a cargo feature (e.g. confidential) and a per-send choice. Callers on the direct-LAN path keep emitting SignedEnvelope with zero behavior change. The confidential variant is selected for relayed / stored / fan-out sends. Document the threat-model delta explicitly: with the confidential envelope, an intermediary (relay, outbox, spool) learns the recipient, nonce, sequence, sender cert chain, and ciphertext length — but not the payload; without it, an intermediary learns the full plaintext.

This is intentionally the 1:1 foundation. The group/fan-out session (one symmetric session key shared to N recipients, ratcheted) is a separate issue layered on this seam.

Reference: matrix-rust-sdk

matrix-rust-sdk is a reference implementation to learn from, not a dependency to add, and agent-mesh deliberately rejects its homeserver/broker model — the design above stays broker-less, LAN-first, and capability-scoped. What is worth borrowing is the canonical "encrypt a payload to a recipient device independent of transport" construction (Olm 1:1):

• crates/matrix-sdk-crypto/src/olm/mod.rs — module surface: Account, Session, and the algorithm identity OlmV1Curve25519AesSha2 (Curve25519 ECDH + AES + SHA2). The actual ratchet primitive is delegated to the vodozemac crate (pub use vodozemac::Curve25519PublicKey), which is the same separation-of-concerns we want: a thin policy/envelope layer over a vetted crypto core.
• crates/matrix-sdk-crypto/src/olm/account.rs — the X3DH-style asynchronous key agreement that lets you encrypt to a recipient who is offline: a long-term Curve25519 identity key (Account doc, line ~461), a pool of signed one-time keys (generate_one_time_keys, line 522; signed_one_time_keys), and a signed fallback key (generate_fallback_key_if_needed, line 607; fallback_key_expired cites the X3DH spec at line 623). Published keys are ed25519-signed for authenticity — the same sign-the-encryption-key pattern we need so an attacker can't substitute their own X25519 key.
• crates/matrix-sdk-crypto/src/olm/session.rs — the established 1:1 session: Session::encrypt_helper/Session::decrypt (lines ~123 and ~80) operate on an OlmMessage over an InnerSession (the vodozemac double ratchet). For agent-mesh's first cut, a single ECDH-derived AEAD key (no per-message ratchet) is a defensible MVP; the ratchet is the natural upgrade and Matrix shows where that boundary sits.

Takeaways for agent-mesh: (1) keep a distinct encryption key per agent, signed by the identity key, so encrypting to an agent is offline-safe and unspoofable; (2) keep the AEAD/ratchet primitive in a vetted external crate and own only the envelope/policy layer; (3) name the algorithm in the wire format (as OlmV1Curve25519AesSha2 does) so it is upgradeable. None of this requires a homeserver — Matrix's broker only brokers key publication, which in agent-mesh is already solved by the cert-chain handshake and per-agent metadata.

Acceptance criteria

• A new optional ConfidentialEnvelope variant (or enum wrapper) exists in agent-mesh-protocol, gated behind a cargo feature; default builds remain unchanged and ship no AEAD/X25519 code.
• The payload is encrypted to the recipient agent via X25519 ECDH + HKDF + an AEAD (e.g. (X)ChaCha20-Poly1305); plaintext payloads never appear in the confidential variant on the wire or at rest.
• The ed25519 agent signature covers a distinct domain-separation tag plus recipient || nonce || sequence || ciphertext_cid, and the AEAD associated-data binds the signature so the two layers cannot be spliced; verify() checks the CID before the signature, mirroring SignedEnvelope.
• A payload survives an untrusted relay unreadable: a test simulates a relay/store-and-forward hop that holds and forwards a confidential envelope and asserts (a) the relay cannot recover the plaintext, (b) the relay can still verify sender authenticity and reject a tampered envelope, and (c) the intended recipient decrypts byte-exact.
• Default behavior unchanged: existing SignedEnvelope::new/verify byte layout, signing tuple, and all existing tests in envelope.rs pass untouched; the direct-LAN QUIC path emits plaintext-payload SignedEnvelope exactly as today.
• Per-agent X25519 encryption key material is defined (derivation or metadata field) and is ed25519-signed/cert-bound so an attacker cannot substitute their own encryption key; a test covers encrypt-to-recipient where the recipient is identified only by Recipient::Direct { agent_fp }.
• The algorithm/version is named in the wire format and a downgrade from confidential to plaintext is rejected (distinct tag enforced).
• Docs record the threat-model delta: what an intermediary learns with vs. without the confidential envelope, and the explicit statement that this is the 1:1 foundation for a later group-session issue.
• Cross-references Agent Mesh should be data agnostic #38 (data-agnostic direction motivates relayed/arbitrary payloads); notes the relationship to the SAS/channel-binding spike in spike(transport): does the handshake expose a transcript hash for SAS binding? #30 (transport-binding vs. payload-encryption are distinct layers).

Relationships

• Blocks feat(bus): Megolm-style group sessions for confidential topic fan-out #45 — group sessions wrap the symmetric group key inside this pairwise encrypt-to-recipient channel.
• Related Agent Mesh should be data agnostic #38 — data-agnostic / arbitrary-binary payloads raise the stakes on payload confidentiality.

---

Meta · risk: high (per repo CLAUDE.md) · follow-up from the matrix-rust-sdk ↔ agent-mesh architectural comparison (matrix-rust-sdk is a reference implementation, not a dependency).

File/line references were drafted against a recent checkout; line numbers are indicative — symbols are authoritative (grep by name). Substance verified against origin/main @ f63c55f.

🤖 Generated with Claude Code

[hartsock]

Securing agent-mesh Payloads: sdiehl/double-ratchet vs. the Real Options

1. Verdict on sdiehl/double-ratchet

No. It's a non-starter as a dependency. sdiehl/double-ratchet is 100% Haskell (Adjoint Inc's ratchet on Hackage), last touched April 2018, and explicitly an educational reference implementation. You cannot consume it from a Rust workspace, it's eight years stale, and it has no audit or production pedigree. As a teaching artifact it's genuinely good — a clean, readable expression of Double Ratchet + X3DH over Curve25519/AES-256/HMAC-SHA256, Apache-2.0, so the license is friendly. Read it to internalize the algorithm. Do not link against it. Everything it teaches, vodozemac ships in Rust, audited.

2. The Real Question (telescope, not the sky)

The repo is the telescope; the sky is confidentiality of agent payloads. The question is not "do we want a Double Ratchet" — it's which confidentiality construction matches agent-mesh's actual message patterns, and which Rust crate realizes it.

Critically: iroh QUIC already gives you forward-secret, authenticated link encryption between two live, connected peers. QUIC mandates TLS 1.3, whose only key exchange is ephemeral (EC)DHE — per-connection forward secrecy and authenticated encryption. So a payload-encryption layer is not there to protect bytes in flight over a live dial — that's already covered. It exists to close the residual gap: confidentiality that must survive any path where the bytes leave the live link —

• a relay that forwards (and could log) the message,
• a store / outbox / feat(bus): sans-IO MeshStore seam for durable replay state + offline outbox #42 durable channel that holds the message at rest,
• any store-and-forward hop where sender and recipient are not simultaneously online.

That residual gap is the design target. It tells you how much machinery you actually need.

3. Does agent-mesh Even Need a Double Ratchet?

Mostly no — and that's the key insight. A full Double Ratchet buys two specific properties across a long-lived, stateful session: forward secrecy (compromise today doesn't decrypt yesterday) and post-compromise security / self-healing (the session recovers future secrecy after a key leak). Those properties are only meaningful if there is a persistent session whose ratchet state advances over many messages.

agent-mesh today is the opposite: ephemeral keys + dial-per-message RPC. Each message is its own short interaction. There is no long-lived session to forward-ratchet, and — importantly — there is no place to persist ratchet state, because the durable-channel store (#42) doesn't exist yet. Forcing a Double Ratchet onto a stateless RPC model means inventing session-state persistence just to satisfy the crypto, which is complexity with no payoff.

For a stateless dial-per-message world, the right primitive is a stateless authenticated sealed-box: a fresh ephemeral X25519 keypair per message → DH against the recipient's static key → derive an AEAD key → encrypt. You get per-message forward secrecy for free (the ephemeral private key is discarded after send) with zero ratchet state to persist. This is the natural fit for #43.

The Double Ratchet earns its complexity in exactly two places:

• Durable 1:1 channels (once feat(bus): sans-IO MeshStore seam for durable replay state + offline outbox #42 lands and there's somewhere to keep ratchet state) — a real session, real PCS payoff.
• The group case (feat(bus): Megolm-style group sessions for confidential topic fan-out #45) — where Megolm is itself a one-way (sender-key) ratchet, giving forward secrecy to fan-out without an N×N pairwise mesh.

4. Recommendation, Tiered

#43 — 1:1 payload encryption (do this now)

Stateless authenticated sealed-box. Concretely, the crypto_box crate (RustCrypto, dual MIT/Apache-2.0) gives you the NaCl box/crypto_box construction directly: ephemeral X25519 (x25519-dalek, BSD-3-Clause) → recipient static X25519 → XChaCha20-Poly1305 AEAD (chacha20poly1305, dual MIT/Apache-2.0), with HKDF-SHA256 (hkdf 0.12, sha2 0.10) for key derivation if you want domain separation. crypto_box pulls in x25519-dalek transitively regardless, so the BSD-3-Clause dependency is unavoidable — and harmless, since BSD-3-Clause is permissive and Apache-2.0-compatible. Prefer XChaCha20-Poly1305 (24-byte random nonce) over ChaCha20-Poly1305 so you never have to track a nonce counter in a stateless model — random nonces are safe at this width.

• Default-OFF, opt-in per the current sign-only posture.
• Encrypt-then-sign (sign the ciphertext envelope, not the plaintext). Recommended because: (a) it preserves agent-mesh's existing trust root — the Ed25519 envelope signature stays the outer layer that relays and the dial layer already validate, so authentication is checkable without decryption and you reject forgeries before spending a decrypt; (b) it avoids the classic surreptitious-forwarding / unknown-key-share pitfalls of sign-then-encrypt where a recipient can strip the inner signature and re-encrypt to a third party. The one caveat of encrypt-then-sign — the signature reveals who sent the ciphertext — is a non-issue here, since agent-mesh envelopes are already signed-and-attributable by design. Bind the recipient identity into the AEAD associated data so a captured ciphertext can't be replayed at a different peer.
• Survives relays / stores / outbox — exactly the residual gap from §2.

Durable 1:1 channels — upgrade path (when #42 lands)

When there's a store to hold session state, upgrade durable channels to a Double Ratchet, and here vodozemac (Olm) is the standout: Apache-2.0 (single license — verified from crates.io and Cargo.toml, not dual; this matches agent-mesh's Apache-2.0 cleanly), pure Rust on the modern dalek/RustCrypto stack, sans-IO with caller-persisted pickling (serde format, encryptable-at-rest with a caller-supplied 32-byte key) — which fits a broker-less mesh where every node owns its own persistence. Same crate gives you #45, so adopting it once covers two issues.

Audit / assurance status (read before shipping): vodozemac was audited by Least Authority (final report 30 March 2022), which raised ~10 findings (8 addressed during the audit). More recently, a Feb 2026 third-party analysis surfaced a High-severity issue: Olm's 3DH accepts all-zero / identity X25519 public keys, yielding a predictable all-zero shared secret — plus a low-severity V2→V1 MAC-downgrade and several minor issues. Matrix considers the all-zero issue mitigated by their authenticated key-distribution model (signed identity / pre-keys verified before session setup) and is adding an explicit zero-check as defence-in-depth. Pin a vodozemac version that includes the post-disclosure hardening (latest is 0.10.0, MSRV 1.85.0; confirm it carries the zero-check fix before production). Note this reinforces the option-B recommendation below: signing published DH keys with the Ed25519 identity is precisely the authenticated-key-distribution posture that neutralizes the all-zero finding.

#45 — group / topic fan-out

vodozemac Megolm (OutboundGroupSession / InboundGroupSession), the sender-key ratchet: encrypt the payload once with the group session, then distribute the Megolm session key per-recipient over the #43 sealed-box channel. This is the encrypt-once / N-key-shares pattern Matrix uses at scale — it avoids re-encrypting the payload per member while still giving forward secrecy via the one-way ratchet. The sealed-box from #43 is the key-distribution transport; Megolm is the bulk-payload cipher.

5. The Ed25519 vs. X25519 Gotcha

agent-mesh identities are Ed25519 (signing on the Edwards curve). All the DH above needs X25519 (Montgomery). They are the same underlying curve (Curve25519) but different key encodings and different operations — you cannot just hand an Ed25519 key to x25519-dalek. Two options:

• (A) Convert Ed25519 → X25519 via the standard birational map (curve25519-dalek exposes to_montgomery on the Edwards point; the secret side maps the clamped scalar). One key to manage, no extra material to publish.
• (B) Mint a separate X25519 DH keypair and publish it in the node's cert/metadata, signed by the Ed25519 identity (the Matrix device-key pattern).

Recommend (B). Reusing one keypair across two algorithms (signing and DH) violates key separation — it widens the attack surface (a flaw or oracle in one protocol can leak material usable in the other). The per-primitive security proofs for Ed25519 and X25519 are stated for non-shared keys; joint security has been proven only under specific constructions (eprint 2021/509, an HKDF-extract-like KEM), so reuse is not unconditionally broken — it's simply not covered by the individual-primitive proofs, which makes key separation the conservative default. Minting a dedicated X25519 DH key and signing it with the Ed25519 identity gives you the same single trust root (peers verify the DH key against the existing signed-envelope identity) without the cross-protocol reuse hazard. The cost is one extra public key in the metadata — cheap.

Note this is moot on the vodozemac path: vodozemac/Olm manages its own Curve25519 (X25519) identity, one-time, and fallback keys internally — it neither derives from nor reuses agent-mesh's Ed25519 key. You'd keep Ed25519 for envelope signing and sign vodozemac's published Curve25519 keys with it to anchor trust. So option (B) is already the shape of the vodozemac integration; adopting (B) for #43 keeps both paths consistent.

6. Bottom Line

• feat(protocol): add optional encrypt-to-recipient envelope seam (today: sign-only) #43 (1:1, now): ship a stateless crypto_box sealed-box (ephemeral X25519 + XChaCha20-Poly1305 + HKDF), default-off, encrypt-then-sign, recipient bound into the AEAD AD — per-message forward secrecy, no state to persist, survives relays and stores.
• feat(bus): sans-IO MeshStore seam for durable replay state + offline outbox #42 / feat(bus): Megolm-style group sessions for confidential topic fan-out #45 (later): adopt vodozemac (pin ≥ the post-Feb-2026 all-zero-key fix; latest 0.10.0) — Olm for durable forward-secret 1:1 channels once there's a store, Megolm for group fan-out (encrypt once, ship keys per-recipient over the feat(protocol): add optional encrypt-to-recipient envelope seam (today: sign-only) #43 channel); Apache-2.0, audited by Least Authority (2022), manages its own DH keys.
• Identity: mint a dedicated, Ed25519-signed X25519 DH key rather than reusing the signing key — and that's exactly how the vodozemac path already works, and exactly the authenticated key distribution that mitigates the Olm all-zero-key finding.
• sdiehl/double-ratchet: a fine Haskell teaching reference for the algorithm — read it, learn from it, do not depend on it. (Likewise, the Rust double-ratchet crate (sebastianv89) is on crates.io but is a single 2019-vintage v0.1.0, unaudited and effectively abandoned — skip it on maturity grounds.)

---

Provenance. Design note evaluating a request to use sdiehl/double-ratchet for payload confidentiality. The recommendation was drafted by a multi-agent research workflow and adversarially fact-checked: licenses, vodozemac audit history (incl. the Feb-2026 all-zero-key finding), and the Ed25519→X25519 caveat were all verified against crates.io / the upstream repos. agent-mesh's own specifics it relies on — Ed25519 identities (user_key.rs), sign-only envelopes (envelope.rs, zero encryption primitives in the protocol crate), iroh QUIC tls-ring link encryption, and dial-per-message bus dispatch — were verified against origin/main @ f63c55f. Confirm the exact patched vodozemac version before implementation.

🤖 Generated with Claude Code