Module transport_realism

Expand description

Transport-layer realism expansion (HTTP/2 + HTTP/3 surfaces).

This module sits on top of the existing tls_validation layer (T46) and adds the HTTP/2 behaviour checks anti-bot vendors observe in the wild:

HTTP/2 SETTINGS frame fingerprint (initial values Chrome, Firefox, Safari send on every connection).
HTTP/2 header order (the order browsers send :method, :authority, :scheme, :path, then standard headers is part of the Akamai / DataDome fingerprint).
HTTP/2 pseudo-header order (:method before :authority before :scheme before :path is the Chrome 136 ordering).
HTTP/3 perk fingerprint (already produced by the existing tls_validation module — this module consumes it).

All checks share the same scoring interface: TransportCompatibility::score produces a normalised compatibility score in [0.0, 1.0], with confidence/coverage markers that tell the caller how much of the surface was actually observable. When HTTP/2 observations are unavailable (e.g. the caller is running a non-HTTP/2 path or a live capture failed), the score collapses to a deterministic neutral value and the coverage marker reflects that no HTTP/2 observations were supplied — see DEFAULT_COVERAGE_WHEN_HTTP2_UNAVAILABLE and DEFAULT_CONFIDENCE_WHEN_HTTP2_UNAVAILABLE.

§Feature flag

This module is default-on and is always compiled as part of the stygian-browser crate. The runner surface (AcquisitionRequest::transport_realism) is additive — callers that do not pass a context see the same runner behaviour they saw before this task landed.

§Integration with the `AcquisitionRunner`

TransportProfile is a typed config field that callers can attach to an AcquisitionRequest. When present, the runner records the resulting TransportCompatibility on the AcquisitionResult::transport_realism field as a TransportRealismReport so downstream policy mapping (T83 / T85 / T89 / T93) can consume it as a strategy hint.

§Default behaviour

TransportProfile::default() enables every observable check and marks HTTP/2 as required.
When no HTTP/2 observations are supplied, the score is 0.0 and coverage is 0.0 (clearly marked as such). Callers that always have HTTP/2 captures should override require_http2_observations to detect partial instrumentation and short-circuit the run.

§Example

use stygian_browser::tls_validation::CHROME_136_HTTP2_SETTINGS;
use stygian_browser::transport_realism::{
    score, TransportObservation, TransportProfile, HEADER_ORDER_CHROME_136,
    PSEUDO_HEADER_ORDER_CHROME_136,
};

// Live capture that exactly matches Chrome 136 → score 1.0
let obs = TransportObservation::from_settings(CHROME_136_HTTP2_SETTINGS)
    .with_header_order(HEADER_ORDER_CHROME_136.iter().copied())
    .with_pseudo_header_order(PSEUDO_HEADER_ORDER_CHROME_136.iter().copied());
let report = score(&TransportProfile::default(), &obs);
assert!(report.compatibility.score > 0.95);
assert!(report.compatibility.is_high_confidence());

Structs§

HeaderOrderMatch: Result of comparing an observed header order against a reference.
Http2CheckResult: Per-check result attached to a TransportCompatibility.
Http2Expectations: HTTP/2 expectations as a compact bitmask.
TransportCompatibility: Per-target compatibility score with confidence/coverage markers.
TransportObservation: Live transport-layer observations consumed by score.
TransportProfile: Per-target HTTP/2 transport expectations.
TransportRealismReport: Top-level transport-realism report (re-exported here for stable import paths — see crate::transport_realism). Top-level transport-realism report attached to acquisition results.

Enums§

Http2CheckKind: Stable identifier for a single HTTP/2 check.
TransportRealismError: Errors produced by transport-realism helpers.

Constants§

DEFAULT_CONFIDENCE_WHEN_HTTP2_UNAVAILABLE: Default confidence score returned when no HTTP/2 observations are available.
DEFAULT_COVERAGE_WHEN_HTTP2_UNAVAILABLE: Default coverage score returned when no HTTP/2 observations are available.
DEFAULT_SCORE_WHEN_HTTP2_UNAVAILABLE: Default compatibility score returned when no HTTP/2 observations are available.
HEADER_ORDER_CHROME_136: Ordered list of HTTP/2 header names Chrome 136 sends on a standard navigation (after the :method, :authority, :scheme, :path pseudo-headers).
HEADER_ORDER_FIREFOX_130: Ordered list of HTTP/2 header names Firefox 130 sends on a standard navigation (after the pseudo-headers).
HTTP2_CHECK_KIND_COUNT: Number of HTTP/2 checks the TransportProfile supports.
PSEUDO_HEADER_ORDER_CHROME_136: Expected HTTP/2 pseudo-header order for Chrome 136.

Functions§

compare_header_order: Compare an observed header order against a reference header order, returning a structured HeaderOrderMatch.
compare_pseudo_header_order: Compare an observed pseudo-header order against the Chrome 136 reference.
score: Score the supplied observation against the profile.

Type Aliases§

Http2SettingsObservation: HTTP/2 SETTINGS frame fingerprint captured from a live connection.