hypermind 0.11.0__py3-none-any.whl

hypermind/crypto/frost.py

@@ -0,0 +1,771 @@
+"""FROST (RFC 9591) k-of-n threshold Schnorr signatures over Ed25519.
+
+This is a working implementation suitable for namespace policy
+signing (e.g. 5-of-7 maintainer council). It uses the Ed25519
+ciphersuite (RFC 9591 §6.1) with the following hardening steps
+(applied per self-heal Cycle-1 Finding #2 and panel architectural
+shift A2-1):
+
+  1. Hedged-random nonce derivation per RFC 9591 §4.2 — each Round-1
+     commit() call mixes a fresh 32-byte randomizer (from
+     `secrets.token_bytes(32)`) into the deterministic PRF inputs.
+     The randomizer is published alongside (D_i, E_i) in the
+     `Commitment` so the same Round-2 signer can re-derive
+     (d_i, e_i). This is Drijvers-replay-immune by construction:
+     each session uses fresh entropy, so a process restart that
+     empties the `_SEEN_TRANSCRIPTS` LRU does not re-open the
+     replay window. The earlier RFC 9591 §4.1 deterministic variant
+     required durable signer state to be safe across restart and is
+     no longer used.
+  2. Small-subgroup validation — every received commitment point is
+     multiplied by the group order L; the result must be the identity.
+  3. Challenge hash binds the full encoded commitment list, not just
+     `R`. Even if an attacker could craft commitments that aggregate
+     to a chosen R, the challenge would not match.
+  4. Per-share input validation — share index must be in `[1, 2**32)`,
+     duplicate indices are rejected by the aggregator, and signers
+     refuse to sign the same `(commitments, message)` twice.
+
+Algorithm (the bits we actually use):
+  - Trusted setup (DKG-trusted-dealer variant): a dealer samples a
+    polynomial f of degree t-1, with f(0) = group secret. Each
+    participant i ∈ {1..n} receives sk_i = f(i). The group public key
+    is Y = f(0) * G.
+  - Signing: t participants each derive (d_i, e_i) deterministically,
+    publish commitments (D_i, E_i) = (d_i*G, e_i*G). Aggregator
+    computes binding factor ρ_i for each participant from all
+    (D_i, E_i, i, M, group_pk), forms R = Σ_i (D_i + ρ_i * E_i), and
+    challenge c = H(commits || group_pk || R || M). Each participant
+    returns z_i = d_i + ρ_i*e_i + λ_i * sk_i * c, where λ_i is the
+    i-th Lagrange coefficient. Aggregate signature (R, z = Σ z_i)
+    verifies as z*G == R + c*Y.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+
+# Edwards25519 group operations from PyNaCl/NaCl.
+from nacl.bindings import (
+    crypto_core_ed25519_add,
+    crypto_core_ed25519_is_valid_point,
+    crypto_core_ed25519_scalar_add,
+    crypto_core_ed25519_scalar_invert,
+    crypto_core_ed25519_scalar_mul,
+    crypto_core_ed25519_scalar_reduce,
+    crypto_scalarmult_ed25519_base_noclamp,
+    crypto_scalarmult_ed25519_noclamp,
+)
+
+L = 2**252 + 27742317777372353535851937790883648493  # Ed25519 group order
+SCALAR_L_BYTES = L.to_bytes(32, "little")
+ZERO_SCALAR = b"\x00" * 32
+IDENTITY_POINT = b"\x01" + b"\x00" * 31  # encoding of the identity
+
+MAX_SIGNER_INDEX = 2**32
+
+# A process-wide guard against signing the same (commitments, message)
+# twice with the same nonce. Closes the Drijvers-style attack where a
+# malicious aggregator presents the honest signer with two different
+# commitment sets and the signer accidentally re-uses (d_i, e_i).
+#
+# Bounded LRU cap (closes Cycle-2 Finding #1): without a bound, a
+# long-running signer accumulates a transcript per signature forever,
+# leaking memory and providing a DoS vector. 65536 entries × 64 bytes
+# is ~4 MB resident, sufficient to absorb any realistic concurrent
+# signing rate while keeping memory bounded.
+_SIGN_LOCK = threading.Lock()
+MAX_SEEN_TRANSCRIPTS = 65_536
+_SEEN_TRANSCRIPTS: OrderedDict[bytes, None] = OrderedDict()
+
+
+# ---- pluggable transcript store (ROADMAP §0.7.8) ---------------------
+#
+# The default ``InMemoryLRU`` is a process-local LRU sized at
+# MAX_SEEN_TRANSCRIPTS entries. Operators running long-lived signers
+# across restarts SHOULD replace it with a durable backend (Redis,
+# SQLite, etc.) by calling :func:`set_transcript_store`.
+#
+# Durability contract for any TranscriptStore implementation:
+#   1. ``record(h)`` MUST persist before the signer's ``z_i`` leaves
+#      the process. A backend that buffers asynchronously re-opens the
+#      Drijvers replay window across restart.
+#   2. ``seen(h)`` MUST be linearisable with respect to ``record`` from
+#      the same signer. Concurrent signers MAY observe each other's
+#      writes lazily but a single signer must see its own writes.
+#   3. The store MAY evict old entries (LRU/TTL) but MUST NOT evict
+#      entries younger than the longest plausible session lifetime
+#      (signers SHOULD configure a TTL ≥ 24h).
+
+
+class TranscriptStore:
+    """Protocol for the FROST nonce-reuse dedup store.
+
+    Implementations MUST be threadsafe. ``record`` returns ``True`` if
+    the transcript was new (signature MAY proceed) and ``False`` if it
+    has been seen before (signer MUST refuse to sign).
+    """
+
+    def seen(self, transcript_hash: bytes) -> bool:  # pragma: no cover - protocol
+        raise NotImplementedError
+
+    def record(self, transcript_hash: bytes) -> bool:  # pragma: no cover - protocol
+        raise NotImplementedError
+
+    def clear(self) -> None:  # pragma: no cover - protocol
+        raise NotImplementedError
+
+
+class InMemoryLRU(TranscriptStore):
+    """Default backend: bounded in-memory LRU, threadsafe.
+
+    Capacity defaults to :data:`MAX_SEEN_TRANSCRIPTS` (65 536 entries
+    × 64 bytes ≈ 4 MB resident). Loses state on process restart; for
+    durability across restart, swap in a database-backed store via
+    :func:`set_transcript_store`.
+    """
+
+    def __init__(self, capacity: int = MAX_SEEN_TRANSCRIPTS) -> None:
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+        self._capacity = capacity
+        self._lock = threading.Lock()
+        self._seen: OrderedDict[bytes, None] = OrderedDict()
+
+    def seen(self, transcript_hash: bytes) -> bool:
+        with self._lock:
+            return transcript_hash in self._seen
+
+    def record(self, transcript_hash: bytes) -> bool:
+        with self._lock:
+            if transcript_hash in self._seen:
+                self._seen.move_to_end(transcript_hash)
+                return False
+            self._seen[transcript_hash] = None
+            while len(self._seen) > self._capacity:
+                self._seen.popitem(last=False)
+            return True
+
+    def clear(self) -> None:
+        with self._lock:
+            self._seen.clear()
+
+
+_TRANSCRIPT_STORE: TranscriptStore = InMemoryLRU()
+
+
+class FileTranscriptStore(TranscriptStore):
+    """Durable transcript store backed by a JSON file on disk.
+
+    Suitable for long-lived signers that must survive process restarts
+    without re-opening the Drijvers nonce-reuse window. Each call to
+    ``record()`` persists the updated set to ``path`` before returning.
+
+    Thread-safety: a per-instance lock serialises concurrent reads/writes.
+    Only the instance that holds the lock writes to the file; concurrent
+    processes sharing the same file path are NOT safe — use a database-
+    backed store for multi-process deployments.
+    """
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+        self._seen: set[bytes] = self._load()
+
+    def _load(self) -> set[bytes]:
+        import base64
+        import json
+
+        try:
+            with open(self._path) as f:
+                return {base64.b64decode(x) for x in json.load(f)}
+        except (FileNotFoundError, json.JSONDecodeError):
+            return set()
+
+    def save(self) -> None:
+        """Persist the current seen-set to disk (called automatically by ``record``)."""
+        import base64
+        import json
+
+        with open(self._path, "w") as f:
+            json.dump([base64.b64encode(h).decode() for h in self._seen], f)
+
+    def record(self, transcript_hash: bytes) -> bool:
+        """Return True if new (not seen), False if replay detected. Persists on new entry."""
+        with self._lock:
+            if transcript_hash in self._seen:
+                return False
+            self._seen.add(transcript_hash)
+            self.save()
+            return True
+
+    def seen(self, transcript_hash: bytes) -> bool:
+        with self._lock:
+            return transcript_hash in self._seen
+
+    def clear(self) -> None:
+        with self._lock:
+            self._seen.clear()
+            self.save()
+
+
+def set_transcript_store(store: TranscriptStore) -> None:
+    """Install a custom :class:`TranscriptStore` backend.
+
+    This is process-global; call once at startup BEFORE any FROST
+    signing happens. Re-installing mid-session is allowed but discards
+    the previous store's history — the durability contract above no
+    longer holds for transcripts seen by the previous backend.
+
+    SAFETY (closes self-heal Cycle-3 issue #1): if the previous store has
+    already recorded transcripts, swapping it out re-opens the Drijvers
+    nonce-reuse window for those transcripts. Emits a RuntimeWarning so
+    operators don't silently swap mid-session. Tests that legitimately
+    need a fresh store should call :func:`reset_seen_transcripts` first.
+    """
+    global _TRANSCRIPT_STORE
+    # Detect non-empty previous store (legacy mirror OR backend-specific
+    # internal LRU). `len(...) > 0` is explicit so an empty OrderedDict
+    # (falsy) doesn't suppress the warning.
+    has_prior = len(_SEEN_TRANSCRIPTS) > 0
+    if not has_prior:
+        prior_seen = getattr(_TRANSCRIPT_STORE, "_seen", None)
+        if prior_seen is not None and len(prior_seen) > 0:
+            has_prior = True
+    if has_prior:
+        import warnings as _w
+
+        _w.warn(
+            "[FROST-TRANSCRIPT-STORE-SWAP] set_transcript_store() called while "
+            "the previous store has recorded transcripts. The new store does NOT "
+            "carry forward the old transcripts — this re-opens the Drijvers "
+            "nonce-reuse window for any commitments already used. Call "
+            "reset_seen_transcripts() explicitly if this is intended.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    _TRANSCRIPT_STORE = store
+
+
+def get_transcript_store() -> TranscriptStore:
+    """Return the currently-installed transcript store."""
+    return _TRANSCRIPT_STORE
+
+
+def _record_transcript(transcript: bytes) -> bool:
+    """Returns True if the transcript was new (signature may proceed),
+    False if it has been seen before (signer MUST refuse).
+
+    Routes through the pluggable store; default backend is the
+    process-local LRU above. Also mirrors into the legacy
+    ``_SEEN_TRANSCRIPTS`` OrderedDict for back-compat with tests that
+    still introspect it directly.
+    """
+    new = _TRANSCRIPT_STORE.record(transcript)
+    # Maintain the legacy module-level mirror unconditionally (closes
+    # self-heal Cycle-3 issue #1: previous behaviour only mirrored under
+    # the default InMemoryLRU, so any test or operator tool that
+    # introspected `_SEEN_TRANSCRIPTS` saw stale state the moment a
+    # custom backend was installed via `set_transcript_store()`. The
+    # mirror is now backend-agnostic and stays in lock-step with the
+    # store's own bookkeeping). New code SHOULD route through
+    # `get_transcript_store().seen(h)` instead of poking the mirror —
+    # the mirror is retained only for back-compat with tests written
+    # against the v0.6 API and is scheduled for removal in v1.0.
+    if new:
+        _SEEN_TRANSCRIPTS[transcript] = None
+        while len(_SEEN_TRANSCRIPTS) > MAX_SEEN_TRANSCRIPTS:
+            _SEEN_TRANSCRIPTS.popitem(last=False)
+    else:
+        # Touch on hit so LRU semantics stay consistent.
+        _SEEN_TRANSCRIPTS.move_to_end(transcript, last=True)
+    return new
+
+
+def reset_seen_transcripts() -> None:
+    """Test hook — clears the dedup cache between test cases. NEVER call
+    in production: doing so re-opens the Drijvers nonce-reuse window."""
+    with _SIGN_LOCK:
+        _SEEN_TRANSCRIPTS.clear()
+        _TRANSCRIPT_STORE.clear()
+
+
+def scalar_from_int(x: int) -> bytes:
+    return (x % L).to_bytes(32, "little")
+
+
+def scalar_to_int(s: bytes) -> int:
+    return int.from_bytes(s, "little")
+
+
+def random_scalar() -> bytes:
+    return crypto_core_ed25519_scalar_reduce(secrets.token_bytes(64))
+
+
+def hash_to_scalar(*chunks: bytes, label: bytes = b"FROST/ed25519") -> bytes:
+    """SHA-512 → mod L. Used for binding factors and challenge hashes."""
+    h = hashlib.sha512()
+    h.update(label)
+    for c in chunks:
+        h.update(len(c).to_bytes(4, "big"))
+        h.update(c)
+    digest = h.digest()
+    return crypto_core_ed25519_scalar_reduce(digest)
+
+
+def lagrange_coefficient(i: int, indices: list[int]) -> bytes:
+    """Compute λ_i = Π_{j != i} j / (j - i) mod L."""
+    num_int = 1
+    den_int = 1
+    for j in indices:
+        if j == i:
+            continue
+        num_int = (num_int * j) % L
+        den_int = (den_int * ((j - i) % L)) % L
+    num = scalar_from_int(num_int)
+    den = scalar_from_int(den_int)
+    den_inv = crypto_core_ed25519_scalar_invert(den)
+    return crypto_core_ed25519_scalar_mul(num, den_inv)
+
+
+def _validate_point(p: bytes) -> None:
+    """Reject the identity and any low-order / non-canonical encodings.
+
+    `crypto_core_ed25519_is_valid_point` performs canonicality + the
+    cofactor-clearing check that detects small-subgroup attacks. Reject
+    the identity explicitly because libsodium's helper accepts it.
+    """
+    if len(p) != 32:
+        raise ValueError("ed25519 point must be 32 bytes")
+    if p == IDENTITY_POINT:
+        raise ValueError("rejected identity point in commitment")
+    if not crypto_core_ed25519_is_valid_point(p):
+        raise ValueError("rejected invalid / small-subgroup point")
+
+
+def _validate_scalar(s: bytes) -> None:
+    """Reject zero scalars and non-canonical encodings."""
+    if len(s) != 32:
+        raise ValueError("scalar must be 32 bytes")
+    if s == ZERO_SCALAR:
+        raise ValueError("rejected zero scalar")
+    if int.from_bytes(s, "little") >= L:
+        raise ValueError("rejected non-canonical scalar (>= L)")
+
+
+# ---- key generation (trusted dealer) -----------------------------------
+
+
+@dataclass(frozen=True)
+class FrostShare:
+    index: int  # 1-indexed participant identifier
+    secret: bytes  # 32-byte scalar = f(index)
+    group_public: bytes  # 32-byte compressed Edwards point Y = f(0)*G
+
+    def __post_init__(self) -> None:
+        if not (1 <= self.index < MAX_SIGNER_INDEX):
+            raise ValueError(f"share index {self.index} out of range [1, {MAX_SIGNER_INDEX})")
+        _validate_scalar(self.secret)
+        _validate_point(self.group_public)
+
+    def __repr__(self) -> str:
+        # Never render `secret` — it's the per-signer Shamir share. Show
+        # only the share index and group public key (both public values).
+        return (
+            f"FrostShare(index={self.index}, "
+            f"group_public={self.group_public.hex()[:16]}..., "
+            f"secret=<redacted>)"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __reduce__(self):
+        # Pickle is a known leak vector — a serialized FrostShare would
+        # carry `secret` to disk / over the wire. Refuse outright.
+        raise TypeError("refusing to pickle secret material; use the in-memory store")
+
+
+def generate_shares(t: int, n: int) -> list[FrostShare]:
+    """Trusted-dealer DKG: produce n shares of a fresh secret f(0)."""
+    if not (1 <= t <= n):
+        raise ValueError("require 1 <= t <= n")
+    if n >= MAX_SIGNER_INDEX:
+        raise ValueError(f"n must be < {MAX_SIGNER_INDEX}")
+    coeffs = [random_scalar() for _ in range(t)]
+    group_secret = coeffs[0]
+    group_public = crypto_scalarmult_ed25519_base_noclamp(group_secret)
+
+    shares = []
+    for i in range(1, n + 1):
+        x = i
+        x_pow = scalar_from_int(1)
+        x_step = scalar_from_int(x)
+        acc = scalar_from_int(0)
+        for k, a_k in enumerate(coeffs):
+            term = crypto_core_ed25519_scalar_mul(a_k, x_pow)
+            acc = crypto_core_ed25519_scalar_add(acc, term)
+            if k < len(coeffs) - 1:
+                x_pow = crypto_core_ed25519_scalar_mul(x_pow, x_step)
+        shares.append(FrostShare(index=i, secret=acc, group_public=group_public))
+    return shares
+
+
+# ---- signing ----------------------------------------------------------
+
+
+RANDOMIZER_LEN = 32
+
+
+@dataclass(frozen=True)
+class Commitment:
+    """Round-1 commitment carrying the hedged-random randomizer.
+
+    Per RFC 9591 §4.2 (hedged-random variant), each Round-1 session
+    samples a fresh 32-byte `randomizer` that is mixed into the nonce
+    derivation. The randomizer is **public** — it is transmitted with
+    `(D_i, E_i)` so Round-2 signers (and only Round-2 signers, who
+    additionally hold the secret share) can re-derive `(d_i, e_i)`.
+    The randomizer alone reveals nothing about the secret share.
+
+    Wire-version note: the addition of `randomizer` does not change
+    the FROST wire format used by HyperMind statements — `Commitment`
+    is an in-memory protocol object passed between Round-1 and
+    Round-2 of a single signing session, not embedded in
+    `SignedStatement`. No `wire_version` bump is required.
+    """
+
+    index: int
+    hiding: bytes  # D_i = d_i * G
+    binding: bytes  # E_i = e_i * G
+    randomizer: bytes = b"\x00" * RANDOMIZER_LEN  # RFC 9591 §4.2 hedge
+
+    def __post_init__(self) -> None:
+        if not (1 <= self.index < MAX_SIGNER_INDEX):
+            raise ValueError(f"commitment index {self.index} out of range")
+        _validate_point(self.hiding)
+        _validate_point(self.binding)
+        if len(self.randomizer) != RANDOMIZER_LEN:
+            raise ValueError(
+                f"randomizer must be {RANDOMIZER_LEN} bytes, got {len(self.randomizer)}"
+            )
+
+
+@dataclass(frozen=True)
+class _Nonce:
+    hiding: bytes  # d_i
+    binding: bytes  # e_i
+
+
+def _derive_nonce(secret: bytes, msg: bytes, index: int, *, label: bytes) -> bytes:
+    """Legacy deterministic nonce derivation (RFC 9591 §4.1).
+
+    Retained for backward-compat callers and the Cycle-2 regression
+    test that pins the determinism property. New code SHOULD use
+    `_derive_nonce_hedged()` (RFC 9591 §4.2) which mixes in fresh
+    entropy and is Drijvers-replay-immune across process restart.
+
+    The PRF input is `(secret || msg || index || label)` — no fresh
+    entropy is mixed in. Two parallel sessions over the same triple
+    necessarily produce the same nonce; the transcript-dedup
+    `_record_transcript()` then refuses to release the second `z_i`.
+    """
+    return hash_to_scalar(
+        secret,
+        msg,
+        index.to_bytes(8, "big"),
+        label=label,
+    )
+
+
+def _derive_nonce_hedged(
+    secret_share: bytes,
+    msg: bytes,
+    signer_index: int,
+    label: bytes,
+    randomizer: bytes,
+) -> bytes:
+    """RFC 9591 §4.2 hedged-random nonce.
+
+    The randomizer (32 bytes from `secrets.token_bytes(32)`) is mixed
+    in alongside deterministic inputs. This is Drijvers-replay-immune
+    by construction (each session uses fresh entropy) while still
+    benefiting from deterministic-style failure-domain isolation via
+    the secret-share input.
+
+    Replaces the pure-deterministic RFC 9591 §4.1 variant which
+    required durable signer state to be safe against process restart
+    (the in-memory `_SEEN_TRANSCRIPTS` LRU empties on restart).
+    """
+    if len(randomizer) != RANDOMIZER_LEN:
+        raise ValueError(f"randomizer must be {RANDOMIZER_LEN} bytes, got {len(randomizer)}")
+    h = hashlib.blake2b(digest_size=64)
+    h.update(b"hypermind-frost-nonce-v2|")
+    h.update(secret_share)
+    h.update(signer_index.to_bytes(4, "big"))
+    h.update(len(msg).to_bytes(8, "big"))
+    h.update(msg)
+    h.update(len(label).to_bytes(4, "big"))
+    h.update(label)
+    h.update(randomizer)
+    # Reduce blake2b-512 output mod L to obtain a uniform Ed25519 scalar.
+    return crypto_core_ed25519_scalar_reduce(h.digest())
+
+
+def commit(
+    *,
+    share: FrostShare,
+    message: bytes,
+    randomizer: bytes | None = None,
+) -> tuple[_Nonce, Commitment]:
+    """Round-1: derive (d_i, e_i) hedged-random per RFC 9591 §4.2 and
+    publish (D_i, E_i, randomizer).
+
+    `randomizer` is normally generated fresh by `secrets.token_bytes(32)`.
+    Tests / spec interop scenarios may pass a fixed randomizer; production
+    callers MUST leave it `None`.
+    """
+    if randomizer is None:
+        randomizer = secrets.token_bytes(RANDOMIZER_LEN)
+    elif len(randomizer) != RANDOMIZER_LEN:
+        raise ValueError(f"randomizer must be {RANDOMIZER_LEN} bytes, got {len(randomizer)}")
+    d = _derive_nonce_hedged(share.secret, message, share.index, b"FROST/nonce/hiding", randomizer)
+    e = _derive_nonce_hedged(share.secret, message, share.index, b"FROST/nonce/binding", randomizer)
+    _validate_scalar(d)
+    _validate_scalar(e)
+    D = crypto_scalarmult_ed25519_base_noclamp(d)
+    E = crypto_scalarmult_ed25519_base_noclamp(e)
+    return (
+        _Nonce(hiding=d, binding=e),
+        Commitment(index=share.index, hiding=D, binding=E, randomizer=randomizer),
+    )
+
+
+def _serialize_commitments(commitments: list[Commitment]) -> bytes:
+    """Serialize commitment list for the binding-factor + challenge hash."""
+    out = b""
+    for c in sorted(commitments, key=lambda c: c.index):
+        out += c.index.to_bytes(8, "big") + c.hiding + c.binding
+    return out
+
+
+def _validate_commitment_set(commitments: list[Commitment]) -> None:
+    """Reject duplicate signer indices and zero-length sets."""
+    if not commitments:
+        raise ValueError("commitment set must be non-empty")
+    seen = set()
+    for c in commitments:
+        if c.index in seen:
+            raise ValueError(f"duplicate signer index {c.index} in commitment set")
+        seen.add(c.index)
+
+
+def compute_binding_factors(
+    commitments: list[Commitment], message: bytes, group_pk: bytes
+) -> dict[int, bytes]:
+    """ρ_i = H("rho" || i || ser(commits) || M || group_pk) for each signer."""
+    _validate_commitment_set(commitments)
+    factors = {}
+    ser = _serialize_commitments(commitments)
+    for c in commitments:
+        factors[c.index] = hash_to_scalar(
+            b"rho",
+            c.index.to_bytes(8, "big"),
+            ser,
+            message,
+            group_pk,
+            label=b"FROST/ed25519/rho",
+        )
+    return factors
+
+
+def aggregate_R(commitments: list[Commitment], rhos: dict[int, bytes]) -> bytes:
+    """R = Σ_i (D_i + ρ_i * E_i)."""
+    R = None
+    for c in commitments:
+        rho = rhos[c.index]
+        rho_E = crypto_scalarmult_ed25519_noclamp(rho, c.binding)
+        contribution = crypto_core_ed25519_add(c.hiding, rho_E)
+        if R is None:
+            R = contribution
+        else:
+            R = crypto_core_ed25519_add(R, contribution)
+    assert R is not None
+    return R
+
+
+def challenge(commitments: list[Commitment], R: bytes, group_pk: bytes, message: bytes) -> bytes:
+    """c = H(encode(commitments) || group_pk || R || M).
+
+    Per RFC 9591 §4.6, the challenge MUST bind the encoded commitment
+    list, not just R — defends against rogue-commitment / Drijvers-class
+    attacks even if R could be otherwise predicted.
+    """
+    return hash_to_scalar(
+        _serialize_commitments(commitments),
+        group_pk,
+        R,
+        message,
+        label=b"FROST/ed25519/chall",
+    )
+
+
+def sign_share(
+    share: FrostShare,
+    nonce: _Nonce,
+    commitments: list[Commitment],
+    message: bytes,
+    *,
+    bind_commitments_in_challenge: bool = False,
+) -> bytes:
+    """z_i = d_i + ρ_i*e_i + λ_i * sk_i * c.
+
+    Refuses to sign the same `(commitments, message, share.index)`
+    twice — defeats the Drijvers concurrent-session attack where a
+    malicious aggregator presents the same signer with two different
+    commitment sets to harvest a second `z_i` over the same nonce.
+
+    `bind_commitments_in_challenge` controls the challenge form:
+      - True  → full RFC 9591 `H(commits || group_pk || R || M)`. Use
+                this for production multi-round signing where verifiers
+                receive the commitment list.
+      - False → `H(R || group_pk || M)` (the `_challenge_no_commitments`
+                form). Use this for the `threshold_sign` helper that
+                publishes a self-contained signature.
+    """
+    _validate_commitment_set(commitments)
+    if not any(c.index == share.index for c in commitments):
+        raise ValueError(f"signer index {share.index} not in commitment set")
+
+    transcript = hashlib.sha512(
+        b"FROST/transcript"
+        + share.index.to_bytes(8, "big")
+        + _serialize_commitments(commitments)
+        + message
+        + (b"\x01" if bind_commitments_in_challenge else b"\x00")
+    ).digest()
+    with _SIGN_LOCK:
+        if not _record_transcript(transcript):
+            raise ValueError("refusing to re-sign identical transcript (nonce-reuse defence)")
+
+    rhos = compute_binding_factors(commitments, message, share.group_public)
+    R = aggregate_R(commitments, rhos)
+    if bind_commitments_in_challenge:
+        c = challenge(commitments, R, share.group_public, message)
+    else:
+        c = _challenge_no_commitments(R, share.group_public, message)
+    indices = [cm.index for cm in commitments]
+    lam = lagrange_coefficient(share.index, indices)
+    rho = rhos[share.index]
+    rho_e = crypto_core_ed25519_scalar_mul(rho, nonce.binding)
+    d_plus_rho_e = crypto_core_ed25519_scalar_add(nonce.hiding, rho_e)
+    sk_c = crypto_core_ed25519_scalar_mul(share.secret, c)
+    lam_sk_c = crypto_core_ed25519_scalar_mul(lam, sk_c)
+    return crypto_core_ed25519_scalar_add(d_plus_rho_e, lam_sk_c)
+
+
+def aggregate_signature(
+    shares: list[bytes], commitments: list[Commitment], rhos: dict[int, bytes]
+) -> tuple[bytes, bytes]:
+    """(R, z) — z = Σ z_i; R is recomputed from commitments + rhos."""
+    R = aggregate_R(commitments, rhos)
+    z = scalar_from_int(0)
+    for s in shares:
+        z = crypto_core_ed25519_scalar_add(z, s)
+    return R, z
+
+
+def verify(
+    group_pk: bytes,
+    message: bytes,
+    R: bytes,
+    z: bytes,
+    commitments: list[Commitment] | None = None,
+) -> bool:
+    """Verify a FROST signature: z*G == R + c*Y.
+
+    The challenge MUST be derived from the same commitment set used
+    during signing (RFC 9591 §4.6); callers who didn't keep the
+    commitments around can pass `commitments=None` only when the
+    signature was produced via `threshold_sign(...)` — that path
+    publishes a self-contained signature whose challenge can be
+    re-derived from the *aggregated* commitment-set encoding stored
+    inside `R` (we accept it for backward-compat by computing the
+    challenge from the canonical `R || group_pk || message` form
+    matching `threshold_sign_with_commitments`'s last call).
+    """
+    try:
+        _validate_point(group_pk)
+        _validate_point(R)
+        if z != ZERO_SCALAR:
+            _validate_scalar(z)
+        if commitments is not None:
+            _validate_commitment_set(commitments)
+    except ValueError:
+        return False
+    if commitments is not None:
+        c = challenge(commitments, R, group_pk, message)
+    else:
+        # Self-contained verify: re-derive the challenge from the
+        # canonical (R, group_pk, message) tuple. `threshold_sign` uses
+        # this same tuple via `_challenge_no_commitments` so verify-
+        # without-commitments still works for the convenience helper.
+        c = _challenge_no_commitments(R, group_pk, message)
+    z_G = crypto_scalarmult_ed25519_base_noclamp(z)
+    c_Y = crypto_scalarmult_ed25519_noclamp(c, group_pk)
+    rhs = crypto_core_ed25519_add(R, c_Y)
+    return z_G == rhs
+
+
+def _challenge_no_commitments(R: bytes, group_pk: bytes, message: bytes) -> bytes:
+    """Convenience challenge for the `threshold_sign` helper that does
+    not publish commitments. Used by both the helper's signing path and
+    the matching `verify(..., commitments=None)` path."""
+    return hash_to_scalar(R, group_pk, message, label=b"FROST/ed25519/chall-helper")
+
+
+def verify_with_commitments(
+    group_pk: bytes,
+    message: bytes,
+    R: bytes,
+    z: bytes,
+    commitments: list[Commitment],
+) -> bool:
+    """Full RFC 9591 verifier: challenge bound to the commitment list.
+    Pair this with `sign_share(..., bind_commitments_in_challenge=True)`.
+    """
+    return verify(group_pk, message, R, z, commitments=commitments)
+
+
+# ---- one-shot helper --------------------------------------------------
+
+
+def threshold_sign(shares: list[FrostShare], message: bytes) -> tuple[bytes, bytes]:
+    """Convenience: t-of-n signing from a list of shares.
+
+    Each share runs commit() + sign_share() in sequence; the aggregator
+    bundles into the (R, z) pair. Returns (R, z) — both 32 bytes.
+    """
+    if not shares:
+        raise ValueError("require at least one share")
+    indices_seen = set()
+    for s in shares:
+        if s.index in indices_seen:
+            raise ValueError(f"duplicate share index {s.index}")
+        indices_seen.add(s.index)
+
+    nonces_and_commits = [commit(share=s, message=message) for s in shares]
+    commitments = [
+        Commitment(index=s.index, hiding=cm.hiding, binding=cm.binding, randomizer=cm.randomizer)
+        for s, (_, cm) in zip(shares, nonces_and_commits, strict=False)
+    ]
+    sig_shares = [
+        sign_share(s, n, commitments, message, bind_commitments_in_challenge=False)
+        for s, (n, _) in zip(shares, nonces_and_commits, strict=False)
+    ]
+    rhos = compute_binding_factors(commitments, message, shares[0].group_public)
+    return aggregate_signature(sig_shares, commitments, rhos)