@jshookmcp/jshook 0.2.2 → 0.2.5

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

@@ -1,97 +1,6 @@
-import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
-import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
-import type { AuditEntry } from '../../../modules/process/memory/AuditTrail.js';
-interface MemoryDiagnosticsInput {
-    pid?: number;
-    address?: string;
-    size?: number;
-    operation: string;
-    error?: string;
-}
-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 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 class ProcessHandlersBase {
-    protected processManager: UnifiedProcessManager;
-    protected memoryManager: MemoryManager;
-    protected platform: string;
-    protected auditTrail: MemoryAuditTrail;
-    constructor();
-    protected buildMemoryDiagnostics(input: MemoryDiagnosticsInput): Promise<MemoryDiagnostics>;
-    protected safeBuildMemoryDiagnostics(input: {
-        pid?: number;
-        address?: string;
-        size?: number;
-        operation: string;
-        error?: string;
-    }): Promise<unknown>;
-    protected recordMemoryAudit(entry: Omit<AuditEntry, 'timestamp' | 'user'>): void;
-    handleProcessFind(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessGet(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessWindows(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessFindChromium(_args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessCheckDebugPort(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessLaunchDebug(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
-    handleProcessKill(args: Record<string, unknown>): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-    }>;
+import { ProcessHandlersCore } from './handlers.base.process.js';
+export { validatePid, requireString, requirePositiveNumber } from './handlers.base.types.js';
+export declare class ProcessHandlersBase extends ProcessHandlersCore {
     handleMemoryRead(args: Record<string, unknown>): Promise<{
         content: {
             type: string;
@@ -147,4 +56,3 @@ export declare class ProcessHandlersBase {
         }[];
     }>;
 }
-export {};

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

@@ -1,464 +1,8 @@
-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';
-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;
-}
-function normalizePatternType(value) {
-    if (typeof value === 'string' && MEMORY_PATTERN_TYPES.has(value)) {
-        return value;
-    }
-    return 'hex';
-}
-function getOptionalPid(value) {
-    const pid = Number(value);
-    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
-}
-function getOptionalString(value) {
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-function getOptionalPositiveNumber(value) {
-    const size = Number(value);
-    return Number.isFinite(size) && size > 0 ? size : undefined;
-}
-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;
-}
-export class ProcessHandlersBase {
-    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 != 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 != 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 != null &&
-            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 != null) {
-            try {
-                const modulesResult = await this.memoryManager.enumerateModules(input.pid);
-                modulesEnumerated = modulesResult.success;
-                moduleCount = modulesResult.modules?.length ?? null;
-            }
-            catch {
-                modulesEnumerated = false;
-            }
-        }
-        if (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 != null ? Boolean(processInfo) : null,
-                pid: input.pid ?? null,
-                name: processInfo?.name ?? null,
-            },
-            address: {
-                queried: input.pid != null && Boolean(input.address),
-                valid: 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),
-                    },
-                ],
-            };
-        }
-    }
+import { ProcessHandlersCore } from './handlers.base.process.js';
+import { validatePid, requireString, requirePositiveNumber, normalizePatternType, getOptionalPid, getOptionalString, getOptionalPositiveNumber, getWriteSize, } from './handlers.base.types.js';
+export { validatePid, requireString, requirePositiveNumber } from './handlers.base.types.js';
+export class ProcessHandlersBase extends ProcessHandlersCore {
     async handleMemoryRead(args) {
         const startedAt = Date.now();
         try {
@@ -615,7 +159,7 @@ export class ProcessHandlersBase {
                                 reason: availability.reason,
                                 platform: this.platform,
                                 requestedAddress: address,
-                                dataLength: data != null ? data.length : 0,
+                                dataLength: data !== undefined && data !== null ? data.length : 0,
                                 encoding,
                                 pid,
                                 diagnostics,
@@ -709,6 +253,7 @@ export class ProcessHandlersBase {
             const pid = validatePid(args.pid);
             const pattern = requireString(args.pattern, 'pattern');
             const patternType = normalizePatternType(args.patternType);
+            const suspendTarget = args.suspendTarget === true;
             const availability = await this.memoryManager.checkAvailability();
             if (!availability.available) {
                 const errorMessage = availability.reason ?? 'Memory operations not available';
@@ -744,7 +289,7 @@ export class ProcessHandlersBase {
                     ],
                 };
             }
-            const result = await this.memoryManager.scanMemory(pid, pattern, patternType);
+            const result = await this.memoryManager.scanMemory(pid, pattern, patternType, suspendTarget);
             const diagnostics = !result.success
                 ? await this.safeBuildMemoryDiagnostics({
                     pid,

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

@@ -0,0 +1,61 @@
+import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
+import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
+import { type MemoryDiagnosticsInput, type MemoryDiagnostics, type AuditEntry } from './handlers.base.types.js';
+export declare class ProcessHandlersCore {
+    protected processManager: UnifiedProcessManager;
+    protected memoryManager: MemoryManager;
+    protected platform: string;
+    protected auditTrail: MemoryAuditTrail;
+    constructor();
+    protected buildMemoryDiagnostics(input: MemoryDiagnosticsInput): Promise<MemoryDiagnostics>;
+    protected safeBuildMemoryDiagnostics(input: {
+        pid?: number;
+        address?: string;
+        size?: number;
+        operation: string;
+        error?: string;
+    }): Promise<unknown>;
+    protected recordMemoryAudit(entry: Omit<AuditEntry, 'timestamp' | 'user'>): void;
+    handleProcessFind(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessGet(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessWindows(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessFindChromium(_args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessCheckDebugPort(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessLaunchDebug(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handleProcessKill(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+}