docs: update scope for auth-capability lanes
This commit is contained in:
parent
6382139890
commit
ad469c39ca
1 changed files with 47 additions and 14 deletions
61
SCOPE.md
61
SCOPE.md
|
|
@ -5,19 +5,22 @@
|
|||
## One-liner
|
||||
|
||||
secrets-engine is the workflow and automation interface for approved secret
|
||||
custody, delivery, and lifecycle work across build, test, and production, with
|
||||
OpenBao as the initial enforcement backend.
|
||||
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, approval decisions, stage-specific OpenBao
|
||||
roles, safe delivery modes, and non-secret evidence.
|
||||
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.
|
||||
|
|
@ -25,7 +28,8 @@ roles, safe delivery modes, and non-secret evidence.
|
|||
workflows.
|
||||
- Exec-time delivery to operators, agents, CI jobs, workloads, and ops-bridge
|
||||
tasks without printing raw values.
|
||||
- ops-warden routing contract for non-SSH credentials.
|
||||
- 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.
|
||||
|
||||
|
|
@ -38,6 +42,8 @@ roles, safe delivery modes, and non-secret evidence.
|
|||
- 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
|
||||
|
||||
|
|
@ -47,6 +53,9 @@ roles, safe delivery modes, and non-secret evidence.
|
|||
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.
|
||||
|
|
@ -64,17 +73,30 @@ roles, safe delivery modes, and non-secret evidence.
|
|||
## Current State
|
||||
|
||||
MVP delivered. The Python CLI (`src/secrets_engine/`) proves the
|
||||
`whynot-design-npm-publish` lane end to end — catalog → decision check →
|
||||
`whynot-design-npm-publish` KV 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`.
|
||||
(`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`.
|
||||
|
||||
The current source also supports non-KV auth-capability lanes. `SECRETS-WP-0004`
|
||||
adds the `warden-sign` catalog lane, exact-path policy guards for
|
||||
`ssh/sign/{agt-role,adm-role,atm-role}`, AppRole TTL/use constraints, positive
|
||||
and negative capability probes, and a handoff command that writes `role_id` and
|
||||
`secret_id` only to mode-0600 files outside Git worktrees. Live apply and
|
||||
cross-repo smoke remain pending OpenBao/operator gates.
|
||||
|
||||
`SECRETS-WP-0003` has been optimized for the real whynot-design pilot closeout:
|
||||
the catalog points at the canonical approved State Hub decision, the old
|
||||
slug-named offline decision mirror has been retired, and a non-secret preflight
|
||||
plus closeout runbook document the remaining real publish steps. The suite is
|
||||
currently green at 59 passed, 2 skipped.
|
||||
|
||||
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.
|
||||
`SECRETS-WP-0002` (MVP) are finished. Active: `SECRETS-WP-0003` (real pilot
|
||||
close-out) and `SECRETS-WP-0004` (scoped `warden-sign` auth-capability lane for
|
||||
ops-warden / FLEX-WP-0007 T4).
|
||||
|
||||
## How It Fits
|
||||
|
||||
|
|
@ -100,10 +122,11 @@ Canonical cross-system boundary: `net-kingdom/docs/secrets-engine-security-infra
|
|||
|
||||
| Term | Meaning |
|
||||
| --- | --- |
|
||||
| **lane / catalog id** | a non-secret entry describing one secret's OpenBao location, consumers, delivery, approval |
|
||||
| **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 a value leaves OpenBao: `exec-env`, `npm-config`, `read-check`, `wrapped` |
|
||||
| **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 |
|
||||
|
|
@ -150,3 +173,13 @@ description: Binds npm publication scope to package maturity (build to gitea-wid
|
|||
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]
|
||||
```
|
||||
|
||||
```capability
|
||||
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]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue