253 lines
8.0 KiB
Markdown
253 lines
8.0 KiB
Markdown
---
|
|
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.
|