coulomb/secrets-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
secrets-engine/SCOPE.md

9.4 KiB
Raw Blame History

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

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]

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]