@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.3-dev.fbe15023cdfe

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

package/dist/sandbox/image-policy.js

@@ -0,0 +1,247 @@
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runSandboxProcess } from "./process.js";
+export async function evaluateSandboxImagePolicy(request) {
+    const environment = request.environment ?? process.env;
+    const required = request.executionPolicy === "sandbox_required";
+    const enforced = environment.FORGE_SANDBOX_IMAGE_POLICY_ENFORCED === "true";
+    const sbomExecutable = environment.FORGE_SANDBOX_SBOM_EXECUTABLE?.trim();
+    const vulnerabilityExecutable = environment.FORGE_SANDBOX_VULNERABILITY_EXECUTABLE?.trim();
+    const signingKeyPath = environment.FORGE_SANDBOX_PROVENANCE_SIGNING_KEY?.trim();
+    const signatureExecutable = environment.FORGE_SANDBOX_SIGNATURE_EXECUTABLE?.trim();
+    const signaturePublicKey = environment.FORGE_SANDBOX_SIGNATURE_PUBLIC_KEY?.trim();
+    if (required && (!enforced || !sbomExecutable || !vulnerabilityExecutable || !signingKeyPath || !signatureExecutable || !signaturePublicKey)) {
+        throw new Error("sandbox_build_policy_failed: sandbox_required needs enforced SBOM, vulnerability, provenance-signing, and upstream-signature configuration.");
+    }
+    const root = path.join(request.stateRoot, "attestations", request.key);
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    const artifacts = {};
+    let status = "passed";
+    const privateKey = signingKeyPath ? await readSigningKey(signingKeyPath) : null;
+    const runCommand = request.runCommand ?? runSandboxProcess;
+    const upstreamSignatures = {};
+    for (const image of [...new Set([request.toolingImage, ...request.upstreamImages])]) {
+        const signatureStatus = await verifySandboxImageSignature({
+            image,
+            executionPolicy: request.executionPolicy,
+            environment,
+            signal: request.signal,
+            runCommand
+        });
+        upstreamSignatures[image] = signatureStatus;
+        if (signatureStatus === "warning")
+            status = "warning";
+    }
+    for (const [layer, imageDigest] of Object.entries(request.images)) {
+        const scanTarget = request.imageScanTargets?.[layer] ?? imageDigest;
+        const provenance = {
+            schemaVersion: 1,
+            predicateType: "https://slsa.dev/provenance/v1",
+            subject: [{ name: `forge/${layer}`, digest: { sha256: imageDigest.slice("sha256:".length) } }],
+            builder: { id: `forge-bridge/${request.builderVersion}` },
+            buildType: "https://forge.dev/buildkit/project-agent-overlay/v1",
+            invocation: { parameters: { key: request.key, project: request.project, layer } },
+            materials: [
+                { uri: "forge:tracked-context", digest: { sha256: request.contextDigest } },
+                { uri: "forge:sandbox-contract", digest: { sha256: request.contractDigest.replace(/^sha256:/u, "") } },
+                { uri: request.toolingImage },
+                { uri: `pkg:npm/@openai/codex@${request.codexVersion}` }
+            ]
+        };
+        const provenanceBytes = Buffer.from(`${canonicalJson(provenance)}\n`, "utf8");
+        const provenanceName = `${layer}.provenance.json`;
+        await writeRestricted(path.join(root, provenanceName), provenanceBytes);
+        let signatureDigest = null;
+        if (privateKey) {
+            const signature = sign("sha256", provenanceBytes, privateKey);
+            if (!verify("sha256", provenanceBytes, createPublicKey(privateKey), signature)) {
+                throw new Error("sandbox_build_policy_failed: generated provenance signature did not verify.");
+            }
+            await writeRestricted(path.join(root, `${provenanceName}.sig`), signature);
+            signatureDigest = sha256(signature);
+        }
+        else {
+            status = "warning";
+        }
+        let sbomDigest = null;
+        if (sbomExecutable) {
+            const sbom = await runCommand({
+                command: sbomExecutable,
+                args: [scanTarget, "-o", "spdx-json"],
+                timeoutMs: 10 * 60_000,
+                maxOutputBytes: 32 * 1024 * 1024,
+                signal: request.signal
+            });
+            if (sbom.exitCode !== 0 || sbom.truncated || !validJsonObject(sbom.stdout)) {
+                throw new Error(`sandbox_build_policy_failed: SPDX SBOM generation failed for ${layer}.`);
+            }
+            const bytes = Buffer.from(sbom.stdout, "utf8");
+            await writeRestricted(path.join(root, `${layer}.sbom.spdx.json`), bytes);
+            sbomDigest = sha256(bytes);
+        }
+        else {
+            status = "warning";
+        }
+        let vulnerabilityDigest = null;
+        if (vulnerabilityExecutable) {
+            const scan = await runCommand({
+                command: vulnerabilityExecutable,
+                args: ["image", "--scanners", "vuln", "--format", "json", "--severity", "HIGH,CRITICAL", "--exit-code", "1", "--no-progress", scanTarget],
+                timeoutMs: 15 * 60_000,
+                maxOutputBytes: 32 * 1024 * 1024,
+                signal: request.signal
+            });
+            const bytes = Buffer.from(scan.stdout || scan.stderr, "utf8");
+            await writeRestricted(path.join(root, `${layer}.vulnerabilities.json`), bytes);
+            vulnerabilityDigest = sha256(bytes);
+            if (scan.exitCode !== 0 || scan.truncated) {
+                throw new Error(`sandbox_build_policy_failed: ${layer} violates the HIGH/CRITICAL vulnerability policy.`);
+            }
+        }
+        else {
+            status = "warning";
+        }
+        artifacts[layer] = {
+            imageDigest,
+            scanTarget,
+            provenanceSha256: sha256(provenanceBytes),
+            provenanceSignatureSha256: signatureDigest,
+            sbomSha256: sbomDigest,
+            vulnerabilityReportSha256: vulnerabilityDigest
+        };
+    }
+    const policyRecord = {
+        schemaVersion: 1,
+        key: request.key,
+        project: request.project,
+        status,
+        enforced,
+        generatedAt: new Date().toISOString(),
+        upstreamSignatures,
+        artifacts
+    };
+    const recordBytes = Buffer.from(`${canonicalJson(policyRecord)}\n`, "utf8");
+    const policyDigest = sha256(recordBytes);
+    await writeRestricted(path.join(root, "policy.json"), recordBytes);
+    return { status, policyDigest, root };
+}
+export async function verifySandboxImageSignature(request) {
+    const required = request.executionPolicy === "sandbox_required";
+    if (!/@sha256:[a-f0-9]{64}$/iu.test(request.image)) {
+        if (required)
+            throw new Error(`sandbox_image_signature_failed: image '${request.image}' is not digest-pinned.`);
+        return "warning";
+    }
+    const environment = request.environment ?? process.env;
+    const executable = environment.FORGE_SANDBOX_SIGNATURE_EXECUTABLE?.trim();
+    const publicKeyPath = environment.FORGE_SANDBOX_SIGNATURE_PUBLIC_KEY?.trim();
+    if (!executable || !publicKeyPath) {
+        if (required)
+            throw new Error("sandbox_image_signature_failed: sandbox_required needs an image signature verifier and public key.");
+        return "warning";
+    }
+    await readBoundedRegularFile(publicKeyPath, "image signature public key", "sandbox_image_signature_failed");
+    const runCommand = request.runCommand ?? runSandboxProcess;
+    const result = await runCommand({
+        command: executable,
+        args: ["verify", "--key", publicKeyPath, request.image],
+        timeoutMs: 5 * 60_000,
+        maxOutputBytes: 4 * 1024 * 1024,
+        terminateOnOutputLimit: true,
+        signal: request.signal
+    });
+    if (result.exitCode !== 0 || result.truncated || !validSignatureResult(result.stdout)) {
+        throw new Error(`sandbox_image_signature_failed: signature verification failed for '${request.image}'.`);
+    }
+    return "passed";
+}
+export async function hasSandboxImagePolicyRecord(stateRoot, key, expectedDigest, requirePassed = false) {
+    const target = path.join(stateRoot, "attestations", key, "policy.json");
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        return false;
+    const bytes = await fs.readFile(target);
+    if (sha256(bytes) !== expectedDigest)
+        return false;
+    if (!requirePassed)
+        return true;
+    try {
+        const record = JSON.parse(bytes.toString("utf8"));
+        return record.status === "passed" && record.enforced === true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function sandboxImagePolicyConfigurationDigest(environment = process.env) {
+    const signingKeyPath = environment.FORGE_SANDBOX_PROVENANCE_SIGNING_KEY?.trim() ?? "";
+    const signaturePublicKeyPath = environment.FORGE_SANDBOX_SIGNATURE_PUBLIC_KEY?.trim() ?? "";
+    const fields = [
+        environment.FORGE_SANDBOX_IMAGE_POLICY_ENFORCED ?? "",
+        environment.FORGE_SANDBOX_SBOM_EXECUTABLE?.trim() ?? "",
+        environment.FORGE_SANDBOX_VULNERABILITY_EXECUTABLE?.trim() ?? "",
+        environment.FORGE_SANDBOX_SIGNATURE_EXECUTABLE?.trim() ?? "",
+        await policyFileFingerprint(signingKeyPath),
+        await policyFileFingerprint(signaturePublicKeyPath)
+    ];
+    return sha256(Buffer.from(fields.join("\0"), "utf8"));
+}
+async function readSigningKey(target) {
+    const bytes = await readBoundedRegularFile(target, "provenance signing key");
+    try {
+        return createPrivateKey(bytes);
+    }
+    catch (error) {
+        throw new Error("sandbox_build_policy_failed: provenance signing key is invalid.", { cause: error });
+    }
+}
+async function readBoundedRegularFile(target, label, failureCode = "sandbox_build_policy_failed") {
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.size === 0 || stat.size > 64 * 1024) {
+        throw new Error(`${failureCode}: ${label} must be a bounded regular file.`);
+    }
+    return await fs.readFile(target);
+}
+async function policyFileFingerprint(target) {
+    if (!target)
+        return "not-configured";
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.size === 0 || stat.size > 64 * 1024)
+        return "invalid";
+    return sha256(await fs.readFile(target));
+}
+async function writeRestricted(target, bytes) {
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(temporary, bytes, { mode: 0o600, flag: "wx" });
+    await fs.rename(temporary, target);
+}
+function validJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Boolean(parsed && typeof parsed === "object" && !Array.isArray(parsed));
+    }
+    catch {
+        return false;
+    }
+}
+function validSignatureResult(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) && parsed.length > 0 && parsed.every(entry => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+    }
+    catch {
+        return false;
+    }
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./sandbox.types.js";
+export * from "./contract.js";
+export * from "./preflight.js";
+export * from "./command-runner.js";
+export * from "./runtime.js";

package/dist/sandbox/index.js

@@ -0,0 +1,5 @@
+export * from "./sandbox.types.js";
+export * from "./contract.js";
+export * from "./preflight.js";
+export * from "./command-runner.js";
+export * from "./runtime.js";

package/dist/sandbox/lease-watchdog.d.ts

@@ -0,0 +1,18 @@
+export interface SignedLeaseUpdate {
+    readonly schemaVersion: 1;
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly expiresAt: string;
+    readonly mac: string;
+}
+export declare function createLeaseUpdate(dispatchAttemptId: string, fencingToken: string, expiresAt: string, controlKey: string): SignedLeaseUpdate;
+export declare class MonotonicLeaseDeadline {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    private readonly controlKey;
+    private expiresAtMs;
+    private deadlineMs;
+    constructor(dispatchAttemptId: string, fencingToken: string, initialExpiresAt: string, controlKey: string, wallNowMs?: number, monotonicNowMs?: number);
+    apply(update: unknown, wallNowMs?: number, monotonicNowMs?: number): boolean;
+    expired(monotonicNowMs?: number): boolean;
+}