[DRAFT - decision-gated] feat(tbtc/signer): add TEE hardening checker stack

pkg/tbtc/signer/README.md

@@ -106,6 +106,211 @@ Sample input schemas are provided in:
 - `pkg/tbtc/signer/scripts/admission-override.sample.json`
 - `pkg/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 pkg/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:
+
+- `pkg/tbtc/signer/scripts/tee-governance-registry-v1.sample.json`
+- `pkg/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 pkg/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.
+Token signatures cover the exact `payload_json` byte string in the token
+artifact. Do not deserialize and reserialize that value before signature
+verification. The token checker enforces a two-trust-root and
+two-verifier-instance floor for quorum diversity; broader vendor concentration
+limits are enforced by the runtime checker.
+
+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:
+
+- `pkg/tbtc/signer/scripts/tee-verifier-keyset-v1.sample.json`
+- `pkg/tbtc/signer/scripts/tee-admission-token.sample.json`
+- `pkg/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 pkg/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:
+
+- `pkg/tbtc/signer/scripts/tee-runtime-governance-registry-v1.sample.json`
+- `pkg/tbtc/signer/scripts/tee-runtime-session-start-v1.sample.json`
+- `pkg/tbtc/signer/scripts/tee-runtime-session-mid-session-grace-v1.sample.json`
+- `pkg/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 pkg/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
+- reused incident tickets bounded by their history-derived activation time and TTL
+
+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:
+
+- `pkg/tbtc/signer/scripts/tee-enforcement-context-monitor-v1.sample.json`
+- `pkg/tbtc/signer/scripts/tee-enforcement-context-hard-canary-v1.sample.json`
+- `pkg/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

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.

pkg/tbtc/signer/scripts/tee-admission-token.sample.json

@@ -0,0 +1,13 @@
+{
+  "payload_json": "{\"token_id\":\"token-operator-1-0001\",\"operator_id\":\"operator-1\",\"signer_identifier\":\"signer-1\",\"tee_type\":\"sgx\",\"measurement_digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"issued_at_unix\":1700100000,\"expires_at_unix\":1700100300,\"registry_snapshot_version\":1,\"verifier_key_ids\":[\"verifier-key-1\",\"verifier-key-2\"],\"token_revocation_epoch\":5}",
+  "signatures": [
+    {
+      "verifier_key_id": "verifier-key-1",
+      "signature_hex": "REPLACE_WITH_SCHNORR_SIGNATURE_HEX_OVER_SHA256_OF_PAYLOAD_JSON"
+    },
+    {
+      "verifier_key_id": "verifier-key-2",
+      "signature_hex": "REPLACE_WITH_SCHNORR_SIGNATURE_HEX_OVER_SHA256_OF_PAYLOAD_JSON"
+    }
+  ]
+}