secrets-engine/INTENT.md

layer	role	standard	companion	declaration	pep_stance	declared_at
Engine	Lifecycle	net-kingdom/canon/standards/security-layer-model_v0.7.md	net-kingdom/SECURITY-COMPANION.md	layer.yaml	pep-stance.yaml	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?