secrets-engine/INTENT.md

# 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?**