pnpm-shield 1.0.0

package/README.md

@@ -0,0 +1,402 @@
+# 🛡️ pnpm-shield
+
+> **Supply chain attack protection audit tool for pnpm projects.**
+
+[![npm version](https://img.shields.io/npm/v/pnpm-shield.svg)](https://www.npmjs.com/package/pnpm-shield)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
+[![GitHub](https://img.shields.io/badge/github-manuxstack%2Fpnpm--shield-181717?logo=github)](https://github.com/manuxstack/pnpm-shield)
+
+`pnpm-shield` audits your pnpm project and developer environment against the most common supply chain attack vectors — postinstall script injection, dependency confusion, phantom dependencies, and accidental npm usage. It runs **13 checks**, explains every finding with attack vectors and remediation steps linked to official docs, and can **auto-fix all of them** interactively.
+
+---
+
+## Why this matters
+
+The npm registry is the largest software registry in the world — and one of the most targeted. Attackers abuse `postinstall` scripts, typosquatting, and account takeovers to execute arbitrary code on every machine that runs `npm install` or `pnpm install`. The attacks below all share one trait: **they would have been stopped by a correctly configured pnpm environment.**
+
+| Incident | Year | Attack vector | Source |
+|---|---|---|---|
+| [event-stream backdoor](https://snyk.io/blog/a-post-mortem-of-the-malicious-event-stream-backdoor/) | 2018 | Malicious `postinstall` injected after maintainer handover | Snyk |
+| [eslint-scope credential theft](https://eslint.org/blog/2018/07/postmortem-for-malicious-package-publishes/) | 2018 | Stolen npm credentials → `postinstall` exfiltrated `.npmrc` tokens | ESLint |
+| [ua-parser-js takeover](https://github.com/advisories/GHSA-pjwm-rvh2-c87w) | 2021 | npm account hijacked → cryptominer + RAT via `postinstall` | GitHub Advisory |
+| [dependency confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610) | 2021 | Public package shadows internal name, executes on install | Alex Birsan |
+| [node-ipc sabotage](https://socket.dev/blog/node-ipc-supply-chain-attack) | 2022 | Maintainer added destructive `postinstall` targeting Russian IPs | Socket.dev |
+| [colors + faker protest](https://snyk.io/blog/open-source-npm-packages-colors-faker/) | 2022 | Maintainer corrupted own packages, breaking thousands of projects | Snyk |
+| [xz-utils backdoor](https://openwall.com/lists/oss-security/2024/03/29/4) | 2024 | 2-year social engineering → malicious build script in release tarball | Openwall |
+| [polyfill.io CDN hijack](https://sansec.io/research/polyfill-supply-chain-attack) | 2024 | Domain acquired → CDN injected malicious JS into 100k+ sites | Sansec |
+| [nx package compromise](https://arcticwolf.com/resources/blog/nx-package-compromise-2025/) | Aug 2025 | Malicious `nx` versions published → credential theft + filesystem scan | Arctic Wolf |
+| [Shai-Hulud worm](https://www.wiz.io/blog/shai-hulud-npm-worm) | Sep 2025 | Self-replicating npm worm stole cloud tokens and re-published infected packages | Wiz |
+| [axios maintainer compromise](https://arcticwolf.com/resources/blog/axios-supply-chain-attack-2026/) | Mar 2026 | Hijacked maintainer account → `postinstall` RAT in `axios` v1.14.1 | Arctic Wolf |
+| [TanStack / TeamPCP campaign](https://cybernews.com/security/teamPCP-tanstack-supply-chain/) | Apr 2026 | Poisoned CI/CD cache → malicious publishes across TanStack ecosystem | Cybernews |
+
+> 💡 **Every `postinstall` attack in this list is blocked by `ignore-scripts=true`.** The dependency confusion attacks are mitigated by a strict `pnpm-lock.yaml` and the `packageManager` field enforced by Corepack. `pnpm-shield` checks for all of these protections.
+
+
+
+---
+
+## Installation
+
+```bash
+# Run directly without installing (recommended for one-off audits):
+pnpm dlx pnpm-shield
+
+# Install globally:
+pnpm add -g pnpm-shield
+
+# Add as a dev dependency in your project:
+pnpm add -D pnpm-shield
+```
+
+> **Zero production dependencies.** Everything uses Node.js built-ins.
+
+---
+
+## Usage
+
+```bash
+# Run in the root of your project:
+pnpm-shield
+
+# Same command, shorter alias:
+pnpm-check
+
+# CI mode — non-interactive, exits with code 1 on failures:
+pnpm-shield --ci
+
+# Show help:
+pnpm-shield --help
+
+# Show version:
+pnpm-shield --version
+```
+
+---
+
+## Interactive menu
+
+After the audit runs, an interactive prompt lets you explore and fix findings without leaving the terminal.
+
+### Commands
+
+| Command | Action |
+|---------|--------|
+| `?` | Open an **arrow-key browser** across all 13 checks — navigate with ↑↓, press Enter to read documentation |
+| `?N` | Read docs for check N directly, e.g. `?3` |
+| `fix` | Open a **visual multi-selector** for fixes — navigate with ↑↓, toggle with Space, confirm with Enter |
+| `all` | Apply all auto-fixable items at once |
+| `q` | Quit |
+
+### Documentation panel
+
+Every check has an integrated documentation panel showing:
+- **Why it matters** — the security rationale
+- **Attack vector** — a concrete attack scenario
+- **How to fix** — step-by-step remediation commands
+- **Official references** — links to pnpm docs, Node.js docs, and security post-mortems
+
+---
+
+## What it checks
+
+`pnpm-shield` runs **13 security checks** across three categories. All non-passing checks support **auto-fix**.
+
+### 🖥 Environment
+
+| # | Check | Severity | Auto-fix |
+|---|-------|----------|---------|
+| 1 | pnpm is installed and in PATH | CRITICAL | — |
+| 2 | Shell alias `npm → pnpm` | HIGH | ✅ Adds alias to shell config |
+| 3 | Corepack enabled and managing pnpm | HIGH | ✅ Runs `corepack enable pnpm` |
+| 4 | No foreign lockfiles (`package-lock.json`, `yarn.lock`, `bun.lockb`) | CRITICAL | ✅ Deletes foreign lockfiles |
+
+### ⚙️ pnpm / npm Configuration
+
+| # | Check | Severity | Auto-fix |
+|---|-------|----------|---------|
+| 5 | Global `ignore-scripts = true` | CRITICAL | ✅ `pnpm config set ignore-scripts true` |
+| 6 | Local `.npmrc`: `ignore-scripts=true` | HIGH | ✅ Appends to `.npmrc` |
+| 7 | Local `.npmrc`: `save-exact=true` | MEDIUM | ✅ Appends to `.npmrc` |
+| 8 | Local `.npmrc`: `shamefully-hoist=false` | LOW | ✅ Appends to `.npmrc` |
+| 9 | Local `.npmrc`: `engine-strict=true` | MEDIUM | ✅ Appends to `.npmrc` |
+
+### 📦 package.json Hardening
+
+| # | Check | Severity | Auto-fix |
+|---|-------|----------|---------|
+| 10 | `pnpm.onlyBuiltDependencies` whitelist | HIGH | ✅ Adds `[]` to `package.json` |
+| 11 | `packageManager` field pinned to `pnpm@X.Y.Z` | HIGH | ✅ Sets current pnpm version |
+| 12 | `engines.node` range specified | MEDIUM | ✅ Sets `>=` current Node major |
+| 13 | `pnpm-lock.yaml` present | HIGH | ✅ Runs `pnpm install` |
+
+---
+
+## Grading
+
+After the audit, your project receives a security grade:
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| **A+** | ≥ 92% | Fortress — all critical paths hardened |
+| **A**  | ≥ 84% | Excellent — minor optional improvements available |
+| **B**  | ≥ 76% | Good — a few medium-risk items to address |
+| **C**  | ≥ 60% | Fair — notable gaps that should be closed |
+| **D**  | < 60% | Needs attention — critical or multiple high failures |
+
+Score = passed checks + 0.5 × warnings.
+
+---
+
+## Check details
+
+### 1. pnpm installed — CRITICAL
+pnpm is the only mainstream package manager with `onlyBuiltDependencies` whitelisting, per-project `ignore-scripts`, and a content-addressable store with integrity verification.
+
+```bash
+corepack enable pnpm
+# or:
+curl -fsSL https://get.pnpm.io/install.sh | sh
+```
+
+📎 [pnpm Installation](https://pnpm.io/installation)
+
+---
+
+### 2. Shell alias `npm → pnpm` — HIGH ✅
+Even with pnpm fully configured, typing `npm install` by muscle memory invokes the real npm binary. npm ignores your `.npmrc`, your `pnpm-lock.yaml`, and your `onlyBuiltDependencies` whitelist.
+
+```bash
+echo 'alias npm=pnpm' >> ~/.zshrc && source ~/.zshrc
+```
+
+📎 [Typosquatting attacks](https://blog.npmjs.org/post/163723642530/crossenv-malware-on-the-npm-registry)
+
+---
+
+### 3. Corepack managing pnpm — HIGH ✅
+Corepack (built into Node.js ≥ 16.9) reads `"packageManager"` in `package.json` and **blocks npm and yarn** project-wide. It also ensures every developer uses the exact same pnpm version.
+
+```bash
+corepack enable
+corepack enable pnpm
+```
+
+📎 [Corepack docs](https://nodejs.org/api/corepack.html) · [pnpm + Corepack](https://pnpm.io/installation#using-corepack)
+
+---
+
+### 4. No foreign lockfiles — CRITICAL ✅
+A `package-lock.json` or `yarn.lock` alongside `pnpm-lock.yaml` creates two conflicting sources of truth. CI systems may pick the wrong one, installing different (potentially malicious) resolved versions.
+
+```bash
+rm package-lock.json yarn.lock bun.lockb
+pnpm install
+git add pnpm-lock.yaml
+```
+
+📎 [Dependency confusion attack](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610)
+
+---
+
+### 5. Global `ignore-scripts=true` — CRITICAL ✅
+Packages can declare `postinstall`, `preinstall`, and `install` lifecycle scripts that run arbitrary shell commands. This is the primary vector for supply chain attacks (event-stream 2018, node-ipc 2022, xz-utils 2024).
+
+```bash
+pnpm config set ignore-scripts true
+```
+
+> **Note:** With `ignore-scripts=true`, packages that legitimately need build scripts (e.g. `esbuild`, `sharp`) will break. Use check #10 (`onlyBuiltDependencies`) to whitelist exactly those packages.
+
+📎 [pnpm ignore-scripts](https://pnpm.io/npmrc#ignore-scripts) · [event-stream post-mortem](https://snyk.io/blog/a-post-mortem-of-the-malicious-event-stream-backdoor/)
+
+---
+
+### 6. Local `.npmrc`: `ignore-scripts=true` — HIGH ✅
+The global config can differ across machines and CI environments. A local `.npmrc` commits the rule into the repository, protecting every developer and every CI runner regardless of their global config.
+
+```bash
+echo "ignore-scripts=true" >> .npmrc
+git add .npmrc
+```
+
+---
+
+### 7. `save-exact=true` — MEDIUM ✅
+By default pnpm saves deps with a `^` prefix (e.g. `^1.2.3`), allowing any compatible update. An attacker who compromises a package can publish `1.2.4` with malicious code and every project using `^1.2.3` adopts it on the next install.
+
+```bash
+echo "save-exact=true" >> .npmrc
+```
+
+📎 [Semver hijacking](https://snyk.io/blog/ten-npm-security-best-practices/)
+
+---
+
+### 8. `shamefully-hoist=false` — LOW ✅
+pnpm uses a strict, isolated `node_modules` layout by default. `shamefully-hoist=true` flattens it like npm, allowing packages to import dependencies they never declared (**phantom dependencies**).
+
+```bash
+echo "shamefully-hoist=false" >> .npmrc
+```
+
+📎 [Phantom dependencies](https://pnpm.io/blog/2020/05/27/flat-node-modules-is-not-the-only-way)
+
+---
+
+### 9. `engine-strict=true` — MEDIUM ✅
+Some security patches are Node.js-version-specific. Running code on an EOL Node version may miss critical fixes.
+
+```bash
+echo "engine-strict=true" >> .npmrc
+```
+
+📎 [Node.js release schedule](https://nodejs.org/en/about/previous-releases)
+
+---
+
+### 10. `pnpm.onlyBuiltDependencies` — HIGH ✅
+Even with `ignore-scripts=true`, you may need certain packages to run build scripts (e.g. `esbuild`, `sharp`). This whitelist gives surgical, auditable control over which packages may run scripts.
+
+```jsonc
+// package.json
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "sharp"]
+  }
+}
+```
+
+An **empty array `[]`** blocks all postinstall scripts without exception.
+
+📎 [onlyBuiltDependencies](https://pnpm.io/package_json#pnpmonlybuiltdependencies)
+
+---
+
+### 11. `packageManager` field — HIGH ✅
+Tells Corepack the exact package manager and version the project requires. Corepack will then block npm and yarn and auto-download the correct pnpm version for any contributor.
+
+```jsonc
+// package.json
+{
+  "packageManager": "pnpm@11.1.1"
+}
+```
+
+📎 [packageManager field](https://nodejs.org/api/packages.html#packagemanager)
+
+---
+
+### 12. `engines.node` range — MEDIUM ✅
+Declares the minimum Node.js version. Combined with `engine-strict=true`, pnpm refuses to install on incompatible environments, preventing use of EOL runtimes with known CVEs.
+
+```jsonc
+// package.json
+{
+  "engines": { "node": ">=20" }
+}
+```
+
+📎 [engines field](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines)
+
+---
+
+### 13. `pnpm-lock.yaml` present — HIGH ✅
+The lockfile pins exact resolved versions AND SHA-512 integrity hashes for every package in the full dependency tree. Without it, `pnpm install` resolves versions fresh each time and can silently adopt a compromised release.
+
+```bash
+pnpm install      # generates pnpm-lock.yaml
+git add pnpm-lock.yaml
+# Never add pnpm-lock.yaml to .gitignore!
+```
+
+📎 [pnpm lockfile format](https://pnpm.io/lockfile-format) · [Should lockfiles be committed?](https://pnpm.io/faq#should-lockfile-be-committed)
+
+---
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/security.yml
+name: Security Audit
+
+on: [push, pull_request]
+
+jobs:
+  pnpm-shield:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: pnpm dlx pnpm-shield --ci
+```
+
+### Native git pre-commit hook (no extra dependencies)
+
+```bash
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/sh
+pnpm-shield --ci
+EOF
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+## Recommended baseline configuration
+
+**`.npmrc`**
+```ini
+ignore-scripts=true
+save-exact=true
+shamefully-hoist=false
+engine-strict=true
+```
+
+**`package.json` additions**
+```jsonc
+{
+  "packageManager": "pnpm@11.1.1",
+  "engines": { "node": ">=20" },
+  "pnpm": {
+    "onlyBuiltDependencies": []
+  }
+}
+```
+
+---
+
+## Project structure
+
+```
+pnpm-shield.js        ← Entry point (20 lines)
+lib/
+  colors.js           ← ANSI color constants
+  docs.js             ← Per-check documentation + official references
+  checks.js           ← Runs all 13 security checks
+  ui.js               ← Terminal output (header, results, doc panel, summary)
+  selector.js         ← Raw TTY arrow-key interactive selector (zero deps)
+  fixes.js            ← Auto-fix implementations for all 13 checks
+  runner.js           ← Orchestrates the full audit + interactive menu
+```
+
+---
+
+## Contributing
+
+Pull requests are welcome. To add a new check:
+
+1. Add the result in `lib/checks.js` with a `docKey` and `fix` key
+2. Add documentation in `lib/docs.js` with `why`, `attack`, `fix`, and `refs`
+3. Add a fix handler in `lib/fixes.js`
+
+---
+
+## License
+
+MIT

package/lib/checks.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { sectionHeader } = require('./ui');
+
+// ─── Result builder ───────────────────────────────────────────────────────────
+function makeResult(status, severity, label, detail, tip, fix, docKey) {
+  return { status, severity, label, detail: detail || '', tip: tip || '', fix: fix || null, docKey: docKey || null };
+}
+
+function tryExec(cmd) {
+  try { return execSync(cmd, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim(); }
+  catch { return null; }
+}
+
+// ─── Main check runner ────────────────────────────────────────────────────────
+function runChecks(cwd) {
+  const results = [];
+
+  const pkgPath  = path.join(cwd, 'package.json');
+  const rcPath   = path.join(cwd, '.npmrc');
+  const lockNpm  = path.join(cwd, 'package-lock.json');
+  const lockYarn = path.join(cwd, 'yarn.lock');
+  const lockBun  = path.join(cwd, 'bun.lockb');
+  const lockPnpm = path.join(cwd, 'pnpm-lock.yaml');
+
+  // ── Section 1: Environment ──────────────────────────────────────────────────
+  sectionHeader('🖥 ', 'Environment');
+
+  // C1 — pnpm installed
+  const pnpmVer = tryExec('pnpm --version');
+  results.push(pnpmVer
+    ? makeResult('pass', 'CRITICAL', 'pnpm is installed and in PATH', `v${pnpmVer}`, '', null, 'pnpm_installed')
+    : makeResult('fail', 'CRITICAL', 'pnpm not found in PATH', '', 'Run: npm install -g pnpm  (one-time bootstrap only)', null, 'pnpm_installed')
+  );
+
+  // C2 — npm → pnpm alias
+  const shellCfgs = [
+    path.join(os.homedir(), '.zshrc'),
+    path.join(os.homedir(), '.bashrc'),
+    path.join(os.homedir(), '.bash_profile'),
+    path.join(os.homedir(), '.profile'),
+    path.join(os.homedir(), '.config', 'fish', 'config.fish'),
+  ];
+  let aliasFile = null;
+  for (const cfg of shellCfgs) {
+    if (fs.existsSync(cfg)) {
+      const txt = fs.readFileSync(cfg, 'utf8');
+      if (/alias\s+npm\s*=\s*['"]?pnpm['"]?/.test(txt) || /alias\s+npm\s+pnpm/.test(txt)) {
+        aliasFile = cfg; break;
+      }
+    }
+  }
+  results.push(aliasFile
+    ? makeResult('pass', 'HIGH', 'Shell alias: npm → pnpm', path.basename(aliasFile), '', null, 'npm_alias')
+    : makeResult('fail', 'HIGH', 'No npm → pnpm shell alias found', '',
+        "Typing 'npm install' bypasses all pnpm protections. Add: alias npm=pnpm", 'npmAlias', 'npm_alias')
+  );
+
+  // C3 — Corepack
+  const corepackVer = tryExec('corepack --version');
+  if (corepackVer) {
+    const pnpmWhich = tryExec('which pnpm') || '';
+    results.push(pnpmWhich.includes('corepack')
+      ? makeResult('pass', 'HIGH', 'Corepack is enabled and managing pnpm', `corepack v${corepackVer}`, '', null, 'corepack')
+      : makeResult('warn', 'HIGH', 'Corepack installed but pnpm not managed by it', '', 'Run: corepack enable pnpm', 'corepack', 'corepack')
+    );
+  } else {
+    results.push(makeResult('warn', 'HIGH', 'Corepack not detected', '',
+      'Enable with: corepack enable', 'corepack', 'corepack'));
+  }
+
+  // C4 — No foreign lockfiles
+  const foreign = [
+    { file: lockNpm, name: 'package-lock.json' },
+    { file: lockYarn, name: 'yarn.lock' },
+    { file: lockBun, name: 'bun.lockb' },
+  ].filter(l => fs.existsSync(l.file));
+
+  results.push(foreign.length === 0
+    ? makeResult('pass', 'CRITICAL', 'No foreign lockfiles detected', 'package-lock.json / yarn.lock / bun.lockb absent', '', null, 'foreign_locks')
+    : makeResult('fail', 'CRITICAL', `Foreign lockfile(s) found: ${foreign.map(l => l.name).join(', ')}`, '',
+        "Delete them and run 'pnpm install' to re-lock with pnpm", 'foreignLocks', 'foreign_locks')
+  );
+
+  // ── Section 2: pnpm / npm Configuration ────────────────────────────────────
+  sectionHeader('⚙️ ', 'pnpm / npm Configuration');
+
+  // C5 — Global ignore-scripts
+  const globalIgnore = tryExec('pnpm config get ignore-scripts');
+  results.push(globalIgnore === 'true'
+    ? makeResult('pass', 'CRITICAL', 'Global ignore-scripts = true', 'Blocks postinstall code injection system-wide', '', null, 'global_ignore_scripts')
+    : makeResult('fail', 'CRITICAL', `Global ignore-scripts = ${globalIgnore ?? 'unknown'}`, '',
+        'Run: pnpm config set ignore-scripts true', 'globalIgnoreScripts', 'global_ignore_scripts')
+  );
+
+  // Read local .npmrc once
+  const npmrc = fs.existsSync(rcPath) ? fs.readFileSync(rcPath, 'utf8') : '';
+  const hasRc = fs.existsSync(rcPath);
+
+  // C6 — Local .npmrc ignore-scripts
+  if (!hasRc) {
+    results.push(makeResult('fail', 'HIGH', 'No local .npmrc file found', '',
+      'Create .npmrc and add: ignore-scripts=true', 'localNpmrc', 'local_npmrc'));
+  } else if (npmrc.includes('ignore-scripts=true')) {
+    results.push(makeResult('pass', 'HIGH', 'Local .npmrc: ignore-scripts=true', 'Protection locked at project level', '', null, 'local_npmrc'));
+  } else {
+    results.push(makeResult('fail', 'HIGH', 'Local .npmrc: ignore-scripts=true missing', '',
+      "Add 'ignore-scripts=true' to .npmrc", 'localNpmrc', 'local_npmrc'));
+  }
+
+  // C7 — save-exact
+  results.push(npmrc.includes('save-exact=true')
+    ? makeResult('pass', 'MEDIUM', 'Local .npmrc: save-exact=true', 'Pins exact dep versions — no semver drift', '', null, 'save_exact')
+    : makeResult('warn', 'MEDIUM', 'Local .npmrc: save-exact not set', '',
+        "Add 'save-exact=true' to pin exact versions", 'saveExact', 'save_exact')
+  );
+
+  // C8 — shamefully-hoist
+  if (npmrc.includes('shamefully-hoist=false')) {
+    results.push(makeResult('pass', 'MEDIUM', 'Local .npmrc: shamefully-hoist=false', 'Strict dep isolation enforced', '', null, 'shamefully_hoist'));
+  } else if (npmrc.includes('shamefully-hoist=true')) {
+    results.push(makeResult('fail', 'MEDIUM', 'Local .npmrc: shamefully-hoist=true (flat node_modules!)', '',
+      "Set 'shamefully-hoist=false' — flat installs allow phantom dependency attacks", 'shamefullyHoist', 'shamefully_hoist'));
+  } else {
+    results.push(makeResult('warn', 'LOW', 'Local .npmrc: shamefully-hoist not set explicitly', '',
+      "pnpm defaults to false (safe), but add 'shamefully-hoist=false' to be explicit", 'shamefullyHoist', 'shamefully_hoist'));
+  }
+
+  // C9 — engine-strict
+  results.push(npmrc.includes('engine-strict=true')
+    ? makeResult('pass', 'MEDIUM', 'Local .npmrc: engine-strict=true', 'Rejects mismatched Node.js versions', '', null, 'engine_strict')
+    : makeResult('warn', 'MEDIUM', 'Local .npmrc: engine-strict not set', '',
+        "Add 'engine-strict=true' to enforce engines.node range", 'engineStrict', 'engine_strict')
+  );
+
+  // ── Section 3: package.json Hardening ──────────────────────────────────────
+  sectionHeader('📦', 'package.json Hardening');
+
+  if (!fs.existsSync(pkgPath)) {
+    results.push(makeResult('warn', 'HIGH', 'package.json not found', '', "Run 'pnpm init' first", null, null));
+  } else {
+    let pkg = null;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); }
+    catch { results.push(makeResult('fail', 'CRITICAL', 'package.json is not valid JSON', '', 'Fix the syntax error', null, null)); }
+
+    if (pkg) {
+      // C10 — onlyBuiltDependencies
+      if (pkg.pnpm && Array.isArray(pkg.pnpm.onlyBuiltDependencies)) {
+        const n = pkg.pnpm.onlyBuiltDependencies.length;
+        results.push(makeResult('pass', 'HIGH', 'pnpm.onlyBuiltDependencies whitelist present',
+          n === 0 ? 'Empty — blocks ALL postinstall scripts' : `${n} package(s) allowed`, '', null, 'only_built_deps'));
+      } else {
+        results.push(makeResult('warn', 'HIGH', 'pnpm.onlyBuiltDependencies not configured', '',
+          "Add 'pnpm.onlyBuiltDependencies: []' to block all postinstall scripts", 'onlyBuiltDeps', 'only_built_deps'));
+      }
+
+      // C11 — packageManager
+      if (pkg.packageManager && pkg.packageManager.startsWith('pnpm@')) {
+        results.push(makeResult('pass', 'HIGH', `packageManager = "${pkg.packageManager}"`,
+          'Corepack can enforce this and block npm/yarn', '', null, 'package_manager_field'));
+      } else {
+        results.push(makeResult('fail', 'HIGH',
+          `packageManager field is ${pkg.packageManager ? `"${pkg.packageManager}"` : 'absent'}`, '',
+          'Add: "packageManager": "pnpm@X.Y.Z" to enable Corepack enforcement',
+          'packageManager', 'package_manager_field'));
+      }
+
+      // C12 — engines.node
+      if (pkg.engines && pkg.engines.node) {
+        results.push(makeResult('pass', 'MEDIUM', `engines.node = "${pkg.engines.node}"`,
+          'Rejects incompatible Node versions (needs engine-strict=true)', '', null, 'engines_node'));
+      } else {
+        results.push(makeResult('warn', 'MEDIUM', 'No engines.node range specified', '',
+          'Add: "engines": { "node": ">=20" }', 'enginesNode', 'engines_node'));
+      }
+
+      // C13 — pnpm-lock.yaml
+      results.push(fs.existsSync(lockPnpm)
+        ? makeResult('pass', 'HIGH', 'pnpm-lock.yaml found', 'Project is locked with pnpm', '', null, 'pnpm_lock')
+        : makeResult('warn', 'HIGH', 'pnpm-lock.yaml not found', '', "Run 'pnpm install' to generate it", 'pnpmInstall', 'pnpm_lock')
+      );
+    }
+  }
+
+  return results;
+}
+
+module.exports = { runChecks };

package/lib/colors.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/** Shared ANSI color constants. */
+const c = {
+  green:   '\x1b[32m',
+  red:     '\x1b[31m',
+  yellow:  '\x1b[33m',
+  orange:  '\x1b[38;5;208m',
+  blue:    '\x1b[34m',
+  cyan:    '\x1b[36m',
+  magenta: '\x1b[35m',
+  white:   '\x1b[97m',
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  bg: {
+    red:    '\x1b[41m',
+    green:  '\x1b[42m',
+    yellow: '\x1b[43m',
+    blue:   '\x1b[44m',
+  },
+};
+
+module.exports = c;