hypermind 0.11.0__py3-none-any.whl

hypermind/wire.py

@@ -0,0 +1,897 @@
+"""COSE/CBOR envelope — Signed Statements, Receipts, Disputes.
+
+Implements `draft-hypermind-scitt-contested-claims-profile-00` wire shape.
+Encoding is RFC 8949 deterministic CBOR (§4.2). Every envelope
+discriminator is bound into the signed Sig_structure preimage
+(A-ALG-BOUND), preventing cross-version substitution attacks.
+
+Protected header label allocations (proposed IANA -65600..-65624):
+    -65601 record_type
+    -65602 namespace_id  (16-byte UUIDv7 of namespace policy root)
+    -65603 hlc           ([logical_ms, counter, node_id])
+    -65604 sig_alg_disc  (mirrors COSE alg=1; bound into preimage)
+    -65605 envelope_schema_hash  (BLAKE3 of CDDL)
+    -65606 wire_version  (= 0)
+    -65607 pq_required   (bool)
+    -65608 receipt_uncertainty  (RECEIPT only)
+    -65609 confirmer_set (SEAL only, ≥3)
+    -65610 dispute_state
+    -65611 protocol_version  (= 0; values ≥1 reserved for future profiles)
+    -65620 dispute_target_kid
+    -65621 dispute_subtype
+    -65622 bond_commitment
+    -65623 prior_dispute_chain
+    -65624 ramp_state
+    -65625 valid_from_hlc  (reserved, Belief State Layer §21)
+    -65626 valid_until_hlc (reserved, Belief State Layer §21)
+    -65627 mcp_provenance  (T1-03; MCP tool-call provenance)
+    -65628..-65629 reserved for Saga Workflow record types (T2)
+    -65630 rfp_id          (Contract-Net §27, T3)
+    -65631 bid_kid         (Contract-Net §27, T3)
+    -65632 winning_bid_kid (Contract-Net §27, T3)
+    -65633 award_signer_kids (Contract-Net §27, T3)
+    -65634 bidder_filter   (Contract-Net §27, T3)
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import secrets
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import cbor2
+
+from hypermind.crypto.hashing import blake3_32, sha256_kid
+from hypermind.crypto.hlc import HLC
+from hypermind.crypto.signing import (
+    ALG_ED25519,
+    ALG_MLDSA65_ED25519,
+    ED25519_PK_LEN,
+    Keypair,
+    verify_signature,
+)
+from hypermind.errors import ConformanceError, ProtocolVersionError
+from hypermind.uncertainty import Uncertainty
+
+# Standard COSE labels
+COSE_ALG = 1
+COSE_KID = 4
+
+# HyperMind extension labels
+HM_RECORD_TYPE = -65601
+HM_NAMESPACE_ID = -65602
+HM_HLC = -65603
+HM_SIG_ALG_DISC = -65604
+HM_ENVELOPE_SCHEMA_HASH = -65605
+HM_WIRE_VERSION = -65606
+HM_PQ_REQUIRED = -65607
+HM_RECEIPT_UNCERTAINTY = -65608
+HM_CONFIRMER_SET = -65609
+HM_DISPUTE_STATE = -65610
+HM_PROTOCOL_VERSION = -65611
+
+HM_DISPUTE_TARGET_KID = -65620
+HM_DISPUTE_SUBTYPE = -65621
+HM_BOND_COMMITMENT = -65622
+HM_PRIOR_DISPUTE_CHAIN = -65623
+HM_RAMP_STATE = -65624
+
+# P3-05: Reserved for Belief State Layer §21 — not yet normative
+HM_VALID_FROM_HLC = -65625  # reserved, Belief State Layer §21
+HM_VALID_UNTIL_HLC = -65626  # reserved, Belief State Layer §21
+
+# T1-03 (v0.10.1) — MCP tool-call provenance binding (spec §coordination-T1).
+# Carries the triple (calling_agent_kid, cap_token_root, request_kid) inside a
+# signed MCP JSON-RPC request envelope. The MCP server MUST reject any
+# `tools/call` whose request lacks this header. The label is reserved here so
+# every wire-label allocation lives in one place, even though MCP requests
+# travel as JSON-RPC (not COSE_Sign1) on the wire — the same numeric label
+# identifies the same semantic field on both transports.
+HM_MCP_PROVENANCE = -65627  # reserved, MCP tool-call provenance (T1-03)
+
+# T2 (Saga Workflow) reserves -65628 / -65629 — placeholder allocation so
+# T3 can pick non-colliding numeric labels even though T2 has not landed
+# yet. T2 is expected to add `WORKFLOW_STEP` and `WORKFLOW_COMPENSATE`
+# record types plus saga-id / step-index protected-header fields.
+HM_WORKFLOW_SAGA_ID = -65628  # reserved, Saga Workflow §coordination-T2
+HM_WORKFLOW_STEP_INDEX = -65629  # reserved, Saga Workflow §coordination-T2
+
+# T3 (Contract-Net Protocol §27) — RFP/Bid/Award/Dispute coordination.
+# These five record types ride on top of the existing SignedStatement
+# envelope; the new protected-header labels carry the tuple identifiers
+# so a verifier can reject a forged bid/award without parsing the payload.
+HM_RFP_ID = -65630  # Contract-Net rfp_id (32 bytes, sha256 of canonical RFP body)
+HM_BID_KID = -65631  # Contract-Net bid_kid (32 bytes, kid of the bid SignedStatement)
+HM_WINNING_BID_KID = -65632  # AWARD-only: kid of the winning bid
+HM_AWARD_SIGNER_KIDS = -65633  # AWARD-only: list of FROST signer kids (≥1)
+HM_BIDDER_FILTER = -65634  # RFP_OPEN-only: minimum-reputation floor + topic glob
+
+# T6-01 (v0.10.4) — Distributed swarm-trace propagation. Carries a W3C
+# TraceContext blob (16-byte trace_id || 8-byte span_id || 1-byte flags ||
+# optional 8-byte parent_span_id) inside the protected header so every
+# SignedStatement that emerges from a deliberation/workflow/RFP step can
+# be stitched into a single OTel span tree across hosts. Reserved here so
+# consumers that don't yet understand the label still preserve it round-
+# trip through canonical re-encoding (A-ALG-BOUND).
+HM_OTEL_TRACE_CONTEXT = -65635  # reserved, distributed swarm-trace (T6-01)
+
+#: Highest wire_version this build knows how to mint and parse, and the
+#: outbound default for newly-minted envelopes. Bumped to 2 in v0.9.x
+#: Phase 2 to register the namespace-lifecycle record types
+#: (NAMESPACE_CREATE / NAMESPACE_FOUNDING_ATTEST / NAMESPACE_INVITE /
+#: NAMESPACE_ACCEPT) and the `EncryptedStatement` payload schema (§23).
+WIRE_VERSION = 2
+
+#: Alias for callers that branch on the highest known wire version.
+WIRE_VERSION_LATEST = WIRE_VERSION
+
+#: Maximum size (in bytes) of a wire-format envelope. Envelopes larger than
+#: this are rejected at parse time before any CBOR decoding work. Bounds the
+#: cost of malformed/oversized inputs and keeps gossip-bus memory usage
+#: predictable. 65536 is comfortably above every legitimate signed statement
+#: shape in v0.x (largest = composite-PQ DISPUTE with full prior chain ≈ 6 KiB).
+MAX_ENVELOPE_BYTES = 65536
+
+# Wire-version cutover support (panel A2-2 task #3).
+#
+# During an overlap window between v0 and v1 the agent accepts any envelope
+# whose wire_version is in WIRE_VERSION_SUPPORTED but **prefers the newest**
+# for outbound traffic (= max of the set, currently == WIRE_VERSION). A new
+# version MUST be added to the supported set BEFORE flipping the default
+# WIRE_VERSION constant — this guarantees a graceful overlap.
+#
+# Why v1 is listed BEFORE the v1 CDDL ships (review issue #2 — intentional)
+# -----------------------------------------------------------------------
+# This is a deliberate dual-stack design, not a leak in the version gate.
+# Adding `1` to the supported set ahead of time is what makes the cutover
+# non-breaking: deployed v0 peers must already be willing to parse a v1
+# envelope BEFORE any peer starts emitting v1, otherwise the network
+# fractures the moment the first v1 sender appears. The "supported set
+# MUST be widened before flipping `WIRE_VERSION`" rule above is the
+# normative form of this requirement (panel A2-2 task #3).
+#
+# Security argument for why dual-listing is safe right now:
+# v1 currently shares the v0 envelope CDDL — `HM_ENVELOPE_SCHEMA_HASH` is
+# the same value for both versions. An adversary forging `wire_version=1`
+# on a payload that otherwise matches the v0 layout therefore changes
+# nothing observable: every other discriminator (record_type, namespace_id,
+# hlc, signature_alg, envelope_schema_hash, pq_required) is bound under
+# A-ALG-BOUND, the COSE_Sign1 signature covers the full protected map,
+# and `from_bytes` re-canonicalises the envelope and rejects on mismatch.
+# The version byte by itself does not unlock any new parser branch.
+#
+# When v1 introduces a NEW envelope shape (different CDDL), a separate
+# `HM_ENVELOPE_SCHEMA_HASH_V1` constant MUST be added and `from_bytes`
+# updated to dispatch on `(wire_version, envelope_schema_hash)` jointly.
+# The dual-stack acceptance test
+# `tests/test_wire.py::TestDualStackWireVersion::test_v1_envelope_accepted_at_parse_time`
+# pins today's "v1 round-trips through the v0 schema" property.
+WIRE_VERSION_SUPPORTED: set[int] = {0, 1, 2}
+
+#: New record type for the witness cosignatures that close a dispute under the
+#: k-of-n quorum rule (panel A2-2 / `HM-DISPUTE-QUORUM-001`).
+RECORD_DISPUTE_CLOSE_WITNESS = "DISPUTE_CLOSE_WITNESS"
+
+#: HyperMind protocol-version negotiation primitive (v0.5; ROADMAP §0.5.1–0.5.3).
+#: Distinct from `wire_version` — `wire_version` discriminates the COSE/CBOR
+#: envelope shape; `protocol_version` discriminates the higher-level profile
+#: rules (panel selection, dispute FSM transitions, reputation kernel formula,
+#: etc.). v0.x ships with `protocol_version=0`. Values ≥1 are reserved for
+#: future profiles negotiated via `min_protocol_version` namespace policy.
+PROTOCOL_VERSION = 0
+
+#: Set of protocol_version values accepted at parse time.  Add new values
+#: BEFORE flipping PROTOCOL_VERSION so existing peers can already parse
+#: newer envelopes (same dual-stack rationale as WIRE_VERSION_SUPPORTED).
+SUPPORTED_PROTOCOL_VERSIONS: set[int] = {0, 1}
+
+RecordType = Literal[
+    "SEAL",
+    "RECEIPT",
+    "DISPUTE",
+    "KEY_ROTATE",
+    "NAMESPACE_CREATE",
+    "NAMESPACE_FOUNDING_ATTEST",
+    "NAMESPACE_INVITE",
+    "NAMESPACE_ACCEPT",
+    "DISPUTE_CLOSE_WITNESS",
+    # P3-04: reserved record types for Belief State Layer §21 (no handler yet)
+    "cite_query",
+    "cite_resp",
+    # T2 (v0.10.2): durable workflow record types — reserved for the
+    # workflow engine to publish step + compensation records as signed
+    # statements once the network-mode wire path lands. The in-process
+    # workflow engine in src/hypermind/workflow/ already records steps
+    # via transparency.append_and_cosign() using these labels for the
+    # leaf-tag domain; reserving them on the wire keeps T3's parallel
+    # RFP record-type expansion conflict-free.
+    "WORKFLOW_STEP",
+    "WORKFLOW_COMPENSATE",
+    # T3 (v0.10.2): Contract-Net Protocol §27 (FIPA00029 lineage).
+    # RFP_OPEN advertises a job, BIDs come back, AWARD picks a winner
+    # under a FROST k-of-n quorum signature when consortium-signed,
+    # BID_REJECT records non-winning outcomes (and is also published to
+    # revoke an awarded bid after a successful dispute), BID_WITHDRAW
+    # lets a bidder pull out before AWARD. Numeric protected-header
+    # labels for these records are -65630..-65634 (see top-of-module
+    # docstring); they sit AFTER T2's -65628/-65629 reservation.
+    "RFP_OPEN",
+    "BID",
+    "AWARD",
+    "BID_REJECT",
+    "BID_WITHDRAW",
+]
+
+#: Record types that are gated on `wire_version >= 2`. v0/v1 envelopes
+#: carrying these record_types are rejected at parse time.
+V2_GATED_RECORD_TYPES: frozenset[str] = frozenset(
+    {
+        "NAMESPACE_CREATE",
+        "NAMESPACE_FOUNDING_ATTEST",
+        "NAMESPACE_INVITE",
+        "NAMESPACE_ACCEPT",
+    }
+)
+DisputeSubtype = Literal["OPEN", "ARGUE", "COUNTER", "FRIVOLOUS"]
+DisputeState = Literal[
+    "OPEN", "ARGUE", "COUNTER", "FRIVOLOUS", "CLOSED", "UNRESOLVED_PARTITION", "MEDIATE"
+]
+
+
+# A-ALG-BOUND: every discriminator that must be inside the signed
+# preimage. The verifier rejects pre-signature-check if any of these
+# is absent from the protected header.
+DISCRIMINATOR_LABELS = (
+    COSE_ALG,
+    HM_RECORD_TYPE,
+    HM_NAMESPACE_ID,
+    HM_HLC,
+    HM_SIG_ALG_DISC,
+    HM_ENVELOPE_SCHEMA_HASH,
+    HM_WIRE_VERSION,
+    HM_PQ_REQUIRED,
+    HM_PROTOCOL_VERSION,
+)
+
+
+# Canonical CDDL schema fingerprint — BLAKE3 of the published CDDL file
+# shipped in `hypermind/schemas/wire-v0.1.cddl`. Loaded once at import
+# time. The independent reference verifier ships its own copy of the
+# same CDDL bytes and must compute the same digest (enforced by
+# `tests/test_schema_hash_pinned.py`).
+# Read as bytes, then normalise CRLF → LF. Without normalisation, a Windows
+# checkout (where git may rewrite LF to CRLF without a .gitattributes pin)
+# would compute a different ENVELOPE_SCHEMA_HASH and reject every Appendix Z
+# conformance vector. The schema fingerprint must be platform-invariant.
+_CDDL_BYTES = (
+    (importlib.resources.files("hypermind") / "schemas" / "wire-v0.1.cddl")
+    .read_bytes()
+    .replace(b"\r\n", b"\n")
+)
+ENVELOPE_SCHEMA_HASH = blake3_32(_CDDL_BYTES)
+
+
+def _load_cddl(name: str) -> bytes:
+    """Load and CRLF-normalise a packaged CDDL file."""
+    return (
+        (importlib.resources.files("hypermind") / "schemas" / name)
+        .read_bytes()
+        .replace(b"\r\n", b"\n")
+    )
+
+
+# Per-record-type CDDL fingerprints registered for wire_version >= 2.
+# For v2 record_types whose payload has its own CDDL, the BLAKE3-256
+# digest of that payload schema is bound into the protected header
+# under HM_ENVELOPE_SCHEMA_HASH. v0/v1 record_types continue to carry
+# the envelope CDDL digest (`ENVELOPE_SCHEMA_HASH`) for backwards
+# compatibility — the v2 payload CDDL files were added by Phase 2 and
+# only apply to the new record types.
+_NAMESPACE_CREATE_CDDL = _load_cddl("namespace_create.cddl")
+_NAMESPACE_FOUNDING_ATTEST_CDDL = _load_cddl("namespace_founding_attest.cddl")
+_NAMESPACE_INVITE_CDDL = _load_cddl("namespace_invite.cddl")
+_NAMESPACE_ACCEPT_CDDL = _load_cddl("namespace_accept.cddl")
+_ENCRYPTED_STATEMENT_CDDL = _load_cddl("encrypted_statement.cddl")
+
+NAMESPACE_CREATE_SCHEMA_HASH = blake3_32(_NAMESPACE_CREATE_CDDL)
+NAMESPACE_FOUNDING_ATTEST_SCHEMA_HASH = blake3_32(_NAMESPACE_FOUNDING_ATTEST_CDDL)
+NAMESPACE_INVITE_SCHEMA_HASH = blake3_32(_NAMESPACE_INVITE_CDDL)
+NAMESPACE_ACCEPT_SCHEMA_HASH = blake3_32(_NAMESPACE_ACCEPT_CDDL)
+ENCRYPTED_STATEMENT_SCHEMA_HASH = blake3_32(_ENCRYPTED_STATEMENT_CDDL)
+
+#: Mapping record_type -> expected envelope_schema_hash for v2-gated
+#: records. Records not present here use the default envelope CDDL
+#: digest (`ENVELOPE_SCHEMA_HASH`).
+RECORD_TYPE_SCHEMA_HASHES: dict[str, bytes] = {
+    "NAMESPACE_CREATE": NAMESPACE_CREATE_SCHEMA_HASH,
+    "NAMESPACE_FOUNDING_ATTEST": NAMESPACE_FOUNDING_ATTEST_SCHEMA_HASH,
+    "NAMESPACE_INVITE": NAMESPACE_INVITE_SCHEMA_HASH,
+    "NAMESPACE_ACCEPT": NAMESPACE_ACCEPT_SCHEMA_HASH,
+}
+
+
+def expected_schema_hash(record_type: str) -> bytes:
+    """Return the BLAKE3-256 schema hash bound for a given record_type."""
+    return RECORD_TYPE_SCHEMA_HASHES.get(record_type, ENVELOPE_SCHEMA_HASH)
+
+
+Kid = bytes  # 32-byte content-addressed claim id
+
+
+def _det_cbor(obj: Any) -> bytes:
+    """RFC 8949 §4.2 deterministic CBOR encode."""
+    return cbor2.dumps(obj, canonical=True)
+
+
+def _count_raw_map_pairs(map_bytes: bytes) -> int:
+    """Count the number of (key, value) pairs declared in a top-level CBOR map.
+
+    Reads only the map header — does NOT walk the values. Used to detect
+    duplicate keys in the protected header: cbor2 silently merges duplicates
+    into a Python dict (last-wins), so comparing the *declared* pair count
+    against `len(decoded_dict)` reveals the attack. The major-type byte must
+    be 5 (map). Indefinite-length maps (0xbf) are rejected as non-canonical.
+    """
+    if not map_bytes:
+        raise ConformanceError("protected header is empty")
+    b0 = map_bytes[0]
+    major = b0 >> 5
+    if major != 5:
+        raise ConformanceError("protected header must be a CBOR map")
+    info = b0 & 0x1F
+    if info < 24:
+        return info
+    if info == 24:
+        return map_bytes[1]
+    if info == 25:
+        return int.from_bytes(map_bytes[1:3], "big")
+    if info == 26:
+        return int.from_bytes(map_bytes[1:5], "big")
+    if info == 27:
+        return int.from_bytes(map_bytes[1:9], "big")
+    # info == 31 -> indefinite length; non-canonical per RFC 8949 §4.2.
+    raise ConformanceError("indefinite-length map is not canonical CBOR")
+
+
+def canonical_sig_input(protected_map: dict[int, Any], payload: bytes) -> bytes:
+    """Build the COSE_Sign1 Sig_structure preimage.
+
+    Per RFC 9052 §4.4. Includes context "Signature1", protected, ext_aad
+    (empty), and payload. The protected map is encoded as deterministic
+    CBOR before being included (so re-ordering keys cannot produce a
+    different signature).
+    """
+    protected_bytes = _det_cbor(protected_map)
+    sig_structure = ["Signature1", protected_bytes, b"", payload]
+    return _det_cbor(sig_structure)
+
+
+def _check_a_alg_bound(protected_map: dict[int, Any]) -> None:
+    """A-ALG-BOUND: every discriminator MUST be in the protected map.
+
+    Reject pre-verify (not signature-error) if any is missing — this is
+    the JWT-`alg=none` / SAML-XML-signature-wrapping defence.
+    """
+    missing = [lbl for lbl in DISCRIMINATOR_LABELS if lbl not in protected_map]
+    if missing:
+        raise ConformanceError(
+            f"A-ALG-BOUND violation: missing discriminators {missing} from protected header",
+            telemetry={"event_type": "A_ALG_BOUND_VIOLATION", "missing": missing},
+        )
+
+    # Cross-check: COSE alg and sig_alg_disc must agree.
+    if protected_map[COSE_ALG] != protected_map[HM_SIG_ALG_DISC]:
+        raise ConformanceError(
+            f"A-ALG-BOUND violation: COSE alg={protected_map[COSE_ALG]} "
+            f"≠ sig_alg_disc={protected_map[HM_SIG_ALG_DISC]}",
+            telemetry={"event_type": "A_ALG_BOUND_VIOLATION_DISCRIMINATOR_MISMATCH"},
+        )
+
+
+def new_namespace_id() -> bytes:
+    """Generate a fresh namespace id (16 random bytes; UUIDv7-shaped)."""
+    return secrets.token_bytes(16)
+
+
+@dataclass
+class SignedStatement:
+    """A HyperMind Signed Statement (COSE_Sign1 with HyperMind extensions).
+
+    Wire form is `[protected_bytes, unprotected, payload, signature]`.
+
+    `issuer_kid` is always the 32-byte stable agent address (Ed25519
+    public-key half). For composite signatures (alg=-49) the full public
+    key (Ed25519 || ML-DSA-65 = 1984 bytes) is carried in the
+    unprotected header under key "issuer_pk_full" so verifiers can
+    validate the ML-DSA half without needing a key lookup service.
+    """
+
+    record_type: RecordType
+    namespace_id: bytes
+    hlc: HLC
+    issuer_kid: bytes
+    payload: bytes
+    signature: bytes
+    alg: int = ALG_ED25519
+    pq_required: bool = False
+    protocol_version: int = PROTOCOL_VERSION
+    issuer_pk_full: bytes = b""  # populated for composite alg
+    confirmer_set: list[bytes] = field(default_factory=list)
+    receipt_uncertainty: Uncertainty | None = None
+    dispute_state: DisputeState | None = None
+    # dispute fields (only populated for record_type == "DISPUTE"):
+    dispute_target_kid: bytes | None = None
+    dispute_subtype: DisputeSubtype | None = None
+    bond_commitment: dict[str, Any] | None = None
+    prior_dispute_chain: list[bytes] = field(default_factory=list)
+    ramp_state: dict[str, Any] | None = None
+    unprotected: dict[Any, Any] = field(default_factory=dict)
+    #: Wire-version of this envelope. Defaults to the newest version this
+    #: build prefers for outbound traffic. During an overlap window (panel
+    #: A2-2 task #3) `from_bytes` may parse any version in
+    #: `WIRE_VERSION_SUPPORTED` and round-trips preserve the original.
+    wire_version: int = WIRE_VERSION
+
+    # ---- construction ----------------------------------------------------
+
+    @classmethod
+    def sign(
+        cls,
+        *,
+        keypair: Keypair,
+        record_type: RecordType,
+        namespace_id: bytes,
+        hlc: HLC,
+        payload: bytes,
+        pq_required: bool = False,
+        protocol_version: int = PROTOCOL_VERSION,
+        confirmer_set: list[bytes] | None = None,
+        receipt_uncertainty: Uncertainty | None = None,
+        dispute_state: DisputeState | None = None,
+        dispute_target_kid: bytes | None = None,
+        dispute_subtype: DisputeSubtype | None = None,
+        bond_commitment: dict[str, Any] | None = None,
+        prior_dispute_chain: list[bytes] | None = None,
+        ramp_state: dict[str, Any] | None = None,
+        wire_version: int | None = None,
+    ) -> SignedStatement:
+        if wire_version is None:
+            wire_version = WIRE_VERSION
+        protected = cls._build_protected_header(
+            alg=keypair.alg,
+            record_type=record_type,
+            namespace_id=namespace_id,
+            hlc=hlc,
+            issuer_kid=keypair.kid,
+            pq_required=pq_required,
+            protocol_version=protocol_version,
+            confirmer_set=confirmer_set,
+            receipt_uncertainty=receipt_uncertainty,
+            dispute_state=dispute_state,
+            dispute_target_kid=dispute_target_kid,
+            dispute_subtype=dispute_subtype,
+            bond_commitment=bond_commitment,
+            prior_dispute_chain=prior_dispute_chain,
+            ramp_state=ramp_state,
+            wire_version=wire_version,
+        )
+        sig_input = canonical_sig_input(protected, payload)
+        signature = keypair.sign(sig_input)
+        issuer_pk_full = keypair.public_bytes if keypair.alg == ALG_MLDSA65_ED25519 else b""
+        return cls(
+            record_type=record_type,
+            namespace_id=namespace_id,
+            hlc=hlc,
+            issuer_kid=keypair.kid,
+            payload=payload,
+            signature=signature,
+            alg=keypair.alg,
+            pq_required=pq_required,
+            protocol_version=protocol_version,
+            issuer_pk_full=issuer_pk_full,
+            confirmer_set=list(confirmer_set or []),
+            receipt_uncertainty=receipt_uncertainty,
+            dispute_state=dispute_state,
+            dispute_target_kid=dispute_target_kid,
+            dispute_subtype=dispute_subtype,
+            bond_commitment=bond_commitment,
+            prior_dispute_chain=list(prior_dispute_chain or []),
+            ramp_state=ramp_state,
+            wire_version=wire_version,
+        )
+
+    # ---- header construction --------------------------------------------
+
+    @staticmethod
+    def _build_protected_header(
+        *,
+        alg: int,
+        record_type: RecordType,
+        namespace_id: bytes,
+        hlc: HLC,
+        issuer_kid: bytes,
+        pq_required: bool,
+        protocol_version: int,
+        confirmer_set: list[bytes] | None,
+        receipt_uncertainty: Uncertainty | None,
+        dispute_state: DisputeState | None,
+        dispute_target_kid: bytes | None,
+        dispute_subtype: DisputeSubtype | None,
+        bond_commitment: dict[str, Any] | None,
+        prior_dispute_chain: list[bytes] | None,
+        ramp_state: dict[str, Any] | None,
+        wire_version: int = WIRE_VERSION,
+    ) -> dict[int, Any]:
+        if len(namespace_id) != 16:
+            raise ValueError("namespace_id must be 16 bytes")
+        if record_type in V2_GATED_RECORD_TYPES and wire_version < 2:
+            raise ValueError(
+                f"record_type {record_type!r} requires wire_version >= 2 (got {wire_version})"
+            )
+        protected: dict[int, Any] = {
+            COSE_ALG: alg,
+            COSE_KID: issuer_kid,
+            HM_RECORD_TYPE: record_type,
+            HM_NAMESPACE_ID: namespace_id,
+            HM_HLC: hlc.to_cbor(),
+            HM_SIG_ALG_DISC: alg,
+            HM_ENVELOPE_SCHEMA_HASH: expected_schema_hash(record_type),
+            HM_WIRE_VERSION: wire_version,
+            HM_PQ_REQUIRED: pq_required,
+            HM_PROTOCOL_VERSION: protocol_version,
+        }
+        if receipt_uncertainty is not None:
+            if record_type != "RECEIPT":
+                raise ValueError("receipt_uncertainty only valid on RECEIPT")
+            protected[HM_RECEIPT_UNCERTAINTY] = receipt_uncertainty.to_cbor()
+        if confirmer_set:
+            if record_type != "SEAL":
+                raise ValueError("confirmer_set only valid on SEAL")
+            if len(confirmer_set) < 3:
+                raise ValueError("confirmer_set must have ≥3 entries")
+            protected[HM_CONFIRMER_SET] = list(confirmer_set)
+        if dispute_state is not None:
+            protected[HM_DISPUTE_STATE] = dispute_state
+        if record_type == "DISPUTE":
+            if dispute_target_kid is None or dispute_subtype is None or bond_commitment is None:
+                raise ValueError(
+                    "DISPUTE record requires dispute_target_kid, "
+                    "dispute_subtype, and bond_commitment"
+                )
+            if len(dispute_target_kid) != 32:
+                raise ValueError("dispute_target_kid must be 32 bytes")
+            protected[HM_DISPUTE_TARGET_KID] = dispute_target_kid
+            protected[HM_DISPUTE_SUBTYPE] = dispute_subtype
+            protected[HM_BOND_COMMITMENT] = bond_commitment
+            if prior_dispute_chain:
+                protected[HM_PRIOR_DISPUTE_CHAIN] = list(prior_dispute_chain)
+            if ramp_state:
+                protected[HM_RAMP_STATE] = ramp_state
+        return protected
+
+    # ---- accessors ------------------------------------------------------
+
+    @property
+    def _protected_bytes(self) -> bytes:
+        """Canonical deterministic CBOR of the protected header only.
+
+        Used as the sole input to ``kid`` — the unprotected header is
+        mutable and NOT signature-bound, so including it in the kid would
+        let an attacker change the kid without invalidating the signature
+        (P1-02 / HM-KID-PROTECTED-ONLY).
+        """
+        return _det_cbor(self.protected_map())
+
+    @property
+    def kid(self) -> Kid:
+        """Content-addressed kid: sha256(protected_header_bytes only).
+
+        Derived from the *protected* header exclusively so that mutations
+        to the unprotected header (which are NOT signature-bound) cannot
+        alter the kid without invalidating the signature.  This closes the
+        P1-02 mutable-unprotected-header substitution class.
+        """
+        return sha256_kid(self._protected_bytes)
+
+    def protected_map(self) -> dict[int, Any]:
+        return self._build_protected_header(
+            alg=self.alg,
+            record_type=self.record_type,
+            namespace_id=self.namespace_id,
+            hlc=self.hlc,
+            issuer_kid=self.issuer_kid,
+            pq_required=self.pq_required,
+            protocol_version=self.protocol_version,
+            confirmer_set=self.confirmer_set,
+            receipt_uncertainty=self.receipt_uncertainty,
+            dispute_state=self.dispute_state,
+            dispute_target_kid=self.dispute_target_kid,
+            dispute_subtype=self.dispute_subtype,
+            bond_commitment=self.bond_commitment,
+            prior_dispute_chain=self.prior_dispute_chain,
+            ramp_state=self.ramp_state,
+            wire_version=self.wire_version,
+        )
+
+    # ---- serialization ---------------------------------------------------
+
+    def to_bytes(self) -> bytes:
+        """Encode as COSE_Sign1: [protected_bytes, unprotected, payload, signature].
+
+        For composite (alg=-49) the full issuer public key is carried in
+        the unprotected header so verifiers can validate without a key
+        lookup. The Ed25519 half (=kid) is also in the protected header
+        (label 4), preventing identity-substitution.
+        """
+        protected_bytes = _det_cbor(self.protected_map())
+        unprotected = dict(self.unprotected)
+        if self.issuer_pk_full and self.alg == ALG_MLDSA65_ED25519:
+            unprotected["issuer_pk_full"] = self.issuer_pk_full
+        return _det_cbor([protected_bytes, unprotected, self.payload, self.signature])
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> SignedStatement:
+        if len(raw) > MAX_ENVELOPE_BYTES:
+            raise ConformanceError(
+                f"envelope exceeds maximum size: {len(raw)} > {MAX_ENVELOPE_BYTES} bytes"
+            )
+        try:
+            msg = cbor2.loads(raw)
+        except cbor2.CBORDecodeError as e:
+            raise ConformanceError(f"envelope is not valid CBOR: {e}") from e
+        if not isinstance(msg, list) or len(msg) != 4:
+            raise ConformanceError("envelope must be 4-element COSE_Sign1 array")
+        protected_bytes, unprotected, payload, signature = msg
+        try:
+            protected = cbor2.loads(protected_bytes)
+        except cbor2.CBORDecodeError as e:
+            raise ConformanceError(f"protected header is not valid CBOR: {e}") from e
+        if not isinstance(protected, dict):
+            raise ConformanceError("protected header must be a CBOR map")
+
+        # Duplicate-key gate: cbor2 silently merges duplicate map keys (last
+        # wins). Compare the *declared* pair count from the raw map header
+        # against the decoded dict length to surface the attack.
+        declared_pairs = _count_raw_map_pairs(protected_bytes)
+        if declared_pairs != len(protected):
+            raise ConformanceError("duplicate keys in protected header")
+
+        # Canonical-encoding gate (closes self-heal Cycle-1 Finding #7):
+        # re-encode the parsed protected map under deterministic CBOR
+        # and require byte-equality with the wire bytes. This prevents
+        # malleable encodings producing two distinct kids for the same
+        # logical statement.
+        if _det_cbor(protected) != protected_bytes:
+            raise ConformanceError("non-canonical protected header encoding (RFC 8949 §4.2)")
+
+        # Domain bound check happens here, BEFORE signature verify.
+        _check_a_alg_bound(protected)
+
+        # Wire-version + schema-hash gate: reject incompatible envelopes
+        # at parse time. A tampered wire_version (Z.7.4-class attack) is
+        # rejected here, not at signature-verify, so the failure mode is
+        # auditable (ConformanceError, not silent signature failure).
+        wv = protected[HM_WIRE_VERSION]
+        if wv not in WIRE_VERSION_SUPPORTED:
+            raise ConformanceError(
+                f"wire_version mismatch: got {wv}, expected one of {sorted(WIRE_VERSION_SUPPORTED)}"
+            )
+        record_type_for_hash = protected[HM_RECORD_TYPE]
+        if record_type_for_hash in V2_GATED_RECORD_TYPES and wv < 2:
+            raise ConformanceError(
+                f"record_type {record_type_for_hash!r} requires wire_version >= 2 (got {wv})"
+            )
+        expected_hash = expected_schema_hash(record_type_for_hash)
+        if protected[HM_ENVELOPE_SCHEMA_HASH] != expected_hash:
+            raise ConformanceError("envelope_schema_hash mismatch")
+
+        # P2-07: protocol_version dispatch — reject unsupported versions
+        # before signature verification so the refusal is auditable as a
+        # policy decision, not a crypto failure.
+        pv = int(protected[HM_PROTOCOL_VERSION])
+        if pv not in SUPPORTED_PROTOCOL_VERSIONS:
+            raise ProtocolVersionError(
+                f"Unsupported protocol version: {pv}; supported={sorted(SUPPORTED_PROTOCOL_VERSIONS)}",
+                statement_version=pv,
+                min_required=min(SUPPORTED_PROTOCOL_VERSIONS),
+            )
+
+        record_type = protected[HM_RECORD_TYPE]
+        unprotected_dict = dict(unprotected) if unprotected else {}
+        issuer_pk_full = bytes(unprotected_dict.pop("issuer_pk_full", b""))
+        return cls(
+            record_type=record_type,
+            namespace_id=bytes(protected[HM_NAMESPACE_ID]),
+            hlc=HLC.from_cbor(protected[HM_HLC]),
+            issuer_kid=bytes(protected[COSE_KID]),
+            payload=bytes(payload),
+            signature=bytes(signature),
+            alg=int(protected[COSE_ALG]),
+            pq_required=bool(protected[HM_PQ_REQUIRED]),
+            protocol_version=int(protected[HM_PROTOCOL_VERSION]),
+            issuer_pk_full=issuer_pk_full,
+            confirmer_set=[bytes(c) for c in protected.get(HM_CONFIRMER_SET, [])],
+            receipt_uncertainty=(
+                Uncertainty.from_cbor(protected[HM_RECEIPT_UNCERTAINTY])
+                if HM_RECEIPT_UNCERTAINTY in protected
+                else None
+            ),
+            dispute_state=protected.get(HM_DISPUTE_STATE),
+            dispute_target_kid=(
+                bytes(protected[HM_DISPUTE_TARGET_KID])
+                if HM_DISPUTE_TARGET_KID in protected
+                else None
+            ),
+            dispute_subtype=protected.get(HM_DISPUTE_SUBTYPE),
+            bond_commitment=protected.get(HM_BOND_COMMITMENT),
+            prior_dispute_chain=[bytes(k) for k in protected.get(HM_PRIOR_DISPUTE_CHAIN, [])],
+            ramp_state=protected.get(HM_RAMP_STATE),
+            unprotected=unprotected_dict,
+            wire_version=int(wv),
+        )
+
+    # ---- verification ----------------------------------------------------
+
+    def verify(self, *, revocation_store: Any = None) -> bool:
+        """Verify signature and A-ALG-BOUND.
+
+        Returns True if (a) every discriminator is in the signed
+        preimage, (b) wire_version + envelope_schema_hash match the
+        local v0 contract, (c) the signature is valid Ed25519 over the
+        canonical sig_input, and (d) — when a `revocation_store` is
+        supplied — the issuer kid is not revoked as of this statement's
+        HLC. Statements signed *before* a revocation remain valid; this
+        is the historical-claim-immutability property of v0.7's CRL
+        primitive (rule_id ``HM-KEY-REVOKED-001``).
+
+        Raises ConformanceError on A-ALG-BOUND or schema mismatch.
+        Returns False on signature failure or revocation hit (no
+        exception — callers can branch on the return value).
+        """
+        protected = self.protected_map()
+        _check_a_alg_bound(protected)
+
+        # Revocation gate: rejected BEFORE signature verify so a revoked
+        # kid cannot waste verifier CPU on signature math.
+        if revocation_store is not None:
+            entry = revocation_store.is_revoked(
+                bytes(self.issuer_kid),
+                (self.hlc.logical_ms, self.hlc.counter),
+            )
+            if entry is not None:
+                return False
+
+        if protected[HM_WIRE_VERSION] not in WIRE_VERSION_SUPPORTED:
+            raise ConformanceError(
+                f"wire_version mismatch: got {protected[HM_WIRE_VERSION]}, "
+                f"expected one of {sorted(WIRE_VERSION_SUPPORTED)}"
+            )
+        if protected[HM_ENVELOPE_SCHEMA_HASH] != expected_schema_hash(self.record_type):
+            raise ConformanceError("envelope_schema_hash mismatch")
+
+        if self.alg not in (ALG_ED25519, ALG_MLDSA65_ED25519):
+            raise ConformanceError(f"unsupported alg {self.alg}")
+
+        sig_input = canonical_sig_input(protected, self.payload)
+        if self.alg == ALG_ED25519:
+            return verify_signature(self.alg, self.issuer_kid, self.signature, sig_input)
+        # composite — need the full public key
+        full_pk = self.issuer_pk_full if len(self.issuer_pk_full) > 0 else self.issuer_kid
+        if len(full_pk) != ED25519_PK_LEN + 1952:
+            return False
+        # Bind the kid (Ed25519 half) to the full key — defeats identity
+        # substitution at parse time.
+        if full_pk[:ED25519_PK_LEN] != self.issuer_kid:
+            raise ConformanceError("issuer_kid does not match Ed25519 prefix of issuer_pk_full")
+        return verify_signature(self.alg, full_pk, self.signature, sig_input)
+
+    def __repr__(self) -> str:
+        return (
+            f"SignedStatement({self.record_type} kid={self.kid.hex()[:12]} "
+            f"hlc={self.hlc} ns={self.namespace_id.hex()[:8]})"
+        )
+
+
+@dataclass
+class EncryptedStatementRecipient:
+    """One recipient slot in an `EncryptedStatement` (§23.5)."""
+
+    recipient_kid: bytes  # 32-byte Ed25519 pubkey half
+    enc: bytes  # HPKE encapsulated key
+
+    def to_cbor(self) -> dict[str, bytes]:
+        if len(self.recipient_kid) != 32:
+            raise ValueError("recipient_kid must be 32 bytes")
+        return {"recipient_kid": self.recipient_kid, "enc": self.enc}
+
+    @classmethod
+    def from_cbor(cls, obj: Any) -> EncryptedStatementRecipient:
+        if not isinstance(obj, dict):
+            raise ConformanceError("Recipient must be a CBOR map")
+        if set(obj.keys()) != {"recipient_kid", "enc"}:
+            raise ConformanceError(
+                f"Recipient must have exactly keys recipient_kid+enc; got {sorted(obj.keys())}"
+            )
+        kid = bytes(obj["recipient_kid"])
+        enc = bytes(obj["enc"])
+        if len(kid) != 32:
+            raise ConformanceError("recipient_kid must be 32 bytes")
+        return cls(recipient_kid=kid, enc=enc)
+
+
+@dataclass
+class EncryptedStatement:
+    """HPKE-AEAD ciphertext payload for hybrid/private namespace records.
+
+    Wire form (RFC 8949 deterministic CBOR; see
+    `hypermind/schemas/encrypted_statement.cddl`):
+
+        [kdf, aead, [+ Recipient], aad_hash, ciphertext, ?epoch_tag]
+
+    `from_bytes` enforces canonical-CBOR (re-encode equality), array
+    arity, and 32-byte sizing of `aad_hash` / `recipient_kid` / optional
+    `epoch_tag` (16 bytes). The signature on the outer `SignedStatement`
+    covers `aad_hash` only — verification MUST NOT require decryption
+    (spec §23.3).
+    """
+
+    kdf: int
+    aead: int
+    enc_recipients: list[EncryptedStatementRecipient]
+    aad_hash: bytes  # 32 bytes
+    ciphertext: bytes
+    epoch_tag: bytes | None = None  # 16 bytes if present
+
+    def to_bytes(self) -> bytes:
+        if len(self.aad_hash) != 32:
+            raise ValueError("aad_hash must be 32 bytes")
+        if not self.enc_recipients:
+            raise ValueError("enc_recipients must contain at least one Recipient")
+        if self.epoch_tag is not None and len(self.epoch_tag) != 16:
+            raise ValueError("epoch_tag must be 16 bytes when present")
+        arr: list[Any] = [
+            int(self.kdf),
+            int(self.aead),
+            [r.to_cbor() for r in self.enc_recipients],
+            self.aad_hash,
+            self.ciphertext,
+        ]
+        if self.epoch_tag is not None:
+            arr.append(self.epoch_tag)
+        return _det_cbor(arr)
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> EncryptedStatement:
+        if len(raw) > MAX_ENVELOPE_BYTES:
+            raise ConformanceError(
+                f"EncryptedStatement exceeds maximum size: {len(raw)} > {MAX_ENVELOPE_BYTES}"
+            )
+        try:
+            arr = cbor2.loads(raw)
+        except cbor2.CBORDecodeError as e:
+            raise ConformanceError(f"EncryptedStatement is not valid CBOR: {e}") from e
+        if not isinstance(arr, list) or len(arr) not in (5, 6):
+            raise ConformanceError("EncryptedStatement must be a 5- or 6-element CBOR array")
+        # Canonical-encoding gate (mirror SignedStatement.from_bytes).
+        if _det_cbor(arr) != raw:
+            raise ConformanceError("non-canonical EncryptedStatement encoding (RFC 8949 §4.2)")
+        kdf, aead, recipients_raw, aad_hash, ciphertext = arr[:5]
+        epoch_tag: bytes | None = bytes(arr[5]) if len(arr) == 6 else None
+        if not isinstance(kdf, int) or not isinstance(aead, int):
+            raise ConformanceError("kdf and aead must be integers")
+        if not isinstance(recipients_raw, list) or not recipients_raw:
+            raise ConformanceError("enc_recipients must be a non-empty array")
+        aad_hash_b = bytes(aad_hash)
+        if len(aad_hash_b) != 32:
+            raise ConformanceError("aad_hash must be 32 bytes")
+        if epoch_tag is not None and len(epoch_tag) != 16:
+            raise ConformanceError("epoch_tag must be 16 bytes when present")
+        return cls(
+            kdf=kdf,
+            aead=aead,
+            enc_recipients=[EncryptedStatementRecipient.from_cbor(r) for r in recipients_raw],
+            aad_hash=aad_hash_b,
+            ciphertext=bytes(ciphertext),
+            epoch_tag=epoch_tag,
+        )