Add dependency cooldown and remediate vulnerabilities

[miguelcalderon]

Summary

• add a 15-day release cooldown (min-release-age for npm, minimumReleaseAge for pnpm) to every independently installable example, and enforce coverage in CI: check-cooldown-coverage.mjs fails when any directory commits a lockfile without opting into the cooldown, so a new example can't silently opt out
• remediate known dependency vulnerabilities across all example lockfiles
• pin the toolchain that enforces the policy — Node 24.19.0 / npm 11.17.0 locally via .tool-versions and in CI via node-version-file, pnpm 11.20.0 via packageManager, plus engines.npm >=11.10.1 + engine-strict at the root so a too-old npm fails loudly instead of skipping the cooldown
• add a Dependency policy workflow (least-privilege contents: read) that keeps the duplicated npm/pnpm override maps in sync and verifies the committed pnpm lockfiles against manifests, overrides, and the cooldown itself — pnpm 11.20's frozen install re-checks minimumReleaseAge per lockfile entry. The dual-manager matrix is generated from check-override-sync.mjs --json, not maintained by hand. npm has no equivalent check (npm ci never re-validates the cooldown); that asymmetry is documented in the workflow.

Cooldown exclusions: removed

The first iteration scoped exclusions to remediation versions published inside the window. All of them matured out by 2026-08-22 (youngest: nanoid 3.3.18, published 2026-08-07), so the dated TODO came due: every min-release-age-exclude / minimumReleaseAgeExclude entry is gone, the stacked audit-generated override rules are collapsed to one rule per package per major line, and the exact brace-expansion pins are relaxed back to ranged floors. Fresh resolution and npm audit fix work again with the cooldown fully active.

Audit state as of 2026-09-01

Full re-sweep on 2026-09-01 found 17 examples with advisories (mostly nanoid GHSA-2v37-7h3g-55p8 and DOMPurify GHSA-55q2-fjhq-7xh7), including two examples merged from master with no policy coverage yet (web/viewer/web-sdk-demo — 9 advisories, gdpicture/office-templating — no .npmrc). All remediated:

• nanoid ≥3.3.18 everywhere (override floor >=3.3.18 <4 in dual-manager examples, npm audit fix elsewhere)
• dompurify ≥3.4.13 (ranged floor <3.4.13 → >=3.4.13 <4, replacing the exact 3.4.12 pin)
• linkify-it ≥5.0.2 (GHSA-v245-v573-v5vm), vite 6.4.3 in web-sdk-demo (GHSA-v6wh-96g9-6wx3 / GHSA-fx2h-pf6j-xcff), plus overrides for @babel/core, markdown-it, postcss in web-sdk-demo

npm audit is clean across all 27 examples and pnpm audit is clean in the three dual-manager examples; the pnpm frozen-install policy check passes on all three.

If this PR sits unmerged for a few days, re-run npm audit across the examples before merging — new advisories may have appeared, and the resolved versions here go stale.

🤖 Generated with Claude Code

[ritz078]

Three cross-cutting items with no single line to anchor to.

npm audit fix no longer works in these examples. A/B on web/ui-customization, npm 12.0.2, no lockfile, identical inputs except the cooldown:

	exit	result
with min-release-age=15	1	2 vulnerabilities (1 moderate, 1 high), prints fix available via 'npm audit fix'
control	0	found 0 vulnerabilities

The control resolves to exactly the versions this PR hand-pins, so the cooldown blocks the remediation from being reachable by the repo's own tooling, and the retry hint loops with no exit. The surviving vulns are this PR's own targets (brace-expansion high, postcss moderate). Scoping note: npm ci from the committed lockfiles is unaffected across all 25 npm examples — npm never validates a lockfile against the age window, only pnpm 11 does, which is why the breakage is confined to the three pnpm examples.

.tool-versions and CI disagree about whether the cooldown exists. nodejs 22.12.0 → npm 10.9.0, which predates the feature; CI's lts/* → Node 24.19.0 → npm 11.17.0, which enforces it. A contributor following the repo's own pin regenerates lockfiles with no cooldown applied and can't reproduce any of this. Bumping .tool-versions and pinning the workflow to the same version would make the policy enforce identically in both places.

The committed lockfiles were generated with the cooldown not in effect — they introduce entries 2 days old (nanoid@3.3.17, next@16.3.0 + 9 @next/*, fast-uri@3.1.5, @emnapi/runtime@1.11.3). Harmless for npm ci, but it means the artifacts can't be reproduced by anyone honoring the policy this same commit adds.

Also — could you spell out what "preserve the protected cache-related dependency versions" refers to? I couldn't find a policy file or anything in AGENTS.md, and no cache-adjacent package (flatted, flat-cache, lru-cache, caniuse-lite) changed version in any of the 26 lockfiles, so there's nothing for a reviewer to check against.

[miguelcalderon]

Replying to the review-level items from #200 (review) — all addressed in f0883d5:

• npm audit fix broken under the cooldown: the example .npmrc files now carry min-release-age-exclude entries scoped to the pinned security-remediation packages, so the remediation versions are reachable by the repo's own tooling again during the window. The exclusions are removable after 2026-08-18 (dated TODO in the root .npmrc).
• .tool-versions vs CI disagreement: .tool-versions is bumped to Node 24.19.0 (npm 11.17.0), and the typecheck workflow now uses node-version-file: '.tool-versions' instead of lts/*, so local and CI enforce the same cooldown.
• Lockfiles generated with the cooldown not in effect: the three pnpm lockfiles were regenerated under the pinned toolchain, and a new Dependency policy workflow verifies each committed lockfile against the supply-chain policy (pnpm install --lockfile-only --frozen-lockfile) and keeps the duplicated npm/pnpm override maps identical — all jobs green on this PR.
• "preserve the protected cache-related dependency versions": that phrasing was inaccurate — there is no such policy file, and no cache-related pins to check. The PR description has been rewritten without it.

[ritz078]

Three things that have no single line to hang off:

• The audit claim in the description is stale. Re-running npm audit today against this branch reports advisories in 17 of the 25 examples, not a clean sweep as of 2026-08-07. Worth re-running and refreshing the remediation set before merge, since the overrides were generated from the older audit output.
• Nothing enforces that an example has an .npmrc. The policy is only as good as its coverage, but the new workflow's paths: filter fires on **/.npmrc — i.e. only when one is touched. A new example added without one silently opts out of the cooldown forever. A CI assertion that every directory with a lockfile also has min-release-age set would close that.
• The npm side has no lockfile verification job, and can't easily get one. pnpm-lockfile-policy covers pnpm; there is no npm equivalent, and npm ci is not a substitute — npm applies min-release-age only at resolution time, so npm ci, npm install, and npm install --package-lock-only all install a cooldown-bypassing package-lock.json without complaint. That asymmetry is worth stating somewhere, because today the pnpm job reads as if both managers are covered.

[miguelcalderon]

Re the three cross-cutting items in the 2026-08-10 review, all addressed in d5d3e74:

• Stale audit — re-ran the sweep on 2026-09-01: 17 examples had advisories (nanoid GHSA-2v37-7h3g-55p8, DOMPurify GHSA-55q2-fjhq-7xh7, plus 9 advisories in web/viewer/web-sdk-demo, newly merged from master). All remediated; npm audit is clean across all 27 examples and pnpm audit clean in the three dual-manager ones. The PR description now carries the current audit state. Since every fix version has matured out of the 15-day window, the refresh also removed all cooldown exclusions per the dated TODO.
• Coverage enforcement — new check-cooldown-coverage.mjs in the Dependency policy workflow fails when any directory commits a lockfile without min-release-age (npm) / minimumReleaseAge (pnpm). It immediately caught gdpicture/office-templating, which merged from master without an .npmrc — exactly the silent opt-out you described.
• npm/pnpm asymmetry — now stated explicitly in the workflow next to the pnpm job: npm applies min-release-age only at resolution time, so npm ci cannot verify a committed package-lock.json against the cooldown; the npm side is covered at regeneration time and by review only. (The pnpm job comment was also corrected per your inline note — pnpm 11.20 does re-check the cooldown on frozen installs.)

[ritz078]

Reviewed the policy tooling by running it rather than reading it — both scripts against a worktree of this SHA, plus npm 11.17.0/12.0.2 extracted from the registry to exercise the cooldown for real. The mechanism holds up well: engine-strict genuinely enforces the root engines.npm, the cooldown is really applied (min-release-age=40 → no matching version … before 7/24/2026), and I confirmed all 1,971 distinct name@version pairs across all 30 lockfiles predate the 15-day cutoff — so the committed lockfiles are reproducible under the cooldown they enforce, with zero exclusions, and nothing was lost collapsing the stacked override rules. npm audit fix also works with the cooldown fully active now, which closes my earlier objection.

Three things with no single line to anchor to:

The audit sweep needs re-running before merge. npm audit --package-lock-only across all 27 examples today reports 16 of them (plus all 3 pnpm-lock.yaml) carrying two high-severity browserslist advisories — GHSA-c83g-rgw3-j3cx and GHSA-73wf-gq98-2v4g, <=4.28.6. Not your oversight: both were published about 65 minutes after your final commit. The fix is unobstructed — 4.28.8 (2026-08-08) is well past the 15-day window, and npm audit fix --package-lock-only under the active cooldown took ui-customization from 4.28.6 to 4.28.8 with found 0 vulnerabilities. Nothing else is unremediated anywhere. Worth dropping the "clean across all 27 examples" line from the description until it's re-run.

The npm floor is a user-facing breaking change that the docs don't mention. Because Node 20 and 22 both ship npm 10.x, npm install now fails in all 27 examples for anyone not on Node 24.14.1+. That's the intended "fail loudly" behaviour, but 29 READMEs still say npm install and the root README mentions neither Node nor npm — so for a clone-and-run examples repo, the failure arrives with no explanation. One line in the root README plus the engines.node change would cover it.

No contributor-facing documentation of the policy. Searching for min-release-age|minimumReleaseAge|cooldown outside lockfiles matches only the three pnpm-workspace.yaml files. AGENTS.md and the root README are untouched, so someone adding an example learns about the .npmrc + engines.npm + pnpm-workspace.yaml requirement by getting a red check. The upstream monorepo points at documentation/dependency-cooldowns.md; a short equivalent here would help.

[miguelcalderon]

Addressed the three unanchored items from the review in f58dc02:

• Audit sweep re-run (2026-09-02): npm audit --package-lock-only reports 0 vulnerabilities in all 27 examples and pnpm audit finds none in the 3 dual-manager examples. browserslist GHSA-c83g-rgw3-j3cx / GHSA-73wf-gq98-2v4g are remediated via a browserslist@<=4.28.6 → >=4.28.8 <5 override in the dual-manager examples (mirrored in pnpm-workspace.yaml and the lock headers) and npm audit fix elsewhere; the frozen pnpm installs pass. I will re-run before merge if the PR sits.
• npm floor in user docs: the root README has a "Local JavaScript requirements" section (pinned Node 24.19.0, or any npm-11-supported Node with npm 11.10.0+ installed separately), and every example README that listed Node prerequisites now states the exact range ^20.17.0 || >=22.9.0.
• Contributor docs: added documentation/dependency-cooldowns.md (what to commit for npm and pnpm examples, what must not be committed, how to update dependencies, what the policy check parses) and linked it from AGENTS.md and the root README. The policy tests run in CI via npm run test:dependency-policy.