Add governance key rotation runbook and rehearsal (SEC-D10, #408) #979

Merged

Brouie merged 1 commit from issue-408-governance-key-rotation into main

2026-06-30 14:51:09 +00:00

Brouie commented

2026-06-30 14:24:26 +00:00

(Migrated from gitlab.com)

Implements SEC-D10 (#408) — the rotation cookbook + LocalTerra rehearsal that key custody (#398) forward-references. Implements backlog DEX-P2-026.

Stacked on !978 (#398) — branched from issue-398-key-custody-roster. Merge !978 first; after that this MR shows only its own diff. (Both edit launch-checklist.md + Makefile, so stacking avoids the cross-MR conflict.)

New docs/runbooks/governance-key-rotation.md:

copy-paste rotation commands — wasm contract-admin (terrad tx wasm set-contract-admin, terrad v4.x) and factory governance pointer (UpdateConfig)
post-rotation verification queries; signer/threshold reference to key custody (SEC-B10)
LocalTerra rehearsal + evidence template

New scripts/rehearse-governance-key-rotation.sh — rehearses the wasm contract-admin round-trip (admin -> 2-of-3 multisig -> back, multisig-signed return) on LocalTerra and restores the original admin (EXIT/INT/TERM trap + self-healing re-run). Never touches the governance pointer; safe on a shared deploy.

Wiring: check_governance_key_rotation_docs.py, verify-issue-408.sh, AGENTS_GOVERNANCE_KEY_ROTATION.md, Makefile targets into lint + help; cross-links from wasm-admin-migration.md + launch-checklist.md; DEX-P2-026 marked shipped.

make verify-issue-408 -> 5/5 incl. a live LocalTerra round-trip (real tx hashes, admin restored). Verified the issue's suggested terrad tx wasm update-admin is outdated — terrad 4.0.1 uses set-contract-admin.

Implements SEC-D10 (#408) — the rotation cookbook + LocalTerra rehearsal that key custody (#398) forward-references. Implements backlog DEX-P2-026. **Stacked on !978 (#398)** — branched from `issue-398-key-custody-roster`. Merge !978 first; after that this MR shows only its own diff. (Both edit `launch-checklist.md` + `Makefile`, so stacking avoids the cross-MR conflict.) New `docs/runbooks/governance-key-rotation.md`: - copy-paste rotation commands — wasm contract-admin (`terrad tx wasm set-contract-admin`, terrad v4.x) and factory `governance` pointer (`UpdateConfig`) - post-rotation verification queries; signer/threshold reference to key custody (SEC-B10) - LocalTerra rehearsal + evidence template New `scripts/rehearse-governance-key-rotation.sh` — rehearses the wasm contract-admin round-trip (admin -> 2-of-3 multisig -> back, multisig-signed return) on LocalTerra and **restores the original admin** (EXIT/INT/TERM trap + self-healing re-run). Never touches the governance pointer; safe on a shared deploy. Wiring: `check_governance_key_rotation_docs.py`, `verify-issue-408.sh`, `AGENTS_GOVERNANCE_KEY_ROTATION.md`, Makefile targets into `lint` + `help`; cross-links from `wasm-admin-migration.md` + `launch-checklist.md`; DEX-P2-026 marked shipped. `make verify-issue-408` -> 5/5 incl. a live LocalTerra round-trip (real tx hashes, admin restored). Verified the issue's suggested `terrad tx wasm update-admin` is outdated — terrad 4.0.1 uses `set-contract-admin`.

Brouie commented

2026-06-30 14:25:08 +00:00

(Migrated from gitlab.com)

mentioned in issue #408

PlasticDigits commented

2026-06-30 14:26:45 +00:00

(Migrated from gitlab.com)

Security review — MR !979

Commit reviewed: afc5c92acb89a964e6a9ca48c73540cb978f5d31
Scope: SEC-D10 governance key rotation runbook (docs/runbooks/governance-key-rotation.md), LocalTerra rehearsal script (scripts/rehearse-governance-key-rotation.sh), doc-invariant checks, Makefile/launch-checklist wiring, and stacked SEC-B10 key-custody artifacts from !978.

Method: Full MR diff review; traced attacker-controlled inputs in the rehearsal/verify scripts (FACTORY_ADDRESS from indexer/.env, --output, env overrides for TERRAD_NODE/CHAIN_ID/multisig names) to sinks (docker exec, set-contract-admin, transcript write). Compared multisig shell pattern to existing scripts/lib/terrad-multisig-tx.sh and rehearse-governance-emergency-controls.sh.

Outcome: FINDINGS: 0 medium+

Security review: no medium+ findings on this diff.

Notes (informational, below reporting threshold):

Rehearsal touches only the factory wasm contract-admin on LocalTerra; it explicitly does not mutate the governance pointer. Admin round-trip is guarded by pre-checks, EXIT/INT/TERM trap + restore_admin, and stranded-multisig self-healing — operational safety for shared dev deploys, not an external exploit path.
set_admin_from_msig interpolates env/deploy values into a docker exec sh -c heredoc (same structural pattern as the existing emergency multisig lib). Values are bech32 addresses or operator-controlled env with safe defaults; no path from untrusted remote input to script execution.
No smart-contract, frontend, indexer API, dependency, or secret-handling changes in this MR.

Inline threads: none (zero medium+ findings).

## Security review — MR !979 **Commit reviewed:** `afc5c92acb89a964e6a9ca48c73540cb978f5d31` **Scope:** SEC-D10 governance key rotation runbook (`docs/runbooks/governance-key-rotation.md`), LocalTerra rehearsal script (`scripts/rehearse-governance-key-rotation.sh`), doc-invariant checks, Makefile/launch-checklist wiring, and stacked SEC-B10 key-custody artifacts from !978. **Method:** Full MR diff review; traced attacker-controlled inputs in the rehearsal/verify scripts (`FACTORY_ADDRESS` from `indexer/.env`, `--output`, env overrides for `TERRAD_NODE`/`CHAIN_ID`/multisig names) to sinks (`docker exec`, `set-contract-admin`, transcript write). Compared multisig shell pattern to existing `scripts/lib/terrad-multisig-tx.sh` and `rehearse-governance-emergency-controls.sh`. **Outcome:** `FINDINGS: 0` medium+ Security review: **no medium+ findings** on this diff. **Notes (informational, below reporting threshold):** - Rehearsal touches only the factory **wasm contract-admin** on LocalTerra; it explicitly does not mutate the `governance` pointer. Admin round-trip is guarded by pre-checks, EXIT/INT/TERM trap + `restore_admin`, and stranded-multisig self-healing — operational safety for shared dev deploys, not an external exploit path. - `set_admin_from_msig` interpolates env/deploy values into a `docker exec sh -c` heredoc (same structural pattern as the existing emergency multisig lib). Values are bech32 addresses or operator-controlled env with safe defaults; no path from untrusted remote input to script execution. - No smart-contract, frontend, indexer API, dependency, or secret-handling changes in this MR. **Inline threads:** none (zero medium+ findings).

PlasticDigits commented

2026-06-30 14:51:09 +00:00

(Migrated from gitlab.com)

mentioned in commit d5f277e85d

mentioned in commit d5f277e85ddbd63bba6d4f01becd58fa66df4dc2