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.

```text
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:

```text
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:

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

Recommended OpenBao path shape when a shared mount is used:

```text
<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:

```text
<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:

```bash
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:

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