fix(dig-node): gate inbound-demand pull on XOR-proximity admission (anti-amplification)

[MichaelTaylor3d]

Closes dig_ecosystem#2014. Follow-up from epic #1934 child 5 (#1990); the dependency (the XOR-proximity primitive) is now live post-#1934.

Why

The tier-1 inbound-demand pull (DIG_NODE_INBOUND_DEMAND_CACHE) lets a remote peer's read drive this node to fetch + cache + DHT-announce a whole .dig capsule — a classic amplification primitive (a peer could make the node cache + advertise arbitrary attacker-chosen content). It was opt-in default-OFF precisely because the defence wasn't wired. This wires it: gate the pull on XOR-proximity (keyspace distance) so a peer can only drive caching of content NEAR this node's peer_id — ungameable (a peer can't move our peer_id).

The default stays OFF — flipping it is a separate later security pass (explicitly out of scope, per #2014).

What changed

• Second admission after the flag — note_inbound_demand (lib.rs): if inbound_demand_cache_enabled() && self.inbound_demand_pull_admitted(store,root). New inbound_demand_pull_admitted computes dig_dht::ContentId::capsule(store,root).to_key() and tests relevance::in_keyspace_neighbourhood(capsule_key, peer_id).
• Predicate (relevance.rs): new in_keyspace_neighbourhood + INBOUND_DEMAND_MIN_PROXIMITY, built on the existing xor_proximity (the SAME primitive relevance()/the tier-0 selector use — xor_proximity promoted to pub(crate)).
• Reference identity plumbed via a new OnceLock<[u8;32]>node_peer_id + set_node_peer_id, installed at peer-network bring-up (peer.rs) from identity.peer_id() — the exact value tier-0's NodeContext.peer_id uses (one shared reference). Kept OUT of the shared spawn_capsule_backfill body so only the inbound-demand path is gated (not the origin-gated fetch-side path).

The proximity bar + justification (the security-sensitive number)

The tier-0 selector has no fixed proximity cutoff to reuse verbatim (it's a relevance/size greedy knapsack over the xor_proximity primary), so — per the ticket's fallback — the boolean is derived from the same xor_proximity + same reference peer_id, bar at the keyspace midpoint 0.5:

• Not too tight: a uniform-random content id has proximity uniform in [0,1] (median 0.5); 0.5 admits the half of keyspace closer to our peer_id than a random point (≈ shares the top keyspace bit). Kademlia routes near-key requests to near-key nodes, so genuine inbound demand sits well inside the neighbourhood — legitimate demand-caching always fires.
• Not too loose (ungameable): the reference is our own peer_id (immovable). Landing a capsule key near it means grinding SHA-256(0x02‖store‖root) toward a fixed target — and because the pull is chain-anchored (backfill merkle-verifies against the CHIP-0035 anchored root), each grind candidate must be a REAL on-chain store, so grinding costs on-chain mints, not cheap hashing. Combined with default-OFF + single-flight + the byte-cap in the shared pull body.
• Fail-closed: no known self-identity or non-canonical (store,root) → no pull.
• Residual (documented):0.5 only guarantees "closer than random" (~2 on-chain mints per admitted key at the extreme); tightening toward a routing-aware k-closest / larger-prefix test needs a live network-size signal not available in this pure gate — deferred to the separate default-ON pass (a one-constant change to INBOUND_DEMAND_MIN_PROXIMITY).

How verified (TDD)

• keyspace_neighbourhood_admits_the_near_half_and_denies_the_far_half (relevance.rs).
• inbound_demand_pull_gated_on_keyspace_proximity — one store, two nodes with near/far peer_id: near admits, far denies no pull.
• inbound_demand_pull_denied_without_a_known_self_identity — fail-closed.
• All 17 inbound_demand tests green (existing opt-in pull tests updated to set a near node_peer_id). cargo test -p dig-node-core --lib → 634 passed, 9 failed (all the known socket-bind sandbox tests). cargo fmt 0, clippy -D warnings clean, build ok.

SPEC

SPEC.md §7.10d updated — the "not yet wired" language replaced with the enforced XOR-proximity admission (bar, ungameability, fail-closed, default-OFF, the later-pass note).

Version

root [workspace.package].version 0.89.0 → 0.90.0; dig-node-core 0.38.0 → 0.39.0; Cargo.lock regenerated (dig-node-service=0.90.0, dig-node-core=0.39.0). Minor (additive gate, no public-API break).

---

Generated by Claude Code