@nexus_js/audit 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @nexus_js/audit
+
+Nexus Dependency Auditor — OSV CVE scanning, offline cache, supply chain risk analysis, and build-time blocking.
+
+## Documentation
+
+All guides, API reference, and examples live on **[nexusjs.dev](https://nexusjs.dev)**.
+
+## Links
+
+- **Website:** [https://nexusjs.dev](https://nexusjs.dev)
+- **Repository:** [github.com/bierfor/nexus](https://github.com/bierfor/nexus) (see `packages/audit/`)
+- **Issues:** [github.com/bierfor/nexus/issues](https://github.com/bierfor/nexus/issues)
+
+## License
+
+MIT © Nexus contributors

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nexus_js/audit",
+  "version": "0.6.0",
+  "description": "Nexus Dependency Auditor — OSV CVE scanning, offline cache, supply chain risk analysis, and build-time blocking",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "nexus",
+    "security",
+    "audit",
+    "cve",
+    "osv",
+    "supply-chain",
+    "framework",
+    "full-stack",
+    "svelte",
+    "islands",
+    "ssr",
+    "vite",
+    "server-actions"
+  ],
+  "license": "MIT",
+  "homepage": "https://nexusjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bierfor/nexus.git",
+    "directory": "packages/audit"
+  },
+  "bugs": {
+    "url": "https://github.com/bierfor/nexus/issues"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,322 @@
+/**
+ * Nexus Audit Engine — CVE Database via OSV (Open Source Vulnerabilities).
+ *
+ * Uses the free, open Google OSV API (https://osv.dev) — no API key required.
+ * Responses are cached locally in ~/.nexus/cache/ for offline operation.
+ *
+ * API reference: https://google.github.io/osv.dev/api/
+ *
+ * Cache strategy:
+ *  - Queries are cached per package@version for 24h (TTL configurable)
+ *  - On offline: stale cache is used transparently (no error)
+ *  - Cache location: ~/.nexus/cache/osv/{pkg-name}.json
+ *
+ * OSV severity mapping to Nexus levels:
+ *   CRITICAL → critical  (CVSS ≥ 9.0 or explicit CRITICAL)
+ *   HIGH     → high      (CVSS 7.0–8.9)
+ *   MEDIUM   → medium    (CVSS 4.0–6.9)
+ *   LOW      → low       (CVSS < 4.0)
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const OSV_API      = 'https://api.osv.dev/v1/query';
+const CACHE_DIR    = join(homedir(), '.nexus', 'cache', 'osv');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1_000; // 24h
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type VulnSeverity = 'critical' | 'high' | 'medium' | 'low' | 'unknown';
+
+export interface Vulnerability {
+  id:               string;        // e.g. 'GHSA-29mw-wpgm-hmr9' or 'CVE-2024-1234'
+  summary:          string;
+  severity:         VulnSeverity;
+  cvss?:            number | undefined;   // CVSS v3 base score
+  aliases:          string[];             // CVE IDs and other aliases
+  affectedVersions: string;              // human-readable range
+  fixedIn?:         string | undefined;   // first patched version
+  references:       string[];            // advisory URLs
+  published:        string;              // ISO date
+}
+
+export interface AuditResult {
+  package:     string;
+  version:     string;
+  status:      'safe' | 'vulnerable' | 'unknown';
+  vulns:       Vulnerability[];
+  /** True if result came from local cache */
+  cached:      boolean;
+  /** True if result is stale (TTL expired) but used because offline */
+  stale:       boolean;
+  checkedAt:   number;
+}
+
+interface CacheEntry {
+  result:    AuditResult;
+  expiresAt: number;
+  version:   string;
+}
+
+interface OsvResponse {
+  vulns?: OsvVuln[];
+}
+
+interface OsvVuln {
+  id:         string;
+  summary?:   string;
+  aliases?:   string[];
+  published:  string;
+  references?: Array<{ url: string }>;
+  severity?:  Array<{ type: string; score: string }>;
+  affected?:  Array<{
+    package?:  { name: string; ecosystem: string };
+    ranges?:   Array<{ type: string; events: Array<{ introduced?: string; fixed?: string }> }>;
+    versions?: string[];
+  }>;
+}
+
+// ── Cache helpers ─────────────────────────────────────────────────────────────
+
+async function ensureCacheDir(): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+  } catch { /* already exists */ }
+}
+
+function cacheKey(pkg: string): string {
+  return pkg.replace(/\//g, '__').replace(/@/g, '_at_');
+}
+
+async function readCache(pkg: string): Promise<CacheEntry | null> {
+  try {
+    const raw = await readFile(join(CACHE_DIR, `${cacheKey(pkg)}.json`), 'utf-8');
+    return JSON.parse(raw) as CacheEntry;
+  } catch { return null; }
+}
+
+async function writeCache(pkg: string, entry: CacheEntry): Promise<void> {
+  await ensureCacheDir();
+  try {
+    await writeFile(join(CACHE_DIR, `${cacheKey(pkg)}.json`), JSON.stringify(entry, null, 2));
+  } catch { /* cache write failure is non-fatal */ }
+}
+
+// ── OSV API ───────────────────────────────────────────────────────────────────
+
+function parseSeverity(vuln: OsvVuln): { severity: VulnSeverity; cvss?: number } {
+  const severityBlock = vuln.severity ?? [];
+
+  // Look for CVSS v3 score first
+  for (const s of severityBlock) {
+    if (s.type === 'CVSS_V3' || s.type === 'CVSS_V4') {
+      // Extract numeric score from vector string (e.g. "CVSS:3.1/AV:N/AC:L/...")
+      // OSV also sometimes provides the numeric score directly
+      const scoreMatch = s.score.match(/^(\d+\.\d+)$/) ??
+                         s.score.match(/\/(\d+\.\d+)$/);
+      const score = scoreMatch ? parseFloat(scoreMatch[1] ?? '0') : 0;
+      let sev: VulnSeverity = 'unknown';
+      if (score >= 9.0) sev = 'critical';
+      else if (score >= 7.0) sev = 'high';
+      else if (score >= 4.0) sev = 'medium';
+      else if (score > 0)    sev = 'low';
+      return { severity: sev, cvss: score };
+    }
+  }
+
+  // Fall back to explicit severity labels in the ID
+  const id = vuln.id.toUpperCase();
+  if (id.includes('CRITICAL')) return { severity: 'critical' };
+  if (id.includes('HIGH'))     return { severity: 'high' };
+  if (id.includes('MEDIUM'))   return { severity: 'medium' };
+  if (id.includes('LOW'))      return { severity: 'low' };
+  return { severity: 'unknown' };
+}
+
+function parseFixedVersion(vuln: OsvVuln): string | undefined {
+  for (const affected of vuln.affected ?? []) {
+    for (const range of affected.ranges ?? []) {
+      for (const event of range.events ?? []) {
+        if (event.fixed) return event.fixed;
+      }
+    }
+  }
+  return undefined;
+}
+
+function parseAffectedVersions(vuln: OsvVuln): string {
+  const parts: string[] = [];
+  for (const affected of vuln.affected ?? []) {
+    for (const range of affected.ranges ?? []) {
+      let intro: string | undefined;
+      let fixed: string | undefined;
+      for (const event of range.events ?? []) {
+        if (event.introduced) intro = event.introduced;
+        if (event.fixed)      fixed = event.fixed;
+      }
+      if (intro && fixed)   parts.push(`>=${intro} <${fixed}`);
+      else if (intro)       parts.push(`>=${intro}`);
+      else if (fixed)       parts.push(`<${fixed}`);
+    }
+    // Direct version list
+    if (affected.versions?.length) {
+      parts.push(affected.versions.slice(0, 5).join(', ') + (affected.versions.length > 5 ? '...' : ''));
+    }
+  }
+  return parts.join('; ') || 'all versions';
+}
+
+async function fetchFromOSV(pkg: string, version?: string): Promise<OsvResponse | null> {
+  const body: Record<string, unknown> = {
+    package: { name: pkg, ecosystem: 'npm' },
+  };
+  if (version) body['version'] = version;
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 8_000);
+
+  try {
+    const res = await fetch(OSV_API, {
+      method:  'POST',
+      headers: { 'content-type': 'application/json' },
+      body:    JSON.stringify(body),
+      signal:  controller.signal,
+    });
+    if (!res.ok) return null;
+    return await res.json() as OsvResponse;
+  } catch {
+    return null; // network error — caller falls back to cache
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Audits a single package for known CVEs using the OSV database.
+ * Results are cached locally for 24h.
+ *
+ * @param pkg      Package name (e.g. 'lodash' or '@angular/core')
+ * @param version  Specific version to check (e.g. '4.17.20'). If omitted, checks all versions.
+ */
+export async function auditPackage(pkg: string, version?: string): Promise<AuditResult> {
+  const cached = await readCache(pkg);
+  const now    = Date.now();
+
+  // Fresh cache hit
+  if (cached && now < cached.expiresAt) {
+    return { ...cached.result, cached: true, stale: false };
+  }
+
+  // Try to fetch from OSV
+  const osvData = await fetchFromOSV(pkg, version);
+
+  if (!osvData) {
+    // Offline or API error — use stale cache if available
+    if (cached) {
+      return { ...cached.result, cached: true, stale: true };
+    }
+    // No cache at all
+    return {
+      package: pkg, version: version ?? '*',
+      status: 'unknown', vulns: [],
+      cached: false, stale: false,
+      checkedAt: now,
+    };
+  }
+
+  // Parse OSV response
+  const vulns: Vulnerability[] = (osvData.vulns ?? []).map((v) => {
+    const { severity, cvss } = parseSeverity(v);
+    return {
+      id:               v.id,
+      summary:          v.summary ?? 'No summary available',
+      severity,
+      cvss,
+      aliases:          v.aliases ?? [],
+      affectedVersions: parseAffectedVersions(v),
+      fixedIn:          parseFixedVersion(v),
+      references:       (v.references ?? []).map((r) => r.url),
+      published:        v.published,
+    };
+  });
+
+  // Sort by severity
+  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+  vulns.sort((a, b) => SORDER[a.severity] - SORDER[b.severity]);
+
+  const result: AuditResult = {
+    package:   pkg,
+    version:   version ?? '*',
+    status:    vulns.length > 0 ? 'vulnerable' : 'safe',
+    vulns,
+    cached:    false,
+    stale:     false,
+    checkedAt: now,
+  };
+
+  await writeCache(pkg, { result, expiresAt: now + CACHE_TTL_MS, version: version ?? '*' });
+  return result;
+}
+
+/**
+ * Audits all dependencies in a package.json.
+ * Runs queries in parallel (max 6 concurrent) to avoid rate limiting.
+ */
+export async function auditDependencies(
+  deps: Record<string, string>,
+): Promise<Map<string, AuditResult>> {
+  const results = new Map<string, AuditResult>();
+  const entries = Object.entries(deps);
+  const BATCH   = 6;
+
+  for (let i = 0; i < entries.length; i += BATCH) {
+    const batch = entries.slice(i, i + BATCH);
+    const settled = await Promise.allSettled(
+      batch.map(async ([name, versionRange]) => {
+        // Strip semver range prefix for OSV query
+        const version = versionRange.replace(/^[\^~>=<]/, '').split(' ')[0];
+        const result  = await auditPackage(name, version);
+        return [name, result] as [string, AuditResult];
+      }),
+    );
+    for (const s of settled) {
+      if (s.status === 'fulfilled') {
+        results.set(s.value[0], s.value[1]);
+      }
+    }
+  }
+
+  return results;
+}
+
+/** Returns only vulnerable packages, sorted by severity. */
+export function filterVulnerable(results: Map<string, AuditResult>): AuditResult[] {
+  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+  return [...results.values()]
+    .filter((r) => r.status === 'vulnerable')
+    .sort((a, b) => {
+      const as = a.vulns[0]?.severity ?? 'unknown';
+      const bs = b.vulns[0]?.severity ?? 'unknown';
+      return SORDER[as] - SORDER[bs];
+    });
+}
+
+/** Invalidates the local cache for a specific package (forces re-fetch). */
+export async function invalidateCache(pkg: string): Promise<void> {
+  const { unlink } = await import('node:fs/promises');
+  try {
+    await unlink(join(CACHE_DIR, `${cacheKey(pkg)}.json`));
+  } catch { /* file may not exist */ }
+}
+
+/** Clears the entire OSV cache (all packages). */
+export async function clearCache(): Promise<void> {
+  const { rm } = await import('node:fs/promises');
+  try {
+    await rm(CACHE_DIR, { recursive: true, force: true });
+  } catch { /* ignore */ }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @nexus_js/audit — Dependency Auditing & Supply Chain Security
+ *
+ * Provides:
+ *  - CVE scanning via Google OSV (open, no API key)
+ *  - Supply chain risk analysis via npm registry
+ *  - Offline-first local cache (~/.nexus/cache/)
+ *  - Override policy with automatic expiry
+ *  - Build-time blocking for critical vulnerabilities
+ *  - `nexus fix` auto-remediation data
+ */
+
+export {
+  auditPackage,
+  auditDependencies,
+  filterVulnerable,
+  invalidateCache,
+  clearCache,
+} from './engine.js';
+export type { AuditResult, Vulnerability, VulnSeverity } from './engine.js';
+
+export {
+  checkSupplyChain,
+  auditSupplyChain,
+  MFA_NOTE,
+} from './supply-chain.js';
+export type { SupplyChainResult, SupplyChainFlag, SupplyChainRiskLevel } from './supply-chain.js';
+
+export {
+  validateOverride,
+  findOverride,
+  formatOverrides,
+  maxOverrideDate,
+} from './override.js';
+export type { VulnerabilityOverride, AllowVulnerableConfig } from './override.js';
+
+export {
+  scanProject,
+  NexusSecurityError,
+  auditPackage as auditSinglePackage,
+} from './scanner.js';
+export type { ScanOptions, ScanResult } from './scanner.js';

package/src/override.ts

@@ -0,0 +1,168 @@
+/**
+ * Nexus Security Override Policy — "Ghost Wall" exceptions.
+ *
+ * Sometimes a library is vulnerable but:
+ *  - The patch isn't yet on a stable release
+ *  - You only use the affected function in a build-time context (never in production)
+ *  - Your organization has an accepted risk decision documented elsewhere
+ *
+ * Overrides are explicit, time-limited exceptions that:
+ *  1. Require a documented reason
+ *  2. Expire automatically — the build fails again after the date
+ *  3. Are logged in every audit report
+ *  4. Do NOT suppress warnings (only prevent build failure)
+ *
+ * Usage in nexus.config.ts:
+ *
+ * ```ts
+ * import { defineNexusConfig } from '@nexus_js/core';
+ *
+ * export default defineNexusConfig({
+ *   security: {
+ *     hardened: true,
+ *     allowVulnerable: {
+ *       'pdfkit': {
+ *         cve: 'CVE-2024-29415',
+ *         reason: 'Used in build-time PDF generation only. Not in the client bundle. ' +
+ *                 'Patched version releases 2026-05-15 according to maintainer.',
+ *         expires: '2026-06-01',
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * After `expires`, the build fails again, forcing re-evaluation.
+ * If the patch is available, update the dependency. If not, extend the override with a new reason.
+ */
+
+export interface VulnerabilityOverride {
+  /** CVE ID or OSV ID being overridden */
+  cve:     string;
+  /** REQUIRED: human-readable business justification */
+  reason:  string;
+  /**
+   * ISO date string (YYYY-MM-DD). After this date, the override expires
+   * and the build will fail again. Maximum: 180 days from today.
+   */
+  expires: string;
+}
+
+export type AllowVulnerableConfig = Record<string, VulnerabilityOverride>;
+
+export interface OverrideValidation {
+  valid:     boolean;
+  expired:   boolean;
+  daysLeft:  number;
+  message:   string;
+}
+
+/**
+ * Validates an override at build time.
+ * Returns { valid: false } if expired or malformed.
+ */
+export function validateOverride(
+  pkg:      string,
+  override: VulnerabilityOverride,
+): OverrideValidation {
+  const expiry = new Date(override.expires);
+
+  if (isNaN(expiry.getTime())) {
+    return {
+      valid:    false,
+      expired:  false,
+      daysLeft: 0,
+      message:  `[Nexus Security] Override for "${pkg}" has an invalid expiry date: "${override.expires}". Use YYYY-MM-DD format.`,
+    };
+  }
+
+  const now      = new Date();
+  const daysLeft = Math.ceil((expiry.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+  const expired  = daysLeft <= 0;
+
+  if (expired) {
+    return {
+      valid:    false,
+      expired:  true,
+      daysLeft: 0,
+      message:
+        `[Nexus Security] ⛔ Override for "${pkg}" (${override.cve}) EXPIRED on ${override.expires}.\n` +
+        `  Original reason: "${override.reason}"\n` +
+        `  The vulnerability must now be addressed. Options:\n` +
+        `    1. Update "${pkg}" to a patched version\n` +
+        `    2. Replace "${pkg}" with a safe alternative\n` +
+        `    3. Extend the override with a new expiry date (requires fresh justification)`,
+    };
+  }
+
+  // Warn when approaching expiry
+  const warningDays = 14;
+  const warning     = daysLeft <= warningDays
+    ? `\n  ⚠️  Override for "${pkg}" expires in ${daysLeft} day${daysLeft === 1 ? '' : 's'} (${override.expires}).`
+    : '';
+
+  return {
+    valid:    true,
+    expired:  false,
+    daysLeft,
+    message: `[Nexus Security] ⚠️  OVERRIDE ACTIVE for "${pkg}" (${override.cve}).${warning}\n  Reason: "${override.reason}"`,
+  };
+}
+
+/**
+ * Checks if a package+CVE combination is covered by an active override.
+ * Returns null if no override applies (build should fail on critical CVE).
+ */
+export function findOverride(
+  pkg:      string,
+  cveId:    string,
+  overrides: AllowVulnerableConfig,
+): OverrideValidation | null {
+  const override = overrides[pkg];
+  if (!override) return null;
+
+  // Check if the CVE matches (direct or alias)
+  const configCve  = override.cve.toUpperCase().trim();
+  const queryCve   = cveId.toUpperCase().trim();
+
+  if (configCve !== queryCve && !queryCve.includes(configCve) && !configCve.includes(queryCve)) {
+    return null;
+  }
+
+  return validateOverride(pkg, override);
+}
+
+/**
+ * Formats all active overrides for display in audit output.
+ * Groups by status: active, expiring soon, expired.
+ */
+export function formatOverrides(
+  overrides: AllowVulnerableConfig,
+): { active: string[]; expiringSoon: string[]; expired: string[] } {
+  const active:       string[] = [];
+  const expiringSoon: string[] = [];
+  const expired:      string[] = [];
+
+  for (const [pkg, override] of Object.entries(overrides)) {
+    const v = validateOverride(pkg, override);
+    if (v.expired) {
+      expired.push(`${pkg} (${override.cve}) — expired ${override.expires}`);
+    } else if (v.daysLeft <= 14) {
+      expiringSoon.push(`${pkg} (${override.cve}) — expires in ${v.daysLeft} days`);
+    } else {
+      active.push(`${pkg} (${override.cve}) — ${v.daysLeft} days left`);
+    }
+  }
+
+  return { active, expiringSoon, expired };
+}
+
+/**
+ * Returns the maximum safe override duration (180 days from now).
+ * Overrides beyond this are rejected to prevent permanent exceptions.
+ */
+export function maxOverrideDate(): string {
+  const d = new Date();
+  d.setDate(d.getDate() + 180);
+  return d.toISOString().split('T')[0] as string;
+}

package/src/scanner.ts

@@ -0,0 +1,169 @@
+/**
+ * Nexus Package Scanner — reads package.json and coordinates audits.
+ *
+ * Combines:
+ *  - CVE scanning via OSV (engine.ts)
+ *  - Supply chain risk via npm registry (supply-chain.ts)
+ *  - Override policy validation (override.ts)
+ *
+ * Entry point for both the CLI and the Vite plugin.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join }     from 'node:path';
+
+import { auditDependencies, filterVulnerable, type AuditResult, type VulnSeverity } from './engine.js';
+import { auditSupplyChain,  type SupplyChainResult }                                  from './supply-chain.js';
+import { findOverride, validateOverride, formatOverrides, type AllowVulnerableConfig } from './override.js';
+
+export type { AuditResult, VulnSeverity, SupplyChainResult, AllowVulnerableConfig };
+export { filterVulnerable };
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface ScanOptions {
+  root:                 string;
+  /** Include devDependencies in the scan (default: false) */
+  includeDev?:          boolean;
+  /** Supply chain guard (default: true) */
+  supplyChain?:         boolean;
+  /** Override exceptions from nexus.config.ts security.allowVulnerable */
+  allowVulnerable?:     AllowVulnerableConfig;
+  /**
+   * If true, critical CVEs that are not overridden will throw (for build-time blocking).
+   * If false, they are reported but don't throw.
+   */
+  failOnCritical?:      boolean;
+  /** Minimum severity to report (default: 'low') */
+  minSeverity?:         VulnSeverity;
+}
+
+export interface ScanResult {
+  scannedPackages:    number;
+  vulnerable:         AuditResult[];
+  supplyChain:        Map<string, SupplyChainResult>;
+  overrideStatus:     ReturnType<typeof formatOverrides>;
+  blockedPackages:    string[];   // packages that would block a build
+  durationMs:         number;
+}
+
+// ── Main scanner ──────────────────────────────────────────────────────────────
+
+/**
+ * Full dependency scan: CVE + supply chain + override validation.
+ * This is the core function called by both `nexus audit` and the Vite plugin.
+ */
+export async function scanProject(opts: ScanOptions): Promise<ScanResult> {
+  const t0 = Date.now();
+
+  // Read package.json
+  const pkgPath = join(opts.root, 'package.json');
+  let pkgJson: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  try {
+    pkgJson = JSON.parse(await readFile(pkgPath, 'utf-8')) as typeof pkgJson;
+  } catch {
+    throw new Error(`[Nexus Audit] Cannot read package.json at ${pkgPath}`);
+  }
+
+  // Collect deps
+  const deps: Record<string, string> = {
+    ...pkgJson.dependencies,
+    ...(opts.includeDev ? pkgJson.devDependencies : {}),
+  };
+
+  const scannedPackages = Object.keys(deps).length;
+
+  // Parallel: CVE scan + supply chain scan
+  const [cveResults, scResults] = await Promise.all([
+    auditDependencies(deps),
+    opts.supplyChain !== false ? auditSupplyChain(deps) : Promise.resolve(new Map<string, SupplyChainResult>()),
+  ]);
+
+  const vulnerable = filterVulnerable(cveResults);
+
+  // Override policy validation
+  const overrides     = opts.allowVulnerable ?? {};
+  const overrideStats = formatOverrides(overrides);
+  const blockedPackages: string[] = [];
+
+  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+  const minSev = opts.minSeverity ?? 'low';
+
+  for (const result of vulnerable) {
+    for (const vuln of result.vulns) {
+      if (SORDER[vuln.severity] > SORDER[minSev]) continue;
+
+      if (vuln.severity !== 'critical' && vuln.severity !== 'high') continue;
+
+      // Check if there's a valid override
+      const overrideResult = findOverride(result.package, vuln.id, overrides)
+        ?? findOverride(result.package, vuln.aliases[0] ?? '', overrides);
+
+      if (overrideResult?.valid) {
+        // Override is active — report but don't block
+        continue;
+      }
+
+      if (!overrideResult || overrideResult.expired) {
+        // No override or expired → block
+        if (!blockedPackages.includes(result.package)) {
+          blockedPackages.push(result.package);
+        }
+      }
+    }
+  }
+
+  const scanResult: ScanResult = {
+    scannedPackages,
+    vulnerable,
+    supplyChain: scResults,
+    overrideStatus: overrideStats,
+    blockedPackages,
+    durationMs: Date.now() - t0,
+  };
+
+  // Throw for build-time blocking
+  if (opts.failOnCritical && blockedPackages.length > 0) {
+    const details = blockedPackages
+      .map((pkg) => {
+        const r = cveResults.get(pkg);
+        const topVuln = r?.vulns[0];
+        return topVuln
+          ? `  "${pkg}" — ${topVuln.id} (${topVuln.severity.toUpperCase()}): ${topVuln.summary}`
+          : `  "${pkg}"`;
+      })
+      .join('\n');
+
+    throw new NexusSecurityError(
+      `[Nexus Security] 🛑 BUILD BLOCKED — ${blockedPackages.length} critical/high CVE${blockedPackages.length > 1 ? 's' : ''} detected:\n\n` +
+      `${details}\n\n` +
+      `Options:\n` +
+      `  1. Run \`nexus fix\` to automatically update to patched versions\n` +
+      `  2. Add a time-limited override in nexus.config.ts (security.allowVulnerable)\n` +
+      `  3. Run \`nexus audit\` for full details and suggested fixes`,
+      blockedPackages,
+      vulnerable,
+    );
+  }
+
+  return scanResult;
+}
+
+// ── Error class ───────────────────────────────────────────────────────────────
+
+export class NexusSecurityError extends Error {
+  constructor(
+    message: string,
+    public readonly blockedPackages: string[],
+    public readonly vulnerable: AuditResult[],
+  ) {
+    super(message);
+    this.name = 'NexusSecurityError';
+  }
+}
+
+// ── Single-package audit (for Vite plugin import hook) ───────────────────────
+
+export { auditPackage } from './engine.js';
+export { checkSupplyChain } from './supply-chain.js';
+export { validateOverride, findOverride } from './override.js';

package/src/supply-chain.ts

@@ -0,0 +1,316 @@
+/**
+ * Nexus Supply Chain Guard.
+ *
+ * Uses the public npm registry API to detect signs of supply chain compromise:
+ *
+ *  1. SINGLE MAINTAINER — one compromised account = full package control
+ *  2. RECENT MAINTAINER CHANGE — new owner in last 90 days (account takeover pattern)
+ *  3. NEWLY PUBLISHED POPULAR NAME — typosquatting / dependency confusion
+ *  4. ABANDONED PACKAGE — no updates in 2+ years but still widely imported
+ *  5. RAPID VERSION BUMP — many versions published in a short time (malware injection)
+ *  6. OWNER TRANSFER — package ownership changed (acquisition or takeover)
+ *
+ * What we CANNOT check (npm considers it private):
+ *  - Whether individual maintainers have MFA/2FA enabled
+ *    (npm Team policy requires it for popular packages as of 2022, but status is not in the API)
+ *
+ * Risk score: 0 (safe) → 100 (critical risk)
+ * Threshold: ≥60 = warn, ≥80 = block in hardened mode
+ *
+ * npm registry API:
+ *   GET https://registry.npmjs.org/{package}       → full metadata
+ *   GET https://registry.npmjs.org/{package}/latest → latest version only
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const REGISTRY     = 'https://registry.npmjs.org';
+const CACHE_DIR    = join(homedir(), '.nexus', 'cache', 'npm-meta');
+const CACHE_TTL_MS = 6 * 60 * 60 * 1_000; // 6h (changes more frequently than CVEs)
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type SupplyChainRiskLevel = 'safe' | 'low' | 'medium' | 'high' | 'critical';
+
+export interface SupplyChainFlag {
+  code:        string;
+  title:       string;
+  description: string;
+  riskPoints:  number;   // contribution to total score (0–100)
+}
+
+export interface SupplyChainResult {
+  package:      string;
+  riskScore:    number;          // 0–100
+  riskLevel:    SupplyChainRiskLevel;
+  flags:        SupplyChainFlag[];
+  maintainers:  string[];
+  latestVersion:string;
+  firstPublished: string;
+  lastPublished:  string;
+  totalVersions:  number;
+  cached:       boolean;
+  stale:        boolean;
+  checkedAt:    number;
+}
+
+interface NpmMeta {
+  name:         string;
+  'dist-tags':  Record<string, string>;
+  maintainers:  Array<{ name: string; email?: string }>;
+  time:         Record<string, string>;  // version → ISO date; also 'created', 'modified'
+  versions:     Record<string, unknown>;
+}
+
+// ── Cache ─────────────────────────────────────────────────────────────────────
+
+async function ensureDir(): Promise<void> {
+  try { await mkdir(CACHE_DIR, { recursive: true }); } catch { /* exists */ }
+}
+
+function cacheKey(pkg: string): string {
+  return pkg.replace(/\//g, '__').replace(/@/g, '_at_');
+}
+
+async function readNpmCache(pkg: string): Promise<{ result: SupplyChainResult; expiresAt: number } | null> {
+  try {
+    const raw = await readFile(join(CACHE_DIR, `${cacheKey(pkg)}.json`), 'utf-8');
+    return JSON.parse(raw) as { result: SupplyChainResult; expiresAt: number };
+  } catch { return null; }
+}
+
+async function writeNpmCache(pkg: string, result: SupplyChainResult): Promise<void> {
+  await ensureDir();
+  try {
+    await writeFile(
+      join(CACHE_DIR, `${cacheKey(pkg)}.json`),
+      JSON.stringify({ result, expiresAt: Date.now() + CACHE_TTL_MS }, null, 2),
+    );
+  } catch { /* non-fatal */ }
+}
+
+// ── Fetch ─────────────────────────────────────────────────────────────────────
+
+async function fetchNpmMeta(pkg: string): Promise<NpmMeta | null> {
+  const controller = new AbortController();
+  const timeout    = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const res = await fetch(`${REGISTRY}/${encodeURIComponent(pkg)}`, {
+      headers: { accept: 'application/vnd.npm.install-v1+json, application/json' },
+      signal:  controller.signal,
+    });
+    if (!res.ok) return null;
+    return await res.json() as NpmMeta;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ── Risk analysis ─────────────────────────────────────────────────────────────
+
+function daysBetween(a: string, b: string = new Date().toISOString()): number {
+  return Math.floor((new Date(b).getTime() - new Date(a).getTime()) / (1000 * 60 * 60 * 24));
+}
+
+function analyzeRisk(meta: NpmMeta): { flags: SupplyChainFlag[]; score: number } {
+  const flags: SupplyChainFlag[] = [];
+  let score = 0;
+
+  const maintainerCount = meta.maintainers?.length ?? 0;
+  const versions        = Object.keys(meta.versions ?? {});
+  const timeEntries     = Object.entries(meta.time ?? {})
+    .filter(([k]) => !['created', 'modified'].includes(k))
+    .sort(([, a], [, b]) => new Date(a).getTime() - new Date(b).getTime());
+
+  const firstPublished  = meta.time['created']  ?? timeEntries[0]?.[1] ?? '';
+  const lastPublished   = meta.time['modified'] ?? timeEntries[timeEntries.length - 1]?.[1] ?? '';
+  const daysOld         = firstPublished ? daysBetween(firstPublished) : 0;
+  const daysSinceUpdate = lastPublished  ? daysBetween(lastPublished)  : 0;
+
+  // ① Single maintainer
+  if (maintainerCount === 1) {
+    const pts = 25;
+    score += pts;
+    flags.push({
+      code:        'SINGLE_MAINTAINER',
+      title:       'Single maintainer',
+      description: `This package has only 1 maintainer. A compromised account means full control over all releases.`,
+      riskPoints:  pts,
+    });
+  } else if (maintainerCount === 0) {
+    const pts = 35;
+    score += pts;
+    flags.push({
+      code:        'NO_MAINTAINER',
+      title:       'No maintainers listed',
+      description: 'No maintainers found in registry metadata — package may be abandoned or orphaned.',
+      riskPoints:  pts,
+    });
+  }
+
+  // ② Recently created (< 30 days old) — typosquatting / dependency confusion window
+  if (daysOld < 30 && daysOld > 0) {
+    const pts = 30;
+    score += pts;
+    flags.push({
+      code:        'NEWLY_PUBLISHED',
+      title:       `Published ${daysOld} day${daysOld === 1 ? '' : 's'} ago`,
+      description: 'Very new packages are high-risk for typosquatting and dependency confusion attacks. Verify the name carefully.',
+      riskPoints:  pts,
+    });
+  }
+
+  // ③ Abandoned — last update > 2 years
+  if (daysSinceUpdate > 730 && versions.length > 0) {
+    const years = (daysSinceUpdate / 365).toFixed(1);
+    const pts   = 20;
+    score += pts;
+    flags.push({
+      code:        'ABANDONED',
+      title:       `Not updated in ${years} years`,
+      description: 'Abandoned packages accumulate unpatched CVEs and may not work with current Node.js versions.',
+      riskPoints:  pts,
+    });
+  }
+
+  // ④ Rapid version publishing — many versions in a short window (injection pattern)
+  const recentVersions = timeEntries.filter(([, ts]) => daysBetween(ts) < 7);
+  if (recentVersions.length >= 5) {
+    const pts = 35;
+    score += pts;
+    flags.push({
+      code:        'RAPID_VERSIONS',
+      title:       `${recentVersions.length} versions published in the last 7 days`,
+      description: 'Rapid version publishing is a known pattern for malware injection — attackers publish many versions to slip through automated scanners.',
+      riskPoints:  pts,
+    });
+  }
+
+  // ⑤ Recent maintainer churn — if many versions published very recently from fresh pkg
+  const last30DayVersions = timeEntries.filter(([, ts]) => daysBetween(ts) < 30).length;
+  if (daysOld < 180 && last30DayVersions > 10) {
+    const pts = 20;
+    score += pts;
+    flags.push({
+      code:        'OWNERSHIP_CHURN',
+      title:       'High version churn on a new package',
+      description: `${last30DayVersions} versions in the last 30 days on a package less than 6 months old — possible account takeover or automated malware distribution.`,
+      riskPoints:  pts,
+    });
+  }
+
+  // ⑥ Very few total versions for a package > 1 year old (abandoned, low quality)
+  if (versions.length <= 2 && daysOld > 365) {
+    const pts = 10;
+    score += pts;
+    flags.push({
+      code:        'LOW_ACTIVITY',
+      title:       'Very few versions for an old package',
+      description: 'Package has barely been maintained. May have unaddressed bugs or security issues.',
+      riskPoints:  pts,
+    });
+  }
+
+  return { flags, score: Math.min(100, score) };
+}
+
+function scoreToLevel(score: number): SupplyChainRiskLevel {
+  if (score >= 80) return 'critical';
+  if (score >= 60) return 'high';
+  if (score >= 35) return 'medium';
+  if (score >= 15) return 'low';
+  return 'safe';
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Analyzes a package for supply chain risk signals using the npm registry.
+ *
+ * Does NOT check individual MFA status (not in npm public API).
+ * DOES check: maintainer count, age, version velocity, abandonment.
+ */
+export async function checkSupplyChain(pkg: string): Promise<SupplyChainResult> {
+  const cached = await readNpmCache(pkg);
+  const now    = Date.now();
+
+  if (cached && now < cached.expiresAt) {
+    return { ...cached.result, cached: true, stale: false };
+  }
+
+  const meta = await fetchNpmMeta(pkg);
+
+  if (!meta) {
+    if (cached) return { ...cached.result, cached: true, stale: true };
+    return {
+      package:      pkg, riskScore: 0, riskLevel: 'safe', flags: [],
+      maintainers: [], latestVersion: 'unknown',
+      firstPublished: '', lastPublished: '', totalVersions: 0,
+      cached: false, stale: false, checkedAt: now,
+    };
+  }
+
+  const { flags, score } = analyzeRisk(meta);
+  const versions         = Object.keys(meta.versions ?? {});
+  const timeEntries      = Object.entries(meta.time ?? {})
+    .filter(([k]) => !['created', 'modified'].includes(k))
+    .sort(([, a], [, b]) => new Date(a).getTime() - new Date(b).getTime());
+
+  const result: SupplyChainResult = {
+    package:       meta.name ?? pkg,
+    riskScore:     score,
+    riskLevel:     scoreToLevel(score),
+    flags,
+    maintainers:   (meta.maintainers ?? []).map((m) => m.name),
+    latestVersion: meta['dist-tags']?.latest ?? versions[versions.length - 1] ?? 'unknown',
+    firstPublished: meta.time['created'] ?? timeEntries[0]?.[1] ?? '',
+    lastPublished:  meta.time['modified'] ?? timeEntries[timeEntries.length - 1]?.[1] ?? '',
+    totalVersions:  versions.length,
+    cached:  false,
+    stale:   false,
+    checkedAt: now,
+  };
+
+  await writeNpmCache(pkg, result);
+  return result;
+}
+
+/**
+ * Checks supply chain risk for all packages in a dependency map.
+ * Returns only packages with riskLevel >= 'medium'.
+ */
+export async function auditSupplyChain(
+  deps: Record<string, string>,
+): Promise<Map<string, SupplyChainResult>> {
+  const results  = new Map<string, SupplyChainResult>();
+  const packages = Object.keys(deps);
+  const BATCH    = 8;
+
+  for (let i = 0; i < packages.length; i += BATCH) {
+    const batch = packages.slice(i, i + BATCH);
+    const settled = await Promise.allSettled(
+      batch.map(async (pkg) => {
+        const result = await checkSupplyChain(pkg);
+        return [pkg, result] as [string, SupplyChainResult];
+      }),
+    );
+    for (const s of settled) {
+      if (s.status === 'fulfilled' && s.value[1].riskLevel !== 'safe') {
+        results.set(s.value[0], s.value[1]);
+      }
+    }
+  }
+
+  return results;
+}
+
+/** Note about MFA status — shown in audit output for transparency */
+export const MFA_NOTE =
+  'npm requires MFA for maintainers of packages with >500 weekly downloads as of 2022, ' +
+  'but individual MFA status is not publicly exposed by the registry API. ' +
+  'Use `npm access list collaborators {package}` with appropriate permissions ' +
+  'to view maintainer details for your own packages.';