feat(supply-chain): resolve npm dependencies through the lockfile

[Mark2Mac]

The gap

SC4 reads package.json and stops there. For npm that is the smaller half of the problem:

• the manifest lists direct dependencies, and npm's default is a range ("^4.18.0"). After fix(supply-chain): SC4 must not claim a vulnerability it did not verify (#318) #319 a range correctly resolves to no version, so there is nothing to ask OSV about — honest, but silent.
• the versions actually installed, direct and transitive, are in package-lock.json. That file is never read.

Python does not have this gap: #263 already reads uv.lock and poetry.lock and prefers those versions. npm had no lockfile support at all.

The change

Read npm lockfiles — package-lock.json and npm-shrinkwrap.json — and use them the same way:

1. Resolve manifest ranges. "commander": "^11.0.0" with a lockfile is 11.1.0. Note it is not 11.0.0, which is what the old caret-stripping produced and what a reader would guess.
2. Scan the lockfile itself, so transitive dependencies are covered — the treatment uv.lock already gets.

Both layouts are handled: lockfileVersion 2/3 (keyed by install path, including nested node_modules/a/node_modules/b) and version 1 (nested dependencies). The root entry is the project itself and is skipped; aliased installs use the declared name.

Three details that are load-bearing

Each of these is a silent-wrong-answer trap, so each has a test that fails without it.

Deduplication is by name and version. npm installs the same package at several versions routinely, nesting the copies it cannot hoist. Keying on the name alone keeps whichever entry came first and drops the rest — and the dropped copy is on disk, so a vulnerable one would simply go unreported. On the corpus below, 12 packages are installed at two versions each; none of those 24 versions happens to carry an advisory, so this changed no finding here. It removes a class of miss, not a count.

The ecosystem maps are kept separate. semver, packaging and requests all exist in both PyPI and npm. One shared map would answer a Python question with an npm version. Name normalization differs for the same reason: _normalize_package_name folds _ into -, which is right for PyPI and wrong for npm, where string_decoder and string-decoder are two different real packages.

Manifest ranges resolve to the direct install. A range in package.json names a direct dependency, so it resolves to the top-level copy — not to a nested one that exists only to satisfy some other package's constraint.

Cost

Looking a line number up per package is quadratic: both the search and the offset-to-line conversion restart at the top of the file each time. One indexing pass instead:

  packages     per-package search     one pass
       500                  0.166s      0.014s
      2000                  0.724s      0.048s
      5000                  6.263s      0.180s
     20000                        —      0.439s

5000-entry lockfiles are ordinary, so the quadratic version was not a theoretical concern. A regression test asserts 2000 packages parse in under a second.

Measured

5 lockfiles found in Claude Code plugins on a real machine, 458 installed packages:

   3 packages    0 SC4   polito-batch
  47 packages    1 SC4   superpowers-chrome
 123 packages    5 SC4   superpowers-chrome/mcp
   1 package     1 SC4   superpowers/tests/brainstorm-server
 287 packages    4 SC4   cli-anything/sketch/agent-harness

TOTAL            11 SC4 findings, 7 HIGH — none of them visible before

Each was re-verified by querying OSV directly for that exact version, not just trusting the analyzer:

package	advisories	where
@modelcontextprotocol/sdk==1.20.1	3 (CVE-2026-25536, CVE-2026-0621, CVE-2025-66414)	inside an MCP server plugin
undici==7.25.0	12	transitive
ws==8.19.0	2	transitive
path-to-regexp==8.3.0	2	transitive
js-yaml==3.14.2, picomatch==2.3.1, brace-expansion==1.1.12	2, 2, 4	transitive

None of these appear in any package.json. They are exactly the dependencies a manifest-only scan cannot see, and the first row is the kind an agent-security scanner should not be missing.

Volume stays sane: 458 packages produced 11 findings, not hundreds — the exact-version match is what keeps it quiet.

Scope

yarn.lock and pnpm-lock.yaml are deliberately not here. They are different formats with their own parsing problems, and bundling them would make this change harder to review than it needs to be. The seam they would plug into — _npm_lock_entries returning (name, version, line, depth) — is the same one this PR adds.

Tests

Both lockfile layouts, aliased installs, the skipped root entry, malformed JSON, ecosystem separation, npm name normalization, exact-pin-beats-lockfile precedence, multi-version installs, direct-vs-nested resolution, and the parse-cost regression. Plus two analyzer-level ones:

• a transitive dependency reported from the lockfile alone;
• a manifest range going from LOW unverifiable to a version-matched HIGH once the lockfile is present — the case fix(supply-chain): SC4 must not claim a vulnerability it did not verify (#318) #319 deliberately made quiet, now made verifiable instead.

Full suite green (1751 passed), ruff check and ruff format --check clean at 0.15.19.

Relationship to #323

Independent, and measured rather than assumed: merging #323 into this branch is a clean merge, and the combined tree passes. Either can land first.

They do compound, though. The tests here build manifests with json.dumps(..., indent=2) on purpose, because a compact package.json still yields zero dependencies on main — the line-oriented scan never enters the dependency section, which is what #323 fixes. Until that lands, range resolution has nothing to resolve on a one-line manifest. The lockfile scan, which is where all 11 findings above come from, is unaffected either way.

[rng1995]

[Automated SkillSpector Review]

Approved. The lockfile parser covers npm lockfile v1 and v2/v3 layouts, preserves distinct installed versions, resolves manifest ranges only from the shallowest direct install, keeps npm normalization separate from PyPI, and avoids quadratic line lookup. Exact-head verification passed all 270 supply-chain pattern tests plus Ruff lint and format checks.

[Mark2Mac]

Rebased onto main at 2b408ee (2.9.3) to clear the conflict. New head 33447d3.

The conflict was with #357, which added SC8 to the same module. It was confined to the import block — #357 adds os and pathlib.Path, this PR adds json and collections.abc.Callable — and the resolution is the union of the two.

The approved content is unchanged. git range-diff 7e9c19d..79771bf upstream/main..33447d3 reports one hunk, and that hunk is the import block; every other hunk in the commit is identical to the head you approved. The push dismissed the approval automatically, so this is a re-request rather than a new proposal.

Verified after the rebase, on the exact head:

• pytest -m "not integration and not provider" tests/ — 2051 passed, 13 skipped, 38 deselected, 4 xfailed
• ruff check and ruff format --check — clean
• Signed-off-by present

SC8 and this PR do not interact: SC8 flags shipped bytecode during discovery, the lockfile resolution runs over dependency manifests.

[Mark2Mac]

Field evidence from a package installed today, which sharpens one claim in the PR body.

text-to-cad (10 skills, installed from the official marketplace) ships 9 package-lock.json files. main reports 23 SC4 findings on it, read from the manifests; most are unpinned and therefore unverifiable. With this PR the lockfiles resolve to 862 distinct (name, version) installs, and querying every one of them against OSV returns 18 vulnerable:

package	versions	advisories
hono	4.12.18	16
next	16.2.6	9
brace-expansion	1.1.14 and 5.0.6	3 each
js-yaml, ip-address, fast-uri, postcss	—	3 each
nanoid	3.3.11 and 3.3.12	2 each
postcss	8.5.10 and 8.5.14	2–3 each
vite, @babel/core, esbuild, sharp, qs, body-parser, @hono/node-server	—	1–2 each

The correction. The PR body says the name-and-version deduplication removes a class of miss "without changing any finding count", because on the corpus I had measured, it didn't. On this package it does: brace-expansion, nanoid and postcss each appear at two distinct vulnerable versions, so deduplicating by name alone silently drops 3 of the 18. That claim was accurate when written and is now too weak — the class it removes is not hypothetical.

For completeness on severity: none of the 18 are installed on this machine (no node_modules anywhere under the package, and the viewer the skill actually launches declares no dependencies and serves a prebuilt bundle). 14 are in docs/ (the project website) and 5 in viewer/ (its build tooling). The point is not that this package is dangerous — it is that main reports its entire transitive surface as absent, and 18 vulnerable installs is what "absent" was hiding.