Module path_validation_codec 

Wire-format helpers for PATH_VALIDATION packets (Phase 4.2).

The path-validation state machine lives in crate::transport::path. This module is the wire encoder/decoder that turns those state transitions into V2 packets ready to push through a SessionTransport and the inverse decode on the receive side.

Frame layout

A PATH_VALIDATION frame is a V2 PhantomPacket with:

• header.flags ⊇ PacketFlags::PATH_VALIDATION
• header.path_id = the path the validation is for
• header.stream_id = 0 (control stream)
• header.sequence = caller-chosen (typically a small monotonic counter; not security-critical here because the payload itself is the unique-per-attempt random challenge)
• payload = exactly 32 bytes (PATH_CHALLENGE_LEN) — either the challenge (request) or the echoed challenge (response). Sender role determines the interpretation.

Authentication

The cryptographic protection on PATH_VALIDATION packets comes from the outer AEAD wrap when the packet is emitted alongside normal application data — the same AEAD context that secures app-data protects the validation payload from forgery. Encoders here do not perform AEAD themselves; the caller threads them through Session::encrypt_packet / decrypt_packet exactly as it does for application-data packets, then sets the PATH_VALIDATION flag in the header.

Why a separate module

transport::path owns the state machine. transport::types owns the wire types. This module is the thin bridge so neither has to know about the other.

Structs

ParsedPathValidation

A parsed incoming PATH_VALIDATION frame, with all fields the receiver needs to feed into the state machine.

Enums

PathValidationKind

Whether a frame carries an outgoing challenge or an echoed response. The two are wire-identical; the distinction lives in the sender state machine.

PathValidationParseError

Errors from parse_path_validation.

Functions

build_path_validation_packet

Build a V2 PATH_VALIDATION packet carrying the given 32-byte challenge/response payload on the supplied path_id.

parse_path_validation

Attempt to parse a V2 packet as a PATH_VALIDATION frame.