autoremediator 0.21.2 → 0.22.0

package/dist/api/prove/index.js

@@ -0,0 +1,289 @@
+/**
+ * Exploit-proof evidence: have an agent write the reproduction that `proofOfFix` needs, and keep
+ * it only if a deterministic harness proves it (fails on the vulnerable version, passes on the
+ * fixed one, repeatably, in a sandbox). See `docs/guides/proof-of-fix-generation.md`.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getModelSpec } from "../../platform/config.js";
+import { findVulnerableSymbols } from "../../remediation/impact/fix-diff.js";
+import { resolveLanguageModel } from "../../remediation/patch/model.js";
+import { isAdvisoryId } from "../incident/target.js";
+import { resolvePatchesDir } from "../patches/helpers.js";
+import { choosePackage, chooseVersions, lookupAdvisoryOsv } from "./advisory.js";
+import { createBuiltinReproductionAgent } from "./agent.js";
+import { baseName, CLAIM, EVIDENCE_SUFFIX, findEvidence, loadSigningKey, relativeTo, scriptFileName, SIGNATURE_SUFFIX, signRecord, } from "./evidence.js";
+import { CONFIRM_RUNS, createHarness, sha256 } from "./harness.js";
+import { fetchVerifiedPackage, installFetchedPackage, listPublishedVersions } from "./install.js";
+import { SANDBOX_ENV, verifySandbox } from "./sandbox.js";
+export { findEvidence, verifyProofEvidence, } from "./evidence.js";
+export { createBuiltinReproductionAgent } from "./agent.js";
+export { screenScript } from "./screen.js";
+export { runSandboxed, SandboxUnavailableError, verifySandbox, } from "./sandbox.js";
+export const defaultProveDeps = {
+    lookupAdvisory: lookupAdvisoryOsv,
+    listVersions: listPublishedVersions,
+    fetchPackage: fetchVerifiedPackage,
+    install: installFetchedPackage,
+    resolveModel: (spec) => resolveLanguageModel(spec),
+    now: () => new Date(),
+};
+const DEFAULT_MAX_TRIALS = 4;
+const DEFAULT_RUN_TIMEOUT_MS = 10_000;
+const MAX_OUTPUT_BYTES = 256 * 1024;
+const AGENT_WALL_MS = 10 * 60_000;
+const NO_MODEL = 'Proof-of-fix generation needs a model to write the reproduction: pass `model` ("<provider>:<model-id>", e.g. "anthropic:claude-sonnet-5-5") or set AUTOREMEDIATOR_MODEL. Nothing was fetched or written.';
+async function resolveAgent(options, deps) {
+    if (options.agent)
+        return options.agent;
+    const spec = getModelSpec(options.model);
+    if (!spec)
+        throw new Error(NO_MODEL);
+    return createBuiltinReproductionAgent(await deps.resolveModel(spec));
+}
+function contextFor(id, looked, advisoryText) {
+    if (looked && !advisoryText)
+        return looked.context;
+    if (looked && advisoryText) {
+        return {
+            ...looked.context,
+            details: `${advisoryText}\n\n${looked.context.details ?? ""}`.trim(),
+        };
+    }
+    const text = advisoryText ?? "";
+    return {
+        id,
+        summary: text.split("\n")[0]?.slice(0, 300) ?? id,
+        details: text,
+        cwes: [],
+        references: [],
+        source: "user",
+    };
+}
+/** Run trials one at a time: they share the two directories. */
+function serialize() {
+    let tail = Promise.resolve();
+    return (task) => {
+        const next = tail.then(task, task);
+        tail = next.catch(() => undefined);
+        return next;
+    };
+}
+export async function generateProofOfFix(cveId, options = {}, deps = defaultProveDeps) {
+    const typedId = cveId.trim();
+    const advisoryId = isAdvisoryId(typedId) ? normalizeAdvisoryId(typedId) : typedId;
+    if (advisoryId === "")
+        throw new Error("Name the advisory: a CVE or GHSA id, or any label together with advisoryText.");
+    if (!options.advisoryText && !isAdvisoryId(advisoryId)) {
+        throw new Error(`"${advisoryId.slice(0, 80)}" is not an advisory id (CVE-, GHSA-, OSV-, MAL-). Give one, or pass advisoryText to describe the vulnerability yourself.`);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const maxTrials = Math.min(10, Math.max(1, Math.trunc(options.maxTrials ?? DEFAULT_MAX_TRIALS)));
+    const timeoutMs = Math.min(60_000, Math.max(1000, Math.trunc(options.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS)));
+    // Everything that can fail cheaply fails before the network is touched or a model is paid for.
+    const agent = await resolveAgent(options, deps);
+    const signingKey = options.signingKeyPath ? loadSigningKey(options.signingKeyPath) : undefined;
+    const sandbox = await verifySandbox();
+    const looked = isAdvisoryId(advisoryId) ? await deps.lookupAdvisory(advisoryId) : undefined;
+    if (!looked && !options.advisoryText) {
+        throw new Error(`${advisoryId} was not found in OSV. Check the id, or pass advisoryText with the package and versions.`);
+    }
+    const advisory = contextFor(looked?.context.id ?? advisoryId, looked, options.advisoryText);
+    const packageName = choosePackage(options.package, looked?.affected ?? []);
+    const published = options.vulnerableVersion ? [] : await deps.listVersions(packageName, cwd);
+    const { vulnerableVersion, fixedVersion } = chooseVersions({
+        packageName,
+        affected: looked?.affected ?? [],
+        published,
+        vulnerableVersion: options.vulnerableVersion,
+        fixedVersion: options.fixedVersion,
+    });
+    const patchesPath = resolvePatchesDir(cwd, options.patchesDir);
+    const scriptPath = join(patchesPath, scriptFileName(packageName, vulnerableVersion));
+    const evidencePath = join(patchesPath, `${baseName(packageName, vulnerableVersion)}${EVIDENCE_SUFFIX}`);
+    if (existsSync(scriptPath) && !options.overwrite && !ownedByEvidence(scriptPath, evidencePath)) {
+        throw new Error(`${relativeTo(cwd, scriptPath)} already exists and was not written by this command. Review it, or pass overwrite to replace it.`);
+    }
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "autoremediator-prove-")));
+    try {
+        const vulnerableDir = join(root, "vulnerable");
+        const fixedDir = join(root, "fixed");
+        mkdirSync(vulnerableDir);
+        mkdirSync(fixedDir);
+        const [vulnerable, fixed] = await Promise.all([
+            deps.fetchPackage(packageName, vulnerableVersion, cwd),
+            deps.fetchPackage(packageName, fixedVersion, cwd),
+        ]);
+        await Promise.all([
+            deps.install(vulnerableDir, vulnerable, cwd),
+            deps.install(fixedDir, fixed, cwd),
+        ]);
+        const candidates = candidateLines(vulnerable, fixed, advisory);
+        const harness = createHarness({
+            packageName,
+            vulnerableVersion,
+            fixedVersion,
+            vulnerableDir,
+            fixedDir,
+            timeoutMs,
+            maxOutputBytes: MAX_OUTPUT_BYTES,
+        });
+        const trials = [];
+        const keep = {};
+        const exclusive = serialize();
+        const trial = (script) => exclusive(async () => {
+            if (keep.value)
+                return keep.value.result;
+            if (trials.length >= maxTrials) {
+                return {
+                    accepted: false,
+                    stage: "screen",
+                    scriptSha256: sha256(script),
+                    reason: "No tries are left; the script was not run.",
+                };
+            }
+            const result = await harness.prove(script);
+            trials.push({
+                attempt: trials.length + 1,
+                accepted: result.accepted,
+                stage: result.stage,
+                reason: result.reason,
+                scriptSha256: result.scriptSha256,
+            });
+            if (result.accepted)
+                keep.value = { script, result };
+            return result;
+        });
+        const outcome = await agent.propose({ advisory, packageName, vulnerableVersion, fixedVersion, candidates, maxTrials }, {
+            sources: { vulnerable: vulnerable.source, fixed: fixed.source },
+            trial,
+            signal: new AbortController().signal,
+            maxWallMs: AGENT_WALL_MS,
+        });
+        const base = {
+            schemaVersion: "1.0",
+            advisoryId,
+            package: packageName,
+            vulnerableVersion,
+            fixedVersion,
+            trials,
+            agent: { id: agent.id, status: outcome.status, rationale: outcome.rationale },
+            usage: outcome.usage,
+            sandbox,
+        };
+        if (!keep.value) {
+            const last = trials.at(-1);
+            return {
+                ...base,
+                status: "rejected",
+                reason: last
+                    ? `No script was kept. The last one was rejected: ${last.reason}`
+                    : `No script was kept: the agent proposed none (${outcome.status}: ${outcome.rationale}).`,
+            };
+        }
+        const { script, result } = keep.value;
+        const record = {
+            schemaVersion: "1.0",
+            kind: "proof-of-fix-evidence",
+            advisoryId,
+            ...(advisory.id !== advisoryId ? { aliases: [advisory.id] } : {}),
+            package: packageName,
+            vulnerableVersion,
+            fixedVersion,
+            claim: CLAIM,
+            script: {
+                path: relativeTo(cwd, scriptPath),
+                sha256: createHash("sha256").update(script).digest("hex"),
+            },
+            vulnerableRun: result.vulnerableRun,
+            fixedRun: result.fixedRun,
+            confirmedRuns: CONFIRM_RUNS,
+            tarballs: {
+                vulnerable: { url: vulnerable.tarballUrl, integrity: vulnerable.integrity },
+                fixed: { url: fixed.tarballUrl, integrity: fixed.integrity },
+            },
+            sandbox: {
+                ...sandbox,
+                env: Object.keys(SANDBOX_ENV),
+                timeoutMs,
+                maxOutputBytes: MAX_OUTPUT_BYTES,
+            },
+            nodeVersion: process.version,
+            timestamp: deps.now().toISOString(),
+            model: outcome.usage[0]?.model ?? null,
+            agent: agent.id,
+            trials: trials.length,
+        };
+        mkdirSync(patchesPath, { recursive: true });
+        const recordText = `${JSON.stringify(record, null, 2)}\n`;
+        writeFileSync(scriptPath, script, "utf8");
+        writeFileSync(evidencePath, recordText, "utf8");
+        let signaturePath;
+        if (signingKey) {
+            signaturePath = `${evidencePath}${SIGNATURE_SUFFIX}`;
+            writeFileSync(signaturePath, `${JSON.stringify(signRecord(Buffer.from(recordText, "utf8"), signingKey), null, 2)}\n`, "utf8");
+        }
+        return {
+            ...base,
+            status: "kept",
+            reason: result.reason,
+            evidence: record,
+            files: {
+                script: relativeTo(cwd, scriptPath),
+                evidence: relativeTo(cwd, evidencePath),
+                ...(signaturePath ? { signature: relativeTo(cwd, signaturePath) } : {}),
+            },
+        };
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** OSV ids are case-sensitive: CVE-, OSV- and MAL- ids are upper case, and GHSA ids are `GHSA-` and lower case. */
+export function normalizeAdvisoryId(id) {
+    return /^GHSA-/i.test(id) ? `GHSA-${id.slice(5).toLowerCase()}` : id.toUpperCase();
+}
+/** A script already at the path that an evidence record of ours vouches for may be replaced. */
+function ownedByEvidence(scriptPath, evidencePath) {
+    try {
+        const record = JSON.parse(readFileSync(evidencePath, "utf8"));
+        return (record.kind === "proof-of-fix-evidence" &&
+            record.script?.sha256 === createHash("sha256").update(readFileSync(scriptPath)).digest("hex"));
+    }
+    catch {
+        return false;
+    }
+}
+function candidateLines(vulnerable, fixed, advisory) {
+    try {
+        const diff = findVulnerableSymbols(vulnerable.source, fixed.source, {
+            hints: {
+                text: [advisory.summary, advisory.details].filter(Boolean).join("\n"),
+                cwes: advisory.cwes,
+            },
+            limit: 8,
+        });
+        return diff.candidates.map((candidate) => `${candidate.specifier} (export ${candidate.exportName}, in ${candidate.file}): ${candidate.reasons.slice(0, 3).join("; ")}`);
+    }
+    catch {
+        // The diff is only a hint for the agent; without it the agent reads the source itself.
+        return [];
+    }
+}
+/** Kept evidence in a patches directory, as the VEX output cites it. Stale evidence (the script changed) is left out. */
+export function proofEvidenceRefs(cwd, patchesDir) {
+    return findEvidence(cwd, patchesDir ?? "./patches")
+        .filter((found) => found.scriptCurrent)
+        .map((found) => ({
+        advisoryIds: [found.record.advisoryId, ...(found.record.aliases ?? [])],
+        packageName: found.record.package,
+        vulnerableVersion: found.record.vulnerableVersion,
+        fixedVersion: found.record.fixedVersion,
+        evidencePath: relativeTo(cwd, found.recordPath),
+        scriptSha256: found.record.script.sha256,
+        signed: found.signaturePath !== undefined,
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/api/prove/index.js.map

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

package/dist/api/prove/install.d.ts

@@ -0,0 +1,24 @@
+import type { FetchedPackage } from "./types.js";
+export declare function assertPackageName(name: string): void;
+export declare function listPublishedVersions(name: string, cwd: string): Promise<string[]>;
+/** Download one version and refuse it unless it matches the registry's digest. */
+export declare function fetchVerifiedPackage(name: string, version: string, cwd: string): Promise<FetchedPackage>;
+/**
+ * Lay the package out as `<dir>/node_modules/<name>` from its verified tarball. `dir` must exist
+ * and be empty. Nothing from the user's project or home directory is read: npm runs with an
+ * environment of its own and no configuration file but the registry URL.
+ */
+export declare function installFetchedPackage(dir: string, fetched: FetchedPackage, cwd: string): Promise<void>;
+/**
+ * The package is attacker-chosen, so its manifest is too. A `file:` or `link:` dependency makes npm
+ * create a symlink to a path of the attacker's choosing, and the sandbox's read permission follows
+ * symlinks. Registry specs only.
+ */
+export declare function assertRegistryOnlyDependencies(manifest: Record<string, unknown>, label: string): void;
+/**
+ * After the install, no symlink may leave the directory (only `node_modules/.bin` links that stay
+ * inside are normal). The sandbox may read everything under `dir`, and a link out of it would let a
+ * script read anything the user can. This also catches links created by transitive dependencies.
+ */
+export declare function assertNoEscapingLinks(dir: string): void;
+//# sourceMappingURL=install.d.ts.map

package/dist/api/prove/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/api/prove/install.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGxF;AAED,kFAAkF;AAClF,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CA2BzB;AAMD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAiDf;AAMD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,MAAM,GACZ,IAAI,CAYN;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA0BvD"}

package/dist/api/prove/install.js

@@ -0,0 +1,150 @@
+/**
+ * Getting two published versions of a package onto disk, each in a directory of its own.
+ *
+ * The package under test is downloaded by us from the configured registry and checked against the
+ * digest the registry advertises before anything touches the disk; a tarball without a digest, or
+ * with one that does not match, is refused. It is then installed from that exact file. Its own
+ * dependencies, if it has any, are resolved by npm from the same registry with lifecycle scripts
+ * disabled; npm checks those against the registry's metadata, we do not check them again.
+ */
+import { mkdirSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import semver from "semver";
+import { downloadTarball, fetchPackageVersions, getTarballInfo, verifyTarballIntegrity, } from "../../intelligence/sources/registry.js";
+import { loadRegistryConfig } from "../../platform/registry-config.js";
+import { safeExeca } from "../../platform/safe-exec.js";
+import { readPackageTarball } from "../../remediation/impact/tarball.js";
+const PACKAGE_NAME = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+export function assertPackageName(name) {
+    if (!PACKAGE_NAME.test(name))
+        throw new Error(`Invalid package name: ${name}`);
+}
+export async function listPublishedVersions(name, cwd) {
+    assertPackageName(name);
+    return fetchPackageVersions(name, loadRegistryConfig(cwd));
+}
+/** Download one version and refuse it unless it matches the registry's digest. */
+export async function fetchVerifiedPackage(name, version, cwd) {
+    assertPackageName(name);
+    if (!semver.valid(version))
+        throw new Error(`Not an exact version: ${version}`);
+    const registry = loadRegistryConfig(cwd);
+    const info = await getTarballInfo(name, version, registry);
+    if (!info)
+        throw new Error(`${name}@${version} was not found on the registry`);
+    const bytes = await downloadTarball(info, registry);
+    const check = verifyTarballIntegrity(bytes, info);
+    if (!check.ok) {
+        throw new Error(`Refusing ${name}@${version}: the tarball failed verification (${check.reason})`);
+    }
+    if (!check.verified || !info.integrity) {
+        throw new Error(`Refusing ${name}@${version}: the registry advertises no integrity digest, so the download cannot be verified.`);
+    }
+    const { files, manifest } = readPackageTarball(bytes);
+    return {
+        name,
+        version,
+        bytes,
+        source: { name, version, files, manifest, integrityVerified: true },
+        integrity: info.integrity,
+        tarballUrl: info.url,
+    };
+}
+function registryUrl(registry, name) {
+    return registry.registryUrlFor(name);
+}
+/**
+ * Lay the package out as `<dir>/node_modules/<name>` from its verified tarball. `dir` must exist
+ * and be empty. Nothing from the user's project or home directory is read: npm runs with an
+ * environment of its own and no configuration file but the registry URL.
+ */
+export async function installFetchedPackage(dir, fetched, cwd) {
+    const tarball = join(dir, "package.tgz");
+    writeFileSync(tarball, fetched.bytes);
+    writeFileSync(join(dir, "package.json"), `${JSON.stringify({ name: "proof-sandbox", version: "0.0.0", private: true })}\n`, "utf8");
+    const home = join(dir, ".npm-home");
+    mkdirSync(home, { recursive: true });
+    assertRegistryOnlyDependencies(fetched.source.manifest, `${fetched.name}@${fetched.version}`);
+    const dependencies = fetched.source.manifest["dependencies"];
+    const hasDependencies = typeof dependencies === "object" &&
+        dependencies !== null &&
+        Object.keys(dependencies).length > 0;
+    const registry = loadRegistryConfig(cwd);
+    await safeExeca("npm", [
+        "install",
+        tarball,
+        "--ignore-scripts",
+        "--omit=dev",
+        "--omit=optional",
+        "--no-audit",
+        "--no-fund",
+        "--no-package-lock",
+        "--no-update-notifier",
+        "--loglevel=error",
+        ...(hasDependencies ? [] : ["--offline"]),
+    ], {
+        cwd: dir,
+        timeoutMs: 180_000,
+        stdio: "pipe",
+        env: {
+            PATH: process.env["PATH"] ?? "",
+            HOME: home,
+            npm_config_cache: join(home, "cache"),
+            npm_config_userconfig: join(home, ".npmrc"),
+            npm_config_globalconfig: join(home, ".npmrc-global"),
+            npm_config_registry: registryUrl(registry, fetched.name.replace(/^@[^/]+\//, "")),
+        },
+    });
+    assertNoEscapingLinks(dir);
+}
+/** What a dependency spec may be: a registry range or tag, never a path, URL, git or workspace reference. */
+const NON_REGISTRY_SPEC = /^(?:file|link|portal|workspace|git|git\+[a-z]+|https?|ssh|github|gitlab|bitbucket|gist):|^[./~\\]|^[^@:\s]+\/[^@:\s]+$/i;
+/**
+ * The package is attacker-chosen, so its manifest is too. A `file:` or `link:` dependency makes npm
+ * create a symlink to a path of the attacker's choosing, and the sandbox's read permission follows
+ * symlinks. Registry specs only.
+ */
+export function assertRegistryOnlyDependencies(manifest, label) {
+    for (const field of ["dependencies", "peerDependencies", "optionalDependencies"]) {
+        const entries = manifest[field];
+        if (typeof entries !== "object" || entries === null)
+            continue;
+        for (const [name, spec] of Object.entries(entries)) {
+            if (typeof spec !== "string" || NON_REGISTRY_SPEC.test(spec.trim())) {
+                throw new Error(`${label} declares ${field}.${name} as "${String(spec).slice(0, 60)}", which is not a registry version; refusing to install it for a proof run.`);
+            }
+        }
+    }
+}
+/**
+ * After the install, no symlink may leave the directory (only `node_modules/.bin` links that stay
+ * inside are normal). The sandbox may read everything under `dir`, and a link out of it would let a
+ * script read anything the user can. This also catches links created by transitive dependencies.
+ */
+export function assertNoEscapingLinks(dir) {
+    const root = realpathSync(dir);
+    const visit = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                const inBin = relative(root, current).split(sep).slice(-2).join("/") === "node_modules/.bin";
+                let target;
+                try {
+                    target = realpathSync(full);
+                }
+                catch {
+                    target = undefined;
+                }
+                const inside = target !== undefined && (target === root || target.startsWith(root + sep));
+                if (!inBin || !inside) {
+                    throw new Error(`The installed package tree contains a symbolic link (${relative(root, full)}); refusing to run a proof inside it.`);
+                }
+            }
+            else if (entry.isDirectory()) {
+                visit(full);
+            }
+        }
+    };
+    visit(root);
+}
+//# sourceMappingURL=install.js.map

package/dist/api/prove/install.js.map

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

package/dist/api/prove/sandbox.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Variables macOS adds to every process whatever it is started with. It holds the user id and a
+ * text encoding, nothing secret; it is allowed in the self-test and never passed on by us.
+ */
+export declare const PLATFORM_INJECTED_ENV: ReadonlySet<string>;
+/** The only environment a sandboxed script sees. */
+export declare const SANDBOX_ENV: Readonly<Record<string, string>>;
+export interface SandboxOptions {
+    /** Directory holding the script. The only place the script may read. */
+    dir: string;
+    /** File name of the script inside `dir`. */
+    script: string;
+    timeoutMs: number;
+    /** Stdout plus stderr beyond this many bytes ends the run. */
+    maxOutputBytes: number;
+    /** V8 old-space limit in MiB. */
+    maxHeapMb?: number;
+}
+export interface SandboxResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    outputLimitExceeded: boolean;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+}
+export declare class SandboxUnavailableError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Run `script` under the permission model. Resolves with what happened; rejects only if it cannot start. */
+export declare function runSandboxed(options: SandboxOptions): Promise<SandboxResult>;
+/** What the self-test established, kept in the evidence record. */
+export interface SandboxReport {
+    node: string;
+    platform: string;
+    /** Each capability the self-test tried and found refused. */
+    denied: string[];
+    /** What the sandbox does not limit (stated, not tested). */
+    notLimited: string[];
+}
+export declare const NOT_LIMITED: string[];
+/**
+ * Prove, on this machine and this Node.js, that the sandbox refuses what it claims to refuse, by
+ * trying each thing from inside it. Throws `SandboxUnavailableError` when it does not. Cached.
+ */
+export declare function verifySandbox(): Promise<SandboxReport>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/api/prove/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/api/prove/sandbox.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAwC,CAAC;AAE/F,oDAAoD;AACpD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxD,CAAC;AAsBF,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF;AAED,6GAA6G;AAC7G,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAyF5E;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,UAIvB,CAAC;AAuIF;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAMtD"}