evolcore 0.0.1 → 0.0.2

package/dist/core/permission/ec-command-parser.js

@@ -0,0 +1,347 @@
+const DEFAULT_HEAD_LINES = 10;
+const MAX_HEAD_LINES = 10_000;
+const SHELL_UNQUOTED_META = new Set([
+    ';', '&', '|', '`', '<', '>', '$', '(', ')', '*', '?', '[', ']', '{', '}', '#',
+]);
+const AMBIGUOUS_FILE_PATH_RE = /[\0\r\n$`*?\[\]{}<>|;&]/;
+const EVOLCORE_COMMAND_POSITION_RE = /(?:^|[;&|()`])\s*ec(?=\s|[;&|()<>`]|$)/i;
+function trimShellSpacing(value) {
+    return value.replace(/^[ \t]+|[ \t]+$/g, '');
+}
+function isShellSpacing(value) {
+    return value === ' ' || value === '\t';
+}
+/**
+ * Parse the deliberately small shell subset accepted by the privileged EC
+ * command path. The returned argv must describe one literal invocation: no
+ * expansion, glob, pipeline, command substitution, redirection, or comment.
+ * Anything outside this subset is never granted the privileged EC path.
+ */
+export function parseLiteralShellArgv(command) {
+    const input = trimShellSpacing(command);
+    if (!input || input.includes('\0'))
+        return null;
+    const argv = [];
+    let token = '';
+    let tokenStarted = false;
+    let quote = null;
+    const finishToken = () => {
+        if (!tokenStarted)
+            return;
+        argv.push(token);
+        token = '';
+        tokenStarted = false;
+    };
+    for (let index = 0; index < input.length; index++) {
+        const char = input[index];
+        if (quote === 'single') {
+            if (char === "'")
+                quote = null;
+            else
+                token += char;
+            continue;
+        }
+        if (quote === 'double') {
+            if (char === '"') {
+                quote = null;
+                continue;
+            }
+            if (char === '$' || char === '`')
+                return null;
+            if (char === '\\') {
+                const next = input[++index];
+                if (next === undefined || next === '\r' || next === '\n')
+                    return null;
+                if (next === '$' || next === '`')
+                    return null;
+                token += ['"', '\\'].includes(next) ? next : `\\${next}`;
+                continue;
+            }
+            token += char;
+            continue;
+        }
+        // A physical newline is literal data only while a quote is open. Outside
+        // quotes it can start another shell command and must remain fail-closed.
+        if (char === ' ' || char === '\t') {
+            finishToken();
+            continue;
+        }
+        // Shell token separators are ASCII space/tab. JavaScript `\s` also
+        // includes NBSP, line/paragraph separators, VT and FF, which the shell
+        // keeps inside the executable name; accepting those would misclassify a
+        // different executable as `ec`.
+        if (char === '\r' || char === '\n' || /\s/u.test(char) || char.charCodeAt(0) < 0x20 || char === '\x7f')
+            return null;
+        if (char === "'") {
+            tokenStarted = true;
+            quote = 'single';
+            continue;
+        }
+        if (char === '"') {
+            tokenStarted = true;
+            quote = 'double';
+            continue;
+        }
+        if (char === '\\') {
+            const next = input[++index];
+            if (next === undefined || next === '\r' || next === '\n')
+                return null;
+            tokenStarted = true;
+            token += next;
+            continue;
+        }
+        // `#` starts a shell comment only at the beginning of a word. Channel
+        // peer keys such as `aun#alice` are ordinary literal arguments.
+        if ((SHELL_UNQUOTED_META.has(char) && (char !== '#' || !tokenStarted))
+            || (char === '~' && !tokenStarted))
+            return null;
+        tokenStarted = true;
+        token += char;
+    }
+    if (quote)
+        return null;
+    finishToken();
+    return argv.length > 0 ? argv : null;
+}
+function scanBoundedOutputOperators(command) {
+    const operators = [];
+    let quote = null;
+    for (let index = 0; index < command.length; index++) {
+        const char = command[index];
+        if (quote === 'single') {
+            if (char === "'")
+                quote = null;
+            continue;
+        }
+        if (quote === 'double') {
+            if (char === '"') {
+                quote = null;
+                continue;
+            }
+            if (char === '$' || char === '`')
+                return null;
+            if (char === '\\') {
+                const next = command[++index];
+                if (next === undefined || next === '\r' || next === '\n' || next === '$' || next === '`')
+                    return null;
+            }
+            continue;
+        }
+        if (char === "'") {
+            quote = 'single';
+            continue;
+        }
+        if (char === '"') {
+            quote = 'double';
+            continue;
+        }
+        if (char === '\\') {
+            if (command[++index] === undefined)
+                return null;
+            continue;
+        }
+        if (command.startsWith('2>&1', index)) {
+            const before = command[index - 1];
+            const after = command[index + 4];
+            if ((before === undefined || isShellSpacing(before))
+                && (after === undefined || isShellSpacing(after) || after === '|' || after === '>')) {
+                operators.push({ kind: 'merge-stderr', start: index, end: index + 4 });
+                index += 3;
+                continue;
+            }
+            return null;
+        }
+        if (char === '|') {
+            if (command[index + 1] === '|')
+                return null;
+            operators.push({ kind: 'pipe', start: index, end: index + 1 });
+            continue;
+        }
+        if (char === '>') {
+            if (command[index + 1] === '>')
+                return null;
+            operators.push({ kind: 'redirect', start: index, end: index + 1 });
+            continue;
+        }
+        if (char === '$' || char === '`' || char === ';' || char === '&' || char === '<'
+            || char === '(' || char === ')' || char === '*' || char === '?'
+            || char === '[' || char === ']' || char === '{' || char === '}'
+            || char === '\0' || char === '\r' || char === '\n')
+            return null;
+    }
+    return quote ? null : operators;
+}
+function parseHeadLines(segment) {
+    const argv = parseLiteralShellArgv(segment);
+    if (!argv || (argv[0] !== 'head' && argv[0] !== '/usr/bin/head'))
+        return null;
+    let value;
+    if (argv.length === 1)
+        value = String(DEFAULT_HEAD_LINES);
+    else if (argv.length === 2 && /^-\d+$/.test(argv[1]))
+        value = argv[1].slice(1);
+    else if (argv.length === 3 && argv[1] === '-n' && /^\d+$/.test(argv[2]))
+        value = argv[2];
+    else
+        return null;
+    const lines = Number(value);
+    return Number.isSafeInteger(lines) && lines >= 1 && lines <= MAX_HEAD_LINES ? lines : null;
+}
+/**
+ * Parse the only shell wrapper allowed around a privileged literal process:
+ * optional stderr merge, one bounded `head`, and one create-only output path.
+ */
+export function parseBoundedOutputShellCommand(command) {
+    const input = trimShellSpacing(command);
+    if (!input)
+        return null;
+    const operators = scanBoundedOutputOperators(input);
+    if (!operators || operators.length === 0)
+        return null;
+    const pattern = operators.map(operator => operator.kind).join(',');
+    if (![
+        'merge-stderr',
+        'pipe',
+        'pipe,redirect',
+        'merge-stderr,pipe',
+        'merge-stderr,pipe,redirect',
+        'redirect',
+    ].includes(pattern))
+        return null;
+    const first = operators[0];
+    const sourceText = trimShellSpacing(input.slice(0, first.start));
+    const argv = parseLiteralShellArgv(sourceText);
+    if (!argv)
+        return null;
+    let mergeStderr = false;
+    let pipe;
+    let redirect;
+    if (first.kind === 'merge-stderr') {
+        mergeStderr = true;
+        if (operators.length === 1)
+            return { argv, mergeStderr };
+        pipe = operators[1];
+        if (!pipe || pipe.kind !== 'pipe')
+            return null;
+        if (trimShellSpacing(input.slice(first.end, pipe.start)))
+            return null;
+        redirect = operators[2];
+    }
+    else if (first.kind === 'pipe') {
+        pipe = first;
+        redirect = operators[1];
+    }
+    else {
+        redirect = first;
+    }
+    let headLines;
+    if (pipe) {
+        const headEnd = redirect?.start ?? input.length;
+        const parsedLines = parseHeadLines(trimShellSpacing(input.slice(pipe.end, headEnd)));
+        if (parsedLines === null)
+            return null;
+        headLines = parsedLines;
+    }
+    let outputPath;
+    if (redirect) {
+        const outputArgv = parseLiteralShellArgv(trimShellSpacing(input.slice(redirect.end)));
+        if (!outputArgv || outputArgv.length !== 1)
+            return null;
+        outputPath = outputArgv[0];
+    }
+    return { argv, mergeStderr, ...(headLines ? { headLines } : {}), ...(outputPath ? { outputPath } : {}) };
+}
+/**
+ * Classify only the shell boundary around an EC process invocation. Runner
+ * policy must not interpret EC subcommands or arguments: a single literal
+ * invocation may leave the sandbox, while shell composition may not.
+ */
+export function classifyEvolcoreShellCommand(command) {
+    const literalArgv = parseLiteralShellArgv(command);
+    if (literalArgv) {
+        return literalArgv[0] === 'ec'
+            ? { kind: 'literal' }
+            : { kind: 'none' };
+    }
+    const boundedOutput = parseBoundedOutputShellCommand(command);
+    if (boundedOutput && boundedOutput.argv[0] === 'ec') {
+        return { kind: 'bounded-output', command: boundedOutput };
+    }
+    return EVOLCORE_COMMAND_POSITION_RE.test(command)
+        ? { kind: 'composite' }
+        : { kind: 'none' };
+}
+function isDeterministicFilePath(value) {
+    return !!value
+        && value === value.trim()
+        && !value.startsWith('--')
+        && !value.startsWith('~')
+        && !AMBIGUOUS_FILE_PATH_RE.test(value);
+}
+function findSingleFileOption(argv, startIndex) {
+    const matches = [];
+    for (let index = startIndex; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--file' || value === '--text-from-file') {
+            matches.push({ index, flag: value });
+        }
+    }
+    if (matches.length === 0)
+        return { invalid: false };
+    if (matches.length !== 1)
+        return { invalid: true };
+    const filePath = argv[matches[0].index + 1];
+    return isDeterministicFilePath(filePath)
+        ? { path: filePath, invalid: false }
+        : { invalid: true };
+}
+export function parseEvolcoreSendCommand(command) {
+    const argv = parseLiteralShellArgv(command);
+    if (!argv || argv[0] !== 'ec')
+        return null;
+    if (argv[1] === 'ctl') {
+        if (argv[2] === 'send')
+            return { scope: 'ctl', action: 'send' };
+        if (argv[2] !== 'file')
+            return null;
+        const operands = argv.slice(3);
+        if (operands.length < 1 || operands.length > 2)
+            return null;
+        const filePath = operands.at(-1);
+        if (!isDeterministicFilePath(filePath))
+            return null;
+        return { scope: 'ctl', action: 'file', filePath };
+    }
+    const scope = argv[1];
+    const subcommand = argv[2];
+    if ((scope !== 'msg' && scope !== 'group') || (subcommand !== 'send' && subcommand !== 'file'))
+        return null;
+    const targetId = argv[4];
+    if (!argv[3] || !targetId || argv[3].startsWith('--') || targetId.startsWith('--'))
+        return null;
+    // Keep the historical `msg/group file <from> <target> <path>` spelling,
+    // while classifying the actual CLI spelling `send ... --file <path>` (and
+    // msg `--text-from-file`) under the file operation as well.
+    if (subcommand === 'file') {
+        if (argv.length !== 6 || !isDeterministicFilePath(argv[5]))
+            return null;
+        return { scope, action: 'file', targetId, filePath: argv[5] };
+    }
+    const fileOption = findSingleFileOption(argv, 5);
+    if (fileOption.invalid)
+        return null;
+    return fileOption.path
+        ? { scope, action: 'file', targetId, filePath: fileOption.path }
+        : { scope, action: 'send', targetId };
+}
+export function isEvolcoreSendCommandForSession(toolName, input, channelId) {
+    if (toolName !== 'Bash')
+        return false;
+    const cmd = typeof input.command === 'string' ? input.command : '';
+    const parsed = parseEvolcoreSendCommand(cmd);
+    if (!parsed)
+        return false;
+    if (parsed.scope === 'ctl')
+        return true;
+    return parsed.targetId === channelId;
+}

package/dist/core/permission/execution-sandbox.js

@@ -0,0 +1,16 @@
+import { normalizePermissionMode } from './mode.js';
+/**
+ * Phase one only disables the task execution sandbox for an authenticated
+ * owner running in bypass mode. Every other combination remains fail-closed.
+ */
+export function resolvePhaseOneExecutionSandbox(permissionMode, role) {
+    const normalizedMode = normalizePermissionMode(permissionMode).mode;
+    const normalizedRole = role ?? undefined;
+    const sandboxOff = normalizedMode === 'bypass' && normalizedRole === 'owner';
+    return {
+        permissionMode: normalizedMode,
+        role: normalizedRole,
+        state: sandboxOff ? 'off' : 'active',
+        reason: sandboxOff ? 'owner-bypass' : 'phase-one-required',
+    };
+}

package/dist/core/permission/index.js

@@ -0,0 +1,6 @@
+export * from './tool-policy.js';
+export * from './ec-command-parser.js';
+export * from './approval-gateway.js';
+export * from './execution-sandbox.js';
+// Tool summaries live in utils; keep the historical permission import path compatible.
+export { summarizeToolInput } from '../../utils/tool-summary.js';

package/dist/core/permission/mode.js

@@ -0,0 +1,24 @@
+export const PUBLIC_PERMISSION_MODES = ['readonly', 'auto', 'request', 'bypass'];
+export function isPublicPermissionMode(value) {
+    return typeof value === 'string'
+        && PUBLIC_PERMISSION_MODES.includes(value);
+}
+/**
+ * Normalize persisted legacy values at the runtime boundary.
+ *
+ * - edit had request-like approval semantics, so it migrates to request.
+ * - noask historically disabled prompts and is therefore safely reduced to readonly.
+ * - plan is a workflow state, not an authority level; permission enforcement is readonly.
+ * - unknown values fail safe to readonly.
+ */
+export function normalizePermissionMode(value) {
+    if (isPublicPermissionMode(value))
+        return { mode: value };
+    if (value === 'edit')
+        return { mode: 'request', migratedFrom: 'edit' };
+    if (value === 'noask')
+        return { mode: 'readonly', migratedFrom: 'noask' };
+    if (value === 'plan')
+        return { mode: 'readonly', workflow: 'plan', migratedFrom: 'plan' };
+    return { mode: 'readonly' };
+}

package/dist/core/permission/sandbox-runtime.js

@@ -0,0 +1,265 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveCommandPath } from '../../utils/cross-platform.js';
+import { getExistingHClassMaskTargets, getExistingLClassReadOnlyTargets, isSameOrDescendant, } from '../protected-paths.js';
+import { resolveRoot } from '../../paths.js';
+let cachedBubblewrapPath;
+/**
+ * Claude Agent SDK's native sandbox is unavailable on Windows. WSL2 reports
+ * itself as Linux, so it remains fail-closed there together with macOS/Linux.
+ */
+export function shouldFailIfClaudeSandboxUnavailable(platform = process.platform) {
+    return platform !== 'win32';
+}
+function isExecutableFile(candidate) {
+    if (!candidate)
+        return false;
+    try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return fs.statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function codexBundledBubblewrap() {
+    if (process.platform !== 'linux')
+        return undefined;
+    const codexPath = resolveCommandPath('codex');
+    if (!codexPath)
+        return undefined;
+    let resolvedCodexPath = codexPath;
+    try {
+        resolvedCodexPath = fs.realpathSync(codexPath);
+    }
+    catch { }
+    const packageRoot = resolvedCodexPath.endsWith(`${path.sep}bin${path.sep}codex.js`)
+        ? path.resolve(path.dirname(resolvedCodexPath), '..')
+        : undefined;
+    if (!packageRoot)
+        return undefined;
+    const target = process.arch === 'arm64'
+        ? 'aarch64-unknown-linux-musl'
+        : 'x86_64-unknown-linux-musl';
+    const platformPackage = process.arch === 'arm64' ? 'codex-linux-arm64' : 'codex-linux-x64';
+    return path.join(packageRoot, 'node_modules', '@openai', platformPackage, 'vendor', target, 'codex-resources', 'bwrap');
+}
+export function resolveBubblewrapPath() {
+    if (cachedBubblewrapPath !== undefined)
+        return cachedBubblewrapPath ?? undefined;
+    if (process.platform !== 'linux') {
+        cachedBubblewrapPath = null;
+        return undefined;
+    }
+    const candidates = [
+        process.env.EVOLCORE_BWRAP_PATH,
+        resolveCommandPath('bwrap') ?? undefined,
+        codexBundledBubblewrap(),
+    ];
+    const resolved = candidates.find(isExecutableFile);
+    cachedBubblewrapPath = resolved ?? null;
+    return resolved;
+}
+export function prependExecutableDirectory(env, executablePath) {
+    const currentPath = env.PATH ?? process.env.PATH ?? '';
+    const directory = path.dirname(executablePath);
+    return {
+        ...env,
+        PATH: currentPath ? `${directory}${path.delimiter}${currentPath}` : directory,
+    };
+}
+function resolveGitDirectory(projectPath) {
+    const marker = path.join(path.resolve(projectPath), '.git');
+    try {
+        if (fs.statSync(marker).isDirectory())
+            return marker;
+        const match = fs.readFileSync(marker, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
+        if (!match)
+            return undefined;
+        return path.resolve(path.dirname(marker), match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveCommonGitDirectory(gitDirectory) {
+    try {
+        const commonDirectory = fs.readFileSync(path.join(gitDirectory, 'commondir'), 'utf8').trim();
+        if (commonDirectory)
+            return path.resolve(gitDirectory, commonDirectory);
+    }
+    catch { }
+    return gitDirectory;
+}
+function hasWorktreeConfigExtension(config) {
+    let section = '';
+    for (const rawLine of config.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#') || line.startsWith(';'))
+            continue;
+        const sectionMatch = line.match(/^\[\s*([^\]\s]+)(?:\s+"[^"]*")?\s*\]$/);
+        if (sectionMatch) {
+            section = sectionMatch[1].toLowerCase();
+            continue;
+        }
+        if (section !== 'extensions')
+            continue;
+        const settingMatch = line.match(/^worktreeconfig(?:\s*=\s*(.*?))?\s*(?:[#;].*)?$/i);
+        if (!settingMatch)
+            continue;
+        const value = (settingMatch[1] ?? 'true').trim().toLowerCase();
+        return ['true', 'yes', 'on', '1'].includes(value);
+    }
+    return false;
+}
+export function ensureClaudeGitWorktreeConfig(projectPath) {
+    const gitDirectory = resolveGitDirectory(projectPath);
+    if (!gitDirectory)
+        return undefined;
+    const commonDirectory = resolveCommonGitDirectory(gitDirectory);
+    let config;
+    try {
+        config = fs.readFileSync(path.join(commonDirectory, 'config'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (!hasWorktreeConfigExtension(config))
+        return undefined;
+    const worktreeConfig = path.join(gitDirectory, 'config.worktree');
+    if (fs.existsSync(worktreeConfig))
+        return worktreeConfig;
+    try {
+        fs.writeFileSync(worktreeConfig, '', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return worktreeConfig;
+}
+function pushWritableBind(args, candidate) {
+    if (!fs.existsSync(candidate))
+        return;
+    args.push('--bind', candidate, candidate);
+}
+function pushMaskedFile(args, candidate) {
+    if (!fs.existsSync(candidate))
+        return;
+    args.push('--ro-bind', '/dev/null', candidate);
+}
+function pushMaskedDirectory(args, candidate) {
+    if (!fs.existsSync(candidate))
+        return;
+    args.push('--tmpfs', candidate);
+}
+function appendRuntimeBackedEtcFiles(args) {
+    if (process.platform !== 'linux' || !fs.existsSync('/run'))
+        return;
+    let runtimeRoot = '/run';
+    try {
+        runtimeRoot = fs.realpathSync('/run');
+    }
+    catch { }
+    const createdDirectories = new Set();
+    for (const candidate of ['/etc/resolv.conf', '/etc/hosts', '/etc/hostname']) {
+        let resolved;
+        try {
+            resolved = fs.realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (resolved === runtimeRoot || !isSameOrDescendant(resolved, runtimeRoot))
+            continue;
+        const directories = [];
+        let current = path.dirname(resolved);
+        while (current !== runtimeRoot && isSameOrDescendant(current, runtimeRoot)) {
+            directories.push(current);
+            current = path.dirname(current);
+        }
+        for (const directory of directories.reverse()) {
+            if (createdDirectories.has(directory))
+                continue;
+            createdDirectories.add(directory);
+            args.push('--dir', directory);
+        }
+        // Bubblewrap opens bind sources before applying the new mount layout. This
+        // preserves only the exact runtime-backed /etc file after /run is replaced,
+        // without re-exposing sibling service or container-runtime sockets.
+        args.push('--ro-bind', candidate, resolved);
+    }
+}
+function appendHClassMasks(args, root, maskContainerSockets) {
+    for (const target of getExistingHClassMaskTargets(root)) {
+        if (target.kind === 'directory')
+            pushMaskedDirectory(args, target.path);
+        else
+            pushMaskedFile(args, target.path);
+    }
+    if (!maskContainerSockets)
+        return;
+    // bubblewrap cannot replace an existing Unix socket with a regular-file bind
+    // on all kernels. A private /run hides Docker, Podman, and user runtime
+    // sockets without disabling ordinary network access needed by web tools.
+    pushMaskedDirectory(args, '/run');
+    appendRuntimeBackedEtcFiles(args);
+}
+function appendLClassReadOnlyBinds(args, root) {
+    for (const target of getExistingLClassReadOnlyTargets(root)) {
+        args.push('--ro-bind', target.path, target.path);
+    }
+}
+export function buildHClassGuardCommand(executable, executableArgs, root = resolveRoot()) {
+    const bubblewrapPath = resolveBubblewrapPath();
+    if (!bubblewrapPath)
+        return undefined;
+    const args = [
+        '--die-with-parent',
+        '--new-session',
+        '--unshare-pid',
+        '--bind', '/', '/',
+        '--dev-bind', '/dev', '/dev',
+        '--proc', '/proc',
+    ];
+    appendLClassReadOnlyBinds(args, path.resolve(root));
+    appendHClassMasks(args, path.resolve(root), true);
+    args.push('--', executable, ...executableArgs);
+    return { command: bubblewrapPath, args };
+}
+export function buildBubblewrapCommand(executable, executableArgs, options) {
+    const bubblewrapPath = resolveBubblewrapPath();
+    if (!bubblewrapPath)
+        return undefined;
+    const projectPath = path.resolve(options.projectPath);
+    const root = path.resolve(options.root ?? resolveRoot());
+    const args = [
+        '--die-with-parent',
+        '--new-session',
+        '--unshare-pid',
+        '--ro-bind', '/', '/',
+        '--dev-bind', '/dev', '/dev',
+        '--proc', '/proc',
+        '--tmpfs', '/tmp',
+    ];
+    pushWritableBind(args, projectPath);
+    for (const writablePath of options.writablePaths ?? []) {
+        const resolved = path.resolve(writablePath);
+        if (isSameOrDescendant(resolved, projectPath))
+            continue;
+        pushWritableBind(args, resolved);
+    }
+    for (const readonlyPath of options.readonlyPaths ?? []) {
+        const resolved = path.resolve(readonlyPath);
+        if (!fs.existsSync(resolved))
+            continue;
+        args.push('--ro-bind', resolved, resolved);
+    }
+    appendLClassReadOnlyBinds(args, root);
+    appendHClassMasks(args, root, true);
+    args.push('--chdir', projectPath, '--', executable, ...executableArgs);
+    return { command: bubblewrapPath, args };
+}
+export function _resetSandboxRuntimeCache() {
+    cachedBubblewrapPath = undefined;
+}