docs: seed SECRETS-WP-0004 (warden-sign lane); complete SCOPE.md sections
- SECRETS-WP-0004: scoped warden-sign OpenBao token lane for ops-warden, to unblock FLEX-WP-0007 T4 joint smoke. First auth-capability (non-KV) lane and first lane touching production OpenBao (bao.coulomb.social). - SCOPE.md: add the standard sections flagged by the repo scope review (Relevant When, Not Relevant When, How It Fits, Terminology, Related / Overlapping, Provided Capabilities with fenced capability blocks); refresh Current State to reflect the delivered MVP. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
9a65875bae
commit
bcdfc78087
2 changed files with 273 additions and 4 deletions
113
SCOPE.md
113
SCOPE.md
|
|
@ -39,9 +39,114 @@ roles, safe delivery modes, and non-secret evidence.
|
|||
- 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.
|
||||
|
||||
## 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.
|
||||
- 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
|
||||
|
||||
The repo is in bootstrap. Seed intent, PRD, boundary documentation, and an MVP
|
||||
workplan are present. The first worker should complete State Hub bootstrap,
|
||||
validate the generated repo identity files, then begin the whynot-design npm
|
||||
publish token pilot through the `SECRETS-WP-0002` workplan.
|
||||
MVP delivered. The Python CLI (`src/secrets_engine/`) proves the
|
||||
`whynot-design-npm-publish` 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
|
||||
(44 tests; `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`.
|
||||
|
||||
Bootstrap workplans `SECRETS-WP-0001` (State Hub integration) and
|
||||
`SECRETS-WP-0002` (MVP) are finished. Open: `SECRETS-WP-0003` (real pilot
|
||||
close-out) and `SECRETS-WP-0004` (scoped `warden-sign` token lane for
|
||||
ops-warden / FLEX-WP-0007 T4), both proposed.
|
||||
|
||||
## 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 one secret's OpenBao location, consumers, delivery, approval |
|
||||
| **stage** | `build` / `test` / `prod` — separate OpenBao privilege contexts |
|
||||
| **stage role** | `secrets-engine-{build,test,prod}` OpenBao role, confined to its prefix |
|
||||
| **delivery mode** | how a value leaves OpenBao: `exec-env`, `npm-config`, `read-check`, `wrapped` |
|
||||
| **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
|
||||
|
||||
```capability
|
||||
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]
|
||||
```
|
||||
|
||||
```capability
|
||||
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]
|
||||
```
|
||||
|
||||
```capability
|
||||
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]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue