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

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]

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]

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]