firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/runner-runtime.js

@@ -0,0 +1,396 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, open, readFile, realpath, rename, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { containerPolicy } from './local-container-policy.js';
+import { boundaryArguments, requireContainerBoundary } from './local-container-boundary.js';
+import { withProcessLifetimeLock } from './runner-process-lock.js';
+import { localRuntimeCatalogMatches } from '../../contracts/local-runner-contracts.js';
+const IMAGE = /^[a-z][a-z0-9-]{0,62}-docker\.pkg\.dev\/[a-z][a-z0-9-]{4,62}\/[a-z][a-z0-9-]{0,62}\/[a-z][a-z0-9-]{0,62}@sha256:[a-f0-9]{64}$/;
+const PROFILE = 'firedrill.local-container.v1';
+// Source-free guest readiness allows 60s for its child and 5s for teardown.
+// Keep 25s for controller setup/observation without changing target budgets or
+// user/ownership cancellation. Cleanup retains its separate fenced deadline.
+const READINESS_ATTACH_SECONDS = 90;
+export function hostArch() {
+    if (!['darwin', 'linux'].includes(process.platform) || !['arm64', 'x64'].includes(process.arch)) {
+        throw new CliError('runner_host_unsupported', 'Use macOS or Linux on arm64 or x64 for this local container path.', 2);
+    }
+    return process.arch === 'x64' ? 'amd64' : 'arm64';
+}
+async function privateSubdirectory(name) {
+    const directory = join(await privateDirectory(), name);
+    await mkdir(directory, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const value = await lstat(directory);
+    if (!value.isDirectory() || value.isSymbolicLink() || value.mode & 0o077 || process.getuid && value.uid !== process.getuid()) {
+        throw new CliError('runner_storage_unsafe', 'Use private runner storage owned by this OS user.');
+    }
+    return directory;
+}
+export async function docker() {
+    hostArch();
+    const home = await privateSubdirectory('docker-client');
+    const configuration = await privateSubdirectory('docker-configuration');
+    const config = join(configuration, 'config.json');
+    try {
+        const file = await open(config, 'wx', 0o600);
+        try {
+            await file.writeFile('{"auths":{}}\n');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const configStat = await lstat(config);
+    if (!configStat.isFile() || configStat.isSymbolicLink() || configStat.mode & 0o077 || configStat.size > 32
+        || process.getuid && configStat.uid !== process.getuid() || await readFile(config, 'utf8') !== '{"auths":{}}\n') {
+        throw new CliError('runner_configuration_unsafe', 'The private container-client configuration changed. It was not used.');
+    }
+    const project = await realpath(process.cwd());
+    let binary;
+    for (const candidate of ['/usr/bin/docker', '/usr/local/bin/docker', '/opt/homebrew/bin/docker', '/Applications/Docker.app/Contents/Resources/bin/docker']) {
+        const path = await realpath(candidate).catch(() => null);
+        if (!path)
+            continue;
+        const within = relative(project, path);
+        if (within === '' || !within.startsWith('..' + sep) && within !== '..' && !isAbsolute(within))
+            continue;
+        const value = await stat(path);
+        if (!value.isFile() || value.mode & 0o022 || process.getuid && ![0, process.getuid()].includes(value.uid))
+            continue;
+        try {
+            await access(path, constants.X_OK);
+            binary = path;
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!binary)
+        throw new CliError('container_runtime_required', 'Install Docker Desktop or Docker Engine outside the project and start it. No host software was installed.', 2);
+    const sockets = [join(homedir(), '.docker/run/docker.sock'), ...(process.getuid ? [`/run/user/${process.getuid()}/docker.sock`] : []), '/var/run/docker.sock'];
+    let socket;
+    for (const candidate of sockets) {
+        const path = await realpath(candidate).catch(() => null);
+        if (!path)
+            continue;
+        const value = await stat(path);
+        if (value.isSocket() && !(value.mode & 0o002) && (!process.getuid || [0, process.getuid()].includes(value.uid))) {
+            socket = path;
+            break;
+        }
+    }
+    if (!socket)
+        throw new CliError('local_container_socket_required', 'Start a local Docker Engine. Remote contexts, SSH and TCP endpoints are not used.', 2);
+    return { binary, socket, configuration, home };
+}
+/** Internal fixed-command callers only. Never a target/model command executor. */
+export function dockerProcess(context, args, signal) {
+    return spawn(context.binary, ['--config', context.configuration, '--host', `unix://${context.socket}`, ...args], { shell: false, cwd: context.home, env: { HOME: context.home, PATH: '/usr/bin:/bin', LANG: 'C.UTF-8', LC_ALL: 'C' },
+        stdio: ['pipe', 'pipe', 'pipe'], signal });
+}
+export async function command(context, args, options = {}) {
+    const signal = AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout((options.seconds ?? 30) * 1000)]);
+    return new Promise((accept, refuse) => {
+        let bytes = 0, overflow = false;
+        const chunks = [];
+        const child = spawn(context.binary, ['--config', context.configuration, '--host', `unix://${context.socket}`, ...args], { shell: false, cwd: context.home, env: { HOME: context.home, PATH: '/usr/bin:/bin', LANG: 'C.UTF-8', LC_ALL: 'C' },
+            stdio: ['ignore', 'pipe', 'pipe'], signal });
+        child.stdout.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > (options.maximum ?? 65536)) {
+                overflow = true;
+                child.kill('SIGTERM');
+            }
+            else if (!overflow)
+                chunks.push(chunk);
+        });
+        child.stderr.resume(); // No arbitrary daemon/registry/host text in output.
+        child.once('error', () => refuse(new CliError('container_operation_uncertain', 'The container operation was not confirmed. Inspect its exact saved request before continuing.')));
+        child.once('close', code => {
+            if (overflow || signal.aborted) {
+                refuse(new CliError('container_operation_uncertain', 'The container operation was not confirmed. Inspect its exact saved request before continuing.'));
+                return;
+            }
+            accept({ code, output: Buffer.concat(chunks).toString('utf8') });
+        });
+    });
+}
+function document(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new CliError('container_response_invalid', 'The container response could not be read safely.');
+    }
+}
+export async function imagePresent(context, runtime, signal) {
+    const result = await command(context, ['image', 'inspect', runtime.image], { signal });
+    if (result.code !== 0)
+        return false;
+    const rows = document(result.output);
+    const row = Array.isArray(rows) && rows.length === 1 ? rows[0] : null;
+    if (!row || row.Os !== 'linux' || row.Architecture !== runtime.arch || !Array.isArray(row.RepoDigests)
+        || !row.RepoDigests.includes(runtime.image) || row.Config?.Labels?.['io.firedrill.engine-source-revision'] !== runtime.source_revision) {
+        throw new CliError('container_image_mismatch', 'The installed image does not match the selected engine and architecture. It was not started.');
+    }
+    return true;
+}
+const journalPath = async (value) => join(await privateDirectory(), `runtime-probe-${identifier(value.owner)}-${identifier(value.workspace)}-${identifier(value.key)}.json`);
+async function persist(value) {
+    const path = await journalPath(value);
+    const temporary = path + '.' + randomUUID() + '.tmp';
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+}
+async function owned(value, signal, work) {
+    signal.throwIfAborted();
+    const path = join(await privateDirectory(), `runtime-probe-lock-${identifier(value.owner)}-${identifier(value.workspace)}-${identifier(value.key)}`);
+    return withProcessLifetimeLock(path, signal, work);
+}
+async function load(scope, key) {
+    const path = await journalPath({ ...scope, key });
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.mode & 0o077 || before.size > 8192
+        || process.getuid && before.uid !== process.getuid())
+        throw new CliError('runner_journal_unsafe', 'The runtime request journal is not private. It was not used.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size)
+            throw new Error();
+        const value = document(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.local-runtime-probe.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace || value.key !== identifier(key)
+            || value.name !== 'fd-readiness-' + key || !IMAGE.test(value.image) || !/^[a-f0-9]{40}$/.test(value.source_revision)
+            || !['create_dispatched', 'created', 'start_dispatched', 'observed', 'cleanup_confirmed'].includes(value.stage)
+            || value.container_id !== null && !/^[a-f0-9]{64}$/.test(value.container_id))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new CliError('runner_journal_invalid', 'The runtime request journal changed. It was not replayed.');
+    }
+    finally {
+        await file.close();
+    }
+}
+async function inspected(context, value, signal) {
+    const response = await command(context, ['container', 'inspect', value.container_id ?? value.name], { signal });
+    if (response.code !== 0)
+        return null; // Absence is not proof a dispatched create cannot still arrive.
+    const rows = document(response.output);
+    const row = Array.isArray(rows) && rows.length === 1 ? rows[0] : null;
+    const labels = row?.Config?.Labels;
+    if (!row || !/^[a-f0-9]{64}$/.test(row.Id) || value.container_id && row.Id !== value.container_id
+        || row.Name !== '/' + value.name || row.Config?.Image !== value.image
+        || labels?.['io.firedrill.local-probe'] !== value.key || labels?.['io.firedrill.actor'] !== value.owner
+        || labels?.['io.firedrill.workspace'] !== value.workspace) {
+        throw new CliError('container_identity_mismatch', 'This container does not belong to the saved runtime request. It was not changed.');
+    }
+    return row;
+}
+const readinessArguments = (policy) => ['-m', 'runtime_support.guest_local_readiness',
+    ...(policy.requiredApparmor ? ['--apparmor-profile', policy.apparmor.name] : [])];
+const readinessBoundary = (image, policy) => ({ image, arguments: readinessArguments(policy),
+    memoryBytes: 4 * 1024 ** 3, nanoCpus: 2 * 10 ** 9, interactive: false, tmpfs: {
+        '/work': 'rw,nosuid,nodev,size=64m,uid=2000,gid=2000,mode=0755',
+        '/run/simulation': 'rw,nosuid,nodev,noexec,size=16m,uid=2000,gid=2000,mode=0700',
+        '/tmp': 'rw,nosuid,nodev,noexec,size=64m,uid=2000,gid=2000,mode=1777'
+    } });
+function sealed(row, policy) {
+    requireContainerBoundary(row, policy, readinessBoundary(row.Config?.Image, policy));
+}
+async function cleanup(context, value, signal) {
+    const row = await inspected(context, value, signal);
+    if (!row)
+        return false;
+    value.container_id = row.Id;
+    await persist(value);
+    const removed = await command(context, ['container', 'rm', '--force', row.Id], { signal });
+    if (removed.code !== 0)
+        return false;
+    value.stage = 'cleanup_confirmed';
+    await persist(value);
+    return true;
+}
+export async function runtimeCommand(action, key, options, output) {
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY,
+        openBrowser: options.openBrowser, signal: options.signal });
+    return scopedRuntimeCommand(scope, action, key, options, output);
+}
+export async function scopedRuntimeCommand(scope, action, key, options, output) {
+    const arch = hostArch();
+    const context = await docker();
+    if (action === 'recover') {
+        if (!key)
+            throw new CliError('request_key_required', 'Use the exact runtime request key.', 2);
+        return owned({ ...scope, key: identifier(key) }, options.signal, async (active) => {
+            const value = await load(scope, identifier(key));
+            if (value.stage === 'cleanup_confirmed') {
+                output('runtime_cleanup', { request_key: value.key, state: value.stage }, 'Runtime readiness container cleanup was confirmed.');
+                return null;
+            }
+            const removed = await cleanup(context, value, active);
+            output('runtime_cleanup', { request_key: value.key, state: removed ? 'cleanup_confirmed' : 'not_visible' }, removed
+                ? 'Runtime readiness container removed.' : 'The container is not visible. Its pending create is not replayed; the journal remains for a later lookup.');
+            return null;
+        });
+    }
+    const info = await command(context, ['info', '--format', '{{json .}}'], { signal: options.signal, maximum: 128 * 1024 });
+    if (info.code !== 0)
+        throw new CliError('local_container_unavailable', 'The local Docker Engine is unavailable. Start it and try again.', 2);
+    const host = document(info.output);
+    const daemonArch = host.Architecture === 'x86_64' ? 'amd64' : host.Architecture === 'aarch64' ? 'arm64' : host.Architecture;
+    if (host.OSType !== 'linux' || daemonArch !== arch)
+        throw new CliError('local_container_architecture_required', 'Use a same-architecture Linux Docker Engine. No emulation was selected.', 2);
+    const policy = await containerPolicy(arch, host.SecurityOptions);
+    if (action === 'policy') {
+        const summary = { schema: policy.schema, seccomp: { path: policy.seccomp.path, sha256: policy.seccomp.sha256 },
+            apparmor: { ...policy.apparmor, required: policy.requiredApparmor }, installed_by_command: false };
+        output('runtime_policy', summary, `Local security policy exported. No host policy was installed or disabled.\nSeccomp: ${policy.seccomp.path}\n`
+            + (policy.requiredApparmor ? `AppArmor: ${policy.apparmor.path}\nA daemon-host administrator must load this exact named AppArmor 4 profile before execution. No daemon default is changed.`
+                : 'This daemon does not advertise AppArmor. Seccomp and strict namespace/role isolation are still required.'));
+        return null;
+    }
+    if (host.OSType !== 'linux' || daemonArch !== arch || !Number.isSafeInteger(host.NCPU) || host.NCPU < 2
+        || !Number.isSafeInteger(host.MemTotal) || host.MemTotal < 4 * 1024 ** 3) {
+        throw new CliError('local_container_capacity_required', 'Use a same-architecture Linux Docker Engine with at least 2 CPUs and 4 GiB of memory. No emulation or cloud fallback was selected.', 2);
+    }
+    const catalog = await api(`/api/workspaces/${scope.workspace}/local-runner-runtime`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+    const runtime = localRuntimeCatalogMatches(catalog, scope.owner, scope.workspace)
+        ? catalog.runtimes.find(item => item.arch === arch) : undefined;
+    if (!runtime || runtime.os !== 'linux' || runtime.profile !== PROFILE || !IMAGE.test(runtime.image) || !/^[a-f0-9]{40}$/.test(runtime.source_revision)) {
+        throw new CliError('local_runtime_configuration_required', 'A pinned local runtime for this architecture is not available. No image or project was run.');
+    }
+    let installed = await imagePresent(context, runtime, options.signal);
+    if (!installed && action === 'install') {
+        if (!options.install) {
+            if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+                throw new CliError('runtime_install_consent_required', 'Pass --install-runtime to download the pinned execution image. No host software is installed.', 2);
+            const approved = await selectOne('Download the local execution image?', [{ value: true, label: 'Download', detail: 'Install only the selected digest-pinned image in your local Docker Engine.' }, { value: false, label: 'Cancel' }], options.signal);
+            if (!approved)
+                throw new CliError('canceled', 'No image was downloaded.', 130);
+        }
+        output('runtime_download', { image: runtime.image }, 'Downloading the pinned execution image.');
+        const pulled = await command(context, ['image', 'pull', '--quiet', '--platform', `linux/${arch}`, runtime.image], { signal: options.signal, seconds: 1800, maximum: 65536 });
+        if (pulled.code !== 0)
+            throw new CliError('runtime_download_unconfirmed', 'The execution image download was not confirmed. No container or project was started.');
+        installed = await imagePresent(context, runtime, options.signal);
+    }
+    const security = { schema: policy.schema, seccomp_sha256: policy.seccomp.sha256,
+        apparmor_profile: policy.requiredApparmor ? policy.apparmor.name : null };
+    const summary = { schema: 'firedrill.local-runtime-host.v1', runtime, installed, cpu_count: host.NCPU,
+        memory_bytes: host.MemTotal, connection: 'local_unix_socket', provenance: 'customer_device', security };
+    if (action !== 'check') {
+        output('runtime_host', summary, installed ? 'Pinned execution image installed. Container isolation has not been observed yet.' : 'The execution image is not installed. Use firedrill runner runtime install.');
+        return { runtime, installed, isolation_observed: false, cleanup_confirmed: false };
+    }
+    if (!installed)
+        throw new CliError('runtime_image_required', 'Use firedrill runner runtime install first. No container was started.', 2);
+    const value = { schema: 'firedrill.local-runtime-probe.v1', ...scope, key: randomUUID(), image: runtime.image,
+        source_revision: runtime.source_revision, name: '', container_id: null, stage: 'create_dispatched', security: summary.security };
+    value.name = 'fd-readiness-' + value.key;
+    await persist(value);
+    output('runtime_request', { request_key: value.key }, `Runtime readiness request ${value.key}. Recover cleanup with firedrill runner runtime recover ${value.key}.`);
+    return owned(value, options.signal, async (active, ownership) => {
+        let cleanupConfirmed = false;
+        try {
+            const created = await command(context, ['container', 'create', '--name', value.name, '--pull', 'never', '--platform', `linux/${arch}`,
+                '--label', `io.firedrill.local-probe=${value.key}`, '--label', `io.firedrill.actor=${scope.owner}`, '--label', `io.firedrill.workspace=${scope.workspace}`,
+                ...boundaryArguments(readinessBoundary(runtime.image, policy), policy)], { signal: active });
+            if (created.code !== 0 || !/^[a-f0-9]{64}$/.test(created.output.trim()))
+                throw new CliError('container_creation_unconfirmed', 'The readiness container was not confirmed. Recover this exact request; no second container was created.');
+            value.container_id = created.output.trim();
+            value.stage = 'created';
+            await persist(value);
+            const row = await inspected(context, value, active);
+            if (!row || row.State?.Status !== 'created' || row.State?.Running || row.State?.Restarting)
+                throw new CliError('container_start_ambiguous', 'The readiness container state changed. Its start was not repeated.');
+            sealed(row, policy);
+            value.stage = 'start_dispatched';
+            await persist(value);
+            const observed = await command(context, ['container', 'start', '--attach', value.container_id], { signal: active, seconds: READINESS_ATTACH_SECONDS, maximum: 8192 });
+            const result = document(observed.output);
+            const after = await inspected(context, value, active);
+            if (after)
+                sealed(after, policy);
+            const facts = result?.data;
+            const surface = facts?.inner?.surface;
+            const observedArch = facts?.container_arch === 'x86_64' ? 'amd64' : facts?.container_arch === 'aarch64' ? 'arm64' : facts?.container_arch;
+            if (observed.code !== 0 || result.ok !== true || !after || after.State?.Running || after.State?.ExitCode !== 0
+                || facts?.schema !== 'firedrill.local-runtime-observation.v1' || facts.container_os !== 'linux'
+                || observedArch !== runtime.arch
+                || facts.writable_storage !== true || facts.engine_import_available !== true || facts.parent_identity_ranges !== true
+                || facts.apparmor_enforced !== security.apparmor_profile || facts.inner?.kind !== 'rootless_user_namespace'
+                || facts.inner?.schema !== 'firedrill.local-inner-observation.v1'
+                || facts.inner?.separate_process_users !== true || facts.inner?.network !== 'isolated_loopback_only' || facts.inner?.role_identity_drop !== true
+                || !surface || typeof surface !== 'object' || Array.isArray(surface)
+                || Object.keys(surface).length !== 5
+                || surface.source_free !== true || surface.html_observed !== true || surface.frame_observed !== true
+                || surface.role_identity_drop !== true || surface.cleanup_confirmed !== true) {
+                throw new CliError(['local_namespace_policy_required', 'local_parent_mapping_required', 'local_lsm_policy_required', 'controller_bootstrap_unavailable',
+                    'local_namespace_syscall_denied', 'local_namespace_capability_unavailable', 'local_namespace_mount_unavailable',
+                    'local_uid_mapping_unavailable', 'local_gid_mapping_unavailable',
+                    'local_inner_identity_unavailable', 'local_role_namespace_unavailable', 'local_role_entry_unavailable',
+                    'local_surface_prerequisite_unavailable'].includes(result?.error?.code) ? result.error.code : 'local_runtime_not_ready', result?.error?.code === 'local_parent_mapping_required'
+                    ? 'The container parent namespace cannot map the required isolated service identities. No host user-namespace setting was changed or bypassed.'
+                    : result?.error?.code === 'controller_bootstrap_unavailable'
+                        ? 'The fixed controller could not establish its required capability boundary. No privileged or weaker runtime was selected.'
+                        : result?.error?.code === 'local_namespace_syscall_denied'
+                            ? 'The runtime refused the required namespace syscall. No host setting, privileged mode or weaker runtime was selected.'
+                            : ['local_namespace_capability_unavailable', 'local_namespace_mount_unavailable'].includes(result?.error?.code)
+                                ? 'The fixed namespace helper could not establish its required inner capabilities or private mounts. No outer capability or host policy was broadened.'
+                                : ['local_uid_mapping_unavailable', 'local_gid_mapping_unavailable'].includes(result?.error?.code)
+                                    ? 'The fixed identity-mapping helper could not establish the required service IDs. No mapping or host policy was bypassed.'
+                                    : ['local_inner_identity_unavailable', 'local_role_namespace_unavailable', 'local_role_entry_unavailable'].includes(result?.error?.code)
+                                        ? 'The inner runtime could not establish its required identity, role namespace or sealed process boundary. No project or weaker fallback was started.'
+                                        : result?.error?.code === 'local_surface_prerequisite_unavailable'
+                                            ? 'The isolated browser could not complete its startup, capture and cleanup check. No project was started. Keep this request for support; no weaker browser mode was selected.'
+                                            : 'The local runtime did not establish the required inner isolation. Inspect runner runtime policy and the daemon-host namespace policy. No project or weaker fallback was started.', 2);
+            }
+            value.stage = 'observed';
+            await persist(value);
+            output('runtime_observation', { ...summary, request_key: value.key, observation: facts }, 'Container isolation and isolated browser capture observed. No project, model call or simulation was started.');
+        }
+        finally {
+            if (value.container_id) {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 10000);
+                try {
+                    cleanupConfirmed = await cleanup(context, value, AbortSignal.any([controller.signal, ownership]));
+                    if (!cleanupConfirmed)
+                        output('runtime_cleanup_pending', { request_key: value.key }, 'Readiness cleanup is pending. Use the exact recovery command shown above.');
+                }
+                catch {
+                    output('runtime_cleanup_pending', { request_key: value.key }, 'Readiness cleanup is unconfirmed. Its journal was retained.');
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+        }
+        return { runtime, installed: true, isolation_observed: true, cleanup_confirmed: cleanupConfirmed, request_key: value.key };
+    });
+}