Tor v3 hidden-service support (BIP155) with fluxnode authentication (depends on #284)

[MorningLightMountain713]

⚠️ Merge dependency

PR #284 must merge first. This branch is based on feat/pon-vrf-integration and shares its protocol bump (170022) — BIP155 addrv2/sendaddrv2 is negotiated against that version. It must land after the PoN-VRF integration and will not apply to master until #284 does.

Why

Roughly 80% of fluxnodes are behind NAT and can only make outbound connections. The ~20% with public IPs become de-facto hubs, producing a hub-and-spoke topology:

• Single points of failure — if the hubs a NAT node depends on go down, it loses all peers.
• Gossip bottleneck — a NAT node can never relay directly to another NAT node; every path is NAT → hub → NAT.
• Uneven load — the 20% carry the connection load for the whole network.
• Eclipse surface — isolating a NAT node only requires controlling the small set of hubs it can reach.
• Poor peer diversity — NAT nodes can only choose from the reachable minority; if that minority is AS/geo-concentrated, network resilience hinges on a few providers.

Tor v3 hidden services give a NAT node a globally reachable inbound address. Two NAT nodes that could never connect directly can now peer through Tor, flattening the hub-and-spoke topology into a mesh. The goal is network resilience, not privacy.

What this adds

• BIP155 addrv2 / sendaddrv2 — gossip and store v3 onion (and other modern) addresses. sendaddrv2 is negotiated between version and verack.
• Tor v3 hidden service — created over the Tor control port (ADD_ONION, SAFECOOKIE auth); the node's .onion is advertised to peers.
• Outbound onion connectivity — dial .onion peers through Tor's SOCKS proxy (-onion).
• Reserved onion outbound — -maxonionoutbound reserves that many of the outbound connection slots for onion; clearnet outbound is held to the remainder, so a node at its outbound limit keeps its onion peers instead of letting faster clearnet dials fill every slot. (A public-IP hub sets maxonionoutbound=0 to reserve none.)
• Deterministic inbound-onion detection — fluxd binds a dedicated, OS-assigned loopback port that the Tor controller forwards the hidden service to. A connection accepted on that socket is provably an onion peer (CNode::fInboundOnion) — no 127.0.0.1 heuristic, so ordinary loopback peers (ssh tunnels, monitors) are never misclassified.
• fluxnode Tor authentication (torauth) — see below.
• Onion-aware address management — v2 anchors.dat (persist and reconnect to onion anchors across restart), onion netgroup bucketing, and onion bannability.

fluxnode Tor authentication (torauth)

A .onion address is just a 32-byte ed25519 public key — anyone can generate one. To make onion peers Sybil-resistant, fluxnodes authenticate each other with a challenge/response (torauthreq → torauthresp) that binds a peer's network identity (its .onion) to its fluxnode identity (a registered collateral outpoint):

• The response is dual-signed — by the fluxnode's secp256k1 collateral key and the hidden service's ed25519 key. The ed25519 signature covers challenge || signer_outpoint_hash.
• For an outbound onion connection, the proven .onion must equal the address we dialed, so a registered fluxnode cannot relabel its connection to another node's .onion (which would otherwise poison anchors, dedup, and the onion cap).
• The outpoint binding makes a captured ed25519 signature non-transferable: a MITM cannot replay the real onion owner's signature under its own fluxnode identity.
• Only authenticated onions are written to addrman / anchors / netgroups, and a verified onion peer is bannable by its .onion (single-host subnet) through the normal misbehavior path.
• The verified outpoint also de-duplicates connections: a fluxnode reachable on two connections at once (e.g. both nodes dialed each other) is reduced to one, and the survivor is chosen deterministically from the two outpoints so both ends keep the same connection instead of each dropping the one the other keeps.

Node roles & configuration

The daemon supports both roles through configuration:

Every node ships the same static torrc (SocksPort 127.0.0.1:9050 + ControlPort 127.0.0.1:9051 + CookieAuthentication 1 + CookieAuthFileGroupReadable 1 + ExitPolicy reject *:*); the NAT/hub split lives entirely in flux.conf:

NAT node (hidden service + SOCKS) — flux.conf: listenonion=1, torcontrol=127.0.0.1:9051, onion=127.0.0.1:9050. Accepts inbound onion peers and makes a small number of onion outbound connections plus clearnet connections to hubs for fast block relay.

Public-IP hub (SOCKS only) — flux.conf: onion=127.0.0.1:9050, maxonionoutbound=0. The hidden service is opt-in (listenonion defaults off), so a hub simply leaves it unset and stands up no .onion of its own — it never drops a hub .onion into the gossip pool or competes for NAT nodes' scarce onion-outbound slots. It still makes NET_ONION reachable so it stores, relays, and feeler-verifies onion addresses — without hubs as connective tissue, onion gossip dies.

Authentication to the control port uses SAFECOOKIE (challenge-response) — no plaintext password in flux.conf and no HashedControlPassword in torrc. fluxd is added to the Tor cookie group (debian-tor on Debian/Ubuntu) on every node at image build, but only NAT nodes (those with torcontrol= set) open a control connection; hubs leave the control port unused.

Testing & review

• Unit tests — src/gtest/test_net.cpp (NetTests): effective-address resolution before/after auth, onion subnet/ban matching, onion netgroup spread, addrv2 high-service-bit round-trip, the onion-aware ban decision + ban→IsBanned round-trip, the feeler exemption from the onion outbound cap, the clearnet/onion outbound reservation, and the duplicate-connection tiebreaker. Full flux-gtest green.
• Integration smoke test — qa/tor-smoke-test.sh runs two nodes over real Tor: hidden-service creation, outbound onion connect, addrv2 exchange, inbound onion tagging via the dedicated bind, block propagation over the onion link, and an anchors.dat round-trip + reconnect after restart.
• Review — adversarially reviewed for lock-ordering, ban-coverage, init-gating, and serialization correctness.
• Live two-node test — the torauth handler flow requires two registered fluxnodes, which regtest cannot represent, so it is validated on a live pair: mutual authentication and onion-proof verification, the duplicate-connection collapse, and onion peers auto-connecting into their reserved slots. A fluxnode-regtest harness to unit-test the handler flow is a follow-up.

Compatibility & follow-ups

• Protocol version 170022 (shared with the PoN-VRF work) — this PR must merge after it. BIP155 sendaddrv2 is negotiated, so pre-bump peers are unaffected.
• Out of scope — production rollout (the FluxOS image's Tor service and per-node-type config) is tracked separately.