@guilz-dev/belay 0.8.1 → 0.9.0

package/dist/core/capability/attestation.js

@@ -1,4 +1,6 @@
+import path from 'node:path';
 export const BOUNDARY_ATTESTATION_VERSION = 1;
+export const CONTAINED_EXECUTION_ATTESTATION_VERSION = 1;
 const KNOWN_DRIVERS = new Set([
     'container',
     'cursor-sandbox',
@@ -6,15 +8,21 @@ const KNOWN_DRIVERS = new Set([
     'landlock',
     'host-integration',
 ]);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isBoundaryDriver(value) {
+    return typeof value === 'string' && KNOWN_DRIVERS.has(value);
+}
 export function validateBoundaryAttestation(value) {
-    if (!value || typeof value !== 'object') {
+    if (!isRecord(value)) {
         return false;
     }
     const record = value;
     if (record.version !== BOUNDARY_ATTESTATION_VERSION) {
         return false;
     }
-    if (!KNOWN_DRIVERS.has(record.driver)) {
+    if (!isBoundaryDriver(record.driver)) {
         return false;
     }
     if (typeof record.probedAt !== 'string' || typeof record.expiresAt !== 'string') {
@@ -34,6 +42,12 @@ export function validateBoundaryAttestation(value) {
         typeof record.isolatesWorkspaceMounts !== 'boolean') {
         return false;
     }
+    if (record.containedExecution !== undefined) {
+        if (record.driver !== 'container' ||
+            !validateContainedExecutionAttestation(record.containedExecution)) {
+            return false;
+        }
+    }
     if (record.driver === 'host-integration' && record.materializesGrants) {
         return false;
     }
@@ -44,7 +58,94 @@ export function validateBoundaryAttestation(value) {
     }
     return true;
 }
-export function isAttestationFresh(attestation, now = Date.now()) {
+function hasPositiveLimit(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+function hasPositiveIntegerLimit(value) {
+    return hasPositiveLimit(value) && Number.isSafeInteger(value);
+}
+export function validateContainedExecutionAttestation(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const record = value;
+    const dockerSubstrate = record.dockerSubstrate;
+    const dockerConfiguration = record.dockerConfiguration;
+    if (record.version !== CONTAINED_EXECUTION_ATTESTATION_VERSION ||
+        typeof record.imageId !== 'string' ||
+        !/^sha256:[a-f0-9]{64}$/i.test(record.imageId) ||
+        typeof record.imageReference !== 'string' ||
+        !record.imageReference ||
+        /[\0\n\r]/.test(record.imageReference) ||
+        record.networkNone !== true ||
+        record.isolatesWorkspaceMirror !== true ||
+        record.readOnlyRoot !== true ||
+        record.sanitizedEnvironment !== true ||
+        !isRecord(dockerSubstrate) ||
+        typeof dockerSubstrate.binaryPath !== 'string' ||
+        !path.isAbsolute(dockerSubstrate.binaryPath) ||
+        /[\0\n\r]/.test(dockerSubstrate.binaryPath) ||
+        typeof dockerSubstrate.binarySha256 !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(dockerSubstrate.binarySha256) ||
+        typeof dockerSubstrate.endpoint !== 'string' ||
+        !dockerSubstrate.endpoint.startsWith('unix:///') ||
+        !path.isAbsolute(dockerSubstrate.endpoint.slice('unix://'.length)) ||
+        /[\0\n\r]/.test(dockerSubstrate.endpoint) ||
+        typeof dockerSubstrate.daemonId !== 'string' ||
+        !dockerSubstrate.daemonId ||
+        /[\0\n\r]/.test(dockerSubstrate.daemonId) ||
+        !isRecord(dockerConfiguration) ||
+        typeof dockerConfiguration.executable !== 'string' ||
+        !path.isAbsolute(dockerConfiguration.executable) ||
+        /[\0\n\r]/.test(dockerConfiguration.executable) ||
+        typeof dockerConfiguration.host !== 'string' ||
+        !dockerConfiguration.host.startsWith('unix:///') ||
+        !path.isAbsolute(dockerConfiguration.host.slice('unix://'.length)) ||
+        /[\0\n\r]/.test(dockerConfiguration.host) ||
+        typeof record.user !== 'string' ||
+        !/^\d+:\d+$/.test(record.user) ||
+        record.entrypoint !== '/bin/sh' ||
+        record.capDropAll !== true ||
+        record.noNewPrivileges !== true ||
+        record.logDriver !== 'none' ||
+        record.proxyEnvironment !== 'neutralized-empty' ||
+        typeof record.probedAt !== 'string' ||
+        typeof record.expiresAt !== 'string') {
+        return false;
+    }
+    const probedAt = Date.parse(record.probedAt);
+    const expiresAt = Date.parse(record.expiresAt);
+    if (!Number.isFinite(probedAt) || !Number.isFinite(expiresAt) || expiresAt <= probedAt) {
+        return false;
+    }
+    const limits = record.resourceLimits;
+    const tmpfs = record.tmpfs;
+    return (isRecord(tmpfs) &&
+        tmpfs.path === '/tmp' &&
+        hasPositiveIntegerLimit(tmpfs.sizeBytes) &&
+        tmpfs.mode === 0o1777 &&
+        tmpfs.exec === false &&
+        tmpfs.nosuid === true &&
+        tmpfs.nodev === true &&
+        hasPositiveIntegerLimit(record.memorySwapMiB) &&
+        hasPositiveIntegerLimit(record.shmSizeMiB) &&
+        record.healthcheckDisabled === true &&
+        record.privateNamespaces === true &&
+        record.privileged === false &&
+        record.devicesNone === true &&
+        isRecord(limits) &&
+        hasPositiveIntegerLimit(limits.timeoutMs) &&
+        hasPositiveIntegerLimit(limits.memoryMiB) &&
+        hasPositiveLimit(limits.cpus) &&
+        hasPositiveIntegerLimit(limits.pids));
+}
+export function isContainedExecutionAttestationFresh(attestation, now = Date.now()) {
+    // A contained proof must have been observed already; no clock skew is accepted.
+    return (validateContainedExecutionAttestation(attestation) &&
+        Date.parse(attestation.probedAt) <= now &&
+        Date.parse(attestation.expiresAt) > now);
+}
+export function isAttestationCurrent(attestation, now = Date.now()) {
     const expires = Date.parse(attestation.expiresAt);
     if (!Number.isFinite(expires)) {
         return false;
@@ -52,6 +153,12 @@ export function isAttestationFresh(attestation, now = Date.now()) {
     if (expires <= now) {
         return false;
     }
+    return true;
+}
+export function isAttestationFresh(attestation, now = Date.now()) {
+    if (!isAttestationCurrent(attestation, now)) {
+        return false;
+    }
     if (attestation.driver === 'host-integration') {
         return true;
     }

package/dist/core/capability/boundary-session.d.ts

@@ -1,4 +1,5 @@
 import type { BelayConfigV4 } from '../config.js';
+import { type ContainedDockerDependencies } from '../contained-execution/docker.js';
 import type { BoundaryAttestation, BoundaryDriverId } from './attestation.js';
 import { type BoundaryDriver } from './boundary-driver.js';
 import { dockerNetworkArgs } from './boundary-egress.js';
@@ -15,6 +16,7 @@ export interface ResolvedBoundaryDriverContext {
     attestationPath: string;
     attestation: BoundaryAttestation | null;
     attestationFresh: boolean;
+    containedExecutionFresh?: boolean;
 }
 export declare function boundaryAttestationPath(repoRoot: string, config: BelayConfigV4): string;
 export declare function loadBoundaryAttestation(filePath: string, expectedRepoRoot?: string, controlPlaneDir?: string): Promise<BoundaryAttestation | null>;
@@ -38,6 +40,7 @@ export declare function startBoundarySession(params: {
     config: BelayConfigV4;
     driverId?: BoundaryDriverId;
     egressProxyRunning?: boolean;
+    containedDockerDependencies?: ContainedDockerDependencies;
 }): Promise<{
     attestation: BoundaryAttestation;
     attestationPath: string;
@@ -45,10 +48,12 @@ export declare function startBoundarySession(params: {
 export declare function boundarySessionStatus(params: {
     repoRoot: string;
     config: BelayConfigV4;
+    now?: number;
 }): Promise<{
     attestationPath: string;
     attestation: BoundaryAttestation | null;
     fresh: boolean;
+    containedExecutionFresh?: boolean;
 }>;
 export declare function runBoundaryAgentCommand(params: {
     repoRoot: string;

package/dist/core/capability/boundary-session.js

@@ -2,11 +2,34 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { egressStatus } from '../../services/egress-service.js';
 import { configuredControlPlaneDir } from '../config.js';
-import { isAttestationFresh } from './attestation.js';
+import { probeContainedDockerForSession, } from '../contained-execution/docker.js';
+import { isAttestationFresh, isContainedExecutionAttestationFresh } from './attestation.js';
 import { readSignedAttestationFile, signBoundaryAttestation, verifySignedBoundaryAttestation, } from './boundary-attestation-sign.js';
 import { getDefaultBoundaryDriver } from './boundary-driver.js';
 import { dockerNetworkArgs, isEgressProxyActive, resolveBoundaryEgressProxyEnv, } from './boundary-egress.js';
 import { runWithBoundaryRunnable, } from './boundary-run.js';
+function containedExecutionFresh(attestation, config, now = Date.now()) {
+    if (attestation?.driver !== 'container' || !attestation.containedExecution)
+        return undefined;
+    const current = config.sandbox.containedExecution;
+    const capability = attestation.containedExecution;
+    const configCompatible = Boolean(current?.enabled &&
+        current.image === capability.imageReference &&
+        current.dockerExecutable === capability.dockerConfiguration.executable &&
+        current.dockerHost === capability.dockerConfiguration.host &&
+        current.timeoutMs === capability.resourceLimits.timeoutMs &&
+        current.memoryMiB === capability.resourceLimits.memoryMiB &&
+        current.cpus === capability.resourceLimits.cpus &&
+        current.pids === capability.resourceLimits.pids);
+    const probedAt = Date.parse(attestation.probedAt);
+    const expiresAt = Date.parse(attestation.expiresAt);
+    return (Number.isFinite(probedAt) &&
+        Number.isFinite(expiresAt) &&
+        probedAt <= now &&
+        expiresAt > now &&
+        configCompatible &&
+        isContainedExecutionAttestationFresh(capability, now));
+}
 export function boundaryAttestationPath(repoRoot, config) {
     const rel = config.capability?.attestationRelPath ?? '.belay/attestation.json';
     return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel);
@@ -92,6 +115,7 @@ export async function resolveBoundaryDriverContext(params) {
         attestationPath,
         attestation,
         attestationFresh: attestation ? isAttestationFresh(attestation) : false,
+        containedExecutionFresh: containedExecutionFresh(attestation, params.config),
     };
 }
 export async function runWithBoundaryDriver(params) {
@@ -104,6 +128,18 @@ export async function runWithBoundaryDriver(params) {
     });
 }
 export async function startBoundarySession(params) {
+    const contained = params.config.sandbox.containedExecution;
+    if (contained?.enabled === true) {
+        const attestation = await probeContainedDockerForSession({
+            repoRoot: params.repoRoot,
+            controlPlaneDir: configuredControlPlaneDir(params.config),
+            config: contained,
+            dependencies: params.containedDockerDependencies,
+        });
+        const attestationPath = boundaryAttestationPath(params.repoRoot, params.config);
+        await saveBoundaryAttestation(attestationPath, attestation, params.repoRoot, configuredControlPlaneDir(params.config));
+        return { attestation, attestationPath };
+    }
     const resolved = await resolveBoundaryDriverContext(params);
     const attestation = await resolved.driver.probe();
     if (resolved.driver.prepare) {
@@ -120,6 +156,7 @@ export async function boundarySessionStatus(params) {
         attestationPath,
         attestation,
         fresh: attestation ? isAttestationFresh(attestation) : false,
+        containedExecutionFresh: containedExecutionFresh(attestation, params.config, params.now),
     };
 }
 export async function runBoundaryAgentCommand(params) {

package/dist/core/capability/index.d.ts

@@ -1,5 +1,5 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
-export { attestsWorkspaceMountIsolation, BOUNDARY_ATTESTATION_VERSION, type BoundaryAttestation, type BoundaryDriverId, isAttestationFresh, } from './attestation.js';
+export { attestsWorkspaceMountIsolation, BOUNDARY_ATTESTATION_VERSION, type BoundaryAttestation, type BoundaryDriverId, CONTAINED_EXECUTION_ATTESTATION_VERSION, type ContainedExecutionAttestation, type ContainedExecutionResourceLimits, isAttestationFresh, isContainedExecutionAttestationFresh, validateContainedExecutionAttestation, } from './attestation.js';
 export { BOUNDARY_PROFILE_L1_ATTESTED, BOUNDARY_PROFILE_L3_L4_ONLY, BOUNDARY_PROFILE_L3_POLICY, boundaryVerifiedAllowEnabled, isAttestedBoundary, resolveBoundaryProfile, } from './boundary-profile.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
 export { CAPABILITY_GRANT_VERSION, type CapabilityGrantV1, isGrantScopeTooBroad, } from './grant.js';

package/dist/core/capability/index.js

@@ -1,5 +1,5 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
-export { attestsWorkspaceMountIsolation, BOUNDARY_ATTESTATION_VERSION, isAttestationFresh, } from './attestation.js';
+export { attestsWorkspaceMountIsolation, BOUNDARY_ATTESTATION_VERSION, CONTAINED_EXECUTION_ATTESTATION_VERSION, isAttestationFresh, isContainedExecutionAttestationFresh, validateContainedExecutionAttestation, } from './attestation.js';
 export { BOUNDARY_PROFILE_L1_ATTESTED, BOUNDARY_PROFILE_L3_L4_ONLY, BOUNDARY_PROFILE_L3_POLICY, boundaryVerifiedAllowEnabled, isAttestedBoundary, resolveBoundaryProfile, } from './boundary-profile.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
 export { CAPABILITY_GRANT_VERSION, isGrantScopeTooBroad, } from './grant.js';

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