feat(mvp): working secrets-engine CLI for the whynot-design npm publish lane
Implements SECRETS-WP-0002 end to end as a uv-managed Python package: - catalog: non-secret lane registry + strict validator (build/test/prod) - stage roles + OpenBao ACL policies; guards refuse wildcards, sys/, identity/, admin names, and cross-stage paths before any backend call - plan/apply: dry-run-first, idempotent policy + approle apply, decision-gated - decisions: State Hub lookup with local-fixture fallback; non-secret evidence to JSONL + hub progress, scrubbed of any value - provision/verify: mode-0600 file import + generated test values; positive/ negative checks that never print the value - exec delivery: `exec --catalog ... -- npm publish` injects the token via a temp .npmrc for the child only, cleaned up on exit/failure/interrupt - ops-warden routing contract + hardening backlog docs - 34 tests incl. live OpenBao integration; scripts/demo-e2e.sh runs the full chain against a throwaway bao dev server Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
58c24cff53
commit
a852d3f1ff
47 changed files with 3743 additions and 122 deletions
|
|
@ -1,34 +0,0 @@
|
|||
---
|
||||
id: REPO-WP-0002
|
||||
type: workplan
|
||||
title: "Template consumer validation checklist"
|
||||
domain: infotech
|
||||
repo: repo-seed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
created: "2026-06-22"
|
||||
updated: "2026-06-24"
|
||||
state_hub_workstream_id: "8aaf98a0-7045-4d5b-915f-bc9ecc5aa319"
|
||||
---
|
||||
|
||||
# Template consumer validation checklist
|
||||
|
||||
Validate repo-seed against statehub_register output and document consumer steps.
|
||||
|
||||
## Template validation checklist
|
||||
|
||||
```task
|
||||
id: REPO-WP-0002-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b"
|
||||
```
|
||||
|
||||
Result 2026-06-24: Added `docs/statehub-register.md` (consumer guide),
|
||||
`docs/template-validation-checklist.md` (bootstrap verification checklist),
|
||||
`registry/capabilities/capability.infotech.repo-template.md` with index entry,
|
||||
and README bootstrap pointers. Validated register output structure against
|
||||
`statehub_register.write_registration_files`.
|
||||
|
||||
Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency.
|
||||
|
|
@ -1,48 +1,42 @@
|
|||
---
|
||||
id: REPO-WP-0001
|
||||
id: SECRETS-WP-0001
|
||||
type: workplan
|
||||
title: "Bootstrap State Hub integration"
|
||||
domain: infotech
|
||||
repo: repo-seed
|
||||
status: finished
|
||||
repo: secrets-engine
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
created: "2026-06-22"
|
||||
updated: "2026-06-22"
|
||||
state_hub_workstream_id: "b809c762-8675-470c-be3e-0e5552f7d79d"
|
||||
topic_slug: custodian
|
||||
created: "2026-06-28"
|
||||
updated: "2026-06-28"
|
||||
state_hub_workstream_id: "53f0c7b7-2899-4e91-a18e-67186775e2e2"
|
||||
---
|
||||
|
||||
# Bootstrap State Hub integration
|
||||
|
||||
Git repository template to bootstrap coulomb projects.
|
||||
secrets-engine is a headless, multi-application, multi-tenant secrets workflow and automation layer that orchestrates approved secret custody, delivery, and lifecycle work across build, test, and production stages, with OpenBao as the initial enforcement backend.
|
||||
|
||||
## Review Generated Integration Files
|
||||
|
||||
```task
|
||||
id: REPO-WP-0001-T01
|
||||
status: done
|
||||
id: SECRETS-WP-0001-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "65734e48-ec48-47f2-bd5c-5673e94343cc"
|
||||
|
||||
state_hub_task_id: "e93ea995-8c3b-4892-ab09-70cf7e0a0346"
|
||||
```
|
||||
|
||||
Result 2026-06-22: Filled SCOPE.md; README is canonical intent.
|
||||
|
||||
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
|
||||
Replace generated placeholders with repo-specific facts where needed.
|
||||
|
||||
## Verify Local Developer Workflow
|
||||
|
||||
```task
|
||||
id: REPO-WP-0001-T02
|
||||
status: done
|
||||
id: SECRETS-WP-0001-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "76f1c245-3f06-4ef7-943f-bf2e9722c71b"
|
||||
|
||||
state_hub_task_id: "3269b817-6e10-4e9f-804f-73a8b1ded920"
|
||||
```
|
||||
|
||||
Result 2026-06-22: Template workflow documented.
|
||||
|
||||
Identify the repo's install, test, lint, build, and run commands. Add or refine
|
||||
those commands in the agent instructions so future coding sessions can verify
|
||||
changes confidently.
|
||||
|
|
@ -50,18 +44,15 @@ changes confidently.
|
|||
## Seed First Real Workplan
|
||||
|
||||
```task
|
||||
id: REPO-WP-0001-T03
|
||||
status: done
|
||||
id: SECRETS-WP-0001-T03
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "9670ff11-ed7a-49e6-8a1f-944af9794f6a"
|
||||
|
||||
state_hub_task_id: "62de7242-1a4c-4ed0-a4e4-ebe17bcc06b6"
|
||||
```
|
||||
|
||||
Result 2026-06-22: Created REPO-WP-0002.
|
||||
|
||||
Create the first implementation workplan for the repository's most important
|
||||
next change. After workplan file updates, run from `~/state-hub`:
|
||||
|
||||
```bash
|
||||
make fix-consistency REPO=repo-seed
|
||||
make fix-consistency REPO=secrets-engine
|
||||
```
|
||||
291
workplans/SECRETS-WP-0002-bootstrap.md
Normal file
291
workplans/SECRETS-WP-0002-bootstrap.md
Normal file
|
|
@ -0,0 +1,291 @@
|
|||
---
|
||||
id: SECRETS-WP-0002
|
||||
type: workplan
|
||||
title: "Bootstrap secrets-engine MVP"
|
||||
domain: platform-security
|
||||
repo: secrets-engine
|
||||
status: finished
|
||||
owner: codex
|
||||
created: "2026-06-28"
|
||||
updated: "2026-06-28"
|
||||
state_hub_workstream_id: "6c9a8c0d-18b5-41ac-8cd5-a8e84fb286b4"
|
||||
---
|
||||
|
||||
# SECRETS-WP-0002 - Bootstrap secrets-engine MVP
|
||||
|
||||
## Goal
|
||||
|
||||
Create the first usable secrets-engine implementation: a decision-aware wrapper
|
||||
around OpenBao that can apply approved secret metadata, provision and verify a
|
||||
pilot secret lane, and deliver a credential to a workload command without
|
||||
printing the secret.
|
||||
|
||||
The whynot-design npm publish token is the pilot case.
|
||||
|
||||
## Context
|
||||
|
||||
The platform currently has OpenBao, credential-change requests, State Hub
|
||||
decisions, ops-warden routing, and initial workload KV lane definitions. The
|
||||
missing piece is a dedicated workflow engine that owns the interaction model and
|
||||
hides OpenBao UI/CLI complexity from daily work.
|
||||
|
||||
During bootstrap, a platform-root operator may create temporary OpenBao
|
||||
credentials for secrets-engine roles and provide their local file paths to the
|
||||
agent. This is a setup accelerator, not the desired steady state.
|
||||
|
||||
## Design Constraints
|
||||
|
||||
- OpenBao remains the canonical custody and audit backend.
|
||||
- secrets-engine must not store raw secrets in Git, State Hub, chat, prompts, or
|
||||
normal logs.
|
||||
- Build, test, and production must have separate OpenBao privilege roles.
|
||||
- Production automation starts with approved metadata apply and safe delivery;
|
||||
raw value provisioning remains constrained and auditable.
|
||||
- ops-warden routes credential needs to secrets-engine but does not vend secrets.
|
||||
|
||||
## Tasks
|
||||
|
||||
## T01 - Seed repository structure and ownership docs
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "e974743b-29bb-42e0-b0c2-56d3fa9f6311"
|
||||
```
|
||||
|
||||
Create the initial repository with:
|
||||
|
||||
- `INTENT.md`;
|
||||
- `ProductRequirementsDocument.md`;
|
||||
- `docs/netkingdom-security-infrastructure.md`;
|
||||
- this workplan under `workplans/`;
|
||||
- `AGENTS.md` with no-secret-handling rules;
|
||||
- a minimal README pointing to the CLI and catalog direction.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- The repo states that secrets-engine owns workflow and interaction, not OpenBao
|
||||
custody itself.
|
||||
- Boundaries with OpenBao, ops-warden, State Hub, key-cape/user-engine, and
|
||||
flex-auth are explicit.
|
||||
- No raw secret value appears in any seed file.
|
||||
|
||||
## T02 - Define catalog schema and path conventions
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "0a21de63-7d79-45f9-aac8-e42adbadae28"
|
||||
```
|
||||
|
||||
Create a non-secret catalog schema for secret lanes and grants.
|
||||
|
||||
The schema must include catalog id, owner, stage, OpenBao mount/path, fields,
|
||||
consumer binding, delivery modes, approval requirement, verification checks,
|
||||
rotation and deactivation expectations, and audit evidence requirements.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- A validator rejects missing stage, mount, path, fields, approval model, and
|
||||
delivery modes.
|
||||
- The whynot-design npm publish lane can be represented without a secret value.
|
||||
- Build, test, and production entries can express different restrictions.
|
||||
|
||||
## T03 - Specify OpenBao stage roles and bootstrap policy
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "64ced137-6ff7-483b-80db-3b51afee7f0a"
|
||||
```
|
||||
|
||||
Define the initial OpenBao roles and policies:
|
||||
|
||||
- `secrets-engine-build`;
|
||||
- `secrets-engine-test`;
|
||||
- `secrets-engine-prod`.
|
||||
|
||||
Also define the bootstrap token-file process for initial setup.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Policy docs list exact allowed and denied OpenBao paths for each role.
|
||||
- Production role cannot act as root, platform-admin, or broad auth/sys admin.
|
||||
- Bootstrap token files are documented as local-only, mode 0600, outside repos,
|
||||
revocable, and temporary.
|
||||
- Negative checks prove each role is denied outside its stage/prefix boundary.
|
||||
|
||||
## T04 - Implement CLI skeleton and dry-run planning
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8cccc01e-4399-4bb3-9242-c3685d0916b4"
|
||||
```
|
||||
|
||||
Implement an initial CLI with dry-run first:
|
||||
|
||||
```text
|
||||
secrets-engine catalog list
|
||||
secrets-engine catalog show <catalog-id>
|
||||
secrets-engine decision inspect <decision-or-ccr-id>
|
||||
secrets-engine plan <decision-or-ccr-id>
|
||||
secrets-engine apply <decision-or-ccr-id> --stage <stage> --dry-run
|
||||
```
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Dry-run renders policy, auth role, path, field, and verification actions.
|
||||
- Dry-run refuses unapproved, denied, superseded, or malformed requests.
|
||||
- Dry-run refuses broad policy names, wildcards, root/platform-admin semantics,
|
||||
and out-of-stage paths.
|
||||
|
||||
## T05 - Integrate State Hub decisions and evidence
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "64898c75-e113-4c39-916e-1a640475ddf7"
|
||||
```
|
||||
|
||||
Connect the CLI to State Hub decision and progress APIs for non-secret metadata.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- A decision can be inspected from the CLI.
|
||||
- The CLI prints or records a review URL when available.
|
||||
- Apply and verification write non-secret progress notes.
|
||||
- Secret values are never sent to State Hub.
|
||||
|
||||
## T06 - Implement OpenBao apply for approved metadata
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T06
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b4b098d0-c6e0-4e50-a21e-b33d8ceea3e8"
|
||||
```
|
||||
|
||||
Apply approved OpenBao ACL policies and auth roles through the selected stage
|
||||
role or temporary bootstrap credential.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Apply succeeds for the whynot-design metadata lane in the intended stage.
|
||||
- Apply is idempotent.
|
||||
- Apply refuses unapproved decisions and out-of-policy mutations.
|
||||
- Apply evidence contains no secret values.
|
||||
|
||||
## T07 - Implement safe provisioning and verification
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T07
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1b458c09-a4e7-490c-acec-d55eff4bae6c"
|
||||
```
|
||||
|
||||
Support initial provisioning modes:
|
||||
|
||||
- attended operator provisioning;
|
||||
- local bootstrap file import with mode checks;
|
||||
- generated non-production test secrets.
|
||||
|
||||
Add positive and negative verification commands that do not print raw values.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- The whynot-design token can be confirmed present without printing it.
|
||||
- Positive verification proves the approved consumer can access/use it.
|
||||
- Negative verification proves an unrelated consumer is denied.
|
||||
- Verification evidence is non-secret and reviewable.
|
||||
|
||||
## T08 - Implement exec-time delivery for npm pilot
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T08
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "871cc4d4-4cbf-43be-98b7-3bad0d371f87"
|
||||
```
|
||||
|
||||
Implement:
|
||||
|
||||
```bash
|
||||
secrets-engine exec --catalog whynot-design-npm-publish -- npm publish
|
||||
```
|
||||
|
||||
For npm, prefer temporary config-file injection over printing/exporting the
|
||||
token. Clean up temporary files after the child process exits.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- npm publish can run with the token available only to the child process.
|
||||
- The token is not printed, persisted in the repo, or written to normal logs.
|
||||
- The temp config file is deleted on success, failure, and interruption where
|
||||
possible.
|
||||
- The command refuses to run when the catalog entry is not approved and ready.
|
||||
|
||||
## T09 - Update ops-warden routing contract
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T09
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b6c14f2a-49b1-4f39-a909-ba02a78fbef5"
|
||||
```
|
||||
|
||||
Define the contract ops-warden should use when routing non-SSH credential needs
|
||||
to secrets-engine.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Route output includes catalog id, readiness, decision status, and safe next
|
||||
command.
|
||||
- ops-warden does not request or store raw secret values.
|
||||
- whynot-design can retry the npm credential request and receive actionable
|
||||
guidance from the front door.
|
||||
|
||||
## T10 - Hardening backlog and exit from bootstrap mode
|
||||
|
||||
```task
|
||||
id: SECRETS-WP-0002-T10
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "52c070ec-33ac-4736-96e3-6bbacaa7fc83"
|
||||
```
|
||||
|
||||
Create the hardening backlog needed after the pilot.
|
||||
|
||||
Minimum items:
|
||||
|
||||
- replace bootstrap token files with OIDC/service auth;
|
||||
- add response-wrapped handoff where suitable;
|
||||
- add production dual-control option;
|
||||
- add rotation and compromised/deactivated secret states;
|
||||
- add audit report command;
|
||||
- add API service mode after CLI semantics stabilize.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Bootstrap tokens have revocation tasks.
|
||||
- Production hardening steps are explicit and prioritized.
|
||||
- The MVP can close without pretending bootstrap mode is the final security
|
||||
state.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- The repo can represent and validate the whynot-design npm publish catalog
|
||||
entry.
|
||||
- An approved decision can become an OpenBao policy/auth-role apply without
|
||||
platform-root hand typing.
|
||||
- The secret value can be provisioned and verified without disclosure.
|
||||
- `secrets-engine exec --catalog whynot-design-npm-publish -- npm publish` is
|
||||
either working or blocked only on an explicit external condition.
|
||||
- ops-warden can route the request to secrets-engine and report readiness.
|
||||
- Bootstrap credentials are documented, bounded, and scheduled for removal.
|
||||
Loading…
Add table
Add a link
Reference in a new issue