docs: refresh tutorials, how-to, design, reference, and examples for v0.4.0

Pre-cut documentation pass for the 0.4.0 release, verified against current source. Corrections: - fipsctl: stale 'show identities'/'show node' -> 'show status' (host-a-service, run-as-unprivileged-user) - mesh address derivation: first 16 bytes of SHA-256(pubkey) with the leading byte set to 0xfd, not a fixed fd97: prefix (reach-mesh-services, ipv6-adapter-walkthrough) - gateway control socket mode 0660 -> 0770 (troubleshoot-gateway) - Tor example: add advertised_port: 8443 so the published port matches the prose (enable-nostr-discovery) - bloom mesh-size estimate rewritten to the OR-union-of-peer-filters algorithm; plus mtu deep-link, gateway pool wording, and a NAT failure-mode line - examples: delete orphaned nostr-rs-relay config, accept inbound to the local 8443 TCP listener, fix fd::/8 -> fd00::/8 typos, dotless wireguard alias Additions: - new Nym mixnet transport section (fips-transport-layer) and the architecture transport list - new LAN/mDNS discovery section (fips-nostr-discovery) - reference docs: Nym transport, LAN discovery, and new control/stats surfaces; drop ble from the connect transport list
2026-07-22 07:48:26 +00:00 · 2026-06-14 15:14:05 +00:00
parent 3e0d9f5726
commit 507086e39d
22 changed files with 436 additions and 86 deletions
--- a/docs/design/fips-architecture.md
+++ b/docs/design/fips-architecture.md
@@ -221,9 +221,11 @@ discovery protocol, and error-recovery integration view live in
 ## Transport Abstraction

 FIPS treats the communication medium as a pluggable component. UDP,
-TCP, raw Ethernet, Tor, and BLE all implement the same small datagram
-interface (send, receive, report MTU) and feed peers into a single FMP
-routing layer; radio and serial transports are in the planned set.
+TCP, raw Ethernet, Tor, BLE, and Nym all implement the same small
+datagram interface (send, receive, report MTU) and feed peers into a
+single FMP routing layer; radio and serial transports are in the
+planned set. Nym (an outbound-only mixnet transport) and Tor are
+privacy-oriented deployment modes rather than failover paths.
 Multi-transport nodes bridge between networks transparently. The
 transport-layer specification — including per-transport categories,
 the trait surface, the connection model, and implementation status —
--- a/docs/design/fips-bloom-filters.md
+++ b/docs/design/fips-bloom-filters.md
@@ -180,7 +180,7 @@ network with no overlap (excluding the node itself at the split point).

 All peers — including non-tree mesh shortcuts — still **receive**
 FilterAnnounce messages and **store** received filters locally. These
-stored filters are consulted during routing (step 3 of `find_next_hop()`)
+stored filters are consulted during routing (step 4 of `find_next_hop()`)
 for single-hop shortcut discovery. However, mesh peer filters contain
 only the mesh peer's own tree-propagated information, not transitive
 entries from the broader network.
@@ -339,14 +339,24 @@ positions that folding produces.

 ## Mesh Size Estimation

-Each filter's saturation can be inverted into an estimated entry count
+A filter's saturation can be inverted into an estimated entry count
 via the standard formula `n ≈ -(m/k) · ln(1 − X/m)`, where `m` is the
 filter size in bits, `k` is the hash count, and `X` is the population
-count. Combining the parent's inbound filter with the children's
-inbound filters gives an estimate of the whole network: parent + each
-child's subtree are disjoint by construction, and adding 1 for the
-node itself yields the total. The result is cached on the node and
-exposed through the control socket and `fipstop` dashboard.
+count. Rather than estimate per-filter and sum, the node first builds
+an **OR-union of every connected peer's inbound filter** — all routing
+peers, including cross-links, not just the tree parent and children —
+inserts its own address into the union, and inverts the cardinality
+**once on the resulting union**. Because filter propagation is
+split-horizon (each outgoing filter excludes the peer it routes back
+to), every routing peer advertises a near-complete "whole mesh minus
+my subtree" view, so the union covers the network. OR-ing is
+idempotent, so overlapping bits deduplicate instead of over-counting,
+and folding in all peers rather than only the tree neighborhood damps
+the count flap on a parent switch (the cross-links still carry the
+upward coverage) and removes any dependence on tree-declaration cache
+freshness. The result is cached on the node and exposed through the
+control socket and `fipstop` dashboard. (See `compute_mesh_size()` in
+`src/node/mod.rs`.)

 The estimator refuses to produce a value when any contributing filter
 is above the antipoison FPR cap (`node.bloom.max_inbound_fpr`,
@@ -378,7 +388,7 @@ as described above.
 | 500ms rate limiting | **Implemented** |
 | FilterAnnounce gossip (all peers) | **Implemented** |
 | Filter cardinality logging | **Implemented** |
-| Mesh size estimation (parent + children + 1) | **Implemented** |
+| Mesh size estimation (OR-union of peer filters) | **Implemented** |
 | Inbound FPR cap (antipoison) | **Implemented** |
 | Size class negotiation | Future direction |
 | Folding support | Future direction |
--- a/docs/design/fips-gateway.md
+++ b/docs/design/fips-gateway.md
@@ -218,7 +218,7 @@ involving the DNS proxy or the pool.

 ### Virtual IP Pool

-The pool allocates IPv6 addresses from a configured CIDR (default
+The pool allocates IPv6 addresses from a required CIDR (commonly
 `fd01::/112`). Each address maps to one mesh destination, keyed by
 `NodeAddr` rather than by hostname — different `.fips` aliases for
 the same node share a virtual IP. Address 0 (the network-equivalent)
--- a/docs/design/fips-mtu.md
+++ b/docs/design/fips-mtu.md
@@ -251,7 +251,7 @@ would later drop.
 The adapter integrates with the MTU subsystem rather than owning it.
 The "why we clamp and what `max_mss` means" lives here in the MTU
 design; the "how the clamp is implemented at the TUN" lives in the
-[IPv6 adapter](fips-ipv6-adapter.md#tcp-mss-clamping) doc.
+[IPv6 adapter](fips-ipv6-adapter.md#tun-side-tcp-mss-clamping) doc.

 ## ICMP Packet Too Big

--- a/docs/design/fips-nostr-discovery.md
+++ b/docs/design/fips-nostr-discovery.md
@@ -1,4 +1,13 @@
-# FIPS Nostr-Mediated Discovery and NAT Traversal
+# FIPS Discovery: Nostr-Mediated and LAN/mDNS
+
+FIPS nodes have two discovery mechanisms beyond the static `peers[]`
+list. The bulk of this document describes **Nostr-mediated discovery**,
+which works across the internet using public Nostr relays as a
+signaling channel and can punch through UDP NAT. A second, much
+simpler mechanism — **LAN/mDNS discovery** — finds peers on the same
+local link with no relay, STUN, or NAT traversal at all; it is
+described in its own section near the end. The two are independent: a
+node can enable either, both, or neither.

 Nostr-mediated discovery lets FIPS nodes find each other, and if
 necessary, punch through UDP NAT, using public Nostr relays as the
@@ -377,6 +386,182 @@ semaphore and replay-cache layers downstream.
  advert says "I am npub X at 1.2.3.4:5678" but whose FMP handshake
  presents a different static key is rejected at the mesh layer.

+## LAN/mDNS discovery
+
+LAN discovery is a separate, link-local discovery mechanism that finds
+peers on the same broadcast domain using mDNS / DNS-SD
+([RFC 6762](https://www.rfc-editor.org/rfc/rfc6762) /
+[RFC 6763](https://www.rfc-editor.org/rfc/rfc6763)). Unlike
+Nostr-mediated discovery, it contacts no relay, runs no STUN
+observation, and performs no NAT traversal: an endpoint learned from a
+LAN advert is by construction routable from the consumer's own link.
+The result is sub-second peer pairing on the same LAN.
+
+It is unrelated to the "LAN candidate" terminology used in the
+NAT-traversal sections above (which refers to a host's own
+locally-bound address offered as a hole-punch candidate). LAN/mDNS
+discovery is a distinct subsystem under `src/discovery/lan/`.
+
+### Role
+
+LAN discovery adds two capabilities, both confined to the local link:
+
+- **Advertising.** The node publishes a `_fips._udp.local.` DNS-SD
+  service advert carrying its `npub`, its protocol version, and (if
+  configured) a discovery scope. The advert is multicast on the local
+  link only; it does not leave the broadcast domain unless the
+  operator's network bridges mDNS.
+- **Browsing.** The node concurrently browses for the same service
+  type, learns the endpoints of other FIPS nodes on the link, and
+  initiates a normal FMP link to each newly-seen peer.
+
+The mDNS service type is `_fips._udp.local.`
+(`src/discovery/lan/mod.rs:45`). Per RFC 6763 the `_udp` label denotes
+the IP transport used for the advert, not the FIPS upper protocol —
+both UDP and TCP FIPS endpoints announce under the same service type
+because the link-layer handshake travels over UDP either way. (In
+practice LAN discovery dials only over a UDP transport; see the
+handshake subsection.)
+
+### When to use it
+
+- **You run several FIPS nodes on one LAN** (a lab bench, an office
+  segment, a home network) and want them to find each other without
+  hand-maintaining `peers[]` blocks or standing up Nostr discovery.
+- **You want the lowest-latency pairing path.** Same-link pairing
+  completes in well under a second with no relay round-trip.
+
+Skip it when nodes are not on a shared broadcast domain (mDNS does not
+cross routed boundaries), or when you do not want the node to multicast
+its identity on the local link. LAN discovery is **opt-in and disabled
+by default**, so doing nothing leaves it off.
+
+### How it works
+
+The LAN discovery runtime (`src/discovery/lan/mod.rs`) is started
+during node initialization when `node.discovery.lan.enabled` is true.
+It is independent of Nostr discovery and runs even when Nostr is
+disabled (`src/node/lifecycle.rs:1159-1162`). Startup requires an
+operational UDP transport: the node advertises the port of its
+lowest-`TransportId` operational, non-bootstrap UDP transport, chosen
+deterministically so the advertised port is stable across restarts
+(`src/node/lifecycle.rs:1169-1180`). If no such port exists, the
+runtime returns `NoAdvertisedPort` and LAN discovery does not start
+(`src/discovery/lan/mod.rs:156-158`).
+
+The runtime does two things concurrently:
+
+1. **Responder.** It registers a DNS-SD service with instance name
+   `fips-<first-16-chars-of-npub>` and a TXT record carrying the keys
+   below. `mdns-sd`'s address auto-detection appends every non-loopback
+   interface address, with `127.0.0.1` seeded so same-host peers and
+   integration tests can still resolve the advert
+   (`src/discovery/lan/mod.rs:182-203`).
+2. **Browser.** A background pump receives `ServiceResolved` events for
+   the same service type. For each resolved advert it extracts the
+   `npub` and `scope` TXT values, drops adverts that echo the node's own
+   npub, drops cross-scope adverts (see scope filtering), drops records
+   without an `npub`, and surfaces one `LanDiscoveredPeer` per routable
+   interface address (`src/discovery/lan/mod.rs:212-299`). IPv6
+   unicast link-local addresses without an interface scope id are
+   skipped, since they cannot be dialed unambiguously
+   (`src/discovery/lan/mod.rs:348-365`).
+
+The TXT record carries three keys (`src/discovery/lan/mod.rs:47-55`):
+
+| TXT key | Contents |
+| --- | --- |
+| `npub` | bech32-encoded npub of the advertising node |
+| `scope` | the node's discovery scope, if one is configured (omitted otherwise) |
+| `v` | FIPS protocol version (the same `PROTOCOL_VERSION` used by the Nostr advert) |
+
+Once per node tick, the node drains browser events and acts on them in
+`poll_lan_discovery()` (`src/node/lifecycle.rs:907`, called from
+`src/node/handlers/rx_loop.rs:266`). For each discovered peer it finds
+a UDP transport whose family matches the peer address, parses the
+`npub` into a `PeerIdentity`, skips peers it is already connected to or
+currently connecting to, and otherwise initiates a connection.
+
+### Handshake: Noise IK
+
+LAN-discovered peers are dialed through the standard FMP outbound link
+path. `poll_lan_discovery()` calls `initiate_connection()`
+(`src/node/lifecycle.rs:380`), which, for connectionless transports
+such as UDP, allocates a link and **starts the Noise IK handshake**
+(documented at `src/node/lifecycle.rs:373-374`). This is the same
+link-layer handshake used by every other FMP connection — IK at the
+link layer per the FIPS architecture — not a different pattern for LAN
+peers.
+
+The mDNS advert is **unauthenticated**: anyone on the link can
+multicast a TXT claiming any `npub`. Identity is proven end-to-end by
+the Noise IK handshake against the observed endpoint. A spoofed advert
+carrying another node's npub fails the handshake — the impostor does
+not hold the matching static key — and the half-open link is dropped.
+The mDNS advert is therefore a routing hint, never an identity
+assertion, exactly as a Nostr advert is treated (a successful contact
+is not trusted until FMP's Noise IK handshake completes).
+
+> Note: a stale source doc-comment at `src/node/lifecycle.rs:904-906`
+> describes this path as a "Noise XX" handshake. That comment is
+> inaccurate — the path uses Noise IK as described above. The comment
+> is flagged for a separate source fix and does not reflect actual
+> behavior.
+
+### Scope filtering
+
+When a discovery scope is configured, the advert carries it in the
+`scope` TXT entry and the browser surfaces only peers whose advert
+carries a matching scope. Nodes on the same physical LAN but configured
+for different mesh networks therefore do not cross-feed each other.
+
+The scope is resolved by `lan_discovery_scope()`
+(`src/node/lifecycle.rs:880-902`): the explicit
+`node.discovery.lan.scope`, if non-empty, is used directly. Otherwise
+the node falls back to deriving a scope from the Nostr discovery `app`
+tag (stripping the `fips-overlay-v1:` prefix when present). This lets
+an application keep its public, relay-visible Nostr `app` tag generic
+while still isolating LAN discovery per private network, or share one
+value across both. A node with no scope on either side surfaces all
+adverts it sees on the link.
+
+### Configuration
+
+LAN discovery is configured under `node.discovery.lan.*`
+(`src/config/node.rs:222-227`, `src/discovery/lan/mod.rs:88-129`):
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `node.discovery.lan.enabled` | bool | `false` | Master switch. LAN discovery is opt-in; default-off avoids an unexpected per-link identity multicast on upgrade. |
+| `node.discovery.lan.service_type` | string | `_fips._udp.local.` | DNS-SD service type. Overridable mainly so integration tests can isolate multiple services on one loopback interface. |
+| `node.discovery.lan.scope` | string (optional) | unset | Application/network scope carried in the LAN-only `scope` TXT record. Kept deliberately separate from the public Nostr `app` tag. When unset, the scope falls back to the derived Nostr `app` value. |
+
+The identity surface published over mDNS (`npub`, version, optional
+scope) is a strict subset of what `nostr.advertise` already publishes
+publicly, so enabling LAN discovery adds no marginal privacy cost
+beyond making the node's presence observable on its own local link.
+
+### Relationship to Nostr discovery
+
+The two mechanisms are complementary and independent:
+
+| | Nostr-mediated | LAN/mDNS |
+| --- | --- | --- |
+| Reach | Internet-wide, via relays | Same broadcast domain only |
+| Signaling channel | Public Nostr relays | mDNS multicast on the local link |
+| NAT traversal | STUN + UDP hole-punch for `udp:nat` peers | None — endpoint is link-routable by construction |
+| Identity carrier | signed kind 37195 advert (authenticated at publish) | unauthenticated mDNS TXT (routing hint only) |
+| Identity proof | FMP Noise IK on the connection | FMP Noise IK on the connection |
+| Default | disabled (`nostr.enabled: false`) | disabled (`lan.enabled: false`) |
+| Scope key | `app` tag (public) | `scope` TXT (link-local), falls back to `app` |
+
+Both ultimately converge on the same trust boundary: discovery only
+supplies candidate endpoints, and no peer is trusted until FMP's Noise
+IK handshake confirms the claimed identity. A node may run both at
+once — for example, advertising globally over Nostr while also pairing
+instantly with same-LAN peers — with no interaction between the two
+beyond the shared scope fallback.
+
 ## See also

 - [../how-to/enable-nostr-discovery.md](../how-to/enable-nostr-discovery.md)
--- a/docs/design/fips-transport-layer.md
+++ b/docs/design/fips-transport-layer.md
@@ -120,6 +120,7 @@ for internet connectivity:
 | UDP/IP | host:port | 1280–1472 | Unreliable | Primary internet transport |
 | TCP/IP | host:port | Stream | Reliable | Requires length-prefix framing |
 | Tor | .onion | Stream | Reliable | High latency, strong anonymity |
+| Nym | host:port | Stream | Reliable | Mixnet, outbound-only, strong anonymity |

 **Shared medium transports** operate over broadcast- or multicast-capable
 media:
@@ -190,6 +191,7 @@ proceed.
 | --------- | ---------------- |
 | TCP/IP | TCP three-way handshake |
 | Tor | Circuit establishment (typically 10–60s, default timeout 120s) |
+| Nym | SOCKS5 connect through mixnet (minutes possible, default timeout 300s) |
 | BLE | L2CAP CoC or GATT connection |
 | Serial | Physical connection (static) |

@@ -599,6 +601,120 @@ SOCKS5-level errors, MTU rejections, accepted/rejected inbound
 connections, and Tor control-port errors. The full counter table
 lives in [../reference/transports.md](../reference/transports.md).

+## Nym: The Mixnet Transport
+
+The Nym transport routes FIPS traffic through the Nym mixnet, providing
+network-level anonymity via Sphinx packet routing and timing
+obfuscation. It uses the "mixnet-as-proxy" pattern: a node connects
+outbound through a local `nym-socks5-client` SOCKS5 proxy, which carries
+the traffic into the mixnet. The `nym-socks5-client` runs as a separate
+process alongside the fips daemon and must be started independently.
+
+Like Tor, Nym is a privacy-oriented deployment mode chosen for the
+anonymity properties of the mixnet, not a failover for other transports.
+Like TCP and Tor, it is connection-oriented and reliable; the same
+TCP-over-TCP considerations apply, and cost-based parent selection
+naturally deprioritizes the high-latency Nym links.
+
+### Architecture
+
+The Nym transport is a separate `NymTransport` implementation. It reuses
+the FMP header-based stream reader (`tcp/stream.rs`) for packet framing
+on the underlying byte stream, and follows the same connection-pool
+pattern as the TCP and Tor transports.
+
+It maintains two pools: a `ConnectingPool` for background SOCKS5
+connection attempts, and an established pool of `NymConnection` entries.
+Each `NymConnection` holds a write half, a per-connection receive task,
+the configured MTU, and a connection timestamp.
+
+| Property | Value |
+| -------- | ----- |
+| Addressing | IP:port or hostname:port |
+| Default MTU | 1400 bytes |
+| Framing | FMP header-based (shared with TCP) |
+| Connection model | Outbound-only, non-blocking connect through SOCKS5 |
+| Platform | Cross-platform (requires external nym-socks5-client) |
+
+### Outbound-Only
+
+The Nym transport is strictly outbound. It supports no inbound service:
+`accept_connections()` returns `false` and `discover()` returns no
+peers. A node using the Nym transport can initiate links to remote peers
+through the mixnet, but cannot accept inbound connections over Nym. (A
+node can still accept inbound links over other transports it runs.)
+
+### Address Types
+
+The Nym transport accepts two address formats, parsed into an internal
+target address:
+
+- **IP:port** — a numeric IP and port, sent to the SOCKS5 proxy as a
+  numeric target.
+- **Hostname:port** — the hostname is passed through SOCKS5 so it is
+  resolved on the exit side rather than locally.
+
+Both forms are routed through the same SOCKS5 proxy.
+
+### Connection Establishment
+
+Connection setup follows the same non-blocking pattern as the TCP and
+Tor transports. When FMP needs to reach a peer, the node initiates a
+background connect (`connect_async`). The transport spawns a background
+tokio task that opens a SOCKS5 connection through the local
+`nym-socks5-client`, configures the socket (including TCP keepalive),
+splits the stream, and spawns a per-connection receive loop using the
+shared FMP stream reader. The call returns immediately while the connect
+proceeds in the background.
+
+SOCKS5 connection setup through the mixnet can take much longer than a
+direct TCP connection because each connection traverses multiple mix
+nodes with timing obfuscation. Accordingly the connect timeout defaults
+to 300 seconds (`connect_timeout_ms`). Non-blocking connect is essential
+here — a blocking connect would stall the FMP event loop for the
+duration of mixnet setup. As a fallback, `send_async(addr, data)`
+performs a connect-on-send if no connection to the address yet exists.
+
+Each outbound packet is checked against the configured MTU before being
+written; an oversized packet is rejected with an MTU-exceeded error
+rather than being sent.
+
+### Startup Readiness
+
+At startup the transport validates the configured `socks5_addr` and then
+probes the SOCKS5 port to wait for `nym-socks5-client` to become ready,
+using exponential backoff (starting at 1 second, capped at 10 seconds
+between attempts) up to `startup_timeout_secs` (default 120 seconds). If
+the proxy does not become reachable within that window, the transport
+logs a warning and starts anyway; outbound connections then fail until
+the `nym-socks5-client` becomes available.
+
+### Session Independence
+
+Same as TCP and Tor: loss of a Nym connection does **not** tear down the
+FIPS peer. Noise keys, MMP state, and FSP sessions survive reconnection.
+
+### Configuration
+
+The Nym transport block (`transports.nym.*`) has the following fields:
+
+| Field | Default | Description |
+| ----- | ------- | ----------- |
+| `socks5_addr` | `127.0.0.1:1080` | Address (host:port) of the local nym-socks5-client SOCKS5 proxy |
+| `connect_timeout_ms` | `300000` | Outbound SOCKS5 connect timeout in milliseconds (300s) |
+| `mtu` | `1400` | Maximum FIPS packet size for Nym connections, in bytes |
+| `startup_timeout_secs` | `120` | Seconds to wait for nym-socks5-client to become ready at startup |
+
+The Nym transport requires an external `nym-socks5-client`. Named
+instances are supported for multiple proxy endpoints. Unknown
+configuration keys are rejected.
+
+### Statistics
+
+The Nym transport exposes per-instance counters covering successful
+send/receive, send/receive errors, connection establishment, SOCKS5-level
+errors, connect timeouts, and MTU rejections.
+
 ## Discovery

 Discovery determines that a FIPS-capable endpoint is reachable at a given
@@ -725,7 +841,8 @@ TransportType {
 }
 ```

-Predefined types exist for UDP, TCP, Ethernet, WiFi, Tor, and Serial.
+Predefined types exist for UDP, TCP, Ethernet, WiFi, Tor, Nym, BLE, and
+Serial.

 ### Congestion Reporting

@@ -750,6 +867,7 @@ on all forwarded datagrams.
 | UDP | `SO_RXQ_OVFL` kernel drop counter | `recvmsg()` ancillary data on every packet |
 | TCP | Not implemented | Returns `None` (TCP handles congestion internally) |
 | Tor | Not implemented | Returns `None` (TCP handles congestion internally) |
+| Nym | Not implemented | Returns `None` (TCP handles congestion internally) |
 | Ethernet | Not implemented | Returns `None` |

 ### Transport Addresses
@@ -780,6 +898,7 @@ transitions through `Starting` to `Up` (operational). `stop()` moves to
 | Ethernet | **Implemented** | AF_PACKET SOCK_DGRAM, EtherType 0x2121, beacon discovery, Linux only |
 | WiFi | **Implemented** (via Ethernet transport, infrastructure mode) | mac80211 translates 802.11↔802.3; broadcast beacons unreliable through APs |
 | Tor | **Implemented** | Outbound SOCKS5, inbound via onion service, .onion and clearnet addressing |
+| Nym | **Implemented** | Outbound-only SOCKS5 through nym-socks5-client, mixnet anonymity, IP/hostname addressing |
 | BLE | **Implemented** (Linux/glibc only; experimental) | L2CAP CoC, ATT_MTU negotiation, per-link MTU; musl/macOS/Windows skip |
 | Radio | Future direction | Constrained MTU (51–222 bytes) |
 | Serial | Future direction | SLIP/COBS framing, point-to-point |
--- a/docs/design/port-advertisement-and-nat-traversal.md
+++ b/docs/design/port-advertisement-and-nat-traversal.md
@@ -526,7 +526,7 @@ own.

 | Failure | Symptom | Mitigation |
 | --- | --- | --- |
-| Symmetric NAT (one side) | Punch timeout | Retry with port-prediction heuristics; otherwise fall back to a relay or different transport |
+| Symmetric NAT (one side) | Punch timeout | Retry with port-prediction heuristics; otherwise fall back to an application-level relay |
 | Symmetric NAT (both sides) | Punch timeout | Application-level relay required |
 | Relay latency > 60 s | Stale reflexive address | Use low-latency relays; consider self-hosted relay |
 | Relay does not support ephemeral kinds | Signaling events persist | Use NIP-40 expiration + NIP-09 deletion as fallback |
--- a/docs/how-to/enable-nostr-discovery.md
+++ b/docs/how-to/enable-nostr-discovery.md
@@ -284,6 +284,7 @@ transports:
  tor:
    mode: directory
    socks5_addr: "127.0.0.1:9050"
+    advertised_port: 8443
    directory_service:
      hostname_file: "/var/lib/tor/fips/hostname"
      bind_addr: "127.0.0.1:8444"
--- a/docs/how-to/run-as-unprivileged-user.md
+++ b/docs/how-to/run-as-unprivileged-user.md
@@ -169,7 +169,7 @@ sudo usermod -aG fips $USER
 Then:

 ```sh
-fipsctl show node
+fipsctl show status
 ```

 ## Caveats
--- a/docs/how-to/troubleshoot-gateway.md
+++ b/docs/how-to/troubleshoot-gateway.md
@@ -151,7 +151,7 @@ rather than `flush ruleset`, which destroys every table on the host.
 Symptom: `nc -U /run/fips/gateway.sock` fails with "Permission
 denied" or "No such file or directory".

-The socket is owned by root with mode `0660` (group `fips`). Either
+The socket is owned by root with mode `0770` (group `fips`). Either
 run `nc` as root (`sudo nc -U ...`) or add your user to the `fips`
 group and re-login. If the file does not exist at all, the gateway
 either failed to start (check `journalctl -u fips-gateway`) or
--- a/docs/reference/cli-fipsctl.md
+++ b/docs/reference/cli-fipsctl.md
@@ -69,6 +69,7 @@ Time-series metrics from the in-process history rings.
 | Subcommand | Control-socket command | Description |
 | ---------- | ---------------------- | ----------- |
 | `stats list` | `show_stats_list` | Enumerate available metrics, their units, and the per-ring retention windows. |
+| `stats metrics` | `show_metrics` | Dump current counter values for every protocol metric family (`forwarding`, `discovery`, `tree`, `bloom`, `congestion`, `errors`). |
 | `stats peers` | `show_stats_peers` | List peers tracked in stats history (active or recently active). |
 | `stats history <metric> [options]` | `show_stats_history` | Fetch a time-series window for one metric. |

@@ -104,7 +105,7 @@ Tell the daemon to dial a peer over a specific transport.
 | -------- | ----------- |
 | `peer` | npub (bech32) or hostname from `/etc/fips/hosts`. |
 | `address` | Transport endpoint, e.g. `192.168.1.10:2121`, `[2001:db8::1]:2121`, or a Tor onion. FIPS-mesh ULAs (`fd00::/8`) are rejected for the IP-based transports (udp, tcp, ethernet). |
-| `transport` | One of `udp`, `tcp`, `tor`, `ethernet`. |
+| `transport` | One of `udp`, `tcp`, `tor`, `nym`, `ethernet`. The named transport must be configured and running. |

 ### `disconnect <peer>`

--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -235,6 +235,29 @@ addresses for the punch socket port.
 During punching, compatible private-subnet candidates and reflexive candidates
 are attempted in parallel; the first successful path wins.

+#### LAN Discovery (`node.discovery.lan.*`)
+
+Peer discovery on the local link via mDNS / DNS-SD (RFC 6762 / RFC
+6763). When enabled, the node publishes a `_fips._udp.local.` service
+advert carrying its `npub` (and optional scope) and concurrently
+browses for the same service type to learn same-broadcast-domain peers.
+The result is sub-second peer pairing with no Nostr-relay roundtrip,
+STUN observation, or NAT traversal: the observed endpoint is by
+construction routable from the consumer's LAN.
+
+mDNS adverts are unauthenticated, so a LAN advert is treated only as a
+routing hint. Identity is still proven end-to-end by the Noise XX
+handshake the node initiates against the observed endpoint; a spoofed
+advert carrying another peer's npub fails the handshake and is dropped.
+LAN discovery requires an active UDP transport (peers dial the
+advertised UDP port to begin the handshake).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `node.discovery.lan.enabled` | bool | `false` | Master switch. Opt-in: enable for sub-second same-LAN pairing. Default-off avoids reintroducing a per-LAN identity broadcast on nodes that have deliberately disabled other discovery channels |
+| `node.discovery.lan.service_type` | string | `"_fips._udp.local."` | DNS-SD service type. Primarily an override for integration tests running multiple isolated services on one loopback interface; leave at the default in production |
+| `node.discovery.lan.scope` | string | *(none)* | Optional application/network scope carried in a `scope=<name>` TXT entry. Browsers with a scope set only surface peers advertising the same scope, so nodes on the same physical LAN configured for different mesh networks do not cross-feed. Intentionally separate from `node.discovery.nostr.app` so relay-visible adverts can stay generic while LAN discovery is isolated per private network |
+
 ### Spanning Tree (`node.tree.*`)

 Controls tree construction and parent selection.
@@ -576,6 +599,25 @@ HiddenServiceDir /var/lib/tor/fips
 HiddenServicePort 8443 127.0.0.1:8444
 ```

+### Nym (`transports.nym.*`)
+
+Nym transport routes FIPS traffic through the Nym mixnet for
+metadata-resistant anonymity. Outbound-only: connections are made
+through a `nym-socks5-client` SOCKS5 proxy that must be running
+separately (e.g. as a service running alongside the fips daemon or as a
+container). There is no inbound listener — a Nym-only node initiates
+outbound links but is not reachable for unsolicited inbound handshakes.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `transports.nym.socks5_addr` | string | `"127.0.0.1:1080"` | `nym-socks5-client` SOCKS5 proxy address (host:port) |
+| `transports.nym.connect_timeout_ms` | u64 | `300000` | Outbound connect timeout in milliseconds. Mixnet SOCKS5 connections traverse 3 mix nodes with timing obfuscation and can take several minutes, so this is generous (300s). |
+| `transports.nym.mtu` | u16 | `1400` | Default MTU |
+| `transports.nym.startup_timeout_secs` | u64 | `120` | Seconds to wait for `nym-socks5-client` to become ready at startup before giving up |
+
+**Named instances.** Like other transports, multiple Nym instances can
+be configured with named sub-keys for different SOCKS5 proxy endpoints.
+
 ### BLE (`transports.ble.*`)

 Bluetooth Low Energy transport using L2CAP Connection-Oriented Channels.
@@ -889,6 +931,9 @@ node:
    backoff_base_secs: 0
    backoff_max_secs: 0
    forward_min_interval_secs: 2
+    # lan:                             # uncomment to enable mDNS LAN discovery
+    #   enabled: true                  # opt-in, default false
+    #   scope: "my-mesh"               # optional per-network scope filter
  tree:
    announce_min_interval_ms: 500
    parent_hysteresis: 0.2              # cost improvement fraction for parent switch
@@ -983,6 +1028,11 @@ transports:
  #   #   bind_addr: "127.0.0.1:8443"
  #   # max_inbound_connections: 64
  #   # advertised_port: 443           # public-facing onion port for Nostr adverts
+  # nym:                              # uncomment to enable Nym mixnet transport (outbound-only)
+  #   socks5_addr: "127.0.0.1:1080" # nym-socks5-client SOCKS5 proxy address
+  #   connect_timeout_ms: 300000    # connect timeout (300s for mixnet)
+  #   mtu: 1400                     # default MTU
+  #   startup_timeout_secs: 120     # wait for nym-socks5-client to be ready
  # ble:                              # uncomment to enable BLE transport (Linux only, requires BlueZ)
  #   adapter: "hci0"                 # HCI adapter name
  #   psm: 0x0085                     # L2CAP PSM (133)
--- a/docs/reference/control-socket.md
+++ b/docs/reference/control-socket.md
@@ -115,6 +115,7 @@ table below lists every command currently registered.
 | `show_identity_cache` | — | `entries[]`, `count`, `max_entries`. Each entry: `node_addr`, `npub`, `display_name`, `ipv6_addr`, `last_seen_ms`, `age_ms`. |
 | `show_listening_sockets` | — | `fips0_addr`, `firewall_active` (bool — `inet fips` table loaded), `sockets[]`. Each entry: `proto` (`tcp` / `udp`), `local_addr` (`::` or the node's fd00::/8 address), `port`, `pid` (nullable), `process` (nullable), `wildcard_bind` (bool — `local_addr == ::`), `filter` (`accept` / `drop` / `unknown` / `no_firewall`). Linux-only; returns an empty `sockets[]` on other platforms. |
 | `show_stats_list` | — | `metrics[]` (each with `name`, `unit`, `scope`), `fast_ring_seconds`, `slow_ring_minutes`, `peer_retention_seconds`. |
+| `show_metrics` | — | Flat snapshot of every counter family in the metrics registry: `forwarding`, `discovery`, `tree`, `bloom`, `congestion`, `errors`. Each value is that family's counter snapshot object. Counter-only — gauges/histograms that need the live node are excluded. Served off the main loop. |
 | `show_stats_history` | `metric` (req), `peer` (req for per-peer metrics), `window` (`<N>s` / `<N>m` / `<N>h`, default `10m`), `granularity` (`1s` / `1m`, default `1s`) | A single `Series`: `metric`, `unit`, `granularity_seconds`, `values[]`. |
 | `show_stats_all_history` | `peer` (optional npub), `window`, `granularity` | `granularity_seconds`, `window_seconds`, `peer`, `series[]` (one per metric). |
 | `show_stats_peers` | — | `peers[]`, `count`. Each entry: `npub`, `node_addr`, `display_name`, `is_active`, `first_seen_secs_ago`, `last_contact_secs_ago`. |
@@ -128,7 +129,7 @@ fixtures.

 | Command | Required params | Behaviour |
 | ------- | --------------- | --------- |
-| `connect` | `npub` (bech32), `address` (transport endpoint), `transport` (`udp`, `tcp`, `tor`, `ethernet`) | Asks the node to dial the peer over the named transport. Returns the API result on success or an error string on failure. |
+| `connect` | `npub` (bech32), `address` (transport endpoint), `transport` (`udp`, `tcp`, `tor`, `nym`, `ethernet`) | Asks the node to dial the peer over the named transport. The named transport must be configured and running. Returns the API result on success or an error string on failure. |
 | `disconnect` | `npub` (bech32) | Asks the node to drop the link to the named peer. |

 Both commands run on the daemon's main task and may block briefly
--- a/docs/reference/transports.md
+++ b/docs/reference/transports.md
@@ -34,6 +34,8 @@ module.
 | `connections_rejected` | Rejected inbound connections (limit exceeded) |
 | `connect_timeouts` | Connection timeout count |
 | `connect_refused` | Connection refused count |
+| `pool_inbound` | Current inbound connections held in the connection pool (gauge) |
+| `pool_outbound` | Current outbound connections held in the connection pool (gauge) |

 ## Ethernet

@@ -61,6 +63,23 @@ module.
 | `connections_accepted` | Accepted inbound connections via onion service |
 | `connections_rejected` | Rejected inbound connections (limit exceeded) |
 | `control_errors` | Tor control port errors |
+| `pool_inbound` | Current inbound connections held in the connection pool (gauge) |
+| `pool_outbound` | Current outbound connections held in the connection pool (gauge) |
+
+## Nym
+
+| Counter | Description |
+| ------- | ----------- |
+| `packets_sent` / `bytes_sent` | Successful sends |
+| `packets_recv` / `bytes_recv` | Successful receives |
+| `send_errors` / `recv_errors` | Send/receive failures |
+| `mtu_exceeded` | Packets rejected for MTU violation |
+| `connections_established` | Successful SOCKS5 connections through `nym-socks5-client` |
+| `connect_timeouts` | Connection timeout count |
+| `socks5_errors` | SOCKS5 protocol errors |
+
+Nym is outbound-only (no inbound listener), so there are no
+`connections_accepted` / `connections_rejected` counters.

 ## Bluetooth

--- a/docs/tutorials/host-a-service.md
+++ b/docs/tutorials/host-a-service.md
@@ -98,11 +98,10 @@ is what you want.
 Or via the daemon:

 ```sh
-sudo fipsctl show identities
+sudo fipsctl show status
 ```

-The first JSON entry has `local: true` and a `ula` field — that
-is your address.
+The JSON has an `ipv6_addr` field — that is your address.

 For the rest of this tutorial we will write the address as
 `<your-fips0-addr>`. Substitute the actual `fd97:...` value
--- a/docs/tutorials/ipv6-adapter-walkthrough.md
+++ b/docs/tutorials/ipv6-adapter-walkthrough.md
@@ -63,9 +63,11 @@ mesh address:
 dig npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98.fips AAAA +short
 ```

-You should see one AAAA record returning a `fd97:...` address.
-The prefix is the FIPS ULA range (`fd00::/8`, with `fd97:...`
-covering the address space derived from npubs).
+You should see one AAAA record returning an address such as
+`fd97:...`. The prefix is the FIPS ULA range (`fd00::/8`): only
+the leading `fd` byte is fixed, and everything after it is hash
+output derived from the npub, so the digits beyond `fd` vary per
+node.

 The query went through `systemd-resolved` (or your platform
 equivalent), which routed `.fips` queries to the daemon's local
--- a/docs/tutorials/reach-mesh-services.md
+++ b/docs/tutorials/reach-mesh-services.md
@@ -56,8 +56,11 @@ hostname on the public internet. There is no separate
 the tool takes a hostname, it accepts a `.fips` hostname.

 > **Where the address comes from.** Every FIPS node's mesh
-> address is the SHA-256 of its public key, truncated to the
-> bottom 64 bits and prepended with `fd97:`. Names of the form
+> address is the first 16 bytes of SHA-256 of its public key,
+> with the leading byte replaced by `0xfd` (the `fd00::/8` ULA
+> prefix). The remaining bytes are hash output, so an address
+> like `fd97:...` is per-node — the `97` is part of the hash,
+> not a fixed prefix shared across nodes. Names of the form
 > `<npub>.fips` and any shortname mapped in `/etc/fips/hosts`
 > are aliases for that address. The daemon's local DNS
 > responder hands the answer back to your kernel without ever
--- a/examples/k8s-sidecar/README.md
+++ b/examples/k8s-sidecar/README.md
@@ -39,7 +39,7 @@ fips sidecar:
 4. Starts dnsmasq and then `exec`s the FIPS daemon.

 The app container starts concurrently and immediately sees `lo`, `eth0`, and
-`fips0`. DNS for `<npub>.fips` names resolves to `fd::/8` addresses via the
+`fips0`. DNS for `<npub>.fips` names resolves to `fd00::/8` addresses via the
 dnsmasq → FIPS daemon pipeline.

 ```text
--- a/examples/sidecar-nostr-relay/README.md
+++ b/examples/sidecar-nostr-relay/README.md
@@ -73,13 +73,14 @@ ws://npub1xxxx.fips:80

 The sidecar pattern enforces strict network isolation on the app container:

- **No IPv4 access**: iptables blocks all eth0 traffic except FIPS UDP
-  transport (port 2121) and TCP transport (port 443). The app container
+- **No IPv4 access**: iptables blocks all eth0 traffic except the FIPS UDP
+  transport (port 2121), the local FIPS TCP listener (port 8443), and
+  outbound TCP to peers' published endpoints (port 443). The app container
  cannot reach the Docker bridge, the host network, or any IPv4 address.
 - **No IPv6 on eth0**: ip6tables blocks all IPv6 traffic on eth0. The app
  container cannot use link-local or any Docker-assigned IPv6 addresses.
 - **FIPS mesh only**: The only routable network path is through `fips0`
-  (`fd::/8`). All application traffic traverses the FIPS mesh with
+  (`fd00::/8`). All application traffic traverses the FIPS mesh with
  end-to-end encryption.
 - **Loopback allowed**: `lo` is unrestricted for inter-process communication
  within the shared namespace.
@@ -105,7 +106,7 @@ with the transport layer directly.
 │ Interfaces:                                       │
 │   lo    — loopback (unrestricted)                 │
 │   eth0  — Docker bridge (iptables: FIPS only)     │
-│   fips0 — FIPS TUN (fd::/8, unrestricted)         │
+│   fips0 — FIPS TUN (fd00::/8, unrestricted)         │
 └───────────────────────────────────────────────────┘
 ```

@@ -118,7 +119,8 @@ before launching the FIPS daemon:

 - ACCEPT on `lo` (both directions)
 - ACCEPT UDP sport/dport 2121 on `eth0` (FIPS UDP transport)
- ACCEPT TCP dport 443 / sport 443 on `eth0` (FIPS TCP transport)
+- ACCEPT TCP dport 443 / sport 443 on `eth0` (outbound to peers' TCP endpoints)
+- ACCEPT TCP dport/sport 8443 on `eth0` (local FIPS TCP listener, `FIPS_TCP_BIND`)
 - DROP everything else on `eth0`

 **IPv6 rules** (ip6tables):
@@ -132,7 +134,7 @@ before launching the FIPS daemon:
 DNS inside the container is handled by dnsmasq (127.0.0.1:53):

 - `.fips` queries are forwarded to the FIPS daemon's built-in DNS resolver
-  (127.0.0.1:5354), which resolves npub-based names to `fd::/8` addresses
+  (127.0.0.1:5354), which resolves npub-based names to `fd00::/8` addresses
 - All other queries are forwarded to Docker's embedded DNS (127.0.0.11)

 The `resolv.conf` mount points the container's resolver at 127.0.0.1,
@@ -165,7 +167,8 @@ From the app container:
 # Ping a mesh node by npub (resolves via .fips DNS):
 docker exec sidecar-nostr-relay-app-1 ping6 -c3 npub1xxxx.fips

-# Fetch a web page from a mesh node over FIPS:
+# Fetch a web page from some other mesh node over FIPS
+# (:8000 is a stand-in for that node's own service; this relay serves :80):
 docker exec sidecar-nostr-relay-app-1 curl -6 "http://npub1xxxx.fips:8000/"

 # Docker bridge is blocked — this should fail:
--- a/examples/sidecar-nostr-relay/entrypoint.sh
+++ b/examples/sidecar-nostr-relay/entrypoint.sh
@@ -70,6 +70,8 @@ iptables -A INPUT  -i eth0 -p udp --dport 2121 -j ACCEPT
 iptables -A INPUT  -i eth0 -p udp --sport 2121 -j ACCEPT
 iptables -A OUTPUT -o eth0 -p tcp --dport 443 -j ACCEPT
 iptables -A INPUT  -i eth0 -p tcp --sport 443 -j ACCEPT
+iptables -A INPUT  -i eth0 -p tcp --dport "${FIPS_TCP_BIND##*:}" -j ACCEPT
+iptables -A OUTPUT -o eth0 -p tcp --sport "${FIPS_TCP_BIND##*:}" -j ACCEPT
 iptables -A OUTPUT -o eth0 -j DROP
 iptables -A INPUT  -i eth0 -j DROP

--- a/examples/sidecar-nostr-relay/relay/config.toml
+++ b/examples/sidecar-nostr-relay/relay/config.toml
@@ -1,49 +0,0 @@
-# nostr-rs-relay configuration for FIPS mesh deployment.
-# Full reference: https://github.com/scsibug/nostr-rs-relay
-
-[info]
-# Shown in NIP-11 relay information document.
-relay_url = ""          # Set to ws://[<your-fips-ipv6>]:8080 after first start
-name = "FIPS Nostr Relay"
-description = "A Nostr relay accessible over the FIPS mesh network."
-pubkey = ""             # Optional: your npub (hex) as relay operator
-contact = ""            # Optional: contact address
-
-[database]
-# SQLite database path inside the container (mapped to relay-data volume).
-data_directory = "/usr/src/app/db"
-
-[network]
-# Bind on all interfaces (IPv4 + IPv6) — FIPS delivers traffic via the fips0
-# TUN as IPv6 (fd00::/8). Using 0.0.0.0 with port 8080; the relay also needs
-# to accept IPv6 connections so we set port separately and rely on the OS
-# dual-stack socket (IPV6_V6ONLY=0).
-# nostr-rs-relay address field is just the IP, port is separate.
-address = "0.0.0.0"
-port = 8080
-ping_interval_seconds = 300
-
-[limits]
-# Adjust to taste. These are conservative defaults for a personal relay.
-messages_per_sec = 10
-subscriptions_per_min = 20
-max_blocking_threads = 4
-max_event_bytes = 131072       # 128 KiB per event
-max_ws_message_bytes = 131072
-max_ws_frame_bytes = 131072
-broadcast_buffer = 16384
-event_persist_buffer = 4096
-
-[authorization]
-# Set to true to require NIP-42 AUTH before accepting events.
-# Useful for a private relay — only authenticated users can publish.
-nip42_auth = false
-nip42_dms = false
-
-[verified_users]
-# NIP-05 verification (optional).
-mode = "disabled"
-
-[pay_to_relay]
-# Lightning payments for relay access (optional).
-enabled = false
--- a/examples/wireguard-sidecar-macos/fips.yaml
+++ b/examples/wireguard-sidecar-macos/fips.yaml
@@ -20,7 +20,9 @@ transports:

 peers:
  - npub: "npub1zv58cn7v83mxvttl70w5fwjwuclfmntv9cnmv5wmz2nzz88u5urqvdx96n"
-    alias: "fips.v0l.io"
+    # alias becomes the peer's .fips hostname (<alias>.fips), so it must be a
+    # plain label with no dots — the connection address below is the real host.
+    alias: "v0l"
    addresses:
      - transport: tcp
        addr: "fips.v0l.io:8443"