mecord-connect 1.0.0

package/runtime/app/apps/local-agent/src/main.js

@@ -0,0 +1,311 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AuditLog } from '../../../src/core/audit.js';
+import { DeviceIdentityStore } from '../../../src/core/device-identity.js';
+import { DeviceRegistryStore } from '../../../src/core/device-registry.js';
+import { TaskStore } from '../../../src/core/task-store.js';
+import { createRuntime } from './runtime-factory.js';
+import { createLocalAgentServer } from './server.js';
+import { EmergencyStopStore } from './emergency-stop.js';
+import { ApprovalStore } from './approval-store.js';
+import { LocalPrivacyDataStore } from './privacy-data.js';
+import { LocalAgentRelayRunner } from './relay-agent.js';
+import { windowsBootstrapProtector } from './bootstrap-config.js';
+import { RelaySessionCredentialManager, deriveRelayDeviceResetUrl, deriveRelaySessionRotateUrl } from './relay-session-credentials.js';
+import { LocalDeviceResetCoordinator } from './device-reset.js';
+import { OperatorError } from '../../../src/core/errors.js';
+import { RelayEnrollmentClient } from './relay-enrollment.js';
+import { PUBLIC_PLUGIN_CAPABILITIES } from '../../../src/core/public-plugin-surface.js';
+import { TaskOrchestrator } from '../../../src/core/task-orchestrator.js';
+import { evidence } from '../../../src/core/evidence.js';
+
+const allowedRoots = (process.env.OPERATOR_ALLOWED_ROOTS ?? process.cwd())
+  .split(path.delimiter)
+  .filter(Boolean)
+  .map((root) => path.resolve(root));
+
+// This allowlist is used only by commands explicitly declared in the trusted
+// Operator project-command registry outside project roots. Generic terminal
+// execution has a separate, empty-by-default allowlist below.
+const allowedExecutables = (process.env.OPERATOR_ALLOWED_EXECUTABLES ?? 'git,node,npm,npx,pnpm,python,python3')
+  .split(',')
+  .map((item) => item.trim())
+  .filter(Boolean);
+
+const terminalAllowedExecutables = (process.env.OPERATOR_TERMINAL_ALLOWED_EXECUTABLES ?? '')
+  .split(',')
+  .map((item) => item.trim())
+  .filter(Boolean);
+
+const token = process.env.OPERATOR_AGENT_TOKEN;
+if (!token || token.length < 32) {
+  console.error('[operator] OPERATOR_AGENT_TOKEN must be set to a secret of at least 32 characters.');
+  process.exit(2);
+}
+
+const recoveryToken = process.env.OPERATOR_RECOVERY_TOKEN;
+if (recoveryToken !== undefined && recoveryToken.length < 32) {
+  console.error('[operator] OPERATOR_RECOVERY_TOKEN must be at least 32 characters when set.');
+  process.exit(2);
+}
+
+const stateDir = path.resolve(process.env.OPERATOR_STATE_DIR ?? path.join(os.homedir(), '.operator'));
+const emergencyStop = new EmergencyStopStore(stateDir);
+const approvals = new ApprovalStore(stateDir);
+const audit = new AuditLog(stateDir);
+const tasks = new TaskStore(stateDir);
+const deviceIdentity = new DeviceIdentityStore(stateDir);
+const deviceRegistry = new DeviceRegistryStore(stateDir);
+const privacy = new LocalPrivacyDataStore(stateDir);
+const browserAutoLaunch = process.env.OPERATOR_BROWSER_AUTO_LAUNCH !== '0';
+const relayUrl = process.env.OPERATOR_RELAY_URL?.trim();
+const relayResultUrl = process.env.OPERATOR_RELAY_RESULT_URL?.trim();
+const relayTokenFile = path.resolve(process.env.OPERATOR_RELAY_SESSION_TOKEN_FILE?.trim() || path.join(stateDir, 'relay-session.token'));
+const relayAllowInsecureLoopback = process.env.OPERATOR_RELAY_ALLOW_INSECURE_LOOPBACK === '1';
+const relayRequired = process.env.OPERATOR_RELAY_REQUIRED === '1';
+const pairUrlBase = process.env.OPERATOR_PAIR_URL_BASE?.trim();
+let pairUrl                 ;
+if (pairUrlBase) {
+  pairUrl = new URL(pairUrlBase);
+  if (pairUrl.protocol !== 'https:' || pairUrl.username || pairUrl.password || pairUrl.hash || pairUrl.search || pairUrl.pathname !== '/pair') {
+    throw new OperatorError('PAIR_URL_INVALID', 'Device pairing URL must be credential-free HTTPS ending exactly at /pair.');
+  }
+}
+if (relayRequired && !relayUrl) {
+  throw new OperatorError('RELAY_REQUIRED_CONFIGURATION_MISSING', 'Relay-only mode requires an explicit relay URL.');
+}
+
+const runtime = createRuntime({
+  stateDir,
+  allowedRoots,
+  allowedExecutables,
+  terminalAllowedExecutables,
+  projectCommandRegistryPath: process.env.OPERATOR_PROJECT_COMMAND_REGISTRY,
+  dockerExecutable: process.env.OPERATOR_DOCKER_PATH,
+  postgresProfileRegistryPath: process.env.OPERATOR_POSTGRES_PROFILE_REGISTRY,
+  psqlExecutable: process.env.OPERATOR_PSQL_PATH,
+  vscodeExecutable: process.env.OPERATOR_VSCODE_PATH,
+  vscodeDataDir: process.env.OPERATOR_VSCODE_DATA_DIR,
+  cdpEndpoint: process.env.OPERATOR_CDP_ENDPOINT,
+  browserAutoLaunch,
+  browserPath: process.env.OPERATOR_BROWSER_PATH,
+  browserDataDir: process.env.OPERATOR_BROWSER_DATA_DIR,
+  windowsUiaPath: process.env.OPERATOR_WINDOWS_UIA_PATH,
+  windowsPathLeasePath: process.env.OPERATOR_WINDOWS_PATH_LEASE_PATH
+});
+let relayRunner                               = null;
+let relayRun                       = null;
+let relaySessionCredentials                                       = null;
+let localAgentBaseUrl = '';
+let shuttingDown = false;
+
+function stopRelay()       {
+  relayRunner?.stop();
+}
+
+async function failRequiredRelay(error         )                {
+  if (!relayRequired || shuttingDown) return;
+  shuttingDown = true;
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[operator] required relay failed: ${message}`);
+  stopRelay();
+  await Promise.allSettled([agent.close(), runtime.close()]);
+  process.exitCode = 1;
+  setImmediate(() => process.exit(1));
+}
+
+function startRelay()       {
+  if (!relayUrl || shuttingDown || relayRun) return;
+  const enrollment = new RelayEnrollmentClient({
+    relayUrl, resultUrl: relayResultUrl, identity: deviceIdentity,
+    allowLoopbackInsecure: relayAllowInsecureLoopback,
+    onUserCode: ({ userCode, expiresAt }) => {
+      console.error(`[operator] device pairing code: ${userCode} (expires ${expiresAt})`);
+      if (pairUrl) {
+        const url = new URL(pairUrl);
+        url.searchParams.set('code', userCode);
+        console.error(`[operator] pair this device: ${url.toString()}`);
+      }
+    }
+  });
+  const sessionCredentials = new RelaySessionCredentialManager({
+    stateDir,
+    legacyTokenFile: relayTokenFile,
+    rotateUrl: deriveRelaySessionRotateUrl(relayUrl, relayResultUrl, relayAllowInsecureLoopback),
+    protector: windowsBootstrapProtector(),
+    allowLoopbackInsecure: relayAllowInsecureLoopback,
+    enrollment,
+    onBackgroundRefreshFailure: () => relayRunner?.reconnect()
+  });
+  relaySessionCredentials = sessionCredentials;
+  relayRunner = new LocalAgentRelayRunner({
+    stateDir,
+    relayUrl,
+    resultUrl: relayResultUrl,
+    sessionTokenFile: relayTokenFile,
+    sessionCredentials,
+    identity: deviceIdentity,
+    localAgentBaseUrl,
+    agentToken: token,
+    getSupportedCapabilities: () => runtime.supportedCapabilities(PUBLIC_PLUGIN_CAPABILITIES),
+    allowLoopbackInsecure: relayAllowInsecureLoopback
+  });
+  const runner = relayRunner;
+  relayRun = runner.run()
+    .then(async () => {
+      if (relayRequired && !shuttingDown) {
+        await failRequiredRelay(new OperatorError('RELAY_REQUIRED_STOPPED', 'The required relay connection stopped.'));
+      }
+    })
+    .catch(async (error) => {
+      console.error(`[operator] relay connection stopped: ${error instanceof Error ? error.message : String(error)}`);
+      await failRequiredRelay(error);
+    })
+    .finally(() => {
+      runner.stop();
+      if (relayRunner === runner) relayRunner = null;
+      if (relaySessionCredentials === sessionCredentials) relaySessionCredentials = null;
+      relayRun = null;
+    });
+}
+
+async function resetLocalDevice() {
+  const coordinator = new LocalDeviceResetCoordinator({
+    stateDir,
+    identity: deviceIdentity,
+    resetUrl: relayUrl ? deriveRelayDeviceResetUrl(relayUrl, relayResultUrl, relayAllowInsecureLoopback) : undefined,
+    getResetToken: relayUrl ? async () => {
+      const credentials = relaySessionCredentials;
+      if (!credentials) throw new OperatorError('DEVICE_RESET_RELAY_UNAVAILABLE', 'Relay session credentials are not active; start Operator and retry device reset.');
+      return await credentials.forReset();
+    } : undefined,
+    stopRelay: async () => {
+      stopRelay();
+      const activeRun = relayRun;
+      if (activeRun) await activeRun;
+    }
+  });
+  return await coordinator.reset();
+}
+
+const permissions = {
+  allowedCapabilities: ['computer.inspect', 'project.inspect', 'project.command.*', 'project.transaction.*', 'docker.*', 'postgres.*', 'vscode.*', 'file.*', 'git.*', 'terminal.execute', 'browser.inspect', 'browser.navigate', 'browser.interact', 'app.inspect', 'app.operate'],
+  allowedRoots,
+  allowExternalWrites: false,
+  allowSystemChanges: false,
+  allowDestructive: false
+};
+const taskOrchestrator = new TaskOrchestrator({
+  runtime,
+  store: tasks,
+  permissions,
+  executeAction: async (action, actionPermissions) => {
+    if ((await emergencyStop.status()).engaged) {
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: 'policy',
+        evidence: [evidence('emergency_stop', 'fail', 'Operator execution is disabled by the local emergency stop.')],
+        error: { code: 'EMERGENCY_STOPPED', message: 'Operator execution is disabled by the local emergency stop.', retryable: false },
+        durationMs: 0
+      };
+    }
+    const result = await runtime.execute(action, actionPermissions);
+    await audit.append({
+      taskId: action.taskId,
+      capability: action.capability,
+      target: action.target,
+      result: result.ok ? 'success' : result.provider === 'policy' ? 'blocked' : 'failure',
+      risk: action.risk,
+      details: { actionId: action.id, provider: result.provider, durationMs: result.durationMs, errorCode: result.error?.code }
+    });
+    return result;
+  }
+});
+
+const agent = createLocalAgentServer({
+  runtime,
+  token,
+  recoveryToken,
+  emergencyStop,
+  approvals,
+  audit,
+  tasks,
+  taskOrchestrator,
+  deviceIdentity,
+  deviceRegistry,
+  privacy,
+  deviceReset: resetLocalDevice,
+  onEmergencyStop: () => stopRelay(),
+  onEmergencyClear: () => {
+    try { startRelay(); }
+    catch (error) { console.error(`[operator] relay reconnect after emergency recovery failed: ${error instanceof Error ? error.message : String(error)}`); }
+  },
+  settings: {
+    recoveryConfigured: Boolean(recoveryToken),
+    browserAutoLaunch,
+    cdpEndpointConfigured: Boolean(process.env.OPERATOR_CDP_ENDPOINT),
+    browserPathConfigured: Boolean(process.env.OPERATOR_BROWSER_PATH),
+    projectCommandRegistryConfigured: Boolean(process.env.OPERATOR_PROJECT_COMMAND_REGISTRY),
+    dockerConfigured: Boolean(process.env.OPERATOR_DOCKER_PATH),
+    postgresConfigured: Boolean(process.env.OPERATOR_POSTGRES_PROFILE_REGISTRY),
+    vscodeConfigured: Boolean(process.env.OPERATOR_VSCODE_PATH),
+    windowsUiaConfigured: Boolean(process.env.OPERATOR_WINDOWS_UIA_PATH),
+    relayConfigured: Boolean(relayUrl),
+    relayResultConfigured: Boolean(relayResultUrl),
+    relayTokenFileConfigured: Boolean(relayUrl),
+    authorizedRootCount: allowedRoots.length,
+    projectExecutableAllowlistCount: allowedExecutables.length,
+    terminalExecutableAllowlistCount: terminalAllowedExecutables.length
+  },
+  permissions
+});
+
+const host = process.env.OPERATOR_AGENT_HOST ?? '127.0.0.1';
+const port = Number(process.env.OPERATOR_AGENT_PORT ?? 47100);
+const bound = await agent.listen(host, port);
+localAgentBaseUrl = relayUrl ? `http://${loopbackAddressForBoundHost(bound.host)}:${bound.port}` : '';
+console.error(`[operator] local agent listening on http://${bound.host}:${bound.port}`);
+console.error(`[operator] authorized roots: ${allowedRoots.join(', ')}`);
+console.error(`[operator] protected state directory: ${stateDir}`);
+console.error(`[operator] recovery API: ${recoveryToken ? 'configured' : 'disabled until OPERATOR_RECOVERY_TOKEN is set'}`);
+console.error(`[operator] generic terminal: ${terminalAllowedExecutables.length ? 'explicit allowlist configured' : 'disabled by default'}`);
+console.error(`[operator] relay: ${relayUrl ? 'configured' : 'disabled'}`);
+if (relayUrl) {
+  const relayCapabilities = await runtime.supportedCapabilities(PUBLIC_PLUGIN_CAPABILITIES);
+  console.error(`[operator] relay capabilities: ${relayCapabilities.join(', ') || 'none'}`);
+}
+
+const emergencyStatus = await emergencyStop.status();
+if (relayUrl && emergencyStatus.engaged) {
+  if (relayRequired) {
+    await failRequiredRelay(new OperatorError(
+      'RELAY_REQUIRED_EMERGENCY_STOP',
+      'The required relay cannot start while the local emergency stop is engaged.'
+    ));
+  }
+} else if (relayUrl) {
+  try { startRelay(); }
+  catch (error) {
+    console.error(`[operator] relay startup failed: ${error instanceof Error ? error.message : String(error)}`);
+    await failRequiredRelay(error);
+  }
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']         ) {
+  process.on(signal, async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    stopRelay();
+    await Promise.allSettled([relayRun, agent.close(), runtime.close()].filter(Boolean)                           );
+    process.exit(0);
+  });
+}
+
+function loopbackAddressForBoundHost(hostInput        )         {
+  const host = hostInput.toLowerCase().replace(/^\[|\]$/g, '');
+  if (host === '::1' || host === '::') return '[::1]';
+  if (host === '0.0.0.0') return '127.0.0.1';
+  if (host === 'localhost' || host === '127.0.0.1') return host;
+  throw new Error('Relay integration requires the local agent to bind to loopback or a wildcard interface so it can re-enter through the local policy boundary.');
+}

package/runtime/app/apps/local-agent/src/privacy-data.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+                                                                     
+
+                                        
+                                                                  
+                
+                  
+                   
+                     
+ 
+
+const MAX_COUNTED_ENTRIES = 10_000;
+
+export class LocalPrivacyDataStore {
+  #stateDir        ;
+
+  constructor(stateDir        ) {
+    this.#stateDir = path.resolve(stateDir);
+  }
+
+  async inventory()                                   {
+    return [
+      await this.#status('activity', ['audit.ndjson', 'audit-head.json', 'provider-learning.json'], true),
+      await this.#status('tasks', ['tasks', 'task-leases'], true),
+      await this.#status('session-state', ['relay-client.json', 'device-sessions.json', 'relay-session.token'], true),
+      await this.#status('device-identity', ['device-identity.json'], false),
+      await this.#status('pairing-state', ['device-registry.json', 'device-routing.json'], false)
+    ];
+  }
+
+  async purge(category                 )                                                                                       {
+    const before = (await this.inventory()).find((item) => item.category === category);
+    if (!before) throw new Error('Unknown privacy category.');
+    const targets = category === 'activity'
+      ? ['audit.ndjson', 'audit-head.json', 'provider-learning.json']
+      : category === 'tasks'
+        ? ['tasks', 'task-leases']
+        : ['relay-client.json', 'device-sessions.json', 'relay-session.token'];
+
+    for (const relative of targets) {
+      const target = this.#target(relative);
+      await this.#assertSafeKnownTarget(target);
+    }
+    for (const relative of targets) {
+      const target = this.#target(relative);
+      await fs.rm(target, { recursive: true, force: true });
+    }
+    return { category, removedBytes: before.bytes, removedEntries: before.entries };
+  }
+
+  async #status(category                                   , relatives          , deletable         )                                 {
+    let bytes = 0;
+    let entries = 0;
+    for (const relative of relatives) {
+      const counted = await countKnownPath(this.#target(relative));
+      bytes += counted.bytes;
+      entries += counted.entries;
+      if (entries > MAX_COUNTED_ENTRIES) throw new Error('Privacy inventory exceeds the bounded entry count.');
+    }
+    return { category, bytes, entries, present: entries > 0, deletable };
+  }
+
+  #target(relative        )         {
+    const target = path.resolve(this.#stateDir, relative);
+    const rel = path.relative(this.#stateDir, target);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) throw new Error('Privacy data target escaped the Operator state directory.');
+    return target;
+  }
+
+  async #assertSafeKnownTarget(target        )                {
+    try {
+      const stat = await fs.lstat(target);
+      if (stat.isSymbolicLink()) throw new Error('Privacy data target must not be a symbolic link.');
+      if (stat.isDirectory()) await assertTreeHasNoSymlinks(target, 0);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return;
+      throw error;
+    }
+  }
+}
+
+async function countKnownPath(target        )                                              {
+  try {
+    const stat = await fs.lstat(target);
+    if (stat.isSymbolicLink()) throw new Error('Privacy inventory refuses symbolic links.');
+    if (stat.isFile()) return { bytes: stat.size, entries: 1 };
+    if (!stat.isDirectory()) return { bytes: 0, entries: 1 };
+    return await countDirectory(target, 0);
+  } catch (error) {
+    if ((error                         ).code === 'ENOENT') return { bytes: 0, entries: 0 };
+    throw error;
+  }
+}
+
+async function countDirectory(dir        , seen        )                                              {
+  let bytes = 0;
+  let entries = 1;
+  const names = await fs.readdir(dir);
+  for (const name of names) {
+    if (seen + entries > MAX_COUNTED_ENTRIES) throw new Error('Privacy inventory exceeds the bounded entry count.');
+    const child = path.join(dir, name);
+    const stat = await fs.lstat(child);
+    if (stat.isSymbolicLink()) throw new Error('Privacy inventory refuses symbolic links.');
+    if (stat.isDirectory()) {
+      const nested = await countDirectory(child, seen + entries);
+      bytes += nested.bytes;
+      entries += nested.entries;
+    } else {
+      bytes += stat.size;
+      entries += 1;
+    }
+  }
+  return { bytes, entries };
+}
+
+async function assertTreeHasNoSymlinks(dir        , seen        )                  {
+  let count = seen;
+  for (const name of await fs.readdir(dir)) {
+    count += 1;
+    if (count > MAX_COUNTED_ENTRIES) throw new Error('Privacy deletion exceeds the bounded entry count.');
+    const child = path.join(dir, name);
+    const stat = await fs.lstat(child);
+    if (stat.isSymbolicLink()) throw new Error('Privacy deletion refuses symbolic links.');
+    if (stat.isDirectory()) count = await assertTreeHasNoSymlinks(child, count);
+  }
+  return count;
+}