@quolu/lattice 0.1.0 → 0.12.2

package/src/bridge-config.mjs

@@ -0,0 +1,346 @@
+import { createServer } from 'node:http';
+import { randomBytes, randomInt } from 'node:crypto';
+import { homedir } from 'node:os';
+import { isIP } from 'node:net';
+import {
+  chmod, lstat, mkdir, open, readFile, rename, rm, writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { domainToASCII } from 'node:url';
+import { parseTree } from 'jsonc-parser';
+
+export const BRIDGE_CONFIG_SCHEMA = 'lattice.bridge_config.v1';
+export const BRIDGE_PORT_MIN = 49_152;
+export const BRIDGE_PORT_MAX = 65_535;
+const CONFIG_NAME = 'bridge.json';
+const LOCK_NAME = 'bridge.lock';
+const OPERATION_LOCK_NAME = 'bridge-operation.lock';
+const LOCK_ATTEMPTS = 240;
+const LOCK_WAIT_MS = 25;
+const LOCK_STALE_MS = 30_000;
+const AUTO_PORT_ATTEMPTS = 256;
+
+export class BridgeConfigError extends Error {
+  constructor(code, message, detail = undefined, cause = undefined) {
+    super(message, { cause });
+    this.name = 'BridgeConfigError';
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+function exact(value, keys) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+function configRoot(env) {
+  const configured = env.LATTICE_CONFIG_DIR;
+  if (configured !== undefined) {
+    if (typeof configured !== 'string' || !path.isAbsolute(configured)) {
+      throw new BridgeConfigError('BRIDGE_CONFIG_DIR_INVALID', 'LATTICE_CONFIG_DIR must be absolute');
+    }
+    return configured;
+  }
+  return path.join(homedir(), '.lattice');
+}
+
+export function bridgeConfigPaths(env = process.env) {
+  const root = configRoot(env);
+  return Object.freeze({ root, config: path.join(root, CONFIG_NAME), lock: path.join(root, LOCK_NAME),
+    operationLock: path.join(root, OPERATION_LOCK_NAME) });
+}
+
+function validTimestamp(value) {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value))
+    && new Date(value).toISOString() === value;
+}
+
+function validateListen(listen) {
+  if (!exact(listen, ['address', 'port']) || isIP(listen.address) === 0
+    || !Number.isSafeInteger(listen.port) || listen.port < BRIDGE_PORT_MIN
+    || listen.port > BRIDGE_PORT_MAX) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'bridge listen configuration is invalid');
+  }
+}
+
+export function normalizeBridgeAllowedHost(value) {
+  if (typeof value !== 'string' || value.length === 0 || value !== value.trim()) {
+    throw new BridgeConfigError('BRIDGE_ALLOWED_HOST_INVALID', 'allowed host is invalid');
+  }
+  if (isIP(value) !== 0) return value.toLowerCase();
+  const withoutDot = value.endsWith('.') ? value.slice(0, -1) : value;
+  const ascii = domainToASCII(withoutDot).toLowerCase();
+  if (ascii.length === 0 || ascii.length > 253
+    || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/u.test(ascii)
+    || ascii.split('.').some((label) => label.length === 0 || label.length > 63
+      || label.startsWith('-') || label.endsWith('-'))) {
+    throw new BridgeConfigError('BRIDGE_ALLOWED_HOST_INVALID', 'allowed host is invalid');
+  }
+  return ascii;
+}
+
+function normalizeAllowedHosts(address, values) {
+  if (!Array.isArray(values) || values.length > 32) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'allowed hosts must be an array');
+  }
+  const hosts = new Set([normalizeBridgeAllowedHost(address)]);
+  if (address === '0.0.0.0') hosts.add('127.0.0.1');
+  if (address === '::') hosts.add('::1');
+  for (const value of values) hosts.add(normalizeBridgeAllowedHost(value));
+  if (hosts.size > 32) throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'too many allowed hosts');
+  return Object.freeze([...hosts].sort((left, right) => left.localeCompare(right, 'en')));
+}
+
+export function normalizeBridgeUpstream(upstream) {
+  if (upstream?.mode === 'dashboard_descriptor' && exact(upstream, ['mode'])) {
+    return Object.freeze({ mode: 'dashboard_descriptor' });
+  }
+  if (upstream?.mode !== 'url' || !exact(upstream, ['mode', 'url']) || typeof upstream.url !== 'string') {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'bridge upstream configuration is invalid');
+  }
+  let parsed;
+  try { parsed = new URL(upstream.url); } catch {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'bridge upstream URL is invalid');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username !== '' || parsed.password !== ''
+    || parsed.hash !== '' || parsed.search !== '') {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'bridge upstream URL must be an HTTP origin or base path');
+  }
+  parsed.pathname = parsed.pathname.endsWith('/') ? parsed.pathname : `${parsed.pathname}/`;
+  return Object.freeze({ mode: 'url', url: parsed.href });
+}
+
+export function validateBridgeConfig(value) {
+  if (!exact(value, ['schema', 'enabled', 'listen', 'allowed_hosts', 'upstream', 'updated_at'])
+    || value.schema !== BRIDGE_CONFIG_SCHEMA || typeof value.enabled !== 'boolean'
+    || !validTimestamp(value.updated_at)) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'bridge configuration schema is invalid');
+  }
+  validateListen(value.listen);
+  const allowedHosts = normalizeAllowedHosts(value.listen.address, value.allowed_hosts);
+  if (allowedHosts.length !== value.allowed_hosts.length
+    || allowedHosts.some((host, index) => host !== value.allowed_hosts[index])) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'allowed hosts are not canonical');
+  }
+  const upstream = normalizeBridgeUpstream(value.upstream);
+  return Object.freeze({
+    schema: BRIDGE_CONFIG_SCHEMA,
+    enabled: value.enabled,
+    listen: Object.freeze({ address: value.listen.address, port: value.listen.port }),
+    allowed_hosts: allowedHosts,
+    upstream,
+    updated_at: value.updated_at,
+  });
+}
+
+async function prepareRoot(root) {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const stats = await lstat(root);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_DIR_INVALID', 'bridge config directory is unsafe');
+  }
+  if ((stats.mode & 0o077) !== 0) await chmod(root, 0o700);
+}
+
+async function readDocument(ref) {
+  let stats;
+  try { stats = await lstat(ref); } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new BridgeConfigError('BRIDGE_CONFIG_UNREADABLE', 'bridge config cannot be read', undefined, error);
+  }
+  if (!stats.isFile() || stats.isSymbolicLink() || (stats.mode & 0o777) !== 0o600) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_MODE_INVALID', 'bridge config must be a regular 0600 file');
+  }
+  let value;
+  try {
+    const text = await readFile(ref, 'utf8');
+    const errors = [];
+    const tree = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
+    const duplicate = (node) => {
+      if (node?.type === 'object') {
+        const keys = new Set();
+        for (const property of node.children ?? []) {
+          const [key, child] = property.children ?? [];
+          if (keys.has(key?.value) || duplicate(child)) return true;
+          keys.add(key?.value);
+        }
+      } else if (node?.type === 'array') return (node.children ?? []).some(duplicate);
+      return false;
+    };
+    if (errors.length > 0 || tree === undefined || duplicate(tree)) {
+      throw new Error('duplicate or invalid JSON');
+    }
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'bridge config JSON is invalid', undefined, error);
+  }
+  return validateBridgeConfig(value);
+}
+
+export async function readBridgeConfig({ env = process.env } = {}) {
+  return readDocument(bridgeConfigPaths(env).config);
+}
+
+async function atomicWrite(ref, value) {
+  const temporary = `${ref}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await rename(temporary, ref);
+    await chmod(ref, 0o600);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+async function withLock(ref, action) {
+  for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
+    let handle;
+    try {
+      handle = await open(ref, 'wx', 0o600);
+      await handle.writeFile(`${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`);
+      try { return await action(); } finally {
+        await handle.close();
+        await rm(ref, { force: true });
+      }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        const lock = JSON.parse(await readFile(ref, 'utf8'));
+        let alive = Number.isSafeInteger(lock.pid) && lock.pid > 0;
+        if (alive) try { process.kill(lock.pid, 0); } catch { alive = false; }
+        if (!alive || Date.now() - Date.parse(lock.created_at) > LOCK_STALE_MS) {
+          await rm(ref, { force: true });
+          continue;
+        }
+      } catch (lockError) {
+        if (lockError?.code === 'ENOENT') continue;
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));
+    }
+  }
+  throw new BridgeConfigError('BRIDGE_CONFIG_BUSY', 'bridge config lock timed out');
+}
+
+export async function withBridgeOperationLock({ env = process.env } = {}, action) {
+  if (typeof action !== 'function') throw new TypeError('bridge operation action required');
+  const refs = bridgeConfigPaths(env);
+  await prepareRoot(refs.root);
+  return withLock(refs.operationLock, action);
+}
+
+function closeServer(server) {
+  return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}
+
+async function bindCandidate(address, port, createCandidateServer) {
+  const server = createCandidateServer();
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen({ host: address, port, exclusive: true }, resolve);
+    });
+    return server;
+  } catch (error) {
+    try { server.close(); } catch {}
+    if (['EADDRINUSE', 'EACCES', 'EADDRNOTAVAIL'].includes(error?.code)) return null;
+    throw new BridgeConfigError('BRIDGE_BIND_FAILED', 'bridge candidate bind failed', { address, port }, error);
+  }
+}
+
+async function reservePort({ address, requestedPort, createCandidateServer, choosePort }) {
+  if (requestedPort !== null) {
+    const server = await bindCandidate(address, requestedPort, createCandidateServer);
+    if (server === null) {
+      throw new BridgeConfigError('BRIDGE_PORT_UNAVAILABLE', 'requested bridge port is unavailable',
+        { address, port: requestedPort });
+    }
+    return { port: requestedPort, server };
+  }
+  const attempted = new Set();
+  while (attempted.size < AUTO_PORT_ATTEMPTS) {
+    let port = choosePort();
+    if (!Number.isSafeInteger(port) || port < BRIDGE_PORT_MIN || port > BRIDGE_PORT_MAX) {
+      port = randomInt(BRIDGE_PORT_MIN, BRIDGE_PORT_MAX + 1);
+    }
+    while (attempted.has(port)) {
+      port = port === BRIDGE_PORT_MAX ? BRIDGE_PORT_MIN : port + 1;
+    }
+    attempted.add(port);
+    const server = await bindCandidate(address, port, createCandidateServer);
+    if (server !== null) return { port, server };
+  }
+  throw new BridgeConfigError('BRIDGE_PORT_EXHAUSTED', 'no exclusive high bridge port could be bound',
+    { address, attempts: attempted.size });
+}
+
+function validateMutation({ address, port, upstream, allowedHosts }) {
+  if (typeof address !== 'string' || isIP(address) === 0) {
+    throw new BridgeConfigError('BRIDGE_LISTEN_INVALID', 'bridge listen address must be an IP literal');
+  }
+  if (port !== null && (!Number.isSafeInteger(port) || port < BRIDGE_PORT_MIN || port > BRIDGE_PORT_MAX)) {
+    throw new BridgeConfigError('BRIDGE_PORT_INVALID', `bridge port must be ${BRIDGE_PORT_MIN}..${BRIDGE_PORT_MAX}`);
+  }
+  return { upstream: normalizeBridgeUpstream(upstream), allowedHosts: normalizeAllowedHosts(address, allowedHosts) };
+}
+
+export async function configureBridge({
+  address, port = null, upstream = { mode: 'dashboard_descriptor' }, allowedHosts = [],
+  env = process.env, now = () => new Date(),
+  createCandidateServer = () => createServer(),
+  choosePort = () => randomInt(BRIDGE_PORT_MIN, BRIDGE_PORT_MAX + 1),
+  reuseCurrentPort = true,
+} = {}) {
+  const normalized = validateMutation({ address, port, upstream, allowedHosts });
+  const refs = bridgeConfigPaths(env);
+  await prepareRoot(refs.root);
+  return withLock(refs.lock, async () => {
+    const current = await readDocument(refs.config);
+    const selectedPort = port ?? (reuseCurrentPort && current?.enabled && current.listen.address === address
+      ? current.listen.port : null);
+    const bindingUnchanged = current?.enabled === true && current.listen.address === address
+      && current.listen.port === selectedPort;
+    let reservation = null;
+    try {
+      if (!bindingUnchanged) {
+        reservation = await reservePort({ address, requestedPort: selectedPort,
+          createCandidateServer, choosePort });
+      }
+      const config = validateBridgeConfig({
+        schema: BRIDGE_CONFIG_SCHEMA,
+        enabled: true,
+        listen: { address, port: bindingUnchanged ? selectedPort : reservation.port },
+        allowed_hosts: normalized.allowedHosts,
+        upstream: normalized.upstream,
+        updated_at: now().toISOString(),
+      });
+      await atomicWrite(refs.config, config);
+      return config;
+    } finally {
+      if (reservation !== null) await closeServer(reservation.server);
+    }
+  });
+}
+
+export async function disableBridge({ env = process.env, now = () => new Date() } = {}) {
+  const refs = bridgeConfigPaths(env);
+  await prepareRoot(refs.root);
+  return withLock(refs.lock, async () => {
+    const current = await readDocument(refs.config);
+    if (current === null) return null;
+    const config = validateBridgeConfig({ ...current, enabled: false, updated_at: now().toISOString() });
+    await atomicWrite(refs.config, config);
+    return config;
+  });
+}
+
+export async function restoreBridgeConfig(config, { env = process.env } = {}) {
+  if (config !== null) validateBridgeConfig(config);
+  const refs = bridgeConfigPaths(env);
+  await prepareRoot(refs.root);
+  return withLock(refs.lock, async () => {
+    if (config === null) await rm(refs.config, { force: true });
+    else await atomicWrite(refs.config, config);
+    return config;
+  });
+}

package/src/bridge-daemon.mjs

@@ -0,0 +1,328 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { chmod, lstat, open, rename, rm, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import path from 'node:path';
+import { parseTree } from 'jsonc-parser';
+
+import {
+  BRIDGE_PORT_MAX, BRIDGE_PORT_MIN, BridgeConfigError, bridgeConfigPaths, readBridgeConfig,
+} from './bridge-config.mjs';
+
+const DESCRIPTOR_SCHEMA = 'lattice.bridge_daemon.v1';
+const START_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 3_000;
+const STOP_REQUEST_SCHEMA = 'lattice.bridge_stop_request.v1';
+const STOP_RECEIPT_SCHEMA = 'lattice.bridge_stop_receipt.v1';
+const ACTIVE_MARKER_SCHEMA = 'lattice.bridge_daemon_active.v1';
+const CONTROL_MAX_BYTES = 65_536;
+
+export function bridgeDaemonDescriptorPath(env = process.env) {
+  return path.join(bridgeConfigPaths(env).root, 'bridge-daemon.json');
+}
+
+export function bridgeDaemonActiveMarkerPath(env = process.env) {
+  return path.join(bridgeConfigPaths(env).root, 'bridge-daemon-active.json');
+}
+
+function bridgeStopPaths(env) {
+  const root = bridgeConfigPaths(env).root;
+  return { request: path.join(root, 'bridge-stop-request.json'),
+    receipt: path.join(root, 'bridge-stop-receipt.json') };
+}
+
+export async function removeBridgeDaemonDescriptor({ env = process.env } = {}) {
+  await rm(bridgeDaemonDescriptorPath(env), { force: true });
+}
+
+export async function removeBridgeDaemonActiveMarker({ env = process.env } = {}) {
+  await rm(bridgeDaemonActiveMarkerPath(env), { force: true });
+}
+
+async function atomicDescriptor(ref, value) {
+  const temporary = `${ref}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await rename(temporary, ref);
+    await chmod(ref, 0o600);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+function duplicateJsonKey(node) {
+  if (node?.type === 'object') {
+    const keys = new Set();
+    for (const property of node.children ?? []) {
+      const [key, child] = property.children ?? [];
+      if (keys.has(key?.value) || duplicateJsonKey(child)) return true;
+      keys.add(key?.value);
+    }
+  } else if (node?.type === 'array') return (node.children ?? []).some(duplicateJsonKey);
+  return false;
+}
+
+function isIsoTimestamp(value) {
+  if (typeof value !== 'string') return false;
+  try { return new Date(value).toISOString() === value; } catch { return false; }
+}
+
+async function readStrictJson(ref, code, label) {
+  let before;
+  let handle;
+  try {
+    before = await lstat(ref);
+    if (!before.isFile() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o600
+      || before.size > CONTROL_MAX_BYTES) throw new Error(`${label} unsafe`);
+    handle = await open(ref, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino
+      || opened.size !== before.size || opened.size > CONTROL_MAX_BYTES) {
+      throw new Error(`${label} changed during validation`);
+    }
+    const text = await handle.readFile('utf8');
+    const after = await lstat(ref);
+    if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
+      throw new Error(`${label} changed during read`);
+    }
+    const errors = [];
+    const tree = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
+    if (errors.length > 0 || tree === undefined || duplicateJsonKey(tree)) {
+      throw new Error(`${label} JSON invalid`);
+    }
+    return JSON.parse(text);
+  } catch (error) {
+    if (error?.code === 'ENOENT' && before === undefined) return null;
+    throw new BridgeConfigError(code, `${label} invalid`, undefined, error);
+  } finally { await handle?.close(); }
+}
+
+async function readStrictControl(ref, schema, keys) {
+  const value = await readStrictJson(ref, 'BRIDGE_STOP_CONTROL_INVALID', 'bridge stop control');
+  if (value === null) return null;
+  const timestampKey = keys.find((key) => key.endsWith('_at'));
+  if (value?.schema !== schema || Object.keys(value).sort().join(',') !== [...keys].sort().join(',')
+    || keys.includes('nonce')
+      && (typeof value.nonce !== 'string' || !/^[0-9a-f]{64}$/u.test(value.nonce))
+    || keys.includes('address') && isIP(value.address) === 0
+    || keys.includes('port')
+      && (!Number.isSafeInteger(value.port) || value.port < BRIDGE_PORT_MIN || value.port > BRIDGE_PORT_MAX)
+    || timestampKey === undefined || !isIsoTimestamp(value[timestampKey])) {
+    throw new BridgeConfigError('BRIDGE_STOP_CONTROL_INVALID', 'bridge stop control schema invalid');
+  }
+  return value;
+}
+
+async function readBridgeDaemonActiveMarker(env) {
+  return (await readStrictControl(bridgeDaemonActiveMarkerPath(env), ACTIVE_MARKER_SCHEMA,
+    ['schema', 'address', 'port', 'started_at']));
+}
+
+export async function readBridgeStopRequest({ env = process.env } = {}) {
+  return readStrictControl(bridgeStopPaths(env).request, STOP_REQUEST_SCHEMA,
+    ['schema', 'nonce', 'requested_at']);
+}
+
+export async function writeBridgeStopReceipt({ nonce, env = process.env }) {
+  if (typeof nonce !== 'string' || !/^[0-9a-f]{64}$/u.test(nonce)) {
+    throw new BridgeConfigError('BRIDGE_STOP_CONTROL_INVALID', 'bridge stop nonce invalid');
+  }
+  await atomicDescriptor(bridgeStopPaths(env).receipt, {
+    schema: STOP_RECEIPT_SCHEMA, nonce, stopped_at: new Date().toISOString(),
+  });
+}
+
+export async function clearBridgeStopControl({ env = process.env } = {}) {
+  const refs = bridgeStopPaths(env);
+  await rm(refs.request, { force: true });
+  await rm(refs.receipt, { force: true });
+}
+
+export async function requestBridgeDaemonStop({ env = process.env, listen = null } = {}) {
+  let descriptor = null;
+  try { descriptor = await readBridgeDaemonDescriptor({ env }); } catch {}
+  if (descriptor !== null && await attest(descriptor) === null
+    && !await bridgeEndpointAvailable({ address: descriptor.address, port: descriptor.port })) {
+    return { state: 'not_running', nonce: null };
+  }
+  if (descriptor === null) {
+    const refs = bridgeStopPaths(env);
+    let descriptorExists = true;
+    try { await lstat(bridgeDaemonDescriptorPath(env)); } catch (error) {
+      if (error?.code === 'ENOENT') descriptorExists = false;
+    }
+    let activeMarker;
+    let activeMarkerInvalid = false;
+    try { activeMarker = await readBridgeDaemonActiveMarker(env); } catch (error) {
+      if (error?.code !== 'BRIDGE_STOP_CONTROL_INVALID') throw error;
+      activeMarkerInvalid = true;
+      activeMarker = null;
+    }
+    if (!descriptorExists) {
+      const witnessedListen = activeMarker === null ? listen : activeMarker;
+      if (!activeMarkerInvalid
+        && (witnessedListen === null || !await bridgeEndpointAvailable(witnessedListen))) {
+        return { state: 'not_running', nonce: null };
+      }
+    }
+  }
+  const refs = bridgeStopPaths(env);
+  const nonce = randomBytes(32).toString('hex');
+  await rm(refs.receipt, { force: true });
+  await atomicDescriptor(refs.request, {
+    schema: STOP_REQUEST_SCHEMA, nonce, requested_at: new Date().toISOString(),
+  });
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const receipt = await readStrictControl(refs.receipt, STOP_RECEIPT_SCHEMA,
+      ['schema', 'nonce', 'stopped_at']);
+    if (receipt?.nonce === nonce) return { state: 'stopped', nonce };
+  }
+  throw new BridgeConfigError('BRIDGE_DAEMON_STOP_FAILED', 'bridge daemon stop receipt timed out');
+}
+
+export async function writeBridgeDaemonDescriptor({ config, env = process.env }) {
+  const instanceToken = env.LATTICE_BRIDGE_INSTANCE_TOKEN;
+  if (typeof instanceToken !== 'string' || !/^[0-9a-f]{64}$/u.test(instanceToken)) {
+    throw new BridgeConfigError('BRIDGE_INSTANCE_TOKEN_INVALID', 'bridge instance token is invalid');
+  }
+  const descriptor = { schema: DESCRIPTOR_SCHEMA, pid: process.pid,
+    address: config.listen.address, port: config.listen.port,
+    config_updated_at: config.updated_at, instance_token: instanceToken,
+    started_at: new Date().toISOString() };
+  await atomicDescriptor(bridgeDaemonDescriptorPath(env), descriptor);
+  await atomicDescriptor(bridgeDaemonActiveMarkerPath(env), {
+    schema: ACTIVE_MARKER_SCHEMA, address: descriptor.address, port: descriptor.port,
+    started_at: descriptor.started_at,
+  });
+  return descriptor;
+}
+
+export async function readBridgeDaemonDescriptor({ env = process.env } = {}) {
+  const value = await readStrictJson(bridgeDaemonDescriptorPath(env),
+    'BRIDGE_DAEMON_DESCRIPTOR_INVALID', 'bridge daemon descriptor');
+  if (value === null) return null;
+  if (value?.schema !== DESCRIPTOR_SCHEMA || !Number.isSafeInteger(value.pid) || value.pid <= 0
+    || typeof value.address !== 'string' || isIP(value.address) === 0
+    || !Number.isSafeInteger(value.port) || value.port < BRIDGE_PORT_MIN || value.port > BRIDGE_PORT_MAX
+    || !isIsoTimestamp(value.config_updated_at) || !isIsoTimestamp(value.started_at)
+    || typeof value.instance_token !== 'string' || !/^[0-9a-f]{64}$/u.test(value.instance_token)
+    || Object.keys(value).sort().join(',')
+      !== 'address,config_updated_at,instance_token,pid,port,schema,started_at') {
+    throw new BridgeConfigError('BRIDGE_DAEMON_DESCRIPTOR_INVALID', 'bridge daemon descriptor schema invalid');
+  }
+  return value;
+}
+
+function healthHost(address) {
+  if (address === '0.0.0.0') return '127.0.0.1';
+  if (address === '::') return '[::1]';
+  return address.includes(':') ? `[${address}]` : address;
+}
+
+async function bridgeEndpointAvailable(listen) {
+  try {
+    const response = await fetch(`http://${healthHost(listen.address)}:${listen.port}/__lattice/bridge-health`,
+      { signal: AbortSignal.timeout(300) });
+    const body = response.status === 200 ? await response.json() : null;
+    return body?.schema === 'lattice.bridge_health.v1';
+  } catch { return false; }
+}
+
+export async function waitForBridgeSocketClose({ listen, timeoutMs = STOP_TIMEOUT_MS } = {}) {
+  if (listen === null || typeof listen !== 'object') throw new TypeError('bridge listen required');
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await bridgeEndpointAvailable(listen)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return !await bridgeEndpointAvailable(listen);
+}
+
+async function attest(descriptor) {
+  if (descriptor === null) return null;
+  try {
+    const response = await fetch(`http://${healthHost(descriptor.address)}:${descriptor.port}/__lattice/bridge-health`, {
+      headers: { 'x-lattice-bridge-instance-token': descriptor.instance_token },
+      signal: AbortSignal.timeout(400),
+    });
+    if (response.status !== 200) return null;
+    const body = await response.json();
+    return body?.schema === 'lattice.bridge_health.v1' && body.pid === descriptor.pid ? body : null;
+  } catch { return null; }
+}
+
+async function healthy(descriptor, config) {
+  if (descriptor === null || descriptor.address !== config.listen.address
+    || descriptor.port !== config.listen.port) return false;
+  const body = await attest(descriptor);
+  return body !== null && body.updated_at === config.updated_at;
+}
+
+export async function ensureBridgeDaemon({ env = process.env } = {}) {
+  const config = await readBridgeConfig({ env });
+  if (config === null || !config.enabled) throw new BridgeConfigError('BRIDGE_DISABLED', 'bridge is disabled');
+  const previous = await readBridgeDaemonDescriptor({ env });
+  if (await healthy(previous, config)) return previous;
+  if (previous !== null && previous.address === config.listen.address
+    && previous.port === config.listen.port && await attest(previous) !== null) {
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      const reconciled = await readBridgeDaemonDescriptor({ env });
+      if (reconciled?.pid === previous.pid && await healthy(reconciled, config)) return reconciled;
+    }
+    throw new BridgeConfigError('BRIDGE_DAEMON_UNAVAILABLE',
+      'existing bridge daemon did not reconcile the updated config');
+  }
+  const instanceToken = randomBytes(32).toString('hex');
+  const child = spawn(process.execPath, [path.resolve(import.meta.dirname, '../bin/lattice-bridge.mjs')], {
+    detached: true, stdio: 'ignore', env: { ...env, LATTICE_BRIDGE_INSTANCE_TOKEN: instanceToken },
+  });
+  child.unref();
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const descriptor = await readBridgeDaemonDescriptor({ env });
+    if (await healthy(descriptor, config)) {
+      if (previous !== null && previous.pid !== descriptor.pid) {
+        if (await attest(previous) !== null) {
+          try { process.kill(previous.pid, 'SIGTERM'); } catch {}
+        }
+      }
+      return descriptor;
+    }
+  }
+  throw new BridgeConfigError('BRIDGE_DAEMON_UNAVAILABLE', 'bridge daemon did not bind and become healthy');
+}
+
+export async function stopBridgeDaemon({ env = process.env } = {}) {
+  const descriptor = await readBridgeDaemonDescriptor({ env });
+  if (descriptor === null) return null;
+  if (await attest(descriptor) === null) {
+    let alive = true;
+    try { process.kill(descriptor.pid, 0); } catch { alive = false; }
+    if (!alive) {
+      await rm(bridgeDaemonDescriptorPath(env), { force: true });
+      await removeBridgeDaemonActiveMarker({ env });
+      return descriptor;
+    }
+    throw new BridgeConfigError('BRIDGE_DAEMON_ATTESTATION_FAILED',
+      'bridge daemon identity could not be attested; refusing to signal descriptor PID');
+  }
+  try { process.kill(descriptor.pid, 'SIGTERM'); } catch (error) {
+    if (error?.code !== 'ESRCH') throw new BridgeConfigError('BRIDGE_DAEMON_STOP_FAILED', 'bridge daemon signal failed');
+  }
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    let alive = true;
+    try { process.kill(descriptor.pid, 0); } catch { alive = false; }
+    if (!alive) {
+      await rm(bridgeDaemonDescriptorPath(env), { force: true });
+      await removeBridgeDaemonActiveMarker({ env });
+      return descriptor;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new BridgeConfigError('BRIDGE_DAEMON_STOP_FAILED', 'bridge daemon did not stop');
+}