From 16090f0fcaf3d134c6257e62a9f63ffe07278a33 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 29 Jun 2026 12:17:03 +0200 Subject: [PATCH] docs(wp-0003): seed pilot close-out workplan SECRETS-WP-0003 scopes the real pilot close-out: canonical State Hub decision, dedicated Gitea bot account for an enforced repo-scope, real token provisioning, a real @whynot/design publish through secrets-engine exec, and the ops-warden routing handoff. Does not change the dormant netkingdom publication-scope gate. Co-Authored-By: Claude Opus 4.8 --- workplans/SECRETS-WP-0003-pilot-closeout.md | 166 ++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 workplans/SECRETS-WP-0003-pilot-closeout.md diff --git a/workplans/SECRETS-WP-0003-pilot-closeout.md b/workplans/SECRETS-WP-0003-pilot-closeout.md new file mode 100644 index 0000000..bdab967 --- /dev/null +++ b/workplans/SECRETS-WP-0003-pilot-closeout.md @@ -0,0 +1,166 @@ +--- +id: SECRETS-WP-0003 +type: workplan +title: "Close out the whynot-design npm publish pilot (real)" +domain: infotech +repo: secrets-engine +status: proposed +owner: codex +topic_slug: custodian +created: "2026-06-29" +updated: "2026-06-29" +--- + +# SECRETS-WP-0003 - Close out the whynot-design npm publish pilot (real) + +## Goal + +Turn the proven MVP chain into a real, no-longer-faked production pilot: replace +the local decision fixture with a canonical State Hub decision, provision a real +Gitea npm token behind a dedicated bot account so the repo-scope is *enforced* +(not just labelled), and perform a real `npm publish` of `@whynot/design` through +`secrets-engine exec`. + +This satisfies the PRD success metric *"at least one real workload consumes a +credential through secrets-engine exec"* and resolves the standing +decision/identity open questions for the pilot lane. + +## Context + +`SECRETS-WP-0002` delivered the working engine and proved the whole chain against +a throwaway OpenBao dev server with a fake token and a `--dry-run` publish. Three +things are still stand-ins: + +- the lane's approval runs on `.decisions/whynot-design-npm-publish.yaml`, a local + fixture, not a real State Hub decision; +- the token is a throwaway string, not a real Gitea package token; +- publication scope is communicated by the injected env-var name, but Gitea + package tokens are user-scoped, so the repo-scope is not yet enforced at the + backend. + +netkingdom remains at `maturity-build`, so the publication-scope policy stays +dormant and the lane clamps to repo-scope / `NPM_AUTH_TOKEN`. This workplan does +not change that gate. + +## Design Constraints + +- No raw token value in Git, State Hub, chat, prompts, workplans, or normal logs. +- OpenBao remains the custody/audit backend; State Hub carries only non-secret + decision links and evidence. +- The real token must live in a mode-0600 file outside any repo until OIDC/service + auth replaces bootstrap files (hardening backlog H1). +- Every minted token gets a revocation task in `docs/hardening-backlog.md` (H0). + +## Tasks + +## T01 - Record the canonical State Hub decision for the lane + +```task +id: SECRETS-WP-0003-T01 +status: todo +priority: high +``` + +Record a real State Hub decision approving establishment of the whynot-design npm +publish lane, then point `catalog/whynot-design-npm-publish.yaml` +`approval.decision_ref` at that decision's UUID. Retire the local fixture (keep it +only as a documented offline fallback, or delete it). + +Acceptance: + +- `secrets-engine decision inspect ` resolves with `source: hub` and shows + the decision approved. +- The lane still passes `require_approved` via the hub, not the fixture. +- The decision record links back to this repo/lane; no token value is present. + +## T02 - Stand up a dedicated Gitea bot account for the repo-scoped grant + +```task +id: SECRETS-WP-0003-T02 +status: todo +priority: high +``` + +Create a dedicated Gitea bot account (e.g. `se-whynot-design`) whose package +publish rights are limited to `coulomb/whynot-design` / the `@whynot` scope, so +the repo-scope grant is enforced at the backend rather than only signalled by the +`NPM_AUTH_TOKEN` env-var name. + +Acceptance: + +- The bot account can publish `@whynot/design` but cannot publish other orgs' + packages; the negative result is documented as Gitea-level evidence. +- The catalog `delivery_config.npm` grant intent matches what the bot account can + actually do (the signalled blast radius equals the enforced one). +- Account creation and its scope are recorded as non-secret evidence. + +## T03 - Provision the real npm token without disclosure + +```task +id: SECRETS-WP-0003-T03 +status: todo +priority: high +``` + +Operator mints a package token for the bot account and places it in a mode-0600 +file outside any repo. Provision it with +`secrets-engine provision whynot-design-npm-publish --stage prod --field npm_token +--from-file `. + +Acceptance: + +- Positive verification proves the approved consumer can read the lane; negative + verification proves an unrelated token is denied. +- No token value appears in Git, State Hub, logs, or chat. +- The bootstrap token file is added to `docs/hardening-backlog.md` H0 with an + explicit revocation task and TTL. + +## T04 - Real `npm publish` of @whynot/design through secrets-engine exec + +```task +id: SECRETS-WP-0003-T04 +status: todo +priority: high +``` + +Publish a real version of `@whynot/design` to the coulomb Gitea npm registry via +`secrets-engine exec --catalog whynot-design-npm-publish -- npm publish` (no +`--dry-run`). Coordinate the version bump with the whynot-design repo. + +Acceptance: + +- The published version appears in + `https://gitea.coulomb.social/api/packages/coulomb/npm/`. +- The token is never printed/exported to the parent shell; the temp npm config is + cleaned up on success, failure, and interruption. +- Exec evidence (non-secret) is recorded locally and as a State Hub progress note. + +## T05 - Hand the routing contract to ops-warden (cross-repo) + +```task +id: SECRETS-WP-0003-T05 +status: todo +priority: medium +``` + +Coordinate with the ops-warden repo so `warden route find` points npm publish +credential needs at secrets-engine, returning the `secrets-engine route` pointer +rather than a value. This is a handoff/coordination task; the route catalog entry +lives in ops-warden. + +Acceptance: + +- `warden route find "npm publish whynot-design"` returns the secrets-engine + catalog id and the safe next command. +- ops-warden does not request or store the raw token. +- The handoff is recorded (State Hub message or progress note) so ownership is + clear. + +## Exit Criteria + +- The whynot-design lane is approved by a real State Hub decision, not a fixture. +- The real token is provisioned and verified without disclosure, behind a bot + account whose enforced scope matches the catalog grant. +- A real `@whynot/design` version is published through `secrets-engine exec`. +- ops-warden routes npm credential needs to secrets-engine. +- Every minted bootstrap token has a revocation task in the hardening backlog.