secrets-engine/INTENT.md

---
# THE layer declaration (§11, GH-DEC-2026-017 §1). `layer.yaml` is derived from
# this frontmatter and must agree with it; it does not govern. Comparison of the
# §3 vocabulary is ASCII case-insensitive, so `Engine` here and `engine` there
# are the same value and neither is re-spelled (GH-DEC-2026-017 §2).
layer: Engine
role: Lifecycle
# No standard version here or in the sidecar (GH-DEC-2026-017 §5 / A12): the
# declared layer is a standing property that does not change when the standard
# is revised. Version-scoped state belongs in the derived conformance record.
standard: net-kingdom/canon/standards/security-layer-model
companion: net-kingdom/SECURITY-COMPANION.md
declaration: layer.yaml       # derived form; this frontmatter governs
pep_stance: pep-stance.yaml
declared_at: "2026-08-29"
---

# INTENT

> **Layer: Engine. Role: Lifecycle.** This is this repository's own declaration
> under the accepted NetKingdom Security Layer Model
> (`net-kingdom/canon/standards/security-layer-model_v0.7.md`) and its working
> companion (`net-kingdom/SECURITY-COMPANION.md`). The machine-readable form
> required by §11 is `layer.yaml`. A layer stated about this repository by
> another repository is not a declaration; this file, in this repository's
> voice, is.
>
> secrets-engine is a **deterministic API over OpenBao** for one modeled
> concept: the cataloged credential lane and its lifecycle. The same
> authoritative inputs — catalog entry, access-engine decision record, and
> OpenBao state — must yield the same plan, apply, delivery, and lifecycle
> result. That is why this repository is an Engine, not Staff, even though
> operators and agents invoke it at runtime.
>
> **It is not a decision point.** `access-engine` (today `flex-auth`) renders
> whether authority exists. gate-house authors the doctrine that may reach that
> decision only as a request claim or a versioned policy rule. OpenBao is
> Tooling: custody, policy enforcement, leases, and backend audit. This engine
> materializes an already-rendered decision into scoped OpenBao work. A
> credential is an artifact of authority, never its source.
>
> **It is PEP-shaped.** Apply, provision, exec delivery, handoff, suspend,
> deactivate, and destroy cause protected side effects, so the four PEP
> obligations in §6.4 bind: no side effect without a decision record or a
> recorded stance; no replay of a verdict outside its binding and lifetime;
> a published unreachable-engine stance at `pep-stance.yaml`; reconstructability
> bounded by §9.6. Being PEP-shaped does not change the layer.
>
> **Proposed surfaces, not yet assented as shipped APIs.** ops-warden has
> declared its SSH-CA signing write as an engine gap with intended owner
> secrets-engine. kings-guard has proposed secret-use evidence against this
> engine. This repository **accepts both as proposed Lifecycle surfaces** and
> **declines operational SSH-lane stewardship**: `ops-warden` remains the Staff
> PEP that requests a certificate after a decision. What belongs here is the
> engine API those Staff repositories should call instead of OpenBao. Until
> those surfaces exist, the gaps stay proposed, not silently taken.
>
> **Finding on the §4 catalog cell.** The catalog row currently says this
> repository owns "credential abstraction, custody, lifecycle". Custody belongs
> to OpenBao. This engine owns the lifecycle API *over* that custody. The
> wording should not assign a Tooling property to an Engine.

> 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.
> See `SCOPE.md` for what is implemented today.

## One-liner

**secrets-engine is the Lifecycle engine for approved credential work: a
deterministic API that turns an access-engine decision into scoped OpenBao
custody, delivery, and lifecycle actions across build, test, and production.**

## 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 Tooling for 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;
- Staff repositories such as ops-warden need an Engine API for credential and
  scoped-capability work, not a direct OpenBao client and not secret-vending
  responsibility of their own.

This repository exists to capture that complexity once, behind a stable,
deterministic, and auditable interface.

## The Mission

To provide a decision-aware Lifecycle engine that can:

- consume an access-engine decision and refuse to proceed without one, or
  record the application of a declared unreachable-engine stance in its place;
- translate that decision 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;
- emit non-secret evidence under the §9.6 bound — the archive proves records
  it holds were not altered or truncated after arrival, not that every event
  was sent, and not that absence means non-occurrence;
- make routine secure work fast enough that operators and agents actually use
  the Engine path instead of touching OpenBao.

## Core Principles

### 1. Decision elsewhere, materialization here

Secret establishment, access, rotation, and deactivation start from an
access-engine decision record naming the request it was rendered for.
This engine may automate the work after that decision; it does not render,
cache, or substitute one. Compiled catalog data that would determine an
outcome before the engine runs is still deciding, and is forbidden. For a
privileged production side effect, a successful approval-engine CAS consume
must precede the OpenBao call (`GH-DEC-2026-003`). Holding an ALLOW is not
authority to act.

### 2. OpenBao is Tooling; this engine is the API over it

OpenBao remains the vault, policy, lease, and audit backend. secrets-engine
owns the catalog, validation, delivery, scoped capability handoff, lifecycle
operations, and the operator/agent/Staff interface to those operations. Staff
must not hold a direct OpenBao client for work this engine is meant to expose.

### 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. Stage is the current equivalent scope for the PEP stance map until
security-zone membership is consumed as a claim.

### 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 Engine API call. That ease must
not require handing platform-root or platform-admin power to routine
automation, and it must not mint standing credentials for agents. Agent
authority is per task, time-bounded, and attributable to the principal the
agent acts for.

### 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, must never
become an implicit fallback, and must be replaced by narrower service identity
bound to OpenBao.

### 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. Every such allow has
an explicit lifetime — a TTL, or a binding to a session that ends. The engine
should make this easier than copying or inspecting a secret value.

### 8. Evidence is bounded, not omniscient

Every apply, read, delivery, lease, verification, revocation, and deactivation
emits non-secret evidence. Load-bearing events — those a control would be
unsound without — require atomic local emission and a declared cadence or
heartbeat. Attributive events should seek atomicity; where they trade it away,
the trade is declared and completeness is not claimed. Evidence belongs in
`audit-core`. Local JSONL and State Hub notes are not a substitute for that
engine.

### 9. Adaptive systems may only tighten

This engine may shorten a lifetime, refuse a delivery, suspend a lane, or
require a fresh decision. It must not manufacture authority, widen a grant, or
treat silence from `access-engine` as permission.

## What This Is

secrets-engine is:

- the Lifecycle engine for cataloged credential lanes;
- a CLI today and a service API for operators, agents, CI, and Staff
  repositories that must not speak OpenBao;
- 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;
- a PEP at every protected side effect, with a published unreachable-engine
  stance;
- the credential interaction surface that ops-warden routes to after a
  decision.

## What This Is Not

secrets-engine is not:

- a replacement for OpenBao, or the owner of custody;
- an identity provider or MFA system;
- an authorization decision engine, an approval store, or a maturity 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;
- the operational owner of the SSH certificate lane — that Staff PEP remains
  ops-warden's; this engine may later expose the signing API it should call;
- an observation or containment system — kings-guard proposes, this engine
  does not watch production, and actuation is unowned estate-wide.

## System Boundary

| Concern | Primary owner | secrets-engine responsibility |
| --- | --- | --- |
| Secret custody, leases, backend audit | OpenBao (Tooling) / railiance-platform | Lifecycle API over least-privilege roles and validated paths. |
| Authorization decisions | access-engine (`flex-auth`) | Consume a decision record; never render or cache one. |
| Approval object | approval-engine | Consume an approval as an input claim; never store or mutate it. |
| Security doctrine | gate-house | Apply doctrine only as it arrives on the decision or in a versioned policy package. |
| Human and service identity | key-cape / user-engine | Consume identity claims; do not replace identity lifecycle. |
| SSH certificate issuance (Staff PEP) | ops-warden | Route and, when the surface exists, expose the OpenBao SSH-CA API; do not take the lane. |
| Evidence custody and integrity | audit-core | Emit non-secret events under the §9.6 bound; do not become the archive. |
| 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 progress pointers only; not a security state plane. |

## 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. **Layer-model conformance:** published PEP stance equals shipped behaviour;
   live side effects hold an access-engine decision record or a recorded stance;
   evidence classified and emitted to audit-core; proposed SSH-CA and secret-use
   surfaces accepted or declined in this repository's own contract, not only in
   other repositories' gap registers.
6. **Service mode:** expose a deterministic 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
to a decision this engine did not render?**