355 lines
14 KiB
Markdown
355 lines
14 KiB
Markdown
---
|
|
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.
|