net-kingdom/docs/secrets-engine-security-infrastructure-boundary.md

NetKingdom Security Infrastructure Boundary

Purpose

This document defines how secrets-engine participates in the NetKingdom security infrastructure. It is the first place agents and operators should read when they need to understand responsibility boundaries, system interactions, secret organization, and stage-specific policy concepts.

secrets-engine is the workflow and interaction layer for approved secret work. OpenBao remains the custody, policy, lease, and audit backend.

Core Responsibility

secrets-engine turns an approved secret request into a safe, reviewable, auditable sequence of actions:

1. Resolve the catalog entry and stage.
2. Verify the decision or approval state.
3. Render a plan for OpenBao metadata, value provisioning, verification, and delivery.
4. Apply only allowed OpenBao changes through the minimal stage role.
5. Provision or confirm the value without exposing it in coordination systems.
6. Deliver the secret to a workload or command without printing it.
7. Record non-secret evidence for audit, troubleshooting, and readiness.
8. Rotate, revoke, deactivate, or mark compromised secrets through the same catalog and decision model.

Boundary Map

System	Owns	secrets-engine interaction	Must not do
OpenBao	Secret custody, ACL policy enforcement, leases, response wrapping, audit logs	Use OpenBao through constrained build, test, and production roles; write policies, auth roles, metadata, and values only through validated plans	Treat OpenBao UI/CLI as the routine operator interface; bypass decision checks; store raw values outside OpenBao
flex-auth	Authorization decisions and policy reasoning	Ask whether an actor may establish, access, rotate, or deactivate a cataloged secret for a purpose	Store or deliver secret values; become the vault
user-engine / key-cape	Human and service identity, user lifecycle, claims, groups, MFA/OIDC context	Consume stable identity claims and service identities for OpenBao auth bindings and decision checks	Own secret lifecycle policy; mint provider tokens
ops-warden	SSH certificate issuance and credential routing front door	Route non-SSH credential requests to secrets-engine; show catalog readiness and safe next commands	Vend API keys, provider tokens, database passwords, or OpenBao tokens
ops-bridge	Remote execution, tunnels, transport, and operator connectivity	Consume secrets through secrets-engine exec or scoped delivery when a remote operation needs credentials	Persist secrets in tunnel configs, logs, or reusable shell state
info-tech-canon	Canonical terminology, governance patterns, stage taxonomy, naming conventions, documentation profiles	Reuse canon terms for stage, catalog, approval, delivery, evidence, rotation, and deactivation concepts	Act as runtime authority or store secret values
State Hub	Non-secret workstreams, decisions, progress, review comments, and evidence pointers	Read decisions and write non-secret progress/evidence	Store raw secret values, tokens, wrapped tokens, passwords, or private keys
llm-connect / agents	Reasoning and task execution	Receive non-secret plans and use exec-time delivery only when needed	Place secrets in prompts, chat, model context, or logs

System-of-Systems Position

secrets-engine sits between request/decision systems and OpenBao operations. It is not the source of identity, authorization, or custody. It is the place where those systems are composed into an operator- and agent-usable workflow.

request / ops-warden route
        |
        v
State Hub decision <---- flex-auth authorization
        |
        v
secrets-engine catalog + plan + policy guard
        |
        v
OpenBao role/policy/value operations
        |
        v
verification + evidence + safe delivery
        |
        v
workload, CI job, operator command, or ops-bridge task

Core Concepts

Secret Lane

A secret lane is the governed path for one secret use case. It joins a catalog id, owner, stage, OpenBao location, fields, consumer binding, approval model, delivery modes, verification checks, and revocation behavior.

Example catalog id:

whynot-design-npm-publish

Catalog Entry

A catalog entry is non-secret metadata. It is the primary object agents and operators should reference. It must never contain raw secret values.

Required concepts:

• catalog id;
• stage;
• owner domain, repo, workload, or service;
• OpenBao backend mount/path and fields;
• allowed consumers and identity claims;
• allowed delivery modes;
• approval/decision requirement;
• verification requirements;
• rotation, revocation, and compromised/deactivated behavior;
• evidence expectations.

Stage

A stage is a security boundary. The initial stages are:

• build;
• test;
• production.

Short aliases such as prod may exist in CLI flags, but catalog and policy documents should normalize to the canonical names above.

Decision

A decision is the non-secret approval state that allows a secret lane to be created, changed, delivered, rotated, or deactivated. Decisions live outside the vault, usually in State Hub and/or flex-auth. A production action must fail closed without an approved decision, except for explicit break-glass flows.

Delivery Mode

A delivery mode defines how a secret reaches a consumer without becoming visible in normal coordination surfaces.

Initial allowed modes:

• exec-time environment injection;
• exec-time temporary config file;
• response-wrapped handoff;
• local bootstrap file import for setup only;
• non-production generated test value.

Denied modes:

• chat;
• prompts or model context;
• Git;
• State Hub message body;
• command-line argument containing the raw value;
• normal logs;
• long-lived untracked local files.

Evidence

Evidence is non-secret proof that an action happened and what its result was. Evidence may include catalog id, actor, stage, decision id, OpenBao path, field names, lease accessor, timestamps, audit request ids, and pass/fail status. It must not include raw secret values.

Stage Policy Model

Build

Purpose:

• local development;
• disposable integration experiments;
• generated or synthetic values;
• quick iteration before stronger policy is justified.

Allowed direction:

• manage build-stage metadata and values under build prefixes;
• generate fake or low-impact values;
• use lightweight decisions or repo-owner approval;
• support fast exec flows for development commands.

Restrictions:

• no production mounts or paths;
• no broad OpenBao sys/auth administration;
• no reuse of build values in test or production;
• short TTLs by default.

Test

Purpose:

• staging and integration verification;
• proving delivery, rotation, and negative checks;
• rehearsing production policy with lower impact.

Allowed direction:

• manage approved test-stage metadata and values;
• run positive and negative access verification;
• use provider tokens or service credentials with test-only scope;
• record evidence before a similar production lane is considered ready.

Restrictions:

• no production values;
• no production auth roles;
• stricter identity binding than build;
• explicit denial checks for unrelated consumers.

Production

Purpose:

• real workload secrets;
• real provider tokens;
• auditable delivery to production-capable consumers.

Allowed direction:

• apply approved production metadata such as ACL policies and auth roles;
• provision values only through approved custody modes;
• deliver values through exec-time or workload-scoped mechanisms;
• record evidence and readiness state.

Restrictions:

• no action without approved decision, except explicit break-glass;
• no broad platform-root, platform-admin, or wildcard admin semantics;
• no raw value printing;
• no default raw reads by agents;
• rotation, revocation, and compromised/deactivated states must be expressible.

OpenBao Role Layers

The initial OpenBao-facing roles are:

Role	Stage	Main capability
secrets-engine-build	build	Manage approved build-stage metadata and values under build prefixes.
secrets-engine-test	test	Manage approved test-stage metadata and values and run verification.
secrets-engine-prod	production	Apply approved production metadata and perform constrained delivery/provisioning actions.

A temporary bootstrap credential may be used to create these roles and policies. Bootstrap credentials must be local-only, outside repositories, mode 0600, revocable, and tracked as temporary setup material.

Secret Organization

The catalog is the stable interface. Physical OpenBao paths may evolve, but catalog entries must keep enough structure to enforce stage and ownership.

Recommended logical dimensions:

stage / tenant-or-org / workload-or-service / bundle / field

Recommended OpenBao path shape when a shared mount is used:

<mount>/workloads/<stage>/<tenant-or-org>/<workload-or-service>/<bundle>

If a mount is already stage-specific, the stage may be represented by the mount instead:

<stage-mount>/workloads/<tenant-or-org>/<workload-or-service>/<bundle>

The catalog must make the resolved stage explicit in either case. Existing legacy paths should be represented by catalog metadata before being normalized.

Policy Families

The engine should distinguish policy families rather than treating every OpenBao policy as a free-form string:

Family	Purpose
catalog-read	Read non-secret catalog metadata and readiness.
stage-applier	Apply metadata inside one stage boundary.
value-provisioner	Write or import secret values under approved custody.
delivery-runner	Fetch and inject a value only into a child process or workload-specific config.
verifier	Run positive/negative checks without printing values.
revoker	Revoke leases, deactivate lanes, or mark compromised state.
auditor	Produce non-secret reports and evidence summaries.

Production policy families should be split so that metadata apply, value provisioning, and value delivery do not automatically imply each other.

Main Interaction Flows

Establish a Secret Lane

1. Actor requests a cataloged secret lane.
2. flex-auth and/or State Hub records an approval decision.
3. secrets-engine renders the OpenBao policy/auth/value plan.
4. Operator or agent reviews the plan.
5. secrets-engine applies allowed metadata through the minimal stage role.
6. Secret value is provisioned by approved custody mode.
7. Positive and negative verification run.
8. Catalog readiness becomes resolvable for ops-warden and consumers.

Use a Secret

1. Consumer asks ops-warden or secrets-engine for a catalog id.
2. secrets-engine checks catalog, stage, readiness, identity, and decision state.
3. secrets-engine fetches the value through OpenBao using a delivery role.
4. The value is injected only into the child process or temporary config.
5. Temporary material is removed.
6. Non-secret evidence is recorded.

Target shape:

secrets-engine exec --catalog whynot-design-npm-publish -- npm publish

Rotate a Secret

1. Rotation request is linked to the existing catalog entry.
2. New value is provisioned under approved custody.
3. Consumers are switched or verified.
4. Old value is revoked or deactivated.
5. Evidence records old/new version identifiers without raw values.

Mark Compromised or Deactivated

1. Actor marks the lane compromised or requests deactivation.
2. secrets-engine blocks delivery immediately where possible.
3. OpenBao leases/tokens are revoked.
4. Related policies or auth roles are disabled if required.
5. ops-warden readiness becomes not resolvable.
6. Evidence and follow-up tasks are recorded.

Explicit Non-responsibilities

secrets-engine must not:

• replace OpenBao;
• make identity or authorization decisions by itself;
• issue SSH certificates;
• establish network tunnels;
• persist raw secret values outside OpenBao as normal operation;
• put secrets into prompts, chat, State Hub, Git, or logs;
• make production changes without an approved decision;
• normalize insecure bootstrap shortcuts into permanent operations.

First Pilot

The first pilot lane is:

catalog id: whynot-design-npm-publish
field: NPM_AUTH_TOKEN
consumer: whynot-design npm publish workflow

The pilot should prove:

• a catalog entry can describe the lane without a raw value;
• an approved decision can drive OpenBao policy and auth role creation;
• provisioning can happen without secret disclosure;
• positive and negative verification can be recorded;
• secrets-engine exec can deliver the token to npm publish safely;
• ops-warden can route to secrets-engine and report readiness.

Canonicalization Tasks

These concepts should be aligned with info-tech-canon as the implementation hardens:

• stage names and aliases;
• catalog entry schema terms;
• decision states and evidence vocabulary;
• delivery mode names;
• compromised, deactivated, rotated, ready, and resolvable states;
• standard OpenBao path and policy naming patterns.