feat(tbtc/signer): install TBTC_SIGNER_* knobs via init-time FFI config

[mswilkison]

Post-merge follow-up #3 from the June 2026 review stack (#4028–#4035; #4036 landed the engine split that stages this change): move the TBTC_SIGNER_* env-var surface into an init-time FFI config struct, shrinking the ops/audit surface from ~40 scattered std::env::var reads to one explicit, validated installation at startup.

What this adds

New FFI entry frost_tbtc_init_signer_config(request_ptr, request_len) taking a typed JSON InitSignerConfigRequest (40 optional fields; field name = lowercased TBTC_SIGNER_* suffix). The host installs it once at startup.

Semantics

• Wholesale source of truth. Once installed, the environment is not consulted for any covered knob; an unset field means the built-in default. No per-knob mixing of config and env — split-brain configs can't exist.
• Fail-closed init. deny_unknown_fields rejects typo'd knobs; enforcement-gated policy combinations (admission, signing-policy firewall, auto-quarantine) are validated at install by running the same loaders the runtime gates use, with rollback on rejection — a misconfigured signer fails at startup, not at first signing.
• Idempotent re-init for an identical request (fingerprint match); conflicting re-init rejected.
• Secrets never ride the config FFI. TBTC_SIGNER_STATE_ENCRYPTION_KEY_HEX is read exclusively from the dedicated env/command key-provider channel even when a config is installed (the one deliberate std::env::var left outside the chokepoint, commented at the read).
• Transitional compatibility. With no config installed, engine::signer_env_var falls through to the process environment — existing hosts and the entire pre-existing test suite run unchanged; non-development profiles log a one-time warning suggesting the init FFI.

Why parity is safe by construction

The typed request converts to the same canonical strings the existing env parsers consume ("true"/"false", decimal ints, comma-joined identifier lists), and every existing clamp/warn/reject path runs unchanged on identical inputs. The diff swaps std::env::var(X) → signer_env_var(X) at 31 sites and changes nothing else about how values are interpreted. Also deletes lib.rs's duplicated profile/truthy parsing in favor of the engine's single implementation.

Thanks to #4036, this lands as one new ~400-line module (engine/init_config.rs) plus one-line touches across config/lifecycle/persistence/policy/provenance/state — not an 18k-line-file churn. engine/config.rs remains the single home of the env-name constants.

Verification

• cargo fmt --check ✅; cargo clippy --all-targets -- -D warnings ✅
• Full suite 235 passed + 1 ignored / 24 / 1 — all 224 pre-existing tests pass unchanged (env-fallback parity), plus 11 new tests: config-over-env precedence, wholesale env-ignoring for unset fields, idempotent/conflicting re-init, invalid-profile rejection, install rollback on incomplete firewall policy, complete-admission-policy validation, secret-stays-on-env-channel, production-profile-forces-strict via config, reset_for_tests clearing, deny_unknown_fields, list/bool canonicalization, and an FFI round-trip
• --features bench-restart-hook builds; chaos suite (5/5 --exact paths) and formal_verification_ filter pass
• include/frost_tbtc.h gains the symbol; README documents the contract

Notes for reviewers

• Knobs the runtime warn-and-defaults on (e.g. out-of-range timeouts) keep that behavior under config values — init validation only rejects what the runtime gates would reject. Tightening init further is possible later without breaking the contract.
• Go-host adoption is a follow-up: this is additive ABI; nothing changes for hosts until they call the new entry.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0e7b2e6-8df1-4d68-8657-1a8d5d5934e4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/signer-init-config-2026-06-12

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mswilkison]

Review follow-ups addressed in 9226be1 (findings from three reviews: mine, Codex, Gemini — the latter two converged on one root cause):

1. Publish-before-validate race (Codex P2 / Gemini P1) — fixed structurally. Candidates are now validated through a thread-local resolver override visible only to the validating thread, and published only after validation succeeds. The previously possible outcomes — a concurrent identical init returning idempotent: true while the twin rolls the slot back to None (Codex), or concurrent readers briefly acting on a config that never legally installed (Gemini) — are now impossible by construction, not by contract: a failed init has zero observable side effects. (Holding the write lock across validation was not an option: the validators read through signer_env_var, which takes the read lock — std RwLock is not reentrant.)
2. State-path init validation (my F1). validate_candidate_config now includes state_file_path(): a production config — explicit, or by omission (production is the profile default) — without state_path fails at init instead of installing and then failing at first state access. The state-path error message now also names the state_path config field, since the old text pointed operators at an env var the installed config would ignore.
3. End-to-end coverage (my F3). New test proves the config-sourced state_path is honored by run_dkg persistence after a process (re)start — and pins the discovered interaction with the existing state-lock hardening: installing a config after state has been touched is refused by the in-process path-switch guard, which is exactly the init-before-first-state-access contract being enforced.
4. Docs (my F5 + guarantee update). README: don't inline key material into state_key_command (the command string rides the config FFI); documented the no-side-effects init guarantee and the production state_path requirement.

Note for test authors: configs in tests must now be explicit about profile — omission means production, which (correctly) demands a state_path.

Suite: 237 passed + 1 ignored / 24 / 1; clippy -D warnings, fmt, chaos suite, bench-restart-hook build all green.

[mswilkison]

Re-review responses — Gemini: approved, no action. Codex's P2 was valid and is fixed in 5fdb09642:

The finding was my own state-path pattern applied to a knob family the previous fix only partially covered: a production config omitting state_key_provider wholesale-defaults to the env provider — which production forbids at first state access — and command without state_key_command had the same install-then-fail shape.

Fix: the structural head of state_encryption_key_material (provider selection, the production env-provider prohibition, command-spec presence — error strings unchanged) is extracted into resolve_state_key_provider_plan, consumed by both the runtime key path and init validation, so there is one source of truth and no drift. Init now rejects: production-defaulting-to-env, command-without-command, and unknown provider values — all without reading the secret or executing the key command. The no-execution property is pinned by a test whose state_key_command points at a nonexistent binary: if init ever ran it, that install would fail.

Suite: 241 passed + 1 ignored / 24 / 1 (4 new tests); clippy -D warnings, fmt, chaos suite, feature build all green.

[mswilkison]

Codex round-3 P2 — valid, fixed in 7beceecb2. This was the family member my own last review had flagged but deferred; Codex's premise check settles it: production forces the provenance gate, so a production config without a complete attestation set isn't conditionally degraded — it's deterministically unusable for every protected operation. That's the same install-then-fail-late shape as state_path and the key provider, and it belongs in init validation.

validate_candidate_config now runs enforce_provenance_gate() itself: self-gating (no-op when unenforced — every dev config is unaffected), reads only candidate values plus local crypto — no secrets, no command execution, no network. I went with the full gate rather than a parse-only subset deliberately: parse-only would still admit status: "revoked" or a wrong-key signature, leaving the same class open for invalid (vs missing) fields. The one thing an init-time pass cannot promise is freshness — runtime calls still re-check the gate, and the README now states that TTL aging applies per call.

New tests pin: production-without-attestation rejected at init (message names the missing knob), enforced-gate-with-unparseable-trust-root rejected, and a complete production config (state path + command key provider + valid signed attestation + min version) installs — the production-config tests now carry real signed attestations via the existing build_signed_provenance_attestation fixture.

Suite: 244 passed + 1 ignored / 24 / 1; clippy -D warnings, fmt, chaos suite green.

With this, the install-then-fail-late family is closed for every knob the config can express: state path, key provider/command, admission/firewall/auto-quarantine combos, and the provenance gate. The remaining deliberate-lazy items are external-world checks (KMS reachability, secret presence, TTL aging) that no init-time validation can honestly promise.