[mickvandijke]

Browsers reach a node only through its WebRTC Direct endpoint. A wildcard listener binds an OS-chosen port and advertises the native view's IP with it, but only the native QUIC endpoint asks the router for a UPnP port mapping. Behind a home router the browser port is never forwarded: native clients reach the node (directly or through a MASQUE relay), browsers cannot.

This is why the browser SDK fails to download chunks the native client fetches fine (ant-browser-sdk#10). A census of 802 mainnet nodes' WebRTC endpoints, dialled from Chromium with a 9 s ICE budget, twice each, found 51% never answer. In that issue all nine nearest holders of each failing chunk are among them.

What changes

• A listener that chooses its own address (wildcard IPv4 bind, no --webrtc-direct-advertised-addr) starts saorsa-transport's UpnpMappingService for its port. This is the same best-effort service the native QUIC endpoint already uses. A development-mode node, whose native endpoint is loopback-only, keeps its loopback browser endpoint and never contacts the gateway. An IPv6 listener isn't mapped either, because the service maps IPv4 only.
• While the router holds the mapping, it is advertised before the native view. The service asks for the listener's own port first, so the advertised port usually stays the same. Without a router, or when it refuses (UPnP off, non-public external IP, CGNAT), or after the lease is lost, publication is exactly as before. The existing 1 s refresh picks up each change.
• An endpoint only the mapping reached (the native view yields no address, or a different one) is withdrawn when the mapping ends and nothing replaces it: from HELLO, the in-process catalog and the DHT record first, then the endpoint file. A file error cannot keep the endpoint advertised, and the node retries the file on each refresh until it is gone. An endpoint the native view still yields stays published, as before.
• The published endpoint records where its address came from (operator, explicit bind, gateway mapping or native view), the way saorsa-transport tags each native candidate with its source. Only an endpoint whose source is the mapping is withdrawn; a withdrawal that is still waiting on the file is its own state.
• Graceful shutdown removes the mapping; after a crash its one-hour lease expires.
• An explicit bind IP or advertised address is never mapped, so devnets (which always set an advertised address) and operator-configured nodes are unaffected.

Companion PR in ant-client: ant node add --webrtc-port gives each node a fixed browser port operators can forward by hand when UPnP isn't available (WithAutonomi/ant-client#245).

Linear issue

Closes V2-1796

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

T2 proposed: nodes behind a UPnP router now open a second router port and advertise a different browser endpoint. There is no wire, format or economics change.

Compatibility

• Wire: none. The signed address record format is unchanged; only the advertised WebRTC address differs when a mapping exists.
• Storage: none.
• API: none. No new configuration or CLI flags; --webrtc-direct-advertised-addr or an explicit --webrtc-direct-bind IP opts a node out.

Semver impact

• breaking
• feature
• fix

Test evidence

• Unit: new only_a_listener_choosing_its_own_address_maps_its_port, a_development_node_does_not_map_its_port, an_ipv6_listener_does_not_map_its_port, a_gateway_mapping_is_advertised_before_the_native_view, a_mapping_the_native_view_also_yields_comes_from_the_native_view and only_a_mapped_publication_is_withdrawn. The existing advertised-address tests pass no mapping and also assert the address's source.
• Refresh-level regression (review): an_endpoint_only_its_mapping_reached_is_withdrawn_when_the_mapping_ends publishes a mapping on a node with no native address, then removes the mapping and asserts HELLO state, the endpoint file, the catalog and the DHT supplemental record are all cleared. It fails on the first commit (the endpoint is kept) and passes on the fix.
• Withdrawal retry (second review): a_withdrawal_the_endpoint_file_blocks_still_unpublishes_and_is_retried puts a directory where the endpoint file was, so removing the file fails. The refresh returns the error, yet HELLO state, the catalog and the DHT record are already cleared. After the directory is replaced by a removable file, the next refresh removes it and the publication returns to Unpublished. Run against the previous production code, it fails because the catalog still holds the endpoint.
• cargo test --lib --features test-utils: 1197 passed. cargo test --bin ant-node: 5 passed. cargo test --test webrtc_direct_devnet: 3 passed. cargo fmt --all -- --check is clean.
• Clippy: cargo +1.99.0 clippy --all-targets --all-features -- -D warnings, the toolchain CI uses, is clean.
• Live, behind a consumer router with UPnP (Sagemcom F3896LG), against a local devnet plus one extra node on this branch with default WebRTC settings:
  • The listener bound 0.0.0.0:51812. The router granted UDP 51812 → host:51812, and the node advertised /ip4/<public IP>/udp/51812/webrtc-direct/….
  • SIGINT removed the mapping.
  • The same node on main got a mapping for its native QUIC port only, and advertised an unmapped browser port.
  • With the companion ant-client PR, ant node add --webrtc-port 24610-24611 → daemon-started nodes listened on 24610/24611, and the router mapped exactly those ports.
• Not shown: inbound reachability from the Internet. This router doesn't loop UDP back to its own LAN, so a browser dial of the public address from the same LAN got no answer. A LAN dial completed ICE, DTLS and the PQ handshake against the mapped listener.
• Not run: dev testnet. Testnet hosts have public interfaces, where router discovery finds nothing and publication is unchanged.
• Follow-up after release: rerun the mainnet census. The share of WebRTC endpoints that never answer should fall.

New dependency

none (saorsa_transport::upnp and igd-next are already built through saorsa-transport/default under the webrtc-direct feature)

ADR

ADR-0027: Map the browser listener's port through UPnP (new; amends ADR-0015's "NAT and relays")

Mitigation / rollback

Revert the commit. Per node, --webrtc-direct-advertised-addr or an explicit bind IP skips the mapping, and a leftover mapping expires within an hour.

🤖 Generated with Claude Code

[MaidSafe-Hermes]

REQUEST_CHANGES

At src/web_rtc.rs:752-756, a mapped-only endpoint is not withdrawn when the UPnP mapping is lost. advertised_addr(...) then returns None, and this early return leaves the previous endpoint in state.endpoint, the persisted endpoint file, the endpoint catalog, and the supplemental self-address set. This can occur when the native address view has no non-relay address of the listener's family. Browsers will keep dialling the expired or reassigned mapping, contrary to the documented promise to advertise it only while the gateway holds it.

Please clear or replace a mapping-derived publication when its mapping disappears and there is no valid native fallback. Add a refresh-level regression test for Mapped → Unavailable with no usable native address; assert the persisted/catalog/supplemental endpoint is withdrawn. Keep the existing last-known endpoint behaviour where that endpoint remains valid.

Panel: 2/2 seats reviewed (sol-1 gpt-6.1-sol xhigh; glm-1 z-ai/glm-5.3). The seats disagreed: sol-1 identified this stale-publication path; glm-1 approved, but its claim that the early return is fail-safe is contradicted by the retained state and side effects above.

Checks: GitHub CI tests, builds, format, clippy, MSRV, ADR governance and devnet checks passed at this head. Security Audit failed on crypto-bigint 0.5.5 (RUSTSEC-2026-0387); the base lockfile has the same version and this PR changes no dependency files, so this is inherited, not introduced here. The focused local Rust test command exceeded its 420-second execution limit before returning a result; no local test pass is claimed.

[MaidSafe-Hermes]

Re-review of 52b7382

The previous blocker is fixed on the normal withdrawal path: when a mapping-only endpoint loses its mapping and has no native fallback, the new refresh-level test verifies removal from endpoint state, the file, catalog and DHT supplemental addresses. The native-address fallback is still selected when present.

New blocker — cleanup can stop halfway and will not retry (src/web_rtc.rs:800-815). refresh_browser_endpoint clears endpoint_needs_mapping before awaiting withdrawal. withdraw_browser_endpoint then takes state.endpoint before removing the persisted file with ?. If that file removal fails, the function exits before removing the catalog and DHT entries; later refreshes see the flag cleared (and endpoint already None) and do not retry. The node can therefore keep advertising the dead mapping through catalog/DHT after reporting the endpoint withdrawn. Please make withdrawal retryable and ensure cleanup of the in-memory/catalog/DHT publications is not skipped by a file error; add a test that injects a file-removal failure and verifies eventual cleanup after recovery.

Panel: 2/2 seats reviewed (sol-1 gpt-6.1-sol xhigh; glm-1 z-ai/glm-5.3). Both confirmed the cleanup-error path.

Checks: Current GitHub test jobs passed. Build (macos-latest) is cancelled. Security Audit fails on the unchanged base-branch dependency crypto-bigint 0.5.5 (RUSTSEC-2026-0387). The focused local Rust test command timed out before returning; no local test pass is claimed.

[MaidSafe-Hermes]

APPROVE — re-review of 2956894

Both earlier findings are fixed. The mapping-only endpoint is withdrawn from HELLO, catalog and DHT when its mapping ends; a file-removal failure leaves a retryable Withdrawing state. The new regression test covers failure and recovery. The source-tagged publication also limits withdrawal to mapping-derived endpoints, and the new development-mode and IPv4 guards match the documented scope.

Panel: 2/2 seats reviewed (sol-1 gpt-6.1-sol xhigh; glm-1 z-ai/glm-5.3); both approve.

Checks: Current unit, e2e, platform, devnet, build, format, Clippy, MSRV, ADR and third-party-notice checks pass. Security Audit remains failed on crypto-bigint 0.5.5 (RUSTSEC-2026-0387), which is also in the base lockfile; this PR changes no dependency files. This approval covers the PR changes only. It does not waive the separate audit finding or authorize merge.