155 lines
6.5 KiB
Markdown
155 lines
6.5 KiB
Markdown
# 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, scoped OpenBao capability handoff, 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 and scoped capability
|
|
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 or capability
|
|
grants;
|
|
- operate with distinct build, test, and production privilege layers;
|
|
- deliver secrets and scoped capabilities 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, scoped capability handoff, 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, scoped capability grants, and
|
|
access;
|
|
- a CLI and service API for operators, agents, and automation;
|
|
- a typed catalog of KV secret lanes, auth-capability lanes, grants, delivery
|
|
modes, and stage policies;
|
|
- an OpenBao policy/auth-role applier with strict local validation;
|
|
- an exec-time secret delivery and scoped capability handoff 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/capability access; do not make ops-warden vend secrets. |
|
|
| Workload secret consumption | Workload repos / CI / runtime | Provide safe delivery and handoff contracts plus 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?**
|