@hcu-lab.me/mcp-device 1.0.5 → 1.0.7

package/dist/device/update-helper.cjs

@@ -0,0 +1,343 @@
+'use strict';
+
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+const crypto = require('crypto');
+const net = require('net');
+const { execFile } = require('child_process');
+
+const statePath = process.argv[2];
+const HANDOFF_WAIT_MS = 120000;
+const PID_WAIT_MS = 30000;
+const PACKAGE_UNLOCK_WAIT_MS = 20000;
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function run(file, args) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+    });
+  });
+}
+
+async function exists(filePath) {
+  try { await fsp.access(filePath); return true; } catch { return false; }
+}
+
+async function readState() {
+  return JSON.parse(await fsp.readFile(statePath, 'utf8'));
+}
+
+async function writeState(patch) {
+  const current = await readState();
+  const next = Object.assign({}, current, patch, { updatedAt: Date.now() });
+  const tmp =
+    statePath + '.' + process.pid + '.' + Date.now() + '.' +
+    crypto.randomBytes(6).toString('hex') + '.tmp';
+  await fsp.writeFile(tmp, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  await fsp.rename(tmp, statePath);
+  try { await fsp.chmod(statePath, 0o600); } catch {}
+  return next;
+}
+
+function isAlive(pid) {
+  if (!pid || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForFile(filePath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await exists(filePath)) return true;
+    await sleep(100);
+  }
+  return await exists(filePath);
+}
+
+async function waitForPids(pids, timeoutMs) {
+  const filtered = pids.filter(pid => Number.isInteger(pid) && pid > 0);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (filtered.every(pid => !isAlive(pid))) return true;
+    await sleep(100);
+  }
+  return filtered.every(pid => !isAlive(pid));
+}
+
+async function stopManager(state) {
+  if (state.managerKind === 'windows-task') {
+    // The update helper runs in a separate task, so ending the original device
+    // task cannot terminate the helper itself. "not running" is harmless.
+    await run(state.schtasksPath, ['/End', '/TN', state.windowsTaskName]).catch(() => {});
+  } else if (state.managerKind === 'systemd') {
+    await run(state.systemctlPath, ['--user', 'stop', state.systemdUnit]);
+  } else if (state.managerKind === 'pm2') {
+    await run(state.pm2Path, ['stop', state.pm2Name]);
+  }
+}
+
+async function startWindowsRunner(state) {
+  if (state.managerKind === 'windows-task') {
+    await run(state.schtasksPath, ['/Run', '/TN', state.windowsTaskName]);
+    return;
+  }
+
+  const escapePs = value => "'" + String(value).replace(/'/g, "''") + "'";
+  const command =
+    'Start-Process -FilePath ' + escapePs(state.powershellPath) +
+    " -ArgumentList @('-NoProfile','-ExecutionPolicy','Bypass','-WindowStyle','Hidden','-File'," +
+    escapePs(state.windowsRunnerPath) + ') -WindowStyle Hidden';
+  await run(state.powershellPath, ['-NoProfile', '-NonInteractive', '-Command', command]);
+}
+
+async function startManager(state) {
+  if (String(state.managerKind).startsWith('windows-')) {
+    await startWindowsRunner(state);
+    return;
+  }
+  if (state.managerKind === 'systemd') {
+    await run(state.systemctlPath, ['--user', 'start', state.systemdUnit]);
+    return;
+  }
+  if (state.managerKind === 'pm2') {
+    await run(state.pm2Path, ['restart', state.pm2Name]);
+    await run(state.pm2Path, ['save']);
+    return;
+  }
+  throw new Error('Unsupported manager kind: ' + state.managerKind);
+}
+
+async function renameWithRetry(source, target, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      await fsp.rename(source, target);
+      return;
+    } catch (error) {
+      lastError = error;
+      const code = String(error && error.code || '');
+      if (!['EBUSY', 'EPERM', 'EACCES', 'ENOTEMPTY'].includes(code)) throw error;
+      await sleep(150);
+    }
+  }
+  throw lastError || new Error('Timed out waiting for package directory to unlock.');
+}
+
+async function packageVersion(packageRoot) {
+  try {
+    const manifest = JSON.parse(await fsp.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    return String(manifest.version || '');
+  } catch {
+    return '';
+  }
+}
+
+async function assertRuntimeOwnerReleased(state) {
+  const controlPath = String(state.runtimeOwnerControlPath || '');
+  if (!controlPath) {
+    const failure = new Error('Runtime owner control path is missing from update state.');
+    failure.code = 'DEVICE_UPDATE_RUNTIME_OWNER_UNVERIFIED';
+    throw failure;
+  }
+  let control;
+  try {
+    control = JSON.parse(await fsp.readFile(controlPath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return;
+    const failure = new Error('Unable to verify MCP Device runtime ownership release.');
+    failure.code = 'DEVICE_UPDATE_RUNTIME_OWNER_UNVERIFIED';
+    throw failure;
+  }
+
+  const endpoint = String(control && control.endpoint || '');
+  if (!endpoint) {
+    const failure = new Error('Runtime owner control state has no endpoint; refusing package replacement.');
+    failure.code = 'DEVICE_UPDATE_RUNTIME_OWNER_UNVERIFIED';
+    throw failure;
+  }
+
+  const active = await new Promise(resolve => {
+    const socket = net.createConnection(endpoint);
+    let data = '';
+    let settled = false;
+    let connected = false;
+    const finish = value => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setEncoding('utf8');
+    socket.setTimeout(800, () => finish(connected));
+    socket.once('error', () => finish(false));
+    socket.on('data', chunk => { data += chunk; });
+    socket.once('end', () => {
+      try {
+        const parsed = JSON.parse(data);
+        finish(parsed && parsed.ok === true && parsed.status && parsed.status.product === 'MCP Device');
+      } catch {
+        // A live endpoint with an unreadable response is not safe to replace.
+        finish(true);
+      }
+    });
+    socket.once('connect', () => {
+      connected = true;
+      socket.write(JSON.stringify({ action: 'status' }) + '\n');
+    });
+  });
+
+  if (active) {
+    const failure = new Error('A live MCP Device runtime owner still exists; refusing package replacement.');
+    failure.code = 'DEVICE_UPDATE_RUNTIME_OWNER_ACTIVE';
+    throw failure;
+  }
+
+  // A stale control file is harmless. Do not delete it here: a new owner could
+  // have acquired the endpoint between checks, and RuntimeOwner owns cleanup.
+}
+
+async function restoreRollback(state) {
+  if (await exists(state.rollbackPath)) {
+    await fsp.rm(state.packageRoot, { recursive: true, force: true }).catch(() => {});
+    await fsp.rename(state.rollbackPath, state.packageRoot);
+  } else {
+    const current = await packageVersion(state.packageRoot);
+    if (current === state.fromVersion) return;
+    if (!await exists(state.rollbackSnapshot)) {
+      throw new Error('Offline rollback package is unavailable.');
+    }
+    await fsp.rm(state.packageRoot, { recursive: true, force: true }).catch(() => {});
+    await fsp.cp(state.rollbackSnapshot, state.packageRoot, {
+      recursive: true,
+      force: true,
+      preserveTimestamps: true
+    });
+  }
+
+  const restored = await packageVersion(state.packageRoot);
+  if (restored !== state.fromVersion) {
+    throw new Error('Rollback package verification failed: expected ' + state.fromVersion + ', got ' + (restored || 'unknown') + '.');
+  }
+}
+
+async function cleanupWindowsUpdateTask(state) {
+  if (!state.windowsUpdateTaskName || !state.schtasksPath) return;
+  await run(state.schtasksPath, ['/Delete', '/F', '/TN', state.windowsUpdateTaskName]).catch(() => {});
+}
+
+async function main() {
+  let state = await readState();
+
+  try {
+    if (!await waitForFile(state.handoffPath, HANDOFF_WAIT_MS)) {
+      const error = new Error('Timed out waiting for MCP Device update handoff.');
+      error.code = 'DEVICE_UPDATE_HANDOFF_TIMEOUT';
+      throw error;
+    }
+
+    state = await writeState({ state: 'quiescing' });
+    await stopManager(state);
+
+    if (!await waitForPids([state.parentPid, state.childPid], PID_WAIT_MS)) {
+      const error = new Error('MCP Device parent/child did not exit before update.');
+      error.code = 'DEVICE_UPDATE_RUNTIME_STILL_ALIVE';
+      throw error;
+    }
+
+    await assertRuntimeOwnerReleased(state);
+
+    if (await exists(state.rollbackPath)) {
+      const error = new Error('Rollback path already exists; refusing to overwrite recovery evidence.');
+      error.code = 'DEVICE_UPDATE_ROLLBACK_PRESENT';
+      throw error;
+    }
+
+    await renameWithRetry(state.packageRoot, state.rollbackPath, PACKAGE_UNLOCK_WAIT_MS);
+    state = await writeState({ state: 'installing' });
+
+    await run(state.nodePath, [
+      state.npmCliPath,
+      'install',
+      '-g',
+      state.targetTarball,
+      '--offline',
+      '--cache', state.cacheDir,
+      '--prefix', state.globalPrefix,
+      '--no-audit',
+      '--no-fund'
+    ]);
+
+    const actual = await packageVersion(state.packageRoot);
+    if (actual !== state.targetVersion) {
+      const error = new Error('Installed target verification failed: expected ' + state.targetVersion + ', got ' + (actual || 'unknown') + '.');
+      error.code = 'DEVICE_UPDATE_VERIFY_FAILED';
+      throw error;
+    }
+
+    state = await writeState({
+      state: 'installed_waiting_reconnect',
+      completedAt: Date.now(),
+      errorCode: null,
+      message: null
+    });
+
+    await startManager(state);
+    await cleanupWindowsUpdateTask(state);
+    process.exit(0);
+  } catch (error) {
+    const code = String(error && error.code || 'DEVICE_UPDATE_FAILED').slice(0, 64);
+    const message = String(error && error.message || error).slice(0, 240);
+
+    try {
+      state = await writeState({ state: 'rollback', errorCode: code, message });
+      await restoreRollback(state);
+      state = await writeState({
+        state: 'failed',
+        completedAt: Date.now(),
+        errorCode: code,
+        message
+      });
+
+      // Never create a second runtime while any tracked process or owner is
+      // still alive. If quiescence failed, preserve bounded failure evidence
+      // and leave the original runtime as the only authority.
+      const trackedRuntimeAlive = [state.parentPid, state.childPid]
+        .filter(pid => Number.isInteger(pid) && pid > 0)
+        .some(isAlive);
+      if (!trackedRuntimeAlive) {
+        try {
+          await assertRuntimeOwnerReleased(state);
+          await startManager(state);
+        } catch {
+          // Failure state remains durable for the next safe/manual recovery.
+        }
+      }
+    } catch (rollbackError) {
+      await writeState({
+        state: 'failed',
+        completedAt: Date.now(),
+        errorCode: 'DEVICE_UPDATE_ROLLBACK_FAILED',
+        message: String(rollbackError && rollbackError.message || rollbackError).slice(0, 240)
+      }).catch(() => {});
+    }
+
+    await cleanupWindowsUpdateTask(state).catch(() => {});
+    process.exit(1);
+  }
+}
+
+main().catch(() => process.exit(1));

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

@@ -9,6 +9,7 @@ export declare function buildWindowsRunnerScript(options: {
     allowedRoots?: string;
     nodePath: string;
     entrypoint: string;
+    runtimeDir?: string;
 }): string;
 export type WindowsDeviceServiceStatus = {
     installed: boolean;
@@ -21,24 +22,22 @@ export declare class WindowsDeviceService {
     private platform;
     private execFile;
     private runnerPath;
-    private legacyRunnerPath;
     private nodePath;
     private entrypoint;
+    private runtimeDir;
     constructor(options?: {
         platform?: NodeJS.Platform | string;
         execFile?: ExecFileFn;
         runnerPath?: string;
-        legacyRunnerPath?: string;
         nodePath?: string;
         entrypoint?: string;
+        runtimeDir?: string;
     });
     private assertWindows;
     private runnerExists;
     private hasUserRunEntry;
     private scheduledTaskState;
     private deleteRegistrations;
-    private commandReferencesLegacyRunner;
-    private deleteVerifiedLegacyRegistrations;
     private createAutostartRegistration;
     private startUserProcess;
     private userProcessRunning;

package/dist/device/windows-service.js

@@ -21,12 +21,11 @@ function isMissingRegistrationError(error) {
 export function buildWindowsTaskName(deviceId) {
     return `MCP-Device-${taskSafeDeviceId(deviceId)}`;
 }
-function legacyWindowsTaskName(deviceId) {
-    return `HCU-Device-${taskSafeDeviceId(deviceId)}`;
-}
 export function buildWindowsRunnerScript(options) {
+    const runtimeDir = options.runtimeDir ? String(options.runtimeDir) : deviceStatePaths().runtime;
     return [
         "$ErrorActionPreference = 'Stop'",
+        `Set-Location -LiteralPath ${psQuote(runtimeDir)}`,
         `& ${psQuote(options.nodePath)} ${psQuote(options.entrypoint)} --service`,
         'exit $LASTEXITCODE',
         ''
@@ -40,9 +39,9 @@ export class WindowsDeviceService {
             return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
         });
         this.runnerPath = path.resolve(options.runnerPath || path.join(deviceStatePaths().root, 'run-device.ps1'));
-        this.legacyRunnerPath = path.resolve(options.legacyRunnerPath || path.join(deviceStatePaths().legacyRoot, 'run-device.ps1'));
         this.nodePath = path.resolve(options.nodePath || process.execPath);
         this.entrypoint = path.resolve(options.entrypoint || process.argv[1]);
+        this.runtimeDir = options.runtimeDir ? String(options.runtimeDir) : deviceStatePaths().runtime;
     }
     assertWindows() {
         if (this.platform !== 'win32')
@@ -91,41 +90,6 @@ export class WindowsDeviceService {
         }
         catch { /* absent is fine */ }
     }
-    commandReferencesLegacyRunner(value) {
-        const normalize = (text) => String(text || '').replace(/\//g, '\\').toLowerCase();
-        return normalize(value).includes(normalize(this.legacyRunnerPath));
-    }
-    async deleteVerifiedLegacyRegistrations(taskName) {
-        let scheduledAction = null;
-        try {
-            const command = `(Get-ScheduledTask -TaskName ${psQuote(taskName)} -ErrorAction Stop).Actions | ForEach-Object { ($_.Execute + ' ' + $_.Arguments) }`;
-            scheduledAction = String((await this.execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command])).stdout || '');
-        }
-        catch { /* absent scheduled task is fine */ }
-        if (scheduledAction !== null && this.commandReferencesLegacyRunner(scheduledAction)) {
-            try {
-                await this.execFile('schtasks.exe', ['/Delete', '/F', '/TN', taskName]);
-            }
-            catch (error) {
-                if (!isMissingRegistrationError(error))
-                    throw error;
-            }
-        }
-        let runValue = null;
-        try {
-            runValue = String((await this.execFile('reg.exe', ['query', USER_RUN_KEY, '/v', taskName])).stdout || '');
-        }
-        catch { /* absent Run value is fine */ }
-        if (runValue !== null && this.commandReferencesLegacyRunner(runValue)) {
-            try {
-                await this.execFile('reg.exe', ['delete', USER_RUN_KEY, '/v', taskName, '/f']);
-            }
-            catch (error) {
-                if (!isMissingRegistrationError(error))
-                    throw error;
-            }
-        }
-    }
     async createAutostartRegistration(taskName) {
         const taskAction = `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "${this.runnerPath}"`;
         try {
@@ -157,13 +121,12 @@ export class WindowsDeviceService {
     async install(options) {
         this.assertWindows();
         const taskName = buildWindowsTaskName(options.deviceId);
-        const legacyTaskName = legacyWindowsTaskName(options.deviceId);
         const existing = await this.status(options.deviceId).catch(() => null);
         const preserveManual = existing?.installed === true && existing.autostart === false;
-        const runner = buildWindowsRunnerScript({ nodePath: this.nodePath, entrypoint: this.entrypoint });
+        const runner = buildWindowsRunnerScript({ nodePath: this.nodePath, entrypoint: this.entrypoint, runtimeDir: this.runtimeDir });
+        await fs.mkdir(this.runtimeDir, { recursive: true, mode: 0o700 });
         await fs.mkdir(path.dirname(this.runnerPath), { recursive: true });
         await fs.writeFile(this.runnerPath, runner, { mode: 0o600 });
-        await this.deleteVerifiedLegacyRegistrations(legacyTaskName);
         if (preserveManual) {
             await this.deleteRegistrations(taskName);
             return;
@@ -226,13 +189,11 @@ export class WindowsDeviceService {
     async uninstall(deviceId) {
         this.assertWindows();
         const taskName = buildWindowsTaskName(deviceId);
-        const legacyTaskName = legacyWindowsTaskName(deviceId);
         try {
             await this.stop(deviceId);
         }
         catch { /* registration cleanup remains authoritative; runtime is never PID-killed. */ }
         await this.deleteRegistrations(taskName);
-        await this.deleteVerifiedLegacyRegistrations(legacyTaskName);
         await fs.rm(this.runnerPath, { force: true });
     }
 }

package/dist/handlers/filesystem-handlers.js

@@ -53,6 +53,9 @@ export async function handleReadFile(args) {
     }
     const readFileOperation = async () => {
         const parsed = ReadFileArgsSchema.parse(args);
+        if (process.env.MCP_DEVICE_REMOTE === 'true' && parsed.isUrl) {
+            return createErrorResponse('REMOTE_URL_READ_DISABLED: URL reads are disabled for MCP Device remote execution.');
+        }
         // Get the configuration for file read limits
         const config = await configManager.getConfig();
         if (!config) {

package/dist/index.js

@@ -38,9 +38,13 @@ async function runServer() {
             deferLog('info', 'Loading configuration...');
             await configManager.loadConfig();
             deferLog('info', 'Configuration loaded successfully');
-            // Initialize feature flags (non-blocking)
-            deferLog('info', 'Initializing feature flags...');
-            await featureFlagManager.initialize();
+            // Remote MCP Device children must not depend on legacy host
+            // feature flags or cached A/B state. Their execution surface is fixed by
+            // GatewayToolAdapter and remote-mode behavior must be deterministic.
+            if (process.env.MCP_DEVICE_REMOTE !== 'true') {
+                deferLog('info', 'Initializing feature flags...');
+                await featureFlagManager.initialize();
+            }
         }
         catch (configError) {
             deferLog('error', `Failed to load configuration: ${configError instanceof Error ? configError.message : String(configError)}`);

package/dist/npm-scripts/remote.d.ts

@@ -1,3 +1,8 @@
+import { GatewayDeviceIdentity } from '../device/gateway-identity.js';
 import { GatewayDeviceStatusStore } from '../device/device-status.js';
 export declare function applyServiceCommandStatus(store: GatewayDeviceStatusStore, command: 'install' | 'start' | 'stop' | 'uninstall'): Promise<void>;
+export declare function resolvePairingIdentity(identity: GatewayDeviceIdentity, options?: {
+    forcePair?: boolean;
+    probeCurrentIdentity?: () => Promise<void>;
+}): Promise<import("../device/gateway-identity.js").GatewayIdentityRecord>;
 export declare function runRemote(): Promise<void>;

package/dist/npm-scripts/remote.js

@@ -111,13 +111,32 @@ async function withBootstrapOwner(action, allowTakeover = true) {
         await owner.release();
     }
 }
+export async function resolvePairingIdentity(identity, options = {}) {
+    const current = await identity.loadOrCreate();
+    if (!options.forcePair || deviceIdentityNeedsPairing(current))
+        return current;
+    if (typeof options.probeCurrentIdentity !== 'function') {
+        throw new Error('Current device identity probe is required before forced pairing.');
+    }
+    try {
+        await options.probeCurrentIdentity();
+        return current;
+    }
+    catch (error) {
+        if (String(error?.code || '') !== 'DEVICE_FORGOTTEN')
+            throw error;
+        await identity.forget();
+        return await identity.loadOrCreate();
+    }
+}
 async function ensureLinkedDeviceUnderOwner(forcePair = false) {
     const store = new GatewayDeviceStatusStore();
     const current = await store.load();
     const config = await captureGatewayConfigFromEnvironment(new GatewayDeviceConfigStore(), { fallbackGatewayUrl: current.gatewayUrl });
     const gatewayUrl = String(config.gatewayUrl || '').trim();
     const identity = new GatewayDeviceIdentity();
-    const record = await identity.loadOrCreate();
+    let record = await identity.loadOrCreate();
+    const initialDeviceId = record.deviceId;
     await store.update({
         gatewayUrl,
         deviceId: record.deviceId,
@@ -130,6 +149,36 @@ async function ensureLinkedDeviceUnderOwner(forcePair = false) {
     const proxy = createGatewayProxyAgent(config);
     let channel;
     try {
+        record = await resolvePairingIdentity(identity, {
+            forcePair,
+            probeCurrentIdentity: async () => {
+                const probe = new GatewayDeviceChannel({
+                    gatewayUrl,
+                    identity,
+                    proxyAgent: proxy.agent,
+                    securityProtocolFloor: config.securityProtocolFloor,
+                    appCaPem: config.appCaPem || undefined,
+                    adapter: controlAdapter(),
+                    agentVersion: process.env.npm_package_version
+                });
+                try {
+                    await probe.start();
+                }
+                finally {
+                    await probe.stop().catch(() => { });
+                }
+            }
+        });
+        if (record.deviceId !== initialDeviceId) {
+            await store.update({
+                gatewayUrl,
+                deviceId: record.deviceId,
+                deviceName: os.hostname(),
+                identityPresent: true,
+                account: { connected: false, label: null },
+                connection: { ...current.connection, online: false }
+            });
+        }
         const pairing = await pairGatewayDevice({ gatewayUrl, identity, proxyAgent: proxy.agent, deviceName: os.hostname() });
         await store.update({
             gatewayUrl,
@@ -276,8 +325,6 @@ async function serviceCommand(command) {
 }
 export async function runRemote() {
     // MCP Device owns its account-scoped usage telemetry at the gateway.
-    // Never send inherited Desktop Commander analytics from the remote execution path.
-    process.env.DESKTOP_COMMANDER_DISABLE_TELEMETRY = 'true';
     const disableNoSleep = process.argv.includes('--disable-no-sleep');
     const verbose = process.argv.includes('--debug');
     if (!verbose)