hypermind 0.11.0__py3-none-any.whl

hypermind/crypto/namespace_root.py

@@ -0,0 +1,204 @@
+"""Namespace root key — FROST k-of-n group public key for §24 namespace lifecycle.
+
+The namespace root is a FROST (RFC 9591) threshold Schnorr group public
+key produced by a DKG ceremony among the founding cohort. It signs the
+`NAMESPACE_CREATE` and `NAMESPACE_FOUNDING_ATTEST` records, and the
+DID:web rendezvous document (§24.6).
+
+This module is a thin wrapper around :mod:`hypermind.crypto.frost` — it
+does not duplicate FROST primitives. ``NamespaceRoot.from_dkg()`` runs
+the trusted-dealer DKG variant and computes a transcript hash that is
+bound into the founding attestation (§24.2).
+
+v1.0 hooks:
+    - :class:`NamespaceEpoch` carries `epoch_id`, transcript hash, and
+      group public key. Root key rotation across transparency-log
+      epochs is reserved for v1.0 (spec §24.9 `epoch_rotation_proof`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import cbor2
+
+from hypermind.crypto import frost
+from hypermind.crypto.hashing import blake3_32
+from hypermind.crypto.hlc import HLC
+from hypermind.crypto.signing import Keypair
+
+# Default FROST threshold — spec §24.2 "k = 5, n = 7".
+DEFAULT_K = 5
+DEFAULT_N = 7
+
+
+def _canonical_dkg_transcript(
+    *,
+    member_kids: list[bytes],
+    k: int,
+    n: int,
+    group_public: bytes,
+    share_indices: list[int],
+) -> bytes:
+    """Build the canonical CBOR transcript whose BLAKE3 digest binds the DKG.
+
+    The transcript records (a) the founding member kids in declaration
+    order, (b) the threshold parameters, (c) the resulting group public
+    key, and (d) the share-index assignment. This is what the §24.3
+    ``dkg_transcript_hash`` field commits to.
+    """
+    return cbor2.dumps(
+        {
+            "v": 1,
+            "members": member_kids,
+            "k": k,
+            "n": n,
+            "group_public": group_public,
+            "share_indices": share_indices,
+        },
+        canonical=True,
+    )
+
+
+@dataclass
+class NamespaceEpoch:
+    """A single epoch of the namespace root key.
+
+    v0.9.x ships epoch 0 only. ``rotate_to_next_epoch()`` is a stub that
+    raises :class:`NotImplementedError`; the actual rotation protocol
+    (epoch_rotation_proof, transparency-log carry-over) is reserved for
+    v1.0 per spec §24.9.
+    """
+
+    epoch_id: int
+    dkg_transcript_hash: bytes
+    group_pubkey: bytes
+    created_at_hlc: HLC
+
+    def rotate_to_next_epoch(self) -> NamespaceEpoch:
+        raise NotImplementedError("v1.0 — see spec §24 reserved fields")
+
+
+@dataclass
+class NamespaceRoot:
+    """Aggregate FROST k-of-n key for a namespace.
+
+    Attributes
+    ----------
+    group_pubkey:
+        32-byte Ed25519 group public key (FROST aggregate).
+    k, n:
+        Threshold parameters (default 5-of-7, spec §24.2).
+    member_kids:
+        Founding-cohort kids in declaration order. ``share_indices[i]``
+        is the FROST share index for ``member_kids[i]``.
+    dkg_transcript_hash:
+        BLAKE3-256 of the canonical DKG transcript, bound into
+        ``NAMESPACE_FOUNDING_ATTEST.dkg_transcript_hash``.
+    epoch:
+        Current :class:`NamespaceEpoch`. v0.9.x only ever sees epoch 0.
+
+    Secret shares are kept in ``_shares`` (private) — never exposed
+    on the wire and refused by ``__reduce__``.
+    """
+
+    group_pubkey: bytes
+    k: int
+    n: int
+    member_kids: list[bytes]
+    dkg_transcript_hash: bytes
+    epoch: NamespaceEpoch
+    _shares: list[frost.FrostShare] = field(default_factory=list, repr=False)
+
+    @classmethod
+    def from_dkg(
+        cls,
+        members: list[Keypair],
+        k: int = DEFAULT_K,
+        n: int | None = None,
+    ) -> NamespaceRoot:
+        """Run the trusted-dealer FROST DKG over ``members``.
+
+        Spec §24.2 `NS-LIFECYCLE-FROST`: ``k >= ceil(2n/3)`` and ``n >= 3``.
+        Default parameters are k=5, n=7. ``len(members)`` MUST equal n.
+        """
+        if n is None:
+            n = len(members)
+        if n < 3:
+            raise ValueError("namespace founding cohort requires n >= 3 (spec §24.2)")
+        if len(members) != n:
+            raise ValueError(f"members count {len(members)} != n={n}")
+        # ceil(2n/3) — integer arithmetic
+        min_k = (2 * n + 2) // 3
+        if k < min_k:
+            raise ValueError(
+                f"k={k} below ceil(2n/3)={min_k} for n={n} (spec §24.2 NS-LIFECYCLE-FROST)"
+            )
+        if k > n:
+            raise ValueError(f"k={k} cannot exceed n={n}")
+
+        shares = frost.generate_shares(t=k, n=n)
+        group_public = shares[0].group_public
+        member_kids = [m.kid for m in members]
+        share_indices = [s.index for s in shares]
+        transcript = _canonical_dkg_transcript(
+            member_kids=member_kids,
+            k=k,
+            n=n,
+            group_public=group_public,
+            share_indices=share_indices,
+        )
+        transcript_hash = blake3_32(transcript)
+        epoch = NamespaceEpoch(
+            epoch_id=0,
+            dkg_transcript_hash=transcript_hash,
+            group_pubkey=group_public,
+            created_at_hlc=HLC.now(node_id=member_kids[0][:8]),
+        )
+        return cls(
+            group_pubkey=group_public,
+            k=k,
+            n=n,
+            member_kids=member_kids,
+            dkg_transcript_hash=transcript_hash,
+            epoch=epoch,
+            _shares=list(shares),
+        )
+
+    def sign(self, message: bytes, signer_subset: list[int]) -> bytes:
+        """Produce an aggregated FROST signature over ``message``.
+
+        ``signer_subset`` is a list of 1-indexed share indices (matching
+        ``share_indices`` from the DKG). MUST contain at least ``k``
+        distinct indices. Returns the wire signature ``R || z`` (64
+        bytes — both 32-byte scalars/points).
+        """
+        if len(set(signer_subset)) != len(signer_subset):
+            raise ValueError("signer_subset must contain unique indices")
+        if len(signer_subset) < self.k:
+            raise ValueError(
+                f"FROST quorum unmet: need at least k={self.k} signers, got {len(signer_subset)}"
+            )
+        share_by_index = {s.index: s for s in self._shares}
+        chosen: list[frost.FrostShare] = []
+        for idx in signer_subset:
+            if idx not in share_by_index:
+                raise ValueError(f"signer index {idx} not in DKG share set")
+            chosen.append(share_by_index[idx])
+        R, z = frost.threshold_sign(chosen, message)
+        return R + z
+
+    def verify(self, message: bytes, signature: bytes) -> bool:
+        """Verify a FROST signature produced by :meth:`sign`."""
+        if len(signature) != 64:
+            return False
+        R = signature[:32]
+        z = signature[32:]
+        return frost.verify(self.group_pubkey, message, R, z, commitments=None)
+
+    # ---- safety -------------------------------------------------------
+
+    def __reduce__(self) -> Any:
+        # Refuse pickle; secret shares would leak.
+        raise TypeError("refusing to pickle NamespaceRoot; contains secret FROST shares")

hypermind/crypto/pq.py

@@ -0,0 +1,152 @@
+"""Dual-vendor ML-DSA-65 backend adapter.
+
+WS-A supply-chain hardening (v0.6): the production path in
+`hypermind.crypto.signing` uses ``quantcrypt`` (FIPS 204 reference
+implementation) directly. To defend against a single-vendor compromise
+of the post-quantum signature primitive, this module defines a backend
+Protocol with two interchangeable implementations:
+
+* :class:`QuantcryptBackend` — wraps ``quantcrypt.dss.MLDSA_65`` (the
+  current production dependency).
+* :class:`OqsBackend` — wraps ``oqs.Signature("ML-DSA-65")`` from the
+  Open Quantum Safe ``liboqs`` Python bindings.
+
+Both vendors implement the same NIST FIPS 204 ML-DSA-65 algorithm, so a
+keypair generated by one MUST verify under the other and vice versa.
+This dual-vendor cross-check is asserted in
+``tests/test_pq_dual_vendor.py``.
+
+This module deliberately does **not** alter any production code path;
+it only adds the Protocol + two adapters. The cutover is gated to a
+later milestone once the cross-vendor cross-check has been running in
+CI for at least one release cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MlDsaBackend(Protocol):
+    """ML-DSA-65 signing backend.
+
+    All implementations MUST be byte-for-byte interoperable on
+    ``verify`` — a signature emitted by one backend must verify under
+    any other backend with the matching public key.
+    """
+
+    name: str
+
+    def keygen(self, seed: bytes | None = None) -> tuple[bytes, bytes]:
+        """Generate a keypair. Returns ``(public_key, secret_key)``.
+
+        ``seed`` is accepted for API symmetry; backends MAY ignore it
+        if they do not expose deterministic key generation. Callers
+        SHOULD NOT rely on ``seed`` for determinism across backends.
+        """
+        ...
+
+    def sign(self, sk: bytes, msg: bytes) -> bytes:
+        """Sign ``msg`` under secret key ``sk``. Returns the raw signature."""
+        ...
+
+    def verify(self, pk: bytes, msg: bytes, sig: bytes) -> bool:
+        """Verify ``sig`` over ``msg`` under public key ``pk``.
+
+        Returns ``True`` on success, ``False`` on any verification
+        failure (bad signature, malformed input, length mismatch).
+        Implementations MUST NOT raise on cryptographic failure.
+        """
+        ...
+
+
+class QuantcryptBackend:
+    """ML-DSA-65 backend backed by ``quantcrypt`` (FIPS 204 reference).
+
+    This is the production backend used by
+    :mod:`hypermind.crypto.signing` today.
+    """
+
+    name = "quantcrypt"
+
+    def __init__(self) -> None:
+        # Lazy import — quantcrypt is a runtime dep but importing it
+        # lazily keeps this module cheap to import for type-only users.
+        from quantcrypt.dss import MLDSA_65
+
+        self._impl = MLDSA_65()
+
+    def keygen(self, seed: bytes | None = None) -> tuple[bytes, bytes]:
+        # quantcrypt's MLDSA_65.keygen() does not expose seed input.
+        # The `seed` parameter is accepted for Protocol conformance.
+        del seed
+        pk, sk = self._impl.keygen()
+        return bytes(pk), bytes(sk)
+
+    def sign(self, sk: bytes, msg: bytes) -> bytes:
+        return bytes(self._impl.sign(sk, msg))
+
+    def verify(self, pk: bytes, msg: bytes, sig: bytes) -> bool:
+        from quantcrypt.errors import DSSVerifyFailedError
+
+        try:
+            return bool(self._impl.verify(pk, msg, sig))
+        except DSSVerifyFailedError:
+            return False
+        except Exception:
+            return False
+
+
+class OqsBackend:
+    """ML-DSA-65 backend backed by ``liboqs`` (Open Quantum Safe).
+
+    Lazy-loaded: importing this class does not require ``oqs`` to be
+    installed, but instantiating it does. Install via the
+    ``crypto-pq-test`` optional extra:
+
+    .. code-block:: bash
+
+        pip install -e ".[crypto-pq-test]"
+
+    Note: ``liboqs`` is intentionally test-only — it is not on the
+    runtime install path. The dual-vendor invariant is asserted in
+    CI; production deployments only require ``quantcrypt``.
+    """
+
+    name = "liboqs"
+
+    def __init__(self) -> None:
+        try:
+            import oqs  # type: ignore[import-not-found]
+        except ImportError as exc:  # pragma: no cover — exercised in skip path
+            raise ImportError(
+                "OqsBackend requires the 'oqs' Python package (liboqs bindings). "
+                "Install it via the crypto-pq-test extra: "
+                'pip install -e ".[crypto-pq-test]"'
+            ) from exc
+        # We hold the module reference, not a long-lived Signature
+        # object: oqs.Signature is stateful (holds a secret key after
+        # generate_keypair), so we instantiate fresh per call.
+        self._oqs = oqs
+
+    def keygen(self, seed: bytes | None = None) -> tuple[bytes, bytes]:
+        del seed  # liboqs does not expose seeded keygen
+        with self._oqs.Signature("ML-DSA-65") as signer:
+            pk = bytes(signer.generate_keypair())
+            sk = bytes(signer.export_secret_key())
+        return pk, sk
+
+    def sign(self, sk: bytes, msg: bytes) -> bytes:
+        with self._oqs.Signature("ML-DSA-65", sk) as signer:
+            return bytes(signer.sign(msg))
+
+    def verify(self, pk: bytes, msg: bytes, sig: bytes) -> bool:
+        try:
+            with self._oqs.Signature("ML-DSA-65") as verifier:
+                return bool(verifier.verify(msg, sig, pk))
+        except Exception:
+            return False
+
+
+__all__ = ["MlDsaBackend", "OqsBackend", "QuantcryptBackend"]

hypermind/crypto/room_epoch.py

@@ -0,0 +1,97 @@
+"""Sender-derived Room epoch key chain.
+
+Lightweight one-way ratchet used by Rooms in v0.9.x to bind ciphertexts to a
+specific epoch boundary. Each epoch's key is derived from the previous via
+HKDF-Expand, so a key from epoch N cannot decrypt traffic encrypted under the
+AEAD key derived from epoch N+1's chain key (forward secrecy at the boundary).
+
+# MLS-SWAP-POINT: in v1.0 this module is replaced by an MLS TreeKEM group state.
+# Callers depend only on `RoomEpochKey.derive_aead_key()` returning a 32-byte
+# AEAD key bound to the current epoch — keep that surface stable across the swap.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, replace
+
+from cryptography.hazmat.primitives import hashes, hmac
+
+_HASH_LEN = 32  # SHA-256
+_KEY_LEN = 32  # AEAD key length (AES-256 / ChaCha20)
+
+_LABEL_ADVANCE = b"hm/room-epoch/advance"
+_LABEL_AEAD = b"hm/room-epoch/aead-key"
+
+
+def _hmac_sha256(key: bytes, data: bytes) -> bytes:
+    h = hmac.HMAC(key, hashes.SHA256())
+    h.update(data)
+    return h.finalize()
+
+
+def _hkdf_extract(salt: bytes, ikm: bytes) -> bytes:
+    if not salt:
+        salt = b"\x00" * _HASH_LEN
+    return _hmac_sha256(salt, ikm)
+
+
+def _hkdf_expand(prk: bytes, info: bytes, length: int) -> bytes:
+    n = (length + _HASH_LEN - 1) // _HASH_LEN
+    if n > 255:
+        raise ValueError("HKDF-Expand: requested length too large")
+    out = b""
+    t = b""
+    for i in range(1, n + 1):
+        t = _hmac_sha256(prk, t + info + bytes([i]))
+        out += t
+    return out[:length]
+
+
+@dataclass(frozen=True)
+class RoomEpochKey:
+    """A Room's chain key at a specific epoch.
+
+    Attributes:
+        room_id: Stable identifier of the Room (any byte string).
+        epoch: Monotonically increasing counter, starts at 0.
+        key: 32-byte chain key for this epoch. Use `derive_aead_key()` for
+            encryption — never use this field directly as an AEAD key.
+    """
+
+    room_id: bytes
+    epoch: int
+    key: bytes
+
+    @classmethod
+    def from_root(cls, room_root_secret: bytes, room_id: bytes) -> RoomEpochKey:
+        """Initialise epoch 0 from a Room root secret."""
+        if not isinstance(room_root_secret, bytes) or len(room_root_secret) == 0:
+            raise ValueError("room_root_secret must be non-empty bytes")
+        if not isinstance(room_id, bytes) or len(room_id) == 0:
+            raise ValueError("room_id must be non-empty bytes")
+        prk = _hkdf_extract(room_id, room_root_secret)
+        info = _LABEL_ADVANCE + room_id + struct.pack(">Q", 0)
+        key0 = _hkdf_expand(prk, info, _HASH_LEN)
+        return cls(room_id=room_id, epoch=0, key=key0)
+
+    def advance(self) -> RoomEpochKey:
+        """Return the next epoch's chain key.
+
+        The previous chain key is the HKDF PRK; the next-epoch info string binds
+        `(room_id, next_epoch)` so distinct rooms never collide and the chain is
+        deterministic given a fixed root.
+        """
+        next_epoch = self.epoch + 1
+        info = _LABEL_ADVANCE + self.room_id + struct.pack(">Q", next_epoch)
+        next_key = _hkdf_expand(self.key, info, _HASH_LEN)
+        return replace(self, epoch=next_epoch, key=next_key)
+
+    def derive_aead_key(self) -> bytes:
+        """Return a 32-byte AEAD key bound to the current epoch.
+
+        Distinct from the chain key so a leaked AEAD key does not let an attacker
+        ratchet forward.
+        """
+        info = _LABEL_AEAD + self.room_id + struct.pack(">Q", self.epoch)
+        return _hkdf_expand(self.key, info, _KEY_LEN)

hypermind/crypto/signing.py

@@ -0,0 +1,245 @@
+"""Signing primitives — Ed25519 (v0.1) + ML-DSA-65 hybrid (v0.2).
+
+Composite signing follows draft-ietf-lamps-pq-composite-sigs-16
+(`id-MLDSA65-Ed25519-SHA512`): the composite signature is the
+concatenation `Ed25519_sig || ML-DSA-65_sig`, both signed over the
+same canonical preimage. Verification requires BOTH signatures to
+verify — defeats single-key compromise.
+
+A-ALG-BOUND invariant: every envelope discriminator is in the signed
+preimage. See `wire.canonical_sig_input`.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import SigningKey, VerifyKey
+
+# Real ML-DSA-65 from quantcrypt (NIST FIPS 204 reference impl).
+from quantcrypt.dss import MLDSA_65
+from quantcrypt.errors import DSSVerifyFailedError
+
+# COSE algorithm identifiers (RFC 9053; LAMPS draft for composite)
+ALG_ED25519 = -8
+ALG_MLDSA65_ED25519 = -49  # composite — id-MLDSA65-Ed25519-SHA512
+
+ED25519_SIG_LEN = 64
+ED25519_PK_LEN = 32
+
+# ML-DSA-65 lengths from FIPS 204
+MLDSA65_SIG_LEN = 3309
+MLDSA65_PK_LEN = 1952
+
+_MLDSA = MLDSA_65()
+
+# --------------------------------------------------------------------------- #
+# LAMPS draft-ietf-lamps-pq-composite-sigs-16 §6 domain-separated preimage.
+#
+# Per draft §6, the message signed by each component algorithm is:
+#   M' = Domain || OID || len(ctx) || ctx || M
+#
+# where:
+#   * Domain  = the ASCII string "CompositeAlgorithmSignatures2025"
+#   * OID     = DER encoding of the composite algorithm OID
+#               (id-MLDSA65-Ed25519-SHA512 = 2.16.840.1.101.3.4.3.21)
+#   * ctx     = caller-supplied context bytes (default empty)
+#   * M       = the original application message
+#
+# This prefix prevents (a) signature stripping — taking only the Ed25519
+# half and re-using it as a non-composite Ed25519 signature over M, and
+# (b) cross-protocol substitution against any signer that signs the raw
+# message with no domain separation.
+#
+# OID encoding: this is the canonical DER encoding of
+# 2.16.840.1.101.3.4.3.21 (id-MLDSA65-Ed25519-SHA512), the assignment
+# tracked by the LAMPS Composite ML-DSA draft. The previous constant
+# (06092a864886f70d010721) was a documented placeholder pointing at an
+# unrelated RSA arc; while internal verify worked (signer and verifier
+# shared the wrong bytes), any LAMPS-conformant external verifier would
+# have rejected our signatures and we would have rejected theirs.
+# Closes self-heal Cycle-3 Finding #21.
+#
+# Wire compatibility: composite signatures created under the placeholder
+# OID will NOT verify under the canonical OID. Operators rotating across
+# this upgrade must accept both during cutover; see
+# docs/migrate/v0.x-to-v1.0.md for the deprecation schedule.
+# --------------------------------------------------------------------------- #
+_LAMPS_DOMAIN: bytes = b"CompositeAlgorithmSignatures2025"
+# Canonical DER for OID 2.16.840.1.101.3.4.3.21:
+#   06 09 60 86 48 01 65 03 04 03 15
+#   tag 0x06 (OBJECT IDENTIFIER), length 0x09 (9 content bytes), then OID body.
+_OID_MLDSA65_ED25519: bytes = bytes.fromhex("0609608648016503040315")
+
+
+def _lamps_preimage(message: bytes, ctx: bytes = b"") -> bytes:
+    """Build the LAMPS §6 domain-separated preimage.
+
+    `ctx` is the optional context string (LAMPS §6); we cap it at 255
+    bytes per the draft's single-byte length field.
+    """
+    if len(ctx) > 255:
+        raise ValueError("LAMPS context must be ≤ 255 bytes")
+    return _LAMPS_DOMAIN + _OID_MLDSA65_ED25519 + len(ctx).to_bytes(1, "big") + ctx + message
+
+
+@dataclass(frozen=True)
+class Keypair:
+    """Signing keypair.
+
+    For Ed25519 (alg=-8): `secret_bytes` and `public_bytes` are the
+    raw 32-byte / 32-byte Ed25519 material. `kid` = public_bytes.
+
+    For composite (alg=-49): `secret_bytes` is `ed_sk(32) || mldsa_sk`,
+    `public_bytes` is `ed_pk(32) || mldsa_pk`. `kid` is the Ed25519
+    public-key half (first 32 bytes of `public_bytes`) — this preserves
+    the v0.1 → v0.2 address-stability contract so an agent's identity
+    survives algorithm rotation from Ed25519 to composite.
+    """
+
+    secret_bytes: bytes
+    public_bytes: bytes
+    alg: int = ALG_ED25519
+
+    @classmethod
+    def generate(cls, *, alg: int = ALG_ED25519) -> Keypair:
+        if alg == ALG_ED25519:
+            sk = SigningKey.generate()
+            return cls(
+                secret_bytes=bytes(sk),
+                public_bytes=bytes(sk.verify_key),
+                alg=alg,
+            )
+        if alg == ALG_MLDSA65_ED25519:
+            ed_sk = SigningKey.generate()
+            mldsa_pk, mldsa_sk = _MLDSA.keygen()
+            return cls(
+                secret_bytes=bytes(ed_sk) + mldsa_sk,
+                public_bytes=bytes(ed_sk.verify_key) + mldsa_pk,
+                alg=alg,
+            )
+        raise NotImplementedError(f"unsupported alg {alg}")
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> Keypair:
+        """Deterministic Ed25519 keypair from a 32-byte seed."""
+        if len(seed) != 32:
+            raise ValueError("seed must be 32 bytes")
+        sk = SigningKey(seed)
+        return cls(
+            secret_bytes=bytes(sk),
+            public_bytes=bytes(sk.verify_key),
+            alg=ALG_ED25519,
+        )
+
+    def sign(self, message: bytes) -> bytes:
+        """Sign — returns raw signature (no envelope).
+
+        Ed25519: 64-byte raw signature.
+        Composite: 64-byte Ed25519 sig || 3309-byte ML-DSA-65 sig.
+        """
+        if self.alg == ALG_ED25519:
+            sk = SigningKey(self.secret_bytes)
+            return sk.sign(message).signature
+        if self.alg == ALG_MLDSA65_ED25519:
+            ed_sk = SigningKey(self.secret_bytes[:32])
+            mldsa_sk = self.secret_bytes[32:]
+            # LAMPS draft-16 §6: BOTH component signatures are computed
+            # over the same domain-separated preimage. This blocks the
+            # "strip-and-reuse the Ed25519 half" downgrade attack.
+            preimage = _lamps_preimage(message)
+            ed_sig = ed_sk.sign(preimage).signature
+            mldsa_sig = _MLDSA.sign(mldsa_sk, preimage)
+            return ed_sig + mldsa_sig
+        raise NotImplementedError(f"sign: unsupported alg {self.alg}")
+
+    @property
+    def ed_public_bytes(self) -> bytes:
+        """Ed25519 public-key half (always 32 bytes)."""
+        return self.public_bytes[:ED25519_PK_LEN]
+
+    @property
+    def mldsa_public_bytes(self) -> bytes:
+        """ML-DSA-65 public-key half. Empty for Ed25519-only keys."""
+        if self.alg == ALG_MLDSA65_ED25519:
+            return self.public_bytes[ED25519_PK_LEN:]
+        return b""
+
+    @property
+    def kid(self) -> bytes:
+        """Stable agent identity = first 32 bytes of public-key bytes.
+
+        For Ed25519, this is the public key itself. For composite, this
+        is the Ed25519 half — preserves the v0.1 → v0.2 key-identity
+        contract so an agent's address survives algorithm rotation.
+        """
+        return self.public_bytes[:ED25519_PK_LEN]
+
+    @property
+    def did_key(self) -> str:
+        return f"did:key:z{self.kid.hex()[:24]}"
+
+    def __repr__(self) -> str:
+        # Never render `secret_bytes` — it would land in logs / tracebacks /
+        # `pytest -v` output. Show only the public kid and algorithm.
+        return f"Keypair(kid={self.kid.hex()[:16]}..., alg={self.alg}, secret=<redacted>)"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __reduce__(self):
+        # Pickle is a known leak vector — a serialized Keypair would carry
+        # `secret_bytes` to disk / over the wire. Refuse outright; callers
+        # who need cross-process sharing must use the in-memory key store.
+        raise TypeError("refusing to pickle secret material; use the in-memory store")
+
+
+def verify_ed25519(public_key: bytes, signature: bytes, message: bytes) -> bool:
+    try:
+        VerifyKey(public_key).verify(message, signature)
+        return True
+    except BadSignatureError:
+        return False
+    except Exception:
+        return False
+
+
+def verify_composite(composite_pk: bytes, composite_sig: bytes, message: bytes) -> bool:
+    """Hybrid verify: BOTH Ed25519 and ML-DSA-65 must validate.
+
+    composite_pk = Ed25519_pk(32) || ML-DSA-65_pk(1952)
+    composite_sig = Ed25519_sig(64) || ML-DSA-65_sig(3309)
+    """
+    if len(composite_pk) != ED25519_PK_LEN + MLDSA65_PK_LEN:
+        return False
+    if len(composite_sig) != ED25519_SIG_LEN + MLDSA65_SIG_LEN:
+        return False
+    ed_pk = composite_pk[:ED25519_PK_LEN]
+    mldsa_pk = composite_pk[ED25519_PK_LEN:]
+    ed_sig = composite_sig[:ED25519_SIG_LEN]
+    mldsa_sig = composite_sig[ED25519_SIG_LEN:]
+    # LAMPS draft-16 §6: verify both halves over the prefixed preimage.
+    preimage = _lamps_preimage(message)
+    if not verify_ed25519(ed_pk, ed_sig, preimage):
+        return False
+    try:
+        return _MLDSA.verify(mldsa_pk, preimage, mldsa_sig)
+    except DSSVerifyFailedError:
+        return False
+    except Exception:
+        return False
+
+
+def verify_signature(alg: int, public_key: bytes, signature: bytes, message: bytes) -> bool:
+    """Algorithm-dispatched verify."""
+    if alg == ALG_ED25519:
+        return verify_ed25519(public_key, signature, message)
+    if alg == ALG_MLDSA65_ED25519:
+        return verify_composite(public_key, signature, message)
+    return False
+
+
+def random_seed() -> bytes:
+    return secrets.token_bytes(32)