@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

package/dist/runtime/workspace-resource-estimator.js

@@ -0,0 +1,174 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+const GiB = 1024 ** 3;
+const alignmentBytes = 512 * 1024 ** 2;
+export const minimumWorkspaceEstimateBytes = 2 * GiB;
+export const architectMinimumWorkspaceEstimateBytes = GiB;
+const maximumBytes = 100 * GiB;
+const footprintCacheLifetimeMs = 5 * 60_000;
+const excludedDirectories = new Set([
+    ".git",
+    ".artifacts",
+    ".forge-worktrees",
+    ".local",
+    ".next",
+    ".nuget",
+    ".pnpm-store",
+    ".tmp",
+    ".turbo",
+    "artifacts",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+    "testresults",
+]);
+const footprintCache = new Map();
+export async function estimateWorkspaceBytesFromRepo(repoPath, hints = {}) {
+    const cacheKey = path.resolve(repoPath);
+    const cached = footprintCache.get(cacheKey);
+    const footprint = cached && Date.now() - cached.measuredAt < footprintCacheLifetimeMs
+        ? cached.footprint
+        : await measureRepositoryWorkspace(cacheKey);
+    if (!cached || cached.footprint !== footprint) {
+        footprintCache.set(cacheKey, { measuredAt: Date.now(), footprint });
+    }
+    return calculateWorkspaceBytes({
+        ...footprint,
+        hasBrowser: footprint.hasBrowser || hints.browser === true,
+        serviceCount: Math.max(footprint.serviceCount, Math.max(0, hints.serviceCount ?? 0)),
+    }, hints.role);
+}
+export function calculateWorkspaceBytes(footprint, role) {
+    const normalizedRole = role?.trim().toLowerCase() ?? "";
+    if (normalizedRole === "architect") {
+        // Architect owns a checkout and planning artifacts, not dependencies,
+        // build outputs, browser state, services, or application runtime output.
+        const estimate = architectMinimumWorkspaceEstimateBytes
+            + Math.max(0, footprint.sourceBytes) * 2;
+        return Math.min(maximumBytes, Math.max(architectMinimumWorkspaceEstimateBytes, alignUp(estimate, alignmentBytes)));
+    }
+    let estimate = 2 * GiB + Math.max(0, footprint.sourceBytes) * 3;
+    if (footprint.hasNode)
+        estimate += 3 * GiB;
+    if (footprint.hasDotNet)
+        estimate += 2 * GiB;
+    if (footprint.hasBrowser)
+        estimate += 1536 * 1024 ** 2;
+    estimate += Math.max(0, footprint.serviceCount) * GiB;
+    if (["qa", "ci_repair", "pr_fix"].includes(normalizedRole)) {
+        estimate += GiB;
+    }
+    return Math.min(maximumBytes, Math.max(minimumWorkspaceEstimateBytes, alignUp(estimate, alignmentBytes)));
+}
+export async function measureRepositoryWorkspace(repoPath) {
+    return await measureGitWorkspace(repoPath) ?? await measureFilesystemFallback(repoPath);
+}
+async function measureGitWorkspace(repoPath) {
+    let sourceBytes = 0;
+    let hasNode = false;
+    let hasDotNet = false;
+    let hasBrowser = false;
+    let serviceCount = 0;
+    const child = spawn("git", ["-c", "core.quotepath=false", "ls-files", "--cached", "--others", "--exclude-standard"], {
+        cwd: repoPath,
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+    });
+    const closed = new Promise((resolve) => {
+        child.once("close", resolve);
+        child.once("error", () => resolve(null));
+    });
+    try {
+        const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+        for await (const relativePath of lines) {
+            if (!relativePath.trim())
+                continue;
+            const file = await inspectWorkspaceFile(path.join(repoPath, relativePath));
+            if (!file)
+                continue;
+            sourceBytes += file.bytes;
+            hasNode ||= file.hasNode;
+            hasDotNet ||= file.hasDotNet;
+            hasBrowser ||= file.hasBrowser;
+            serviceCount = Math.max(serviceCount, file.serviceCount);
+        }
+        return await closed === 0 ? { sourceBytes, hasNode, hasDotNet, hasBrowser, serviceCount } : null;
+    }
+    catch {
+        child.kill();
+        await closed;
+        return null;
+    }
+}
+async function measureFilesystemFallback(repoPath) {
+    let sourceBytes = 0;
+    let hasNode = false;
+    let hasDotNet = false;
+    let hasBrowser = false;
+    let serviceCount = 0;
+    const pending = [path.resolve(repoPath)];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!excludedDirectories.has(entry.name.toLowerCase()))
+                    pending.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const file = await inspectWorkspaceFile(entryPath);
+            if (!file)
+                continue;
+            sourceBytes += file.bytes;
+            hasNode ||= file.hasNode;
+            hasDotNet ||= file.hasDotNet;
+            hasBrowser ||= file.hasBrowser;
+            serviceCount = Math.max(serviceCount, file.serviceCount);
+        }
+    }
+    return { sourceBytes, hasNode, hasDotNet, hasBrowser, serviceCount };
+}
+async function inspectWorkspaceFile(filePath) {
+    const stat = await fs.stat(filePath).catch(() => null);
+    if (!stat?.isFile())
+        return null;
+    const name = path.basename(filePath).toLowerCase();
+    const sandbox = name === "forge.sandbox.yml" || name === "forge.sandbox.yaml";
+    return {
+        bytes: stat.size,
+        hasNode: ["package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"].includes(name),
+        hasDotNet: name.endsWith(".sln") || name.endsWith(".csproj") || name.endsWith(".fsproj"),
+        hasBrowser: name.startsWith("playwright.config"),
+        serviceCount: sandbox
+            ? countSandboxServices(await fs.readFile(filePath, "utf8").catch(() => ""))
+            : 0,
+    };
+}
+function countSandboxServices(yaml) {
+    let inServices = false;
+    let count = 0;
+    for (const rawLine of yaml.split(/\r?\n/gu)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (!/^\s/u.test(rawLine)) {
+            inServices = line.toLowerCase() === "services:";
+            continue;
+        }
+        if (inServices && line.startsWith("-"))
+            count += 1;
+    }
+    return count;
+}
+function alignUp(value, alignment) {
+    return Math.ceil(value / alignment) * alignment;
+}

package/dist/sandbox/command-runner.d.ts

@@ -0,0 +1,4 @@
+import type { CommandOptions, CommandResult, CommandRunner } from "./sandbox.types.js";
+export declare class BoundedCommandRunner implements CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}

package/dist/sandbox/command-runner.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+export class BoundedCommandRunner {
+    async run(command, args, options = {}) {
+        const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+        return await new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const abort = () => controller.abort(options.signal?.reason ?? "command cancelled");
+            options.signal?.addEventListener("abort", abort, { once: true });
+            const timeout = options.timeoutMs
+                ? setTimeout(() => controller.abort(`command exceeded ${options.timeoutMs}ms`), options.timeoutMs)
+                : null;
+            timeout?.unref?.();
+            const child = spawn(command, [...args], {
+                cwd: options.cwd,
+                env: options.env ? { ...options.env } : undefined,
+                stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+                signal: controller.signal,
+                windowsHide: true,
+            });
+            let stdout = Buffer.alloc(0);
+            let stderr = Buffer.alloc(0);
+            const append = (current, chunk) => {
+                if (current.length >= maxOutputBytes)
+                    return current;
+                return Buffer.concat([current, chunk.subarray(0, maxOutputBytes - current.length)]);
+            };
+            child.stdout.on("data", (chunk) => { stdout = append(stdout, chunk); });
+            child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
+            child.on("error", (error) => {
+                cleanup();
+                reject(error);
+            });
+            child.on("close", (code) => {
+                cleanup();
+                resolve({ exitCode: code ?? 1, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8") });
+            });
+            if (options.stdin !== undefined) {
+                child.stdin.end(options.stdin);
+            }
+            function cleanup() {
+                if (timeout)
+                    clearTimeout(timeout);
+                options.signal?.removeEventListener("abort", abort);
+            }
+        });
+    }
+}

package/dist/sandbox/contract.d.ts

@@ -0,0 +1,5 @@
+import type { ValidatedSandboxContract } from "./sandbox.types.js";
+export declare function validateSandboxContract(source: string): ValidatedSandboxContract;
+export declare function validateDockerfilePolicy(source: string, requirePinnedBase: boolean): readonly string[];
+export declare function dockerfileBaseImages(source: string): readonly string[];
+export declare function dockerfileUpstreamImages(source: string): readonly string[];

package/dist/sandbox/contract.js

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import { isAlias, parseDocument, visit } from "yaml";
+const maxContractBytes = 64 * 1024;
+const maxDepth = 16;
+const topLevelKeys = new Set(["schemaVersion", "workingDirectory", "commands", "caches", "services", "environment", "artifacts", "logs", "browser"]);
+const forbiddenKeys = new Set([
+    "privileged", "cap_add", "capAdd", "devices", "device", "network_mode", "networkMode", "pid", "ipc",
+    "userns_mode", "usernsMode", "security_opt", "securityOpt", "volumes", "mounts", "binds", "dockerSocket",
+    "hostNetwork", "extra_hosts", "extraHosts", "ports", "secrets", "buildSecrets", "ssh", "entitlements"
+]);
+const allowedCaches = new Set(["npm", "pnpm", "yarn", "nuget", "pip", "cargo", "gradle", "maven"]);
+const defaultPorts = { postgres: 5432, redis: 6379, browser: 9222 };
+export function validateSandboxContract(source) {
+    const bytes = Buffer.byteLength(source, "utf8");
+    if (bytes === 0 || bytes > maxContractBytes)
+        throw new Error(`contract_invalid: forge.sandbox.yml must be 1-${maxContractBytes} bytes.`);
+    if (containsForbiddenControlCharacter(source)) {
+        throw new Error("contract_invalid: control characters are not allowed.");
+    }
+    const document = parseDocument(source, { uniqueKeys: true, prettyErrors: false, strict: true });
+    if (document.errors.length > 0)
+        throw new Error(`contract_invalid: ${document.errors[0]?.message ?? "invalid YAML"}`);
+    visit(document, {
+        Node(_key, node) {
+            if (isAlias(node) || node.anchor)
+                throw new Error("contract_invalid: YAML aliases and anchors are not allowed.");
+        }
+    });
+    const parsed = document.toJS({ maxAliasCount: 0 });
+    assertDepth(parsed, 0);
+    const root = object(parsed, "contract");
+    rejectUnknownKeys(root, topLevelKeys, "contract");
+    rejectForbiddenKeys(root, "contract");
+    if (root.schemaVersion !== 1)
+        throw new Error("contract_invalid: schemaVersion must be 1.");
+    const workingDirectory = root.workingDirectory ?? "/workspace";
+    if (workingDirectory !== "/workspace")
+        throw new Error("contract_invalid: workingDirectory must be /workspace.");
+    const contract = {
+        schemaVersion: 1,
+        workingDirectory: "/workspace",
+        commands: parseCommands(root.commands),
+        caches: parseCaches(root.caches),
+        services: parseServices(root.services),
+        environment: stringArray(root.environment, "environment", 64).map(validateEnvironmentName),
+        artifacts: stringArray(root.artifacts, "artifacts", 128).map((value) => validateRelativePath(value, "artifacts")),
+        logs: stringArray(root.logs, "logs", 128).map((value) => validateRelativePath(value, "logs")),
+        browser: optionalBoolean(root.browser, "browser") ?? false,
+    };
+    const normalizedJson = canonicalJson(contract);
+    const digest = `sha256:${createHash("sha256").update(normalizedJson).digest("hex")}`;
+    return { contract, normalizedJson, digest };
+}
+function containsForbiddenControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint === 0x7f
+            || (codePoint < 0x20 && codePoint !== 0x09 && codePoint !== 0x0a && codePoint !== 0x0d);
+    });
+}
+export function validateDockerfilePolicy(source, requirePinnedBase) {
+    if (Buffer.byteLength(source, "utf8") > 1024 * 1024)
+        throw new Error("contract_invalid: Dockerfile exceeds 1 MiB.");
+    if (containsForbiddenControlCharacter(source))
+        throw new Error("contract_invalid: Dockerfile control characters are not allowed.");
+    const logicalSource = source.replace(/\\\r?\n/gu, " ");
+    if (/^\s*#\s*syntax\s*=/imu.test(source)) {
+        throw new Error("contract_invalid: custom Dockerfile syntax frontends are forbidden.");
+    }
+    if (/^\s*#\s*escape\s*=/imu.test(source)) {
+        throw new Error("contract_invalid: custom Dockerfile escape directives are forbidden.");
+    }
+    if (/^\s*(?:ONBUILD\s+)?RUN\b[^\r\n]*--mount\s*=\s*type\s*=\s*(?:secret|ssh|bind)\b/imu.test(logicalSource)) {
+        throw new Error("contract_invalid: Dockerfile secret, SSH, and bind build mounts are forbidden.");
+    }
+    if (/^\s*(?:ONBUILD\s+)?RUN\b[^\r\n]*--(?:network\s*=\s*host|security\s*=\s*insecure|device(?:\s|=))/imu.test(logicalSource)) {
+        throw new Error("contract_invalid: Dockerfile host-network, insecure-security, and device build options are forbidden.");
+    }
+    if (/^\s*(?:ONBUILD\s+)?VOLUME(?:\s|\[)/imu.test(source)) {
+        throw new Error("contract_invalid: Dockerfile VOLUME instructions are forbidden; Forge owns writable mounts.");
+    }
+    const warnings = [];
+    for (const image of dockerfileUpstreamImages(source)) {
+        if (!/@sha256:[a-f0-9]{64}$/iu.test(image)) {
+            const message = `Upstream image '${image}' is not pinned by sha256 digest.`;
+            if (requirePinnedBase)
+                throw new Error(`contract_invalid: ${message}`);
+            warnings.push(message);
+        }
+    }
+    return warnings;
+}
+export function dockerfileBaseImages(source) {
+    if (Buffer.byteLength(source, "utf8") > 1024 * 1024)
+        throw new Error("contract_invalid: Dockerfile exceeds 1 MiB.");
+    const fromLines = source.replace(/\\\r?\n/gu, " ").split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => /^FROM\s+/iu.test(line));
+    if (fromLines.length === 0)
+        throw new Error("contract_invalid: .forge/Dockerfile must contain FROM.");
+    const stageAliases = new Set();
+    const externalImages = [];
+    for (const line of fromLines) {
+        const tokens = line.split(/\s+/u).slice(1);
+        const imageIndex = tokens.findIndex((token) => !token.startsWith("--"));
+        const image = imageIndex >= 0 ? tokens[imageIndex] ?? "" : "";
+        if (!image || /[\r\n\0]/u.test(image))
+            throw new Error("contract_invalid: Dockerfile FROM image is invalid.");
+        if (!stageAliases.has(image.toLowerCase()))
+            externalImages.push(image);
+        const asIndex = tokens.findIndex((token, index) => index > imageIndex && token.toUpperCase() === "AS");
+        const alias = asIndex >= 0 ? tokens[asIndex + 1] : undefined;
+        if (alias) {
+            if (!/^[a-zA-Z0-9_.-]{1,128}$/u.test(alias))
+                throw new Error("contract_invalid: Dockerfile stage alias is invalid.");
+            stageAliases.add(alias.toLowerCase());
+        }
+    }
+    return [...new Set(externalImages)];
+}
+export function dockerfileUpstreamImages(source) {
+    const bases = dockerfileBaseImages(source);
+    const logicalLines = source.replace(/\\\r?\n/gu, " ").split(/\r?\n/u).map(line => line.trim());
+    const stageAliases = new Set();
+    for (const line of logicalLines.filter(line => /^FROM\s+/iu.test(line))) {
+        const tokens = line.split(/\s+/u).slice(1);
+        const imageIndex = tokens.findIndex(token => !token.startsWith("--"));
+        const asIndex = tokens.findIndex((token, index) => index > imageIndex && token.toUpperCase() === "AS");
+        const alias = asIndex >= 0 ? tokens[asIndex + 1] : undefined;
+        if (alias)
+            stageAliases.add(alias.toLowerCase());
+    }
+    const copyImages = logicalLines
+        .filter(line => /^\s*(?:ONBUILD\s+)?COPY\b/iu.test(line))
+        .map(line => /(?:^|\s)--from=([^\s]+)/iu.exec(line)?.[1] ?? "")
+        .filter(image => image && !/^\d+$/u.test(image) && !stageAliases.has(image.toLowerCase()));
+    return [...new Set([...bases, ...copyImages])];
+}
+function parseCommands(value) {
+    if (value === undefined || value === null)
+        return {};
+    const commands = object(value, "commands");
+    if (Object.keys(commands).length > 32)
+        throw new Error("contract_invalid: commands cannot contain more than 32 entries.");
+    const result = {};
+    for (const [name, command] of Object.entries(commands)) {
+        if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(name) || typeof command !== "string" || !command.trim() || command.length > 4096) {
+            throw new Error("contract_invalid: commands must map safe names to non-empty strings.");
+        }
+        result[name] = command.trim();
+    }
+    return result;
+}
+function parseCaches(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("contract_invalid: caches must be an array.");
+    if (value.length > allowedCaches.size)
+        throw new Error(`contract_invalid: caches cannot contain more than ${allowedCaches.size} entries.`);
+    const seen = new Set();
+    return value.map((entry, index) => {
+        const cache = typeof entry === "string" ? { name: entry } : object(entry, `caches[${index}]`);
+        rejectUnknownKeys(cache, new Set(["name", "mode"]), `caches[${index}]`);
+        const name = requiredString(cache.name, `caches[${index}].name`).toLowerCase();
+        if (!allowedCaches.has(name))
+            throw new Error(`contract_invalid: cache '${name}' is not allowlisted.`);
+        if (seen.has(name))
+            throw new Error(`contract_invalid: duplicate cache '${name}'.`);
+        seen.add(name);
+        const mode = cache.mode ?? "readonly";
+        if (mode !== "readonly" && mode !== "per_attempt")
+            throw new Error("contract_invalid: cache mode must be readonly or per_attempt.");
+        return { name, mode };
+    });
+}
+function parseServices(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("contract_invalid: services must be an array.");
+    if (value.length > 3)
+        throw new Error("contract_invalid: services cannot contain more than 3 entries.");
+    const seen = new Set();
+    return value.map((entry, index) => {
+        const service = typeof entry === "string" ? { type: entry } : object(entry, `services[${index}]`);
+        rejectUnknownKeys(service, new Set(["type", "port"]), `services[${index}]`);
+        const type = requiredString(service.type, `services[${index}].type`).toLowerCase();
+        if (type !== "postgres" && type !== "redis" && type !== "browser")
+            throw new Error(`contract_invalid: service '${type}' is not in the Forge catalogue.`);
+        if (seen.has(type))
+            throw new Error(`contract_invalid: duplicate service '${type}'.`);
+        seen.add(type);
+        const port = service.port === undefined ? defaultPorts[type] : positivePort(service.port, `services[${index}].port`);
+        return { type, port };
+    });
+}
+function rejectForbiddenKeys(value, path) {
+    if (Array.isArray(value))
+        return value.forEach((entry, index) => rejectForbiddenKeys(entry, `${path}[${index}]`));
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (forbiddenKeys.has(key))
+            throw new Error(`contract_invalid: forbidden privilege key '${path}.${key}'.`);
+        rejectForbiddenKeys(child, `${path}.${key}`);
+    }
+}
+function assertDepth(value, depth) {
+    if (depth > maxDepth)
+        throw new Error(`contract_invalid: YAML nesting exceeds ${maxDepth}.`);
+    if (Array.isArray(value)) {
+        value.forEach((entry) => assertDepth(entry, depth + 1));
+    }
+    else if (value && typeof value === "object") {
+        Object.values(value).forEach((entry) => assertDepth(entry, depth + 1));
+    }
+}
+function validateRelativePath(value, field) {
+    const normalized = value.trim().replace(/\\/gu, "/");
+    if (!normalized || normalized.length > 512 || normalized.startsWith("/") || normalized.includes("\0") || normalized.split("/").some((part) => part === ".." || part === "." || !part)) {
+        throw new Error(`contract_invalid: ${field} paths must be normalized relative paths under /workspace.`);
+    }
+    return normalized;
+}
+function validateEnvironmentName(value) {
+    const name = value.trim();
+    if (!/^[A-Z_][A-Z0-9_]{0,127}$/u.test(name) || name.startsWith("FORGE_") || name === "HOME" || name === "PATH") {
+        throw new Error(`contract_invalid: environment variable '${name}' is reserved or invalid.`);
+    }
+    return name;
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`contract_invalid: ${label} must be an object.`);
+    return value;
+}
+function rejectUnknownKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new Error(`contract_invalid: unknown ${label} key '${unknown[0]}'.`);
+}
+function stringArray(value, label, maximumCount) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+        throw new Error(`contract_invalid: ${label} must be a string array.`);
+    if (value.length > maximumCount)
+        throw new Error(`contract_invalid: ${label} cannot contain more than ${maximumCount} entries.`);
+    return [...new Set(value.map((entry) => entry.trim()))];
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`contract_invalid: ${label} must be a non-empty string.`);
+    return value.trim();
+}
+function optionalBoolean(value, label) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "boolean")
+        throw new Error(`contract_invalid: ${label} must be boolean.`);
+    return value;
+}
+function positivePort(value, label) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 65535)
+        throw new Error(`contract_invalid: ${label} must be a valid internal port.`);
+    return value;
+}

package/dist/sandbox/event-budget.d.ts

@@ -0,0 +1,11 @@
+export declare class SandboxEventBudget {
+    private readonly maximumCount;
+    private readonly maximumBytes;
+    private readonly maximumPerSecond;
+    private totalCount;
+    private totalBytes;
+    private windowStartedMs;
+    private windowCount;
+    constructor(maximumCount?: number, maximumBytes?: number, maximumPerSecond?: number, nowMs?: number);
+    accept(line: string, nowMs?: number): void;
+}

package/dist/sandbox/event-budget.js

@@ -0,0 +1,27 @@
+export class SandboxEventBudget {
+    maximumCount;
+    maximumBytes;
+    maximumPerSecond;
+    totalCount = 0;
+    totalBytes = 0;
+    windowStartedMs;
+    windowCount = 0;
+    constructor(maximumCount = 100_000, maximumBytes = 64 * 1024 * 1024, maximumPerSecond = 1_000, nowMs = performance.now()) {
+        this.maximumCount = maximumCount;
+        this.maximumBytes = maximumBytes;
+        this.maximumPerSecond = maximumPerSecond;
+        this.windowStartedMs = nowMs;
+    }
+    accept(line, nowMs = performance.now()) {
+        if (nowMs - this.windowStartedMs >= 1_000) {
+            this.windowStartedMs = nowMs;
+            this.windowCount = 0;
+        }
+        this.totalCount += 1;
+        this.windowCount += 1;
+        this.totalBytes += Buffer.byteLength(line, "utf8");
+        if (this.totalCount > this.maximumCount || this.totalBytes > this.maximumBytes || this.windowCount > this.maximumPerSecond) {
+            throw new Error("sandbox_event_flood: sandbox event rate or total volume exceeded its bounded budget.");
+        }
+    }
+}

package/dist/sandbox/image-policy.d.ts

@@ -0,0 +1,35 @@
+import { type SandboxProcessRequest, type SandboxProcessResult } from "./process.js";
+export type SandboxImageLayer = "project" | "tooling" | "agent";
+export interface SandboxImagePolicyRequest {
+    readonly key: string;
+    readonly project: string;
+    readonly executionPolicy: string;
+    readonly stateRoot: string;
+    readonly builderVersion: string;
+    readonly contextDigest: string;
+    readonly contractDigest: string;
+    readonly toolingImage: string;
+    readonly upstreamImages: readonly string[];
+    readonly codexVersion: string;
+    readonly images: Readonly<Record<SandboxImageLayer, string>>;
+    readonly imageScanTargets?: Readonly<Partial<Record<SandboxImageLayer, string>>>;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly runCommand?: (command: SandboxProcessRequest) => Promise<SandboxProcessResult>;
+}
+export interface SandboxImagePolicyResult {
+    readonly status: "passed" | "warning";
+    readonly policyDigest: string;
+    readonly root: string;
+}
+export declare function evaluateSandboxImagePolicy(request: SandboxImagePolicyRequest): Promise<SandboxImagePolicyResult>;
+export interface SandboxImageSignatureRequest {
+    readonly image: string;
+    readonly executionPolicy: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly runCommand?: (command: SandboxProcessRequest) => Promise<SandboxProcessResult>;
+}
+export declare function verifySandboxImageSignature(request: SandboxImageSignatureRequest): Promise<"passed" | "warning">;
+export declare function hasSandboxImagePolicyRecord(stateRoot: string, key: string, expectedDigest: string, requirePassed?: boolean): Promise<boolean>;
+export declare function sandboxImagePolicyConfigurationDigest(environment?: NodeJS.ProcessEnv): Promise<string>;