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, delivery, and lifecycle work across build, test, and production, with
OpenBao as the initial enforcement backend.

## Core Idea

OpenBao is the vault. secrets-engine is the day-to-day interaction layer that
connects cataloged secret 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.
- 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.
- 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.

## 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.
- 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` 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
(44 tests; `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`.

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

## 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 one secret's OpenBao location, consumers, delivery, approval | 
| **stage** | `build` / `test` / `prod` — separate OpenBao privilege contexts |
| **stage role** | `secrets-engine-{build,test,prod}` OpenBao role, confined to its prefix |
| **delivery mode** | how a value leaves OpenBao: `exec-env`, `npm-config`, `read-check`, `wrapped` |
| **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]
```