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.

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.

Verification

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

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.

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. Scoped AppRole tokens rely on configured TTL/use limits; exec and verification do not explicitly revoke them after use.

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

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.

Revocation currently available

• For auth-capability lanes, live revoke deletes the AppRole and policy.
• For KV lanes, live revoke deletes all KV metadata/versions at the path.

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.

CLI Surface

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

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]

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

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]

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]