[DRAFT - decision-gated] feat(tbtc/signer): mirror TEE hardening stack from tBTC monorepo

⚠️ DRAFT — DECISION-GATED. This PR mirrors the source PR
tlabs-xyz/tbtc#88 which is itself a decision-gated draft. It must NOT
merge until the Threshold policy decision to require TEE operation
for signers is explicit.

Stacked on top of [PR #4005](https://github.com/threshold-network/
keep-core/pull/4005) which lands the base FROST/ROAST Rust signer at
pkg/tbtc/signer/. This PR adds the optional TEE signer-hardening
checker stack on top.

Phases A-D (per source PR #88)
- Phase A: governance registry + audit-event validation
  (tee_registry_checker)
- Phase B: verifier/keyset/token/revocation validation
  (tee_token_checker)
- Phase C: runtime token + denylist + vendor-diversity enforcement
  (tee_runtime_checker)
- Phase D: enforcement modes + break-glass controls
  (tee_enforcement_checker)

Files (19 total — all mirror status)
- 4 Rust binaries at pkg/tbtc/signer/src/bin/
- 12 sample config JSON files at pkg/tbtc/signer/scripts/
- 1 README.md update at pkg/tbtc/signer/
- 2 docs at pkg/tbtc/signer/docs/ (tee-whitelisted-signer-activation-
  gate-record.md + tee-whitelisted-signer-enforcement-plan.md)

Provenance
- Source repository: tlabs-xyz/tbtc
- Source PR: #88 (decision-gated, draft)
- Source commit (PR #88 HEAD): 31f0aa2b8efbf8ac42909f8e8d4ce67248cb478e
- Source branch: feat/tee-phase-a-governance-registry (stacked on
  feat/frost-schnorr-migration)
- Base for THIS PR: extraction/frost-signer-mirror-2026-05-26 (PR #4005)
- Source PR includes stacked phases B, C, D from PRs #89, #90, #91
  merged into PR #88's branch

Decision gate
The source PR #88 description is explicit: this stays in draft until
the runtime TEE policy decision is made. The same constraint applies
to this canonical mirror — DO NOT MERGE before:
1. PR #4005 (base FROST signer) lands
2. Threshold policy decision on TEE enforcement for signers is
   explicit and documented (per the source PR's "Decision-Gated"
   framing)

Verification (per plan v38 §7.2 mirror status)
For each file:
- sha256(git show 31f0aa2b8e:<sourcePath>) ==
  sha256(file at this PR head at <targetPath>)

The 19 files port as byte-for-byte mirrors with path normalization:
- tools/tbtc-signer/* → pkg/tbtc/signer/*
- docs/frost-migration/tee-* → pkg/tbtc/signer/docs/tee-*

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mswilkison

pkg/tbtc/signer/README.md

@@ -1,7 +1,7 @@
 # tbtc-signer (bootstrap)
 
-This crate is the first implementation slice of the Rust rewrite plan tracked
-in `../../docs/frost-migration/rust-rewrite-bootstrap.md`.
+This crate is the first implementation slice of the Rust rewrite plan in
+`../tbtc-rust-rewrite-consensus-plan.md`.
 
 ## Current scope
 
@@ -33,10 +33,7 @@ in `../../docs/frost-migration/rust-rewrite-bootstrap.md`.
 - Uses deterministic JSON request/response envelopes across the FFI boundary.
 - Provides explicit, typed error codes for retry-safe orchestration.
 - Keeps bootstrap synthetic finalize behavior fail-closed by default; enable it
-  explicitly with `TBTC_SIGNER_ALLOW_BOOTSTRAP=true` in non-production profiles
-  only.
-- Rejects bootstrap dealer DKG when `TBTC_SIGNER_PROFILE=production`; production
-  requires distributed DKG wiring before this path can be enabled.
+  explicitly with `TBTC_SIGNER_ALLOW_BOOTSTRAP=true`.
 
 ## Not yet implemented
 
@@ -106,6 +103,205 @@ Sample input schemas are provided in:
 - `tools/tbtc-signer/scripts/admission-override.sample.json`
 - `tools/tbtc-signer/scripts/admission-override-registry.sample.json`
 
+## TEE Governance Registry Checker (Phase A)
+
+Run the governance registry validator for TEE-required signer policy artifacts:
+
+```bash
+cd tools/tbtc-signer
+cargo run --bin tee_registry_checker -- \
+  --registry scripts/tee-governance-registry-v1.sample.json \
+  --events scripts/tee-governance-audit-events-v1.sample.json \
+  --now-unix 1700100000
+```
+
+Flags:
+
+- `--registry <path>` (required): path to governance registry JSON
+- `--events <path>` (optional): path to governance audit events JSON
+- `--now-unix <seconds>` (optional): override current Unix timestamp for
+  deterministic validation (useful for CI and testing)
+
+Exit codes:
+
+- `0`: registry/events satisfy Phase A schema and workflow checks
+- `1`: policy or workflow violations were detected (see JSON reason codes)
+- `2`: checker input/config error
+
+Output schema (exit codes 0 and 1):
+
+```json
+{
+  "decision": "allow | reject",
+  "reasons": [{ "code": "reason_code", "detail": "human-readable detail" }],
+  "validated_at_unix": 1700100000
+}
+```
+
+Sample input schemas are provided in:
+
+- `tools/tbtc-signer/scripts/tee-governance-registry-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-governance-audit-events-v1.sample.json`
+
+## TEE Admission Token Checker (Phase B)
+
+Run the verifier/token checker for threshold-signed admission tokens:
+
+```bash
+cd tools/tbtc-signer
+cargo run --bin tee_token_checker -- \
+  --registry scripts/tee-governance-registry-v1.sample.json \
+  --keyset scripts/tee-verifier-keyset-v1.sample.json \
+  --token scripts/tee-admission-token.sample.json \
+  --revocation-registry scripts/tee-token-revocation-registry-v1.sample.json \
+  --now-unix 1700100000
+```
+
+Flags:
+
+- `--registry <path>` (required): governance registry JSON
+- `--keyset <path>` (required): verifier keyset JSON (`m-of-n` threshold config)
+- `--token <path>` (required): admission token artifact JSON (`payload_json` + signatures)
+- `--revocation-registry <path>` (required): token/key revocation registry JSON
+- `--now-unix <seconds>` (optional): deterministic time override for CI/testing
+
+The checker requires `profile_status = mandatory` in the governance registry.
+
+Exit codes:
+
+- `0`: token satisfies Phase B checks
+- `1`: token/keyset/revocation violations detected (see JSON reason codes)
+- `2`: checker input/config error
+
+Output schema (exit codes 0 and 1):
+
+```json
+{
+  "decision": "allow | reject",
+  "reasons": [{ "code": "reason_code", "detail": "human-readable detail" }],
+  "validated_at_unix": 1700100000
+}
+```
+
+Sample input schemas are provided in:
+
+- `tools/tbtc-signer/scripts/tee-verifier-keyset-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-admission-token.sample.json`
+- `tools/tbtc-signer/scripts/tee-token-revocation-registry-v1.sample.json`
+
+`tee-admission-token.sample.json` and `tee-verifier-keyset-v1.sample.json` are
+schema-only examples and require real verifier keys/signatures to pass.
+
+## TEE Runtime Enforcement Checker (Phase C)
+
+Run the runtime selection/session checker for attestation-token and denylist
+enforcement:
+
+```bash
+cd tools/tbtc-signer
+cargo run --bin tee_runtime_checker -- \
+  --registry scripts/tee-runtime-governance-registry-v1.sample.json \
+  --session scripts/tee-runtime-session-start-v1.sample.json \
+  --now-unix 1700100000
+```
+
+Flags:
+
+- `--registry <path>` (required): governance registry JSON for runtime checks
+- `--session <path>` (required): runtime session/cohort snapshot JSON
+- `--now-unix <seconds>` (optional): deterministic time override for CI/testing
+
+Runtime session phase values:
+
+- `session_start`: strict token validity required
+- `mid_session`: expired tokens tolerated only within `grace_period_seconds`
+
+Hard safety ceilings enforced by the checker:
+
+- `grace_period_seconds <= 3600`
+- `attestation_max_age_seconds <= 86400`
+- `denylist_max_staleness_seconds` in `1..=300`
+- `max_single_vendor_share_percent` in `1..=60`
+
+Exit codes:
+
+- `0`: runtime session satisfies Phase C checks
+- `1`: runtime policy violations detected (see JSON reason codes)
+- `2`: checker input/config error
+
+Output schema (exit codes 0 and 1):
+
+```json
+{
+  "decision": "allow | reject",
+  "reasons": [{ "code": "reason_code", "detail": "human-readable detail" }],
+  "validated_at_unix": 1700100000
+}
+```
+
+Sample input schemas are provided in:
+
+- `tools/tbtc-signer/scripts/tee-runtime-governance-registry-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-runtime-session-start-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-runtime-session-mid-session-grace-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-runtime-session-vendor-outage-v1.sample.json`
+
+## TEE Phase D Enforcement Checker (Phase D)
+
+Run the Phase D mode/waiver checker that applies canary and full-enforcement
+policy over a Phase C runtime decision:
+
+```bash
+cd tools/tbtc-signer
+cargo run --bin tee_enforcement_checker -- \
+  --registry scripts/tee-governance-registry-v1.sample.json \
+  --context scripts/tee-enforcement-context-monitor-v1.sample.json \
+  --now-unix 1700100000
+```
+
+Flags:
+
+- `--registry <path>` (required): governance registry JSON with break-glass policy
+- `--context <path>` (required): Phase D session context JSON
+- `--now-unix <seconds>` (optional): deterministic time override for CI/testing
+
+Supported `enforcement_mode` values:
+
+- `monitor_only`: record runtime violations without blocking
+- `soft_enforcement`: warnings + exclusion preference without blocking
+- `hard_enforcement_canary`: blocking applies to canary sessions only
+- `full_enforcement`: blocking applies to all sessions
+
+Break-glass enforcement controls:
+
+- scope coverage for selected operators
+- required quorum (`break_glass_quorum_bps`)
+- waiver TTL bounded by policy (`break_glass_ttl_seconds`) and hard maximum (7 days)
+- activation cap per 7 days (`break_glass_max_activations_per_7d`) for new activations
+- minimum cooldown (`break_glass_cooldown_seconds`) for new activations
+
+Exit codes:
+
+- `0`: `allow` or `allow_with_warnings`
+- `1`: `reject`
+- `2`: checker input/config error
+
+Output schema (exit codes 0 and 1):
+
+```json
+{
+  "decision": "allow | allow_with_warnings | reject",
+  "reasons": [{ "code": "reason_code", "detail": "human-readable detail" }],
+  "validated_at_unix": 1700100000
+}
+```
+
+Sample input schemas are provided in:
+
+- `tools/tbtc-signer/scripts/tee-enforcement-context-monitor-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-enforcement-context-hard-canary-v1.sample.json`
+- `tools/tbtc-signer/scripts/tee-enforcement-context-full-break-glass-v1.sample.json`
+
 ## Encrypted State Key Providers
 
 Signer state persistence is encrypted at rest. Key-provider behavior is controlled
@@ -120,19 +316,8 @@ by the following environment variables:
   - shell command executed via `/bin/sh -lc` when provider is `command`.
 - `TBTC_SIGNER_STATE_KEY_COMMAND_TIMEOUT_SECS`:
   - timeout for command-provider execution in seconds (default `30`, range `1..300`).
-- `TBTC_SIGNER_STATE_PATH`:
-  - signer state file path. Required when `TBTC_SIGNER_PROFILE=production`;
-    non-production profiles default to a temp-dir state file if omitted.
 - `TBTC_SIGNER_PROFILE`:
-  - when set to `production`, provider `env` is rejected fail-closed,
-    `TBTC_SIGNER_STATE_PATH` is required, bootstrap dealer DKG is rejected, and
-    `TBTC_SIGNER_ALLOW_BOOTSTRAP` cannot enable synthetic finalize payloads.
-    The production profile also forces ROAST strict attempt-context enforcement
-    even if `TBTC_SIGNER_ENABLE_ROAST_STRICT` is unset or false.
-
-Set these environment variables before the first FFI call in the process. The
-engine state handle is initialized once per process from the settled
-`TBTC_SIGNER_STATE_PATH` and key-provider configuration.
+  - when set to `production`, provider `env` is rejected fail-closed.
 
 Command-provider contract (`TBTC_SIGNER_STATE_KEY_COMMAND`):
 

pkg/tbtc/signer/docs/tee-whitelisted-signer-activation-gate-record.md

@@ -0,0 +1,65 @@
+# TEE Hardening Activation Gate Record
+
+Date: `TBD`
+Status: `PENDING`
+Owner: `Threshold Labs + DAO Governance`
+Related plan:
+`docs/frost-migration/tee-whitelisted-signer-enforcement-plan.md`
+
+## 1. Gate Statement
+
+This record approves (or rejects) transitioning the TEE hardening profile
+status from `draft` to `mandatory`.
+
+## 2. Governance Decision Metadata
+
+- Governance proposal/decision ID: `TBD`
+- Effective timestamp (UTC): `TBD`
+- Quorum denominator: `TBD`
+- Achieved quorum: `TBD`
+- Required quorum: `>= 67.00%` (`activation_gate_required_quorum_bps=6700`)
+
+## 3. Preconditions
+
+- [ ] Validation scenarios in Section 11 of the TEE plan are complete.
+- [ ] No unresolved CRITICAL/HIGH findings remain in attestation path.
+- [ ] Incident runbook simulation is complete.
+- [ ] Policy and measurements are approved by DAO governance process.
+
+## 3.1 Readiness Review Summary
+
+The integrated TEE readiness stack completed a final merge-readiness review on
+2026-03-03 with recommendation `READY` for the scaffold branch. The review
+recorded:
+
+- all eight prior Phase D enforcement-mode blockers resolved,
+- no remaining merge blockers,
+- Phase D unit coverage passing (`24/24`),
+- Phase A/B/C regression suites passing (`29/29`, `24/24`, `23/23`),
+- sample enforcement commands runnable for monitor, hard-canary, and
+  full-enforcement break-glass contexts.
+
+Remaining review notes are non-blocking future hardening items for production
+activation, including additional break-glass edge-case tests, structural input
+validation cases, and stricter duplicate-history semantics. These do not replace
+the governance preconditions above.
+
+## 4. Approval Record
+
+| Reviewer | Role | Decision | Date (UTC) | Notes |
+| --- | --- | --- | --- | --- |
+| `UNASSIGNED` | security owner | `PENDING` | `TBD` | |
+| `UNASSIGNED` | signer/runtime owner | `PENDING` | `TBD` | |
+| `UNASSIGNED` | governance delegate | `PENDING` | `TBD` | |
+
+## 5. Transition Decision
+
+- `profile_status_transition`: `draft -> mandatory` / `REJECTED`
+- Scope: `TBD`
+- Activation start (UTC): `TBD`
+
+## 6. Rollback Controls
+
+- Rollback authority: `TBD`
+- Rollback trigger conditions: `TBD`
+- Rollback execution SLA: `TBD`

pkg/tbtc/signer/docs/tee-whitelisted-signer-enforcement-plan.md

@@ -72,7 +72,8 @@ Each signer admission record should include:
 | `break_glass_max_activations_per_7d` | `2` | prevent break-glass chaining abuse |
 | `break_glass_cooldown_seconds` | `86400` | 24-hour cooldown between activations |
 | `break_glass_scope` | `named_operator_ids_only` | no global suspension in default policy |
-| `break_glass_quorum_bps` | `6700` | supermajority quorum for activation |
+| `break_glass_quorum_bps` | `6700` | supermajority quorum for emergency break-glass actions |
+| `activation_gate_required_quorum_bps` | `6700` | independent quorum threshold for `draft -> mandatory` activation gate; hard floor of 6700 bps enforced by checker |
 | `re_attestation_poll_interval_seconds` | `300` | signer refresh cadence |
 
 Values should be tuned with canary data and incident drills.
@@ -239,6 +240,56 @@ Requirements:
 4. full enforcement after gate pass
 5. enforce break-glass abuse controls (activation caps + cooldown + scope)
 
+### 10.2 Phase A Scaffold Artifacts
+
+Initial Phase A schema/workflow checks are implemented in:
+
+1. `tools/tbtc-signer/src/bin/tee_registry_checker.rs`
+2. `tools/tbtc-signer/scripts/tee-governance-registry-v1.sample.json`
+3. `tools/tbtc-signer/scripts/tee-governance-audit-events-v1.sample.json`
+
+### 10.3 Phase B Scaffold Artifacts
+
+Initial Phase B verifier/token checks are implemented in:
+
+1. `tools/tbtc-signer/src/bin/tee_token_checker.rs`
+2. `tools/tbtc-signer/scripts/tee-verifier-keyset-v1.sample.json`
+3. `tools/tbtc-signer/scripts/tee-admission-token.sample.json`
+4. `tools/tbtc-signer/scripts/tee-token-revocation-registry-v1.sample.json`
+
+### 10.4 Phase C Scaffold Artifacts
+
+Initial Phase C runtime selection/session checks are implemented in:
+
+1. `tools/tbtc-signer/src/bin/tee_runtime_checker.rs`
+2. `tools/tbtc-signer/scripts/tee-runtime-governance-registry-v1.sample.json`
+3. `tools/tbtc-signer/scripts/tee-runtime-session-start-v1.sample.json`
+4. `tools/tbtc-signer/scripts/tee-runtime-session-mid-session-grace-v1.sample.json`
+5. `tools/tbtc-signer/scripts/tee-runtime-session-vendor-outage-v1.sample.json`
+
+### 10.5 Phase D Scaffold Artifacts
+
+Initial Phase D canary/hard-enforcement checks are implemented in:
+
+1. `tools/tbtc-signer/src/bin/tee_enforcement_checker.rs`
+2. `tools/tbtc-signer/scripts/tee-enforcement-context-monitor-v1.sample.json`
+3. `tools/tbtc-signer/scripts/tee-enforcement-context-hard-canary-v1.sample.json`
+4. `tools/tbtc-signer/scripts/tee-enforcement-context-full-break-glass-v1.sample.json`
+
+Phase D final readiness outcome:
+
+- final review recommendation: `READY` for the scaffold branch,
+- prior Phase D enforcement-mode blockers resolved: `8/8`,
+- merge blockers remaining: `0`,
+- Phase D unit tests passing: `24/24`,
+- Phase A/B/C regression tests passing: `29/29`, `24/24`, `23/23`,
+- sample enforcement commands verified for monitor-only, hard-canary, and
+  full-enforcement break-glass contexts.
+
+Non-blocking future hardening items remain for additional break-glass edge
+cases, structural input validation, duplicate-history behavior, and
+`serde(deny_unknown_fields)` policy consistency.
+
 ### 10.1 Mapping To ROAST Phase 5 Stages
 
 1. ROAST Stage 1 (5% canary) requires TEE Phase C completed and TEE Phase D in
@@ -273,6 +324,8 @@ Before hard enforcement in production:
 4. policy and measurements approved by DAO governance process
 5. activation gate approved in governance record:
    - profile status transitions from `draft` to `mandatory`
+   - approval artifact:
+     `docs/frost-migration/tee-whitelisted-signer-activation-gate-record.md`
 
 ### 12.1 Activation Gate Record Requirements
 
@@ -295,6 +348,7 @@ This plan is linked from:
 
 1. `docs/frost-migration/roast-phase-5-security-rollout-gates.md`
 2. `docs/frost-migration/roast-phase-5-rollout-runbook.md`
+3. `docs/frost-migration/roast-phase-5-human-signoff-packet.md`
 
 as a future mandatory TEE hardening profile for permissioned operator deployments
 once Section 12 activation gate is approved.