| Agent such as Codex or ops-warden | Request or use approved credentials through a safe front door. |
| Workload maintainer | Get a clear request, review, approval, and consumption path. |
| Security reviewer | See decisions, policy boundaries, verification evidence, and revocation state. |
| Future service maintainer | Add new secret types and delivery modes without weakening production custody. |
## Operating Model
### Stage roles
secrets-engine should bootstrap at least three OpenBao-facing roles:
| Role | Intended use | Initial privilege shape |
| --- | --- | --- |
| secrets-engine-build | Build/dev lanes, generated test values, low-risk experimentation | Can manage approved build-stage metadata and values under build prefixes. |
| secrets-engine-test | Test/staging lanes and integration verification | Can manage approved test-stage metadata and values; can perform positive/negative checks. |
| secrets-engine-prod | Production metadata apply and tightly controlled delivery | Can apply approved prod metadata and auth roles; raw prod value read/provisioning remains gated and logged. |
The exact OpenBao policy names can change, but the stage distinction is a
product requirement, not an implementation detail.
### Bootstrap credential files
Until proper OIDC/service authentication exists, a platform-root operator may
create temporary OpenBao credentials for the three roles and place them outside
repositories, for example under a local mode-0700 directory. The files must be:
- mode 0600;
- outside Git worktrees;
- named by role and environment only, never by secret value;
- revocable;
- recorded in non-secret bootstrap notes by path and accessor only when safe;
- treated as temporary infrastructure setup material.
Agents may be told the file path, not the token value. The engine should read
such files only when explicitly invoked in bootstrap mode.
## Functional Requirements
### FR1 - Secret catalog
The engine must maintain a non-secret catalog of secret lanes and grants.
Each catalog entry should include:
- catalog id;
- owning domain/repo/workload;
- stage: build, test, production, or another explicit stage;
- OpenBao mount and path;
- fields exposed;
- allowed consumers and auth claims;
- delivery modes;
- approval requirement;
- TTL and rotation expectations;
- verification requirements;
- revocation/deactivation behavior;
- audit evidence expectations.
### FR2 - Decision integration
Privileged actions must require an approved decision or approved credential
change request unless explicitly running in a local bootstrap or dry-run mode.
The engine must be able to:
- inspect a request;
- render a human-reviewable plan;
- link to the decision record when available;
- refuse denied, superseded, stale, or unapproved requests;
- record non-secret apply and verification evidence.
### FR3 - OpenBao metadata apply
The engine must generate and apply OpenBao metadata safely:
- ACL policies;
- auth roles;
- token roles where needed;
- KV metadata where safe;
- path and name restrictions based on catalog and stage;
- dry-run output before live mutation.
Production apply must fail closed if the request is not approved or if the plan
contains an out-of-bound policy, role, mount, path, wildcard, or broad admin
capability.
### FR4 - Secret provisioning
The engine must support secret value provisioning without exposing raw values in
coordination channels.
Initial supported modes:
- operator-attended OpenBao provisioning;
- bootstrap local file import with strict permissions;
- response-wrapped handoff where OpenBao supports it;
- generated test secrets for non-production only.
Production raw value automation should remain deliberately constrained until the
wrapped or dual-control flow is proven.
### FR5 - Secret delivery
The engine must provide delivery modes that avoid printing secret values:
- exec-time environment injection;
- exec-time temp file injection with cleanup;
- workload-specific config file generation such as temporary npm config;
- response wrapping for handoff flows;
- read checks that return boolean/evidence, not the value.
