Declare Engine/Lifecycle against security layer model v0.7
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:
parent
b1f0f7b666
commit
1945e16685
14 changed files with 1177 additions and 108 deletions
103
SCOPE.md
103
SCOPE.md
|
|
@ -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]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue