@checkstack/script-packages-backend 0.2.1 → 0.3.1

package/src/audit-runner.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "bun:test";
+import type {
+  AuditAdvisory,
+  AuditState,
+} from "@checkstack/script-packages-common";
+import { createAuditRunner, type AuditRunnerDeps } from "./audit-runner";
+import { advisoryKey } from "./audit-delta";
+
+function adv(
+  packageName: string,
+  advisoryId: string,
+  severity: AuditAdvisory["severity"],
+): AuditAdvisory {
+  return {
+    packageName,
+    advisoryId,
+    severity,
+    title: `${packageName} ${advisoryId}`,
+    vulnerableVersions: "<1",
+    url: null,
+    cvssScore: null,
+  };
+}
+
+/** In-memory audit store + notify capture for a given hash. */
+function makeHarness(opts: {
+  lockfileHash: string | null;
+  scanResult: AuditAdvisory[];
+  managers?: string[];
+  initialStored?: AuditAdvisory[];
+  initialNotifiedKeys?: Set<string>;
+}) {
+  const stored = new Map<string, AuditAdvisory>(); // key -> advisory
+  const notifiedFlags = new Set<string>();
+  for (const a of opts.initialStored ?? []) stored.set(advisoryKey(a), a);
+  for (const k of opts.initialNotifiedKeys ?? []) notifiedFlags.add(k);
+
+  let lastState: AuditState | null = null;
+  const notifies: { userId: string; body: string }[] = [];
+  let locked = false;
+  const completed: { lockfileHash: string | null; total: number }[] = [];
+  const pruneCalls: string[][] = [];
+
+  const deps: AuditRunnerDeps = {
+    installerLock: {
+      async tryInstallerLock() {
+        if (locked) return null;
+        locked = true;
+        return { release: async () => { locked = false; } };
+      },
+    },
+    auditStore: {
+      async advisoriesForHash() {
+        return [...stored.values()];
+      },
+      async notifiedSeverities() {
+        const m = new Map<string, AuditAdvisory["severity"]>();
+        for (const k of notifiedFlags) {
+          const a = stored.get(k);
+          if (a) m.set(k, a.severity);
+        }
+        return m;
+      },
+      async replaceForHash({ advisories, notifiedKeys }) {
+        stored.clear();
+        notifiedFlags.clear();
+        for (const a of advisories) {
+          stored.set(advisoryKey(a), a);
+          if (notifiedKeys.has(advisoryKey(a))) notifiedFlags.add(advisoryKey(a));
+        }
+      },
+      async markNotified({ keys }) {
+        for (const k of keys) notifiedFlags.add(advisoryKey(k));
+      },
+      async pruneHashesNotIn(keepHashes: string[]) {
+        // Harness keys are not hash-scoped, so we record the call to assert
+        // the runner prunes superseded hashes (keeping only the current one).
+        pruneCalls.push(keepHashes);
+      },
+      async getState() {
+        return lastState!;
+      },
+      async recordRun({ lockfileHash, total, counts }) {
+        lastState = {
+          lastRunAt: new Date(),
+          lockfileHash,
+          total,
+          counts,
+          errorMessage: null,
+        };
+      },
+      async recordError(message) {
+        lastState = {
+          lastRunAt: new Date(),
+          lockfileHash: null,
+          total: 0,
+          counts: { low: 0, moderate: 0, high: 0, critical: 0 },
+          errorMessage: message,
+        };
+      },
+    },
+    async loadCurrent() {
+      return {
+        lockfileHash: opts.lockfileHash,
+        packages: [{ name: "lodash", version: "4.0.0", enabled: true }],
+        ignoreScripts: true,
+      };
+    },
+    async scan() {
+      return { advisories: opts.scanResult };
+    },
+    async getUserIds() {
+      return (opts.managers ?? []).length > 0 ? ["u1", "u2"] : [];
+    },
+    async filterManagers() {
+      return opts.managers ?? [];
+    },
+    async notifyUser({ userId, body }) {
+      notifies.push({ userId, body });
+    },
+    async emitCompleted(input) {
+      completed.push(input);
+    },
+  };
+
+  return {
+    deps,
+    notifies,
+    completed,
+    stored,
+    notifiedFlags,
+    pruneCalls,
+    getState: () => lastState,
+  };
+}
+
+describe("createAuditRunner", () => {
+  it("records all severities and notifies managers on new at/above-threshold advisories", async () => {
+    const h = makeHarness({
+      lockfileHash: "hash-1",
+      scanResult: [adv("lodash", "1", "high"), adv("a", "2", "low")],
+      managers: ["u1", "u2"],
+    });
+    const run = createAuditRunner(h.deps);
+    const summary = await run();
+
+    expect(summary).toMatchObject({ ran: true, lockfileHash: "hash-1", total: 2, notified: 1 });
+    // Prunes advisory rows for any superseded hash, keeping only the current one.
+    expect(h.pruneCalls).toEqual([["hash-1"]]);
+    // Recorded all (low counted too).
+    expect(h.getState()?.counts).toEqual({ low: 1, moderate: 0, high: 1, critical: 0 });
+    // Notified both managers, once each.
+    expect(h.notifies.map((n) => n.userId).sort()).toEqual(["u1", "u2"]);
+    // Completion signal emitted.
+    expect(h.completed).toEqual([{ lockfileHash: "hash-1", total: 2 }]);
+  });
+
+  it("does NOT re-notify an unchanged set on the second run (spam guard)", async () => {
+    const h = makeHarness({
+      lockfileHash: "hash-1",
+      scanResult: [adv("lodash", "1", "high")],
+      managers: ["u1"],
+    });
+    const run = createAuditRunner(h.deps);
+    await run();
+    expect(h.notifies).toHaveLength(1);
+    // Second run, identical scan result.
+    await run();
+    expect(h.notifies).toHaveLength(1); // no new notification
+  });
+
+  it("re-notifies on escalation of a previously-notified advisory", async () => {
+    const h = makeHarness({
+      lockfileHash: "hash-1",
+      scanResult: [adv("lodash", "1", "moderate")],
+      managers: ["u1"],
+    });
+    const run = createAuditRunner(h.deps);
+    await run();
+    expect(h.notifies).toHaveLength(1);
+
+    // Re-point the scan at an escalated severity for the same advisory.
+    h.deps.scan = async () => ({ advisories: [adv("lodash", "1", "critical")] });
+    await run();
+    expect(h.notifies).toHaveLength(2);
+  });
+
+  it("refuses cleanly when the installer lock is held", async () => {
+    const h = makeHarness({
+      lockfileHash: "hash-1",
+      scanResult: [adv("lodash", "1", "high")],
+      managers: ["u1"],
+    });
+    // Hold the lock first.
+    await h.deps.installerLock.tryInstallerLock();
+    const run = createAuditRunner(h.deps);
+    const summary = await run();
+    expect(summary.ran).toBe(false);
+    expect(summary.reason).toContain("installer lock");
+    expect(h.notifies).toHaveLength(0);
+  });
+
+  it("records an empty result when nothing is installed", async () => {
+    const h = makeHarness({
+      lockfileHash: null,
+      scanResult: [],
+      managers: ["u1"],
+    });
+    const run = createAuditRunner(h.deps);
+    const summary = await run();
+    expect(summary).toMatchObject({ ran: true, lockfileHash: null, total: 0, notified: 0 });
+    expect(h.notifies).toHaveLength(0);
+  });
+
+  it("records an error and does not throw when the scan fails", async () => {
+    const h = makeHarness({
+      lockfileHash: "hash-1",
+      scanResult: [],
+      managers: ["u1"],
+    });
+    h.deps.scan = async () => {
+      throw new Error("bun audit boom");
+    };
+    const run = createAuditRunner(h.deps);
+    const summary = await run();
+    expect(summary.ran).toBe(false);
+    expect(summary.reason).toContain("boom");
+    expect(h.getState()?.errorMessage).toContain("boom");
+  });
+});

package/src/audit-runner.ts

@@ -0,0 +1,224 @@
+import {
+  AUDIT_NOTIFY_THRESHOLD,
+  scriptPackagesRoutes,
+  type AuditAdvisory,
+  type AuditRunSummary,
+} from "@checkstack/script-packages-common";
+import { extractErrorMessage, resolveRoute } from "@checkstack/common";
+import type { InstallerLock } from "./install-state-store";
+import type { AuditStore } from "./stores";
+import { countBySeverity } from "./audit-parse";
+import { advisoryKey, computeAuditDelta } from "./audit-delta";
+
+/**
+ * Build an `auditNow()` callable that wires the pure audit pieces (scanner,
+ * delta logic, store) to the real stores + notification path, shared by the
+ * admin `auditNow` RPC and the scheduled recurring job (so the safety + delta
+ * logic lives in exactly one place). Mirrors {@link createBlobGcTrigger}.
+ *
+ * Election + mutual exclusion: takes the installer-election advisory lock for
+ * the whole pass, so a concurrent install / migration / blob-GC (which
+ * contend for the same lock) cannot run while the audit does, and vice versa.
+ * If the lock is held, the audit refuses cleanly and retries on the next tick.
+ *
+ * Notify suppression: only NEWLY-APPEARED or severity-ESCALATED advisories at
+ * or above the threshold notify; the durable per-advisory `notified` flag in
+ * the store carries across runs so a stable set never re-notifies (even
+ * across a redeploy). RECORD all severities regardless of the notify gate.
+ */
+
+export interface AuditRunnerDeps {
+  installerLock: InstallerLock;
+  auditStore: AuditStore;
+  /** Current desired install state (the tree to audit). */
+  loadCurrent(): Promise<{
+    lockfileHash: string | null;
+    packages: { name: string; version: string; enabled: boolean }[];
+    ignoreScripts: boolean;
+  }>;
+  /** Run the actual `bun audit` scan against the resolved tree. */
+  scan(input: {
+    packages: { name: string; version: string; enabled: boolean }[];
+    ignoreScripts: boolean;
+  }): Promise<{ advisories: AuditAdvisory[] }>;
+  /** Enumerate candidate user ids (auth.getUsers ids). */
+  getUserIds(): Promise<string[]>;
+  /** Narrow to holders of `script-packages.manage`. */
+  filterManagers(userIds: string[]): Promise<string[]>;
+  /** Deliver one transactional notification to one user. */
+  notifyUser(input: {
+    userId: string;
+    title: string;
+    body: string;
+    importance: "info" | "warning" | "critical";
+    action?: { label: string; url: string };
+  }): Promise<void>;
+  /** Broadcast the audit-completed signal so settings pages refresh. */
+  emitCompleted(input: {
+    lockfileHash: string | null;
+    total: number;
+  }): Promise<void>;
+  logger?: { debug(msg: string): void; error(msg: string): void };
+}
+
+/** Importance for a notification batch, driven by its most-severe advisory. */
+function importanceFor(
+  advisories: AuditAdvisory[],
+): "info" | "warning" | "critical" {
+  if (advisories.some((a) => a.severity === "critical")) return "critical";
+  if (advisories.some((a) => a.severity === "high")) return "warning";
+  return "info";
+}
+
+function buildBody(advisories: AuditAdvisory[]): string {
+  const lines = advisories.map((a) => {
+    const link = a.url ? `[${a.title || a.advisoryId}](${a.url})` : a.title || a.advisoryId;
+    return `- **${a.packageName}** (${a.severity}): ${link}`;
+  });
+  return [
+    `${advisories.length} new vulnerability advisor${advisories.length === 1 ? "y" : "ies"} found in the installed script packages:`,
+    "",
+    ...lines,
+  ].join("\n");
+}
+
+export function createAuditRunner(
+  deps: AuditRunnerDeps,
+): () => Promise<AuditRunSummary> {
+  return async function auditNow(): Promise<AuditRunSummary> {
+    const lock = await deps.installerLock.tryInstallerLock();
+    if (!lock) {
+      const reason =
+        "An install, storage migration, or blob GC holds the installer lock; skipping audit.";
+      deps.logger?.debug(reason);
+      return { ran: false, reason, lockfileHash: null, total: 0, notified: 0 };
+    }
+
+    try {
+      const current = await deps.loadCurrent();
+      const lockfileHash = current.lockfileHash;
+
+      // Nothing installed → record an empty, error-free result.
+      if (!lockfileHash) {
+        await deps.auditStore.recordRun({
+          lockfileHash: null,
+          total: 0,
+          counts: { low: 0, moderate: 0, high: 0, critical: 0 },
+        });
+        await deps.emitCompleted({ lockfileHash: null, total: 0 });
+        return { ran: true, lockfileHash: null, total: 0, notified: 0 };
+      }
+
+      const previous = await deps.auditStore.advisoriesForHash(lockfileHash);
+      const alreadyNotified =
+        await deps.auditStore.notifiedSeverities(lockfileHash);
+
+      const { advisories } = await deps.scan({
+        packages: current.packages,
+        ignoreScripts: current.ignoreScripts,
+      });
+
+      const delta = computeAuditDelta({
+        previous,
+        current: advisories,
+        threshold: AUDIT_NOTIFY_THRESHOLD,
+      });
+
+      // Drop advisories we've already notified at (at least) their current
+      // severity, so a redeploy with the same set never re-spams.
+      const toNotify = delta.toNotify.filter((a) => {
+        const prev = alreadyNotified.get(advisoryKey(a));
+        // Re-notify only if not yet notified, or it escalated beyond what we
+        // last told them about (handled by the delta's escalation check).
+        return prev === undefined || prev !== a.severity;
+      });
+
+      // Persist findings first (so the read path is correct even if notify
+      // fails). Carry `notified` forward for advisories that stay unchanged.
+      const notifiedKeys = new Set(alreadyNotified.keys());
+      await deps.auditStore.replaceForHash({
+        lockfileHash,
+        advisories,
+        notifiedKeys,
+      });
+
+      // Drop advisory rows for superseded lockfile hashes so they don't
+      // accumulate forever as the installed tree changes. Only the current
+      // hash is queryable (getAuditState reads the current hash), so anything
+      // else is dead data. Best-effort: a prune failure must not fail the run.
+      await deps.auditStore
+        .pruneHashesNotIn([lockfileHash])
+        .catch((error) => {
+          deps.logger?.error(
+            `Audit: pruning superseded advisory hashes failed: ${extractErrorMessage(error)}`,
+          );
+        });
+
+      const counts = countBySeverity(advisories);
+      await deps.auditStore.recordRun({
+        lockfileHash,
+        total: advisories.length,
+        counts,
+      });
+
+      // Notify holders about the new/escalated advisories (best-effort).
+      if (toNotify.length > 0) {
+        try {
+          const userIds = await deps.getUserIds();
+          const managers =
+            userIds.length > 0 ? await deps.filterManagers(userIds) : [];
+          if (managers.length > 0) {
+            const body = buildBody(toNotify);
+            const importance = importanceFor(toNotify);
+            for (const userId of managers) {
+              await deps
+                .notifyUser({
+                  userId,
+                  title: `Script packages: ${toNotify.length} new vulnerability advisor${toNotify.length === 1 ? "y" : "ies"}`,
+                  body,
+                  importance,
+                  action: {
+                    label: "Review advisories",
+                    url: resolveRoute(scriptPackagesRoutes.routes.settings),
+                  },
+                })
+                .catch((error) => {
+                  deps.logger?.error(
+                    `Audit notify to ${userId} failed: ${extractErrorMessage(error)}`,
+                  );
+                });
+            }
+          }
+          // Mark the notified advisories so the next pass doesn't re-notify.
+          await deps.auditStore.markNotified({
+            lockfileHash,
+            keys: toNotify.map((a) => ({
+              packageName: a.packageName,
+              advisoryId: a.advisoryId,
+            })),
+          });
+        } catch (error) {
+          deps.logger?.error(
+            `Audit notification step failed: ${extractErrorMessage(error)}`,
+          );
+        }
+      }
+
+      await deps.emitCompleted({ lockfileHash, total: advisories.length });
+
+      return {
+        ran: true,
+        lockfileHash,
+        total: advisories.length,
+        notified: toNotify.length,
+      };
+    } catch (error) {
+      const message = extractErrorMessage(error);
+      deps.logger?.error(`Audit pass failed: ${message}`);
+      await deps.auditStore.recordError(message).catch(() => {});
+      return { ran: false, reason: message, lockfileHash: null, total: 0, notified: 0 };
+    } finally {
+      await lock.release();
+    }
+  };
+}

package/src/audit-scanner.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  createAuditScanner,
+  type SpawnFn,
+  type SpawnOptions,
+} from "./audit-scanner";
+
+/**
+ * Unit tests for the audit scanner's spawn wiring. We inject a fake `spawn`
+ * so no real process runs - the property under test is that the audit reuses
+ * the installer's SHARED cache dir (via `BUN_INSTALL_CACHE_DIR`) rather than
+ * Bun's default global cache, so it cannot drift from the install path.
+ */
+describe("createAuditScanner spawn wiring", () => {
+  let work: string;
+
+  beforeEach(async () => {
+    work = await mkdtemp(path.join(tmpdir(), "cs-audit-scanner-"));
+  });
+  afterEach(async () => {
+    await rm(work, { recursive: true, force: true });
+  });
+
+  function fakeSpawn(stdouts: string[]): {
+    spawnFn: SpawnFn;
+    calls: SpawnOptions[];
+  } {
+    const calls: SpawnOptions[] = [];
+    let i = 0;
+    const spawnFn: SpawnFn = (options) => {
+      calls.push(options);
+      const out = stdouts[i] ?? "";
+      i += 1;
+      return {
+        stdout: new Response(out).body!,
+        stderr: new Response("").body!,
+        exited: Promise.resolve(0),
+      };
+    };
+    return { spawnFn, calls };
+  }
+
+  test("passes the shared cache dir as BUN_INSTALL_CACHE_DIR to install AND audit", async () => {
+    const cacheDir = path.join(work, "shared-cache");
+    // First spawn = install (empty stdout), second = audit (JSON advisories).
+    const auditJson = JSON.stringify({
+      lodash: [
+        { id: 1, severity: "high", vulnerable_versions: "<4.17.21" },
+      ],
+    });
+    const { spawnFn, calls } = fakeSpawn(["", auditJson]);
+
+    const scanner = createAuditScanner({
+      scratchDir: path.join(work, "scratch"),
+      cacheDir,
+      registry: {
+        registryUrl: "https://registry.npmjs.org/",
+        scopedRegistries: [],
+        authToken: undefined,
+      },
+      spawnFn,
+    });
+
+    const result = await scanner.scan({
+      packages: [{ name: "lodash", version: "4.17.4", enabled: true }],
+      ignoreScripts: true,
+    });
+
+    expect(calls).toHaveLength(2);
+    // Both the install and the audit spawn must point at the shared cache dir.
+    expect(calls[0]!.env.BUN_INSTALL_CACHE_DIR).toBe(cacheDir);
+    expect(calls[1]!.env.BUN_INSTALL_CACHE_DIR).toBe(cacheDir);
+    // First spawn installs (with --ignore-scripts), second runs `audit --json`.
+    expect(calls[0]!.cmd).toContain("install");
+    expect(calls[0]!.cmd).toContain("--ignore-scripts");
+    expect(calls[1]!.cmd).toEqual([process.execPath, "audit", "--json"]);
+    // The parsed advisory comes through.
+    expect(result.advisories).toHaveLength(1);
+    expect(result.advisories[0]!.packageName).toBe("lodash");
+  });
+
+  test("short-circuits (no spawn) when there are no enabled packages", async () => {
+    const { spawnFn, calls } = fakeSpawn([]);
+    const scanner = createAuditScanner({
+      scratchDir: path.join(work, "scratch"),
+      cacheDir: path.join(work, "cache"),
+      registry: {
+        registryUrl: "https://registry.npmjs.org/",
+        scopedRegistries: [],
+        authToken: undefined,
+      },
+      spawnFn,
+    });
+    const result = await scanner.scan({ packages: [], ignoreScripts: true });
+    expect(result.advisories).toEqual([]);
+    expect(calls).toHaveLength(0);
+  });
+});