d-bis/proxmox
4
0
Fork 0
Code Issues 2 Pull Requests 13 Actions Packages Projects Releases Wiki Activity

security(phase1a): Phoenix Vault rotation runbook + consumer-prep scaffolding #5

Open
nsatoshi wants to merge 1 commits from devin/phase1a-vault-consumer-prep-1776543363 into master
pull from: devin/phase1a-vault-consumer-prep-1776543363
merge into: d-bis:master
Conversation 0 Commits 1 Files Changed 6 +468
nsatoshi commented 2026-04-18 20:19:35 +00:00
Owner
Copy Link

Summary

Part of the sequenced cleanup tracked in issue #1. Phase 1a — Vault consumer-prep scaffolding. No rotation executed, no secret values committed.

This PR stages the infrastructure Phoenix ops need to execute the actual Vault rotation. It does not change any live system.

What this PR adds

File Purpose
docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md 9-step authoritative runbook: new root → rekey unseal → regenerate AppRoles → flip consumers → revoke old. Verification table + rollback path + Phase 2 handoff.
docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md Decision record for the next rotation. Three options (named-operator / cloud-KMS auto-unseal / Transit auto-unseal). Selection pending before rotation executes.
scripts/verify/enumerate-vault-consumers.sh Read-only grep over the tree for VAULT_ROLE_ID / VAULT_SECRET_ID / auth/approle/login references. Groups by top-level consumer.
scripts/verify/verify-vault-approle-auth.sh Post-rotation sanity check — posts AppRole login + token lookup-self. PASS/FAIL without echoing the Role ID, Secret ID, or client token.
phoenix-deploy-api/.env.example +10 lines: VAULT_ADDR / VAULT_ROLE_ID / VAULT_SECRET_ID placeholders + pointer to the runbook.
mission-control/.env.example NEW file (previously had none); documents launchpad NEXT_PUBLIC_* vars and the same Vault AppRole placeholder block. Server-side only.

What this PR does NOT do

  • Does NOT execute the rotation. That is operator-driven, per the runbook.
  • Does NOT touch the leaked-value docs in LEAKED_SECRETS_INVENTORY.md §3 — those are Phase 2 (history rewrite + redaction) and land after the rotation has executed.
  • Does NOT add a Vault client to phoenix-deploy-api/server.js or mission-control/ source. Those services do not currently auth to Vault; adding the client is a follow-up once the decision in VAULT_SHARD_CUSTODY_POLICY.md §3 is made.
  • Does NOT include any secret values. The .env.example entries are empty placeholders.

Consumer enumeration (from scripts/verify/enumerate-vault-consumers.sh)

Current matches:

  • dbis_core/ — 1 file (documentation reference to process.env.VAULT_ROLE_ID)
  • rpc-translator-138/ — 2 files (separate AppRole 19cbc945-…, rotate independently)
  • scripts/ — 4 files (archived configure-phoenix-vault*.sh + migrate-secrets-to-vault.sh)

phoenix-deploy-api/ and mission-control/ do not yet appear because they don't read Vault today — this PR adds the env-var scaffolding so they are ready to.

Review & Testing Checklist for Human

Risk: green — documentation + two new read-only verification scripts + two .env.example additions. Cannot break anything when merged.

  • Read docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md end-to-end; confirm the 9-step order matches Phoenix ops' mental model.
  • Read docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md and indicate (in the PR or in issue #1) which option to go with. Rotation blocks on this.
  • Run bash scripts/verify/enumerate-vault-consumers.sh locally and confirm no out-of-repo consumer is missing.
  • Confirm scripts/verify/verify-vault-approle-auth.sh never writes the Role ID / Secret ID / client token to any log (grep the script — the only thing printed is lengths and policy names).
  • Confirm phoenix-deploy-api/.env.example and mission-control/.env.example additions are consistent with how those services are actually deployed on the live hosts.

Next phase after merge

  1. Operator picks an option in VAULT_SHARD_CUSTODY_POLICY.md §3.
  2. Phoenix ops executes docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md §1.1–§1.8.
  3. Phase 2 (history rewrite) starts, coordinated with a Gitea repo admin for branch-protection changes.

Tracking: issue #1.

## Summary Part of the sequenced cleanup tracked in issue #1. **Phase 1a — Vault consumer-prep scaffolding.** No rotation executed, no secret values committed. This PR stages the infrastructure Phoenix ops need to execute the actual Vault rotation. It does not change any live system. ### What this PR adds | File | Purpose | |---|---| | `docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md` | 9-step authoritative runbook: new root → rekey unseal → regenerate AppRoles → flip consumers → revoke old. Verification table + rollback path + Phase 2 handoff. | | `docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md` | Decision record for the next rotation. Three options (named-operator / cloud-KMS auto-unseal / Transit auto-unseal). Selection pending before rotation executes. | | `scripts/verify/enumerate-vault-consumers.sh` | Read-only grep over the tree for `VAULT_ROLE_ID` / `VAULT_SECRET_ID` / `auth/approle/login` references. Groups by top-level consumer. | | `scripts/verify/verify-vault-approle-auth.sh` | Post-rotation sanity check — posts AppRole login + token lookup-self. PASS/FAIL without echoing the Role ID, Secret ID, or client token. | | `phoenix-deploy-api/.env.example` | +10 lines: `VAULT_ADDR` / `VAULT_ROLE_ID` / `VAULT_SECRET_ID` placeholders + pointer to the runbook. | | `mission-control/.env.example` | NEW file (previously had none); documents launchpad `NEXT_PUBLIC_*` vars and the same Vault AppRole placeholder block. Server-side only. | ### What this PR does NOT do - Does NOT execute the rotation. That is operator-driven, per the runbook. - Does NOT touch the leaked-value docs in `LEAKED_SECRETS_INVENTORY.md` §3 — those are Phase 2 (history rewrite + redaction) and land after the rotation has executed. - Does NOT add a Vault client to `phoenix-deploy-api/server.js` or `mission-control/` source. Those services do not currently auth to Vault; adding the client is a follow-up once the decision in `VAULT_SHARD_CUSTODY_POLICY.md` §3 is made. - Does NOT include any secret values. The `.env.example` entries are empty placeholders. ### Consumer enumeration (from `scripts/verify/enumerate-vault-consumers.sh`) Current matches: - `dbis_core/` — 1 file (documentation reference to `process.env.VAULT_ROLE_ID`) - `rpc-translator-138/` — 2 files (separate AppRole `19cbc945-…`, rotate independently) - `scripts/` — 4 files (archived `configure-phoenix-vault*.sh` + `migrate-secrets-to-vault.sh`) `phoenix-deploy-api/` and `mission-control/` do not yet appear because they don't read Vault today — this PR adds the env-var scaffolding so they are ready to. ## Review & Testing Checklist for Human Risk: **green** — documentation + two new read-only verification scripts + two `.env.example` additions. Cannot break anything when merged. - [ ] Read `docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md` end-to-end; confirm the 9-step order matches Phoenix ops' mental model. - [ ] Read `docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md` and indicate (in the PR or in issue #1) which option to go with. Rotation blocks on this. - [ ] Run `bash scripts/verify/enumerate-vault-consumers.sh` locally and confirm no out-of-repo consumer is missing. - [ ] Confirm `scripts/verify/verify-vault-approle-auth.sh` never writes the Role ID / Secret ID / client token to any log (grep the script — the only thing printed is lengths and policy names). - [ ] Confirm `phoenix-deploy-api/.env.example` and `mission-control/.env.example` additions are consistent with how those services are actually deployed on the live hosts. ### Next phase after merge 1. Operator picks an option in `VAULT_SHARD_CUSTODY_POLICY.md` §3. 2. Phoenix ops executes `docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md` §1.1–§1.8. 3. Phase 2 (history rewrite) starts, coordinated with a Gitea repo admin for branch-protection changes. Tracking: issue #1.
nsatoshi added 1 commit 2026-04-18 20:19:36 +00:00
security(phase1a): Phoenix Vault rotation runbook + consumer-prep scaffolding
Some checks failed
AI Code Review / claude-review (pull_request) Failing after 48s
Details
57c717ad7e 
Part of the sequenced cleanup tracked in issue #1.

Scaffolding only — no rotation executed, no secret values committed.

- docs/runbooks/PHOENIX_VAULT_ROTATION_RUNBOOK.md: authoritative
  Phoenix Vault rotation procedure (9-step: new root → rekey unseal
  → regenerate AppRoles → flip consumers → revoke old). Verification
  table + rollback path + Phase 2 handoff notes.
- docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md: decision
  record for the next rotation. Three options documented
  (named-operator / cloud-KMS auto-unseal / Transit auto-unseal);
  selection pending operator sign-off before rotation executes.
- scripts/verify/enumerate-vault-consumers.sh: read-only grep over
  the tree for VAULT_ROLE_ID / VAULT_SECRET_ID / auth/approle/login
  references; flags which top-level consumers need a coordinated
  .env update at §1.6 of the runbook.
- scripts/verify/verify-vault-approle-auth.sh: post-rotation sanity
  check — posts AppRole login + token lookup-self; returns PASS/FAIL
  without echoing the Role ID, Secret ID, or client token.
- phoenix-deploy-api/.env.example: added VAULT_ADDR / VAULT_ROLE_ID
  / VAULT_SECRET_ID placeholder block with a pointer to the runbook.
  No values committed.
- mission-control/.env.example: NEW file (previously had none);
  documents the launchpad NEXT_PUBLIC_* vars and the same
  Vault AppRole placeholder block. Server-side only — never
  NEXT_PUBLIC_*.

Rotation execution stays with Phoenix ops; this commit only stages
the runbook + env scaffolding so the eventual rotation does not
require inventing infrastructure mid-incident.

Co-Authored-By: Nakamoto, S <defi@defi-oracle.io>
Some checks failed
AI Code Review / claude-review (pull_request) Failing after 48s
Details
This pull request has changes conflicting with the target branch.
  • docs/04-configuration/VAULT_SHARD_CUSTODY_POLICY.md
  • phoenix-deploy-api/.env.example
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin devin/phase1a-vault-consumer-prep-1776543363:devin/phase1a-vault-consumer-prep-1776543363
git checkout devin/phase1a-vault-consumer-prep-1776543363
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
70rn4710n A.r.yavari SEG nsatoshi
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: d-bis/proxmox#5
Delete Branch "devin/phase1a-vault-consumer-prep-1776543363"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?