feat(tbtc/signer): Phase 7.1 hardened interactive signing session (#4051)

## What

Phase 7.1 of the frozen spec
([#4049](#4049),
`docs/phase-7-interactive-session-spec-freeze.md` §§4–5): the engine
session layer for the interactive two-round signing path, with
**engine-held nonce custody** as the defining property.

## The custody contract (spec §4)

- Round-1 nonces: OS randomness, in-memory only, bound to `(session_id,
attempt_id)`, zeroized on consumption/abort/expiry/replacement,
**never** in any request, response, or persisted state.
- **Consumption-before-release**: the durable per-attempt marker
persists BEFORE the share leaves the engine. Persist failure → marker
rolled back, nonces stay live, no share escaped (pinned by a
persist-fault-injection test). Marker-without-share → attempt dead, fail
closed.
- Restart can never yield a second share under one nonce pair; the
cloned-state nonce-reuse class is structurally eliminated. Pinned by a
restart test: the marker survives reload and rejects the consumed
attempt at every entry point while a fresh attempt proceeds.

## The API (spec §5, strict-mode only)

| Call | Contract highlights |
|---|---|
| `InteractiveSessionOpen` | Key package once per session (validated
against member); idempotent by fingerprint; conflicting reopen fails
closed; **newer attempt implicitly aborts the prior live one**; consumed
attempts rejected |
| `InteractiveRound1` | Fresh nonces + commitments; idempotent until
consumed |
| `InteractiveRound2` | **All verification precedes consumption**:
message binding, subset ⊆ included set, exactly-`t` size, own
membership, and check (f) — own-commitment byte-identity, defeating
coordinator framing of honest members |
| `InteractiveSessionAbort` | Idempotent; destroys nonces without a
marker (never-consumed attempts may reopen with fresh nonces) |

Live-state bounds per the spec: fail-closed capacity cap
(`TBTC_SIGNER_MAX_LIVE_INTERACTIVE_SESSIONS`, default 64) + lazy TTL
sweep with abort semantics
(`TBTC_SIGNER_INTERACTIVE_SESSION_TTL_SECONDS`, default 3600); both
knobs ride the init-config surface. New structured error
`consumed_nonce_replay`. Telemetry: call/success counters ×4, latency
for the two cryptographic rounds.

The four `frost_tbtc_interactive_*` FFI exports ship additively per the
established pattern (Go adoption is Phase 7.3; nothing breaks until the
host calls them).

## Verification

- **10 engine tests**: e2e round trip with one member through the
session API and one through the stateless primitive, aggregating to a
**verified BIP-340 signature** (custody changed, cryptography didn't);
framing-attack rejection then honest-package acceptance
(verify-before-consume); package-shape rejections (outside-set, message
mismatch, oversized, self-missing); round-1 idempotency → consumed
replay; restart-marker durability; persist-fault rollback; open
lifecycle (idempotent/conflict/replacement); abort; TTL expiry; capacity
fail-closed.
- **1 FFI dispatch smoke test** across all four exports.
- Full suite **255 passed / 1 ignored** (baseline 244+1 plus the 11
new), `clippy -D warnings` clean on all targets incl. the bench shape,
**Phase 5 chaos suite green**, persisted-state schema additive (existing
state files load unchanged).

## Scope boundary

`InteractiveAggregate` + package-envelope evidence + cross-language
vectors are Phase 7.2 by the frozen phasing; Go orchestration is 7.3.
Out of scope per the freeze: DKG secret-package custody (named
follow-up).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: mswilkison

pkg/tbtc/signer/docs/phase-7-interactive-session-spec-freeze.md

@@ -145,6 +145,17 @@ self-contained):
    mode is the only mode here: no legacy-shape fallback), checks
    policy gates and provenance, registers the session. Idempotent
    by full-request fingerprint; conflicting reopen fails closed.
+   **The member's key package is resolved from the session's own DKG
+   state (run_dkg), NOT carried in the request** — so the session
+   must already exist with completed DKG, and no signing secret
+   crosses the FFI/host boundary (section 4). This is a correction to
+   an earlier draft of this spec that had Open accept the key package
+   in the request; accepting it would have left key shares outside
+   the engine and defeated the sidecar's signing-secret boundary. A
+   request `threshold` is still carried but must equal the DKG
+   threshold. As a consequence, an interactive session always rides a
+   DKG-populated session and never creates registry entries of its
+   own.
 2. `InteractiveRound1` — fresh nonces + commitments as in section
    4. Per (session, attempt, member) at most one live handle;
    repeat calls return the same commitments (idempotent) until

pkg/tbtc/signer/include/frost_tbtc.h

@@ -57,6 +57,22 @@ TbtcSignerResult frost_tbtc_finalize_sign_round(const uint8_t* request_ptr, size
 TbtcSignerResult frost_tbtc_build_taproot_tx(const uint8_t* request_ptr, size_t request_len);
 TbtcSignerResult frost_tbtc_refresh_shares(const uint8_t* request_ptr, size_t request_len);
 
+/*
+ * Phase 7.1 hardened interactive signing session.
+ *
+ * Unlike the stateless nonce contract above, secret nonces NEVER cross this
+ * boundary in either direction: the engine generates, holds, consumes, and
+ * zeroizes them internally, keyed by (session_id, attempt_id). The caller
+ * exchanges only public commitments, signing packages, and signature shares.
+ * frost_tbtc_interactive_round2 verifies the coordinator's signing package in
+ * full and consumes the attempt's nonces exactly once; a repeat call for a
+ * consumed attempt fails closed with the `consumed_nonce_replay` error code.
+ */
+TbtcSignerResult frost_tbtc_interactive_session_open(const uint8_t* request_ptr, size_t request_len);
+TbtcSignerResult frost_tbtc_interactive_round1(const uint8_t* request_ptr, size_t request_len);
+TbtcSignerResult frost_tbtc_interactive_round2(const uint8_t* request_ptr, size_t request_len);
+TbtcSignerResult frost_tbtc_interactive_session_abort(const uint8_t* request_ptr, size_t request_len);
+
 #ifdef __cplusplus
 }
 #endif

pkg/tbtc/signer/src/api.rs

@@ -146,6 +146,87 @@ pub struct SignShareResult {
     pub signature_share: NativeFrostSignatureShare,
 }
 
+// Phase 7.1 hardened interactive signing session (frozen spec
+// docs/phase-7-interactive-session-spec-freeze.md, section 5). Unlike
+// the stateless primitives above, secret nonces NEVER appear in these
+// requests or results: the engine generates, holds, consumes, and
+// zeroizes them internally, keyed by (session_id, attempt_id).
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveSessionOpenRequest {
+    pub session_id: String,
+    pub member_identifier: u16,
+    pub message_hex: String,
+    pub key_group: String,
+    /// Signing threshold; must equal the session's DKG threshold. The
+    /// key material itself is resolved from the engine's DKG state and
+    /// is never carried in this request - no signing secret crosses the
+    /// FFI (frozen spec section 4).
+    pub threshold: u16,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub taproot_merkle_root_hex: Option<String>,
+    /// Required: interactive sessions are strict-mode only; there is
+    /// no legacy-shape fallback on this path.
+    pub attempt_context: AttemptContext,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveSessionOpenResult {
+    pub session_id: String,
+    pub attempt_id: String,
+    pub idempotent: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveRound1Request {
+    pub session_id: String,
+    pub attempt_id: String,
+    pub member_identifier: u16,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveRound1Result {
+    /// The member's public signing commitments. Idempotent until the
+    /// attempt's nonces are consumed; the secret nonces they
+    /// correspond to never leave the engine.
+    pub commitments_hex: String,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveRound2Request {
+    pub session_id: String,
+    pub attempt_id: String,
+    pub member_identifier: u16,
+    /// The coordinator's signing package (the chosen responsive
+    /// subset's commitment list). Verified in full - membership,
+    /// subset-of-included, exact threshold size, message binding, and
+    /// byte-identity of this member's own commitment entry - BEFORE
+    /// the nonces are consumed.
+    pub signing_package_hex: String,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveRound2Result {
+    pub session_id: String,
+    pub attempt_id: String,
+    pub signature_share_hex: String,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveSessionAbortRequest {
+    pub session_id: String,
+    /// When set, abort only if the live attempt matches; when unset,
+    /// abort whatever attempt is live for the session.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub attempt_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct InteractiveSessionAbortResult {
+    pub session_id: String,
+    pub aborted: bool,
+}
+
 #[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
 pub struct AggregateRequest {
     pub signing_package_hex: String,
@@ -521,6 +602,30 @@ pub struct SignerHardeningMetricsResult {
     pub finalize_sign_round_latency_samples: u64,
     pub refresh_shares_latency_p95_ms: u64,
     pub refresh_shares_latency_samples: u64,
+    #[serde(default)]
+    pub interactive_session_open_calls_total: u64,
+    #[serde(default)]
+    pub interactive_session_open_success_total: u64,
+    #[serde(default)]
+    pub interactive_round1_calls_total: u64,
+    #[serde(default)]
+    pub interactive_round1_success_total: u64,
+    #[serde(default)]
+    pub interactive_round2_calls_total: u64,
+    #[serde(default)]
+    pub interactive_round2_success_total: u64,
+    #[serde(default)]
+    pub interactive_session_abort_calls_total: u64,
+    #[serde(default)]
+    pub interactive_session_abort_success_total: u64,
+    #[serde(default)]
+    pub interactive_round1_latency_p95_ms: u64,
+    #[serde(default)]
+    pub interactive_round1_latency_samples: u64,
+    #[serde(default)]
+    pub interactive_round2_latency_p95_ms: u64,
+    #[serde(default)]
+    pub interactive_round2_latency_samples: u64,
     pub last_updated_unix: u64,
 }
 
@@ -565,6 +670,10 @@ pub struct InitSignerConfigRequest {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub max_sessions: Option<u64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_live_interactive_sessions: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub interactive_session_ttl_seconds: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub state_key_provider: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub state_key_command: Option<String>,

pkg/tbtc/signer/src/engine/config.rs

@@ -51,6 +51,20 @@ pub(crate) const TBTC_SIGNER_MAX_SESSIONS_ENV: &str = "TBTC_SIGNER_MAX_SESSIONS"
 
 pub(crate) const TBTC_SIGNER_DEFAULT_MAX_SESSIONS: usize = 1024;
 
+// Phase 7.1 interactive session bounds. Live interactive sessions hold
+// secret nonces in memory, so they get a dedicated, smaller cap than
+// the overall session registry, and a TTL after which an abandoned
+// attempt's nonces are destroyed (expiry has abort semantics).
+pub(crate) const TBTC_SIGNER_MAX_LIVE_INTERACTIVE_SESSIONS_ENV: &str =
+    "TBTC_SIGNER_MAX_LIVE_INTERACTIVE_SESSIONS";
+
+pub(crate) const TBTC_SIGNER_DEFAULT_MAX_LIVE_INTERACTIVE_SESSIONS: usize = 64;
+
+pub(crate) const TBTC_SIGNER_INTERACTIVE_SESSION_TTL_SECONDS_ENV: &str =
+    "TBTC_SIGNER_INTERACTIVE_SESSION_TTL_SECONDS";
+
+pub(crate) const TBTC_SIGNER_DEFAULT_INTERACTIVE_SESSION_TTL_SECONDS: u64 = 3600;
+
 pub(crate) const TBTC_SIGNER_STATE_LOCKFILE_SUFFIX: &str = ".lock";
 
 pub(crate) const TBTC_SIGNER_ALLOW_BOOTSTRAP_ENV: &str = "TBTC_SIGNER_ALLOW_BOOTSTRAP";

pkg/tbtc/signer/src/engine/init_config.rs

@@ -267,6 +267,16 @@ pub(crate) fn config_values_from_request(
         TBTC_SIGNER_MAX_SESSIONS_ENV,
         request.max_sessions,
     );
+    insert_u64(
+        &mut values,
+        TBTC_SIGNER_MAX_LIVE_INTERACTIVE_SESSIONS_ENV,
+        request.max_live_interactive_sessions,
+    );
+    insert_u64(
+        &mut values,
+        TBTC_SIGNER_INTERACTIVE_SESSION_TTL_SECONDS_ENV,
+        request.interactive_session_ttl_seconds,
+    );
     insert_u64(
         &mut values,
         TBTC_SIGNER_STATE_KEY_COMMAND_TIMEOUT_SECS_ENV,