@expressots/studio-agent 4.0.0-preview.1

package/dist/security/npm-audit.js

@@ -0,0 +1,320 @@
+/**
+ * `npm audit --json` runner.
+ *
+ * Spawns the host project's `npm audit` in a child process, captures
+ * stdout, and normalises the result into `DependencyFinding[]` so the
+ * agent doesn't have to know about npm's wire format anywhere else.
+ *
+ * Design constraints:
+ *   - **Async only.** This runs inside the host's process; blocking the
+ *     event loop with `execSync` would freeze the host server.
+ *   - **Bounded.** We cap stdout at 16 MB and impose a 30 s wall timeout
+ *     to keep a misbehaving npm install from hanging Studio forever.
+ *   - **Defensive.** `npm audit` writes useful JSON to stdout even when
+ *     it exits 1 (the convention is "exit 1 means vulns were found").
+ *     We treat exit codes 0 and 1 as success.
+ *
+ * The runner is decoupled from the engine: it returns a structured
+ * result plus a `state` value the engine maps onto `scanState.audit`.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Maximum bytes of stdout we'll buffer from `npm audit`. */
+const MAX_STDOUT_BYTES = 16 * 1024 * 1024; // 16 MB
+/** How long we wait before killing the child process. */
+const AUDIT_TIMEOUT_MS = 30_000;
+/**
+ * Run `npm audit --json` in `cwd` and return findings. The function is
+ * resilient to npm not being installed, the project missing a
+ * lockfile, or audit returning malformed JSON — every error path
+ * yields a structured `NpmAuditResult` instead of throwing.
+ */
+export async function runNpmAudit(cwd) {
+    // Bail early if there's no lockfile — `npm audit` would just fail
+    // anyway, and we want to give the UI a clearer signal so it can
+    // render an empty state with instructions.
+    if (!hasLockfile(cwd)) {
+        return { state: 'missing-lockfile', findings: [], fixAvailability: new Map() };
+    }
+    let stdout = '';
+    let stderr = '';
+    try {
+        const result = await spawnAudit(cwd);
+        stdout = result.stdout;
+        stderr = result.stderr;
+        // npm audit exits 1 when it finds vulns, which is normal. Codes >=2
+        // signal a real failure (network, malformed package.json, etc.).
+        if (result.code !== null && result.code > 1) {
+            return {
+                state: 'error',
+                findings: [],
+                fixAvailability: new Map(),
+                error: extractShortError(stderr) ||
+                    `npm audit exited with code ${result.code}`,
+            };
+        }
+    }
+    catch (err) {
+        return {
+            state: 'error',
+            findings: [],
+            fixAvailability: new Map(),
+            error: err.message || 'failed to spawn npm audit',
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return {
+            state: 'error',
+            findings: [],
+            fixAvailability: new Map(),
+            error: 'npm audit produced invalid JSON',
+        };
+    }
+    const findings = normaliseNpmAudit(parsed);
+    const fixAvailability = extractFixAvailability(parsed);
+    return { state: 'ok', findings, fixAvailability };
+}
+/**
+ * Walk the parsed audit report and produce a per-package `fixAvailable`
+ * map. Preserves npm's three-way semantics:
+ *
+ *   - `false`  → `{ kind: 'none' }` — no upstream fix exists.
+ *   - `true`   → `{ kind: 'auto' }` — `npm audit fix` can resolve it
+ *                 but no concrete pinned target.
+ *   - object   → `{ kind: 'specific', name, version, isSemVerMajor }`.
+ */
+function extractFixAvailability(report) {
+    const out = new Map();
+    const vulns = report.vulnerabilities ?? {};
+    for (const [pkgName, vuln] of Object.entries(vulns)) {
+        const fa = vuln.fixAvailable;
+        if (typeof fa === 'object' && fa !== null) {
+            out.set(pkgName, {
+                kind: 'specific',
+                name: fa.name,
+                version: fa.version,
+                isSemVerMajor: Boolean(fa.isSemVerMajor),
+            });
+        }
+        else if (fa === true) {
+            out.set(pkgName, { kind: 'auto' });
+        }
+        else {
+            out.set(pkgName, { kind: 'none' });
+        }
+    }
+    return out;
+}
+/**
+ * Translate the `npm audit --json` vulnerability map into the agent's
+ * canonical `DependencyFinding` shape.
+ *
+ * Two filtering rules de-noise the report:
+ *
+ *   1. We dedupe advisories by id within a package — a single CVE
+ *      affecting multiple packages yields one finding per affected
+ *      package, but a package isn't reported twice for the same CVE.
+ *
+ *   2. **Alias-only entries are skipped when an alias target has its
+ *      own real advisory in the same report.** npm audit cascades
+ *      "effects" up the dependency chain — every package that
+ *      transitively depends on `path-to-regexp` shows up as a separate
+ *      vulnerability entry with `via: ['path-to-regexp']`. Surfacing
+ *      each link in that chain triples the finding count without
+ *      adding signal; users only care about the package they actually
+ *      need to upgrade (the real advisory's owner).
+ */
+function normaliseNpmAudit(report) {
+    const out = [];
+    const vulns = report.vulnerabilities ?? {};
+    // First pass: figure out which package names have *real* advisories
+    // (a `via` entry that's an object, not a string alias). Used below
+    // to drop alias-only cascades that point at one of these.
+    const packagesWithRealAdvisories = new Set();
+    for (const [pkgName, vuln] of Object.entries(vulns)) {
+        const hasReal = (vuln.via ?? []).some((v) => typeof v === 'object' && v !== null);
+        if (hasReal)
+            packagesWithRealAdvisories.add(pkgName);
+    }
+    for (const [pkgName, vuln] of Object.entries(vulns)) {
+        const advisories = (vuln.via ?? []).filter((v) => typeof v === 'object' && v !== null);
+        for (const adv of advisories) {
+            const id = buildFindingId(adv, pkgName);
+            out.push({
+                id,
+                package: pkgName,
+                installedVersion: vuln.range ?? adv.range ?? 'unknown',
+                fixedVersion: typeof vuln.fixAvailable === 'object' && vuln.fixAvailable
+                    ? vuln.fixAvailable.version
+                    : undefined,
+                severity: parseSeverity(adv.severity ?? vuln.severity),
+                cvss: typeof adv.cvss?.score === 'number' && Number.isFinite(adv.cvss.score)
+                    ? adv.cvss.score
+                    : undefined,
+                title: adv.title ?? `Vulnerability in ${pkgName}`,
+                summary: adv.title ?? '',
+                references: adv.url ? [adv.url] : [],
+                // npm audit reports `effects` as the chain of affected dependents;
+                // we surface it so users can see what brings the vulnerable
+                // package in. Most direct deps will have an empty effects array.
+                path: [pkgName, ...(vuln.effects ?? [])],
+            });
+        }
+        // Alias-only entries: surface as a finding ONLY if no alias target
+        // already has a real advisory in this report. Otherwise it's pure
+        // cascade noise — every transitive dependent of path-to-regexp
+        // shouldn't get its own row.
+        const aliasOnly = (vuln.via ?? []).filter((v) => typeof v === 'string');
+        if (advisories.length === 0 && aliasOnly.length > 0) {
+            const allAliasesCoveredByRealFindings = aliasOnly.every((a) => packagesWithRealAdvisories.has(a));
+            if (allAliasesCoveredByRealFindings)
+                continue;
+            out.push({
+                id: `npm-audit-${pkgName}-${vuln.severity ?? 'unknown'}`,
+                package: pkgName,
+                installedVersion: vuln.range ?? 'unknown',
+                fixedVersion: typeof vuln.fixAvailable === 'object' && vuln.fixAvailable
+                    ? vuln.fixAvailable.version
+                    : undefined,
+                severity: parseSeverity(vuln.severity),
+                title: `Vulnerable transitive dependency via ${aliasOnly.join(', ')}`,
+                summary: '',
+                references: [],
+                path: [pkgName, ...aliasOnly],
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Build a stable advisory id. Prefer the GHSA / CVE embedded in the
+ * advisory URL — that's what we'll dedupe against OSV later. Falls
+ * back to a hash-equivalent synthetic id otherwise.
+ */
+function buildFindingId(adv, pkgName) {
+    const url = adv.url ?? '';
+    const ghsa = url.match(/(GHSA-[a-z0-9-]+)/i);
+    if (ghsa)
+        return ghsa[1].toUpperCase();
+    const cve = url.match(/(CVE-\d{4}-\d+)/i);
+    if (cve)
+        return cve[1].toUpperCase();
+    if (typeof adv.source === 'number') {
+        return `npm-${adv.source}-${pkgName}`;
+    }
+    // Last resort: deterministic synthetic id keyed by title+pkg so reruns
+    // produce the same id across scans.
+    return `npm-${pkgName}-${(adv.title ?? 'unknown').slice(0, 40).replace(/\s+/g, '-')}`;
+}
+function parseSeverity(input) {
+    switch ((input ?? '').toLowerCase()) {
+        case 'critical':
+            return 'CRITICAL';
+        case 'high':
+            return 'HIGH';
+        case 'moderate':
+        case 'medium':
+            return 'MEDIUM';
+        case 'low':
+            return 'LOW';
+        case 'info':
+        case 'informational':
+            return 'INFO';
+        default:
+            return 'LOW';
+    }
+}
+/** Does the project at `cwd` have an npm lockfile? */
+function hasLockfile(cwd) {
+    return (fs.existsSync(path.join(cwd, 'package-lock.json')) ||
+        fs.existsSync(path.join(cwd, 'npm-shrinkwrap.json')));
+}
+/**
+ * Spawn `npm audit --json`, captures both streams, enforces the
+ * timeout, and resolves once the child exits (or we kill it).
+ */
+function spawnAudit(cwd) {
+    return new Promise((resolve, reject) => {
+        // On Windows the actual binary is `npm.cmd`. Spawn through the shell
+        // so platform differences don't matter. We don't pass any user input
+        // through the shell — only constant flags — so this is safe.
+        const child = spawn('npm', ['audit', '--json'], {
+            cwd,
+            shell: process.platform === 'win32',
+            // Inherit env so npm picks up the user's registry config / proxy.
+            env: process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        let bytes = 0;
+        child.stdout.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > MAX_STDOUT_BYTES) {
+                // Truncate rather than ENOMEM. The first 16 MB of audit output
+                // is far more than any real project produces — if we hit this
+                // limit it's almost certainly a runaway.
+                if (stdout.length < MAX_STDOUT_BYTES) {
+                    stdout += chunk.toString('utf-8');
+                    stdout = stdout.slice(0, MAX_STDOUT_BYTES);
+                }
+                return;
+            }
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            // npm warning lines can be plentiful but are short; cap conservatively.
+            if (stderr.length < 32 * 1024) {
+                stderr += chunk.toString('utf-8');
+            }
+        });
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // already gone
+            }
+            // Give it 250ms to actually die before resolving with what we have.
+            setTimeout(() => {
+                settle({ stdout, stderr, code: null });
+            }, 250);
+        }, AUDIT_TIMEOUT_MS);
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            settle({ stdout, stderr, code });
+        });
+    });
+}
+/**
+ * Pull the first informative line out of `npm audit` stderr for display.
+ * npm prints a lot of `npm warn …` noise we don't want to surface.
+ */
+function extractShortError(stderr) {
+    const lines = stderr
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !/^npm warn/i.test(l));
+    return lines[0] ?? '';
+}
+//# sourceMappingURL=npm-audit.js.map

package/dist/security/npm-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-audit.js","sourceRoot":"","sources":["../../src/security/npm-audit.ts"],"names":[],"mappings":"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"}

package/dist/security/osv-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * On-disk cache for OSV.dev advisory lookups.
+ *
+ * The OSV batch endpoint is generous but not infinite — repeating a
+ * scan in a project with 500+ deps every few minutes would burn quota
+ * fast. We cache results in `.studio/security-cache.json` keyed by
+ * `(ecosystem, package, version)` with a 6h TTL, so subsequent scans
+ * inside the TTL do zero network work for stable deps.
+ *
+ * The cache is best-effort: any I/O / parse error degrades to a
+ * cache-miss rather than failing the scan.
+ */
+export interface OsvAdvisory {
+    id: string;
+    aliases: string[];
+    summary: string;
+    details?: string;
+    severity?: number;
+    references: string[];
+    fixedVersion?: string;
+}
+export declare class OsvCache {
+    private readonly filePath;
+    private data;
+    private loaded;
+    private dirty;
+    /**
+     * Throttle disk writes — many cache puts inside one scan would
+     * otherwise produce many sequential writes. We coalesce into a
+     * single fsync at the end of a scan via `flush()`.
+     */
+    constructor(dbPath: string);
+    /** Load cache from disk; safe to call repeatedly. */
+    load(): void;
+    /**
+     * Look up advisories for a package@version. Returns null on miss /
+     * expired entry; callers should then fall back to a network query.
+     */
+    get(ecosystem: string, name: string, version: string): OsvAdvisory[] | null;
+    /** Store advisories for a package@version. Flush() persists to disk. */
+    put(ecosystem: string, name: string, version: string, advisories: OsvAdvisory[]): void;
+    /**
+     * Persist any pending writes. Safe to call when there's nothing to
+     * flush. Failures are swallowed because the cache is an optimisation
+     * — losing it just means the next scan pays one more OSV roundtrip.
+     */
+    flush(): void;
+    /** Drop everything. Exposed for tests / future "clear cache" UI. */
+    clear(): void;
+}
+//# sourceMappingURL=osv-cache.d.ts.map

package/dist/security/osv-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osv-cache.d.ts","sourceRoot":"","sources":["../../src/security/osv-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmBH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,IAAI,CAAsD;IAClE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB;;;;OAIG;gBAES,MAAM,EAAE,MAAM;IAM1B,qDAAqD;IACrD,IAAI,IAAI,IAAI;IAeZ;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,IAAI;IAQ3E,wEAAwE;IACxE,GAAG,CACD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,WAAW,EAAE,GACxB,IAAI;IASP;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAcb,oEAAoE;IACpE,KAAK,IAAI,IAAI;CAId"}

package/dist/security/osv-cache.js

@@ -0,0 +1,99 @@
+/**
+ * On-disk cache for OSV.dev advisory lookups.
+ *
+ * The OSV batch endpoint is generous but not infinite — repeating a
+ * scan in a project with 500+ deps every few minutes would burn quota
+ * fast. We cache results in `.studio/security-cache.json` keyed by
+ * `(ecosystem, package, version)` with a 6h TTL, so subsequent scans
+ * inside the TTL do zero network work for stable deps.
+ *
+ * The cache is best-effort: any I/O / parse error degrades to a
+ * cache-miss rather than failing the scan.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
+const CACHE_VERSION = 1;
+function cacheKey(ecosystem, name, version) {
+    return `${ecosystem}|${name}|${version}`;
+}
+export class OsvCache {
+    filePath;
+    data = { version: CACHE_VERSION, entries: {} };
+    loaded = false;
+    dirty = false;
+    /**
+     * Throttle disk writes — many cache puts inside one scan would
+     * otherwise produce many sequential writes. We coalesce into a
+     * single fsync at the end of a scan via `flush()`.
+     */
+    constructor(dbPath) {
+        // Co-locate with the studio db file so users only need to gitignore
+        // one folder (`.studio/`) to opt out of committing tooling state.
+        this.filePath = path.join(path.dirname(dbPath), 'security-cache.json');
+    }
+    /** Load cache from disk; safe to call repeatedly. */
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === CACHE_VERSION && parsed.entries) {
+                this.data = parsed;
+            }
+        }
+        catch {
+            // Missing file or corrupt JSON — start fresh, don't crash the scan.
+        }
+    }
+    /**
+     * Look up advisories for a package@version. Returns null on miss /
+     * expired entry; callers should then fall back to a network query.
+     */
+    get(ecosystem, name, version) {
+        this.load();
+        const entry = this.data.entries[cacheKey(ecosystem, name, version)];
+        if (!entry)
+            return null;
+        if (Date.now() - entry.storedAt > TTL_MS)
+            return null;
+        return entry.advisories;
+    }
+    /** Store advisories for a package@version. Flush() persists to disk. */
+    put(ecosystem, name, version, advisories) {
+        this.load();
+        this.data.entries[cacheKey(ecosystem, name, version)] = {
+            storedAt: Date.now(),
+            advisories,
+        };
+        this.dirty = true;
+    }
+    /**
+     * Persist any pending writes. Safe to call when there's nothing to
+     * flush. Failures are swallowed because the cache is an optimisation
+     * — losing it just means the next scan pays one more OSV roundtrip.
+     */
+    flush() {
+        if (!this.dirty)
+            return;
+        try {
+            const dir = path.dirname(this.filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.filePath, JSON.stringify(this.data));
+            this.dirty = false;
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /** Drop everything. Exposed for tests / future "clear cache" UI. */
+    clear() {
+        this.data = { version: CACHE_VERSION, entries: {} };
+        this.dirty = true;
+    }
+}
+//# sourceMappingURL=osv-cache.js.map

package/dist/security/osv-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"osv-cache.js","sourceRoot":"","sources":["../../src/security/osv-cache.ts"],"names":[],"mappings":"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"}

package/dist/security/osv-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OSV.dev client — supply-chain advisory lookups for installed packages.
+ *
+ * Why OSV: it's an open vulnerability database maintained by Google,
+ * exposes a programmatic JSON API, doesn't require auth, and aggregates
+ * GHSA, npm, OSS-Fuzz and other sources behind one query shape. It's
+ * also the source `npm audit` increasingly delegates to internally, so
+ * we get the same data without scraping anything.
+ *
+ * This client batches per-scan: one POST to `/v1/querybatch` covering
+ * every direct dependency. Results that aren't already in cache are
+ * persisted via `OsvCache` so subsequent scans inside the TTL skip the
+ * network entirely.
+ *
+ * Network failures degrade gracefully: we return an empty findings
+ * array so the engine can still ship a report using only `npm audit`.
+ */
+import type { DependencyFinding } from '../types/index.js';
+import { OsvCache } from './osv-cache.js';
+export interface PackageQuery {
+    name: string;
+    version: string;
+}
+export declare class OsvClient {
+    private readonly cache;
+    constructor(cache: OsvCache);
+    /**
+     * Look up advisories for every (package, version) pair and return
+     * normalised findings. Cache hits are served without touching the
+     * network; the rest are batched into one (or more, if very large)
+     * POSTs to OSV.
+     */
+    lookup(packages: PackageQuery[]): Promise<DependencyFinding[]>;
+    /**
+     * POST a batch of queries to OSV's `/v1/querybatch`. Splits oversize
+     * input into multiple requests to stay under the per-call limit.
+     */
+    private fetchAdvisoryIds;
+    /**
+     * Hydrate advisory id list into full records. OSV requires one GET
+     * per id (no batch endpoint for full records yet) — we run them in
+     * parallel with a hard concurrency cap so we don't open hundreds of
+     * sockets at once.
+     */
+    private fetchFullAdvisories;
+}
+//# sourceMappingURL=osv-client.d.ts.map

package/dist/security/osv-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osv-client.d.ts","sourceRoot":"","sources":["../../src/security/osv-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAY,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAoB,MAAM,gBAAgB,CAAC;AAQ5D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAyBD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,QAAQ;IAE5C;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAqDpE;;;OAGG;YACW,gBAAgB;IAsC9B;;;;;OAKG;YACW,mBAAmB;CA2BlC"}