@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.04a1e5b9e484

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

package/dist/sandbox/lease-watchdog.js

@@ -0,0 +1,67 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export function createLeaseUpdate(dispatchAttemptId, fencingToken, expiresAt, controlKey) {
+    return {
+        schemaVersion: 1,
+        dispatchAttemptId,
+        fencingToken,
+        expiresAt,
+        mac: leaseMac(dispatchAttemptId, fencingToken, expiresAt, controlKey)
+    };
+}
+export class MonotonicLeaseDeadline {
+    dispatchAttemptId;
+    fencingToken;
+    controlKey;
+    expiresAtMs;
+    deadlineMs;
+    constructor(dispatchAttemptId, fencingToken, initialExpiresAt, controlKey, wallNowMs = Date.now(), monotonicNowMs = performance.now()) {
+        this.dispatchAttemptId = dispatchAttemptId;
+        this.fencingToken = fencingToken;
+        this.controlKey = controlKey;
+        this.expiresAtMs = parsedExpiry(initialExpiresAt);
+        this.deadlineMs = monotonicNowMs + Math.max(0, this.expiresAtMs - wallNowMs);
+    }
+    apply(update, wallNowMs = Date.now(), monotonicNowMs = performance.now()) {
+        if (!isSignedLeaseUpdate(update)
+            || update.dispatchAttemptId !== this.dispatchAttemptId
+            || update.fencingToken !== this.fencingToken
+            || parsedExpiry(update.expiresAt) <= this.expiresAtMs)
+            return false;
+        const expected = leaseMac(update.dispatchAttemptId, update.fencingToken, update.expiresAt, this.controlKey);
+        if (!safeEqual(expected, update.mac))
+            return false;
+        this.expiresAtMs = parsedExpiry(update.expiresAt);
+        this.deadlineMs = monotonicNowMs + Math.max(0, this.expiresAtMs - wallNowMs);
+        return true;
+    }
+    expired(monotonicNowMs = performance.now()) {
+        return monotonicNowMs >= this.deadlineMs;
+    }
+}
+function leaseMac(dispatchAttemptId, fencingToken, expiresAt, controlKey) {
+    return createHmac("sha256", controlKey)
+        .update(`${dispatchAttemptId}\n${fencingToken}\n${expiresAt}`, "utf8")
+        .digest("base64url");
+}
+function safeEqual(left, right) {
+    const leftBytes = Buffer.from(left, "utf8");
+    const rightBytes = Buffer.from(right, "utf8");
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function parsedExpiry(value) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        throw new Error("Lease expiry is invalid.");
+    return parsed;
+}
+function isSignedLeaseUpdate(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const update = value;
+    return update.schemaVersion === 1
+        && typeof update.dispatchAttemptId === "string"
+        && typeof update.fencingToken === "string"
+        && typeof update.expiresAt === "string"
+        && Number.isFinite(Date.parse(update.expiresAt))
+        && typeof update.mac === "string";
+}

package/dist/sandbox/preflight.d.ts

@@ -0,0 +1,84 @@
+import type { CommandRunner, SandboxPreflightResult } from "./sandbox.types.js";
+export interface DockerPreflightOptions {
+    readonly dockerExecutable?: string;
+    readonly dockerContext?: string;
+    readonly stateRoot?: string;
+    readonly runnerInstanceId?: string;
+    readonly maxConcurrentSandboxes?: number;
+    readonly diskHighWatermarkPercent?: number;
+    readonly diskLowWatermarkPercent?: number;
+    readonly minimumWorkspaceBytes?: number;
+    readonly hostMemoryReserveBytes?: number;
+    readonly defaultWorkerMemoryLimitBytes?: number;
+    readonly defaultServiceMemoryLimitBytes?: number;
+    readonly runtimeOverheadBytes?: number;
+    readonly requireRootless?: boolean;
+}
+export declare class DockerPreflight {
+    private readonly commands;
+    private readonly cacheMs;
+    private generation;
+    private cached;
+    private fullPreflightAt;
+    private staticPreflight;
+    private inspectionInFlight;
+    private lastCapacitySample;
+    private readonly options;
+    private readonly docker;
+    private readonly ownership;
+    private diskPressureLatched;
+    private readonly memoryAvailability;
+    constructor(options?: DockerPreflightOptions | string, commands?: CommandRunner, cacheMs?: number);
+    private unavailable;
+    private memoryReserveBytes;
+    private defaultAdmissionMemoryBytes;
+    current(): SandboxPreflightResult | null;
+    refresh(): Promise<SandboxPreflightResult>;
+    release(): Promise<void>;
+    run(force?: boolean): Promise<SandboxPreflightResult>;
+    /**
+     * Refreshes only the admission inputs that change while the daemon's static
+     * capability snapshot remains valid. Heartbeats use this path so periodic
+     * liveness reporting does not wake Docker/WSL to rerun feature probes.
+     */
+    refreshCapacity(): Promise<SandboxPreflightResult>;
+    /**
+     * When the cached static preflight remains usable, produces a capacity sample
+     * that began after this admission request. An older inspection is awaited,
+     * not preempted or reused. Later admission callers may share the next sample
+     * only when it began after they entered this method. Without a usable static
+     * snapshot, the existing fail-closed result is returned without probing.
+     */
+    refreshCapacityForAdmission(): Promise<SandboxPreflightResult>;
+    private startInspection;
+    private inspect;
+    private inspectCapacity;
+}
+/**
+ * Uses the same reviewed reserve vector as host-runtime admission. The input
+ * is always the physical host total; Docker Desktop's VM total is tracked as
+ * a separate daemon commitment domain.
+ */
+export declare function resolveSandboxHostMemoryReserveBytes(totalMemoryBytes: number, explicitBytes?: number, environment?: NodeJS.ProcessEnv): number;
+export declare function canRunDockerMaintenance(preflight: {
+    readonly healthy: boolean;
+    readonly unavailableCode?: string | null;
+}): boolean;
+export declare function evaluateDiskPressure(availableBytes: number, totalBytes: number, minimumAvailableBytes: number, highWatermarkPercent: number, lowWatermarkPercent: number, pressureLatched: boolean): boolean;
+export declare function requiredAvailableBytesToClearDiskPressure(totalBytes: number, minimumAvailableBytes: number, lowWatermarkPercent: number): number;
+export declare function storagePolicyAvailable(storageQuota: boolean, environment?: NodeJS.ProcessEnv): boolean;
+export declare class DockerContextOwnershipLock {
+    private lockPath;
+    private lockToken;
+    acquire(contextName?: string): Promise<void>;
+    release(): Promise<void>;
+}
+export declare function parseDockerMemoryUsage(value: string): number;
+interface DockerContextLockOwner {
+    readonly token?: string;
+    readonly pid?: number;
+    readonly processIdentity?: string | null;
+    readonly acquiredAt?: string;
+}
+export declare function dockerContextOwnerIsActive(owner: DockerContextLockOwner | null): boolean;
+export {};