railiance-platform/workplans/RAILIANCE-WP-0007-credential-change-approval-workflow.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on_workplans, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on_workplans	state_hub_workstream_id
RAILIANCE-WP-0007	workplan	Credential Change Proposal Review Workflow	financials	railiance-platform	ready	codex	railiance	high	7	2026-06-27	2026-06-27	RAIL-PL-WP-0002 RAILIANCE-WP-0005 RAILIANCE-WP-0006	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

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

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

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

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

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

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

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

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.