@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.13

package/dist/codex-permissions.mjs

@@ -0,0 +1,590 @@
+// @ts-check
+
+import { spawn } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {JsonObject & { version: number, writableRoots: string[], profile?: string }} PermissionEnvelope */
+/** @typedef {JsonObject & { additionalRoots: string[], nativeArgs: string[], effectiveCwd: string, profile?: string|undefined, server: JsonObject }} LaunchPlan */
+/** @typedef {import('node:child_process').ChildProcess} OwnedChild */
+/** @typedef {{ id?: string|number, result?: JsonObject, error?: unknown }} JsonRpcResponse */
+
+export const CODEX_LAUNCH_ENVELOPE = 'AIBRAIN_CODEX_LAUNCH_ENVELOPE';
+export const CODEX_APP_SERVER_PROFILE = 'CODEX_APP_SERVER_PROFILE';
+export const CODEX_MONITOR_CWD = 'CODEX_MONITOR_CWD';
+
+const ENVELOPE_VERSION = 1;
+const MAX_ROOTS = 32;
+const MAX_PATH_BYTES = 4096;
+const MAX_ENVELOPE_BYTES = 16 * 1024;
+const PREFLIGHT_TIMEOUT_MS = 5_000;
+const PREFLIGHT_FRAME_BYTES = 2 * 1024 * 1024;
+const PROFILE_PATTERN = /^[A-Za-z0-9._-]{1,64}$/u;
+const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
+const APPROVAL_POLICIES = new Set(['untrusted', 'on-request', 'never']);
+const REVIEWERS = new Set(['user', 'auto_review', 'guardian_subagent']);
+const CONFIG_KEYS = new Set([
+  'sandbox_mode',
+  'approval_policy',
+  'approvals_reviewer',
+  'apps._default.approvals_reviewer',
+  'sandbox_workspace_write.network_access',
+]);
+const ENVELOPE_KEYS = new Set([
+  'version',
+  'writableRoots',
+  'profile',
+  'sandboxMode',
+  'approvalPolicy',
+  'approvalsReviewer',
+  'appsDefaultApprovalsReviewer',
+  'networkAccess',
+]);
+const VALUE_OPTIONS = new Set([
+  '--add-dir',
+  '--sandbox',
+  '-s',
+  '--ask-for-approval',
+  '-a',
+  '--profile',
+  '-p',
+  '-c',
+  '--config',
+]);
+
+/** @param {string} code @returns {never} */
+function fail(code) {
+  throw new Error(`codex_permissions_${code}`);
+}
+
+/** @param {string} argument */
+function optionName(argument) {
+  return argument.split('=', 1)[0];
+}
+
+/** @param {string} value @param {string} key */
+function parseBoolean(value, key) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  fail(`config_value_invalid:${key}`);
+}
+
+/** @param {string} value @param {string} key */
+function parseTomlString(value, key) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    try {
+      const parsed = JSON.parse(value);
+      if (typeof parsed === 'string') return parsed;
+    } catch {
+      // Fall through to the bounded error below.
+    }
+  }
+  if (/^[A-Za-z0-9._-]+$/u.test(value)) return value;
+  fail(`config_value_invalid:${key}`);
+}
+
+/** @param {string} key @param {string} value */
+function assertValue(key, value) {
+  if (key === 'sandbox_mode') {
+    const parsed = parseTomlString(value, key);
+    if (!SANDBOX_MODES.has(parsed)) fail('sandbox_invalid');
+    return parsed;
+  }
+  if (key === 'approval_policy') {
+    const parsed = parseTomlString(value, key);
+    if (!APPROVAL_POLICIES.has(parsed)) fail('approval_invalid');
+    return parsed;
+  }
+  if (key === 'approvals_reviewer' || key === 'apps._default.approvals_reviewer') {
+    const parsed = parseTomlString(value, key);
+    if (!REVIEWERS.has(parsed)) fail('reviewer_invalid');
+    return parsed;
+  }
+  if (key === 'sandbox_workspace_write.network_access') return parseBoolean(value, key);
+  fail(`config_key_unsupported:${key}`);
+}
+
+/** @param {JsonObject} target @param {string} key @param {string} value */
+function setPermission(target, key, value) {
+  const parsed = assertValue(key, value);
+  const field =
+    key === 'sandbox_mode'
+      ? 'sandboxMode'
+      : key === 'approval_policy'
+        ? 'approvalPolicy'
+        : key === 'approvals_reviewer'
+          ? 'approvalsReviewer'
+          : key === 'apps._default.approvals_reviewer'
+            ? 'appsDefaultApprovalsReviewer'
+            : 'networkAccess';
+  if (target[field] !== undefined && target[field] !== parsed) fail(`permission_conflict:${key}`);
+  target[field] = parsed;
+}
+
+/** @param {string[]} args @param {number} index @param {string} argument */
+function consumeValue(args, index, argument) {
+  const value = args[index + 1];
+  if (value === undefined || value === '' || value === '--') fail(`value_required:${argument}`);
+  return value;
+}
+
+/** @param {string} raw @param {JsonObject} target */
+function parseConfigArgument(raw, target) {
+  const equals = raw.indexOf('=');
+  if (equals <= 0) fail('config_value_required');
+  const key = raw.slice(0, equals);
+  const value = raw.slice(equals + 1);
+  if (key === 'sandbox_workspace_write.writable_roots') fail('writable_roots_override_unsupported');
+  if (!CONFIG_KEYS.has(key)) return false;
+  setPermission(target, key, value);
+  return true;
+}
+
+/** @param {string} value @param {string} cwd */
+async function normalizeAdditionalRoot(value, cwd) {
+  if (value.length === 0 || value.includes('\0')) fail('root_invalid');
+  const path = resolve(cwd, value);
+  if (Buffer.byteLength(path, 'utf8') > MAX_PATH_BYTES) fail('root_too_long');
+  const info = await lstat(path).catch(() => null);
+  if (info === null) fail('root_missing');
+  if (info.isSymbolicLink()) fail('root_symlink_rejected');
+  if (!info.isDirectory()) fail('root_not_directory');
+  return path;
+}
+
+/** @param {string[]} values */
+function deduplicate(values) {
+  return [...new Set(values)];
+}
+
+/**
+ * Parse native arguments while preserving all ordinary terminal arguments.
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+export async function parseCodexLaunchArgs(args, cwd) {
+  let effectiveCwd = cwd;
+  let cwdValue;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--') break;
+    const name = optionName(argument);
+    if (name !== '--cd' && name !== '-C') {
+      if (!argument.includes('=') && VALUE_OPTIONS.has(name)) {
+        if (index + 1 >= args.length || args[index + 1] === '--')
+          fail(`value_required:${argument}`);
+        index += 1;
+      }
+      continue;
+    }
+    const value = argument.includes('=')
+      ? argument.slice(argument.indexOf('=') + 1)
+      : consumeValue(args, index, argument);
+    if (!argument.includes('=')) index += 1;
+    const nextCwd = resolve(cwd, value);
+    if (cwdValue !== undefined && nextCwd !== cwdValue) fail('cwd_conflict');
+    cwdValue = nextCwd;
+  }
+  if (cwdValue !== undefined) {
+    const info = await lstat(cwdValue).catch(() => null);
+    if (info === null || info.isSymbolicLink() || !info.isDirectory()) fail('cwd_invalid');
+    effectiveCwd = cwdValue;
+  }
+  /** @type {JsonObject} */
+  const server = {};
+  const additionalRoots = [];
+  const nativeArgs = [];
+  let profile;
+  let afterTerminator = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (afterTerminator) {
+      nativeArgs.push(argument);
+      continue;
+    }
+    if (argument === '--') {
+      afterTerminator = true;
+      nativeArgs.push(argument);
+      continue;
+    }
+    const name = optionName(argument);
+    if (name === '--add-dir' || name === '--add-dir=') {
+      const value = argument.startsWith('--add-dir=')
+        ? argument.slice('--add-dir='.length)
+        : consumeValue(args, index, argument);
+      if (!argument.startsWith('--add-dir=')) index += 1;
+      additionalRoots.push(await normalizeAdditionalRoot(value, effectiveCwd));
+      continue;
+    }
+    if (name === '--sandbox' || name === '-s') {
+      const value = argument.includes('=')
+        ? argument.slice(argument.indexOf('=') + 1)
+        : consumeValue(args, index, argument);
+      if (!argument.includes('=')) index += 1;
+      if (!SANDBOX_MODES.has(value)) fail('sandbox_invalid');
+      setPermission(server, 'sandbox_mode', JSON.stringify(value));
+      continue;
+    }
+    if (name === '--ask-for-approval' || name === '-a') {
+      const value = argument.includes('=')
+        ? argument.slice(argument.indexOf('=') + 1)
+        : consumeValue(args, index, argument);
+      if (!argument.includes('=')) index += 1;
+      if (!APPROVAL_POLICIES.has(value)) fail('approval_invalid');
+      setPermission(server, 'approval_policy', JSON.stringify(value));
+      continue;
+    }
+    if (name === '--profile' || name === '-p') {
+      const value = argument.includes('=')
+        ? argument.slice(argument.indexOf('=') + 1)
+        : consumeValue(args, index, argument);
+      if (!argument.includes('=')) index += 1;
+      if (!PROFILE_PATTERN.test(value)) fail('profile_invalid');
+      if (profile !== undefined && profile !== value) fail('profile_conflict');
+      profile = value;
+      nativeArgs.push(argument);
+      if (!argument.includes('=')) nativeArgs.push(value);
+      continue;
+    }
+    if (name === '--cd' || name === '-C') {
+      const value = argument.includes('=')
+        ? argument.slice(argument.indexOf('=') + 1)
+        : consumeValue(args, index, argument);
+      if (!argument.includes('=')) index += 1;
+      nativeArgs.push(argument);
+      if (!argument.includes('=')) nativeArgs.push(value);
+      continue;
+    }
+    if (name === '-c' || name === '--config') {
+      const raw = argument.includes('=')
+        ? argument.slice(argument.indexOf('=') + 1)
+        : consumeValue(args, index, argument);
+      if (!argument.includes('=')) index += 1;
+      if (parseConfigArgument(raw, server)) continue;
+      nativeArgs.push(argument);
+      if (!argument.includes('=')) nativeArgs.push(raw);
+      continue;
+    }
+    if (argument.startsWith('--config=')) {
+      if (parseConfigArgument(argument.slice('--config='.length), server)) continue;
+    }
+    nativeArgs.push(argument);
+  }
+  const roots = deduplicate(additionalRoots);
+  if (roots.length > MAX_ROOTS) fail('too_many_roots');
+  return {
+    nativeArgs,
+    effectiveCwd,
+    profile,
+    additionalRoots: roots,
+    server,
+  };
+}
+
+/** @param {string|undefined} profile */
+function validateProfile(profile) {
+  if (profile !== undefined && !PROFILE_PATTERN.test(profile)) fail('profile_invalid');
+}
+
+/** @param {unknown} value @returns {PermissionEnvelope} */
+function validateEnvelope(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) fail('envelope_invalid');
+  const record = /** @type {JsonObject} */ (value);
+  if (Object.keys(record).some((key) => !ENVELOPE_KEYS.has(key))) fail('envelope_invalid');
+  if (record.version !== ENVELOPE_VERSION || !Array.isArray(record.writableRoots))
+    fail('envelope_invalid');
+  const writableRoots = /** @type {unknown[]} */ (record.writableRoots);
+  if (
+    writableRoots.length > MAX_ROOTS ||
+    writableRoots.some(
+      (path) =>
+        typeof path !== 'string' ||
+        path.includes('\0') ||
+        !isAbsolute(path) ||
+        Buffer.byteLength(path, 'utf8') > MAX_PATH_BYTES,
+    )
+  )
+    fail('envelope_invalid');
+  if (record.profile !== undefined && typeof record.profile !== 'string') fail('envelope_invalid');
+  validateProfile(record.profile === undefined ? undefined : String(record.profile));
+  const settings = /** @type {Record<string, unknown>} */ (record);
+  for (const [key, expected] of /** @type {[string, Set<string>][]} */ ([
+    ['sandboxMode', SANDBOX_MODES],
+    ['approvalPolicy', APPROVAL_POLICIES],
+    ['approvalsReviewer', REVIEWERS],
+    ['appsDefaultApprovalsReviewer', REVIEWERS],
+  ])) {
+    if (
+      settings[key] !== undefined &&
+      (typeof settings[key] !== 'string' || !expected.has(settings[key]))
+    )
+      fail('envelope_invalid');
+  }
+  if (settings.networkAccess !== undefined && typeof settings.networkAccess !== 'boolean')
+    fail('envelope_invalid');
+  return /** @type {PermissionEnvelope} */ (
+    Object.freeze({
+      ...record,
+      writableRoots: [...deduplicate(writableRoots.filter((path) => typeof path === 'string'))],
+    })
+  );
+}
+
+/** @param {string|undefined} raw */
+export function parseCodexLaunchEnvelope(raw) {
+  if (raw === undefined || raw === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_ENVELOPE_BYTES) fail('envelope_too_large');
+  try {
+    return validateEnvelope(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('codex_permissions_')) throw error;
+    fail('envelope_invalid');
+  }
+}
+
+/** @param {string} value */
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+/** @param {string[]} values */
+function tomlArray(values) {
+  return `[${values.map(tomlString).join(',')}]`;
+}
+
+/** @param {PermissionEnvelope} envelope */
+export function ownedAppServerConfigArgs(envelope) {
+  const checked = validateEnvelope(envelope);
+  const args = [];
+  if (checked.sandboxMode !== undefined)
+    args.push('-c', `sandbox_mode=${tomlString(String(checked.sandboxMode))}`);
+  if (checked.approvalPolicy !== undefined)
+    args.push('-c', `approval_policy=${tomlString(String(checked.approvalPolicy))}`);
+  if (checked.approvalsReviewer !== undefined)
+    args.push('-c', `approvals_reviewer=${tomlString(String(checked.approvalsReviewer))}`);
+  if (checked.appsDefaultApprovalsReviewer !== undefined)
+    args.push(
+      '-c',
+      `apps._default.approvals_reviewer=${tomlString(String(checked.appsDefaultApprovalsReviewer))}`,
+    );
+  if (checked.networkAccess !== undefined)
+    args.push(
+      '-c',
+      `sandbox_workspace_write.network_access=${checked.networkAccess ? 'true' : 'false'}`,
+    );
+  if (checked.writableRoots.length > 0)
+    args.push('-c', `sandbox_workspace_write.writable_roots=${tomlArray(checked.writableRoots)}`);
+  return args;
+}
+
+/** @param {NodeJS.ProcessEnv} environment */
+function childEnvironment(environment) {
+  const copy = { ...environment };
+  delete copy[CODEX_LAUNCH_ENVELOPE];
+  delete copy[CODEX_APP_SERVER_PROFILE];
+  delete copy.JEV_API_KEY;
+  delete copy.TYPESAFE_API_KEY;
+  return copy;
+}
+
+/** @param {OwnedChild} child @returns {Promise<void>} */
+function stopChild(child) {
+  /** @param {NodeJS.Signals} signal */
+  const signalGroup = (signal) => {
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch {
+      // The owned process may already have exited; the group still gets a bounded attempt.
+    }
+  };
+  signalGroup('SIGTERM');
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signalGroup('SIGKILL');
+      resolvePromise();
+    };
+    const timer = setTimeout(finish, 500);
+    child.once('exit', finish);
+  });
+}
+
+/** @param {OwnedChild} child @param {string|number} requestId @returns {Promise<JsonRpcResponse>} */
+function waitForResponse(child, requestId) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    let buffer = Buffer.alloc(0);
+    /** @param {Error|null} error @param {JsonRpcResponse} [value] */
+    const finish = (error, value = {}) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout?.removeListener('data', onData);
+      child.stdout?.removeListener('error', onError);
+      child.removeListener('exit', onExit);
+      child.removeListener('error', onChildError);
+      child.stdin?.removeListener('error', onStdinError);
+      if (error) rejectPromise(error);
+      else resolvePromise(value);
+    };
+    const onError = () => finish(new Error('codex_permissions_preflight_failed'));
+    const onChildError = () => finish(new Error('codex_permissions_preflight_failed'));
+    const onStdinError = () => finish(new Error('codex_permissions_preflight_failed'));
+    /** @param {number|null} code */
+    const onExit = (code) => {
+      if (code !== null) finish(new Error('codex_permissions_preflight_failed'));
+    };
+    /** @param {Buffer|string} chunk */
+    const onData = (chunk) => {
+      buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+      if (buffer.length > PREFLIGHT_FRAME_BYTES) {
+        finish(new Error('codex_permissions_preflight_frame_limit'));
+        return;
+      }
+      while (true) {
+        const newline = buffer.indexOf(10);
+        if (newline < 0) return;
+        const line = buffer.subarray(0, newline);
+        buffer = buffer.subarray(newline + 1);
+        let message;
+        try {
+          message = JSON.parse(line.toString('utf8'));
+        } catch {
+          continue;
+        }
+        if (message?.id === requestId) {
+          finish(null, message);
+          return;
+        }
+      }
+    };
+    const timer = setTimeout(
+      () => finish(new Error('codex_permissions_preflight_timeout')),
+      PREFLIGHT_TIMEOUT_MS,
+    );
+    child.stdout?.on('data', onData);
+    child.stdout?.once('error', onError);
+    child.once('exit', onExit);
+    child.once('error', onChildError);
+    child.stdin?.once('error', onStdinError);
+  });
+}
+
+/** @param {OwnedChild} child @param {number} id @param {string} method @param {JsonObject} params */
+async function request(child, id, method, params) {
+  const stdin = /** @type {import('node:stream').Writable} */ (child.stdin);
+  if (stdin.destroyed || child.exitCode !== null) fail('preflight_failed');
+  const responsePromise = waitForResponse(child, id);
+  try {
+    stdin.write(`${JSON.stringify({ id, method, params })}\n`);
+  } catch {
+    await stopChild(child);
+    await responsePromise.catch(() => undefined);
+    fail('preflight_failed');
+  }
+  const message = await responsePromise;
+  if (
+    message.error !== undefined ||
+    message.result === undefined ||
+    message.result === null ||
+    typeof message.result !== 'object' ||
+    Array.isArray(message.result)
+  )
+    fail('preflight_response_invalid');
+  return message.result;
+}
+
+/** @param {string} executable @param {string} cwd @param {string|undefined} profile @param {NodeJS.ProcessEnv} environment */
+export async function readEffectiveWritableRoots(executable, cwd, profile, environment) {
+  validateProfile(profile);
+  const args = [];
+  if (profile !== undefined) args.push('--profile', profile);
+  args.push('app-server', '--listen', 'stdio://');
+  const child = spawn(executable, args, {
+    cwd,
+    env: childEnvironment(environment),
+    stdio: ['pipe', 'pipe', 'ignore'],
+    detached: process.platform !== 'win32',
+  });
+  let cancelled = false;
+  const cancel = () => {
+    cancelled = true;
+    void stopChild(child);
+  };
+  process.once('SIGINT', cancel);
+  process.once('SIGTERM', cancel);
+  process.once('SIGHUP', cancel);
+  try {
+    await request(child, 0, 'initialize', {
+      clientInfo: { name: 'aibrain-preflight', version: '1' },
+      capabilities: { experimentalApi: true },
+    });
+    const stdin = /** @type {import('node:stream').Writable} */ (child.stdin);
+    if (cancelled) fail('preflight_cancelled');
+    try {
+      stdin.write(`${JSON.stringify({ method: 'initialized' })}\n`);
+    } catch {
+      fail('preflight_failed');
+    }
+    const result = await request(child, 1, 'config/read', { cwd, includeLayers: true });
+    const rawConfig = result.config;
+    if (
+      rawConfig === undefined ||
+      rawConfig === null ||
+      typeof rawConfig !== 'object' ||
+      Array.isArray(rawConfig)
+    )
+      fail('preflight_roots_unavailable');
+    const config = /** @type {JsonObject} */ (rawConfig);
+    const rawSandbox = config.sandbox_workspace_write;
+    if (cancelled) fail('preflight_cancelled');
+    if (rawSandbox === undefined || rawSandbox === null) return [];
+    if (typeof rawSandbox !== 'object' || Array.isArray(rawSandbox))
+      fail('preflight_roots_unavailable');
+    const sandbox = /** @type {JsonObject} */ (rawSandbox);
+    const roots = sandbox.writable_roots;
+    if (cancelled) fail('preflight_cancelled');
+    if (roots === undefined || roots === null) return [];
+    if (
+      !Array.isArray(roots) ||
+      roots.some((path) => typeof path !== 'string' || !isAbsolute(path))
+    )
+      fail('preflight_roots_unavailable');
+    if (cancelled) fail('preflight_cancelled');
+    return deduplicate(roots);
+  } finally {
+    process.removeListener('SIGINT', cancel);
+    process.removeListener('SIGTERM', cancel);
+    process.removeListener('SIGHUP', cancel);
+    await stopChild(child);
+  }
+}
+
+/** @param {LaunchPlan} plan @param {string[]} configuredRoots */
+export function makeCodexLaunchEnvelope(plan, configuredRoots) {
+  const roots = deduplicate([...configuredRoots, ...plan.additionalRoots]);
+  if (roots.length > MAX_ROOTS) fail('too_many_roots');
+  const envelope = {
+    version: ENVELOPE_VERSION,
+    writableRoots: roots,
+    profile: plan.profile,
+    ...plan.server,
+  };
+  const checked = validateEnvelope(envelope);
+  if (Buffer.byteLength(JSON.stringify(checked), 'utf8') > MAX_ENVELOPE_BYTES)
+    fail('envelope_too_large');
+  return checked;
+}
+
+export const codexPermissionInternals = {
+  MAX_ROOTS,
+  MAX_PATH_BYTES,
+  MAX_ENVELOPE_BYTES,
+  CONFIG_KEYS,
+  validateEnvelope,
+};