Declare Engine/Lifecycle against security layer model v0.7
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 1s

Replace the gate-house review note with this repository's own declaration:
INTENT.md frontmatter, layer.yaml, and a published PEP stance map. SCOPE.md
and agent boundary docs now match that layer. The review under history/
identifies the implementation remainder; SECRETS-WP-0008 is the follow-on
workplan. SECRETS-IN-0001 is closed.

The layer is not contested. Catalog "custody" is a finding: OpenBao owns
custody, this engine owns the lifecycle API over it. SSH-CA signing is
accepted as a proposed engine API and declined as a Staff lane.

Assistant: grok
Assistant-Session: 01a04cea-cb33-7c63-bad7-c1b0f9f0076b
This commit is contained in:
tegwick 2026-08-29 11:57:47 +02:00
parent b1f0f7b666
commit 1945e16685
14 changed files with 1177 additions and 108 deletions

103
SCOPE.md
View file

@ -3,15 +3,20 @@
> Implemented capability boundary for agents and contributors. Aspirational
> direction belongs in `INTENT.md`; current work and operational gates belong in
> `workplans/`.
>
> **Layer declaration (accepted model v0.7):** Engine / Lifecycle. Machine-readable
> form: `layer.yaml`. PEP stance: `pep-stance.yaml`. This file states what the
> implementation currently does inside that layer; it does not restate doctrine.
## One-liner
secrets-engine is a decision-gated Python CLI that validates non-secret secret
lane metadata and orchestrates narrowly scoped OpenBao policy, AppRole,
provisioning, verification, delivery, routing, handoff, and revocation actions.
secrets-engine is the Lifecycle engine for cataloged credential work: a
decision-gated Python CLI that validates non-secret lane metadata and
orchestrates narrowly scoped OpenBao policy, AppRole, provisioning,
verification, delivery, routing, handoff, and revocation actions.
It is an OpenBao workflow client, not a vault, authorization service, identity
provider, credential broker, or general secrets API.
It is a deterministic API over OpenBao, not a vault, not a policy decision
point, not an identity provider, and not a general secrets API.
## Implemented Capabilities
@ -33,15 +38,19 @@ provider, credential broker, or general secrets API.
- Resolves a catalog lane by catalog id or `approval.decision_ref`.
- Resolves legacy lane decisions from State Hub by id, with tracked local YAML
mirrors retained only for non-production and explicit throwaway demos.
- Fails every production live command closed while State Hub lacks the durable
action-authorization endpoint. A local mirror can unlock a prod-labeled lane
only when an explicit unsafe-demo switch, disabled Hub URL, and loopback
OpenBao target are all present. Plans and `apply --dry-run` remain usable.
mirrors retained only for non-production and explicit throwaway demos. This is
not an access-engine decision record.
- Fails every production live command closed while there is no durable
access-engine / ActionAuthorization record. That fail-closed row is the
published unreachable-engine stance for `prod` in `pep-stance.yaml`. A local
mirror can unlock a prod-labeled lane only when an explicit unsafe-demo
switch, disabled Hub URL, and loopback OpenBao target are all present. Plans
and `apply --dry-run` remain usable.
- Builds and validates the flex-auth `ActionAuthorization` profile, including
exact lane/stage/action/target/actor/purpose matching, bounded validity,
State Hub authority, request digest and decision binding, accepted policy
package/version, and an independently required distinct-approver threshold.
Validation is consume-only; this process does not evaluate policy.
- Renders guarded OpenBao plans for exact consumer ACL policies and AppRoles.
- Applies policy and AppRole metadata idempotently. Existing mounts render a
non-mutating check and are never created by apply.
@ -116,7 +125,8 @@ cannot be recovered through that AppRole.
event on a best-effort basis. Posts carry stable idempotency/source headers.
Each requested State Hub delivery receives an append-only local `delivered`,
`queued`, `failed`, or `skipped-no-topic` companion record; edge-relay queued
receipts retain only the non-secret outbox id.
receipts retain only the non-secret outbox id. This trail is attributive:
completeness is not claimed, and it is not `audit-core`.
- Every live privileged CLI handler records an attempt before lane-approval
resolution and a terminal success, verification failure, rejection,
interruption, or typed backend/input failure. Failure evidence contains the
@ -211,9 +221,11 @@ verification, `approle-login` is auth-capability handoff metadata, and
- First-class rotate, compromise, reactivate, lease-status, or audit report
commands; lifecycle operations currently execute plans without persistent
lane state.
- Resolution of a durable State Hub action authorization and wiring its
validated approval threshold to each production handler.
- Direct flex-auth evaluation, JWT signature verification, or identity
- Resolution of a durable access-engine decision record / State Hub
ActionAuthorization and wiring its validated approval threshold to each
production handler. The consumer validator exists; the serving endpoint does
not, so live production remains fail-closed.
- Direct access-engine evaluation, JWT signature verification, or identity
authentication. KeyCape claims receive only a consumer preflight; OpenBao is
responsible for cryptographic JWT validation.
- Runtime tenancy isolation; `org`, `repo`, consumers, and stages are catalog
@ -221,32 +233,55 @@ verification, `approle-login` is auth-capability handoff metadata, and
- Management or health verification of ESO, Kubernetes Secrets, deployments,
provider accounts, SSH issuance, tunnels, or remote transport.
- Any backend other than the local `bao`/`vault` CLI speaking to OpenBao.
- An SSH-CA signing engine API. ops-warden still signs through its declared
OpenBao gap; this repository has accepted that surface as proposed only.
- A secret-use evidence engine API for kings-guard. `route` and `audit` are
operator summaries over local JSONL, not an observation surface.
- Emission to `audit-core`. Evidence today is local JSONL plus best-effort
State Hub progress notes, classified attributive, completeness not claimed.
- Named stance-application records (stage, failure mode, decision id present
only where rendered). Fail-closed production currently surfaces as a
`DecisionError` on the privileged-evidence path.
- Security-zone membership as a request claim. PEP scope is catalog stage.
## System Boundary
- **OpenBao / railiance-platform** owns custody, policy enforcement, leases, and
audit. secrets-engine invokes it through supplied credentials.
- **flex-auth / State Hub decisions** own authorization. secrets-engine only
resolves and enforces recorded decision status.
- **OpenBao / railiance-platform** (Tooling) owns custody, policy enforcement,
leases, and backend audit. secrets-engine is the Lifecycle API over it.
- **access-engine (`flex-auth`)** owns authorization decisions. secrets-engine
consumes a decision record or applies its published unreachable-engine stance;
it does not evaluate policy.
- **approval-engine** owns the durable approval object. secrets-engine may
consume an approval as an input claim and must not store or mutate one.
- **gate-house** owns security doctrine. Doctrine reaches this engine only as it
already reached the decision, never as a side channel.
- **audit-core** owns evidence custody and integrity. Local JSONL and State Hub
notes are not that archive.
- **user-engine / key-cape** own identity, OIDC, MFA, and claims.
- **ops-warden** issues SSH certificates and routes non-SSH credential needs; it
does not vend their values.
- **ops-warden** issues SSH certificates (Staff PEP) and routes non-SSH
credential needs here; it does not vend their values. The SSH-CA write
surface is a proposed engine API, not a transferred lane.
- **ops-bridge** owns tunnels and remote execution transport and may consume a
scoped delivery path.
- **workload/platform repositories** own ESO/Kubernetes delivery, provider
rotation, and application health.
- **info-tech-canon / net-kingdom** own canonical terminology and the
cross-system security boundary.
cross-system security boundary. **gate-house** owns the layer model.
Canonical boundary:
`net-kingdom/docs/secrets-engine-security-infrastructure-boundary.md`.
Layer model: `net-kingdom/canon/standards/security-layer-model_v0.7.md`.
Working companion: `net-kingdom/SECURITY-COMPANION.md`.
## Security Rules
- Never place raw secret values in Git, State Hub, chat, prompts, workplans,
normal logs, or evidence.
- Never treat catalog admission, a dry-run, or an old workload CCR as approval
for a new production auth surface.
- Never render or cache an authorization decision. Catalog admission, a dry-run,
an old workload CCR, or a local fixture is not an access-engine allow.
- Never treat silence from `access-engine` as permission. Production live
actions fail closed; any unreachable-engine residue must be the published
stance, recorded, never implicit.
- Never mutate an existing shared mount or replace workload delivery by
implication.
- Never add KV destruction back to ordinary `revoke`; irreversible custody
@ -254,7 +289,22 @@ Canonical boundary:
approved action. The live path remains disabled until that approval contract
exists.
- Keep bootstrap and handoff material outside repositories with mode 0600 and
explicit expiry/revocation handling.
explicit expiry/revocation handling. Bootstrap is not an implicit fallback
from service identity.
- Never claim that local evidence or a missing record proves occurrence or
non-occurrence. Completeness is not claimed.
## Layer-model obligations (current vs intended)
| Obligation | Current | Intended |
| --- | --- | --- |
| Layer declaration | `INTENT.md` frontmatter + `layer.yaml` | Keep in this repository's own voice |
| One decision point | Consumer validator for ActionAuthorization; production live fail-closed | Consume an access-engine decision record before every protected side effect |
| PEP stance | `pep-stance.yaml`; prod fail-closed, build/test fail-open relative to access-engine | Published map equals shipped behaviour; stance application recorded by name |
| Evidence bound | Attributive local JSONL + best-effort State Hub | Load-bearing vs attributive classified; load-bearing to `audit-core` with cadence |
| SSH-CA surface | Proposed; not shipped | Engine API for ops-warden's Staff PEP; lane stewardship stays with ops-warden |
| Secret-use evidence | `route` / `audit` over local JSONL | Engine surface of lease/revocation/mount/rotation metadata |
| Agent credential | Bootstrap token file still accepted; KeyCape scaffold unwired | Per-task, time-bounded service identity; no standing engine credential |
## Where Current Work Lives
@ -262,6 +312,7 @@ Canonical boundary:
- `docs/hardening-backlog.md` tracks exit from bootstrap mode.
- `history/` contains dated capability and intent assessments.
- `INTENT.md` remains the stable aspirational direction.
- `layer.yaml` and `pep-stance.yaml` are the layer-model declaration surface.
## Provided Capabilities
@ -298,7 +349,7 @@ title: Non-secret routing and evidence pointers
description: Reports decision/readiness metadata and records scrubbed local and best-effort State Hub
evidence without returning secret values. Append-only delivery receipts expose State Hub failures,
and an allowlisted audit command summarizes lane operations and cleanup. KV verification can attest a
supplied real unrelated identity, but the engine does not own identity selection. This is not a durable
remote audit store.
supplied real unrelated identity, but the engine does not own identity selection. This is attributive
local evidence, not audit-core and not a secret-use observation API.
keywords: [routing, evidence, state-hub, audit, secrets]
```