Capability Handshake & Proper Ping

[maxholman]

Capability Handshake & Proper Ping

Scope

Wire protocol foundation: replace one-way ExitNodeHello with bidirectional
Capability exchange, wire up proper ping/pong with latency tracking, remove
dead capability code, rename bridge.rs.

Touches: crates/wire/proto/ (data, control, management protos),
crates/core/src/transport/protocol.rs (renamed from bridge.rs),
crates/core/src/control/peers.rs, crates/core/src/node_api.rs,
crates/daemon/src/mode/{entry,exit,relay}.rs,
crates/core/src/client/{quic,ws}/mod.rs,
crates/core/src/server/{quic,ws}/mod.rs.

Out of scope

• Auto-negotiation / role derivation from capabilities (Phase 13c)
• Indeterminate mode (Phase 13b)
• Route announcement and TUN routing table updates (Phase 13e)
• Hints (--prefer, --exclude-role, --fixed-role) (Phase 13d)
• Mode transitions / RoleTransition messages (Phase 13g)
• Security posture bundling (--psk suppressing auto-negotiate) (Phase 13f)
• routes and hint fields are defined in the proto but not acted on

Why

ExitNodeHello is one-directional (connector → acceptor only), leaks the PSK
in plaintext inside the TLS tunnel, and carries no capability information. Every
subsequent auto-negotiation phase depends on both sides having a full picture of
each other's capabilities before tunnel traffic flows. This phase establishes
that foundation and also fixes the PSK authentication to use HMAC channel
binding instead of plaintext.

Notes

• Design spec: docs/tasks/13a-capability-handshake.md — items 1-6 are the
  implementation checklist. Tests section is mandatory.
• PSK proof: HMAC-SHA256 over TLS export_keying_material() channel binding.
  Requires threading TLS session handle from quinn/rustls into handshake path.
  After validation, zeroize the plaintext PSK from memory.
• Concurrent exchange: Both sides send Capability immediately after
  transport connects and wait to receive. No ordering — bidi control stream
  supports this already.
• Server accept paths: QUIC and WS servers currently read the first
  Capability directly in accept() before spawning run_control_loop,
  bypassing run_control_stream_acceptor. The new bidirectional exchange needs
  to unify this — both sides should go through the same exchange path.
• Ping latency: Periodic ping timer already fires in run_control_loop.
  update_latency() and PeerInfo.latency_ms exist in the registry. Missing
  link: pong receipt → latency calculation → registry.update_latency().
• Rename: bridge.rs → protocol.rs — done.

---

Progress (impl agent)

Branch: feat/capability-handshake (from main at c712ddc)

Build status: just check passes — fmt, clippy (slim + default), tests
(172 pass), musl cross-build, VM smoke/resilience tests all green. No warnings.

Completed (prior sessions)

1. Proto changes (items 1-2) — ExitNodeHello → Capability in all protos.
2. Rename bridge.rs → protocol.rs (item 6) — done.
3. Dead code removal (item 4) — NodeCapability, set_relay_capability(),
   capability_to_proto() all removed. Registry uses tun_capable/listening/
   connecting fields directly.
4. Client Capability sending — QUIC and WS clients send Capability via
   control stream immediately after connecting.
5. Server Capability reading — QUIC and WS servers read Capability as
   first control message with 10s timeout. AcceptResult carries
   peer_capability.
6. Daemon mode updates — entry.rs validates PSK (temporary raw bytes),
   exit.rs reads peer_capability().
7. Bidirectional capability exchange (item 3) — DONE
   • Added local_capability: Option<Capability> to ServerOptions.
   • QUIC and WS server accept() now writes server's Capability to control
     stream after reading client's Capability (before spawning control loop).
   • All daemon modes (entry, exit listen, exit relay, relay) populate
     local_capability in their ServerOptions construction.
   • run_control_stream_initiator now accepts capability_tx: Option<oneshot::Sender<Capability>> and passes it to run_control_loop.
   • QUIC and WS clients create a oneshot and pass the sender to the control
     loop; the receiver is stored in ConnectResult.
   • ConnectResult gained peer_capability_rx: Option<oneshot::Receiver<Capability>> with take_peer_capability_rx().
   • exit.rs: renamed _node_name → node_name (now used for
     local_capability).
8. Ping/pong latency tracking (item 5) — DONE
   • run_control_loop signature changed: pong_tx: Option<&mpsc::Sender<Pong>>
     → latency_tx: Option<&mpsc::Sender<f64>>.
   • Pong handler now computes RTT as now_ms - pong.timestamp_ms and sends the
     f64 via latency_tx (instead of forwarding raw Pong).
   • QUIC and WS server accept() creates latency_tx/latency_rx mpsc channel;
     passes latency_tx to control loop, latency_rx via AcceptResult.
   • entry.rs handle_connection takes latency_rx parameter and uses it in
     the select loop: periodic latency updates registry, one-shot REPL ping
     injects Ping via control_tx and stashes oneshot in pending_ping.

Completed (previous session)

9. Split hmac_proof.rs → hmac.rs + psk.rs — DONE
10. Rename relay_capability functions — DONE
11. Wire PSK proof into capability construction (items 2-3) — DONE
12. Clippy suppressions justified — DONE (now replaced by real fixes)
13. just check passes — DONE

Completed (this session — review fixes)

14. Capability → Handshake rename — DONE

    • Proto: message Capability → message Handshake in data.proto.
    • Proto: capability = 1 → handshake = 1 in control.proto ControlMessage.
    • All Rust code: types, field names, function names, doc comments, log messages.
    • peer_capability → peer_handshake, local_capability → local_handshake,
      with_capability → with_handshake, update_capability → update_handshake,
      serialize_capability_fields → serialize_handshake_fields, etc.

15. RoleHint proto shape fixed — DONE

    • Flat enum RoleHint → message RoleHint { HintLevel level = 1; DataNodeRole target = 2; }
    • Added enum HintLevel (PREFER/EXCLUDE/FIXED) and enum DataNodeRole in data.proto.
    • Updated psk.rs serialization and test to handle RoleHint message fields.

16. Channel proliferation resolved — DONE

    • Created ControlChannels struct in protocol.rs grouping outgoing_rx,
      handshake_tx, latency_tx, control_response_tx.
    • run_control_loop, run_control_stream_initiator, run_control_stream_acceptor
      signatures simplified from 7 args to 4.
    • All callers (QUIC/WS server and client) updated.

17. handle_connection refactored — DONE

    • ConnectionParams<T> struct groups 8 arguments.
    • validate_handshake() extracted: PSK proof + identity validation.
    • spawn_data_tasks() extracted: incoming/outgoing data task spawning.
    • run_connection_loop() extracted: manager + ping/latency select loop.
    • #[allow(clippy::too_many_arguments, clippy::too_many_lines)] removed.

18. PSK zeroize — DONE

    • Added explicit zeroize = "1" dep to wallhack-core, wallhackd, wallhack-cli.
    • Option<String> → Option<Zeroizing<String>> across entire PSK pipeline:
      GlobalConfig, SecurityParams, ServerConfig, ClientConfig,
      QuicClient, QuicServer, WsServer, ConnectionParams.
    • PSK bytes are zeroized on drop (when the owning struct goes out of scope).

19. Mandatory tests — DONE

    • test_handshake_exchange: concurrent bidirectional handshake via MockBiStream.
    • test_malformed_handshake: non-Handshake first message → handshake_tx unfulfilled.
    • test_ping_latency: Ping auto-reply verified; Pong with past timestamp →
      latency computed and forwarded via latency_tx.
    • test_periodic_ping: timer fires at configured interval (start_paused).

20. just check passes — All quality gates green (fmt, clippy slim+default,
    tests, musl cross-build, VM smoke/resilience, website build).

Completed (cleanup session)

21. Renamed cap_ variables to handshake — DONE

    • cap_tx/cap_rx → handshake_tx/handshake_rx in QUIC and WS clients.
    • cap_result → handshake_result in QUIC and WS servers.
    • local_cap/let mut cap → local/let mut handshake in server accept paths.
    • Local cap variables building Handshake structs → handshake in both clients.

22. Capability vs handshake naming audit — DONE

    • update_handshake() → update_capabilities() (peers.rs + entry.rs call site).
    • cap parameter in serialize_handshake_fields, compute_proof, verify_proof
      → handshake.
    • All test variables cap/cap1/cap2 → handshake/handshake1/handshake2.
    • Test different_capabilities_produce_different_proofs →
      different_handshakes_produce_different_proofs.

23. DataNodeRole dedup — DONE

    • Moved NodeRole from control.proto to data.proto. Removed DataNodeRole.
    • Renamed ROLE_UNKNOWN → ROLE_INDETERMINATE (Phase 13b terminology).
    • RoleHint.target now uses NodeRole directly (no duplicate enum).
    • control.proto references wallhack.data.NodeRole via existing import.
    • Rust: types.rs and handler.rs now import from wallhack_wire::data::NodeRole.

24. Capabilities struct grouping — DONE

    • Added message Capabilities { tun_capable, listening, connecting } to data.proto.
    • Handshake now nests Capabilities capabilities = 1 (field numbers renumbered).
    • Proto comments fixed: "Can accept incoming connections" / "Can initiate
      outgoing connections" (not "Started with --listen/--connect").
    • Internal PeerInfo (peers.rs) and node_api::PeerInfo/NodeStatus use
      Capabilities instead of 3 separate bools.
    • update_capabilities() takes &Capabilities instead of 3 bools.
    • serialize_handshake_fields() replaced with encode_to_vec() — uses protobuf's
      deterministic encoding instead of manual byte packing. psk_proof zeroed before
      encoding. Removed ~40 lines of manual serialization.
    • Management proto (management.proto) kept flat — it's the CLI-facing IPC
      boundary, flat fields are appropriate there.

Remaining work

None — all review items addressed. Ready for re-review.

---

Review Notes

Addressed

• run_quic_relay_capability — renamed to run_quic_exit_both (and
  siblings). Uses ConnectivitySpec::Both terminology.
• "Dual mode" — replaced with "both" to match ConnectivitySpec::Both.
• binding in hmac tests — renamed to context throughout hmac.rs
  (generic module uses generic names). Added known-output test that verifies
  actual HMAC-SHA256 bytes.
• clippy suppressions — all now have justification comments.

Outstanding (resolved)

• Capability → Handshake rename — the message carries identity,
  capabilities, authentication, and topology metadata. "Capability" described
  one of eight fields. Renamed to Handshake in proto, spec docs (13a-13g),
  and parent design doc. Impl agent must rename in Rust code to match.
• Channel proliferation — addressed by review finding chore: release main #4 (group into
  struct).
• channel_binding terminology — standard RFC 9266 term. No change.
• "Exit (both):" — correct for this phase. Parent spec says
  ConnectivitySpec::Both = relay, but role derivation is Phase 13c scope.
  Leave as-is for now.

---

Review (Gemini) — All Fixed

1. Mandatory tests — ✅ Added: test_handshake_exchange,
   test_malformed_handshake, test_ping_latency, test_periodic_ping.
2. PSK zeroize — ✅ Zeroizing<String> across entire config pipeline.
3. RoleHint proto shape — ✅ message RoleHint { HintLevel level; NodeRole target; }.
4. Channel proliferation — ✅ ControlChannels struct, 7 args → 4.
5. Clippy suppressions — ✅ handle_connection refactored into sub-functions.
6. Capability → Handshake rename — ✅ Proto + all Rust code.

Questions for review agent (all resolved)

• local_handshake: Option<Handshake> naming — correct. Stores the full
  Handshake message (name, version, psk_proof, routes, hint, plus capability
  flags). "Handshake" accurately describes the message type.
• cap named variables — all renamed to handshake (full name, no abbreviations).
• Capability vs handshake naming — update_handshake() → update_capabilities().
  serialize_handshake_fields stays (serializes the full Handshake, not just capabilities).
• DataNodeRole duplication — removed. NodeRole moved to data.proto,
  ROLE_UNKNOWN → ROLE_INDETERMINATE, control.proto uses via import.