Add credential approval workflow plan

docs/workload-kv-access-lanes.md

@@ -0,0 +1,154 @@
+# Workload KV Access Lanes
+
+This document records concrete OpenBao workload KV paths that external access
+front doors can reference without storing or vending secret values themselves.
+The first lane is for ops-warden `warden access --fetch` / `--exec`.
+
+## Safety Rules
+
+- Do not put secret values in Git, State Hub, chat, prompts, workplans, or logs.
+- Store only non-secret pointers here: path, field name, policy name, auth role,
+  flex-auth reference, and verification status.
+- ops-warden may proxy a read as the caller, but it must not hold the returned
+  value beyond the caller-requested fetch/exec process.
+- Live writes require an approved OpenBao/operator path and attended handling
+  of the secret value.
+
+## whynot-design npm Publish Token
+
+Ops-warden request:
+`551031d1-335e-4db8-9535-820fea52d0a3`
+
+| Item | Value |
+| --- | --- |
+| ops-warden catalog id | `whynot-design-npm-token` |
+| KV mount | `platform` |
+| OpenBao CLI path | `platform/workloads/whynot-design/whynot-design/npm-publish` |
+| Secret field | `NPM_AUTH_TOKEN` |
+| Read policy | `workload-kv-read-whynot-design-npm-publish` |
+| Policy file | `openbao/policies/workload-kv-read-whynot-design-npm-publish.hcl` |
+| OIDC auth mount | `netkingdom` |
+| OIDC role | `whynot-design-workload-kv-read` |
+| Kubernetes auth role | `whynot-design-workload-kv-read` if an in-cluster service account consumes this lane |
+| flex-auth ref | `secret.read:whynot-design` if tenant policy requires pre-approval |
+
+Expected caller login shape:
+
+```bash
+bao login -method=oidc -path=netkingdom role=whynot-design-workload-kv-read
+```
+
+Expected fetch shape:
+
+```bash
+bao kv get -field=NPM_AUTH_TOKEN platform/workloads/whynot-design/whynot-design/npm-publish
+```
+
+The fetch command returns the secret value to the authenticated caller. Run it
+only in an attended shell or through a process that consumes the value without
+logging it.
+
+## OpenBao Policy
+
+The source policy grants only:
+
+```text
+read platform/data/workloads/whynot-design/whynot-design/npm-publish
+read platform/metadata/workloads/whynot-design/whynot-design/npm-publish
+```
+
+It does not grant write, delete, patch, sudo, auth, sibling workload, or parent
+list capabilities.
+
+Dry-run the policy apply path:
+
+```bash
+make openbao-workload-kv-lanes-dry-run
+```
+
+Apply the policy with an approved platform-admin/operator token:
+
+```bash
+OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token \
+  make openbao-configure-workload-kv-lanes
+```
+
+If the OpenBao pod has an approved token-helper session, use:
+
+```bash
+make openbao-configure-workload-kv-lanes OPENBAO_WORKLOAD_KV_ARGS=--use-token-helper
+```
+
+Do not paste the token into shell history or logs. The helper reads a token
+from `OPENBAO_TOKEN_FILE` or an interactive hidden prompt unless
+`--use-token-helper` is set, and passes it to OpenBao through stdin.
+
+## Auth Role
+
+The intended OpenBao OIDC role is:
+
+```text
+auth/netkingdom/role/whynot-design-workload-kv-read
+```
+
+The role must attach only:
+
+```text
+workload-kv-read-whynot-design-npm-publish
+```
+
+Before applying the role, confirm the KeyCape/NetKingdom claim that identifies
+the whynot-design caller. The role must bind to that claim; do not create an
+unbounded OIDC role that grants this policy to every OIDC user.
+
+If the consumer is an in-cluster service account instead of an OIDC caller, use
+Kubernetes auth with the same role name and bind only the approved namespace
+and service account.
+
+## Secret Provisioning
+
+An approved operator must create or confirm the secret with:
+
+```text
+path:  platform/workloads/whynot-design/whynot-design/npm-publish
+field: NPM_AUTH_TOKEN
+```
+
+The value must be entered directly through OpenBao/operator custody. Record only
+non-secret evidence: actor, timestamp, path, field name, policy name, and
+verification result.
+
+## Verification
+
+Positive verification:
+
+1. Authenticate as the whynot-design caller using the approved OIDC or
+   Kubernetes auth role.
+2. Fetch the field in an attended session or through `warden access --fetch`.
+3. Record only that the fetch succeeded; do not record the value.
+
+Negative verification:
+
+1. Authenticate as a non-whynot identity.
+2. Confirm the same field read is denied.
+3. Record the non-secret OpenBao audit request ids or timestamps for the
+   allowed and denied attempts.
+
+## ops-warden Handoff
+
+Send ops-warden only these pointers:
+
+```text
+catalog id: whynot-design-npm-token
+mount: platform
+path: platform/workloads/whynot-design/whynot-design/npm-publish
+field: NPM_AUTH_TOKEN
+oidc login: bao login -method=oidc -path=netkingdom role=whynot-design-workload-kv-read
+policy: workload-kv-read-whynot-design-npm-publish
+policy file: openbao/policies/workload-kv-read-whynot-design-npm-publish.hcl
+flex-auth ref: secret.read:whynot-design, if tenant policy requires it
+runbook: docs/workload-kv-access-lanes.md
+```
+
+Until live provisioning and verification are complete, ops-warden should keep
+the catalog entry in `draft` or equivalent non-active state.