docs: align scope with implemented capabilities
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a0217e-8c4c-7383-be6b-f50a6e485306
This commit is contained in:
parent
3ca0e63bed
commit
7799716c73
4 changed files with 454 additions and 159 deletions
355
SCOPE.md
355
SCOPE.md
|
|
@ -1,207 +1,244 @@
|
|||
# SCOPE
|
||||
|
||||
> Lightweight boundary for agents and contributors.
|
||||
> Implemented capability boundary for agents and contributors. Aspirational
|
||||
> direction belongs in `INTENT.md`; current work and operational gates belong in
|
||||
> `workplans/`.
|
||||
|
||||
## One-liner
|
||||
|
||||
secrets-engine is the workflow and automation interface for approved secret
|
||||
custody, auth-capability handoff, delivery, and lifecycle work across build,
|
||||
test, and production, with OpenBao as the enforcement backend.
|
||||
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.
|
||||
|
||||
## Core Idea
|
||||
It is an OpenBao workflow client, not a vault, authorization service, identity
|
||||
provider, credential broker, or general secrets API.
|
||||
|
||||
OpenBao is the vault. secrets-engine is the day-to-day interaction layer that
|
||||
connects cataloged secret lanes, scoped auth-capability lanes, approval
|
||||
decisions, stage-specific OpenBao roles, safe delivery modes, and non-secret
|
||||
evidence.
|
||||
## Implemented Capabilities
|
||||
|
||||
## In Scope
|
||||
### Catalog and validation
|
||||
|
||||
- Non-secret catalog of secret lanes, grants, consumers, stages, and delivery
|
||||
modes.
|
||||
- Non-secret catalog of scoped OpenBao auth capabilities where the protected
|
||||
material is a narrow policy/AppRole grant rather than a KV value.
|
||||
- Decision-aware planning and apply flows for OpenBao policies, auth roles, and
|
||||
metadata.
|
||||
- Build, test, and production privilege separation.
|
||||
- Safe provisioning, verification, rotation, revocation, and deactivation
|
||||
workflows.
|
||||
- Exec-time delivery to operators, agents, CI jobs, workloads, and ops-bridge
|
||||
tasks without printing raw values.
|
||||
- Future service/API mode that exposes the same approved planning, delivery,
|
||||
handoff, lifecycle, and evidence semantics to ops-warden, agents, CI,
|
||||
workloads, and UI surfaces without exposing OpenBao internals.
|
||||
- ops-warden routing contract for non-SSH credentials and scoped OpenBao
|
||||
capabilities.
|
||||
- State Hub non-secret evidence and progress integration.
|
||||
- Canonicalization of terms with info-tech-canon.
|
||||
- Loads YAML catalog entries for `kv` and `auth-capability` lanes.
|
||||
- Models `build`, `test`, and `prod` stages, exact mounts/paths/fields,
|
||||
consumers, approvals, delivery modes, verification, lifecycle ownership,
|
||||
workload-delivery metadata, and `standard`/`high` risk.
|
||||
- Distinguishes engine-managed and existing KV mounts, and engine-managed,
|
||||
existing, or absent native delivery auth.
|
||||
- Rejects malformed entries, inline secret-looking values, wildcard paths,
|
||||
unsupported modes, bootstrap-only approval for high-risk lanes, and high-risk
|
||||
entries without rotation/deactivation owners.
|
||||
- Records existing ESO/Kubernetes/OIDC workload delivery as metadata only; it
|
||||
does not operate those delivery systems.
|
||||
|
||||
## Out of Scope
|
||||
### Decision-gated planning and OpenBao metadata apply
|
||||
|
||||
- Replacing OpenBao as custody, policy, lease, or audit backend.
|
||||
- Replacing flex-auth authorization decisions.
|
||||
- Replacing user-engine/key-cape identity and claim lifecycle.
|
||||
- Issuing SSH certificates, which remains ops-warden responsibility.
|
||||
- Owning tunnels or remote transport, which remains ops-bridge responsibility.
|
||||
- Storing raw secret values in this repo, State Hub, chat, prompts, or logs.
|
||||
- Broad platform-root or platform-admin automation as a steady-state model.
|
||||
- Handing broad OpenBao tokens to another subsystem when a narrower
|
||||
cataloged capability can satisfy the request.
|
||||
- Resolves a catalog lane by catalog id or `approval.decision_ref`.
|
||||
- Resolves an approval from State Hub by id, with tracked local YAML mirrors as
|
||||
a pilot/offline fallback.
|
||||
- Fails privileged live commands closed when a required decision is missing,
|
||||
unapproved, or superseded. Plans and `apply --dry-run` remain non-mutating.
|
||||
- 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.
|
||||
- Rejects stage mismatches, wildcard paths, broad-admin names, forbidden
|
||||
`sys/`, token, identity, root, or sudo semantics, and auth-capability paths
|
||||
outside an exact allowlist.
|
||||
|
||||
## Relevant When
|
||||
### KV provisioning
|
||||
|
||||
- An approved decision needs to become a narrow OpenBao policy/auth-role apply
|
||||
without platform-root hand-typing.
|
||||
- A workload or operator command needs a secret delivered **into the command**
|
||||
without printing or exporting it (e.g. `npm publish`).
|
||||
- A non-SSH credential need (API key, provider token, npm token, DB password,
|
||||
scoped OpenBao token) is routed here by ops-warden.
|
||||
- ops-warden needs an approved, narrow OpenBao capability such as
|
||||
`ssh/sign/<role>` access for its own SSH certificate flow, without receiving a
|
||||
broad platform-root token.
|
||||
- Build/test/production need different privilege, ceremony, and delivery rules
|
||||
for the same kind of secret.
|
||||
- A reviewer needs non-secret evidence of who applied/provisioned/verified what.
|
||||
- Imports one declared field from a mode-0600 file outside Git worktrees.
|
||||
- Generates random values only for non-production lanes.
|
||||
- Keeps values out of CLI output and evidence records.
|
||||
|
||||
## Not Relevant When
|
||||
This is a bootstrap/pilot primitive, not a safe general updater for existing
|
||||
multi-field production paths. The current adapter invokes `bao kv put` with one
|
||||
field and can replace sibling fields at that KV path; it also places the value
|
||||
in the local `bao` subprocess argument vector. Do not use it for the admitted
|
||||
shared multi-field lanes until merge-safe, non-argv provisioning is implemented.
|
||||
|
||||
- You need an **SSH certificate** (→ ops-warden `warden sign`).
|
||||
- You need an **authorization decision** (→ flex-auth).
|
||||
- You need **identity / OIDC / MFA / claim lifecycle** (→ user-engine / key-cape).
|
||||
- You need a **tunnel** or remote transport (→ ops-bridge).
|
||||
- You want OpenBao itself replaced as the custody/lease/audit backend (it is not).
|
||||
- You want a raw secret value moved through Git, State Hub, chat, prompts, or logs
|
||||
(never — delivery is exec-time or out-of-band only).
|
||||
### Verification
|
||||
|
||||
## Current State
|
||||
- KV positive verification logs in through the lane AppRole and reports whether
|
||||
one declared field is present, without printing the field value.
|
||||
- KV negative verification checks that a fixed invalid token cannot read the
|
||||
path.
|
||||
- Auth-capability verification checks the AppRole token's capabilities on exact
|
||||
allowlisted and denial-probe paths.
|
||||
|
||||
MVP delivered. The Python CLI (`src/secrets_engine/`) supports the core lane
|
||||
flow: catalog → decision check → guarded OpenBao policy/AppRole apply →
|
||||
provision or handoff → positive/negative verification → safe delivery →
|
||||
non-secret route pointers → revoke.
|
||||
These are bounded policy/presence probes. They do not yet prove denial for a
|
||||
real unrelated workload identity, validate every field by default, exercise a
|
||||
provider operation, or produce OpenBao audit-request correlation.
|
||||
|
||||
The repo supports both stored-value KV lanes and non-KV auth-capability lanes.
|
||||
KV lanes cover secrets such as npm publish tokens; auth-capability lanes cover
|
||||
narrow OpenBao policy/AppRole grants such as `ssh/sign/<role>` access for
|
||||
ops-warden. The maturity-gated publication-scope policy is in place and
|
||||
fail-safe: until the broader domain reaches the required maturity, publish lanes
|
||||
clamp to the safest repo-scoped token shape.
|
||||
### Exec-time delivery
|
||||
|
||||
Current operational status lives in workplans, `.custodian-brief.md`, and
|
||||
`history/`; this file should stay stable enough for agents and contributors to
|
||||
use as the boundary reference.
|
||||
- `exec-env` fetches one declared field through the lane AppRole and injects it
|
||||
into a child process environment.
|
||||
- `npm-config` creates a temporary mode-0600 npm config containing an environment
|
||||
reference rather than the token, injects the value only into the child, and
|
||||
deletes the config afterward.
|
||||
- Child stdout and stderr are combined and streamed through token-pattern and
|
||||
exact-value redaction.
|
||||
- Undeclared fields and undeclared/unsupported exec modes are rejected before
|
||||
value fetch.
|
||||
|
||||
## Hardening Trajectory
|
||||
The OpenBao KV response is parsed in the parent process, so every field stored
|
||||
at the path crosses that process boundary even though only the selected field is
|
||||
injected. Scoped AppRole tokens rely on configured TTL/use limits; exec and
|
||||
verification do not explicitly revoke them after use.
|
||||
|
||||
The steady-state target is to keep routine secure work low-friction while
|
||||
removing bootstrap shortcuts. The hardening path is tracked in
|
||||
`docs/hardening-backlog.md` and includes:
|
||||
### Auth-capability handoff
|
||||
|
||||
- replacing bootstrap token files with OIDC, service auth, or another scoped
|
||||
OpenBao auth path for steady-state stage roles;
|
||||
- using response wrapping, short leases, and single-use handoff paths when
|
||||
exec-time delivery does not fit;
|
||||
- requiring dual control for production value provisioning beyond approved
|
||||
pilots;
|
||||
- making rotation, revocation, and deactivation routine evidenced operations;
|
||||
- exposing stabilized CLI semantics through service/API mode only after the
|
||||
underlying decision, delivery, lifecycle, and evidence contracts are proven.
|
||||
- Models narrow non-KV AppRole grants such as exact `ssh/sign/<role>` update
|
||||
capability.
|
||||
- Mints `role_id`/`secret_id` material only after approval and writes it to
|
||||
distinct mode-0600 files outside Git worktrees without printing the
|
||||
`secret_id`.
|
||||
|
||||
## How It Fits
|
||||
The cataloged standalone `warden-sign` AppRole is currently parked by governance
|
||||
and must not be applied as a break-glass or recovery path. OpenBao being sealed
|
||||
cannot be recovered through that AppRole.
|
||||
|
||||
secrets-engine is the **interaction layer** in the NetKingdom security stack. It
|
||||
sits between approval/identity systems and the OpenBao backend:
|
||||
### Routing and evidence
|
||||
|
||||
- **OpenBao / railiance-platform** — enforces custody, policy, lease, audit.
|
||||
secrets-engine drives it through least-privilege stage roles and validated
|
||||
paths, never as root.
|
||||
- **flex-auth / State Hub decisions** — authorize. secrets-engine requires and
|
||||
verifies a decision before privileged action and writes non-secret evidence
|
||||
back.
|
||||
- **user-engine / key-cape** — own identity and claims that bind consumers.
|
||||
- **ops-warden** — routes non-SSH credential needs here (conduit-not-broker) and
|
||||
issues SSH certs itself; secrets-engine orchestrates OpenBao-backed issuance,
|
||||
delivery, handoff, verification, and revocation while OpenBao remains the
|
||||
custody backend.
|
||||
- **ops-bridge** — may consume scoped delivery for remote execution but stores no
|
||||
secret material.
|
||||
- **info-tech-canon** — source of canonical terminology and stage/policy concepts.
|
||||
- `route` returns a non-secret pointer containing lane ownership, decision
|
||||
status, metadata/value-presence booleans, readiness, and a safe next command.
|
||||
- Records scrubbed local JSONL evidence and posts a minimal State Hub progress
|
||||
event on a best-effort basis.
|
||||
- Keeps OpenBao audit logs as the backend source of truth.
|
||||
|
||||
Canonical cross-system boundary: `net-kingdom/docs/secrets-engine-security-infrastructure-boundary.md`.
|
||||
Route readiness checks only the first declared KV field, and State Hub evidence
|
||||
delivery is not durable or transactional. Treat route output as operational
|
||||
guidance, not complete attestation for multi-field or high-risk lanes.
|
||||
|
||||
## Terminology
|
||||
### Revocation currently available
|
||||
|
||||
| Term | Meaning |
|
||||
| --- | --- |
|
||||
| **lane / catalog id** | a non-secret entry describing a KV secret or auth capability, its OpenBao location, consumers, delivery, and approval |
|
||||
| **auth-capability lane** | a catalog lane whose protected material is a narrow OpenBao policy/AppRole capability, not a stored KV value |
|
||||
| **stage** | `build` / `test` / `prod` — separate OpenBao privilege contexts |
|
||||
| **stage role** | `secrets-engine-{build,test,prod}` OpenBao role, confined to its prefix |
|
||||
| **delivery mode** | how material leaves OpenBao: `exec-env`, `npm-config`, `read-check`, `wrapped`, `approle-login` |
|
||||
| **org / repo** | Gitea organisation (`coulomb`) / repository (`whynot-design`) — explicit, not the overloaded "project" |
|
||||
| **npm scope** | the `@`-prefixed npm name (`@whynot`) — distinct from org and repo |
|
||||
| **maturity** | `maturity-build/test/prod` package tag; feeds the publication-scope policy |
|
||||
| **bootstrap token** | temporary mode-0600 OpenBao token used during setup, revocable, outside repos |
|
||||
| **service/API mode** | future stable API surface over proven CLI semantics for approved plans, deliveries, handoffs, lifecycle actions, and evidence |
|
||||
- For `auth-capability` lanes, live `revoke` deletes the AppRole and policy.
|
||||
- For KV lanes, live `revoke` deletes all KV metadata/versions at the path.
|
||||
|
||||
## Related / Overlapping
|
||||
KV revoke is destructive decommissioning, not soft deactivation: it currently
|
||||
leaves the KV lane's consumer AppRole and policy in place. There is no general
|
||||
lease/accessor revoke, rotation command, compromised state, or reversible lane
|
||||
state machine.
|
||||
|
||||
- **ops-warden** — front door / SSH cert issuer; routes non-SSH needs here.
|
||||
- **OpenBao (railiance-platform)** — the custody/policy/lease/audit backend.
|
||||
- **flex-auth** — authorization decisions secrets-engine depends on.
|
||||
- **user-engine / key-cape** — identity and claim lifecycle for consumers.
|
||||
- **ops-bridge** — remote transport; may consume scoped delivery.
|
||||
- **net-kingdom** — owns the cross-system security-infrastructure boundary doc.
|
||||
- **info-tech-canon** — canonical terminology source.
|
||||
## CLI Surface
|
||||
|
||||
```text
|
||||
secrets-engine catalog list|show
|
||||
secrets-engine decision inspect
|
||||
secrets-engine plan
|
||||
secrets-engine apply [--dry-run]
|
||||
secrets-engine provision
|
||||
secrets-engine verify
|
||||
secrets-engine handoff
|
||||
secrets-engine exec
|
||||
secrets-engine policy publication
|
||||
secrets-engine route
|
||||
secrets-engine revoke [--dry-run]
|
||||
```
|
||||
|
||||
The implemented exec adapters are `exec-env` and `npm-config`. `read-check` is
|
||||
verification, `approle-login` is auth-capability handoff metadata, and
|
||||
`exec-file`/`wrapped` are reserved schema names without executable adapters.
|
||||
|
||||
## Proven Operationally
|
||||
|
||||
- The whynot-design npm pilot completed a real publish through native
|
||||
`secrets-engine exec` without placing the token in the parent shell.
|
||||
- Throwaway OpenBao integration tests exercise plan, apply, provisioning,
|
||||
positive/negative verification, exec delivery, routing, revocation, and
|
||||
idempotent metadata apply.
|
||||
- Five existing high-risk `platform` mount lanes have reviewed catalog metadata
|
||||
and guarded dry-run plans. Their native AppRoles are not live: workplan
|
||||
`SECRETS-WP-0006` waits on per-lane approval, production authority, live
|
||||
positive/negative verification, and routing cutover.
|
||||
|
||||
## Not Implemented
|
||||
|
||||
- A service API, daemon, UI, queue, scheduler, or remote multi-user service.
|
||||
- OpenBao OIDC/service-auth login for steady-state secrets-engine operation.
|
||||
- Native `exec-file` or response-wrapped delivery.
|
||||
- Merge-safe multi-field KV updates or provider-side rotation.
|
||||
- First-class rotate, compromise, suspend, reactivate, lease-status, or audit
|
||||
report commands.
|
||||
- Dual-control enforcement beyond accepting the catalog label.
|
||||
- Direct flex-auth evaluation, claim validation, or identity authentication.
|
||||
- Runtime tenancy isolation; `org`, `repo`, consumers, and stages are catalog
|
||||
metadata plus local path/policy guards, not a tenant control plane.
|
||||
- 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.
|
||||
|
||||
## 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.
|
||||
- **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-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.
|
||||
|
||||
Canonical boundary:
|
||||
`net-kingdom/docs/secrets-engine-security-infrastructure-boundary.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 mutate an existing shared mount or replace workload delivery by
|
||||
implication.
|
||||
- Never use current single-field provisioning on a shared multi-field path.
|
||||
- Never call KV `revoke` unless destructive deletion of all path versions is the
|
||||
explicitly approved intent.
|
||||
- Keep bootstrap and handoff material outside repositories with mode 0600 and
|
||||
explicit expiry/revocation handling.
|
||||
|
||||
## Where Current Work Lives
|
||||
|
||||
- `workplans/` is the source of truth for open work and operational gates.
|
||||
- `docs/hardening-backlog.md` tracks exit from bootstrap mode.
|
||||
- `history/` contains dated capability and intent assessments.
|
||||
- `INTENT.md` remains the stable aspirational direction.
|
||||
|
||||
## Provided Capabilities
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: Decision-aware OpenBao policy/role apply
|
||||
description: Turns an approved State Hub decision into a narrow, guarded OpenBao apply —
|
||||
catalog lane to dry-run plan to idempotent ACL policy + AppRole write — through
|
||||
least-privilege build/test/prod stage roles. Refuses unapproved, superseded, wildcard,
|
||||
out-of-stage, or broad-admin plans before any backend call. Writes non-secret evidence.
|
||||
keywords: [secrets, openbao, vault, policy, approle, catalog, decision, stage, least-privilege, netkingdom]
|
||||
title: Guarded OpenBao lane planning and metadata apply
|
||||
description: Validates cataloged KV and auth-capability lanes, renders exact policy/AppRole plans,
|
||||
and applies approved metadata while rejecting missing decisions, stage mismatches, wildcards,
|
||||
broad-admin names, and forbidden capability paths. Existing mounts are check-only.
|
||||
keywords: [secrets, openbao, policy, approle, catalog, decision, stage, least-privilege]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: Exec-time secret delivery
|
||||
description: Delivers a secret into a child process only — never printing, exporting, or
|
||||
persisting the value. npm-config injects a temporary mode-0600 .npmrc pointing at the
|
||||
configured registry; exec-env injects a scoped env var. Temp config is cleaned up on
|
||||
success, failure, and interruption; child output is redacted as a backstop.
|
||||
keywords: [secrets, delivery, exec, npm, publish, token, injection, redaction, npmrc, openbao]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: governance
|
||||
title: Maturity-gated publication-scope policy
|
||||
description: Binds npm publication scope to package maturity (build to gitea-wide, test to
|
||||
org-wide, prod to repo-scoped) and gates the graduated table behind the netkingdom domain
|
||||
reaching production grade. While dormant, every lane clamps to the safest repo-scope —
|
||||
fail-safe, never fail-open. The injected token env-var name signals the effective blast radius.
|
||||
keywords: [policy, maturity, publication-scope, governance, least-privilege, npm, gitea, netkingdom]
|
||||
title: AppRole-scoped exec delivery
|
||||
description: Fetches one declared KV field through a lane AppRole and injects it into a child
|
||||
process using exec-env or a temporary npm config, with output redaction and cleanup. This is
|
||||
CLI-local delivery; exec-file, wrapping, service delivery, and explicit token revocation are absent.
|
||||
keywords: [secrets, delivery, exec, npm, injection, redaction, openbao]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: Scoped OpenBao auth-capability handoff
|
||||
description: Models non-KV grants such as warden-sign as guarded policy/AppRole lanes.
|
||||
Plans refuse wildcards, sys/auth/token/identity paths, root-like capabilities, and
|
||||
non-update SSH signing paths; handoff emits only file paths and non-secret metadata
|
||||
while keeping role-id and secret-id material outside Git and normal logs.
|
||||
keywords: [secrets, openbao, approle, auth-capability, warden-sign, ssh-signing, handoff, least-privilege]
|
||||
description: Generates an exact-path policy/AppRole plan and writes role-id/secret-id material to
|
||||
strict out-of-repo files after approval. Operational use remains subject to lane-specific governance.
|
||||
keywords: [openbao, approle, auth-capability, handoff, least-privilege]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: Lifecycle and non-secret evidence
|
||||
description: Tracks secret and capability lifecycle actions as explicit, reversible
|
||||
workflow steps: provision, verify, deliver, rotate, revoke, deactivate, and audit.
|
||||
OpenBao keeps custody and audit; secrets-engine records only non-secret decisions,
|
||||
paths, policy names, actors, timestamps, and verification outcomes.
|
||||
keywords: [secrets, lifecycle, rotation, revocation, deactivation, audit, evidence, openbao, state-hub]
|
||||
type: governance
|
||||
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. It is not a durable audit store or complete multi-field attestation.
|
||||
keywords: [routing, evidence, state-hub, audit, secrets]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue