laantungir/fips
1
0
Fork 0
mirror of https://github.com/jmcorgan/fips.git synced 2026-10-06 03:28:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into next

Browse Source 
# Conflicts:
#	src/node/lifecycle.rs
#	testing/static/scripts/rekey-test.sh
This commit is contained in:
Johnathan Corgan
2026-04-27 16:10:11 +00:00
parent 64c38b2e26 34e00b9f6e
commit 5a5dbe36da
74 changed files with 7646 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
+32 -4
View File
@@ -82,7 +82,7 @@ jobs:
${{ runner.os }}-cargo-
- name: Build
run: cargo build --release ${{ (runner.os == 'macOS' || runner.os == 'Windows') && '--no-default-features --features tui' || '--features gateway' }}
run: cargo build --release
- name: SHA-256 hashes (Linux)
if: runner.os == 'Linux'
@@ -147,7 +147,7 @@ jobs:
uses: taiki-e/install-action@nextest
- name: Run unit tests
run: cargo nextest run --all --profile ci --features gateway
run: cargo nextest run --all --profile ci
- name: Publish test report (Checks tab)
uses: dorny/test-reporter@v2
@@ -197,7 +197,7 @@ jobs:
uses: taiki-e/install-action@nextest
- name: Run unit tests
run: cargo nextest run --all --profile ci --no-default-features --features tui
run: cargo nextest run --all --profile ci
# ─────────────────────────────────────────────────────────────────────────────
# Job 2c – Unit tests (Windows)
@@ -226,7 +226,7 @@ jobs:
uses: taiki-e/install-action@nextest
- name: Run unit tests
run: cargo nextest run --all --profile ci --no-default-features --features tui
run: cargo nextest run --all --profile ci
# ─────────────────────────────────────────────────────────────────────────────
# Job 3 – Integration tests (static mesh + chaos simulation)
@@ -301,6 +301,16 @@ jobs:
# ── Sidecar deployment ──────────────────────────────────────────
- suite: sidecar
type: sidecar
# ── NAT traversal lab (Nostr/STUN UDP hole punch) ───────────────
- suite: nat-cone
type: nat
scenario: cone
- suite: nat-symmetric
type: nat
scenario: symmetric
- suite: nat-lan
type: nat
scenario: lan
steps:
- uses: actions/checkout@v4
@@ -426,3 +436,21 @@ jobs:
docker logs "sidecar-${node}-fips-1" 2>&1 || true
echo ""
done
# ── NAT traversal lab ───────────────────────────────────────────────
- name: Run NAT lab scenario
if: matrix.type == 'nat'
run: bash testing/nat/scripts/nat-test.sh ${{ matrix.scenario }}
- name: Collect logs on failure (nat)
if: matrix.type == 'nat' && failure()
run: |
docker compose -f testing/nat/docker-compose.yml \
--profile ${{ matrix.scenario }} logs --no-color
- name: Stop containers (nat)
if: matrix.type == 'nat' && always()
run: |
docker compose -f testing/nat/docker-compose.yml \
--profile cone --profile symmetric --profile lan \
down --volumes --remove-orphans
.github/workflows/package-linux.yml
+1 -1
View File
@@ -90,7 +90,7 @@ jobs:
run: cargo install cargo-deb --version 3.6.3 --locked
- name: Build release binaries
run: cargo build --release --features gateway
run: cargo build --release
- name: Build systemd tarball
env:
.github/workflows/package-macos.yml
+1 -1
View File
@@ -86,7 +86,7 @@ jobs:
macos-release-${{ matrix.arch }}-
- name: Build release binaries
run: cargo build --release --target ${{ matrix.target }} --no-default-features --features tui
run: cargo build --release --target ${{ matrix.target }}
- name: Build macOS package
run: |
.github/workflows/package-openwrt.yml
+2 -2
View File
@@ -247,7 +247,7 @@ jobs:
id: publish
shell: bash
env:
RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://relay.primal.net"
RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://offchain.pub"
NSEC: ${{ steps.keys.outputs.nsec }}
run: |
: ${GITHUB_OUTPUT:=/tmp/github_output}
@@ -295,7 +295,7 @@ jobs:
if: ${{ steps.publish.outputs.eventId != '' }}
env:
EVENT_ID: ${{ steps.publish.outputs.eventId }}
RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://relay.primal.net"
RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://offchain.pub"
run: |
echo "Verifying event $EVENT_ID on relays..."
FOUND=0
.github/workflows/package-windows.yml
+1 -1
View File
@@ -77,7 +77,7 @@ jobs:
windows-release-x86_64-
- name: Build release binaries
run: cargo build --release --no-default-features --features tui
run: cargo build --release
- name: Build Windows package
shell: pwsh
.gitignore
+6
View File
@@ -33,3 +33,9 @@ __pycache__/
*.egg-info/
*.egg
# Runtime artifacts from running fips in-tree during local testing.
# Root-anchored so legitimately-tracked fips.yaml under packaging/ and
# examples/ stays included.
/fips.key
/fips.pub
/fips.yaml
CHANGELOG.md
+43
View File
@@ -116,6 +116,29 @@ with v0.2.x peers.
forwarding, proxy NDP, RA route advertisements, and IPv6 forwarding
sysctls. Gateway enabled by default on OpenWrt
#### Nostr-Mediated Discovery and NAT Traversal
- Optional overlay-discovery and NAT-hole-punching path behind the
`nostr-discovery` cargo feature. Nodes publish signed overlay adverts
as Nostr kind `37195` parameterized replaceable events listing
reachable transport endpoints to a configurable set of public relays,
and consume peer adverts to populate fallback addresses for
`via_nostr` peers or, under `policy: open`, for non-configured peers
within a budget cap. The kind value is FIPS-specific: `37195` sits in
the application-defined replaceable range `30000–39999`, and the
digits visually spell `FIPS` (7=F, 1=I, 9=P, 5=S)
- STUN-assisted UDP hole punching for `addr: "nat"` UDP endpoints. STUN
reflexive observation, gift-wrap (NIP-59) offer/answer signaling, and
candidate-pair punch planner (LAN-private + reflexive paths attempted in
parallel). Successful punches hand the live socket into the standard
FIPS UDP transport via a bootstrap-handoff API
- New `node.discovery.nostr.*` configuration tree with operator-tunable
resource caps, replay tracking, and punch timing; new `peers[].via_nostr`
and per-transport `advertise_on_nostr` / `public` flags. Cross-field
validation at startup catches mis-configured combinations
- Docker NAT lab covering cone, symmetric (TCP-fallback), and LAN
scenarios, wired into the integration CI matrix
#### Examples
- macOS WireGuard sidecar: run FIPS in a local Docker container and
@@ -214,6 +237,26 @@ with v0.2.x peers.
updated. In-tree `fipstop` is adjusted to the new schema. The
control socket interface is still pre-1.0 and not covered by
stability guarantees
- Discovery rate limiting retuned to be less aggressive at cold start.
The previous defaults (30s base post-failure suppression, doubling
to a 300s cap, with reset only on parent change / new peer / first
RTT / reconnection) reliably outlasted initial mesh convergence: a
single timed-out lookup during bloom-filter propagation suppressed
any retry for 30s while none of the reset triggers fired on a
stable post-handshake topology. The suppression window dictated
effective time-to-converge instead of bounding repeat traffic.
Replaces the single-lookup-with-internal-retry model
(`timeout_secs`/`retry_interval_secs`/`max_attempts`) with a
per-attempt timeout sequence in
`node.discovery.attempt_timeouts_secs` (default `[1, 2, 4, 8]`).
Each attempt sends a fresh `LookupRequest` with a new `request_id`,
which lets successive attempts take different forwarding paths as
the bloom and tree state evolve. The destination is declared
unreachable only after the full sequence is exhausted (15s total
at the default). Disables post-failure suppression by default
(`backoff_base_secs`/`backoff_max_secs` now both `0`); operators
with chatty apps generating repeat lookups against unreachable
destinations can opt back in
- Validate bloom filter fill ratio on FilterAnnounce ingress.
Inbound FilterAnnounce messages whose derived false-positive
rate exceeds `node.bloom.max_inbound_fpr` (new config field,
Cargo.lock
Generated
+714 -2
View File
@@ -122,6 +122,37 @@ version = "4.7.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
[[package]]
name = "async-utility"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a34a3b57207a7a1007832416c3e4862378c8451b4e8e093e436f48c2d3d2c151"
dependencies = [
"futures-util",
"gloo-timers",
"tokio",
"wasm-bindgen-futures",
]
[[package]]
name = "async-wsocket"
version = "0.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1c92385c7c8b3eb2de1b78aeca225212e4c9a69a78b802832759b108681a5069"
dependencies = [
"async-utility",
"futures",
"futures-util",
"js-sys",
"tokio",
"tokio-rustls",
"tokio-socks",
"tokio-tungstenite",
"url",
"wasm-bindgen",
"web-sys",
]
[[package]]
name = "atomic"
version = "0.6.1"
@@ -131,6 +162,12 @@ dependencies = [
"bytemuck",
]
[[package]]
name = "atomic-destructor"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ef49f5882e4b6afaac09ad239a4f8c70a24b8f2b0897edb1f706008efd109cf4"
[[package]]
name = "atomic-waker"
version = "1.1.2"
@@ -149,6 +186,12 @@ version = "0.22.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
[[package]]
name = "base64ct"
version = "1.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
[[package]]
name = "bech32"
version = "0.11.1"
@@ -175,6 +218,17 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "bip39"
version = "2.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "90dbd31c98227229239363921e60fcf5e558e43ec69094d46fc4996f08d1d5bc"
dependencies = [
"bitcoin_hashes",
"serde",
"unicode-normalization",
]
[[package]]
name = "bit-set"
version = "0.5.3"
@@ -204,6 +258,7 @@ checksum = "26ec84b80c482df901772e931a9a681e26a1b9ee2302edeff23cb30328745c8b"
dependencies = [
"bitcoin-io",
"hex-conservative",
"serde",
]
[[package]]
@@ -227,6 +282,15 @@ dependencies = [
"generic-array",
]
[[package]]
name = "block-padding"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a8894febbff9f758034a5b8e12d87918f56dfc64a8e1fe757d65e29041538d93"
dependencies = [
"generic-array",
]
[[package]]
name = "blocking"
version = "1.6.2"
@@ -342,6 +406,15 @@ dependencies = [
"rustversion",
]
[[package]]
name = "cbc"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "26b52a9543ae338f279b96b0b9fed9c8093744685043739079ce85cd58f289a6"
dependencies = [
"cipher",
]
[[package]]
name = "cc"
version = "1.2.54"
@@ -758,6 +831,12 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "data-encoding"
version = "2.10.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea"
[[package]]
name = "dbus"
version = "0.9.9"
@@ -985,12 +1064,14 @@ dependencies = [
"hex",
"hkdf",
"libc",
"nostr",
"nostr-sdk",
"portable-atomic",
"rand 0.10.0",
"ratatui",
"rtnetlink",
"rustables",
"secp256k1",
"secp256k1 0.30.0",
"serde",
"serde_json",
"serde_yaml",
@@ -1032,6 +1113,15 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
[[package]]
name = "form_urlencoded"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
dependencies = [
"percent-encoding",
]
[[package]]
name = "futures"
version = "0.3.31"
@@ -1148,8 +1238,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
dependencies = [
"cfg-if",
"js-sys",
"libc",
"wasi",
"wasm-bindgen",
]
[[package]]
@@ -1184,6 +1276,18 @@ version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
[[package]]
name = "gloo-timers"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bbb143cf96099802033e0d4f4963b19fd2e0b728bcf076cd9cf7f6634f092994"
dependencies = [
"futures-channel",
"futures-core",
"js-sys",
"wasm-bindgen",
]
[[package]]
name = "half"
version = "2.7.1"
@@ -1254,6 +1358,104 @@ dependencies = [
"digest",
]
[[package]]
name = "http"
version = "1.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a"
dependencies = [
"bytes",
"itoa",
]
[[package]]
name = "httparse"
version = "1.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
[[package]]
name = "icu_collections"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
dependencies = [
"displaydoc",
"potential_utf",
"utf8_iter",
"yoke",
"zerofrom",
"zerovec",
]
[[package]]
name = "icu_locale_core"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
dependencies = [
"displaydoc",
"litemap",
"tinystr",
"writeable",
"zerovec",
]
[[package]]
name = "icu_normalizer"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
dependencies = [
"icu_collections",
"icu_normalizer_data",
"icu_properties",
"icu_provider",
"smallvec",
"zerovec",
]
[[package]]
name = "icu_normalizer_data"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
[[package]]
name = "icu_properties"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
dependencies = [
"icu_collections",
"icu_locale_core",
"icu_properties_data",
"icu_provider",
"zerotrie",
"zerovec",
]
[[package]]
name = "icu_properties_data"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
[[package]]
name = "icu_provider"
version = "2.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
dependencies = [
"displaydoc",
"icu_locale_core",
"writeable",
"yoke",
"zerofrom",
"zerotrie",
"zerovec",
]
[[package]]
name = "id-arena"
version = "2.3.0"
@@ -1266,6 +1468,27 @@ version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
[[package]]
name = "idna"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
dependencies = [
"idna_adapter",
"smallvec",
"utf8_iter",
]
[[package]]
name = "idna_adapter"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
dependencies = [
"icu_normalizer",
"icu_properties",
]
[[package]]
name = "indexmap"
version = "2.13.0"
@@ -1293,6 +1516,7 @@ version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
dependencies = [
"block-padding",
"generic-array",
]
@@ -1309,6 +1533,18 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "instant"
version = "0.1.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e0242819d153cba4b4b05a5a8f2a7e9bbf97b6055b2a002b395c96b5ff3c0222"
dependencies = [
"cfg-if",
"js-sys",
"wasm-bindgen",
"web-sys",
]
[[package]]
name = "ipnet"
version = "2.11.0"
@@ -1450,6 +1686,12 @@ version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
[[package]]
name = "litemap"
version = "0.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
[[package]]
name = "litrs"
version = "1.0.0"
@@ -1544,6 +1786,12 @@ dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "negentropy"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0efe882e02d206d8d279c20eb40e03baf7cb5136a1476dc084a324fbc3ec42d"
[[package]]
name = "netlink-packet-core"
version = "0.8.1"
@@ -1628,6 +1876,83 @@ dependencies = [
"minimal-lexical",
]
[[package]]
name = "nostr"
version = "0.44.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3aa5e3b6a278ed061835fe1ee293b71641e6bf8b401cfe4e1834bbf4ef0a34e1"
dependencies = [
"base64",
"bech32",
"bip39",
"bitcoin_hashes",
"cbc",
"chacha20 0.9.1",
"chacha20poly1305",
"getrandom 0.2.17",
"hex",
"instant",
"scrypt",
"secp256k1 0.29.1",
"serde",
"serde_json",
"unicode-normalization",
"url",
]
[[package]]
name = "nostr-database"
version = "0.44.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7462c9d8ae5ef6a28d66a192d399ad2530f1f2130b13186296dbb11bdef5b3d1"
dependencies = [
"lru",
"nostr",
"tokio",
]
[[package]]
name = "nostr-gossip"
version = "0.44.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ade30de16869618919c6b5efc8258f47b654a98b51541eb77f85e8ec5e3c83a6"
dependencies = [
"nostr",
]
[[package]]
name = "nostr-relay-pool"
version = "0.44.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b1073ccfbaea5549fb914a9d52c68dab2aecda61535e5143dd73e95445a804b"
dependencies = [
"async-utility",
"async-wsocket",
"atomic-destructor",
"hex",
"lru",
"negentropy",
"nostr",
"nostr-database",
"tokio",
"tracing",
]
[[package]]
name = "nostr-sdk"
version = "0.44.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "471732576710e779b64f04c55e3f8b5292f865fea228436daf19694f0bf70393"
dependencies = [
"async-utility",
"nostr",
"nostr-database",
"nostr-gossip",
"nostr-relay-pool",
"tokio",
"tracing",
]
[[package]]
name = "nu-ansi-term"
version = "0.50.3"
@@ -1750,12 +2075,39 @@ dependencies = [
"windows-link",
]
[[package]]
name = "password-hash"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
dependencies = [
"base64ct",
"rand_core 0.6.4",
"subtle",
]
[[package]]
name = "paste"
version = "1.0.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
[[package]]
name = "pbkdf2"
version = "0.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8ed6a7761f76e3b9f92dfb0a60a6a6477c61024b775147ff0973a02653abaf2"
dependencies = [
"digest",
"hmac",
]
[[package]]
name = "percent-encoding"
version = "2.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "pest"
version = "2.8.6"
@@ -1945,6 +2297,15 @@ version = "1.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
[[package]]
name = "potential_utf"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
dependencies = [
"zerovec",
]
[[package]]
name = "powerfmt"
version = "0.2.0"
@@ -2014,10 +2375,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
dependencies = [
"libc",
"rand_chacha",
"rand_chacha 0.3.1",
"rand_core 0.6.4",
]
[[package]]
name = "rand"
version = "0.9.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
dependencies = [
"rand_chacha 0.9.0",
"rand_core 0.9.5",
]
[[package]]
name = "rand"
version = "0.10.0"
@@ -2039,6 +2410,16 @@ dependencies = [
"rand_core 0.6.4",
]
[[package]]
name = "rand_chacha"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
dependencies = [
"ppv-lite86",
"rand_core 0.9.5",
]
[[package]]
name = "rand_core"
version = "0.6.4"
@@ -2048,6 +2429,15 @@ dependencies = [
"getrandom 0.2.17",
]
[[package]]
name = "rand_core"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
dependencies = [
"getrandom 0.3.4",
]
[[package]]
name = "rand_core"
version = "0.10.0"
@@ -2208,6 +2598,20 @@ version = "0.8.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7a2d987857b319362043e95f5353c0535c1f58eec5336fdfcf626430af7def58"
[[package]]
name = "ring"
version = "0.17.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
dependencies = [
"cc",
"cfg-if",
"getrandom 0.2.17",
"libc",
"untrusted",
"windows-sys 0.52.0",
]
[[package]]
name = "rtnetlink"
version = "0.20.0"
@@ -2284,6 +2688,40 @@ dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "rustls"
version = "0.23.38"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
dependencies = [
"once_cell",
"ring",
"rustls-pki-types",
"rustls-webpki",
"subtle",
"zeroize",
]
[[package]]
name = "rustls-pki-types"
version = "1.14.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
dependencies = [
"zeroize",
]
[[package]]
name = "rustls-webpki"
version = "0.103.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
dependencies = [
"ring",
"rustls-pki-types",
"untrusted",
]
[[package]]
name = "rustversion"
version = "1.0.22"
@@ -2296,6 +2734,15 @@ version = "1.0.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a50f4cf475b65d88e057964e0e9bb1f0aa9bbb2036dc65c64596b42932536984"
[[package]]
name = "salsa20"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "97a22f5af31f73a954c10289c93e8a50cc23d971e80ee446f1f6f7137a088213"
dependencies = [
"cipher",
]
[[package]]
name = "same-file"
version = "1.0.6"
@@ -2311,6 +2758,29 @@ version = "1.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
[[package]]
name = "scrypt"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0516a385866c09368f0b5bcd1caff3366aace790fcd46e2bb032697bb172fd1f"
dependencies = [
"password-hash",
"pbkdf2",
"salsa20",
"sha2",
]
[[package]]
name = "secp256k1"
version = "0.29.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9465315bc9d4566e1724f0fffcbcc446268cb522e60f9a27bcded6b19c108113"
dependencies = [
"rand 0.8.5",
"secp256k1-sys",
"serde",
]
[[package]]
name = "secp256k1"
version = "0.30.0"
@@ -2393,6 +2863,17 @@ dependencies = [
"unsafe-libyaml",
]
[[package]]
name = "sha1"
version = "0.10.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
dependencies = [
"cfg-if",
"cpufeatures 0.2.17",
"digest",
]
[[package]]
name = "sha2"
version = "0.10.9"
@@ -2487,6 +2968,12 @@ dependencies = [
"windows-sys 0.60.2",
]
[[package]]
name = "stable_deref_trait"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
[[package]]
name = "static_assertions"
version = "1.1.0"
@@ -2727,6 +3214,16 @@ version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7694e1cfe791f8d31026952abf09c69ca6f6fa4e1a1229e18988f06a04a12dca"
[[package]]
name = "tinystr"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
dependencies = [
"displaydoc",
"zerovec",
]
[[package]]
name = "tinytemplate"
version = "1.2.1"
@@ -2737,6 +3234,21 @@ dependencies = [
"serde_json",
]
[[package]]
name = "tinyvec"
version = "1.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
dependencies = [
"tinyvec_macros",
]
[[package]]
name = "tinyvec_macros"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
[[package]]
name = "tokio"
version = "1.49.0"
@@ -2764,6 +3276,16 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "tokio-rustls"
version = "0.26.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
dependencies = [
"rustls",
"tokio",
]
[[package]]
name = "tokio-socks"
version = "0.5.2"
@@ -2787,6 +3309,22 @@ dependencies = [
"tokio",
]
[[package]]
name = "tokio-tungstenite"
version = "0.26.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7a9daff607c6d2bf6c16fd681ccb7eecc83e4e2cdc1ca067ffaadfca5de7f084"
dependencies = [
"futures-util",
"log",
"rustls",
"rustls-pki-types",
"tokio",
"tokio-rustls",
"tungstenite",
"webpki-roots 0.26.11",
]
[[package]]
name = "tokio-util"
version = "0.7.18"
@@ -2882,6 +3420,25 @@ dependencies = [
"wintun-bindings",
]
[[package]]
name = "tungstenite"
version = "0.26.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4793cb5e56680ecbb1d843515b23b6de9a75eb04b66643e256a396d43be33c13"
dependencies = [
"bytes",
"data-encoding",
"http",
"httparse",
"log",
"rand 0.9.4",
"rustls",
"rustls-pki-types",
"sha1",
"thiserror 2.0.18",
"utf-8",
]
[[package]]
name = "typenum"
version = "1.19.0"
@@ -2900,6 +3457,15 @@ version = "1.0.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
[[package]]
name = "unicode-normalization"
version = "0.1.25"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
dependencies = [
"tinyvec",
]
[[package]]
name = "unicode-segmentation"
version = "1.12.0"
@@ -2945,6 +3511,37 @@ version = "0.2.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
[[package]]
name = "untrusted"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
[[package]]
name = "url"
version = "2.5.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
dependencies = [
"form_urlencoded",
"idna",
"percent-encoding",
"serde",
"serde_derive",
]
[[package]]
name = "utf-8"
version = "0.7.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
[[package]]
name = "utf8_iter"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "utf8parse"
version = "0.2.2"
@@ -3031,6 +3628,20 @@ dependencies = [
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-futures"
version = "0.4.58"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "70a6e77fd0ae8029c9ea0063f87c46fde723e7d887703d74ad2616d792e51e6f"
dependencies = [
"cfg-if",
"futures-util",
"js-sys",
"once_cell",
"wasm-bindgen",
"web-sys",
]
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.108"
@@ -3107,6 +3718,24 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "webpki-roots"
version = "0.26.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
dependencies = [
"webpki-roots 1.0.7",
]
[[package]]
name = "webpki-roots"
version = "1.0.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
dependencies = [
"rustls-pki-types",
]
[[package]]
name = "wezterm-bidi"
version = "0.2.3"
@@ -3525,12 +4154,41 @@ dependencies = [
"wasmparser",
]
[[package]]
name = "writeable"
version = "0.6.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
[[package]]
name = "yansi"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
[[package]]
name = "yoke"
version = "0.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca"
dependencies = [
"stable_deref_trait",
"yoke-derive",
"zerofrom",
]
[[package]]
name = "yoke-derive"
version = "0.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.114",
"synstructure",
]
[[package]]
name = "zerocopy"
version = "0.8.33"
@@ -3551,12 +4209,66 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "zerofrom"
version = "0.1.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df"
dependencies = [
"zerofrom-derive",
]
[[package]]
name = "zerofrom-derive"
version = "0.1.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.114",
"synstructure",
]
[[package]]
name = "zeroize"
version = "1.8.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
[[package]]
name = "zerotrie"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
dependencies = [
"displaydoc",
"yoke",
"zerofrom",
]
[[package]]
name = "zerovec"
version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
dependencies = [
"yoke",
"zerofrom",
"zerovec-derive",
]
[[package]]
name = "zerovec-derive"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.114",
]
[[package]]
name = "zmij"
version = "1.0.21"
Cargo.toml
+10 -9
View File
@@ -9,13 +9,11 @@ repository = "https://github.com/jmcorgan/fips"
readme = "README.md"
[features]
default = ["tui", "ble"]
tui = ["dep:ratatui"]
ble = ["dep:bluer"]
gateway = ["dep:rustables"]
default = ["nostr-discovery"]
nostr-discovery = ["dep:nostr", "dep:nostr-sdk"]
[dependencies]
ratatui = { version = "0.30", optional = true }
ratatui = "0.30"
secp256k1 = { version = "0.30", features = ["rand", "global-context"] }
sha2 = "0.10"
hkdf = "0.12"
@@ -38,7 +36,8 @@ socket2 = { version = "0.6.2", features = ["all"] }
tokio-socks = "0.5"
portable-atomic = { version = "1", features = ["std"] }
rustables = { version = "0.8.7", optional = true }
nostr = { version = "0.44", features = ["std", "nip59"], optional = true }
nostr-sdk = { version = "0.44", optional = true }
[target.'cfg(unix)'.dependencies]
tun = { version = "0.8.5", features = ["async"] }
@@ -46,7 +45,11 @@ libc = "0.2"
[target.'cfg(target_os = "linux")'.dependencies]
rtnetlink = "0.20.0"
bluer = { version = "0.17", features = ["bluetoothd", "l2cap"], optional = true }
rustables = "0.8.7"
# bluer/BlueZ needs glibc — see build.rs `bluer_available` cfg gate.
[target.'cfg(all(target_os = "linux", not(target_env = "musl")))'.dependencies]
bluer = { version = "0.17", features = ["bluetoothd", "l2cap"] }
[target.'cfg(windows)'.dependencies]
wintun = "0.5"
@@ -95,9 +98,7 @@ path = "src/bin/fipsctl.rs"
[[bin]]
name = "fips-gateway"
path = "src/bin/fips-gateway.rs"
required-features = ["gateway"]
[[bin]]
name = "fipstop"
path = "src/bin/fipstop/main.rs"
required-features = ["tui"]
README.md
+5 -1
View File
@@ -400,10 +400,14 @@ Ethernet, Tor, and Bluetooth (BLE) with a small live mesh of deployed nodes.
- Reproducible builds with toolchain pinning and SOURCE_DATE_EPOCH
- Linux (Debian, systemd tarball, OpenWrt, AUR), macOS (`.pkg`), and Windows (ZIP, service) packaging
- Docker-based integration and chaos testing
- Nostr-mediated overlay endpoint discovery and UDP hole punching for
NAT traversal — peers publish endpoint adverts on public Nostr
relays, exchange candidates via NIP-59 gift-wrapped offers/answers,
and establish direct paths through NATs using STUN-assisted
punching (behind the `nostr-discovery` cargo feature)
### Near-term priorities
- Peer discovery via Nostr relays (bootstrap without static peer lists)
- Native API for FIPS-aware applications (npub:port addressing)
- Security audit of cryptographic protocols
build.rs
+10
View File
@@ -36,4 +36,14 @@ fn main() {
// Support reproducible builds (Debian packaging)
println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH");
// bluer/BlueZ is glibc-linux only: musl cross-compiles (OpenWrt) can't
// satisfy libdbus-sys's pkg-config cross-compile requirement, and musl
// router targets don't run BlueZ by default anyway.
println!("cargo:rustc-check-cfg=cfg(bluer_available)");
let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
let target_env = std::env::var("CARGO_CFG_TARGET_ENV").unwrap_or_default();
if target_os == "linux" && target_env != "musl" {
println!("cargo:rustc-cfg=bluer_available");
}
}
docs/design/README.md
+1
View File
@@ -26,6 +26,7 @@ specific topics.
| -------- | ----------- |
| [fips-mesh-operation.md](fips-mesh-operation.md) | How the mesh operates: routing, discovery, error recovery |
| [fips-wire-formats.md](fips-wire-formats.md) | Wire format reference for all message types |
| [fips-nostr-discovery.md](fips-nostr-discovery.md) | Optional Nostr-mediated peer discovery and UDP NAT hole-punch (behind `nostr-discovery` feature) |
### Supporting References
docs/design/fips-configuration.md
+63 -10
View File
@@ -166,14 +166,66 @@ Controls bloom-guided node discovery (LookupRequest/LookupResponse).
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `node.discovery.ttl` | u8 | `64` | Hop limit for LookupRequest forwarding |
| `node.discovery.timeout_secs` | u64 | `10` | Lookup completion timeout |
| `node.discovery.attempt_timeouts_secs` | array<u64> | `[1, 2, 4, 8]` | Per-attempt timeouts. Each entry is the deadline for one `LookupRequest` before sending the next attempt with a fresh `request_id`. Length determines total attempt count; default gives 4 attempts and a 15s total budget |
| `node.discovery.recent_expiry_secs` | u64 | `10` | Dedup cache expiry for recent request IDs |
| `node.discovery.retry_interval_secs` | u64 | `5` | Retry interval within the timeout window; after this interval without a response, resend the lookup |
| `node.discovery.max_attempts` | u8 | `2` | Max attempts per lookup (1 = no retry, 2 = one retry) |
| `node.discovery.backoff_base_secs` | u64 | `30` | Base for exponential backoff after lookup failure; doubles per consecutive failure |
| `node.discovery.backoff_max_secs` | u64 | `300` | Cap on exponential backoff (5 minutes) |
| `node.discovery.backoff_base_secs` | u64 | `0` | Optional post-failure suppression base in seconds; doubles per consecutive failure. `0` disables (default) — the per-attempt sequence is the only retry pacing |
| `node.discovery.backoff_max_secs` | u64 | `0` | Cap on optional post-failure backoff |
| `node.discovery.forward_min_interval_secs` | u64 | `2` | Transit-side rate limiting: minimum interval between forwarded lookups for the same target |
#### Nostr Overlay Discovery (`node.discovery.nostr.*`)
Optional Nostr-mediated overlay discovery. This layer publishes replaceable
endpoint adverts (`fips-overlay-v1`), consumes advert-derived endpoint
fallbacks for configured peers, and can optionally discover non-configured
peers (`policy: open`). `udp:nat` remains the trigger for NAT traversal
offer/answer + punch-through, after which the established UDP socket is handed
into the normal FIPS transport/session stack.
Inbox-relay discovery falls back to the local DM relay list if remote relay
metadata cannot be fetched.
This support is compiled behind the crate feature `nostr-discovery`; builds
without that feature ignore `udp:nat` bootstrap configuration.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `node.discovery.nostr.enabled` | bool | `false` | Enable Nostr-mediated overlay discovery |
| `node.discovery.nostr.policy` | string | `"configured_only"` | Advert discovery policy: `disabled`, `configured_only`, `open` |
| `node.discovery.nostr.open_discovery_max_pending` | usize | `64` | Max open-discovery peers queued in outbound retry/connection state at once |
| `node.discovery.nostr.max_concurrent_incoming_offers` | usize | `16` | Max concurrent inbound traversal offers processed at once (rate limit against offer spam) |
| `node.discovery.nostr.advert_cache_max_entries` | usize | `2048` | Max cached overlay adverts retained from relay traffic |
| `node.discovery.nostr.seen_sessions_max_entries` | usize | `2048` | Max seen-session IDs retained for replay detection |
| `node.discovery.nostr.advertise` | bool | `true` | Publish local endpoint adverts |
| `node.discovery.nostr.advert_relays` | list[string] | `["wss://relay.damus.io", "wss://nos.lol", "wss://offchain.pub"]` | Relays used for service adverts |
| `node.discovery.nostr.dm_relays` | list[string] | `["wss://relay.damus.io", "wss://nos.lol", "wss://offchain.pub"]` | Relays used for encrypted signaling events |
| `node.discovery.nostr.stun_servers` | list[string] | `["stun:stun.l.google.com:19302", "stun:stun.cloudflare.com:3478", "stun:global.stun.twilio.com:3478"]` | STUN servers used for local reflexive address discovery |
| `node.discovery.nostr.app` | string | `"fips-overlay-v1"` | Traversal application namespace and advert identifier suffix |
| `node.discovery.nostr.signal_ttl_secs` | u64 | `120` | Signaling TTL in seconds |
| `node.discovery.nostr.attempt_timeout_secs` | u64 | `10` | Overall traversal attempt timeout in seconds |
| `node.discovery.nostr.replay_window_secs` | u64 | `300` | Replay tracking retention window in seconds |
| `node.discovery.nostr.punch_start_delay_ms` | u64 | `2000` | Delay before punch traffic starts |
| `node.discovery.nostr.punch_interval_ms` | u64 | `200` | Interval between punch packets |
| `node.discovery.nostr.punch_duration_ms` | u64 | `10000` | How long to keep punching before failure |
| `node.discovery.nostr.advert_ttl_secs` | u64 | `3600` | Advert TTL in seconds |
| `node.discovery.nostr.advert_refresh_secs` | u64 | `1800` | How often adverts are refreshed in seconds |
If `stun_servers` is omitted, the built-in default list above is used. If it is
specified in YAML, the configured list fully overrides the defaults.
Initiators use only this local list for outbound STUN queries; peer-advertised
STUN values are published for diagnostics/interoperability but are not used as
arbitrary egress targets.
The built-in advert and DM relay defaults point at widely-operated public
relays (Damus, nos.lol, Primal) as best-effort endpoints; operators are
encouraged to override them with their own relay preferences for production
deployments.
Advert freshness is enforced semantically: events with expired NIP-40
`expiration` tags are dropped, and adverts are also bounded by a created-at
staleness window derived from `advert_ttl_secs` (with a grace multiplier).
The current in-tree STUN parser handles IPv4 and IPv6 mapped-address
attributes. Local traversal candidates include active non-loopback private
interface addresses (RFC1918 IPv4 and IPv6 ULA) plus probed local egress
addresses for the punch socket port.
During punching, compatible private-subnet candidates and reflexive candidates
are attempted in parallel; the first successful path wins.
### Spanning Tree (`node.tree.*`)
Controls tree construction and parent selection.
@@ -327,6 +379,8 @@ restarting the daemon. Hostnames are case-insensitive.
| `transports.udp.mtu` | u16 | `1280` | Transport MTU |
| `transports.udp.recv_buf_size` | usize | `2097152` | UDP socket receive buffer size in bytes (2 MB). Linux kernel doubles the requested value internally. Host `net.core.rmem_max` must be >= this value. |
| `transports.udp.send_buf_size` | usize | `2097152` | UDP socket send buffer size in bytes (2 MB). Host `net.core.wmem_max` must be >= this value. |
| `transports.udp.advertise_on_nostr` | bool | `false` | Include this UDP transport in Nostr endpoint adverts |
| `transports.udp.public` | bool | `false` | If advertised: `true` publishes direct `host:port`; `false` publishes `udp:nat` rendezvous |
### Ethernet (`transports.ethernet.*`)
@@ -585,6 +639,7 @@ Static peer list. Each entry defines a peer to connect to.
| `peers[].addresses[].priority` | u8 | `100` | Address priority (lower = preferred) |
| `peers[].connect_policy` | string | `"auto_connect"` | Connection policy: `auto_connect`, `on_demand`, or `manual` |
| `peers[].auto_reconnect` | bool | `true` | Automatically reconnect after MMP link-dead removal (exponential backoff, unlimited retries) |
| `peers[].via_nostr` | bool | `false` | Append Nostr advert-derived endpoints after static addresses for this peer |
## Minimal Example
@@ -709,12 +764,10 @@ node:
identity_size: 10000
discovery:
ttl: 64
timeout_secs: 10
attempt_timeouts_secs: [1, 2, 4, 8]
recent_expiry_secs: 10
retry_interval_secs: 5
max_attempts: 2
backoff_base_secs: 30
backoff_max_secs: 300
backoff_base_secs: 0
backoff_max_secs: 0
forward_min_interval_secs: 2
tree:
announce_min_interval_ms: 500
docs/design/fips-intro.md
+12 -8
View File
@@ -510,15 +510,19 @@ and radio are natural fits for this, as they can reach nearby devices without
prior configuration. When discovery is available, nodes can automatically
find and peer with other FIPS nodes on the same medium. Transports that
lack discovery (such as configured UDP endpoints) simply skip this step and
connect directly to configured addresses. Additionally, endpoint discovery
using Nostr relays and signed events is planned, allowing internet-reachable
nodes to publish their transport addresses for other FIPS nodes to find.
connect directly to configured addresses. For internet-reachable nodes,
endpoint discovery via signed Nostr events allows nodes to publish and
consume transport addresses through public relays — available behind the
`nostr-discovery` cargo feature.
NAT traversal is not currently addressed by the protocol.
Internet-connected nodes behind NAT must be reachable through port
forwarding, a publicly addressed peer, or relay through other mesh nodes.
UDP hole punching and relay-assisted NAT traversal are potential future
mechanisms but are not part of the current design.
NAT traversal for internet-connected nodes is supported via STUN-assisted
UDP hole punching, with offer/answer signaling carried over Nostr gift-wrap
events. Once a direct UDP path is established, the punched socket is handed
into the standard FIPS transport/session stack. Nodes that cannot establish
a direct path remain reachable through port forwarding, a publicly addressed
peer, or relay through other mesh nodes. The Nostr-mediated discovery and
NAT traversal paths are gated by the `nostr-discovery` cargo feature and
configured under `node.discovery.nostr.*`.
> **Implementation status**: UDP/IP, TCP/IP, Ethernet, Tor
> (SOCKS5 outbound + directory-mode inbound via onion service),
docs/design/fips-mesh-layer.md
+6
View File
@@ -302,6 +302,12 @@ Roaming is most useful for UDP, where source addresses can change due to NAT
rebinding or network changes. For connection-oriented transports, "roaming"
manifests as reconnection rather than mid-session address change.
Roaming addresses *mid-session* NAT rebinding. Establishing the initial UDP
path through NAT is a separate concern, addressed by the optional
Nostr-mediated overlay discovery and STUN-assisted hole punching feature
(see [fips-transport-layer.md](fips-transport-layer.md) and
[fips-configuration.md](fips-configuration.md)).
## Replay Protection
Each link session maintains per-direction counters:
docs/design/fips-mesh-operation.md
+22 -10
View File
@@ -385,19 +385,31 @@ The default `max_attempts` is 2 (initial + one retry). Each retry generates
a fresh `request_id` and re-evaluates bloom filter matches, so it can take
a different path if the tree has restructured.
### Originator Backoff
### Per-Attempt Timeouts
After a lookup times out or no peer's bloom filter contains the target, the
originator enters **exponential backoff** before re-attempting discovery for
the same target:
Each discovery is a sequence of attempts with growing per-attempt timeouts.
Default sequence is `[1s, 2s, 4s, 8s]` (configurable via
`node.discovery.attempt_timeouts_secs`). When the current attempt's deadline
elapses without a `LookupResponse`, the originator sends another
`LookupRequest` with a **fresh `request_id`** and the next entry in the
sequence as its deadline. Fresh request_ids let each attempt take a
different forwarding path as the bloom and tree state evolve, which is
particularly useful during cold-start convergence. The destination is
declared unreachable only after the full sequence is exhausted (15s total
with the default).
- **Base delay**: 30s (configurable via `backoff_base_secs`)
- **Multiplier**: 2x per consecutive failure
- **Cap**: 300s (configurable via `backoff_max_secs`)
### Originator Backoff (optional, off by default)
Backoff is **reset on topology changes** that might make previously
unreachable targets reachable: parent switch, new peer connection, first
RTT measurement from MMP, or peer reconnection.
After the per-attempt sequence is exhausted, the originator can additionally
suppress further fresh lookups for the same target with exponential
post-failure backoff. This is **disabled by default** (`backoff_base_secs:
0`); the per-attempt sequence is the only retry pacing in the standard
configuration. Operators may opt in via `node.discovery.backoff_base_secs`
and `node.discovery.backoff_max_secs` if their deployment has chatty apps
generating repeated lookups for genuinely unreachable destinations. When
enabled, backoff is **reset on topology changes** that might make
previously unreachable targets reachable: parent switch, new peer
connection, first RTT measurement from MMP, or peer reconnection.
### Bloom Filter Pre-Check
docs/design/fips-nostr-discovery.md
+659
View File
@@ -0,0 +1,659 @@
# FIPS Nostr-Mediated Discovery and NAT Traversal
Nostr-mediated discovery lets FIPS nodes find each other, and if
necessary, punch through UDP NAT, using public Nostr relays as the
signaling channel. A node publishes its reachable transport endpoints to
a small set of relays under its own Nostr identity (which is also its
FIPS identity), and peers resolve those endpoints at dial time by npub.
For peers behind UDP NAT, the same relay channel carries an encrypted
offer/answer exchange, and STUN supplies the reflexive address used for
a coordinated hole-punch.
The feature is compiled into FIPS by default on all supported platforms
(Linux, macOS, Windows) and ships in every stock packaging artifact
(`.deb`, AUR, systemd tarball, OpenWrt `.ipk`, macOS `.pkg`, Windows
`.zip`). It is runtime-opt-in: the YAML configuration defaults to
disabled, so shipping the feature is a no-op until an operator enables
it. When disabled, nodes behave exactly as before: only the static
`peers[]` addresses are used. See
[Build configuration](#build-configuration) for details on opting out
at build time.
## Role
The feature adds three capabilities on top of FIPS's static peer model:
- **Advertising.** A node publishes the transport endpoints it wants
peers to use (direct UDP, direct TCP, a Tor onion, or the special
`udp:nat` rendezvous token) as a signed Nostr event. The advert is
anchored to the node's FIPS identity key — a peer that knows the npub
knows the advert is authentic.
- **Lookup.** When dialing a configured peer marked `via_nostr`, or any
peer in `policy: open` mode, the node fetches that peer's advert from
the configured relays and appends the advertised endpoints to its
dial list. Static addresses are always tried first.
- **UDP NAT hole-punch.** When both sides of a connection have UDP NAT
endpoints, the advert carries enough information to run a STUN-based
offer/answer exchange over encrypted ([NIP-59](https://github.com/nostr-protocol/nips/blob/master/59.md))
Nostr events. Each side observes its reflexive address via STUN,
exchanges candidate pairs through the relay, and both sides send UDP
probes at a shared punch time. On the first successful probe, the
punch socket is handed to FMP and becomes a normal UDP transport.
## When to use it
- **You run a public node** and want peers who know your npub to reach
you without you distributing an address list out-of-band.
- **You want to reach a peer behind UDP NAT** without deploying a relay
or running Tor on both sides. The peer advertises `udp:nat` and you
dial by npub.
- **You want zero-touch peer discovery** within a known application
namespace (`policy: open`), subject to an admission budget.
- **You want to advertise a Tor onion** so peers don't need to know the
`.onion` address out-of-band.
Skip the feature when every peer is already reachable through a stable
static address (a LAN mesh, a pre-configured test bed, or a deployment
where operators distribute `peers[]` blocks directly). The feature adds
relay dependencies, STUN round-trips for NAT cases, and a small ambient
background of relay traffic; none of that is useful when you already
know where peers are.
## Build configuration
`nostr-discovery` is a default Cargo feature. Plain `cargo build
--release` produces a binary with the feature compiled in, and every
stock packaging artifact under `packaging/` ships with it enabled.
There is no extra `--features` flag to remember, on any platform.
Shipping the feature is runtime-safe: Nostr discovery is **off by
default in the YAML configuration**
(`node.discovery.nostr.enabled: false` in every stock config). An
operator opts in per-node by flipping the flag and providing a relay
list; until then the feature is dormant and does not open connections
to any relay.
To build a binary **without** the feature — for example, to reduce
the dependency footprint on a minimal build — use
`--no-default-features`:
```bash
cargo build --release --no-default-features
```
The `nostr` and `nostr-sdk` crates are then omitted from the
dependency tree entirely, and `node.discovery.nostr` config blocks
fail at startup validation.
## Scenarios and configuration
Each scenario below gives the minimal YAML fragment that enables it.
Only keys relevant to Nostr discovery are shown; surrounding node,
transport, TUN, DNS, and peer configuration follows the usual shape
described in [fips-configuration.md](fips-configuration.md).
All scenarios assume `node.identity` is set to a persistent key — an
ephemeral identity would invalidate any advert the moment the node
restarts.
### Scenario 1: Advertise a directly-reachable UDP node
The node has a public IP (or a stable port-forward) and binds UDP on a
known port. It publishes `udp:host:port` to the advert relays. Any peer
that knows this node's npub and has Nostr discovery enabled can dial it
without knowing the address out-of-band.
```yaml
node:
identity:
persistent: true
discovery:
nostr:
enabled: true
advertise: true
transports:
udp:
bind_addr: "0.0.0.0:2121"
advertise_on_nostr: true
public: true
```
What this achieves: the node publishes a single `udp:<public-ip>:2121`
endpoint to the three default advert relays
(`wss://relay.damus.io`, `wss://nos.lol`, `wss://offchain.pub`).
What the other side needs: either a static `addresses` entry for this
peer, or a peer entry with `via_nostr: true` and an empty (or omitted)
`addresses` list — the advert-resolved endpoint will be used at dial
time. Static and Nostr-resolved addresses can also be combined: when
both are present, static addresses are tried first and Nostr-resolved
endpoints are appended as fallback.
### Scenario 2: Advertise a Tor onion node
The node runs a Tor onion service in directory mode (Tor-managed
`HiddenServiceDir`) and advertises the `.onion` address. Peers dial via
their local Tor SOCKS5 proxy without ever knowing the onion string
out-of-band.
```yaml
node:
identity:
persistent: true
discovery:
nostr:
enabled: true
advertise: true
transports:
tor:
mode: directory
socks5_addr: "127.0.0.1:9050"
directory_service:
hostname_file: "/var/lib/tor/fips/hostname"
bind_addr: "127.0.0.1:8444"
advertise_on_nostr: true
```
What this achieves: the node publishes a `tor:<hash>.onion:8443`
endpoint alongside any other advertised transports. The advert itself
is still published over clearnet WebSocket relays — Tor protects the
data plane, not the discovery plane. See
[Security and threat model](#security-and-threat-model) for the trade-off.
### Scenario 3: Lookup a configured peer by npub (no advertising)
The node does not publish any advert of its own. It only consumes
adverts for peers it has explicitly listed with `via_nostr: true`. This
is the right shape for a client that wants Nostr-mediated resolution
without becoming a rendezvous target itself.
```yaml
node:
identity:
persistent: true
discovery:
nostr:
enabled: true
advertise: false
policy: configured_only
transports:
udp:
bind_addr: "0.0.0.0:2121"
peers:
- npub: "npub1peer..."
alias: "remote-node"
addresses:
- transport: udp
addr: "203.0.113.45:2121"
priority: 10
via_nostr: true
connect_policy: auto_connect
```
What this achieves: on dial, the static address is tried first; if the
peer has published a newer advert (for example, its public IP has
changed), those addresses are appended as additional candidates.
`configured_only` is the default — it is shown here for clarity.
If you have no static address for the peer at all, omit `addresses`
entirely (or leave it empty) — `via_nostr: true` is sufficient on its
own and dial endpoints are taken from the advert.
### Scenario 4: UDP NAT hole-punch with a configured peer
Neither side has a stable public UDP endpoint. Both sides advertise
`udp:nat`, run the STUN + offer/answer exchange, and punch through
their NATs to establish a direct UDP link. This is the full
NAT-traversal path.
```yaml
node:
identity:
persistent: true
discovery:
nostr:
enabled: true
advertise: true
dm_relays:
- "wss://relay.damus.io"
- "wss://nos.lol"
stun_servers:
- "stun:stun.l.google.com:19302"
- "stun:stun.cloudflare.com:3478"
transports:
udp:
bind_addr: "0.0.0.0:2121"
advertise_on_nostr: true
public: false
peers:
- npub: "npub1peer..."
alias: "nat-peer"
addresses:
- transport: udp
addr: "nat"
priority: 1
via_nostr: true
connect_policy: auto_connect
auto_reconnect: true
```
What this achieves: the node publishes a `udp:nat` endpoint plus its
signaling relays and STUN server list in the advert. The peer side runs
the same configuration. When either side initiates, an encrypted offer
is sealed to the peer's npub, a matching answer comes back, and both
sides punch at the negotiated time. On success, the punch socket is
adopted as an FMP UDP transport and Noise IK proceeds normally.
> **Validation:** `advertise_on_nostr: true` with `public: false` on UDP
> requires both `dm_relays` and `stun_servers` to be non-empty. The
> node fails startup with a config validation error if either list is
> empty. This is enforced because 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`; fall back to a Tor or TCP transport in
that case.
### Scenario 5: Open discovery — no pre-configured peers
Under `policy: open`, any node that publishes an advert under the same
`app` namespace becomes a candidate. Discovered peers are queued for
connection attempts subject to `open_discovery_max_pending`.
```yaml
node:
identity:
persistent: true
discovery:
nostr:
enabled: true
advertise: true
policy: open
open_discovery_max_pending: 32
app: "my-experiment.v1"
transports:
udp:
bind_addr: "0.0.0.0:2121"
advertise_on_nostr: true
public: true
peers: []
```
What this achieves: peers are discovered entirely through ambient advert
traffic on the configured relays. Setting a non-default `app` value
(replacing `fips-overlay-v1`) scopes the discovery set to participants
who opt into the same experiment and avoids being joined to unrelated
overlays that happen to share the default namespace.
> **Scope warning:** Open discovery is an admission-free mode. Any node
> that publishes on the same `app` name and passes the peer-ACL check
> becomes a connection candidate. If you rely on peer ACLs for admission
> control, verify that list is set correctly before enabling this mode.
## Operational knobs
All fields below live under `node.discovery.nostr.*`. Defaults are
defined in `src/config/node.rs`.
| Field | Type | Default | Purpose |
| --- | --- | --- | --- |
| `enabled` | bool | `false` | Master switch. When false, the discovery runtime is not started. |
| `advertise` | bool | `true` | If true, publish this node's own overlay advert. |
| `advert_relays` | list | `["wss://relay.damus.io", "wss://nos.lol", "wss://offchain.pub"]` | Relays used to publish and fetch overlay adverts (kind 37195). |
| `dm_relays` | list | same as `advert_relays` | Relays used for encrypted offer/answer signaling (kind 21059). |
| `stun_servers` | list | `["stun:stun.l.google.com:19302", "stun:stun.cloudflare.com:3478", "stun:global.stun.twilio.com:3478"]` | STUN servers used to observe the local reflexive address before a punch. Peer-advertised STUN values are not used. |
| `share_local_candidates` | bool | `false` | If true, include this node's RFC 1918 / ULA interface addresses as host candidates in the traversal offer. Off by default — sharing private host candidates is only useful when peers are on the same physical LAN, and tends to cause misleading punch successes when an asymmetric L3 path (corporate VPN, Tailscale subnet route, overlapping address space) makes a peer's private IP one-way reachable. Enable per-node only when same-LAN punching is wanted. |
| `app` | string | `"fips-overlay-v1"` | Application namespace. Included in the advert identifier; only peers with the same value cross-resolve. |
| `policy` | enum | `configured_only` | Advert consumption policy: `disabled`, `configured_only`, or `open`. |
| `signal_ttl_secs` | u64 | `120` | TTL on the encrypted offer/answer events. Also caps the wait for an answer. |
| `advert_ttl_secs` | u64 | `3600` | NIP-40 expiration set on this node's published advert. |
| `advert_refresh_secs` | u64 | `1800` | Interval between re-publishes. Must be less than `advert_ttl_secs`. |
| `attempt_timeout_secs` | u64 | `10` | Overall timeout for a single punch attempt (STUN + signal + punch). |
| `punch_start_delay_ms` | u64 | `2000` | Delay between receiving the answer and sending the first punch packet. Gives the remote side time to arrive at the same point. |
| `punch_interval_ms` | u64 | `200` | Gap between successive punch probes. |
| `punch_duration_ms` | u64 | `10000` | How long to keep probing before declaring the attempt failed. |
| `replay_window_secs` | u64 | `300` | How long a session id stays in the replay-detection cache. |
| `max_concurrent_incoming_offers` | usize | `16` | Semaphore cap on inbound offers being processed simultaneously. Excess offers are dropped with a warn log. |
| `advert_cache_max_entries` | usize | `2048` | Max cached peer adverts (LRU by expiry). |
| `seen_sessions_max_entries` | usize | `2048` | Max tracked session ids for replay detection. |
| `open_discovery_max_pending` | usize | `64` | Max peers queued for connection attempts under `policy: open`. |
The per-transport keys are:
| Key | Type | Where | Default | Purpose |
| --- | --- | --- | --- | --- |
| `advertise_on_nostr` | bool | `transports.{udp,tcp,tor}` | `false` | Include this transport's endpoint in the overlay advert. |
| `public` | bool | `transports.udp` | `false` | When `advertise_on_nostr` is true: `true` publishes `udp:host:port`, `false` publishes `udp:nat`. |
| `via_nostr` | bool | `peers[]` | `false` | Append advert-resolved endpoints to this peer's dial list. |
## Validation rules at startup
The following combinations are rejected with `ConfigError::Validation`:
- Any transport sets `advertise_on_nostr: true` while
`node.discovery.nostr.enabled` is `false` or absent.
- Any peer sets `via_nostr: true` while
`node.discovery.nostr.enabled` is `false` or absent.
- A UDP transport sets `advertise_on_nostr: true` with `public: false`
(a `udp:nat` advert) but `dm_relays` is empty.
- A UDP transport sets `advertise_on_nostr: true` with `public: false`
but `stun_servers` is empty.
## Under the covers
The rest of this document describes how the feature works inside the
node. For the on-the-wire event format and NIP references, see the
protocol reference at
[../proposals/nostr-udp-hole-punch-protocol.md](../proposals/nostr-udp-hole-punch-protocol.md).
### Overview
The discovery runtime is a background task group started during node
initialization when `nostr.enabled` is true. It maintains a single
`nostr-sdk` client connected to the union of `advert_relays` and
`dm_relays`, and runs four loops: advert publication, advert
subscription (for open discovery and cache warming), DM subscription
(for incoming offers and answers), and a periodic advert-cache prune.
Discovery has no CLI surface; all operations are driven by the
configuration and by connection attempts made by the rest of the node.
```text
+-----------------------+
| Discovery runtime |
+-----------------------+
| | |
advert publish | | DM sub (offers, answers)
| |
v v
+-------------------------+
| Nostr relay pool | (advert_relays ∪ dm_relays)
+-------------------------+
^ ^
advert fetch/cache | | encrypted signaling
| |
+----------------+ | | +--------------------+
| connect_peer |--+ +->| offer / answer |
| (node side) | | handler |
+----------------+ +--------------------+
| |
v v
+---------+ +--------------+
| STUN |<-- same socket --->| UDP punch |
+---------+ +--------------+
|
v
adopt_established_traversal()
|
v
FMP IK handshake
on adopted socket
```
### Phase 1 — Advertisement
Adverts are published as Nostr kind `37195` parameterized replaceable
events (FIPS-specific, in the application-defined replaceable range
`30000–39999`; the digits visually spell `FIPS` — 7=F, 1=I, 9=P, 5=S).
The `d` tag is set to the `app` value (default `fips-overlay-v1`), so
each node has a single, in-place-updatable advert under its identity.
The event is signed with the node's FIPS identity key; there is no
separate Nostr key. A NIP-40 `expiration` tag is set to now +
`advert_ttl_secs`.
The advert content is a JSON document shaped as `OverlayAdvert`:
```json
{
"identifier": "fips-overlay-v1",
"version": 1,
"endpoints": [
{"transport": "udp", "addr": "203.0.113.45:2121"},
{"transport": "tor", "addr": "xxxxx.onion:8443"},
{"transport": "udp", "addr": "nat"}
],
"signalRelays": ["wss://relay.damus.io", "wss://nos.lol"],
"stunServers": ["stun:stun.l.google.com:19302"]
}
```
`signalRelays` and `stunServers` are only present when at least one
endpoint is `udp:nat`; for advert shapes that cannot involve punching
they are omitted to reduce advert size and keep the relay and STUN
lists private to the nodes that need them.
Publication happens on startup, again whenever the set of advertised
endpoints changes (for example, when a Tor onion hostname first
becomes available), and on a refresh timer every `advert_refresh_secs`.
If the `advertise` flag is turned off, the previous advert event is
deleted using a NIP-9 kind 5 delete event. Advert publication is
fan-out: the same event is sent to every relay in `advert_relays` with
no explicit failover — relay redundancy is implicit.
### Phase 2 — Lookup
When the node decides to dial a peer that is eligible for Nostr
resolution (a `via_nostr` peer, or any peer under `policy: open`), it
issues a Nostr REQ filtered by `author = peer_pubkey`, `kind = 37195`,
`#d = <app>`. The fetch is time-bounded (~2 s) and runs against all
configured `advert_relays` in parallel. The first valid advert wins.
Results are kept in an in-memory cache keyed by author npub. Cache
entries carry the advert's expiration time; a periodic prune drops
expired entries, and an LRU-by-expiry eviction enforces
`advert_cache_max_entries`. A parallel long-lived subscription on the
advert relays populates the cache passively, so open-discovery
candidates do not require per-dial fetches.
On cache hit, advert endpoints are appended to the peer's static
address list with lower priority; the static list is tried first.
### Phase 3 — Offer/Answer signaling
For any endpoint shaped as `udp:nat`, dialing triggers an
offer/answer exchange before the first packet is sent. Signaling events
are Nostr kind `21059` (ephemeral, not stored by conforming relays),
gift-wrapped per [NIP-59](https://github.com/nostr-protocol/nips/blob/master/59.md)
and encrypted with [NIP-44](https://github.com/nostr-protocol/nips/blob/master/44.md),
so only the intended recipient can decrypt the payload.
The initiator performs STUN first (see Phase 4), then builds a
`TraversalOffer` containing:
- A unique `sessionId` and a random `nonce` (used to correlate the
answer).
- Its reflexive address (if STUN succeeded).
- Its list of local (private) addresses for same-LAN paths.
- The STUN server it used, for informational reporting only.
- An `expiresAt` equal to now + `signal_ttl_secs`.
The offer is sealed to the recipient's npub and published to the peer's
preferred signaling relays — the node first tries to resolve the peer's
NIP-65 inbox relay list (kind 10002), and falls back to `dm_relays` if
the inbox-relays fetch fails. Each side also publishes its own inbox
relay list on startup so dialers can discover it.
On the receiving side, an inbound semaphore bounds concurrent offer
processing at `max_concurrent_incoming_offers`. When the semaphore is
full, the offer is dropped with a warn log; this is the primary guard
against offer-spam from a misbehaving or compromised relay. A
`sessionId` replay cache (bounded by `seen_sessions_max_entries`, with
entries valid for `replay_window_secs`) rejects duplicates.
The responder runs its own STUN query and replies with a
`TraversalAnswer` carrying its reflexive and local addresses plus a
`PunchHint { startAtMs, intervalMs, durationMs }` that tells both sides
when to begin probing and how aggressively. If the responder has no
usable addresses at all, it replies with `accepted: false` and a
`reason` string.
### Phase 4 — UDP hole-punch
Each side runs STUN (parsing XOR-MAPPED-ADDRESS from the response, all
other attributes ignored) on the *same* UDP socket it will later use
for punching and for the adopted FMP transport. This is critical: NAT
state is per-socket, so the punch has to reuse the socket that taught
the NAT about this binding.
Given its own reflexive + local addresses and the peer's, each side
builds a candidate-pair plan that tries, in priority order:
1. **Reflexive ↔ reflexive.** The classic STUN path. Tried first because
it is the only candidate that's reliable across arbitrary network
topologies — host candidates from one peer that happen to be
reachable from the other (via a corporate VPN, a Tailscale subnet
route, or overlapping private address space) will succeed at the
socket layer in the punch but fail in the FMP handshake when the
return path doesn't match.
2. **LAN ↔ LAN.** If both sides share a /24 prefix, same-subnet private
addresses are likely reachable directly. Only fires when both peers
shared local host candidates (which requires `share_local_candidates`
to be enabled — off by default).
3. **Mixed.** Reflexive on one side, local on the other — catches
hairpin and one-side-public scenarios.
At `startAtMs` both sides begin sending 24-byte probe packets on the
candidate pair(s) at `intervalMs` cadence for up to `durationMs`. A
probe carries a 4-byte magic (`NPTC`), a 4-byte sequence, and the
first 16 bytes of `SHA256(sessionId)`; both sides can compute the same
session hash independently from the public `sessionId`, so no shared
secret is needed on the punch path itself. On receiving a valid probe,
a side replies with an `NPTA` ack. The first valid probe or ack seen
from the far side records the working remote address and completes the
attempt.
On timeout (`attempt_timeout_secs` as overall bound,
`punch_duration_ms` as probe window), both sides issue NIP-9 deletes
for their offer and answer events and report failure up to the
discovery runtime's `BootstrapEvent::Failed` channel.
### Phase 5 — Adoption
On success, the discovery runtime emits `BootstrapEvent::Established`
carrying the session id, the punch socket, and the learned remote
address. `adopt_established_traversal()` in the node lifecycle takes
the socket, registers it with the UDP transport layer as a new
transport instance, and calls `initiate_connection()` with the peer's
FIPS identity as the expected remote. FMP's Noise IK handshake runs on
the same socket — there is no "promote link" step between punch and
handshake; the punch socket *is* the FMP socket.
From that moment on, the connection is a normal FMP link and is
subject to the usual liveness (MMP heartbeats), rekey, and removal
behavior. A link-dead event does not re-enter the discovery runtime
automatically; reconnection relies on `auto_reconnect` and the same
dial path that triggered the original punch.
### Auto-connect semantics
Discovery does not itself initiate connections. It only supplies
addresses. Dial attempts originate from the existing peer-connection
machinery:
- **Configured peers** (`peers[]` with `connect_policy: auto_connect`)
are dialed on startup and on retry. When `via_nostr` is set, advert
endpoints are appended to the dial list with lower priority than
static entries.
- **Open discovery peers** are assembled from the advert cache, fenced
by the peer ACL, and enqueued into a bounded retry queue sized by
`open_discovery_max_pending`. There is no event-driven
"connect on every advert" — a peer re-enters the queue only when its
prior attempt has drained.
- **Manual dials** (`fipsctl connect`) can target any configured peer
and use the same dial path, including Nostr resolution if configured.
### Rate limits and safeguards
| Mechanism | Default | What it prevents | Behavior at limit |
| --- | --- | --- | --- |
| Offer semaphore (`max_concurrent_incoming_offers`) | 16 | CPU and memory exhaustion from offer spam on DM relays. | Warn log, offer dropped. |
| Advert cache (`advert_cache_max_entries`) | 2048 | Memory growth from ambient advert traffic under `policy: open`. | LRU-by-expiry eviction. |
| Seen-sessions (`seen_sessions_max_entries`) | 2048 | Replay of stale `sessionId` values. | Oldest entry evicted. |
| Signal TTL (`signal_ttl_secs`) | 120 s | Indefinite in-flight offers on relays. | Expired offers rejected at validation. |
| Open discovery queue (`open_discovery_max_pending`) | 64 | Unbounded retry queue under ambient advert load. | New candidates skipped until the queue drains. |
| Punch window (`punch_duration_ms`) | 10 s | Endless probe traffic after one side has given up. | Attempt declared failed; sockets discarded. |
Only one of these (`max_concurrent_incoming_offers`) is a load-shedding
mechanism — the rest are capacity bounds. The load-shedding threshold
is deliberately conservative so that a misbehaving relay cannot flood
the node with offers fast enough to starve legitimate traffic.
### Relay model
All configured relays (advert + DM) are opened on a single
`nostr-sdk::Client` at startup. Publication is fan-out: the same event
is sent to every relay in the target list, with no explicit retry or
relay selection. Redundancy is implicit — a downed relay simply means
its copy of the advert or signal is unavailable, while other relays
still serve the same data.
For signaling specifically, the node prefers the recipient's NIP-65
inbox relays when available (the recipient publishes its inbox list as
a kind 10002 event to its own DM relays on startup) and falls back to
the local `dm_relays` list otherwise. This keeps the common case
off the sender's DM relays when those are different from the
recipient's, at the cost of one extra NIP-65 fetch per offer.
There is no per-relay rate limiting or health check. The relay model
assumes that an operator chooses relays they trust to be best-effort
available and that outright misbehavior is handled at the offer
semaphore and replay-cache layers downstream.
## Security and threat model
- **Relay operators can observe metadata.** They see which npubs
publish adverts, to whom offers are sent, and the timing of that
traffic. The *contents* of offer and answer events are
NIP-59/NIP-44 sealed — only the intended recipient decrypts them.
Adverts are public by design.
- **STUN servers see the node's public IP and port.** Only the STUN
servers listed in the node's own `stun_servers` are ever contacted
for reflexive discovery. Peer-advertised STUN values are
informational; a malicious peer cannot steer this node to a
chosen STUN target. See the doc comment on
`node.discovery.nostr.stun_servers`.
- **The FIPS identity key signs adverts.** Compromise of
`fips.key` is compromise of the node's Nostr identity — an attacker
can publish adverts on behalf of the node. The recovery path is
the same as for any identity compromise: rotate the key and
re-advertise. There is no separate Nostr keypair to rotate
independently.
- **Tor advertising leaks timing via clearnet relays.** When a
Tor-only node advertises its onion address, the advert itself is
published on clearnet WebSocket relays. Operators who want full
unlinkability between the advertising identity and the node's
IP must route relay traffic through Tor as well — for example by
running `fips` inside a network namespace with a Tor SOCKS
proxy as its only egress, or by pointing `advert_relays` and
`dm_relays` at onion relay endpoints.
- **Open discovery accepts anyone publishing on the same `app`.**
Admission control is the peer ACL, not the discovery layer. Verify
the ACL before enabling `policy: open`, and consider using a
non-default `app` value to scope visibility.
- **Nothing about discovery bypasses FMP.** A successful punch yields
a UDP socket with a claimed remote identity. That identity is not
trusted until FMP's Noise IK handshake completes. A peer whose
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.
## See also
- [fips-configuration.md](fips-configuration.md) — full configuration
reference, including all surrounding keys elided from the scenarios
above.
- [fips-transport-layer.md](fips-transport-layer.md) — UDP, TCP, and
Tor transport mechanics; the punch socket is adopted as a normal
UDP transport after handoff.
- [fips-mesh-layer.md](fips-mesh-layer.md) — FMP Noise IK handshake
that runs on the adopted socket.
- [../proposals/nostr-udp-hole-punch-protocol.md](../proposals/nostr-udp-hole-punch-protocol.md)
— protocol-level reference for event tags, NIP usage, and the
on-the-wire offer/answer schema.
docs/design/fips-transport-layer.md
+12 -3
View File
@@ -693,7 +693,7 @@ X." FMP does not need to distinguish beacons from query responses.
| Radio | Beacon | Shared RF channel, natural fit |
| BLE | Advertising | GATT service UUID |
### Nostr Relay Discovery *(future direction)*
### Nostr Relay Discovery
For internet-reachable transports, a node publishes a signed Nostr event
containing its FIPS discovery information — public key and reachable
@@ -705,6 +705,12 @@ feeds addresses to other transports. A node discovers via Nostr that a peer
is reachable at UDP 1.2.3.4:9735, then establishes the link over the UDP
transport.
For NAT'd UDP endpoints, a node may advertise `addr: "nat"` instead of a
concrete address, signaling that peers should initiate STUN-assisted UDP
hole punching. Offer/answer exchange uses Nostr gift-wrap (NIP-59) events
on the configured DM relays; the resulting punched socket is adopted into
the standard UDP transport via the bootstrap handoff path.
Key properties:
- Identity is built in — Nostr events are signed, so discovery information
@@ -721,8 +727,11 @@ Key properties:
> broadcast — the `discover()` trait method returns newly seen endpoints,
> and per-transport `auto_connect()` / `accept_connections()` policies
> control whether discovered peers are connected automatically or require
> explicit configuration. TCP and Tor have no discovery mechanism.
> Nostr relay discovery is not yet implemented.
> explicit configuration. TCP and Tor have no built-in discovery mechanism.
> Nostr relay discovery and STUN-assisted UDP hole punching are
> implemented behind the `nostr-discovery` cargo feature; see
> [fips-configuration.md](fips-configuration.md) for the
> `node.discovery.nostr.*` configuration tree.
## Transport Interface
docs/proposals/README.md
+9 -6
View File
@@ -1,9 +1,12 @@
# Proposals
Protocol proposals and specifications for features under consideration.
These documents describe mechanisms that have not yet been implemented
and may evolve significantly during review.
Protocol proposals and specifications for features under consideration or
recently implemented. Documents marked Proposed describe mechanisms that
have not yet been implemented and may evolve significantly during review.
| Document | Description |
|----------|-------------|
| [nostr-udp-hole-punch-protocol.md](nostr-udp-hole-punch-protocol.md) | Nostr-signaled UDP hole punching protocol |
Implemented proposals are retained as protocol references until they are
superseded by dedicated design documents.
| Document | Status | Description |
|----------------------------------------------------------------------|-------------|----------------------------------------------------------------------------------------|
| [nostr-udp-hole-punch-protocol.md](nostr-udp-hole-punch-protocol.md) | Implemented | Nostr-signaled UDP hole punching protocol (behind the `nostr-discovery` cargo feature) |
docs/proposals/nostr-udp-hole-punch-protocol.md
+93 -38
View File
@@ -1,5 +1,9 @@
# Nostr-Signaled UDP Hole Punching Protocol
> **Status**: Implemented behind the `nostr-discovery` cargo feature.
> This proposal is retained as a protocol reference and will be
> superseded by a dedicated design document.
## Abstract
This document describes a protocol for establishing direct UDP connectivity between two peers behind NAT, using Nostr relays as the signaling channel and public STUN servers for reflexive address discovery. The protocol assumes a **responder** that advertises a UDP service via a Nostr replaceable event, and an **initiator** that discovers the responder and negotiates a direct UDP connection.
@@ -13,7 +17,19 @@ No WebRTC, DTLS, or ICE stack is required. The protocol operates at the raw UDP
- **Initiator**: The peer that discovers the responder's service advertisement and begins the connection process.
- **Responder**: The peer running a UDP service, which has published a replaceable event advertising its availability.
- **Reflexive address**: The public `IP:port` tuple as observed by a STUN server (i.e., the NAT's external mapping).
- **Punch socket**: The single UDP socket a peer uses for both STUN queries and subsequent hole-punching traffic. This socket **must not** change between phases.
- **Punch socket**: The single UDP socket a peer uses for both STUN queries and subsequent hole-punching traffic within one connection attempt. This socket **must not** change between phases of that attempt.
### Socket lifecycle
This protocol assumes **per-peer, per-attempt punch sockets**:
- Each outbound traversal attempt creates a fresh UDP socket bound to `0.0.0.0:0`.
- That socket is owned by exactly one remote peer and exactly one traversal session.
- STUN, offer/answer metadata, punch packets, and the eventual adopted UDP transport all use that same socket for the lifetime of the attempt.
- If the attempt fails, the socket is discarded. A retry allocates a new socket and obtains a fresh reflexive address.
- The long-lived application UDP listener (for example, a fixed port such as `2121`) is **not** reused as the punch socket.
This choice avoids cross-peer state coupling and keeps NAT mappings, retry state, and adopted traversal transports isolated per peer.
---
@@ -21,10 +37,10 @@ No WebRTC, DTLS, or ICE stack is required. The protocol operates at the raw UDP
| Purpose | Kind | Persistence |
|---|---|---|
| Service advertisement | `30078` (parameterized replaceable) | Persistent, updated by responder |
| Service advertisement | `37195` (parameterized replaceable) | Persistent, updated by responder |
| Signaling messages | `21059` (ephemeral gift-wrap) | Ephemeral, not stored by relays |
The service advertisement uses kind `30078` (an application-specific parameterized replaceable event per NIP-78), allowing the responder to update it in place. Signaling messages use ephemeral gift-wrapped events (kind `21059`, combining NIP-59 gift wrap with the ephemeral kind range `20000–29999`) to avoid relay storage.
The service advertisement uses kind `37195`, an application-specific parameterized replaceable event in the NIP-01 replaceable range `30000–39999`. The digits visually spell `FIPS` (7=F, 1=I, 9=P, 5=S). The replaceable semantics let the responder update the advert in place under the same `d` tag. Signaling messages use ephemeral gift-wrapped events (kind `21059`, combining NIP-59 gift wrap with the ephemeral kind range `20000–29999`) to avoid relay storage.
---
@@ -34,11 +50,11 @@ The responder publishes a parameterized replaceable event advertising its UDP se
```json
{
"kind": 30078,
"kind": 37195,
"pubkey": "<responder_pubkey>",
"created_at": <timestamp>,
"tags": [
["d", "udp-service-v1/<application_id>"],
["d", "fips-overlay-v1"],
["protocol", "<application_protocol_name>"],
["version", "<protocol_version>"],
["relays", "wss://relay1.example.com", "wss://relay2.example.com"],
@@ -52,7 +68,7 @@ The responder publishes a parameterized replaceable event advertising its UDP se
### Tag semantics
- **`d`**: Namespaced identifier. The prefix `udp-service-v1/` scopes this to the protocol; `<application_id>` is an application-defined string (e.g., `myapp-sync`).
- **`d`**: Namespaced identifier. `fips-overlay-v1` scopes this to FIPS overlay endpoint adverts.
- **`protocol`**: Application protocol name for filtering (e.g., `myapp-file-sync`).
- **`version`**: Protocol version string for compatibility checking.
- **`relays`**: One or more relay URLs where the responder subscribes for incoming signaling messages. The initiator **must** send signaling events to at least one of these relays.
@@ -62,6 +78,11 @@ The responder publishes a parameterized replaceable event advertising its UDP se
The responder should update this event (same `d` tag, new `created_at`) whenever its parameters change, and publish a kind `5` deletion event (NIP-09) when it goes offline permanently.
Current in-tree defaults:
- `node.discovery.nostr.advert_ttl_secs = 3600` (1 hour)
- `node.discovery.nostr.advert_refresh_secs = 1800` (30 minutes)
---
## Phase 1: Discovery (Initiator)
@@ -70,9 +91,9 @@ The initiator queries one or more relays for the responder's service advertiseme
```json
["REQ", "<sub_id>", {
"kinds": [30078],
"kinds": [37195],
"authors": ["<responder_pubkey>"],
"#d": ["udp-service-v1/<application_id>"]
"#d": ["fips-overlay-v1"]
}]
```
@@ -80,12 +101,19 @@ If the responder's pubkey is not known in advance, the initiator can discover pe
```json
["REQ", "<sub_id>", {
"kinds": [30078],
"kinds": [37195],
"#protocol": ["<application_protocol_name>"]
}]
```
Upon receiving the advertisement, the initiator extracts the relay list and STUN server preferences.
Upon receiving the advertisement, the initiator extracts the relay list and any
advertised STUN metadata. In the current in-tree implementation, advertised
STUN entries are informational only; outbound STUN is driven by the initiator's
own configured allowlist.
The current in-tree STUN parser handles IPv4 and IPv6 mapped-address
responses. Offer/answer local-address candidates include active private
non-loopback interface addresses (RFC1918 IPv4 and IPv6 ULA) plus probed local
egress addresses.
---
@@ -93,12 +121,13 @@ Upon receiving the advertisement, the initiator extracts the relay list and STUN
Before sending any signaling message, the initiator binds a UDP socket and performs a STUN Binding Request:
1. Bind a UDP socket to `0.0.0.0:0` (OS-assigned port). This becomes the **punch socket**.
2. Send a STUN Binding Request (RFC 8489) to one of the STUN servers listed in the responder's advertisement.
1. Bind a fresh UDP socket to `0.0.0.0:0` (OS-assigned port). This becomes the **punch socket** for this peer and this traversal attempt.
2. Send a STUN Binding Request (RFC 8489) to one of the initiator's locally configured STUN servers.
3. Parse the Binding Response and extract the `XOR-MAPPED-ADDRESS` attribute — this is the initiator's reflexive address.
4. Record the local socket address and the reflexive address.
4. Record the reflexive address and local interface candidates for the same
punch-socket port.
**Critical**: The punch socket must remain open and must be reused for all subsequent protocol phases. Closing or rebinding it invalidates the NAT mapping.
**Critical**: The punch socket must remain open and must be reused for all subsequent protocol phases of the same attempt. Closing or rebinding it invalidates the NAT mapping.
---
@@ -110,21 +139,29 @@ The initiator constructs a signaling message containing its reflexive address an
```json
{
"app": "<app-namespace>",
"eventKind": 21059,
"type": "offer",
"session_id": "<random_hex_32>",
"reflexive_addr": "<ip>:<port>",
"local_addr": "<ip>:<port>",
"stun_server": "<host>:<port>",
"timestamp": <unix_seconds>,
"sessionId": "<random_hex_32>",
"issuedAt": <unix_millis>,
"expiresAt": <unix_millis>,
"nonce": "<random_nonce>",
"senderNpub": "<initiator_npub>",
"recipientNpub": "<responder_npub>",
"reflexiveAddress": {"protocol":"udp","ip":"<ip>","port":<port>},
"localAddresses": [{"protocol":"udp","ip":"<ip1>","port":<port>}],
"stunServer": "<host>:<port>",
"app_params": { ... }
}
```
- **`session_id`**: A random 32-character hex string identifying this connection attempt. Both peers use this to correlate signaling messages belonging to the same session.
- **`reflexive_addr`**: The initiator's reflexive address as reported by STUN.
- **`local_addr`**: The initiator's local socket address. Useful if both peers happen to be on the same LAN (the responder can attempt a direct local connection in parallel).
- **`stun_server`**: Which STUN server the initiator used, so the responder can use the same one if desired.
- **`timestamp`**: Unix timestamp. The responder should reject offers older than a threshold (e.g., 60 seconds) since the NAT mapping may have expired.
- **`sessionId`**: A random 32-character hex string identifying this connection attempt. Both peers use this to correlate signaling messages belonging to the same session.
- **`reflexiveAddress`**: The initiator's reflexive address as reported by STUN.
- **`localAddresses`**: Candidate local interface addresses for the same socket
port. Useful if both peers happen to share a private subnet (the responder
can attempt direct local paths in parallel).
- **`stunServer`**: Which STUN server the initiator used, so the responder can use the same one if desired.
- **`issuedAt`/`expiresAt`**: Freshness window. The responder should reject stale offers since the NAT mapping may have expired.
- **`app_params`**: Optional application-specific handshake parameters.
### Wrapping and delivery
@@ -176,8 +213,8 @@ Upon receiving and decrypting an offer, the responder:
1. Validates the timestamp (rejects if older than 60 seconds).
2. Validates the `session_id` is not a replay of a previously seen session.
3. Binds its own **punch socket** to `0.0.0.0:0`.
4. Performs a STUN Binding Request (preferably using the same STUN server the initiator used).
3. Binds its own fresh **punch socket** to `0.0.0.0:0`.
4. Performs a STUN Binding Request using one of the responder's locally configured STUN servers.
5. Extracts its own reflexive address.
6. Constructs and sends an answer:
@@ -185,29 +222,45 @@ Upon receiving and decrypting an offer, the responder:
```json
{
"app": "<app-namespace>",
"eventKind": 21059,
"type": "answer",
"session_id": "<same session_id from offer>",
"reflexive_addr": "<ip>:<port>",
"local_addr": "<ip>:<port>",
"stun_server": "<host>:<port>",
"timestamp": <unix_seconds>,
"sessionId": "<same sessionId from offer>",
"issuedAt": <unix_millis>,
"expiresAt": <unix_millis>,
"nonce": "<random_nonce>",
"senderNpub": "<responder_npub>",
"recipientNpub": "<initiator_npub>",
"inReplyTo": "<offer_nonce>",
"accepted": true,
"reflexiveAddress": {"protocol":"udp","ip":"<ip>","port":<port>},
"localAddresses": [{"protocol":"udp","ip":"<ip1>","port":<port>}],
"stunServer": "<host>:<port>",
"app_params": { ... }
}
```
This is encrypted and gift-wrapped identically to the offer, but addressed to the initiator's pubkey and published to the same relay(s).
Implementations should also bind the JSON sender/recipient identity fields to
the actual Nostr pubkeys that delivered the gift-wrapped events, rather than
treating those JSON fields as independently trustworthy.
**Immediately after publishing the answer**, the responder begins Phase 5 (punching) without waiting for confirmation that the initiator received it. Time is critical — the NAT mappings are decaying.
---
## Phase 5: Hole Punching
Both peers now know each other's reflexive address. Both begin sending UDP packets to the other's reflexive address from their punch socket.
Both peers now know each other's reflexive address and local-address
candidates. Both begin sending UDP packets from their punch socket.
### Procedure
1. Both peers send a punch packet to the other's reflexive address once every **200ms**.
1. Both peers send punch packets every **200ms** across planned target paths:
- reflexive-to-reflexive
- private-subnet local-address paths (when subnet-compatible)
- mixed local/reflexive fallbacks
2. Each punch packet contains a fixed magic header to distinguish it from stray traffic:
```
@@ -228,17 +281,19 @@ Bytes 8–23: first 16 bytes of SHA-256(session_id)
### Timeout
If no valid punch packet is received within **10 seconds**, the attempt has failed. Possible causes include symmetric NAT on one or both sides, firewall interference, or stale reflexive addresses. The initiator may retry with a fresh STUN query and new offer, or fall back to an application-level relay.
If no valid punch packet is received within **10 seconds**, the attempt has failed. Possible causes include symmetric NAT on one or both sides, firewall interference, or stale reflexive addresses. The initiator may retry with a fresh STUN query, a fresh punch socket, and a new offer, or fall back to an application-level relay.
### LAN optimization
If both peers' `local_addr` values are in the same private subnet (e.g., both `192.168.1.x`), the peers should simultaneously attempt punching via both the reflexive address and the local address. The first path to complete wins.
If both peers advertise compatible private-subnet candidates (e.g.,
`192.168.1.x`), they should simultaneously attempt punching via both reflexive
and local-address paths. The first path to complete wins.
---
## Phase 6: Application Protocol Handoff
Once both peers have exchanged acknowledgments, the connection is established. The punch socket is now a live UDP channel between the two peers. From this point:
Once both peers have exchanged acknowledgments, the connection is established. The punch socket for that attempt is now a live UDP channel between the two peers. From this point:
- The application protocol takes over the socket.
- The Nostr signaling channel is no longer needed for this session.
@@ -265,7 +320,7 @@ After the hole punch succeeds (or fails), both peers perform cleanup:
3. Because the signaling events used an ephemeral kind (`21059`) with an `expiration` tag, well-behaved relays will discard them automatically even without explicit deletion.
If the responder is going offline permanently, it should also delete its kind `30078` service advertisement.
If the responder is going offline permanently, it should also delete its kind `37195` service advertisement.
---
@@ -283,7 +338,7 @@ The `session_id` and `timestamp` fields protect against replay attacks on the si
### Metadata exposure
Even though signaling content is encrypted, the gift-wrap metadata reveals that the initiator's ephemeral pubkey contacted the responder's pubkey at a particular time, through a particular relay. The service advertisement (kind `30078`) is public and reveals the responder's pubkey and that it is running a particular service.
Even though signaling content is encrypted, the gift-wrap metadata reveals that the initiator's ephemeral pubkey contacted the responder's pubkey at a particular time, through a particular relay. The service advertisement (kind `37195`) is public and reveals the responder's pubkey and that it is running a particular service.
If metadata privacy is required, the `content` of the service advertisement can be encrypted (requiring the initiator to already know the responder's pubkey), and both peers can use ephemeral Nostr identities rather than their long-term keys.
packaging/aur/PKGBUILD
+2 -2
View File
@@ -29,13 +29,13 @@ build() {
cd "$pkgname-$pkgver"
export CARGO_TARGET_DIR=target
export SOURCE_DATE_EPOCH=$(stat -c %Y Cargo.toml)
cargo build --frozen --release --features gateway
cargo build --frozen --release
}
check() {
cd "$pkgname-$pkgver"
export CARGO_TARGET_DIR=target
cargo test --frozen --lib --features gateway
cargo test --frozen --lib
}
package() {
packaging/common/fips.yaml
+30
View File
@@ -10,6 +10,30 @@ node:
#
# Or set an explicit key (overrides persistent):
# nsec: "nsec1..."
discovery:
# Optional Nostr-mediated overlay endpoint discovery.
# Requires a build of fips compiled with the 'nostr-discovery' feature.
# nostr:
# enabled: true
# policy: configured_only # disabled | configured_only | open
# open_discovery_max_pending: 64 # caps queued open-discovery retries
# app: "fips-overlay-v1"
# advertise: true
# advert_relays:
# - "wss://relay.damus.io"
# - "wss://nos.lol"
# - "wss://offchain.pub"
# dm_relays:
# - "wss://relay.damus.io"
# - "wss://nos.lol"
# - "wss://offchain.pub"
# # Optional override. If omitted, FIPS uses the built-in STUN list.
# # Built-in relay/STUN defaults are best-effort and should be
# # overridden by operators for production use.
# stun_servers:
# - "stun:stun.l.google.com:19302"
# - "stun:stun.cloudflare.com:3478"
# - "stun:global.stun.twilio.com:3478"
tun:
enabled: true
@@ -27,10 +51,13 @@ dns:
transports:
udp:
bind_addr: "0.0.0.0:2121"
# advertise_on_nostr: true
# public: false # false => advertise udp:nat; true => advertise bound host:port
tcp:
# Accepts inbound connections. No static outbound peers.
bind_addr: "0.0.0.0:8443"
# advertise_on_nostr: true
# Ethernet transport — uncomment and set your interface name.
# ethernet:
@@ -71,7 +98,10 @@ peers: []
# Static peers for bootstrapping (UDP or TCP):
# - npub: "npub1qmc3cvfz0yu2hx96nq3gp55zdan2qclealn7xshgr448d3nh6lks7zel98"
# alias: "gateway"
# via_nostr: true
# addresses:
# - transport: udp
# addr: "217.77.8.91:2121" # IP or hostname (e.g., "peer.example.com:2121")
# - transport: udp
# addr: "nat" # Use node.discovery.nostr for Nostr/STUN hole punching
# connect_policy: auto_connect
packaging/debian/build-deb.sh
+1 -1
View File
@@ -71,7 +71,7 @@ echo "Building .deb package..."
OUTPUT_DIR="$(mktemp -d)"
trap 'rm -rf "${OUTPUT_DIR}"' EXIT
cargo_args=(deb --output "${OUTPUT_DIR}" --features gateway)
cargo_args=(deb --output "${OUTPUT_DIR}")
if [[ -n "${TARGET_TRIPLE}" ]]; then
cargo_args+=(--target "${TARGET_TRIPLE}")
fi
packaging/macos/build-pkg.sh
+1 -1
View File
@@ -72,7 +72,7 @@ echo "Building FIPS v${VERSION} for macOS ${ARCH}..."
# Build release binaries
if [[ "${NO_BUILD}" -eq 0 ]]; then
cargo_args=(build --release --manifest-path="${PROJECT_ROOT}/Cargo.toml" --no-default-features --features tui)
cargo_args=(build --release --manifest-path="${PROJECT_ROOT}/Cargo.toml")
[[ -n "${TARGET_TRIPLE}" ]] && cargo_args+=(--target "${TARGET_TRIPLE}")
cargo "${cargo_args[@]}"
fi
packaging/openwrt-ipk/build-ipk.sh
-2
View File
@@ -109,8 +109,6 @@ cd "$PROJECT_ROOT"
cargo zigbuild \
--release \
--target "$RUST_TARGET" \
--no-default-features \
--features tui,gateway \
--bin fips \
--bin fipsctl \
--bin fipstop \
packaging/systemd/build-tarball.sh
+2 -2
View File
@@ -84,9 +84,9 @@ fi
echo "Building FIPS v${VERSION} for ${ARCH}..."
# Build release binaries (tui is a default feature, includes fipstop)
# Build release binaries
if [[ "${NO_BUILD}" -eq 0 ]]; then
cargo_args=(build --release --manifest-path="${PROJECT_ROOT}/Cargo.toml" --features gateway)
cargo_args=(build --release --manifest-path="${PROJECT_ROOT}/Cargo.toml")
if [[ -n "${TARGET_TRIPLE}" ]]; then
cargo_args+=(--target "${TARGET_TRIPLE}")
fi
packaging/windows/build-zip.ps1
+1 -1
View File
@@ -38,7 +38,7 @@ Write-Host "Building FIPS v$Version for Windows $Arch..."
# Build release binaries
if (-not $NoBuild) {
Push-Location $ProjectRoot
cargo build --release --no-default-features --features tui
cargo build --release
if ($LASTEXITCODE -ne 0) {
Write-Error "cargo build failed"
exit 1
src/bin/fips-gateway.rs
+19
View File
@@ -3,21 +3,33 @@
//! Allows unmodified LAN hosts to reach FIPS mesh destinations via
//! DNS-allocated virtual IPs and kernel nftables NAT.
#[cfg(target_os = "linux")]
use clap::Parser;
#[cfg(target_os = "linux")]
use fips::Config;
#[cfg(target_os = "linux")]
use fips::gateway::{control, dns, nat, net, pool};
#[cfg(target_os = "linux")]
use fips::version;
#[cfg(target_os = "linux")]
use std::path::PathBuf;
#[cfg(target_os = "linux")]
use std::sync::Arc;
#[cfg(target_os = "linux")]
use std::sync::atomic::{AtomicUsize, Ordering};
#[cfg(target_os = "linux")]
use std::time::Instant;
#[cfg(target_os = "linux")]
use tokio::signal::unix::{SignalKind, signal};
#[cfg(target_os = "linux")]
use tokio::sync::{Mutex, mpsc, watch};
#[cfg(target_os = "linux")]
use tracing::{error, info, warn};
#[cfg(target_os = "linux")]
use tracing_subscriber::{EnvFilter, fmt};
/// FIPS outbound LAN gateway
#[cfg(target_os = "linux")]
#[derive(Parser, Debug)]
#[command(
name = "fips-gateway",
@@ -35,6 +47,13 @@ struct Args {
log_level: String,
}
#[cfg(not(target_os = "linux"))]
fn main() {
eprintln!("fips-gateway requires Linux (nftables unavailable on this platform)");
std::process::exit(1);
}
#[cfg(target_os = "linux")]
#[tokio::main(flavor = "current_thread")]
async fn main() {
let args = Args::parse();
src/bin/fips.rs
+22 -2
View File
@@ -73,11 +73,31 @@ async fn run_daemon(
}
};
// Initialize logging: RUST_LOG env var overrides config if set
// Initialize logging: RUST_LOG env var overrides config if set.
//
// The nostr-sdk relay pool emits the full JSON of every event it
// sends and receives at DEBUG level. At our DEBUG level that drowns
// out everything else, so suppress it unless the operator has
// explicitly asked for TRACE — at which point the raw frames come
// back.
let log_level = config.node.log_level();
let nostr_directive = if log_level == tracing::Level::TRACE {
"trace"
} else {
"info"
};
let default_directive = format!(
"{log_level},nostr_relay_pool={nostr_directive},nostr_sdk={nostr_directive},nostr={nostr_directive}"
);
let filter = EnvFilter::builder()
.with_default_directive(log_level.into())
.from_env_lossy();
.parse_lossy(default_directive);
let filter = match std::env::var("RUST_LOG") {
Ok(env) if !env.is_empty() => EnvFilter::builder()
.with_default_directive(log_level.into())
.parse_lossy(env),
_ => filter,
};
fmt().with_env_filter(filter).with_target(true).init();
src/config/mod.rs
+194 -6
View File
@@ -18,7 +18,7 @@
//! nsec: "nsec1..."
//! ```
#[cfg(feature = "gateway")]
#[cfg(target_os = "linux")]
mod gateway;
mod node;
mod peer;
@@ -30,12 +30,12 @@ use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use thiserror::Error;
#[cfg(feature = "gateway")]
#[cfg(target_os = "linux")]
pub use gateway::{ConntrackConfig, GatewayConfig, GatewayDnsConfig, PortForward, Proto};
pub use node::{
BloomConfig, BuffersConfig, CacheConfig, ControlConfig, DiscoveryConfig, LimitsConfig,
NodeConfig, RateLimitConfig, RekeyConfig, RetryConfig, SessionConfig, SessionMmpConfig,
TreeConfig,
NodeConfig, NostrDiscoveryConfig, NostrDiscoveryPolicy, RateLimitConfig, RekeyConfig,
RetryConfig, SessionConfig, SessionMmpConfig, TreeConfig,
};
pub use peer::{ConnectPolicy, PeerAddress, PeerConfig};
pub use transport::{
@@ -337,6 +337,9 @@ pub enum ConfigError {
#[error("identity error: {0}")]
Identity(#[from] IdentityError),
#[error("invalid configuration: {0}")]
Validation(String),
}
/// Identity configuration (`node.identity.*`).
@@ -378,7 +381,7 @@ pub struct Config {
pub peers: Vec<PeerConfig>,
/// Gateway configuration (`gateway`).
#[cfg(feature = "gateway")]
#[cfg(target_os = "linux")]
#[serde(default, skip_serializing_if = "Option::is_none")]
pub gateway: Option<GatewayConfig>,
}
@@ -500,7 +503,7 @@ impl Config {
self.peers = other.peers;
}
// Merge gateway section — higher-priority config replaces entirely
#[cfg(feature = "gateway")]
#[cfg(target_os = "linux")]
if other.gateway.is_some() {
self.gateway = other.gateway;
}
@@ -552,6 +555,69 @@ impl Config {
self.peers.iter().filter(|p| p.is_auto_connect())
}
/// Validate cross-field configuration invariants.
pub fn validate(&self) -> Result<(), ConfigError> {
let nostr = &self.node.discovery.nostr;
let any_transport_advertises_on_nostr = self
.transports
.udp
.iter()
.any(|(_, cfg)| cfg.advertise_on_nostr())
|| self
.transports
.tcp
.iter()
.any(|(_, cfg)| cfg.advertise_on_nostr())
|| self
.transports
.tor
.iter()
.any(|(_, cfg)| cfg.advertise_on_nostr());
if any_transport_advertises_on_nostr && !nostr.enabled {
return Err(ConfigError::Validation(
"at least one transport has `advertise_on_nostr = true`, but `node.discovery.nostr.enabled` is false".to_string(),
));
}
if self.peers.iter().any(|peer| peer.via_nostr) && !nostr.enabled {
return Err(ConfigError::Validation(
"at least one peer has `via_nostr = true`, but `node.discovery.nostr.enabled` is false".to_string(),
));
}
for (i, peer) in self.peers.iter().enumerate() {
if peer.addresses.is_empty() && !peer.via_nostr {
return Err(ConfigError::Validation(format!(
"peers[{i}] ({}): must specify at least one address, or set `via_nostr = true` to resolve endpoints from the Nostr advert",
peer.npub
)));
}
}
let has_nat_udp_advert = self
.transports
.udp
.iter()
.any(|(_, cfg)| cfg.advertise_on_nostr() && !cfg.is_public());
if nostr.enabled && has_nat_udp_advert {
if nostr.dm_relays.is_empty() {
return Err(ConfigError::Validation(
"NAT UDP advert publishing requires `node.discovery.nostr.dm_relays` to be non-empty".to_string(),
));
}
if nostr.stun_servers.is_empty() {
return Err(ConfigError::Validation(
"NAT UDP advert publishing requires `node.discovery.nostr.stun_servers` to be non-empty".to_string(),
));
}
}
Ok(())
}
/// Serialize this configuration to YAML.
pub fn to_yaml(&self) -> Result<String, serde_yaml::Error> {
serde_yaml::to_string(self)
@@ -1122,4 +1188,126 @@ peers:
assert_eq!(peer.addresses.len(), 2);
assert!(peer.is_auto_connect());
}
#[test]
fn test_parse_nostr_discovery_config() {
let yaml = r#"
node:
discovery:
nostr:
enabled: true
advertise: false
policy: configured_only
open_discovery_max_pending: 12
app: "fips.nat.test.v1"
signal_ttl_secs: 45
advert_relays:
- "wss://relay-a.example"
dm_relays:
- "wss://relay-b.example"
stun_servers:
- "stun:stun.example.org:3478"
peers:
- npub: "npub1peer"
via_nostr: true
addresses:
- transport: udp
addr: "nat"
"#;
let config: Config = serde_yaml::from_str(yaml).unwrap();
assert!(config.node.discovery.nostr.enabled);
assert!(!config.node.discovery.nostr.advertise);
assert_eq!(config.node.discovery.nostr.app, "fips.nat.test.v1");
assert_eq!(config.node.discovery.nostr.signal_ttl_secs, 45);
assert_eq!(
config.node.discovery.nostr.policy,
NostrDiscoveryPolicy::ConfiguredOnly
);
assert_eq!(config.node.discovery.nostr.open_discovery_max_pending, 12);
assert_eq!(
config.node.discovery.nostr.advert_relays,
vec!["wss://relay-a.example".to_string()]
);
assert_eq!(
config.node.discovery.nostr.dm_relays,
vec!["wss://relay-b.example".to_string()]
);
assert_eq!(
config.node.discovery.nostr.stun_servers,
vec!["stun:stun.example.org:3478".to_string()]
);
assert_eq!(
config.peers[0].addresses[0].addr, "nat",
"udp:nat address should parse without special-casing in YAML"
);
assert!(config.peers[0].via_nostr);
}
#[test]
fn test_validate_transport_advert_requires_nostr_enabled() {
let mut config = Config::default();
config.transports.udp = TransportInstances::Single(UdpConfig {
advertise_on_nostr: Some(true),
..Default::default()
});
config.node.discovery.nostr.enabled = false;
let err = config.validate().expect_err("validation should fail");
assert!(err.to_string().contains("advertise_on_nostr"));
}
#[test]
#[allow(clippy::field_reassign_with_default)]
fn test_validate_peer_via_nostr_requires_nostr_enabled() {
let mut config = Config::default();
config.peers = vec![PeerConfig {
npub: "npub1peer".to_string(),
via_nostr: true,
..Default::default()
}];
config.node.discovery.nostr.enabled = false;
let err = config.validate().expect_err("validation should fail");
assert!(err.to_string().contains("via_nostr"));
}
#[test]
#[allow(clippy::field_reassign_with_default)]
fn test_validate_peer_addresses_required_unless_via_nostr() {
// Empty addresses + via_nostr=false → error.
let mut config = Config::default();
config.peers = vec![PeerConfig {
npub: "npub1peer".to_string(),
..Default::default()
}];
let err = config.validate().expect_err("validation should fail");
assert!(err.to_string().contains("at least one address"));
// Empty addresses + via_nostr=true + nostr.enabled=true → ok.
config.peers[0].via_nostr = true;
config.node.discovery.nostr.enabled = true;
config
.validate()
.expect("via_nostr should allow empty addresses");
}
#[test]
fn test_validate_nat_udp_advert_requires_relays_and_stun() {
let mut config = Config::default();
config.node.discovery.nostr.enabled = true;
config.node.discovery.nostr.dm_relays.clear();
config.transports.udp = TransportInstances::Single(UdpConfig {
advertise_on_nostr: Some(true),
public: Some(false),
..Default::default()
});
let err = config.validate().expect_err("validation should fail");
assert!(err.to_string().contains("dm_relays"));
config.node.discovery.nostr.dm_relays = vec!["wss://relay.example".to_string()];
config.node.discovery.nostr.stun_servers.clear();
let err = config.validate().expect_err("validation should fail");
assert!(err.to_string().contains("stun_servers"));
}
}
src/config/node.rs
+228 -27
View File
@@ -192,14 +192,20 @@ pub struct DiscoveryConfig {
/// Hop limit for LookupRequest flood (`node.discovery.ttl`).
#[serde(default = "DiscoveryConfig::default_ttl")]
pub ttl: u8,
/// Lookup completion timeout in seconds (`node.discovery.timeout_secs`).
#[serde(default = "DiscoveryConfig::default_timeout_secs")]
pub timeout_secs: u64,
/// Per-attempt timeouts in seconds (`node.discovery.attempt_timeouts_secs`).
/// Each entry is the time to wait for a response before sending the next
/// LookupRequest (with a fresh request_id). Sequence length determines the
/// total number of attempts before declaring the destination unreachable.
/// Default `[1, 2, 4, 8]` gives 4 attempts and a 15s total budget.
#[serde(default = "DiscoveryConfig::default_attempt_timeouts_secs")]
pub attempt_timeouts_secs: Vec<u64>,
/// Dedup cache expiry in seconds (`node.discovery.recent_expiry_secs`).
#[serde(default = "DiscoveryConfig::default_recent_expiry_secs")]
pub recent_expiry_secs: u64,
/// Base backoff after first lookup failure in seconds (`node.discovery.backoff_base_secs`).
/// Doubles per consecutive failure up to `backoff_max_secs`.
/// Base backoff after lookup failure in seconds (`node.discovery.backoff_base_secs`).
/// Doubles per consecutive failure up to `backoff_max_secs`. Defaults to 0
/// (no post-failure suppression); the per-attempt sequence in
/// `attempt_timeouts_secs` provides the only retry pacing.
#[serde(default = "DiscoveryConfig::default_backoff_base_secs")]
pub backoff_base_secs: u64,
/// Maximum backoff cap in seconds (`node.discovery.backoff_max_secs`).
@@ -210,28 +216,21 @@ pub struct DiscoveryConfig {
/// Defense-in-depth against misbehaving nodes.
#[serde(default = "DiscoveryConfig::default_forward_min_interval_secs")]
pub forward_min_interval_secs: u64,
/// Retry interval within the timeout window in seconds
/// (`node.discovery.retry_interval_secs`).
/// After this interval without a response, resend the lookup.
#[serde(default = "DiscoveryConfig::default_retry_interval_secs")]
pub retry_interval_secs: u64,
/// Maximum attempts per lookup (`node.discovery.max_attempts`).
/// 1 = no retry, 2 = one retry, etc.
#[serde(default = "DiscoveryConfig::default_max_attempts")]
pub max_attempts: u8,
/// Nostr-mediated overlay endpoint discovery.
#[serde(default = "DiscoveryConfig::default_nostr")]
pub nostr: NostrDiscoveryConfig,
}
impl Default for DiscoveryConfig {
fn default() -> Self {
Self {
ttl: 64,
timeout_secs: 10,
attempt_timeouts_secs: vec![1, 2, 4, 8],
recent_expiry_secs: 10,
backoff_base_secs: 30,
backoff_max_secs: 300,
backoff_base_secs: 0,
backoff_max_secs: 0,
forward_min_interval_secs: 2,
retry_interval_secs: 5,
max_attempts: 2,
nostr: NostrDiscoveryConfig::default(),
}
}
}
@@ -240,26 +239,228 @@ impl DiscoveryConfig {
fn default_ttl() -> u8 {
64
}
fn default_timeout_secs() -> u64 {
10
fn default_attempt_timeouts_secs() -> Vec<u64> {
vec![1, 2, 4, 8]
}
fn default_recent_expiry_secs() -> u64 {
10
}
fn default_backoff_base_secs() -> u64 {
30
0
}
fn default_backoff_max_secs() -> u64 {
300
0
}
fn default_forward_min_interval_secs() -> u64 {
2
}
fn default_retry_interval_secs() -> u64 {
5
fn default_nostr() -> NostrDiscoveryConfig {
NostrDiscoveryConfig::default()
}
fn default_max_attempts() -> u8 {
2
}
/// Nostr advert discovery policy.
///
/// Controls how overlay endpoint adverts are consumed:
/// - `disabled`: ignore advert-derived endpoints for all peers
/// - `configured_only`: allow advert fallback only for configured peers with
/// `peers[].via_nostr = true`
/// - `open`: also consider adverts for non-configured peers
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NostrDiscoveryPolicy {
Disabled,
#[default]
ConfiguredOnly,
Open,
}
/// Nostr-mediated overlay endpoint discovery (`node.discovery.nostr.*`).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NostrDiscoveryConfig {
/// Enable Nostr-signaled traversal bootstrap.
#[serde(default)]
pub enabled: bool,
/// Publish service advertisements so remote peers can bootstrap inbound.
#[serde(default = "NostrDiscoveryConfig::default_advertise")]
pub advertise: bool,
/// Relay URLs used for service advertisements.
#[serde(default = "NostrDiscoveryConfig::default_advert_relays")]
pub advert_relays: Vec<String>,
/// Relay URLs used for encrypted signaling events.
#[serde(default = "NostrDiscoveryConfig::default_dm_relays")]
pub dm_relays: Vec<String>,
/// STUN servers used for local reflexive address discovery.
/// Outbound observation uses only this local list; peer-advertised STUN
/// values are informational and are not treated as egress targets.
#[serde(default = "NostrDiscoveryConfig::default_stun_servers")]
pub stun_servers: Vec<String>,
/// Whether to advertise local (RFC 1918 / ULA) interface addresses as
/// host candidates in the traversal offer.
///
/// Off by default: in most deployments the relevant peers are not on the
/// same broadcast domain, and sharing private host candidates causes
/// misleading punch successes when an asymmetric L3 path (corporate VPN,
/// Tailscale subnet route, overlapping address space, etc.) makes a
/// peer's private IP one-way reachable from this node. Enable only when
/// peers are on the same physical LAN and same-LAN punching is wanted.
#[serde(default)]
pub share_local_candidates: bool,
/// Traversal application namespace and advert identifier suffix.
#[serde(default = "NostrDiscoveryConfig::default_app")]
pub app: String,
/// Signaling TTL in seconds.
#[serde(default = "NostrDiscoveryConfig::default_signal_ttl_secs")]
pub signal_ttl_secs: u64,
/// Policy for advert-derived endpoint discovery.
#[serde(default)]
pub policy: NostrDiscoveryPolicy,
/// Max number of open-discovery peers queued for outbound retry/connection
/// at once. Prevents unbounded queue growth from ambient advert traffic.
#[serde(default = "NostrDiscoveryConfig::default_open_discovery_max_pending")]
pub open_discovery_max_pending: usize,
/// Max concurrent inbound traversal offers processed at once.
/// Acts as a rate limit against offer spam from relays.
#[serde(default = "NostrDiscoveryConfig::default_max_concurrent_incoming_offers")]
pub max_concurrent_incoming_offers: usize,
/// Max cached overlay adverts retained from relay traffic.
/// Bounds memory under ambient advert volume.
#[serde(default = "NostrDiscoveryConfig::default_advert_cache_max_entries")]
pub advert_cache_max_entries: usize,
/// Max seen-session IDs retained for replay detection.
/// Oldest entries are evicted when the cap is exceeded.
#[serde(default = "NostrDiscoveryConfig::default_seen_sessions_max_entries")]
pub seen_sessions_max_entries: usize,
/// Overall punch attempt timeout in seconds.
#[serde(default = "NostrDiscoveryConfig::default_attempt_timeout_secs")]
pub attempt_timeout_secs: u64,
/// Replay tracking retention window in seconds.
#[serde(default = "NostrDiscoveryConfig::default_replay_window_secs")]
pub replay_window_secs: u64,
/// Delay before punch traffic starts.
#[serde(default = "NostrDiscoveryConfig::default_punch_start_delay_ms")]
pub punch_start_delay_ms: u64,
/// Interval between punch packets.
#[serde(default = "NostrDiscoveryConfig::default_punch_interval_ms")]
pub punch_interval_ms: u64,
/// How long to keep punching before failure.
#[serde(default = "NostrDiscoveryConfig::default_punch_duration_ms")]
pub punch_duration_ms: u64,
/// Advert TTL in seconds.
#[serde(default = "NostrDiscoveryConfig::default_advert_ttl_secs")]
pub advert_ttl_secs: u64,
/// How often adverts are refreshed in seconds.
#[serde(default = "NostrDiscoveryConfig::default_advert_refresh_secs")]
pub advert_refresh_secs: u64,
}
impl Default for NostrDiscoveryConfig {
fn default() -> Self {
Self {
enabled: false,
advertise: Self::default_advertise(),
advert_relays: Self::default_advert_relays(),
dm_relays: Self::default_dm_relays(),
stun_servers: Self::default_stun_servers(),
share_local_candidates: false,
app: Self::default_app(),
signal_ttl_secs: Self::default_signal_ttl_secs(),
policy: NostrDiscoveryPolicy::default(),
open_discovery_max_pending: Self::default_open_discovery_max_pending(),
max_concurrent_incoming_offers: Self::default_max_concurrent_incoming_offers(),
advert_cache_max_entries: Self::default_advert_cache_max_entries(),
seen_sessions_max_entries: Self::default_seen_sessions_max_entries(),
attempt_timeout_secs: Self::default_attempt_timeout_secs(),
replay_window_secs: Self::default_replay_window_secs(),
punch_start_delay_ms: Self::default_punch_start_delay_ms(),
punch_interval_ms: Self::default_punch_interval_ms(),
punch_duration_ms: Self::default_punch_duration_ms(),
advert_ttl_secs: Self::default_advert_ttl_secs(),
advert_refresh_secs: Self::default_advert_refresh_secs(),
}
}
}
impl NostrDiscoveryConfig {
fn default_advertise() -> bool {
true
}
fn default_advert_relays() -> Vec<String> {
vec![
"wss://relay.damus.io".to_string(),
"wss://nos.lol".to_string(),
"wss://offchain.pub".to_string(),
]
}
fn default_dm_relays() -> Vec<String> {
vec![
"wss://relay.damus.io".to_string(),
"wss://nos.lol".to_string(),
"wss://offchain.pub".to_string(),
]
}
fn default_stun_servers() -> Vec<String> {
vec![
"stun:stun.l.google.com:19302".to_string(),
"stun:stun.cloudflare.com:3478".to_string(),
"stun:global.stun.twilio.com:3478".to_string(),
]
}
fn default_app() -> String {
"fips-overlay-v1".to_string()
}
fn default_signal_ttl_secs() -> u64 {
120
}
fn default_open_discovery_max_pending() -> usize {
64
}
fn default_max_concurrent_incoming_offers() -> usize {
16
}
fn default_advert_cache_max_entries() -> usize {
2048
}
fn default_seen_sessions_max_entries() -> usize {
2048
}
fn default_attempt_timeout_secs() -> u64 {
10
}
fn default_replay_window_secs() -> u64 {
300
}
fn default_punch_start_delay_ms() -> u64 {
2_000
}
fn default_punch_interval_ms() -> u64 {
200
}
fn default_punch_duration_ms() -> u64 {
10_000
}
fn default_advert_ttl_secs() -> u64 {
3_600
}
fn default_advert_refresh_secs() -> u64 {
1_800
}
}
src/config/peer.rs
+14 -1
View File
@@ -94,7 +94,11 @@ pub struct PeerConfig {
pub alias: Option<String>,
/// Transport addresses for reaching this peer.
/// At least one address is required.
///
/// At least one address is required unless `via_nostr` is `true`,
/// in which case the address list may be empty and endpoints are
/// resolved from the peer's Nostr advert at dial time.
#[serde(default)]
pub addresses: Vec<PeerAddress>,
/// Connection policy for this peer.
@@ -106,6 +110,13 @@ pub struct PeerConfig {
/// backoff after MMP removes this peer due to liveness timeout.
#[serde(default = "default_auto_reconnect")]
pub auto_reconnect: bool,
/// Whether to append Nostr-advertised endpoints when dialing this peer.
///
/// Static addresses are still attempted first; advert-derived endpoints are
/// appended as fallback candidates.
#[serde(default)]
pub via_nostr: bool,
}
impl Default for PeerConfig {
@@ -116,6 +127,7 @@ impl Default for PeerConfig {
addresses: Vec::new(),
connect_policy: ConnectPolicy::default(),
auto_reconnect: default_auto_reconnect(),
via_nostr: false,
}
}
}
@@ -133,6 +145,7 @@ impl PeerConfig {
addresses: vec![PeerAddress::new(transport, addr)],
connect_policy: ConnectPolicy::default(),
auto_reconnect: default_auto_reconnect(),
via_nostr: false,
}
}
src/config/transport.rs
+43
View File
@@ -38,6 +38,19 @@ pub struct UdpConfig {
/// UDP send buffer size in bytes (`send_buf_size`). Defaults to 2 MB.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub send_buf_size: Option<usize>,
/// Whether this transport should be advertised on Nostr overlay discovery.
/// Default: false.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub advertise_on_nostr: Option<bool>,
/// Whether UDP should be advertised as directly reachable (`host:port`) on
/// Nostr. When false and advertised, UDP is emitted as `addr: "nat"` to
/// trigger rendezvous traversal.
///
/// Default: false.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub public: Option<bool>,
}
impl UdpConfig {
@@ -60,6 +73,16 @@ impl UdpConfig {
pub fn send_buf_size(&self) -> usize {
self.send_buf_size.unwrap_or(DEFAULT_UDP_SEND_BUF)
}
/// Whether this UDP transport should be advertised on Nostr discovery.
pub fn advertise_on_nostr(&self) -> bool {
self.advertise_on_nostr.unwrap_or(false)
}
/// Whether this UDP transport should be advertised as directly reachable.
pub fn is_public(&self) -> bool {
self.public.unwrap_or(false)
}
}
/// Transport instances - either a single config or named instances.
@@ -293,6 +316,11 @@ pub struct TcpConfig {
/// Maximum simultaneous inbound connections. Defaults to 256.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_inbound_connections: Option<usize>,
/// Whether this transport should be advertised on Nostr overlay discovery.
/// Default: false.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub advertise_on_nostr: Option<bool>,
}
impl TcpConfig {
@@ -332,6 +360,11 @@ impl TcpConfig {
self.max_inbound_connections
.unwrap_or(DEFAULT_TCP_MAX_INBOUND)
}
/// Whether this TCP transport should be advertised on Nostr discovery.
pub fn advertise_on_nostr(&self) -> bool {
self.advertise_on_nostr.unwrap_or(false)
}
}
// ============================================================================
@@ -420,6 +453,11 @@ pub struct TorConfig {
/// in torrc; fips reads the .onion hostname from a file.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub directory_service: Option<DirectoryServiceConfig>,
/// Whether this transport should be advertised on Nostr overlay discovery.
/// Default: false.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub advertise_on_nostr: Option<bool>,
}
/// Directory-mode onion service configuration.
@@ -507,6 +545,11 @@ impl TorConfig {
self.max_inbound_connections
.unwrap_or(DEFAULT_TOR_MAX_INBOUND)
}
/// Whether this Tor transport should be advertised on Nostr discovery.
pub fn advertise_on_nostr(&self) -> bool {
self.advertise_on_nostr.unwrap_or(false)
}
}
// ============================================================================
src/discovery.rs
+80
View File
@@ -0,0 +1,80 @@
//! Bootstrap handoff types.
//!
//! These types model the boundary between an external rendezvous/bootstrap
//! runtime and the core FIPS transport/handshake stack. The rendezvous side
//! owns Nostr/STUN/UDP hole punching; once a direct UDP path is established,
//! it hands the live socket and selected remote endpoint to FIPS so the
//! existing Noise/FMP transport path can take over.
#[cfg(feature = "nostr-discovery")]
pub mod nostr;
use crate::config::UdpConfig;
use crate::{NodeAddr, TransportId};
use std::net::{SocketAddr, UdpSocket};
/// Result of handing an established traversal session into FIPS.
#[derive(Debug, Clone)]
pub struct BootstrapHandoffResult {
/// Newly allocated transport ID used for the adopted UDP socket.
pub transport_id: TransportId,
/// Local socket address now owned by the FIPS UDP transport.
pub local_addr: SocketAddr,
/// Confirmed remote UDP endpoint selected by traversal.
pub remote_addr: SocketAddr,
/// Peer node address derived from the supplied peer identity.
pub peer_node_addr: NodeAddr,
/// Nostr session identifier used by the bootstrap runtime.
pub session_id: String,
}
/// Established UDP traversal ready to be handed into FIPS.
///
/// The socket must already be bound and must be the same socket used for the
/// traversal runtime's STUN and punch traffic so the NAT mapping is preserved.
#[derive(Debug)]
pub struct EstablishedTraversal {
/// Rendezvous session identifier for logging/correlation.
pub session_id: String,
/// Remote peer identity in `npub` form.
pub peer_npub: String,
/// The selected remote UDP endpoint to use for the FIPS handshake.
pub remote_addr: SocketAddr,
/// The live UDP socket carrying the established mapping.
pub socket: UdpSocket,
/// Optional name for the adopted UDP transport.
pub transport_name: Option<String>,
/// Optional UDP transport tuning overrides.
pub transport_config: Option<UdpConfig>,
}
impl EstablishedTraversal {
/// Construct an established traversal handoff.
pub fn new(
session_id: impl Into<String>,
peer_npub: impl Into<String>,
remote_addr: SocketAddr,
socket: UdpSocket,
) -> Self {
Self {
session_id: session_id.into(),
peer_npub: peer_npub.into(),
remote_addr,
socket,
transport_name: None,
transport_config: None,
}
}
/// Attach an explicit transport name to the adopted UDP transport.
pub fn with_transport_name(mut self, name: impl Into<String>) -> Self {
self.transport_name = Some(name.into());
self
}
/// Override UDP transport tuning for the adopted socket.
pub fn with_transport_config(mut self, config: UdpConfig) -> Self {
self.transport_config = Some(config);
self
}
}
src/discovery/nostr/mod.rs
+18
View File
@@ -0,0 +1,18 @@
#![cfg(feature = "nostr-discovery")]
mod runtime;
mod signal;
mod stun;
mod traversal;
mod types;
#[cfg(test)]
mod tests;
pub use runtime::NostrDiscovery;
pub use types::{
ADVERT_IDENTIFIER, ADVERT_KIND, ADVERT_VERSION, BootstrapError, BootstrapEvent,
CachedOverlayAdvert, OverlayAdvert, OverlayEndpointAdvert, OverlayTransportKind,
PROTOCOL_VERSION, PUNCH_ACK_MAGIC, PUNCH_MAGIC, PunchHint, PunchPacket, PunchPacketKind,
SIGNAL_KIND, TraversalAddress, TraversalAnswer, TraversalOffer,
};
src/discovery/nostr/runtime.rs
+1096
View File
File diff suppressed because it is too large Load Diff
src/discovery/nostr/signal.rs
+193
View File
@@ -0,0 +1,193 @@
use nostr::EventId;
use nostr::nips::{nip44, nip59};
use nostr::prelude::{
Event, EventBuilder, JsonUtil, Kind, NostrSigner, PublicKey, Tag, Timestamp, UnsignedEvent,
};
use super::types::{BootstrapError, PunchHint, SIGNAL_KIND, TraversalAnswer, TraversalOffer};
pub(super) struct SignalEnvelope<T> {
pub(super) payload: T,
pub(super) event_id: EventId,
pub(super) sender_npub: String,
}
pub(super) struct UnwrappedSignal {
pub(super) sender: PublicKey,
pub(super) rumor: UnsignedEvent,
}
pub(super) async fn build_signal_event(
signer: &nostr::Keys,
receiver: PublicKey,
rumor: UnsignedEvent,
expiration: Timestamp,
) -> Result<Event, BootstrapError> {
let seal = nip59::make_seal(signer, &receiver, rumor)
.await
.map_err(|e| BootstrapError::Nostr(e.to_string()))?
.sign(signer)
.await
.map_err(|e| BootstrapError::Nostr(e.to_string()))?;
let ephemeral = nostr::Keys::generate();
let content = nip44::encrypt(
ephemeral.secret_key(),
&receiver,
seal.as_json(),
nip44::Version::default(),
)
.map_err(|e| BootstrapError::Nostr(e.to_string()))?;
EventBuilder::new(Kind::Custom(SIGNAL_KIND), content)
.tags([Tag::public_key(receiver), Tag::expiration(expiration)])
.sign_with_keys(&ephemeral)
.map_err(|e| BootstrapError::Nostr(e.to_string()))
}
pub(super) async fn unwrap_signal_event(
signer: &nostr::Keys,
event: &Event,
) -> Result<UnwrappedSignal, BootstrapError> {
if event.kind != Kind::Custom(SIGNAL_KIND) {
return Err(BootstrapError::Protocol(
"not a traversal signal".to_string(),
));
}
let seal_json = signer
.nip44_decrypt(&event.pubkey, &event.content)
.await
.map_err(|e| BootstrapError::Nostr(e.to_string()))?;
let seal =
Event::from_json(seal_json).map_err(|e| BootstrapError::EventParse(e.to_string()))?;
seal.verify()
.map_err(|e| BootstrapError::Nostr(e.to_string()))?;
let rumor_json = signer
.nip44_decrypt(&seal.pubkey, &seal.content)
.await
.map_err(|e| BootstrapError::Nostr(e.to_string()))?;
let rumor = UnsignedEvent::from_json(rumor_json)
.map_err(|e| BootstrapError::EventParse(e.to_string()))?;
Ok(UnwrappedSignal {
sender: seal.pubkey,
rumor,
})
}
pub(super) fn validate_offer_freshness(
offer: &TraversalOffer,
now: u64,
signal_ttl_ms: u64,
actual_sender_npub: &str,
local_npub: &str,
) -> Result<(), BootstrapError> {
if offer.message_type != "offer" {
return Err(BootstrapError::Protocol("invalid-offer".to_string()));
}
if offer.expires_at <= now || now.saturating_sub(offer.issued_at) > signal_ttl_ms {
return Err(BootstrapError::Protocol("expired-offer".to_string()));
}
if offer.sender_npub != actual_sender_npub || offer.recipient_npub != local_npub {
return Err(BootstrapError::Protocol("identity-mismatch".to_string()));
}
Ok(())
}
#[allow(clippy::too_many_arguments)]
pub(super) fn create_traversal_offer(
session_id: String,
issued_at: u64,
ttl_ms: u64,
nonce: String,
sender_npub: String,
recipient_npub: String,
reflexive_address: Option<super::TraversalAddress>,
local_addresses: Vec<super::TraversalAddress>,
stun_server: Option<String>,
) -> TraversalOffer {
TraversalOffer {
message_type: "offer".to_string(),
session_id,
issued_at,
expires_at: issued_at + ttl_ms,
nonce,
sender_npub,
recipient_npub,
reflexive_address,
local_addresses,
stun_server,
}
}
#[allow(clippy::too_many_arguments)]
pub(super) fn create_traversal_answer(
session_id: String,
issued_at: u64,
ttl_ms: u64,
nonce: String,
sender_npub: String,
recipient_npub: String,
in_reply_to: String,
accepted: bool,
reflexive_address: Option<super::TraversalAddress>,
local_addresses: Vec<super::TraversalAddress>,
stun_server: Option<String>,
punch: Option<PunchHint>,
reason: Option<String>,
) -> TraversalAnswer {
TraversalAnswer {
message_type: "answer".to_string(),
session_id,
issued_at,
expires_at: issued_at + ttl_ms,
nonce,
sender_npub,
recipient_npub,
in_reply_to,
accepted,
reflexive_address,
local_addresses,
stun_server,
punch,
reason,
}
}
pub(super) fn validate_traversal_answer_for_offer(
offer: &TraversalOffer,
answer: &TraversalAnswer,
now: u64,
signal_ttl_ms: u64,
actual_sender_npub: &str,
local_npub: &str,
) -> Result<(), BootstrapError> {
if answer.message_type != "answer" {
return Err(BootstrapError::Protocol("invalid-answer".to_string()));
}
if offer.expires_at <= now
|| answer.expires_at <= now
|| now.saturating_sub(answer.issued_at) > signal_ttl_ms
{
return Err(BootstrapError::Protocol("expired-answer".to_string()));
}
if offer.session_id != answer.session_id || answer.in_reply_to != offer.nonce {
return Err(BootstrapError::Protocol("session-mismatch".to_string()));
}
if offer.sender_npub != local_npub
|| offer.recipient_npub != actual_sender_npub
|| answer.sender_npub != actual_sender_npub
|| answer.recipient_npub != local_npub
{
return Err(BootstrapError::Protocol("identity-mismatch".to_string()));
}
if answer.accepted && answer.reflexive_address.is_none() && answer.local_addresses.is_empty() {
return Err(BootstrapError::Protocol("missing-addresses".to_string()));
}
if !answer.accepted && answer.reason.as_deref().unwrap_or_default().is_empty() {
return Err(BootstrapError::Protocol(
"missing-rejection-reason".to_string(),
));
}
Ok(())
}
src/discovery/nostr/stun.rs
+391
View File
@@ -0,0 +1,391 @@
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::time::Duration;
use tokio::net::{UdpSocket, lookup_host};
use tracing::debug;
use super::types::{BootstrapError, TraversalAddress};
// Current STUN parsing is intentionally minimal and only supports
// MAPPED-ADDRESS / XOR-MAPPED-ADDRESS for IPv4 and IPv6.
// Local interface discovery remains best-effort and may still be incomplete
// on dual-stack, NAT64, or heavily firewalled hosts.
pub(super) async fn observe_traversal_addresses(
socket: &std::net::UdpSocket,
stun_servers: &[String],
share_local_candidates: bool,
) -> Result<
(
Option<TraversalAddress>,
Vec<TraversalAddress>,
Option<String>,
),
BootstrapError,
> {
let local_port = socket.local_addr()?.port();
let local_addresses = if share_local_candidates {
local_addresses_from_port(local_port)
.into_iter()
.map(|ip| TraversalAddress {
protocol: "udp".to_string(),
ip,
port: local_port,
})
.collect::<Vec<_>>()
} else {
Vec::new()
};
let mut last_error = None;
for stun_server in stun_servers {
match perform_stun(socket, stun_server).await {
Ok(mapped) => {
debug!(
stun_server = %stun_server,
reflexive = ?mapped,
"STUN observation succeeded"
);
return Ok((
mapped.map(|addr| TraversalAddress {
protocol: "udp".to_string(),
ip: addr.ip().to_string(),
port: addr.port(),
}),
local_addresses.clone(),
Some(stun_server.clone()),
));
}
Err(err) => last_error = Some(err),
}
}
if let Some(err) = last_error {
debug!(error = %err, "stun observation failed, falling back to LAN-only addresses");
}
Ok((None, local_addresses, None))
}
async fn perform_stun(
socket: &std::net::UdpSocket,
stun_server: &str,
) -> Result<Option<SocketAddr>, BootstrapError> {
let endpoint = parse_stun_url(stun_server)?;
let txn_id = random_txn_id();
let request = create_stun_binding_request(txn_id);
let addr = resolve_udp_target(&endpoint.host, endpoint.port)
.await?
.ok_or_else(|| BootstrapError::Stun(format!("no address for {}", stun_server)))?;
let udp = UdpSocket::from_std(socket.try_clone()?)?;
udp.send_to(&request, addr).await?;
let mut buf = [0u8; 2048];
let deadline = tokio::time::Instant::now() + Duration::from_secs(2);
loop {
let result = tokio::time::timeout_at(deadline, udp.recv_from(&mut buf)).await;
let Ok(Ok((len, _remote))) = result else {
break;
};
if let Some(mapped) = parse_stun_binding_success(&buf[..len], &txn_id) {
return Ok(Some(mapped));
}
}
Err(BootstrapError::Stun(format!(
"timed out waiting for {}",
stun_server
)))
}
pub(super) fn parse_stun_url(input: &str) -> Result<StunEndpoint, BootstrapError> {
let raw = input.strip_prefix("stun:").unwrap_or(input);
let Some((host, port)) = raw.rsplit_once(':') else {
return Err(BootstrapError::Stun(format!("invalid STUN URL: {}", input)));
};
let port = port
.parse::<u16>()
.map_err(|_| BootstrapError::Stun(format!("invalid STUN URL: {}", input)))?;
if host.is_empty() {
return Err(BootstrapError::Stun(format!("invalid STUN URL: {}", input)));
}
Ok(StunEndpoint {
host: host.to_string(),
port,
})
}
pub(super) struct StunEndpoint {
pub(super) host: String,
pub(super) port: u16,
}
fn create_stun_binding_request(txn_id: [u8; 12]) -> [u8; 20] {
const STUN_BINDING_REQUEST: u16 = 0x0001;
const STUN_MAGIC_COOKIE: u32 = 0x2112_a442;
let mut packet = [0u8; 20];
packet[..2].copy_from_slice(&STUN_BINDING_REQUEST.to_be_bytes());
packet[2..4].copy_from_slice(&0u16.to_be_bytes());
packet[4..8].copy_from_slice(&STUN_MAGIC_COOKIE.to_be_bytes());
packet[8..20].copy_from_slice(&txn_id);
packet
}
pub(super) fn parse_stun_binding_success(packet: &[u8], txn_id: &[u8; 12]) -> Option<SocketAddr> {
const STUN_BINDING_SUCCESS: u16 = 0x0101;
const STUN_MAGIC_COOKIE: u32 = 0x2112_a442;
const STUN_ATTR_MAPPED_ADDRESS: u16 = 0x0001;
const STUN_ATTR_XOR_MAPPED_ADDRESS: u16 = 0x0020;
if packet.len() < 20 {
return None;
}
if u16::from_be_bytes(packet[..2].try_into().ok()?) != STUN_BINDING_SUCCESS {
return None;
}
if u32::from_be_bytes(packet[4..8].try_into().ok()?) != STUN_MAGIC_COOKIE {
return None;
}
if &packet[8..20] != txn_id {
return None;
}
let message_length = u16::from_be_bytes(packet[2..4].try_into().ok()?) as usize;
let mut offset = 20usize;
let max_offset = packet.len().min(20 + message_length);
while offset + 4 <= max_offset {
let attr_type = u16::from_be_bytes(packet[offset..offset + 2].try_into().ok()?);
let attr_len = u16::from_be_bytes(packet[offset + 2..offset + 4].try_into().ok()?) as usize;
let value_start = offset + 4;
let value_end = value_start + attr_len;
if value_end > packet.len() {
break;
}
let value = &packet[value_start..value_end];
let parsed = match attr_type {
STUN_ATTR_XOR_MAPPED_ADDRESS => parse_xor_mapped_address(value, txn_id),
STUN_ATTR_MAPPED_ADDRESS => parse_mapped_address(value),
_ => None,
};
if parsed.is_some() {
return parsed;
}
offset = value_end + ((4 - (attr_len % 4)) % 4);
}
None
}
fn parse_mapped_address(value: &[u8]) -> Option<SocketAddr> {
match value.get(1).copied()? {
0x01 if value.len() >= 8 => Some(SocketAddr::new(
IpAddr::V4(Ipv4Addr::new(value[4], value[5], value[6], value[7])),
u16::from_be_bytes([value[2], value[3]]),
)),
0x02 if value.len() >= 20 => {
let ip = Ipv6Addr::from(<[u8; 16]>::try_from(&value[4..20]).ok()?);
Some(SocketAddr::new(
IpAddr::V6(ip),
u16::from_be_bytes([value[2], value[3]]),
))
}
_ => None,
}
}
fn parse_xor_mapped_address(value: &[u8], txn_id: &[u8; 12]) -> Option<SocketAddr> {
const STUN_MAGIC_COOKIE: u32 = 0x2112_a442;
let xored_port = u16::from_be_bytes([value.get(2).copied()?, value.get(3).copied()?])
^ ((STUN_MAGIC_COOKIE >> 16) as u16);
let cookie = STUN_MAGIC_COOKIE.to_be_bytes();
match value.get(1).copied()? {
0x01 if value.len() >= 8 => {
let ip = Ipv4Addr::new(
value[4] ^ cookie[0],
value[5] ^ cookie[1],
value[6] ^ cookie[2],
value[7] ^ cookie[3],
);
Some(SocketAddr::new(IpAddr::V4(ip), xored_port))
}
0x02 if value.len() >= 20 => {
let mut ip = [0u8; 16];
for (index, byte) in ip.iter_mut().enumerate() {
let mask = if index < 4 {
cookie[index]
} else {
txn_id[index - 4]
};
*byte = value[4 + index] ^ mask;
}
Some(SocketAddr::new(IpAddr::V6(Ipv6Addr::from(ip)), xored_port))
}
_ => None,
}
}
async fn resolve_udp_target(host: &str, port: u16) -> Result<Option<SocketAddr>, BootstrapError> {
let normalized_host = host
.strip_prefix('[')
.and_then(|trimmed| trimmed.strip_suffix(']'))
.unwrap_or(host);
if let Ok(ip) = normalized_host.parse::<IpAddr>() {
return Ok(Some(SocketAddr::new(ip, port)));
}
let mut results = lookup_host((normalized_host, port)).await?;
Ok(results.next())
}
fn local_addresses_from_port(port: u16) -> Vec<String> {
let mut addresses = Vec::new();
push_private_interface_ips(&mut addresses);
push_local_probe(&mut addresses, "0.0.0.0:0", "8.8.8.8:80");
push_local_probe(&mut addresses, "[::]:0", "[2001:4860:4860::8888]:80");
push_bound_addr(&mut addresses, ("0.0.0.0", port));
push_bound_addr(&mut addresses, ("::", port));
addresses
}
fn push_private_interface_ips(addresses: &mut Vec<String>) {
for ip in private_interface_ips() {
push_ip(addresses, ip);
}
}
#[cfg(unix)]
fn private_interface_ips() -> Vec<IpAddr> {
let mut output = Vec::new();
let mut ifaddrs: *mut libc::ifaddrs = std::ptr::null_mut();
// SAFETY: `getifaddrs` initializes `ifaddrs` on success, and the linked
// list is valid until `freeifaddrs` is called.
let rc = unsafe { libc::getifaddrs(&mut ifaddrs) };
if rc != 0 || ifaddrs.is_null() {
return output;
}
let mut cursor = ifaddrs;
while !cursor.is_null() {
// SAFETY: `cursor` points at a valid node from the `getifaddrs` list.
let entry = unsafe { &*cursor };
let flags = entry.ifa_flags as i32;
let is_up = (flags & libc::IFF_UP) != 0;
let is_loopback = (flags & libc::IFF_LOOPBACK) != 0;
if is_up && !is_loopback && !entry.ifa_addr.is_null() {
// SAFETY: `ifa_addr` is non-null and its concrete type matches
// `sa_family` for this entry.
let maybe_ip = unsafe {
match (*entry.ifa_addr).sa_family as i32 {
libc::AF_INET => {
let sockaddr = &*(entry.ifa_addr as *const libc::sockaddr_in);
Some(IpAddr::V4(Ipv4Addr::from(
sockaddr.sin_addr.s_addr.to_ne_bytes(),
)))
}
libc::AF_INET6 => {
let sockaddr = &*(entry.ifa_addr as *const libc::sockaddr_in6);
Some(IpAddr::V6(Ipv6Addr::from(sockaddr.sin6_addr.s6_addr)))
}
_ => None,
}
};
if let Some(ip) = maybe_ip
&& is_private_overlay_candidate_ip(ip)
{
output.push(ip);
}
}
cursor = entry.ifa_next;
}
// SAFETY: `ifaddrs` came from `getifaddrs` and has not yet been freed.
unsafe { libc::freeifaddrs(ifaddrs) };
output
}
#[cfg(not(unix))]
fn private_interface_ips() -> Vec<IpAddr> {
Vec::new()
}
fn is_private_overlay_candidate_ip(ip: IpAddr) -> bool {
match ip {
IpAddr::V4(v4) => v4.is_private(),
IpAddr::V6(v6) => v6.is_unique_local(),
}
}
fn push_local_probe(addresses: &mut Vec<String>, bind_addr: &str, connect_addr: &str) {
if let Ok(socket) = std::net::UdpSocket::bind(bind_addr)
&& socket.connect(connect_addr).is_ok()
&& let Ok(local_addr) = socket.local_addr()
{
push_ip(addresses, local_addr.ip());
}
}
fn push_bound_addr<A: std::net::ToSocketAddrs>(addresses: &mut Vec<String>, bind_addr: A) {
if let Ok(local_addr) =
std::net::UdpSocket::bind(bind_addr).and_then(|socket| socket.local_addr())
{
push_ip(addresses, local_addr.ip());
}
}
fn push_ip(addresses: &mut Vec<String>, ip: IpAddr) {
if ip.is_unspecified() {
return;
}
let ip = ip.to_string();
if !addresses.contains(&ip) {
addresses.push(ip);
}
}
fn random_txn_id() -> [u8; 12] {
let mut txn_id = [0u8; 12];
for byte in &mut txn_id {
*byte = rand::random::<u8>();
}
txn_id
}
#[cfg(test)]
mod tests {
use super::is_private_overlay_candidate_ip;
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
#[test]
fn private_overlay_candidate_filter_includes_rfc1918_and_ula() {
assert!(is_private_overlay_candidate_ip(IpAddr::V4(Ipv4Addr::new(
192, 168, 1, 10
))));
assert!(is_private_overlay_candidate_ip(IpAddr::V4(Ipv4Addr::new(
10, 0, 0, 4
))));
assert!(is_private_overlay_candidate_ip(IpAddr::V4(Ipv4Addr::new(
172, 16, 5, 20
))));
assert!(is_private_overlay_candidate_ip(IpAddr::V6(
"fd00::1234".parse::<Ipv6Addr>().unwrap()
)));
}
#[test]
fn private_overlay_candidate_filter_excludes_public_and_link_local() {
assert!(!is_private_overlay_candidate_ip(IpAddr::V4(Ipv4Addr::new(
8, 8, 8, 8
))));
assert!(!is_private_overlay_candidate_ip(IpAddr::V4(Ipv4Addr::new(
169, 254, 1, 10
))));
assert!(!is_private_overlay_candidate_ip(IpAddr::V6(
"fe80::1".parse::<Ipv6Addr>().unwrap()
)));
assert!(!is_private_overlay_candidate_ip(IpAddr::V6(
"2001:db8::1".parse::<Ipv6Addr>().unwrap()
)));
}
}
src/discovery/nostr/tests.rs
+411
View File
@@ -0,0 +1,411 @@
use nostr::prelude::{EventBuilder, Kind, Tag, Timestamp};
use super::runtime::NostrDiscovery;
use super::signal::{
build_signal_event, create_traversal_answer, create_traversal_offer, validate_offer_freshness,
validate_traversal_answer_for_offer,
};
use super::stun::{parse_stun_binding_success, parse_stun_url};
use super::traversal::{
PunchStrategy, build_punch_packet, parse_punch_packet, plan_punch_targets,
planned_remote_endpoints, session_hash,
};
use super::{
ADVERT_IDENTIFIER, ADVERT_KIND, ADVERT_VERSION, OverlayAdvert, OverlayEndpointAdvert,
OverlayTransportKind, PunchHint, PunchPacketKind, TraversalAddress,
};
#[derive(Clone, Copy, PartialEq, Eq)]
enum NatType {
RestrictedCone,
PortRestricted,
Symmetric,
}
fn addr(ip: &str, port: u16) -> TraversalAddress {
TraversalAddress {
protocol: "udp".to_string(),
ip: ip.to_string(),
port,
}
}
fn can_reach(local_nat: NatType, remote_nat: NatType) -> bool {
if local_nat == NatType::Symmetric || remote_nat == NatType::Symmetric {
return false;
}
!(local_nat == NatType::PortRestricted && remote_nat == NatType::PortRestricted)
}
fn signed_overlay_advert_event(created_at_secs: u64, expiration_secs: Option<u64>) -> nostr::Event {
let keys = nostr::Keys::generate();
let content = r#"{"identifier":"fips-overlay-v1","version":1,"endpoints":[{"transport":"tcp","addr":"203.0.113.10:443"}]}"#;
let mut builder = EventBuilder::new(Kind::Custom(ADVERT_KIND), content)
.custom_created_at(Timestamp::from(created_at_secs));
if let Some(expiration_secs) = expiration_secs {
builder = builder.tags([Tag::expiration(Timestamp::from(expiration_secs))]);
}
builder.sign_with_keys(&keys).unwrap()
}
#[test]
fn serializes_direct_overlay_advert_without_nat_metadata() {
let advert = OverlayAdvert {
identifier: ADVERT_IDENTIFIER.to_string(),
version: ADVERT_VERSION,
endpoints: vec![
OverlayEndpointAdvert {
transport: OverlayTransportKind::Tcp,
addr: "203.0.113.10:443".to_string(),
},
OverlayEndpointAdvert {
transport: OverlayTransportKind::Tor,
addr: "exampleonion.onion:1234".to_string(),
},
],
signal_relays: None,
stun_servers: None,
};
let json = serde_json::to_string(&advert).unwrap();
assert!(json.contains("\"endpoints\""));
assert!(!json.contains("\"signalRelays\""));
assert!(!json.contains("\"stunServers\""));
}
#[test]
fn serializes_nat_overlay_advert_with_metadata() {
let advert = OverlayAdvert {
identifier: ADVERT_IDENTIFIER.to_string(),
version: ADVERT_VERSION,
endpoints: vec![OverlayEndpointAdvert {
transport: OverlayTransportKind::Udp,
addr: "nat".to_string(),
}],
signal_relays: Some(vec!["wss://relay.example".to_string()]),
stun_servers: Some(vec!["stun:stun.example.org:3478".to_string()]),
};
let json = serde_json::to_string(&advert).unwrap();
assert!(json.contains("\"signalRelays\""));
assert!(json.contains("\"stunServers\""));
}
#[test]
fn rejects_invalid_overlay_adverts() {
let missing_nat_metadata = OverlayAdvert {
identifier: ADVERT_IDENTIFIER.to_string(),
version: ADVERT_VERSION,
endpoints: vec![OverlayEndpointAdvert {
transport: OverlayTransportKind::Udp,
addr: "nat".to_string(),
}],
signal_relays: None,
stun_servers: None,
};
assert!(NostrDiscovery::validate_overlay_advert(missing_nat_metadata).is_err());
let wrong_identifier = OverlayAdvert {
identifier: "not-fips-overlay".to_string(),
version: ADVERT_VERSION,
endpoints: vec![OverlayEndpointAdvert {
transport: OverlayTransportKind::Tcp,
addr: "203.0.113.10:443".to_string(),
}],
signal_relays: None,
stun_servers: None,
};
assert!(NostrDiscovery::validate_overlay_advert(wrong_identifier).is_err());
}
#[test]
fn advert_freshness_rejects_expired_events() {
let now_secs = Timestamp::now().as_secs();
let event = signed_overlay_advert_event(now_secs, Some(now_secs.saturating_sub(1)));
let valid_until =
NostrDiscovery::compute_advert_valid_until_ms(&event, 600_000, now_secs * 1000);
assert!(valid_until.is_none());
}
#[test]
fn advert_freshness_rejects_stale_created_at_without_expiration() {
let now_secs = Timestamp::now().as_secs();
let stale_created = now_secs.saturating_sub(10_000);
let event = signed_overlay_advert_event(stale_created, None);
let valid_until =
NostrDiscovery::compute_advert_valid_until_ms(&event, 600_000, now_secs * 1000);
assert!(valid_until.is_none());
}
#[test]
fn advert_freshness_uses_earliest_expiration_bound() {
let now_secs = Timestamp::now().as_secs();
let event = signed_overlay_advert_event(now_secs.saturating_sub(10), Some(now_secs + 30));
let valid_until =
NostrDiscovery::compute_advert_valid_until_ms(&event, 3_600_000, now_secs * 1000)
.expect("event should be fresh");
assert_eq!(valid_until, (now_secs + 30) * 1000);
}
#[test]
fn parses_stun_urls() {
let parsed = parse_stun_url("stun:stun.l.google.com:19302").unwrap();
assert_eq!(parsed.host, "stun.l.google.com");
assert_eq!(parsed.port, 19302);
}
#[test]
fn parses_ipv6_stun_urls() {
let parsed = parse_stun_url("stun:[2001:db8::10]:3478").unwrap();
assert_eq!(parsed.host, "[2001:db8::10]");
assert_eq!(parsed.port, 3478);
}
#[test]
fn parses_ipv6_xor_mapped_address() {
let txn_id = [
0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x10, 0x32, 0x54, 0x76,
];
let addr = std::net::SocketAddr::new("2001:db8::1234".parse().unwrap(), 3478);
let port = addr.port() ^ 0x2112;
let mut attr = Vec::with_capacity(24);
attr.extend_from_slice(&0x0020u16.to_be_bytes());
attr.extend_from_slice(&20u16.to_be_bytes());
attr.push(0);
attr.push(0x02);
attr.extend_from_slice(&port.to_be_bytes());
let ipv6 = match addr.ip() {
std::net::IpAddr::V6(ip) => ip.octets(),
std::net::IpAddr::V4(_) => panic!("expected IPv6 test address"),
};
let cookie = 0x2112_a442u32.to_be_bytes();
for index in 0..16 {
let mask = if index < 4 {
cookie[index]
} else {
txn_id[index - 4]
};
attr.push(ipv6[index] ^ mask);
}
let mut packet = Vec::with_capacity(44);
packet.extend_from_slice(&0x0101u16.to_be_bytes());
packet.extend_from_slice(&(attr.len() as u16).to_be_bytes());
packet.extend_from_slice(&0x2112_a442u32.to_be_bytes());
packet.extend_from_slice(&txn_id);
packet.extend_from_slice(&attr);
assert_eq!(parse_stun_binding_success(&packet, &txn_id), Some(addr));
}
#[test]
fn builds_and_parses_probe_packets() {
let packet = build_punch_packet(PunchPacketKind::Probe, 7, "sess-1");
let parsed = parse_punch_packet(&packet).unwrap();
assert_eq!(parsed.kind, PunchPacketKind::Probe);
assert_eq!(parsed.sequence, 7);
assert_eq!(parsed.session_hash, session_hash("sess-1"));
}
#[test]
fn validates_offer_answer_pair() {
let offer = create_traversal_offer(
"sess-1".to_string(),
1_700_000_000_000,
60_000,
"offer-1".to_string(),
"npub1client".to_string(),
"npub1server".to_string(),
Some(addr("203.0.113.10", 62000)),
vec![addr("192.168.1.10", 62000)],
Some("stun:example.org:3478".to_string()),
);
let answer = create_traversal_answer(
"sess-1".to_string(),
1_700_000_000_500,
60_000,
"answer-1".to_string(),
"npub1server".to_string(),
"npub1client".to_string(),
"offer-1".to_string(),
true,
Some(addr("198.51.100.20", 63000)),
vec![addr("192.168.1.20", 63000)],
Some("stun:example.org:3478".to_string()),
Some(PunchHint {
start_at_ms: 1_700_000_002_000,
interval_ms: 200,
duration_ms: 10_000,
}),
None,
);
assert!(
validate_traversal_answer_for_offer(
&offer,
&answer,
1_700_000_000_900,
60_000,
"npub1server",
"npub1client",
)
.is_ok()
);
}
#[test]
fn rejects_offer_with_mismatched_actual_sender() {
let offer = create_traversal_offer(
"sess-1".to_string(),
1_700_000_000_000,
60_000,
"offer-1".to_string(),
"npub1claimed".to_string(),
"npub1server".to_string(),
None,
vec![addr("192.168.1.10", 62000)],
None,
);
let result = validate_offer_freshness(
&offer,
1_700_000_000_100,
60_000,
"npub1actual",
"npub1server",
);
assert!(result.is_err());
}
#[test]
fn rejects_answer_with_mismatched_actual_sender() {
let offer = create_traversal_offer(
"sess-1".to_string(),
1_700_000_000_000,
60_000,
"offer-1".to_string(),
"npub1client".to_string(),
"npub1server".to_string(),
Some(addr("203.0.113.10", 62000)),
vec![addr("192.168.1.10", 62000)],
Some("stun:example.org:3478".to_string()),
);
let answer = create_traversal_answer(
"sess-1".to_string(),
1_700_000_000_500,
60_000,
"answer-1".to_string(),
"npub1server".to_string(),
"npub1client".to_string(),
"offer-1".to_string(),
true,
Some(addr("198.51.100.20", 63000)),
vec![addr("192.168.1.20", 63000)],
Some("stun:example.org:3478".to_string()),
Some(PunchHint {
start_at_ms: 1_700_000_002_000,
interval_ms: 200,
duration_ms: 10_000,
}),
None,
);
let result = validate_traversal_answer_for_offer(
&offer,
&answer,
1_700_000_000_900,
60_000,
"npub1spoofed",
"npub1client",
);
assert!(result.is_err());
}
#[test]
fn plans_reflexive_targets_before_lan() {
let planned = plan_punch_targets(
&[addr("192.168.1.10", 62000)],
Some(&addr("203.0.113.10", 62000)),
&[addr("192.168.1.20", 63000)],
Some(&addr("198.51.100.20", 63000)),
);
assert_eq!(planned[0].strategy, PunchStrategy::Reflexive);
assert_eq!(planned[1].strategy, PunchStrategy::Lan);
}
#[test]
fn simulated_lan_scenario_includes_lan_target_and_succeeds() {
let planned = plan_punch_targets(
&[addr("192.168.1.10", 62000)],
Some(&addr("203.0.113.10", 62000)),
&[addr("192.168.1.20", 63000)],
Some(&addr("198.51.100.20", 63000)),
);
assert!(
planned
.iter()
.any(|target| target.strategy == PunchStrategy::Lan)
);
assert!(can_reach(NatType::RestrictedCone, NatType::RestrictedCone));
}
#[test]
fn simulated_symmetric_nat_scenario_requires_fallback() {
let planned = plan_punch_targets(
&[addr("10.0.0.10", 62000)],
Some(&addr("203.0.113.10", 62000)),
&[addr("10.0.1.10", 63000)],
Some(&addr("198.51.100.20", 63000)),
);
assert!(
planned
.iter()
.any(|target| target.strategy == PunchStrategy::Reflexive)
);
assert!(!can_reach(NatType::Symmetric, NatType::RestrictedCone));
}
#[test]
fn planned_remote_endpoints_include_private_and_reflexive_paths() {
let endpoints = planned_remote_endpoints(
&[addr("192.168.1.10", 62000)],
Some(&addr("203.0.113.10", 62000)),
&[addr("192.168.1.20", 63000)],
Some(&addr("198.51.100.20", 63000)),
)
.expect("endpoint planning should succeed");
assert!(endpoints.contains(&"192.168.1.20:63000".parse().unwrap()));
assert!(endpoints.contains(&"198.51.100.20:63000".parse().unwrap()));
}
#[tokio::test]
async fn signal_events_use_current_timestamps() {
let sender = nostr::Keys::generate();
let receiver = nostr::Keys::generate();
let rumor = EventBuilder::private_msg_rumor(receiver.public_key(), "hello".to_string())
.build(sender.public_key());
let before = Timestamp::now().as_secs();
let event = build_signal_event(
&sender,
receiver.public_key(),
rumor,
Timestamp::from(before + 30),
)
.await
.expect("signal event should build");
let after = Timestamp::now().as_secs();
let created_at = event.created_at.as_secs();
assert!(created_at >= before);
assert!(created_at <= after);
}
src/discovery/nostr/traversal.rs
+276
View File
@@ -0,0 +1,276 @@
use std::net::SocketAddr;
use std::sync::{Arc, OnceLock};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use tokio::net::UdpSocket;
use super::types::{
BootstrapError, PUNCH_ACK_MAGIC, PUNCH_MAGIC, PunchHint, PunchPacket, PunchPacketKind,
TraversalAddress,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum AddressSource {
Local,
Reflexive,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum PunchStrategy {
Lan,
Reflexive,
Mixed,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct PlannedPunchTarget {
pub(super) strategy: PunchStrategy,
pub(super) local_source: AddressSource,
pub(super) remote_source: AddressSource,
pub(super) local: TraversalAddress,
pub(super) remote: TraversalAddress,
}
fn same_subnet_24(left: &TraversalAddress, right: &TraversalAddress) -> bool {
let left_parts = left.ip.split('.').collect::<Vec<_>>();
let right_parts = right.ip.split('.').collect::<Vec<_>>();
left_parts.len() == 4 && right_parts.len() == 4 && left_parts[..3] == right_parts[..3]
}
pub(super) fn plan_punch_targets(
local_addresses: &[TraversalAddress],
local_reflexive_address: Option<&TraversalAddress>,
remote_addresses: &[TraversalAddress],
remote_reflexive_address: Option<&TraversalAddress>,
) -> Vec<PlannedPunchTarget> {
let mut planned = Vec::new();
let mut push_unique = |target: PlannedPunchTarget| {
if !planned.iter().any(|existing| existing == &target) {
planned.push(target);
}
};
// Reflexive ↔ Reflexive first: the only path that's reliable across
// arbitrary network topologies. Try this before any host-candidate path
// so we don't latch onto a misleading asymmetric route (e.g. an offer's
// private host candidate that we can reach one-way via a routed VPN).
if let (Some(local), Some(remote)) = (local_reflexive_address, remote_reflexive_address) {
push_unique(PlannedPunchTarget {
strategy: PunchStrategy::Reflexive,
local_source: AddressSource::Reflexive,
remote_source: AddressSource::Reflexive,
local: local.clone(),
remote: remote.clone(),
});
}
// Same-LAN paths (matching /24 between local and remote host candidates).
// Only fires when both sides exposed local candidates AND they share a
// /24 prefix.
for local in local_addresses {
for remote in remote_addresses {
if same_subnet_24(local, remote) {
push_unique(PlannedPunchTarget {
strategy: PunchStrategy::Lan,
local_source: AddressSource::Local,
remote_source: AddressSource::Local,
local: local.clone(),
remote: remote.clone(),
});
}
}
}
// Mixed paths cover hairpin and one-side-public scenarios.
if let Some(remote) = remote_reflexive_address {
for local in local_addresses {
push_unique(PlannedPunchTarget {
strategy: PunchStrategy::Mixed,
local_source: AddressSource::Local,
remote_source: AddressSource::Reflexive,
local: local.clone(),
remote: remote.clone(),
});
}
}
if let Some(local) = local_reflexive_address {
for remote in remote_addresses {
push_unique(PlannedPunchTarget {
strategy: PunchStrategy::Mixed,
local_source: AddressSource::Reflexive,
remote_source: AddressSource::Local,
local: local.clone(),
remote: remote.clone(),
});
}
}
planned
}
pub(super) fn planned_remote_endpoints(
local_addresses: &[TraversalAddress],
local_reflexive_address: Option<&TraversalAddress>,
remote_addresses: &[TraversalAddress],
remote_reflexive_address: Option<&TraversalAddress>,
) -> Result<Vec<SocketAddr>, BootstrapError> {
let mut remotes = Vec::new();
for target in plan_punch_targets(
local_addresses,
local_reflexive_address,
remote_addresses,
remote_reflexive_address,
) {
let remote = SocketAddr::new(
target
.remote
.ip
.parse()
.map_err(|_| BootstrapError::Protocol("invalid-remote-ip".to_string()))?,
target.remote.port,
);
if !remotes.contains(&remote) {
remotes.push(remote);
}
}
Ok(remotes)
}
pub(super) async fn run_punch_attempt(
socket: &std::net::UdpSocket,
session_id: &str,
targets: &[SocketAddr],
punch: PunchHint,
timeout: Duration,
) -> Result<SocketAddr, BootstrapError> {
if targets.is_empty() {
return Err(BootstrapError::Protocol("no-punch-targets".to_string()));
}
let udp = Arc::new(UdpSocket::from_std(socket.try_clone()?)?);
let started_at = tokio::time::Instant::now();
let finish_at = started_at + timeout;
let delay = Duration::from_millis(punch.start_at_ms.saturating_sub(now_ms()));
let send_socket = Arc::clone(&udp);
let send_targets = targets.to_vec();
let send_session = session_id.to_string();
let send_handle = tokio::spawn(async move {
tokio::time::sleep(delay).await;
let end = Instant::now() + Duration::from_millis(punch.duration_ms.max(1));
let mut sequence = 0u32;
while Instant::now() < end {
let packet = build_punch_packet(PunchPacketKind::Probe, sequence, &send_session);
for target in &send_targets {
let _ = send_socket.send_to(&packet, target).await;
}
sequence = sequence.wrapping_add(1);
tokio::time::sleep(Duration::from_millis(punch.interval_ms.max(20))).await;
}
});
let expected_hash = session_hash(session_id);
let mut buf = [0u8; 2048];
let result = loop {
let recv = tokio::time::timeout_at(finish_at, udp.recv_from(&mut buf)).await;
let Ok(Ok((len, remote))) = recv else {
break Err(BootstrapError::PunchTimeout(session_id.to_string()));
};
let Ok(packet) = parse_punch_packet(&buf[..len]) else {
continue;
};
if packet.session_hash != expected_hash {
continue;
}
if packet.kind == PunchPacketKind::Probe {
let ack = build_punch_packet(PunchPacketKind::Ack, packet.sequence, session_id);
let _ = udp.send_to(&ack, remote).await;
}
break Ok(remote);
};
send_handle.abort();
result
}
pub(super) fn nonce() -> String {
format!("{}-{:016x}", now_ms(), rand::random::<u64>())
}
pub(super) fn now_ms() -> u64 {
struct ClockAnchor {
started_at: Instant,
started_unix_ms: u64,
}
static ANCHOR: OnceLock<ClockAnchor> = OnceLock::new();
let anchor = ANCHOR.get_or_init(|| ClockAnchor {
started_at: Instant::now(),
started_unix_ms: SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_millis() as u64)
.unwrap_or(0),
});
anchor
.started_unix_ms
.saturating_add(anchor.started_at.elapsed().as_millis() as u64)
}
pub(super) fn session_hash(session_id: &str) -> [u8; 16] {
use sha2::{Digest, Sha256};
let digest = Sha256::digest(session_id.as_bytes());
let mut output = [0u8; 16];
output.copy_from_slice(&digest[..16]);
output
}
pub(super) fn build_punch_packet(
kind: PunchPacketKind,
sequence: u32,
session_id: &str,
) -> [u8; 24] {
let magic = match kind {
PunchPacketKind::Probe => PUNCH_MAGIC,
PunchPacketKind::Ack => PUNCH_ACK_MAGIC,
};
let mut packet = [0u8; 24];
packet[..4].copy_from_slice(&magic.to_be_bytes());
packet[4..8].copy_from_slice(&sequence.to_be_bytes());
packet[8..24].copy_from_slice(&session_hash(session_id));
packet
}
pub(super) fn parse_punch_packet(bytes: &[u8]) -> Result<PunchPacket, BootstrapError> {
if bytes.len() < 24 {
return Err(BootstrapError::Protocol(
"invalid-punch-packet-length".to_string(),
));
}
let magic = u32::from_be_bytes(
bytes[..4]
.try_into()
.map_err(|_| BootstrapError::Protocol("invalid-punch-magic".to_string()))?,
);
let kind = match magic {
PUNCH_MAGIC => PunchPacketKind::Probe,
PUNCH_ACK_MAGIC => PunchPacketKind::Ack,
_ => {
return Err(BootstrapError::Protocol("invalid-punch-magic".to_string()));
}
};
let sequence = u32::from_be_bytes(
bytes[4..8]
.try_into()
.map_err(|_| BootstrapError::Protocol("invalid-punch-seq".to_string()))?,
);
let mut hash = [0u8; 16];
hash.copy_from_slice(&bytes[8..24]);
Ok(PunchPacket {
kind,
sequence,
session_hash: hash,
})
}
src/discovery/nostr/types.rs
+179
View File
@@ -0,0 +1,179 @@
use crate::config::PeerConfig;
use crate::discovery::EstablishedTraversal;
use serde::{Deserialize, Serialize};
pub const ADVERT_KIND: u16 = 37195;
pub const ADVERT_IDENTIFIER: &str = "fips-overlay-v1";
pub const ADVERT_VERSION: u32 = 1;
pub const SIGNAL_KIND: u16 = 21059;
pub const PUNCH_MAGIC: u32 = 0x4E505443;
pub const PUNCH_ACK_MAGIC: u32 = 0x4E505441;
pub const PROTOCOL_VERSION: &str = "1";
#[derive(Debug, thiserror::Error)]
pub enum BootstrapError {
#[error("bootstrap disabled")]
Disabled,
#[error("peer {0} has no overlay advert")]
MissingAdvert(String),
#[error("peer {0} advert does not contain udp:nat endpoint")]
MissingNatEndpoint(String),
#[error("peer {0} has no usable traversal relays")]
MissingRelays(String),
#[error("invalid overlay advert: {0}")]
InvalidAdvert(String),
#[error("invalid npub '{npub}': {reason}")]
InvalidPeerNpub { npub: String, reason: String },
#[error("signal timeout waiting for answer from {0}")]
SignalTimeout(String),
#[error("traversal attempt timed out for {0}")]
PunchTimeout(String),
#[error("replayed or duplicate session id: {0}")]
Replay(String),
#[error("stun failed: {0}")]
Stun(String),
#[error("protocol error: {0}")]
Protocol(String),
#[error("nostr error: {0}")]
Nostr(String),
#[error("io error: {0}")]
Io(#[from] std::io::Error),
#[error("serde error: {0}")]
Serde(#[from] serde_json::Error),
#[error("event parse error: {0}")]
EventParse(String),
}
#[derive(Debug)]
pub enum BootstrapEvent {
Established {
traversal: EstablishedTraversal,
},
Failed {
peer_config: PeerConfig,
reason: String,
},
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TraversalAddress {
pub protocol: String,
pub ip: String,
pub port: u16,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PunchHint {
#[serde(rename = "startAtMs")]
pub start_at_ms: u64,
#[serde(rename = "intervalMs")]
pub interval_ms: u64,
#[serde(rename = "durationMs")]
pub duration_ms: u64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum OverlayTransportKind {
Udp,
Tcp,
Tor,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct OverlayEndpointAdvert {
pub transport: OverlayTransportKind,
pub addr: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct OverlayAdvert {
pub identifier: String,
pub version: u32,
pub endpoints: Vec<OverlayEndpointAdvert>,
#[serde(rename = "signalRelays", skip_serializing_if = "Option::is_none")]
pub signal_relays: Option<Vec<String>>,
#[serde(rename = "stunServers", skip_serializing_if = "Option::is_none")]
pub stun_servers: Option<Vec<String>>,
}
impl OverlayAdvert {
pub fn has_udp_nat_endpoint(&self) -> bool {
self.endpoints.iter().any(|endpoint| {
endpoint.transport == OverlayTransportKind::Udp
&& endpoint.addr.eq_ignore_ascii_case("nat")
})
}
}
#[derive(Debug, Clone)]
pub struct CachedOverlayAdvert {
pub author_npub: String,
pub advert: OverlayAdvert,
pub created_at: u64,
pub valid_until_ms: u64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TraversalOffer {
#[serde(rename = "type")]
pub message_type: String,
#[serde(rename = "sessionId")]
pub session_id: String,
#[serde(rename = "issuedAt")]
pub issued_at: u64,
#[serde(rename = "expiresAt")]
pub expires_at: u64,
pub nonce: String,
#[serde(rename = "senderNpub")]
pub sender_npub: String,
#[serde(rename = "recipientNpub")]
pub recipient_npub: String,
#[serde(rename = "reflexiveAddress")]
pub reflexive_address: Option<TraversalAddress>,
#[serde(rename = "localAddresses")]
pub local_addresses: Vec<TraversalAddress>,
#[serde(rename = "stunServer")]
pub stun_server: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TraversalAnswer {
#[serde(rename = "type")]
pub message_type: String,
#[serde(rename = "sessionId")]
pub session_id: String,
#[serde(rename = "issuedAt")]
pub issued_at: u64,
#[serde(rename = "expiresAt")]
pub expires_at: u64,
pub nonce: String,
#[serde(rename = "senderNpub")]
pub sender_npub: String,
#[serde(rename = "recipientNpub")]
pub recipient_npub: String,
#[serde(rename = "inReplyTo")]
pub in_reply_to: String,
pub accepted: bool,
#[serde(rename = "reflexiveAddress")]
pub reflexive_address: Option<TraversalAddress>,
#[serde(rename = "localAddresses")]
pub local_addresses: Vec<TraversalAddress>,
#[serde(rename = "stunServer")]
pub stun_server: Option<String>,
pub punch: Option<PunchHint>,
pub reason: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PunchPacketKind {
Probe,
Ack,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PunchPacket {
pub kind: PunchPacketKind,
pub sequence: u32,
pub session_hash: [u8; 16],
}
src/lib.rs
+5 -1
View File
@@ -7,7 +7,8 @@ pub mod bloom;
pub mod cache;
pub mod config;
pub mod control;
#[cfg(feature = "gateway")]
pub mod discovery;
#[cfg(target_os = "linux")]
pub mod gateway;
pub mod identity;
pub mod mmp;
@@ -31,6 +32,9 @@ pub use identity::{
pub use config::{Config, ConfigError, IdentityConfig, TorConfig, UdpConfig};
pub use upper::config::{DnsConfig, TunConfig};
// Re-export discovery types
pub use discovery::{BootstrapHandoffResult, EstablishedTraversal};
// Re-export tree types
pub use tree::{CoordEntry, ParentDeclaration, TreeCoordinate, TreeError, TreeState};
src/node/discovery_rate_limit.rs
+14 -11
View File
@@ -2,10 +2,12 @@
//!
//! Two complementary mechanisms:
//!
//! - **`DiscoveryBackoff`** (originator-side): Exponential backoff for failed
//! lookups. After a lookup times out, suppresses re-initiation with
//! increasing delays (30s → 60s → 300s cap). Reset on topology changes
//! (parent change, new peer, first RTT, reconnection).
//! - **`DiscoveryBackoff`** (originator-side, optional): Exponential
//! suppression of fresh lookups after the per-attempt sequence in
//! `node.discovery.attempt_timeouts_secs` has been exhausted.
//! **Disabled by default** (base/cap = 0); the per-attempt sequence
//! is the only retry pacing in the standard configuration. Reset on
//! topology changes (parent change, new peer, first RTT, reconnection).
//!
//! - **`DiscoveryForwardRateLimiter`** (transit-side): Per-target minimum
//! interval for forwarded requests. Defense-in-depth against misbehaving
@@ -19,11 +21,11 @@ use std::time::{Duration, Instant};
// Originator-side: Discovery Backoff
// ============================================================================
/// Default base backoff after first lookup failure.
const DEFAULT_BACKOFF_BASE_SECS: u64 = 30;
/// Default base backoff after first lookup failure. `0` = disabled.
const DEFAULT_BACKOFF_BASE_SECS: u64 = 0;
/// Default maximum backoff cap.
const DEFAULT_BACKOFF_MAX_SECS: u64 = 300;
/// Default maximum backoff cap. `0` = disabled.
const DEFAULT_BACKOFF_MAX_SECS: u64 = 0;
/// Backoff multiplier per consecutive failure.
const BACKOFF_MULTIPLIER: u64 = 2;
@@ -49,7 +51,7 @@ struct BackoffEntry {
}
impl DiscoveryBackoff {
/// Create with default parameters (30s base, 300s cap).
/// Create with default parameters (disabled — base/cap = 0).
pub fn new() -> Self {
Self::with_params(DEFAULT_BACKOFF_BASE_SECS, DEFAULT_BACKOFF_MAX_SECS)
}
@@ -245,7 +247,8 @@ mod tests {
#[test]
fn test_backoff_suppressed_after_failure() {
let mut backoff = DiscoveryBackoff::new();
// Backoff is opt-in; exercise the suppression path with explicit params.
let mut backoff = DiscoveryBackoff::with_params(30, 300);
backoff.record_failure(&addr(1));
assert!(backoff.is_suppressed(&addr(1)));
// Different target not affected
@@ -254,7 +257,7 @@ mod tests {
#[test]
fn test_backoff_cleared_on_success() {
let mut backoff = DiscoveryBackoff::new();
let mut backoff = DiscoveryBackoff::with_params(30, 300);
backoff.record_failure(&addr(1));
assert!(backoff.is_suppressed(&addr(1)));
src/node/handlers/discovery.rs
+35 -34
View File
@@ -444,31 +444,26 @@ impl Node {
/// Initiate a discovery lookup if one is not already pending for this target.
///
/// Checks: pending dedup, backoff, bloom filter pre-check. If all pass,
/// initiates the lookup. If no tree peers have the target in their bloom
/// filter, the lookup is skipped (bloom miss) and recorded as a failure
/// for backoff purposes.
/// Checks: pending dedup, post-failure backoff (off by default), bloom
/// filter pre-check. If all pass, sends the first attempt's LookupRequest.
/// Subsequent attempts (with fresh request_ids) are scheduled by
/// [`Self::check_pending_lookups`] when each attempt's per-attempt timeout
/// expires, using the sequence in `node.discovery.attempt_timeouts_secs`.
pub(in crate::node) async fn maybe_initiate_lookup(&mut self, dest: &NodeAddr) {
let now_ms = Self::now_ms();
let lookup_timeout_ms = self.config.node.discovery.timeout_secs * 1000;
// Check pending lookup dedup (in-flight)
if let Some(entry) = self.pending_lookups.get(dest) {
let age_ms = now_ms.saturating_sub(entry.initiated_ms);
let attempt = entry.attempt;
if age_ms < lookup_timeout_ms {
self.stats_mut().discovery.req_deduplicated += 1;
debug!(
target_node = %self.peer_display_name(dest),
age_ms = age_ms,
attempt = attempt,
"Discovery lookup deduplicated, already pending"
);
return;
}
// Dedup: any pending lookup means we are already trying.
if self.pending_lookups.contains_key(dest) {
self.stats_mut().discovery.req_deduplicated += 1;
debug!(
target_node = %self.peer_display_name(dest),
"Discovery lookup deduplicated, already pending"
);
return;
}
// Check backoff from previous failures
// Optional post-failure suppression. Defaults are 0/0 (inert);
// operators can opt in by setting `node.discovery.backoff_*_secs`.
if self.discovery_backoff.is_suppressed(dest) {
self.stats_mut().discovery.req_backoff_suppressed += 1;
debug!(
@@ -508,27 +503,33 @@ impl Node {
}
}
/// Check pending lookups for retry or timeout.
/// Check pending lookups for next-attempt or final timeout.
///
/// Called periodically from the tick handler. For each pending lookup:
/// - If retry interval elapsed and attempts remain: resend
/// - If total timeout elapsed: fail, record backoff, send ICMP unreachable
/// Called periodically from the tick handler. The lookup state machine
/// runs through `node.discovery.attempt_timeouts_secs` (default
/// `[1, 2, 4, 8]`): each entry is the deadline for one attempt. When the
/// current attempt's deadline elapses:
/// - If more entries remain: send the next attempt with a fresh
/// `request_id`.
/// - Otherwise: declare the destination unreachable, drop queued packets,
/// and emit ICMPv6 destination-unreachable for each.
pub(in crate::node) async fn check_pending_lookups(&mut self, now_ms: u64) {
let timeout_ms = self.config.node.discovery.timeout_secs * 1000;
let retry_ms = self.config.node.discovery.retry_interval_secs * 1000;
let timeouts = self.config.node.discovery.attempt_timeouts_secs.clone();
let max_attempts = timeouts.len() as u8;
// Collect targets needing action
let mut to_retry: Vec<NodeAddr> = Vec::new();
let mut to_timeout: Vec<NodeAddr> = Vec::new();
for (&target, entry) in &self.pending_lookups {
let age = now_ms.saturating_sub(entry.initiated_ms);
if age >= timeout_ms {
to_timeout.push(target);
} else if entry.attempt < self.config.node.discovery.max_attempts
&& now_ms.saturating_sub(entry.last_sent_ms) >= retry_ms
{
to_retry.push(target);
let attempt_idx = (entry.attempt as usize).saturating_sub(1);
let attempt_timeout_ms = timeouts.get(attempt_idx).copied().unwrap_or(0) * 1000;
if now_ms.saturating_sub(entry.last_sent_ms) >= attempt_timeout_ms {
if entry.attempt >= max_attempts {
to_timeout.push(target);
} else {
to_retry.push(target);
}
}
}
@@ -556,7 +557,7 @@ impl Node {
self.stats_mut().discovery.resp_timed_out += 1;
self.pending_lookups.remove(&addr);
// Record failure for backoff
// Record failure for optional backoff
self.discovery_backoff.record_failure(&addr);
let failures = self.discovery_backoff.failure_count(&addr);
src/node/handlers/dispatch.rs
+3
View File
@@ -179,6 +179,9 @@ impl Node {
// Remove link and address mapping
self.remove_link(&link_id);
if let Some(transport_id) = transport_id {
self.cleanup_bootstrap_transport_if_unused(transport_id);
}
// Tree state cleanup
let tree_changed = self.handle_peer_removal_tree_cleanup(node_addr);
src/node/handlers/rx_loop.rs
+3 -4
View File
@@ -114,12 +114,11 @@ impl Node {
}
_ = tick.tick() => {
self.check_timeouts();
let now_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
let now_ms = Self::now_ms();
self.reload_peer_acl();
self.poll_pending_connects().await;
#[cfg(feature = "nostr-discovery")]
self.poll_nostr_discovery().await;
self.resend_pending_handshakes(now_ms).await;
self.resend_pending_rekeys(now_ms).await;
self.resend_pending_session_handshakes(now_ms).await;
src/node/handlers/timeout.rs
+5 -4
View File
@@ -16,10 +16,7 @@ impl Node {
return;
}
let now_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
let now_ms = Self::now_ms();
let timeout_ms = self.config.node.rate_limit.handshake_timeout_secs * 1000;
let stale: Vec<LinkId> = self
@@ -70,6 +67,7 @@ impl Node {
Some(c) => c,
None => return,
};
let transport_id = conn.transport_id();
// Free session index and pending_outbound/pending_inbound if allocated
if let Some(idx) = conn.our_index() {
@@ -82,6 +80,9 @@ impl Node {
// Remove link and addr_to_link
self.remove_link(&link_id);
if let Some(transport_id) = transport_id {
self.cleanup_bootstrap_transport_if_unused(transport_id);
}
}
/// Resend handshake messages for pending connections.
src/node/lifecycle.rs
+692 -97
View File
@@ -1,6 +1,13 @@
//! Node lifecycle management: start, stop, and peer connection initiation.
use super::{Node, NodeError, NodeState};
use crate::config::{ConnectPolicy, PeerAddress, PeerConfig};
#[cfg(feature = "nostr-discovery")]
use crate::discovery::nostr::{
ADVERT_IDENTIFIER, ADVERT_VERSION, BootstrapEvent, NostrDiscovery, OverlayAdvert,
OverlayEndpointAdvert, OverlayTransportKind,
};
use crate::discovery::{BootstrapHandoffResult, EstablishedTraversal};
use crate::node::acl::PeerAclContext;
use crate::node::wire::build_msg1;
use crate::peer::PeerConnection;
@@ -8,10 +15,15 @@ use crate::protocol::{Disconnect, DisconnectReason};
use crate::transport::{Link, LinkDirection, LinkId, TransportAddr, TransportId, packet_channel};
use crate::upper::tun::{TunDevice, TunState, run_tun_reader, shutdown_tun_interface};
use crate::{NodeAddr, PeerIdentity};
#[cfg(feature = "nostr-discovery")]
use std::collections::HashSet;
use std::thread;
use std::time::Duration;
use tracing::{debug, info, warn};
#[cfg(feature = "nostr-discovery")]
const OPEN_DISCOVERY_RETRY_LIFETIME_MULTIPLIER: u64 = 2;
impl Node {
/// Initiate connections to configured static peers.
///
@@ -107,86 +119,8 @@ impl Node {
return Ok(());
}
// Try addresses in priority order until one works
for addr in peer_config.addresses_by_priority() {
// For Ethernet addresses ("interface/mac"), find the transport
// instance matching the interface name and parse the MAC.
let (transport_id, remote_addr) = if addr.transport == "ethernet" {
match self.resolve_ethernet_addr(&addr.addr) {
Ok(result) => result,
Err(e) => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
error = %e,
"Failed to resolve Ethernet address"
);
continue;
}
}
} else if addr.transport == "ble" {
#[cfg(target_os = "linux")]
{
match self.resolve_ble_addr(&addr.addr) {
Ok(result) => result,
Err(e) => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
error = %e,
"Failed to resolve BLE address"
);
continue;
}
}
}
#[cfg(not(target_os = "linux"))]
{
debug!(
transport = %addr.transport,
"BLE transport not available on this platform"
);
continue;
}
} else {
// Find a transport matching this address type
let tid = match self.find_transport_for_type(&addr.transport) {
Some(id) => id,
None => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
"No operational transport for address type"
);
continue;
}
};
(tid, TransportAddr::from_string(&addr.addr))
};
match self
.initiate_connection(transport_id, remote_addr, Some(peer_identity))
.await
{
Ok(()) => return Ok(()),
Err(e @ NodeError::AccessDenied(_)) => return Err(e),
Err(e) => {
debug!(
npub = %peer_config.npub,
transport_id = %transport_id,
error = %e,
"Connection attempt failed, trying next address"
);
continue;
}
}
}
// No address worked
Err(NodeError::NoTransportForType(format!(
"no operational transport for any of {}'s addresses",
peer_config.npub
)))
self.try_peer_addresses(peer_config, peer_identity, true)
.await
}
/// Initiate a connection to a peer on a specific transport and address.
@@ -302,15 +236,12 @@ impl Node {
remote_addr: TransportAddr,
peer_identity: Option<PeerIdentity>,
) -> Result<(), NodeError> {
// Create connection in handshake phase
let current_time_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
// Create connection in handshake phase. Anonymous discovery
// (no peer_identity) leaves identity to be learned from XX msg2.
let current_time_ms = Self::now_ms();
let mut connection = if let Some(identity) = peer_identity {
PeerConnection::outbound(link_id, identity, current_time_ms)
} else {
// Anonymous discovery connection — identity learned from XX msg2
PeerConnection::outbound_anonymous(link_id, current_time_ms)
};
@@ -491,6 +422,58 @@ impl Node {
}
}
#[cfg(feature = "nostr-discovery")]
pub(super) async fn poll_nostr_discovery(&mut self) {
let Some(bootstrap) = self.nostr_discovery.clone() else {
return;
};
if let Err(err) = self.refresh_overlay_advert(&bootstrap).await {
debug!(error = %err, "Failed to refresh local Nostr overlay advert");
}
for event in bootstrap.drain_events().await {
match event {
BootstrapEvent::Established { traversal } => {
let peer_npub = traversal.peer_npub.clone();
match self.adopt_established_traversal(traversal).await {
Ok(_) => {
info!(peer_npub = %peer_npub, "Adopted NAT traversal socket");
}
Err(err) => {
warn!(peer_npub = %peer_npub, error = %err, "Failed to adopt NAT traversal");
if let Ok(peer_identity) = PeerIdentity::from_npub(&peer_npub) {
self.schedule_retry(*peer_identity.node_addr(), Self::now_ms());
}
}
}
}
BootstrapEvent::Failed {
peer_config,
reason,
} => {
warn!(npub = %peer_config.npub, error = %reason, "NAT traversal failed");
let peer_identity = match PeerIdentity::from_npub(&peer_config.npub) {
Ok(identity) => identity,
Err(_) => continue,
};
if self
.try_peer_addresses(&peer_config, peer_identity, false)
.await
.is_ok()
{
continue;
}
self.schedule_retry(*peer_identity.node_addr(), Self::now_ms());
}
}
}
self.queue_open_discovery_retries(&bootstrap).await;
}
/// Poll pending transport connects and initiate handshakes for ready ones.
///
/// Called from the tick handler. For each pending connect, queries the
@@ -573,17 +556,14 @@ impl Node {
"Transport connect failed"
);
// Clean up link and schedule retry
// Clean up link and schedule retry. Anonymous discovery
// connections (no expected identity) don't retry —
// they'll be rediscovered via the shared-medium beacon.
self.remove_link(&pending.link_id);
self.links.remove(&pending.link_id);
if let Some(ref id) = pending.peer_identity {
let now_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
self.schedule_retry(*id.node_addr(), now_ms);
self.schedule_retry(*id.node_addr(), Self::now_ms());
}
// Anonymous connections don't retry — they'll be rediscovered
}
}
}
@@ -606,7 +586,7 @@ impl Node {
self.packet_tx = Some(packet_tx.clone());
self.packet_rx = Some(packet_rx);
// Initialize transports first (before TUN)
// Initialize transports first (before TUN, before Nostr discovery).
let transport_handles = self.create_transports(&packet_tx).await;
for mut handle in transport_handles {
@@ -632,6 +612,31 @@ impl Node {
info!(count = self.transports.len(), "Transports initialized");
}
#[cfg(feature = "nostr-discovery")]
if self.config.node.discovery.nostr.enabled {
match NostrDiscovery::start(&self.identity, self.config.node.discovery.nostr.clone())
.await
{
Ok(runtime) => {
if let Err(err) = self.refresh_overlay_advert(&runtime).await {
warn!(error = %err, "Failed to publish initial Nostr overlay advert");
}
self.nostr_discovery = Some(runtime);
info!("Nostr overlay discovery enabled");
}
Err(err) => {
warn!(error = %err, "Failed to start Nostr overlay discovery");
}
}
}
#[cfg(not(feature = "nostr-discovery"))]
if self.config.node.discovery.nostr.enabled {
warn!(
"Nostr overlay discovery configured but this build was compiled without the 'nostr-discovery' feature"
);
}
// Connect to static peers before TUN is active
// This allows handshake messages to be sent before we start accepting packets
self.initiate_peer_connections().await;
@@ -898,6 +903,14 @@ impl Node {
self.send_disconnect_to_all_peers(DisconnectReason::Shutdown)
.await;
// Stop Nostr overlay discovery background work and withdraw any advert.
#[cfg(feature = "nostr-discovery")]
if let Some(bootstrap) = self.nostr_discovery.take()
&& let Err(e) = bootstrap.shutdown().await
{
warn!(error = %e, "Failed to shutdown Nostr overlay discovery");
}
// Shutdown transports (they're packet producers)
let transport_ids: Vec<_> = self.transports.keys().cloned().collect();
for transport_id in transport_ids {
@@ -1005,6 +1018,500 @@ impl Node {
info!(sent, total = peer_addrs.len(), reason = %reason, "Sent disconnect notifications");
}
fn static_peer_addresses(&self, peer_config: &PeerConfig) -> Vec<PeerAddress> {
peer_config
.addresses_by_priority()
.into_iter()
.cloned()
.collect()
}
#[cfg(feature = "nostr-discovery")]
async fn nostr_peer_fallback_addresses(
&self,
peer_config: &PeerConfig,
existing: &[PeerAddress],
) -> Vec<PeerAddress> {
if !self.config.node.discovery.nostr.enabled
|| !peer_config.via_nostr
|| self.config.node.discovery.nostr.policy
== crate::config::NostrDiscoveryPolicy::Disabled
{
return Vec::new();
}
let Some(bootstrap) = self.nostr_discovery.clone() else {
return Vec::new();
};
let endpoints = match bootstrap.advert_endpoints_for_peer(&peer_config.npub).await {
Ok(endpoints) => endpoints,
Err(err) => {
debug!(
npub = %peer_config.npub,
error = %err,
"Failed to resolve Nostr advert endpoints for configured peer"
);
return Vec::new();
}
};
let mut fallback = Vec::new();
let mut next_priority = existing
.iter()
.map(|addr| addr.priority)
.max()
.unwrap_or(100)
.saturating_add(1);
for endpoint in endpoints {
let Some(candidate) = Self::overlay_endpoint_to_peer_address(&endpoint, next_priority)
else {
continue;
};
if existing
.iter()
.any(|addr| addr.transport == candidate.transport && addr.addr == candidate.addr)
|| fallback.iter().any(|addr: &PeerAddress| {
addr.transport == candidate.transport && addr.addr == candidate.addr
})
{
continue;
}
fallback.push(candidate);
next_priority = next_priority.saturating_add(1);
}
fallback
}
#[cfg(feature = "nostr-discovery")]
fn overlay_endpoint_to_peer_address(
endpoint: &OverlayEndpointAdvert,
priority: u8,
) -> Option<PeerAddress> {
let transport = match endpoint.transport {
OverlayTransportKind::Udp => "udp",
OverlayTransportKind::Tcp => "tcp",
OverlayTransportKind::Tor => "tor",
};
Some(PeerAddress::with_priority(
transport,
endpoint.addr.clone(),
priority,
))
}
async fn attempt_peer_address_list(
&mut self,
peer_config: &PeerConfig,
peer_identity: PeerIdentity,
allow_bootstrap_nat: bool,
addresses: &[PeerAddress],
) -> Result<(), NodeError> {
for addr in addresses {
if addr.transport == "udp" && addr.addr.eq_ignore_ascii_case("nat") {
if !allow_bootstrap_nat {
continue;
}
#[cfg(not(feature = "nostr-discovery"))]
{
debug!(npub = %peer_config.npub, "Skipping udp:nat address because this build does not include the nostr-discovery feature");
continue;
}
#[cfg(feature = "nostr-discovery")]
{
let Some(bootstrap) = self.nostr_discovery.clone() else {
debug!(npub = %peer_config.npub, "No Nostr overlay runtime for udp:nat address");
continue;
};
bootstrap.request_connect(peer_config.clone()).await;
info!(npub = %peer_config.npub, "Started Nostr UDP NAT traversal attempt");
return Ok(());
}
}
let (transport_id, remote_addr) = if addr.transport == "ethernet" {
match self.resolve_ethernet_addr(&addr.addr) {
Ok(result) => result,
Err(e) => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
error = %e,
"Failed to resolve Ethernet address"
);
continue;
}
}
} else if addr.transport == "ble" {
#[cfg(bluer_available)]
{
match self.resolve_ble_addr(&addr.addr) {
Ok(result) => result,
Err(e) => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
error = %e,
"Failed to resolve BLE address"
);
continue;
}
}
}
#[cfg(not(bluer_available))]
{
debug!(transport = %addr.transport, "BLE transport not available on this build");
continue;
}
} else {
let tid = match self.find_transport_for_type(&addr.transport) {
Some(id) => id,
None => {
debug!(
transport = %addr.transport,
addr = %addr.addr,
"No operational transport for address type"
);
continue;
}
};
(tid, TransportAddr::from_string(&addr.addr))
};
match self
.initiate_connection(transport_id, remote_addr, Some(peer_identity))
.await
{
Ok(()) => return Ok(()),
Err(e @ NodeError::AccessDenied(_)) => return Err(e),
Err(e) => {
debug!(
npub = %peer_config.npub,
transport_id = %transport_id,
error = %e,
"Connection attempt failed, trying next address"
);
}
}
}
Err(NodeError::NoTransportForType(format!(
"no operational transport for any of {}'s addresses",
peer_config.npub
)))
}
#[cfg(feature = "nostr-discovery")]
async fn queue_open_discovery_retries(&mut self, bootstrap: &std::sync::Arc<NostrDiscovery>) {
if !self.config.node.discovery.nostr.enabled
|| self.config.node.discovery.nostr.policy != crate::config::NostrDiscoveryPolicy::Open
{
return;
}
let configured_npubs = self
.config
.peers()
.iter()
.map(|peer| peer.npub.clone())
.collect::<HashSet<_>>();
let now_ms = Self::now_ms();
let mut enqueue_budget = self.open_discovery_enqueue_budget(&configured_npubs);
if enqueue_budget == 0 {
return;
}
for (npub, endpoints) in bootstrap.cached_open_discovery_candidates(64).await {
if enqueue_budget == 0 {
break;
}
if configured_npubs.contains(&npub) {
continue;
}
let peer_identity = match PeerIdentity::from_npub(&npub) {
Ok(identity) => identity,
Err(_) => continue,
};
let node_addr = *peer_identity.node_addr();
if node_addr == *self.identity.node_addr() || self.peers.contains_key(&node_addr) {
continue;
}
if self.retry_pending.contains_key(&node_addr) {
continue;
}
let connecting = self.connections.values().any(|conn| {
conn.expected_identity()
.map(|id| id.node_addr() == &node_addr)
.unwrap_or(false)
});
if connecting {
continue;
}
let mut addresses = Vec::new();
let mut priority = 120u8;
for endpoint in endpoints {
let Some(candidate) = Self::overlay_endpoint_to_peer_address(&endpoint, priority)
else {
continue;
};
if addresses.iter().any(|existing: &PeerAddress| {
existing.transport == candidate.transport && existing.addr == candidate.addr
}) {
continue;
}
addresses.push(candidate);
priority = priority.saturating_add(1);
}
if addresses.is_empty() {
continue;
}
self.peer_aliases
.entry(node_addr)
.or_insert_with(|| peer_identity.short_npub());
self.register_identity(node_addr, peer_identity.pubkey_full());
let mut state = super::retry::RetryState::new(PeerConfig {
npub: npub.clone(),
alias: None,
addresses,
connect_policy: ConnectPolicy::AutoConnect,
auto_reconnect: true,
via_nostr: false,
});
state.reconnect = false;
state.retry_after_ms = now_ms;
state.expires_at_ms = Some(self.open_discovery_retry_expires_at_ms(now_ms));
self.retry_pending.insert(node_addr, state);
enqueue_budget = enqueue_budget.saturating_sub(1);
}
}
#[cfg(feature = "nostr-discovery")]
fn available_outbound_slots(&self) -> usize {
let connection_used = self
.connections
.len()
.saturating_add(self.pending_connects.len());
let connection_slots = if self.max_connections == 0 {
usize::MAX
} else {
self.max_connections.saturating_sub(connection_used)
};
let peer_slots = if self.max_peers == 0 {
usize::MAX
} else {
self.max_peers.saturating_sub(self.peers.len())
};
connection_slots.min(peer_slots)
}
#[cfg(feature = "nostr-discovery")]
fn open_discovery_enqueue_budget(&self, configured_npubs: &HashSet<String>) -> usize {
let current_open_discovery_pending = self
.retry_pending
.values()
.filter(|state| !configured_npubs.contains(&state.peer_config.npub))
.count();
let cap_remaining = self
.config
.node
.discovery
.nostr
.open_discovery_max_pending
.saturating_sub(current_open_discovery_pending);
cap_remaining.min(self.available_outbound_slots())
}
#[cfg(feature = "nostr-discovery")]
fn open_discovery_retry_expires_at_ms(&self, now_ms: u64) -> u64 {
now_ms.saturating_add(
self.config
.node
.discovery
.nostr
.advert_ttl_secs
.saturating_mul(1000)
.saturating_mul(OPEN_DISCOVERY_RETRY_LIFETIME_MULTIPLIER),
)
}
#[cfg(feature = "nostr-discovery")]
fn build_overlay_advert(&self) -> Option<OverlayAdvert> {
if !self.config.node.discovery.nostr.enabled {
return None;
}
let mut endpoints = Vec::new();
let mut has_udp_nat = false;
for handle in self.transports.values() {
if !handle.is_operational() {
continue;
}
match handle.transport_type().name {
"udp" => {
let Some(cfg) = self.lookup_udp_config(handle.name()) else {
continue;
};
if !cfg.advertise_on_nostr() {
continue;
}
if cfg.is_public() {
if let Some(addr) = handle.local_addr()
&& !addr.ip().is_unspecified()
{
endpoints.push(OverlayEndpointAdvert {
transport: OverlayTransportKind::Udp,
addr: addr.to_string(),
});
}
} else {
endpoints.push(OverlayEndpointAdvert {
transport: OverlayTransportKind::Udp,
addr: "nat".to_string(),
});
has_udp_nat = true;
}
}
"tcp" => {
let Some(cfg) = self.lookup_tcp_config(handle.name()) else {
continue;
};
if !cfg.advertise_on_nostr() {
continue;
}
if let Some(addr) = handle.local_addr()
&& !addr.ip().is_unspecified()
{
endpoints.push(OverlayEndpointAdvert {
transport: OverlayTransportKind::Tcp,
addr: addr.to_string(),
});
}
}
"tor" => {
let Some(cfg) = self.lookup_tor_config(handle.name()) else {
continue;
};
if !cfg.advertise_on_nostr() {
continue;
}
if let Some(addr) = handle.onion_address() {
endpoints.push(OverlayEndpointAdvert {
transport: OverlayTransportKind::Tor,
addr: addr.to_string(),
});
}
}
_ => {}
}
}
if endpoints.is_empty() {
return None;
}
Some(OverlayAdvert {
identifier: ADVERT_IDENTIFIER.to_string(),
version: ADVERT_VERSION,
endpoints,
signal_relays: has_udp_nat.then(|| self.config.node.discovery.nostr.dm_relays.clone()),
stun_servers: has_udp_nat
.then(|| self.config.node.discovery.nostr.stun_servers.clone()),
})
}
#[cfg(feature = "nostr-discovery")]
async fn refresh_overlay_advert(
&self,
bootstrap: &std::sync::Arc<NostrDiscovery>,
) -> Result<(), crate::discovery::nostr::BootstrapError> {
let advert = self.build_overlay_advert();
bootstrap.update_local_advert(advert).await
}
#[cfg(feature = "nostr-discovery")]
fn lookup_udp_config(&self, transport_name: Option<&str>) -> Option<&crate::config::UdpConfig> {
match (&self.config.transports.udp, transport_name) {
(crate::config::TransportInstances::Single(cfg), None) => Some(cfg),
(crate::config::TransportInstances::Named(configs), Some(name)) => configs.get(name),
_ => None,
}
}
#[cfg(feature = "nostr-discovery")]
fn lookup_tcp_config(&self, transport_name: Option<&str>) -> Option<&crate::config::TcpConfig> {
match (&self.config.transports.tcp, transport_name) {
(crate::config::TransportInstances::Single(cfg), None) => Some(cfg),
(crate::config::TransportInstances::Named(configs), Some(name)) => configs.get(name),
_ => None,
}
}
#[cfg(feature = "nostr-discovery")]
fn lookup_tor_config(&self, transport_name: Option<&str>) -> Option<&crate::config::TorConfig> {
match (&self.config.transports.tor, transport_name) {
(crate::config::TransportInstances::Single(cfg), None) => Some(cfg),
(crate::config::TransportInstances::Named(configs), Some(name)) => configs.get(name),
_ => None,
}
}
pub(in crate::node) async fn try_peer_addresses(
&mut self,
peer_config: &PeerConfig,
peer_identity: PeerIdentity,
allow_bootstrap_nat: bool,
) -> Result<(), NodeError> {
// Static-first dialing: avoid delaying configured address attempts on
// advert fetch/network latency.
let static_addresses = self.static_peer_addresses(peer_config);
if self
.attempt_peer_address_list(
peer_config,
peer_identity,
allow_bootstrap_nat,
&static_addresses,
)
.await
.is_ok()
{
return Ok(());
}
#[cfg(feature = "nostr-discovery")]
{
let fallback = self
.nostr_peer_fallback_addresses(peer_config, &static_addresses)
.await;
if !fallback.is_empty()
&& self
.attempt_peer_address_list(
peer_config,
peer_identity,
allow_bootstrap_nat,
&fallback,
)
.await
.is_ok()
{
return Ok(());
}
}
Err(NodeError::NoTransportForType(format!(
"no operational transport for any of {}'s addresses",
peer_config.npub
)))
}
// === Control API methods ===
/// Connect to a peer via the control API.
@@ -1018,12 +1525,13 @@ impl Node {
address: &str,
transport: &str,
) -> Result<serde_json::Value, String> {
let peer_config = crate::config::PeerConfig {
let peer_config = PeerConfig {
npub: npub.to_string(),
alias: None,
addresses: vec![crate::config::PeerAddress::new(transport, address)],
connect_policy: crate::config::ConnectPolicy::Manual,
addresses: vec![PeerAddress::new(transport, address)],
connect_policy: ConnectPolicy::Manual,
auto_reconnect: false,
via_nostr: false,
};
// Pre-seed identity cache (same as initiate_peer_connections does)
@@ -1076,4 +1584,91 @@ impl Node {
"disconnected": true,
}))
}
/// Adopt an already-established UDP traversal and start the normal FIPS
/// Noise handshake over it.
///
/// This is intended for integration with an external rendezvous runtime
/// that has already completed relay signaling, STUN observation, and UDP
/// hole punching. After handoff, the adopted socket is owned by FIPS.
pub async fn adopt_established_traversal(
&mut self,
traversal: EstablishedTraversal,
) -> Result<BootstrapHandoffResult, NodeError> {
debug!(
peer_npub = %traversal.peer_npub,
session_id = %traversal.session_id,
remote_addr = %traversal.remote_addr,
"adopting established traversal socket"
);
if !self.state.is_operational() {
return Err(NodeError::NotStarted);
}
let packet_tx = self.packet_tx.clone().ok_or(NodeError::NotStarted)?;
let peer_identity = PeerIdentity::from_npub(&traversal.peer_npub).map_err(|e| {
NodeError::InvalidPeerNpub {
npub: traversal.peer_npub.clone(),
reason: e.to_string(),
}
})?;
let peer_node_addr = *peer_identity.node_addr();
self.peer_aliases
.insert(peer_node_addr, peer_identity.short_npub());
self.register_identity(peer_node_addr, peer_identity.pubkey_full());
let transport_id = self.allocate_transport_id();
let mut transport = crate::transport::udp::UdpTransport::new(
transport_id,
traversal.transport_name.clone(),
traversal.transport_config.clone().unwrap_or_default(),
packet_tx,
);
transport
.adopt_socket_async(traversal.socket)
.await
.map_err(|e| NodeError::BootstrapHandoff(e.to_string()))?;
let local_addr = transport.local_addr().ok_or_else(|| {
NodeError::BootstrapHandoff("adopted UDP transport has no local address".into())
})?;
self.transports.insert(
transport_id,
crate::transport::TransportHandle::Udp(transport),
);
self.bootstrap_transports.insert(transport_id);
let remote_addr = TransportAddr::from_string(&traversal.remote_addr.to_string());
if let Err(err) = self
.initiate_connection(transport_id, remote_addr.clone(), Some(peer_identity))
.await
{
self.bootstrap_transports.remove(&transport_id);
if let Some(mut handle) = self.transports.remove(&transport_id) {
let _ = handle.stop().await;
}
return Err(err);
}
info!(
peer = %self.peer_display_name(&peer_node_addr),
transport_id = %transport_id,
local_addr = %local_addr,
remote_addr = %traversal.remote_addr,
session_id = %traversal.session_id,
"adopted NAT traversal socket; handshake initiated"
);
Ok(BootstrapHandoffResult {
transport_id,
local_addr,
remote_addr: traversal.remote_addr,
peer_node_addr,
session_id: traversal.session_id,
})
}
}
src/node/mod.rs
+66 -13
View File
@@ -47,7 +47,7 @@ use crate::upper::tun::{TunError, TunOutboundRx, TunState, TunTx};
use crate::utils::index::IndexAllocator;
use crate::{Config, ConfigError, Identity, IdentityError, NodeAddr, PeerIdentity};
use rand::Rng;
use std::collections::{HashMap, VecDeque};
use std::collections::{HashMap, HashSet, VecDeque};
use std::fmt;
use std::sync::Arc;
use std::thread::JoinHandle;
@@ -137,6 +137,9 @@ pub enum NodeError {
#[error("transport error: {0}")]
TransportError(String),
#[error("bootstrap handoff failed: {0}")]
BootstrapHandoff(String),
}
/// Node operational state.
@@ -262,7 +265,7 @@ struct PendingConnect {
///
/// The `addr_to_link` map enables dispatching incoming packets to the right
/// connection before authentication completes.
// Discovery lookup constants moved to config: node.discovery.timeout_secs, node.discovery.ttl
// Discovery lookup constants moved to config: node.discovery.attempt_timeouts_secs, node.discovery.ttl
pub struct Node {
// === Identity ===
/// This node's cryptographic identity.
@@ -344,7 +347,6 @@ pub struct Node {
/// Packets queued while waiting for session establishment.
/// Keyed by destination NodeAddr, bounded per-dest and total.
pending_tun_packets: HashMap<NodeAddr, VecDeque<Vec<u8>>>,
// === Pending Discovery Lookups ===
/// Tracks in-flight discovery lookups. Maps target NodeAddr to the
/// initiation timestamp (Unix ms). Prevents duplicate flood queries.
@@ -437,6 +439,12 @@ pub struct Node {
/// are exhausted.
retry_pending: HashMap<NodeAddr, retry::RetryState>,
/// Optional Nostr/STUN overlay discovery coordinator for `udp:nat` peers.
#[cfg(feature = "nostr-discovery")]
nostr_discovery: Option<Arc<crate::discovery::nostr::NostrDiscovery>>,
/// Per-peer UDP transports adopted from NAT traversal handoff.
bootstrap_transports: HashSet<TransportId>,
// === Periodic Parent Re-evaluation ===
/// Timestamp of last periodic parent re-evaluation (for pacing).
last_parent_reeval: Option<std::time::Instant>,
@@ -475,6 +483,7 @@ pub struct Node {
impl Node {
/// Create a new node from configuration.
pub fn new(config: Config) -> Result<Self, NodeError> {
config.validate()?;
let identity = config.create_identity()?;
let node_addr = *identity.node_addr();
let is_leaf_only = config.is_leaf_only();
@@ -599,6 +608,9 @@ impl Node {
),
pending_connects: Vec::new(),
retry_pending: HashMap::new(),
#[cfg(feature = "nostr-discovery")]
nostr_discovery: None,
bootstrap_transports: HashSet::new(),
last_parent_reeval: None,
last_congestion_log: None,
estimated_mesh_size: None,
@@ -611,7 +623,11 @@ impl Node {
}
/// Create a node with a specific identity.
pub fn with_identity(identity: Identity, config: Config) -> Self {
///
/// This constructor validates cross-field config invariants before
/// constructing the node, same as [`Node::new`].
pub fn with_identity(identity: Identity, config: Config) -> Result<Self, NodeError> {
config.validate()?;
let node_addr = *identity.node_addr();
let mut startup_epoch = [0u8; 8];
@@ -667,7 +683,7 @@ impl Node {
std::path::PathBuf::from(crate::upper::hosts::DEFAULT_HOSTS_PATH),
);
Self {
Ok(Self {
identity,
startup_epoch,
started_at: std::time::Instant::now(),
@@ -722,6 +738,9 @@ impl Node {
discovery_forward_limiter: DiscoveryForwardRateLimiter::new(),
pending_connects: Vec::new(),
retry_pending: HashMap::new(),
#[cfg(feature = "nostr-discovery")]
nostr_discovery: None,
bootstrap_transports: HashSet::new(),
last_parent_reeval: None,
last_congestion_log: None,
estimated_mesh_size: None,
@@ -730,7 +749,7 @@ impl Node {
peer_aliases: HashMap::new(),
peer_acl,
host_map,
}
})
}
/// Create a leaf-only node (simplified state).
@@ -813,7 +832,7 @@ impl Node {
}
// Create BLE transport instances
#[cfg(target_os = "linux")]
#[cfg(bluer_available)]
{
let ble_instances: Vec<_> = self
.config
@@ -823,7 +842,7 @@ impl Node {
.map(|(name, config)| (name.map(|s| s.to_string()), config.clone()))
.collect();
#[cfg(all(feature = "ble", not(test)))]
#[cfg(all(bluer_available, not(test)))]
for (name, ble_config) in ble_instances {
let transport_id = self.allocate_transport_id();
let adapter = ble_config.adapter().to_string();
@@ -845,12 +864,10 @@ impl Node {
}
}
#[cfg(any(not(feature = "ble"), test))]
#[cfg(any(not(bluer_available), test))]
if !ble_instances.is_empty() {
#[cfg(not(test))]
tracing::warn!(
"BLE transport configured but 'ble' feature not enabled at compile time"
);
tracing::warn!("BLE transport configured but this build lacks BlueZ support");
}
}
@@ -920,7 +937,7 @@ impl Node {
/// Resolve a BLE address string (`"adapter/AA:BB:CC:DD:EE:FF"`) to a
/// (TransportId, TransportAddr) pair by finding the BLE transport
/// instance matching the adapter name.
#[cfg(target_os = "linux")]
#[cfg(bluer_available)]
fn resolve_ble_addr(&self, addr_str: &str) -> Result<(TransportId, TransportAddr), NodeError> {
let ta = TransportAddr::from_string(addr_str);
let adapter = crate::transport::ble::addr::adapter_from_addr(&ta).ok_or_else(|| {
@@ -1416,6 +1433,42 @@ impl Node {
}
}
pub(crate) fn cleanup_bootstrap_transport_if_unused(&mut self, transport_id: TransportId) {
if !self.bootstrap_transports.contains(&transport_id) {
return;
}
let transport_in_use = self
.links
.values()
.any(|link| link.transport_id() == transport_id)
|| self
.connections
.values()
.any(|conn| conn.transport_id() == Some(transport_id))
|| self
.peers
.values()
.any(|peer| peer.transport_id() == Some(transport_id))
|| self
.pending_connects
.iter()
.any(|pending| pending.transport_id == transport_id);
if transport_in_use {
return;
}
tracing::debug!(
transport_id = %transport_id,
"bootstrap transport has no remaining references; dropping"
);
self.bootstrap_transports.remove(&transport_id);
self.transport_drops.remove(&transport_id);
self.transports.remove(&transport_id);
}
/// Iterate over all links.
pub fn links(&self) -> impl Iterator<Item = &Link> {
self.links.values()
src/node/retry.rs
+31
View File
@@ -25,6 +25,12 @@ pub struct RetryState {
/// Whether this is an auto-reconnect (unlimited retries, ignores max_retries).
pub reconnect: bool,
/// Optional absolute expiry for this retry entry (Unix ms).
///
/// When set, retries are dropped after this point even if reconnect logic
/// would otherwise continue.
pub expires_at_ms: Option<u64>,
}
impl RetryState {
@@ -35,6 +41,7 @@ impl RetryState {
retry_count: 0,
retry_after_ms: 0,
reconnect: false,
expires_at_ms: None,
}
}
@@ -203,6 +210,27 @@ impl Node {
return;
}
let expired: Vec<NodeAddr> = self
.retry_pending
.iter()
.filter_map(|(addr, state)| {
state
.expires_at_ms
.filter(|expires_at_ms| now_ms >= *expires_at_ms)
.map(|_| *addr)
})
.collect();
for node_addr in expired {
self.retry_pending.remove(&node_addr);
info!(
peer = %self.peer_display_name(&node_addr),
"Retry window expired, dropping pending retry state"
);
}
if self.retry_pending.is_empty() {
return;
}
// Collect retries that are due
let due: Vec<NodeAddr> = self
.retry_pending
@@ -277,6 +305,7 @@ mod tests {
retry_count: 0,
retry_after_ms: 0,
reconnect: false,
expires_at_ms: None,
};
// base = 5000ms
assert_eq!(state.backoff_ms(5000, TEST_MAX_BACKOFF_MS), 5000); // 5s * 2^0
@@ -313,6 +342,7 @@ mod tests {
retry_count: 20, // 2^20 * 5000 would be huge
retry_after_ms: 0,
reconnect: false,
expires_at_ms: None,
};
assert_eq!(
state.backoff_ms(5000, TEST_MAX_BACKOFF_MS),
@@ -327,6 +357,7 @@ mod tests {
retry_count: 3,
retry_after_ms: 0,
reconnect: false,
expires_at_ms: None,
};
assert_eq!(state.backoff_ms(0, TEST_MAX_BACKOFF_MS), 0);
}
src/node/tests/bootstrap.rs
+247
View File
@@ -0,0 +1,247 @@
//! Integration tests for bootstrap handoff into the FIPS node.
use super::*;
use crate::EstablishedTraversal;
use crate::config::UdpConfig;
use crate::node::wire::{PHASE_MSG1, PHASE_MSG2};
use crate::transport::udp::UdpTransport;
use crate::utils::index::IndexAllocator;
use tokio::time::{Duration, timeout, timeout_at};
#[ignore = "needs XX-handshake adaptation: peer promotion now happens at msg3, not msg1; test runs only two rx_loop iterations"]
#[tokio::test]
async fn test_adopted_udp_traversal_completes_handshake() {
let mut node_a = make_node();
let mut node_b = make_node();
let transport_id_b = TransportId::new(1);
let udp_config = UdpConfig {
bind_addr: Some("127.0.0.1:0".to_string()),
mtu: Some(1280),
..Default::default()
};
let (packet_tx_a, packet_rx_a) = packet_channel(64);
let (packet_tx_b, packet_rx_b) = packet_channel(64);
node_a.packet_tx = Some(packet_tx_a.clone());
node_a.packet_rx = Some(packet_rx_a);
node_a.state = NodeState::Running;
let mut transport_b = UdpTransport::new(transport_id_b, None, udp_config, packet_tx_b.clone());
transport_b.start_async().await.unwrap();
let addr_b = transport_b.local_addr().unwrap();
node_b.packet_tx = Some(packet_tx_b.clone());
node_b.packet_rx = Some(packet_rx_b);
node_b.state = NodeState::Running;
node_b
.transports
.insert(transport_id_b, TransportHandle::Udp(transport_b));
let adopted_socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
let handoff = EstablishedTraversal::new("sess-1", node_b.npub(), addr_b, adopted_socket)
.with_transport_name("nostr-punched");
let result = node_a.adopt_established_traversal(handoff).await.unwrap();
assert_eq!(result.remote_addr, addr_b);
assert!(node_a.get_transport(&result.transport_id).is_some());
tokio::select! {
result = node_b.run_rx_loop() => {
panic!("node_b rx loop exited unexpectedly: {:?}", result);
}
_ = tokio::time::sleep(Duration::from_millis(500)) => {}
}
tokio::select! {
result = node_a.run_rx_loop() => {
panic!("node_a rx loop exited unexpectedly: {:?}", result);
}
_ = tokio::time::sleep(Duration::from_millis(500)) => {}
}
let peer_a_node_addr =
*PeerIdentity::from_pubkey_full(node_a.identity.pubkey_full()).node_addr();
let peer_b_node_addr =
*PeerIdentity::from_pubkey_full(node_b.identity.pubkey_full()).node_addr();
assert_eq!(
node_a.peer_count(),
1,
"node_a should promote node_b after handoff"
);
assert_eq!(
node_b.peer_count(),
1,
"node_b should promote node_a after receiving msg1"
);
assert!(node_a.get_peer(&peer_b_node_addr).unwrap().has_session());
assert!(node_b.get_peer(&peer_a_node_addr).unwrap().has_session());
for (_, transport) in node_a.transports.iter_mut() {
transport.stop().await.ok();
}
for (_, transport) in node_b.transports.iter_mut() {
transport.stop().await.ok();
}
}
#[tokio::test]
async fn test_failed_adopted_traversal_cleans_up_transport() {
let mut node = make_node();
let (packet_tx, packet_rx) = packet_channel(64);
node.packet_tx = Some(packet_tx);
node.packet_rx = Some(packet_rx);
node.state = NodeState::Running;
node.index_allocator = IndexAllocator::with_max_attempts(0);
let peer = make_node();
let adopted_socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
let handoff = EstablishedTraversal::new(
"sess-fail",
peer.npub(),
"127.0.0.1:9".parse().unwrap(),
adopted_socket,
)
.with_transport_name("nostr-punched");
let result = node.adopt_established_traversal(handoff).await;
assert!(
result.is_err(),
"handoff should fail when handshake setup cannot allocate a session index"
);
assert!(
node.transports.is_empty(),
"failed handoff should remove the adopted transport"
);
}
#[ignore = "needs XX-handshake adaptation: peer promotion now happens at msg3, not msg1; test runs only two rx_loop iterations"]
#[tokio::test]
async fn test_third_peer_can_handshake_via_adopted_transport_socket() {
let mut node_a = make_node(); // Existing traversal peer (Alice)
let mut node_b = make_node(); // Node with adopted socket (Bob)
let mut node_c = make_node(); // New peer onboarding via Bob socket (Colin)
let transport_id_a = TransportId::new(1);
let transport_id_c = TransportId::new(1);
let udp_config = UdpConfig {
bind_addr: Some("127.0.0.1:0".to_string()),
mtu: Some(1280),
..Default::default()
};
let (packet_tx_a, packet_rx_a) = packet_channel(64);
let (packet_tx_b, packet_rx_b) = packet_channel(64);
let (packet_tx_c, packet_rx_c) = packet_channel(64);
node_a.packet_tx = Some(packet_tx_a.clone());
node_a.packet_rx = Some(packet_rx_a);
node_a.state = NodeState::Running;
node_b.packet_tx = Some(packet_tx_b.clone());
node_b.packet_rx = Some(packet_rx_b);
node_b.state = NodeState::Running;
node_c.packet_tx = Some(packet_tx_c.clone());
node_c.packet_rx = Some(packet_rx_c);
node_c.state = NodeState::Running;
let mut transport_a = UdpTransport::new(transport_id_a, None, udp_config.clone(), packet_tx_a);
transport_a.start_async().await.unwrap();
let addr_a = transport_a.local_addr().unwrap();
node_a
.transports
.insert(transport_id_a, TransportHandle::Udp(transport_a));
// Bob adopts a traversal socket already "established" to Alice.
let adopted_socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
let handoff = EstablishedTraversal::new("sess-existing", node_a.npub(), addr_a, adopted_socket)
.with_transport_name("nostr-nat");
let handoff_result = node_b.adopt_established_traversal(handoff).await.unwrap();
// Drive Alice/Bob handshake manually (msg1 -> msg2).
let mut rx_a = node_a.packet_rx.take().expect("node_a packet_rx");
let mut rx_b = node_b.packet_rx.take().expect("node_b packet_rx");
let pkt_at_a = timeout(Duration::from_secs(1), rx_a.recv())
.await
.expect("timeout waiting for Bob->Alice msg1")
.expect("node_a channel closed");
assert_eq!(pkt_at_a.data[0] & 0x0f, PHASE_MSG1);
node_a.handle_msg1(pkt_at_a).await;
let pkt_at_b = timeout(Duration::from_secs(1), rx_b.recv())
.await
.expect("timeout waiting for Alice->Bob msg2")
.expect("node_b channel closed");
assert_eq!(pkt_at_b.data[0] & 0x0f, PHASE_MSG2);
node_b.handle_msg2(pkt_at_b).await;
let node_a_addr = *PeerIdentity::from_pubkey_full(node_a.identity.pubkey_full()).node_addr();
assert!(
node_b.get_peer(&node_a_addr).is_some(),
"node_b should first be connected to node_a via adopted transport"
);
// Start Colin UDP transport and connect to Bob's adopted socket address.
let mut transport_c = UdpTransport::new(transport_id_c, None, udp_config, packet_tx_c);
transport_c.start_async().await.unwrap();
let addr_c = transport_c.local_addr().unwrap();
node_c
.transports
.insert(transport_id_c, TransportHandle::Udp(transport_c));
let peer_b_identity = PeerIdentity::from_pubkey_full(node_b.identity.pubkey_full());
let adopted_addr = TransportAddr::from_string(&handoff_result.local_addr.to_string());
node_c
.initiate_connection(transport_id_c, adopted_addr, Some(peer_b_identity))
.await
.unwrap();
// Drive Bob/Colin handshake manually (msg1 -> msg2).
let mut rx_c = node_c.packet_rx.take().expect("node_c packet_rx");
let deadline = tokio::time::Instant::now() + Duration::from_secs(1);
let pkt_at_b = loop {
let pkt = timeout_at(deadline, rx_b.recv())
.await
.expect("timeout waiting for Colin->Bob msg1")
.expect("node_b channel closed");
if pkt.remote_addr.as_str() == Some(&addr_c.to_string())
&& pkt.data.first().map(|b| b & 0x0f) == Some(PHASE_MSG1)
{
break pkt;
}
};
node_b.handle_msg1(pkt_at_b).await;
let deadline = tokio::time::Instant::now() + Duration::from_secs(1);
let pkt_at_c = loop {
let pkt = timeout_at(deadline, rx_c.recv())
.await
.expect("timeout waiting for Bob->Colin msg2")
.expect("node_c channel closed");
if pkt.data.first().map(|b| b & 0x0f) == Some(PHASE_MSG2) {
break pkt;
}
};
node_c.handle_msg2(pkt_at_c).await;
let node_c_addr = *PeerIdentity::from_pubkey_full(node_c.identity.pubkey_full()).node_addr();
assert!(
node_b.get_peer(&node_c_addr).is_some(),
"node_b should promote node_c when node_c handshakes via adopted socket"
);
for (_, transport) in node_a.transports.iter_mut() {
transport.stop().await.ok();
}
for (_, transport) in node_b.transports.iter_mut() {
transport.stop().await.ok();
}
for (_, transport) in node_c.transports.iter_mut() {
transport.stop().await.ok();
}
}
src/node/tests/mod.rs
+2 -1
View File
@@ -9,9 +9,10 @@ mod acl;
mod ble;
mod bloom;
mod bloom_poison;
mod bootstrap;
mod disconnect;
mod discovery;
#[cfg(unix)]
#[cfg(target_os = "linux")]
mod ethernet;
mod forwarding;
mod handshake;
src/node/tests/unit.rs
+89 -1
View File
@@ -1,5 +1,7 @@
use super::*;
use crate::peer::PromotionResult;
use crate::transport::udp::UdpTransport;
use crate::transport::{TransportHandle, packet_channel};
#[test]
fn test_node_creation() {
@@ -18,11 +20,26 @@ fn test_node_with_identity() {
let expected_node_addr = *identity.node_addr();
let config = Config::new();
let node = Node::with_identity(identity, config);
let node = Node::with_identity(identity, config).unwrap();
assert_eq!(node.node_addr(), &expected_node_addr);
}
#[test]
fn test_node_with_identity_validates_config() {
let identity = Identity::generate();
let mut config = Config::new();
config.node.discovery.nostr.enabled = false;
config.peers = vec![crate::config::PeerConfig {
npub: "npub1peer".to_string(),
via_nostr: true,
..Default::default()
}];
let err = Node::with_identity(identity, config).expect_err("expected config validation error");
assert!(matches!(err, NodeError::Config(_)));
}
#[test]
fn test_node_leaf_only() {
let config = Config::new();
@@ -32,6 +49,52 @@ fn test_node_leaf_only() {
assert!(node.bloom_state().is_leaf_only());
}
#[tokio::test]
async fn test_nat_bootstrap_failure_falls_back_to_direct_udp_address() {
let peer_identity = Identity::generate();
let mut node = make_node();
let (packet_tx, packet_rx) = packet_channel(64);
node.packet_tx = Some(packet_tx.clone());
node.packet_rx = Some(packet_rx);
let transport_id = TransportId::new(1);
let mut udp = UdpTransport::new(
transport_id,
Some("main".to_string()),
crate::config::UdpConfig {
bind_addr: Some("127.0.0.1:0".to_string()),
..Default::default()
},
packet_tx,
);
udp.start_async().await.unwrap();
node.transports
.insert(transport_id, TransportHandle::Udp(udp));
let peer_config = crate::config::PeerConfig {
npub: peer_identity.npub(),
alias: None,
addresses: vec![
crate::config::PeerAddress::with_priority("udp", "nat", 1),
crate::config::PeerAddress::with_priority("udp", "127.0.0.1:9", 2),
],
connect_policy: crate::config::ConnectPolicy::AutoConnect,
auto_reconnect: true,
via_nostr: false,
};
let peer_identity = PeerIdentity::from_npub(&peer_config.npub).unwrap();
node.try_peer_addresses(&peer_config, peer_identity, false)
.await
.unwrap();
assert_eq!(node.connection_count(), 1);
for transport in node.transports.values_mut() {
transport.stop().await.ok();
}
}
#[tokio::test]
async fn test_node_state_transitions() {
let mut node = make_node();
@@ -719,6 +782,31 @@ fn test_schedule_retry_skips_connected_peer() {
);
}
#[tokio::test]
async fn test_process_pending_retries_drops_expired_entries() {
let mut node = make_node();
let peer_identity = Identity::generate();
let peer_npub = peer_identity.npub();
let peer_node_addr = *PeerIdentity::from_npub(&peer_npub).unwrap().node_addr();
let mut state = super::super::retry::RetryState::new(crate::config::PeerConfig::new(
peer_npub,
"udp",
"127.0.0.1:9",
));
state.retry_after_ms = 0;
state.expires_at_ms = Some(1_000);
state.reconnect = true;
node.retry_pending.insert(peer_node_addr, state);
node.process_pending_retries(1_000).await;
assert!(
!node.retry_pending.contains_key(&peer_node_addr),
"expired retry entries should be dropped before retry processing"
);
}
/// Test that schedule_reconnect preserves accumulated backoff across link-dead cycles.
///
/// Regression test for issue #5: previously `schedule_reconnect` always created a
src/transport/ble/addr.rs
+2 -2
View File
@@ -55,10 +55,10 @@ impl BleAddr {
}
// ============================================================================
// bluer type conversions (behind ble feature)
// bluer type conversions (glibc-linux only; see build.rs bluer_available)
// ============================================================================
#[cfg(feature = "ble")]
#[cfg(bluer_available)]
impl BleAddr {
/// Construct from a bluer `Address` and adapter name.
pub fn from_bluer(addr: bluer::Address, adapter: &str) -> Self {
src/transport/ble/io.rs
+3 -3
View File
@@ -1,7 +1,7 @@
//! BLE I/O abstraction layer.
//!
//! Defines the `BleIo` trait that separates transport logic from the
//! BlueZ/bluer stack. `BluerIo` (behind `cfg(feature = "ble")`) provides
//! BlueZ/bluer stack. `BluerIo` (behind `cfg(bluer_available)`) provides
//! the real implementation; `MockBleIo` provides an in-memory test double.
use crate::transport::TransportError;
@@ -109,7 +109,7 @@ pub trait BleIo: Send + Sync + 'static {
// BluerIo — Production BLE I/O via BlueZ D-Bus
// ============================================================================
#[cfg(feature = "ble")]
#[cfg(bluer_available)]
mod bluer_impl {
use super::*;
use crate::transport::TransportError;
@@ -486,7 +486,7 @@ mod bluer_impl {
}
}
#[cfg(feature = "ble")]
#[cfg(bluer_available)]
pub use bluer_impl::{BluerAcceptor, BluerIo, BluerScanner, BluerStream, FIPS_SERVICE_UUID};
// ============================================================================
src/transport/ble/mod.rs
+5 -5
View File
@@ -9,7 +9,7 @@
//!
//! Transport logic (pool, discovery, lifecycle) is separated from the
//! BlueZ/bluer stack via the `BleIo` trait. `BluerIo` provides the real
//! implementation (behind `cfg(feature = "ble")`); `MockBleIo` provides
//! implementation (behind `cfg(bluer_available)`); `MockBleIo` provides
//! an in-memory test double for CI without hardware.
//!
//! ## Connection Pool
@@ -48,12 +48,12 @@ pub const DEFAULT_PSM: u16 = 0x0085;
/// Concrete BLE transport type for use in TransportHandle.
///
/// Production builds with the `ble` feature use `BluerIo` (real BlueZ stack).
/// Test builds and builds without `ble` use `MockBleIo`.
#[cfg(all(feature = "ble", not(test)))]
/// Production builds on glibc-linux use `BluerIo` (real BlueZ stack).
/// Test builds, musl-linux, and non-Linux platforms use `MockBleIo`.
#[cfg(all(bluer_available, not(test)))]
pub type DefaultBleTransport = BleTransport<io::BluerIo>;
#[cfg(any(not(feature = "ble"), test))]
#[cfg(any(not(bluer_available), test))]
pub type DefaultBleTransport = BleTransport<io::MockBleIo>;
// ============================================================================
src/transport/udp/mod.rs
+82
View File
@@ -198,6 +198,65 @@ impl UdpTransport {
Ok(())
}
/// Start the transport using an already-bound UDP socket.
///
/// This preserves an existing NAT mapping established by another
/// subsystem, such as STUN or UDP hole punching.
pub async fn adopt_socket_async(
&mut self,
socket: std::net::UdpSocket,
) -> Result<(), TransportError> {
if !self.state.can_start() {
return Err(TransportError::AlreadyStarted);
}
self.state = TransportState::Starting;
let raw_socket = UdpRawSocket::adopt(
socket,
self.config.recv_buf_size(),
self.config.send_buf_size(),
)?;
let actual_recv = raw_socket.recv_buffer_size()?;
let actual_send = raw_socket.send_buffer_size()?;
self.local_addr = Some(raw_socket.local_addr());
let async_socket = raw_socket.into_async()?;
self.socket = Some(async_socket.clone());
let transport_id = self.transport_id;
let packet_tx = self.packet_tx.clone();
let mtu = self.config.mtu();
let stats = self.stats.clone();
let recv_task = tokio::spawn(async move {
udp_receive_loop(async_socket, transport_id, packet_tx, mtu, stats).await;
});
self.recv_task = Some(recv_task);
self.state = TransportState::Up;
if let Some(ref name) = self.name {
info!(
name = %name,
local_addr = %self.local_addr.unwrap(),
recv_buf = actual_recv,
send_buf = actual_send,
"UDP transport adopted existing socket"
);
} else {
info!(
local_addr = %self.local_addr.unwrap(),
recv_buf = actual_recv,
send_buf = actual_send,
"UDP transport adopted existing socket"
);
}
Ok(())
}
/// Stop the transport asynchronously.
pub async fn stop_async(&mut self) -> Result<(), TransportError> {
if !self.state.is_operational() {
@@ -309,6 +368,27 @@ impl Transport for UdpTransport {
}
}
impl Drop for UdpTransport {
fn drop(&mut self) {
let had_task = self.recv_task.is_some();
let had_socket = self.socket.is_some();
if had_task || had_socket {
debug!(
transport_id = %self.transport_id,
state = ?self.state,
had_recv_task = had_task,
had_socket = had_socket,
"UdpTransport dropped without stop_async(); cleaning up",
);
}
if let Some(task) = self.recv_task.take() {
task.abort();
}
self.socket.take();
self.local_addr = None;
}
}
/// UDP receive loop - runs as a spawned task.
async fn udp_receive_loop(
socket: AsyncUdpSocket,
@@ -379,6 +459,8 @@ mod tests {
mtu: Some(1280),
recv_buf_size: None,
send_buf_size: None,
advertise_on_nostr: None,
public: None,
}
}
src/transport/udp/socket.rs
+106
View File
@@ -125,6 +125,81 @@ mod platform {
})
}
/// Adopt an existing bound UDP socket.
///
/// This preserves socket identity/NAT mapping created by bootstrap code.
pub fn adopt(
socket: std::net::UdpSocket,
recv_buf_size: usize,
send_buf_size: usize,
) -> Result<Self, TransportError> {
let sock = Socket::from(socket);
sock.set_nonblocking(true).map_err(|e| {
TransportError::StartFailed(format!("set nonblocking failed: {}", e))
})?;
sock.set_recv_buffer_size(recv_buf_size)
.map_err(|e| TransportError::StartFailed(format!("set recv buffer: {}", e)))?;
sock.set_send_buffer_size(send_buf_size)
.map_err(|e| TransportError::StartFailed(format!("set send buffer: {}", e)))?;
let actual_recv = sock
.recv_buffer_size()
.map_err(|e| TransportError::StartFailed(format!("get recv buffer: {}", e)))?;
let actual_send = sock
.send_buffer_size()
.map_err(|e| TransportError::StartFailed(format!("get send buffer: {}", e)))?;
if actual_recv < recv_buf_size {
warn!(
requested = recv_buf_size,
actual = actual_recv,
"UDP recv buffer clamped by kernel (increase net.core.rmem_max)"
);
}
if actual_send < send_buf_size {
warn!(
requested = send_buf_size,
actual = actual_send,
"UDP send buffer clamped by kernel (increase net.core.wmem_max)"
);
}
#[cfg(target_os = "linux")]
{
let enable: libc::c_int = 1;
let ret = unsafe {
libc::setsockopt(
sock.as_raw_fd(),
libc::SOL_SOCKET,
libc::SO_RXQ_OVFL,
&enable as *const _ as *const libc::c_void,
std::mem::size_of::<libc::c_int>() as libc::socklen_t,
)
};
if ret < 0 {
warn!(
"setsockopt(SO_RXQ_OVFL) failed: {}",
std::io::Error::last_os_error()
);
}
}
let local_addr = sock
.local_addr()
.map_err(|e| TransportError::StartFailed(format!("get local addr: {}", e)))?
.as_socket()
.ok_or_else(|| {
TransportError::StartFailed("local address is not an IP socket".into())
})?;
Ok(Self {
inner: sock,
local_addr,
})
}
/// Get the local bound address.
pub fn local_addr(&self) -> SocketAddr {
self.local_addr
@@ -371,6 +446,37 @@ mod platform {
})
}
/// Adopt an existing bound UDP socket.
pub fn adopt(
socket: std::net::UdpSocket,
recv_buf_size: usize,
send_buf_size: usize,
) -> Result<Self, TransportError> {
let sock = Socket::from(socket);
sock.set_nonblocking(true).map_err(|e| {
TransportError::StartFailed(format!("set nonblocking failed: {}", e))
})?;
sock.set_recv_buffer_size(recv_buf_size)
.map_err(|e| TransportError::StartFailed(format!("set recv buffer: {}", e)))?;
sock.set_send_buffer_size(send_buf_size)
.map_err(|e| TransportError::StartFailed(format!("set send buffer: {}", e)))?;
let local_addr = sock
.local_addr()
.map_err(|e| TransportError::StartFailed(format!("get local addr: {}", e)))?
.as_socket()
.ok_or_else(|| {
TransportError::StartFailed("local address is not an IP socket".into())
})?;
Ok(Self {
inner: sock,
local_addr,
})
}
/// Get the local bound address.
pub fn local_addr(&self) -> SocketAddr {
self.local_addr
testing/README.md
+12
View File
@@ -30,6 +30,18 @@ Tor daemons. Requires internet access for Tor bootstrapping.
| socks5-outbound | Outbound SOCKS5 connections through Tor to clearnet peer |
| directory-mode | Inbound via HiddenServiceDir onion service (co-located) |
### [nat/](nat/) -- NAT Traversal Lab
Real Docker NAT traversal tests for the Nostr/STUN bootstrap path,
using router containers with `iptables`-based NAT, a local Nostr relay,
and a local STUN responder.
| Scenario | Description |
| --------- | ------------------------------------------------------------ |
| cone | Two NATed peers establish a UDP traversal path |
| symmetric | UDP traversal fails under symmetric NAT, TCP fallback wins |
| lan | Peers on the same LAN prefer local addresses over reflexive |
### [chaos/](chaos/) -- Stochastic Simulation
Automated network testing with configurable node counts, topology
testing/ci-local.sh
+6 -6
View File
@@ -145,8 +145,8 @@ record() {
run_build() {
stage "Stage 1: Build"
info "cargo build --release --features gateway"
if cargo build --release --features gateway 2>&1; then
info "cargo build --release"
if cargo build --release 2>&1; then
record "build" 0
else
record "build" 1
@@ -161,8 +161,8 @@ run_build() {
return 1
fi
info "cargo clippy --all --features gateway -- -D warnings"
if cargo clippy --all --features gateway -- -D warnings 2>&1; then
info "cargo clippy --all -- -D warnings"
if cargo clippy --all -- -D warnings 2>&1; then
record "clippy" 0
else
record "clippy" 1
@@ -177,7 +177,7 @@ run_tests() {
local cmd
if command -v cargo-nextest &>/dev/null; then
cmd="cargo nextest run --all --features gateway"
cmd="cargo nextest run --all"
info "$cmd"
if $cmd 2>&1; then
record "unit-tests" 0
@@ -185,7 +185,7 @@ run_tests() {
record "unit-tests" 1
fi
else
cmd="cargo test --all --features gateway"
cmd="cargo test --all"
info "$cmd (nextest not found, using cargo test)"
if $cmd 2>&1; then
record "unit-tests" 0
testing/nat/.gitignore
+1
View File
@@ -0,0 +1 @@
generated-configs
testing/nat/README.md
+99
View File
@@ -0,0 +1,99 @@
# NAT Lab Harness
Real Docker-based NAT traversal integration tests for the mainline
FIPS Nostr/STUN bootstrap path.
This harness spins up:
- two FIPS nodes
- a local Nostr relay
- a local STUN server
- one or two Linux router containers performing NAT with `iptables`
For the NAT scenarios, the node LAN interfaces are not attached to
Docker bridge networks. The harness creates explicit `veth` pairs and
moves them into the node and router namespaces after `docker compose up`
so every packet must traverse the router namespace.
It covers three scenarios:
- `cone`: both peers behind explicit namespace/veth full-cone emulation, UDP traversal succeeds
- `symmetric`: both peers behind symmetric-style NAT, UDP traversal fails, TCP fallback succeeds
- `lan`: both peers share a LAN subnet, LAN targets are preferred over reflexive addresses
## NAT model notes
The harness does not rely on plain Docker `MASQUERADE` for the cone case.
- `cone`
- uses explicit full-cone emulation in the router namespace
- outbound UDP is `SNAT`ed to the router WAN address while preserving the source port
- inbound UDP to the router WAN address is `DNAT`ed back to the single LAN host regardless of remote source
- `symmetric`
- uses UDP `MASQUERADE --random-fully`
- outbound mappings may be port-randomized and are only reopened by matching conntrack state
This distinction matters because plain `MASQUERADE` is convenient source NAT, but it does not by itself model the "accept from any remote once mapped" behavior expected from a full-cone NAT.
## Prerequisites
- Docker with Compose support
- locally built `fips-test:latest`
Build the test image with:
```bash
./testing/scripts/build.sh
```
## Run
Run all scenarios:
```bash
./testing/nat/scripts/nat-test.sh
```
Run one scenario:
```bash
./testing/nat/scripts/nat-test.sh cone
./testing/nat/scripts/nat-test.sh symmetric
./testing/nat/scripts/nat-test.sh lan
```
## Layout
- `docker-compose.yml`
- relay/STUN/WAN topology plus container definitions
- `node/`
- node bootstrap wrapper that waits for the injected veth interface
- `router/`
- NAT router image and `iptables` setup
- `stun/`
- minimal STUN binding responder
- `relay/`
- local `strfry` config
- `scripts/generate-configs.sh`
- derives ephemeral identities and writes per-scenario FIPS configs
- `scripts/setup-topology.sh`
- injects and configures the NAT LAN `veth` pairs in the container namespaces
- `scripts/nat-test.sh`
- boots the lab, waits for convergence, and asserts the resulting path
## Assertions
- `cone`
- both nodes connect
- connected transport is UDP
- active link remote addresses are on the WAN NAT subnet
- `symmetric`
- NAT bootstrap does not establish a UDP link
- fallback converges
- connected transport is TCP via router-published WAN addresses
- `lan`
- both nodes connect
- connected transport is UDP
- active link remote addresses stay on the shared LAN subnet
testing/nat/docker-compose.yml
+234
View File
@@ -0,0 +1,234 @@
networks:
wan:
driver: bridge
ipam:
config:
- subnet: 172.31.254.0/24
shared-lan:
driver: bridge
ipam:
config:
- subnet: 172.31.10.0/24
volumes:
relay-data:
x-fips-common: &fips-common
image: fips-test:latest
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
sysctls:
- net.ipv6.conf.all.disable_ipv6=0
restart: "no"
environment:
- RUST_LOG=info,fips::discovery::nostr=debug,fips::node::lifecycle=debug
services:
relay:
build:
context: ../..
dockerfile: examples/sidecar-nostr-relay/Dockerfile.app
container_name: fips-nat-relay
restart: "no"
volumes:
- relay-data:/usr/src/app/strfry-db
- ./relay/strfry.conf:/usr/src/app/strfry.conf:ro
- ../docker/resolv.conf:/etc/resolv.conf:ro
networks:
wan:
ipv4_address: 172.31.254.30
shared-lan:
ipv4_address: 172.31.10.30
stun:
build:
context: ./stun
container_name: fips-nat-stun
restart: "no"
networks:
wan:
ipv4_address: 172.31.254.40
shared-lan:
ipv4_address: 172.31.10.40
nat-a:
build:
context: ./router
profiles: ["cone", "symmetric"]
container_name: fips-nat-router-a
cap_add:
- NET_ADMIN
sysctls:
- net.ipv4.ip_forward=1
restart: "no"
environment:
- NAT_MODE=${NAT_MODE_A:-cone}
- TCP_FORWARD_PORTS=8443
- LAN_IF=eth1
- WAN_IF=eth0
- LAN_HOST=172.31.1.10
- LAN_SUBNET=172.31.1.0/24
- WAN_SUBNET=172.31.254.0/24
- WAN_GATEWAY=172.31.254.1
networks:
wan:
ipv4_address: 172.31.254.10
nat-b:
build:
context: ./router
profiles: ["cone", "symmetric"]
container_name: fips-nat-router-b
cap_add:
- NET_ADMIN
sysctls:
- net.ipv4.ip_forward=1
restart: "no"
environment:
- NAT_MODE=${NAT_MODE_B:-cone}
- TCP_FORWARD_PORTS=8443
- LAN_IF=eth1
- WAN_IF=eth0
- LAN_HOST=172.31.2.10
- LAN_SUBNET=172.31.2.0/24
- WAN_SUBNET=172.31.254.0/24
- WAN_GATEWAY=172.31.254.1
networks:
wan:
ipv4_address: 172.31.254.11
cone-a:
<<: *fips-common
profiles: ["cone"]
container_name: fips-nat-cone-a
hostname: fips-nat-cone-a
depends_on:
- nat-a
- relay
- stun
entrypoint:
- /usr/local/bin/nat-node-entrypoint.sh
environment:
- RUST_LOG=info,fips::discovery::nostr=debug,fips::node::lifecycle=debug
- DATA_IF=eth0
- ROUTE_SUBNET=172.31.254.0/24
- ROUTE_VIA=172.31.1.254
- RELAY_HOST=172.31.254.30
- RELAY_PORT=7777
- STUN_HOST=172.31.254.40
- STUN_PORT=3478
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./node/entrypoint.sh:/usr/local/bin/nat-node-entrypoint.sh:ro
- ./generated-configs/cone/node-a.yaml:/etc/fips/fips.yaml:ro
network_mode: none
cone-b:
<<: *fips-common
profiles: ["cone"]
container_name: fips-nat-cone-b
hostname: fips-nat-cone-b
depends_on:
- nat-b
- relay
- stun
entrypoint:
- /usr/local/bin/nat-node-entrypoint.sh
environment:
- RUST_LOG=info,fips::discovery::nostr=debug,fips::node::lifecycle=debug
- DATA_IF=eth0
- ROUTE_SUBNET=172.31.254.0/24
- ROUTE_VIA=172.31.2.254
- RELAY_HOST=172.31.254.30
- RELAY_PORT=7777
- STUN_HOST=172.31.254.40
- STUN_PORT=3478
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./node/entrypoint.sh:/usr/local/bin/nat-node-entrypoint.sh:ro
- ./generated-configs/cone/node-b.yaml:/etc/fips/fips.yaml:ro
network_mode: none
symmetric-a:
<<: *fips-common
profiles: ["symmetric"]
container_name: fips-nat-symmetric-a
hostname: fips-nat-symmetric-a
depends_on:
- nat-a
- relay
- stun
entrypoint:
- /usr/local/bin/nat-node-entrypoint.sh
environment:
- RUST_LOG=info,fips::discovery::nostr=debug,fips::node::lifecycle=debug
- DATA_IF=eth0
- ROUTE_SUBNET=172.31.254.0/24
- ROUTE_VIA=172.31.1.254
- RELAY_HOST=172.31.254.30
- RELAY_PORT=7777
- STUN_HOST=172.31.254.40
- STUN_PORT=3478
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./node/entrypoint.sh:/usr/local/bin/nat-node-entrypoint.sh:ro
- ./generated-configs/symmetric/node-a.yaml:/etc/fips/fips.yaml:ro
network_mode: none
symmetric-b:
<<: *fips-common
profiles: ["symmetric"]
container_name: fips-nat-symmetric-b
hostname: fips-nat-symmetric-b
depends_on:
- nat-b
- relay
- stun
entrypoint:
- /usr/local/bin/nat-node-entrypoint.sh
environment:
- RUST_LOG=info,fips::discovery::nostr=debug,fips::node::lifecycle=debug
- DATA_IF=eth0
- ROUTE_SUBNET=172.31.254.0/24
- ROUTE_VIA=172.31.2.254
- RELAY_HOST=172.31.254.30
- RELAY_PORT=7777
- STUN_HOST=172.31.254.40
- STUN_PORT=3478
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./node/entrypoint.sh:/usr/local/bin/nat-node-entrypoint.sh:ro
- ./generated-configs/symmetric/node-b.yaml:/etc/fips/fips.yaml:ro
network_mode: none
lan-a:
<<: *fips-common
profiles: ["lan"]
container_name: fips-nat-lan-a
hostname: fips-nat-lan-a
depends_on:
- relay
- stun
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./generated-configs/lan/node-a.yaml:/etc/fips/fips.yaml:ro
networks:
shared-lan:
ipv4_address: 172.31.10.10
lan-b:
<<: *fips-common
profiles: ["lan"]
container_name: fips-nat-lan-b
hostname: fips-nat-lan-b
depends_on:
- relay
- stun
volumes:
- ../docker/resolv.conf:/etc/resolv.conf:ro
- ./generated-configs/lan/node-b.yaml:/etc/fips/fips.yaml:ro
networks:
shared-lan:
ipv4_address: 172.31.10.11
testing/nat/node/entrypoint.sh
Executable
+79
View File
@@ -0,0 +1,79 @@
#!/bin/bash
set -euo pipefail
DATA_IF="${DATA_IF:-eth0}"
ROUTE_SUBNET="${ROUTE_SUBNET:-}"
ROUTE_VIA="${ROUTE_VIA:-}"
WAIT_TIMEOUT_SECS="${WAIT_TIMEOUT_SECS:-30}"
RELAY_HOST="${RELAY_HOST:-}"
RELAY_PORT="${RELAY_PORT:-7777}"
STUN_HOST="${STUN_HOST:-}"
STUN_PORT="${STUN_PORT:-3478}"
deadline=$((SECONDS + WAIT_TIMEOUT_SECS))
while [ "$SECONDS" -lt "$deadline" ]; do
if ip -4 addr show dev "$DATA_IF" 2>/dev/null | grep -q 'inet '; then
break
fi
sleep 0.5
done
if ! ip -4 addr show dev "$DATA_IF" 2>/dev/null | grep -q 'inet '; then
echo "Timed out waiting for IPv4 on ${DATA_IF}" >&2
ip addr >&2 || true
exit 1
fi
ip link set lo up
ip link set "$DATA_IF" up
if [ -n "$ROUTE_SUBNET" ] && [ -n "$ROUTE_VIA" ]; then
ip route replace "$ROUTE_SUBNET" via "$ROUTE_VIA" dev "$DATA_IF"
fi
wait_for_tcp() {
local host="$1"
local port="$2"
local deadline=$((SECONDS + WAIT_TIMEOUT_SECS))
while [ "$SECONDS" -lt "$deadline" ]; do
if nc -z -w1 "$host" "$port" >/dev/null 2>&1; then
return 0
fi
sleep 0.5
done
return 1
}
wait_for_udp() {
local host="$1"
local port="$2"
local deadline=$((SECONDS + WAIT_TIMEOUT_SECS))
while [ "$SECONDS" -lt "$deadline" ]; do
if printf 'probe' | nc -u -w1 "$host" "$port" >/dev/null 2>&1; then
return 0
fi
sleep 0.5
done
return 1
}
if [ -n "$RELAY_HOST" ]; then
wait_for_tcp "$RELAY_HOST" "$RELAY_PORT" || {
echo "Timed out waiting for relay ${RELAY_HOST}:${RELAY_PORT}" >&2
exit 1
}
fi
if [ -n "$STUN_HOST" ]; then
wait_for_udp "$STUN_HOST" "$STUN_PORT" || {
echo "Timed out waiting for STUN ${STUN_HOST}:${STUN_PORT}" >&2
exit 1
}
fi
exec /usr/local/bin/entrypoint.sh
testing/nat/relay/strfry.conf
+33
View File
@@ -0,0 +1,33 @@
db = "/usr/src/app/strfry-db/"
relay {
bind = "0.0.0.0"
port = 7777
nofiles = 0
info {
name = "FIPS NAT Lab Relay"
description = "Local relay for Docker NAT traversal tests."
pubkey = ""
contact = ""
}
maxWebsocketPayloadSize = 131072
autoPingSeconds = 30
enableTcpNoDelay = true
rejectFutureEventsSeconds = 60
rejectEphemeralEventsOlderThanSeconds = 60
rejectEventsNewerThanSeconds = 60
maxFilterLimit = 500
maxSubsPerConnection = 50
writePolicy {
plugin = ""
}
compression {
enabled = true
slidingWindow = true
}
}
testing/nat/router/Dockerfile
+11
View File
@@ -0,0 +1,11 @@
FROM debian:trixie-slim
RUN apt-get update && \
apt-get install -y --no-install-recommends \
conntrack iproute2 iptables procps tcpdump netcat-openbsd && \
rm -rf /var/lib/apt/lists/*
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
testing/nat/router/entrypoint.sh
Executable
+134
View File
@@ -0,0 +1,134 @@
#!/bin/bash
set -euo pipefail
NAT_MODE="${NAT_MODE:-cone}"
LAN_HOST="${LAN_HOST:?LAN_HOST is required}"
LAN_SUBNET="${LAN_SUBNET:?LAN_SUBNET is required}"
WAN_SUBNET="${WAN_SUBNET:?WAN_SUBNET is required}"
TCP_FORWARD_PORTS="${TCP_FORWARD_PORTS:-8443}"
WAN_GATEWAY="${WAN_GATEWAY:-}"
find_iface_for_subnet() {
local subnet="$1"
while read -r idx iface _ cidr _; do
case "$cidr" in
${subnet%0/24}*)
echo "$iface"
return 0
;;
esac
done < <(ip -o -4 addr show)
}
wait_for_iface() {
local if_name="$1"
local timeout_secs="${2:-30}"
local deadline=$((SECONDS + timeout_secs))
while [ "$SECONDS" -lt "$deadline" ]; do
if ip link show dev "$if_name" >/dev/null 2>&1; then
return 0
fi
sleep 0.5
done
return 1
}
wait_for_subnet_iface() {
local subnet="$1"
local timeout_secs="${2:-30}"
local deadline=$((SECONDS + timeout_secs))
local iface=""
while [ "$SECONDS" -lt "$deadline" ]; do
iface="$(find_iface_for_subnet "$subnet" || true)"
if [ -n "$iface" ]; then
echo "$iface"
return 0
fi
sleep 0.5
done
return 1
}
if [ -n "${LAN_IF:-}" ]; then
wait_for_iface "$LAN_IF"
else
LAN_IF="$(wait_for_subnet_iface "$LAN_SUBNET")"
fi
if [ -n "${WAN_IF:-}" ]; then
wait_for_iface "$WAN_IF"
else
WAN_IF="$(wait_for_subnet_iface "$WAN_SUBNET")"
fi
if [ -z "${LAN_IF:-}" ] || [ -z "${WAN_IF:-}" ]; then
echo "Failed to detect LAN/WAN interfaces"
ip -o -4 addr show
exit 1
fi
if [ -z "$WAN_GATEWAY" ]; then
WAN_GATEWAY="$(echo "$WAN_SUBNET" | awk -F. '{print $1 "." $2 "." $3 ".1"}')"
fi
WAN_ADDR="$(ip -o -4 addr show dev "$WAN_IF" | awk '{print $4}' | cut -d/ -f1 | head -1)"
if [ -z "$WAN_ADDR" ]; then
echo "Failed to determine WAN IPv4 address for ${WAN_IF}"
ip -o -4 addr show dev "$WAN_IF" || true
exit 1
fi
sysctl -w net.ipv4.ip_forward=1 >/dev/null || true
sysctl -w net.ipv4.conf.all.rp_filter=0 >/dev/null || true
sysctl -w "net.ipv4.conf.${LAN_IF}.rp_filter=0" >/dev/null || true
sysctl -w "net.ipv4.conf.${WAN_IF}.rp_filter=0" >/dev/null || true
ip route replace default via "$WAN_GATEWAY" dev "$WAN_IF"
iptables -F
iptables -t nat -F
iptables -P FORWARD DROP
iptables -A FORWARD -i "$LAN_IF" -o "$WAN_IF" -j ACCEPT
iptables -A FORWARD -i "$WAN_IF" -o "$LAN_IF" -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
for port in $TCP_FORWARD_PORTS; do
iptables -t nat -A PREROUTING -i "$WAN_IF" -p tcp --dport "$port" \
-j DNAT --to-destination "${LAN_HOST}:8443"
iptables -A FORWARD -i "$WAN_IF" -o "$LAN_IF" -p tcp -d "$LAN_HOST" --dport 8443 -j ACCEPT
done
case "$NAT_MODE" in
cone)
# Full-cone emulation for the single LAN node in this harness:
# preserve the UDP source port on egress and forward any inbound UDP
# on the WAN address back to the lone LAN host on the same port.
iptables -t nat -A PREROUTING -i "$WAN_IF" -p udp -j DNAT --to-destination "$LAN_HOST"
iptables -A FORWARD -i "$WAN_IF" -o "$LAN_IF" -p udp -d "$LAN_HOST" -j ACCEPT
iptables -t nat -A POSTROUTING -s "$LAN_SUBNET" -o "$WAN_IF" -p udp \
-j SNAT --to-source "$WAN_ADDR"
iptables -t nat -A POSTROUTING -s "$LAN_SUBNET" -o "$WAN_IF" ! -p udp -j MASQUERADE
;;
symmetric)
iptables -t nat -A POSTROUTING -s "$LAN_SUBNET" -o "$WAN_IF" -p udp \
-j MASQUERADE --random-fully
iptables -t nat -A POSTROUTING -s "$LAN_SUBNET" -o "$WAN_IF" ! -p udp -j MASQUERADE
;;
*)
echo "Unknown NAT_MODE: $NAT_MODE"
exit 1
;;
esac
echo "Router ready: mode=${NAT_MODE} lan_if=${LAN_IF} wan_if=${WAN_IF}"
ip route
iptables -S
iptables -t nat -S
exec tail -f /dev/null
testing/nat/scripts/generate-configs.sh
Executable
+138
View File
@@ -0,0 +1,138 @@
#!/bin/bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
NAT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
ROOT_DIR="$(cd "$NAT_DIR/../.." && pwd)"
DERIVE_KEYS="$ROOT_DIR/testing/lib/derive_keys.py"
OUTPUT_DIR="$NAT_DIR/generated-configs"
SCENARIO="${1:?usage: generate-configs.sh <cone|symmetric|lan> [mesh-name]}"
MESH_NAME="${2:-nat-lab-$(date +%s)-$$}"
case "$SCENARIO" in
cone|symmetric|lan) ;;
*)
echo "Unknown scenario: $SCENARIO" >&2
exit 1
;;
esac
mkdir -p "$OUTPUT_DIR/$SCENARIO"
keys_a="$(python3 "$DERIVE_KEYS" "$MESH_NAME" "a")"
keys_b="$(python3 "$DERIVE_KEYS" "$MESH_NAME" "b")"
nsec_a="$(echo "$keys_a" | awk -F= '/^nsec=/{print $2}')"
npub_a="$(echo "$keys_a" | awk -F= '/^npub=/{print $2}')"
nsec_b="$(echo "$keys_b" | awk -F= '/^nsec=/{print $2}')"
npub_b="$(echo "$keys_b" | awk -F= '/^npub=/{print $2}')"
relay_addr="ws://172.31.254.30:7777"
stun_addr="stun:172.31.254.40:3478"
if [ "$SCENARIO" = "lan" ]; then
relay_addr="ws://172.31.10.30:7777"
stun_addr="stun:172.31.10.40:3478"
fi
peer_block_a=$(cat <<EOF
- npub: "$npub_b"
alias: "node-b"
addresses:
- transport: udp
addr: "nat"
priority: 1
EOF
)
peer_block_b=$(cat <<EOF
- npub: "$npub_a"
alias: "node-a"
addresses:
- transport: udp
addr: "nat"
priority: 1
EOF
)
if [ "$SCENARIO" = "symmetric" ]; then
peer_block_a="$peer_block_a"$'\n'" - transport: tcp
addr: \"172.31.254.11:8443\"
priority: 20"
peer_block_b="$peer_block_b"$'\n'" - transport: tcp
addr: \"172.31.254.10:8443\"
priority: 20"
fi
write_config() {
local output_file="$1"
local nsec="$2"
local peer_block="$3"
cat > "$output_file" <<EOF
node:
identity:
nsec: "$nsec"
retry:
max_retries: 3
base_interval_secs: 2
max_backoff_secs: 8
discovery:
nostr:
enabled: true
advertise: true
app: "fips.nat.lab.v1"
advert_relays:
- "$relay_addr"
dm_relays:
- "$relay_addr"
stun_servers:
- "$stun_addr"
signal_ttl_secs: 30
attempt_timeout_secs: 6
replay_window_secs: 60
punch_start_delay_ms: 500
punch_interval_ms: 100
punch_duration_ms: 2500
advert_ttl_secs: 60
advert_refresh_secs: 20
tun:
enabled: true
name: fips0
mtu: 1280
dns:
enabled: true
bind_addr: "127.0.0.1"
port: 5354
transports:
udp:
bind_addr: "0.0.0.0:2121"
mtu: 1472
advertise_on_nostr: true
public: false
tcp:
bind_addr: "0.0.0.0:8443"
peers:
$peer_block
connect_policy: auto_connect
auto_reconnect: true
EOF
}
write_config "$OUTPUT_DIR/$SCENARIO/node-a.yaml" "$nsec_a" "$peer_block_a"
write_config "$OUTPUT_DIR/$SCENARIO/node-b.yaml" "$nsec_b" "$peer_block_b"
cat > "$OUTPUT_DIR/$SCENARIO/npubs.env" <<EOF
NPUB_A=$npub_a
NPUB_B=$npub_b
MESH_NAME=$MESH_NAME
SCENARIO=$SCENARIO
EOF
echo "Generated NAT lab configs for scenario=$SCENARIO mesh=$MESH_NAME"
echo "NPUB_A=$npub_a"
echo "NPUB_B=$npub_b"
testing/nat/scripts/nat-test.sh
Executable
+418
View File
@@ -0,0 +1,418 @@
#!/bin/bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
NAT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
ROOT_DIR="$(cd "$NAT_DIR/../.." && pwd)"
BUILD_SCRIPT="$ROOT_DIR/testing/scripts/build.sh"
GENERATE_SCRIPT="$SCRIPT_DIR/generate-configs.sh"
TOPOLOGY_SCRIPT="$SCRIPT_DIR/setup-topology.sh"
WAIT_LIB="$ROOT_DIR/testing/lib/wait-converge.sh"
SCENARIO="${1:-all}"
COMPOSE=(docker compose -f "$NAT_DIR/docker-compose.yml")
source "$WAIT_LIB"
cleanup() {
"${COMPOSE[@]}" --profile cone --profile symmetric --profile lan \
down -v --remove-orphans >/dev/null 2>&1 || true
}
helper_tcpdump_image() {
docker inspect -f '{{.Config.Image}}' fips-nat-router-a 2>/dev/null || echo nat-nat-a
}
dump_container_state() {
local container="$1"
echo ""
echo "--- $container: logs (last 80) ---"
docker logs "$container" 2>&1 | tail -80 || true
}
send_stun_probe() {
local container="$1"
local stun_host="$2"
local stun_port="$3"
docker exec "$container" python3 - "$stun_host" "$stun_port" <<'PY' 2>&1 || true
import os
import socket
import struct
import sys
host = sys.argv[1]
port = int(sys.argv[2])
txn_id = os.urandom(12)
request = struct.pack("!HHI", 0x0001, 0, 0x2112A442) + txn_id
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.settimeout(2.0)
sock.sendto(request, (host, port))
try:
data, remote = sock.recvfrom(2048)
except socket.timeout:
print(f"stun timeout waiting for {host}:{port}")
raise SystemExit(1)
if len(data) < 20:
print(f"short stun response from {remote}: {len(data)} bytes")
raise SystemExit(1)
msg_type, msg_len, cookie = struct.unpack("!HHI", data[:8])
if msg_type != 0x0101 or cookie != 0x2112A442 or data[8:20] != txn_id:
print(f"unexpected stun response from {remote}: type=0x{msg_type:04x} len={msg_len} cookie=0x{cookie:08x}")
raise SystemExit(1)
print(f"stun binding success from {remote[0]}:{remote[1]}")
PY
}
dump_fips_state() {
local container="$1"
local relay_host="${2:-172.31.254.30}"
local relay_port="${3:-7777}"
local stun_host="${4:-172.31.254.40}"
local stun_port="${5:-3478}"
dump_container_state "$container"
echo ""
echo "--- $container: UDP sockets ---"
docker exec "$container" sh -lc 'ss -H -uanp 2>/dev/null || ss -H -uan 2>/dev/null || netstat -anu 2>/dev/null' 2>&1 || true
echo ""
echo "--- $container: fipsctl show status ---"
docker exec "$container" fipsctl show status 2>&1 || true
echo ""
echo "--- $container: fipsctl show peers ---"
docker exec "$container" fipsctl show peers 2>&1 || true
echo ""
echo "--- $container: fipsctl show links ---"
docker exec "$container" fipsctl show links 2>&1 || true
echo ""
echo "--- $container: relay reachability ---"
docker exec "$container" sh -lc "nc -vz -w5 ${relay_host} ${relay_port}" 2>&1 || true
echo ""
echo "--- $container: stun reachability ---"
send_stun_probe "$container" "$stun_host" "$stun_port"
}
dump_node_udp_probe() {
local node="$1"
local stun_host="${2:-172.31.254.40}"
local stun_port="${3:-3478}"
echo ""
echo "--- $node: UDP sockets (pre-capture) ---"
docker exec "$node" sh -lc 'ss -H -uanp 2>/dev/null || ss -H -uan 2>/dev/null || netstat -anu 2>/dev/null' 2>&1 || true
echo ""
echo "--- $node: UDP routes to STUN and peer WANs ---"
docker exec "$node" sh -lc 'for ip in 172.31.254.40 172.31.254.10 172.31.254.11; do ip route get "$ip"; done' 2>&1 || true
local capture_file
capture_file="$(mktemp)"
docker exec "$node" sh -lc "timeout 8 tcpdump -ni eth0 'udp and not port 53' -c 80" \
>"$capture_file" 2>&1 &
local tcpdump_pid=$!
sleep 1
echo ""
echo "--- $node: UDP active probe ---"
echo "probe: ${node} -> ${stun_host}:${stun_port}/udp (STUN binding request)"
send_stun_probe "$node" "$stun_host" "$stun_port"
wait "$tcpdump_pid" || true
echo ""
echo "--- $node: UDP tcpdump during active probe ---"
cat "$capture_file"
rm -f "$capture_file"
echo ""
echo "--- $node: UDP sockets (post-capture) ---"
docker exec "$node" sh -lc 'ss -H -uanp 2>/dev/null || ss -H -uan 2>/dev/null || netstat -anu 2>/dev/null' 2>&1 || true
}
dump_router_udp_probe() {
local router="$1"
local source_node="$2"
local stun_host="${3:-172.31.254.40}"
local stun_port="${4:-3478}"
echo ""
echo "--- $router: UDP conntrack/state (before probe) ---"
docker exec "$router" sh -lc 'conntrack -L -p udp 2>/dev/null || echo "conntrack unavailable"' 2>&1 || true
echo ""
echo "--- $router: UDP counters (before probe) ---"
docker exec "$router" sh -lc 'iptables -vnL FORWARD; echo; iptables -t nat -vnL POSTROUTING' 2>&1 || true
echo ""
echo "--- $router: UDP routes to STUN and peer WANs ---"
docker exec "$router" sh -lc 'for ip in 172.31.254.40 172.31.254.10 172.31.254.11; do ip route get "$ip"; done' 2>&1 || true
local capture_file
capture_file="$(mktemp)"
docker exec "$router" sh -lc "timeout 8 tcpdump -ni any 'udp and not port 53' -c 80" \
>"$capture_file" 2>&1 &
local tcpdump_pid=$!
sleep 1
echo ""
echo "--- $router: UDP active probe ---"
echo "probe: ${source_node} -> ${stun_host}:${stun_port}/udp (STUN binding request)"
send_stun_probe "$source_node" "$stun_host" "$stun_port"
wait "$tcpdump_pid" || true
echo ""
echo "--- $router: UDP tcpdump during active probe ---"
cat "$capture_file"
rm -f "$capture_file"
echo ""
echo "--- $router: UDP counters (after probe) ---"
docker exec "$router" sh -lc 'iptables -vnL FORWARD; echo; iptables -t nat -vnL POSTROUTING' 2>&1 || true
echo ""
echo "--- $router: UDP conntrack/state (after probe) ---"
docker exec "$router" sh -lc 'conntrack -L -p udp 2>/dev/null || echo "conntrack unavailable"' 2>&1 || true
}
dump_stun_udp_probe() {
local source_node="$1"
local stun_host="${2:-172.31.254.40}"
local stun_port="${3:-3478}"
local helper_image
helper_image="$(helper_tcpdump_image)"
local capture_file
capture_file="$(mktemp)"
docker run --rm --net=container:fips-nat-stun --cap-add NET_ADMIN --cap-add NET_RAW \
--entrypoint sh "$helper_image" \
-lc "timeout 8 tcpdump -ni any 'udp and not port 53' -c 80" \
>"$capture_file" 2>&1 &
local tcpdump_pid=$!
sleep 1
echo ""
echo "--- fips-nat-stun: UDP active probe ---"
echo "probe: ${source_node} -> ${stun_host}:${stun_port}/udp (STUN binding request)"
send_stun_probe "$source_node" "$stun_host" "$stun_port"
wait "$tcpdump_pid" || true
echo ""
echo "--- fips-nat-stun: UDP tcpdump during active probe ---"
cat "$capture_file"
rm -f "$capture_file"
}
dump_cone_diagnostics() {
echo ""
echo "=== cone diagnostics ==="
dump_fips_state fips-nat-cone-a 172.31.254.30 7777 172.31.254.40 3478
dump_node_udp_probe fips-nat-cone-a
dump_fips_state fips-nat-cone-b 172.31.254.30 7777 172.31.254.40 3478
dump_node_udp_probe fips-nat-cone-b
dump_container_state fips-nat-router-a
dump_router_udp_probe fips-nat-router-a fips-nat-cone-a
dump_container_state fips-nat-router-b
dump_router_udp_probe fips-nat-router-b fips-nat-cone-b
dump_container_state fips-nat-relay
dump_stun_udp_probe fips-nat-cone-a
dump_stun_udp_probe fips-nat-cone-b
dump_container_state fips-nat-stun
}
dump_symmetric_diagnostics() {
echo ""
echo "=== symmetric diagnostics ==="
dump_fips_state fips-nat-symmetric-a 172.31.254.30 7777 172.31.254.40 3478
dump_fips_state fips-nat-symmetric-b 172.31.254.30 7777 172.31.254.40 3478
dump_container_state fips-nat-router-a
dump_container_state fips-nat-router-b
dump_container_state fips-nat-relay
dump_container_state fips-nat-stun
}
dump_lan_diagnostics() {
echo ""
echo "=== lan diagnostics ==="
dump_fips_state fips-nat-lan-a 172.31.10.30 7777 172.31.10.40 3478
dump_fips_state fips-nat-lan-b 172.31.10.30 7777 172.31.10.40 3478
dump_container_state fips-nat-relay
dump_container_state fips-nat-stun
}
trap 'echo ""; echo "NAT test interrupted"; cleanup; exit 130' INT TERM
require_test_image() {
if ! docker image inspect fips-test:latest >/dev/null 2>&1; then
echo "fips-test:latest not found; building test image"
"$BUILD_SCRIPT"
fi
}
require_docker_daemon() {
if ! docker info >/dev/null 2>&1; then
echo "Docker daemon is not reachable; cannot run NAT lab harness" >&2
exit 1
fi
}
assert_peer_path() {
local container="$1"
local expected_transport="$2"
local expected_prefix="$3"
docker exec "$container" fipsctl show peers \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
peers = [p for p in data.get('peers', []) if p.get('connectivity') == 'connected']
if not peers:
raise SystemExit(1)
peer = peers[0]
transport = peer.get('transport_type', '')
addr = peer.get('transport_addr', '')
if transport != sys.argv[1]:
raise SystemExit(f'transport mismatch: expected {sys.argv[1]!r}, got {transport!r}')
if not addr.startswith(sys.argv[2]):
raise SystemExit(f'addr mismatch: expected prefix {sys.argv[2]!r}, got {addr!r}')
" "$expected_transport" "$expected_prefix"
}
assert_link_path() {
local container="$1"
local expected_prefix="$2"
docker exec "$container" fipsctl show links \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
links = data.get('links', [])
if not links:
raise SystemExit(1)
addr = links[0].get('remote_addr', '')
if not addr.startswith(sys.argv[1]):
raise SystemExit(f'link addr mismatch: expected prefix {sys.argv[1]!r}, got {addr!r}')
" "$expected_prefix"
}
require_bootstrap_activity() {
local container="$1"
local logs
logs="$(docker logs "$container" 2>&1 || true)"
if ! grep -Eq "bootstrap failed|Started Nostr( UDP)? NAT traversal attempt" <<<"$logs"; then
echo "Expected bootstrap activity in ${container} logs" >&2
return 1
fi
}
ping_peer() {
local container="$1"
local npub="$2"
docker exec "$container" ping6 -c 3 -W 5 "${npub}.fips" >/dev/null
}
run_cone() {
echo "=== NAT lab: cone ==="
cleanup
"$GENERATE_SCRIPT" cone
"${COMPOSE[@]}" --profile cone up -d --build --force-recreate
"$TOPOLOGY_SCRIPT" cone
wait_for_peers fips-nat-cone-a 1 45 || {
dump_cone_diagnostics
return 1
}
wait_for_peers fips-nat-cone-b 1 45 || {
dump_cone_diagnostics
return 1
}
assert_peer_path fips-nat-cone-a udp 172.31.254.
assert_peer_path fips-nat-cone-b udp 172.31.254.
assert_link_path fips-nat-cone-a 172.31.254.
assert_link_path fips-nat-cone-b 172.31.254.
# shellcheck disable=SC1090
source "$NAT_DIR/generated-configs/cone/npubs.env"
ping_peer fips-nat-cone-a "$NPUB_B"
ping_peer fips-nat-cone-b "$NPUB_A"
cleanup
}
run_symmetric() {
echo "=== NAT lab: symmetric fallback ==="
cleanup
NAT_MODE_A=symmetric NAT_MODE_B=symmetric "$GENERATE_SCRIPT" symmetric
NAT_MODE_A=symmetric NAT_MODE_B=symmetric "${COMPOSE[@]}" --profile symmetric up -d --build --force-recreate
"$TOPOLOGY_SCRIPT" symmetric
wait_for_peers fips-nat-symmetric-a 1 60 || {
dump_symmetric_diagnostics
return 1
}
wait_for_peers fips-nat-symmetric-b 1 60 || {
dump_symmetric_diagnostics
return 1
}
assert_peer_path fips-nat-symmetric-a tcp 172.31.254.11:
assert_peer_path fips-nat-symmetric-b tcp 172.31.254.10:
assert_link_path fips-nat-symmetric-a 172.31.254.11:
assert_link_path fips-nat-symmetric-b 172.31.254.10:
require_bootstrap_activity fips-nat-symmetric-a
require_bootstrap_activity fips-nat-symmetric-b
# shellcheck disable=SC1090
source "$NAT_DIR/generated-configs/symmetric/npubs.env"
ping_peer fips-nat-symmetric-a "$NPUB_B"
ping_peer fips-nat-symmetric-b "$NPUB_A"
cleanup
}
run_lan() {
echo "=== NAT lab: lan preference ==="
cleanup
"$GENERATE_SCRIPT" lan
"${COMPOSE[@]}" --profile lan up -d --build --force-recreate
wait_for_peers fips-nat-lan-a 1 45 || {
dump_lan_diagnostics
return 1
}
wait_for_peers fips-nat-lan-b 1 45 || {
dump_lan_diagnostics
return 1
}
assert_peer_path fips-nat-lan-a udp 172.31.10.
assert_peer_path fips-nat-lan-b udp 172.31.10.
assert_link_path fips-nat-lan-a 172.31.10.
assert_link_path fips-nat-lan-b 172.31.10.
# shellcheck disable=SC1090
source "$NAT_DIR/generated-configs/lan/npubs.env"
ping_peer fips-nat-lan-a "$NPUB_B"
ping_peer fips-nat-lan-b "$NPUB_A"
cleanup
}
main() {
require_docker_daemon
require_test_image
case "$SCENARIO" in
all)
run_cone
run_symmetric
run_lan
;;
cone)
run_cone
;;
symmetric)
run_symmetric
;;
lan)
run_lan
;;
*)
echo "Usage: $0 [all|cone|symmetric|lan]" >&2
exit 1
;;
esac
echo "NAT lab scenarios passed"
}
main "$@"
testing/nat/scripts/setup-topology.sh
Executable
+131
View File
@@ -0,0 +1,131 @@
#!/bin/bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
NAT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
SCENARIO="${1:?usage: setup-topology.sh <cone|symmetric>}"
case "$SCENARIO" in
cone)
node_a="fips-nat-cone-a"
node_b="fips-nat-cone-b"
;;
symmetric)
node_a="fips-nat-symmetric-a"
node_b="fips-nat-symmetric-b"
;;
*)
echo "Unsupported topology scenario: $SCENARIO" >&2
exit 1
;;
esac
router_a="fips-nat-router-a"
router_b="fips-nat-router-b"
helper_image() {
if [ -n "${IP_HELPER_IMAGE:-}" ]; then
echo "$IP_HELPER_IMAGE"
return 0
fi
docker inspect -f '{{.Config.Image}}' "$router_a"
}
wait_for_pid() {
local container="$1"
local timeout_secs="${2:-30}"
local deadline=$((SECONDS + timeout_secs))
local pid=""
while [ "$SECONDS" -lt "$deadline" ]; do
pid="$(docker inspect -f '{{.State.Pid}}' "$container" 2>/dev/null || true)"
if [[ "$pid" =~ ^[0-9]+$ ]] && [ "$pid" -gt 0 ]; then
echo "$pid"
return 0
fi
sleep 0.5
done
echo "Timed out waiting for container PID: $container" >&2
return 1
}
run_host_ip() {
local image="$1"
shift
docker run --rm \
--privileged \
--net=host \
--pid=host \
--entrypoint ip \
"$image" \
"$@"
}
configure_node_iface() {
local container="$1"
local current_name="$2"
local final_name="$3"
local cidr="$4"
docker exec "$container" sh -lc "
ip link set lo up &&
ip link set '$current_name' name '$final_name' &&
ip addr flush dev '$final_name' &&
ip addr add '$cidr' dev '$final_name' &&
ip link set '$final_name' up
"
}
configure_router_iface() {
local container="$1"
local current_name="$2"
local final_name="$3"
local cidr="$4"
docker exec "$container" sh -lc "
ip link set lo up &&
ip link set '$current_name' name '$final_name' &&
ip addr flush dev '$final_name' &&
ip addr add '$cidr' dev '$final_name' &&
ip link set '$final_name' up
"
}
setup_pair() {
local image="$1"
local node_container="$2"
local router_container="$3"
local host_node="$4"
local host_router="$5"
local node_cidr="$6"
local router_cidr="$7"
local node_pid router_pid
node_pid="$(wait_for_pid "$node_container")"
router_pid="$(wait_for_pid "$router_container")"
run_host_ip "$image" link delete "$host_node" >/dev/null 2>&1 || true
run_host_ip "$image" link delete "$host_router" >/dev/null 2>&1 || true
run_host_ip "$image" link add "$host_node" type veth peer name "$host_router"
run_host_ip "$image" link set "$host_node" netns "$node_pid"
run_host_ip "$image" link set "$host_router" netns "$router_pid"
configure_node_iface "$node_container" "$host_node" eth0 "$node_cidr"
configure_router_iface "$router_container" "$host_router" eth1 "$router_cidr"
}
main() {
cd "$NAT_DIR"
local image
image="$(helper_image)"
setup_pair "$image" "$node_a" "$router_a" vna0 vna1 172.31.1.10/24 172.31.1.254/24
setup_pair "$image" "$node_b" "$router_b" vnb0 vnb1 172.31.2.10/24 172.31.2.254/24
}
main "$@"
testing/nat/stun/Dockerfile
+8
View File
@@ -0,0 +1,8 @@
FROM python:3.12-slim
WORKDIR /app
COPY stun_server.py /app/stun_server.py
EXPOSE 3478/udp
CMD ["python3", "/app/stun_server.py"]
testing/nat/stun/stun_server.py
+37
View File
@@ -0,0 +1,37 @@
import socket
import struct
MAGIC_COOKIE = 0x2112A442
STUN_BINDING_REQUEST = 0x0001
STUN_BINDING_SUCCESS = 0x0101
STUN_ATTR_XOR_MAPPED_ADDRESS = 0x0020
def build_success(txn_id: bytes, addr: tuple[str, int]) -> bytes:
ip_bytes = socket.inet_aton(addr[0])
cookie_bytes = MAGIC_COOKIE.to_bytes(4, "big")
x_port = addr[1] ^ (MAGIC_COOKIE >> 16)
x_ip = bytes(ip_bytes[i] ^ cookie_bytes[i] for i in range(4))
value = b"\x00\x01" + struct.pack("!H", x_port) + x_ip
attr = struct.pack("!HH", STUN_ATTR_XOR_MAPPED_ADDRESS, len(value)) + value
header = struct.pack("!HHI", STUN_BINDING_SUCCESS, len(attr), MAGIC_COOKIE) + txn_id
return header + attr
def main() -> None:
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(("0.0.0.0", 3478))
while True:
data, remote = sock.recvfrom(2048)
if len(data) < 20:
continue
msg_type, msg_len, cookie = struct.unpack("!HHI", data[:8])
txn_id = data[8:20]
if msg_type != STUN_BINDING_REQUEST or msg_len != 0 or cookie != MAGIC_COOKIE:
continue
sock.sendto(build_success(txn_id, remote), remote)
if __name__ == "__main__":
main()
testing/scripts/build.sh
+11 -4
View File
@@ -19,6 +19,15 @@ if [ ! -f "$PROJECT_ROOT/Cargo.toml" ]; then
fi
BUILD_DOCKER=true
# NAT harness binaries need Nostr bootstrap support; everything else is
# governed by platform cfg gates after PR #79's feature-matrix collapse.
DEFAULT_CARGO_BUILD_ARGS=(--features nostr-discovery)
if [ -n "${FIPS_CARGO_BUILD_ARGS:-}" ]; then
# shellcheck disable=SC2206
CARGO_BUILD_ARGS=($FIPS_CARGO_BUILD_ARGS)
else
CARGO_BUILD_ARGS=("${DEFAULT_CARGO_BUILD_ARGS[@]}")
fi
while [ $# -gt 0 ]; do
case "$1" in
--no-docker) BUILD_DOCKER=false; shift ;;
@@ -45,14 +54,12 @@ if [ "$UNAME_S" = "Darwin" ]; then
fi
echo "Building FIPS for Linux (release) using cargo-zigbuild..."
cargo zigbuild --release --target "$CARGO_TARGET" --manifest-path="$PROJECT_ROOT/Cargo.toml"
cargo zigbuild --release --target "$CARGO_TARGET" --manifest-path="$PROJECT_ROOT/Cargo.toml" --features gateway --bin fips-gateway
cargo zigbuild --release --target "$CARGO_TARGET" --manifest-path="$PROJECT_ROOT/Cargo.toml" "${CARGO_BUILD_ARGS[@]}"
TARGET_DIR="$PROJECT_ROOT/target/$CARGO_TARGET/release"
else
echo "Building FIPS (release)..."
cargo build --release --manifest-path="$PROJECT_ROOT/Cargo.toml"
cargo build --release --manifest-path="$PROJECT_ROOT/Cargo.toml" --features gateway --bin fips-gateway
cargo build --release --manifest-path="$PROJECT_ROOT/Cargo.toml" "${CARGO_BUILD_ARGS[@]}"
TARGET_DIR="$PROJECT_ROOT/target/release"
fi
testing/static/scripts/rekey-test.sh
+1 -1
View File
@@ -60,7 +60,7 @@ trap 'echo ""; echo "Test interrupted"; exit 130' INT
# Wait times derived from rekey timer
BASELINE_CONVERGENCE_TIMEOUT=60
REKEY_SETTLE=5 # settle time after rekey for cutover to complete
REKEY_SETTLE=12 # > DRAIN_WINDOW_SECS (10) so post-rekey samples are off the old session
# First FMP rekey should follow shortly after the 35s interval once the mesh is
# fully converged. Keep this bounded to preserve a meaningful scheduling check
# while still allowing for log visibility at the timeout edge.