mecord-connect 1.0.0

package/runtime/app/apps/local-agent/src/relay-session-credentials.js

@@ -0,0 +1,436 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+                                                                                  
+import { OperatorError } from '../../../src/core/errors.js';
+import { readDurableStateText, writeDurableStateText } from '../../../src/core/durable-state.js';
+
+const MAX_TOKEN_BYTES = 16 * 1024;
+const MAX_STATE_BYTES = 128 * 1024;
+const DEFAULT_REFRESH_SKEW_MS = 60_000;
+const RETRY_REFRESH_MS = 10_000;
+const MIN_REMAINING_MS = 5_000;
+const MAX_SESSION_LIFETIME_MS = 30 * 60_000;
+
+const LEGACY_TOKEN_OPTIONS = {
+  maxBytes: MAX_TOKEN_BYTES,
+  errorCode: 'RELAY_SESSION_TOKEN_FILE_INVALID',
+  invalidMessage: 'Relay session token file is invalid.'
+}         ;
+
+                         
+             
+                    
+               
+                                         
+                             
+    
+  
+
+                                          
+                            
+               
+ 
+
+                                                 
+                                   
+                                
+               
+ 
+
+                                                       
+                   
+                          
+                    
+                                   
+                                  
+                         
+                           
+                     
+                                       
+                                          
+ 
+
+                      
+              
+                    
+                      
+  
+
+                         
+                
+                          
+  
+
+export class RelaySessionCredentialManager                                           {
+  #stateFile        ;
+  #legacyTokenFile        ;
+  #rotateUrl        ;
+  #protector                       ;
+  #refreshSkewMs        ;
+  #fetch              ;
+  #clock            ;
+  #enrollment                          ;
+  #onBackgroundRefreshFailure             ;
+  #timer                        = null;
+  #queue                = Promise.resolve();
+  #stopped = false;
+
+  constructor(options                                      ) {
+    this.#stateFile = path.join(path.resolve(options.stateDir), 'relay-session-credential.json');
+    this.#legacyTokenFile = path.resolve(options.legacyTokenFile);
+    this.#rotateUrl = validateRotateUrl(options.rotateUrl, Boolean(options.allowLoopbackInsecure));
+    this.#protector = options.protector;
+    if (this.#protector.scheme !== 'windows-dpapi-current-user') {
+      throw new OperatorError('RELAY_SESSION_PROTECTOR_INVALID', 'Relay session credentials require the Windows DPAPI CurrentUser protector.');
+    }
+    const refreshSkewMs = Number(options.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS);
+    if (!Number.isInteger(refreshSkewMs) || refreshSkewMs < 5_000 || refreshSkewMs > 5 * 60_000) {
+      throw new OperatorError('RELAY_SESSION_REFRESH_CONFIG_INVALID', 'Relay session refresh skew is invalid.');
+    }
+    this.#refreshSkewMs = refreshSkewMs;
+    this.#fetch = options.fetchImpl ?? fetch;
+    this.#clock = options.clock ?? (() => new Date());
+    this.#enrollment = options.enrollment;
+    this.#onBackgroundRefreshFailure = options.onBackgroundRefreshFailure;
+  }
+
+  async forConnection()                  { return await this.#freshToken(); }
+  async forReset()                  {
+    const token = await this.#exclusive(async () => {
+      let current = await this.#loadOrMigrate(true);
+      if (current.metadata.expiresAtMs <= this.#clock().getTime()) current = await this.#enrollAndPersist();
+      return current.token;
+    });
+    this.stop();
+    return token;
+  }
+  async forRequest()                  {
+    return await this.#exclusive(async () => {
+      const current = await this.#loadOrMigrate(false);
+      const now = this.#clock().getTime();
+      if (current.metadata.expiresAtMs <= now) {
+        throw new OperatorError('RELAY_SESSION_REENROLL_REQUIRED', 'Relay session expired before the result could be submitted.', { retryable: false });
+      }
+      this.#schedule(current.metadata.expiresAtMs);
+      return current.token;
+    });
+  }
+
+  stop()       {
+    this.#stopped = true;
+    this.#enrollment?.stop();
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+
+  async #freshToken()                  {
+    return await this.#exclusive(async () => {
+      let current = await this.#loadOrMigrate(true);
+      const now = this.#clock().getTime();
+      if (current.metadata.expiresAtMs <= now) {
+        if (!this.#enrollment) throw new OperatorError('RELAY_SESSION_REENROLL_REQUIRED', 'Relay session expired before it could be refreshed.', { retryable: false });
+        current = await this.#enrollAndPersist();
+      }
+      if (current.metadata.expiresAtMs - now <= this.#refreshSkewMs) {
+        try {
+          current = await this.#rotate(current);
+        } catch (error) {
+          if (error instanceof OperatorError && error.code === 'RELAY_SESSION_REENROLL_REQUIRED' && this.#enrollment) {
+            current = await this.#enrollAndPersist();
+            this.#schedule(current.metadata.expiresAtMs);
+            return current.token;
+          }
+          const remaining = current.metadata.expiresAtMs - this.#clock().getTime();
+          if (!(error instanceof OperatorError) || !error.retryable || remaining <= MIN_REMAINING_MS) throw error;
+          this.#scheduleRetry(current.metadata.expiresAtMs);
+          return current.token;
+        }
+      }
+      this.#schedule(current.metadata.expiresAtMs);
+      return current.token;
+    });
+  }
+
+  async #loadOrMigrate(allowEnrollment         )                            {
+    try { return await this.#loadProtected(); }
+    catch (error) {
+      if ((error                         ).code !== 'ENOENT') throw error;
+    }
+    let token        ;
+    try { token = await readRelaySessionTokenFile(this.#legacyTokenFile); }
+    catch (error) {
+      if (allowEnrollment && this.#enrollment && error instanceof OperatorError && error.code === 'RELAY_SESSION_TOKEN_FILE_MISSING') {
+        return await this.#enrollAndPersist();
+      }
+      throw error;
+    }
+    const metadata = parseTokenMetadata(token);
+    await this.#persist(token, metadata);
+    await fs.rm(this.#legacyTokenFile, { force: true });
+    return { token, metadata };
+  }
+
+  async #enrollAndPersist()                            {
+    if (!this.#enrollment) throw new OperatorError('RELAY_SESSION_REENROLL_REQUIRED', 'Relay session requires device enrollment.', { retryable: false });
+    const token = validateTokenText(await this.#enrollment.enroll());
+    const metadata = parseTokenMetadata(token);
+    if (metadata.expiresAtMs <= this.#clock().getTime()) throw new OperatorError('DEVICE_ENROLLMENT_SESSION_INVALID', 'Device enrollment returned an expired session credential.');
+    await this.#persist(token, metadata);
+    return { token, metadata };
+  }
+
+  async #loadProtected()                            {
+    const text = await readDurableStateText(this.#stateFile, {
+      maxBytes: MAX_STATE_BYTES,
+      errorCode: 'RELAY_SESSION_CREDENTIAL_INVALID',
+      invalidMessage: 'Protected relay session credential state is invalid.'
+    });
+    let stored                  ;
+    try { stored = validateStoredCredential(JSON.parse(text)); }
+    catch (error) {
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential state could not be parsed.');
+    }
+    const ciphertext = decodeCiphertext(stored.protection.ciphertextBase64);
+    let plaintext                    ;
+    try {
+      plaintext = await this.#protector.unprotect(ciphertext);
+      const token = validateTokenText(plaintext.toString('utf8'));
+      const metadata = parseTokenMetadata(token);
+      if (metadata.expiresAt !== stored.expiresAt) throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session expiry metadata does not match its token.');
+      return { token, metadata };
+    } finally {
+      ciphertext.fill(0);
+      plaintext?.fill(0);
+    }
+  }
+  async #rotate(current                  )                            {
+    let response          ;
+    try {
+      response = await this.#fetch(this.#rotateUrl, {
+        method: 'POST',
+        redirect: 'error',
+        headers: { authorization: `Bearer ${current.token}` },
+        signal: AbortSignal.timeout(15_000)
+      });
+    } catch (error) {
+      throw new OperatorError('RELAY_SESSION_REFRESH_FAILED', `Relay session refresh request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+    }
+    let body      = null;
+    try { body = await response.json(); } catch { /* safe generic handling below */ }
+    if (response.status !== 200) {
+      const code = String(body?.error?.code ?? 'RELAY_SESSION_REFRESH_FAILED');
+      const retryable = response.status === 408 || response.status === 429 || response.status >= 500;
+      if (response.status === 401) throw new OperatorError('RELAY_SESSION_REENROLL_REQUIRED', 'Relay session authority is no longer refreshable.', { retryable: false });
+      throw new OperatorError(code, `Relay session refresh failed with HTTP ${response.status}.`, { retryable });
+    }
+    const token = validateTokenText(body?.session?.token);
+    const metadata = parseTokenMetadata(token);
+    if (token === current.token || metadata.jti === current.metadata.jti || metadata.expiresAtMs <= this.#clock().getTime()) {
+      throw new OperatorError('RELAY_SESSION_REFRESH_INVALID', 'Relay returned an invalid replacement session.', { retryable: false });
+    }
+    await this.#persist(token, metadata);
+    return { token, metadata };
+  }
+
+  async #persist(token        , metadata               )                {
+    const plaintext = Buffer.from(token, 'utf8');
+    let ciphertext                    ;
+    try {
+      ciphertext = await this.#protector.protect(plaintext);
+      const stored                   = {
+        version: 1,
+        expiresAt: metadata.expiresAt,
+        protection: {
+          scheme: 'windows-dpapi-current-user',
+          ciphertextBase64: ciphertext.toString('base64')
+        }
+      };
+      await writeDurableStateText(this.#stateFile, JSON.stringify(stored, null, 2), {
+        maxBytes: MAX_STATE_BYTES,
+        errorCode: 'RELAY_SESSION_CREDENTIAL_INVALID',
+        invalidMessage: 'Protected relay session credential state is invalid.'
+      });
+    } finally {
+      plaintext.fill(0);
+      ciphertext?.fill(0);
+    }
+  }
+
+  #schedule(expiresAtMs        )       {
+    if (this.#stopped) return;
+    if (this.#timer) clearTimeout(this.#timer);
+    const delay = Math.max(1_000, expiresAtMs - this.#clock().getTime() - this.#refreshSkewMs);
+    this.#timer = setTimeout(() => { void this.#refreshFromTimer(); }, delay);
+    this.#timer.unref();
+  }
+
+  #scheduleRetry(expiresAtMs        )       {
+    if (this.#stopped) return;
+    if (this.#timer) clearTimeout(this.#timer);
+    const remaining = expiresAtMs - this.#clock().getTime() - MIN_REMAINING_MS;
+    if (remaining <= 0) return;
+    const delay = Math.max(1_000, Math.min(RETRY_REFRESH_MS, remaining));
+    this.#timer = setTimeout(() => { void this.#refreshFromTimer(); }, delay);
+    this.#timer.unref();
+  }
+
+  async #refreshFromTimer()                {
+    try { await this.#freshToken(); }
+    catch {
+      if (this.#stopped) return;
+      try { this.#onBackgroundRefreshFailure?.(); } catch { /* liveness callback is best-effort */ }
+    }
+  }
+
+  async #exclusive   (operation                  )             {
+    let release             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { release = resolve; });
+    await previous;
+    try { return await operation(); }
+    finally { release(); }
+  }
+}
+
+export async function readRelaySessionTokenFile(fileInput        )                  {
+  const file = path.resolve(fileInput);
+  let raw        ;
+  try { raw = await readDurableStateText(file, LEGACY_TOKEN_OPTIONS); }
+  catch (error) {
+    if ((error                         ).code === 'ENOENT') {
+      throw new OperatorError('RELAY_SESSION_TOKEN_FILE_MISSING', 'Relay session token file is missing.', { retryable: true });
+    }
+    if (error instanceof OperatorError) throw error;    throw new OperatorError('RELAY_SESSION_TOKEN_FILE_INVALID', 'Relay session token file could not be read.', {
+      retryable: false,
+      details: { cause: String(error) }
+    });
+  }
+  return validateTokenText(raw.trim());
+}
+
+function validateStoredCredential(input         )                   {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential state is invalid.');
+  }
+  const raw = input                           ;
+  if (raw.version !== 1 || !raw.protection || typeof raw.protection !== 'object' || Array.isArray(raw.protection)) {
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential state is invalid.');
+  }
+  const protection = raw.protection                           ;
+  if (protection.scheme !== 'windows-dpapi-current-user') {
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential scheme is invalid.');
+  }
+  const expiresAt = validIso(String(raw.expiresAt ?? ''), 'credential expiry');
+  const ciphertextBase64 = String(protection.ciphertextBase64 ?? '');
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(ciphertextBase64) || ciphertextBase64.length > MAX_STATE_BYTES) {
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential ciphertext is invalid.');
+  }
+  return { version: 1, expiresAt, protection: { scheme: 'windows-dpapi-current-user', ciphertextBase64 } };
+}
+function decodeCiphertext(value        )         {
+  let decoded        ;
+  try { decoded = Buffer.from(value, 'base64'); }
+  catch { throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential ciphertext is invalid.'); }
+  if (decoded.length < 1 || decoded.length > MAX_STATE_BYTES) {
+    decoded.fill(0);
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', 'Protected relay session credential ciphertext is invalid.');
+  }
+  return decoded;
+}
+
+function validateTokenText(input         )         {
+  const token = String(input ?? '').trim();
+  const bytes = Buffer.byteLength(token, 'utf8');
+  if (bytes < 16 || bytes > MAX_TOKEN_BYTES || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)) {
+    throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session credential is invalid.', { retryable: true });
+  }
+  return token;
+}
+
+function parseTokenMetadata(tokenInput        )                {
+  const token = validateTokenText(tokenInput);
+  const payloadPart = token.split('.', 1)[0] ;
+  let payload         ;
+  try { payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString('utf8')); }
+  catch { throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session credential payload is invalid.', { retryable: true }); }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session credential payload is invalid.', { retryable: true });
+  }
+  const raw = payload                           ;
+  const jti = String(raw.jti ?? '').toLowerCase();
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(jti)) {
+    throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session credential JTI is invalid.', { retryable: true });
+  }
+  const expiresAt = validIso(String(raw.expiresAt ?? ''), 'token expiry');
+  const expiresAtMs = Date.parse(expiresAt);
+  const issuedAt = validIso(String(raw.issuedAt ?? ''), 'token issue time');
+  const issuedAtMs = Date.parse(issuedAt);
+  assertRelaySessionLifetime(issuedAtMs, expiresAtMs);
+  return { jti, expiresAt, expiresAtMs };
+}
+
+export function assertRelaySessionLifetime(issuedAtMs        , expiresAtMs        )       {
+  if (!Number.isFinite(issuedAtMs) || !Number.isFinite(expiresAtMs) || expiresAtMs <= issuedAtMs || expiresAtMs - issuedAtMs > MAX_SESSION_LIFETIME_MS) {
+    throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session credential lifetime is invalid.', { retryable: true });
+  }
+}
+
+function validIso(value        , label        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new OperatorError('RELAY_SESSION_CREDENTIAL_INVALID', `Relay session ${label} is invalid.`);
+  }
+  return value;
+}
+
+function validateRotateUrl(input        , allowLoopbackInsecure         )         {
+  let url     ;
+  try { url = new URL(input); }
+  catch { throw new OperatorError('RELAY_SESSION_ROTATE_URL_INVALID', 'Relay session rotation URL is invalid.'); }
+  if (url.username || url.password || url.hash || url.search || url.pathname !== '/v1/device-session/rotate') {
+    throw new OperatorError('RELAY_SESSION_ROTATE_URL_INVALID', 'Relay session rotation URL must use the fixed credential-free endpoint.');
+  }
+  if (url.protocol === 'https:') return url.toString();
+  if (url.protocol === 'http:' && allowLoopbackInsecure && isLoopback(url.hostname)) return url.toString();
+  throw new OperatorError('RELAY_SESSION_ROTATE_TLS_REQUIRED', 'Relay session rotation requires HTTPS except for explicit loopback development.');
+}
+
+function isLoopback(host        )          {
+  const value = host.replace(/^\[|\]$/g, '').toLowerCase();
+  return value === '127.0.0.1' || value === '::1' || value === 'localhost';
+}
+
+export function deriveRelaySessionRotateUrl(relayUrlInput        , resultUrlInput         , allowLoopbackInsecure = false)         {
+  let relay     ;
+  try { relay = new URL(relayUrlInput); }
+  catch { throw new OperatorError('RELAY_URL_INVALID', 'Relay URL is invalid.'); }
+  if (relay.username || relay.password || relay.hash || relay.search || !['ws:', 'wss:'].includes(relay.protocol)) {
+    throw new OperatorError('RELAY_URL_INVALID', 'Relay URL must be credential-free ws:// or wss://.');
+  }
+  const expected = new URL(relay.toString());
+  expected.protocol = relay.protocol === 'wss:' ? 'https:' : 'http:';
+  if (resultUrlInput) {
+    let result     ;
+    try { result = new URL(resultUrlInput); }
+    catch { throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL is invalid.'); }
+    if (result.username || result.password || result.hash || result.search || result.pathname !== '/v1/device-result') {
+      throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL authority is invalid.');
+    }
+    const loopback = allowLoopbackInsecure && isLoopback(relay.hostname) && isLoopback(result.hostname);
+    if (!loopback && (result.protocol !== 'https:' || expected.protocol !== 'https:' || result.origin !== expected.origin)) {
+      throw new OperatorError('RELAY_RESULT_AUTHORITY_MISMATCH', 'Relay session rotation must stay on the relay-authorized HTTPS origin.');
+    }
+    result.pathname = '/v1/device-session/rotate';
+    return result.toString();
+  }
+  expected.pathname = '/v1/device-session/rotate';
+  expected.search = ''; expected.hash = '';
+  return expected.toString();
+}
+
+export function deriveRelayDeviceResetUrl(relayUrlInput        , resultUrlInput         , allowLoopbackInsecure = false)         {
+  const url = new URL(deriveRelaySessionRotateUrl(relayUrlInput, resultUrlInput, allowLoopbackInsecure));
+  url.pathname = '/v1/device-self/reset';
+  return url.toString();
+}

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

@@ -0,0 +1,130 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_RELAY_URL = 'wss://operator.splcart.in/device';
+const REQUIRED_RESULT_URL = 'https://operator.splcart.in/v1/device-result';
+const remoteDir = path.dirname(fileURLToPath(import.meta.url));
+const nativeRoot = path.resolve(remoteDir, '..', '..', '..', '..', 'native');
+const expectedHelpers = {
+  OPERATOR_WINDOWS_DPAPI_PATH: path.join(nativeRoot, 'operator-windows-dpapi.exe'),
+  OPERATOR_WINDOWS_UIA_PATH: path.join(nativeRoot, 'operator-windows-uia.exe'),
+  OPERATOR_WINDOWS_PATH_LEASE_PATH: path.join(nativeRoot, 'operator-windows-path-lease.exe')
+}         ;
+
+if (!process.env.OPERATOR_AGENT_TOKEN || process.env.OPERATOR_AGENT_TOKEN.length < 32) {
+  throw new Error('Operator remote requires an ephemeral local agent token from the trusted launcher.');
+}
+if (!process.env.OPERATOR_RECOVERY_TOKEN || process.env.OPERATOR_RECOVERY_TOKEN.length < 32) {
+  throw new Error('Operator remote requires an ephemeral recovery token from the trusted launcher.');
+}
+if (!process.env.OPERATOR_ALLOWED_ROOTS) {
+  throw new Error('Operator remote requires an explicit authorized root from the trusted launcher.');
+}
+if (process.env.OPERATOR_ALLOWED_ROOTS.includes(path.win32.delimiter)) {
+  throw new Error(`Operator remote authorized root cannot contain the Windows path-list delimiter '${path.win32.delimiter}'.`);
+}
+for (const [name, expected] of Object.entries(expectedHelpers)) {
+  const configured = process.env[name];
+  if (!configured || !sameWindowsPath(configured, expected)) {
+    throw new Error(`${name} must reference the native helper bundled with the verified npm payload.`);
+  }
+  process.env[name] = expected;
+}
+
+// npm/npx parent environment is caller-controlled. Resolve Windows executable and
+// profile roots through the bundled native helper before importing any provider.
+const roots = trustedWindowsRoots(expectedHelpers.OPERATOR_WINDOWS_PATH_LEASE_PATH);
+const trustedPath = [
+  path.dirname(process.execPath),
+  roots.SYSTEM,
+  roots.WINDOWS,
+  path.join(roots.SYSTEM, 'Wbem'),
+  path.join(roots.PROGRAMFILES, 'Git', 'cmd'),
+  path.join(roots.PROGRAMFILES_X86, 'Git', 'cmd'),
+  path.join(roots.PROGRAMFILES, 'nodejs'),
+  path.join(roots.PROGRAMFILES_X86, 'nodejs'),
+  path.join(roots.PROGRAMFILES, 'Docker', 'Docker', 'resources', 'bin')
+];
+
+for (const key of [
+  'PATH', 'Path', 'SYSTEMROOT', 'WINDIR', 'PROGRAMFILES', 'PROGRAMFILES(X86)',
+  'PROGRAMW6432', 'USERPROFILE', 'HOME', 'HOMEDRIVE', 'HOMEPATH',
+  'LOCALAPPDATA', 'APPDATA', 'PROGRAMDATA', 'TEMP', 'TMP',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_RUNTIME_DIR'
+]) delete process.env[key];
+process.env.SYSTEMROOT = roots.WINDOWS;
+process.env.WINDIR = roots.WINDOWS;
+process.env.PROGRAMFILES = roots.PROGRAMFILES;
+process.env['PROGRAMFILES(X86)'] = roots.PROGRAMFILES_X86;
+process.env.PROGRAMW6432 = roots.PROGRAMFILES;
+process.env.USERPROFILE = roots.USERPROFILE;
+process.env.HOME = roots.USERPROFILE;
+const profileRoot = path.win32.parse(roots.USERPROFILE).root;
+process.env.HOMEDRIVE = profileRoot.slice(0, -1);
+process.env.HOMEPATH = roots.USERPROFILE.slice(Math.max(0, profileRoot.length - 1));
+process.env.LOCALAPPDATA = roots.LOCALAPPDATA;
+process.env.APPDATA = roots.APPDATA;
+process.env.PROGRAMDATA = roots.PROGRAMDATA;
+process.env.TEMP = path.join(roots.LOCALAPPDATA, 'Temp');
+process.env.TMP = process.env.TEMP;
+process.env.PATH = [...new Set(trustedPath.map((entry) => path.win32.resolve(entry)))].join(';');
+process.env.PATHEXT = '.COM;.EXE;.BAT;.CMD';
+
+// The public npm command is intentionally pinned to the production relay authority.
+process.env.OPERATOR_RELAY_URL = REQUIRED_RELAY_URL;
+process.env.OPERATOR_RELAY_RESULT_URL = REQUIRED_RESULT_URL;
+process.env.OPERATOR_RELAY_REQUIRED = '1';
+delete process.env.OPERATOR_RELAY_ALLOW_INSECURE_LOOPBACK;
+
+await import('./main.js');
+
+                            
+                  
+                 
+                       
+                           
+                      
+                       
+                  
+                      
+  
+
+function trustedWindowsRoots(helper        )                      {
+  let output        ;
+  try {
+    output = execFileSync(helper, ['system-roots'], {
+      encoding: 'utf8', windowsHide: true, timeout: 5_000, maxBuffer: 32 * 1024, env: {}
+    });
+  } catch {
+    throw new Error('Operator could not derive trusted Windows known folders from its native helper.');
+  }
+  const required = new Set                           ([
+    'WINDOWS', 'SYSTEM', 'PROGRAMFILES', 'PROGRAMFILES_X86',
+    'USERPROFILE', 'LOCALAPPDATA', 'APPDATA', 'PROGRAMDATA'
+  ]);
+  const parsed = new Map                ();
+  for (const line of output.split(/\r?\n/).filter(Boolean)) {
+    const separator = line.indexOf('=');
+    if (separator < 1) throw new Error('Operator native known-folder response is invalid.');
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    if (!required.has(key                             ) || parsed.has(key)) {
+      throw new Error('Operator native known-folder response is invalid.');
+    }
+    if (!path.win32.isAbsolute(value) || /[\0\r\n;]/.test(value)) {
+      throw new Error(`Operator native known folder ${key} is invalid.`);
+    }
+    parsed.set(key, path.win32.normalize(value));
+  }
+  for (const key of required) if (!parsed.has(key)) throw new Error(`Operator native known folder ${key} is missing.`);
+  const roots = Object.fromEntries(parsed)                       ;
+  if (!sameWindowsPath(roots.SYSTEM, path.win32.join(roots.WINDOWS, 'System32'))) {
+    throw new Error('Operator native Windows system root relationship is invalid.');
+  }
+  return roots;
+}
+
+function sameWindowsPath(left        , right        )          {
+  return path.win32.resolve(left).toLowerCase() === path.win32.resolve(right).toLowerCase();
+}

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

@@ -0,0 +1,66 @@
+import { OperatorRuntime } from '../../../src/core/runtime.js';
+import { FilesystemProvider, GitProvider, GitCheckpointProvider, GitWriteProvider, ProcessProvider, ProjectInspectProvider, ProjectCommandProvider, ProjectTransactionProvider, DockerProvider, PostgresProvider, VsCodeProvider, SystemInspectProvider, ManagedBrowserProvider, WindowsUiaProvider } from '../../../src/capabilities/index.js';
+import { ProviderLearningStore } from '../../../src/core/provider-learning.js';
+
+export function createRuntime(config   
+                    
+                         
+                               
+                                        
+                                      
+                            
+                                       
+                          
+                            
+                         
+                       
+                              
+                       
+                          
+                          
+                                
+ )                  {
+  return new OperatorRuntime(config.stateDir ? { learning: new ProviderLearningStore(config.stateDir) } : {})
+    .register(new SystemInspectProvider())
+    .register(new FilesystemProvider({ allowedRoots: config.allowedRoots, windowsPathLeaseExecutable: config.windowsPathLeasePath }))
+    .register(new ProjectInspectProvider({ allowedRoots: config.allowedRoots }))
+    .register(new ProjectCommandProvider({
+      allowedRoots: config.allowedRoots,
+      allowedExecutables: config.allowedExecutables,
+      registryPath: config.projectCommandRegistryPath
+    }))
+    .register(new ProjectTransactionProvider({
+      allowedRoots: config.allowedRoots,
+      allowedExecutables: config.allowedExecutables,
+      registryPath: config.projectCommandRegistryPath
+    }))
+    .register(new DockerProvider({
+      allowedRoots: config.allowedRoots,
+      dockerExecutable: config.dockerExecutable
+    }))
+    .register(new PostgresProvider({
+      allowedRoots: config.allowedRoots,
+      registryPath: config.postgresProfileRegistryPath,
+      psqlExecutable: config.psqlExecutable
+    }))
+    .register(new VsCodeProvider({
+      allowedRoots: config.allowedRoots,
+      codeExecutable: config.vscodeExecutable,
+      dataDir: config.vscodeDataDir
+    }))
+    .register(new GitProvider({ allowedRoots: config.allowedRoots }))
+    .register(new GitCheckpointProvider({ allowedRoots: config.allowedRoots }))
+    .register(new GitWriteProvider({ allowedRoots: config.allowedRoots }))
+    .register(new ProcessProvider({
+      allowedRoots: config.allowedRoots,
+      allowedExecutables: config.terminalAllowedExecutables ?? [],
+      requiredRisk: 'destructive'
+    }))
+    .register(new ManagedBrowserProvider({
+      endpoint: config.cdpEndpoint,
+      autoLaunch: config.browserAutoLaunch,
+      executablePath: config.browserPath,
+      dataDir: config.browserDataDir
+    }))
+    .register(new WindowsUiaProvider({ binaryPath: config.windowsUiaPath }));
+}