feat(policy): netkingdom maturity-gated publication-scope policy

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>
2026-06-28 13:14:46 +02:00 · 2026-06-28 13:14:46 +02:00 · 5b48033bce
commit 5b48033bce
parent f87f4e5e4d
11 changed files with 394 additions and 9 deletions
--- a/README.md
+++ b/README.md
@ -48,6 +48,7 @@ SECRETS_ENGINE_HUB_URL="" bash scripts/demo-e2e.sh
 ```

 - CLI reference: [docs/cli.md](docs/cli.md)
+- Publication-scope policy (maturity → token scope): [docs/publication-scope-policy.md](docs/publication-scope-policy.md)
 - Stage roles & bootstrap tokens: [docs/openbao-stage-roles.md](docs/openbao-stage-roles.md)
 - ops-warden routing contract: [docs/ops-warden-routing-contract.md](docs/ops-warden-routing-contract.md)
 - Hardening backlog (exit bootstrap mode): [docs/hardening-backlog.md](docs/hardening-backlog.md)
--- a/catalog/whynot-design-npm-publish.yaml
+++ b/catalog/whynot-design-npm-publish.yaml
@ -44,6 +44,13 @@ delivery_config:
    registry: "https://gitea.coulomb.social/api/packages/coulomb/npm/"
    scope: "@whynot"
    package: "@whynot/design"
+    # Package maturity tag. Under the netkingdom publication-scope policy this
+    # would map to a publication scope (build->gitea, test->org, prod->repo) once
+    # netkingdom is production grade. netkingdom is at maturity-build today, so the
+    # policy is dormant and this lane clamps to repo-scope, injected as
+    # NPM_AUTH_TOKEN. Set `token_env` to override the resolved name.
+    maturity: maturity-build
+    # token_env: NPM_AUTH_WHYNOTDESIGN   # explicit per-repo form (optional)

 # Privileged actions on this lane require an approved decision/CCR.
 approval:
--- a/docs/cli.md
+++ b/docs/cli.md
@ -44,10 +44,15 @@ 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](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.

--- a/docs/publication-scope-policy.md
+++ b/docs/publication-scope-policy.md
@ -0,0 +1,74 @@
+# 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
+
+```yaml
+delivery_config:
+  npm:
+    registry: "https://gitea.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.
--- a/policies/netkingdom-publication-scope.yaml
+++ b/policies/netkingdom-publication-scope.yaml
@ -0,0 +1,46 @@
+# Publication-scope policy — owned by the netkingdom security-infrastructure domain,
+# enforced by secrets-engine.
+#
+# Binds npm package *publication scope* to package *maturity*, and GATES the
+# graduated (relaxed) scoping behind netkingdom itself reaching production grade.
+#
+# Design intent (proves policy-bound secret handling):
+#   - A repo's maturity translates into the maturity tag of the package it ships
+#     (maturity-build / maturity-test / maturity-prod).
+#   - Each maturity tag is restricted by the publication scope its token carries.
+#   - Low-stakes build artifacts may publish with a BROAD shared token; high-stakes
+#     production publishes require a TIGHT, repo-scoped token. Scope narrows as
+#     stakes rise.
+#   - The graduated table is DORMANT until netkingdom is production grade. While
+#     dormant, every lane clamps to the safest scope (repo) — fail-safe, never
+#     fail-open.
+domain: netkingdom
+policy: publication-scope
+version: "0.1.0"
+
+# netkingdom's own maturity. `production_grade` is derived: it is true only when
+# this equals "maturity-prod". Today netkingdom is at maturity-build.
+netkingdom_maturity: maturity-build
+
+# When ACTIVE (production_grade == true): package maturity tag -> required scope.
+maturity_scope:
+  maturity-build: gitea     # gitea-wide publication rights
+  maturity-test:  org       # org-wide publication rights
+  maturity-prod:  repo      # repo-scoped publication rights
+
+# Safe scope applied while DORMANT, and the floor that cannot be exceeded before
+# netkingdom is production grade.
+dormant_scope: repo
+
+# Token env-var naming convention by effective scope. {ORG}/{SCOPE}/{REPO} are
+# upper-cased, de-hyphenated forms of the lane's org / npm-scope / repo.
+#   org  coulomb         -> COULOMB
+#   scope @whynot        -> WHYNOT     (npm scope = "project"; defined, NOT used by policy)
+#   repo whynot-design   -> WHYNOTDESIGN
+# The default repo-scope name is the bare NPM_AUTH_TOKEN; the explicit per-repo
+# form (NPM_AUTH_{REPO}) is available when a lane overrides it.
+token_env:
+  gitea: "NPM_AUTH_GITEA_TOKEN"
+  org:   "NPM_AUTH_{ORG}_TOKEN"
+  scope: "NPM_AUTH_{SCOPE}_TOKEN"
+  repo:  "NPM_AUTH_TOKEN"
--- a/scripts/npm-publish-demo.sh
+++ b/scripts/npm-publish-demo.sh
@ -83,8 +83,11 @@ chmod +x "$WORK/npm-wrapped.sh"
 secrets-engine exec --catalog whynot-design-npm-publish -- "$WORK/npm-wrapped.sh"

 echo
+echo "### policy binding: which scope/token-env did the lane resolve to?"
+secrets-engine policy publication whynot-design-npm-publish | sed 's/^/    /'
+
 echo "### confirm parent shell never held the token"
-echo "    SE_NPM_TOKEN in parent: '${SE_NPM_TOKEN:-<unset>}'"
+echo "    NPM_AUTH_TOKEN in parent: '${NPM_AUTH_TOKEN:-<unset>}'"
 echo "    NPM_CONFIG_USERCONFIG in parent: '${NPM_CONFIG_USERCONFIG:-<unset>}'"
 echo
 echo "### DONE — npm publish (dry-run) ran with the token injected by secrets-engine."
--- a/src/secrets_engine/cli.py
+++ b/src/secrets_engine/cli.py
@ -211,6 +211,27 @@ def cmd_exec(cfg: Config, args) -> int:
    return rc


+def cmd_policy_publication(cfg: Config, args) -> int:
+    from secrets_engine.publication_policy import PublicationPolicy, resolve
+    entry = get_entry(cfg.catalog_dir, args.catalog_id)
+    npm = entry.npm
+    if not npm:
+        from secrets_engine.errors import PolicyGuardError
+        raise PolicyGuardError(f"lane '{entry.id}' has no npm delivery config")
+    policy = PublicationPolicy.load(cfg.policy_dir)
+    res = resolve(
+        policy,
+        org=entry.org, repo=entry.repo, npm_scope=npm.get("scope", ""),
+        package_maturity=npm.get("maturity", "maturity-build"),
+        token_env_override=npm.get("token_env", ""),
+    )
+    print(f"lane: {entry.id}  ({entry.owner})")
+    print(f"netkingdom maturity: {policy.netkingdom_maturity}  "
+          f"(production_grade={policy.production_grade})")
+    print(res.render())
+    return 0
+
+
 def cmd_route(cfg: Config, args) -> int:
    entry = get_entry(cfg.catalog_dir, args.catalog_id)
    client = OpenBaoClient.resolve(cfg.bao_addr)
@ -306,6 +327,12 @@ def build_parser() -> argparse.ArgumentParser:
                    help="command after '--'")
    ex.set_defaults(func=cmd_exec)

+    po = sub.add_parser("policy", help="inspect secrets-engine policies")
+    posub = po.add_subparsers(dest="subcmd", required=True)
+    popub = posub.add_parser("publication", help="resolve a lane's publication scope + token env")
+    popub.add_argument("catalog_id")
+    popub.set_defaults(func=cmd_policy_publication)
+
    ro = sub.add_parser("route", help="ops-warden routing pointer for a lane")
    ro.add_argument("catalog_id")
    ro.add_argument("--json", action="store_true")
--- a/src/secrets_engine/exec_delivery.py
+++ b/src/secrets_engine/exec_delivery.py
@ -27,9 +27,29 @@ from typing import Iterator
 from secrets_engine.catalog import CatalogEntry
 from secrets_engine.errors import DeliveryError
 from secrets_engine.openbao import OpenBaoClient
+from secrets_engine.publication_policy import PublicationPolicy, resolve
 from secrets_engine.redact import redact_text


+def resolve_npm_token_env(entry: CatalogEntry, *, policy_dir=None) -> str:
+    """Resolve the env-var name to inject for a lane via the publication policy."""
+    if policy_dir is None:
+        from secrets_engine.config import Config
+
+        policy_dir = Config.load().policy_dir
+    npm = entry.npm
+    policy = PublicationPolicy.load(policy_dir)
+    res = resolve(
+        policy,
+        org=entry.org,
+        repo=entry.repo,
+        npm_scope=npm.get("scope", ""),
+        package_maturity=npm.get("maturity", "maturity-build"),
+        token_env_override=npm.get("token_env", ""),
+    )
+    return res.token_env
+
+
 def _fetch_value(client: OpenBaoClient, entry: CatalogEntry, field: str) -> str:
    """Read the field value via an approle-scoped token. Held in memory only."""
    try:
@ -58,11 +78,13 @@ def _registry_authkey(registry: str) -> str:


@contextmanager
-def _npm_userconfig(registry: str, scope: str) -> Iterator[Path]:
+def _npm_userconfig(registry: str, scope: str, token_env: str) -> Iterator[Path]:
    """Write a mode-0600 temp .npmrc for the configured registry/scope.

-    The token itself is NOT written to the file — npm expands ${SE_NPM_TOKEN}
-    from the child environment, so the value never touches disk.
+    The token itself is NOT written to the file — npm expands ${<token_env>}
+    from the child environment, so the value never touches disk. `token_env` is
+    resolved from the netkingdom publication-scope policy, so its name reflects
+    the lane's effective publication scope.
    """
    fd, name = tempfile.mkstemp(prefix="se-npmrc-", suffix=".ini")
    path = Path(name)
@ -72,7 +94,7 @@ def _npm_userconfig(registry: str, scope: str) -> Iterator[Path]:
        with os.fdopen(fd, "w") as fh:
            # e.g. @whynot:registry=https://gitea.coulomb.social/api/packages/coulomb/npm/
            fh.write(f"{scope}:registry={registry}\n")
-            fh.write(f"{authkey}:_authToken=${{SE_NPM_TOKEN}}\n")
+            fh.write(f"{authkey}:_authToken=${{{token_env}}}\n")
        yield path
    finally:
        try:
@ -96,6 +118,7 @@ def exec_with_secret(
    command: list[str],
    *,
    mode: str = "auto",
+    policy_dir=None,
 ) -> int:
    """Run `command` with the lane's secret injected for the child only.

@ -132,9 +155,10 @@ def exec_with_secret(
                f"lane '{entry.id}' npm-config delivery needs "
                "delivery_config.npm.registry and .scope"
            )
-        with _npm_userconfig(registry, scope) as npmrc:
+        token_env = resolve_npm_token_env(entry, policy_dir=policy_dir)
+        with _npm_userconfig(registry, scope, token_env) as npmrc:
            child_env["NPM_CONFIG_USERCONFIG"] = str(npmrc)
-            child_env["SE_NPM_TOKEN"] = value
+            child_env[token_env] = value
            rc = _spawn(command, child_env, value)
        return rc

--- a/src/secrets_engine/publication_policy.py
+++ b/src/secrets_engine/publication_policy.py
@ -0,0 +1,144 @@
+"""netkingdom publication-scope policy: bind npm publication scope to maturity.
+
+Resolves, for a publish lane, the *effective* publication scope and the token
+env-var name to inject. The graduated maturity->scope table only activates once
+netkingdom is production grade; until then every lane clamps to repo-scope
+(fail-safe). This is the policy-binding the catalog data feeds into.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from secrets_engine.errors import PolicyGuardError
+
+VALID_MATURITY = ("maturity-build", "maturity-test", "maturity-prod")
+VALID_SCOPES = ("gitea", "org", "scope", "repo")
+# Narrow (small index) to broad (large index) — repo is narrowest, gitea broadest.
+SCOPE_BREADTH = {"repo": 0, "scope": 1, "org": 2, "gitea": 3}
+
+
+@dataclass(frozen=True)
+class PublicationPolicy:
+    domain: str
+    netkingdom_maturity: str
+    maturity_scope: dict[str, str]
+    dormant_scope: str
+    token_env: dict[str, str]
+    raw: dict[str, Any]
+
+    @property
+    def production_grade(self) -> bool:
+        return self.netkingdom_maturity == "maturity-prod"
+
+    @classmethod
+    def load(cls, policy_dir: Path) -> "PublicationPolicy":
+        path = Path(policy_dir) / "netkingdom-publication-scope.yaml"
+        if not path.exists():
+            raise PolicyGuardError(f"publication-scope policy not found: {path}")
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        maturity = data.get("netkingdom_maturity")
+        if maturity not in VALID_MATURITY:
+            raise PolicyGuardError(
+                f"{path}: netkingdom_maturity '{maturity}' invalid; {VALID_MATURITY}"
+            )
+        return cls(
+            domain=data.get("domain", "netkingdom"),
+            netkingdom_maturity=maturity,
+            maturity_scope=data.get("maturity_scope", {}),
+            dormant_scope=data.get("dormant_scope", "repo"),
+            token_env=data.get("token_env", {}),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class Resolution:
+    package_maturity: str
+    effective_scope: str
+    token_env: str
+    active: bool          # is the graduated table in effect?
+    clamped: bool         # was a broader maturity scope clamped to dormant_scope?
+    rationale: str
+
+    def render(self) -> str:
+        return (
+            f"  netkingdom production-grade: {self.active}\n"
+            f"  package maturity:            {self.package_maturity}\n"
+            f"  effective publication scope: {self.effective_scope}"
+            f"{'  (clamped from graduated table — fail-safe)' if self.clamped else ''}\n"
+            f"  inject token as env var:     {self.token_env}\n"
+            f"  rationale: {self.rationale}"
+        )
+
+
+def _slug(value: str) -> str:
+    """COULOMB / WHYNOT / WHYNOTDESIGN — upper, strip @ and non-alphanumerics."""
+    return re.sub(r"[^A-Za-z0-9]", "", value).upper()
+
+
+def _render_env(template: str, *, org: str, npm_scope: str, repo: str) -> str:
+    return (
+        template.replace("{ORG}", _slug(org))
+        .replace("{SCOPE}", _slug(npm_scope))
+        .replace("{REPO}", _slug(repo))
+    )
+
+
+def resolve(
+    policy: PublicationPolicy,
+    *,
+    org: str,
+    repo: str,
+    npm_scope: str,
+    package_maturity: str,
+    token_env_override: str = "",
+) -> Resolution:
+    """Resolve effective scope + token env for a lane under the policy."""
+    if package_maturity not in VALID_MATURITY:
+        raise PolicyGuardError(
+            f"package maturity '{package_maturity}' invalid; {VALID_MATURITY}"
+        )
+
+    if not policy.production_grade:
+        effective = policy.dormant_scope
+        graduated = policy.maturity_scope.get(package_maturity, effective)
+        clamped = SCOPE_BREADTH[graduated] > SCOPE_BREADTH[effective]
+        rationale = (
+            f"netkingdom is '{policy.netkingdom_maturity}', not production grade — "
+            f"graduated scoping is dormant; clamped to '{effective}'"
+            if clamped
+            else f"netkingdom dormant; lane already at safe scope '{effective}'"
+        )
+        active = False
+    else:
+        effective = policy.maturity_scope.get(package_maturity)
+        if effective not in VALID_SCOPES:
+            raise PolicyGuardError(
+                f"no scope mapped for maturity '{package_maturity}'"
+            )
+        clamped = False
+        active = True
+        rationale = (
+            f"netkingdom production grade — {package_maturity} maps to "
+            f"'{effective}' publication scope"
+        )
+
+    if token_env_override:
+        token_env = token_env_override
+    else:
+        template = policy.token_env.get(effective, "NPM_AUTH_TOKEN")
+        token_env = _render_env(template, org=org, npm_scope=npm_scope, repo=repo)
+
+    return Resolution(
+        package_maturity=package_maturity,
+        effective_scope=effective,
+        token_env=token_env,
+        active=active,
+        clamped=clamped,
+        rationale=rationale,
+    )
--- a/tests/test_exec_delivery.py
+++ b/tests/test_exec_delivery.py
@ -12,11 +12,11 @@ def test_registry_authkey_strips_scheme_and_trails_slash():

 def test_npm_userconfig_writes_registry_and_token_ref_not_value():
    registry = "https://gitea.coulomb.social/api/packages/coulomb/npm/"
-    with _npm_userconfig(registry, "@whynot") as path:
+    with _npm_userconfig(registry, "@whynot", "NPM_AUTH_TOKEN") as path:
        body = path.read_text()
        assert f"@whynot:registry={registry}" in body
        # token is referenced via env expansion, never written literally
-        assert "${SE_NPM_TOKEN}" in body
+        assert "${NPM_AUTH_TOKEN}" in body
        assert "//gitea.coulomb.social/api/packages/coulomb/npm/:_authToken" in body
        # file is mode 0600
        assert (path.stat().st_mode & 0o077) == 0
--- a/tests/test_publication_policy.py
+++ b/tests/test_publication_policy.py
@ -0,0 +1,54 @@
+from dataclasses import replace
+
+import pytest
+
+from secrets_engine.config import repo_root
+from secrets_engine.errors import PolicyGuardError
+from secrets_engine.publication_policy import PublicationPolicy, resolve
+
+
+def _policy():
+    return PublicationPolicy.load(repo_root() / "policies")
+
+
+def test_netkingdom_is_build_and_dormant():
+    p = _policy()
+    assert p.netkingdom_maturity == "maturity-build"
+    assert p.production_grade is False
+
+
+def test_dormant_clamps_to_repo_and_default_token_env():
+    p = _policy()
+    r = resolve(p, org="coulomb", repo="whynot-design", npm_scope="@whynot",
+                package_maturity="maturity-build")
+    assert r.effective_scope == "repo"
+    assert r.token_env == "NPM_AUTH_TOKEN"
+    assert r.clamped is True       # build->gitea would be broader; clamped down
+    assert r.active is False
+
+
+def test_active_graduated_scoping_when_production_grade():
+    p = replace(_policy(), netkingdom_maturity="maturity-prod")
+    build = resolve(p, org="coulomb", repo="whynot-design", npm_scope="@whynot",
+                    package_maturity="maturity-build")
+    test = resolve(p, org="coulomb", repo="whynot-design", npm_scope="@whynot",
+                   package_maturity="maturity-test")
+    prod = resolve(p, org="coulomb", repo="whynot-design", npm_scope="@whynot",
+                   package_maturity="maturity-prod")
+    assert (build.effective_scope, build.token_env) == ("gitea", "NPM_AUTH_GITEA_TOKEN")
+    assert (test.effective_scope, test.token_env) == ("org", "NPM_AUTH_COULOMB_TOKEN")
+    assert (prod.effective_scope, prod.token_env) == ("repo", "NPM_AUTH_TOKEN")
+    assert build.active is True and build.clamped is False
+
+
+def test_token_env_override_wins():
+    p = _policy()
+    r = resolve(p, org="coulomb", repo="whynot-design", npm_scope="@whynot",
+                package_maturity="maturity-build", token_env_override="NPM_AUTH_WHYNOTDESIGN")
+    assert r.token_env == "NPM_AUTH_WHYNOTDESIGN"
+
+
+def test_invalid_maturity_rejected():
+    p = _policy()
+    with pytest.raises(PolicyGuardError):
+        resolve(p, org="coulomb", repo="x", npm_scope="@y", package_maturity="maturity-ga")