fix(network): canonicalize IPv4-mapped inbound peer addresses for bans and per-IP limits

[evan-forbes]

Motivation

On a dual-stack listener (listen_addr = "[::]:port" with IPV6_V6ONLY=false), Linux reports an inbound IPv4 peer as an IPv4-mapped IPv6 address ::ffff:A.B.C.D. Zakura's ban map and address book are keyed on the canonical IPv4 form (A.B.C.D), but the inbound accept path and the legacy PeerSet compared the raw PeerSocketAddr::ip(), which keeps the mapped form. Insert-canonical / lookup-raw ⇒ the lookups miss.

Exploit (dual-stack binds only): a banned or rate-limited peer evades enforcement by reconnecting in the other address form:

• A banned peer reconnecting as ::ffff:A.B.C.D is not re-banned (both the accept path and the peer set miss the canonical ban entry).
• The per-IP recent-inbound rate limiter and the max_conns_per_ip cap (default 1) are evadable: the mapped and canonical forms count as two different hosts.

Nodes that bind 0.0.0.0 never see mapped addresses and are unaffected. The bug is invisible in regtest/e2e (those bind 127.0.0.1).

Solution

• Accept boundary (the real fix): canonicalize the inbound address once with canonical_peer_addr in accept_inbound_connections. Every later use of addr — the ban check, the recent-inbound limiter, and the key forwarded into the handshake / PeerSet — is then canonical.
• Peer set (defense-in-depth + testability): the PeerSet ban re-checks (poll_unready, poll_ready_peer_errors, and the broadcast_all_queued ban filter) and the per-IP accounting (num_peers_with_ip) also canonicalize before comparing, via a small shared canonical_ip helper. The boundary fix already makes all keys canonical; this enforces the invariant even if some future path inserts a raw key, and lets the equivalence be unit-tested directly by injecting a mapped key.

The zcashd-compat reserved-slot check already canonicalized (canonical_socket_addr(addr.remove_socket_addr_privacy())) and is unchanged. Genuine IPv6 peers are left untouched by canonical_peer_addr. Outbound keys come from the address book and are already canonical.

Testing

cargo fmt --all -- --check, cargo clippy -p zakura-network --all-targets -- -D warnings, and cargo test -p zakura-network (1000 passed, 0 failed) all green, including the zcashd-compat carve-out tests and prop::sidecar_peer_always_receives_block_gossip.

Two new deterministic unit tests in peer_set::set::tests::vectors:

• per_ip_accounting_treats_mapped_and_canonical_as_same_host — inserts a connection keyed by the canonical form and asserts both the canonical and the mapped query see it as one host, then reverses the key/query roles. This is what poll_discover's max_conns_per_ip gate relies on.
• broadcast_all_queued_bans_mapped_ipv6_against_canonical_ban — a peer keyed ::ffff:A.B.C.D against a ban map holding canonical A.B.C.D is dropped by the ban filter. All three peer-set ban re-checks share the canonical_ip helper, so this exercises that shared path.

Both tests were confirmed to fail against the un-canonicalized code (test 1 with left: 0, right: 1; test 2 with the banned mapped peer surviving the filter) and pass with the fix.

Follow-up Work

The async accept_inbound_connections loop (over a real TcpListener) isn't unit-tested directly — a TODO(test) marks the boundary canonicalization, and the equivalence is covered by the peer-set tests above. Extracting the accept decision into a pure (bans, addr) -> accept/reject helper for direct testing was left out of scope to keep the diff focused; happy to add it if a reviewer prefers.

Independent of #231 (fix/sidecar-block-gossip-unready) and #236 — different functions, no shared lines. Branched off main at v1.0.1.

[v12-auditor]

Note

Complete: Audit complete. V12 did not find any issues that need review.

Open the full results here.

Analyzed two files, diff 7130dca...0ae4355.