I3189 — Two nodes with no direct path cooperate through a trusted hub that relays their authenticated frames

✕BLOCKED wave 2 · p3 · deep-work profile · parallel safe

Part of mesh-connectivity — Trusted nodes connect across NAT through proven transports, and every surface says which path.

Objective

Let a hub both nodes trust carry link frames between them when neither can dial the other, with the frames still signed end to end by the existing link keys, a byte and rate bound per relayed link, and a direct upgrade attempted in the background and taken when it succeeds.

Why

Relay-first with direct upgrade was the 10-12 phase-1 vertical and the 10-16 NAT design; hubs already exist (docs/MESH.md) and only register. A relay through an existing trusted node avoids a new STUN/TURN service. The link is dialer-initiated request-answer (link.rs:7-21), so a relay for two undialable nodes needs a reverse channel the protocol lacks. Confidentiality is the network's (docs/MESH.md:189), so the relay inherits case 491's private-hub rule. Released-claim replication is I2825, in flight on branch docs/a-released-claim-reaches-every-runtime with no record yet. This issue waits for it, and the next planner adds depends_on I2825 once its record exists. Proposed in ADR 0202 (The mesh routes work to an identity, never an address, and selects among proven transports instead of implementing NAT traversal) (proposed; it carries no authority until the owner accepts it). Sources: chatgpt-majordomus:c237#4, chatgpt-majordomus:c240#5.

Current state

Verified: rendezvous hubs register and answer lookups; nothing relays.

Desired state

A relayed link is a link like any other, marked relayed in its path record.

Scope

• apps/majordomus-cli/src/mesh/rendezvous.rs
• apps/majordomus-cli/src/mesh/link.rs
• docs/MESH.md
• apps/majordomus-cli/src/capability/builtin/mesh.rs
• apps/majordomus-cli/src/mesh/protocol.rs
• apps/majordomus-cli/src/mesh/testing.rs
• test/cases/491_the_mesh_is_on_here.sh

Out of scope

• libp2p, QUIC or ICE adoption (a later decision)
• Relaying for an untrusted node
• In-crate transport confidentiality (Noise over the link keys, or TLS): it would amend ADR 0032, ADR 0067 and docs/MESH.md:189 and is the owner's decision
• A relay hub on a plain-http public address

Dependencies

• I3187✕BLOCKED A link names the endpoint candidates it tried, the one it chose and why

What waits on this

• I3190✕BLOCKED The mesh lab proves links behind NAT, with the relay, a hub outage and an address change

Acceptance criteria

• A relayed link carries claims and handovers both ways
• A relay refuses frames beyond its bound and says so
• A relay hub is one case 491 admits unchanged (private or overlay endpoint), or one reached through an encrypted ingress the deployment provides (ADR 0204); no relayed frame crosses a public network in cleartext
• The answerer reaches the hub through an outbound mailbox poll, and the hub queues frames per target runtime under a byte and count bound; the routes are declared once as capabilities and projected by majordomus generate
• An in-process transport test where neither runtime accepts an inbound request completes Hello and Sync through the relay, with the skew window and single-use nonce holding under the polling delay
• A claim released on one side of a relayed link is no longer held on the other side
• This issue writes apps/majordomus-cli/tests/mesh_relay.rs and, in the same change, records it as the test ref of criterion relay-when-no-direct-path (evidence: test)

Validation

• majordomus plan validate
• cargo test --lib mesh::rendezvous
• bash test/run.sh 491_the_mesh_is_on_here

Evidence required

• test_a_hub_relays_a_link
• test_mesh_relay_links_two_undialable_nodes

Evidence

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

Timeline

started

—

verified

—

completed

—

Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.

Canonical record: .ai/repo/project/issues/I3189.yaml. Read it back with majordomus plan show I3189.