Repository navigation
Implement Iroh mailbox transport with explicit relay policy #4633
Description
Agent pickup triage
Category: ready. This classifies the next task, not completion or a verified current-source pass.
Next bounded step: Confirm #4632/#4628 landed API shapes, then implement the Iroh adapter against the canonical envelope and explicit relay policy; no guest-network fallback.
Read the linked handoff and coordinate any active owner before implementation. Preserve the original acceptance criteria below; this triage grants no spending, credentials, publication, host reconfiguration, or landing authority.
Parent: #4622
Outcome
Implement Iroh as the first cross-host mailbox byte transport while preserving MVM-owned identity, authorization, encryption, delivery semantics, and audit evidence.
This is a message-envelope transport, not a guest NIC, host bridge, general IP overlay, FlowMux replacement, or implementation of #4607.
Iroh transports the canonical encoded MVM envelope unchanged. Neither Iroh nor mvmd defines a second mailbox envelope, signature domain, ACK format, or payload schema.
Scope
- Direct local/LAN and NAT-traversed connections.
- Customer-configured relays as the no-account relay path.
- Public Iroh relay infrastructure only through explicit configuration.
- Binding between rotatable Iroh endpoint identity and stable MVM identity, tenant, assurance tier, policy epoch, and expiry.
- Connection reuse, reconnection, bounded concurrent streams, path classification, resource limits, and clean shutdown.
- Ciphertext-only relay behavior and payload-free audit events.
Acceptance criteria
- Two hosts exchange mailbox envelopes directly and through a customer-configured relay using the same mailbox contract.
- Public relay use is disabled by default and cannot occur as a silent fallback.
- Wrong, expired, revoked, stale-epoch, or cross-tenant transport bindings are rejected.
- Iroh or relay compromise cannot forge a mailbox sender, alter accepted content, or manufacture a destination receipt.
- Resource limits cover peers, streams, queued bytes, retries, reconnect work, and relay usage.
- Tests cover direct, relay, reconnect, partition, identity rotation, revocation, tamper, overload, and shutdown paths.
- The implementation exposes no packet-forwarding or guest-network fallback when mailbox delivery is unavailable.
- Direct and relayed paths interoperate with the standalone local mailbox service using the same
mvm-contractfixtures, with nomvmd-typesdependency in the MVM transport implementation.
Activity
auser commentedon Nov 2, 2026
Scoped reconciliation against current
main(662176d74eda5351be5d5be689370d6527475a05) supports checking only acceptance boxes 2, 4, and 7:3104a12c5b071a6851323fa8115d2afaf3f0bb8b) makesCustomerRelaysthe default and requires explicitPublicRelaysAllowed. Overlay filtering and regression tests enforce default public-relay exclusion, explicit opt-in, and direct-only behavior.0c233d22aef392371631a915a4180ec17d4467c7) sender-signs messages before AEAD encryption, verifies sender and content on open, and requires destination-signed receipts. Wrong-sender, ciphertext/routing-tamper, and receipt-tamper tests reject forged or altered data. #4698 (02bf0c3a3ad5a0f603b75d88fe04ccf022bd3a1c) preserves the separate transport/authority boundary.02bf0c3a3ad5a0f603b75d88fe04ccf022bd3a1c) exposes only private, authorized mailbox frames, not arbitrary byte writes or packet forwarding, and returnsAllRoutesFailedwhen authorized mailbox routes are exhausted. ADR-057 explicitly keeps guest networking and packet forwarding outside mailbox authority.Box 3 was deliberately excluded. No other acceptance row was assessed or checked. This reconciliation used static source and outcome-test inspection; no new tests were run.
fix(mailbox): reject revoked transport bindings (tinylabscom#5034)
auser commentedon Nov 9, 2026
Cross-host carrier boundary requested by the MVMD networking work
At MVM
63e751d4,mvm-core::mailbox::transport::AuthorizedMailboxFrameexposes only canonical encoded envelope bytes, andPeerChannel::try_sendreturns only transport success/failure (source). The current local frame/service instead requires the signed capability and offers an in-memoryResult<(), Refusal>, not durable destination acceptance (frame, admission). #4629 and #4630 remain open. An Iroh connection, authenticated route hint, or successfultry_sendmust not be calledaccepted_durableor interpreted as ACK.Proposed MVM-owned interface to review with #4629/#4630 owners (not an API already implemented): authorize outbound exact encoded canonical envelope together with signed Send capability and the authenticated tenant/domain/recipient/mailbox/epoch route binding; bound all fields/frames before a peer carrier can transmit. At the destination, MVM's mailbox authority verifies capability signature/scope, sender, tenant, recipient, boot/epoch, expiry/replay, message commitment and route binding before committing encrypted canonical envelope + dedup identity to the MVM-owned durable mailbox journal. Only that destination authority signs an acceptance receipt after the commit; transport returns a path outcome separately, and receipt verification precedes user-visible publication. Full/expired/refused/duplicate/unavailable and lost-receipt
unknownremain distinct. Do not share per-host signer seeds with peers or MVMD; distribute only scoped public recipient/route material through authorized enrollment. Keep peer/stream/byte/attempt quotas and direct/customer-relay defaults with public relay opt-in.Order: #4628 canonical contract + #4632 transport seam → #4629 local service/inbound gate → #4630 durable journal/dedup/receipt → enable #4633 cross-host publication and MVMD #254 opaque discovery/routing. The byte-transport adapter can be developed/tested independently before #4630, but must remain unserved/unadvertised as durable delivery until the destination receipt path is real. #5260 software-first typed reports are the current local priority; #5259 optional hardware tier is separate. #5057 still needs the active #4629 contributor's exact source pin and patch ownership. No acceptance box is checked by this design note.
auser commentedon Nov 9, 2026
Ownership correction to my preceding cross-host seam comment: the MVMD networking work reports an explicit user decision that MVM owns canonical mailbox DTOs/authorization/local admission/storage, while MVMD owns the concrete Iroh/Hydro host-to-host transport adapter behind the MVM-owned authorization/receipt contract. Its ADR-057 update is unmerged and in a separate worktree (
mvm@deb9588a85fab55244057259dd17ccc27c43ea00); my attached MVM checkout was63e751d4. Therefore this issue body and my prior phrase 'MVM-owned Iroh adapter' describe a tracker/ADR scope conflict, not a settled implementation assignment. Reconcile #4633, ADR-057 and MVMD #254 after reviewing the actual proposed diff/pin; do not merge or relabel anything solely from this comment. The security/data boundary is unchanged: transport success is not destination acceptance; MVM's inbound gate and #4630 durable commit must yield a verifiable destination-signed receipt before enablingmvmd/mailbox/1. MVMD cannot mint MVM authority, decrypt payloads, invent another envelope or queue, or become required for same-host messaging. Keep #4633 implementation boxes unchecked until reviewed evidence.