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?