From 9a8938be3eab193f2fcdeeb286a8b022d618158b Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 22 Oct 2026 17:46:15 +0200 Subject: [PATCH] Align the lifecycle intent with the accepted engine blueprint. INTENT.md now describes one enabling library over the store, manifested as a CLI or a single-stage service. SECRETS-WP-0016 is the implementation workplan. The accepted layer statute is still v0.8. Assistant: grok Assistant-Session: 01a1609f-72b8-7222-9dff-fae300115e42 --- INTENT.md | 89 +++++++++----- WORK-RECORDS.md | 6 + .../SECRETS-WP-0016-engine-manifestations.md | 116 ++++++++++++++++++ 3 files changed, 181 insertions(+), 30 deletions(-) create mode 100644 workplans/SECRETS-WP-0016-engine-manifestations.md diff --git a/INTENT.md b/INTENT.md index e7b7c9b..7d29c6f 100644 --- a/INTENT.md +++ b/INTENT.md @@ -25,19 +25,37 @@ declared_at: "2026-08-29" > 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. +> secrets-engine is a tool of automation for one capability: the cataloged +> credential lane and its lifecycle. It encapsulates that work in one +> consistent interface. The same authoritative inputs — catalog entry, +> access-engine decision record, and OpenBao state — yield the same plan, +> apply, delivery, and lifecycle result. That determinism 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. +> This shape is gate-house ADR-015 and `ArchitectureBlueprint.md` §2.2, +> accepted 2026-10-22. The same wording is assembled in proposed +> `security-layer-model_v0.9` §3.3. The accepted statute and companion remain +> v0.8 until that successor is adopted. v0.8's PEP obligations still bind. +> +> **It enables the capability. It is not access control.** `access-engine` +> (today `flex-auth`) renders whether authority exists, including whether an +> operator may start or call an instance. 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 does not hold those records. Other engines may use OpenBao for +> other capabilities. This engine materializes an already-rendered decision +> into scoped OpenBao work. A credential is an artifact of authority, never +> its source. Holding the credential inside the process does not make this +> engine a gate on the store. +> +> **One library, three manifestations.** The library validates, explains, and +> plans without the store credential. The CLI is that library in a process. A +> service is the same process kept running for one stage. At start the process +> is injected with that stage's OpenBao credential. The credential enables the +> capability and is not returned to the operator. A use-privilege does not +> confer it. An operator who may delegate can assign the work to an operator +> who may use the instance. The assignment transfers neither privilege. > > **It is PEP-shaped.** Apply, provision, exec delivery, handoff, suspend, > deactivate, and destroy cause protected side effects, so the four PEP @@ -67,9 +85,10 @@ declared_at: "2026-08-29" ## 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.** +**secrets-engine enables cataloged credential lifecycle: one deterministic +library over OpenBao, manifested as a CLI or as a service for a single stage, +with that stage's credential injected at start and never returned to the +operator.** ## Why This Exists @@ -92,7 +111,8 @@ produced avoidable friction: responsibility of their own. This repository exists to capture that complexity once, behind a stable, -deterministic, and auditable interface. +deterministic, and auditable interface that is more reliable and more +efficient than doing the same OpenBao work by hand. ## The Mission @@ -124,12 +144,15 @@ 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 +### 2. OpenBao is Tooling; this engine enables one capability 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. +OpenBao remains the vault, policy, lease, and audit backend. Several engines +may use that store. secrets-engine enables the catalog, validation, delivery, +scoped capability handoff, and lifecycle operations, and it is the +operator/agent/Staff interface for that capability. It does not own custody, +it is not the store's only client, and it does not decide who may use an +instance. Staff does this capability through the engine rather than by hand. +Another engine's different capability over OpenBao is outside this intent. ### 3. Stage-aware privilege @@ -189,14 +212,15 @@ treat silence from `access-engine` as permission. 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 +- one library for that capability; +- a CLI, and for one stage that must stay up, a service, both manifestations + of that library and both injected with that stage's credential at start; +- a typed catalog of KV 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; +- an exec-time delivery and scoped capability handoff helper; - a PEP at every protected side effect, with a published unreachable-engine - stance; + stance, consuming access-engine's decision rather than rendering one; - the credential interaction surface that ops-warden routes to after a decision. @@ -204,9 +228,11 @@ secrets-engine is: secrets-engine is not: -- a replacement for OpenBao, or the owner of custody; +- a replacement for OpenBao, the owner of custody, or the only client of that store; +- access control for OpenBao, or a decider of who may start or call an instance; - an identity provider or MFA system; - an authorization decision engine, an approval store, or a maturity engine; +- a second implementation that appears only when the library is manifested as a service; - an application-specific secret store; - a place to persist raw secret values outside OpenBao; - a prompt-time secret injection mechanism for LLMs; @@ -220,7 +246,7 @@ secrets-engine is not: | Concern | Primary owner | secrets-engine responsibility | | --- | --- | --- | -| Secret custody, leases, backend audit | OpenBao (Tooling) / railiance-platform | Lifecycle API over least-privilege roles and validated paths. | +| Secret custody, leases, backend audit | OpenBao (Tooling) / railiance-platform | Enable the lifecycle capability over least-privilege roles and validated paths. Other engines may use the same store for other capabilities. | | 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. | @@ -248,8 +274,11 @@ The repository should evolve through these phases: 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. +6. **Manifestations:** the library stays free of the store credential. The CLI + and a kept-running service are that same library in a process injected for + one stage. The service is not a second product. Operators, agents, CI, and + future UI surfaces call it without knowing OpenBao internals and without + receiving the injected credential. ## Guiding Question diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 9fb6173..6b9c141 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -24,6 +24,7 @@ | workplan | SECRETS-WP-0013 | proposed | — | workplans/SECRETS-WP-0013-task-scoped-openbao-execution.md | | workplan | SECRETS-WP-0014 | active | — | workplans/SECRETS-WP-0014-pdp-transport-and-responder-authentication.md | | workplan | SECRETS-WP-0015 | active | — | workplans/SECRETS-WP-0015-original-keycape-recovery-selector.md | +| workplan | SECRETS-WP-0016 | ready | — | workplans/SECRETS-WP-0016-engine-manifestations.md | | task | SECRETS-WP-ADHOC-2026-08-21-T01 | done | — | workplans/ADHOC-2026-08-21.md | | task | SECRETS-WP-ADHOC-2026-08-23-T01 | done | — | workplans/ADHOC-2026-08-23.md | | task | SECRETS-WP-0001-T01 | done | — | workplans/SECRETS-WP-0001-statehub-bootstrap.md | @@ -97,6 +98,11 @@ | task | SECRETS-WP-0015-T03 | done | — | workplans/SECRETS-WP-0015-original-keycape-recovery-selector.md | | task | SECRETS-WP-0015-T04 | wait | — | workplans/SECRETS-WP-0015-original-keycape-recovery-selector.md | | task | SECRETS-WP-0015-T05 | done | — | workplans/SECRETS-WP-0015-original-keycape-recovery-selector.md | +| task | SECRETS-WP-0016-T01 | todo | — | workplans/SECRETS-WP-0016-engine-manifestations.md | +| task | SECRETS-WP-0016-T02 | todo | — | workplans/SECRETS-WP-0016-engine-manifestations.md | +| task | SECRETS-WP-0016-T03 | todo | — | workplans/SECRETS-WP-0016-engine-manifestations.md | +| task | SECRETS-WP-0016-T04 | todo | — | workplans/SECRETS-WP-0016-engine-manifestations.md | +| task | SECRETS-WP-0016-T05 | todo | — | workplans/SECRETS-WP-0016-engine-manifestations.md | | intake | SECRETS-IN-0001 | closed | — | intakes/intakes.md | | intake | SECRETS-IN-0002 | closed | — | intakes/intakes.md | | intake | SECRETS-IN-0003 | closed | — | intakes/intakes.md | diff --git a/workplans/SECRETS-WP-0016-engine-manifestations.md b/workplans/SECRETS-WP-0016-engine-manifestations.md new file mode 100644 index 0000000..d3fdfb7 --- /dev/null +++ b/workplans/SECRETS-WP-0016-engine-manifestations.md @@ -0,0 +1,116 @@ +--- +id: SECRETS-WP-0016 +type: workplan +title: "Manifest the lifecycle engine as one library, a CLI, and a single-stage service" +domain: infotech +repo: secrets-engine +status: ready +owner: secrets-engine +topic_slug: custodian +created: "2026-10-22" +updated: "2026-10-22" +flavor: implementation +depends_on: [] +related: [SECRETS-WP-0008, SECRETS-WP-0014] +--- + +Implements the engine shape in `INTENT.md` after gate-house ADR-015 +(accepted 2026-10-22) and `ArchitectureBlueprint.md` §2.2. + +Reviewed against the tree on 2026-10-22. `secrets_engine.plan.build_plan` +already renders a plan without an OpenBao client. `secrets_engine.cli` is the +process. `SCOPE.md` records that service delivery is absent, and that a +service API or daemon is not implemented. `service-jwt` can log in and cannot +yet carry engine actions. Accepted security-layer-model v0.8 still governs +PEP behavior. Proposed v0.9 §3.3 carries the same engine wording and does not +yet govern. + +This workplan does not add a release-unit declaration, does not deploy a +workload, and does not make this engine the only client of OpenBao or a +decider of who may use it. + +## Lock the library boundary + +```task +id: SECRETS-WP-0016-T01 +status: todo +priority: high +``` + +`build_plan` and the catalog validation it depends on stay free of the OpenBao +client. Add a test that calls the shipped `build_plan` for a fixture lane and +asserts no OpenBao client is constructed. If a plan path constructs one, move +that call to the process that applies the plan. + +Done when that test passes against `src/secrets_engine/plan.py` and the apply +path still performs the OpenBao calls. + +## Inject one stage credential at process start + +```task +id: SECRETS-WP-0016-T02 +status: todo +priority: high +depends_on: [SECRETS-WP-0016-T01] +``` + +The CLI process binds to exactly one stage, `build`, `test`, or `production`. +That stage's OpenBao credential is supplied to the process at start and is not +printed, returned, or written to Git, State Hub, logs, or the workplan. A +second stage credential present in the same process is a startup failure. + +Done when a test starts the shipped CLI entry against fixture configuration, +shows one stage bound, shows the credential value absent from stdout and +stderr, and shows startup failure when two stage credentials are present. + +## Manifest the same library as a single-stage service + +```task +id: SECRETS-WP-0016-T03 +status: todo +priority: medium +depends_on: [SECRETS-WP-0016-T02] +``` + +Add a service manifestation of the same library and the same one-stage +injection. It is a kept-running process, not a second implementation and not a +Deployment. It does not accept another stage's credential. + +Done when an in-process test starts that manifestation for one stage and a +lifecycle call goes through the shipped library functions used by the CLI. + +## Consume use, do not decide it + +```task +id: SECRETS-WP-0016-T04 +status: todo +priority: medium +depends_on: [SECRETS-WP-0016-T03] +``` + +Permission to start or call an instance is an access-engine decision. This +repository documents the claim it will consume and does not invent a local +allow-list. A caller-supplied flag or config key must not authorize apply or +the service. Protected side effects keep the existing rule: a decision record +or the published unreachable-engine stance. v0.8 PEP obligations stay. + +Done when a test shows a local allow flag does not authorize a protected call, +and the claim shape is written in `docs/` without storing a credential. + +## Record the manifestations in SCOPE + +```task +id: SECRETS-WP-0016-T05 +status: todo +priority: low +depends_on: [SECRETS-WP-0016-T03, SECRETS-WP-0016-T04] +``` + +Update `SCOPE.md` so it describes the library, the one-stage CLI, and the +service manifestation that the code then contains. State that other engines +may use OpenBao for other capabilities. Remove the claim that service delivery +is absent only for the manifestation this workplan adds. Leave exec-time +delivery as the default for a one-task caller. + +Done when `SCOPE.md` matches the shipped commands and tests, and does not +describe a cluster Deployment this workplan did not add.