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
150
INTENT.md
Normal file
150
INTENT.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
# INTENT
|
||||
|
||||
> This file captures why this repository exists, the direction it is moving
|
||||
> toward, and the kind of system it is meant to become. It is intentionally
|
||||
> aspirational and stable, not a description of current implementation.
|
||||
|
||||
## One-liner
|
||||
|
||||
**secrets-engine is the secure interaction and automation layer for approved
|
||||
secret custody, delivery, and lifecycle work across build, test, and production,
|
||||
with OpenBao as the initial enforcement backend.**
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Secret management is too important to be handled through scattered manual UI
|
||||
steps, copied commands, chat handoffs, and ad hoc token files.
|
||||
|
||||
OpenBao is the right place to enforce custody, policy, lease, and audit. It is
|
||||
not, by itself, the right daily interaction surface for operators, agents,
|
||||
workloads, and approval workflows. Direct use of OpenBao UI and CLI surfaces has
|
||||
already produced avoidable friction:
|
||||
|
||||
- approved decisions still require a human to bridge low-level OpenBao details;
|
||||
- agents and operators hit interface mismatches before reaching the security
|
||||
work they were trying to complete;
|
||||
- build, test, and production need different levels of privilege and ceremony;
|
||||
- secret values must never move through chat, Git, prompts, State Hub messages,
|
||||
or workplans;
|
||||
- ops-warden needs a reliable front door for credential use, not direct secret
|
||||
custody responsibility.
|
||||
|
||||
This repository exists to capture that complexity once, behind a stable and
|
||||
auditable interface.
|
||||
|
||||
## The Mission
|
||||
|
||||
To provide a decision-aware secrets workflow that can:
|
||||
|
||||
- translate approved requests into narrowly scoped OpenBao changes;
|
||||
- operate with distinct build, test, and production privilege layers;
|
||||
- deliver secrets to commands and workloads without printing or storing raw
|
||||
values in coordination systems;
|
||||
- record enough non-secret evidence for review, audit, and troubleshooting;
|
||||
- make routine secure work fast enough that operators and agents actually use
|
||||
the secure path.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Decision First
|
||||
|
||||
Secret establishment, access, rotation, and deactivation start from an explicit
|
||||
request and decision. The engine may automate the work after approval; it does
|
||||
not silently create new secret authority.
|
||||
|
||||
### 2. OpenBao Enforces, secrets-engine Orchestrates
|
||||
|
||||
OpenBao remains the vault, policy, lease, and audit backend. secrets-engine owns
|
||||
the workflow, catalog, validation, delivery, and operator/agent interface.
|
||||
|
||||
### 3. Stage-aware Privilege
|
||||
|
||||
Build, test, and production are separate security contexts. Each has its own
|
||||
OpenBao role, policy boundary, approval expectation, TTL limits, and delivery
|
||||
rules.
|
||||
|
||||
### 4. No Secret Values in Coordination Surfaces
|
||||
|
||||
Git, State Hub, workplans, chat, prompts, issue comments, and normal logs carry
|
||||
only non-secret metadata. Raw values are delivered through OpenBao, wrapped
|
||||
responses, local exec-time injection, or short-lived bootstrap files with strict
|
||||
permissions.
|
||||
|
||||
### 5. Least Friction Without Broad Power
|
||||
|
||||
The common path should be one clear command or review action. That ease must not
|
||||
require handing platform-root or platform-admin power to routine automation.
|
||||
|
||||
### 6. Bootstrap Honestly, Then Harden
|
||||
|
||||
During infrastructure setup it is acceptable to use temporary root-created
|
||||
OpenBao credentials stored outside repositories with mode 0600 and explicit
|
||||
revocation. Those bootstrap shortcuts must be tracked as temporary and replaced
|
||||
by narrower auth roles.
|
||||
|
||||
### 7. Prefer Exec-time Delivery
|
||||
|
||||
When a workload or operator command needs a secret, the default delivery mode is
|
||||
process-local injection for the duration of that command. The engine should make
|
||||
this easier than copying or inspecting a secret value.
|
||||
|
||||
### 8. Auditable and Reversible
|
||||
|
||||
Every apply, read, delivery, lease, verification, revocation, and deactivation
|
||||
has non-secret evidence that can be reviewed later.
|
||||
|
||||
## What This Is
|
||||
|
||||
secrets-engine is:
|
||||
|
||||
- a workflow layer for approved secret changes and access;
|
||||
- a CLI and service API for operators, agents, and automation;
|
||||
- a typed catalog of secret lanes, grants, delivery modes, and stage policies;
|
||||
- an OpenBao policy/auth-role applier with strict local validation;
|
||||
- an exec-time secret delivery helper;
|
||||
- an audit evidence writer for State Hub and local logs;
|
||||
- the credential interaction surface that ops-warden can route to.
|
||||
|
||||
## What This Is Not
|
||||
|
||||
secrets-engine is not:
|
||||
|
||||
- a replacement for OpenBao;
|
||||
- an identity provider or MFA system;
|
||||
- an authorization decision engine;
|
||||
- an application-specific secret store;
|
||||
- a place to persist raw secret values outside OpenBao;
|
||||
- a prompt-time secret injection mechanism for LLMs;
|
||||
- a bypass around review, approval, or production custody.
|
||||
|
||||
## System Boundary
|
||||
|
||||
| Concern | Primary owner | secrets-engine responsibility |
|
||||
| --- | --- | --- |
|
||||
| Secret custody, leases, audit backend | OpenBao / railiance-platform | Use through least-privilege roles and validated paths. |
|
||||
| Human and service identity | key-cape / user-engine | Consume identity claims; do not replace identity lifecycle. |
|
||||
| Authorization decisions | flex-auth / State Hub decision model | Require and verify decisions before privileged actions. |
|
||||
| SSH certificate issuance | ops-warden | Provide routed credential access; do not make ops-warden vend secrets. |
|
||||
| Workload secret consumption | Workload repos / CI / runtime | Provide safe delivery contracts and catalog entries. |
|
||||
| Request history and progress | State Hub | Write non-secret evidence and decision links only. |
|
||||
|
||||
## Direction of Evolution
|
||||
|
||||
The repository should evolve through these phases:
|
||||
|
||||
1. **Bootstrap:** root-created temporary OpenBao roles/tokens allow efficient
|
||||
setup without repeated manual UI handoffs.
|
||||
2. **MVP:** catalog, decision validation, OpenBao apply plan, and safe exec-time
|
||||
delivery work for the whynot-design npm publish token pilot.
|
||||
3. **Stage separation:** build, test, and production roles have distinct policy
|
||||
boundaries and verification rules.
|
||||
4. **Hardening:** replace bootstrap token files with OIDC/service auth, wrapped
|
||||
delivery, short leases, dual control for production provisioning, and routine
|
||||
rotation/deactivation workflows.
|
||||
5. **Service mode:** expose an API that ops-warden, agents, CI, and future UI
|
||||
surfaces can use without knowing OpenBao internals.
|
||||
|
||||
## Guiding Question
|
||||
|
||||
**How can approved secret work become low-friction for humans and agents while
|
||||
keeping raw values, OpenBao privileges, and production impact tightly bounded?**
|
||||
Loading…
Add table
Add a link
Reference in a new issue