mecord-connect 1.0.0

package/runtime/app/apps/local-agent/src/device-reset.js

@@ -0,0 +1,260 @@
+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_JOURNAL_BYTES = 64 * 1024;
+const MAX_TREE_ENTRIES = 10_000;
+
+                             
+             
+                   
+                                       
+                                             
+                            
+                    
+ 
+
+                                         
+                     
+                    
+                                                                
+                           
+ 
+                                          
+                   
+                                
+                    
+                                        
+                                         
+                           
+                     
+ 
+
+export class LocalDeviceResetCoordinator {
+  #stateDir        ;
+  #journalFile        ;
+  #identity                     ;
+  #resetUrl         ;
+  #getResetToken                        ;
+  #stopRelay                             ;
+  #fetch              ;
+  #clock            ;
+  #queue                = Promise.resolve();
+
+  constructor(options                         ) {
+    this.#stateDir = path.resolve(options.stateDir);
+    this.#journalFile = path.join(this.#stateDir, 'local-device-reset.json');
+    this.#identity = options.identity;
+    this.#resetUrl = options.resetUrl === undefined ? undefined : validateResetUrl(options.resetUrl);
+    this.#getResetToken = options.getResetToken;
+    this.#stopRelay = options.stopRelay;
+    this.#fetch = options.fetchImpl ?? fetch;
+    this.#clock = options.clock ?? (() => new Date());
+    if (this.#resetUrl && !this.#getResetToken) {
+      throw new OperatorError('DEVICE_RESET_CONFIG_INVALID', 'Hosted device reset requires a relay reset credential provider.');
+    }
+  }
+
+  async reset()                                  {
+    return await this.#exclusive(async () => {
+      const identity = await this.#identity.loadExisting();
+      const journal = await this.#readJournal();
+      if (!identity && journal?.phase === 'COMPLETE') {
+        return { status: 'complete', deviceId: journal.deviceId, hostedStatus: journal.hostedStatus, removedTargets: [] };
+      }
+      if (!identity && !journal) {
+        return { status: 'complete', hostedStatus: 'not-applicable', removedTargets: [] };
+      }
+
+      const deviceId = identity?.deviceId ?? journal .deviceId;
+      let activeJournal = journal?.deviceId === deviceId && journal.phase === 'HOSTED_REVOKED' ? journal : null;
+      if (!activeJournal) activeJournal = await this.#revokeHosted(deviceId);
+      const removedTargets = await this.#purgeLocalAuthority();
+      await this.#identity.erase();
+      const completed                    = {
+        ...activeJournal,
+        phase: 'COMPLETE',
+        updatedAt: this.#clock().toISOString()
+      };
+      await this.#writeJournal(completed);
+      return { status: 'complete', deviceId, hostedStatus: completed.hostedStatus, removedTargets };
+    });
+  }
+
+  async #revokeHosted(deviceId        )                             {
+    if (!this.#resetUrl) {
+      await this.#stopRelay?.();
+      const now = this.#clock().toISOString();
+      const journal                    = { version: 1, deviceId, phase: 'HOSTED_REVOKED', hostedStatus: 'not-configured', hostedCompletedAt: now, updatedAt: now };
+      await this.#writeJournal(journal);
+      return journal;
+    }
+    const token = await this.#getResetToken ();
+    await this.#stopRelay?.();
+    let response          ;
+    try {
+      response = await this.#fetch(this.#resetUrl, { method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
+    } catch (error) {
+      throw new OperatorError('DEVICE_RESET_HOSTED_FAILED', `Hosted device reset request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+    }
+    let body      = null;
+    try { body = await response.json(); } catch { /* handled below */ }
+    if (response.status !== 200 || body?.ok !== true || body?.reset?.status !== 'complete') {
+      const code = String(body?.error?.code ?? 'DEVICE_RESET_HOSTED_FAILED');
+      const retryable = response.status === 408 || response.status === 429 || response.status >= 500;
+      throw new OperatorError(code, `Hosted device reset failed with HTTP ${response.status}.`, { retryable });
+    }
+    const returnedDeviceId = validUuid(String(body.reset.deviceId ?? ''), 'hosted reset deviceId');
+    if (returnedDeviceId !== deviceId) throw new OperatorError('DEVICE_RESET_RECEIPT_MISMATCH', 'Hosted reset receipt belongs to a different device.');
+    const completedAt = validIso(String(body.reset.completedAt ?? ''), 'hosted reset completion');
+    const now = this.#clock().toISOString();
+    const journal                    = {
+      version: 1,
+      deviceId,
+      phase: 'HOSTED_REVOKED',
+      hostedStatus: 'revoked',
+      hostedCompletedAt: completedAt,
+      updatedAt: now
+    };
+    await this.#writeJournal(journal);
+    return journal;
+  }
+
+  async #purgeLocalAuthority()                    {
+    const relatives = authorityTargets();
+    for (const relative of relatives) await this.#assertSafeTarget(this.#target(relative));
+    const removed           = [];
+    for (const relative of relatives) {
+      const target = this.#target(relative);
+      try {
+        await fs.lstat(target);
+        await fs.rm(target, { recursive: true, force: true });
+        removed.push(relative);
+      } catch (error) {
+        if ((error                         ).code !== 'ENOENT') throw error;
+      }
+    }
+    return removed;
+  }
+
+  #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 OperatorError('DEVICE_RESET_PATH_INVALID', 'Device reset target escaped the Operator state directory.');
+    return target;
+  }
+
+  async #assertSafeTarget(target        )                {
+    try {
+      const stat = await fs.lstat(target);
+      if (stat.isSymbolicLink()) throw new OperatorError('DEVICE_RESET_PATH_UNSAFE', 'Device reset refuses symbolic-link targets.');
+      if (stat.isDirectory()) await assertTreeHasNoSymlinks(target, 0);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return;
+      throw error;
+    }
+  }
+  async #readJournal()                                    {
+    try {
+      const text = await readDurableStateText(this.#journalFile, {
+        maxBytes: MAX_JOURNAL_BYTES,
+        errorCode: 'DEVICE_RESET_LOCAL_STATE_INVALID',
+        invalidMessage: 'Local device reset state is invalid.'
+      });
+      return validateJournal(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return null;
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', 'Local device reset state could not be read.');
+    }
+  }
+
+  async #writeJournal(journal                   )                {
+    await writeDurableStateText(this.#journalFile, JSON.stringify(validateJournal(journal), null, 2), {
+      maxBytes: MAX_JOURNAL_BYTES,
+      errorCode: 'DEVICE_RESET_LOCAL_STATE_INVALID',
+      invalidMessage: 'Local device reset state is invalid.'
+    });
+  }
+
+  async #exclusive   (operation                  )             {
+    let release             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { release = resolve; });
+    await previous;
+    try { return await operation(); } finally { release(); }
+  }
+}
+function authorityTargets()           {
+  return [
+    'relay-session-credential.json',
+    'relay-session.token',
+    'relay-client.json',
+    'device-sessions.json',
+    'device-registry.json',
+    'device-routing.json',
+    'approvals.json',
+    'provider-learning.json',
+    'relay-outbox'
+  ];
+}
+
+function validateJournal(input         )                    {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', 'Local reset journal must be an object.');
+  const raw = input                           ;
+  if (raw.version !== 1) throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', 'Local reset journal version is invalid.');
+  const deviceId = validUuid(String(raw.deviceId ?? ''), 'deviceId');
+  const phase = raw.phase === 'HOSTED_REVOKED' || raw.phase === 'COMPLETE' ? raw.phase : null;
+  if (!phase) throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', 'Local reset journal phase is invalid.');
+  const hostedStatus = raw.hostedStatus === 'revoked' || raw.hostedStatus === 'not-configured' ? raw.hostedStatus : null;
+  if (!hostedStatus) throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', 'Local reset hosted status is invalid.');
+  const hostedCompletedAt = validIso(String(raw.hostedCompletedAt ?? ''), 'hostedCompletedAt');
+  const updatedAt = validIso(String(raw.updatedAt ?? ''), 'updatedAt');
+  return { version: 1, deviceId, phase, hostedStatus, hostedCompletedAt, updatedAt };
+}
+
+function validateResetUrl(input        )         {
+  let url     ;
+  try { url = new URL(input); }
+  catch { throw new OperatorError('DEVICE_RESET_URL_INVALID', 'Hosted device reset URL is invalid.'); }
+  if (url.username || url.password || url.hash || url.search || url.pathname !== '/v1/device-self/reset') {
+    throw new OperatorError('DEVICE_RESET_URL_INVALID', 'Hosted device reset URL must use the fixed credential-free endpoint.');
+  }
+  if (url.protocol === 'https:') return url.toString();
+  if (url.protocol === 'http:' && isLoopback(url.hostname)) return url.toString();
+  throw new OperatorError('DEVICE_RESET_TLS_REQUIRED', 'Hosted device reset requires HTTPS except for loopback development.');
+}
+
+function validUuid(value        , label        )         {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', `${label} must be a UUID.`);
+  }
+  return value.toLowerCase();
+}
+function validIso(value        , label        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new OperatorError('DEVICE_RESET_LOCAL_STATE_INVALID', `${label} must be an ISO timestamp.`);
+  }
+  return value;
+}
+
+function isLoopback(host        )          {
+  const value = host.replace(/^\[|\]$/g, '').toLowerCase();
+  return value === '127.0.0.1' || value === '::1' || value === 'localhost';
+}
+
+async function assertTreeHasNoSymlinks(dir        , seen        )                  {
+  let count = seen;
+  for (const name of await fs.readdir(dir)) {
+    count += 1;
+    if (count > MAX_TREE_ENTRIES) throw new OperatorError('DEVICE_RESET_PATH_UNSAFE', 'Device reset tree exceeds the bounded entry count.');
+    const child = path.join(dir, name);
+    const stat = await fs.lstat(child);
+    if (stat.isSymbolicLink()) throw new OperatorError('DEVICE_RESET_PATH_UNSAFE', 'Device reset refuses symbolic links inside authority state.');
+    if (stat.isDirectory()) count = await assertTreeHasNoSymlinks(child, count);
+  }
+  return count;
+}

package/runtime/app/apps/local-agent/src/emergency-stop.js

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { OperatorError } from '../../../src/core/errors.js';
+import { readDurableStateText, writeDurableStateText } from '../../../src/core/durable-state.js';
+
+const MAX_REASON = 512;
+const EMERGENCY_STOP_OPTIONS = {
+  maxBytes: 16 * 1024,
+  errorCode: 'EMERGENCY_STOP_STATE_INVALID',
+  invalidMessage: 'Emergency stop state is invalid.'
+}         ;
+
+                           
+             
+                   
+                     
+                  
+                     
+  
+
+export class EmergencyStopStore {
+  #file        ;
+  #queue                = Promise.resolve();
+
+  constructor(stateDir        ) {
+    this.#file = path.join(path.resolve(stateDir), 'emergency-stop.json');
+  }
+
+  async status()                                        {
+    return await this.#read();
+  }
+
+  async engage(reasonInput         )                                        {
+    const reason = reasonInput === undefined ? undefined : validReason(reasonInput);
+    return await this.#mutate((current) => {
+      if (current.engaged) return current;
+      return {
+        version: 1,
+        engaged: true,
+        engagedAt: new Date().toISOString(),
+        reason
+      };
+    });
+  }
+
+  async clear()                                        {
+    return await this.#mutate(() => ({
+      version: 1,
+      engaged: false,
+      clearedAt: new Date().toISOString()
+    }));
+  }
+
+  async #read()                              {
+    let raw        ;
+    try {
+      raw = await readDurableStateText(this.#file, EMERGENCY_STOP_OPTIONS);
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, engaged: false };
+      throw error;
+    }
+
+    let parsed         ;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw invalidState('Stored emergency stop state is not valid JSON.');
+    }
+    return validateState(parsed);
+  }
+
+  async #write(stateInput                    )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#file, JSON.stringify(state, null, 2), EMERGENCY_STOP_OPTIONS);
+  }
+
+  async #mutate(mutator                                                   )                              {
+    let release             ;
+    const previous = this.#queue;
+    this.#queue = new Promise      ((resolve) => { release = resolve; });
+    await previous;
+    try {
+      const next = mutator(await this.#read());
+      await this.#write(next);
+      return next;
+    } finally {
+      release();
+    }
+  }
+}
+
+function validReason(value        )         {
+  if (typeof value !== 'string') throw invalidState('Emergency stop reason is invalid.');
+  const reason = value.trim();
+  if (!reason || reason.length > MAX_REASON || /\0/.test(reason)) throw invalidState('Emergency stop reason is invalid.');
+  return reason;
+}
+
+function validateState(input         )                     {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw invalidState('Emergency stop state structure is invalid.');
+  }
+  const raw = input                           ;
+  const allowed = new Set(['version', 'engaged', 'engagedAt', 'reason', 'clearedAt']);
+  if (Object.keys(raw).some((key) => !allowed.has(key))) {
+    throw invalidState('Emergency stop state contains unsupported fields.');
+  }
+  if (raw.version !== 1 || typeof raw.engaged !== 'boolean') {
+    throw invalidState('Emergency stop state structure is invalid.');
+  }
+
+  const engagedAt = raw.engagedAt === undefined ? undefined : strictIso(raw.engagedAt, 'engagedAt');
+  const clearedAt = raw.clearedAt === undefined ? undefined : strictIso(raw.clearedAt, 'clearedAt');
+  const reason = raw.reason === undefined ? undefined : strictReason(raw.reason);
+
+  if (raw.engaged) {
+    if (!engagedAt) throw invalidState('Engaged emergency stop requires engagedAt.');
+    if (clearedAt) throw invalidState('Engaged emergency stop cannot retain clearedAt.');
+  } else if (engagedAt || reason) {
+    throw invalidState('Cleared emergency stop cannot retain engagement metadata.');
+  }
+
+  return { version: 1, engaged: raw.engaged, engagedAt, reason, clearedAt };
+}
+
+function strictReason(value         )         {
+  if (typeof value !== 'string') throw invalidState('Emergency stop reason must be a string.');
+  return validReason(value);
+}
+
+function strictIso(value         , field        )         {
+  if (typeof value !== 'string') throw invalidState(`Emergency stop ${field} must be a string timestamp.`);
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw invalidState(`Emergency stop ${field} timestamp is invalid.`);
+  }
+  return value;
+}
+
+function invalidState(message        )                {
+  return new OperatorError('EMERGENCY_STOP_STATE_INVALID', message);
+}