From e817239e7d542da1e7bc5c137abd55afbaa47fad Mon Sep 17 00:00:00 2001
From: everdimension <everdimension@gmail.com>
Date: Mon, 18 May 2026 15:34:13 +0300
Subject: [PATCH] Add supply-chain cooldown for npm dependencies

Enforce a rolling release-age cooldown so npm only resolves dependency
versions that have been published for at least 15 days, reducing exposure
to compromised "fresh" releases. Malicious packages are typically detected
and unpublished within that window.

- .npmrc: set min-release-age=15 (requires npm >= 11.10.0);
- package.json: add devEngines pinning node >=20.10 and npm >=11.10;
hard-fail for earlier npm versions
- workflows: bump CI to Node 24 (Node 22 ships npm 10, which lacks
min-release-age) and switch the publish job's npm install -> npm ci
for deterministic, lockfile-pinned installs
- README: document the policy and the --min-release-age=0 override for
urgent security fixes

No breaking changes for consumers of the published zerion-cli package:
the runtime requirement stays node >=20 (engines is unchanged), and
devEngines / .npmrc are dev-and-CI only. The cooldown affects only version resolution
(updating package-lock.json); installs from the existing lockfile,
including npm ci, are unaffected.
---
 .github/workflows/release-please.yml |  4 ++--
 .github/workflows/test.yml           |  2 +-
 .npmrc                               |  7 +++++++
 README.md                            | 18 ++++++++++++++++++
 package.json                         | 12 ++++++++++++
 5 files changed, 40 insertions(+), 3 deletions(-)
 create mode 100644 .npmrc

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index 7d4988e2..cc8310ae 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -32,10 +32,10 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           registry-url: https://registry.npmjs.org
 
-      - run: npm install
+      - run: npm ci
 
       - run: npm test
 
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1c431569..68cd3b75 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -14,7 +14,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
 
       - run: npm ci
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 00000000..ed7a2ab9
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,7 @@
+# Reject package versions published less than 15 days ago (rolling supply-chain
+# cooldown). Requires npm >= 11.10.0
+#
+# To pull in an urgent fix newer than the window, override for a single run:
+#   npm install <pkg> --min-release-age=0
+# then commit the updated package-lock.json. See README for the policy.
+min-release-age=15
diff --git a/README.md b/README.md
index ded8892f..6a38611d 100644
--- a/README.md
+++ b/README.md
@@ -384,6 +384,24 @@ npm run test:all          # both
 node ./cli/zerion.js --help
 ```
 
+Development requires **npm >=11.10** (see Supply-chain cooldown below); CI and `npm publish` run on Node 24.
+
+### Supply-chain cooldown
+
+To reduce exposure to npm supply-chain attacks, this repo enforces a **release-age cooldown**: `npm install` will only resolve dependency versions that have been published for at least a fixed number of days. Compromised "fresh" releases are usually detected and unpublished within that window.
+
+The cooldown length is set by `min-release-age` in [`.npmrc`](./.npmrc) — that line is the single source of truth for the window. It requires **npm >=11.10** (older npm silently ignores it); `devEngines` in `package.json` pins npm to that range with `onFail: error`, so an unsupported npm hard-fails instead of quietly skipping the cooldown.
+
+The cooldown only affects version _resolution_ (i.e. updating `package-lock.json`); a plain install from the existing lockfile — including `npm ci` in CI — is unaffected.
+
+**Overriding for an urgent fix.** If you need a security patch newer than the window, bypass it for a single install and commit the result:
+
+```bash
+npm install <package>@<version> --min-release-age=0
+```
+
+Then commit the updated `package-lock.json` with a note explaining why.
+
 ### Contribution guidelines
 
 - Keep examples copy-pasteable.
diff --git a/package.json b/package.json
index 7130f2d8..832ff6dc 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,18 @@
   "engines": {
     "node": ">=20"
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=20.10.0",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": ">=11.10.0",
+      "onFail": "error"
+    }
+  },
   "keywords": [
     "zerion",
     "ai",