@memoryblock/tools 0.1.0-beta

package/src/sandbox.ts

@@ -0,0 +1,169 @@
+/**
+ * ToolSandbox — central enforcement layer for tool execution.
+ * 
+ * Every tool.execute() call passes through this gate.
+ * It intercepts params, scans for file paths, validates them against
+ * the block's permission scope, and blocks disallowed operations.
+ * 
+ * This class is designed as a drop-in replaceable module. Any future
+ * enforcement backend can substitute this class as long as it exposes
+ * the same static validate() and validateCommand() interface.
+ */
+
+import { resolve, relative, isAbsolute } from 'node:path';
+import type { ToolContext, ToolExecutionResult, PermissionsConfig } from 'memoryblock';
+
+// Patterns that look like file paths in tool params
+const PATH_PARAM_NAMES = ['path', 'file', 'filePath', 'directory', 'dir', 'target', 'source', 'destination'];
+
+// Sensitive files that should never be accessible regardless of scope
+const SENSITIVE_PATTERNS = [
+    'auth.json',
+    '.env',
+    '.memoryblock/auth.json',
+    'id_rsa',
+    'id_ed25519',
+    '.ssh/config',
+    '.aws/credentials',
+];
+
+// Shell tools that need special handling
+const SHELL_TOOL_NAMES = ['execute_command', 'run_lint', 'run_build', 'run_test'];
+
+export class ToolSandbox {
+
+    /**
+     * Validate a tool call BEFORE execution.
+     * Returns null if allowed, or an error ToolExecutionResult if denied.
+     */
+    static validate(
+        toolName: string,
+        params: Record<string, unknown>,
+        context: ToolContext,
+    ): ToolExecutionResult | null {
+        const perms = context.permissions || { scope: 'block', allowShell: false, allowNetwork: true, maxTimeout: 120_000 };
+
+        // 1. Shell access check
+        if (SHELL_TOOL_NAMES.includes(toolName)) {
+            if (!perms.allowShell && perms.scope !== 'system') {
+                return {
+                    content: `Denied: "${toolName}" requires shell access. Current scope: "${perms.scope}". Run \`mblk permissions ${context.blockName} --allow-shell\` to grant access.`,
+                    isError: true,
+                };
+            }
+        }
+
+        // 2. Scan all params for file paths and validate
+        const pathViolation = ToolSandbox.scanPaths(params, context, perms);
+        if (pathViolation) {
+            return { content: pathViolation, isError: true };
+        }
+
+        // 3. Check for sensitive file access in any string param
+        const sensitiveHit = ToolSandbox.scanSensitive(params);
+        if (sensitiveHit) {
+            return {
+                content: `Denied: access to "${sensitiveHit}" is blocked for security.`,
+                isError: true,
+            };
+        }
+
+        return null; // Allowed
+    }
+
+    /**
+     * Scan params for file path values and validate against scope.
+     */
+    private static scanPaths(
+        params: Record<string, unknown>,
+        context: ToolContext,
+        perms: PermissionsConfig,
+    ): string | null {
+        if (perms.scope === 'system') return null; // No path restrictions
+
+        for (const [key, value] of Object.entries(params)) {
+            if (typeof value !== 'string') continue;
+
+            // Check named path params
+            const isPathParam = PATH_PARAM_NAMES.some(p =>
+                key.toLowerCase().includes(p.toLowerCase()),
+            );
+
+            // Also check any string that looks like an absolute path
+            const looksLikePath = isPathParam || value.startsWith('/') || value.startsWith('~');
+
+            if (!looksLikePath) continue;
+
+            const resolved = isAbsolute(value)
+                ? value
+                : resolve(context.workingDir || context.blockPath, value);
+
+            const allowedRoot = perms.scope === 'workspace' && context.workspacePath
+                ? context.workspacePath
+                : context.blockPath;
+
+            const rel = relative(allowedRoot, resolved);
+            if (rel.startsWith('..') || isAbsolute(rel)) {
+                const label = perms.scope === 'workspace' ? 'workspace' : 'block directory';
+                return `Denied: "${key}" points to "${value}" which is outside the ${label}. Scope: "${perms.scope}".`;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if any string param references a sensitive file.
+     */
+    private static scanSensitive(params: Record<string, unknown>): string | null {
+        for (const value of Object.values(params)) {
+            if (typeof value !== 'string') continue;
+            const normalized = value.replace(/\\/g, '/');
+            for (const pattern of SENSITIVE_PATTERNS) {
+                if (normalized.endsWith(pattern) || normalized.includes(`/${pattern}`)) {
+                    return pattern;
+                }
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Scan a shell command string for path traversal attempts.
+     * Returns an error message if the command looks like it's escaping scope.
+     */
+    static validateCommand(
+        command: string,
+        context: ToolContext,
+    ): string | null {
+        const perms = context.permissions || { scope: 'block', allowShell: false, allowNetwork: true, maxTimeout: 120_000 };
+        if (perms.scope === 'system') return null;
+
+        // Check for common escape patterns in shell commands
+        const escapePatterns = [
+            /\bcd\s+\//,             // cd /absolute
+            /\bcat\s+\//,            // cat /etc/passwd
+            /\bls\s+\//,             // ls / (outside block)
+            />\s*\//,                // redirect to absolute path
+            /\|\s*tee\s+\//,         // pipe to absolute path
+        ];
+
+        // Only flag these in block scope — workspace/system allow broader access
+        if (perms.scope === 'block') {
+            for (const pattern of escapePatterns) {
+                if (pattern.test(command)) {
+                    return `Denied: command appears to access paths outside the block directory. Scope: "block".`;
+                }
+            }
+        }
+
+        // Check for sensitive file access in any scope
+        for (const sensitive of SENSITIVE_PATTERNS) {
+            if (command.includes(sensitive)) {
+                return `Denied: command references sensitive file "${sensitive}".`;
+            }
+        }
+
+        return null;
+    }
+}

package/src/shell/index.ts

@@ -0,0 +1,96 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { ToolExecutionResult } from 'memoryblock';
+import type { Tool } from '../base.js';
+import { createSchema } from '../base.js';
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT = 120_000; // 2 minutes
+const MAX_OUTPUT = 50_000;
+
+// Commands that are safe to auto-execute without approval
+const SAFE_PREFIXES = [
+    'ls', 'cat', 'head', 'tail', 'wc', 'find', 'grep', 'which', 'echo', 'pwd',
+    'node --version', 'bun --version', 'pnpm --version', 'npm --version',
+    'git status', 'git log', 'git diff', 'git branch',
+    'tsc --noEmit', 'npx eslint', 'pnpm lint', 'npm run lint',
+    'pnpm build', 'npm run build', 'pnpm test', 'npm test',
+];
+
+function isSafeCommand(command: string): boolean {
+    const trimmed = command.trim();
+    return SAFE_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+
+// ===== execute_command =====
+export const executeCommandTool: Tool = {
+    definition: {
+        name: 'execute_command',
+        description: 'Run shell command (Safe cmds run auto).',
+        parameters: createSchema(
+            {
+                command: { type: 'string', description: 'Command.' },
+                timeout: { type: 'string', description: 'Timeout (ms).' },
+            },
+            ['command'],
+        ),
+        // Dynamic approval: overridden at dispatch time based on command safety
+        requiresApproval: true,
+    },
+    async execute(params, context): Promise<ToolExecutionResult> {
+        const command = params.command as string;
+        const scope = context.permissions?.scope || 'block';
+
+        // Permission check: shell access must be explicitly granted
+        if (!context.permissions?.allowShell && scope !== 'system') {
+            return {
+                content: `Shell access denied. Current permission scope: "${scope}". Set allowShell: true or scope: "system" via \`mblk permissions ${context.blockName} --allow-shell\`.`,
+                isError: true,
+            };
+        }
+
+        const timeout = context.permissions?.maxTimeout
+            || (params.timeout ? parseInt(params.timeout as string, 10) : DEFAULT_TIMEOUT);
+
+        // Determine cwd based on scope
+        let cwd = context.workingDir || context.blockPath;
+        if (scope === 'block') {
+            cwd = context.blockPath;
+        } else if (scope === 'workspace' && context.workspacePath) {
+            // Allow commands within workspace, but default cwd to block
+            cwd = context.workingDir || context.blockPath;
+        }
+        // scope === 'system' — use whatever workingDir is set
+
+        try {
+            const { stdout, stderr } = await execFileAsync('/bin/sh', ['-c', command], {
+                cwd,
+                timeout,
+                maxBuffer: 2 * 1024 * 1024,
+                env: { ...process.env, HOME: process.env.HOME },
+            });
+
+            let output = '';
+            if (stdout) output += stdout;
+            if (stderr) output += (output ? '\n--- stderr ---\n' : '') + stderr;
+
+            if (output.length > MAX_OUTPUT) {
+                output = output.slice(0, MAX_OUTPUT) + `\n...(truncated, ${output.length} total chars)`;
+            }
+
+            return { content: output || '(no output)', isError: false };
+        } catch (err) {
+            const error = err as Error & { stdout?: string; stderr?: string; code?: number };
+            let message = error.message;
+            if (error.stdout) message += `\nstdout: ${error.stdout.slice(0, 5000)}`;
+            if (error.stderr) message += `\nstderr: ${error.stderr.slice(0, 5000)}`;
+            return { content: `Command failed: ${message}`, isError: true };
+        }
+    },
+};
+
+/** Check if a command is safe (export for use in approval logic). */
+export { isSafeCommand };
+
+/** All built-in shell tools. */
+export const shellTools: Tool[] = [executeCommandTool];

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": [
+        "src"
+    ]
+}