frutebox-node 0.1.0__py3-none-any.whl

frutebox/pqctransport.py

@@ -0,0 +1,660 @@
+"""Hybrid post-quantum transport — content is never plaintext on a wire (file 22).
+
+THE RULE (owner, non-negotiable, universal)
+For every user, free or paid: the prompt and any attached files are ALWAYS encrypted when they
+cross a network, on every hop. Only ROUTING METADATA may be in the clear — model, tier, region,
+latency class, job id, size hint, jurisdiction class. Nothing that reveals content.
+
+THE THREAT: HARVEST NOW, DECRYPT LATER
+An adversary can record today's traffic and decrypt it once a quantum computer exists. That is
+why post-quantum key exchange has to be the default NOW rather than an upgrade later: traffic
+sent today is already exposed to a machine that does not exist yet.
+
+WHY HYBRID AND NOT PQC ALONE (22-B1)
+`X25519MLKEM768` is X25519 ECDH **and** ML-KEM-768 (FIPS 203), with both shared secrets mixed
+into one key. It is safe if either primitive falls: a quantum break of X25519 leaves ML-KEM, and
+an implementation flaw in early ML-KEM leaves X25519. This is what Chrome, Cloudflare and AWS
+deployed in 2025-26.
+
+ML-KEM comes from `cryptography`'s OpenSSL binding, which is what `libraries.md` names
+("OpenSSL 3.5 / liboqs", and note 7 prefers OpenSSL-native PQC). No new dependency, no
+home-rolled lattice code.
+
+NO DOWNGRADE (22-B5)
+A peer that cannot negotiate the hybrid suite is REFUSED. There is no classical-only fallback for
+a content-bearing hop — a downgrade path is the vulnerability, because an attacker who can force
+the downgrade gets the plaintext-equivalent they wanted. Suites are config-named
+(`FRUTEBOX_PQC_KEM`, `FRUTEBOX_PQC_SIG`; the `STEVAI_` spellings are still read) so the
+algorithm can advance, never descend.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import mlkem, x25519
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM, ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from .envvars import env as envvar
+
+#: The negotiated suite. Config-named for crypto-agility (22-B5) — may advance, never descend.
+KEM_SUITE = envvar("PQC_KEM", "X25519MLKEM768")
+SIG_SUITE = envvar("PQC_SIG", "ML-DSA-65")
+
+#: Payload AEAD. Both are 256-bit symmetric, which is already quantum-resistant: Grover only
+#: halves the effective strength, leaving 128 bits.
+AEAD = envvar("PQC_AEAD", "AES-256-GCM")
+
+#: Suites we will negotiate. Anything else is refused rather than downgraded to.
+#: X25519MLKEM768 is the deployed default (22-B1). The 1024 variant is the same HYBRID construction
+#: with ML-KEM-1024 in place of ML-KEM-768, so it is an ADVANCE and belongs here — a floor that
+#: rejected it would have been a ceiling, and 22-B5's whole point is that the suite can move up.
+#: What is NOT here, and cannot be configured, is anything classical-only.
+SUPPORTED_KEMS = frozenset({"X25519MLKEM768", "X25519MLKEM1024"})
+SUPPORTED_AEADS = frozenset({"AES-256-GCM", "ChaCha20-Poly1305"})
+#: 22-B2's signature families. ML-DSA (FIPS 204) by default, SLH-DSA (FIPS 205) as the conservative
+#: hash-based alternative. A classical-only signature is not on this list and cannot be configured.
+SUPPORTED_SIGS = frozenset({"ML-DSA-65", "ML-DSA-87", "SLH-DSA-SHA2-128s"})
+
+
+#: KEMs and signatures that are CLASSICAL ONLY. Naming one of these is always a downgrade, whatever
+#: else changes, so they are refused by name — a denylist rather than an allowlist, and that choice is
+#: the whole design of the floor below.
+CLASSICAL_ONLY = frozenset({
+    "X25519", "X448", "P-256", "P-384", "P-521", "ECDH", "ECDHE", "DH", "RSA", "RSA-OAEP",
+    "Ed25519", "Ed448", "ECDSA", "RSA-PSS", "RSASSA-PKCS1-v1_5",
+})
+
+
+def _assert_suite_is_not_a_downgrade() -> None:
+    """OUR OWN configured suite must not be a classical one. Checked at import.
+
+    ── THE HOLE THIS CLOSES ─────────────────────────────────────────────────────────────────────────
+    `negotiate` checked the PEER's offer and never checked ours. The selection line read
+
+        kem = KEM_SUITE if KEM_SUITE in offered else sorted(offered & SUPPORTED_KEMS)[0]
+
+    so with `FRUTEBOX_PQC_KEM=X25519` — classical only — against a peer offering BOTH suites, the first
+    clause matched and A CLASSICAL KEM WAS SELECTED for a content-bearing hop. The peer check passed,
+    nothing raised, and the channel was quantum-vulnerable by configuration alone.
+
+    ── WHY A DENYLIST AND NOT AN ALLOWLIST ──────────────────────────────────────────────────────────
+    An allowlist was the first attempt and it is wrong, because the done-criterion asks for two things
+    at once: the suite "swaps without code changes" AND "still refuses non-PQC". An allowlist fails the
+    first — adopting a genuinely new NIST suite would need this file edited, which is exactly the
+    inflexibility 22-B5 made these names configurable to avoid. It also broke a test that uses
+    placeholder names to prove which environment spelling wins, and that test was right to.
+    
+    A denylist gets both: a name we have never heard of passes here (and still cannot be NEGOTIATED,
+    see `negotiate` — the floor that matters on the wire is the intersection with `SUPPORTED_KEMS`),
+    while a classical family is refused by name with certainty and no false positives.
+
+    FAILING AT IMPORT IS THE POINT for the classical case. The alternative, refusing per-connection,
+    means a typo takes the fleet down one confusing request at a time; this way it is one named error
+    before anything is served — the same choice `gateway.py` makes for the territory filter.
+    """
+    for var, value, kind in (("FRUTEBOX_PQC_KEM", KEM_SUITE, "key exchange"),
+                             ("FRUTEBOX_PQC_SIG", SIG_SUITE, "signature")):
+        if value in CLASSICAL_ONLY:
+            raise DowngradeRefused(
+                f"{var} is {value!r}, which is a CLASSICAL-ONLY {kind}. 22-B5 allows this to advance, "
+                f"never to descend: a content-bearing hop is not served over a suite weaker than "
+                f"hybrid post-quantum. Refusing to start.")
+    if AEAD not in SUPPORTED_AEADS:
+        # The AEAD is different in kind: the code must actually implement it to encrypt anything, so
+        # there is no "unknown but fine" case and an allowlist is correct here.
+        raise DowngradeRefused(
+            f"FRUTEBOX_PQC_AEAD is {AEAD!r}, which is not one of {sorted(SUPPORTED_AEADS)}. "
+            f"Refusing to start rather than silently falling back to a suite nobody chose.")
+
+
+_assert_suite_is_not_a_downgrade()
+
+#: Routing metadata that may travel in the clear (22-A2). Nothing here reveals content.
+PUBLIC_METADATA_KEYS = frozenset({
+    "job_id", "model", "tier", "region", "latency_class", "size_hint",
+    "jurisdiction_class", "redundant", "allowed_jurisdictions",
+})
+
+_HKDF_INFO = b"frutebox/transport/v1"
+
+
+class DowngradeRefused(Exception):
+    """A peer offered something weaker than the hybrid PQC suite. Content-bearing hops fail
+    closed rather than negotiate down."""
+
+
+class TransportError(Exception):
+    """Sealing or opening failed."""
+
+
+def negotiate(peer_kems, peer_aeads=None) -> Tuple[str, str]:
+    """Agree a suite with a peer, or refuse (22-B5).
+
+    Deliberately not "pick the best mutually supported" — there is exactly one acceptable KEM
+    family, and a peer without it does not get a weaker channel, it gets no channel.
+    """
+    offered = set(peer_kems or ())
+    if not (offered & SUPPORTED_KEMS):
+        raise DowngradeRefused(
+            f"peer offers {sorted(offered) or ['nothing']}; this hop carries content and "
+            f"requires one of {sorted(SUPPORTED_KEMS)}. Refusing rather than downgrading.")
+    # INTERSECTED WITH `SUPPORTED_KEMS`, not merely with what the peer offered — and this is the floor
+    # that matters on the wire. This line used to read `KEM_SUITE if KEM_SUITE in offered`, so a
+    # configured CLASSICAL suite was selected whenever the peer happened to offer it alongside the
+    # hybrid one: the peer check passed and the channel was quantum-vulnerable by configuration alone.
+    #
+    # It is also what makes the import-time DENYLIST safe rather than lax: a suite nobody has
+    # implemented can be named in the environment and still cannot be negotiated, because it is not in
+    # this set.
+    acceptable = offered & SUPPORTED_KEMS
+    kem = KEM_SUITE if KEM_SUITE in acceptable else sorted(acceptable)[0]
+
+    aeads = set(peer_aeads or SUPPORTED_AEADS)
+    usable = aeads & SUPPORTED_AEADS
+    if not usable:
+        raise DowngradeRefused(f"peer offers no acceptable AEAD; need {sorted(SUPPORTED_AEADS)}")
+    # Same shape: `usable` is already intersected with SUPPORTED_AEADS, so a configured AEAD outside
+    # it cannot be selected — it falls through to an acceptable one rather than being honoured.
+    aead = AEAD if AEAD in usable else sorted(usable)[0]
+    return kem, aead
+
+
+@dataclass
+class HybridPublic:
+    """What a peer publishes so others can encrypt to it."""
+    x25519: bytes
+    mlkem: bytes
+
+    def encode(self) -> bytes:
+        return self.x25519 + self.mlkem
+
+    @staticmethod
+    def decode(raw: bytes) -> "HybridPublic":
+        if len(raw) != 32 + 1184:
+            raise TransportError(f"hybrid public key must be {32 + 1184} bytes, got {len(raw)}")
+        return HybridPublic(x25519=raw[:32], mlkem=raw[32:])
+
+
+@dataclass
+class HybridPrivate:
+    """An EPHEMERAL recipient keypair. Ephemeral is the point: forward secrecy means recording
+    today's traffic and stealing the key tomorrow still yields nothing (22-B3)."""
+    x25519: x25519.X25519PrivateKey
+    mlkem: mlkem.MLKEM768PrivateKey
+
+    def public(self) -> HybridPublic:
+        return HybridPublic(
+            x25519=self.x25519.public_key().public_bytes_raw(),
+            mlkem=self.mlkem.public_key().public_bytes_raw(),
+        )
+
+
+def generate() -> HybridPrivate:
+    """A fresh ephemeral hybrid keypair."""
+    return HybridPrivate(x25519=x25519.X25519PrivateKey.generate(),
+                         mlkem=mlkem.MLKEM768PrivateKey.generate())
+
+
+def _derive(x_secret: bytes, pq_secret: bytes, salt: bytes, info: bytes = _HKDF_INFO) -> bytes:
+    """Mix BOTH shared secrets into one key.
+
+    Concatenating and running them through HKDF is what makes the construction hybrid: the output
+    is unpredictable unless an attacker breaks BOTH primitives. Using either alone, or XOR-ing
+    them, would forfeit that.
+
+    `info` DOMAIN-SEPARATES the two constructions that use this. A one-shot `seal` and a
+    `begin_session` handshake can hold the same (ephemeral key, KEM ciphertext) pair, and if
+    both derived the same key from it, a one-shot frame and a session frame could be made to
+    share a key — and the session's nonces are counters starting at zero, so that is a nonce
+    collision across constructions. Different info, different key, no crossover.
+    """
+    return HKDF(algorithm=hashes.SHA256(), length=32, salt=salt,
+                info=info).derive(x_secret + pq_secret)
+
+
+@dataclass
+class Sealed:
+    """Ciphertext plus the public handshake material needed to open it.
+
+    `metadata` rides in the CLEAR and is authenticated (AAD) but never encrypted — it is what
+    routing needs, and it is checked so it cannot be tampered with in flight.
+    """
+    kem: str
+    aead: str
+    sender_x25519: bytes
+    kem_ciphertext: bytes
+    nonce: bytes
+    ciphertext: bytes
+    metadata: dict
+
+
+def _aead(name: str, key: bytes):
+    if name == "AES-256-GCM":
+        return AESGCM(key)
+    if name == "ChaCha20-Poly1305":
+        return ChaCha20Poly1305(key)
+    raise DowngradeRefused(f"AEAD {name!r} is not acceptable for a content-bearing hop")
+
+
+def _aad(metadata: dict, kem: str, aead: str) -> bytes:
+    """Metadata is authenticated even though it is public, so a relay cannot re-point a job at a
+    different model or region without the recipient noticing."""
+    import json
+    return json.dumps({"kem": kem, "aead": aead, "md": metadata},
+                      sort_keys=True, separators=(",", ":")).encode()
+
+
+def check_metadata(metadata: dict) -> dict:
+    """Refuse to put anything content-revealing in the clear (22-A2).
+
+    Enforced rather than documented: the difference between "only routing metadata is public" and
+    "only routing metadata is public unless a caller adds more" is the whole guarantee.
+    """
+    extra = set(metadata or {}) - PUBLIC_METADATA_KEYS
+    if extra:
+        raise TransportError(
+            f"these keys are not routing metadata and must not travel in the clear: "
+            f"{sorted(extra)}. Put them in the sealed payload.")
+    return dict(metadata or {})
+
+
+def seal(plaintext: bytes, recipient: HybridPublic, *, metadata: Optional[dict] = None,
+         kem: str = "", aead: str = "") -> Sealed:
+    """Encrypt content to a recipient's hybrid public key."""
+    kem = kem or KEM_SUITE
+    aead = aead or AEAD
+    if kem not in SUPPORTED_KEMS:
+        raise DowngradeRefused(f"KEM {kem!r} is not hybrid post-quantum")
+    md = check_metadata(metadata or {})
+
+    eph = x25519.X25519PrivateKey.generate()
+    x_secret = eph.exchange(x25519.X25519PublicKey.from_public_bytes(recipient.x25519))
+    pq_secret, kem_ct = mlkem.MLKEM768PublicKey.from_public_bytes(recipient.mlkem).encapsulate()
+
+    sender_pub = eph.public_key().public_bytes_raw()
+    key = _derive(x_secret, pq_secret, salt=sender_pub + kem_ct[:32])
+    nonce = os.urandom(12)
+    ct = _aead(aead, key).encrypt(nonce, plaintext, _aad(md, kem, aead))
+    return Sealed(kem=kem, aead=aead, sender_x25519=sender_pub, kem_ciphertext=kem_ct,
+                  nonce=nonce, ciphertext=ct, metadata=md)
+
+
+def open_sealed(sealed: Sealed, recipient: HybridPrivate) -> bytes:
+    """Decrypt at the authorized boundary (22-A3). Raises if anything was tampered with."""
+    if sealed.kem not in SUPPORTED_KEMS:
+        raise DowngradeRefused(f"refusing to open a {sealed.kem!r} channel")
+    try:
+        x_secret = recipient.x25519.exchange(
+            x25519.X25519PublicKey.from_public_bytes(sealed.sender_x25519))
+        pq_secret = recipient.mlkem.decapsulate(sealed.kem_ciphertext)
+        key = _derive(x_secret, pq_secret, salt=sealed.sender_x25519 + sealed.kem_ciphertext[:32])
+        return _aead(sealed.aead, key).decrypt(
+            sealed.nonce, sealed.ciphertext, _aad(sealed.metadata, sealed.kem, sealed.aead))
+    except DowngradeRefused:
+        raise
+    except Exception as e:
+        raise TransportError(f"could not open sealed content: {type(e).__name__}") from e
+
+
+def wire_format(sealed: Sealed) -> dict:
+    """What actually goes on the wire. Content is base64 ciphertext; metadata is readable."""
+    import base64
+
+    b64 = lambda b: base64.b64encode(b).decode()
+    return {
+        "v": 1,
+        "kem": sealed.kem,
+        "aead": sealed.aead,
+        "epk": b64(sealed.sender_x25519),
+        "kct": b64(sealed.kem_ciphertext),
+        "n": b64(sealed.nonce),
+        "ct": b64(sealed.ciphertext),
+        "md": sealed.metadata,
+    }
+
+
+def from_wire(frame: dict) -> Sealed:
+    import base64
+
+    d = lambda s: base64.b64decode(s)
+    return Sealed(kem=str(frame.get("kem")), aead=str(frame.get("aead")),
+                  sender_x25519=d(frame["epk"]), kem_ciphertext=d(frame["kct"]),
+                  nonce=d(frame["n"]), ciphertext=d(frame["ct"]),
+                  metadata=dict(frame.get("md") or {}))
+
+
+# ── PER-STREAM SESSIONS ──────────────────────────────────────────────────────────────────────
+# WHY THIS EXISTS (owner's ruling on the measured streaming cost)
+# `seal()` mints a fresh X25519 ephemeral AND a fresh ML-KEM encapsulation for every frame. On a
+# one-shot frame — a job, an embed reply — that is the right shape and the cost is invisible. On
+# a STREAM it is not: measured at +1703 B and ~0.8 ms per chunk, a 500-token completion carrying
+# 2 KiB of answer paid 400 ms of CPU and 831 KiB of handshake to protect 2 KiB. The owner ruled:
+# "result frames — take the per-stream session key. 400 ms and 831 KiB to protect 2 KiB is not a
+# cost worth paying for the same guarantee. The guarantee does not change: no plaintext on the
+# wire, ever."
+#
+# IT IS THE SAME GUARANTEE, AND THIS IS WHY.
+# Every frame of a stream encapsulates to the SAME recipient key — one per-process ephemeral that
+# lives for the life of that process. Forward secrecy is a property of that key's LIFETIME, not
+# of how many times anyone encapsulates to it: an attacker who recovers the recipient's private
+# key opens every frame sealed to it, whether they were sealed with one KEM ciphertext or with
+# two thousand. So per-frame KEM buys nothing the key's lifetime does not already give, and one
+# handshake per stream costs nothing the guarantee needs.
+#
+# WHAT IT DOES CHANGE — AND IT IS THE WHOLE RISK — IS THE NONCE.
+# A one-shot seal has a fresh key per frame, so `os.urandom(12)` is safe. A session REUSES one
+# AES-GCM key across every frame, and under a reused key a repeated nonce is catastrophic: it
+# leaks the XOR of the two plaintexts and hands over the authentication key, so an attacker can
+# forge. At 12 random bytes the birthday bound puts a collision within reach of a long-lived
+# session, and "we'll just be careful" is not a property. So the nonce is a COUNTER, and the
+# counter is enforced structurally at both ends rather than documented:
+#   * the nonce IS the sequence number — it is not carried on the wire at all, so there is no
+#     field for an attacker to vary independently of the seq the AAD commits to;
+#   * `seal_frame` refuses a sequence it has already used, or any sequence at or below the last
+#     one it sealed, and burns the number BEFORE encrypting, so even a failed encrypt cannot
+#     hand the same nonce back;
+#   * `seal_frame` refuses to run off the end of the counter's range rather than wrapping;
+#   * `open_frame` REJECTS a replayed sequence and one that arrives further out of order than
+#     `REPLAY_WINDOW`, instead of decrypting it — a receiver that accepts a replay makes the
+#     sender's discipline worthless;
+#   * a frame belongs to exactly one session: the session id is checked, and it is mixed into
+#     the key derivation as well, so a frame from another session cannot open here.
+
+#: The per-session identifier. 16 random bytes: it names the session on the wire, is committed to
+#: by the AAD, and is mixed into the key so two sessions cannot collide even if a KEM
+#: implementation ever repeated a ciphertext.
+SESSION_ID_BYTES = 16
+
+#: The counter's range. The nonce is 12 bytes: 4 reserved zero bytes and this counter big-endian,
+#: so a sequence number is a nonce and nothing else can be. Running out is refused, never wrapped
+#: — wrapping is exactly the nonce reuse this whole construction exists to make impossible.
+MAX_SEQ = 2 ** 64 - 1
+
+#: How far out of order a frame may arrive and still be opened. A WebSocket delivers in order, so
+#: in production this is slack, not a requirement — but a receiver with no window at all either
+#: has to accept everything (a replay is then free) or reject anything non-consecutive (one
+#: dropped frame ends the stream). Anything older than this is refused rather than decrypted.
+REPLAY_WINDOW = 64
+
+_HKDF_SESSION_INFO = b"frutebox/transport/session/v1"
+
+
+class NonceReuse(TransportError):
+    """A sender asked for a sequence number it has already used on this session.
+
+    Refused rather than honoured: under a reused AES-GCM key a repeated nonce leaks the XOR of
+    both plaintexts and the authentication key with it. There is no degraded mode here — the
+    caller gets an exception and the frame is not sealed.
+    """
+
+
+class ReplayRefused(TransportError):
+    """A receiver was handed a sequence it has already accepted, or one older than the window.
+
+    This is refused BEFORE the AEAD is asked to decrypt. A receiver that quietly opens a replay
+    turns the sender's counter discipline into decoration.
+    """
+
+
+@dataclass
+class SessionHandshake:
+    """The public half of a session: what the peer needs to derive the same key, once.
+
+    Exactly the material a one-shot `Sealed` carries per frame — an ephemeral X25519 public key
+    and an ML-KEM ciphertext — sent once for the whole stream instead of once per frame.
+    """
+    kem: str
+    aead: str
+    session_id: bytes
+    sender_x25519: bytes
+    kem_ciphertext: bytes
+
+
+@dataclass
+class SessionFrame:
+    """One frame on an established session: a sequence number and a ciphertext.
+
+    No key material, no nonce and no algorithm names — the session already fixed all of those,
+    and a field is a thing an attacker can change. `metadata` rides in the clear and is
+    authenticated, exactly as it is on a one-shot `Sealed`.
+    """
+    session_id: bytes
+    seq: int
+    ciphertext: bytes
+    metadata: dict
+
+
+def _session_nonce(seq: int) -> bytes:
+    """The nonce for a sequence number, and the only way a session nonce is ever produced.
+
+    There is no random path and no second construction: a nonce is a function of the sequence
+    number, so "did this session ever reuse a nonce" is answerable by looking at the counter.
+    """
+    if not isinstance(seq, int) or isinstance(seq, bool) or seq < 0 or seq > MAX_SEQ:
+        raise TransportError(f"sequence number out of range for a session nonce: {seq!r}")
+    return b"\x00\x00\x00\x00" + seq.to_bytes(8, "big")
+
+
+def _session_aad(session_id: bytes, seq: int, kem: str, aead: str, metadata: dict) -> bytes:
+    """What the AEAD authenticates but does not encrypt.
+
+    The SEQUENCE NUMBER is in here, which is the point. Without it a frame could be renumbered on
+    the path — and since the nonce is derived from the number, a renumbered frame would be
+    decrypted under a different nonce and fail confusingly rather than be rejected as the
+    tampering it is. The session id is here too, so a frame cannot be moved between sessions.
+    """
+    import json
+    return json.dumps({"kem": kem, "aead": aead, "sid": session_id.hex(), "seq": seq,
+                       "md": metadata}, sort_keys=True, separators=(",", ":")).encode()
+
+
+class Session:
+    """One established key, used for many frames — with the counter discipline that makes that safe.
+
+    A session is created at one end by `begin_session` and at the other by `accept_session`. Both
+    ends get the same key; each keeps its own counters, because the two directions of a stream are
+    not the same stream. In this codebase a session carries one direction (the node's answer home),
+    so one end only ever seals and the other only ever opens.
+    """
+
+    def __init__(self, key: bytes, kem: str, aead: str, session_id: bytes,
+                 handshake: Optional[SessionHandshake] = None):
+        self._key = key
+        self.kem = kem
+        self.aead = aead
+        self.session_id = session_id
+        #: Set on the INITIATOR only: what the peer needs to accept this session. The sender puts
+        #: it on the first frame and never again — that is where the saving comes from.
+        self.handshake = handshake
+        #: The highest sequence this session has SEALED. Starts below zero so the first frame can
+        #: legitimately be sequence 0, and only ever goes up.
+        self._sent_high = -1
+        #: The highest sequence this session has OPENED, and the window of ones already accepted.
+        self._seen_high = -1
+        self._seen: set = set()
+
+    # -- sending ------------------------------------------------------------------------------
+    def seal_frame(self, plaintext: bytes, seq: Optional[int] = None, *,
+                   metadata: Optional[dict] = None) -> SessionFrame:
+        """Encrypt one frame under the session key.
+
+        `seq` defaults to the next number this session has not used, which is what every caller
+        in this codebase does; passing one explicitly is allowed so a caller with its own frame
+        numbering can use it, and is checked exactly as hard. A number at or below the last one
+        sealed raises `NonceReuse` — including the same number twice, which is the catastrophic
+        case this method exists to make impossible.
+        """
+        if seq is None:
+            seq = self._sent_high + 1
+        if not isinstance(seq, int) or isinstance(seq, bool):
+            raise TransportError(f"a sequence number must be an int, got {type(seq).__name__}")
+        if seq < 0:
+            raise TransportError(f"a sequence number may not be negative: {seq}")
+        if seq <= self._sent_high:
+            raise NonceReuse(
+                f"sequence {seq} has already been used on this session (last sealed: "
+                f"{self._sent_high}). Reusing a nonce under a reused AES-GCM key leaks the XOR "
+                f"of both plaintexts and the authentication key with it — refusing.")
+        if seq > MAX_SEQ:
+            raise TransportError(
+                f"this session has run out of sequence numbers ({MAX_SEQ}); start a new session "
+                f"rather than wrapping the counter, which would reuse a nonce.")
+        md = check_metadata(metadata or {})
+        # BURN THE NUMBER FIRST. If the encrypt below raises, the caller may well retry — and a
+        # retry that got the same sequence back would be the exact reuse this refuses above.
+        self._sent_high = seq
+        ct = _aead(self.aead, self._key).encrypt(
+            _session_nonce(seq), plaintext,
+            _session_aad(self.session_id, seq, self.kem, self.aead, md))
+        return SessionFrame(session_id=self.session_id, seq=seq, ciphertext=ct, metadata=md)
+
+    # -- receiving ----------------------------------------------------------------------------
+    def open_frame(self, frame: SessionFrame) -> bytes:
+        """Decrypt one frame, or refuse it. Never silently accepts a replay.
+
+        Order matters: the session and the sequence are checked BEFORE the AEAD is asked to do
+        anything, and the sequence is recorded as accepted only AFTER it authenticates — so a
+        forged frame cannot consume a sequence number and lock out the real one.
+        """
+        if not isinstance(frame, SessionFrame):
+            raise TransportError(f"expected a session frame, got {type(frame).__name__}")
+        if frame.session_id != self.session_id:
+            raise TransportError(
+                "this frame belongs to a different session; refusing to open it here")
+        seq = frame.seq
+        if not isinstance(seq, int) or isinstance(seq, bool) or seq < 0 or seq > MAX_SEQ:
+            raise ReplayRefused(f"frame carries an unusable sequence number: {seq!r}")
+        if seq in self._seen:
+            raise ReplayRefused(
+                f"sequence {seq} has already been accepted on this session — this is a replay")
+        if self._seen_high >= 0 and seq <= self._seen_high - REPLAY_WINDOW:
+            raise ReplayRefused(
+                f"sequence {seq} is more than {REPLAY_WINDOW} behind this session's highest "
+                f"({self._seen_high}); it is either a replay or far enough out of order that "
+                f"accepting it would mean giving up on detecting one")
+        try:
+            plaintext = _aead(self.aead, self._key).decrypt(
+                _session_nonce(seq), frame.ciphertext,
+                _session_aad(self.session_id, seq, self.kem, self.aead, frame.metadata))
+        except DowngradeRefused:
+            raise
+        except Exception as e:
+            raise TransportError(f"could not open sealed frame: {type(e).__name__}") from e
+        self._seen.add(seq)
+        self._seen_high = max(self._seen_high, seq)
+        # Keep the window bounded: a long stream is thousands of frames, and an unbounded set of
+        # accepted sequence numbers is a memory leak that grows with the user's answer.
+        self._seen = {s for s in self._seen if s > self._seen_high - REPLAY_WINDOW}
+        return plaintext
+
+
+def begin_session(recipient: HybridPublic, *, kem: str = "",
+                  aead: str = "") -> Tuple[Session, SessionHandshake]:
+    """Start a session to a recipient's hybrid public key. One handshake, then AEAD only.
+
+    Returns the session and the handshake the recipient needs. The handshake is public material —
+    an ephemeral public key and a KEM ciphertext, the same two fields `wire_format` already puts
+    in the clear on every one-shot frame — so it is not a secret. What it is NOT is optional:
+    without it the peer has no key, so it is sent on the session's first frame.
+    """
+    kem = kem or KEM_SUITE
+    aead = aead or AEAD
+    if kem not in SUPPORTED_KEMS:
+        raise DowngradeRefused(f"KEM {kem!r} is not hybrid post-quantum")
+    if aead not in SUPPORTED_AEADS:
+        raise DowngradeRefused(f"AEAD {aead!r} is not acceptable for a content-bearing hop")
+
+    eph = x25519.X25519PrivateKey.generate()
+    x_secret = eph.exchange(x25519.X25519PublicKey.from_public_bytes(recipient.x25519))
+    pq_secret, kem_ct = mlkem.MLKEM768PublicKey.from_public_bytes(recipient.mlkem).encapsulate()
+    sender_pub = eph.public_key().public_bytes_raw()
+    session_id = os.urandom(SESSION_ID_BYTES)
+    key = _derive(x_secret, pq_secret, salt=session_id + sender_pub + kem_ct[:32],
+                  info=_HKDF_SESSION_INFO)
+    handshake = SessionHandshake(kem=kem, aead=aead, session_id=session_id,
+                                 sender_x25519=sender_pub, kem_ciphertext=kem_ct)
+    return Session(key, kem, aead, session_id, handshake=handshake), handshake
+
+
+def accept_session(handshake: SessionHandshake, recipient: HybridPrivate) -> Session:
+    """Derive the other end of a session from its handshake and the recipient's private key."""
+    if handshake.kem not in SUPPORTED_KEMS:
+        raise DowngradeRefused(f"refusing to accept a {handshake.kem!r} session")
+    if handshake.aead not in SUPPORTED_AEADS:
+        raise DowngradeRefused(f"refusing to accept a session under AEAD {handshake.aead!r}")
+    if len(handshake.session_id) != SESSION_ID_BYTES:
+        raise TransportError(
+            f"a session id must be {SESSION_ID_BYTES} bytes, got {len(handshake.session_id)}")
+    try:
+        x_secret = recipient.x25519.exchange(
+            x25519.X25519PublicKey.from_public_bytes(handshake.sender_x25519))
+        pq_secret = recipient.mlkem.decapsulate(handshake.kem_ciphertext)
+    except Exception as e:
+        raise TransportError(f"could not accept this session: {type(e).__name__}") from e
+    key = _derive(x_secret, pq_secret,
+                  salt=handshake.session_id + handshake.sender_x25519
+                  + handshake.kem_ciphertext[:32], info=_HKDF_SESSION_INFO)
+    return Session(key, handshake.kem, handshake.aead, handshake.session_id)
+
+
+def session_handshake_wire(handshake: SessionHandshake) -> dict:
+    """The handshake as it travels. Public material only — no private key ever leaves here."""
+    import base64
+
+    b64 = lambda b: base64.b64encode(b).decode()
+    return {"v": 1, "kem": handshake.kem, "aead": handshake.aead,
+            "sid": b64(handshake.session_id), "epk": b64(handshake.sender_x25519),
+            "kct": b64(handshake.kem_ciphertext)}
+
+
+def session_handshake_from_wire(frame: dict) -> SessionHandshake:
+    import base64
+
+    d = lambda s: base64.b64decode(s)
+    return SessionHandshake(kem=str(frame.get("kem")), aead=str(frame.get("aead")),
+                            session_id=d(frame["sid"]), sender_x25519=d(frame["epk"]),
+                            kem_ciphertext=d(frame["kct"]))
+
+
+def session_wire_format(frame: SessionFrame, *,
+                        handshake: Optional[SessionHandshake] = None) -> dict:
+    """What a session frame puts on the wire.
+
+    No nonce field, deliberately: the nonce is the sequence number, so there is nothing for a
+    relay to vary independently of the number the AAD commits to. No `kem`/`aead` either — the
+    session fixed those at the handshake, and a per-frame algorithm name is a per-frame downgrade
+    offer. `hs` is present on the FIRST frame of a session and absent on every one after it,
+    which is the entire saving.
+    """
+    import base64
+
+    out = {"v": 1, "sid": base64.b64encode(frame.session_id).decode(), "seq": frame.seq,
+           "ct": base64.b64encode(frame.ciphertext).decode(), "md": frame.metadata}
+    if handshake is not None:
+        out["hs"] = session_handshake_wire(handshake)
+    return out
+
+
+def session_from_wire(frame: dict) -> SessionFrame:
+    import base64
+
+    seq = frame.get("seq")
+    if not isinstance(seq, int) or isinstance(seq, bool):
+        raise TransportError(f"a session frame needs an integer sequence number, got {seq!r}")
+    return SessionFrame(session_id=base64.b64decode(frame["sid"]), seq=seq,
+                        ciphertext=base64.b64decode(frame["ct"]),
+                        metadata=dict(frame.get("md") or {}))
+
+
+def is_session_frame(sealed: object) -> bool:
+    """Is this wire dict a session frame, or a one-shot `Sealed`?
+
+    Both forms are accepted on the reply path for the length of the cutover: a node on an older
+    build still seals each frame on its own, and a reader that could only take the new shape
+    would be the flag day the staging exists to avoid. The discriminator is `sid`, which only a
+    session frame carries.
+    """
+    return isinstance(sealed, dict) and bool(sealed.get("sid"))