docs(security): harden package-manager supply-chain guidance

[federicobartoli]

Summary

Strengthens the existing dependency supply-chain guidance by making it package-manager-aware and safe before dependency lifecycle scripts are allowed to execute.

• resolves the correct installation boundary for workspaces and independent nested projects;
• distinguishes reproducible installs and full-project audits across npm, pnpm, Yarn Modern, and Yarn Classic;
• documents version-aware native install-script controls and a safe bootstrap path before first execution;
• requires review of forced remediation, lockfile and script-policy changes, signatures/provenance, ownership, and release-age signals;
• keeps detailed version-sensitive commands in the security checklist so the main skill remains concise.

Why

The dependency-upgrade workflow added in #346 correctly delegates audit triage and supply-chain risk to security-and-hardening, but the existing guidance primarily uses npm examples and does not define a complete gate for reviewing lifecycle scripts before they execute.

Known-vulnerability auditing and install-script containment address different risks. This change makes that distinction operational without introducing a third-party dependency or a new workflow.

Scope

• Updates the existing security-and-hardening skill and checklist.
• Preserves the existing frontmatter and routing behavior.
• Adds no new skill, CI workflow, or third-party dependency.
• Does not attempt exhaustive support for every JavaScript package manager; unlisted clients must be checked against the pinned version’s official documentation.

Fixes #391

[addyosmani]

This is a genuinely good hardening pass and the timing is right: blocking dependency lifecycle scripts before the first install is exactly the hole the recent npm postinstall worms drove through, so making it the default posture rather than an afterthought is the correct instinct. I also like that you kept the skill body at the principle level and pushed the version-specific matrix into the checklist, since that's the right split for keeping the skill readable while the detail lives where it belongs. The new "the audit passed, so it's safe" rationalization is a nice touch too, it's the exact wrong mental model this whole section is fighting.

My one real question is maintenance. The per-version bands (pnpm 10.1-10.25 vs 10.26 vs 11+, npm 11.18, Yarn 4.14+) are precise today, but package-manager defaults churn fast, so this matrix is the part most likely to quietly go stale and mislead someone in six months. You've hedged it well with the "verify against the official docs before changing policy" line and the links, which I think is the right call, so I'm not asking you to drop the specificity. It might just be worth a one-line note at the top of that table that it's a point-in-time snapshot to check against current docs, plus a quick spot-check that the newest flag names (npm install-scripts ls, strict-allow-scripts) match current npm, since a couple of those are recent enough that I'd want to be sure. Everything's green and it's a clear improvement over the npm-only version, so I'm inclined to take it once we've figured out how to keep that matrix honest over time.

[federicobartoli]

This is a genuinely good hardening pass and the timing is right: blocking dependency lifecycle scripts before the first install is exactly the hole the recent npm postinstall worms drove through, so making it the default posture rather than an afterthought is the correct instinct. I also like that you kept the skill body at the principle level and pushed the version-specific matrix into the checklist, since that's the right split for keeping the skill readable while the detail lives where it belongs. The new "the audit passed, so it's safe" rationalization is a nice touch too, it's the exact wrong mental model this whole section is fighting.

My one real question is maintenance. The per-version bands (pnpm 10.1-10.25 vs 10.26 vs 11+, npm 11.18, Yarn 4.14+) are precise today, but package-manager defaults churn fast, so this matrix is the part most likely to quietly go stale and mislead someone in six months. You've hedged it well with the "verify against the official docs before changing policy" line and the links, which I think is the right call, so I'm not asking you to drop the specificity. It might just be worth a one-line note at the top of that table that it's a point-in-time snapshot to check against current docs, plus a quick spot-check that the newest flag names (npm install-scripts ls, strict-allow-scripts) match current npm, since a couple of those are recent enough that I'd want to be sure. Everything's green and it's a clear improvement over the npm-only version, so I'm inclined to take it once we've figured out how to keep that matrix honest over time.

Good call. I’ve now checked the version boundary directly rather than treating the current npm behavior as uniform.

The command surface is valid in npm 11.18.0 and 12.0.1, and an isolated npm 12.0.1 probe with a real dependency postinstall confirmed the complete flow:

• the default install succeeded but blocked the unreviewed script;
• npm install-scripts ls surfaced it as pending;
• explicit approval followed by npm rebuild executed it;
• strict-allow-scripts=true failed with ESTRICTALLOWSCRIPTS before execution.

The lower boundary matters too: npm 11.12.1 does not expose the install-scripts namespace at all. I’m therefore going to make the checklist explicit across three cases rather than leaving older clients implicit:

• older npm versions without granular native approvals: bootstrap with lifecycle scripts disabled (npm ci --ignore-scripts, or a project-level ignore-scripts=true policy when persistence is intended), then keep them disabled or upgrade deliberately before allowing reviewed dependency scripts;
• npm 11.18: the approval interface exists, but unreviewed scripts require strict enforcement to become a hard failure;
• npm 12+: unreviewed scripts are skipped by default, while strict mode makes their presence fail the install.

I’ll also add the one-line version-sensitive snapshot note above the matrix and keep the first-party links as the authoritative check for the project’s pinned version. That should preserve the useful precision without silently treating either the newest defaults or the newest commands as universally available.

[federicobartoli]

Implemented in 509281d.
The matrix is now explicitly marked as a point-in-time snapshot and separates:
npm without verified granular approval support;
npm 11.18.x, verified on 11.18.0;
npm 12.x, verified on 12.0.1.
Unlisted or future versions are directed back to the pinned client’s official documentation rather than inheriting newer defaults. All PR checks are green.

[addyosmani]

This is exactly the response I was hoping for, and then some. Actually probing the version boundaries beats the "add a caveat" fix I suggested, and finding that 11.12.1 has no install-scripts namespace at all is the kind of thing that would have quietly bitten someone. The three-case split plus the snapshot note lands it. Concern fully addressed, checks green, good to go from my side. Nice work @federicobartoli.