[FEATURE] Add npm supply chain defense hook example

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When Claude Code runs npm install / yarn add / pnpm add on behalf of users, there's no built-in mechanism to verify whether the target package is safe before installation. This opens the door to:

• Typosquatting — lodash vs l0dash
• Known vulnerabilities — installing lodash@4.17.20 with prototype pollution CVEs
• Malicious install scripts — postinstall exfiltrating credentials
• Nonexistent packages — hallucinated package names that don't exist on npm

The current examples/hooks/ has a great starting point with bash_command_validator_example.py, but there's no security-focused hook example — particularly for supply chain defense, which is one of the most common attack vectors in the npm ecosystem.

Proposed Solution

A PreToolUse hook that intercepts all npm install / yarn add / pnpm add / bun add commands and performs automated safety checks before allowing installation.

Design: fail-closed — if parsing fails, network is unreachable for core signals, or a version can't be resolved, the hook blocks the install.

What it checks

| Signal | Source | On failure |
|--------|--------|------------|
| Package exists on registry | npm registry API | Block |
| Known vulnerabilities (CVE/GHSA) | OSV.dev | Block |
| Version resolution (tags, ranges) | Registry dist-tags + npm view | Block |
| Install scripts (preinstall/postinstall) | Version-specific manifest | Block (if combined with low downloads) |
| Weekly download count | npm downloads API | Warning |
| Publish recency (< 7 days) | Registry metadata | Warning |

Key features

• Per-PM CLI parsing — validates flags against arity tables for npm/yarn/pnpm/bun; unknown flags are blocked to prevent parser bypass
• Version resolution — exact semver used directly; dist-tags resolved from registry; ranges resolved via npm view with 3s timeout; unresolvable specs are blocked
• Whitelist support — safe packages (e.g., esbuild, sharp) skip checks; path configurable via env var
• Minimal context cost — safe packages produce one line of output (~10 tokens); only suspicious packages expand

The hook works standalone, but is designed as layer 2 of a 3-layer defense (.npmrc script blocking → this hook → Semgrep supply chain scan).

Alternative Solutions

• Manual review before every install — doesn't scale when Claude Code installs packages autonomously during coding sessions
• Running npm audit after install — too late; malicious postinstall scripts have already executed
• Using .npmrc ignore-scripts=true alone — blocks install scripts but doesn't catch typosquatting, nonexistent packages, or known CVEs
• Relying on Claude's judgment — the model can hallucinate package names or not know about recent CVEs

I'm currently using a combination of all the above, but a PreToolUse hook that checks before installation is the only approach that catches all these vectors in one place.

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

Scenario: You're building a Node.js project with Claude Code and ask it to "add a date formatting library."

1. Claude decides to run npm install dayjs
2. The PreToolUse hook intercepts the command
3. Hook queries the npm registry — package exists, 20M downloads/week, no install scripts, no known CVEs
4. Hook outputs: ✓ dayjs — 20M/week, 2 maintainers
5. Installation proceeds normally

Now the dangerous version:

1. Claude hallucinates and runs npm install dayjss (typo)
2. Hook queries the registry — package not found (or exists with 12 downloads/week and a postinstall script)
3. Hook outputs: 🚫 dayjss — BLOCKED (not found on npm registry)
4. Installation is blocked, Claude is informed and can retry with the correct package name

Another scenario:

1. Claude runs npm install lodash@4.17.20
2. Hook resolves the version, queries OSV.dev — 3 known prototype pollution CVEs
3. Hook outputs: 🚫 lodash@4.17.20 — BLOCKED (3 known vuln(s): GHSA-...)
4. Installation is blocked

Additional Context

Reference implementation with full source, 42 regression tests (31 unit + 11 live), and documentation (English + Traditional Chinese):
https://github.com/dianyike/claude-code-insights/tree/main/examples/npm-supply-chain-defense

Dependencies: Only python3 (pre-installed on macOS/Linux). No additional packages required.

Testing:

• Unit tests use whitelisted packages — no network dependency, fully reproducible
• Live tests hit real registry/OSV endpoints

Happy to adapt the structure to match the repo's examples/hooks/ conventions and submit a PR if there's interest.