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

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]

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]

10 KiB Raw Blame History