magi-ai 0.1.0

package/dist/src/utils/logger.js

@@ -0,0 +1,112 @@
+import { AuditLogWriter } from '../audit/writer.js';
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLevel = 'info';
+let auditWriter = null;
+let tuiActive = false;
+let tuiBuffer = [];
+/**
+ * Suppress console output during TUI mode.
+ * Logs are buffered and flushed when TUI mode is disabled.
+ */
+export function setTuiMode(enabled) {
+    if (tuiActive && !enabled) {
+        for (const entry of tuiBuffer) {
+            console.error(`${entry.level} ${entry.message}`, entry.data);
+        }
+        tuiBuffer = [];
+    }
+    tuiActive = enabled;
+}
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/**
+ * Initialize audit logging. Must be called before logger.audit() will write entries.
+ * If not called, audit() calls are silently ignored.
+ */
+export async function initAuditLog(config) {
+    auditWriter = new AuditLogWriter(config);
+    await auditWriter.initialize();
+}
+/**
+ * Get the current audit writer (for testing purposes).
+ */
+export function getAuditWriter() {
+    return auditWriter;
+}
+/**
+ * Reset audit writer (for testing teardown).
+ */
+export function resetAuditWriter() {
+    auditWriter = null;
+}
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+function formatTimestamp() {
+    return new Date().toISOString();
+}
+export const logger = {
+    debug(message, data) {
+        if (!shouldLog('debug'))
+            return;
+        const prefix = `[${formatTimestamp()}] DEBUG`;
+        if (tuiActive) {
+            tuiBuffer.push({ level: prefix, message, data: data ? JSON.stringify(data) : '' });
+            return;
+        }
+        console.error(`${prefix} ${message}`, data ?? '');
+    },
+    info(message, data) {
+        if (!shouldLog('info'))
+            return;
+        const prefix = `[${formatTimestamp()}] INFO `;
+        if (tuiActive) {
+            tuiBuffer.push({ level: prefix, message, data: data ? JSON.stringify(data) : '' });
+            return;
+        }
+        console.error(`${prefix} ${message}`, data ?? '');
+    },
+    warn(message, data) {
+        if (!shouldLog('warn'))
+            return;
+        const prefix = `[${formatTimestamp()}] WARN `;
+        if (tuiActive) {
+            tuiBuffer.push({ level: prefix, message, data: data ? JSON.stringify(data) : '' });
+            return;
+        }
+        console.error(`${prefix} ${message}`, data ?? '');
+    },
+    error(message, data) {
+        if (!shouldLog('error'))
+            return;
+        const prefix = `[${formatTimestamp()}] ERROR`;
+        if (tuiActive) {
+            tuiBuffer.push({ level: prefix, message, data: data ? JSON.stringify(data) : '' });
+            return;
+        }
+        console.error(`${prefix} ${message}`, data ?? '');
+    },
+    /**
+     * Write an audit log entry. Fire-and-forget -- never blocks the caller.
+     * If audit logging is not initialized, the call is silently ignored.
+     */
+    audit(event, deliberationId, data) {
+        if (!auditWriter)
+            return;
+        // Fire and forget -- catch errors to prevent unhandled rejections
+        auditWriter.write(event, deliberationId, data).catch((err) => {
+            const msg = `[AUDIT ERROR] Failed to write audit event ${event}: ${String(err)}`;
+            if (tuiActive) {
+                tuiBuffer.push({ level: '[AUDIT]', message: msg, data: '' });
+                return;
+            }
+            console.error(msg);
+        });
+    },
+};

package/dist/src/utils/process.d.ts

@@ -0,0 +1,40 @@
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+    timedOut: boolean;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+}
+export interface SpawnOptions {
+    command: string;
+    args: string[];
+    stdin?: string;
+    timeoutMs?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+    maxBufferSize?: number;
+    onStdoutChunk?: (chunk: string) => void;
+    onStderrChunk?: (chunk: string) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Filter environment variables to only allowed keys.
+ * Prevents leaking sensitive env vars to child processes.
+ */
+export declare function filterEnvironment(env?: NodeJS.ProcessEnv, extraKeys?: readonly string[]): Record<string, string>;
+/**
+ * Validate that a command is in the allowlist.
+ * Throws if the command is not allowed.
+ */
+export declare function validateCommand(command: string): void;
+/**
+ * Spawns a CLI process with timeout, stdin support, and structured result.
+ * Uses stdin for prompt injection to prevent shell injection attacks.
+ */
+export declare function spawnProcess(options: SpawnOptions): Promise<SpawnResult>;
+/**
+ * Check if a CLI binary is available in PATH.
+ */
+export declare function isBinaryAvailable(name: string): Promise<boolean>;

package/dist/src/utils/process.js

@@ -0,0 +1,253 @@
+import { spawn } from 'node:child_process';
+import { realpathSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { registerProcess } from './shutdown.js';
+import { logger } from './logger.js';
+/** Environment variables allowed to pass through to child processes */
+const ENV_ALLOWLIST = new Set([
+    'PATH',
+    'HOME',
+    'USER',
+    'SHELL',
+    'LANG',
+    'LC_ALL',
+    'TERM',
+    'TMPDIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'NODE_ENV',
+]);
+/** Per-command API key mapping (least-privilege) */
+const COMMAND_API_KEYS = {
+    claude: ['ANTHROPIC_API_KEY'],
+    codex: ['OPENAI_API_KEY'],
+    gemini: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+};
+/**
+ * Filter environment variables to only allowed keys.
+ * Prevents leaking sensitive env vars to child processes.
+ */
+export function filterEnvironment(env = process.env, extraKeys) {
+    const allowed = new Set([...ENV_ALLOWLIST, ...(extraKeys ?? [])]);
+    const filtered = {};
+    for (const key of allowed) {
+        const value = env[key];
+        if (value !== undefined) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+/** Commands allowed to be executed */
+const COMMAND_ALLOWLIST = new Set([
+    'claude',
+    'codex',
+    'gemini',
+    'which',
+]);
+/**
+ * Validate that a command is in the allowlist.
+ * Throws if the command is not allowed.
+ */
+export function validateCommand(command) {
+    // Reject null bytes
+    if (command.includes('\0')) {
+        throw new Error('Command must not contain null bytes');
+    }
+    // Extract basename (handle full paths like /usr/bin/claude)
+    const basename = command.split('/').pop() ?? command;
+    if (COMMAND_ALLOWLIST.has(basename)) {
+        // Falls through to symlink check below if path has separators
+    }
+    else if (command.includes('node_modules/.bin/')) {
+        // Allow local devDependency binaries (tsc, eslint, vitest, etc.)
+        const normalized = path.normalize(command);
+        if (normalized.includes('..')) {
+            throw new Error(`Path traversal detected in command: ${command}`);
+        }
+        return; // node_modules/.bin paths don't need symlink check
+    }
+    else {
+        throw new Error(`Command not allowed: ${command}. Allowed: ${[...COMMAND_ALLOWLIST].join(', ')}`);
+    }
+    // If command contains a path separator, resolve symlinks and re-validate
+    if (command.includes('/')) {
+        try {
+            const stats = lstatSync(command);
+            if (stats.isSymbolicLink()) {
+                logger.warn('Symlink detected in command path, resolving', { command });
+            }
+            const resolved = realpathSync(command);
+            const resolvedBasename = resolved.split('/').pop() ?? resolved;
+            if (!COMMAND_ALLOWLIST.has(resolvedBasename)) {
+                throw new Error(`Resolved command not allowed: ${command} -> ${resolved}. Allowed: ${[...COMMAND_ALLOWLIST].join(', ')}`);
+            }
+        }
+        catch (err) {
+            // ENOENT: binary not found at explicit path — let spawn handle the error
+            if (err.code === 'ENOENT') {
+                return;
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * Spawns a CLI process with timeout, stdin support, and structured result.
+ * Uses stdin for prompt injection to prevent shell injection attacks.
+ */
+export function spawnProcess(options) {
+    const { command, args, stdin: stdinData, timeoutMs = 120_000, cwd, env: extraEnv, maxBufferSize = 10 * 1024 * 1024, } = options;
+    validateCommand(command);
+    // Inject only the API keys needed for this specific command (least-privilege)
+    const cmdBasename = command.split('/').pop() ?? command;
+    const apiKeys = COMMAND_API_KEYS[cmdBasename] ?? [];
+    const filteredEnv = filterEnvironment(undefined, apiKeys);
+    const env = extraEnv
+        ? { ...filteredEnv, ...filterEnvironment(extraEnv) }
+        : filteredEnv;
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutSize = 0;
+        let stderrSize = 0;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let timedOut = false;
+        logger.debug(`Spawning: ${command} ${args.join(' ')}`, { cwd, timeoutMs });
+        const proc = spawn(command, args, {
+            cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        registerProcess(proc);
+        // External abort support (e.g. from orchestrator phase timeout)
+        if (options.signal) {
+            const killProc = () => {
+                if (!proc.killed) {
+                    timedOut = true;
+                    proc.kill('SIGTERM');
+                    const forceTimer = setTimeout(() => {
+                        if (!proc.killed)
+                            proc.kill('SIGKILL');
+                    }, 5_000);
+                    forceTimer.unref();
+                }
+            };
+            if (options.signal.aborted) {
+                killProc();
+            }
+            else {
+                options.signal.addEventListener('abort', killProc, { once: true });
+                proc.on('close', () => {
+                    options.signal.removeEventListener('abort', killProc);
+                });
+            }
+        }
+        // Handle EPIPE: child may exit before reading all stdin
+        proc.stdin.on('error', (err) => {
+            if (err.code !== 'EPIPE') {
+                logger.warn('stdin write error', { error: String(err) });
+            }
+        });
+        if (stdinData) {
+            proc.stdin.write(stdinData);
+            proc.stdin.end();
+        }
+        else {
+            proc.stdin.end();
+        }
+        // Use StringDecoder to safely handle UTF-8 multibyte chars at chunk boundaries
+        const stdoutDecoder = new StringDecoder('utf8');
+        const stderrDecoder = new StringDecoder('utf8');
+        proc.stdout.on('data', (data) => {
+            const chunk = stdoutDecoder.write(data);
+            stdoutSize += data.length;
+            if (stdoutSize <= maxBufferSize) {
+                stdoutChunks.push(chunk);
+            }
+            else if (!stdoutTruncated) {
+                stdoutTruncated = true;
+                logger.warn(`stdout exceeded ${maxBufferSize} bytes, truncating`);
+            }
+            options.onStdoutChunk?.(chunk);
+        });
+        proc.stderr.on('data', (data) => {
+            const chunk = stderrDecoder.write(data);
+            stderrSize += data.length;
+            if (stderrSize <= maxBufferSize) {
+                stderrChunks.push(chunk);
+            }
+            else if (!stderrTruncated) {
+                stderrTruncated = true;
+                logger.warn(`stderr exceeded ${maxBufferSize} bytes, truncating`);
+            }
+            options.onStderrChunk?.(chunk);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            proc.kill('SIGTERM');
+            // Give 5s grace period then SIGKILL
+            const forceKillTimer = setTimeout(() => {
+                if (!proc.killed)
+                    proc.kill('SIGKILL');
+            }, 5_000);
+            forceKillTimer.unref(); // Don't block Node.js exit
+        }, timeoutMs);
+        proc.on('close', (exitCode) => {
+            clearTimeout(timer);
+            // Flush remaining multibyte bytes from decoders
+            const stdoutFinal = stdoutDecoder.end();
+            if (stdoutFinal && stdoutSize <= maxBufferSize)
+                stdoutChunks.push(stdoutFinal);
+            const stderrFinal = stderrDecoder.end();
+            if (stderrFinal && stderrSize <= maxBufferSize)
+                stderrChunks.push(stderrFinal);
+            const durationMs = Date.now() - startTime;
+            const stdout = stdoutChunks.join('');
+            const stderr = stderrChunks.join('');
+            logger.debug(`Process exited`, {
+                command,
+                exitCode: exitCode ?? -1,
+                durationMs,
+                timedOut,
+                stdoutLen: stdout.length,
+                stderrLen: stderr.length,
+                stdoutTruncated,
+                stderrTruncated,
+            });
+            resolve({
+                stdout,
+                stderr,
+                exitCode: exitCode ?? -1,
+                durationMs,
+                timedOut,
+                stdoutTruncated,
+                stderrTruncated,
+            });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Check if a CLI binary is available in PATH.
+ */
+export async function isBinaryAvailable(name) {
+    try {
+        const result = await spawnProcess({
+            command: 'which',
+            args: [name],
+            timeoutMs: 5_000,
+        });
+        return result.exitCode === 0;
+    }
+    catch (err) {
+        logger.debug('isBinaryAvailable: check failed', { name, error: String(err) });
+        return false;
+    }
+}

package/dist/src/utils/retry.d.ts

@@ -0,0 +1,12 @@
+export interface RetryOptions {
+    maxRetries: number;
+    baseDelayMs?: number;
+    shouldRetry?: (error: unknown) => boolean;
+}
+/**
+ * Retry a function with exponential backoff.
+ */
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, options: RetryOptions): Promise<{
+    result: T;
+    attempts: number;
+}>;

package/dist/src/utils/retry.js

@@ -0,0 +1,30 @@
+import { logger } from './logger.js';
+/**
+ * Retry a function with exponential backoff.
+ */
+export async function withRetry(fn, options) {
+    const { maxRetries, baseDelayMs = 1_000, shouldRetry } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const result = await fn(attempt);
+            return { result, attempts: attempt + 1 };
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxRetries)
+                break;
+            if (shouldRetry && !shouldRetry(error))
+                break;
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            logger.warn(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`, {
+                error: String(error),
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/src/utils/safe-fs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * safe-fs --- セキュアなファイル永続化ユーティリティ
+ *
+ * mkdir + writeFile + chmod の重複パターンを統一し、
+ * デフォルトでセキュアなパーミッション (0o700/0o600) を保証する。
+ * symlink検出もオプションで提供。
+ */
+/**
+ * セキュアなディレクトリ作成。
+ * デフォルトで 0o700 (owner only) パーミッション + symlink検出。
+ */
+export declare function safeMkdir(dirPath: string, options?: {
+    mode?: number;
+    checkSymlink?: boolean;
+}): Promise<void>;
+/**
+ * セキュアなファイル書き込み。
+ * デフォルトで 0o600 (owner read/write) パーミッション。
+ */
+export declare function safeWriteFile(filePath: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+/**
+ * セキュアなファイル追記。
+ * デフォルトで 0o600 (owner read/write) パーミッション。
+ */
+export declare function safeAppendFile(filePath: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+/**
+ * ディレクトリ作成 + ファイル書き込みを一括で実行。
+ * 最もよくあるパターン: mkdir(dirname(filePath)) → writeFile(filePath)
+ */
+export declare function safePersist(filePath: string, content: string, options?: {
+    dirMode?: number;
+    fileMode?: number;
+    checkSymlink?: boolean;
+}): Promise<void>;

package/dist/src/utils/safe-fs.js

@@ -0,0 +1,56 @@
+/**
+ * safe-fs --- セキュアなファイル永続化ユーティリティ
+ *
+ * mkdir + writeFile + chmod の重複パターンを統一し、
+ * デフォルトでセキュアなパーミッション (0o700/0o600) を保証する。
+ * symlink検出もオプションで提供。
+ */
+import { mkdir, writeFile, appendFile, lstat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { logger } from './logger.js';
+/**
+ * セキュアなディレクトリ作成。
+ * デフォルトで 0o700 (owner only) パーミッション + symlink検出。
+ */
+export async function safeMkdir(dirPath, options) {
+    const mode = options?.mode ?? 0o700;
+    await mkdir(dirPath, { recursive: true, mode });
+    if (options?.checkSymlink !== false) {
+        try {
+            const stats = await lstat(dirPath);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`Symlink detected at ${dirPath}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith('Symlink detected'))
+                throw err;
+            logger.debug('safeMkdir: directory stat failed during symlink check', { dirPath, error: String(err) });
+        }
+    }
+}
+/**
+ * セキュアなファイル書き込み。
+ * デフォルトで 0o600 (owner read/write) パーミッション。
+ */
+export async function safeWriteFile(filePath, content, options) {
+    await writeFile(filePath, content, { encoding: 'utf-8', mode: options?.mode ?? 0o600 });
+}
+/**
+ * セキュアなファイル追記。
+ * デフォルトで 0o600 (owner read/write) パーミッション。
+ */
+export async function safeAppendFile(filePath, content, options) {
+    await appendFile(filePath, content, { encoding: 'utf-8', mode: options?.mode ?? 0o600 });
+}
+/**
+ * ディレクトリ作成 + ファイル書き込みを一括で実行。
+ * 最もよくあるパターン: mkdir(dirname(filePath)) → writeFile(filePath)
+ */
+export async function safePersist(filePath, content, options) {
+    await safeMkdir(dirname(filePath), {
+        mode: options?.dirMode,
+        checkSymlink: options?.checkSymlink,
+    });
+    await safeWriteFile(filePath, content, { mode: options?.fileMode });
+}

package/dist/src/utils/safe-json-parse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Safe JSON parser with prototype pollution prevention.
+ *
+ * Rejects objects containing __proto__, constructor, or prototype keys
+ * at any nesting depth to prevent prototype pollution attacks.
+ */
+/**
+ * Parse JSON string with prototype pollution protection.
+ * Returns the parsed value, or throws on invalid JSON or prototype pollution.
+ */
+export declare function safeJsonParse<T = unknown>(raw: string): T;
+/**
+ * Parse JSON string safely, returning null on any error instead of throwing.
+ */
+export declare function safeJsonParseOrNull<T = unknown>(raw: string): T | null;

package/dist/src/utils/safe-json-parse.js

@@ -0,0 +1,49 @@
+/**
+ * Safe JSON parser with prototype pollution prevention.
+ *
+ * Rejects objects containing __proto__, constructor, or prototype keys
+ * at any nesting depth to prevent prototype pollution attacks.
+ */
+import { logger } from './logger.js';
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function assertNoPrototypePollution(val) {
+    if (val === null || typeof val !== 'object')
+        return;
+    const stack = [val];
+    const visited = new WeakSet();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === null || typeof current !== 'object')
+            continue;
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        for (const key of Object.keys(current)) {
+            if (UNSAFE_KEYS.has(key)) {
+                throw new Error(`Prototype pollution attempt detected: key "${key}"`);
+            }
+            stack.push(current[key]);
+        }
+    }
+}
+/**
+ * Parse JSON string with prototype pollution protection.
+ * Returns the parsed value, or throws on invalid JSON or prototype pollution.
+ */
+export function safeJsonParse(raw) {
+    const parsed = JSON.parse(raw);
+    assertNoPrototypePollution(parsed);
+    return parsed;
+}
+/**
+ * Parse JSON string safely, returning null on any error instead of throwing.
+ */
+export function safeJsonParseOrNull(raw) {
+    try {
+        return safeJsonParse(raw);
+    }
+    catch (err) {
+        logger.debug('safeJsonParse failed', { error: String(err) });
+        return null;
+    }
+}

package/dist/src/utils/sanitize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompt injection sanitization utilities for MAGI system.
+ *
+ * Detects and neutralizes 9 categories of prompt injection / control character
+ * abuse before embedding user-supplied content into LLM prompts.
+ */
+export interface SanitizeResult {
+    sanitized: string;
+    warnings: string[];
+    originalLength: number;
+    truncated: boolean;
+}
+export declare function sanitizeForPromptEmbedding(input: string): SanitizeResult;
+export declare function quoteForEmbedding(input: string, label?: string): string;