Skip to content

feat(nfxd): --mesh-public, the mesh endpoint's public address behind a DNAT (#71) - #86

Closed
SovereignTechnology wants to merge 7 commits into
mainfrom
nfxd/mesh-public
Closed

SovereignTechnology wants to merge 7 commits into
mainfrom
nfxd/mesh-public

Conversation

@SovereignTechnology

@SovereignTechnology SovereignTechnology commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Part of #71.

Why

nfxd's mesh endpoint (#82) is a full-ICE str0m peer signaled over Nostr (NFX-10 §6). Its candidates are its host address, server-reflexive mappings from --mesh-stun, and a gateway port mapping. A seeder in a VM behind a DNAT gets none of the useful ones:

  • No srflx: when the only STUN server is the node's own --stun on the same public address, asking it would take a UDP hairpin, so STUN cannot report the public address.
  • No portmapper: a guest has no gateway that maps ports.

So the endpoint offers only its private address and browsers cannot reach it, even with the public UDP port forwarded. The ICE-lite bridge already solved this with --bridge-public (N2): the advertised candidate is the public address, and received datagrams are presented to str0m as destined to it.

What

nfxd run --mesh-public <ip:port> (needs --mesh-relay, and --mesh-bind with a fixed port, the one the DNAT forwards to):

  • Validated before anything binds: a public unicast address (nfx_node::node::is_public, fail-closed: private, shared, loopback, link-local, documentation, multicast, port 0 and so on are refused), of --mesh-bind's family.
  • Candidates: the public address is the first host candidate. With it set, no candidate whose address is not public is offered, as --iroh-external filters iroh's direct addresses: not the bound address behind the DNAT, nor a private STUN or gateway mapping. A public bound address is still offered.
  • STUN stays optional. With both, both candidates are kept; a srflx equal to the public address is offered once. Server-reflexive candidates take the public address as their base, so str0m's foundation hash (which takes in the base) is never derived from the private address, and str0m writes no real raddr.
  • Arrival: every datagram on the bound socket is presented to str0m as sent to the public address (Receive.destination), as the bridge does, so connectivity checks to it are accepted.
  • Output: a mesh public: udp <ip:port> line at start; the status line's candidate list starts with host <public>.
  • nfx_node::mesh::MeshConfig::public and Mesh::public_addr() in the library. The library checks only that the address is dialable, of the bind's family, and one str0m accepts as a host candidate; whether it is public is the caller's check (nfxd makes it), so tests can use loopback and documentation addresses.

Docs: the usage text, the nfxd module docs, the README (with an example), and a one-sentence non-normative note in NFX-10 §6 (plus its changelog line). Nothing changes on the wire.

Tests

  • nfx-node unit (mesh/tests.rs):

    • the candidate set without and with a public address: the private bind left out; STUN mappings deduplicated, private and special-purpose ones dropped, public ones kept; a public bind kept;
    • the offer and the answer SDPs name only those addresses, with no private one anywhere in them;
    • srflx bases are the public address;
    • a simulated punch: a node behind a DNAT, told its public address, connects with a browser behind a consistent NAT. Control: the same node not told it does not connect.
  • nfx-node integration (tests/mesh.rs): the endpoint bound on loopback and told a public address. The str0m browser peer reaches it only through a DNAT in the test: datagrams to the public address go to the bind with the browser's own source, and replies come back as from the public address, only after the browser has sent there. Through the relay, in both glare directions, the browser:

    • finds the endpoint by room;
    • checks that the endpoint's SDP names only the public address;
    • opens the data channel;
    • fetches segment 0 and checks its sha256.

    Settings the library refuses are tested too: wrong family, port 0, unspecified, multicast, broadcast, link-local.

  • nfxd:

    • --mesh-public parsing (form, given twice, missing value);
    • every refusal: needs --mesh-relay, needs --mesh-bind, port 0 bind, private, documentation, multicast, port 0, wrong family;
    • a daemon started with --mesh-public offers exactly host <public>.

The money crates and Cargo.lock are untouched.

Merge

One commit; squash.

Summary by CodeRabbit

  • New Features
    • Mesh endpoints can now advertise a configured public address when operating behind DNAT, enabling peers to connect through that address.
    • Added the --mesh-public option for setting the address. It requires a fixed mesh bind port and a public unicast address matching the bind address family.
    • When configured, the public address is advertised as a host candidate, and non-public candidates are excluded.
  • Documentation
    • Added setup guidance for DNAT configurations and clarified how public addresses appear in mesh status and signaling.

…a DNAT (#71)

A seeder in a VM behind a DNAT gets no useful mesh candidate: STUN cannot
report its public address when the STUN server is its own (that would take
a UDP hairpin), and a guest has no gateway to map a port. So it offered only
its private address, and browsers could not reach it.

--mesh-public <ip:port> names the DNAT's public address, as --bridge-public
does for the ICE-lite bridge:

- It needs --mesh-relay, and --mesh-bind with a fixed port (the one the
  DNAT forwards to). It must be a public unicast address (node::is_public,
  fail-closed) of --mesh-bind's family.
- It is the first host candidate. Every datagram on the bound socket is
  presented to str0m as sent to it (Receive.destination), so checks
  addressed to the public address are accepted.
- With it set, no candidate whose address is not public is offered, as
  --iroh-external filters iroh's: not the bound address behind the DNAT,
  nor a private STUN or gateway mapping. A public bound address is kept.
- --mesh-stun stays optional: both candidates are kept, and a srflx equal
  to the public address is offered once. Server-reflexive candidates take
  the public address as their base, so str0m's foundation hash never
  derives from the private one.
- nfxd prints "mesh public: udp <ip:port>" at start, and the status line's
  candidates begin with it.

The library takes it as MeshConfig::public (dialable, the bind's family,
a valid str0m host candidate), with Mesh::public_addr().

Tests:
- the candidate set and the SDPs with and without it;
- a simulated DNAT punch, and its control;
- a loopback integration test where a str0m browser reaches the endpoint
  only through a DNAT in the test and fetches segment 0 (sha256 checked),
  in both glare directions;
- the library's and nfxd's refusals, flag parsing, and a daemon offering
  exactly the public candidate.

README and usage text, plus a one-sentence non-normative note in NFX-10 §6.
Nothing changes on the wire. Cargo.lock and the money crates are untouched.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters: 2

  • crates/Cargo.lock is excluded by !**/*.lock
  • crates/desktop/Cargo.lock is excluded by !**/*.lock

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 29109bf0-f9f4-4485-bb36-ce2e8b0249d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The mesh endpoint can now use a configured public DNAT address as a host candidate. Startup validates the address and its relationship to the bind address. The daemon and CLI expose the setting, and tests cover candidate selection, datagram handling, and connectivity through DNAT.

Changes: Mesh DNAT address support

Layer / File(s) Summary
Mesh public address and candidate flow
crates/nfx-node/src/mesh/mod.rs, crates/nfx-node/src/mesh/tests.rs
MeshConfig accepts an optional public address. Startup validates it, candidate gathering filters candidates when it is configured, and received datagrams use it as their arrival address. Mesh tests cover candidate selection and ICE connectivity through DNAT.
Daemon configuration and CLI
crates/nfxd/src/daemon.rs, crates/nfxd/src/main.rs, crates/nfxd/tests/daemon.rs, README.md
The daemon and CLI accept and validate mesh_public, pass it to the mesh, and report the resolved address. Tests cover parsing, startup validation, and the advertised host candidate. The README documents DNAT setup.
DNAT integration tests and protocol description
crates/nfx-node/tests/mesh.rs, spec/nfx-10-web.md
The browser test simulator models DNAT forwarding and tests both negotiation roles with and without a configured public address. The protocol text describes the DNAT host-candidate case and states that the wire protocol is unchanged.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Mesh
  participant Browser
  participant Dnat
  participant Rtc
  Mesh->>Browser: Offer public host candidate in SDP
  Browser->>Dnat: Route datagram to public address
  Dnat->>Mesh: Forward datagram to bound socket
  Mesh->>Rtc: Parse datagram using public arrival address
Loading
Merge Risk: Minimal · up to e8b54

Merge Risk: ⚪ Minimal · up to e8b54

This adds an opt-in --mesh-public option so a node behind DNAT can advertise its forwarded public address. Behavior without the option is unchanged, and the new validation and tests cover the intended paths. No blocking issue was found; setups that forward a public port below 1024 may still fail to connect, so a forwarded port of 1024 or higher is the safer choice.

Security architecture risk: Minimal · up to 6a247

The public-address option is validated before startup and consistently applied to candidate advertisement and receive handling. The inspected change establishes no introduced security-control bypass, persistent-state hazard, or weakened cleanup guarantee.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The intended exposure change is public reachability of a configured mesh endpoint across its joined rendition rooms. Remote room participants can negotiate using the advertised public address; received UDP packets still require an existing accepting RTC link rather than creating a room or connection directly.

Trust Boundaries and Controls

  • observed — The public address is trusted operator configuration. nfxd enforces public-unicast policy before its binding phase and passes the validated value to Mesh::start. Direct library callers receive dialability and family checks, but remain responsible for public-unicast validation.
  • observed — The destination substitution preserves the received source address. Signaling still selects a joined room and opens the session payload; answers remain bound to the sender, room and pending offer. Remote-candidate filtering remains based on the actual socket scope, including its loopback restriction.

Resilience and Maintainability Implications

  • inferred — The added address has no independent persistent resource lifecycle. The event loop serializes mapping updates and candidate generation reapplies filtering and deduplication. Existing timeout and shutdown paths still expire failed connections, close links and clear rooms; the new configuration adds no separate rollback or cleanup step.
Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: a new --mesh-public option in nfxd that sets the mesh endpoint's public address when it sits behind DNAT. The changeset matches this. It adds the flag in the CLI, da…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: a new --mesh-public option in nfxd that sets the mesh endpoint's public address when it sits behind DNAT. The changeset matches this. It adds the flag in the CLI, daemon config, and MeshConfig. It also adds candidate gathering changes, validation, tests, and docs. The title uses the conventional feat(nfxd) prefix and includes the PR number. It is concise and specific.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: acbae517-91af-460e-886f-5fae8d4c703a
Commits

Reviewing files that changed from the base of the PR and between b5fe5e4 and 6a247a1.

Files selected for processing: 8

  • README.md
  • crates/nfx-node/src/mesh/mod.rs
  • crates/nfx-node/src/mesh/tests.rs
  • crates/nfx-node/tests/mesh.rs
  • crates/nfxd/src/daemon.rs
  • crates/nfxd/src/main.rs
  • crates/nfxd/tests/daemon.rs
  • spec/nfx-10-web.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

@sovtechpro

sovtechpro Bot commented Nov 16, 2026

Copy link
Copy Markdown

Adds an opt-in --mesh-public DNAT path with startup validation, public ICE candidate filtering/deduplication, and matching receive-destination handling in the mesh library and daemon.
The SDP/NAT unit tests and both relay/glare integration paths cover the main behavior; nfxd tests cover parsing, refusals, and advertised status.

Risks:

  • Security/privacy: nfxd rejects non-public addresses before startup (crates/nfxd/src/daemon.rs:1381-1409), and candidate generation excludes private and special-purpose mappings (crates/nfx-node/src/mesh/mod.rs:699-727). The library itself deliberately checks only dialability/family and leaves the public-address policy to its caller (crates/nfx-node/src/mesh/mod.rs:323-336), so that documented trust boundary matters for other consumers.
  • Compatibility: no wire-format change and the feature defaults off. External users with exhaustive MeshConfig literals will need the new field (crates/nfx-node/src/mesh/mod.rs:149-162), and the local-candidate cap rises from six to seven even without public (crates/nfx-node/src/mesh/mod.rs:124-126), a small bounded change only for nodes with many mappings.
  • Test coverage: public+STUN/public-bind combinations are covered at candidate/SDP level, while end-to-end DNAT tests use the single primary host candidate (crates/nfx-node/src/mesh/tests.rs:485-598, crates/nfx-node/tests/mesh.rs:370-424). Multi-candidate failover therefore retains some interoperability risk, but I found no demonstrated defect.

Looks fine to merge

@sovtechpro sovtechpro Bot added the size/L Lines changed by this pull request: L (sovtechpro[bot]) label Nov 16, 2026
RUSTSEC-2026-0486 (published 2026-11-16) marks rustix 1.1.5 unsound: its xattr functions mark unwritten
bytes initialized when given a zero-length buffer. nfx reaches rustix through iroh-blobs > reflink-copy
and never calls the xattr functions, but cargo deny fails every CI check on the advisory. Fixed in 1.1.6.

crates/desktop/Cargo.lock also gains cipher 0.5.2 and inout 0.2.6: nfx-proto has needed them since #75
(chacha20 0.10 for NIP-44), and the desktop workspace's lock had not been refreshed. No manifest changes;
the money crates' locked closure (crates/ci/locked-compiled.txt) has no rustix and is unchanged.
@sovtechpro

sovtechpro Bot commented Nov 16, 2026

Copy link
Copy Markdown

CI diagnosis — run 43788310088

  • Failing job/step: check / check (job 133040809778). The lock job passed.

  • Root cause: cargo-deny rejects the locked rustix 1.1.5 under RUSTSEC-2026-0486. Its xattr functions can mark unwritten bytes as initialized for zero-length buffers, causing undefined behavior reachable from safe code. The dependency path is nfxd → nfx-node 0.1.1 → iroh-blobs 0.103.1 → reflink-copy 0.1.30 → rustix 1.1.5.

  • Evidence: crates/Cargo.lock:343:

    error[unsound]: xattr functions mark unwritten bytes as initialized when given a zero-length buffer

    343 │ rustix 1.1.5 registry+https://github.com/rust-lang/crates.io-index

    ├ ID: RUSTSEC-2026-0486

    ├ Solution: Upgrade to >=1.1.6 (try cargo update -p rustix)

    advisories FAILED, bans ok, licenses ok, sources ok

  • Smallest fix: From crates/, run cargo update -p rustix, confirm the lockfile selects rustix 1.1.6 or newer, and commit the resulting crates/Cargo.lock change. The duplicate-crate messages are warnings, not the cause of this failure.

@sovtechpro

sovtechpro Bot commented Nov 16, 2026

Copy link
Copy Markdown

CI diagnosis for run 43793965522

  • Failing jobs/steps: lock / step 4 lock and check / step 5 check.
  • Root cause: crates/Cargo.lock changes money-crate transitive references from windows-sys 0.61.2 to 0.52.0 (for example at crates/Cargo.lock:1354) and updates rustix from 1.1.5 to 1.1.6 at crates/Cargo.lock:4220, even though this PR changes no Cargo manifest. The resolved money-dependency graph therefore no longer matches its checked-in pins; both jobs fail deterministically at the same guard, not in tests.

Both logs report:

locked paths: 44 guarded files and sections match their pins
locked paths: what the money crates are built from differs from its pins:
- money-dep windows-sys 0.61.2 ...
+ money-dep windows-sys 0.52.0 ...
+ money-dep windows-sys 0.61.2 ...
+ money-dep windows-targets 0.52.6 ...

The remaining additions are the windows_* 0.52.6 target packages, and both steps exit with code 1.

Smallest fix: revert the unrelated crates/Cargo.lock and crates/desktop/Cargo.lock edits to their base-branch versions; the mesh-public source changes do not require a dependency update. If those lockfile changes are intentional, instead regenerate them from the intended manifests and update the money-dependency pins in the same change.

@sovtechpro

sovtechpro Bot commented Nov 16, 2026

Copy link
Copy Markdown

CI diagnosis — run 43793960624

  • Failing jobs/steps: lock / step 4 lock and check / step 5 check.
  • Root cause: The rustix 1.1.5 → 1.1.6 lockfile update also rewired four entries from windows-sys 0.61.2 to windows-sys 0.52.0 (crates/Cargo.lock:1354, :4230, :4320, and :5716). That changed the money crates’ resolved dependency graph without updating its dependency pins; all 44 guarded files and sections match, so this is deterministic pin drift, not a flaky or infrastructural failure.

Both logs report (long package lines abbreviated):

locked paths: 44 guarded files and sections match their pins
locked paths: what the money crates are built from differs from its pins:
- money-dep windows-sys 0.61.2 …
+ money-dep windows-sys 0.52.0 …
+ money-dep windows-sys 0.61.2 …
+ money-dep windows-targets 0.52.6 …

The remaining additions are eight windows_* 0.52.6 architecture packages, after which both steps exit 1. crates/Cargo.lock:4222 confirms the intended rustix 1.1.6 update; the check job’s Cargo-deny checks and WASM tests had already passed.

Smallest fix: Keep the rustix 1.1.6 security update but restore the four previous windows-sys 0.61.2 references if that Windows-dependency churn was accidental, then verify with cargo metadata --locked and the repository’s locked-paths check. If rustix 1.1.6 requires the new Windows resolution, keep the lockfile and update the corresponding money-dependency pins in the same change instead. Do not wholesale revert to rustix 1.1.5: that would reintroduce the earlier RUSTSEC-2026-0486 failure.

…2), so the money crates' closure is unchanged

cargo update -p rustix --precise 1.1.6 had moved rustix's windows-sys to 0.52.0, which brought windows-sys 0.52 and
windows-targets 0.52.6 into what the money crates are built from, and the lock job refused it. Both locks are
validated with cargo metadata --locked --offline.
…sktop lock's missing cipher/inout)

093f469 still left errno 0.3.14, rustls-platform-verifier 0.7.0 and winapi-util 0.1.11 on windows-sys 0.52.0 (moved
by the same cargo update), so the money crates' closure still differed. Now crates/Cargo.lock differs from main in
rustix's version and checksum only, and crates/desktop/Cargo.lock adds cipher 0.5.2 and inout 0.2.6 and the same
rustix bump, with no windows-sys line changed. Both validated with cargo metadata --locked --offline.
@sovtechpro

sovtechpro Bot commented Nov 16, 2026

Copy link
Copy Markdown

CI diagnosis — run 43799892042

  • Failing jobs/steps: check / step 5 check and lock / step 4 lock.
  • Root cause: The rustix 1.1.5 → 1.1.6 security update also rewired four lockfile references from windows-sys 0.61.2 to 0.52.0 (crates/Cargo.lock:1354, :4230, :4320, and :5716). The money crates’ resolved dependency graph therefore differs from its checked-in pins; both jobs fail deterministically at that guard, not in compilation or tests.

Both logs report (long package fields abbreviated):

locked paths: 44 guarded files and sections match their pins
locked paths: what the money crates are built from differs from its pins:
- money-dep windows-sys 0.61.2 …
+ money-dep windows-sys 0.52.0 …
+ money-dep windows-sys 0.61.2 …
+ money-dep windows-targets 0.52.6 …

The remaining additions are the eight windows_* 0.52.6 architecture packages, followed by Process completed with exit code 1. The check job’s Cargo-deny checks and WASM tests had already passed.

Smallest fix: Keep rustix 1.1.6; reverting it would reintroduce RUSTSEC-2026-0486. Restore the four previous windows-sys 0.61.2 references if that Windows churn was accidental, then run cargo metadata --locked and the repository’s locked-paths check. If the new Windows resolution is intentional, keep it and update the corresponding money-dependency pins in the same change instead.

SovereignTechnology added a commit that referenced this pull request Nov 16, 2026
…a DNAT (#71) (#86)

A seeder in a VM behind a DNAT gets no useful mesh candidate: STUN cannot
report its public address when the STUN server is its own (that would take
a UDP hairpin), and a guest has no gateway to map a port. So it offered only
its private address, and browsers could not reach it.

--mesh-public <ip:port> names the DNAT's public address, as --bridge-public
does for the ICE-lite bridge:

- It needs --mesh-relay, and --mesh-bind with a fixed port (the one the
  DNAT forwards to). It must be a public unicast address (node::is_public,
  fail-closed) of --mesh-bind's family.
- It is the first host candidate. Every datagram on the bound socket is
  presented to str0m as sent to it (Receive.destination), so checks
  addressed to the public address are accepted.
- With it set, no candidate whose address is not public is offered, as
  --iroh-external filters iroh's: not the bound address behind the DNAT,
  nor a private STUN or gateway mapping. A public bound address is kept.
- --mesh-stun stays optional: both candidates are kept, and a srflx equal
  to the public address is offered once. Server-reflexive candidates take
  the public address as their base, so str0m's foundation hash never
  derives from the private one.
- nfxd prints "mesh public: udp <ip:port>" at start, and the status line's
  candidates begin with it.

The library takes it as MeshConfig::public (dialable, the bind's family,
a valid str0m host candidate), with Mesh::public_addr().

Tests:
- the candidate set and the SDPs with and without it;
- a simulated DNAT punch, and its control;
- a loopback integration test where a str0m browser reaches the endpoint
  only through a DNAT in the test and fetches segment 0 (sha256 checked),
  in both glare directions;
- the library's and nfxd's refusals, flag parsing, and a daemon offering
  exactly the public candidate.

README and usage text, plus a one-sentence non-normative note in NFX-10 §6.
Nothing changes on the wire. Cargo.lock and the money crates are untouched.
@SovereignTechnology

Copy link
Copy Markdown
Owner Author

Squash-merged as 2df9bc4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/L Lines changed by this pull request: L (sovtechpro[bot])

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant