Phase 7.3: engine-side DeriveInteractiveAttemptContext helper (#4077)

## Phase 7.3 — engine-side attempt-context derivation (Option B, PR 1 of
2)

Per the Codex+Gemini design consult, the host must not re-implement the
engine's domain-separated attempt-context derivations (the
seed-divergence class). This PR exposes them from the engine.

### What
- New FFI export `frost_tbtc_derive_interactive_attempt_context` →
`engine::derive_interactive_attempt_context`. Stateless, secret-free:
takes an attempt's public inputs, returns the canonical `AttemptContext`
(coordinator, included-participants fingerprint, attempt id) + one
canonical FROST identifier per participant.
- Composes the existing ROAST primitives and **re-validates the derived
context against strict-mode `validate_attempt_context`** before
returning, so the host receives a context `interactive_session_open` is
guaranteed to accept.

### Why
The interactive runner ships placeholder
fingerprint/attempt_id/identifier values documented as inert (only the
fake engine is wired). The real engine strict-validates those fields;
deriving them in Go would duplicate domain-separated hashing across
languages. Exposing from the engine = single source of truth.

### Tests
- Engine units: matches the standalone derivations (coordinator,
fingerprint, attempt_id, canonical ordering, identifier encoding);
deterministic; rejects empty message / zero attempt number /
threshold>set / duplicate / empty participants.
- FFI success round-trip (the helper succeeds with no DKG fixture).
- `cargo fmt` + `clippy --all-targets --all-features -D warnings` clean;
full lib suite 289 pass / 1 ignored.

### Scope / follow-up
- Go-host wiring (bridge wrapper + Go-coordinator cross-check +
replacing the runner's three placeholders + threading identifiers) is
the next PR.
- Production real-engine signing remains gated on the
`frost-secp256k1-tr =3.0.0` external audit; this helper is
parse/canonicalization surface only.

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

Author: mswilkison

pkg/tbtc/signer/include/frost_tbtc.h

@@ -98,6 +98,16 @@ TbtcSignerResult frost_tbtc_interactive_aggregate(const uint8_t* request_ptr, si
  * blame on its own.
  */
 TbtcSignerResult frost_tbtc_verify_signature_share(const uint8_t* request_ptr, size_t request_len);
+/*
+ * Phase 7.3 interactive attempt-context derivation. Stateless and secret-free:
+ * derives the canonical attempt context (coordinator, included-participants
+ * fingerprint, attempt id) and the per-participant FROST identifiers the host
+ * feeds into frost_tbtc_interactive_session_open, so the host never
+ * re-implements the engine's domain-separated derivations. The returned context
+ * is re-validated against the same strict-mode check session_open runs, so the
+ * engine is guaranteed to accept it. No DKG/nonce/session state is touched.
+ */
+TbtcSignerResult frost_tbtc_derive_interactive_attempt_context(const uint8_t* request_ptr, size_t request_len);
 
 #ifdef __cplusplus
 }

pkg/tbtc/signer/src/api.rs

@@ -381,6 +381,45 @@ pub struct AttemptContext {
     pub attempt_id: String,
 }
 
+/// Request to derive the canonical interactive attempt context (plus the
+/// per-participant FROST identifiers) from an attempt's public inputs, so the
+/// host never re-implements the engine's domain-separated derivations - the
+/// cross-language divergence class. Stateless and secret-free: no DKG lookup,
+/// no nonce/session state, no policy decision.
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct DeriveInteractiveAttemptContextRequest {
+    pub session_id: String,
+    pub message_hex: String,
+    pub key_group: String,
+    /// Validation gate only - the derivation requires `included_participants`
+    /// to hold at least `threshold` members; it is NOT an input to the
+    /// fingerprint, attempt-id, or coordinator derivation.
+    pub threshold: u16,
+    /// 1-based wire attempt number (the host's 0-based value + 1), matching
+    /// `AttemptContext.attempt_number`.
+    pub attempt_number: u32,
+    pub included_participants: Vec<u16>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct DeriveInteractiveAttemptContextResult {
+    /// The canonical attempt context, re-validated against strict-mode
+    /// `validate_attempt_context` before returning, so the host can pass it
+    /// verbatim to `InteractiveSessionOpenRequest.attempt_context` and the
+    /// engine will accept it.
+    pub attempt_context: AttemptContext,
+    /// One FROST identifier string per included participant, in canonical
+    /// (ascending) participant order - the exact key-package encoding the
+    /// signing-package and aggregate paths expect.
+    pub frost_identifiers: Vec<ParticipantFrostIdentifier>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
+pub struct ParticipantFrostIdentifier {
+    pub participant_identifier: u16,
+    pub frost_identifier: String,
+}
+
 #[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
 pub struct AttemptExclusionEvidence {
     pub reason: String,

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

@@ -64,24 +64,25 @@ use zeroize::{Zeroize, Zeroizing};
 use crate::api::{
     AggregateRequest, AggregateResult, AttemptContext, AttemptExclusionEvidence,
     AttemptTransitionEvidence, AttemptTransitionTelemetry, BlameProofVerificationResult,
-    BuildTaprootTxRequest, CanaryRolloutStatusResult, DifferentialDivergence,
-    DifferentialFuzzRequest, DifferentialFuzzResult, DkgPart1Request, DkgPart1Result,
-    DkgPart2Request, DkgPart2Result, DkgPart3Request, DkgPart3Result, DkgResult, DkgRound1Package,
-    DkgRound2Package, FinalizeSignRoundRequest, GenerateNoncesAndCommitmentsRequest,
+    BuildTaprootTxRequest, CanaryRolloutStatusResult, DeriveInteractiveAttemptContextRequest,
+    DeriveInteractiveAttemptContextResult, DifferentialDivergence, DifferentialFuzzRequest,
+    DifferentialFuzzResult, DkgPart1Request, DkgPart1Result, DkgPart2Request, DkgPart2Result,
+    DkgPart3Request, DkgPart3Result, DkgResult, DkgRound1Package, DkgRound2Package,
+    FinalizeSignRoundRequest, GenerateNoncesAndCommitmentsRequest,
     GenerateNoncesAndCommitmentsResult, InitSignerConfigRequest, InitSignerConfigResult,
     InteractiveAggregateRequest, InteractiveAggregateResult, InteractiveRound1Request,
     InteractiveRound1Result, InteractiveRound2Request, InteractiveRound2Result,
     InteractiveSessionAbortRequest, InteractiveSessionAbortResult, InteractiveSessionOpenRequest,
     InteractiveSessionOpenResult, NativeFrostCommitment, NativeFrostKeyPackage,
     NativeFrostPublicKeyPackage, NativeFrostSignatureShare, NewSigningPackageRequest,
-    NewSigningPackageResult, PromoteCanaryRequest, PromoteCanaryResult, QuarantineStatusRequest,
-    QuarantineStatusResult, RefreshCadenceStatusRequest, RefreshCadenceStatusResult,
-    RefreshSharesRequest, RefreshSharesResult, RoastLivenessPolicyResult, RollbackCanaryRequest,
-    RollbackCanaryResult, RoundContribution, RoundState, RunDkgRequest, ShareMaterial,
-    SignShareRequest, SignShareResult, SignatureResult, SignerHardeningMetricsResult,
-    StartSignRoundRequest, TransactionResult, TranscriptAuditRecord, TranscriptAuditRequest,
-    TranscriptAuditResult, TriggerEmergencyRekeyRequest, TriggerEmergencyRekeyResult,
-    VerifyBlameProofRequest,
+    NewSigningPackageResult, ParticipantFrostIdentifier, PromoteCanaryRequest, PromoteCanaryResult,
+    QuarantineStatusRequest, QuarantineStatusResult, RefreshCadenceStatusRequest,
+    RefreshCadenceStatusResult, RefreshSharesRequest, RefreshSharesResult,
+    RoastLivenessPolicyResult, RollbackCanaryRequest, RollbackCanaryResult, RoundContribution,
+    RoundState, RunDkgRequest, ShareMaterial, SignShareRequest, SignShareResult, SignatureResult,
+    SignerHardeningMetricsResult, StartSignRoundRequest, TransactionResult, TranscriptAuditRecord,
+    TranscriptAuditRequest, TranscriptAuditResult, TriggerEmergencyRekeyRequest,
+    TriggerEmergencyRekeyResult, VerifyBlameProofRequest,
 };
 use crate::errors::EngineError;
 use crate::go_math_rand::select_coordinator_identifier;

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

@@ -456,6 +456,127 @@ pub(crate) fn validate_attempt_context(
     Ok(Some(canonical_included_participants))
 }
 
+/// Derives the canonical interactive attempt context for an attempt from its
+/// public inputs, so the host never re-implements the engine's domain-separated
+/// derivations (the cross-language divergence class that bit the coordinator
+/// seed). Stateless and secret-free: it touches no DKG, nonce, or session state.
+///
+/// The returned context is re-validated against strict-mode
+/// `validate_attempt_context` for the same inputs before returning, so it is
+/// guaranteed to be accepted by `interactive_session_open`; the per-participant
+/// FROST identifiers use the canonical key-package encoding the
+/// signing-package/aggregate paths require.
+pub(crate) fn derive_interactive_attempt_context(
+    request: DeriveInteractiveAttemptContextRequest,
+) -> Result<DeriveInteractiveAttemptContextResult, EngineError> {
+    // Mirror interactive_session_open's front door (and every other engine
+    // endpoint, including the public-material-only verify_signature_share): an
+    // unattested engine, or a session_id open would reject, must fail closed
+    // here too rather than hand back a context the real open refuses.
+    enforce_provenance_gate()?;
+    validate_session_id(&request.session_id)?;
+
+    let message_bytes = hex::decode(&request.message_hex)
+        .map_err(|e| EngineError::Validation(format!("message_hex is not valid hex: {e}")))?;
+    if message_bytes.is_empty() {
+        return Err(EngineError::Validation(
+            "message_hex must not be empty".to_string(),
+        ));
+    }
+    if request.attempt_number == 0 {
+        return Err(EngineError::Validation(
+            "attempt_number must be at least 1".to_string(),
+        ));
+    }
+    // interactive_session_open rejects threshold == 0 BEFORE validating the
+    // context, and validate_attempt_context only checks len >= threshold (always
+    // true for 0). Reject it here too so the helper never hands the host a
+    // context open would reject - a missing/uninitialized threshold fails at the
+    // derivation seam, not later at open.
+    if request.threshold == 0 {
+        return Err(EngineError::Validation(
+            "threshold must be non-zero".to_string(),
+        ));
+    }
+
+    let canonical_included_participants =
+        canonicalize_included_participants(&request.included_participants)?;
+    if canonical_included_participants.len() < usize::from(request.threshold) {
+        return Err(EngineError::Validation(format!(
+            "included_participants must contain at least threshold members [{}]",
+            request.threshold
+        )));
+    }
+
+    // Coordinator: the RFC-21 Annex A shuffle binds the padded raw message
+    // digest and uses the 0-based attempt number.
+    let attempt_seed = roast_attempt_shuffle_seed(
+        &request.key_group,
+        &request.session_id,
+        &rfc21_message_digest(&message_bytes)?,
+    )?;
+    let coordinator_identifier = select_coordinator_identifier(
+        &canonical_included_participants,
+        attempt_seed,
+        request.attempt_number - 1,
+    )
+    .ok_or_else(|| {
+        EngineError::Validation("included_participants must not be empty".to_string())
+    })?;
+
+    // Fingerprint over the canonical set; the attempt_id binds the engine's
+    // SHA256 transcript digest of the message (NOT the RFC-21 shuffle digest).
+    let included_participants_fingerprint =
+        roast_included_participants_fingerprint_hex(&canonical_included_participants)?;
+    let message_digest_hex = hash_hex(&message_bytes);
+    let attempt_id = roast_attempt_id_hex(
+        &request.session_id,
+        &message_digest_hex,
+        request.attempt_number,
+        coordinator_identifier,
+        &included_participants_fingerprint,
+    )?;
+
+    let attempt_context = AttemptContext {
+        attempt_number: request.attempt_number,
+        coordinator_identifier,
+        included_participants: canonical_included_participants.clone(),
+        included_participants_fingerprint,
+        attempt_id,
+    };
+
+    // Post-condition: the derived context MUST satisfy the same strict-mode
+    // validator `interactive_session_open` runs, so the host can never be handed
+    // a context the engine would later reject. A failure here is an internal
+    // derivation inconsistency, surfaced rather than shipped.
+    validate_attempt_context(
+        &request.session_id,
+        &request.key_group,
+        &message_bytes,
+        &message_digest_hex,
+        request.threshold,
+        Some(&attempt_context),
+        true,
+    )?;
+
+    let frost_identifiers = canonical_included_participants
+        .iter()
+        .map(|participant| {
+            Ok(ParticipantFrostIdentifier {
+                participant_identifier: *participant,
+                frost_identifier: frost_identifier_to_go_string(
+                    participant_identifier_to_frost_identifier(*participant)?,
+                ),
+            })
+        })
+        .collect::<Result<Vec<_>, EngineError>>()?;
+
+    Ok(DeriveInteractiveAttemptContextResult {
+        attempt_context,
+        frost_identifiers,
+    })
+}
+
 pub(crate) fn canonical_attempt_context(attempt_context: &AttemptContext) -> AttemptContext {
     let mut canonical = Some(attempt_context.clone());
     canonicalize_attempt_context_for_fingerprint(&mut canonical);