tegwick
5b48033bce
Token scope is now bound to package maturity, gated on netkingdom's own maturity: - maturity-build -> gitea-wide, maturity-test -> org-wide, maturity-prod -> repo-scoped (scope narrows as stakes rise; broad tokens only for low-stakes build artifacts) - the graduated table is DORMANT until netkingdom reaches production grade; until then every lane clamps to repo-scope, injected as NPM_AUTH_TOKEN (fail-safe) - token env-var name signals blast radius: NPM_AUTH_TOKEN (repo default), NPM_AUTH_COULOMB_TOKEN (org), NPM_AUTH_GITEA_TOKEN (gitea), NPM_AUTH_WHYNOT_TOKEN (npm scope, defined but unused), NPM_AUTH_WHYNOTDESIGN (explicit repo) netkingdom is at maturity-build today, so whynot-design resolves to repo-scope / NPM_AUTH_TOKEN. Flip netkingdom_maturity to maturity-prod to activate graduation. - policies/netkingdom-publication-scope.yaml: the policy data + gate - publication_policy.py: load + resolve (clamp/active, env naming, override) - exec delivery injects under the resolved env-var name (was fixed SE_NPM_TOKEN) - catalog lane carries delivery_config.npm.maturity - new CLI: `secrets-engine policy publication <lane>` - docs/publication-scope-policy.md; tests for clamp, graduation, naming, override Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
4.5 KiB
secrets-engine CLI
Terminology (Gitea is overloaded — be explicit)
| Term we use | Means | Example | Not to be confused with |
|---|---|---|---|
| org | the Gitea organisation | coulomb |
the npm scope |
| repo | the Gitea repository / product | whynot-design |
an org; a Gitea "project" board |
| npm scope | the @-prefix npm name |
@whynot |
the org or the repo |
| npm package | the published artifact | @whynot/design |
the repo it's built from |
| lane / catalog id | a secrets-engine secret lane | whynot-design-npm-publish |
— |
A catalog entry carries org + repo explicitly (never a bare "owner"), and the
npm registry/scope live in delivery_config.npm as data — the engine never
hardcodes a registry. The pilot publishes @whynot/design from the
coulomb/whynot-design repo to https://gitea.coulomb.social/api/packages/coulomb/npm/.
Install
uv venv && uv pip install -e ".[dev]"
source .venv/bin/activate
secrets-engine --version
Environment
| Var | Default | Purpose |
|---|---|---|
BAO_ADDR |
http://127.0.0.1:8200 |
OpenBao address |
BAO_TOKEN |
(unset) | OpenBao token (or use --bootstrap-token-file) |
SECRETS_ENGINE_HUB_URL |
http://127.0.0.1:8000 |
State Hub for decisions + evidence (empty to disable) |
SECRETS_ENGINE_CATALOG |
./catalog |
catalog directory |
SECRETS_ENGINE_EVIDENCE |
./.evidence |
local non-secret evidence log |
Commands
secrets-engine catalog list
secrets-engine catalog show <catalog-id>
secrets-engine decision inspect <decision-or-ccr-id>
secrets-engine plan <ref> --stage <build|test|prod>
secrets-engine apply <ref> --stage <stage> [--dry-run] [--bootstrap-token-file F]
secrets-engine provision <catalog-id> --stage <stage> --field NAME (--from-file F | --generate)
secrets-engine verify <catalog-id> --field NAME [--positive] [--negative]
secrets-engine exec --catalog <catalog-id> [--field NAME] [--mode auto|npm-config|exec-env] -- CMD...
secrets-engine policy publication <catalog-id>
secrets-engine route <catalog-id> [--json]
secrets-engine revoke <catalog-id> [--dry-run]
policy publication resolves a lane's effective publication scope and the env
var the token is injected under, per the netkingdom publication-scope policy
(see docs/publication-scope-policy.md).
<ref> is a catalog id or a decision/CCR ref (matched against
approval.decision_ref). plan and apply --dry-run never mutate OpenBao.
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 2 | catalog error (missing/invalid lane) |
| 3 | decision error (unapproved / superseded / missing) |
| 4 | policy guard error (out-of-stage / wildcard / broad admin) |
| 5 | backend error (OpenBao unreachable / failed) |
| 6 | provisioning error (bad file mode / inside repo / missing field) |
| 7 | verification failed |
| 8 | delivery error |
End-to-end demo
SECRETS_ENGINE_HUB_URL="" bash scripts/demo-e2e.sh
Boots a throwaway in-memory OpenBao dev server and runs the whole pilot chain: plan → apply → provision → verify(+/-) → exec (npm-config injection) → route → revoke. Nothing is persisted; the token is a throwaway local string.
npm publish wiring (dry-run)
bash scripts/npm-publish-demo.sh
Boots a throwaway OpenBao, applies + provisions the lane with a fake token, and
runs a real npm publish --dry-run through secrets-engine exec against a
scratch package. Proves npm in the child resolves its auth token from the temp
.npmrc secrets-engine injected, builds the tarball, and reaches the publish
step — while the parent shell never holds the token. For a real publish,
provision a real npm automation token the same way and drop --dry-run.
Pilot: whynot-design npm publish
# 1. inspect the approved decision
secrets-engine decision inspect whynot-design-npm-publish
# 2. preview the OpenBao changes (no mutation)
secrets-engine plan whynot-design-npm-publish --stage prod
# 3. apply policy + approle
secrets-engine apply whynot-design-npm-publish --stage prod
# 4. provision the token from a mode-0600 file OUTSIDE the repo
secrets-engine provision whynot-design-npm-publish --stage prod \
--field npm_token --from-file ~/.secrets-engine/whynot.token
# 5. prove access without printing the value
secrets-engine verify whynot-design-npm-publish --field npm_token --positive --negative
# 6. publish with the token injected into the child only
secrets-engine exec --catalog whynot-design-npm-publish -- npm publish