From ad469c39ca53cb0cac2d2fb51f8ab3514856d383 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 29 Jun 2026 17:06:20 +0200 Subject: [PATCH] docs: update scope for auth-capability lanes --- SCOPE.md | 61 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 14 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index d40803c..3fd0852 100644 --- a/SCOPE.md +++ b/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/` 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] +```