hypermind 0.11.0__py3-none-any.whl

hypermind/crypto/hashing.py

@@ -0,0 +1,38 @@
+"""Hashing primitives — SHA-256 for kids, BLAKE3 for fingerprints."""
+
+from __future__ import annotations
+
+import hashlib
+
+import blake3 as _blake3
+
+from hypermind.crypto.domain import DomainTag, domain_separated_hash
+
+
+def sha256_kid(payload: bytes) -> bytes:
+    """Compute the kid (knowledge id) for a payload.
+
+    `kid = sha256(0x02 || payload)` — domain tag KID enforces that this
+    32-byte digest cannot be confused with any other hash operation in
+    the protocol.
+    """
+    return domain_separated_hash(DomainTag.KID, payload)
+
+
+def sha256_with_tag(tag: DomainTag, payload: bytes) -> bytes:
+    """Generic domain-tagged SHA-256."""
+    return domain_separated_hash(tag, payload)
+
+
+def blake3_32(payload: bytes) -> bytes:
+    """32-byte BLAKE3 digest. Used for envelope schema hashes and
+    anti-entropy fingerprints (truncation-safe at 64 bits).
+    """
+    return _blake3.blake3(payload).digest()
+
+
+def hmac_sha256(key: bytes, msg: bytes) -> bytes:
+    """HMAC-SHA-256 — used for keyed-pseudonym salts (HMAC custody)."""
+    import hmac
+
+    return hmac.new(key, msg, hashlib.sha256).digest()

hypermind/crypto/hlc.py

@@ -0,0 +1,163 @@
+"""Hybrid Logical Clock (Kulkarni et al. 2014).
+
+`HLC = (logical_ms: u64, counter: u32, node_id: bytes[8])`
+
+v0.1 normative pin (closes spec/06-conformance.md gap #2):
+  - logical_ms = CLOCK_REALTIME snapshot in ms, single read at envelope-validate entry
+  - NTP sync ≤500 ms drift required
+  - clamp on receive: l_stored = min(l_received, now_ms + hlc_max_skew_ms)
+  - reject if l_received > now_ms + 2 × hlc_max_skew_ms (anomaly: clock_drift)
+
+Clock-source contract (WS-H finding C5):
+  - `ClockSource` Protocol pairs a wall-clock with a monotonic clock.
+  - `SystemClock` (the default) detects >100ms divergence between calls and
+    emits `ClockSkewWarning`. This is the early-warning signal for NTP step,
+    VM pause, or backward leap second — all of which can cause `merge()` to
+    reject HLCs as exceeding `2 * HLC_MAX_SKEW_MS`.
+"""
+
+from __future__ import annotations
+
+import time
+import warnings
+from dataclasses import dataclass, field
+from typing import ClassVar, Protocol, runtime_checkable
+
+
+class HLCSkewError(Exception):
+    """Received HLC exceeds 2× hlc_max_skew_ms — reject, do not clamp."""
+
+
+class ClockSkewWarning(UserWarning):
+    """Emitted when wall-clock and monotonic-clock diverge by more than 100ms between calls."""
+
+
+@runtime_checkable
+class ClockSource(Protocol):
+    """Contract for HLC time sources.
+
+    Implementations must provide:
+    - now_ms(): wall-clock-anchored milliseconds (allowed to jump under NTP step)
+    - monotonic_ms(): monotonic milliseconds (must never go backwards)
+
+    Default impl pairs time.time_ns() with time.monotonic_ns(); detects skew jumps
+    >100ms between calls and emits ClockSkewWarning.
+    """
+
+    def now_ms(self) -> int: ...
+    def monotonic_ms(self) -> int: ...
+
+
+class SystemClock:
+    """Default ClockSource using time.time_ns() + time.monotonic_ns()."""
+
+    def __init__(self) -> None:
+        self._last_wall: int | None = None
+        self._last_mono: int | None = None
+
+    def now_ms(self) -> int:
+        wall = time.time_ns() // 1_000_000
+        mono = time.monotonic_ns() // 1_000_000
+        if self._last_wall is not None and self._last_mono is not None:
+            wall_delta = wall - self._last_wall
+            mono_delta = mono - self._last_mono
+            jump_ms = abs(wall_delta - mono_delta)
+            if jump_ms > 100:
+                warnings.warn(
+                    f"ClockSkewWarning: wall-clock jumped {jump_ms}ms relative to monotonic "
+                    "(NTP step, VM pause, or backward leap second). HLC operations across "
+                    "this boundary may be rejected by HLC_MAX_SKEW_MS.",
+                    ClockSkewWarning,
+                    stacklevel=2,
+                )
+        self._last_wall = wall
+        self._last_mono = mono
+        return wall
+
+    def monotonic_ms(self) -> int:
+        return time.monotonic_ns() // 1_000_000
+
+
+@dataclass(frozen=True, order=True)
+class HLC:
+    """Lexicographically-orderable hybrid logical clock value."""
+
+    logical_ms: int
+    counter: int
+    node_id: bytes
+    # Non-comparable, non-hashed companion state; `frozen=True` requires object.__setattr__
+    # to mutate, which we only do for skew-rejection counting in merge().
+    clock: ClockSource = field(default=None, compare=False, repr=False, hash=False)  # type: ignore[assignment]
+    _skew_rejections: list = field(default_factory=list, compare=False, repr=False, hash=False)
+
+    HLC_MAX_SKEW_MS: ClassVar[int] = 300_000  # 5 min, normative v0.1
+
+    def __post_init__(self) -> None:
+        if len(self.node_id) != 8:
+            raise ValueError("node_id must be 8 bytes")
+        if self.logical_ms < 0 or self.counter < 0:
+            raise ValueError("HLC components must be non-negative")
+        if self.clock is None:
+            object.__setattr__(self, "clock", SystemClock())
+
+    @classmethod
+    def now(cls, node_id: bytes, clock: ClockSource | None = None) -> HLC:
+        """Snapshot current wall-clock as logical_ms."""
+        c = clock if clock is not None else SystemClock()
+        return cls(
+            logical_ms=c.now_ms(),
+            counter=0,
+            node_id=node_id[:8].ljust(8, b"\x00"),
+            clock=c,
+        )
+
+    def tick(self) -> HLC:
+        """Advance for a local event."""
+        now_ms = self.clock.now_ms()
+        if now_ms > self.logical_ms:
+            return HLC(now_ms, 0, self.node_id, clock=self.clock)
+        return HLC(self.logical_ms, self.counter + 1, self.node_id, clock=self.clock)
+
+    def merge(self, received: HLC) -> HLC:
+        """Merge a received HLC, applying clamp + skew reject."""
+        now_ms = self.clock.now_ms()
+        if received.logical_ms > now_ms + 2 * self.HLC_MAX_SKEW_MS:
+            # Increment skew-rejection counter (using list as a mutable bucket on a frozen dc).
+            self._skew_rejections.append(1)
+            raise HLCSkewError(
+                f"received HLC {received.logical_ms} exceeds 2× max skew "
+                f"({2 * self.HLC_MAX_SKEW_MS}ms) above local now {now_ms}"
+            )
+        clamped_l = min(received.logical_ms, now_ms + self.HLC_MAX_SKEW_MS)
+        new_l = max(self.logical_ms, clamped_l, now_ms)
+        if new_l == self.logical_ms == clamped_l:
+            new_c = max(self.counter, received.counter) + 1
+        elif new_l == self.logical_ms:
+            new_c = self.counter + 1
+        elif new_l == clamped_l:
+            new_c = received.counter + 1
+        else:
+            new_c = 0
+        # Carry the skew-rejection bucket forward so metrics persist across merges.
+        merged = HLC(new_l, new_c, self.node_id, clock=self.clock)
+        merged._skew_rejections.extend(self._skew_rejections)
+        return merged
+
+    def get_skew_metrics(self) -> dict[str, int]:
+        """Return clock-skew telemetry for this HLC chain."""
+        return {
+            "skew_rejections_total": len(self._skew_rejections),
+            "current_logical_ms": self.logical_ms,
+            "current_counter": self.counter,
+        }
+
+    def to_cbor(self) -> list:
+        """CBOR triple per protected header label -65603."""
+        return [self.logical_ms, self.counter, self.node_id]
+
+    @classmethod
+    def from_cbor(cls, triple: list) -> HLC:
+        return cls(int(triple[0]), int(triple[1]), bytes(triple[2]))
+
+    def __repr__(self) -> str:
+        return f"HLC({self.logical_ms}.{self.counter}@{self.node_id.hex()[:8]})"

hypermind/crypto/hpke.py

@@ -0,0 +1,277 @@
+"""RFC 9180 HPKE (base mode) — DHKEM(X25519, HKDF-SHA256) + AES-256-GCM/ChaCha20-Poly1305.
+
+Implements only HPKE base mode (no PSK, no auth), single-shot seal/open.
+Used by L3 envelope encryption (`cose_encrypt.py`) and Room epoch keying.
+
+Domain-separation note: a dedicated `DomainTag.HPKE_INFO` byte was considered
+for `crypto/domain.py`, but the existing closed-set tag space (0x01..0x18) is
+guarded by `reject_unallocated`. Adding 0x40 would create a hole and break the
+contiguous-allocation invariant tested in `tests/test_crypto.py`. Caller-supplied
+HPKE `info` strings already provide cross-protocol separation per RFC 9180 §9.6.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+
+from cryptography.hazmat.primitives import hashes, hmac
+from cryptography.hazmat.primitives.asymmetric import x25519
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM, ChaCha20Poly1305
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+# --------------------------------------------------------------------------- #
+# Suite registry — RFC 9180 §7.
+# --------------------------------------------------------------------------- #
+SUITE_DHKEM_X25519_HKDF_SHA256_AES256GCM = 0x0001
+SUITE_DHKEM_X25519_HKDF_SHA256_CHACHA20_POLY1305 = 0x0002
+
+# RFC 9180 §7.1 KEM ID for DHKEM(X25519, HKDF-SHA256)
+_KEM_ID_X25519 = 0x0020
+# RFC 9180 §7.2 KDF ID for HKDF-SHA256
+_KDF_ID_HKDF_SHA256 = 0x0001
+# RFC 9180 §7.3 AEAD IDs
+_AEAD_ID_AES256GCM = 0x0002
+_AEAD_ID_CHACHA20POLY1305 = 0x0003
+
+_MODE_BASE = 0x00
+
+_NH = 32  # HKDF-SHA256 output length
+_NSECRET = 32  # DHKEM(X25519) shared-secret length
+_NPK = 32  # X25519 public-key length
+_NSK = 32  # X25519 private-key length
+
+
+def _suite_aead(suite_id: int) -> tuple[int, int]:
+    """Return (Nk, Nn) for the suite's AEAD."""
+    if suite_id == SUITE_DHKEM_X25519_HKDF_SHA256_AES256GCM:
+        return 32, 12
+    if suite_id == SUITE_DHKEM_X25519_HKDF_SHA256_CHACHA20_POLY1305:
+        return 32, 12
+    raise ValueError(f"unsupported HPKE suite id: 0x{suite_id:04x}")
+
+
+def _suite_aead_id(suite_id: int) -> int:
+    if suite_id == SUITE_DHKEM_X25519_HKDF_SHA256_AES256GCM:
+        return _AEAD_ID_AES256GCM
+    if suite_id == SUITE_DHKEM_X25519_HKDF_SHA256_CHACHA20_POLY1305:
+        return _AEAD_ID_CHACHA20POLY1305
+    raise ValueError(f"unsupported HPKE suite id: 0x{suite_id:04x}")
+
+
+def _new_aead(suite_id: int, key: bytes) -> AESGCM | ChaCha20Poly1305:
+    aead_id = _suite_aead_id(suite_id)
+    if aead_id == _AEAD_ID_AES256GCM:
+        return AESGCM(key)
+    return ChaCha20Poly1305(key)
+
+
+# --------------------------------------------------------------------------- #
+# HKDF labelled extract/expand — RFC 9180 §4.1.
+# --------------------------------------------------------------------------- #
+_HPKE_VERSION = b"HPKE-v1"
+
+
+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" * _NH
+    return _hmac_sha256(salt, ikm)
+
+
+def _hkdf_expand(prk: bytes, info: bytes, length: int) -> bytes:
+    n = (length + _NH - 1) // _NH
+    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]
+
+
+def _suite_id_kem() -> bytes:
+    # "KEM" || I2OSP(kem_id, 2)
+    return b"KEM" + struct.pack(">H", _KEM_ID_X25519)
+
+
+def _suite_id_hpke(suite_id: int) -> bytes:
+    # "HPKE" || I2OSP(kem_id,2) || I2OSP(kdf_id,2) || I2OSP(aead_id,2)
+    return (
+        b"HPKE"
+        + struct.pack(">H", _KEM_ID_X25519)
+        + struct.pack(">H", _KDF_ID_HKDF_SHA256)
+        + struct.pack(">H", _suite_aead_id(suite_id))
+    )
+
+
+def _labeled_extract(salt: bytes, suite_id_bytes: bytes, label: bytes, ikm: bytes) -> bytes:
+    labeled_ikm = _HPKE_VERSION + suite_id_bytes + label + ikm
+    return _hkdf_extract(salt, labeled_ikm)
+
+
+def _labeled_expand(
+    prk: bytes, suite_id_bytes: bytes, label: bytes, info: bytes, length: int
+) -> bytes:
+    labeled_info = struct.pack(">H", length) + _HPKE_VERSION + suite_id_bytes + label + info
+    return _hkdf_expand(prk, labeled_info, length)
+
+
+# --------------------------------------------------------------------------- #
+# DHKEM(X25519, HKDF-SHA256) — RFC 9180 §4.1.
+# --------------------------------------------------------------------------- #
+def _serialize_pk(pk: x25519.X25519PublicKey) -> bytes:
+    return pk.public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+
+def _deserialize_pk(raw: bytes) -> x25519.X25519PublicKey:
+    return x25519.X25519PublicKey.from_public_bytes(raw)
+
+
+def _serialize_sk(sk: x25519.X25519PrivateKey) -> bytes:
+    return sk.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+
+
+def _deserialize_sk(raw: bytes) -> x25519.X25519PrivateKey:
+    return x25519.X25519PrivateKey.from_private_bytes(raw)
+
+
+def _extract_and_expand(dh: bytes, kem_context: bytes) -> bytes:
+    suite_id = _suite_id_kem()
+    eae_prk = _labeled_extract(b"", suite_id, b"eae_prk", dh)
+    return _labeled_expand(eae_prk, suite_id, b"shared_secret", kem_context, _NSECRET)
+
+
+def _kem_encap(
+    recipient_pub: bytes, eph_priv: x25519.X25519PrivateKey | None = None
+) -> tuple[bytes, bytes]:
+    """DHKEM Encap. Returns (shared_secret, enc)."""
+    pk_r = _deserialize_pk(recipient_pub)
+    if eph_priv is None:
+        eph_priv = x25519.X25519PrivateKey.generate()
+    enc = _serialize_pk(eph_priv.public_key())
+    dh = eph_priv.exchange(pk_r)
+    kem_context = enc + recipient_pub
+    shared_secret = _extract_and_expand(dh, kem_context)
+    return shared_secret, enc
+
+
+def _kem_decap(recipient_priv: bytes, enc: bytes) -> bytes:
+    sk_r = _deserialize_sk(recipient_priv)
+    pk_e = _deserialize_pk(enc)
+    dh = sk_r.exchange(pk_e)
+    pk_r_bytes = _serialize_pk(sk_r.public_key())
+    kem_context = enc + pk_r_bytes
+    return _extract_and_expand(dh, kem_context)
+
+
+# --------------------------------------------------------------------------- #
+# Key schedule (base mode) — RFC 9180 §5.1.
+# --------------------------------------------------------------------------- #
+def _key_schedule_base(suite_id: int, shared_secret: bytes, info: bytes) -> tuple[bytes, bytes]:
+    """Return (key, base_nonce) for base-mode single-shot AEAD."""
+    suite_bytes = _suite_id_hpke(suite_id)
+    psk_id_hash = _labeled_extract(b"", suite_bytes, b"psk_id_hash", b"")
+    info_hash = _labeled_extract(b"", suite_bytes, b"info_hash", info)
+    key_schedule_context = bytes([_MODE_BASE]) + psk_id_hash + info_hash
+
+    secret = _labeled_extract(shared_secret, suite_bytes, b"secret", b"")
+    nk, nn = _suite_aead(suite_id)
+    key = _labeled_expand(secret, suite_bytes, b"key", key_schedule_context, nk)
+    base_nonce = _labeled_expand(secret, suite_bytes, b"base_nonce", key_schedule_context, nn)
+    return key, base_nonce
+
+
+# --------------------------------------------------------------------------- #
+# Public API.
+# --------------------------------------------------------------------------- #
+def seal(
+    suite_id: int,
+    recipient_pub: bytes,
+    info: bytes,
+    aad: bytes,
+    plaintext: bytes,
+    *,
+    _test_eph_priv: bytes | None = None,
+) -> tuple[bytes, bytes]:
+    """HPKE base-mode single-shot seal.
+
+    Args:
+        suite_id: One of the SUITE_* constants in this module.
+        recipient_pub: Recipient X25519 public key (32 bytes).
+        info: Application-bound contextual string per RFC 9180 §5.1.
+        aad: Additional authenticated data (bound by AEAD).
+        plaintext: Bytes to encrypt.
+        _test_eph_priv: Test-only override for the ephemeral private key. Production
+            callers MUST omit this; a fresh random ephemeral is generated per call.
+
+    Returns:
+        Tuple `(enc, ciphertext)`. `enc` is the encapsulated key (32 bytes for
+        X25519). `ciphertext` includes the 16-byte AEAD tag.
+    """
+    if len(recipient_pub) != _NPK:
+        raise ValueError(f"recipient_pub must be {_NPK} bytes")
+    eph = _deserialize_sk(_test_eph_priv) if _test_eph_priv is not None else None
+    shared_secret, enc = _kem_encap(recipient_pub, eph_priv=eph)
+    key, base_nonce = _key_schedule_base(suite_id, shared_secret, info)
+    ct = _new_aead(suite_id, key).encrypt(base_nonce, plaintext, aad)
+    return enc, ct
+
+
+def open(
+    suite_id: int,
+    recipient_priv: bytes,
+    enc: bytes,
+    info: bytes,
+    aad: bytes,
+    ciphertext: bytes,
+) -> bytes:
+    """HPKE base-mode single-shot open.
+
+    Args:
+        suite_id: One of the SUITE_* constants in this module.
+        recipient_priv: Recipient X25519 private key (32 bytes).
+        enc: Encapsulated key from `seal()`.
+        info: Same `info` passed to `seal()`.
+        aad: Same `aad` passed to `seal()`.
+        ciphertext: Output of `seal()`.
+
+    Returns:
+        Decrypted plaintext bytes.
+
+    Raises:
+        cryptography.exceptions.InvalidTag: AEAD verification failed.
+    """
+    if len(recipient_priv) != _NSK:
+        raise ValueError(f"recipient_priv must be {_NSK} bytes")
+    if len(enc) != _NPK:
+        raise ValueError(f"enc must be {_NPK} bytes")
+    shared_secret = _kem_decap(recipient_priv, enc)
+    key, base_nonce = _key_schedule_base(suite_id, shared_secret, info)
+    return _new_aead(suite_id, key).decrypt(base_nonce, ciphertext, aad)
+
+
+def generate_keypair() -> tuple[bytes, bytes]:
+    """Generate a fresh X25519 keypair. Returns `(private_raw, public_raw)`."""
+    sk = x25519.X25519PrivateKey.generate()
+    return _serialize_sk(sk), _serialize_pk(sk.public_key())
+
+
+# Pure-Python fallback gate (RFC 9180 implementations exist but the project pins
+# `cryptography>=44`; any host missing native primitives can opt-in here).
+if os.environ.get("HM_PURE_PY_HPKE") == "1":  # pragma: no cover  - opt-in path
+    raise RuntimeError(
+        "HM_PURE_PY_HPKE=1 set but no pure-Python HPKE backend is bundled. "
+        "Install cryptography>=44 or remove the env var."
+    )

hypermind/crypto/kms.py

@@ -0,0 +1,196 @@
+"""Signer abstraction — pluggable signing backends for v0.8 production profile.
+
+The SDK historically embedded `Keypair` directly in the agent. That is fine
+for sandbox / single-tenant deployments but blocks the v0.8 production
+profile where signing keys are expected to live in:
+
+  * AWS KMS — keys created with `KeySpec=ECC_NIST_P256` cannot be used
+    directly (Ed25519 is not yet GA in KMS as of 2026-04-27); the planned
+    backend wraps a customer-supplied `Sign` API call and validates the
+    returned DER signature against the published kid.
+  * GCP Cloud KMS — `EC_SIGN_ED25519` algorithm; the backend issues an
+    `AsymmetricSign` RPC and unwraps the IETF-encoded signature.
+  * HashiCorp Vault Transit — Ed25519 keys via the `transit/sign/<key>`
+    endpoint; backend uses the leased AppRole token, refreshes via the
+    sidecar.
+
+All three back-ends are wired in v0.8.5 (see ROADMAP). v0.8.0 ships
+the `Signer` Protocol and the `LocalSigner` adapter so the rest of the
+SDK can already program against the abstraction.
+
+Security invariants (production profile):
+
+* `kid` is always the 32-byte Ed25519 public key half — never the secret.
+  This matches the wire format's `COSE_KID` discriminator.
+* `sign(msg)` MUST return a raw signature (no envelope, no DER wrapper)
+  matching `crypto.signing.verify_signature(alg, public_key, sig, msg)`.
+* The Signer MUST refuse `sign()` after the underlying key material has
+  been rotated; callers detect this via a stable `kid` plus monotonic
+  rotation epoch.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from hypermind.crypto.signing import ALG_ED25519, Keypair
+
+
+@runtime_checkable
+class Signer(Protocol):
+    """Pluggable signing backend.
+
+    Implementations MUST be safe to call concurrently from multiple
+    coroutines; the production AWS/GCP/Vault adapters serialise inside
+    the SDK they wrap.
+    """
+
+    @property
+    def public_key(self) -> bytes:
+        """Full algorithm-specific public-key material.
+
+        For Ed25519: the 32-byte raw public key.
+        For composite (alg=-49): `ed_pk(32) || mldsa_pk(1952)`.
+        """
+        ...
+
+    @property
+    def kid(self) -> bytes:
+        """Stable 32-byte agent identity (Ed25519 public-key half)."""
+        ...
+
+    @property
+    def alg(self) -> int:
+        """COSE algorithm identifier (e.g. ALG_ED25519 = -8)."""
+        ...
+
+    def sign(self, message: bytes) -> bytes:
+        """Return a raw signature over `message` (no envelope)."""
+        ...
+
+
+class LocalSigner:
+    """In-process Signer backed by a `Keypair`.
+
+    This is the v0.1–v0.7 path: the secret is held in memory by the
+    agent. Suitable for sandbox/testbed and for self-hosted deployments
+    where operators have decided that an HSM/KMS dependency is not
+    required.
+
+    The constructor accepts either a `Keypair` (preferred) or a 32-byte
+    Ed25519 seed for deterministic test fixtures.
+    """
+
+    def __init__(self, keypair: Keypair) -> None:
+        self._kp = keypair
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> LocalSigner:
+        return cls(Keypair.from_seed(seed))
+
+    @classmethod
+    def generate(cls, *, alg: int = ALG_ED25519) -> LocalSigner:
+        return cls(Keypair.generate(alg=alg))
+
+    @property
+    def keypair(self) -> Keypair:
+        """Escape hatch for code paths that still need the raw Keypair.
+
+        Removed in v0.9; callers should switch to `sign()` and `kid`.
+        """
+        return self._kp
+
+    @property
+    def public_key(self) -> bytes:
+        return self._kp.public_bytes
+
+    @property
+    def kid(self) -> bytes:
+        return self._kp.kid
+
+    @property
+    def alg(self) -> int:
+        return self._kp.alg
+
+    def sign(self, message: bytes) -> bytes:
+        return self._kp.sign(message)
+
+    def __repr__(self) -> str:
+        return f"LocalSigner(kid={self.kid.hex()[:16]}..., alg={self.alg})"
+
+
+class KMSSigner:
+    """Stub Signer for cloud KMS / Vault back-ends.
+
+    **Not yet wired** — instantiating and calling `sign()` raises
+    `NotImplementedError`. The class exists so downstream code can
+    program against the contract today and the ROADMAP 0.8.5 backends
+    can drop in without an API break.
+
+    Construction parameters (anticipated):
+
+    * `provider` — one of `"aws-kms"`, `"gcp-kms"`, `"vault-transit"`.
+    * `key_uri` — provider-native key reference. Examples:
+        - AWS:   ``arn:aws:kms:us-east-1:123456789012:key/abcd-…``
+        - GCP:   ``projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1``
+        - Vault: ``transit/keys/<key-name>``
+    * `published_kid` — the 32-byte Ed25519 public key half, fetched
+      out-of-band from the provider's `GetPublicKey` API and pinned at
+      construction. The Signer refuses to sign if the provider rotates
+      the underlying material without the operator updating this pin.
+    * `auth` — provider auth context (boto3 session, GCP credentials,
+      Vault token). Held by reference; the SDK does not persist it.
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: str,
+        key_uri: str,
+        published_kid: bytes,
+        auth: object | None = None,
+        alg: int = ALG_ED25519,
+    ) -> None:
+        if len(published_kid) != 32:
+            raise ValueError("published_kid must be 32 bytes (Ed25519 public)")
+        if provider not in ("aws-kms", "gcp-kms", "vault-transit"):
+            raise ValueError(
+                f"unknown KMS provider {provider!r}; expected aws-kms | gcp-kms | vault-transit"
+            )
+        self._provider = provider
+        self._key_uri = key_uri
+        self._kid = published_kid
+        self._auth = auth
+        self._alg = alg
+
+    @property
+    def public_key(self) -> bytes:
+        # Today we only know the Ed25519 half (the published kid). When
+        # the v0.8.5 backends land, the constructor will fetch the full
+        # public-key bytes (composite case includes the ML-DSA-65 half)
+        # via the provider's GetPublicKey RPC.
+        return self._kid
+
+    @property
+    def kid(self) -> bytes:
+        return self._kid
+
+    @property
+    def alg(self) -> int:
+        return self._alg
+
+    def sign(self, message: bytes) -> bytes:
+        raise NotImplementedError(
+            "KMS backend not yet wired; see ROADMAP 0.8.5. "
+            f"Provider={self._provider!r}, key_uri={self._key_uri!r}. "
+            "Use LocalSigner for now."
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"KMSSigner(provider={self._provider!r}, "
+            f"kid={self._kid.hex()[:16]}..., alg={self._alg})"
+        )
+
+
+__all__ = ["KMSSigner", "LocalSigner", "Signer"]