NAT holepunch hardening + blind-relay server implementation

.dockerignore

@@ -0,0 +1,11 @@
+# Keep Docker build contexts (tests/docker/Dockerfile.*) small — these
+# build with `context: ../../` (the repo root) so `COPY . .` in
+# Dockerfile.rust-peer must not drag in local build artifacts or
+# unrelated tooling directories.
+/target/
+tests/node/node_modules/
+.git/
+.claude/
+.sisyphus/
+.vogon_poetry/
+docs/book/

AGENTS.md

@@ -59,6 +59,17 @@ peeroxide          — topic-based peer discovery + connection management
 - Adding optional parameters via a new companion function
 - Internal implementation changes with no public surface effect
 
+### New public API surface — always apply VISIBILITY_POLICY.md
+
+Adding new "does NOT count as breaking" surface above is still not free of process: any new `pub` type, function, or module in `libudx`, `peeroxide-dht`, or `peeroxide` must be checked against [`VISIBILITY_POLICY.md`](./VISIBILITY_POLICY.md) **in the same change**, not as an optional follow-up — do this automatically, without waiting to be asked:
+
+- Decide `pub` vs `pub(crate)` per the policy's Axis 1 rubric.
+- If `pub`, classify it into a type-role (Handle / Config / Event-Result / Error / Primitive / Wire-envelope) and apply that role's `#[non_exhaustive]` default. The burden of proof is on exemptions — don't skip `#[non_exhaustive]` on a Config/Result/Error/Event-role type without a documented reason.
+- `#[non_exhaustive]` Config/Options types must ship a `::new(...)`/builder/`Default` impl in the same commit (consumers must be able to construct them).
+- New `pub mod` needs real module-level docs in the same commit, or it should be `pub(crate) mod` instead.
+
+This check belongs in the same pass as writing the code, before it's ever proposed as done — treat it like running clippy, not like a separate audit someone else requests later.
+
 ### The boundary that matters
 
 `peeroxide-cli` is a binary consumer. Constraints it places on how it uses library internals (e.g. needing to share a socket across tasks) must be solved **inside `peeroxide-cli` or by adding new non-breaking API**, never by altering existing library signatures.

CONTRIBUTING.md

@@ -57,13 +57,16 @@ These three library crates are published at `>=1.0` and have external users.
 
 When in doubt, add a new function rather than changing an existing one.
 
+For *new* public types/functions/modules, see [`VISIBILITY_POLICY.md`](./VISIBILITY_POLICY.md) for the visibility (`pub` vs `pub(crate)`) and `#[non_exhaustive]` rubric — it exists precisely so future additive changes (new fields, new variants) don't become breaking changes later.
+
 ## PR Checklist
 
 ### Before opening a PR
 
 - [ ] Both test suites pass locally (see Testing above)
 - [ ] Clippy clean
 - [ ] No public API breaking changes without maintainer approval
+- [ ] New/changed public API in `libudx`, `peeroxide-dht`, or `peeroxide` reviewed against `VISIBILITY_POLICY.md` (visibility + `#[non_exhaustive]` per the type-role taxonomy)
 - [ ] CHANGELOG updated for each affected crate
 - [ ] Version bumps are correct per semver (patch / minor / major)
 - [ ] New public API items have `///` doc comments

VISIBILITY_POLICY.md

@@ -0,0 +1,122 @@
+# Visibility Policy
+
+How to decide whether a new type, function, or module in `libudx`, `peeroxide-dht`, or `peeroxide` should be `pub`, `pub(crate)`, or `#[non_exhaustive]`.
+
+`peeroxide-cli` is a binary consumer of these crates; it adapts to the library API, not the other way around.
+
+## Why this exists
+
+Routine bug fixes and feature gap-fills should not trigger SemVer-breaking diffs. They do whenever something is `pub` that shouldn't be, or whenever a public Config/Result/Event lacks `#[non_exhaustive]` and we want to add a field. This policy is the rubric we apply to keep the published API surface intentional and additively extensible.
+
+## Goals
+
+1. Identify the complete public API surface — every reachable item.
+2. Keep non-surface entities `pub(crate)` so internal changes don't trigger SemVer churn.
+3. Enable additive evolution of the surviving surface (new fields, new variants, new methods) without breaking the SemVer contract.
+4. Stay compatible with the broader Hyperswarm / Hypercore / Holepunch ecosystem (see "Reference ecosystem pins" below).
+
+## Non-goals
+
+- Preserving struct-literal constructability for downstream users.
+- Backward compatibility for items we explicitly demote.
+- Wire-protocol changes (envelopes' Rust shape is downstream of the wire format, not the API contract).
+
+## The two-axis decision
+
+For every public-ish item, make two independent decisions.
+
+### Axis 1 — visibility (`pub` vs `pub(crate)`)
+
+In order of precedence:
+
+1. Is it reached from outside its defining crate today (workspace-internal cross-crate use counts)? → `pub`.
+2. Is it on the **pin list** below? → `pub`.
+3. Is it returned by, or required as a parameter of, a public function in the same crate? → `pub` (cascade reachability).
+4. Is it a wire-format envelope used cross-crate within the workspace? → `pub`.
+5. Otherwise → `pub(crate)`.
+
+### Axis 2 — `#[non_exhaustive]` (only if Axis 1 = `pub`)
+
+1. The role default from the **type-role taxonomy** below applies unless explicitly carved out.
+2. Default is **apply**. The burden of proof is on exemptions.
+
+**Constructor rule**: every `#[non_exhaustive]` type that users construct (Configs, Options, Params, HandlerReply-shaped types) must ship a `::new(...)` / builder / `Default` impl in the same commit. Otherwise consumers can't construct it.
+
+## Type-role taxonomy
+
+Classify every public-ish item into exactly one role. The role drives both defaults.
+
+| Role | Visibility default | `#[non_exhaustive]` default | Examples |
+|---|---|---|---|
+| **Handle** — opaque internal-state-with-methods, factory-constructed, never struct-literal'd | `pub` | no (adds nothing; consumers can't struct-literal a private-field type anyway) | `HyperDhtHandle`, `SwarmHandle`, `DhtHandle`, `Io`, `CongestionWindow`, `Holepuncher`, `SecretStream<T>`, `Push`, `Pull`, `SecurePayload`, `SocketPool`, `NoiseWrap`, `BlindRelayClient`, `Persistent`, `Router`, `UdxRuntime`, `UdxStream`, `UdxSocket`, `UdxAsyncStream` |
+| **Config / Options / Params** — user-constructed for input | `pub` | **yes** (forward-compat for new knobs) | `SwarmConfig`, `JoinOpts`, `HyperDhtConfig`, `ServerConfig`, `ConnectOpts`, `IoConfig`, `PersistentConfig`, `WireCounters` |
+| **Event / Result / Reply** — produced by the library, matched/destructured by the user | `pub` | **yes** (forward-compat for new fields/variants) | `LookupResult`, `AnnounceResult`, `ConnectResult`, `ImmutablePutResult`, `MutablePutResult`, `MutableGetResult`, `ServerEvent`, `IoEvent`, `TimeoutEvent`, `HolepunchEvent`, `ChannelEvent`, `PairResponse`, `HandshakeResult`, `PeerConnection`, `SwarmConnection`, `PeerInfo` |
+| **Error** — matched by the user | `pub` | **yes** (forward-compat for new variants) | `HyperDhtError`, `SwarmError`, `UdxError`, `SecretStreamError`, `SecretstreamError`, `RelayError`, `ProtomuxError`, `IoError`, `NoiseError`, `EncodingError` |
+| **Primitive / value type** — small, widely-constructed, semantics stable | `pub` | no (would block legitimate value construction) | `KeyPair`, `PeerAddr`, `noise::Keypair`, `Datagram`, `Priority` |
+| **Wire-format envelope** — Rust shape mirrors a serialized protocol message | `pub` if cross-crate, else `pub(crate)` | **no** (struct-literal construction IS the protocol implementation) | All of `messages::*`, `hyperdht_messages::*`, `protomux::{ControlFrame, BatchItem, DecodedFrame}`, `blind_relay::{PairMessage, UnpairMessage}`, `noise::{Handshake, HandshakeIK}`, `compact_encoding::State` |
+| **Public free function** | `pub` only if part of public contract; else `pub(crate)` | n/a (functions don't take `#[non_exhaustive]` — use signature discipline) | `discovery_key`, `crypto::{hash, hash_batch, sign_detached, verify_detached, namespace}` |
+| **Trait** | case-by-case; use sealed-trait pattern (private supertrait or `Sealed` marker) if no out-of-crate impls are intended | n/a | — |
+| **Internal helper** — never reached from outside the defining crate | `pub(crate)` | n/a | NAT state machine, routing-table internals, encoder primitives in `compact_encoding`, demoted `blind_relay::encode_*`/`decode_*` helpers |
+
+## Reference ecosystem pins
+
+These types MUST remain `pub`. They are the surface a future Rust port of any Hyperswarm-family project (hyperbeam, `@hyperswarm/rpc`, hypercore replication, etc.) would need to import. Verified against ~150 holepunchto-org projects.
+
+**peeroxide**:
+- `spawn()`, `discovery_key()`
+- `SwarmConfig`, `JoinOpts`, `SwarmHandle`, `SwarmConnection`
+- `SwarmHandle::{join, leave, dht, key_pair}`
+
+**peeroxide-dht**:
+- `spawn` (in `hyperdht` and `rpc`)
+- `HyperDhtConfig`, `ServerConfig`, `ConnectOpts`
+- `KeyPair` (with `from_seed` / `generate`)
+- `HyperDhtHandle`, `PeerConnection`, `Holepuncher`
+- `HyperDhtHandle::{lookup, announce, connect, connect_with_options, connect_with_nodes, connect_to, find_peer, mutable_put, mutable_get, immutable_put, immutable_get}`
+- `LookupResult`, `AnnounceResult`, `ConnectResult`, `ImmutablePutResult`, `MutablePutResult`, `MutableGetResult`, `ServerEvent`
+- `secret_stream::SecretStream`, `noise_wrap::NoiseWrap`, `protomux::*`
+- `crypto::{discovery_key, hash, hash_batch, sign_detached, verify_detached, namespace}`
+
+**libudx**:
+- `UdxRuntime`, `UdxSocket`, `UdxStream`, `UdxAsyncStream`
+- `UdxRuntime::{create_socket, create_stream}`
+- `UdxSocket::{bind, send_to, recv_start, close}`
+- `Header` and the wire flag constants (`FLAG_DATA`, `FLAG_END`, etc.)
+
+## When the rubric is ambiguous
+
+- **Adding a new public type?** Apply the role taxonomy. Default to `#[non_exhaustive]` for Config / Result / Event / Error roles. Skip for Handles, Primitives, and wire-format envelopes.
+- **Adding a new module?** Default `pub(crate) mod`. Promote to `pub mod` only if it's a documented advanced-use surface — and only if it gets real module-level docs in the same commit.
+- **Tempted to use `#[doc(hidden)] pub mod`?** Don't. It's a footgun: the module is publicly reachable but absent from rustdoc, so reviewers miss leaks. Either it's `pub mod` (with real docs) or it's `pub(crate) mod`.
+- **Removing an item?** Breaking change. Requires explicit human approval per AGENTS.md HARD STOP.
+- **Adding a field to a non-`#[non_exhaustive]` struct?** Breaking change. Requires approval. (Reconsider whether the struct should have been `#[non_exhaustive]` in the first place.)
+- **Changing an existing public signature?** Breaking change. Requires approval.
+
+## How to extend this policy
+
+If a new use case doesn't fit cleanly into an existing role, prefer either:
+
+1. **Carve-out**: prove it's an exception to a clear role and document the carve-out inline in the relevant role row above.
+2. **New role**: introduce a new row in the type-role taxonomy with explicit defaults.
+
+Don't ad-hoc decide visibility per-type without updating this document.
+
+## Auditing the current state
+
+When the question "is the public surface still consistent with this policy?" comes up:
+
+1. Generate the public-surface inventory:
+   ```bash
+   RUSTC_BOOTSTRAP=1 cargo rustdoc -p <crate> -- \
+       -Z unstable-options --output-format json --document-hidden-items
+   ```
+   (The `--document-hidden-items` flag is required to surface `#[doc(hidden)] pub mod` content if any has crept back in.)
+2. For each public `struct` / `enum`, confirm it's covered by the role taxonomy above (either `#[non_exhaustive]` is applied per its role's default, or its role exempts it).
+3. For each `pub mod`, confirm it has real module-level documentation. No `#[doc(hidden)] pub mod`.
+4. For cross-crate reachability questions, use qualified-path grep (`use peeroxide_dht::<mod>`, `peeroxide_dht::<mod>::`). Do NOT rely on name-only graph queries — common method names like `destroy`, `add`, `update` create false positives.
+
+## Hard constraints (from AGENTS.md, restated here for convenience)
+
+- **No `git push`** without explicit user direction.
+- **API breaking change HARD STOP**: visibility demotions (`pub` → `pub(crate)`) and removal of items are breaking changes. They require explicit human approval — they are not part of "routine maintenance."
+- **MSRV**: Rust 1.85 (2024 edition).

docs/src/SUMMARY.md

@@ -42,3 +42,4 @@
 
 - [Security Model](./appendices/security-model.md)
 - [Limits and Performance](./appendices/limits-and-performance.md)
+- [Tracing and Logging](./appendices/tracing.md)

docs/src/appendices/tracing.md

@@ -0,0 +1,138 @@
+# Tracing and Logging
+
+Peeroxide uses the [`tracing`](https://docs.rs/tracing) crate for all
+diagnostic output across its four crates (`libudx`, `peeroxide-dht`,
+`peeroxide`, `peeroxide-cli`). This appendix documents the conventions
+operators and developers can rely on when filtering, capturing, or
+extending log output.
+
+## Target conventions
+
+Every tracing call has a *target* — a string used by the
+[`EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html)
+to decide whether to emit the event. Peeroxide uses two kinds of
+targets:
+
+**1. Module-path targets (default).** Most calls inherit their target
+from the Rust module path: `peeroxide_dht::holepuncher`,
+`peeroxide_dht::hyperdht`, `libudx::native::stream`, and so on. These
+are the natural granularity for developers debugging a specific
+subsystem. EnvFilter directives prefix-match, so
+`peeroxide_dht::holepuncher=trace` enables that one module and its
+children.
+
+**2. Reserved `peeroxide::_events::*` lifecycle targets.** A curated set
+of high-signal operator-facing events use a stable, hand-picked target
+under `peeroxide::_events::`. These are not Rust modules — they are
+fixed labels that survive refactors. Examples:
+
+```text
+peeroxide::_events::swarm::started
+peeroxide::_events::dht::bootstrapped
+peeroxide::_events::peer::connected
+peeroxide::_events::peer::connect_failed
+peeroxide::_events::holepunch::probe_received
+peeroxide::_events::holepunch::passive_reflected
+peeroxide::_events::holepunch::nat_settled
+peeroxide::_events::holepunch::final_punch_sent
+peeroxide::_events::holepunch::connected
+peeroxide::_events::holepunch::aborted
+peeroxide::_events::holepunch::failed_no_verified_addr
+```
+
+Operators tail these to get a clean lifecycle stream without developer
+noise:
+
+```sh
+RUST_LOG=peeroxide::_events=info peeroxide cp send ./file
+```
+
+## Level discipline
+
+| Level | Used for | Default visibility |
+|---|---|---|
+| `error` | Fatal conditions; the operation cannot proceed | always |
+| `warn` | Recoverable anomalies, validation failures, retries | always |
+| `info` | Lifecycle events (`peeroxide::_events::*`) + startup | `-v` and above |
+| `debug` | Per-connection / per-round state transitions | `-vv` and above |
+| `trace` | Per-packet, per-loop iteration | only with explicit `RUST_LOG` |
+
+Anything that fires more than once per significant operation lives at
+`debug` or below. Per-packet paths live at `trace`. The `info` level is
+reserved for the `_events::*` subtree plus a small handful of true
+startup events.
+
+## CLI verbosity
+
+The `peeroxide` CLI exposes three verbosity levels via the `-v` flag,
+each composing a default `EnvFilter`:
+
+| Flag | Default filter | What you see |
+|---|---|---|
+| _(none)_ | `warn,peeroxide::_events=info` | Warnings + lifecycle events |
+| `-v` | `peeroxide=info,peeroxide_dht=info,peeroxide::_events=info,warn` | Info-level developer events across both swarm and DHT crates |
+| `-vv` | `peeroxide=debug,peeroxide_dht=debug,libudx=debug,peeroxide::_events=info,info` | Full debug stream across all peeroxide crates |
+
+The `RUST_LOG` environment variable always overrides the default. Any
+EnvFilter directive syntax is supported:
+
+```sh
+RUST_LOG=peeroxide_dht::holepuncher=trace peeroxide cp send ./file
+RUST_LOG=peeroxide::_events=info,libudx=warn peeroxide cp recv <topic> -
+RUST_LOG=peeroxide_dht::hyperdht=trace,peeroxide_dht::io=debug peeroxide node
+```
+
+## Subsystem map
+
+The 8 natural subsystems and the targets that feed them:
+
+| Subsystem | Module path | Event subtree |
+|---|---|---|
+| holepunch | `peeroxide_dht::holepuncher` | `peeroxide::_events::holepunch::*` |
+| nat | `peeroxide_dht::nat` | _(none currently)_ |
+| socket_pool | `peeroxide_dht::socket_pool` | _(none currently)_ |
+| relay | `peeroxide_dht::blind_relay` | _(none currently)_ |
+| discovery | `peeroxide_dht::query`, `peeroxide::peer_discovery` | _(none currently)_ |
+| swarm | `peeroxide::swarm` | `peeroxide::_events::swarm::*`, `peeroxide::_events::peer::*` |
+| dht_rpc | `peeroxide_dht::rpc`, `peeroxide_dht::io` | `peeroxide::_events::dht::*` |
+| udx | `libudx::native::*` | _(none currently)_ |
+
+New `_events::*` labels should be added sparingly, only when an event
+represents an operator-visible lifecycle transition (something a
+production operator would want in a clean default-level log).
+
+## Adding a new lifecycle event
+
+When wiring a new high-signal event, use an explicit target:
+
+```rust
+tracing::info!(
+    target: "peeroxide::_events::holepunch::nat_settled",
+    round,
+    "NAT settled + verified remote, transitioning to final punch round"
+);
+```
+
+When the same site also wants developer-level detail at debug level,
+emit two separate calls or include enough structured fields in the
+single `info!` so it serves both audiences (the latter is preferred).
+
+## Anti-patterns
+
+- **`eprintln!` for telemetry.** Bypasses level filtering and structured
+  fields. Always use a tracing macro.
+- **Emitting at `info` from a per-packet path.** Demote to `debug` or
+  `trace`; the `info` level is reserved for lifecycle events.
+- **Inventing many ad-hoc targets.** Stick to module-path defaults
+  unless the call belongs to a curated `_events::*` lifecycle category.
+- **Putting expensive computation outside the tracing macro.** The
+  `tracing` macros short-circuit on the level filter before evaluating
+  field expressions, so inline `format!()` / `.collect()` calls inside
+  the macro are gated. The same code as a `let` outside the macro
+  always runs.
+
+## Reference
+
+- [`tracing` crate](https://docs.rs/tracing)
+- [`tracing-subscriber::EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html)
+- Inspired by [iroh's `iroh::_events::*` pattern](https://github.com/n0-computer/iroh)

libudx/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- Fixed a `process_incoming` ordering bug: the relay fast-path (packet forwarding once `UdxStream::relay_to` is configured) was checked before the firewall-hook gate, permanently starving hook-based 4-tuple address adoption whenever `relay_to` was pre-wired on both sides of a pairing before either side's first packet arrived. The relay-forwarding check now runs after the firewall-hook gate.
+
 ## [1.3.1](https://github.com/Rightbracket/peeroxide/compare/libudx-v1.3.0...libudx-v1.3.1) - 2026-05-14
 
 ### Other