Module path 

Multi-path / connection migration state (Phase 4.2).

Tracks the per-path lifecycle from “newly observed” through “validated” so the session can refuse to send application data over an unverified path. Each path is identified by the 1-byte path_id field in PacketHeader (Phase 3.3 / Phase 4.2 wire addition).

Validation protocol

When a peer arrives on a new (session_id, path_id) tuple — a fresh UDP source IP, a different transport leg, whatever — the receiver MUST NOT trust the path for application data until it has proven reachability by completing a challenge-response round-trip:

1. Receiver registers the new path_id (state: Unvalidated).
2. Receiver calls PathRegistry::issue_challenge to allocate a fresh 32-byte random challenge, stored under the path_id. The state transitions to Validating.
3. Receiver sends a PATH_VALIDATION flagged packet on the new path carrying the challenge bytes as its payload.
4. The legitimate peer echoes the same bytes back in a PATH_VALIDATION packet (the AEAD authentication guarantees only the legitimate peer who holds the session key can do this).
5. Receiver calls PathRegistry::verify_response. If the bytes match the stored challenge, the path transitions to Validated and may carry application data. A mismatch transitions to Failed.

The cryptographic protection comes from the AEAD layer: a network attacker observing the wire cannot forge a PATH_VALIDATION packet with the right payload because they don’t hold the session AEAD key. The challenge bytes themselves don’t need to be secret — they exist to bind a specific path-validation attempt to a specific response.

Use against migration

When a peer’s source IP changes mid-session (mobile handoff, LTE↔Wi-Fi switch, multi-path), the session must NOT silently accept packets on the new path — that would let an attacker hijack by spoofing the source IP. Issuing a challenge on the new path before accepting traffic forces the attacker to also hold the AEAD key, which they don’t.

Structs

PathRegistry

Per-session collection of PathStates indexed by path_id.

PathState

Per-path bookkeeping. Lives inside PathRegistry.

Enums

PathStateKind

Lifecycle state of a single path within a session.

RegistrationResult

Outcome of a PathRegistry::register call.

Constants

PATH_CHALLENGE_LEN

Width of a path-validation challenge / response, in bytes.