--- id: RAILIANCE-WP-0007 type: workplan title: "Credential Change Proposal Review Workflow" domain: financials repo: railiance-platform status: ready owner: codex topic_slug: railiance planning_priority: high planning_order: 7 created: "2026-06-27" updated: "2026-06-27" depends_on_workplans: - RAIL-PL-WP-0002 - RAILIANCE-WP-0005 - RAILIANCE-WP-0006 state_hub_workstream_id: "4d7ce243-f40a-4249-a46a-a24f75d6fe4c" --- # RAILIANCE-WP-0007 - Credential Change Proposal Review Workflow ## Goal Create a proposal -> review -> approve/deny with comment -> apply -> verify workflow for credential and it-sec changes, so operators do not need to author or mentally validate raw OpenBao commands. The first target is the whynot-design npm token lane from `RAILIANCE-WP-0006`. The workflow should then generalize to workload KV paths, OpenBao token roles, ops-warden access catalog entries, External Secrets lanes, credential rotation, deactivation, and compromise handling. ## Direction Do not start by extending OpenBao. Instead, build a small approval control plane around OpenBao: - OpenBao remains the enforcement, secret storage, token, and audit engine. - State Hub stores non-secret request lifecycle, comments, decisions, and evidence. - Repo files store reviewable non-secret request specs and generated policy artifacts. - Agents and CLIs create proposals and render them for human review. - Humans approve or deny with comments. - Only approved requests can be applied by an operator-controlled runner or interactive runbook. If the workflow proves valuable, a later UI or OpenBao extension can surface the same request index and statuses. ## Proposed Object Introduce a non-secret Credential Change Request, or `CCR`. Each CCR captures: - request id, title, requester, reviewer, approver, and applier; - target tenant/workload/environment/purpose; - OpenBao mount, path, fields, policies, auth roles, and bound claims; - access front door such as ops-warden, External Secrets, CSI, or direct caller fetch; - risk classification and approval requirements; - generated apply plan and verification plan; - rollback, deactivate, rotate, and compromise response plan; - comments, decision, timestamps, and non-secret audit evidence. Each CCR explicitly excludes secret values, token values, private keys, passwords, unseal/recovery material, and secret-bearing command output. ## Tasks ## T01 - Record the approval workflow design ```task id: RAILIANCE-WP-0007-T01 status: done priority: high state_hub_task_id: "c82ee783-80f1-48da-a9ed-4565eac699fc" ``` Document the desired operator workflow and why it should sit around OpenBao rather than inside the OpenBao UI initially. Acceptance: - The design describes the proposal, review, approval/denial, apply, verify, activate, deactivate, rotate, and compromised states. - The design names where State Hub, OpenBao, ops-warden, repo files, agents, and interactive runbooks fit. - The design keeps secret values out of State Hub, Git, chat, and prompts. **2026-06-27:** Added `docs/credential-change-approval.md` with the control plane direction, CCR object, state machine, State Hub/OpenBao/ops-warden roles, interactive runbook role, and compromise/deactivation path. ## T02 - Define the CCR schema and storage layout ```task id: RAILIANCE-WP-0007-T02 status: todo priority: high state_hub_task_id: "d50fb9e2-68c2-4a2b-8476-ce646d13e60a" ``` Create a versioned non-secret schema for credential change requests. Acceptance: - A schema exists for `workload-kv-read` requests covering mount, path, fields, policy name, auth role, bound claims, access front door, verification plan, and activation conditions. - The schema supports decision metadata: requested, proposed, approved, denied, needs_changes, applied, verified, active, deactivated, rotated, compromised, superseded, and cancelled. - The schema supports comments and references State Hub ids without storing secrets. - Example CCR fixtures include the whynot-design npm token lane. ## T03 - Add offline validation and rendering ```task id: RAILIANCE-WP-0007-T03 status: todo priority: high state_hub_task_id: "012f05cd-30ce-43dd-802b-4acc938db133" ``` Add a helper that validates CCR files and renders human review summaries. Acceptance: - Invalid CCRs fail before any OpenBao apply is attempted. - The renderer produces a compact review block that a human can understand in chat or State Hub. - The renderer highlights risky fields: broad claims, wildcard paths, privileged policies, missing negative verification, and missing deactivation plan. - A secret-pattern scan rejects likely token values in CCR files. ## T04 - Generate OpenBao apply plans from approved CCRs ```task id: RAILIANCE-WP-0007-T04 status: todo priority: high state_hub_task_id: "1b2e7752-815c-46f8-a2e2-212e8d04da80" ``` Generate deterministic, reviewable OpenBao apply plans from CCRs. Acceptance: - A workload KV CCR can generate policy HCL and auth-role commands or API payloads. - The plan includes a dry-run mode and a diff against existing source artifacts when available. - Applying a plan is refused unless the CCR is approved. - The applier uses an approved operator authority path and does not accept raw tokens in argv or logs. ## T05 - Add chat/CLI approval commands ```task id: RAILIANCE-WP-0007-T05 status: todo priority: high state_hub_task_id: "e6d4d2d1-1881-4db7-92f8-05e3fdb846ae" ``` Make the workflow usable from chat and command line. Acceptance: - Operators can approve, deny, or request changes with a comment. - Approvals/denials are recorded as non-secret State Hub events and in the CCR file or linked decision record. - The system refuses apply when the latest human decision is denied or needs_changes. - Agents can propose changes and respond to review comments without receiving secret values. ## T06 - Build an interactive runbook for apply and verify ```task id: RAILIANCE-WP-0007-T06 status: todo priority: high state_hub_task_id: "3c3fc38c-afa4-4367-b3e6-ba4b286ced30" ``` Wrap privileged application in an operator-friendly guided runbook. Acceptance: - The runbook loads an approved CCR, shows the plan, asks for final attended confirmation, then applies policy/auth metadata. - Secret value entry is handled through an approved OpenBao/operator path and is never echoed or logged. - Positive and negative verification steps are guided. - Non-secret evidence is recorded automatically. ## T07 - Pilot with whynot-design and ops-warden ```task id: RAILIANCE-WP-0007-T07 status: todo priority: high state_hub_task_id: "07a7d8bf-5528-41c8-a791-d6ccd0466a33" ``` Use the existing whynot-design npm token lane as the first end-to-end pilot. Acceptance: - The current whynot-design lane is represented as a CCR. - The CCR is rendered and reviewed in chat or State Hub. - A human approval or denial comment is recorded. - If approved, the runbook applies the policy/auth metadata, guides secret provisioning, verifies access, and notifies ops-warden. - ops-warden activates its catalog entry only after CCR verification. ## T08 - Add deactivation, rotation, and compromise flows ```task id: RAILIANCE-WP-0007-T08 status: todo priority: medium state_hub_task_id: "23d6ef9d-8dbc-4468-b486-5ec8ada71130" ``` Support lifecycle states beyond initial creation. Acceptance: - Existing credentials can be imported as CCR-backed inventory without secret values. - Operators can mark a lane deactivated, rotated, or compromised with reason and evidence. - Deactivation disables the relevant access front door and auth/policy path. - Compromise flow records blast-radius notes and required follow-up tasks. ## Exit Criteria - A human can review and approve or deny a credential/security change without writing raw OpenBao commands. - An approved request can be applied by an operator-controlled helper or interactive runbook. - State Hub and repo artifacts contain non-secret lifecycle, decision, and evidence records. - OpenBao remains the enforcement and audit source for actual secret access. - The whynot-design npm token lane can complete through this workflow.