feat(ext-hdr): match §3.1/§3.2 first-4-byte selector on reflected header TLVs

Implement the draft-ietf-ippm-stamp-ext-hdr selector rule for the Reflected
IPv6 Extension Header (Type 246) and Reflected Fixed Header (Type 247) TLVs.
Previously the reflector ignored the request's first-4-byte pattern and
concatenated every captured extension header ("Not yet implemented" per
doc/architecture.md).

Reflector (src/tlv/list/processing.rs):
- Type 246: a non-zero first-4-byte selector picks the single captured
  extension-header record whose first 4 bytes match, disambiguating multiple
  headers of the same length; no match zero-fills and sets the U-flag.
- Type 247: the selector acts as a validation gate after the length check —
  it must equal the received header's first 4 bytes, else U-flag.
- A zero selector preserves the legacy copy-everything behavior.

Sender (opt-in): --reflected-ipv6-ext-hdr-selector /
--reflected-fixed-hdr-selector hex flags, validated in
Configuration::validate() (requires the enabling flag, >=1 non-zero byte,
family-size cap) and built via ReflectedIpv6ExtHdrTlv/ReflectedFixedHdrTlv::
request_with_selector.

The selector matches stamp-suite's reflected representation, where byte 0 is
the extension-header type (0x00 Hop-by-Hop, 0x3C Destination Options), not
the on-wire Next Header pointer — documented in CLI help and architecture.md.

No change to existing exchanges: the rule is dormant until a sender opts in.

Author: asmie

doc/architecture.md

@@ -455,15 +455,29 @@ the datalink layer. Only the `pnet` backend can do this (see
   reflector), the reflector zero-fills the Value and sets the U-flag
   rather than silently truncating or zero-padding. This conformance check
   ships in stamp-suite as of this release.
-- **Not yet implemented:** the §3.1/§3.2 "non-zero first 4 bytes"
-  disambiguation rule. When the sender pre-populates the first 4 bytes of
-  a Type 246 TLV with header data to ask the reflector for a *specific*
-  extension header (e.g. one of two same-length Hop-by-Hop options), the
-  reflector is required to match against that pattern. Today we
-  concatenate every captured extension header into the TLV Value
-  regardless of the first-4-byte pattern. Tracked separately; safe today
-  for senders that send a single TLV-instance per packet with the value
-  field zeroed.
+- **§3.1/§3.2 "non-zero first 4 bytes" selector (implemented).** When the
+  sender pre-populates the first 4 bytes of the request Value with a non-zero
+  pattern, the reflector matches it against the captured header(s) before
+  copying. For Type 246 this disambiguates multiple extension headers of the
+  same length: the reflector walks the captured records (`[type][HdrExtLen][body]`,
+  `(HdrExtLen+1)*8` bytes each) and copies **only** the record whose first 4
+  bytes match the selector; if none matches it zero-fills and sets the U-flag.
+  For Type 247 (one fixed header) it is a validation gate: the selector must
+  equal the received header's first 4 bytes, else U-flag. A zero selector (the
+  default) preserves the legacy behavior — Type 246 concatenates every captured
+  header, Type 247 copies the fixed header. Senders opt in with
+  `--reflected-ipv6-ext-hdr-selector <hex>` / `--reflected-fixed-hdr-selector <hex>`;
+  this is dormant until a sender sets it, so no existing exchange changes.
+  - **Selector byte-0 caveat.** stamp-suite's reflected representation stores
+    each extension header's byte 0 as the header *type* (`0x00` Hop-by-Hop,
+    `0x3C` Destination Options — the protocol number from the preceding Next
+    Header field), with bytes 1..3 equal to the wire bytes. The reflector
+    matches the selector against this reflected representation (the only
+    internally-consistent choice, since that is what it copies back), so a
+    stamp-suite selector's byte 0 is the header type, not the on-wire Next
+    Header pointer. Fully wire-accurate matching would require reworking the
+    capture format and is deferred (Types 246/247 use experimental codepoints
+    that are already stamp-suite-specific).
 
 ## Prometheus Metrics
 

doc/usage.md

@@ -194,7 +194,9 @@ The canonical reference is `stamp-suite --help` (this list is generated from the
       --reflected-control-length <LEN>  Requested reply packet length, 0 = don't pad [default: 0]
       --reflected-control-interval-ns <NS>  Inter-packet gap [default: 1_000_000]
       --reflected-fixed-hdr        Request reflected IPv4/IPv6 fixed header (TLV 247, draft-ietf-ippm-stamp-ext-hdr §4)
+      --reflected-fixed-hdr-selector <HEX>  §3.2 selector: first bytes must match the received IP header, else U-flag (requires --reflected-fixed-hdr)
       --reflected-ipv6-ext-hdr     Request reflected IPv6 extension headers (TLV 246, draft-ietf-ippm-stamp-ext-hdr §3)
+      --reflected-ipv6-ext-hdr-selector <HEX>  §3.1 selector: return only the matching extension header; byte 0 is the header type (00=Hop-by-Hop, 3c=Dest-Opts) (requires --reflected-ipv6-ext-hdr)
       --ber                        Enable BER TLVs (draft-gandhi-ippm-stamp-ber, Types 240/241/242)
       --ber-pattern <HEX>          Padding bit pattern (default: ff00)
       --ber-padding-size <BYTES>   Extra Padding length used with --ber [default: 64]

src/configuration.rs

@@ -567,6 +567,25 @@ pub struct Configuration {
     /// the TLV with the U-flag set.
     #[clap(long)]
     pub reflected_ipv6_ext_hdr: bool,
+
+    /// Selector for the Type 246 request (draft-ietf-ippm-stamp-ext-hdr §3.1).
+    /// Hex string (e.g. "3c000102"); its bytes are placed at the start of the
+    /// request Value so the reflector returns only the matching extension
+    /// header (disambiguating multiple same-length headers). Byte 0 is the
+    /// header TYPE — `00` = Hop-by-Hop, `3c` = Destination Options — matching
+    /// the reflected representation, not the on-wire Next Header pointer.
+    /// Must contain at least one non-zero byte. Requires
+    /// `--reflected-ipv6-ext-hdr`.
+    #[clap(long, value_name = "HEX")]
+    pub reflected_ipv6_ext_hdr_selector: Option<String>,
+
+    /// Selector for the Type 247 request (draft-ietf-ippm-stamp-ext-hdr §3.2).
+    /// Hex string whose bytes must match the start of the received IP fixed
+    /// header; on mismatch the reflector echoes the TLV with the U-flag set.
+    /// At most 20 bytes (IPv4) or 40 bytes (IPv6) by the destination family,
+    /// and at least one non-zero byte. Requires `--reflected-fixed-hdr`.
+    #[clap(long, value_name = "HEX")]
+    pub reflected_fixed_hdr_selector: Option<String>,
 }
 
 impl Configuration {
@@ -742,6 +761,49 @@ impl Configuration {
             ));
         }
 
+        // draft-ietf-ippm-stamp-ext-hdr §3.1/§3.2 header-reflection selectors.
+        if let Some(sel) = &self.reflected_ipv6_ext_hdr_selector {
+            if !self.reflected_ipv6_ext_hdr {
+                return Err(ConfigurationError::InvalidConfiguration(
+                    "--reflected-ipv6-ext-hdr-selector requires --reflected-ipv6-ext-hdr"
+                        .to_string(),
+                ));
+            }
+            let bytes = decode_selector(sel).map_err(|e| {
+                ConfigurationError::InvalidConfiguration(format!(
+                    "invalid --reflected-ipv6-ext-hdr-selector: {e}"
+                ))
+            })?;
+            if bytes.len() > MAX_IPV6_EXT_HDR_SELECTOR_BYTES {
+                return Err(ConfigurationError::InvalidConfiguration(format!(
+                    "--reflected-ipv6-ext-hdr-selector is {} bytes; the maximum is {} \
+                     (one IPv6 extension header)",
+                    bytes.len(),
+                    MAX_IPV6_EXT_HDR_SELECTOR_BYTES
+                )));
+            }
+        }
+        if let Some(sel) = &self.reflected_fixed_hdr_selector {
+            if !self.reflected_fixed_hdr {
+                return Err(ConfigurationError::InvalidConfiguration(
+                    "--reflected-fixed-hdr-selector requires --reflected-fixed-hdr".to_string(),
+                ));
+            }
+            let bytes = decode_selector(sel).map_err(|e| {
+                ConfigurationError::InvalidConfiguration(format!(
+                    "invalid --reflected-fixed-hdr-selector: {e}"
+                ))
+            })?;
+            let max = if self.remote_addr.is_ipv4() { 20 } else { 40 };
+            if bytes.len() > max {
+                return Err(ConfigurationError::InvalidConfiguration(format!(
+                    "--reflected-fixed-hdr-selector is {} bytes; the maximum for the \
+                     destination family is {max} (the IP fixed-header length)",
+                    bytes.len()
+                )));
+            }
+        }
+
         Ok(())
     }
 
@@ -898,6 +960,8 @@ impl Configuration {
         merge!(reflected_control_min_interval_ns);
         merge!(reflected_fixed_hdr);
         merge!(reflected_ipv6_ext_hdr);
+        merge_opt!(reflected_ipv6_ext_hdr_selector);
+        merge_opt!(reflected_fixed_hdr_selector);
     }
 }
 
@@ -992,6 +1056,8 @@ pub struct FileConfiguration {
     pub reflected_control_min_interval_ns: Option<u32>,
     pub reflected_fixed_hdr: Option<bool>,
     pub reflected_ipv6_ext_hdr: Option<bool>,
+    pub reflected_ipv6_ext_hdr_selector: Option<String>,
+    pub reflected_fixed_hdr_selector: Option<String>,
 }
 
 /// JSON Schema (draft 2020-12) for the TOML config file accepted by
@@ -1079,7 +1145,9 @@ pub const CONFIG_JSON_SCHEMA: &str = r##"{
     "reflected_control_max_size":  { "type": "integer", "minimum": 0, "maximum": 65535 },
     "reflected_control_min_interval_ns": { "type": "integer", "minimum": 0 },
     "reflected_fixed_hdr":    { "type": "boolean" },
-    "reflected_ipv6_ext_hdr": { "type": "boolean" }
+    "reflected_ipv6_ext_hdr": { "type": "boolean" },
+    "reflected_ipv6_ext_hdr_selector": { "type": "string", "pattern": "^[0-9a-fA-F]+$" },
+    "reflected_fixed_hdr_selector":    { "type": "string", "pattern": "^[0-9a-fA-F]+$" }
   }
 }"##;
 
@@ -1089,6 +1157,29 @@ pub fn is_auth(mode: AuthMode) -> bool {
     mode.is_authenticated()
 }
 
+/// Maximum length of a Type 246 selector: one full IPv6 extension header,
+/// `(255 + 1) * 8` bytes (draft-ietf-ippm-stamp-ext-hdr §3.1).
+pub(crate) const MAX_IPV6_EXT_HDR_SELECTOR_BYTES: usize = 2048;
+
+/// Decodes a hex selector string (optional `0x` prefix) into bytes for the
+/// draft-ietf-ippm-stamp-ext-hdr §3.1/§3.2 header-reflection request TLVs.
+/// Requires non-empty input with at least one non-zero byte — an all-zero
+/// selector would be indistinguishable from "no selector requested".
+pub(crate) fn decode_selector(s: &str) -> Result<Vec<u8>, String> {
+    let trimmed = s
+        .strip_prefix("0x")
+        .or_else(|| s.strip_prefix("0X"))
+        .unwrap_or(s);
+    if trimmed.is_empty() {
+        return Err("empty selector".to_string());
+    }
+    let bytes = hex::decode(trimmed).map_err(|e| format!("invalid hex `{s}`: {e}"))?;
+    if bytes.iter().all(|&b| b == 0) {
+        return Err("selector must contain at least one non-zero byte".to_string());
+    }
+    Ok(bytes)
+}
+
 /// clap value_parser: parse a u16 from decimal or `0x`-prefixed hex, rejecting 0.
 ///
 /// Accepts: `255`, `0xff`, `0XFF`, `0x00ab`. Rejects: `0`, `0x0`, empty, `ff`,
@@ -1167,6 +1258,100 @@ mod tests {
         assert!(conf.is_err());
     }
 
+    /// A known-good argument set that passes `validate()`, for tests that want
+    /// to isolate a single new validation rule.
+    fn base_valid_args() -> Vec<String> {
+        [
+            "test",
+            "--remote-addr",
+            "127.0.0.1",
+            "--local-addr",
+            "0.0.0.0",
+            "--remote-port",
+            "862",
+            "--local-port",
+            "862",
+            "--clock-source",
+            "NTP",
+            "--send-delay",
+            "1000",
+            "--count",
+            "1000",
+            "--timeout",
+            "5",
+            "--auth-mode",
+            "A",
+            "--is-reflector",
+            "--hmac-key",
+            "0123456789abcdef0123456789abcdef",
+        ]
+        .iter()
+        .map(|s| (*s).to_string())
+        .collect()
+    }
+
+    #[test]
+    fn ext_hdr_selector_requires_enabling_flag() {
+        let mut args = base_valid_args();
+        args.extend([
+            "--reflected-ipv6-ext-hdr-selector".to_string(),
+            "3c000102".to_string(),
+        ]);
+        let conf = Configuration::try_parse_from(args).unwrap();
+        assert!(conf.validate().is_err());
+    }
+
+    #[test]
+    fn ext_hdr_selector_with_flag_is_accepted() {
+        let mut args = base_valid_args();
+        args.extend([
+            "--reflected-ipv6-ext-hdr".to_string(),
+            "--reflected-ipv6-ext-hdr-selector".to_string(),
+            "3c000102".to_string(),
+        ]);
+        let conf = Configuration::try_parse_from(args).unwrap();
+        assert!(conf.validate().is_ok());
+        assert_eq!(
+            conf.reflected_ipv6_ext_hdr_selector.as_deref(),
+            Some("3c000102")
+        );
+    }
+
+    #[test]
+    fn all_zero_ext_hdr_selector_is_rejected() {
+        let mut args = base_valid_args();
+        args.extend([
+            "--reflected-ipv6-ext-hdr".to_string(),
+            "--reflected-ipv6-ext-hdr-selector".to_string(),
+            "00000000".to_string(),
+        ]);
+        let conf = Configuration::try_parse_from(args).unwrap();
+        assert!(conf.validate().is_err());
+    }
+
+    #[test]
+    fn fixed_hdr_selector_requires_enabling_flag() {
+        let mut args = base_valid_args();
+        args.extend([
+            "--reflected-fixed-hdr-selector".to_string(),
+            "45000054".to_string(),
+        ]);
+        let conf = Configuration::try_parse_from(args).unwrap();
+        assert!(conf.validate().is_err());
+    }
+
+    #[test]
+    fn fixed_hdr_selector_too_long_for_ipv4_is_rejected() {
+        let mut args = base_valid_args();
+        args.extend([
+            "--reflected-fixed-hdr".to_string(),
+            "--reflected-fixed-hdr-selector".to_string(),
+            "01".repeat(21), // 21 bytes > 20-byte IPv4 fixed header
+        ]);
+        let conf = Configuration::try_parse_from(args).unwrap();
+        assert!(conf.validate().is_err());
+    }
+
     #[test]
     fn test_control_plane_flags() {
         let args = vec![