generated from coulomb/repo-seed
Repo hygiene: fill stack-and-commands, normalize workplan statuses
- Fill .claude/rules/stack-and-commands.md (was an empty TODO template) - Normalize workplan frontmatter statuses to canonical vocabulary (completed/done -> finished) per ADR-001 - Repair glued frontmatter delimiter in NK-WP-0001 (superseded_by line) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
363
docs/secrets-engine-security-infrastructure-boundary.md
Normal file
363
docs/secrets-engine-security-infrastructure-boundary.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user