Module freshness 

Fingerprint freshness contracts for browser identity reuse.

Browser identity artifacts — fingerprints, sticky sessions, and challenge contexts — must not be reused past a safe age, across incompatible targets, or when their underlying signature has rotated. This module provides a deterministic freshness decision function that callers can plug into the acquisition runner and the stealth v3 identity paths to reject stale or mismatched artifacts before they are reused.

Feature flag

This module is default-on and is always compiled as part of the stygian-browser crate. The AcquisitionRunner and stealth v3 paths consult the freshness check on every reuse so integration tests gated on those features exercise it.

Domain-aware TTL defaults

FreshnessPolicy::for_domain resolves a max-age using four DomainClasses that callers can tune via the domain_class_overrides map:

• DomainClass::Sensitive (default 120 s) — auth, payment, or challenge-issuing endpoints.
• DomainClass::Authenticated (default 600 s) — logged-in user surfaces.
• DomainClass::Hostile (default 300 s) — known anti-bot targets.
• DomainClass::Default (default 1800 s) — generic targets.

Telemetry fields

Every non-FreshnessDecision::Valid decision carries an InvalidationReason whose fields explain why the artifact was rejected (observed vs. contract domain, observed vs. contract signature, captured vs. observed timestamp, elapsed vs. max-age). The runner emits these fields via tracing::warn! and the FreshnessReport attached to the acquisition result.

Example

use stygian_browser::freshness::{
    DomainClass, FreshnessCheckInput, FreshnessContract, FreshnessPolicy,
    FreshnessPolicyKind, check,
};
use std::time::Duration;

let policy = FreshnessPolicy::default();
let contract = FreshnessContract::with_signature(
    "example.com",
    "sha256:abc123",
    1_700_000_000_000,
    Duration::from_millis(policy.max_age_ms_for(DomainClass::Default)),
    FreshnessPolicyKind::Standard,
)
.expect("valid contract");
let decision = check(
    &contract,
    &FreshnessCheckInput::new("example.com", Some("sha256:abc123"), 1_700_000_060_000),
);
assert!(decision.is_valid());

Structs

FreshnessCheckInput

Observed context passed to check.

FreshnessContract

A freshness contract describing the origin and constraints of an identity artifact.

FreshnessPolicy

Configurable TTL and signature policy for freshness contracts.

FreshnessReport

Compact freshness report attached to acquisition results and emitted via tracing.

InvalidationReason

Structured reason a freshness contract was invalidated.

Enums

DomainClass

Domain classification that controls default max-age selection.

FreshnessDecision

Decision produced by check.

FreshnessError

Errors produced by freshness contract construction.

FreshnessPolicyKind

Coarse policy band for a freshness contract.

InvalidationKind

Machine-readable reason tag attached to InvalidationReason.

Functions

check

Evaluate contract against input, returning a deterministic FreshnessDecision.

signature_hash

Produce a stable, low-cost signature hash for an arbitrary list of string fields.

unix_epoch_ms

Current Unix epoch in milliseconds, clamped to u64.