mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
docs: reviewer feedback pass on Nostr-discovery surface
Walk through reviewer feedback on the Nostr-discovery docs and land 18 items. Bulk patterns: - `external_addr` / `public: true` semantics consistently misdescribed. The advert path is gated on `cfg.is_public()`; inside that branch the daemon picks an address by precedence (`external_addr`, non-wildcard `bind_addr`, STUN). The docs treated `public: true` and `external_addr` as alternatives when they are stacked: `public: true` is the master switch and `external_addr` populates the address inside it. Reconciled across `enable-nostr-discovery.md` and `advertise-your-node.md`: add `public: true` to the `external_addr` examples; replace "STUN as a logging cross-check" with "STUN is skipped entirely"; fix "neither flag is needed" for direct public bind (both flags still required); make the publish-tutorial Step 3 conditional on the chosen Step 2 path (STUN runs only on the `public: true` path); rewrite the troubleshooting "wrong public IP advertised" bullet with two coherent fixes. - `udp:nat` overpromised as a symmetric-NAT solution. Symmetric NAT on either side typically defeats the punch. Reframe `udp:nat` as best-effort hole-punching for nodes without a directly reachable UDP endpoint in the how-to, the publish tutorial (intro, callout, section heading rewrite from "If you're behind symmetric NAT" to "If your direct UDP advert isn't reachable"), the consume tutorial's "What's next" pointer, and `tutorials/README.md`. Promote reachability over named NAT classes: STUN can confirm the public IP but not that the listener-port mapping is open. - YAML "silently ignores unknown keys" is wrong. Config parser rejects unknown fields via `serde(deny_unknown_fields)` on the per-section structs; misspelled fields refuse the daemon's start with a parse-error line in the journal. Fixed in the publish tutorial's troubleshooting and the open-discovery tutorial's `policy` typo bullet. Mechanical fixes: - Repoint stale anchors. `getting-started.md` and `configuration.md` linked to `#installation` / `#inspect` on the README; the README has no such headings. Repoint to `#quick-start` and `cli-fipsctl.md`. Two stale anchors in the publish tutorial pointing at non-existent sub-scenarios in the how-to (`#sub-scenario-2c-...`, `#sub-scenario-2b-tor-onion-node`) repointed to the correct anchors. - Drop the `fipsctl show status` claim from the open-discovery troubleshooting bullet (`show_status` doesn't include `discovery.nostr.policy`). Replace with daemon startup logs. - Fix the `advertise: false` parenthetical in the consume-only tutorial (`default_advertise()` returns `true`; we set `false` explicitly for the consume-only path). - Drop the "supplies a relay list" overstatement in two activation paragraphs (the how-to and the design doc). Default relay / STUN-server lists ship in the config; both are optional overrides. - Add the missing `transports.udp.public` entry to the open-discovery tutorial's prerequisites checklist. Tutorial users coming out of advertise-your-node could be on either the direct-UDP (`public: true`) or `udp:nat` (`public: false`) path; list both. Files: docs/getting-started.md, docs/reference/configuration.md, docs/how-to/enable-nostr-discovery.md, docs/tutorials/README.md, docs/tutorials/advertise-your-node.md, docs/tutorials/resolve-peers-via-nostr.md, docs/tutorials/open-discovery.md, docs/design/fips-nostr-discovery.md.
This commit is contained in:
@@ -4,7 +4,8 @@ Nostr-mediated discovery lets FIPS nodes find each other (and punch
|
||||
through UDP NAT) using public Nostr relays as the signaling channel.
|
||||
The feature ships in every stock packaging artifact but is **off by
|
||||
default** — it activates when an operator sets
|
||||
`node.discovery.nostr.enabled: true` and provides a relay list. See
|
||||
`node.discovery.nostr.enabled: true`. Default relay and STUN-server
|
||||
lists ship in the config; both are optional overrides. See
|
||||
[../design/fips-nostr-discovery.md](../design/fips-nostr-discovery.md)
|
||||
for the design and rationale; see
|
||||
[../reference/configuration.md](../reference/configuration.md) for the
|
||||
@@ -126,15 +127,20 @@ transports:
|
||||
udp:
|
||||
bind_addr: "0.0.0.0:2121"
|
||||
advertise_on_nostr: true
|
||||
external_addr: "203.0.113.45:2121" # ← explicit
|
||||
public: true # ← required, master switch
|
||||
external_addr: "203.0.113.45:2121" # ← explicit address
|
||||
```
|
||||
|
||||
`external_addr` accepts a bare IP (combined with the bind port) or a
|
||||
full `host:port`. Setting both `public: true` and `external_addr`
|
||||
together is allowed — the explicit override wins, with STUN as a
|
||||
logging cross-check. If UDP is bound directly to a public IP rather
|
||||
than to a wildcard, neither flag is needed; the daemon advertises
|
||||
the bound endpoint.
|
||||
full `host:port`. `public: true` is the master switch that gates UDP
|
||||
advertisement; inside that branch, the daemon picks the advertised
|
||||
address in precedence order: explicit `external_addr` (no STUN
|
||||
observation), a non-wildcard `bind_addr`, or STUN auto-discovery.
|
||||
Setting `external_addr` alongside `public: true` skips STUN entirely
|
||||
— there is no logging cross-check. If UDP is bound directly to a
|
||||
public IP rather than to a wildcard, neither `external_addr` nor STUN
|
||||
is needed — but `advertise_on_nostr: true` and `public: true` are
|
||||
still both required for the daemon to publish the endpoint.
|
||||
|
||||
What this achieves: the node publishes a single
|
||||
`udp:<public-ip>:2121` endpoint to the three default advert relays
|
||||
@@ -202,9 +208,17 @@ proceeds normally.
|
||||
> a `udp:nat` advert without signaling relays or STUN servers is
|
||||
> unreachable by construction.
|
||||
|
||||
Works best with full-cone NAT on at least one side. Symmetric NAT on
|
||||
both sides is not reliably traversable with this protocol and will
|
||||
time out after `punch_duration_ms`.
|
||||
Hole-punching is best-effort. It works reliably when both sides are
|
||||
full-cone or port-restricted NATs. Symmetric NAT on either side
|
||||
typically defeats the punch — the public port a peer sees varies per
|
||||
remote endpoint, so the address learned via STUN does not match the
|
||||
mapping the peer actually needs. The punch attempt times out after
|
||||
`punch_duration_ms`. `udp:nat` is the only NAT-traversal mechanism
|
||||
in FIPS; when it can't succeed, there's no in-protocol substitute.
|
||||
Being reachable then becomes a deployment-prerequisite question
|
||||
rather than a transport question — a publicly reachable port (UDP
|
||||
or TCP — both require the same kind of network resource) published
|
||||
as a direct advert per Sub-scenario 2a or 2b.
|
||||
|
||||
### Sub-scenario 2b: TCP
|
||||
|
||||
|
||||
Reference in New Issue
Block a user