diff --git a/README.md b/README.md index 62afe46..42fca30 100644 --- 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) diff --git a/catalog/whynot-design-npm-publish.yaml b/catalog/whynot-design-npm-publish.yaml index 214a01d..30a5c04 100644 --- 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: diff --git a/docs/cli.md b/docs/cli.md index 3a59e45..a7e5c66 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -44,10 +44,15 @@ secrets-engine apply --stage [--dry-run] [--bootstrap-token-file F secrets-engine provision --stage --field NAME (--from-file F | --generate) secrets-engine verify --field NAME [--positive] [--negative] secrets-engine exec --catalog [--field NAME] [--mode auto|npm-config|exec-env] -- CMD... +secrets-engine policy publication secrets-engine route [--json] secrets-engine revoke [--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)). + `` is a catalog id or a decision/CCR ref (matched against `approval.decision_ref`). `plan` and `apply --dry-run` never mutate OpenBao. diff --git a/docs/publication-scope-policy.md b/docs/publication-scope-policy.md new file mode 100644 index 0000000..10091f4 --- /dev/null +++ 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[_]_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. diff --git a/policies/netkingdom-publication-scope.yaml b/policies/netkingdom-publication-scope.yaml new file mode 100644 index 0000000..93c6117 --- /dev/null +++ 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" diff --git a/scripts/npm-publish-demo.sh b/scripts/npm-publish-demo.sh index d5a0ba1..f02d32c 100755 --- 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:-}'" +echo " NPM_AUTH_TOKEN in parent: '${NPM_AUTH_TOKEN:-}'" echo " NPM_CONFIG_USERCONFIG in parent: '${NPM_CONFIG_USERCONFIG:-}'" echo echo "### DONE — npm publish (dry-run) ran with the token injected by secrets-engine." diff --git a/src/secrets_engine/cli.py b/src/secrets_engine/cli.py index 1bd9b9b..e569cc3 100644 --- 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") diff --git a/src/secrets_engine/exec_delivery.py b/src/secrets_engine/exec_delivery.py index eed1aa7..355186b 100644 --- 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 ${} + 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 diff --git a/src/secrets_engine/publication_policy.py b/src/secrets_engine/publication_policy.py new file mode 100644 index 0000000..dae04ab --- /dev/null +++ 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, + ) diff --git a/tests/test_exec_delivery.py b/tests/test_exec_delivery.py index 8fd5c91..94e6f84 100644 --- 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 diff --git a/tests/test_publication_policy.py b/tests/test_publication_policy.py new file mode 100644 index 0000000..4c26e4c --- /dev/null +++ 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")