secrets-engine/docs/publication-scope-policy.md

netkingdom Publication-Scope Policy

Owner: netkingdom (security-infrastructure domain) · Enforced by: secrets-engine Data: policies/netkingdom-publication-scope.yaml · Code: src/secrets_engine/publication_policy.py

Idea

The scope of a publish token depends on the maturity of what is being published. A repo's maturity translates into the maturity tag of the package it ships, and each tag is restricted by the publication scope its token carries:

Package maturity tag	Publication scope (when active)	Token env var	Why
maturity-build	gitea-wide	NPM_AUTH_GITEA_TOKEN	low-stakes build artifacts may use a broad, shared token
maturity-test	org-wide	NPM_AUTH_COULOMB_TOKEN	integration artifacts scoped to the org
maturity-prod	repo-scoped	NPM_AUTH_TOKEN (default) / NPM_AUTH_WHYNOTDESIGN (explicit)	high-stakes production publishes require tight, repo-scoped rights

Scope narrows as stakes rise — the production token is the most tightly bound.

The netkingdom maturity gate (why it's dormant today)

The graduated table above only takes effect once netkingdom itself reaches production grade (netkingdom_maturity: maturity-prod). netkingdom is at maturity-build today, so the policy is dormant and every lane clamps to the safest scope (repo), injected as NPM_AUTH_TOKEN.

This is fail-safe, not fail-open: until the policy machinery is itself production-grade, we never hand out the broad (gitea/org-wide) tokens the graduated table would otherwise allow.

$ secrets-engine policy publication whynot-design-npm-publish
netkingdom maturity: maturity-build  (production_grade=False)
  effective publication scope: repo  (clamped from graduated table — fail-safe)
  inject token as env var:     NPM_AUTH_TOKEN

When netkingdom graduates, flip netkingdom_maturity to maturity-prod in the policy file; the same lanes then resolve build→gitea, test→org, prod→repo automatically. Nothing else changes.

Token env-var naming convention

NPM_AUTH[_<QUALIFIER>]_TOKEN, where the qualifier signals the blast radius:

Effective scope	Env var	Qualifier source
repo (default)	NPM_AUTH_TOKEN	— (bare default)
repo (explicit)	NPM_AUTH_WHYNOTDESIGN	repo whynot-design
npm-scope / "project"	NPM_AUTH_WHYNOT_TOKEN	scope @whynot — defined, not used by the policy
org	NPM_AUTH_COULOMB_TOKEN	org coulomb
gitea-wide	NPM_AUTH_GITEA_TOKEN	—

The name is a signal, not the boundary. The real boundary is how the Gitea token is minted (a dedicated bot account per grant is usually needed — Gitea package tokens are user-scoped, not natively scope/org-scoped) plus the OpenBao lane path + consumer policy. The catalog records the intended grant via delivery_config.npm.maturity; a reviewer sees the intended blast radius even when the backend can only enforce a coarser one.

Lane configuration

delivery_config:
  npm:
    registry: "https://forgejo.coulomb.social/api/packages/coulomb/npm/"
    scope: "@whynot"
    package: "@whynot/design"
    maturity: maturity-build          # feeds the policy
    # token_env: NPM_AUTH_WHYNOTDESIGN # optional explicit override

secrets-engine exec injects the resolved token under the resolved env-var name into the npm child only; the parent shell never holds it.