@jshookmcp/jshook 0.2.2 → 0.2.5

package/dist/src/server/domains/process/handlers.base.process.js

@@ -0,0 +1,417 @@
+import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
+import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
+import { logger } from '../../../utils/logger.js';
+import { argNumber, argStringArray } from '../../domains/shared/parse-args.js';
+import { validatePid, requireString, } from './handlers.base.types.js';
+export class ProcessHandlersCore {
+    processManager;
+    memoryManager;
+    platform;
+    auditTrail = new MemoryAuditTrail();
+    constructor() {
+        this.processManager = new UnifiedProcessManager();
+        this.memoryManager = new MemoryManager();
+        this.platform = this.processManager.getPlatform();
+        logger.info(`ProcessToolHandlers initialized for platform: ${this.platform}`);
+    }
+    async buildMemoryDiagnostics(input) {
+        const recommendedActions = new Set();
+        const permission = await this.memoryManager.checkAvailability();
+        if (!permission.available) {
+            recommendedActions.add('Run as administrator');
+        }
+        let processInfo = null;
+        if (input.pid !== undefined && input.pid !== null) {
+            try {
+                const resolvedProcess = await this.processManager.getProcessByPid(input.pid);
+                processInfo = resolvedProcess
+                    ? {
+                        pid: resolvedProcess.pid,
+                        name: resolvedProcess.name,
+                        executablePath: resolvedProcess.executablePath,
+                        windowTitle: resolvedProcess.windowTitle,
+                        windowHandle: resolvedProcess.windowHandle,
+                        memoryUsage: resolvedProcess.memoryUsage,
+                    }
+                    : null;
+            }
+            catch {
+                processInfo = null;
+            }
+            if (!processInfo) {
+                recommendedActions.add('Check if process is still running');
+            }
+        }
+        let protectionInfo = null;
+        let protectionQueryFailed = false;
+        if (input.pid !== undefined && input.pid !== null && input.address) {
+            try {
+                protectionInfo = await this.memoryManager.checkMemoryProtection(input.pid, input.address);
+            }
+            catch {
+                protectionQueryFailed = true;
+            }
+            if (protectionQueryFailed || protectionInfo?.success === false) {
+                recommendedActions.add('Verify address is within valid memory region');
+            }
+        }
+        if (input.size !== undefined &&
+            input.size !== null &&
+            protectionInfo?.regionSize !== undefined &&
+            protectionInfo.regionSize !== null &&
+            input.size > protectionInfo.regionSize) {
+            recommendedActions.add('Reduce the requested size to fit the target memory region');
+        }
+        if (input.operation === 'memory_read' &&
+            protectionInfo?.success &&
+            protectionInfo.isReadable === false) {
+            recommendedActions.add('Ensure target memory region is readable');
+        }
+        if (input.operation === 'memory_write' &&
+            protectionInfo?.success &&
+            protectionInfo.isWritable === false) {
+            recommendedActions.add('Ensure target memory region is writable');
+        }
+        let modulesEnumerated = false;
+        let moduleCount = null;
+        if (input.pid !== undefined && input.pid !== null) {
+            try {
+                const modulesResult = await this.memoryManager.enumerateModules(input.pid);
+                modulesEnumerated = modulesResult.success;
+                moduleCount = modulesResult.modules?.length ?? null;
+            }
+            catch {
+                modulesEnumerated = false;
+            }
+        }
+        if (input.pid !== undefined && input.pid !== null && input.address) {
+            recommendedActions.add('Re-resolve the address after the process restarts because ASLR can shift module addresses');
+        }
+        const normalizedError = input.error?.toLowerCase() ?? '';
+        if (normalizedError.includes('access denied') ||
+            normalizedError.includes('permission') ||
+            normalizedError.includes('privilege') ||
+            normalizedError.includes('administrator')) {
+            recommendedActions.add('Run as administrator');
+        }
+        const aslrNote = modulesEnumerated
+            ? moduleCount && moduleCount > 0
+                ? `Enumerated ${moduleCount} module(s). Treat absolute addresses as session-specific because ASLR can shift module bases between launches.`
+                : 'Module enumeration succeeded but returned no modules. Absolute addresses may still change across process launches because of ASLR.'
+            : 'Module enumeration was unavailable. Assume ASLR may shift absolute addresses between launches and re-resolve addresses after restarts.';
+        return {
+            permission: {
+                available: permission.available,
+                reason: permission.reason,
+                platform: this.platform,
+            },
+            process: {
+                exists: input.pid !== undefined && input.pid !== null ? Boolean(processInfo) : null,
+                pid: input.pid ?? null,
+                name: processInfo?.name ?? null,
+            },
+            address: {
+                queried: input.pid !== undefined && input.pid !== null && Boolean(input.address),
+                valid: input.pid !== undefined && input.pid !== null && input.address
+                    ? (protectionInfo?.success ?? null)
+                    : null,
+                protection: protectionInfo?.protection ?? null,
+                regionStart: protectionInfo?.regionStart ?? null,
+                regionSize: protectionInfo?.regionSize ?? null,
+            },
+            aslr: {
+                heuristic: true,
+                note: aslrNote,
+            },
+            recommendedActions: Array.from(recommendedActions),
+        };
+    }
+    async safeBuildMemoryDiagnostics(input) {
+        try {
+            return await this.buildMemoryDiagnostics(input);
+        }
+        catch (diagnosticError) {
+            logger.warn('Memory diagnostics generation failed:', diagnosticError);
+            return undefined;
+        }
+    }
+    recordMemoryAudit(entry) {
+        try {
+            this.auditTrail.record(entry);
+        }
+        catch (auditError) {
+            logger.warn('Memory audit trail recording failed:', auditError);
+        }
+    }
+    async handleProcessFind(args) {
+        try {
+            const pattern = requireString(args.pattern, 'pattern');
+            const processes = await this.processManager.findProcesses(pattern);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pattern,
+                            count: processes.length,
+                            processes: processes.map((p) => ({
+                                pid: p.pid,
+                                name: p.name,
+                                path: p.executablePath,
+                                windowTitle: p.windowTitle,
+                                windowHandle: p.windowHandle,
+                                memoryMB: p.memoryUsage ? Math.round(p.memoryUsage / 1024 / 1024) : undefined,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process find failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessGet(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const process = await this.processManager.getProcessByPid(pid);
+            if (!process) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: `Process with PID ${pid} not found`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const cmdLine = await this.processManager.getProcessCommandLine(pid);
+            const debugPort = await this.processManager.checkDebugPort(pid, {
+                commandLine: cmdLine.commandLine,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            process: {
+                                ...process,
+                                commandLine: cmdLine.commandLine,
+                                parentPid: cmdLine.parentPid,
+                                debugPort,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process get failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessWindows(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const windows = await this.processManager.getProcessWindows(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pid,
+                            windowCount: windows.length,
+                            windows: windows.map((w) => ({
+                                handle: w.handle,
+                                title: w.title,
+                                className: w.className,
+                                processId: w.processId,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process windows failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessFindChromium(_args) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        disabled: true,
+                        message: 'process_find_chromium is disabled to avoid scanning user-installed browser processes.',
+                        guidance: [
+                            'Use browser_launch(driver="chrome"|"camoufox") to start a managed browser session.',
+                            'Use browser_attach/browser_launch(mode="connect") with an explicit browserURL/wsEndpoint.',
+                            'Use process_launch_debug for explicitly targeted Electron/Chromium executables.',
+                        ],
+                        platform: this.platform,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handleProcessCheckDebugPort(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const debugPort = await this.processManager.checkDebugPort(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pid,
+                            debugPort,
+                            canAttach: debugPort !== null,
+                            attachUrl: debugPort ? `http://localhost:${debugPort}` : null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Check debug port failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessLaunchDebug(args) {
+        try {
+            const executablePath = requireString(args.executablePath, 'executablePath');
+            const debugPort = argNumber(args, 'debugPort', 9222);
+            const argsList = argStringArray(args, 'args');
+            const process = await this.processManager.launchWithDebug(executablePath, debugPort, argsList);
+            if (!process) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Failed to launch process',
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            process: {
+                                pid: process.pid,
+                                name: process.name,
+                                path: process.executablePath,
+                            },
+                            debugPort,
+                            attachUrl: `http://localhost:${debugPort}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Launch debug failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessKill(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const killed = await this.processManager.killProcess(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: killed,
+                            pid,
+                            message: killed
+                                ? `Process ${pid} killed successfully`
+                                : `Failed to kill process ${pid}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process kill failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+}

package/dist/src/server/domains/process/handlers.base.types.d.ts

@@ -0,0 +1,57 @@
+import type { AuditEntry } from '../../../modules/process/memory/AuditTrail.js';
+export type { AuditEntry };
+export interface ProcessSummarySource {
+    pid: number;
+    name: string;
+    executablePath?: string;
+    windowTitle?: string;
+    windowHandle?: string;
+    memoryUsage?: number;
+}
+export interface ProcessWindowSource {
+    handle: string;
+    title: string;
+    className: string;
+    processId: number;
+}
+export interface MemoryDiagnosticsInput {
+    pid?: number;
+    address?: string;
+    size?: number;
+    operation: string;
+    error?: string;
+}
+export interface MemoryDiagnostics {
+    permission: {
+        available: boolean;
+        reason?: string;
+        platform: string;
+    };
+    process: {
+        exists: boolean | null;
+        pid: number | null;
+        name: string | null;
+    };
+    address: {
+        queried: boolean;
+        valid: boolean | null;
+        protection: string | null;
+        regionStart: string | null;
+        regionSize: number | null;
+    };
+    aslr: {
+        heuristic: true;
+        note: string;
+    };
+    recommendedActions: string[];
+}
+export type MemoryPatternType = 'hex' | 'int32' | 'int64' | 'float' | 'double' | 'string';
+export declare const MEMORY_PATTERN_TYPES: Set<MemoryPatternType>;
+export declare function validatePid(value: unknown): number;
+export declare function requireString(value: unknown, name: string): string;
+export declare function requirePositiveNumber(value: unknown, name: string): number;
+export declare function normalizePatternType(value: unknown): MemoryPatternType;
+export declare function getOptionalPid(value: unknown): number | undefined;
+export declare function getOptionalString(value: unknown): string | undefined;
+export declare function getOptionalPositiveNumber(value: unknown): number | undefined;
+export declare function getWriteSize(data: string, encoding: 'hex' | 'base64'): number;

package/dist/src/server/domains/process/handlers.base.types.js

@@ -0,0 +1,50 @@
+export const MEMORY_PATTERN_TYPES = new Set([
+    'hex',
+    'int32',
+    'int64',
+    'float',
+    'double',
+    'string',
+]);
+export function validatePid(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`Invalid PID: ${JSON.stringify(value)}`);
+    return n;
+}
+export function requireString(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+export function requirePositiveNumber(value, name) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`${name} must be a positive number`);
+    return n;
+}
+export function normalizePatternType(value) {
+    if (typeof value === 'string' && MEMORY_PATTERN_TYPES.has(value)) {
+        return value;
+    }
+    return 'hex';
+}
+export function getOptionalPid(value) {
+    const pid = Number(value);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+export function getOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function getOptionalPositiveNumber(value) {
+    const size = Number(value);
+    return Number.isFinite(size) && size > 0 ? size : undefined;
+}
+export function getWriteSize(data, encoding) {
+    if (encoding === 'hex') {
+        const normalized = data.replace(/\s+/g, '');
+        return Math.ceil(normalized.length / 2);
+    }
+    return Buffer.from(data, 'base64').length;
+}

package/dist/src/server/domains/process/handlers.impl.core.runtime.inject.js

@@ -16,6 +16,20 @@ function getOptionalPid(value) {
     const pid = Number(value);
     return Number.isInteger(pid) && pid > 0 ? pid : null;
 }
+function formatUnknownError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'object' && error !== null) {
+        try {
+            return JSON.stringify(error, null, 2);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
 function getOptionalString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -232,20 +246,6 @@ export class ProcessToolHandlersRuntime extends ProcessHandlersBase {
         const wsEndpointArg = args.wsEndpoint ?? '';
         const evaluateExpr = args.evaluate ?? '';
         const pageUrl = args.pageUrl ?? '';
-        const formatUnknownError = (error) => {
-            if (error instanceof Error) {
-                return error.message;
-            }
-            if (typeof error === 'object' && error !== null) {
-                try {
-                    return JSON.stringify(error, null, 2);
-                }
-                catch {
-                    return String(error);
-                }
-            }
-            return String(error);
-        };
         try {
             const baseUrl = `http://127.0.0.1:${port}`;
             const listUrl = `${baseUrl}/json/list`;
@@ -261,7 +261,9 @@ export class ProcessToolHandlersRuntime extends ProcessHandlersBase {
                 try {
                     const resp = await fetch(`${baseUrl}/json`);
                     if (!resp.ok) {
-                        throw new Error(`CDP fallback endpoint returned HTTP ${resp.status}`);
+                        throw new Error(`CDP fallback endpoint returned HTTP ${resp.status}`, {
+                            cause: listError,
+                        });
                     }
                     targets = (await resp.json());
                 }
@@ -269,7 +271,7 @@ export class ProcessToolHandlersRuntime extends ProcessHandlersBase {
                     const original = formatUnknownError(fallbackError || listError);
                     throw new Error(`Cannot connect to Electron CDP at ${baseUrl}. ` +
                         `Ensure the target app is running with a remote debugging port (for example: process_launch_debug with debugPort=${port}), ` +
-                        `then retry electron_attach. Original error: ${original}`);
+                        `then retry electron_attach. Original error: ${original}`, { cause: fallbackError });
                 }
             }
             if (!Array.isArray(targets)) {
@@ -297,7 +299,7 @@ export class ProcessToolHandlersRuntime extends ProcessHandlersBase {
                 };
             }
             const target = filtered[0];
-            if (!target || !target.webSocketDebuggerUrl) {
+            if (!target?.webSocketDebuggerUrl) {
                 return {
                     content: [
                         {

package/dist/src/server/domains/process/manifest.js

@@ -5,12 +5,17 @@ const DOMAIN = 'process';
 const DEP_KEY = 'processHandlers';
 const t = toolLookup(processToolDefinitions);
 const b = (invoke) => bindByDepKey(DEP_KEY, invoke);
+const EFFECTIVE_PLATFORM = process.env.JSHOOK_REGISTRY_PLATFORM === 'win32' ||
+    process.env.JSHOOK_REGISTRY_PLATFORM === 'linux' ||
+    process.env.JSHOOK_REGISTRY_PLATFORM === 'darwin'
+    ? process.env.JSHOOK_REGISTRY_PLATFORM
+    : process.platform;
 function ensure(ctx) {
     if (!ctx.processHandlers)
         ctx.processHandlers = new ProcessToolHandlers();
     return ctx.processHandlers;
 }
-const IS_WIN32 = process.platform === 'win32';
+const IS_WIN32 = EFFECTIVE_PLATFORM === 'win32';
 const WIN32_ONLY_TOOLS = new Set([
     'inject_dll',
     'module_inject_dll',

package/dist/src/server/domains/sandbox/definitions.js

@@ -1,35 +1,13 @@
+import { tool } from '../../registry/tool-builder.js';
 export const sandboxTools = [
-    {
-        name: 'execute_sandbox_script',
-        description: 'Execute JavaScript code in a WASM-isolated QuickJS sandbox with optional MCP tool bridging, session persistence, and auto-correction.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                code: {
-                    type: 'string',
-                    description: 'JavaScript source code to execute inside the sandbox.',
-                },
-                sessionId: {
-                    type: 'string',
-                    description: 'Optional session ID for scratchpad persistence across executions. If omitted, no persistence.',
-                },
-                timeoutMs: {
-                    type: 'number',
-                    description: 'Execution timeout in ms (default: 1000).',
-                },
-                autoCorrect: {
-                    type: 'boolean',
-                    description: 'When true, failed scripts are retried up to 2 times with error context appended.',
-                    default: false,
-                },
-            },
-            required: ['code'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('execute_sandbox_script')
+        .desc('Execute JavaScript in a WASM-isolated QuickJS sandbox with optional tool bridging and auto-correction')
+        .string('code', 'JavaScript source code to execute')
+        .string('sessionId', 'Session ID for scratchpad persistence across executions')
+        .number('timeoutMs', 'Execution timeout in ms', { default: 1000 })
+        .boolean('autoCorrect', 'Retry failed scripts up to 2 times with error context', {
+        default: false,
+    })
+        .required('code')
+        .build(),
 ];