secrets-engine/SCOPE.md

# SCOPE

> 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 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.

It is an OpenBao workflow client, not a vault, authorization service, identity
provider, credential broker, or general secrets API.

## Implemented Capabilities

### Catalog and validation

- 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.

### Decision-gated planning and OpenBao metadata apply

- 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.

### KV provisioning

- 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.
- Uses a CAS-aware create/patch primitive. Secret data is passed through a
  mode-0600 temporary JSON input reference that is removed in a `finally` path,
  never as a raw subprocess argument. Existing-path updates preserve unmentioned
  sibling fields and stale-version writes fail closed.

### Verification

- KV positive verification logs in through the lane AppRole and reports field
  presence without printing values. With no `--field`, it checks every declared
  field; an explicit `--field` narrows the check.
- 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.

These are bounded policy/presence probes. They do not yet prove denial for a
real unrelated workload identity, exercise a provider operation, or produce
OpenBao audit-request correlation.

### Exec-time delivery

- `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.

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. Exec and verification use scoped AppRole sessions that explicitly
self-revoke in a `finally` path. Non-secret evidence contains only an accessor
fingerprint and establishment/revocation outcome; TTL/use limits remain cleanup
backstops.

### Auth-capability handoff

- 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`.

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.

### Routing and evidence

- `route` returns a non-secret pointer containing lane ownership, decision
  status, metadata/value-presence booleans, missing declared field names,
  readiness, and a safe next command. Every declared field must be present.
- 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.

State Hub evidence delivery is not durable or transactional, and route does not
replace authorization or unrelated-identity denial evidence. Treat route output
as operational guidance, not complete attestation for high-risk lanes.

### Revocation currently available

- For engine-managed native auth, live `revoke` deletes the AppRole and policy.
- For KV lanes, ordinary revoke explicitly preserves all KV metadata/versions.
- Externally managed delivery auth and workload delivery are reported as
  preserved and are not mutated.
- `lifecycle suspend` removes only the managed AppRole and preserves its policy
  for reviewed re-apply.
- `lifecycle deactivate` removes managed native AppRole/policy objects while
  preserving KV custody.
- `lifecycle destroy --dry-run` renders managed-auth removal plus irreversible
  KV metadata deletion. Live destroy is currently disabled even with exact
  catalog-id confirmation; it will remain closed until the canonical
  exact-action approval contract in `SECRETS-WP-0007-T04` is enforced.

These operations do not manage external workload delivery. There is currently
no general lease/accessor operator command, rotation command, compromised state,
or persistent/reversible lane state machine.

## 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]
secrets-engine lifecycle suspend|deactivate|destroy
```

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.
- Provider-side rotation or coordinated multi-consumer rollout.
- First-class rotate, compromise, reactivate, lease-status, or audit report
  commands; lifecycle operations currently execute plans without persistent
  lane state.
- 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 add KV destruction back to ordinary `revoke`; irreversible custody
  destruction requires `lifecycle destroy`, exact confirmation, and a distinct
  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.

## 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: 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: 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, explicit scoped-token
  self-revocation, and non-secret cleanup evidence. This is CLI-local delivery; exec-file, wrapping,
  and service delivery are absent.
keywords: [secrets, delivery, exec, npm, injection, redaction, openbao]
```

```capability
type: security
title: Scoped OpenBao auth-capability handoff
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: 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. Readiness covers every declared field, but this is not a
  durable audit store or a real-unrelated-identity denial attestation.
keywords: [routing, evidence, state-hub, audit, secrets]
```