@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.d46a8e73d03d

package/dist/sandbox/provider-auth/codex.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const maxCredentialFileBytes = 1024 * 1024;
+// Capability and heartbeat paths call doctor() synchronously; keep validation
+// fresh enough for auth changes without rereading auth.json for every offer.
+const authDoctorCacheTtlMs = 5_000;
+let authDoctorCache = null;
+export const codexSandboxProviderAuthAdapter = {
+    provider: "codex",
+    authKind: "bridge_cli",
+    containerMountPath: "/home/forge/.codex",
+    // Codex refreshes OAuth tokens in place, so the container mount is writable.
+    // The writable state is an attempt-scoped Docker volume copy only; no code path
+    // syncs modified container credentials back to the host ~/.codex directory.
+    writable: true,
+    doctor(environment = process.env) {
+        return codexAuthDoctor(environment);
+    },
+    async prepareAttemptAuth(environment = process.env) {
+        const doctor = codexAuthDoctor(environment);
+        if (!doctor.available || !doctor.authPath) {
+            throw new Error(`sandbox_auth_unavailable: ${doctor.message}`);
+        }
+        let content;
+        try {
+            content = await readValidatedCodexAuthFile(doctor.authPath);
+        }
+        catch (error) {
+            throw new Error(`sandbox_auth_unavailable: ${error instanceof Error ? error.message : "Codex Local CLI auth.json could not be validated."}`, { cause: error });
+        }
+        return {
+            files: [
+                {
+                    name: "auth.json",
+                    contentBase64: content.toString("base64")
+                }
+            ],
+            containerMountPath: this.containerMountPath,
+            writable: this.writable
+        };
+    }
+};
+export function sandboxProviderAuthAdapterFor(provider, authKind) {
+    if (authKind.trim().toLowerCase() !== "bridge_cli") {
+        return null;
+    }
+    return provider.trim().toLowerCase() === "codex"
+        ? codexSandboxProviderAuthAdapter
+        : null;
+}
+export function sandboxProviderAuthUnavailableMessage(provider, authKind) {
+    if (authKind.trim().toLowerCase() !== "bridge_cli") {
+        return null;
+    }
+    return provider.trim().toLowerCase() === "codex"
+        ? null
+        : `Provider ${provider} Local CLI auth is not portable into Docker yet.`;
+}
+function codexAuthDoctor(environment) {
+    const authPath = path.join(resolveCodexHome(environment), "auth.json");
+    const now = Date.now();
+    if (authDoctorCache?.authPath === authPath && authDoctorCache.expiresAt > now) {
+        return authDoctorCache.result;
+    }
+    let result;
+    try {
+        readValidatedCodexAuthFileSync(authPath);
+        result = {
+            available: true,
+            code: "ok",
+            message: "Codex Local CLI auth is portable into an attempt-scoped Docker volume.",
+            authPath
+        };
+    }
+    catch (error) {
+        result = unavailable(error instanceof Error ? error.message : "Codex Local CLI auth.json could not be validated.");
+    }
+    authDoctorCache = {
+        authPath,
+        expiresAt: now + authDoctorCacheTtlMs,
+        result
+    };
+    return result;
+}
+async function readValidatedCodexAuthFile(authPath) {
+    let pathStat;
+    try {
+        pathStat = await fsp.lstat(authPath);
+    }
+    catch {
+        throw new Error("Codex Local CLI auth is not available on the bridge host.");
+    }
+    validateCodexAuthStat(pathStat);
+    let handle;
+    try {
+        handle = await fsp.open(authPath, codexAuthOpenFlags());
+    }
+    catch (error) {
+        throw codexAuthOpenError(error);
+    }
+    try {
+        const openedStat = await handle.stat();
+        validateSameCodexAuthFile(pathStat, openedStat);
+        validateCodexAuthStat(openedStat);
+        const content = await handle.readFile();
+        const afterStat = await handle.stat();
+        validateSameCodexAuthFile(openedStat, afterStat);
+        validateCodexAuthStat(afterStat);
+        validateCodexAuthReadSize(content, openedStat, afterStat);
+        validateCodexAuthJson(content);
+        return content;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function readValidatedCodexAuthFileSync(authPath) {
+    let pathStat;
+    try {
+        pathStat = fs.lstatSync(authPath);
+    }
+    catch {
+        throw new Error("Codex Local CLI auth is not available on the bridge host.");
+    }
+    validateCodexAuthStat(pathStat);
+    let fd;
+    try {
+        fd = fs.openSync(authPath, codexAuthOpenFlags());
+    }
+    catch (error) {
+        throw codexAuthOpenError(error);
+    }
+    try {
+        const openedStat = fs.fstatSync(fd);
+        validateSameCodexAuthFile(pathStat, openedStat);
+        validateCodexAuthStat(openedStat);
+        const content = fs.readFileSync(fd);
+        const afterStat = fs.fstatSync(fd);
+        validateSameCodexAuthFile(openedStat, afterStat);
+        validateCodexAuthStat(afterStat);
+        validateCodexAuthReadSize(content, openedStat, afterStat);
+        validateCodexAuthJson(content);
+        return content;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function codexAuthOpenFlags() {
+    return fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW;
+}
+function validateCodexAuthStat(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new Error("Codex Local CLI auth.json must not be a symlink.");
+    }
+    if (!stat.isFile()) {
+        throw new Error("Codex Local CLI auth.json is not a regular file.");
+    }
+    if (stat.size <= 0) {
+        throw new Error("Codex Local CLI auth.json is empty.");
+    }
+    if (stat.size > maxCredentialFileBytes) {
+        throw new Error("Codex Local CLI auth.json exceeds the 1 MiB sandbox auth limit.");
+    }
+}
+function validateSameCodexAuthFile(before, after) {
+    if (before.dev !== 0 && before.ino !== 0 && after.dev !== 0 && after.ino !== 0
+        && (before.dev !== after.dev || before.ino !== after.ino)) {
+        throw new Error("Codex Local CLI auth.json changed while being copied.");
+    }
+}
+function validateCodexAuthReadSize(content, openedStat, afterStat) {
+    if (openedStat.size !== afterStat.size || content.length !== afterStat.size) {
+        throw new Error("Codex Local CLI auth.json changed while being copied.");
+    }
+}
+function validateCodexAuthJson(content) {
+    try {
+        JSON.parse(content.toString("utf8"));
+    }
+    catch {
+        throw new Error("Codex Local CLI auth.json is not valid JSON.");
+    }
+}
+function codexAuthOpenError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+    if (code === "ELOOP") {
+        return new Error("Codex Local CLI auth.json must not be a symlink.");
+    }
+    if (code === "ENOENT") {
+        return new Error("Codex Local CLI auth is not available on the bridge host.");
+    }
+    if (code === "EACCES" || code === "EPERM") {
+        return new Error("Codex Local CLI auth.json could not be read.");
+    }
+    return error instanceof Error ? error : new Error("Codex Local CLI auth.json could not be read.");
+}
+function unavailable(message) {
+    return {
+        available: false,
+        code: "sandbox_auth_unavailable",
+        message
+    };
+}
+function resolveCodexHome(environment) {
+    const configured = environment.FORGE_CODEX_HOME?.trim();
+    return configured ? path.resolve(configured) : path.join(os.homedir(), ".codex");
+}

package/dist/sandbox/repository-lock.d.ts

@@ -0,0 +1,5 @@
+export declare class RepositoryCoordinatorLock {
+    private readonly stateRoot;
+    constructor(stateRoot: string);
+    withLock<T>(repoPath: string, action: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}

package/dist/sandbox/repository-lock.js

@@ -0,0 +1,83 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+export class RepositoryCoordinatorLock {
+    stateRoot;
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async withLock(repoPath, action, signal) {
+        const resolved = path.resolve(repoPath);
+        const key = createHash("sha256").update(resolved.toLowerCase()).digest("hex");
+        const root = path.join(this.stateRoot, "repo-locks");
+        const target = path.join(root, `${key}.lock`);
+        const token = randomUUID();
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const started = Date.now();
+        while (true) {
+            if (signal?.aborted)
+                throw new Error("sandbox_import_cancelled: repository coordination was cancelled.");
+            try {
+                const handle = await fs.open(target, "wx", 0o600);
+                try {
+                    await handle.writeFile(`${JSON.stringify({ schemaVersion: 1, token, pid: process.pid, repoPath: resolved, acquiredAt: new Date().toISOString() })}\n`);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (await staleLock(target)) {
+                    await fs.rm(target, { force: true });
+                    continue;
+                }
+                if (Date.now() - started >= 2 * 60_000) {
+                    throw new Error("sandbox_import_unavailable: repository coordinator lock timed out.", { cause: error });
+                }
+                await abortableDelay(50, signal);
+            }
+        }
+        try {
+            return await action();
+        }
+        finally {
+            const owner = await readOwner(target);
+            if (owner?.token === token)
+                await fs.rm(target, { force: true });
+        }
+    }
+}
+async function staleLock(target) {
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024)
+        return true;
+    const owner = await readOwner(target);
+    if (!owner || typeof owner.pid !== "number" || !Number.isInteger(owner.pid) || owner.pid <= 0)
+        return true;
+    if (Date.now() - stat.mtimeMs > 10 * 60_000)
+        return true;
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+async function readOwner(target) {
+    return await fs.readFile(target, "utf8").then(value => JSON.parse(value)).catch(() => null);
+}
+async function abortableDelay(delayMs, signal) {
+    if (!signal)
+        return await new Promise(resolve => setTimeout(resolve, delayMs));
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, delayMs);
+        const abort = () => { clearTimeout(timer); reject(new Error("sandbox_import_cancelled: repository coordination was cancelled.")); };
+        signal.addEventListener("abort", abort, { once: true });
+        timer.unref?.();
+    });
+}

package/dist/sandbox/runtime.d.ts

@@ -0,0 +1,234 @@
+import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
+import type { SessionEventSink } from "../session/session.base.js";
+import { type RunOnceDispatchPacket, type RunOnceResultPacket } from "../session/session.types.js";
+import type { SandboxService, ValidatedSandboxContract } from "./sandbox.types.js";
+export interface SandboxRuntime {
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+    reap(options?: SandboxReapOptions): Promise<void>;
+    pendingCleanupReports?(): Promise<readonly SandboxCleanupReport[]>;
+    acknowledgeCleanupReport?(reportId: string): Promise<void>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    snapshot(): SandboxRuntimeSnapshot;
+}
+export interface SandboxReapOptions {
+    readonly diskLow?: boolean;
+    readonly attemptSnapshot?: readonly SandboxAttemptSnapshot[];
+}
+export interface SandboxAttemptSnapshot {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: string;
+    readonly expiresAt: string;
+}
+export interface SandboxCleanupReport {
+    readonly reportId: string;
+    readonly source: "teardown" | "reaper";
+    readonly actions: readonly SandboxCleanupAction[];
+}
+export interface SandboxCleanupAction {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly resourceType: "container" | "network" | "volume";
+    readonly resourceId: string;
+    readonly outcome: "removed" | "failed";
+    readonly message?: string | null;
+    readonly occurredAt: string;
+}
+export interface SandboxRuntimeSnapshot {
+    readonly starting: number;
+    readonly active: number;
+    readonly degraded: number;
+}
+export interface SandboxPublicationGrantRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly grantId: string;
+    readonly branch: string;
+    readonly resultCommitSha: string;
+}
+export interface SandboxPublicationCredential {
+    readonly username: string;
+    readonly secret: string;
+    readonly remoteUrl: string;
+    readonly expiresAt: string;
+}
+export type SandboxPublicationGrantRedeemer = (request: SandboxPublicationGrantRequest, signal?: AbortSignal) => Promise<SandboxPublicationCredential>;
+export declare class DockerSandboxRuntime implements SandboxRuntime {
+    private readonly config;
+    private readonly publicationGrantRedeemer?;
+    private readonly active;
+    private readonly degraded;
+    private readonly builds;
+    private readonly verifiedCatalogImages;
+    private buildTail;
+    constructor(config: BridgeServiceConfig, publicationGrantRedeemer?: SandboxPublicationGrantRedeemer | undefined);
+    runOnce(dispatch: RunOnceDispatchPacket, sink: SessionEventSink, signal?: AbortSignal): Promise<RunOnceResultPacket>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    private pushLeaseUpdate;
+    snapshot(): SandboxRuntimeSnapshot;
+    reap(options?: SandboxReapOptions): Promise<void>;
+    pendingCleanupReports(): Promise<readonly SandboxCleanupReport[]>;
+    acknowledgeCleanupReport(reportId: string): Promise<void>;
+    private persistCleanupReport;
+    private cleanupReportPath;
+    private writeLedger;
+    private readLedgers;
+    private ledgerPath;
+    private removeLedger;
+    private buildImage;
+    private withBuildPermit;
+    private buildImageCore;
+    private runBuildStage;
+    private ensureBuildxBuilder;
+    private initializeVolumes;
+    private inspectContainerState;
+    private initializeServiceSecrets;
+    private initializeProviderCredentials;
+    private initializeEgressPolicy;
+    private startEgressProxy;
+    private startServices;
+    private verifyCatalogImage;
+    private waitForServiceHealthy;
+    private teardown;
+    private listResources;
+    private inspectResourceLabels;
+    private removeResource;
+    private writeImageCacheRecord;
+    private readImageCacheRecords;
+    private readImageCacheRecord;
+    private collectExpiredImages;
+    private purgeRestrictedAuditArtifacts;
+    private docker;
+    private dockerArgs;
+}
+export declare function publicationPushArgs(branch: string, resultCommitSha: string, inputCommitSha: string, remoteCommitSha: string, remote?: string): string[] | null;
+export declare function validatePublicationCredential(credential: SandboxPublicationCredential, nowMs?: number): void;
+export declare function publicationCredentialEnvironment(credential: SandboxPublicationCredential, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface RestrictedBuildLog {
+    readonly content: string;
+    readonly digest: string;
+    readonly byteCount: number;
+    readonly truncated: boolean;
+}
+export declare function restrictedBuildLog(source: string, exactSecrets?: readonly string[], maximumBytes?: number): RestrictedBuildLog;
+export declare function validateGitObjectBudget(inventory: string, maximumObjectCount?: number, maximumExpandedBytes?: number): {
+    readonly objectCount: number;
+    readonly expandedBytes: number;
+};
+export declare function validateGitCommitDepth(value: string, maximumCommitDepth?: number): number;
+export interface AuditArtifactRecord {
+    readonly key: string;
+    readonly lastModifiedMs: number;
+}
+export declare function selectAuditArtifactGcCandidates(records: readonly AuditArtifactRecord[], retentionCount: number, retentionTtlMs: number, protectedKeys?: ReadonlySet<string>, nowMs?: number): string[];
+export declare function selectSandboxConfigRefs(executionPolicy: string, configuredSha: string | null | undefined, defaultBranch: string): {
+    readonly refs: readonly string[];
+    readonly approvedSha: string | null;
+};
+export declare function sandboxTimeLimits(environment?: NodeJS.ProcessEnv): {
+    readonly hardWallMs: number;
+    readonly idleMs: number;
+};
+export interface ImageCacheRecord {
+    readonly schemaVersion: 1;
+    readonly key: string;
+    readonly project: string;
+    readonly createdAt: string;
+    readonly lastUsedAt: string;
+    readonly projectTag: string;
+    readonly helperTag: string;
+    readonly overlayTag: string;
+    readonly imageDigest: string;
+    readonly helperImageDigest: string;
+    readonly policyDigest: string;
+}
+interface ResourceNames {
+    prefix: string;
+    container: string;
+    network: string;
+    egressNetwork: string;
+    workspaceVolume: string;
+    controlVolume: string;
+    secretsVolume: string;
+    credentialsVolume: string;
+    egressConfigVolume: string;
+    cacheVolumes: Record<string, string>;
+}
+interface SandboxRuntimeVolume {
+    readonly name: string;
+    readonly role: string;
+}
+interface ActiveSandbox {
+    dispatchAttemptId: string;
+    fencingToken: string;
+    expiresAt: string;
+    controller: AbortController;
+    phase: "starting" | "active";
+    ledger: SandboxLedger | null;
+    leaseControlKey: string;
+}
+export declare function assertSandboxImportCurrent(expected: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken" | "expiresAt">, current: Pick<ActiveSandbox, "dispatchAttemptId" | "fencingToken"> | undefined, signal: AbortSignal, nowMs?: number): void;
+interface SandboxLedger {
+    schemaVersion: 1;
+    dispatchAttemptId: string;
+    fencingToken: string;
+    runnerInstanceId: string;
+    expiresAt: string;
+    resources: ResourceNames;
+    labels: Record<string, string>;
+    includeCredentials?: boolean;
+}
+export declare function resourceNames(attemptHex: string, perAttemptCaches?: readonly string[]): ResourceNames;
+export declare function dockerObjectId(output: string, kind: "container" | "network"): string;
+export declare function sandboxRuntimeVolumes(resources: ResourceNames, includeEgressPolicy?: boolean, includeCredentials?: boolean): SandboxRuntimeVolume[];
+export declare function sandboxRuntimeCleanupVolumeNames(resources: ResourceNames, includeCredentials?: boolean): string[];
+export declare function mayReapManagedResource(labels: Readonly<Record<string, string>>, runnerId: string, liveAttempts: ReadonlySet<string>): boolean;
+export declare function shouldReapSandboxLedger(ledger: Readonly<Pick<SandboxLedger, "dispatchAttemptId" | "fencingToken" | "runnerInstanceId" | "expiresAt">>, currentRunnerInstanceId: string, serverAttempt: SandboxAttemptSnapshot | undefined, snapshotAvailable: boolean, nowMs?: number): boolean;
+export declare function prepareOverlayBuildRoot(overlayRoot: string): Promise<void>;
+export declare function extractOciLayoutArchive(archivePath: string, destination: string, signal?: AbortSignal): Promise<void>;
+export declare function ociLayoutContextRef(layoutPath: string): string;
+export declare function formatOciExtractionFailure(result: {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+}): string;
+export declare function readOciLayoutImageDigest(layoutRoot: string): Promise<string>;
+export declare function removeExtractedOciLayout(layoutRoot: string): Promise<void>;
+export declare function ociLayoutScanTarget(layoutPath: string): string;
+export declare function agentOverlayDockerignore(): string;
+export declare function agentOverlayDockerfile(toolingImage: string, projectContextName: string, installMode: BridgePackageInstallMode, codexVersion: string): string;
+export type BridgePackageInstallMode = "ci" | "install";
+export declare function copyBridgePackageManifests(packageRoot: string, bridgeRoot: string): Promise<BridgePackageInstallMode>;
+export declare function bridgePackageInstallCommand(mode: BridgePackageInstallMode, codexVersion: string): string;
+export declare function buildxBuildArgs(builder: string, metadataFile: string, tail: readonly string[], environment?: NodeJS.ProcessEnv, options?: {
+    readonly load?: boolean;
+}): string[];
+export declare function buildResourcePolicy(environment?: NodeJS.ProcessEnv): {
+    readonly nofile: number;
+    readonly sharedMemory: string;
+    readonly builderPidsLimit: number;
+};
+export declare function dedicatedBuildxBuilderName(runnerId: string, dockerContext: string | null | undefined): string;
+export declare function dedicatedBuildxBuilderContainerName(builder: string): string;
+export declare function selectImageGcCandidates(records: readonly ImageCacheRecord[], keepPerProject: number, ttlMs: number, nowMs: number): ImageCacheRecord[];
+export declare function workerCreateArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames, labels: Record<string, string>, image: string, securityOptions?: readonly string[]): string[];
+export declare function cacheVolumeArgs(contract: ValidatedSandboxContract, resources: ResourceNames): string[];
+export declare function proxyEnvironmentArgs(dispatch: RunOnceDispatchPacket, contract: ValidatedSandboxContract, resources: ResourceNames): string[];
+export declare function egressProxyConfig(allowedHosts: readonly string[]): string;
+export declare function serviceContainerArgs(service: SandboxService, image: string, resources: ResourceNames, labels: Record<string, string>, securityOptions: readonly string[], environment?: NodeJS.ProcessEnv): string[];
+export declare function resolveSandboxSecurityOptions(executionPolicy: string, environment?: NodeJS.ProcessEnv): string[];
+export declare function networkCreateArgs(dispatch: RunOnceDispatchPacket, environment?: NodeJS.ProcessEnv): string[];
+export declare function classifySandboxRuntimeFailure(value: string): {
+    readonly code: string;
+    readonly phase: string;
+    readonly message: string;
+};
+export declare function classifySandboxResourceFailure(value: string): {
+    readonly code: string;
+    readonly message: string;
+} | null;
+export {};