@guilz-dev/belay 0.8.1 → 0.9.1

package/dist/core/config.d.ts

@@ -146,6 +146,20 @@ export interface BelaySandboxConfig {
     enabled: boolean;
     runtime: SandboxRuntime;
     denyNetworkByDefault: boolean;
+    /** Optional in source config for backwards compatibility; normalization always supplies it. */
+    containedExecution?: BelayContainedExecutionConfig;
+}
+export interface BelayContainedExecutionConfig {
+    enabled: boolean;
+    image: string | null;
+    /** Required when enabled; optional in source objects for disabled backwards compatibility. */
+    dockerExecutable?: string | null;
+    /** Required when enabled; only local absolute unix:// endpoints are accepted. */
+    dockerHost?: string | null;
+    timeoutMs: number;
+    memoryMiB: number;
+    cpus: number;
+    pids: number;
 }
 export interface BelayClassifierConfig {
     strictChains: boolean;
@@ -225,7 +239,9 @@ export declare const DEFAULT_REDACTION_V3: BelayRedactionConfig;
 export declare const DEFAULT_CONTROL_PLANE_ISOLATION_V3: BelayControlPlaneIsolationConfig;
 export declare const LEGACY_CONTROL_PLANE_V3: BelayControlPlaneConfig;
 export declare const DEFAULT_CONTROL_PLANE_V3: BelayControlPlaneConfig;
+export declare const DEFAULT_CONTAINED_EXECUTION: BelayContainedExecutionConfig;
 export declare const DEFAULT_SANDBOX_V3: BelaySandboxConfig;
+export declare function normalizeContainedExecutionConfig(raw: Partial<BelayContainedExecutionConfig> | undefined): BelayContainedExecutionConfig;
 export declare const DEFAULT_NOTIFICATIONS_V3: BelayNotificationsConfig;
 export declare const DEFAULT_APPROVAL_SIGNING_V3: BelayApprovalSigningConfig;
 export declare const DEFAULT_APPROVAL_CONFIG: BelayApprovalConfig;
@@ -276,6 +292,8 @@ export declare function normalizeConfigV2(config: BelayConfigV2): BelayConfigV2;
 export declare function normalizeConfig(config: BelayConfigV4): BelayConfigV4;
 export declare function normalizeConfig(config: BelayConfigV2): BelayConfigV2;
 export declare function isFreshConfigInput(loaded: unknown): boolean;
+export declare function hasForbiddenShellOverrideLists(config: BelayConfigV4): boolean;
+export declare function stripForbiddenShellOverrideLists(config: BelayConfigV4): BelayConfigV4;
 export declare function mergeConfig(existing: unknown, defaults?: BelayConfigV4): BelayConfigV4;
 export declare function scrubOptionsFromConfig(config: BelayConfigV4): ScrubOptions;
 export declare function classifierOptionsFromConfig(config: BelayConfigV4): ClassifierOptions;

package/dist/core/config.js

@@ -148,11 +148,80 @@ export const DEFAULT_CONTROL_PLANE_V3 = {
     integrity: 'hash-pinned',
     isolation: { ...DEFAULT_CONTROL_PLANE_ISOLATION_V3 },
 };
+export const DEFAULT_CONTAINED_EXECUTION = {
+    enabled: false,
+    image: null,
+    dockerExecutable: null,
+    dockerHost: null,
+    timeoutMs: 30_000,
+    memoryMiB: 2048,
+    cpus: 2,
+    pids: 256,
+};
 export const DEFAULT_SANDBOX_V3 = {
     enabled: false,
     runtime: 'none',
     denyNetworkByDefault: true,
+    containedExecution: { ...DEFAULT_CONTAINED_EXECUTION },
 };
+function positiveInteger(value, fallback) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function positiveNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export function normalizeContainedExecutionConfig(raw) {
+    return {
+        enabled: raw?.enabled === true,
+        image: typeof raw?.image === 'string' && raw.image.trim() ? raw.image.trim() : null,
+        dockerExecutable: typeof raw?.dockerExecutable === 'string' && raw.dockerExecutable.trim()
+            ? raw.dockerExecutable.trim()
+            : null,
+        dockerHost: typeof raw?.dockerHost === 'string' && raw.dockerHost.trim() ? raw.dockerHost.trim() : null,
+        timeoutMs: positiveInteger(raw?.timeoutMs, DEFAULT_CONTAINED_EXECUTION.timeoutMs),
+        memoryMiB: positiveInteger(raw?.memoryMiB, DEFAULT_CONTAINED_EXECUTION.memoryMiB),
+        cpus: positiveNumber(raw?.cpus, DEFAULT_CONTAINED_EXECUTION.cpus),
+        pids: positiveInteger(raw?.pids, DEFAULT_CONTAINED_EXECUTION.pids),
+    };
+}
+function normalizeSandboxConfig(raw) {
+    const runtime = raw?.runtime === 'cursor-sandbox' ||
+        raw?.runtime === 'container' ||
+        raw?.runtime === 'seatbelt' ||
+        raw?.runtime === 'landlock'
+        ? raw.runtime
+        : DEFAULT_SANDBOX_V3.runtime;
+    const containedExecution = normalizeContainedExecutionConfig(raw?.containedExecution);
+    if (containedExecution.enabled && (raw?.enabled !== true || runtime !== 'container')) {
+        throw new Error('contained execution requires sandbox.runtime=container with sandbox.enabled=true');
+    }
+    if (containedExecution.enabled && !containedExecution.image) {
+        throw new Error('contained execution requires an explicit image');
+    }
+    if (containedExecution.enabled && !containedExecution.dockerExecutable) {
+        throw new Error('contained execution requires an explicit Docker executable');
+    }
+    if (containedExecution.enabled &&
+        (!path.isAbsolute(containedExecution.dockerExecutable ?? '') ||
+            /[\0\n\r]/.test(containedExecution.dockerExecutable ?? ''))) {
+        throw new Error('contained execution requires an absolute executable path');
+    }
+    if (containedExecution.enabled && !containedExecution.dockerHost) {
+        throw new Error('contained execution requires an explicit Docker host');
+    }
+    if (containedExecution.enabled &&
+        (!containedExecution.dockerHost?.startsWith('unix:///') ||
+            !path.isAbsolute(containedExecution.dockerHost.slice('unix://'.length)) ||
+            /[\0\n\r]/.test(containedExecution.dockerHost))) {
+        throw new Error('contained execution requires a local unix Docker host');
+    }
+    return {
+        enabled: raw?.enabled === true,
+        runtime,
+        denyNetworkByDefault: raw?.denyNetworkByDefault !== false,
+        containedExecution,
+    };
+}
 export const DEFAULT_NOTIFICATIONS_V3 = {};
 export const DEFAULT_APPROVAL_SIGNING_V3 = {
     required: false,
@@ -829,16 +898,7 @@ export function normalizeConfig(config) {
                 : DEFAULT_EGRESS_V3.listenPort,
             demoteL3External: v4.egress?.demoteL3External !== false,
         },
-        sandbox: {
-            enabled: v4.sandbox?.enabled === true,
-            runtime: v4.sandbox?.runtime === 'cursor-sandbox' ||
-                v4.sandbox?.runtime === 'container' ||
-                v4.sandbox?.runtime === 'seatbelt' ||
-                v4.sandbox?.runtime === 'landlock'
-                ? v4.sandbox.runtime
-                : DEFAULT_SANDBOX_V3.runtime,
-            denyNetworkByDefault: v4.sandbox?.denyNetworkByDefault !== false,
-        },
+        sandbox: normalizeSandboxConfig(v4.sandbox),
         audit: {
             logPath: v4.audit?.logPath || DEFAULT_CONFIG_V4.audit.logPath,
             includeAssessment: v4.audit?.includeAssessment !== false,
@@ -859,6 +919,21 @@ export function isFreshConfigInput(loaded) {
     }
     return Object.keys(loaded).length === 0;
 }
+export function hasForbiddenShellOverrideLists(config) {
+    return config.overrides.allow.length > 0 || config.overrides.external.length > 0;
+}
+export function stripForbiddenShellOverrideLists(config) {
+    if (!hasForbiddenShellOverrideLists(config)) {
+        return config;
+    }
+    return {
+        ...config,
+        overrides: {
+            allow: [],
+            external: [],
+        },
+    };
+}
 export function mergeConfig(existing, defaults = DEFAULT_CONFIG_V4) {
     const migrated = isFreshConfigInput(existing)
         ? normalizeConfig({ ...defaults, version: 4 })
@@ -914,6 +989,10 @@ export function mergeConfig(existing, defaults = DEFAULT_CONFIG_V4) {
         sandbox: {
             ...defaults.sandbox,
             ...migrated.sandbox,
+            containedExecution: {
+                ...(defaults.sandbox.containedExecution ?? DEFAULT_CONTAINED_EXECUTION),
+                ...(migrated.sandbox.containedExecution ?? DEFAULT_CONTAINED_EXECUTION),
+            },
         },
         audit: {
             ...defaults.audit,

package/dist/core/contained-execution/docker-policy.d.ts

@@ -0,0 +1,18 @@
+import type { ContainedExecutionResourceLimits } from '../capability/attestation.js';
+export declare const TMPFS_SIZE_BYTES: number;
+export declare const SHM_SIZE_MIB = 64;
+export declare const TMPFS_OPTIONS = "rw,nosuid,nodev,noexec,size=67108864,mode=1777";
+export declare const PROXY_ENV_NAMES: readonly ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy"];
+export declare const IMAGE_ID_PATTERN: RegExp;
+export declare function assertContainedExecutionResourceLimits(limits: ContainedExecutionResourceLimits): void;
+export interface BuildContainedDockerCreateArgsParams {
+    containerName: string;
+    imageId: string;
+    command: string;
+    hostMirrorRoot: string;
+    guestWorkspacePath: string;
+    guestCwd: string;
+    resourceLimits: ContainedExecutionResourceLimits;
+    user: string;
+}
+export declare function buildContainedDockerCreateArgs(params: BuildContainedDockerCreateArgsParams): string[];

package/dist/core/contained-execution/docker-policy.js

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import { ContainedExecutionFailureError } from './failure.js';
+export const TMPFS_SIZE_BYTES = 64 * 1024 * 1024;
+export const SHM_SIZE_MIB = 64;
+export const TMPFS_OPTIONS = `rw,nosuid,nodev,noexec,size=${TMPFS_SIZE_BYTES},mode=1777`;
+export const PROXY_ENV_NAMES = [
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'ALL_PROXY',
+    'NO_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'all_proxy',
+    'no_proxy',
+];
+export const IMAGE_ID_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const SAFE_CONTAINER_NAME = /^belay-contained-[0-9a-f-]{36}$/;
+function assertSafeDockerPath(value, code) {
+    if (!path.isAbsolute(value) || /[\0\n\r,]/.test(value)) {
+        throw new ContainedExecutionFailureError(code);
+    }
+}
+export function assertContainedExecutionResourceLimits(limits) {
+    if (!Number.isSafeInteger(limits.timeoutMs) ||
+        limits.timeoutMs <= 0 ||
+        !Number.isSafeInteger(limits.memoryMiB) ||
+        limits.memoryMiB <= 0 ||
+        !Number.isFinite(limits.cpus) ||
+        limits.cpus <= 0 ||
+        !Number.isSafeInteger(limits.pids) ||
+        limits.pids <= 0) {
+        throw new ContainedExecutionFailureError('contained_execution_resource_limits_invalid');
+    }
+}
+export function buildContainedDockerCreateArgs(params) {
+    if (!IMAGE_ID_PATTERN.test(params.imageId)) {
+        throw new ContainedExecutionFailureError('contained_execution_invalid_image_id');
+    }
+    if (!SAFE_CONTAINER_NAME.test(params.containerName)) {
+        throw new ContainedExecutionFailureError('contained_execution_invalid_container_name');
+    }
+    assertSafeDockerPath(params.hostMirrorRoot, 'contained_execution_invalid_mount');
+    assertSafeDockerPath(params.guestWorkspacePath, 'contained_execution_invalid_mount');
+    assertSafeDockerPath(params.guestCwd, 'contained_execution_invalid_cwd');
+    assertContainedExecutionResourceLimits(params.resourceLimits);
+    if (!/^\d+:\d+$/.test(params.user)) {
+        throw new ContainedExecutionFailureError('contained_execution_invalid_user');
+    }
+    const memory = `${params.resourceLimits.memoryMiB}m`;
+    return [
+        'create',
+        '--name',
+        params.containerName,
+        '--network',
+        'none',
+        '--read-only',
+        '--tmpfs',
+        `/tmp:${TMPFS_OPTIONS}`,
+        '--cap-drop',
+        'ALL',
+        '--security-opt',
+        'no-new-privileges',
+        '--log-driver',
+        'none',
+        '--privileged=false',
+        '--publish-all=false',
+        '--restart',
+        'no',
+        '--memory',
+        memory,
+        '--memory-swap',
+        memory,
+        '--shm-size',
+        `${SHM_SIZE_MIB}m`,
+        '--cpus',
+        String(params.resourceLimits.cpus),
+        '--pids-limit',
+        String(params.resourceLimits.pids),
+        '--user',
+        params.user,
+        '--no-healthcheck',
+        '--ipc',
+        'none',
+        '--cgroupns',
+        'private',
+        ...PROXY_ENV_NAMES.flatMap((name) => ['--env', `${name}=`]),
+        '--mount',
+        `type=bind,src=${params.hostMirrorRoot},dst=${params.guestWorkspacePath}`,
+        '--workdir',
+        params.guestCwd,
+        '--entrypoint',
+        '/bin/sh',
+        params.imageId,
+        '-c',
+        params.command,
+    ];
+}

package/dist/core/contained-execution/docker.d.ts

@@ -0,0 +1,223 @@
+import type { BoundaryAttestation, ContainedExecutionAttestation, ContainedExecutionResourceLimits, DockerSubstrateIdentity } from '../capability/attestation.js';
+import type { BelayContainedExecutionConfig } from '../config.js';
+import { type ProcessOutputPolicy, type ShellRunResult } from '../process-runner.js';
+import { type BuildContainedDockerCreateArgsParams, buildContainedDockerCreateArgs } from './docker-policy.js';
+import { type ContainedExecutionFailureCode, ContainedExecutionFailureError } from './failure.js';
+import { type ContainedExecutionMirrorBackend, type ContainedExecutionMirrorHandle } from './mirror.js';
+export declare class ContainedDockerBoundaryUnavailableError extends ContainedExecutionFailureError {
+    readonly reason: ContainedExecutionFailureCode;
+    readonly receipt: undefined;
+    constructor(reason: ContainedExecutionFailureCode, options?: ErrorOptions);
+}
+export declare class ContainedDockerStartAttemptError extends ContainedExecutionFailureError {
+    constructor(options?: ErrorOptions);
+}
+export declare class ContainedDockerCleanupUnconfirmedError extends ContainedExecutionFailureError {
+    readonly containerName: string;
+    readonly executionStarted: boolean;
+    readonly cleanupConfirmed = false;
+    constructor(containerName: string, executionStarted: boolean, options?: ErrorOptions);
+}
+export interface ContainedDockerInspect {
+    Id: string;
+    Image: string;
+    Config: {
+        User: string;
+        Env: string[] | null;
+        Entrypoint: string[] | string | null;
+        Cmd: string[] | null;
+        WorkingDir: string;
+        Healthcheck: {
+            Test?: string[] | null;
+        } | null;
+    };
+    HostConfig: {
+        AutoRemove: boolean;
+        Privileged: boolean;
+        CapAdd: string[] | null;
+        CapDrop: string[] | null;
+        SecurityOpt: string[] | null;
+        LogConfig: {
+            Type: string;
+            Config: Record<string, string> | null;
+        } | null;
+        Devices: unknown[] | null;
+        DeviceRequests: unknown[] | null;
+        DeviceCgroupRules: string[] | null;
+        GroupAdd: string[] | null;
+        VolumesFrom: string[] | null;
+        Binds: string[] | null;
+        PortBindings: Record<string, unknown> | null;
+        PublishAllPorts: boolean;
+        Links: string[] | null;
+        ExtraHosts: string[] | null;
+        Dns: string[] | null;
+        DnsOptions: string[] | null;
+        DnsSearch: string[] | null;
+        NetworkMode: string;
+        ReadonlyRootfs: boolean;
+        Tmpfs: Record<string, string> | null;
+        Memory: number;
+        MemorySwap: number;
+        ShmSize: number;
+        NanoCpus: number;
+        PidsLimit: number | null;
+        RestartPolicy: {
+            Name: string;
+            MaximumRetryCount: number;
+        };
+        IpcMode: string;
+        PidMode: string;
+        UTSMode: string;
+        UsernsMode: string;
+        CgroupnsMode: string;
+    };
+    NetworkSettings: {
+        Ports: Record<string, unknown> | null;
+    };
+    Mounts: Array<{
+        Type: string;
+        Source: string;
+        Destination: string;
+        RW: boolean;
+    }>;
+}
+export interface ContainedDockerDependencies {
+    resolveSubstrate(params: {
+        executable: string;
+        host: string;
+        repoRoot: string;
+        protectedRoots: readonly string[];
+    }): Promise<DockerSubstrateIdentity>;
+    runProcess(file: string, args: string[], env: Record<string, string>, timeoutMs: number, outputPolicy?: ProcessOutputPolicy): Promise<ShellRunResult>;
+    now(): number;
+    randomUUID(): string;
+    uid(): number;
+    gid(): number;
+}
+export type { BuildContainedDockerCreateArgsParams };
+export { buildContainedDockerCreateArgs };
+export declare function probeContainedDockerBoundary(params: {
+    repoRoot: string;
+    protectedRoots: readonly string[];
+    imageReference: string;
+    dockerExecutable: string;
+    dockerHost: string;
+    hostProbeRoot: string;
+    guestWorkspacePath: string;
+    resourceLimits: ContainedExecutionResourceLimits;
+    dependencies?: ContainedDockerDependencies;
+}): Promise<ContainedExecutionAttestation>;
+export interface ContainedExecutionReceipt {
+    version: 1;
+    inputFingerprint: string;
+    actionFingerprint: string;
+    attestationDigest: string;
+    executionStarted: true;
+    timeoutMs: number;
+    dockerSubstrate: DockerSubstrateIdentity;
+    imageId: string;
+    mirror: {
+        backend: ContainedExecutionMirrorBackend;
+        type: 'bind';
+        cardinality: 1;
+        readWrite: true;
+        sourceFingerprint: string;
+        guestWorkspacePathFingerprint: string;
+        guestCwdFingerprint: string;
+    };
+    logging: {
+        driver: 'none';
+        config: Record<string, never>;
+    };
+    network: {
+        mode: 'none';
+        publishAllPorts: false;
+        portBindings: Record<string, never>;
+        links: [];
+        extraHosts: [];
+        dns: [];
+        dnsOptions: [];
+        dnsSearch: [];
+    };
+    readOnlyRoot: true;
+    tmpfs: {
+        path: '/tmp';
+        sizeBytes: number;
+        mode: 0o1777;
+        exec: false;
+        nosuid: true;
+        nodev: true;
+    };
+    environment: {
+        hostForwarded: false;
+        proxyEnvironment: 'neutralized-empty';
+        neutralizedVariables: readonly string[];
+        imageEnvironmentDigest: string;
+    };
+    privilege: {
+        privileged: false;
+        noNewPrivileges: true;
+        capAdd: [];
+        capDrop: ['ALL'];
+        groupAdd: [];
+    };
+    devices: {
+        devices: [];
+        deviceRequests: [];
+        deviceCgroupRules: [];
+    };
+    storage: {
+        volumesFrom: [];
+        bindsOutsideMirror: [];
+    };
+    namespaces: {
+        ipc: 'none';
+        pid: 'private';
+        uts: 'private';
+        cgroup: 'private';
+        user: 'default';
+    };
+    healthcheckDisabled: true;
+    lifecycle: {
+        autoRemove: false;
+        restart: 'no';
+        maximumRetryCount: 0;
+    };
+    resources: {
+        memoryMiB: number;
+        memorySwapMiB: number;
+        shmSizeMiB: number;
+        cpus: number;
+        nanoCpus: number;
+        pids: number;
+    };
+    user: string;
+    entrypoint: '/bin/sh';
+    exitCode: number | null;
+    timedOut: boolean;
+}
+export interface ContainedDockerExecutionResult extends ShellRunResult {
+    executionStarted: true;
+    receipt: ContainedExecutionReceipt;
+    receiptHash: string;
+}
+export interface ExecuteContainedDockerParams {
+    repoRoot: string;
+    controlPlaneDir: string;
+    protectedRoots: readonly string[];
+    config: BelayContainedExecutionConfig;
+    mirror: ContainedExecutionMirrorHandle;
+    guestCwd: string;
+    command: string;
+    inputFingerprint: string;
+    signedAttestation: unknown;
+    dependencies?: ContainedDockerDependencies;
+}
+export declare function executeContainedDocker(params: ExecuteContainedDockerParams): Promise<ContainedDockerExecutionResult>;
+export declare function probeContainedDockerForSession(params: {
+    repoRoot: string;
+    controlPlaneDir: string;
+    config: BelayContainedExecutionConfig;
+    dependencies?: ContainedDockerDependencies;
+}): Promise<BoundaryAttestation>;