mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
f624013b834b480cfe0aee1f8a916933207d9c59
16
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
  ArjenandGitHub
|
f624013b83 |
feat(openwrt): open !FIPS access SSID layer (#126)
Access layer for phones and laptops to reach FIPS routers on OpenWrt, stacked on the 802.11s mesh backhaul from #123. Squashed from five commits by Arjen (Origami74); their original messages follow. * feat(openwrt): open !FIPS access SSID — fips-ap-setup helper, default transport binding, how-to Client access layer for phones and laptops: every FIPS router broadcasts the same open SSID ('!FIPS' — the leading '!' sorts it to the top of alphabetically ordered network pickers), forming one standard ESS. Clients save it once and roam between all FIPS routers natively, with FIPS's Noise IK handshake as the only security layer: - fips-ap-setup: opt-in UCI helper that creates the 'fips-ap0' open AP (encryption none — security type must be uniform across routers or clients treat the ESS as different saved networks), an isolated network with a static ULA /64, RA-only odhcpd addressing (stateless SLAAC, no DHCP — the minimum that satisfies Android's provisioning check; no internet by design, so phones keep cellular as default route), and a locked-down fips_ap firewall zone (no path to br-lan or the WAN; only ICMPv6, mDNS, and the FIPS transports reachable). 'remove' subcommand undoes it. Radio setup stays opt-in; a package must not commandeer radios on install. - fips.yaml: ship 'ap0'/'ap1' Ethernet-transport entries commented out (matching the 802.11s mesh backhaul) so a stock install that never creates fips-ap* logs no per-boot "interface missing" bind warning; fips-ap-setup uncomments the matching block when it creates the interface and re-comments it on remove. - Regression test: extend shipped_openwrt_config_parses to assert the ap0/ap1 entries ship commented out and still parse once uncommented, alongside mesh0/mesh1. - Packaging: install the helper in ipk/apk/buildroot (three synced copies), extend CI structural checks and shellcheck targets. - docs/how-to/set-up-open-access-ssid.md: full guide, including the one-time 'no internet, stay connected' acceptance (stored per SSID, covers every FIPS router) and the security-type-uniformity constraint. * docs(openwrt): correct open-SSID/mesh security framing — peering is open by design The fips-ap-setup/fips-mesh-setup comments and both how-tos claimed a stranger "cannot pass the FIPS handshake" / "their frames die at the handshake" / the handshake surface "drops them". That is wrong: FIPS peer admission is open. An inbound handshake from any net-new identity is promoted (node::handlers::handshake::promote_connection), gated only by the daemon's max-peers cap — there is no allowlist, no PSK, and the AuthChallenge path is not wired to admission. The Noise IK handshake provides authentication (no impersonation of another identity, no MITM), not authorization. Restate the model accurately in all five places: a stranger on the open SSID (or the open mesh) can associate AND form a FIPS peer link — that is the point of open access. Containment is the isolated fips_ap zone (no path to br-lan or the WAN) plus the max-peers cap, not the handshake. Clarify that AP client isolation is an L2 control only: a peered stranger is an overlay peer like any other, so the FIPS overlay, not L2, is the trust boundary between clients. * feat(openwrt): serve DHCPv4 on the access SSID from a fixed roamable subnet RA-only addressing satisfied Android's provisioning check but left anything expecting IPv4 with a self-assigned address and a "no IP" complaint. dnsmasq now leases out of 10.21.<N>.0/24 (N = radio index; prefix echoes FIPS port 2121), deliberately identical on every router: a roaming client keeps its lease across the ESS, and dnsmasq's authoritative mode — the OpenWrt default, pinned by the helper — ACKs the renew a foreign router never issued. Lease collisions across routers surface as a NAK on renew and the client re-DHCPs. The dhcp section's 'dhcpv4 server' is read by both dnsmasq (default images) and odhcpd (only with maindhcp), so either arrangement serves. A DHCPv4/udp-67 accept rule joins the fips_ap zone; DHCPv6 stays off, the ULA RA stays as-is, and nothing depends on an upstream. The zone remains isolated — no forwardings, no internet. * feat(openwrt): enable mDNS rendezvous from fips-ap-setup Phone FIPS apps cannot open raw-Ethernet sockets, so DNS-SD is how they find the router's daemon — but node.rendezvous.lan defaults to off. Ship the lan block commented in fips.yaml (consistent with the apN transport entries) and have fips-ap-setup uncomment it when creating the access SSID. The awk match is scoped to node.rendezvous because transports.ethernet carries a 'lan' entry at the same indent. The switch is daemon-wide, so 'remove' deliberately leaves it on rather than guess whether other transports rely on it. * fix(openwrt): bind UDP dual-stack [::]:2121 so access-SSID clients reach it The shipped router config bound the UDP transport "0.0.0.0:2121" (IPv4 wildcard) while the mDNS LAN advert announces every interface address, including the router's IPv6 link-local — which phones on the !FIPS access SSID rightly prefer (their cellular default route swallows v4, and fd00::/8 is captured by the Myco mesh TUN). Result: the client's Noise msg1 arrives on an unbound v6 port and is silently lost; the handshake resends and times out. Symptom chain (observed on-device): mDNS resolve OK, platform push OK, "Sent Noise handshake message 1" to [fe80::…%N]:2121, four resends, no reply, 30 s stale-timeout. OpenWrt is Linux (bindv6only=0), so "[::]" accepts IPv4 via v4-mapped addresses too — nothing is lost. packaging/common is deliberately left on "0.0.0.0" for now: Windows defaults IPV6_V6ONLY=1, where "[::]" would drop v4 instead. |
||
 ArjenandJohnathan Corgan
|
054d17aac5 |
feat(openwrt): 802.11s open-mesh backhaul support
Router-to-router radio backhaul over an open 802.11s mesh interface, with FIPS providing all encryption (Noise IK), authentication, and routing on top of bare L2 neighbor links. The mesh runs OPEN with mesh_fwding 0 — SAE would duplicate the Noise layer and force ath10k raw mode, and FIPS is the routing layer — so the Noise handshake is the real auth/encryption boundary and FIPS's spanning tree does the routing. fips-mesh-setup: an opt-in UCI helper that creates a per-radio mesh-point interface (radio0 -> fips-mesh0, radio1 -> fips-mesh1; trailing-digit derivation with a free-index fallback and a collision guard). Radio setup stays opt-in — a package must not commandeer radios on install. 'remove' takes an optional radio and otherwise removes all instances. Dual-band routers get one instance per radio; FIPS treats the two backhaul paths as failover, not multipath: it keeps one active link per peer (cross-connection resolution picks a single winner), and the second band stands by, re-establishing the peer after keepalive timeout — traffic never uses both bands at once. fips.yaml ships the mesh0/mesh1 Ethernet-transport entries commented out, so a stock install that never creates fips-mesh* logs no per-boot "interface missing" bind warning. fips-mesh-setup uncomments the matching meshN block when it creates the interface and re-comments it on remove, so the flash-and-drop-in flow needs no manual config edit. The file is rewritten 0600-first (it may hold an inline nsec) via an atomic replace. Two field-found silent non-peering causes are surfaced by the helper and the guide: - Same channel: mesh points only peer on a shared channel, and 'auto' lets each radio pick its own. The helper prints the radio's band/channel and warns loudly on 'auto' with the exact uci command to pin one; the how-to gains an ordered no-peers triage (channel mismatch, on-air scan check, DFS CAC wait, regdomain). - STA channel capture: a client (sta) interface drags the whole radio to its upstream AP's channel, so a mesh pinned elsewhere never joins and does not recover until the STA disconnects. The helper warns when the target radio carries a STA; the guide documents the incompatibility of a roaming uplink with a fixed-channel mesh on the same radio. Both the create and remove paths run 'wifi reload', which briefly drops every client AP on all radios; the how-to sets that expectation. Regression test: the shipped OpenWrt fips.yaml must parse via the real Config deserializer in both states — as shipped (mesh inactive) and after the uncomment the helper performs. Packaging: the helper is installed across the ipk/apk/buildroot paths (three synced copies), with the CI structural checks and shellcheck targets extended to cover it. Full guide in docs/how-to/set-up-80211s-mesh-backhaul.md. |
||
|
Johnathan Corgan
|
3ea7ca1fd1 |
ci(openwrt): retry Blossom upload and skip nostr event on failure
A transient timeout uploading the built .ipk to the Blossom CDN (blossom.primal.net) failed the entire OpenWrt Package run, and because the GitHub release job depends on the build jobs, a CDN blip would block every OpenWrt artifact from the release. Blossom/nostr distribution is supplementary; the package already ships as a GitHub release artifact. Wrap the upload in a 3-attempt retry with backoff to absorb transient timeouts, mark the step continue-on-error so a persistent outage no longer fails the build, and guard the NIP-94 publish on the upload succeeding so no event is created with an empty URL. Applied to both the .ipk and .apk build jobs. Claude-Session: https://claude.ai/code/session_01A2pYfSypNmmG4HyHwZuLex |
||
|
ArjenandJohnathan Corgan
|
0f1fd18c25 |
packaging(openwrt): SDK-free .apk build for OpenWrt 25+ and control-socket fix
Add OpenWrt .apk packaging for OpenWrt 25+, where apk-tools is the mandatory package manager. The existing .ipk continues to cover OpenWrt 24.x and earlier. Built SDK-free like the .ipk: it reuses the cargo-zigbuild cross-compile and the shared installed-filesystem payload under openwrt-ipk/files, and assembles the ADB container with the official `apk mkpkg` applet from apk-tools 3.0.5 built from source, so no OpenWrt SDK image is needed. The package-openwrt workflow is refactored so a single compile-binaries job cross-compiles and strips each arch once; both the .ipk and .apk packagers consume the binaries via a new --bin-dir flag instead of each recompiling. A build-apk job (aarch64, x86_64) builds apk-tools, packages, and structurally verifies the .apk with `apk adbdump`. Releases now publish .apk artifacts and checksums alongside .ipk; the release download is scoped to fips_* so the shared raw-binary artifacts are not swept into the published release. apk-version.sh maps a release tag or commit height to an apk-tools-valid version, covered by a case-table test. Packages are unsigned, installed with `apk add --allow-untrusted`, matching the .ipk posture. Also fix the OpenWrt control socket: the init script now pre-creates /run/fips before starting the daemon, the procd equivalent of the systemd unit's RuntimeDirectory=fips. Without it, on a fresh boot the daemon resolves its control socket to /tmp (since /run/fips does not yet exist), while fips-gateway later creates /run/fips for its own gateway.sock, leaving fipsctl/fipstop resolving a /run/fips/control.sock the daemon never bound. |
||
|
ArjenandJohnathan Corgan
|
effd69bd53 |
ci(openwrt): bump Node 20 actions to Node 24 majors
checkout v4->v6, cache v4->v5, upload-artifact v4->v7, download-artifact v4->v8 to clear the Node 20 runner deprecation. |
||
|
Johnathan Corgan
|
3749853716 |
packaging(openwrt): publish checksums-openwrt.txt alongside .ipk artifacts
The linux/macos/windows package workflows each publish a checksums-<platform>.txt sha256 file with their release artifacts, but the OpenWrt workflow attached only the .ipk files with no checksum coverage. Generate checksums-openwrt.txt over the .ipk outputs using the same sha256sum idiom as the other platforms and add it to the release file set. |
||
|
Johnathan Corgan
|
c7218d8486 |
ci: align local/GitHub integration coverage and pin the toolchain source
Bring the local runner (testing/ci-local.sh) and GitHub CI into agreement on two axes. Suite coverage: the admission-cap integration suite ran only locally, so a regression in it could never turn the GitHub gate red. Add an admission-cap leg to the integration matrix, add testing/check-ci-parity.sh (wired as 'ci-local.sh --check-parity') to diff the two suite sets and fail on unexpected drift, and document the deliberate local-only (live-Tor) and granularity-only differences in a comment block atop both runners. Toolchain selection: every CI and packaging job installed its toolchain with dtolnay/rust-toolchain@stable, but the rust-toolchain.toml channel pin overrode it for all compilation, wasting an install and printing a misleading rustc version. Switch the stable call sites to actions-rust-lang/setup-rust-toolchain, which reads rust-toolchain.toml as the single source of truth. Keep the explicit cache steps (cache: false on the new action), set rustflags empty so the action does not impose a global -D warnings the previous setup never applied, fold the macOS cross-compile target into the action input, and leave the OpenWrt nightly Tier-3 leg on dtolnay/rust-toolchain@nightly. |
||
 Martti MalmiandJohnathan Corgan
|
9b1016ffaf |
ci: correct OpenWrt MIPS-disabled comment to locate the actual blocker
Investigated the mipsel-unknown-linux-musl build of this branch on a
Linux/x86_64 host. ring 0.17, portable-atomic, and the fips codebase
itself all compile cleanly for that target — the AtomicU64 portability
work is already done. The actual blocker is in the nostr-relay-pool 0.44
transitive dep, which uses std::sync::atomic::AtomicU64 directly in
src/relay/{stats,ping,flags}.rs. Verified fixable with a 6-line
portable-atomic patch via a [patch.crates-io] shim during local testing.
Updating the comment so the next person looking at this matrix has the
right starting point.
No functional change.
|
||
|
Johnathan Corgan
|
5c92fffa2b |
Extend shellcheck excludes for OpenWrt rc.common and ash conventions
The package-openwrt.yml shellcheck step was failing on warnings that
are false positives for OpenWrt scripts:
SC2034 — USE_PROCD, START, STOP in /etc/init.d scripts are read by
rc.common, not by the script itself; standard shellcheck
cannot see the indirection.
SC3043 — `local` is undefined in strict POSIX sh, but OpenWrt uses
ash which supports it. The init scripts use `local`
extensively for parameter scoping.
SC2086, SC2089, SC2090 — firewall.sh constructs nft match clauses
with literal quotes that need to survive variable expansion
(`match='iifname "$TUN"'` then `nft ... $match accept`). The
lack of double-quoting around `$match` is intentional so
word-splitting yields separate nft arguments.
Adding these to the exclude list. SC2317 (unreachable code) and
SC1008 (rc.common shebang form) were already excluded.
|
||
|
Johnathan Corgan
|
616010f8c8 |
Verify package structural correctness across macOS, Windows, and OpenWrt builds
Add post-build structural verification steps to the three platform packaging workflows so structural defects abort before checksum/upload. The .pkg/.zip/.ipk builds run on tag (or every push for OpenWrt) but their output layouts were unverified — silent drift could ship missing binaries, broken plists, or malformed package containers that would only surface at install time. Field operators rely on manual validation; CI now catches packaging regressions before release. macOS (.github/workflows/package-macos.yml): The pkg is a pkgbuild component flat package; pkgutil --expand yields the structure but actual files live inside Payload (cpio.gz). The verification step extracts that with gzip -dc | cpio -i, then asserts: - usr/local/bin/fips, fipsctl, fipstop all present - Library/LaunchDaemons/com.fips.daemon.plist present - plutil -lint on the plist returns zero Each check prints PASS/FAIL; verifier dumps the full extracted tree on failure for diagnosis. Codesigning verification deferred (pkgbuild invocation has no --sign — nothing to verify yet). Windows (.github/workflows/package-windows.yml): build-zip.ps1 produces a flat archive (no wrapper directory) via Compress-Archive -Path "$StagingDir\*". The verifier extracts and asserts each expected file at the extract root: fips.exe, fipsctl.exe, fipstop.exe (binaries) fips.yaml, hosts (config from packaging/common/) install-service.ps1, uninstall-service.ps1 (from packaging/windows/) README.txt (generated inline by build script) Each check prints PASS/FAIL; verifier dumps the full extracted listing on failure for diagnosis. LICENSE intentionally not asserted: the build script does not currently ship one, and asserting on it would false-fail every build. OpenWrt (.github/workflows/package-openwrt.yml): Add four post-build verification steps between Build .ipk and SHA-256 hashes. The ipk build runs every push but its contents, shell-script lint state, and sysctl drop-in syntax were unverified. Steps: 1. Install shellcheck (conditional — pre-installed on ubuntu-latest; apt-get install fallback only if missing). 2. Lint init/uci/hotplug/firewall scripts: run shellcheck --shell=sh --exclude=SC1008,SC2317 against the 5 shipped #!/bin/sh scripts (fips, fips-gateway, firewall.sh, 99-fips hotplug, 90-fips-setup uci-default). SC1008 silences the rc.common shebang form; SC2317 silences "unreachable" warnings for externally-invoked rc.common hooks. 3. Sysctl drop-in syntax: per-line regex check against both fips-gateway.conf and fips-bridge.conf. 4. Verify ipk structural integrity: extract via tar -xzf (OpenWrt's actual format despite the misleading "ar archive" comment in build-ipk.sh), assert all three top-level entries (control.tar.gz, data.tar.gz, debian-binary), assert 14 file paths in data.tar.gz (binaries, init scripts, configs, sysctl drop-ins, hotplug + uci-defaults + sysupgrade keep), and assert the 4 control-tarball entries plus debian-binary content "2.0". Full ipk install/runtime test deferred past v0.3.0 scope. Operator-side note: testing/ci-local.sh NOT modified for the OpenWrt verifier (operators don't typically have the cross-compile toolchain locally). |
||
|
34e00b9f6e |
Add Nostr-mediated overlay discovery and UDP NAT traversal (#53)
Optional peer discovery and NAT hole-punching path gated behind a new
`nostr-discovery` cargo feature. Nodes publish signed overlay endpoint
adverts to public Nostr relays, consume peer adverts to populate
fallback dial addresses, and use STUN-assisted UDP hole punching with
NIP-59 gift-wrap offer/answer signaling to establish direct UDP paths
between NATed peers. Once a punched socket is up, it is handed into
the existing FIPS UDP transport and the standard Noise/FMP session
stack takes over unchanged.
The cargo feature is in the default feature set
(`default = ["nostr-discovery"]`) so stock builds include it; a
build that explicitly disables default features (or selects a
feature set without `nostr-discovery`) does not link the nostr /
nostr-sdk crates and does not emit a no-op poll in the tick loop.
Runtime behavior is independently gated by
`node.discovery.nostr.enabled`, which defaults to false; if the
config enables Nostr on a non-feature build, startup logs a
warning and continues without it.
== Cargo feature and dependencies
- New cargo feature `nostr-discovery = ["dep:nostr", "dep:nostr-sdk"]`.
Not in the default feature set.
- New optional Linux-only dependencies: `nostr 0.44` (features: std,
nip59) and `nostr-sdk 0.44`. Gift-wrap unwrap is hand-rolled in
`src/discovery/nostr/signal.rs` rather than relying on the SDK's
rumor-author check, which FIPS sidesteps by trusting `seal.pubkey`
exclusively.
== Wire format
Overlay advert event: `kind 37195`, parameterized replaceable
(NIP-01 application-defined replaceable range 30000-39999), with
`d = "fips-overlay-v1"`. The digits visually spell FIPS (7=F, 1=I,
9=P, 5=S); a relay survey confirmed the kind is unused.
Advert content carries the version tag, endpoint list
(`udp|tcp|tor` + addr), optional signal-relay and stun-server
metadata, and `issuedAt` / `expiresAt` timestamps. Endpoint
`addr: "nat"` is the sentinel that triggers traversal on the peer
side. NIP-40 `expiration` tag bounds staleness on permanent
shutdown. Lifecycle relies on parameterized-replaceable
supersession; the daemon does not emit NIP-09 kind-5 deletes —
strict relays (Damus, Primal) race delete-against-replace and can
silently drop the replacement.
Gift-wrapped signal event: `kind 21059`. Punch packets carry magic
values `PUNCH_MAGIC` / `PUNCH_ACK_MAGIC`, a sequence number, and a
16-byte session hash.
== Discovery surface
- `src/discovery.rs` (always compiled)
- `EstablishedTraversal`: bound UDP socket + selected remote +
peer npub + optional transport name/config tuning overrides.
- `BootstrapHandoffResult`: returned on successful handoff —
allocated transport id, local/remote addrs, peer NodeAddr,
session id.
- `src/discovery/nostr/` (`#![cfg(feature = "nostr-discovery")]`)
- `types.rs`: wire and control types described above. `ADVERT_KIND`
constant. `BootstrapError` enumerates failure modes (disabled,
missing advert, missing NAT endpoint, no usable relays, invalid
advert, invalid npub, signal timeout, punch timeout, replay,
STUN failure, protocol, nostr, io, serde, event-parse).
- `runtime.rs`: `NostrDiscovery` coordinator. Owns the shared
nostr-sdk `Client`, subscribes to advert + signal event kinds,
maintains a bounded advert cache and a bounded seen-sessions
replay set, drains `BootstrapEvent::{Established, Failed}` for
the node to consume, exposes `update_local_advert`,
`request_connect`, `advert_endpoints_for_peer`,
`cached_open_discovery_candidates`, and `shutdown`.
- `signal.rs`: NIP-59 gift-wrap encode/decode. Outbound wraps are
built against per-attempt ephemeral keys; inbound events are
unwrapped against the node identity.
- `stun.rs`: RFC 5389/8489 Binding Request client with
XOR-MAPPED-ADDRESS parsing for both IPv4 and IPv6; used only to
observe the initiator's own reflexive address against its
locally configured STUN list (peer-advertised STUN is
informational, never an egress target).
- `traversal.rs`: per-attempt candidate-pair punch planner.
Allocates a fresh `0.0.0.0:0` UDP socket per attempt, enumerates
LAN-private and ULA interface addresses alongside the STUN
reflexive address, schedules probe/ack exchanges at the
configured interval for the configured duration, and picks the
first candidate pair that authenticates end-to-end.
Strategy ordering is Reflexive↔Reflexive first, then LAN, then
Mixed. The STUN-observed pair is the only candidate that's reliable
across arbitrary network topologies; trying it first prevents the
planner from latching onto a misleading host-candidate path before
the reflexive path gets a chance. There is no catch-all
Local↔Local strategy: a previous design that paired every local
host candidate from one side with every local host candidate from
the other could declare success on a one-way reachable asymmetric
L3 path (corporate VPN, Tailscale subnet route, overlapping private
address space), only for the FMP handshake to stall because the
return path didn't match. The legitimate `Lan` strategy still pairs
candidates that share a subnet.
== Configuration surface
`node.discovery.nostr.*` (`NostrDiscoveryConfig`), all `serde(default)`
with `deny_unknown_fields`:
- `enabled` (default false), `advertise` (default true)
- `advert_relays`, `dm_relays`, `stun_servers`: defaults are
`wss://relay.damus.io`, `wss://nos.lol`, `wss://offchain.pub`
for both relay lists, and Google / Cloudflare / Twilio for STUN.
Operators are expected to override for production. Other
verified-working public relays for reference:
`nostr.bitcoiner.social`, `nostr-pub.wellorder.net`,
`nostr.oxtr.dev`, `nostr.mom`.
- `app` (default `"fips-overlay-v1"`), `signal_ttl_secs` (120)
- `policy`: `NostrDiscoveryPolicy::{Disabled, ConfiguredOnly (default),
Open}` — controls whether advert-derived endpoints are consumed
only for peers carrying `via_nostr = true`, or also for
non-configured peers within a budget cap.
- `share_local_candidates` (default false) — when false, the offer's
`local_addresses` list is empty and peers see only the reflexive
address. Enable per-node only for genuinely same-LAN deployments;
off-by-default eliminates the misleading-path failure mode for
the common case where peers are not on the same broadcast domain.
- `open_discovery_max_pending` (64) — caps queued open-discovery
retries; bounded by available outbound slots.
- `max_concurrent_incoming_offers` (16) — semaphore against offer
spam; excess offers are debug-logged and dropped.
- `advert_cache_max_entries` (2048) and `seen_sessions_max_entries`
(2048) — bound memory under ambient relay volume; overflow
evictions are debug-logged.
- `attempt_timeout_secs` (10), `replay_window_secs` (300)
- `punch_start_delay_ms` (2000), `punch_interval_ms` (200),
`punch_duration_ms` (10000)
- `advert_ttl_secs` (3600), `advert_refresh_secs` (1800)
Per-peer and per-transport flags:
- `PeerConfig.via_nostr: bool` — when true (and Nostr is enabled),
advert-derived addresses are appended as fallback dial candidates
after static addresses for that peer.
- `PeerConfig.addresses` is now `serde(default)` and may be empty
when `via_nostr: true`; validation requires at least one of the
two to be present per peer, and the error message names the
peer's npub.
- `UdpConfig.advertise_on_nostr: Option<bool>` and
`UdpConfig.public: Option<bool>` — UDP transports can be
advertised either as direct `host:port` (public = true) or as the
`addr: "nat"` sentinel that triggers rendezvous on the peer side.
- `TcpConfig.advertise_on_nostr` and `TorConfig.advertise_on_nostr`
— TCP and Tor onion endpoints can be advertised as directly
reachable.
- A reserved peer address `transport: udp, addr: "nat"` parses without
special-casing in YAML and routes through the bootstrap runtime.
Cross-field validation (`Config::validate`, called from `Node::new`
and `Node::with_identity`):
- Any transport with `advertise_on_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- Any peer with `via_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- A non-public UDP advert (`advertise_on_nostr = true`,
`public = false` — i.e. `udp:nat`) additionally requires at least
one `dm_relay` and at least one `stun_server`.
Surfaced as `ConfigError::Validation`.
== Node integration
`src/node/lifecycle.rs` is the main integration point.
- At node start (after transports are up, before TUN), if Nostr is
enabled and the feature is compiled in, `NostrDiscovery::start` is
invoked, the initial local overlay advert is built from the live
transport set and published, and the runtime handle is stored.
- The rx tick loop calls `poll_nostr_discovery` (feature-gated both
at method definition and call site), which refreshes the local
advert, drains bootstrap events, adopts established traversals,
schedules retries for failed traversals, and — under `policy:
open` — enqueues outbound retries for non-configured peers
visible in the advert cache, bounded by
`open_discovery_max_pending` and the remaining outbound slots.
- Outbound peer dialing is refactored to `try_peer_addresses`, which
first exhausts the static address list in priority order and only
then appends advert-derived fallback addresses; both lists run
through the same `attempt_peer_address_list` code path. The
`udp:nat` sentinel address triggers `NostrDiscovery::request_connect`
for the peer instead of a direct dial and returns `Ok(())`.
- `build_overlay_advert` walks operational transports, consults
per-instance `UdpConfig` / `TcpConfig` / `TorConfig` (matching by
optional transport instance name), and emits an `OverlayAdvert`
including `signalRelays` and `stunServers` when any UDP endpoint
is advertised as NAT.
- `adopt_established_traversal` is the bootstrap handoff API:
allocates a new `TransportId`, constructs a `UdpTransport` with
the user-supplied (or default) `UdpConfig`, calls the new
`adopt_socket_async` to reuse the punched socket verbatim,
registers the transport in the normal transport map, records it
in `bootstrap_transports`, and calls `initiate_connection` so the
normal handshake path runs. On failure, the transport is stopped
and removed cleanly and the set membership is rolled back.
- On clean shutdown, `NostrDiscovery::shutdown` is awaited so
background tasks stop before transports are torn down. (The
advert is not explicitly retracted; NIP-40 expiration plus the
next refresh from any live publisher supersedes it.)
New `Node` fields:
- `nostr_discovery: Option<Arc<NostrDiscovery>>` (feature-gated).
- `bootstrap_transports: HashSet<TransportId>` — per-peer UDP
transports adopted from NAT traversal, cleaned up via
`cleanup_bootstrap_transport_if_unused` whenever the link,
connection, peer, or pending-connect referencing them is removed.
Retry and error surface:
- `RetryState.expires_at_ms: Option<u64>` — optional absolute expiry
for a retry entry. `pump_retries` drops expired entries with an
info log. Used for open-discovery retries, which expire at two
times the advert TTL.
- New `NodeError::BootstrapHandoff(String)` returned from
`adopt_established_traversal` when the underlying transport
adoption fails or local address discovery fails.
- New `ConfigError::Validation(String)`.
- A small refactor extracts `Node::now_ms()` and reuses it across
lifecycle, rx-loop tick, and timeout bookkeeping.
== UDP transport
`src/transport/udp/`:
- `UdpRawSocket::adopt(std::net::UdpSocket, recv_buf, send_buf)`:
adopts an externally bound socket, makes it non-blocking, applies
the configured buffer sizes (warning if the kernel clamps), and
reports the resulting local address. Preserves the NAT mapping —
no rebind.
- `UdpTransport::adopt_socket_async(std::net::UdpSocket)`: the
`start_async` analogue for an already-bound socket, wiring the
async socket and recv task exactly as the fresh-bind path would.
- `Drop` impl for `UdpTransport`: if a transport is dropped while
still holding a recv task or socket (for example on error
teardown), aborts the task, clears the socket, and emits a debug
log so the cleanup is visible in tracing rather than silent.
== Logging and observability
Default `EnvFilter` demotes third-party relay-pool DEBUG output to
TRACE-only: `nostr_relay_pool`, `nostr_sdk`, and `nostr` are pinned
at INFO when our level is anything below TRACE, and at TRACE when
our level is TRACE — so the raw frames are still reachable when
explicitly asked for. RUST_LOG continues to override completely.
Concise one-line DEBUG events are emitted at the meaningful points
in the discovery / hole-punch sequence:
- `advert: published` (event id, relay count, endpoints, ttl)
- `advert: peer cached` (notify-loop ingress for non-self)
- `advert: resolved` (cache hit / relay fetch outcome)
- `traversal: initiator starting`
- `traversal: initiator STUN observed` (reflexive, local count)
- `traversal: offer sent` (session id, relay count, event id)
- `traversal: answer received` (accepted, reflexive, local)
- `traversal: initiator punch succeeded` (remote addr)
- `traversal: offer received` (responder side)
- `traversal: responder STUN observed`
- `traversal: answer sent`
- `traversal: responder punch succeeded`
Npubs are shortened to `npub1<4>..<4>` and event/session ids to
their first 8 hex characters.
Other operator-facing logs:
- `UdpTransport` adoption and drop paths log at info / debug.
- `adopt_established_traversal` logs at debug on entry and info on
successful return, tagged with peer npub, session id, transport
id, and both socket endpoints, so the bootstrap handoff is
traceable end-to-end alongside the `UdpTransport::drop` log.
- `cleanup_bootstrap_transport_if_unused` logs at debug when the
reference-count check drops an adopted transport.
- `connect_peer` tags its entry `debug!` with `peer_npub` so
downstream STUN, punch, and handshake logs for the same peer
correlate for operators.
- Advert-cache and seen-sessions overflow evictions log at debug so
mis-sized caps are visible under ambient relay volume.
- Gift-wrap unwrap failures on `SIGNAL_KIND` events log at trace
(hot path: fires for every unrelated signal event on the same
relay).
- Traversal-offer handler failures log at debug. Expected conditions
such as punch timeout on symmetric NAT are covered there; real
problems are reported upstream via `BootstrapEvent::Failed`.
- Inbound-offer rate-limit messages name the governing config field
(`max_concurrent_incoming_offers`) and state that the offer was
rate-limited rather than failing.
== Tests
- 18 new unit tests in `src/discovery/nostr/tests.rs` covering advert
encoding, signal envelope round-trip, STUN parsing, punch-packet
codec, and replay-window enforcement. Run under the
`nostr-discovery` feature.
- Config-validation tests in `src/config/mod.rs` covering the three
cross-field invariants and YAML parsing of the full
`node.discovery.nostr` block plus `peers[].via_nostr`, empty
`addresses` with `via_nostr: true`, and a `udp: nat` address.
- `src/node/tests/bootstrap.rs` integration tests that drive a
synthetic traversal (bound UDP socket pair + synthetic peer
identity) through `adopt_established_traversal` and assert the
Noise handshake completes over the adopted socket.
- Punch-planner tests assert reflexive-before-LAN ordering and that
same-LAN scenarios still include the LAN target in the plan.
- `testing/nat/` Docker NAT lab harness:
- Local `strfry` relay, local STUN responder, and one or two
router containers performing `iptables` NAT.
- Node LAN interfaces are provisioned with explicit `veth` pairs
injected into the node and router namespaces so every packet
traverses the router namespace (plain Docker bridges are not
used for the LAN).
- `cone` scenario: both peers behind full-cone-emulation NAT
(SNAT with source-port preservation, inbound DNAT back to the
single LAN host regardless of remote source); asserts UDP
traversal succeeds and link remote addresses are on the router
WAN subnet.
- `symmetric` scenario: `MASQUERADE --random-fully`; asserts UDP
traversal fails and TCP fallback converges over router-
published WAN addresses.
- `lan` scenario: both peers share a LAN subnet; asserts LAN
addresses are preferred over reflexive ones.
- Cleanup tears down all profile-gated services
(`--profile cone --profile symmetric --profile lan`) so no
orphan containers survive a run.
- `testing/scripts/build.sh` builds the Docker test image with
`--features "tui nostr-discovery"` by default so NAT-harness
binaries include bootstrap support.
== CI
- Linux release build and nextest unit-test job both use
`--features "gateway nostr-discovery"` so the feature-gated code
and its unit tests compile and run in CI.
- Three new integration matrix entries (`nat-cone`, `nat-symmetric`,
`nat-lan`) invoke `testing/nat/scripts/nat-test.sh`, collect
`docker compose logs` on failure, and always stop containers.
== Packaging and operations
- `packaging/common/fips.yaml` ships a fully commented
`node.discovery.nostr.*` block, plus documented
`advertise_on_nostr` / `public` examples under the UDP transport,
an `advertise_on_nostr` example under TCP, and a `via_nostr: true`
example under the static peer section with both a direct
`host:port` UDP address and a `udp: nat` fallback.
- `.github/workflows/package-openwrt.yml`: NIP-94 release event
publishes target the new default relay set.
== Documentation
- `README.md`: overlay discovery + NAT traversal moved from
"Near-term priorities" into "What works today".
- `docs/design/fips-intro.md`: rewrites the paragraphs that
previously described Nostr discovery and NAT traversal as future
work; describes the shipped mechanism and the feature gate.
- `docs/design/fips-transport-layer.md`: drops the "(future
direction)" qualifier from the Nostr Relay Discovery section,
expands with the `udp:nat` advertisement and bootstrap handoff
description, and updates the Current State callout.
- `docs/design/fips-mesh-layer.md`: notes that mid-session NAT
rebinding (roaming) and initial NAT traversal (Nostr path) are
distinct mechanisms.
- `docs/design/fips-configuration.md`: documents the full
`node.discovery.nostr.*` surface, including the three resource
caps and `share_local_candidates`.
- `docs/design/fips-nostr-discovery.md`: design and configuration
reference for the shipped mechanism, including the empty-
`addresses`-with-`via_nostr` shorthand.
- `docs/proposals/nostr-udp-hole-punch-protocol.md`: adds an
Implemented status callout, clarifies that the punch socket is
per-peer and per-attempt rather than shared with the application
listener, aligns field names with the shipped JSON
(`sessionId`, `issuedAt` / `expiresAt`, `reflexiveAddress`,
`localAddresses`, `stunServer`), sets the `d`-tag to
`fips-overlay-v1`, names the kind as 37195, and notes that
advertised STUN entries are informational.
- `docs/proposals/README.md`: adds a Status column and marks the
hole-punching proposal Implemented.
- `CHANGELOG.md`: Unreleased > Added entry covering the discovery
path, STUN/punch path, configuration surface, and Docker NAT lab.
Co-authored-by: Johnathan Corgan <johnathan@corganlabs.com>
|
||
 Origami74
|
e693f4fb7e |
Add macOS support, fix bloom filter routing and MMP intervals
macOS platform: - Platform-native TUN interface management with shutdown pipe - Raw Ethernet transport with macOS socket backend (socket_macos.rs) - EthernetTransport and TransportHandle::Ethernet ungated from Linux-only - macOS .pkg packaging (build-pkg.sh, launchd plist, uninstall script) - CI: macOS build and unit test jobs; x86_64 cross-compiled from macos-latest via rustup target add x86_64-apple-darwin Gateway feature flag: - New opt-in `gateway` Cargo feature activates optional `rustables` dep - `pub mod gateway` and `Config.gateway` gated behind the feature so macOS builds never pull in Linux-only nftables bindings - `fips-gateway` bin has `required-features = ["gateway"]` - All Linux/OpenWrt/AUR packaging passes `--features gateway` CI / packaging: - package-linux, package-macos, package-openwrt now trigger on push to master/maint/next and on pull requests; release uploads remain tag-gated - Bloom filter routing fix: fall through to tree routing when no candidate is strictly closer - MMP intervals: raise MIN to 1s / MAX to 5s with 5-sample cold-start phase |
||
|
Origami74andJohnathan Corgan
|
7a643a9ac3 |
Add Nostr release publishing to OpenWrt package workflow
Add versioning job with release channel detection, Blossom upload, NIP-94 event publishing, and relay verification. Replace setup-zig action with direct download for act runner compatibility. Pin cargo-zigbuild and zig versions for reproducible builds. |
||
|
Origami74andJohnathan Corgan
|
c164de8808 |
Add reproducible build infrastructure
Pin Rust toolchain to 1.94.0 via rust-toolchain.toml for deterministic compiler output across environments. Set SOURCE_DATE_EPOCH from git commit timestamp in CI workflows and packaging scripts to normalize embedded timestamps. Make packaging archives reproducible: pass --mtime=@$SOURCE_DATE_EPOCH to tar in .deb, .ipk, and systemd tarball builds. Normalize ownership to root:root in systemd tarballs. Pin cargo-zigbuild to 0.19.8 for cross-compilation stability. Add SHA-256 hash output to CI build and OpenWrt packaging workflows for binary verification. |
||
|
Origami74
|
c8b7459fbc |
Add sidecar-nostr-relay example and fix openwrt CI path
Add a complete example running a strfry Nostr relay exclusively over the FIPS mesh using the sidecar pattern. Includes Docker Compose stack, network isolation via iptables, .fips DNS resolution, nak CLI, build script with cross-compilation support, and documentation. Also fix the package-openwrt.yml workflow path to match the openwrt → openwrt-ipk directory rename. |
||
|
origami74@gmail.comandJohnathan Corgan
|
46ccd9744e |
Add OpenWrt .ipk packaging with CI workflow
Adds packaging/openwrt/ with everything needed to produce and distribute FIPS .ipk packages for OpenWrt routers: - Makefile: OpenWrt feed package definition using rust/host toolchain, maps OpenWrt ARCH to Rust musl target triples - build-ipk.sh: local build script using cargo-zigbuild + direct tar assembly — no OpenWrt SDK or Docker required. Handles macOS BSD tar (ustar format, resource fork suppression) and portable ar header generation for cross-platform .ipk creation. Accepts PKG_VERSION env var override for CI use. - files/: procd init script, default fips.yaml (persistent identity, br-lan and wwan interface examples), firewall helper, dnsmasq .fips forwarding, br_netfilter sysctl, hotplug for fips0, UCI defaults for first-boot setup, sysupgrade keeplist - .github/workflows/package-openwrt.yml: CI workflow (ubuntu-latest + cargo-zigbuild) building aarch64 and x86_64 .ipk packages using build-ipk.sh; llvm-strip for cross-compiled binaries; triggers on every push; publishes to GitHub Releases on version tags. MIPS targets disabled pending portable-atomic crate (32-bit MIPS lacks native AtomicU64), with nightly/rust-src toolchain steps prepared for re-enablement. - .gitignore: add reference/, dist/, *.ipk |