@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba7d36726eda

package/dist/runtime/runtime-isolation-lease.js

@@ -0,0 +1,158 @@
+export const runtimeIsolationLeaseStates = [
+    "reserved",
+    "starting",
+    "active",
+    "releasing",
+    "released",
+    "degraded",
+];
+const allowedTransitions = {
+    reserved: new Set(["starting", "releasing", "degraded"]),
+    starting: new Set(["active", "releasing", "degraded"]),
+    active: new Set(["releasing", "degraded"]),
+    releasing: new Set(["released", "degraded"]),
+    released: new Set(),
+    degraded: new Set(["releasing"]),
+};
+export function createRuntimeIsolationLease(input) {
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const lease = {
+        schemaVersion: 1,
+        leaseId: input.leaseId,
+        dispatchAttemptId: input.dispatchAttemptId,
+        executionLeaseId: input.executionLeaseId,
+        fencingToken: input.fencingToken,
+        runnerId: input.runnerId,
+        runnerInstanceId: input.runnerInstanceId,
+        worktreeKey: input.worktreeKey,
+        worktreePath: input.worktreePath,
+        mode: input.mode,
+        state: "reserved",
+        createdAt,
+        stateChangedAt: createdAt,
+        expiresAt: input.expiresAt,
+        releasedAt: null,
+        resources: input.resources,
+    };
+    if (!validRuntimeIsolationLease(lease)) {
+        throw new Error("runtime_lease_invalid: lease identity, lifetime, or resources are invalid.");
+    }
+    return lease;
+}
+export function transitionRuntimeIsolationLease(lease, nextState, occurredAt = new Date().toISOString()) {
+    if (lease.state === nextState)
+        return lease;
+    if (!allowedTransitions[lease.state].has(nextState) || !validTimestamp(occurredAt)) {
+        throw new Error(`runtime_lease_transition_invalid: cannot transition ${lease.state} to ${nextState}.`);
+    }
+    const transitioned = {
+        ...lease,
+        state: nextState,
+        stateChangedAt: occurredAt,
+        releasedAt: nextState === "released" ? occurredAt : null,
+    };
+    if (!validRuntimeIsolationLease(transitioned)) {
+        throw new Error("runtime_lease_invalid: transitioned lease is invalid.");
+    }
+    return transitioned;
+}
+export function renewRuntimeIsolationLease(lease, fencingToken, expiresAt) {
+    if (lease.fencingToken !== fencingToken || lease.state === "released" || !validTimestamp(expiresAt))
+        return null;
+    const renewed = { ...lease, expiresAt };
+    return validRuntimeIsolationLease(renewed) ? renewed : null;
+}
+export function withRuntimeIsolationResources(lease, resources) {
+    if (lease.state === "released") {
+        throw new Error("runtime_lease_transition_invalid: released leases cannot acquire resources.");
+    }
+    const updated = { ...lease, resources };
+    if (!validRuntimeIsolationLease(updated)) {
+        throw new Error("runtime_lease_invalid: resources are invalid.");
+    }
+    return updated;
+}
+export function validRuntimeIsolationLease(value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 1
+        || !isUuid(value.leaseId)
+        || !isUuid(value.dispatchAttemptId)
+        || !isUuid(value.executionLeaseId)
+        || !isUuid(value.fencingToken)
+        || !isUuid(value.runnerId)
+        || !isUuid(value.runnerInstanceId)
+        || !boundedText(value.worktreeKey, 255)
+        || !boundedText(value.worktreePath, 4096)
+        || (value.mode !== "docker" && value.mode !== "host")
+        || !runtimeIsolationLeaseStates.includes(value.state)
+        || !validTimestamp(value.createdAt)
+        || !validTimestamp(value.stateChangedAt)
+        || !validTimestamp(value.expiresAt)
+        || Date.parse(value.stateChangedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.expiresAt) < Date.parse(value.createdAt)
+        || (value.state === "released") !== validTimestamp(value.releasedAt)) {
+        return false;
+    }
+    if (value.releasedAt !== null && Date.parse(value.releasedAt) < Date.parse(value.createdAt))
+        return false;
+    return validResources(value.resources, value.mode);
+}
+function validResources(value, mode) {
+    if (!isRecord(value)
+        || !nonNegativeInteger(value.memoryReservationBytes)
+        || !nonNegativeInteger(value.cpuMillis)
+        || !nonNegativeInteger(value.pids)
+        || !Array.isArray(value.ports) || value.ports.length > 64
+        || !Array.isArray(value.paths) || value.paths.length > 64
+        || !Array.isArray(value.dockerResources) || value.dockerResources.length > 128
+        || !Array.isArray(value.singletonKeys) || value.singletonKeys.length > 64
+        || (value.processSupervisorId !== null && !boundedText(value.processSupervisorId, 255))) {
+        return false;
+    }
+    if (value.ports.some(port => !validPort(port))
+        || value.paths.some(entry => !isRecord(entry) || !boundedText(entry.path, 4096) || !boundedText(entry.role, 128))
+        || value.singletonKeys.some(key => !boundedText(key, 255))
+        || value.dockerResources.some(resource => !validDockerResource(resource))) {
+        return false;
+    }
+    return mode === "docker" || value.dockerResources.length === 0;
+}
+function validPort(value) {
+    return isRecord(value)
+        && boundedText(value.name, 128)
+        && (value.protocol === "tcp" || value.protocol === "udp")
+        && (value.hostIp === "127.0.0.1" || value.hostIp === "::1")
+        && validPortNumber(value.hostPort)
+        && validPortNumber(value.targetPort);
+}
+function validDockerResource(value) {
+    return isRecord(value)
+        && (value.type === "container" || value.type === "network" || value.type === "volume")
+        && boundedText(value.name, 255)
+        && boundedText(value.role, 128)
+        && (value.id === undefined || value.id === null || boundedText(value.id, 255));
+}
+function validPortNumber(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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>;