@guilz-dev/belay 0.8.0 → 0.9.0

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

@@ -0,0 +1,9 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { GatedAction } from '../gate-contract.js';
+import type { ClassifyResult } from '../types.js';
+/**
+ * Returns whether an unknown shell EffectPlan can be mediated by the contained
+ * execution boundary. This only interprets normalized effects and gate context;
+ * it never derives authority from command syntax or command identity.
+ */
+export declare function isContainedUnknownExecutionEligible(config: BelayConfigV3, action: Pick<GatedAction, 'kind' | 'repoRoot'>, result: ClassifyResult): boolean;

package/dist/core/contained-execution/eligibility.js

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { collectRequirements } from '../effect-ir/build.js';
+import { resolveWorkspaceRootMatch } from '../path-utils.js';
+const FORBIDDEN_SIGNALS = new Set([
+    'command_substitution',
+    'control_plane_mutation',
+    'dynamic_shell_evaluation',
+    'high_stakes_path',
+    'pipe_to_shell',
+    'secret_payload_send',
+    'shell.xargs_stdin_dynamic',
+    'sensitive_path_read',
+    'tier0_external',
+    'tier1_catastrophic',
+    'unparseable_shell',
+]);
+/**
+ * Returns whether an unknown shell EffectPlan can be mediated by the contained
+ * execution boundary. This only interprets normalized effects and gate context;
+ * it never derives authority from command syntax or command identity.
+ */
+export function isContainedUnknownExecutionEligible(config, action, result) {
+    const contained = config.sandbox.containedExecution;
+    if (!contained?.enabled ||
+        !config.sandbox.enabled ||
+        config.sandbox.runtime !== 'container' ||
+        action.kind !== 'shell' ||
+        !path.isAbsolute(action.repoRoot) ||
+        !hasResolvedRepoIdentity(action.repoRoot) ||
+        !config.gates.shell ||
+        result.reason !== 'unknown_local_effect' ||
+        result.axes?.location !== 'repo_local' ||
+        result.assessment.external) {
+        return false;
+    }
+    const plan = result.effectPlan;
+    if (!plan || (plan.opacity !== 'transparent' && plan.opacity !== 'recursive')) {
+        return false;
+    }
+    const requirements = collectRequirements(plan.root);
+    if (requirements.length === 0 ||
+        !hasSafeRecursiveExpansion(plan, requirements) ||
+        !requirements.some((requirement) => requirement.action === 'process.exec') ||
+        requirements.some((requirement) => !isPermittedRequirement(requirement, action.repoRoot))) {
+        return false;
+    }
+    return !collectSignals(result, requirements).some(isForbiddenSignal);
+}
+function hasSafeRecursiveExpansion(plan, requirements) {
+    if (plan.opacity === 'transparent') {
+        return true;
+    }
+    return requirements.some((requirement) => (requirement.provenances ?? [requirement.provenance]).some((provenance) => typeof provenance.innerCommand === 'string' && provenance.innerCommand !== ''));
+}
+function isPermittedRequirement(requirement, repoRoot) {
+    if (requirement.tag === 'indeterminate' || requirement.action === 'indeterminate') {
+        return (requirement.tag === 'indeterminate' &&
+            requirement.action === 'indeterminate' &&
+            requirement.resource.kind === 'unknown');
+    }
+    if (requirement.tag === 'process.exec' && requirement.action === 'process.exec') {
+        return (requirement.resource.kind === 'executable' &&
+            (requirement.resource.operation === 'inspect' || requirement.resource.operation === 'spawn'));
+    }
+    return (((requirement.tag === 'fs.read' && requirement.action === 'fs.read') ||
+        (requirement.tag === 'fs.write' && requirement.action === 'fs.write')) &&
+        requirement.resource.kind === 'path' &&
+        isRepoLocalPath(repoRoot, requirement.resource.path));
+}
+function isRepoLocalPath(repoRoot, targetPath) {
+    try {
+        return resolveWorkspaceRootMatch(repoRoot, [], targetPath)?.kind === 'repo';
+    }
+    catch {
+        return false;
+    }
+}
+function hasResolvedRepoIdentity(repoRoot) {
+    try {
+        const match = resolveWorkspaceRootMatch(repoRoot, [], repoRoot);
+        return match?.kind === 'repo' && match.relativePath === '.';
+    }
+    catch {
+        return false;
+    }
+}
+function collectSignals(result, requirements) {
+    return [
+        ...new Set([
+            ...result.assessment.signals,
+            ...(result.axes?.signals ?? []),
+            ...(result.effectPlan?.signals ?? []),
+            ...requirements.flatMap((requirement) => requirement.evidence.signals),
+        ]),
+    ];
+}
+function isForbiddenSignal(signal) {
+    return (FORBIDDEN_SIGNALS.has(signal) ||
+        signal.startsWith('tier0_') ||
+        signal.startsWith('tier1_') ||
+        signal.includes('high_stakes') ||
+        signal.includes('control_plane'));
+}

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

@@ -0,0 +1,18 @@
+export declare const CONTAINED_EXECUTION_FAILURE_CODES: readonly ["contained_execution_boundary_failed", "contained_execution_capability_invalid", "contained_execution_capability_mismatch", "contained_execution_cleanup_unconfirmed", "contained_execution_container_cleanup_unconfirmed", "contained_execution_control_plane_roots_required", "contained_execution_create_failed", "contained_execution_create_invalid", "contained_execution_create_mismatch", "contained_execution_create_timeout", "contained_execution_create_truncated", "contained_execution_disabled", "contained_execution_docker_binary_invalid", "contained_execution_docker_config_missing", "contained_execution_docker_daemon_invalid", "contained_execution_docker_daemon_unavailable", "contained_execution_docker_host_invalid", "contained_execution_docker_substrate_mismatch", "contained_execution_docker_substrate_overlap", "contained_execution_docker_substrate_unavailable", "contained_execution_host_identity_unavailable", "contained_execution_image_inspect_invalid", "contained_execution_image_inspect_truncated", "contained_execution_image_mismatch", "contained_execution_image_missing", "contained_execution_input_fingerprint_invalid", "contained_execution_inspect_failed", "contained_execution_inspect_invalid", "contained_execution_inspect_mismatch", "contained_execution_inspect_timeout", "contained_execution_inspect_truncated", "contained_execution_invalid_container_name", "contained_execution_invalid_cwd", "contained_execution_invalid_image_id", "contained_execution_invalid_mirror_lease", "contained_execution_invalid_mount", "contained_execution_invalid_user", "contained_execution_mirror_limits_invalid", "contained_execution_probe_create_failed", "contained_execution_probe_failed", "contained_execution_probe_inspect_failed", "contained_execution_probe_inspect_invalid", "contained_execution_probe_inspect_truncated", "contained_execution_probe_root_cleanup_unconfirmed", "contained_execution_protected_root_overlap", "contained_execution_resource_limits_invalid", "contained_execution_safe_open_unavailable", "contained_execution_source_changed", "contained_execution_source_is_protected", "contained_execution_source_not_directory", "contained_execution_start_attempt_failed", "contained_execution_unknown_option", "contained_execution_unsafe_symlink"];
+export type ContainedExecutionFailureCode = (typeof CONTAINED_EXECUTION_FAILURE_CODES)[number];
+export type ContainedExecutionFailurePhase = 'boundary' | 'capability' | 'image' | 'mirror' | 'lease' | 'container-lifecycle' | 'cleanup';
+export type ContainedExecutionFailureDisposition = 'approval-fallback' | 'deny';
+export type ContainedExecutionFailureRemediation = 'session-start' | 'none';
+export declare function isContainedExecutionFailureCode(value: unknown): value is ContainedExecutionFailureCode;
+export declare function containedExecutionFailurePhase(code: ContainedExecutionFailureCode): ContainedExecutionFailurePhase;
+export declare class ContainedExecutionFailureError extends Error {
+    readonly code: ContainedExecutionFailureCode;
+    readonly phase: ContainedExecutionFailurePhase;
+    readonly executionStarted: boolean;
+    readonly disposition: ContainedExecutionFailureDisposition;
+    readonly remediation: ContainedExecutionFailureRemediation;
+    constructor(code: ContainedExecutionFailureCode, options?: ErrorOptions & {
+        phase?: ContainedExecutionFailurePhase;
+        executionStarted?: boolean;
+    });
+}

package/dist/core/contained-execution/failure.js

@@ -0,0 +1,105 @@
+import { isContainedExecutionApprovalFallbackReason } from './policy.js';
+export const CONTAINED_EXECUTION_FAILURE_CODES = [
+    'contained_execution_boundary_failed',
+    'contained_execution_capability_invalid',
+    'contained_execution_capability_mismatch',
+    'contained_execution_cleanup_unconfirmed',
+    'contained_execution_container_cleanup_unconfirmed',
+    'contained_execution_control_plane_roots_required',
+    'contained_execution_create_failed',
+    'contained_execution_create_invalid',
+    'contained_execution_create_mismatch',
+    'contained_execution_create_timeout',
+    'contained_execution_create_truncated',
+    'contained_execution_disabled',
+    'contained_execution_docker_binary_invalid',
+    'contained_execution_docker_config_missing',
+    'contained_execution_docker_daemon_invalid',
+    'contained_execution_docker_daemon_unavailable',
+    'contained_execution_docker_host_invalid',
+    'contained_execution_docker_substrate_mismatch',
+    'contained_execution_docker_substrate_overlap',
+    'contained_execution_docker_substrate_unavailable',
+    'contained_execution_host_identity_unavailable',
+    'contained_execution_image_inspect_invalid',
+    'contained_execution_image_inspect_truncated',
+    'contained_execution_image_mismatch',
+    'contained_execution_image_missing',
+    'contained_execution_input_fingerprint_invalid',
+    'contained_execution_inspect_failed',
+    'contained_execution_inspect_invalid',
+    'contained_execution_inspect_mismatch',
+    'contained_execution_inspect_timeout',
+    'contained_execution_inspect_truncated',
+    'contained_execution_invalid_container_name',
+    'contained_execution_invalid_cwd',
+    'contained_execution_invalid_image_id',
+    'contained_execution_invalid_mirror_lease',
+    'contained_execution_invalid_mount',
+    'contained_execution_invalid_user',
+    'contained_execution_mirror_limits_invalid',
+    'contained_execution_probe_create_failed',
+    'contained_execution_probe_failed',
+    'contained_execution_probe_inspect_failed',
+    'contained_execution_probe_inspect_invalid',
+    'contained_execution_probe_inspect_truncated',
+    'contained_execution_probe_root_cleanup_unconfirmed',
+    'contained_execution_protected_root_overlap',
+    'contained_execution_resource_limits_invalid',
+    'contained_execution_safe_open_unavailable',
+    'contained_execution_source_changed',
+    'contained_execution_source_is_protected',
+    'contained_execution_source_not_directory',
+    'contained_execution_start_attempt_failed',
+    'contained_execution_unknown_option',
+    'contained_execution_unsafe_symlink',
+];
+const failureCodes = new Set(CONTAINED_EXECUTION_FAILURE_CODES);
+const mirrorFailureCodes = new Set([
+    'contained_execution_control_plane_roots_required',
+    'contained_execution_mirror_limits_invalid',
+    'contained_execution_safe_open_unavailable',
+    'contained_execution_source_changed',
+    'contained_execution_source_is_protected',
+    'contained_execution_source_not_directory',
+    'contained_execution_unsafe_symlink',
+]);
+export function isContainedExecutionFailureCode(value) {
+    return typeof value === 'string' && failureCodes.has(value);
+}
+export function containedExecutionFailurePhase(code) {
+    if (code.includes('cleanup'))
+        return 'cleanup';
+    if (code.includes('capability'))
+        return 'capability';
+    if (code.includes('image'))
+        return 'image';
+    if (code.includes('lease'))
+        return 'lease';
+    if (mirrorFailureCodes.has(code))
+        return 'mirror';
+    if (/_(?:create|inspect|start|probe)_/.test(code))
+        return 'container-lifecycle';
+    return 'boundary';
+}
+export class ContainedExecutionFailureError extends Error {
+    code;
+    phase;
+    executionStarted;
+    disposition;
+    remediation;
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+        this.name = 'ContainedExecutionFailureError';
+        this.phase = options?.phase ?? containedExecutionFailurePhase(code);
+        this.executionStarted = options?.executionStarted ?? false;
+        this.disposition = isContainedExecutionApprovalFallbackReason(code)
+            ? 'approval-fallback'
+            : 'deny';
+        this.remediation =
+            this.phase === 'capability' || this.phase === 'image' || code.includes('_docker_')
+                ? 'session-start'
+                : 'none';
+    }
+}

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

@@ -0,0 +1,54 @@
+import { ContainedExecutionFailureError } from './failure.js';
+export declare const CONTAINED_EXECUTION_CLEANUP_UNCONFIRMED = "contained_execution_cleanup_unconfirmed";
+export declare const CONTAINED_EXECUTION_SOURCE_CHANGED = "contained_execution_source_changed";
+export declare const CONTAINED_EXECUTION_UNSAFE_SYMLINK = "contained_execution_unsafe_symlink";
+export declare class ContainedExecutionCleanupUnconfirmedError extends ContainedExecutionFailureError {
+    readonly mirrorRoot: string;
+    constructor(mirrorRoot: string, options?: ErrorOptions);
+}
+export type ContainedExecutionMirrorBackend = 'file_copy';
+export interface ContainedExecutionMirrorLimits {
+    maxFiles: number;
+    maxSourceBytes: number;
+    maxWorkspaceBytes: number;
+    prepareTimeoutMs: number;
+}
+export interface ContainedExecutionMirrorOptions {
+    sourceRoot: string;
+    /** Must be supplied explicitly, even when the resolved set is deliberately empty. */
+    controlPlaneRoots: string[];
+    limits: ContainedExecutionMirrorLimits;
+}
+export interface ContainedExecutionMirrorHandle {
+    /** Exact private host root containing guest-visible content only. */
+    hostMirrorRoot: string;
+    /** Absolute path at which Task 4 must mount hostMirrorRoot inside the guest. */
+    guestWorkspacePath: string;
+    backend: ContainedExecutionMirrorBackend;
+    cleanup(): Promise<void>;
+}
+/** Internal execution-boundary check; the public core index deliberately does not re-export it. */
+export declare function validateContainedExecutionMirrorLease(handle: ContainedExecutionMirrorHandle, expected: {
+    sourceRoot: string;
+    protectedRoots: readonly string[];
+}): boolean;
+interface MirrorTestDependencies {
+    makeTempRoot?(): Promise<string>;
+    removeRoot?(root: string): Promise<void>;
+    now?(): number;
+    afterSnapshotCaptured?(): Promise<void>;
+    beforeCopyOpen?(sourcePath: string): Promise<void>;
+    afterCopyRead?(sourcePath: string, bytesRead: number, totalBytes: number): Promise<void>;
+}
+/**
+ * Non-atomic acceptance rule: the current source tree is read, copied, then read again. A mirror
+ * is returned only when both source observations and the copied tree have the same content/mode
+ * hash. This detects ordinary concurrent changes but does not claim an atomic filesystem snapshot.
+ */
+export declare function prepareContainedExecutionMirror(options: ContainedExecutionMirrorOptions): Promise<ContainedExecutionMirrorHandle>;
+/** Narrow test seam for deterministic allocation, race, deadline, and removal failures. */
+export declare function prepareContainedExecutionMirrorForTests(options: ContainedExecutionMirrorOptions, overrides: MirrorTestDependencies): Promise<ContainedExecutionMirrorHandle>;
+export declare function withContainedExecutionMirror<T>(options: ContainedExecutionMirrorOptions, operation: (mirror: ContainedExecutionMirrorHandle) => Promise<T>): Promise<T>;
+/** Narrow test seam matching prepareContainedExecutionMirrorForTests. */
+export declare function withContainedExecutionMirrorForTests<T>(options: ContainedExecutionMirrorOptions, operation: (mirror: ContainedExecutionMirrorHandle) => Promise<T>, overrides: MirrorTestDependencies): Promise<T>;
+export {};