Home /Modules/http-3.0/http3_flow.py

http3_flow.py

http-3.0/http3_flow.py · 734 line(s) · py

"""Python reference for the HTTP 3.0 data flow (spec §4/§5/§7/§9).

This mirrors the C reference (http3_envelope.c / http3_naming.c /
http3_pipeline.c) at the level the spec actually defines: the compact
envelope, fast naming, the response model, and retry classes. It is
dependency-free so a Python connector can speak the protocol without
becoming a SLeeLa runtime (spec §20). Crypto is out of scope here; that
lives in the C substrate (crypto_openssl.c et al.).

Every packet also carries a NONCE (per-connection monotonic counter, covered by
the MAC, for replay rejection), a per-packet DIGEST (a 64-bit KEYED MAC,
SipHash-2-4, over the header + basket + payload under a per-connection secret
key), an INTACTX id (64-bit system-specific host-integrity identity), and the
fixed BASKET of 14 goods & services (atomic-bound to the US capitalism system,
ISO USD per gram) as a canonical block covered by the MAC. The keyed DIGEST
resists deliberate forgery, not just accidental corruption. A receiver rejects a
packet whose DIGEST does not verify under the shared key, RESETs the exchange
when a packet's INTACTX variance exceeds the tamper threshold, and rejects a
packet whose NONCE is not ahead of its high-water mark (a replay).

Textual wire forms (must match the C implementation byte-for-byte):

    envelope:  H3 <ver> <flags> <service_id> <op_id> <request_id> <nonce> <digest> <intactx> <basket-hex> <len>:<payload>\\n
    response:  H3R <status> <request_id> <len>:<result>\\n
"""
from __future__ import annotations

import os
import platform
import struct
from dataclasses import dataclass
from enum import IntEnum
from typing import Callable, Dict, Optional, Tuple

ENVELOPE_VERSION = 3
MAX_PAYLOAD = 4096

# ---- 64-bit FNV-1a (matches env_fnv1a in http3_envelope.c) ------------------
_FNV64_OFFSET = 0xCBF29CE484222325
_FNV64_PRIME = 0x100000001B3
_U64 = 0xFFFFFFFFFFFFFFFF


def _fnv1a(data: bytes, h: int = _FNV64_OFFSET) -> int:
    for byte in data:
        h ^= byte
        h = (h * _FNV64_PRIME) & _U64
    return h


# ---- SipHash-2-4 keyed MAC (matches http3_mac.c byte-for-byte) --------------
MAC_KEY_BYTES = 16


def _rotl64(x: int, b: int) -> int:
    return ((x << b) | (x >> (64 - b))) & _U64


def siphash24(key: bytes, data: bytes) -> int:
    """64-bit SipHash-2-4 keyed MAC. `key` is 16 bytes; returns a 64-bit int.

    Reference-conformant (Aumasson & Bernstein): 2 compression rounds per 8-byte
    block, 4 finalization rounds; key and message read little-endian.
    """
    if len(key) != MAC_KEY_BYTES:
        raise ValueError("SipHash key must be 16 bytes")
    k0 = int.from_bytes(key[0:8], "little")
    k1 = int.from_bytes(key[8:16], "little")
    v0 = 0x736F6D6570736575 ^ k0
    v1 = 0x646F72616E646F6D ^ k1
    v2 = 0x6C7967656E657261 ^ k0
    v3 = 0x7465646279746573 ^ k1

    def sipround(v0: int, v1: int, v2: int, v3: int):
        v0 = (v0 + v1) & _U64; v1 = _rotl64(v1, 13); v1 ^= v0; v0 = _rotl64(v0, 32)
        v2 = (v2 + v3) & _U64; v3 = _rotl64(v3, 16); v3 ^= v2
        v0 = (v0 + v3) & _U64; v3 = _rotl64(v3, 21); v3 ^= v0
        v2 = (v2 + v1) & _U64; v1 = _rotl64(v1, 17); v1 ^= v2; v2 = _rotl64(v2, 32)
        return v0, v1, v2, v3

    n = len(data)
    end = n - (n % 8)
    for off in range(0, end, 8):
        m = int.from_bytes(data[off:off + 8], "little")
        v3 ^= m
        v0, v1, v2, v3 = sipround(v0, v1, v2, v3)
        v0, v1, v2, v3 = sipround(v0, v1, v2, v3)
        v0 ^= m

    b = (n & 0xFF) << 56
    tail = data[end:]
    for i, byte in enumerate(tail):
        b |= byte << (8 * i)

    v3 ^= b
    v0, v1, v2, v3 = sipround(v0, v1, v2, v3)
    v0, v1, v2, v3 = sipround(v0, v1, v2, v3)
    v0 ^= b

    v2 ^= 0xFF
    for _ in range(4):
        v0, v1, v2, v3 = sipround(v0, v1, v2, v3)
    return (v0 ^ v1 ^ v2 ^ v3) & _U64


# ---- Basket of goods & services (mirrors http3_basket.{h,c} and BASKET.docx) --
# A fixed, carefully-selected set of 14 goods/services, atomic-bound to the US
# capitalism system. Each item: (atomic_number, value_micro_usd_per_gram, name).
# The name does NOT travel on the wire; only the number and per-gram value do.
BASKET_ITEMS = 14
BASKET_ISO_CURRENCY = "USD"
BASKET_ISO_NUMERIC = 840
BASKET_BLOCK_SIZE = 4 + BASKET_ITEMS * 12  # iso(2)+count(2) + per item number(4)+value(8)

BASKET = (
    (1, 56249759, "Bleached pulp paper"),
    (2, 34243099, "Broadband gigabyte (svc)"),
    (3, 69987683, "Cane sugar"),
    (4, 43104945, "Cobalt metal"),
    (5, 29864648, "Cured tobacco leaf"),
    (6, 17981345, "Freight ton-mile (svc)"),
    (7, 6610716, "Gold bullion"),
    (8, 12259381, "Legal counsel hour (svc)"),
    (9, 65041790, "Managed cloud-compute (svc)"),
    (10, 31566795, "Natural rubber"),
    (11, 24592204, "Portland cement"),
    (12, 65211966, "Raw cotton"),
    (13, 35009362, "Roasted coffee"),
    (14, 35480545, "Structural steel"),
)


def basket_serialize() -> bytes:
    """Canonical basket block: iso(2) + count(2), then per item number(4)+value(8).
    Big-endian; matches http3_basket_serialize() in C byte-for-byte."""
    out = struct.pack(">HH", BASKET_ISO_NUMERIC, BASKET_ITEMS)
    for number, value, _name in BASKET:
        out += struct.pack(">IQ", number & 0xFFFFFFFF, value & _U64)
    return out


def basket_parse(block: bytes):
    """Parse a canonical basket block -> (iso_numeric, [(number, value), ...])."""
    if len(block) < 4:
        raise ValueError("short basket block")
    iso, count = struct.unpack(">HH", block[:4])
    if len(block) < 4 + count * 12:
        raise ValueError("short basket block")
    items = []
    for i in range(count):
        number, value = struct.unpack(">IQ", block[4 + i * 12:4 + i * 12 + 12])
        items.append((number, value))
    return iso, items


class Flag(IntEnum):
    NONE = 0x00
    BINARY = 0x01
    COMPRESSED = 0x02
    STREAM = 0x04
    IDEMPOTENT = 0x08
    RESET = 0x10  # packet reset: host tampered/untrusted


class Status(IntEnum):
    OK = 0
    APP_ERROR = 1
    UNKNOWN_SERVICE = 2
    UNKNOWN_OPERATION = 3
    BAD_ENVELOPE = 4
    TOO_LARGE = 5
    RETRY_DENIED = 6
    BAD_DIGEST = 7  # per-packet DIGEST did not verify
    TAMPERED = 8    # INTACTX variance exceeded threshold
    REPLAYED = 9    # NONCE not ahead of high-water: replay


class RetryClass(IntEnum):
    READ = 0
    IDEMPOTENT = 1
    MUTATING = 2
    STREAM = 3


# ---- INTACTX host-integrity identity (mirrors http3_intactx.{c,h}) ----------
INTACTX_VARIANCE_SHIFT = 48
INTACTX_VARIANCE_MASK = 0xFFFF
INTACTX_IDENTITY_MASK = 0x0000FFFFFFFFFFFF
INTACTX_TAMPER_THRESHOLD = 0x0400  # 1024 of 65535
INTACTX_DEFAULT_BASELINE_PATH = ".http3_intactx_baseline"


def _fnv1a_str(h: int, s: Optional[str]) -> int:
    return _fnv1a((s or "").encode("utf-8"), h)


def _sample_identity() -> int:
    """Stable OS/identity hash: changes only on re-image/clone/rename/user swap."""
    h = _FNV64_OFFSET
    u = platform.uname()
    h = _fnv1a_str(h, u.system)
    h = _fnv1a_str(h, u.release)
    h = _fnv1a_str(h, u.version)
    h = _fnv1a_str(h, u.machine)
    h = _fnv1a_str(h, u.node)
    h = _fnv1a_str(h, platform.node())
    h = _fnv1a_str(h, os.environ.get("USER"))
    h = _fnv1a_str(h, os.environ.get("LOGNAME"))
    h = _fnv1a_str(h, os.environ.get("HOME"))
    return h


def _sample_use_normality(identity: int) -> int:
    """How the host is being used right now; small drift expected, big jump = anomaly."""
    h = identity
    h = _fnv1a_str(h, os.environ.get("SHELL"))
    h = _fnv1a_str(h, os.environ.get("PWD"))
    h = _fnv1a_str(h, os.environ.get("TERM"))
    h = _fnv1a_str(h, os.environ.get("LANG"))
    return h


def _variance_from(current: int, baseline: int) -> int:
    dist = bin((current ^ baseline) & _U64).count("1")  # Hamming distance 0..64
    scaled = dist * 1024
    return min(scaled, INTACTX_VARIANCE_MASK)


class Intactx:
    """Computes the 64-bit INTACTX value for outgoing packets and judges tampering.

    Layout: bits[63..48] = 16-bit variance from baseline, bits[47..0] = identity.
    A larger environmental change yields a statically larger number.
    """

    def __init__(self, baseline_path: Optional[str] = None) -> None:
        self.baseline_path = baseline_path or INTACTX_DEFAULT_BASELINE_PATH
        self.loaded = False
        try:
            with open(self.baseline_path, "r", encoding="utf-8") as f:
                self.baseline = int(f.read().strip())
            self.loaded = True
        except (OSError, ValueError):
            # Baseline captures the same shape as an emit sample so a healthy,
            # unchanged host measures near-zero variance.
            self.baseline = _sample_use_normality(_sample_identity())
            self._write_baseline()

    def _write_baseline(self) -> None:
        try:
            with open(self.baseline_path, "w", encoding="utf-8") as f:
                f.write(f"{self.baseline:020d}\n")
        except OSError:
            pass

    def compute(self) -> int:
        identity = _sample_identity()
        sample = _sample_use_normality(identity)
        variance = _variance_from(sample, self.baseline)
        return ((variance << INTACTX_VARIANCE_SHIFT) |
                (identity & INTACTX_IDENTITY_MASK)) & _U64

    def reset_baseline(self) -> None:
        self.baseline = _sample_use_normality(_sample_identity())
        self.loaded = True
        self._write_baseline()

    @staticmethod
    def variance(intactx: int) -> int:
        return (intactx >> INTACTX_VARIANCE_SHIFT) & INTACTX_VARIANCE_MASK

    @staticmethod
    def is_tampered(intactx: int, threshold: int = 0) -> bool:
        if threshold == 0:
            threshold = INTACTX_TAMPER_THRESHOLD
        return Intactx.variance(intactx) >= threshold


@dataclass
class Envelope:
    """The §5 compact application envelope, with NONCE, DIGEST, and INTACTX."""

    service_id: int
    op_id: int
    request_id: int
    payload: bytes = b""
    flags: int = Flag.NONE
    version: int = ENVELOPE_VERSION
    nonce: int = 0
    intactx: int = 0
    digest: int = 0
    basket: bytes = None  # canonical basket block; defaults to the fixed basket

    def __post_init__(self) -> None:
        if self.basket is None:
            self.basket = basket_serialize()

    def compute_digest(self, key: bytes) -> int:
        """Keyed MAC (SipHash-2-4) over canonical header + basket + payload.

        Must match http3_envelope_compute_digest() in the C reference exactly.
        The transport-only BINARY flag is excluded so text and binary forms of
        the same logical envelope share a digest; `key` is the 16-byte
        per-connection secret. The NONCE and the BASKET are inside the MAC.
        """
        logical_flags = self.flags & ~int(Flag.BINARY)
        hdr = struct.pack(
            ">BBIIQQQI",
            self.version & 0xFF,
            logical_flags & 0xFF,
            self.service_id & 0xFFFFFFFF,
            self.op_id & 0xFFFFFFFF,
            self.request_id & _U64,
            self.nonce & _U64,
            self.intactx & _U64,
            len(self.payload) & 0xFFFFFFFF,
        )
        return siphash24(key, hdr + self.basket + self.payload)

    def seal(self, key: bytes) -> "Envelope":
        """Stamp the keyed DIGEST over the current contents; returns self for chaining."""
        self.digest = self.compute_digest(key)
        return self

    def verify_digest(self, key: bytes) -> bool:
        return self.compute_digest(key) == self.digest

    def pack_text(self, key: Optional[bytes] = None) -> bytes:
        if len(self.payload) > MAX_PAYLOAD:
            raise ValueError("payload too large")
        if key is not None:
            self.seal(key)
        basket_hex = self.basket.hex()
        head = (
            f"H3 {self.version} {self.flags} {self.service_id} {self.op_id} "
            f"{self.request_id} {self.nonce} {self.digest} {self.intactx} "
            f"{basket_hex} {len(self.payload)}:"
        )
        return head.encode("utf-8") + self.payload + b"\n"

    @staticmethod
    def unpack_text(wire: bytes) -> "Envelope":
        # Split off the fixed prefix up to the ':' after the length field.
        head, sep, rest = wire.partition(b":")
        if not sep:
            raise ValueError("malformed envelope")
        parts = head.decode("utf-8").split(" ")
        if len(parts) != 11 or parts[0] != "H3":
            raise ValueError("malformed envelope")
        _, ver, flags, sid, oid, rid, nonce, digest, intactx, basket_hex, plen = parts
        n = int(plen)
        if n > MAX_PAYLOAD:
            raise ValueError("payload too large")
        payload = rest[:n]
        if len(payload) != n:
            raise ValueError("short payload")
        return Envelope(
            service_id=int(sid), op_id=int(oid), request_id=int(rid),
            payload=payload, flags=int(flags), version=int(ver),
            nonce=int(nonce), intactx=int(intactx), digest=int(digest),
            basket=bytes.fromhex(basket_hex),
        )


@dataclass
class Response:
    """The §7 response model: STATUS | REQUEST-ID | RESULT."""

    status: Status
    request_id: int
    result: bytes = b""

    def pack_text(self) -> bytes:
        head = f"H3R {int(self.status)} {self.request_id} {len(self.result)}:"
        return head.encode("utf-8") + self.result + b"\n"

    @staticmethod
    def unpack_text(wire: bytes) -> "Response":
        head, sep, rest = wire.partition(b":")
        if not sep:
            raise ValueError("malformed response")
        parts = head.decode("utf-8").split(" ")
        if len(parts) != 4 or parts[0] != "H3R":
            raise ValueError("malformed response")
        _, status, rid, rlen = parts
        n = int(rlen)
        return Response(status=Status(int(status)), request_id=int(rid), result=rest[:n])


class Naming:
    """§4 fast naming: connection-local name <-> compact id, cached on first use."""

    def __init__(self) -> None:
        self._services: Dict[str, int] = {}
        self._ops: Dict[Tuple[int, str], int] = {}
        self._next_service = 1

    def intern_service(self, name: str) -> int:
        if name not in self._services:
            self._services[name] = self._next_service
            self._next_service += 1
        return self._services[name]

    def intern_op(self, service: str, op: str) -> int:
        sid = self.intern_service(service)
        key = (sid, op)
        if key not in self._ops:
            existing = [o for (s, o) in self._ops if s == sid]
            self._ops[key] = len(existing) + 1
        return self._ops[key]

    def lookup_service(self, name: str) -> int:
        return self._services.get(name, 0)


Handler = Callable[[bytes, object], Tuple[Status, bytes]]


class Pipeline:
    """§19 pipeline: register services/ops, then dispatch envelopes to handlers."""

    def __init__(self, intactx_threshold: int = 0, mac_key: bytes = b"\x00" * MAC_KEY_BYTES) -> None:
        self.naming = Naming()
        self._bindings: Dict[Tuple[int, int], Tuple[RetryClass, Handler]] = {}
        self._ctx: Dict[int, object] = {}
        self.requests_handled = 0
        self.intactx_threshold = intactx_threshold or INTACTX_TAMPER_THRESHOLD
        self.digest_rejects = 0
        self.tamper_resets = 0
        self.replays_rejected = 0
        self.nonce_high_water = 0
        # Connection-level timing (advisory; no wire change).
        self.timing = Timing()
        self.late_packets = 0
        self.over_rate_packets = 0
        self.unbalanced_packets = 0
        self.set_mac_key(mac_key)

    def set_timing(self, min_gap_ns: int = 0, lateness_ns: int = 0, balance_ns: int = 0) -> None:
        """Configure timing bounds (ns); 0 keeps the current value for a field."""
        self.timing.configure(min_gap_ns, lateness_ns, balance_ns)

    def observe_timing(self, arrival_ns: int, deadline_ns: int = 0) -> int:
        """Advisory: observe a packet's arrival; update certainty + counters.
        Never rejects. Returns the advisory flags for this packet."""
        flags = self.timing.observe(arrival_ns, deadline_ns)
        if flags & TIMING_LATE:
            self.late_packets += 1
        if flags & TIMING_OVER_RATE:
            self.over_rate_packets += 1
        if flags & TIMING_UNBALANCED:
            self.unbalanced_packets += 1
        return flags

    def carrier_certainty(self) -> float:
        return self.timing.certainty

    def set_mac_key(self, key: bytes) -> None:
        """Install the 16-byte per-connection MAC key used to verify each
        packet's keyed-MAC DIGEST (the shared secret from key agreement)."""
        if len(key) != MAC_KEY_BYTES:
            raise ValueError("MAC key must be 16 bytes")
        self.mac_key = bytes(key)

    def reset_replay_window(self, start: int = 0) -> None:
        """Reset the NONCE high-water mark; the next accepted packet must carry
        a NONCE strictly greater than `start`."""
        self.nonce_high_water = start

    def register(self, service: str, op: str, retry: RetryClass, handler: Handler,
                 ctx: object = None) -> Tuple[int, int]:
        sid = self.naming.intern_service(service)
        oid = self.naming.intern_op(service, op)
        self._bindings[(sid, oid)] = (retry, handler)
        if ctx is not None:
            self._ctx[sid] = ctx
        return sid, oid

    def retry_class(self, sid: int, oid: int) -> Optional[RetryClass]:
        b = self._bindings.get((sid, oid))
        return b[0] if b else None

    def dispatch(self, env: Envelope) -> Response:
        # §19: service-id lookup then op-id lookup.
        if not any(s == env.service_id for (s, _o) in self._bindings):
            return Response(Status.UNKNOWN_SERVICE, env.request_id)
        binding = self._bindings.get((env.service_id, env.op_id))
        if binding is None:
            return Response(Status.UNKNOWN_OPERATION, env.request_id)
        _retry, handler = binding
        status, result = handler(env.payload, self._ctx.get(env.service_id))
        self.requests_handled += 1
        return Response(status, env.request_id, result)

    def handle_wire(self, wire: bytes) -> bytes:
        # §19: minimal parse -> integrity gate -> dispatch -> pack response.
        try:
            env = Envelope.unpack_text(wire)
        except ValueError:
            return Response(Status.BAD_ENVELOPE, 0).pack_text()
        # 1. Per-packet DIGEST (keyed MAC) must verify under the shared key --
        #    else the packet was corrupted OR forged without the secret.
        if not env.verify_digest(self.mac_key):
            self.digest_rejects += 1
            return Response(Status.BAD_DIGEST, env.request_id).pack_text()
        # 2. INTACTX variance below threshold -- else the host is tampered: RESET.
        if Intactx.is_tampered(env.intactx, self.intactx_threshold):
            self.tamper_resets += 1
            return Response(Status.TAMPERED, env.request_id, b"RESET").pack_text()
        # 3. NONCE must be strictly ahead of the high-water mark -- else replay.
        #    The NONCE is MAC'd, so it cannot be bumped to evade this check.
        if env.nonce <= self.nonce_high_water:
            self.replays_rejected += 1
            return Response(Status.REPLAYED, env.request_id).pack_text()
        self.nonce_high_water = env.nonce
        return self.dispatch(env).pack_text()



# ---- HTTP "colors": named configuration profiles (mirrors http3_profile.{h,c})
# A SLeeLa program names a COLOR from source; the color bundles wire form,
# default flags, and the integrity profile (MAC / INTACTX / replay / basket).
# Colors are advisory selectors over already-supported behavior; naming a color
# never changes the on-the-wire envelope layout.
COLOR_NAME_MAX = 24


class WireForm(IntEnum):
    TEXT = 0
    BINARY = 1


@dataclass
class Profile:
    """A resolved HTTP color (see http3_colors.conf / HTTP-COLORS.md)."""

    name: str
    wire: WireForm
    flags: int
    mac_required: bool
    intactx_enabled: bool
    intactx_threshold: int  # 0 => library default
    replay_guard: bool
    basket_required: bool


# The shipped palette, kept in sync with http3_profile.c and http3_colors.conf.
PALETTE = (
    Profile("green", WireForm.TEXT,   Flag.NONE,                         False, False, 0, False, False),
    Profile("amber", WireForm.TEXT,   Flag.NONE,                         True,  False, 0, True,  False),
    Profile("red",   WireForm.BINARY, int(Flag.BINARY),                  True,  True,  0, True,  True),
    Profile("black", WireForm.BINARY, int(Flag.BINARY) | int(Flag.COMPRESSED),
                                                                          True,  True,  0, True,  True),
)


def profile_by_color(color: str) -> Profile:
    """Resolve a shipped color by name. Raises KeyError if unknown."""
    for p in PALETTE:
        if p.name == color:
            return p
    raise KeyError(f"unknown HTTP color: {color!r}")


def profile_load(path: str, color: str) -> Profile:
    """Load a color from an http3_colors.conf-format file. Raises KeyError if
    the color is not present, ValueError if a matching line is malformed."""
    with open(path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if not line or line.startswith("#"):
                continue
            parts = line.split()
            if len(parts) != 8 or parts[0] != color:
                continue
            name, wire, flags, mac, intactx, threshold, replay, basket = parts
            if wire not in ("text", "binary"):
                raise ValueError(f"bad wire form: {wire!r}")
            return Profile(
                name=name,
                wire=WireForm.TEXT if wire == "text" else WireForm.BINARY,
                flags=int(flags),
                mac_required=bool(int(mac)),
                intactx_enabled=bool(int(intactx)),
                intactx_threshold=int(threshold),
                replay_guard=bool(int(replay)),
                basket_required=bool(int(basket)),
            )
    raise KeyError(f"color {color!r} not found in {path}")



# ---- Connection-level timing (mirrors http3_timing.{h,c}) -------------------
# Advisory: max speed, on-time arrival, temporal balance, and a running
# carrier-certainty estimate in [0,1]. Nothing travels on the wire; the pipeline
# observes arrivals (caller-supplied nanoseconds) and tallies concerns.
TIMING_OK = 0x00
TIMING_OVER_RATE = 0x01   # arrived faster than max speed (burst)
TIMING_LATE = 0x02        # arrived after deadline + tolerance
TIMING_UNBALANCED = 0x04  # inter-arrival jitter outside the band

TIMING_DEFAULT_MIN_GAP_NS = 1000            # >= 1us between packets
TIMING_DEFAULT_LATENESS_NS = 50_000_000     # 50ms grace
TIMING_DEFAULT_BALANCE_NS = 10_000_000      # +/-10ms jitter band
TIMING_CERTAINTY_WINDOW = 64


class Timing:
    """Per-connection timing state. Must match http3_timing.c behavior."""

    def __init__(self) -> None:
        self.min_gap_ns = TIMING_DEFAULT_MIN_GAP_NS
        self.lateness_ns = TIMING_DEFAULT_LATENESS_NS
        self.balance_ns = TIMING_DEFAULT_BALANCE_NS
        self.have_last = False
        self.last_arrival_ns = 0
        self.mean_gap_ns = 0.0
        self.observed = 0
        self.certainty = 1.0  # optimistic until evidence says otherwise

    def configure(self, min_gap_ns: int = 0, lateness_ns: int = 0, balance_ns: int = 0) -> None:
        if min_gap_ns:
            self.min_gap_ns = min_gap_ns
        if lateness_ns:
            self.lateness_ns = lateness_ns
        if balance_ns:
            self.balance_ns = balance_ns

    def observe(self, arrival_ns: int, deadline_ns: int = 0) -> int:
        flags = TIMING_OK
        # ON TIME
        if deadline_ns and arrival_ns > deadline_ns + self.lateness_ns:
            flags |= TIMING_LATE
        if self.have_last:
            gap = arrival_ns - self.last_arrival_ns
            if gap < 0:
                gap = 0
            # MAX SPEED
            if gap < self.min_gap_ns:
                flags |= TIMING_OVER_RATE
            # BALANCED (skip the first gap; mean not yet established)
            if self.observed >= 2:
                dev = abs(gap - self.mean_gap_ns)
                if dev > self.balance_ns:
                    flags |= TIMING_UNBALANCED
            # update running mean gap (EWMA, alpha = 1/window)
            alpha = 1.0 / TIMING_CERTAINTY_WINDOW
            if self.observed == 1:
                self.mean_gap_ns = float(gap)
            else:
                self.mean_gap_ns += alpha * (float(gap) - self.mean_gap_ns)
        # CARRIER CERTAINTY: EWMA of "clean packet"
        w = 1.0 / TIMING_CERTAINTY_WINDOW
        clean = 1.0 if flags == TIMING_OK else 0.0
        self.certainty += w * (clean - self.certainty)
        self.certainty = max(0.0, min(1.0, self.certainty))
        self.last_arrival_ns = arrival_ns
        self.have_last = True
        self.observed += 1
        return flags



# ---- Capability-negotiation handshake (mirrors http3_handshake.{h,c}) -------
# Two peers advertise a capability bitmask (cumulative levels L1..L4); the
# handshake deterministically selects the highest common level, with a baseline
# (L1) fallback so an older/not-yet-updated router runs the modest baseline
# until it advertises more. Offers are MAC-backed. The bitmask is neutral: it
# names supported protocol tiers only (no national/geographic/identity meaning).
CAP_NONE = 0x00
CAP_L1_BASE = 0x01     # baseline: envelope + integrity gate
CAP_L2_PERLEG = 0x02   # per-leg MSS / path-MTU sizing
CAP_L3_PACING = 0x04   # timing-aware pacing (max-speed/balance)
CAP_L4_ECHO = 0x08     # echo-acknowledged, deadline-aware delivery
CAP_BASELINE = CAP_L1_BASE
CAP_ALL = CAP_L1_BASE | CAP_L2_PERLEG | CAP_L3_PACING | CAP_L4_ECHO

_CAP_LEVEL_NAMES = {
    CAP_NONE: "NONE",
    CAP_L1_BASE: "L1_BASELINE",
    CAP_L2_PERLEG: "L2_PERLEG",
    CAP_L3_PACING: "L3_PACING",
    CAP_L4_ECHO: "L4_ECHO",
}


def cap_level_name(level: int) -> str:
    return _CAP_LEVEL_NAMES.get(level, "MIXED")


def _offer_mac(caps: int, key: bytes) -> int:
    # Domain tag "H3CP" + caps big-endian (8 bytes); must match http3_handshake.c.
    msg = b"H3CP" + struct.pack(">I", caps & 0xFFFFFFFF)
    return siphash24(key, msg)


@dataclass
class CapOffer:
    """A peer's capability offer: the advertised bitmask + a MAC over it."""

    capabilities: int
    mac: int = 0

    @staticmethod
    def make(capabilities: int, key: bytes) -> "CapOffer":
        caps = (capabilities | CAP_BASELINE) & 0xFFFFFFFF
        return CapOffer(capabilities=caps, mac=_offer_mac(caps, key))

    def verify(self, key: bytes) -> bool:
        return _offer_mac(self.capabilities, key) == self.mac


def handshake_negotiate(local_caps: int, remote_caps: int) -> int:
    """Highest single level present in both capability sets (baseline fallback).
    Returns CAP_NONE only if a peer lacks the baseline (non-conforming)."""
    common = local_caps & remote_caps
    if not (common & CAP_BASELINE):
        return CAP_NONE
    if common & CAP_L4_ECHO:
        return CAP_L4_ECHO
    if common & CAP_L3_PACING:
        return CAP_L3_PACING
    if common & CAP_L2_PERLEG:
        return CAP_L2_PERLEG
    return CAP_L1_BASE


def handshake_resolve(local: CapOffer, remote: CapOffer, key: bytes):
    """Verify both offers' MACs under key, then negotiate. Returns the agreed
    level, or raises ValueError if either MAC fails (as the C -1 return)."""
    if not local.verify(key) or not remote.verify(key):
        raise ValueError("capability offer MAC failed")
    return handshake_negotiate(local.capabilities, remote.capabilities)