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

## 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/`) 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.

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.

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.

## Hardening Trajectory

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:

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

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

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 |
| **service/API mode** | future stable API surface over proven CLI semantics for approved plans, deliveries, handoffs, lifecycle actions, and evidence |

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

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