feat(tbtc/signer): mirror FROST/ROAST Rust signer from tBTC monorepo

[mswilkison]

Summary

Lands the Rust FROST/ROAST signer at pkg/tbtc/signer/ alongside the existing Go DKG coordinator. The initial import was extracted from tlabs-xyz/tbtc:feat/frost-schnorr-migration at frozen signed tag frost-extraction-source-v1, then this PR applied targeted canonical-path, CI, and reviewer hardening follow-ups in the canonical keep-core repo.

This is no longer a pure byte-for-byte mirror PR. The post-freeze divergences are intentional canonical keep-core changes and are recorded below. After this PR lands, threshold-network/keep-core is the source of truth for the signer; the extracted monorepo tag is provenance for the initial import only.

Source-PR Provenance

• Source repository: tlabs-xyz/tbtc
• Source branch: feat/frost-schnorr-migration
• Frozen source tag: frost-extraction-source-v1 (signed annotated tag by maclane)
• Frozen source commit: 52389bd5cccb5daeef195671feb7ca46be6e2f37
• Initial frozen manifest: https://github.com/tlabs-xyz/tbtc/blob/frost-extraction-source-v1/extraction/frost-extraction-source-manifest.json

The monorepo provenance above is used only to audit the initial import. Ongoing signer development, fixes, CI, and reviews happen in threshold-network/keep-core.

Why This Lives In keep-core

Per extraction plan v38 section 3.1, the signer co-locates with keep-core because:

• HSM enforcement is external to signer code via standard PKCS#11/KMIP and does not force a separate audit lifecycle.
• Coordinator coupling dominates; the B-2 Go DKG coordinator already lives in this repo via PR FROST/ROAST readiness branch #3866.
• TEE adoption later is reversible without forcing a repo split.

Layout Introduced

pkg/tbtc/signer/
├── Cargo.toml + Cargo.lock + build.sh
├── src/
├── tests/
├── benches/
├── include/
├── docs/
│   └── formal/models/
├── scripts/formal/
└── test/vectors/

Expanded Divergence Register

These are the intentional post-freeze divergences from frost-extraction-source-v1.

Target file	SHA256	Rationale
pkg/tbtc/signer/scripts/formal/check_roast_attempt_context_vectors.mjs	7ceb3929b8403ebde515e7ac290414e2aa1fe6920085f1f4930dd2219d93a406	Path normalization to signer-repo paths.
pkg/tbtc/signer/scripts/formal/run_tla_models.sh	64474409f2682fb903e26fee30613bc3d2a3542df4cebec6d86992112ab26b8c	Path normalization plus updated pinned tla2tools.jar release-asset checksum.
pkg/tbtc/signer/README.md	3fe9046df81442a95139d9ced977df3ec05cca468bf77fdd185be48e73426539	Canonical path normalization from tools/tbtc-signer to pkg/tbtc/signer; fixed local docs link.
pkg/tbtc/signer/src/engine.rs	e149510ec9eca52290f09d26f5d16c684d0a3941134cc46d4c3484947d8bf0dd	Reviewer hardening: Bitcoin max-money aggregate checks, order-insensitive DKG/refresh retry fingerprints, state-key command timeout/process-group pipe handling, vector path fix, and clippy cleanup.
pkg/tbtc/signer/src/ffi.rs	02bd12a7aab5d40e9e0eb55f8011caf86a3586eb795ab910179a4604b4335c14	Clippy/FFI hardening: rebuild owned slice via ptr::slice_from_raw_parts_mut in free_buffer.
pkg/tbtc/signer/src/lib.rs	e04f05b30ffa6bd9f282e63482c465945ebaacb31a989c6c045cb6dae418b24c	Reviewer hardening tests and FFI validation expectation updates.
pkg/tbtc/signer/tests/p2tr_signature_fraud_vectors.rs	1c852f79ab683c03bf4846dd2ac58c37cf73d1645f1c4813034a16a0a39a04dd	Canonical path normalization to signer-local test/vectors layout.
.github/workflows/tbtc-signer-formal.yml	623e9c8fab66497339c5ec88800c20afc68075a76680f4a8eb9ea7e327d0ce28	Canonical-only keep-core workflow: signer Rust checks, formal invariants, and TLA model checks.
pkg/tbtc/signer/test/vectors/p2tr-signature-fraud-v0.json	4edc25113ef5a022af347eb0c6752b06f61f4baace94a13b91cf15042065b002	Canonical signer-local copy of the P2TR signature-fraud vector required by the Rust conformance test.

Dual signoff for allowlisted divergences remains required before merge per plan v38 section 4.2:

• Extraction lead: pending
• Canonical repo maintainer: pending

CI Coverage

This PR now runs:

• cargo fmt --manifest-path pkg/tbtc/signer/Cargo.toml -- --check
• cargo clippy --manifest-path pkg/tbtc/signer/Cargo.toml --all-targets -- -D warnings
• cargo test --manifest-path pkg/tbtc/signer/Cargo.toml
• cargo test --manifest-path pkg/tbtc/signer/Cargo.toml formal_verification_
• pkg/tbtc/signer/scripts/formal/run_tla_models.sh

Verification

Latest local verification after review fixes:

• cargo fmt --manifest-path pkg/tbtc/signer/Cargo.toml -- --check
• cargo clippy --manifest-path pkg/tbtc/signer/Cargo.toml --all-targets -- -D warnings
• TBTC_SIGNER_STATE_PATH=/tmp/tbtc-signer-ci-state-local-4005.json cargo test --manifest-path pkg/tbtc/signer/Cargo.toml
• cargo test --manifest-path pkg/tbtc/signer/Cargo.toml formal_verification_

Latest GitHub CI on this branch is green, including Signer Rust checks, Signer formal invariants, and TLA model checks.

Relationship To PR #3866

PR #3866 lands the Go-side DKG coordinator. This PR lands the Rust-side signer. They are complementary protocol implementations:

• DKG: keep-core Go side coordinates; signer participates; DKG result digest is computed on both sides and checked for parity.
• Signing: signer produces FROST signature shares; coordinator aggregates.

PR #3866 and this PR can land independently in either order.

Plan Context

This is one of the mergeable mirror PRs comprising the FROST extraction, alongside tbtc-v2, tbtc-subgraph, and tbtc-v3-indexer mirror PRs.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces pkg/tbtc/signer, a Rust tbtc-signer bootstrap crate with a C ABI JSON-over-buffer interface, FFI translation helpers, API types, error semantics, deterministic coordinator selection, a comprehensive lib.rs FFI surface with tests, an admission-checker CLI, Criterion benchmarks, TLA+ formal models, conformance vectors/checkers, and extensive design/runbook documentation.

Changes

Core Signer Implementation

Layer / File(s)	Summary
FFI & API contract definition include/frost_tbtc.h, src/api.rs	C header declares TbtcBuffer and TbtcSignerResult structs plus ~18 frost_tbtc_* function signatures; Rust API types define serde-serialized request/response payloads for DKG, sign-round lifecycle, transcript audit, quarantine, refresh, emergency rekey, differential fuzzing, and canary rollout.
Error classification and recovery semantics src/errors.rs	EngineError enum with thiserror integration; code() maps variants to stable string identifiers; recovery_class() classifies errors as "recoverable" or "terminal" with explicit handling for consumed attempt/round replays.
FFI translation layer src/ffi.rs	C-compatible buffer structs, JSON serialization/deserialization helpers, ffi_entry for panic containment via catch_unwind, and safe free_buffer memory management for the FFI boundary.
Deterministic coordinator selection src/go_math_rand.rs	Rust port of Go's math/rand with fixed cooked constants table, seedrand, bounded sampling, and shuffle; select_coordinator_identifier returns deterministic coordinators matching keep-core outputs per test vectors.
Lib.rs FFI endpoints & bootstrap gating src/lib.rs	Module declarations, signer version, bootstrap-mode environment/profile parsing with strict production gating, test-only override, ~18 #[no_mangle] extern "C" endpoints (DKG, sign-round, transcript audit, emergency rekey, canary rollout, refresh-shares), and comprehensive test suite covering idempotency, lifecycle transitions, Taproot validation, and emergency/rollout semantics.

Admission Checking & Policy Enforcement

Layer / File(s)	Summary
Admission checker binary src/bin/admission_checker.rs	JSON-configured operator admission evaluator with policy constraints (per-provider/region caps, custody/attestation/SLA requirements), optional DAO override verification (Schnorr signature validation over SHA-256 payload digest), and replay registry persistence to prevent re-use of override decisions.

Benchmarking & Formal Test Vectors

Layer / File(s)	Summary
Phase 5 ROAST benchmark suite benches/phase5_roast.rs	Criterion benchmarks exercising DKG, start/finalize sign-round, state reload/recovery, and attempt transitions (timeout/invalid-share/stale-replay); includes FFI helpers, hashing/fingerprinting utilities, deterministic coordinator probing, and error validation.
Taproot signature fraud formal verification tests/p2tr_signature_fraud_vectors.rs	Integration test loading p2tr-signature-fraud-v0.json vectors, computing BIP-341 key-path sighashes, verifying Schnorr signatures, deriving dual challenge identities, and asserting mutation-based identity uniqueness.
ROAST attempt-context test vectors test/vectors/roast-attempt-context-v1.json	JSON schema and fixtures for deterministic fingerprint/attempt-id computation across multiple participant sets and edge cases, used by formal verification checkers.

TLA+ Formal Verification Models

Layer / File(s)	Summary
ROAST attempt state machine model docs/formal/models/RoastAttemptStateMachine.tla, .cfg	TLA+ module defining attempt numbering, active participants, deterministic coordinator, consumed-attempt registries (transient and durable), transitions (advance/restart/reload), and safety invariants for monotonicity and replay safety.
ROAST rollout policy state machine docs/formal/models/RoastRolloutPolicy.tla, .cfg	TLA+ module specifying five-stage rollout progression (bootstrap→canary→broad→rollback↔halted) with control signals and temporal properties governing promotion/hold/rollback and emergency stop.
State-key provider policy & production gating model docs/formal/models/StateKeyProviderPolicy.tla, .cfg, .production.cfg	TLA+ module modeling provider/key selection lifecycle and load outcomes; production-gate enforcement; properties asserting fail-closed behavior and exact binding enforcement.
TEE enforcement modes state machine docs/formal/models/TeeEnforcementModes.tla, .cfg	TLA+ module for TE admission control with three enforcement modes, attestation states, break-glass override, and properties enforcing valid attestation and admission stability.
Formal models documentation & runner docs/formal/models/README.md, scripts/formal/run_tla_models.sh	README documenting model coverage and bounds; Bash runner downloading/verifying TLA+ toolchain and executing TLC model checks.

Design Documentation & Specifications

Layer / File(s)	Summary
ROAST protocol phase specifications docs/roast-phase-{0-spec-freeze,1.5-consumed-registry,2-coordinator,3-transcript,4-liveness,5-baseline,5-runbook,5-security-gates}.md	Phase 0 spec defining attempt-context, coordinator validation, strict-mode gating, and error taxonomy; Phases 1.5–5 covering consumed-registry integration, coordinator enforcement, transcript replay hardening, liveness policy with recovery classification, baseline calibration, rollout runbook, and security gates.
ROAST implementation roadmap docs/roast-implementation-plan.md	Complete ROAST migration plan covering baseline, goals/non-goals, design principles, threat model, target semantics (deterministic attempt/coordinator, authenticated retry, replay-safety), phased deliverables (Phase 0–5), cross-repo dependencies, and Definition-of-Done.
Hardening, security & operational plans docs/permissioned-signer-hardening-rfc.md, docs/tbtc-signer-secret-material-hardening-plan.md, docs/tee-whitelisted-signer-enforcement-plan.md	RFC with P0–P2 hardening phases; secret-material plan (encrypted-at-rest XChaCha20-Poly1305 envelope); TEE operator enforcement covering admission tokens, runtime behavior, break-glass, and failure modes.
API contract and design decisions docs/signer-api-contract-decision-brief.md, docs/rust-rewrite-bootstrap.md	Decision brief comparing round-level vs coarse session API (recommending session); bootstrap status documenting implemented features and production gates.
Future considerations documentation docs/true-late-t_of_n_finalize_considerations.md	Discussion draft on true late t-of-n finalize tradeoffs and current recommendation to defer as future consideration.

Build Configuration & Scripts

Layer / File(s)	Summary
Crate metadata and build setup pkg/tbtc/signer/Cargo.toml, pkg/tbtc/signer/build.sh, pkg/tbtc/signer/.gitignore	Cargo.toml defines tbtc-signer crate (edition 2021, MIT), library config (cdylib+rlib), bench-restart-hook feature, frost-secp256k1-tr dependency; build.sh with strict bash and release cargo build; .gitignore ignores target/.
Comprehensive README documentation pkg/tbtc/signer/README.md	Full README covering exposed C ABI endpoints, not-yet-implemented items, build/test commands, admission checker CLI, encrypted state provider contracts, benchmark/chaos suite invocation, FFI JSON contract, error codes, and buffer management.
Admission checker sample configurations pkg/tbtc/signer/scripts/admission-*.sample.json	JSON samples for policy (constraints, DAO overrides), candidates, existing operators, override signatures, and replay registries.
Formal verification & testing scripts pkg/tbtc/signer/scripts/formal/check_roast_attempt_context_vectors.mjs, pkg/tbtc/signer/scripts/run_phase5_chaos_suite.sh, pkg/tbtc/signer/scripts/formal/run_tla_models.sh	Node.js CLI for ROAST vector conformance; Bash runners for chaos suite scenarios and TLA+ model checking.

🎯 4 (Complex) | ⏱️ ~75 minutes

🐰 A bootstrap springs forth, with FFI calls so bright,
Formal models carved in TLA+ light,
ROAST coordinators dancing in Go-lang's stride,
Secrets encrypted with cryptographic pride,
From signer to harness, one system unified!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch extraction/frost-signer-mirror-2026-05-26

[coderabbitai]

Actionable comments posted: 13

🧹 Nitpick comments (3)

pkg/tbtc/signer/src/api.rs (1)

196-202: 💤 Low value

Missing #[serde(default, skip_serializing_if)] on script_tree_hex.

All other Option<T> fields in this file use #[serde(default, skip_serializing_if = "Option::is_none")], but script_tree_hex does not. This inconsistency means the field will serialize as null when absent, rather than being omitted.

Suggested fix

 pub struct BuildTaprootTxRequest {
     pub session_id: String,
     pub inputs: Vec<TxInput>,
     pub outputs: Vec<TxOutput>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub script_tree_hex: Option<String>,
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtc/signer/src/api.rs` around lines 196 - 202, The BuildTaprootTxRequest
struct's script_tree_hex Option field lacks the serde attributes used elsewhere;
update the declaration of BuildTaprootTxRequest so the script_tree_hex field is
annotated with #[serde(default, skip_serializing_if = "Option::is_none")] to
match other Option<T> fields (preserving Clone/Debug/Deserialize/Serialize
behavior) so it is omitted from serialized output when None instead of
serializing as null.

pkg/tbtc/signer/src/lib.rs (1)

391-421: 💤 Low value

std::env::set_var and std::env::remove_var are not thread-safe.

These functions are unsound in multi-threaded contexts and deprecated since Rust 1.66. While the tests appear to serialize access via lock_test_state(), this guard must be held across all env mutations and checks within a test to prevent races with parallel test threads.

Current usage appears safe given the locking pattern, but this is fragile. Consider using a dedicated test configuration mechanism that doesn't rely on process-wide environment mutation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtc/signer/src/lib.rs` around lines 391 - 421, EnvVarGuard's methods
(EnvVarGuard::set, EnvVarGuard::unset) and its Drop rely on
std::env::set_var/remove_var which are process-wide and not thread-safe; replace
this pattern with a test-scoped, non-global solution such as using a crate that
provides scoped environment variables (e.g., temp_env or similar) or refactor
tests to accept an injected configuration object instead of mutating process
env; update usages to acquire and hold the new scoped guard for the entire
duration of tests that need env changes (or pass a Config struct into functions
under test) and remove direct calls to std::env::set_var/remove_var and the
EnvVarGuard Drop behavior to avoid races.

pkg/tbtc/signer/src/bin/admission_checker.rs (1)

257-276: 💤 Low value

Consider cleaning up the temp file if rename fails.

If fs::rename fails (e.g., cross-filesystem move or permissions issue), the temp file remains on disk. Adding a cleanup attempt in the error path would improve robustness.

♻️ Proposed cleanup on error

     fs::write(&tmp_path, serialized).map_err(|error| {
         format!(
             "failed to write override replay registry temp file [{}]: {error}",
             tmp_path.display()
         )
     })?;
-    fs::rename(&tmp_path, path).map_err(|error| {
-        format!(
-            "failed to persist override replay registry [{}]: {error}",
-            path.display()
-        )
-    })
+    fs::rename(&tmp_path, path).map_err(|error| {
+        let _ = fs::remove_file(&tmp_path); // Best-effort cleanup
+        format!(
+            "failed to persist override replay registry [{}]: {error}",
+            path.display()
+        )
+    })
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtc/signer/src/bin/admission_checker.rs` around lines 257 - 276,
persist_override_replay_registry currently leaves the temporary file (tmp_path)
if fs::rename fails; modify the rename error path to attempt cleanup of tmp_path
before returning the error. Specifically, call fs::remove_file(&tmp_path)
(ignoring or logging its result) inside the Err branch that handles the rename
failure so the function still returns the original formatted error for
fs::rename but also tries to remove the leftover tmp file; reference
persist_override_replay_registry, path, tmp_path, and fs::rename when making the
change.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pkg/tbtc/signer/docs/formal/models/README.md`:
- Around line 32-51: Update the incorrect repository paths in the traceability
matrix of pkg/tbtc/signer/docs/formal/models/README.md so links point to the
actual implementation and docs in this repo: change references to
tools/tbtc-signer/src/engine.rs to pkg/tbtc/signer/src/engine.rs for the entries
mentioning RoastAttemptStateMachine.tla (validate_attempt_context, replay
guards) and StateKeyProviderPolicy.tla (decode_encrypted_state_envelope,
encode_encrypted_state_envelope); change
docs/frost-migration/tee-whitelisted-signer-enforcement-plan.md to
pkg/tbtc/signer/docs/tee-whitelisted-signer-enforcement-plan.md for
TeeEnforcementModes.tla; and change
docs/frost-migration/roast-phase-5-security-rollout-gates.md to
pkg/tbtc/signer/docs/roast-phase-5-security-rollout-gates.md for
RoastRolloutPolicy.tla so readers can locate the referenced code and policy
docs.

In `@pkg/tbtc/signer/docs/roast-implementation-plan.md`:
- Line 93: Update the broken doc links in
pkg/tbtc/signer/docs/roast-implementation-plan.md by replacing repo-external
paths like `docs/frost-migration/roast-phase-0-spec-freeze.md` and any
`tools/tbtc-signer/...` references with the correct repo-local paths under
pkg/tbtc/signer/docs (or use correct relative paths from this markdown file);
search the file for all occurrences of `docs/frost-migration/...` and
`tools/tbtc-signer/...` (including the instances similar to the shown
`docs/frost-migration/roast-phase-0-spec-freeze.md`) and normalize each link so
it points to the new location in this package, preserving anchor fragments and
updating any link text as needed.

In `@pkg/tbtc/signer/docs/roast-phase-5-rollout-runbook.md`:
- Around line 26-29: Update the incorrect crate path used in the runbook
commands: replace occurrences of "cd tools/tbtc-signer" with "cd
pkg/tbtc/signer" for the benchmark command (`cargo bench --features
bench-restart-hook --bench phase5_roast`) and the chaos suite script invocation
(`./scripts/run_phase5_chaos_suite.sh`) so the commands run from the correct
crate directory.

In `@pkg/tbtc/signer/docs/roast-phase-5-security-rollout-gates.md`:
- Around line 92-99: Update stale repository paths in
roast-phase-5-security-rollout-gates.md: replace any occurrences of the old
tooling path "tools/tbtc-signer" with the new location "pkg/tbtc/signer" (e.g.,
update the run command `cd tools/tbtc-signer && cargo bench --features
bench-restart-hook --bench phase5_roast` to `cd pkg/tbtc/signer ...`), and
update any links referencing
`docs/frost-migration/roast-phase-5-baseline-calibration.md` to the document’s
new location in the repo (search for the exact link text and swap to the correct
path). Ensure all instances at the reported locations (around the run command
and the listed links) are changed consistently so operators following the
runbook hit the correct files and commands.

In `@pkg/tbtc/signer/docs/rust-rewrite-bootstrap.md`:
- Around line 10-13: The documentation still references the old crate path
"tools/tbtc-signer" and the validation command using that path; update every
occurrence to "pkg/tbtc/signer" in rust-rewrite-bootstrap.md (including the
header lines that list the crate, the C ABI include path `include/frost_tbtc.h`,
and any validation/build commands) so links and commands point to the colocated
pkg/tbtc/signer location; search for "tools/tbtc-signer" and replace with
"pkg/tbtc/signer" and verify the validation command and any examples reference
the new path.

In `@pkg/tbtc/signer/docs/signer-api-contract-decision-brief.md`:
- Around line 43-47: Update the two referenced paths in
signer-api-contract-decision-brief.md so they point to the mirrored crate
locations: replace `docs/frost-migration/rust-rewrite-bootstrap.md` with
`pkg/tbtc/signer/docs/frost-migration/rust-rewrite-bootstrap.md` and replace
`tools/tbtc-signer/src/lib.rs` with `pkg/tbtc/signer/src/lib.rs` (look for the
occurrences shown around the paragraph mentioning the bootstrap Rust crate and
file: `tools/tbtc-signer/src/lib.rs` and update those strings accordingly).

In `@pkg/tbtc/signer/docs/tbtc-signer-secret-material-hardening-plan.md`:
- Around line 6-7: The doc still uses the old crate path string
`tools/tbtc-signer`; update that scope reference to `pkg/tbtc/signer` throughout
the file (tbtc-signer-secret-material-hardening-plan.md) so the plan points to
the mirrored crate location, and scan for any other occurrences of
`tools/tbtc-signer` in this document to replace with `pkg/tbtc/signer`.

In `@pkg/tbtc/signer/docs/tee-whitelisted-signer-enforcement-plan.md`:
- Around line 296-298: Update the two broken cross-doc links in
pkg/tbtc/signer/docs/tee-whitelisted-signer-enforcement-plan.md (currently
referencing docs/frost-migration/roast-phase-5-security-rollout-gates.md and
docs/frost-migration/roast-phase-5-rollout-runbook.md on lines ~296–297) to
point to their correct locations inside this PR:
pkg/tbtc/signer/docs/roast-phase-5-security-rollout-gates.md and
pkg/tbtc/signer/docs/roast-phase-5-rollout-runbook.md so cross-document
navigation resolves correctly.

In `@pkg/tbtc/signer/README.md`:
- Around line 53-54: Update the README.md occurrence(s) that reference the old
path string "tools/tbtc-signer" to the new crate location "pkg/tbtc/signer":
search for and replace that path in all command snippets, code blocks, and file
references (e.g., cargo build/cd commands and any path bullets) so every
instance uses "pkg/tbtc/signer" consistently; ensure both shell commands and
prose file paths are updated, and run a quick grep for "tools/tbtc-signer" to
confirm no remaining references.

In `@pkg/tbtc/signer/scripts/admission-policy-v1.sample.json`:
- Line 8: Replace the non-hex placeholder value for the JSON key
dao_override_trust_root_pubkey_hex with a syntactically valid 32-byte hex string
(64 lowercase hex characters) so sample files and copy/paste validation don't
break; update the sample value to something like a 64-character hex placeholder
and leave replacement guidance in the README or nearby comment explaining it
must be replaced with the real x-only pubkey hex.

In `@pkg/tbtc/signer/scripts/formal/check_roast_attempt_context_vectors.mjs`:
- Around line 15-18: vectorsPath currently resolves to
"docs/frost-migration/test-vectors/roast-attempt-context-v1.json" and will fail
because the vectors live under "test/vectors"; update the path.join call that
constructs vectorsPath (using rootDir and the filename) to point to
"test/vectors/roast-attempt-context-v1.json" so the script loads the correct
file; ensure the change is made where vectorsPath is declared and used in this
module.

In `@pkg/tbtc/signer/scripts/formal/run_tla_models.sh`:
- Around line 4-5: The MODEL_DIR assignment in run_tla_models.sh is pointing to
the wrong path; update the MODEL_DIR variable (currently computed relative to
ROOT_DIR) to "$ROOT_DIR/docs/formal/models" so the directory existence check in
the script (around the directory existence test near line 20) succeeds; modify
the MODEL_DIR definition in the script (look for the MODEL_DIR variable
assignment and references) to use the corrected path and ensure any subsequent
uses of MODEL_DIR still reference this updated variable.

In `@pkg/tbtc/signer/tests/p2tr_signature_fraud_vectors.rs`:
- Around line 375-376: The test constructs vectors_path using the vectors_path
variable in pkg/tbtc/signer/tests/p2tr_signature_fraud_vectors.rs which
currently joins
"../../docs/frost-migration/test-vectors/p2tr-signature-fraud-v0.json" relative
to CARGO_MANIFEST_DIR and points to a non-existent file; fix by either adding
the missing p2tr-signature-fraud-v0.json to the repo at that path or update the
vectors_path join to the correct relative path where the JSON actually lives
(adjust the "../" segments or point to the canonical test-vectors location),
ensuring the variable name vectors_path and its usage remain unchanged.

---

Nitpick comments:
In `@pkg/tbtc/signer/src/api.rs`:
- Around line 196-202: The BuildTaprootTxRequest struct's script_tree_hex Option
field lacks the serde attributes used elsewhere; update the declaration of
BuildTaprootTxRequest so the script_tree_hex field is annotated with
#[serde(default, skip_serializing_if = "Option::is_none")] to match other
Option<T> fields (preserving Clone/Debug/Deserialize/Serialize behavior) so it
is omitted from serialized output when None instead of serializing as null.

In `@pkg/tbtc/signer/src/bin/admission_checker.rs`:
- Around line 257-276: persist_override_replay_registry currently leaves the
temporary file (tmp_path) if fs::rename fails; modify the rename error path to
attempt cleanup of tmp_path before returning the error. Specifically, call
fs::remove_file(&tmp_path) (ignoring or logging its result) inside the Err
branch that handles the rename failure so the function still returns the
original formatted error for fs::rename but also tries to remove the leftover
tmp file; reference persist_override_replay_registry, path, tmp_path, and
fs::rename when making the change.

In `@pkg/tbtc/signer/src/lib.rs`:
- Around line 391-421: EnvVarGuard's methods (EnvVarGuard::set,
EnvVarGuard::unset) and its Drop rely on std::env::set_var/remove_var which are
process-wide and not thread-safe; replace this pattern with a test-scoped,
non-global solution such as using a crate that provides scoped environment
variables (e.g., temp_env or similar) or refactor tests to accept an injected
configuration object instead of mutating process env; update usages to acquire
and hold the new scoped guard for the entire duration of tests that need env
changes (or pass a Config struct into functions under test) and remove direct
calls to std::env::set_var/remove_var and the EnvVarGuard Drop behavior to avoid
races.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c0224eef-499a-42a2-a346-f06ef353278b

📥 Commits

Reviewing files that changed from the base of the PR and between 980587b and 335ce60.

⛔ Files ignored due to path filters (1)

• pkg/tbtc/signer/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (48)

• pkg/tbtc/signer/.gitignore
• pkg/tbtc/signer/Cargo.toml
• pkg/tbtc/signer/README.md
• pkg/tbtc/signer/benches/phase5_roast.rs
• pkg/tbtc/signer/build.sh
• pkg/tbtc/signer/docs/formal/models/README.md
• pkg/tbtc/signer/docs/formal/models/RoastAttemptStateMachine.cfg
• pkg/tbtc/signer/docs/formal/models/RoastAttemptStateMachine.tla
• pkg/tbtc/signer/docs/formal/models/RoastRolloutPolicy.cfg
• pkg/tbtc/signer/docs/formal/models/RoastRolloutPolicy.tla
• pkg/tbtc/signer/docs/formal/models/StateKeyProviderPolicy.cfg
• pkg/tbtc/signer/docs/formal/models/StateKeyProviderPolicy.production.cfg
• pkg/tbtc/signer/docs/formal/models/StateKeyProviderPolicy.tla
• pkg/tbtc/signer/docs/formal/models/TeeEnforcementModes.cfg
• pkg/tbtc/signer/docs/formal/models/TeeEnforcementModes.tla
• pkg/tbtc/signer/docs/permissioned-signer-hardening-rfc.md
• pkg/tbtc/signer/docs/roast-implementation-plan.md
• pkg/tbtc/signer/docs/roast-phase-0-spec-freeze.md
• pkg/tbtc/signer/docs/roast-phase-1.5-consumed-registry-integration.md
• pkg/tbtc/signer/docs/roast-phase-2-coordinator-policy-enforcement.md
• pkg/tbtc/signer/docs/roast-phase-3-attempt-transcript-replay-hardening.md
• pkg/tbtc/signer/docs/roast-phase-4-liveness-policy-recovery.md
• pkg/tbtc/signer/docs/roast-phase-5-baseline-calibration.md
• pkg/tbtc/signer/docs/roast-phase-5-rollout-runbook.md
• pkg/tbtc/signer/docs/roast-phase-5-security-rollout-gates.md
• pkg/tbtc/signer/docs/rust-rewrite-bootstrap.md
• pkg/tbtc/signer/docs/signer-api-contract-decision-brief.md
• pkg/tbtc/signer/docs/tbtc-signer-secret-material-hardening-plan.md
• pkg/tbtc/signer/docs/tee-whitelisted-signer-enforcement-plan.md
• pkg/tbtc/signer/docs/true-late-t-of-n-finalize-considerations.md
• pkg/tbtc/signer/include/frost_tbtc.h
• pkg/tbtc/signer/scripts/admission-candidate.sample.json
• pkg/tbtc/signer/scripts/admission-existing.sample.json
• pkg/tbtc/signer/scripts/admission-override-registry.sample.json
• pkg/tbtc/signer/scripts/admission-override.sample.json
• pkg/tbtc/signer/scripts/admission-policy-v1.sample.json
• pkg/tbtc/signer/scripts/formal/check_roast_attempt_context_vectors.mjs
• pkg/tbtc/signer/scripts/formal/run_tla_models.sh
• pkg/tbtc/signer/scripts/run_phase5_chaos_suite.sh
• pkg/tbtc/signer/src/api.rs
• pkg/tbtc/signer/src/bin/admission_checker.rs
• pkg/tbtc/signer/src/engine.rs
• pkg/tbtc/signer/src/errors.rs
• pkg/tbtc/signer/src/ffi.rs
• pkg/tbtc/signer/src/go_math_rand.rs
• pkg/tbtc/signer/src/lib.rs
• pkg/tbtc/signer/test/vectors/roast-attempt-context-v1.json
• pkg/tbtc/signer/tests/p2tr_signature_fraud_vectors.rs

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Replace tools/tbtc-signer path references with pkg/tbtc/signer.

This doc is now colocated in pkg/tbtc/signer/docs, but key references and the validation command still use tools/tbtc-signer. That will cause immediate command/link failures for anyone following this bootstrap guide.

Suggested doc patch

-- Added `tools/tbtc-signer` Rust crate that builds a `cdylib` named
+- Added `pkg/tbtc/signer` Rust crate that builds a `cdylib` named

-- Added a C ABI contract in `tools/tbtc-signer/include/frost_tbtc.h`.
+- Added a C ABI contract in `pkg/tbtc/signer/include/frost_tbtc.h`.

-- Added post-finalize signing-material cleanup in `tools/tbtc-signer` session
+- Added post-finalize signing-material cleanup in `pkg/tbtc/signer` session

-- Added finalized-session guardrails in `tools/tbtc-signer`: subsequent
+- Added finalized-session guardrails in `pkg/tbtc/signer`: subsequent

- cd tools/tbtc-signer
+ cd pkg/tbtc/signer

Also applies to: 138-143, 264-266

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtc/signer/docs/rust-rewrite-bootstrap.md` around lines 10 - 13, The
documentation still references the old crate path "tools/tbtc-signer" and the
validation command using that path; update every occurrence to "pkg/tbtc/signer"
in rust-rewrite-bootstrap.md (including the header lines that list the crate,
the C ABI include path `include/frost_tbtc.h`, and any validation/build
commands) so links and commands point to the colocated pkg/tbtc/signer location;
search for "tools/tbtc-signer" and replace with "pkg/tbtc/signer" and verify the
validation command and any examples reference the new path.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use a parseable sample value for dao_override_trust_root_pubkey_hex.

"REPLACE_WITH_XONLY_PUBKEY_HEX" is not valid hex, so this sample can break copy/paste flows in docs or local validation. Prefer a syntactically valid 32-byte hex placeholder (and keep replacement guidance in README).

Suggested change

-  "dao_override_trust_root_pubkey_hex": "REPLACE_WITH_XONLY_PUBKEY_HEX",
+  "dao_override_trust_root_pubkey_hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"dao_override_trust_root_pubkey_hex": "REPLACE_WITH_XONLY_PUBKEY_HEX",
	"dao_override_trust_root_pubkey_hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtc/signer/scripts/admission-policy-v1.sample.json` at line 8, Replace
the non-hex placeholder value for the JSON key
dao_override_trust_root_pubkey_hex with a syntactically valid 32-byte hex string
(64 lowercase hex characters) so sample files and copy/paste validation don't
break; update the sample value to something like a 64-character hex placeholder
and leave replacement guidance in the README or nearby comment explaining it
must be replaced with the real x-only pubkey hex.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/tbtc-signer-formal.yml:
- Around line 25-26: The checkout steps using actions/checkout@v4 persist git
credentials by default; update each Checkout step (the uses: actions/checkout@v4
entries) to add with: persist-credentials: false so credentials are not stored
in the runner after checkout. Ensure both occurrences of actions/checkout@v4 in
the workflow are modified accordingly.
- Line 26: Update the GitHub Actions workflow to pin action versions and harden
checkout credentials: replace occurrences of actions/checkout@v4 with
actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 and add with:
persist-credentials: false to both checkout steps that use checkout, replace
dtolnay/rust-toolchain@stable with
dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8, and replace
actions/setup-java@v4 with
actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 so the workflow pins
SHA-based commits and disables persisting credentials on checkout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 88553e79-6db4-4e95-98fe-00c56e1bc640

📥 Commits

Reviewing files that changed from the base of the PR and between bfd7658 and 551bd42.

📒 Files selected for processing (1)

• .github/workflows/tbtc-signer-formal.yml

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
FILE=".github/workflows/tbtc-signer-formal.yml"
echo "== File exists? =="
ls -l "$FILE"
echo "== Lines 1-120 with numbers =="
nl -ba "$FILE" | sed -n '1,120p'

Repository: threshold-network/keep-core

Length of output: 272

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
FILE=".github/workflows/tbtc-signer-formal.yml"
echo "== File exists? =="
ls -l "$FILE"
echo "== Lines 1-120 with numbers =="
nl -ba "$FILE" | sed -n '1,120p'

Repository: threshold-network/keep-core

Length of output: 272

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
FILE=".github/workflows/tbtc-signer-formal.yml"

echo "== Showing lines 1-80 =="
awk 'NR>=1 && NR<=80 {printf "%4d: %s\n", NR, $0}' "$FILE"

echo "== Showing checkout-related lines (search) =="
rg -n "name:\s*Checkout|uses:\s*actions/checkout|persist-credentials" "$FILE" || true

Repository: threshold-network/keep-core

Length of output: 2302

---

Set persist-credentials: false on both actions/checkout@v4 steps

The current workflow checks out without disabling persisted git credentials; add with: persist-credentials: false to reduce credential exposure.

Suggested patch

       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
@@
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- name: Checkout
	uses: actions/checkout@v4
	- name: Checkout
	uses: actions/checkout@v4
	with:
	persist-credentials: false

🧰 Tools

🪛 zizmor (1.25.2)

[warning] 25-26: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

---

[error] 26-26: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/tbtc-signer-formal.yml around lines 25 - 26, The checkout
steps using actions/checkout@v4 persist git credentials by default; update each
Checkout step (the uses: actions/checkout@v4 entries) to add with:
persist-credentials: false so credentials are not stored in the runner after
checkout. Ensure both occurrences of actions/checkout@v4 in the workflow are
modified accordingly.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

for repo in actions/checkout actions/setup-java dtolnay/rust-toolchain; do
  echo "=== $repo ==="
  git ls-remote "https://github.com/${repo}.git" | head -n 5
  echo
done

Repository: threshold-network/keep-core

Length of output: 535

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# 1) Inspect workflow around the referenced lines
echo "=== Workflow file context ==="
nl -ba .github/workflows/tbtc-signer-formal.yml | sed -n '1,120p'

# 2) Resolve refs to commit SHAs (avoid SIGPIPE by capturing then slicing)
resolve_ref() {
  local repo="$1" ref="$2"
  local url="https://github.com/${repo}.git"
  local tmp="/tmp/lsremote_${repo//\//_}_${ref//\//_}"
  git ls-remote "$url" "$ref" > "$tmp" 2>/dev/null || true
  echo "--- ${repo} ${ref} ---"
  cat "$tmp" || true
  echo
  rm -f "$tmp" || true
}

echo "=== Resolve action refs to SHAs ==="
resolve_ref "actions/checkout" "refs/tags/v4"
resolve_ref "actions/checkout" "refs/heads/v4"
resolve_ref "actions/setup-java" "refs/tags/v4"
resolve_ref "actions/setup-java" "refs/heads/v4"
resolve_ref "dtolnay/rust-toolchain" "refs/heads/stable"
resolve_ref "dtolnay/rust-toolchain" "refs/tags/stable"

Repository: threshold-network/keep-core

Length of output: 162

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Workflow file context (numbered) ==="
python3 - <<'PY'
from pathlib import Path
p = Path(".github/workflows/tbtc-signer-formal.yml")
lines = p.read_text().splitlines()
start, end = 1, min(len(lines), 140)
for i in range(start, end+1):
    print(f"{i}\t{lines[i-1]}")
PY

echo
echo "=== Resolve action refs to commit SHAs ==="
resolve_ref() {
  local repo="$1" ref="$2"
  local url="https://github.com/${repo}.git"
  echo "--- ${repo} ${ref} ---"
  git ls-remote "$url" "$ref" || true
  echo
}

resolve_ref "actions/checkout" "refs/tags/v4"
resolve_ref "actions/checkout" "refs/heads/v4"
resolve_ref "actions/setup-java" "refs/tags/v4"
resolve_ref "actions/setup-java" "refs/heads/v4"
resolve_ref "dtolnay/rust-toolchain" "refs/heads/stable"
resolve_ref "dtolnay/rust-toolchain" "refs/tags/stable"

Repository: threshold-network/keep-core

Length of output: 2438

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Total lines: $(python3 - <<'PY'\nimport pathlib\np=pathlib.Path('.github/workflows/tbtc-signer-formal.yml')\nprint(len(p.read_text().splitlines()))\nPY)"

echo
echo "=== uses: occurrences ==="
rg -n "uses:" .github/workflows/tbtc-signer-formal.yml || true

echo
echo "=== persist-credentials occurrences ==="
rg -n "persist-credentials" .github/workflows/tbtc-signer-formal.yml || true

Repository: threshold-network/keep-core

Length of output: 133

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Total lines: $(python3 - <<'PY'
import pathlib
p=pathlib.Path('.github/workflows/tbtc-signer-formal.yml')
print(len(p.read_text().splitlines()))
PY)"

echo
echo "=== uses: occurrences ==="
rg -n "uses:" .github/workflows/tbtc-signer-formal.yml || true

echo
echo "=== persist-credentials occurrences ==="
rg -n "persist-credentials" .github/workflows/tbtc-signer-formal.yml || true

Repository: threshold-network/keep-core

Length of output: 424

---

Pin GitHub Actions to commit SHAs and harden checkout credentials.

• actions/checkout@v4 (lines 26, 44) -> actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5; also add with: persist-credentials: false to both checkout steps.
• dtolnay/rust-toolchain@stable (line 29) -> dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8.
• actions/setup-java@v4 (line 47) -> actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9.

🧰 Tools

🪛 zizmor (1.25.2)

[warning] 25-26: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

---

[error] 26-26: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/tbtc-signer-formal.yml at line 26, Update the GitHub
Actions workflow to pin action versions and harden checkout credentials: replace
occurrences of actions/checkout@v4 with
actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 and add with:
persist-credentials: false to both checkout steps that use checkout, replace
dtolnay/rust-toolchain@stable with
dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8, and replace
actions/setup-java@v4 with
actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 so the workflow pins
SHA-based commits and disables persisting credentials on checkout.