sealbridge 0.0.1 → 0.2.0

package/dist/packages/sandbox/dist/container.js

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+import { randomUUID } from 'node:crypto';
+import { execFile, spawn } from 'node:child_process';
+import { mkdtemp, writeFile, rm, chown } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runSandbox, sandboxWrapper, sanitizedEnvironment, terminateSubprocess } from './index.js';
+import { OCI_CONTAINER_BOUNDARY, subprocessSandboxBoundary } from './permission.js';
+export async function detectDockerRuntime(probe = (binary, args) => new Promise((resolve) => {
+    execFile(binary, args, {
+        timeout: 3000,
+        maxBuffer: 65536,
+        env: { PATH: '/usr/local/bin:/usr/bin:/bin', LANG: 'C.UTF-8' },
+    }, (error) => resolve(!error));
+})) {
+    for (const binary of ['podman', 'docker'])
+        if (await probe(binary, ['info']))
+            return binary;
+    return undefined;
+}
+/**
+ * OCI argv for untrusted code. Kernel isolation is `--network none`, a read-only
+ * root filesystem, `--cap-drop ALL`, and `--security-opt no-new-privileges`, plus
+ * PID and memory limits. Node's `--permission` model is not this boundary.
+ */
+export function containerArguments(directory, image = 'node:22-bookworm-slim', name) {
+    return [
+        'run',
+        ...(name ? ['--name', name] : []),
+        '--rm',
+        '--pull=never',
+        '--network',
+        'none',
+        '--read-only',
+        '--cap-drop',
+        'ALL',
+        '--security-opt',
+        'no-new-privileges',
+        '--pids-limit',
+        '64',
+        '--memory',
+        '128m',
+        '--cpus',
+        '1',
+        '--user',
+        `${process.getuid?.() || 65534}:${process.getgid?.() || 65534}`,
+        '--tmpfs',
+        '/tmp:rw,noexec,nosuid,size=16m',
+        '--mount',
+        `type=bind,src=${directory},dst=/work`,
+        '--workdir',
+        '/work',
+        '-i',
+        image,
+        'node',
+        '--no-addons',
+        '--disable-proto=throw',
+        '--max-old-space-size=64',
+        '/work/runner.cjs',
+    ];
+}
+export async function runContainerOrSubprocessSandbox(options) {
+    if (!Number.isSafeInteger(options.timeoutMs) ||
+        options.timeoutMs < 1 ||
+        options.timeoutMs > 604800000)
+        throw new Error('INVALID_TIMEOUT');
+    if (!['subprocess_restricted', 'oci_container'].includes(options.isolationLevel ?? 'subprocess_restricted'))
+        throw new Error('UNSUPPORTED_SANDBOX_POLICY');
+    const runtime = options.isolationLevel === 'oci_container'
+        ? options.runtime === undefined
+            ? await detectDockerRuntime(options.probe)
+            : options.runtime
+        : undefined;
+    if (!runtime)
+        return {
+            output: await runSandbox(options),
+            effectiveIsolationLevel: 'subprocess_restricted',
+            // Same flag choice `runSandbox` passes. Network stays open at the kernel.
+            sandboxBoundary: subprocessSandboxBoundary(),
+        };
+    const directory = await mkdtemp(join(tmpdir(), 'acp-oci-')), name = 'acp-' + randomUUID();
+    try {
+        if (process.getuid?.() === 0)
+            await chown(directory, 65534, 65534);
+        const bridge = `const send=m=>process.stdout.write(JSON.stringify(m)+'\\n');process.disconnect=()=>{process.stdin.destroy();};require('node:readline').createInterface({input:process.stdin}).on('line',l=>process.emit('message',JSON.parse(l)));\n`;
+        await writeFile(join(directory, 'runner.cjs'), bridge + sandboxWrapper.replaceAll('process.send(', 'send('));
+        await writeFile(join(directory, 'task.json'), JSON.stringify({
+            code: options.code,
+            input: options.input ?? null,
+            timeoutMs: options.timeoutMs,
+        }));
+        // An empty config avoids Docker CLI proxy defaults and registry credentials.
+        await writeFile(join(directory, 'config.json'), '{}');
+        const output = await new Promise((resolve, reject) => {
+            const environment = {
+                ...sanitizedEnvironment(directory),
+                PATH: '/usr/local/bin:/usr/bin:/bin',
+                DOCKER_CONFIG: directory,
+            };
+            const child = options.containerSpawn
+                ? options.containerSpawn(runtime, containerArguments(directory, options.image, name), {
+                    cwd: directory,
+                    env: environment,
+                })
+                : spawn(runtime, containerArguments(directory, options.image, name), {
+                    env: environment,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            child.stderr.resume();
+            let done = false, buffer = '', calls = 0;
+            let serial = Promise.resolve();
+            const finish = (error, value) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', abort);
+                terminateSubprocess(child);
+                error ? reject(error) : resolve(value ?? null);
+            };
+            const abort = () => finish(new Error('SANDBOX_HALTED'));
+            const timer = setTimeout(() => finish(new Error('SANDBOX_TIMEOUT')), options.timeoutMs);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            child.stdout.on('data', (chunk) => {
+                buffer += chunk.toString();
+                if (buffer.length > 1048576)
+                    return finish(new Error('SANDBOX_MESSAGE_LIMIT'));
+                let index;
+                while ((index = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 1);
+                    serial = serial
+                        .then(async () => {
+                        if (done)
+                            return;
+                        const m = JSON.parse(line);
+                        if (m.type === 'done')
+                            return finish(m.error ? new Error(m.error) : undefined, m.value);
+                        if (m.type !== 'tool' || ++calls > 10000)
+                            throw new Error('SANDBOX_PROTOCOL');
+                        let value = null;
+                        if (m.name === '$usage') {
+                            if (!options.onUsage)
+                                throw new Error('USAGE_ADAPTER_REQUIRED');
+                            options.onUsage(m.args.inputTokens, m.args.outputTokens);
+                        }
+                        else
+                            value = await options.onTool(m.name, m.args);
+                        if (!done)
+                            child.stdin.write(JSON.stringify({ id: m.id, value }) + '\n');
+                    })
+                        .catch((e) => finish(e instanceof Error ? e : new Error(String(e))));
+                }
+            });
+            child.on('error', (e) => finish(e));
+            child.stdin.on('error', () => { });
+            child.on('close', (code) => {
+                void serial.then(() => {
+                    if (!done)
+                        finish(new Error('CONTAINER_EXIT: ' + code));
+                });
+            });
+        });
+        return {
+            output,
+            effectiveIsolationLevel: 'oci_container',
+            sandboxBoundary: OCI_CONTAINER_BOUNDARY,
+        };
+    }
+    finally {
+        await new Promise((resolve) => execFile(runtime, ['rm', '-f', name], {
+            timeout: 3000,
+            env: {
+                ...sanitizedEnvironment(directory),
+                PATH: '/usr/local/bin:/usr/bin:/bin',
+                DOCKER_CONFIG: directory,
+            },
+        }, () => resolve()));
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+export class SandboxRunner {
+    run(options) {
+        return runContainerOrSubprocessSandbox(options);
+    }
+}
+//# sourceMappingURL=container.js.map

package/dist/packages/sandbox/dist/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"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"}

package/dist/packages/sandbox/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { Json } from '@acp/core';
+import type { NodePermissionProbe } from './permission.js';
+export type { NodePermissionFlag, NodePermissionProbe, ResolvedNodePermission, SandboxBoundaryMetadata, } from './permission.js';
+export { OCI_CONTAINER_BOUNDARY, detectNodePermissionFlag, prefersStableNodePermissionFlag, resolveNodePermissionArgs, subprocessSandboxBoundary, } from './permission.js';
+export interface SandboxOptions {
+    code: string;
+    input?: Json;
+    timeoutMs: number;
+    onTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    onUsage?: (inputTokens: number, outputTokens: number) => void;
+    signal?: AbortSignal;
+}
+export declare const sandboxWrapper: string;
+export declare function sanitizedEnvironment(directory: string): NodeJS.ProcessEnv;
+/**
+ * Argv after `process.execPath` for a `subprocess_restricted` child.
+ * Permission-model flags come from `resolveNodePermissionArgs`. `--no-addons`
+ * stays even when this Node binary supports neither permission flag.
+ */
+export declare function buildRestrictedSubprocessArgv(directory: string, entry: string, probe?: NodePermissionProbe): string[];
+/** SIGTERM, then SIGKILL if the child is still alive. `killed` is true after either signal. */
+export declare function terminateSubprocess(subprocess: {
+    exitCode: number | null;
+    kill: (signal?: NodeJS.Signals) => boolean;
+}): void;
+/**
+ * `subprocess_restricted` runner. Separate OS process, sanitized environment,
+ * scratch directory, timeout then SIGKILL, and an output byte cap. Node's
+ * permission model is applied when `detectNodePermissionFlag` finds a flag.
+ * `node:vm` inside the child is not a security mechanism, and the permission
+ * model does not block network syscalls. Untrusted code needs `oci_container`.
+ */
+export declare function runSandbox(options: SandboxOptions): Promise<Json>;
+export * from './container.js';

package/dist/packages/sandbox/dist/index.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+import { mkdtemp, realpath, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveNodePermissionArgs } from './permission.js';
+export { OCI_CONTAINER_BOUNDARY, detectNodePermissionFlag, prefersStableNodePermissionFlag, resolveNodePermissionArgs, subprocessSandboxBoundary, } from './permission.js';
+// The parent process is the only one that holds owner keys and tool handlers.
+// Task values cross that process boundary as JSON. Inside the child, `node:vm`
+// evaluates task source in a null-prototype context. Node.js documents that
+// `node:vm` is not a security mechanism: code that escapes the context runs as
+// this child. `--permission` / `--experimental-permission` can deny filesystem,
+// child-process, worker, and addon access. They do not deny network syscalls
+// (`fetch`, `node:net`, `node:http`, `node:https`, `node:dns`, `node:dgram`).
+// Deleting the Web globals below only hides those names in the wrapper.
+export const sandboxWrapper = String.raw `
+const vm = require('node:vm');
+const fs = require('node:fs');
+try { delete globalThis.fetch; } catch { /* name may be non-configurable */ }
+try { delete globalThis.WebSocket; } catch { /* name may be non-configurable */ }
+const config = JSON.parse(fs.readFileSync('task.json', 'utf8'));
+const context = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false }, microtaskMode: 'afterEvaluate' });
+const bootstrap = 'globalThis.queue=[]; globalThis.waiters=new Map(); globalThis.serial=0; globalThis.finished=false; globalThis.callTool=(name,args)=>new Promise((resolve,reject)=>{const id=++serial;waiters.set(id,{resolve,reject});queue.push({id,name,args});}); globalThis.reportUsage=(inputTokens,outputTokens)=>callTool("$usage",{inputTokens,outputTokens}); globalThis.input=JSON.parse(' + JSON.stringify(JSON.stringify(config.input)) + ');';
+vm.runInContext(bootstrap, context, { timeout: 100 });
+new vm.Script('(async()=>{'+config.code+'})().then(value=>{globalThis.result=JSON.stringify({value:value===undefined?null:value});globalThis.finished=true;},error=>{globalThis.result=JSON.stringify({error:String(error)});globalThis.finished=true;});').runInContext(context, { timeout: config.timeoutMs });
+const timer = setInterval(()=>{
+ try {
+   const queued=JSON.parse(vm.runInContext('JSON.stringify(queue.splice(0))',context,{timeout:100}));
+   for(const req of queued)process.send({type:'tool',...req});
+   if(vm.runInContext('finished',context,{timeout:100})){clearInterval(timer);process.send({type:'done',...JSON.parse(vm.runInContext('result',context,{timeout:100}))});process.disconnect();}
+ } catch(e){process.send({type:'done',error:String(e)});process.exit(1);}
+},5);
+process.on('message',msg=>{
+ try { const data=JSON.stringify(msg); vm.runInContext('{const r=JSON.parse('+JSON.stringify(data)+');const w=waiters.get(r.id);if(w){waiters.delete(r.id);r.error?w.reject(new Error(r.error)):w.resolve(r.value);}}',context,{timeout:100}); }
+ catch(e){process.send({type:'done',error:String(e)});process.exit(1);}
+});
+`;
+export function sanitizedEnvironment(directory) {
+    // Build an allowlist from scratch: NODE_OPTIONS, proxy auth, cloud credentials,
+    // provider keys, SSH sockets and inherited PATH never enter the worker.
+    return { LANG: 'C.UTF-8', TZ: 'UTC', HOME: directory, TMPDIR: directory };
+}
+/**
+ * Argv after `process.execPath` for a `subprocess_restricted` child.
+ * Permission-model flags come from `resolveNodePermissionArgs`. `--no-addons`
+ * stays even when this Node binary supports neither permission flag.
+ */
+export function buildRestrictedSubprocessArgv(directory, entry, probe) {
+    return [
+        ...resolveNodePermissionArgs(directory, probe).args,
+        '--no-addons',
+        '--disable-proto=throw',
+        '--max-old-space-size=64',
+        entry,
+    ];
+}
+/** SIGTERM, then SIGKILL if the child is still alive. `killed` is true after either signal. */
+export function terminateSubprocess(subprocess) {
+    if (subprocess.exitCode !== null)
+        return;
+    subprocess.kill('SIGTERM');
+    const timer = setTimeout(() => {
+        if (subprocess.exitCode === null)
+            subprocess.kill('SIGKILL');
+    }, 40);
+    timer.unref?.();
+}
+/**
+ * `subprocess_restricted` runner. Separate OS process, sanitized environment,
+ * scratch directory, timeout then SIGKILL, and an output byte cap. Node's
+ * permission model is applied when `detectNodePermissionFlag` finds a flag.
+ * `node:vm` inside the child is not a security mechanism, and the permission
+ * model does not block network syscalls. Untrusted code needs `oci_container`.
+ */
+export async function runSandbox(options) {
+    if (!Number.isSafeInteger(options.timeoutMs) ||
+        options.timeoutMs < 1 ||
+        options.timeoutMs > 604800000)
+        throw new Error('INVALID_TIMEOUT');
+    // macOS tmpdir() is /var/folders/..., a symlink to /private/var/folders/...
+    // Node's permission model realpath's the entry script and then stats '/var'
+    // unless --allow-fs-read already names the physical directory.
+    const directory = await realpath(await mkdtemp(join(tmpdir(), 'acp-task-')));
+    let child;
+    let exited = Promise.resolve();
+    try {
+        await writeFile(join(directory, 'runner.cjs'), sandboxWrapper, { mode: 0o600 });
+        await writeFile(join(directory, 'task.json'), JSON.stringify({
+            code: options.code,
+            input: options.input ?? null,
+            timeoutMs: options.timeoutMs,
+        }), { mode: 0o600 });
+        return await new Promise((resolve, reject) => {
+            const subprocess = spawn(process.execPath, buildRestrictedSubprocessArgv(directory, join(directory, 'runner.cjs')), {
+                cwd: directory,
+                env: sanitizedEnvironment(directory),
+                stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            });
+            child = subprocess;
+            // `close` means stdio and the process handle are gone, so Windows can release cwd.
+            exited = new Promise((resolveExit) => {
+                const finished = () => resolveExit();
+                subprocess.once('exit', finished);
+                subprocess.once('close', finished);
+            });
+            let done = false, requests = 0, stderr = '';
+            const finish = (error, result) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', abort);
+                terminateSubprocess(subprocess);
+                error ? reject(error) : resolve(result ?? null);
+            };
+            const abort = () => finish(new Error('SANDBOX_HALTED: ' + String(options.signal?.reason)));
+            const timer = setTimeout(() => finish(new Error('SANDBOX_TIMEOUT')), options.timeoutMs);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            subprocess.stderr?.on('data', (b) => {
+                stderr = (stderr + b.toString()).slice(-4096);
+            });
+            // Requests arrive from another OS process. The child has no tool handlers,
+            // capability counters, private keys or credentials, and cannot skip CapGuard.
+            let serial = Promise.resolve();
+            subprocess.on('message', (message) => {
+                serial = serial
+                    .then(async () => {
+                    if (done)
+                        return;
+                    const m = message;
+                    // Output byte cap for one IPC message from the child.
+                    if (JSON.stringify(m).length > 1048576)
+                        return finish(new Error('SANDBOX_MESSAGE_LIMIT'));
+                    if (m.type === 'done')
+                        return finish(m.error ? new Error(m.error) : undefined, m.value);
+                    if (m.type !== 'tool' || ++requests > 10000)
+                        return finish(new Error('SANDBOX_PROTOCOL'));
+                    try {
+                        let value = null;
+                        if (m.name === '$usage') {
+                            if (!options.onUsage)
+                                throw new Error('USAGE_ADAPTER_REQUIRED');
+                            options.onUsage(m.args.inputTokens, m.args.outputTokens);
+                        }
+                        else
+                            value = await options.onTool(m.name, m.args);
+                        if (!done && subprocess.connected)
+                            subprocess.send({ id: m.id, value });
+                    }
+                    catch (error) {
+                        finish(error instanceof Error ? error : new Error(String(error)));
+                    }
+                })
+                    .catch((e) => finish(e));
+            });
+            subprocess.on('error', (e) => finish(e));
+            subprocess.on('exit', (code) => {
+                if (!done)
+                    finish(new Error('SANDBOX_EXIT: ' + code + ' ' + stderr));
+            });
+        });
+    }
+    finally {
+        try {
+            if (child)
+                terminateSubprocess(child);
+            // Wait until the child has actually exited, then give Windows a short retry window.
+            await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 250))]);
+            await rm(directory, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+        }
+        catch {
+            // EBUSY, EPERM, and EACCES while deleting the temp dir must not replace the result.
+        }
+    }
+}
+export * from './container.js';
+//# sourceMappingURL=index.js.map

package/dist/packages/sandbox/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/packages/sandbox/dist/permission.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI spelling of Node's permission model.
+ * `--permission` is the stable flag on Node.js >= 22.13 and on Node.js 23+.
+ * Earlier Node.js 20 and 22 releases accept `--experimental-permission`.
+ * `--allow-fs-read` / `--allow-fs-write` are valid only together with one of these.
+ */
+export declare const NODE_PERMISSION_FLAGS: readonly ["--permission", "--experimental-permission"];
+export type NodePermissionFlag = (typeof NODE_PERMISSION_FLAGS)[number];
+/**
+ * What a sandbox run can honestly claim about Node's permission model.
+ * `kernelNetworkIsolated` is true only for `oci_container` (`--network none`).
+ * The permission model does not deny `fetch`, `node:net`, `node:http`,
+ * `node:https`, `node:dns`, or `node:dgram`.
+ * `permissionModelActive` means a permission flag was passed. It is false for
+ * `oci_container`, which uses the container runtime instead of that flag.
+ */
+export interface SandboxBoundaryMetadata {
+    nodePermissionFlag: NodePermissionFlag | null;
+    permissionModelActive: boolean;
+    kernelNetworkIsolated: boolean;
+}
+export interface NodePermissionProbe {
+    /** Flags the binary advertises. Defaults to `process.allowedNodeEnvironmentFlags`. */
+    flags?: Iterable<string>;
+    /** `process.versions.node`, with or without a leading `v`. */
+    nodeVersion?: string;
+}
+export interface ResolvedNodePermission {
+    flag: NodePermissionFlag | null;
+    /** Empty when neither permission flag is supported. Never contains `--allow-fs-*` alone. */
+    args: string[];
+    boundary: SandboxBoundaryMetadata;
+}
+/** Boundary recorded for Podman/Docker `--network none` runs. */
+export declare const OCI_CONTAINER_BOUNDARY: SandboxBoundaryMetadata;
+export declare function parseNodeVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/** True when the documented stable spelling is `--permission` (Node.js >= 22.13, or >= 23). */
+export declare function prefersStableNodePermissionFlag(nodeVersion: string): boolean;
+/**
+ * Chooses `--permission` or `--experimental-permission` for `process.execPath`.
+ * Returns null when `allowedNodeEnvironmentFlags` lists neither, so callers can
+ * start the child without `--allow-fs-*` and record `permissionModelActive: false`.
+ * Version selects the spelling when both flags are advertised. A binary that
+ * lists only one spelling uses that spelling.
+ */
+export declare function detectNodePermissionFlag(probe?: NodePermissionProbe): NodePermissionFlag | null;
+/** Subprocess claim. `kernelNetworkIsolated` stays false even when the flag is active. */
+export declare function subprocessSandboxBoundary(probe?: NodePermissionProbe): SandboxBoundaryMetadata;
+/**
+ * Permission-model argv for one scratch directory.
+ * `--allow-fs-read` and `--allow-fs-write` are omitted when no permission flag exists,
+ * because Node rejects them unless `--permission` or `--experimental-permission` is active.
+ */
+export declare function resolveNodePermissionArgs(directory: string, probe?: NodePermissionProbe): ResolvedNodePermission;

package/dist/packages/sandbox/dist/permission.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CLI spelling of Node's permission model.
+ * `--permission` is the stable flag on Node.js >= 22.13 and on Node.js 23+.
+ * Earlier Node.js 20 and 22 releases accept `--experimental-permission`.
+ * `--allow-fs-read` / `--allow-fs-write` are valid only together with one of these.
+ */
+export const NODE_PERMISSION_FLAGS = ['--permission', '--experimental-permission'];
+/** Boundary recorded for Podman/Docker `--network none` runs. */
+export const OCI_CONTAINER_BOUNDARY = {
+    nodePermissionFlag: null,
+    permissionModelActive: false,
+    kernelNetworkIsolated: true,
+};
+export function parseNodeVersion(version) {
+    const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(version.trim());
+    if (!match)
+        return { major: 0, minor: 0, patch: 0 };
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: match[3] ? Number(match[3]) : 0,
+    };
+}
+/** True when the documented stable spelling is `--permission` (Node.js >= 22.13, or >= 23). */
+export function prefersStableNodePermissionFlag(nodeVersion) {
+    const { major, minor } = parseNodeVersion(nodeVersion);
+    return major > 22 || (major === 22 && minor >= 13);
+}
+function advertisedFlags(probe) {
+    return new Set(probe?.flags ?? process.allowedNodeEnvironmentFlags);
+}
+/**
+ * Chooses `--permission` or `--experimental-permission` for `process.execPath`.
+ * Returns null when `allowedNodeEnvironmentFlags` lists neither, so callers can
+ * start the child without `--allow-fs-*` and record `permissionModelActive: false`.
+ * Version selects the spelling when both flags are advertised. A binary that
+ * lists only one spelling uses that spelling.
+ */
+export function detectNodePermissionFlag(probe) {
+    const flags = advertisedFlags(probe);
+    const version = probe?.nodeVersion ?? process.versions.node;
+    const hasStable = flags.has('--permission');
+    const hasExperimental = flags.has('--experimental-permission');
+    if (prefersStableNodePermissionFlag(version) && hasStable)
+        return '--permission';
+    if (hasExperimental)
+        return '--experimental-permission';
+    if (hasStable)
+        return '--permission';
+    return null;
+}
+/** Subprocess claim. `kernelNetworkIsolated` stays false even when the flag is active. */
+export function subprocessSandboxBoundary(probe) {
+    const flag = detectNodePermissionFlag(probe);
+    return {
+        nodePermissionFlag: flag,
+        permissionModelActive: flag !== null,
+        kernelNetworkIsolated: false,
+    };
+}
+function assertScratchDirectory(directory) {
+    // A comma is a permission-model path separator, so it would widen the allowlist.
+    if (directory.length === 0 ||
+        directory === '/' ||
+        directory.includes(',') ||
+        directory.includes('\0'))
+        throw new Error('INVALID_SANDBOX_DIRECTORY');
+}
+/**
+ * Permission-model argv for one scratch directory.
+ * `--allow-fs-read` and `--allow-fs-write` are omitted when no permission flag exists,
+ * because Node rejects them unless `--permission` or `--experimental-permission` is active.
+ */
+export function resolveNodePermissionArgs(directory, probe) {
+    const boundary = subprocessSandboxBoundary(probe);
+    if (!boundary.nodePermissionFlag)
+        return { flag: null, args: [], boundary };
+    assertScratchDirectory(directory);
+    return {
+        flag: boundary.nodePermissionFlag,
+        args: [
+            boundary.nodePermissionFlag,
+            '--allow-fs-read=' + directory,
+            '--allow-fs-write=' + directory,
+        ],
+        boundary,
+    };
+}
+//# sourceMappingURL=permission.js.map

package/dist/packages/sandbox/dist/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"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"}