Forward-merge the transport neighbor-beacon rename (ethernet + BLE
discovery -> neighbor module/buffer rename; ethernet config discovery
flag -> listen with serde alias). Hand-resolved the module files against
next's identity-out-of-beacon beacon rewrite by starting from next's
bodies and re-applying the rename by identifier, so next's beacon logic
(no-arg build_beacon, bool parse_beacon, computed BEACON_SIZE, one-arg
add_peer, deleted BLE add_peer_with_pubkey) is preserved unchanged.
Rename the Ethernet per-interface config flag from discovery to listen,
so the receive/transmit toggle pair reads as the symmetric announce
(transmit) / listen (receive) neighbor-beacon vocabulary. The old
discovery: key is still accepted via a serde alias, so deployed configs
load unchanged; to_yaml re-emits it under the canonical listen: name.
Marked deprecated for removal at the v2 cutover.
Updates the config field + accessor, the transport listen_enabled local,
the one struct-literal test consumer, the chaos sim config generator,
packaged fips.yaml examples, and the classified operator-facing docs
(ethernet neighbor-beacon subsystem prose; the generic Transport
discovery capability prose is left unchanged). Adds a compat parse test
asserting the legacy alias, the new key, and that deny_unknown_fields
still rejects unknown keys. Behavior-neutral.
Forward-merge the v0.4.0 pre-release content (dependency refresh, CI
deb-install + AUR-build legs, docs refresh, doc-comment fixes, and the
Phase 4 source-content squash: CHANGELOG, release notes, README,
fips.yaml, Cargo.toml metadata, reference docs) up the one-way flow.
Conflict fixups (keep next's identity, fold in master's improvements):
- Version: keep next's 0.5.0-dev (Cargo.toml/lock).
- README status: keep next's v0.5.0-dev / wire-format-breaking framing
and the Breaking-section pointer; fold in the Nym transport and the
"global, public test mesh of thousands of nodes" description.
- docs/reference/cli-fips.md: keep next's 0.5.0-dev version example.
- CHANGELOG: keep next's XX-handshake admission entry (no early cap gate
on XX) and drop master's IK early-cap-at-handle_msg1 entry, which
describes IK-only behavior that does not apply on next; take master's
OR-union mesh-size rewrite (next carries the OR-union code); restore
the Tor connect_refused and MMP receiver-report entries that the
Fixed-section consolidation would otherwise have dropped.
- lifecycle.rs: keep the mDNS/LAN handshake doc-comment as Noise XX
(next unifies on XX), not master's XX-to-IK correction.
Quartet green on the merged tree: fmt, build, clippy -D warnings, and
cargo test --lib (1434 passed).
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
The inbound FilterAnnounce FPR cap rejects filters whose false-positive
rate (fill^k) exceeds the configured maximum. On the fixed 1 KB / k=5
filter, 0.05 corresponds to fill 0.549 (~1,300 reachable entries), and
the busiest nodes' aggregates were beginning to hit that ceiling as the
mesh grew. Raise the default to 0.10 (fill 0.631, ~1,630 entries) to
restore headroom toward the fixed-filter capacity limit. A saturated or
poisoned filter is ~100% FPR and remains rejected, so the antipoison
gate is not materially weakened.
Updates the config default, the config-reference and bloom-filter
design docs, and the changelog.
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.
Forward-merge of 12 master commits past the previous merge
(823b830, master @ 18019bb): dep-audit bumps (rand,
clap, tun, rtnetlink, windows-service, plus the bump-safe
lockfile batch), bloom-storm chaos scenario, control-socket
resolver consolidation, gateway dns.listen default change,
OpenWrt ipk README refresh, gateway tutorial review, Ethernet
MTU rustdoc fix, dead session-variant drop, CHANGELOG prep.
Conflict resolution:
- CHANGELOG.md: both bullets kept under [Unreleased] / Fixed.
Master's spanning-tree internal-path-propagation fix precedes
next's tree-ancestry-test determinism entry and the
responder-Disconnect XX-handshake entry.
- src/protocol/session.rs: kept next's SessionSetup/SessionAck
variants and rustdoc. Master's drop of those variants suits
v0.3.0's FSP phase-byte dispatch but is undone by next's
v0.4.0 wire format, which retains the variants and uses the
inner msg_type byte for handshake identification.
- src/transport/ethernet/mod.rs: kept next's "interface MTU - 4"
comment. Master corrected the v0.3.0 3-byte rustdoc; next
redesigned the framing to a 4-byte header (type/flags/length)
for shared-media beacons, so master's correction does not
apply to next's format.
Auto-merged cleanly: Cargo.toml (next's 0.4.0-dev + the new dep
pins from master), Cargo.lock, all gateway docs,
docs/reference/configuration.md, packaging files,
.github/workflows/ci.yml, testing/chaos/sim/* and
testing/ci-local.sh (bloom-storm additions), src/config/*.
Local verification: cargo build --release, cargo test (1252
passed, 4 ignored), cargo clippy -D warnings, cargo fmt --check
all green.
The gateway is designed for systems already serving DHCP and DNS to
a LAN segment (canonically an OpenWrt AP). On those systems port 53
is already taken by the existing resolver, so the prior `[::]:53`
default conflicted with the gateway's intended deployment target out
of the box.
The OpenWrt ipk previously overrode this in its packaged config as a
workaround; matching the source default to what the canonical
deployment actually wants makes the override redundant and removes a
foot-gun for fresh manual Linux-host installs. The redundant
`dns.listen` line in `packaging/openwrt-ipk/files/etc/fips/fips.yaml`
is dropped along with this change.
Operators on a host without a pre-existing resolver on port 53 can
opt back into the wildcard bind by setting `dns.listen: "[::]:53"`
explicitly. The new default binds IPv6 loopback only — Linux IPv6
sockets bound to explicit `::1` do not accept v4-mapped traffic, so
forwarders that reach the gateway over IPv4 loopback need to be
pointed at an explicit IPv4 listen address instead.
Touches the gateway config struct and its default-value test, the
commented-out gateway example in the Debian common fips.yaml, the
OpenWrt ipk config (override removed), the gateway reference /
how-to / design / tutorial / troubleshoot docs, and a CHANGELOG
entry under [Unreleased] -> Changed.
Forward-merge of the docs-overhaul squash (5abf9a9) and top-level
README rewrite (18019bb). Conflict resolution:
- README.md: master's rewritten feature lists adopted, with the encryption
bullets reflecting next's two-layer Noise XX (replacing the IK/XK pair
master describes for v0.3.0).
- 6 design/reference markdown files (fips-bloom-filters.md, fips-mesh-layer.md,
fips-mesh-operation.md, fips-session-layer.md, fips-transport-layer.md,
reference/wire-formats.md): master's reorg taken, next's protocol details
preserved (XX handshake naming, bloom v2 RLE/delta wire format,
v2 LookupRequest sizing).
- fips-intro.md modify/delete: accepted master's split into
fips-architecture.md / fips-concepts.md / fips-prior-work.md, then
re-applied next's IK/XK -> XX transition and spin-bit removal across
the relevant split files. Same pass swept docs/reference/security.md,
docs/design/fips-mmp.md, docs/design/fips-security.md,
docs/design/fips-nostr-discovery.md,
docs/design/port-advertisement-and-nat-traversal.md,
docs/how-to/enable-nostr-discovery.md, and the affected tutorials so
no IK/XK or spin-bit prose remains in current-state docs.
- Diagram path conflicts: noise-ik-msg{1,2}.svg removed (IK is gone);
noise-xx-msg{1,2,3}.svg moved from docs/design/diagrams/ to
docs/reference/diagrams/ to match master's diagram reorg. The
wire-formats.md image references resolve correctly to the new path.
Local verification: cargo build --release, cargo test (1265 passed,
4 ignored), cargo clippy -D warnings, cargo fmt --check all green.
Restructures /docs/ by reader purpose (tutorials, how-to,
reference, design), adds the new-user-progression and
operator-recipe content the prior layout lacked, runs an
accuracy pass against current source across the pre-existing
design docs, and rewrites the gateway feature-set documentation
end-to-end around its actual operational profile (a niche
feature designed for systems already serving DHCP/DNS to a
LAN, with two independent halves — outbound LAN→mesh, inbound
mesh→LAN — sharing one nftables table, one binary, and one
control socket). Top-level README and getting-started rewritten
around two equally-weighted deployment modes (overlay on
existing IP networks; ground-up over non-IP transports).
## Additions
- 11 new tutorials in docs/tutorials/: an 8-step new-user
progression from single-daemon test-mesh peering through
to a ground-up two-device mesh, an IPv6-adapter side-trip
walkthrough, an Advanced Tutorials index, and a hand-held
OpenWrt walk-through for fips-gateway deployment that
exercises both halves of the feature.
- 12 new how-tos in docs/how-to/: firewall activation,
Nostr discovery (resolve / advertise / open across five
scenarios), Tor onion (directory + control_port modes),
UDP buffer tuning, unprivileged-user setup, persistent
identity, host aliases, Bluetooth LE peering, MTU
diagnostics, manual Linux-host gateway deployment (covers
both halves), gateway troubleshooting (organised by half),
and a section index.
- 9 new reference docs in docs/reference/: configuration,
wire formats, control-socket protocol, four CLI references
(fips, fipsctl, fipstop, fips-gateway), security posture
matrix, and Nostr events catalog. Configuration and
wire-formats are renamed-and-extended from prior design/
versions; the other seven are net-new.
- 6 new design docs: fips-concepts, fips-architecture, and
fips-prior-work split out of the deleted fips-intro.md;
consolidated fips-mmp and fips-mtu aggregations; and a
new generic port-advertisement-and-nat-traversal doc
(Nostr-signaled port advertisement plus UDP NAT-traversal
protocol, FIPS as an example implementation, suitable for
eventual NIP submission).
- Top-level docs/getting-started.md walking through the
binary-installer-only Install story.
- packaging/common/hosts pre-populated with the eight public
test-mesh nodes so shortnames resolve out of the box on
every fresh install.
## Changes
- 23 wire-format diagrams relocated to reference/diagrams/
alongside the wire-formats move.
- 4 design diagrams corrected against source code
(fips-protocol-stack, fips-identity-derivation,
fips-coordinate-discovery, fips-routing-decision).
- 10 pre-existing design docs reconciled with current
source. Numeric corrections: stale link-MMP report bounds
(now [1s, 5s] with 200 ms cold-start floor); UDP default
MTU (now 1280, IPv6 minimum); node_addr formula
(SHA-256(pubkey)[..16]); Noise patterns (IK at link, XK
at session); peer-ACL semantics (strict allowlist requires
ALL in peers.deny); daemon DNS upstream ([::1]:5354);
on-the-wire bloom-filter size (1,071 bytes); obsolete
Cargo-feature references (PR #79 dropped them) removed.
- Transport framing tightened across the docs: TCP is for
UDP-filtered networks (not NAT traversal); Tor is a
deployment mode (not failover); WebSocket dropped (not a
shipped FIPS transport); WiFi promoted to Implemented via
Ethernet in infrastructure mode; classic-Bluetooth row
removed (BLE is the only Bluetooth-mode transport).
- docs/design/fips-gateway.md rewritten end-to-end to lead
with the niche-feature framing and the two-halves
structure. Title moved from "FIPS Outbound LAN Gateway"
to "FIPS Gateway"; architecture section describes the
common machinery (the fips-gateway service, the nftables
table, the control socket) before splitting into separate
"Outbound Half" and "Inbound Half" sections of equal
weight; security considerations split per-half; no Future
Work section (speculative directions live in the project
tracker, not in protocol design docs). Inbound port
forwarding is a first-class half rather than a buried
"Implemented Extensions" subsection.
- Gateway terminology unified across all gateway docs as a
separate Linux service running alongside the fips daemon
(its own systemd unit / OpenWrt init script). Container-
pattern terms (sidecar) are reserved for the
Docker/Kubernetes sidecar deployment examples — the
testing/sidecar/ tree, examples/k8s-sidecar/,
examples/sidecar-nostr-relay/,
examples/wireguard-sidecar-macos/, and the related
CHANGELOG / top-level README entries — where the term
carries its standard container meaning.
- Net-new design body content: rekey section in
fips-mesh-layer (Noise IK msg1/msg2 over the established
link, K-bit cutover, drain window, smaller-NodeAddr-wins
tie-breaker on dual-init); Mesh Size Estimation and
Antipoison FPR Cap sections in fips-bloom-filters;
Mesh-Interface Query Filter subsection in
fips-ipv6-adapter; failure-suppression knobs and clock-
skew tolerance in fips-nostr-discovery; loop-rejection
and mid-chain ancestor swap added to spanning-tree
propagation / stability rules; Priority Chain in
fips-mesh-operation renumbered to match the
routing-decision diagram.
- Top-level README: dropped the stale nostr-discovery
cargo-feature parenthetical. docs/README.md and the four
section READMEs (tutorials, how-to, reference, design)
refreshed for the new structure; index rows reflect both
halves of the gateway feature and the new fips-gateway
CLI reference.
- Cargo.toml [package.metadata.deb] assets path updated for
the fips-security.md move; .gitignore /reference/ rule
anchored to repo root so docs/reference/ is trackable.
- packaging/openwrt-ipk/files/etc/fips/fips.yaml
configuration-doc URL updated to the new
docs/reference/configuration.md location.
## Deletions
- docs/design/fips-intro.md (split into the three new intro
design docs).
- docs/design/document-relationships.svg (orphan, no longer
referenced).
- docs/proposals/ tree removed; the only proposal it
contained (the Nostr UDP hole-punch protocol) was
rewritten as the new generic
design/port-advertisement-and-nat-traversal.md.
Johnathan Corgan