mandrel-platform 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-action-pins.mjs

@@ -27,13 +27,29 @@
  *     `pnpm/action-setup`.) A non-SHA ref (a tag like `v4`, a branch, a short
  *     SHA) FAILS the lint.
  *
- *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — are
- *     EXEMPT from this ratchet. They are this repo's OWN reusable workflows /
- *     composite actions, governed by the cross-repo portability lint's pin-lag
- *     guard (`check-workflow-portability.mjs`, Rule 3), and they carry a
- *     release-tag shape at publish time. The first-party owner is overridable
- *     via `--first-party-owner` for a fork. They ARE, however, subject to the
- *     single-pin invariant below.
+ *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — MUST
+ *     ALSO be a 40-char hex SHA, and are reported as their own violation class.
+ *     They were exempt until Story #354's audit: the exemption's stated
+ *     justification was that `check-workflow-portability.mjs` Rule 3 governs
+ *     them, but Rule 3's `collectInternalPins` skips any ref that is not
+ *     already a 40-hex SHA (`if (!isSha40(cls.ref)) return`), so a
+ *     branch-pinned self-reference was validated by NOTHING. The two other
+ *     first-party guards had the same hole — the single-pin invariant below
+ *     compares whatever refs it finds without requiring a SHA, and
+ *     `check-first-party-pin-freshness.mjs` files a non-SHA ref under an
+ *     informational `unpinnedRefs` note that never fails. So
+ *     `…/gitleaks-scan@main` was green on all three.
+ *
+ *     A moving self-ref is the same supply-chain risk the third-party ratchet
+ *     exists to close, with a wider blast radius: `pr-quality.yml` is inherited
+ *     by every consumer. It is also invisible to `platform-sync.mjs`, whose
+ *     rewrite regex matches `@[0-9a-fA-F]{40}` only — a branch-pinned consumer
+ *     workflow is silently skipped on every platform bump.
+ *
+ *     The land-then-bump flow is unaffected: it always pins full SHAs (see
+ *     docs/reusable-workflows.md § First-party self-pin freshness). The
+ *     first-party owner is overridable via `--first-party-owner` for a fork,
+ *     and first-party refs remain subject to the single-pin invariant below.
  *
  *   • LOCAL `./path` references and `docker://image` references are EXEMPT —
  *     a local path has no upstream tag to move, and a docker ref is pinned by
@@ -125,10 +141,18 @@ export function parseArgs(argv) {
 // ---------------------------------------------------------------------------
 
 /**
- * Scan a single file's TEXT for `uses:` step keys and evaluate each third-party
- * reference. Returns { violations: [...], scanned: <count> }. A violation is
- * `{ file, line, ref, owner, reason }`. `file` is left as passed-in (the
- * caller supplies a display path).
+ * Scan a single file's TEXT for `uses:` step keys and evaluate every REMOTE
+ * reference against the 40-hex SHA ratchet. Returns
+ * `{ violations, scanned, firstPartyViolations, firstPartyScanned }` — the two
+ * owner classes are counted and reported separately because their remediation
+ * differs (bump a vendored third-party pin vs. re-pin one of this repo's own
+ * call sites, which must move at every call site together to keep the
+ * single-pin invariant). A violation is `{ file, line, ref, owner, reason }`;
+ * `file` is left as passed-in (the caller supplies a display path).
+ *
+ * LOCAL (`./path`) and `docker://` references stay exempt: a local path has no
+ * upstream ref that can move, and a docker ref carries its own digest
+ * convention.
  *
  * Only lines whose first non-space token is `uses:` (a YAML mapping key) are
  * inspected — `uses:` appearing inside a comment or a `run:` heredoc never
@@ -138,13 +162,33 @@ export function parseArgs(argv) {
  */
 export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   const lines = String(content).split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const bareRef = parseUsesLine(lines[i]);
     if (bareRef === null) continue;
     const cls = classifyUses(bareRef, firstPartyOwner);
-    if (cls.kind !== "third-party") continue; // local/docker/first-party/unparseable → exempt
+
+    // First-party self-references (Story #354 audit). A bare `owner/repo@ref`
+    // carrying no subpath is ratcheted too: the hazard is the MOVING REF, and
+    // it moves whether or not the reference names a subpath.
+    if (cls.kind === "first-party") {
+      firstPartyScanned++;
+      if (!isSha40(cls.ref)) {
+        firstPartyViolations.push({
+          file: displayFile,
+          line: i + 1,
+          ref: bareRef,
+          owner: cls.owner,
+          reason: `first-party self-reference "${cls.owner}" is pinned to "${cls.ref}", not a full 40-char commit SHA`,
+        });
+      }
+      continue;
+    }
+
+    if (cls.kind !== "third-party") continue; // local/docker/unparseable → exempt
     scanned++;
     if (!isSha40(cls.ref)) {
       violations.push({
@@ -156,7 +200,7 @@ export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRS
       });
     }
   }
-  return { violations, scanned };
+  return { violations, scanned, firstPartyViolations, firstPartyScanned };
 }
 
 // ---------------------------------------------------------------------------
@@ -178,7 +222,9 @@ export function runLint(opts) {
   const files = [...workflowFiles, ...listActionFiles(acDir)];
 
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   // Keep the raw workflow-file contents for the single-pin pass so we read
   // each file from disk once.
   const workflowRecords = [];
@@ -192,7 +238,9 @@ export function runLint(opts) {
     const display = relative(cwd, file) || file;
     const res = scanContent(content, display, opts.firstPartyOwner);
     violations.push(...res.violations);
+    firstPartyViolations.push(...res.firstPartyViolations);
     scanned += res.scanned;
+    firstPartyScanned += res.firstPartyScanned;
     if (workflowFiles.includes(file)) {
       workflowRecords.push({ file: display, content });
     }
@@ -204,9 +252,14 @@ export function runLint(opts) {
     : [];
 
   return {
-    ok: violations.length === 0 && singlePinViolations.length === 0,
+    ok:
+      violations.length === 0 &&
+      firstPartyViolations.length === 0 &&
+      singlePinViolations.length === 0,
     violations,
+    firstPartyViolations,
     scanned,
+    firstPartyScanned,
     files,
     singlePinViolations,
   };
@@ -242,6 +295,24 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
     );
   }
 
+  if (result.firstPartyViolations.length > 0) {
+    failed = true;
+    err(
+      `[action-pins] ❌ ${result.firstPartyViolations.length} first-party self-reference(s) pinned to a moving ref:`
+    );
+    for (const v of result.firstPartyViolations) {
+      err(`  • ${v.file}:${v.line} — ${v.reason}`);
+    }
+    err(
+      "[action-pins] Pin every first-party `uses:` to a full 40-char commit SHA " +
+        "too (keep the `# vX.Y.Z` tag note as a comment). A branch or tag ref " +
+        "means the revision that runs can change with no diff here — and " +
+        "`pr-quality.yml` is inherited by every consumer. It is also invisible " +
+        "to platform-sync.mjs, whose rewrite matches 40-hex SHAs only, so it " +
+        "would be skipped on every platform bump."
+    );
+  }
+
   if (result.singlePinViolations.length > 0) {
     failed = true;
     err(
@@ -263,7 +334,8 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
   if (failed) return 1;
 
   log(
-    `[action-pins] ✅ all ${result.scanned} third-party action reference(s) are SHA-pinned ` +
+    `[action-pins] ✅ all ${result.scanned} third-party and ${result.firstPartyScanned} ` +
+      `first-party action reference(s) are SHA-pinned ` +
       `(${result.files.length} file(s) scanned); first-party single-pin invariant holds.`
   );
   return 0;

package/scripts/check-action-pins.test.mjs

@@ -10,6 +10,12 @@
  * a full content scan with both a SHA-pinned (pass) and a tag-pinned (fail)
  * fixture. Pure helpers + a temp-dir fixture keep the whole pipeline offline.
  *
+ * The first-party ratchet block (Story #354 audit) covers what used to be a
+ * three-way blind spot: a self-reference on a moving ref passed this lint (as
+ * exempt), the portability lint's Rule 3 (which skips non-SHA refs), and
+ * check-first-party-pin-freshness.mjs (which files it under a non-failing
+ * informational note) all at once.
+ *
  * Run: node scripts/check-action-pins.test.mjs   (or `node --test scripts/`)
  */
 
@@ -138,7 +144,7 @@ test("scanContent fails a tag-pinned third-party uses", () => {
   assert.match(violations[0].reason, /not a full 40-char commit SHA/);
 });
 
-test("scanContent ignores first-party, local, docker, and comment lines", () => {
+test("scanContent ignores local, docker, and comment lines", () => {
   const yaml = [
     "# uses: actions/checkout@v4  (this is a comment example, must be ignored)",
     "    steps:",
@@ -146,11 +152,102 @@ test("scanContent ignores first-party, local, docker, and comment lines", () =>
     "      - uses: ./.github/actions/local-thing",
     "      - uses: docker://alpine:3.19",
   ].join("\n");
-  const { violations, scanned } = scanContent(yaml, "wf.yml");
-  assert.equal(scanned, 0); // none are third-party
+  const res = scanContent(yaml, "wf.yml");
+  assert.equal(res.scanned, 0); // none are third-party
+  assert.deepEqual(res.violations, []);
+  // The first-party ref IS counted now, and passes because it is SHA-pinned.
+  // A local `./path` and a `docker://` ref remain exempt from both classes.
+  assert.equal(res.firstPartyScanned, 1);
+  assert.deepEqual(res.firstPartyViolations, []);
+});
+
+// ---------------------------------------------------------------------------
+// First-party SHA ratchet (Story #354 audit)
+//
+// A first-party self-reference on a moving ref used to be green on all three
+// first-party guards at once: this ratchet skipped it as exempt, the
+// portability lint's Rule 3 skips any ref that is not already a 40-hex SHA,
+// and check-first-party-pin-freshness.mjs files it under an informational
+// note that never fails. These tests pin the hole shut.
+// ---------------------------------------------------------------------------
+
+test("scanContent flags a branch-pinned first-party self-reference", () => {
+  const yaml = "      - uses: dsj1984/mandrel-platform/.github/actions/gitleaks-scan@main";
+  const { firstPartyViolations, firstPartyScanned, violations } = scanContent(yaml, "wf.yml");
+  assert.equal(firstPartyScanned, 1);
+  assert.equal(firstPartyViolations.length, 1);
+  assert.equal(firstPartyViolations[0].line, 1);
+  assert.equal(firstPartyViolations[0].owner, "dsj1984/mandrel-platform");
+  assert.match(firstPartyViolations[0].reason, /not a full 40-char commit SHA/);
+  // Never misfiled as a third-party violation — the remediation differs.
   assert.deepEqual(violations, []);
 });
 
+test("scanContent flags a tag-pinned and a short-SHA first-party self-reference", () => {
+  const yaml = [
+    "      - uses: dsj1984/mandrel-platform/.github/workflows/pr-quality.yml@v1.1.0",
+    `      - uses: dsj1984/mandrel-platform/.github/actions/osv-scan@${SHORT}`,
+  ].join("\n");
+  const { firstPartyViolations } = scanContent(yaml, "wf.yml");
+  assert.equal(firstPartyViolations.length, 2);
+  assert.deepEqual(
+    firstPartyViolations.map((v) => v.line),
+    [1, 2],
+  );
+});
+
+test("scanContent ratchets a bare first-party self-reference carrying no subpath", () => {
+  // No subpath means no manifest for the freshness checker to resolve, but the
+  // ref still moves — so the ratchet must still apply.
+  const yaml = "      - uses: dsj1984/mandrel-platform@main";
+  const { firstPartyViolations, firstPartyScanned } = scanContent(yaml, "wf.yml");
+  assert.equal(firstPartyScanned, 1);
+  assert.equal(firstPartyViolations.length, 1);
+});
+
+test("scanContent honours --first-party-owner when ratcheting a fork's self-refs", () => {
+  const yaml = "      - uses: my-org/my-fork/.github/actions/thing@main";
+  const asFirstParty = scanContent(yaml, "wf.yml", "my-org/my-fork");
+  assert.equal(asFirstParty.firstPartyViolations.length, 1);
+  assert.deepEqual(asFirstParty.violations, []);
+
+  // Under the default owner the SAME line is a third-party violation instead —
+  // still caught, just under the other class.
+  const asThirdParty = scanContent(yaml, "wf.yml");
+  assert.equal(asThirdParty.violations.length, 1);
+  assert.deepEqual(asThirdParty.firstPartyViolations, []);
+});
+
+test("runLint / runCli are red on a branch-pinned first-party self-reference", () => {
+  const root = fixtureRepo({
+    workflow: [
+      "    steps:",
+      `      - uses: actions/checkout@${SHA} # v4`,
+      "      - uses: dsj1984/mandrel-platform/.github/actions/gitleaks-scan@main",
+    ].join("\n"),
+  });
+  try {
+    const res = runLint({
+      cwd: root,
+      workflowsDir: ".github/workflows",
+      actionsDir: ".github/actions",
+      firstPartyOwner: "dsj1984/mandrel-platform",
+    });
+    assert.equal(res.ok, false);
+    assert.equal(res.firstPartyViolations.length, 1);
+    assert.deepEqual(res.violations, []); // the third-party pin is fine
+
+    const errs = [];
+    const code = runCli(["--cwd", root], { log: () => {}, err: (m) => errs.push(m) });
+    assert.equal(code, 1);
+    assert.ok(errs.some((m) => /first-party self-reference\(s\) pinned to a moving ref/.test(m)));
+    // The remedy names the blast radius, not just the rule.
+    assert.ok(errs.some((m) => /inherited by every consumer/.test(m)));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("scanContent flags a short-SHA third-party pin", () => {
   const yaml = `      - uses: actions/setup-node@${SHORT}`;
   const { violations } = scanContent(yaml, "wf.yml");
@@ -205,7 +302,9 @@ test("runLint is green when every third-party action is SHA-pinned", () => {
       firstPartyOwner: "dsj1984/mandrel-platform",
     });
     assert.equal(res.ok, true);
-    assert.equal(res.scanned, 1); // only the third-party checkout counts
+    assert.equal(res.scanned, 1); // only the third-party checkout counts here
+    assert.equal(res.firstPartyScanned, 1); // the self-reference is counted separately
+    assert.deepEqual(res.firstPartyViolations, []);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }