mecord-connect 1.0.0

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

@@ -0,0 +1,333 @@
+import path from 'node:path';
+import { DeviceIdentityStore } from '../../../src/core/device-identity.js';
+import { OperatorError } from '../../../src/core/errors.js';
+import { RelayClient,                                                                         } from '../../../src/core/relay-client.js';
+import { RelayResultStore } from '../../../src/core/relay-result-store.js';
+                                                                
+                                                                    
+import { containsRestrictedData } from '../../../src/core/public-restricted-data.js';
+import { readRelaySessionTokenFile,                                     } from './relay-session-credentials.js';
+
+const MAX_RESULT_BYTES = 256 * 1024;
+
+                                          
+
+                                               
+                   
+                   
+                     
+                           
+                                                      
+                                
+                            
+                     
+                                            
+                                                              
+                                  
+                                     
+ 
+
+export class LocalAgentRelayRunner {
+  #client             ;
+  #identity                     ;
+  #outbox                  ;
+  #sessionCredentials                                ;
+  #resultUrl        ;
+  #localAgentBaseUrl        ;
+  #localExecuteUrl        ;
+  #agentToken        ;
+
+  constructor(options                              ) {
+    this.#identity = options.identity;
+    this.#outbox = new RelayResultStore(path.join(path.resolve(options.stateDir), 'relay-outbox'));
+    const legacyFile = path.resolve(options.sessionTokenFile);
+    this.#sessionCredentials = options.sessionCredentials ?? {
+      forConnection: () => readRelaySessionTokenFile(legacyFile),
+      forRequest: () => readRelaySessionTokenFile(legacyFile),
+      stop: () => undefined
+    };
+    this.#resultUrl = validateResultUrl(options.resultUrl ?? deriveResultUrl(options.relayUrl), options.relayUrl, Boolean(options.allowLoopbackInsecure));
+    this.#localAgentBaseUrl = ensureHttpBase(options.localAgentBaseUrl);
+    this.#localExecuteUrl = new URL('/v1/execute', this.#localAgentBaseUrl).toString();
+    this.#agentToken = options.agentToken;
+    this.#client = new RelayClient({
+      stateDir: options.stateDir,
+      url: options.relayUrl,
+      identity: options.identity,
+      socketFactory: options.socketFactory,
+      allowLoopbackInsecureWs: Boolean(options.allowLoopbackInsecure),
+      getSessionToken: () => this.#sessionCredentials.forConnection(),
+      supportedCapabilities: options.supportedCapabilities,
+      getSupportedCapabilities: options.getSupportedCapabilities,
+      onDelivery: (delivery) => this.#handleDelivery(delivery),
+      onRecovery: (context) => this.#recoverStoredResult(context.delivery.seq, context.delivery.id, context.delivery),
+      onExpiredRecovery: (context) => this.#recoverStoredResult(context.processing.seq, context.processing.id),
+      onAcknowledged: (delivery) => this.#discardStoredResult(delivery.seq, delivery.id)
+    });
+  }
+
+  run()                { return this.#client.run(); }
+  stop()       { this.#client.stop(); this.#sessionCredentials.stop(); }
+  reconnect()       { this.#client.reconnect(); }
+  state()                                   { return this.#client.state(); }
+
+  async #handleDelivery(delivery               )                {
+    const identity = await this.#identity.loadOrCreate();
+    const result = delivery.kind === 'action'
+      ? await this.#executeActionPayload(delivery.payload)
+      : delivery.kind === 'task'
+        ? await this.#executeTaskPayload(delivery.payload)
+        : { ok: false, error: { code: 'RELAY_DELIVERY_KIND_UNSUPPORTED', message: `Unsupported relay delivery kind ${delivery.kind}.` } };
+    const safe = boundedResult(result);
+    await this.#outbox.put(identity.deviceId, delivery.seq, delivery.id, safe);
+    await this.#submitResult(delivery.seq, delivery.id, safe);
+  }
+
+  async #recoverStoredResult(seq        , deliveryId        , delivery                )                                 {
+    const identity = await this.#identity.loadOrCreate();
+    const stored = await this.#outbox.get(identity.deviceId, seq);
+    if (!stored || stored.deliveryId !== deliveryId) return delivery && canRetryUncertainRelayDelivery(delivery) ? 'retry' : 'stop';
+    await this.#submitResult(seq, deliveryId, stored.result);
+    return 'ack';
+  }
+
+  async #discardStoredResult(seq        , deliveryId        )                {
+    const identity = await this.#identity.loadOrCreate();
+    await this.#outbox.removeExact(identity.deviceId, seq, deliveryId);
+  }
+
+  async #executeActionPayload(payload            )                      {
+    const action = validateRemoteAction(payload.action);
+    const approvalAuthority = validateApprovalAuthority(payload.approvalAuthority);
+    const publicBoundary = payload.publicBoundary === true;
+    if (publicBoundary && containsRestrictedData(action.input)) return restrictedDataBlockedResult(action.capability);
+    const response = await fetch(this.#localExecuteUrl, {
+      redirect: 'error',
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${this.#agentToken}`
+      },
+      body: JSON.stringify({ action, ...(approvalAuthority ? { approvalAuthority } : {}) })
+    });
+    let body         ;
+    try { body = await response.json(); }
+    catch { throw new OperatorError('RELAY_LOCAL_RESULT_INVALID', 'Local agent returned a non-JSON execution response.', { retryable: false }); }
+    if (publicBoundary && containsRestrictedData(body)) return restrictedDataBlockedResult(action.capability);
+    if (![200, 409, 423].includes(response.status)) {
+      throw new OperatorError('RELAY_LOCAL_EXECUTION_UNCERTAIN', `Local agent returned HTTP ${response.status}; execution state cannot be safely inferred.`, { retryable: false });
+    }
+    return boundedResult(body);
+  }
+
+  async #executeTaskPayload(payload            )                      {
+    const task = validateRelayTaskRequest(payload.task);
+    if (task.operation === 'submit') {
+      return await this.#callTaskApi('/v1/tasks', 'POST', task.request);
+    }
+
+    const path = `/v1/tasks/${task.taskId}`;
+    const current = await this.#callTaskApi(path, 'GET');
+    if (!current.ok || task.operation === 'inspect') return current;
+    const state = current.task && typeof current.task === 'object' ? String((current.task                           ).state ?? '') : '';
+    if (task.operation === 'pause' && state === 'PAUSED') return current;
+    if (task.operation === 'cancel' && state === 'CANCELLED') return current;
+    if (task.operation === 'run' && ['VERIFIED', 'FAILED', 'CANCELLED'].includes(state)) return current;
+    if (task.operation === 'resume' && ['VERIFIED', 'FAILED'].includes(state)) return current;
+    return await this.#callTaskApi(`${path}/${task.operation}`, 'POST', {});
+  }
+
+  async #callTaskApi(pathname        , method                , body          )                      {
+    const response = await fetch(new URL(pathname, this.#localAgentBaseUrl), {
+      redirect: 'error', method,
+      headers: { ...(method === 'POST' ? { 'content-type': 'application/json' } : {}), authorization: `Bearer ${this.#agentToken}` },
+      ...(method === 'POST' ? { body: JSON.stringify(body ?? {}) } : {})
+    });
+    let bodyValue         ;
+    try { bodyValue = await response.json(); }
+    catch { throw new OperatorError('RELAY_LOCAL_TASK_RESULT_INVALID', 'Local agent returned a non-JSON durable task response.', { retryable: false }); }
+    if (!bodyValue || typeof bodyValue !== 'object' || Array.isArray(bodyValue) || typeof (bodyValue                           ).ok !== 'boolean') {
+      throw new OperatorError('RELAY_LOCAL_TASK_RESULT_INVALID', 'Local agent returned a malformed durable task response.', { retryable: false });
+    }
+    if (![200, 202, 400, 403, 404, 409, 423, 503].includes(response.status)) {
+      throw new OperatorError('RELAY_LOCAL_TASK_UNCERTAIN', `Local task API returned HTTP ${response.status}; durable task state must be reconciled before retry.`, { retryable: true });
+    }
+    return boundedResult(bodyValue);
+  }
+
+  async #submitResult(seq        , deliveryId        , result            )                {
+    const token = await this.#sessionCredentials.forRequest();
+    let response          ;
+    try {
+      response = await fetch(this.#resultUrl, {
+        redirect: 'error',
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        body: JSON.stringify({ seq, deliveryId, result })
+      });
+    } catch (error) {
+      throw new OperatorError('RELAY_RESULT_SUBMIT_FAILED', `Relay result submission failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+    }
+    if (response.status === 200) return;
+    let code = 'RELAY_RESULT_SUBMIT_FAILED';
+    try { code = String((await response.json()       )?.error?.code ?? code); } catch { /* bounded generic failure */ }
+    const retryable = response.status === 401 || response.status === 408 || response.status === 429 || response.status >= 500;
+    throw new OperatorError(code, `Relay result service rejected result with HTTP ${response.status}.`, { retryable });
+  }
+
+
+}
+
+export { readRelaySessionTokenFile } from './relay-session-credentials.js';
+
+export function canRetryUncertainRelayDelivery(delivery               )          {
+  try {
+    if (delivery.kind === 'task') { validateRelayTaskRequest(delivery.payload.task); return true; }
+    if (delivery.kind === 'action') return validateRemoteAction(delivery.payload.action).risk === 'read';
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+                       
+                                                             
+                                                                                     
+
+function validateRelayTaskRequest(input         )                   {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task payload must be an object.');
+  const raw = input                           ;
+  const operation = String(raw.operation ?? '');
+  if (operation === 'submit') {
+    if (!raw.request || typeof raw.request !== 'object' || Array.isArray(raw.request)) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task submit payload requires a request object.');
+    const request = structuredClone(raw.request                           );
+    request.requestId = validTaskUuid(request.requestId, 'requestId');
+    if (!request.goal || typeof request.goal !== 'object' || Array.isArray(request.goal)) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task submit payload requires a goal object.');
+    const text = JSON.stringify(request);
+    if (Buffer.byteLength(text, 'utf8') > 256 * 1024) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task submit payload exceeds the bounded size.');
+    return { operation: 'submit', request };
+  }
+  if (!['inspect', 'run', 'pause', 'resume', 'cancel'].includes(operation)) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task operation is invalid.');
+  if (raw.approvedActionId !== undefined) throw new OperatorError('RELAY_TASK_INVALID', 'Relay task control cannot carry local approval authority.');
+  return { operation: operation                                                     , taskId: validTaskUuid(raw.taskId, 'taskId') };
+}
+
+function validTaskUuid(input         , label        )         {
+  const value = String(input ?? '').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(value)) throw new OperatorError('RELAY_TASK_INVALID', `Relay task ${label} must be a UUID.`);
+  return value;
+}
+
+function validateRemoteAction(input         )                {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('RELAY_ACTION_INVALID', 'Relay action payload must contain an action object.');
+  const raw = input                           ;
+  const id = boundedName(raw.id, 'action id');
+  const capability = boundedName(raw.capability, 'capability');
+  const risk = raw.risk;
+  if (!['read', 'write', 'external', 'system', 'destructive'].includes(String(risk))) throw new OperatorError('RELAY_ACTION_INVALID', 'Relay action risk is invalid.');
+  if (!raw.input || typeof raw.input !== 'object' || Array.isArray(raw.input)) throw new OperatorError('RELAY_ACTION_INVALID', 'Relay action input must be an object.');
+  const inputText = JSON.stringify(raw.input);
+  if (Buffer.byteLength(inputText, 'utf8') > 128 * 1024) throw new OperatorError('RELAY_ACTION_INVALID', 'Relay action input exceeds the bounded size.');
+  if (!raw.provenance || typeof raw.provenance !== 'object' || Array.isArray(raw.provenance) || (raw.provenance       ).kind !== 'chatgpt') {
+    throw new OperatorError('RELAY_ACTION_PROVENANCE_INVALID', 'Remote relay actions must carry ChatGPT instruction provenance.');
+  }
+  const taskId = raw.taskId === undefined ? undefined : boundedName(raw.taskId, 'task id');
+  const target = raw.target === undefined ? undefined : boundedText(raw.target, 'target', 2048);
+  return {
+    id,
+    capability,
+    risk: risk                         ,
+    input: structuredClone(raw.input                           ),
+    provenance: { kind: 'chatgpt', source: (raw.provenance       ).source === undefined ? undefined : boundedText((raw.provenance       ).source, 'provenance source', 512) },
+    taskId,
+    target
+  };
+}
+
+function validateApprovalAuthority(input         )                           {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new OperatorError('RELAY_APPROVAL_AUTHORITY_INVALID', 'Relay approval authority is invalid.');
+  }
+  const raw = input                           ;
+  const accountId = String(raw.accountId ?? '');
+  const deviceId = String(raw.deviceId ?? '');
+  const generation = Number(raw.generation);
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  if (!uuid.test(accountId) || !uuid.test(deviceId) || !Number.isSafeInteger(generation) || generation < 1) {
+    throw new OperatorError('RELAY_APPROVAL_AUTHORITY_INVALID', 'Relay approval authority is invalid.');
+  }
+  return { accountId: accountId.toLowerCase(), deviceId: deviceId.toLowerCase(), generation };
+}
+
+function restrictedDataBlockedResult(capability        )             {
+  return {
+    ok: false,
+    capability,
+    provider: 'public-boundary',
+    error: {
+      code: 'RESTRICTED_DATA_BLOCKED',
+      message: 'The public plugin refused content that may contain restricted data.'
+    },
+    evidence: [],
+    durationMs: 0
+  };
+}
+
+function boundedResult(input         )             {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OperatorError('RELAY_LOCAL_RESULT_INVALID', 'Relay action result must be a JSON object.');
+  let text        ;
+  try { text = JSON.stringify(input); } catch { throw new OperatorError('RELAY_LOCAL_RESULT_INVALID', 'Relay action result is not JSON serializable.'); }
+  if (!text || Buffer.byteLength(text, 'utf8') > MAX_RESULT_BYTES) throw new OperatorError('RELAY_LOCAL_RESULT_TOO_LARGE', 'Relay action result exceeds the bounded result size.');
+  return JSON.parse(text)              ;
+}
+
+function boundedName(input         , label        )         {
+  const value = String(input ?? '');
+  if (!value || value.length > 256 || !/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(value)) throw new OperatorError('RELAY_ACTION_INVALID', `Relay ${label} is invalid.`);
+  return value;
+}
+
+function boundedText(input         , label        , max        )         {
+  const value = String(input ?? '');
+  if (!value || Buffer.byteLength(value, 'utf8') > max) throw new OperatorError('RELAY_ACTION_INVALID', `Relay ${label} is invalid.`);
+  return value;
+}
+
+function deriveResultUrl(relayUrlInput        )         {
+  let relay     ;
+  try { relay = new URL(relayUrlInput); } catch { throw new OperatorError('RELAY_URL_INVALID', 'Relay URL is invalid.'); }
+  relay.protocol = relay.protocol === 'wss:' ? 'https:' : relay.protocol === 'ws:' ? 'http:' : relay.protocol;
+  relay.pathname = '/v1/device-result'; relay.search = ''; relay.hash = '';
+  return relay.toString();
+}
+
+function validateResultUrl(input        , relayUrlInput        , allowLoopbackInsecure         )         {
+  let url     ;
+  let relay     ;
+  try { url = new URL(input); } catch { throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL is invalid.'); }
+  try { relay = new URL(relayUrlInput); } catch { throw new OperatorError('RELAY_URL_INVALID', 'Relay URL is invalid.'); }
+  if (url.username || url.password || url.hash || url.search) throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL must not contain credentials, a query, or a fragment.');
+  if (url.pathname !== '/v1/device-result') throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL must use the fixed /v1/device-result endpoint.');
+
+  const localOverride = allowLoopbackInsecure && isLoopback(url.hostname) && isLoopback(relay.hostname);
+  if (localOverride && ['http:', 'https:'].includes(url.protocol)) return url.toString();
+
+  const expected = new URL(deriveResultUrl(relayUrlInput));
+  if (url.protocol === 'https:' && expected.protocol === 'https:' && url.origin === expected.origin && url.pathname === expected.pathname) {
+    return url.toString();
+  }
+  if (url.protocol !== 'https:') throw new OperatorError('RELAY_RESULT_TLS_REQUIRED', 'Relay results require HTTPS; insecure HTTP is allowed only for explicit loopback development.');
+  throw new OperatorError('RELAY_RESULT_AUTHORITY_MISMATCH', 'Relay result URL must remain on the relay-authorized HTTPS origin.');
+}
+
+function ensureHttpBase(input        )         {
+  let url     ;
+  try { url = new URL(input); } catch { throw new OperatorError('RELAY_LOCAL_AGENT_URL_INVALID', 'Local agent base URL is invalid.'); }
+  if (url.protocol !== 'http:' || !isLoopback(url.hostname) || url.username || url.password) throw new OperatorError('RELAY_LOCAL_AGENT_URL_INVALID', 'Relay runner may call only a loopback HTTP local-agent endpoint.');
+  return url.toString();
+}
+
+function isLoopback(host        )          {
+  const value = host.replace(/^\[|\]$/g, '').toLowerCase();
+  return value === '127.0.0.1' || value === '::1' || value === 'localhost';
+}

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

@@ -0,0 +1,156 @@
+import crypto from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DeviceIdentityStore } from '../../../src/core/device-identity.js';
+import { answerPairingChallenge,                             } from '../../../src/core/device-registry.js';
+import { enrollmentPollBinding } from '../../../src/core/device-enrollment.js';
+import { OperatorError } from '../../../src/core/errors.js';
+
+const REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_POLL_MS = 2_000;
+
+                                                                    
+
+                                               
+                   
+                     
+                                
+                                  
+                          
+                           
+                                                                      
+ 
+
+export class RelayEnrollmentClient {
+  #identity                     ;
+  #base     ;
+  #fetch              ;
+  #pollIntervalMs        ;
+  #onUserCode                                                         ;
+  #abort = new AbortController();
+
+  constructor(options                              ) {
+    this.#identity = options.identity;
+    this.#base = validateEnrollmentAuthority(options.relayUrl, options.resultUrl, Boolean(options.allowLoopbackInsecure));
+    this.#fetch = options.fetchImpl ?? fetch;
+    const pollMs = Number(options.pollIntervalMs ?? DEFAULT_POLL_MS);
+    if (!Number.isInteger(pollMs) || pollMs < 100 || pollMs > 30_000) {
+      throw new OperatorError('DEVICE_ENROLLMENT_POLL_CONFIG_INVALID', 'Device enrollment poll interval is invalid.');
+    }
+    this.#pollIntervalMs = pollMs;
+    this.#onUserCode = options.onUserCode;
+  }
+
+  stop()       { this.#abort.abort(); }
+
+  async enroll()                  {
+    if (this.#abort.signal.aborted) throw new OperatorError('DEVICE_ENROLLMENT_STOPPED', 'Device enrollment was stopped.');
+    const device = await this.#identity.loadOrCreate();
+    const challenged = await this.#post('/v1/device-enrollment/challenge', { deviceId: device.deviceId });
+    if (challenged.status !== 200) throw enrollmentHttpError(challenged.status, challenged.body);
+    const challenge = challenged.body?.challenge                          ;
+    const pairing = await answerPairingChallenge(challenge, this.#identity);
+    const pollToken = crypto.randomBytes(32).toString('base64url');
+    const pollSignature = await this.#identity.sign(enrollmentPollBinding(pairing.challengeId, device.deviceId, pollToken));
+    const completed = await this.#post('/v1/device-enrollment/complete', { pairingResponse: pairing, pollToken, pollSignature });
+    if (completed.status !== 200) throw enrollmentHttpError(completed.status, completed.body);
+    const enrollmentId = validUuid(String(completed.body?.enrollment?.enrollmentId ?? ''), 'enrollmentId');
+    if (enrollmentId !== pairing.challengeId) throw new OperatorError('DEVICE_ENROLLMENT_STATE_MISMATCH', 'Relay enrollment identity changed unexpectedly.');
+    const userCode = validUserCode(String(completed.body?.enrollment?.userCode ?? ''));
+    const expiresAt = validIso(String(completed.body?.enrollment?.expiresAt ?? ''), 'enrollment expiry');
+    await this.#onUserCode?.({ userCode, expiresAt });
+
+    while (Date.now() < Date.parse(expiresAt)) {
+      const polled = await this.#post('/v1/device-enrollment/poll', { enrollmentId, pollToken });
+      if (polled.status === 202) {
+        await delay(this.#pollIntervalMs, undefined, { signal: this.#abort.signal });
+        continue;
+      }
+      if (polled.status !== 200) throw enrollmentHttpError(polled.status, polled.body);
+      const token = String(polled.body?.session?.token ?? '');
+      if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token) || Buffer.byteLength(token, 'utf8') > 16 * 1024) {
+        throw new OperatorError('DEVICE_ENROLLMENT_SESSION_INVALID', 'Relay enrollment returned an invalid session credential.');
+      }
+      return token;
+    }
+    throw new OperatorError('DEVICE_ENROLLMENT_EXPIRED', 'Device enrollment expired before account claim completed.');
+  }
+  async #post(pathname        , payload         )                                         {
+    const url = new URL(pathname, this.#base);
+    let response          ;
+    try {
+      response = await this.#fetch(url, {
+        redirect: 'error',
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.any([this.#abort.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+      });
+    } catch (error) {
+      if (this.#abort.signal.aborted) throw new OperatorError('DEVICE_ENROLLMENT_STOPPED', 'Device enrollment was stopped.');
+      throw new OperatorError('DEVICE_ENROLLMENT_REQUEST_FAILED', `Device enrollment request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+    }
+    let body      = null;
+    try { body = await response.json(); } catch { /* handled below */ }
+    return { status: response.status, body };
+  }
+}
+
+function enrollmentHttpError(status        , body     )                {
+  const code = typeof body?.error?.code === 'string' ? body.error.code : 'DEVICE_ENROLLMENT_REQUEST_FAILED';
+  const retryable = status === 408 || status === 429 || status >= 500;
+  return new OperatorError(code, `Device enrollment service returned HTTP ${status}.`, { retryable });
+}
+function validateEnrollmentAuthority(relayInput        , resultInput                    , allowLoopbackInsecure         )      {
+  let relay     ;
+  try { relay = new URL(relayInput); } catch { throw new OperatorError('RELAY_URL_INVALID', 'Relay URL is invalid.'); }
+  if (relay.username || relay.password || relay.search || relay.hash || !['ws:', 'wss:'].includes(relay.protocol)) {
+    throw new OperatorError('RELAY_URL_INVALID', 'Relay URL authority is invalid.');
+  }
+  const expected = new URL(relay.toString());
+  expected.protocol = relay.protocol === 'wss:' ? 'https:' : 'http:';
+  expected.pathname = '/'; expected.search = ''; expected.hash = '';
+  if (!resultInput) {
+    if (expected.protocol === 'https:' || (allowLoopbackInsecure && isLoopback(expected.hostname))) return expected;
+    throw new OperatorError('DEVICE_ENROLLMENT_TLS_REQUIRED', 'Device enrollment requires HTTPS except for explicit loopback development.');
+  }
+  let result     ;
+  try { result = new URL(resultInput); } catch { throw new OperatorError('RELAY_RESULT_URL_INVALID', 'Relay result URL is invalid.'); }
+  if (result.username || result.password || result.search || result.hash || 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('DEVICE_ENROLLMENT_AUTHORITY_MISMATCH', 'Device enrollment must use the relay-authorized HTTPS origin.');
+  }
+  result.pathname = '/'; return result;
+}
+
+function validUuid(input        , label        )         {
+  const value = String(input ?? '').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(value)) {
+    throw new OperatorError('DEVICE_ENROLLMENT_INPUT_INVALID', `${label} must be a UUID.`);
+  }
+  return value;
+}
+
+function validUserCode(input        )         {
+  const compact = String(input ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+  if (!/^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{8}$/.test(compact)) {
+    throw new OperatorError('DEVICE_ENROLLMENT_CODE_INVALID', 'Relay enrollment returned an invalid pairing code.');
+  }
+  return `${compact.slice(0, 4)}-${compact.slice(4)}`;
+}
+
+function validIso(input        , label        )         {
+  const value = String(input ?? '');
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new OperatorError('DEVICE_ENROLLMENT_INPUT_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';
+}