secrets-engine/SCOPE.md

# SCOPE

> Lightweight boundary for agents and contributors.

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

## Core Idea

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.

## In Scope

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

## Out of Scope

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

## Relevant When

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

## Not Relevant When

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

## Current State

MVP delivered. The Python CLI (`src/secrets_engine/`) proves the
`whynot-design-npm-publish` KV lane end to end — catalog → decision check →
policy/AppRole apply → provision → positive/negative verify → exec-time npm
delivery → ops-warden routing pointer → revoke — verified live against OpenBao
(`scripts/demo-e2e.sh`, `scripts/npm-publish-demo.sh`). The netkingdom
maturity-gated publication-scope policy is in place but dormant (netkingdom at
`maturity-build`), so lanes clamp to repo-scope / `NPM_AUTH_TOKEN`.

The current source also supports non-KV auth-capability lanes. `SECRETS-WP-0004`
adds the `warden-sign` catalog lane, exact-path policy guards for
`ssh/sign/{agt-role,adm-role,atm-role}`, AppRole TTL/use constraints, positive
and negative capability probes, and a handoff command that writes `role_id` and
`secret_id` only to mode-0600 files outside Git worktrees. Live apply and
cross-repo smoke remain pending OpenBao/operator gates.

`SECRETS-WP-0003` has been optimized for the real whynot-design pilot closeout:
the catalog points at the canonical approved State Hub decision, the old
slug-named offline decision mirror has been retired, and a non-secret preflight
plus closeout runbook document the remaining real publish steps. The suite is
currently green at 59 passed, 2 skipped.

Bootstrap workplans `SECRETS-WP-0001` (State Hub integration) and
`SECRETS-WP-0002` (MVP) are finished. Active: `SECRETS-WP-0003` (real pilot
close-out) and `SECRETS-WP-0004` (scoped `warden-sign` auth-capability lane for
ops-warden / FLEX-WP-0007 T4).

## How It Fits

secrets-engine is the **interaction layer** in the NetKingdom security stack. It
sits between approval/identity systems and the OpenBao backend:

- **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 mints and custodies the tokens.
- **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.

Canonical cross-system boundary: `net-kingdom/docs/secrets-engine-security-infrastructure-boundary.md`.

## Terminology

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

## Related / Overlapping

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

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

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

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