Skip to main content

Module path_validation_codec

phantom_protocol::transport

Module path_validation_codec 

Source
Available on crate feature std only.
Expand description

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 PhantomPackets ready to push through a SessionTransport, and the inverse decode on the receive side.

§Frame layout

A PATH_VALIDATION frame is an ordinary PhantomPacket with:

  • header.flags ⊇ PacketFlags::PATH_VALIDATION
  • header.path_id = the path the validation is for
  • header.stream_id = 0 (control stream)
  • header.packet_number = caller-chosen (the per-direction monotonic u64; not security-critical for the validation logic itself because the payload is the unique-per-attempt random challenge, but it still feeds the per-direction replay window so a retransmit is deduped)
  • 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 PATH_VALIDATION packet carrying the given 32-byte challenge/response payload on the supplied path_id.
parse_path_validation
Attempt to parse a PhantomPacket as a PATH_VALIDATION frame.