@hcu-lab.me/mcp-device 1.0.0

package/dist/device/gateway-secure-transport.js

@@ -0,0 +1,117 @@
+import { createHash } from 'crypto';
+import tls from 'tls';
+import { Duplex } from 'stream';
+import WebSocket from 'ws';
+export const DEVICE_INNER_TLS_SUBPROTOCOL = 'hcu-device-v2-inner-tls';
+export const DEVICE_MAX_MESSAGE_BYTES = 64 * 1024;
+export class WebSocketDuplex extends Duplex {
+    constructor(ws) {
+        super();
+        this.ws = ws;
+        ws.on('message', (data, isBinary) => {
+            if (!isBinary) {
+                this.destroy(new Error('Inner TLS transport requires binary WebSocket messages.'));
+                return;
+            }
+            const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            this.push(chunk);
+        });
+        ws.once('close', () => this.push(null));
+        ws.once('error', error => this.destroy(error));
+    }
+    _read() { }
+    _write(chunk, _encoding, callback) {
+        if (this.ws.readyState !== WebSocket.OPEN) {
+            callback(new Error('WebSocket is not open.'));
+            return;
+        }
+        this.ws.send(Buffer.from(chunk), { binary: true }, callback);
+    }
+    _destroy(error, callback) {
+        try {
+            if (this.ws.readyState === WebSocket.OPEN)
+                this.ws.close(1000, 'inner transport closed');
+            else if (this.ws.readyState === WebSocket.CONNECTING)
+                this.ws.terminate();
+        }
+        catch { }
+        callback(error);
+    }
+}
+export function createWebSocketDuplex(ws) {
+    return new WebSocketDuplex(ws);
+}
+export function createClientInnerTls(ws, options) {
+    return tls.connect({
+        socket: createWebSocketDuplex(ws),
+        ca: options.ca,
+        servername: options.servername,
+        minVersion: 'TLSv1.3',
+        rejectUnauthorized: true
+    });
+}
+export function exportDeviceAuthKeyingMaterial(socket, deviceId, mode) {
+    const context = createHash('sha256')
+        .update(`hcu-mcp-device-auth-v2\n${String(deviceId)}\n${String(mode)}`, 'utf8')
+        .digest();
+    return socket.exportKeyingMaterial(32, 'EXPERIMENTAL-HCU-MCP-DEVICE-AUTH-V2', context);
+}
+export function encodeJsonFrame(message, maxMessageBytes = DEVICE_MAX_MESSAGE_BYTES) {
+    const payload = Buffer.from(JSON.stringify(message), 'utf8');
+    if (payload.length < 1 || payload.length > maxMessageBytes) {
+        throw new Error('Device JSON frame exceeds maximum size.');
+    }
+    const frame = Buffer.allocUnsafe(4 + payload.length);
+    frame.writeUInt32BE(payload.length, 0);
+    payload.copy(frame, 4);
+    return frame;
+}
+export function createJsonFrameParser(options) {
+    const maxMessageBytes = options.maxMessageBytes ?? DEVICE_MAX_MESSAGE_BYTES;
+    if (typeof options.onMessage !== 'function')
+        throw new Error('onMessage callback is required.');
+    const header = Buffer.allocUnsafe(4);
+    let headerBytes = 0;
+    let expectedLength = null;
+    let bodyBytes = 0;
+    let bodyParts = [];
+    return {
+        push(value) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            let offset = 0;
+            while (offset < chunk.length) {
+                if (expectedLength === null) {
+                    const take = Math.min(4 - headerBytes, chunk.length - offset);
+                    chunk.copy(header, headerBytes, offset, offset + take);
+                    headerBytes += take;
+                    offset += take;
+                    if (headerBytes < 4)
+                        continue;
+                    const length = header.readUInt32BE(0);
+                    headerBytes = 0;
+                    if (length < 1 || length > maxMessageBytes)
+                        throw new Error('Invalid device JSON frame length.');
+                    expectedLength = length;
+                    bodyBytes = 0;
+                    bodyParts = [];
+                    continue;
+                }
+                const remaining = expectedLength - bodyBytes;
+                const take = Math.min(remaining, chunk.length - offset);
+                bodyParts.push(chunk.subarray(offset, offset + take));
+                bodyBytes += take;
+                offset += take;
+                if (bodyBytes !== expectedLength)
+                    continue;
+                const text = Buffer.concat(bodyParts, expectedLength).toString('utf8');
+                expectedLength = null;
+                bodyBytes = 0;
+                bodyParts = [];
+                const message = JSON.parse(text);
+                if (!message || typeof message !== 'object')
+                    throw new Error('Device JSON frame must contain an object.');
+                options.onMessage(message);
+            }
+        }
+    };
+}

package/dist/device/gateway-tool-adapter.d.ts

@@ -0,0 +1,17 @@
+import { DesktopCommanderIntegration } from './execution-engine.js';
+export declare const GATEWAY_CAPABILITIES: readonly ["read_text_file", "write_file", "edit_file", "shell_execute", "start_process", "read_process_output", "interact_with_process", "terminate_process", "image_preview", "project_inspect"];
+export interface GatewayToolAdapterOptions {
+    allowedRoots?: string[];
+    pathValidator?: (requestedPath: string) => Promise<string>;
+}
+export declare class GatewayToolAdapter {
+    private desktop;
+    private allowedRoots;
+    private pathValidator;
+    private canonicalRoots?;
+    constructor(desktop: DesktopCommanderIntegration, options?: GatewayToolAdapterOptions);
+    private guardPath;
+    private imagePreview;
+    call(tool: string, args?: any): Promise<any>;
+    private editFile;
+}

package/dist/device/gateway-tool-adapter.js

@@ -0,0 +1,284 @@
+import { exec, execFile } from 'child_process';
+import fs from 'fs/promises';
+import { promisify } from 'util';
+import path from 'path';
+import sharp from 'sharp';
+import { commandManager } from '../command-manager.js';
+import { configManager } from '../config-manager.js';
+import { validatePath } from '../tools/filesystem.js';
+import { inspectProjectOnDevice } from './project-inspection.js';
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+const MAX_REMOTE_IMAGE_SOURCE_BYTES = 32 * 1024 * 1024;
+const MAX_REMOTE_IMAGE_PREVIEW_BYTES = 32 * 1024;
+const IMAGE_PREVIEW_ATTEMPTS = [
+    { size: 512, quality: 65 },
+    { size: 384, quality: 55 },
+    { size: 256, quality: 45 },
+    { size: 160, quality: 35 }
+];
+export const GATEWAY_CAPABILITIES = [
+    'read_text_file',
+    'write_file',
+    'edit_file',
+    'shell_execute',
+    'start_process',
+    'read_process_output',
+    'interact_with_process',
+    'terminate_process',
+    'image_preview',
+    'project_inspect'
+];
+function configuredGatewayRoots() {
+    const raw = String(process.env.MCP_GATEWAY_ALLOWED_ROOTS || '').trim();
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MCP_GATEWAY_ALLOWED_ROOTS must be a JSON array of absolute paths');
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('MCP_GATEWAY_ALLOWED_ROOTS must be a JSON array of absolute paths');
+    return [...new Set(parsed.map(value => String(value).trim()).filter(Boolean))];
+}
+function isWithinRoot(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function textFromResult(result) {
+    return (result?.content || [])
+        .filter((item) => item?.type === 'text')
+        .map((item) => String(item.text || ''))
+        .join('\n');
+}
+function assertSuccess(result, tool) {
+    if (result?.isError)
+        throw new Error(textFromResult(result) || `${tool} failed`);
+    return result;
+}
+function parsePid(result) {
+    const match = textFromResult(result).match(/PID\s+(-?\d+)/i);
+    const pid = Number(match?.[1]);
+    if (!Number.isInteger(pid))
+        throw new Error('Desktop Commander did not return a process PID');
+    return pid;
+}
+async function runShell(args) {
+    const command = String(args.command || '');
+    if (!await commandManager.validateCommand(command))
+        throw new Error(`Command not allowed: ${command}`);
+    const cwd = args.working_directory
+        ? await validatePath(String(args.working_directory))
+        : process.cwd();
+    const config = await configManager.getConfig();
+    const timeoutMs = Number(args.timeout_ms || 28000);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 28000) {
+        throw new Error('Remote shell_execute timeout_ms must be between 1 and 28000');
+    }
+    try {
+        const shell = config.defaultShell || undefined;
+        const shellName = shell ? path.basename(shell).toLowerCase() : '';
+        const options = {
+            cwd,
+            timeout: timeoutMs,
+            windowsHide: true,
+            maxBuffer: 1024 * 1024,
+            encoding: 'utf8'
+        };
+        const result = shellName === 'powershell' || shellName === 'powershell.exe' || shellName === 'pwsh' || shellName === 'pwsh.exe'
+            ? await execFileAsync(shell, ['-NoProfile', '-NonInteractive', '-Command', command], options)
+            : await execAsync(command, { ...options, shell });
+        const { stdout, stderr } = result;
+        return {
+            workingDirectoryResolved: cwd,
+            exitCode: 0,
+            stdout,
+            stderr,
+            timedOut: false,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            stdoutSpillPath: null,
+            stderrSpillPath: null
+        };
+    }
+    catch (error) {
+        const timedOut = error?.killed === true && error?.signal;
+        return {
+            workingDirectoryResolved: cwd,
+            exitCode: timedOut ? 124 : Number.isInteger(error?.code) ? error.code : 1,
+            stdout: String(error?.stdout || ''),
+            stderr: String(error?.stderr || error?.message || ''),
+            timedOut: Boolean(timedOut),
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            stdoutSpillPath: null,
+            stderrSpillPath: null
+        };
+    }
+}
+export class GatewayToolAdapter {
+    constructor(desktop, options = {}) {
+        this.desktop = desktop;
+        this.allowedRoots = options.allowedRoots ?? configuredGatewayRoots();
+        this.pathValidator = options.pathValidator ?? validatePath;
+    }
+    async guardPath(requestedPath) {
+        const value = String(requestedPath || '').trim();
+        if (!value)
+            throw new Error('Remote device path/working_directory is required');
+        const candidate = await this.pathValidator(value);
+        if (!this.allowedRoots.length)
+            return candidate;
+        this.canonicalRoots ?? (this.canonicalRoots = Promise.all(this.allowedRoots.map(root => this.pathValidator(root))));
+        const roots = await this.canonicalRoots;
+        if (!roots.some(root => isWithinRoot(candidate, root))) {
+            throw new Error('Remote device path is outside MCP_GATEWAY_ALLOWED_ROOTS');
+        }
+        return candidate;
+    }
+    async imagePreview(args) {
+        const requestedPath = args.path || args.file || args.sourcePath;
+        const filePath = await this.guardPath(requestedPath);
+        const stat = await fs.stat(filePath);
+        if (!stat.isFile())
+            throw new Error('Remote image preview path is not a file');
+        const requestedMaxBytes = Number(args.maxBytes ?? 8 * 1024 * 1024);
+        const maxBytes = Number.isFinite(requestedMaxBytes)
+            ? Math.max(1, Math.min(MAX_REMOTE_IMAGE_SOURCE_BYTES, Math.floor(requestedMaxBytes)))
+            : 8 * 1024 * 1024;
+        if (stat.size > maxBytes)
+            throw new Error(`Remote image source exceeds maxBytes (${stat.size} > ${maxBytes})`);
+        const includeImage = Boolean(args.embed ?? args.includeImage ?? args.includeData ?? true);
+        const source = sharp(filePath, { animated: false, limitInputPixels: 64 * 1024 * 1024 });
+        const metadata = await source.metadata();
+        const text = {
+            ok: true,
+            tool: 'image_preview',
+            summary: includeImage ? 'Loaded bounded remote image preview.' : 'Loaded remote image metadata.',
+            data: {
+                path: filePath,
+                bytes: stat.size,
+                width: metadata.width ?? null,
+                height: metadata.height ?? null,
+                sourceFormat: metadata.format ?? null,
+                mimeType: 'image/webp',
+                embedded: includeImage
+            }
+        };
+        if (!includeImage)
+            return { content: [{ type: 'text', text: JSON.stringify(text) }] };
+        for (const attempt of IMAGE_PREVIEW_ATTEMPTS) {
+            const preview = await sharp(filePath, { animated: false, limitInputPixels: 64 * 1024 * 1024 })
+                .rotate()
+                .resize({ width: attempt.size, height: attempt.size, fit: 'inside', withoutEnlargement: true })
+                .webp({ quality: attempt.quality })
+                .toBuffer();
+            if (preview.length <= MAX_REMOTE_IMAGE_PREVIEW_BYTES) {
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify({ ...text, data: { ...text.data, previewBytes: preview.length } }) },
+                        { type: 'image', data: preview.toString('base64'), mimeType: 'image/webp' }
+                    ]
+                };
+            }
+        }
+        throw new Error(`REMOTE_IMAGE_TOO_LARGE: unable to fit preview within ${MAX_REMOTE_IMAGE_PREVIEW_BYTES} bytes`);
+    }
+    async call(tool, args = {}) {
+        if (tool === 'read_text_file') {
+            if (args.head !== undefined && args.tail !== undefined)
+                throw new Error('Use either head or tail, not both');
+            const mapped = { path: await this.guardPath(args.path) };
+            if (args.head !== undefined) {
+                mapped.offset = 0;
+                mapped.length = Number(args.head);
+            }
+            else if (args.tail !== undefined) {
+                mapped.offset = -Number(args.tail);
+            }
+            return assertSuccess(await this.desktop.callClientTool('read_file', mapped), 'read_file');
+        }
+        if (tool === 'write_file') {
+            return assertSuccess(await this.desktop.callClientTool('write_file', {
+                path: await this.guardPath(args.path),
+                content: args.content,
+                mode: 'rewrite'
+            }), 'write_file');
+        }
+        if (tool === 'edit_file')
+            return await this.editFile({ ...args, path: await this.guardPath(args.path) });
+        if (tool === 'shell_execute')
+            return await runShell({ ...args, working_directory: await this.guardPath(args.working_directory) });
+        if (tool === 'start_process') {
+            const workingDirectory = await this.guardPath(args.working_directory);
+            const result = assertSuccess(await this.desktop.callClientTool('start_process', {
+                command: args.command,
+                timeout_ms: Number(args.timeout_ms || 10000),
+                working_directory: workingDirectory
+            }), 'start_process');
+            return { ...result, pid: parsePid(result), session_id: String(parsePid(result)) };
+        }
+        if (tool === 'read_process_output') {
+            return assertSuccess(await this.desktop.callClientTool('read_process_output', {
+                pid: Number(args.session_id),
+                offset: args.offset,
+                length: args.length,
+                timeout_ms: 5000
+            }), 'read_process_output');
+        }
+        if (tool === 'interact_with_process') {
+            return assertSuccess(await this.desktop.callClientTool('interact_with_process', {
+                pid: Number(args.session_id),
+                input: String(args.input ?? ''),
+                timeout_ms: Number(args.timeout_ms || 8000)
+            }), 'interact_with_process');
+        }
+        if (tool === 'terminate_process') {
+            return assertSuccess(await this.desktop.callClientTool('force_terminate', {
+                pid: Number(args.session_id)
+            }), 'force_terminate');
+        }
+        if (tool === 'image_preview')
+            return await this.imagePreview(args);
+        if (tool === 'project_inspect') {
+            return await inspectProjectOnDevice(await this.guardPath(args.path), args);
+        }
+        throw new Error(`Unsupported gateway capability: ${tool}`);
+    }
+    async editFile(args) {
+        if (typeof args.old_text !== 'string' || args.old_text.length === 0)
+            throw new Error('old_text is required');
+        if (typeof args.new_text !== 'string')
+            throw new Error('new_text is required');
+        const expectedReplacements = Number(args.expected_replacements ?? 1);
+        if (!Number.isInteger(expectedReplacements) || expectedReplacements < 1) {
+            throw new Error('expected_replacements must be a positive integer');
+        }
+        if (args.dry_run === true) {
+            const read = assertSuccess(await this.desktop.callClientTool('read_file', {
+                path: args.path,
+                offset: 0,
+                length: 100000
+            }), 'read_file');
+            const source = textFromResult(read);
+            const count = source.split(args.old_text).length - 1;
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            ok: count === expectedReplacements,
+                            dry_run: true,
+                            expected_replacements: expectedReplacements,
+                            actual_count: count
+                        }) }]
+            };
+        }
+        return assertSuccess(await this.desktop.callClientTool('edit_block', {
+            file_path: args.path,
+            old_string: args.old_text,
+            new_string: args.new_text,
+            expected_replacements: expectedReplacements
+        }), 'edit_block');
+    }
+}

package/dist/device/gateway-url-policy.d.ts

@@ -0,0 +1,3 @@
+export declare function assertSecureGatewayUrl(url: URL): void;
+export declare function gatewaySocketUrl(raw: string): string;
+export declare function gatewayHttpBase(raw: string): string;

package/dist/device/gateway-url-policy.js

@@ -0,0 +1,43 @@
+function isLoopbackHostname(hostname) {
+    const host = String(hostname || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === 'localhost' || host === '::1')
+        return true;
+    const parts = host.split('.');
+    return parts.length === 4 && parts.every(part => /^\d+$/.test(part)) && Number(parts[0]) === 127 && parts.every(part => Number(part) >= 0 && Number(part) <= 255);
+}
+export function assertSecureGatewayUrl(url) {
+    if ((url.protocol === 'http:' || url.protocol === 'ws:') && !isLoopbackHostname(url.hostname)) {
+        throw new Error('Plaintext MCP gateway URLs are allowed only on loopback; use https/wss for non-loopback gateways.');
+    }
+}
+export function gatewaySocketUrl(raw) {
+    const url = new URL(raw);
+    const configuredProtocol = url.protocol;
+    if (url.protocol === 'http:')
+        url.protocol = 'ws:';
+    if (url.protocol === 'https:')
+        url.protocol = 'wss:';
+    if (!['ws:', 'wss:'].includes(url.protocol))
+        throw new Error('MCP_GATEWAY_URL must use http(s) or ws(s)');
+    assertSecureGatewayUrl(url);
+    if (configuredProtocol === 'http:' || configuredProtocol === 'https:' || !url.pathname || url.pathname === '/') {
+        url.pathname = '/device';
+        url.search = '';
+        url.hash = '';
+    }
+    return url.toString();
+}
+export function gatewayHttpBase(raw) {
+    const url = new URL(raw);
+    if (url.protocol === 'ws:')
+        url.protocol = 'http:';
+    if (url.protocol === 'wss:')
+        url.protocol = 'https:';
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('Gateway URL must use http(s) or ws(s).');
+    assertSecureGatewayUrl(url);
+    url.pathname = '/';
+    url.search = '';
+    url.hash = '';
+    return url.toString().replace(/\/$/, '');
+}

package/dist/device/linux-service.d.ts

@@ -0,0 +1,70 @@
+type ExecFileResult = {
+    stdout: string;
+    stderr: string;
+};
+type ExecFileFn = (file: string, args: string[]) => Promise<ExecFileResult>;
+export type LinuxManager = 'systemd' | 'pm2';
+export type LinuxServiceStatus = {
+    installed: boolean;
+    running: boolean;
+    autostart: boolean;
+    manager: LinuxManager;
+};
+export declare function chooseLinuxManager({ ask }?: {
+    ask?: () => Promise<string>;
+}): Promise<LinuxManager>;
+export declare class SystemdUserDeviceService {
+    private platform;
+    private execFile;
+    readonly unitPath: string;
+    private nodePath;
+    private entrypoint;
+    private pathValue;
+    constructor(options?: {
+        platform?: NodeJS.Platform | string;
+        execFile?: ExecFileFn;
+        unitPath?: string;
+        nodePath?: string;
+        entrypoint?: string;
+        pathValue?: string;
+    });
+    private assertLinux;
+    private unitExists;
+    private assertOwnedUnitIfPresent;
+    private unitText;
+    install(): Promise<void>;
+    stop(): Promise<void>;
+    status(): Promise<LinuxServiceStatus>;
+    uninstall(): Promise<void>;
+}
+export declare class Pm2DeviceService {
+    private platform;
+    private execFile;
+    private pm2Path;
+    private nodePath;
+    private entrypoint;
+    private user;
+    private pm2Home;
+    constructor(options?: {
+        platform?: NodeJS.Platform | string;
+        execFile?: ExecFileFn;
+        pm2Path?: string;
+        nodePath?: string;
+        entrypoint?: string;
+        user?: string;
+        pm2Home?: string;
+    });
+    private assertLinux;
+    private processRow;
+    private assertOwnedProcess;
+    private proveStartup;
+    install(): Promise<void>;
+    stop(): Promise<void>;
+    status(): Promise<LinuxServiceStatus>;
+    uninstall(): Promise<void>;
+}
+export declare function discoverLinuxManagers(options?: {
+    systemd?: SystemdUserDeviceService;
+    pm2?: Pm2DeviceService;
+}): Promise<LinuxServiceStatus[]>;
+export {};