docs: update scope for auth-capability lanes

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
+custody, auth-capability handoff, delivery, and lifecycle work across build,
-OpenBao as the initial enforcement backend.
+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
+connects cataloged secret lanes, scoped auth-capability lanes, approval
-roles, safe delivery modes, and non-secret evidence.
+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
+(`scripts/demo-e2e.sh`, `scripts/npm-publish-demo.sh`). The netkingdom
-netkingdom maturity-gated publication-scope policy is in place but dormant
+maturity-gated publication-scope policy is in place but dormant (netkingdom at
-(netkingdom at `maturity-build`), so lanes clamp to repo-scope / `NPM_AUTH_TOKEN`.
+`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
+`SECRETS-WP-0002` (MVP) are finished. Active: `SECRETS-WP-0003` (real pilot
-close-out) and `SECRETS-WP-0004` (scoped `warden-sign` token lane for
+close-out) and `SECRETS-WP-0004` (scoped `warden-sign` auth-capability lane for
-ops-warden / FLEX-WP-0007 T4), both proposed.
+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]
+```