@mechasm/cli 0.0.0-stage → 0.1.0

package/src/service.js

@@ -0,0 +1,460 @@
+import { createServer, createConnection, connect } from 'node:net';
+import { chmod, mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { timingSafeEqual, randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { cliConfigDirectory, createCliClient, CliError, apiUrl as validateApiUrl } from './api-client.js';
+import { approvedLocalPorts } from './local-approvals.js';
+import { startFrpClient } from './frp.js';
+import { acquireUpdateGuard, verifyUpdateGuard } from './update-guard.js';
+
+const socketPath = () => process.platform === 'win32'
+  ? `\\\\.\\pipe\\mechasm-${process.env.USERNAME || 'user'}`
+  : join(cliConfigDirectory(), 'service.sock');
+const lockPath = () => join(cliConfigDirectory(), 'service.lock');
+const keyPath = () => join(cliConfigDirectory(), 'service.key');
+
+async function ipcKey() {
+  try {
+    const key = await readFile(keyPath());
+    if (key.length !== 32) throw new CliError('Local IPC key is invalid.');
+    return key;
+  }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const key = randomBytes(32);
+    let file;
+    try {
+      file = await open(keyPath(), 'wx', 0o600);
+      await file.writeFile(key);
+      await file.sync();
+      return key;
+    } catch (writeError) {
+      if (writeError.code !== 'EEXIST') throw writeError;
+      for (let attempt = 0; attempt < 20; attempt++) {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        try {
+          const saved = await readFile(keyPath());
+          if (saved.length === 32) return saved;
+        } catch (readError) { if (readError.code !== 'ENOENT') throw readError; }
+      }
+      throw new CliError('Could not read local IPC key.');
+    } finally { await file?.close(); }
+  }
+}
+
+export async function serviceStart(rawApiUrl) {
+  const apiUrl = validateApiUrl(rawApiUrl).origin;
+  const deadline = Date.now() + 30_000;
+  let startupGuard;
+  while (!startupGuard) {
+    try {
+      startupGuard = await acquireUpdateGuard();
+    } catch (error) {
+      if (!error.message.includes('startup or update is already in progress')) throw error;
+      const state = await serviceStatus();
+      if (state.running && state.apiUrl) {
+        if (state.apiUrl !== apiUrl) throw new CliError(`Local service already uses ${state.apiUrl}.`);
+        return state;
+      }
+      if (Date.now() >= deadline) throw error;
+      await delay(100);
+    }
+  }
+  try {
+  const current = await serviceStatus();
+  if (current.running) {
+    if (current.apiUrl !== apiUrl) throw new CliError(`Local service already uses ${current.apiUrl}.`);
+    return current;
+  }
+  await mkdir(cliConfigDirectory(), { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') await chmod(cliConfigDirectory(), 0o700);
+  await ipcKey();
+  const script = fileURLToPath(new URL('../bin/mechasm.js', import.meta.url));
+  const child = spawn(process.execPath, [script, 'service', 'foreground', '--api-url', apiUrl, '--startup-guard-token', startupGuard.token], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, MECHASM_STARTUP_GUARD_TOKEN: startupGuard.token },
+  });
+  child.unref();
+  const startDeadline = Date.now() + 30_000;
+  while (Date.now() < startDeadline) {
+    const state = await serviceCall('status').catch(() => null);
+    if (state?.lastError) throw new CliError(state.lastError);
+    if (state?.running && state.lastHeartbeatAt) {
+      if (state.apiUrl !== apiUrl) throw new CliError(`Local service already uses ${state.apiUrl}.`);
+      return state;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new CliError('Local service did not start. Run `mechasm service foreground` to see its error.');
+  } finally {
+    await startupGuard.release();
+  }
+}
+
+export async function serviceStatus() {
+  try {
+    return await serviceCall('status');
+  } catch {
+    try {
+      const lock = JSON.parse(await readFile(lockPath(), 'utf8'));
+      return await lockIsAlive(lock)
+        ? { running: true, lastError: 'Local service is running but not responding.' }
+        : { running: false };
+    } catch {
+      return { running: false };
+    }
+  }
+}
+
+export async function serviceStop() {
+  return await serviceCall('stop').catch(() => ({ stopped: true }));
+}
+
+function serviceCall(action) {
+  return new Promise(async (resolve, reject) => {
+    let key;
+    try { key = await ipcKey(); } catch (error) { reject(error); return; }
+    const connection = createConnection(socketPath());
+    let response = '';
+    const timeout = setTimeout(() => connection.destroy(new Error('Local service request timed out.')), 3000);
+    connection.once('connect', () => connection.write(`${JSON.stringify({ action, key: key.toString('base64url') })}\n`));
+    connection.on('data', (chunk) => {
+      response += chunk;
+      if (Buffer.byteLength(response) > 4096) connection.destroy(new Error('Local service response too large.'));
+    });
+    connection.once('error', (error) => { clearTimeout(timeout); reject(error); });
+    connection.once('end', () => {
+      clearTimeout(timeout);
+      try { resolve(JSON.parse(response)); } catch { reject(new Error('Invalid local service response.')); }
+    });
+  });
+}
+
+function pidIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+}
+
+async function processStartTime(pid) {
+  if (process.platform !== 'linux') return null;
+  try {
+    const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+    return stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/)[19] || null;
+  } catch { return null; }
+}
+
+async function lockIsAlive(lock) {
+  if (!pidIsAlive(lock?.pid)) return false;
+  if (typeof lock.processStartTime !== 'string') return true;
+  const currentStartTime = await processStartTime(lock.pid);
+  return !currentStartTime || currentStartTime === lock.processStartTime;
+}
+
+async function acquireLock() {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const file = await open(lockPath(), 'wx', 0o600);
+      await file.writeFile(JSON.stringify({ pid: process.pid, processStartTime: await processStartTime(process.pid) }));
+      await file.sync();
+      await file.close();
+      return;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let lock;
+      try { lock = JSON.parse(await readFile(lockPath(), 'utf8')); }
+      catch {
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        try { lock = JSON.parse(await readFile(lockPath(), 'utf8')); } catch { /* stale or incomplete lock */ }
+      }
+      if (await lockIsAlive(lock)) throw new CliError('Local service is already running.');
+      if (!Number.isInteger(lock?.pid) || lock.pid < 1) {
+        const info = await stat(lockPath()).catch(() => null);
+        if (info && Date.now() - info.mtimeMs < 5000) throw new CliError('Local service is starting.');
+      }
+      await rm(lockPath(), { force: true });
+    }
+  }
+  throw new CliError('Could not acquire local service lock.');
+}
+
+export async function runServiceForeground(rawApiUrl, startupGuardToken) {
+  let startupGuard;
+  if (startupGuardToken) await verifyUpdateGuard(startupGuardToken);
+  else startupGuard = await acquireUpdateGuard();
+  let released = false;
+  const releaseStartupGuard = async () => {
+    if (startupGuard && !released) {
+      released = true;
+      await startupGuard.release();
+    }
+  };
+  try {
+    return await runServiceForegroundInner(rawApiUrl, releaseStartupGuard);
+  } finally {
+    await releaseStartupGuard();
+  }
+}
+
+async function runServiceForegroundInner(rawApiUrl, onReady) {
+  const apiUrl = validateApiUrl(rawApiUrl).origin;
+  const client = createCliClient(apiUrl);
+  const identity = (await client.whoami()).data;
+  await mkdir(cliConfigDirectory(), { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') await chmod(cliConfigDirectory(), 0o700);
+  const key = await ipcKey();
+  await acquireLock();
+  const path = socketPath();
+  if (process.platform !== 'win32') await rm(path, { force: true });
+  const state = {
+    running: true,
+    apiUrl,
+    deviceId: identity.deviceId,
+    startedAt: new Date().toISOString(),
+    lastHeartbeatAt: null,
+    lastError: null,
+  };
+  const active = new Map();
+  let stopped = false;
+  let serverClosed = false;
+  const pollController = new AbortController();
+  let retryDelay = 1000;
+  let lastErrorSource = null;
+  const closeActive = async () => {
+    await Promise.allSettled([...active.values()].map((item) => item.process.stop()));
+    active.clear();
+  };
+  const server = createServer((connection) => {
+    let buffer = '';
+    const timer = setTimeout(() => connection.destroy(), 3000);
+    connection.on('data', async (chunk) => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer) > 4096) { connection.destroy(); return; }
+      const end = buffer.indexOf('\n');
+      if (end < 0) return;
+      clearTimeout(timer);
+      let request;
+      try { request = JSON.parse(buffer.slice(0, end)); }
+      catch { connection.end(`${JSON.stringify({ error: 'Invalid request' })}\n`); return; }
+      const supplied = Buffer.from(String(request.key || ''), 'base64url');
+      if (supplied.length !== key.length || !timingSafeEqual(supplied, key)) {
+        connection.end(`${JSON.stringify({ error: 'Unauthorized' })}\n`);
+        return;
+      }
+      if (request.action === 'stop') {
+        stopped = true;
+        state.running = false;
+        pollController.abort();
+        void closeActive();
+        if (!serverClosed) { serverClosed = true; server.close(); }
+      }
+      connection.end(`${JSON.stringify({ ...state, stopped: request.action === 'stop' })}\n`);
+    });
+    connection.once('close', () => clearTimeout(timer));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(path, resolve);
+  }).catch(async (error) => { await rm(lockPath(), { force: true }); throw error; });
+  if (process.platform !== 'win32') await chmod(path, 0o600);
+  await onReady();
+  const stop = () => {
+    stopped = true;
+    state.running = false;
+    pollController.abort();
+    if (!serverClosed) { serverClosed = true; server.close(); }
+  };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    while (!stopped) {
+      let operation = 'heartbeat';
+      try {
+        await client.localHeartbeat(undefined, pollController.signal);
+        state.lastHeartbeatAt = new Date().toISOString();
+        if (lastErrorSource?.type === 'heartbeat') {
+          state.lastError = null;
+          lastErrorSource = null;
+        }
+        operation = 'lease';
+        for (const [leaseId, item] of active) {
+          if (stopped) break;
+          try {
+            await client.heartbeatLocalLease(leaseId, undefined, pollController.signal);
+            const remote = await client.getLocalLease(leaseId, undefined, pollController.signal);
+            if (remote?.status !== 'active' || item.process.child.exitCode !== null || item.process.child.signalCode !== null) {
+              await item.process.stop();
+              active.delete(leaseId);
+            }
+          } catch (error) {
+            if (error.name === 'AbortError' && stopped) break;
+            if (error.exitCode === 3 || error.apiCode === 'user_unavailable') throw error;
+            if (error.apiCode === 'lease_closed') {
+              if (lastErrorSource?.type === 'lease' && lastErrorSource.leaseId === leaseId) {
+                state.lastError = null;
+                lastErrorSource = null;
+              }
+              await item.process.stop();
+              active.delete(leaseId);
+              continue;
+            }
+            state.lastError = `Lease ${leaseId}: ${error.message}`;
+            lastErrorSource = { type: 'lease', leaseId };
+            await item.process.stop();
+            active.delete(leaseId);
+          }
+        }
+        operation = 'poll';
+        const response = await client.nextLocalLease(undefined, pollController.signal);
+        const lease = response.data;
+        if (response.status === 200 && lease?.leaseId && !active.has(lease.leaseId)) {
+          try {
+            await startLocalLease(client, apiUrl, state.deviceId, lease, active, state, pollController.signal);
+          } catch (error) {
+            if (error.name === 'AbortError' && stopped) break;
+            if (error.exitCode === 3 || error.apiCode === 'user_unavailable') throw error;
+            state.lastError = `Lease ${lease.leaseId}: ${error.message}`;
+            lastErrorSource = { type: 'lease', leaseId: lease.leaseId };
+            try {
+              await client.closeLocalLease(lease.leaseId);
+            } catch (closeError) {
+              if (closeError.exitCode === 3 || closeError.apiCode === 'user_unavailable') throw closeError;
+            }
+          }
+          retryDelay = 1000;
+        } else if (response.status === 204) retryDelay = 1000;
+      } catch (error) {
+        if (error.name === 'AbortError' && stopped) break;
+        state.lastError = error.message;
+        lastErrorSource = { type: operation };
+        await closeActive();
+        if (error.exitCode === 3 || error.exitCode === 4) {
+          stopped = true;
+          state.running = false;
+          if (!serverClosed) { serverClosed = true; server.close(); }
+        } else if (!stopped) {
+          try { await delay(retryDelay, undefined, { signal: pollController.signal }); }
+          catch { if (stopped) break; }
+          retryDelay = Math.min(30_000, retryDelay * 2);
+        }
+      }
+    }
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+    state.running = false;
+    pollController.abort();
+    await closeActive();
+    if (!serverClosed) server.close();
+    if (process.platform !== 'win32') await rm(path, { force: true });
+    await rm(lockPath(), { force: true });
+  }
+}
+
+async function startLocalLease(client, origin, deviceId, lease, active, state, signal) {
+  const leaseId = lease.leaseId;
+  if (typeof lease.projectId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(lease.projectId) ||
+      typeof leaseId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(leaseId)) {
+    throw new CliError('Local run lease has invalid project or lease ID.');
+  }
+  if (lease.deviceId !== deviceId) throw new CliError('Local run lease targets another device.');
+  if (!Array.isArray(lease.ports) || !lease.ports.length || lease.ports.length > 16 ||
+      lease.ports.some((port) => !Number.isInteger(port) || port < 1 || port > 65535) || new Set(lease.ports).size !== lease.ports.length) {
+    throw new CliError('Local run lease has invalid ports.');
+  }
+  const approved = await approvedLocalPorts(origin, lease.projectId, deviceId);
+  if (!approved || lease.ports.some((port) => !approved.ports.includes(port))) {
+    throw new CliError(`Run lease requests a port without local approval for project ${lease.projectId}.`);
+  }
+  const localIPs = await Promise.all(lease.ports.map((port) => chooseLoopbackAddress(port, approved.preferredLocalIP, signal)));
+  const relay = lease.relay;
+  const invalidRelayFields = [];
+  if (!relay || relay.role !== 'client') invalidRelayFields.push('role');
+  if (relay?.user !== leaseId) invalidRelayFields.push('user');
+  if (typeof relay?.serverAddr !== 'string' || !/^[A-Za-z0-9.:[\]-]+$/.test(relay.serverAddr)) invalidRelayFields.push('serverAddr');
+  const serverPort = relay?.serverPort;
+  if (!Number.isInteger(serverPort) || serverPort < 1 || serverPort > 65535) invalidRelayFields.push('serverPort');
+  if (typeof relay?.serverName !== 'string' || !/^[A-Za-z0-9.-]{1,253}$/.test(relay.serverName)) invalidRelayFields.push('serverName');
+  if (typeof relay?.trustedCaPem !== 'string' || relay.trustedCaPem.length > 32768 || !relay.trustedCaPem.includes('-----BEGIN CERTIFICATE-----')) invalidRelayFields.push('trustedCaPem');
+  if (typeof relay?.credential !== 'string' || relay.credential.length < 16 || relay.credential.length > 4096) invalidRelayFields.push('credential');
+  if (invalidRelayFields.length) throw new CliError(`Local run lease has invalid relay fields: ${invalidRelayFields.join(', ')}.`);
+  const executorId = lease.executorId;
+  const proxyRows = relay.proxies;
+  const idSuffix = leaseId.replaceAll('-', '');
+  if (typeof executorId !== 'string' || !executorId || !Array.isArray(proxyRows) || proxyRows.length !== lease.ports.length ||
+      proxyRows.some((proxy, index) => proxy?.name !== `ml_${idSuffix}_${lease.ports[index]}` || proxy.type !== 'stcp' ||
+        proxy.localIP !== '127.0.0.1' || proxy.localPort !== lease.ports[index] ||
+        !Array.isArray(proxy.allowUsers) || proxy.allowUsers.length !== 1 || proxy.allowUsers[0] !== executorId ||
+        typeof proxy.secretKey !== 'string' || proxy.secretKey.length < 16 || proxy.secretKey.length > 4096)) {
+    throw new CliError('Local run lease has invalid loopback proxies.');
+  }
+  const config = {
+    user: relay.user,
+    auth: { method: 'token', token: '' },
+    serverAddr: relay.serverAddr,
+    serverPort,
+    loginFailExit: true,
+    metadatas: { lease_id: leaseId, role: relay.role, credential: relay.credential },
+    transport: { tls: { serverName: relay.serverName } },
+    proxies: proxyRows.map((proxy, index) => ({
+      name: proxy.name,
+      type: 'stcp',
+      secretKey: proxy.secretKey,
+      localIP: localIPs[index],
+      localPort: proxy.localPort,
+      allowUsers: [executorId],
+    })),
+  };
+  const process = await startFrpClient(config, relay.trustedCaPem, signal);
+  if (signal?.aborted) { await process.stop(); return; }
+  active.set(leaseId, { process, projectId: lease.projectId, runId: lease.runId });
+  try {
+    await readyLocalLease(client, leaseId, signal);
+    if (signal?.aborted) throw Object.assign(new Error('Tunnel start cancelled.'), { name: 'AbortError' });
+    state.lastError = null;
+  } catch (error) {
+    active.delete(leaseId);
+    await process.stop();
+    throw error;
+  }
+}
+
+async function readyLocalLease(client, leaseId, signal) {
+  const deadline = Date.now() + 5000;
+  while (true) {
+    try {
+      return await client.readyLocalLease(leaseId, undefined, signal);
+    } catch (error) {
+      if (error.apiCode !== 'tunnel_not_ready' || Date.now() >= deadline) throw error;
+      await delay(100, undefined, { signal });
+    }
+  }
+}
+
+async function chooseLoopbackAddress(port, preferred, signal) {
+  const candidates = [preferred, preferred === '127.0.0.1' ? '::1' : '127.0.0.1'];
+  for (const host of candidates) {
+    if (signal?.aborted) throw Object.assign(new Error('Tunnel start cancelled.'), { name: 'AbortError' });
+    const reachable = await new Promise((resolve) => {
+      const socket = connect({ host, port });
+      const onAbort = () => finish(false);
+      const finish = (value) => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        socket.destroy();
+        resolve(value);
+      };
+      const timer = setTimeout(() => finish(false), 500);
+      socket.once('connect', () => finish(true));
+      socket.once('error', () => finish(false));
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+    if (reachable) return host;
+  }
+  throw new CliError(`Approved local port ${port} is not listening on 127.0.0.1 or ::1.`);
+}

package/src/update-guard.js

@@ -0,0 +1,74 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cliConfigDirectory, CliError } from './api-client.js';
+
+const guardPath = () => join(cliConfigDirectory(), 'update-start.lock');
+
+function pidIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+}
+
+export async function acquireUpdateGuard() {
+  await mkdir(cliConfigDirectory(), { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') await chmod(cliConfigDirectory(), 0o700);
+  const token = randomBytes(24).toString('base64url');
+  let file;
+  let acquired = false;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      file = await open(guardPath(), 'wx', 0o600);
+      await file.writeFile(JSON.stringify({ token, pid: process.pid }));
+      await file.sync();
+      acquired = true;
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        await rm(guardPath(), { force: true });
+        throw error;
+      }
+      let existingPid = 0;
+      try { existingPid = JSON.parse(await readFile(guardPath(), 'utf8')).pid; } catch { /* incomplete lock */ }
+      const info = await stat(guardPath()).catch(() => null);
+      if (pidIsAlive(existingPid) || (info && Date.now() - info.mtimeMs < 5000)) {
+        throw new CliError('A service startup or update is already in progress.');
+      }
+      await rm(guardPath(), { force: true });
+    } finally {
+      await file?.close();
+      file = null;
+    }
+  }
+  if (!acquired) throw new CliError('Could not acquire service startup/update lock.');
+  return {
+    token,
+    async release() {
+      try {
+        const saved = JSON.parse(await readFile(guardPath(), 'utf8')).token;
+        const expected = Buffer.from(token);
+        const actual = Buffer.from(String(saved));
+        if (actual.length === expected.length && timingSafeEqual(actual, expected)) {
+          await rm(guardPath(), { force: true });
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    },
+  };
+}
+
+export async function verifyUpdateGuard(token) {
+  try {
+    const saved = JSON.parse(await readFile(guardPath(), 'utf8')).token;
+    const expected = Buffer.from(String(saved));
+    const actual = Buffer.from(String(token));
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+      throw new CliError('Service startup guard is invalid.');
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new CliError('Service startup guard expired.');
+    throw error;
+  }
+}

package/src/version.js

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const packagePath = fileURLToPath(new URL('../package.json', import.meta.url));
+export const CLI_VERSION = JSON.parse(readFileSync(packagePath, 'utf8')).version;