--- id: RAILIANCE-WP-0007 type: workplan title: "Credential Change Proposal Review Workflow" domain: financials repo: railiance-platform status: active owner: codex topic_slug: railiance planning_priority: high planning_order: 7 created: "2026-06-27" updated: "2026-06-28" 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: done 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. **2026-06-27:** Added `schemas/credential-change-request.schema.yaml`, the `credential-change-requests/` storage directory, and `credential-change-requests/CCR-2026-0001-whynot-design-npm-publish.yaml` as the first non-secret CCR fixture. The whynot CCR is intentionally `proposed` and marks the bound claim as unconfirmed, so apply is blocked until review. ## T03 - Add offline validation and rendering ```task id: RAILIANCE-WP-0007-T03 status: done 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. **2026-06-27:** Added `scripts/credential-change.py validate` and `render`, plus Make targets `credential-change-validate` and `credential-change-render`. Validation rejects secret-looking markers and broad/unsafe request shapes; render produces the chat/State Hub review summary and highlights unconfirmed bound claims. CCRs now also carry machine-readable front-door readiness fields: `access_frontdoor.readiness` and `access_frontdoor.resolvable`. Unit coverage lives in `tests/test_credential_change.py`. ## T04 - Generate OpenBao apply plans from approved CCRs ```task id: RAILIANCE-WP-0007-T04 status: progress 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. **2026-06-27:** Added `plan` and guarded `apply-plan` rendering for workload KV CCRs, with Make targets `credential-change-plan` and `credential-change-apply-plan`. `apply-plan` currently refuses any CCR that is not `approved` and also refuses unconfirmed bound claims. Remaining T04 work is to add a richer diff against existing source artifacts and eventually bridge from reviewed plan to the interactive live applier. **2026-06-28:** Added OIDC `allowed_redirect_uris` to the CCR contract and generated role payloads after live OpenBao rejected an OIDC role without callbacks. Unit coverage now checks the generated whynot-design role payload. ## T05 - Add chat/CLI approval commands ```task id: RAILIANCE-WP-0007-T05 status: progress 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. **2026-06-27:** Added file-backed `approve`, `deny`, and `needs-changes` commands that require reviewer and comment text and append non-secret review comments to the CCR. Added `confirm-binding` for explicit non-secret auth binding confirmation. Added `status` plus Make targets `credential-change-status` and `credential-change-status-json` so ops-warden can consume `readiness`/`resolvable` without scraping prose. Remaining T05 work is State Hub decision-event emission and tighter chat integration. Created a State Hub decision for `CCR-2026-0001` and added `sync-decision` so resolved State Hub decisions can update the file-backed CCR status. ## 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: progress 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. **2026-06-27:** The whynot-design lane is represented as `CCR-2026-0001` and can be rendered for review. The whynot-design bound claim was confirmed from operator chat context and recorded in the CCR, but it remains proposed/unapproved, so live apply and ops-warden activation are correctly blocked. **2026-06-27:** Converted the ops-warden batch follow-up `fe5b1696-8956-4bd5-9d6f-dbde1901a076` into three proposed CCRs: `CCR-2026-0001` for `whynot-design-npm-publish`, `CCR-2026-0002` for `issue-core-ingestion-api-key`, and `CCR-2026-0003` for `llm-connect-openrouter-api-key`. All three are explicitly `readiness: template` and `resolvable: false` until owner confirmation, approval, OpenBao apply, secret provisioning, and verification are complete. **2026-06-28:** Synced State Hub decision `250669d0-8475-4527-9624-cd072249f9a9` into `CCR-2026-0001`; the lane is now `approved` with confirmed binding and `apply_allowed: true`. A live OpenBao policy apply using the available token helper reached the active OpenBao pod but still failed with `403 permission denied` on `sys/policies/acl/workload-kv-read-whynot-design-npm-publish`, so the front door remains `readiness: template` and `resolvable: false`. Added guarded `credential-change-operator-commands` output so a platform operator can run the reviewed non-secret policy and auth-role commands without hand-writing them; secret value provisioning and verification remain under approved custody. **2026-06-28:** After correcting the tenant/org to `coulomb`, the corrected approval was synced from State Hub decision `e6381a56-6b04-4fd5-b2de-f3ef59cde888`; `CCR-2026-0001` is approved and `apply_allowed: true` for `platform/workloads/coulomb/whynot-design/npm-publish`. The operator reported secret provisioning likely completed, but Codex metadata-only verification still received `403 permission denied`. Prepared `docs/whynot-design-npm-publish-handoff.md` as the next-session checklist for policy, auth-role, metadata verification, positive verification, negative verification, and activation without printing the token. **2026-06-28:** With the temporary operator token, Codex applied/confirmed the OpenBao read policy and OIDC role, confirmed metadata `catalog-id`, and confirmed `NPM_AUTH_TOKEN` field presence without printing or recording the value. The CCR now records non-secret evidence for that apply check. Positive whynot-design and negative non-whynot caller verification still gate `active`/`ready`. ## 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. ## T09 - Add decision templates and guided review actions ```task id: RAILIANCE-WP-0007-T09 status: todo priority: high state_hub_task_id: "c436fd8b-cd82-4600-81b0-87ec069d7ae6" ``` Remove the current friction where reviewers must know magic rationale prefixes for State Hub decisions to sync back into CCR status. Acceptance: - Each CCR review page or chat handoff shows explicit approve, deny, and needs changes templates. - Generated templates include the accepted prefixes (`APPROVE:`, `DENY:`, and `NEEDS_CHANGES:`) and pre-fill the CCR id, corrected path, policy, auth role, and non-secret rationale prompt. - The dashboard or agent response links directly to the decision and states what phrase or button will be recognized. - The sync tooling refuses ambiguous free-text approvals with a friendly message that shows the valid templates. - Future UI work can replace prefix parsing with structured decision outcomes without changing the CCR audit trail. ## 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.