ci: standardize on npm 11 with min-release-age gate

[nickytonline]

Summary

The pre-commit CI failure on #2350 surfaced that this repo had never actually been migrated to npm 11 as part of ENG-3817's package-age-quarantine rollout — it was still on Yarn when that work was scoped, so it got missed. npm ci errored with:

npm error Missing: unist-util-visit@4.1.2 from lock file
npm error Missing: unist-util-visit-parents@5.1.3 from lock file

Root cause: Node's bundled npm (10.9.4, from .tool-versions' pinned Node 22.22.0) resolves an optional nested dependency subtree differently than npm 11 (hast-util-to-estree's optional dependency on unist-util-visit/unist-util-visit-parents) — npm 11 tolerates the gap, npm 10.9.4 hard-fails npm ci on it. Confirmed by reproducing the failure locally with npx npm@10.9.4 ci against a freshly-regenerated lockfile, and confirming success with npm 11.

This PR brings the repo onto npm 11 by bumping Node itself, rather than pinning npm separately: .tool-versions now pins Node 24.19.0, which bundles npm 11.17.0 by default (matching the convention already used in pomerium/pomerium). That also means min-release-age (which npm 10 silently ignores) actually takes effect now, bringing this repo in line with the supply-chain hardening already rolled out to other Pomerium repos.

Changes

• .tool-versions: nodejs 22.22.0 → 24.19.0 — Node's bundled npm 11 is what actually fixes the npm ci failure; no separate npm install step needed
• .npmrc: min-release-age=3
• package.json:
  • engines.node bumped to >=24.0.0 (the version where npm 11 becomes the bundled default), engines.npm pinned to >=11 <12 — the <12 ceiling is deliberate: npm 12.0.2 already exists on the registry, but no Node release line bundles it yet, so this avoids picking up an unvetted major version by accident
  • no packageManager field — Corepack only manages npm from this field if you explicitly run corepack enable npm (this repo doesn't), npm itself doesn't validate its own version against it, and Netlify's docs confirm it's consulted via Corepack for Yarn/pnpm but not for npm, so pinning it here wouldn't have done anything except go stale
• npm-audit-signatures.yml (new): verifies registry signatures and provenance attestations on package.json/package-lock.json changes
• package-lock.json regenerated with npm 11

Locally verified under Node 24.19.0 (bundled npm 11.17.0), with no manual npm install and no corepack enable: npm ci, npm ci --ignore-scripts, npm audit signatures --min-release-age=0, and npm run check all pass — including postman-code-generators's yarn-based postinstall script (a transitive dep of docusaurus-theme-openapi-docs), which runs fine since nothing in the ancestor package.json chain declares a packageManager field to trigger Node's disabled yarn shim.

Related

• Resolves the CI failure on Build(deps): Bump the npm group across 1 directory with 9 updates #2350 (by moving this repo onto npm 11, not by patching around it)
• ENG-4332 — tracking issue
• Related to ENG-3817, the original npm 11 + min-release-age rollout that skipped this repo (it was still on yarn at the time it was scoped)

AI disclosure

Claude Code (Sonnet 5) was used throughout, iteratively rather than as a single draft-and-review pass: it investigated the original CI failure, and initial attempts at a fix (regenerating the lockfile, then just bumping npm) didn't hold up under scrutiny, which led to jointly digging further and finding the actual npm 10 vs 11 dependency-resolution root cause. That led to cross-checking the convention used in other Pomerium repos (ENG-3817) and, after review feedback questioned why Node wasn't just bumped, confirming against Node's own release metadata and pomerium/pomerium's existing .tool-versions/CI convention that bumping to Node 24 gets npm 11 natively. Along the way, several intermediate fixes (a packageManager pin, a curl-installed npm binary, a corepack enable step) turned out to be unnecessary once Node was bumped and were removed after verifying locally (clean installs, with Corepack explicitly disabled, confirming npm ci including the yarn-based postinstall still succeeds). Nick Taylor directed the investigation and design decisions at each step and reviewed all resulting changes.

Also needed to manually intervene here. We're not using a netlify.toml so had to modify the build command in the Netlify UI. We already moved to npm a while back, but the build command was not updated.

Also set the Node version to 24.x in the Netlify UI

Checklist

• reference any related issues
• disclosed AI usage (or wrote "none") per AI_POLICY.md

[netlify]

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	d99e310
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/6a884573d1a6d8000832a6d1
😎 Deploy Preview	https://deploy-preview-2351--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Summary

The PR standardizes development and CI on Node 24 with npm 11 and adds a three-day package-release quarantine.

• Adds a dependency-signature and provenance audit workflow.
• Declares the supported Node and npm ranges.
• Regenerates npm lockfile metadata for npm 11.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
.github/workflows/npm-audit-signatures.yml	Adds a least-privilege workflow that installs dependencies without lifecycle scripts and audits registry signatures and provenance.
.npmrc	Configures npm 11 to exclude packages published within the preceding three days.
.tool-versions	Pins Node 24.19.0 so local and CI environments receive the intended npm 11 runtime.
package.json	Raises the supported Node floor and constrains npm to major version 11.
package-lock.json	Regenerates dependency metadata under npm 11, including removal of the problematic optional nested subtree.

_{Reviews (6): Last reviewed commit: "ci: drop packageManager pin and corepack..." | Re-trigger Greptile}

[nickytonline]

We're not using a netlify.toml so had to modify the build command in the Netlify UI. We already moved to npm a while back, but the build command was not updated.

[kenjenkins]

I thought npm was bundled with nodejs? Do we need to bump the nodejs version in the .tool-versions file?

[nickytonline]

I thought npm was bundled with nodejs? Do we need to bump the nodejs version in the .tool-versions file?

We can definitely bump to node 24 (Netlify supports it) and get npm 11 with it. I was just going the "standard" way what we did in other repos when we added npm 11.

[nickytonline]

I thought npm was bundled with nodejs? Do we need to bump the nodejs version in the .tool-versions file?

@kenjenkins, I just moved to Node.js 24. No need to stay on 22.

[kenjenkins]

I don't see a min-release-age in any of our other repos. Should we hold off on adding this for now, for consistency?

[nickytonline]

I had it on auto-merge. 😅 I took that from the issue Bobby had created initially I believe, but you're right. It's not in our other repos. I can rollback the .npmrc change.