@quolu/lattice 0.1.0 → 0.12.2

package/src/bridge-launch-agent.mjs

@@ -0,0 +1,311 @@
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import {
+  chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { BridgeConfigError, readBridgeConfig } from './bridge-config.mjs';
+import { readBridgeDaemonDescriptor } from './bridge-daemon.mjs';
+
+export const BRIDGE_LAUNCH_AGENT_LABEL = 'dev.kitepon.lattice.bridge';
+const START_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 3_000;
+const execFileAsync = promisify(execFile);
+
+function fail(code, message, cause = undefined) {
+  return new BridgeConfigError(code, message, undefined, cause);
+}
+
+function userId() {
+  const uid = process.getuid?.();
+  if (!Number.isSafeInteger(uid) || uid < 0) {
+    throw fail('BRIDGE_LAUNCH_AGENT_UID_INVALID', 'current user id is unavailable');
+  }
+  return uid;
+}
+
+export function bridgeLaunchAgentPaths(env = process.env) {
+  const home = env.HOME;
+  if (typeof home !== 'string' || !path.isAbsolute(home)) {
+    throw fail('BRIDGE_LAUNCH_AGENT_HOME_INVALID', 'HOME must be an absolute path');
+  }
+  const directory = path.join(home, 'Library', 'LaunchAgents');
+  return Object.freeze({ directory,
+    plist: path.join(directory, `${BRIDGE_LAUNCH_AGENT_LABEL}.plist`) });
+}
+
+async function prepareDirectory(directory, uid = userId()) {
+  const home = path.dirname(path.dirname(directory));
+  const library = path.dirname(directory);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  for (const ref of [home, library, directory]) {
+    await mkdir(ref, { mode: 0o700 }).catch((error) => {
+      if (error?.code !== 'EEXIST') throw error;
+    });
+    const stats = await lstat(ref);
+    if (!stats.isDirectory() || stats.isSymbolicLink() || stats.uid !== uid
+      || (stats.mode & 0o022) !== 0) {
+      throw fail('BRIDGE_LAUNCH_AGENT_DIR_UNSAFE', 'LaunchAgents path is unsafe');
+    }
+  }
+}
+
+async function strictPlist(ref, uid = userId()) {
+  let before;
+  let handle;
+  try {
+    before = await lstat(ref);
+    if (!before.isFile() || before.isSymbolicLink() || before.uid !== uid
+      || (before.mode & 0o777) !== 0o600 || before.size > 65_536) {
+      throw new Error('unsafe plist');
+    }
+    handle = await open(ref, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.uid !== uid || opened.dev !== before.dev
+      || opened.ino !== before.ino || opened.size !== before.size) {
+      throw new Error('plist changed during validation');
+    }
+    const content = 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('plist changed during read');
+    }
+    return content;
+  } catch (error) {
+    if (error?.code === 'ENOENT' && before === undefined) return null;
+    throw fail('BRIDGE_LAUNCH_AGENT_PLIST_UNSAFE', 'bridge LaunchAgent plist is unsafe', error);
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function atomicPlist(ref, content) {
+  const temporary = `${ref}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await rename(temporary, ref);
+    await chmod(ref, 0o600);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+function xml(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+async function executablePath(ref, label, { executable = true, uid = userId() } = {}) {
+  if (typeof ref !== 'string' || !path.isAbsolute(ref)) {
+    throw fail('BRIDGE_LAUNCH_AGENT_EXECUTABLE_INVALID', `${label} path must be absolute`);
+  }
+  let resolved;
+  let stats;
+  try {
+    resolved = await realpath(ref);
+    stats = await lstat(resolved);
+  } catch (error) {
+    throw fail('BRIDGE_LAUNCH_AGENT_EXECUTABLE_INVALID', `${label} is unavailable`, error);
+  }
+  if (!stats.isFile() || stats.isSymbolicLink() || ![0, uid].includes(stats.uid)
+    || (stats.mode & 0o022) !== 0
+    || executable && (stats.mode & 0o111) === 0) {
+    throw fail('BRIDGE_LAUNCH_AGENT_EXECUTABLE_INVALID', `${label} is unsafe`);
+  }
+  return resolved;
+}
+
+function plistDocument({ nodePath, bridgePath, instanceToken, env }) {
+  const environment = [['LATTICE_BRIDGE_INSTANCE_TOKEN', instanceToken]];
+  if (env.LATTICE_CONFIG_DIR !== undefined) {
+    if (typeof env.LATTICE_CONFIG_DIR !== 'string' || !path.isAbsolute(env.LATTICE_CONFIG_DIR)) {
+      throw fail('BRIDGE_CONFIG_DIR_INVALID', 'LATTICE_CONFIG_DIR must be absolute');
+    }
+    environment.push(['LATTICE_CONFIG_DIR', env.LATTICE_CONFIG_DIR]);
+  }
+  const environmentXml = environment.map(([key, value]) =>
+    `      <key>${xml(key)}</key>\n      <string>${xml(value)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${BRIDGE_LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(bridgePath)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${environmentXml}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+</dict>
+</plist>
+`;
+}
+
+export async function defaultLaunchctlRunner(args) {
+  try {
+    const result = await execFileAsync('/bin/launchctl', args, { encoding: 'utf8' });
+    return { code: 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  } catch (error) {
+    if (Number.isInteger(error?.code)) {
+      return { code: error.code, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
+    }
+    throw fail('BRIDGE_LAUNCHCTL_UNAVAILABLE', 'launchctl could not be executed', error);
+  }
+}
+
+function domain(uid) { return `gui/${uid}`; }
+function service(uid) { return `${domain(uid)}/${BRIDGE_LAUNCH_AGENT_LABEL}`; }
+
+async function launchctl(runner, args, code, message, accepted = [0]) {
+  let result;
+  try { result = await runner(args); } catch (error) {
+    if (error instanceof BridgeConfigError) throw error;
+    throw fail(code, message, error);
+  }
+  if (!result || !Number.isInteger(result.code) || !accepted.includes(result.code)) {
+    throw fail(code, message);
+  }
+  return result;
+}
+
+async function loadedState(runner, uid) {
+  const result = await launchctl(runner, ['print', service(uid)],
+    'BRIDGE_LAUNCHCTL_STATUS_FAILED', 'could not inspect bridge LaunchAgent', [0, 113]);
+  return result.code === 0;
+}
+
+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 defaultWaitReady({ config, instanceToken, env, timeoutMs = START_TIMEOUT_MS }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const descriptor = await readBridgeDaemonDescriptor({ env });
+    if (descriptor?.address === config.listen.address && descriptor?.port === config.listen.port
+      && descriptor?.config_updated_at === config.updated_at) {
+      try {
+        const response = await fetch(
+          `http://${healthHost(descriptor.address)}:${descriptor.port}/__lattice/bridge-health`, {
+            headers: { 'x-lattice-bridge-instance-token': instanceToken },
+            signal: AbortSignal.timeout(400),
+          });
+        const body = response.status === 200 ? await response.json() : null;
+        if (body?.schema === 'lattice.bridge_health.v1' && body.pid === descriptor.pid
+          && body.updated_at === config.updated_at) return descriptor;
+      } catch {}
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw fail('BRIDGE_LAUNCH_AGENT_START_FAILED', 'bridge LaunchAgent did not become healthy');
+}
+
+async function defaultWaitStopped({ listen, timeoutMs = STOP_TIMEOUT_MS }) {
+  if (listen === null) return;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(`http://${healthHost(listen.address)}:${listen.port}/__lattice/bridge-health`,
+        { signal: AbortSignal.timeout(300) });
+    } catch { return; }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw fail('BRIDGE_LAUNCH_AGENT_STOP_FAILED', 'bridge LaunchAgent socket did not stop');
+}
+
+export async function snapshotBridgeLaunchAgent({ env = process.env,
+  runner = defaultLaunchctlRunner, uid = userId() } = {}) {
+  const refs = bridgeLaunchAgentPaths(env);
+  await prepareDirectory(refs.directory, uid);
+  const content = await strictPlist(refs.plist, uid);
+  const loaded = await loadedState(runner, uid);
+  if (loaded && content === null) {
+    throw fail('BRIDGE_LAUNCH_AGENT_STATE_INVALID', 'loaded bridge LaunchAgent has no owned plist');
+  }
+  return Object.freeze({ installed: content !== null, loaded, content });
+}
+
+async function bootoutIfLoaded({ runner, uid }) {
+  if (!await loadedState(runner, uid)) return false;
+  await launchctl(runner, ['bootout', service(uid)], 'BRIDGE_LAUNCHCTL_BOOTOUT_FAILED',
+    'could not stop bridge LaunchAgent');
+  return true;
+}
+
+export async function installBridgeLaunchAgent({ config, env = process.env,
+  runner = defaultLaunchctlRunner, uid = userId(), nodePath = process.execPath,
+  bridgePath = path.resolve(import.meta.dirname, '../bin/lattice-bridge.mjs'),
+  waitReady = defaultWaitReady, waitStopped = defaultWaitStopped,
+  previousListen = null } = {}) {
+  if (config?.enabled !== true) throw fail('BRIDGE_DISABLED', 'bridge is disabled');
+  const refs = bridgeLaunchAgentPaths(env);
+  await prepareDirectory(refs.directory, uid);
+  await strictPlist(refs.plist, uid);
+  const resolvedNode = await executablePath(nodePath, 'node executable', { uid });
+  const resolvedBridge = await executablePath(bridgePath, 'bridge executable', { executable: false, uid });
+  const instanceToken = randomBytes(32).toString('hex');
+  const content = plistDocument({ nodePath: resolvedNode, bridgePath: resolvedBridge, instanceToken, env });
+  const stopped = await bootoutIfLoaded({ runner, uid });
+  if (stopped) await waitStopped({ listen: previousListen, env });
+  await atomicPlist(refs.plist, content);
+  await launchctl(runner, ['bootstrap', domain(uid), refs.plist],
+    'BRIDGE_LAUNCHCTL_BOOTSTRAP_FAILED', 'could not start bridge LaunchAgent');
+  return waitReady({ config, instanceToken, env });
+}
+
+export async function disableBridgeLaunchAgent({ snapshot, listen, env = process.env,
+  runner = defaultLaunchctlRunner, uid = userId(), waitStopped = defaultWaitStopped } = {}) {
+  if (!snapshot || typeof snapshot.installed !== 'boolean' || typeof snapshot.loaded !== 'boolean') {
+    throw new TypeError('bridge LaunchAgent snapshot required');
+  }
+  const refs = bridgeLaunchAgentPaths(env);
+  if (snapshot.loaded) {
+    await launchctl(runner, ['bootout', service(uid)], 'BRIDGE_LAUNCHCTL_BOOTOUT_FAILED',
+      'could not stop bridge LaunchAgent');
+    await waitStopped({ listen, env });
+  }
+  await rm(refs.plist, { force: true });
+  return { removed: snapshot.installed, stopped: snapshot.loaded };
+}
+
+export async function restoreBridgeLaunchAgent({ snapshot, listen = null, env = process.env,
+  runner = defaultLaunchctlRunner, uid = userId(), waitStopped = defaultWaitStopped,
+  config = undefined, waitReady = defaultWaitReady } = {}) {
+  if (!snapshot || typeof snapshot.installed !== 'boolean' || typeof snapshot.loaded !== 'boolean'
+    || (snapshot.installed && typeof snapshot.content !== 'string')) {
+    throw new TypeError('bridge LaunchAgent snapshot required');
+  }
+  const refs = bridgeLaunchAgentPaths(env);
+  await prepareDirectory(refs.directory, uid);
+  const stopped = await bootoutIfLoaded({ runner, uid });
+  if (stopped) await waitStopped({ listen, env });
+  if (snapshot.installed) await atomicPlist(refs.plist, snapshot.content);
+  else await rm(refs.plist, { force: true });
+  if (snapshot.loaded) {
+    await launchctl(runner, ['bootstrap', domain(uid), refs.plist],
+      'BRIDGE_LAUNCHCTL_ROLLBACK_FAILED', 'could not restore bridge LaunchAgent');
+    const restoredConfig = config ?? await readBridgeConfig({ env });
+    const tokenMatch = snapshot.content.match(
+      /<key>LATTICE_BRIDGE_INSTANCE_TOKEN<\/key>\s*<string>([0-9a-f]{64})<\/string>/u);
+    if (restoredConfig?.enabled !== true || tokenMatch === null) {
+      throw fail('BRIDGE_LAUNCHCTL_ROLLBACK_FAILED', 'restored bridge LaunchAgent is not attestable');
+    }
+    await waitReady({ config: restoredConfig, instanceToken: tokenMatch[1], env });
+  }
+  return snapshot;
+}

package/src/bridge-server.mjs

@@ -0,0 +1,309 @@
+import { createServer, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { constants as fsConstants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import path from 'node:path';
+import { parseTree } from 'jsonc-parser';
+
+import {
+  BridgeConfigError, bridgeConfigPaths, normalizeBridgeAllowedHost, readBridgeConfig,
+} from './bridge-config.mjs';
+
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade',
+]);
+const UNTRUSTED_CLIENT_IP_HEADERS = new Set([
+  'cf-connecting-ip', 'client-ip', 'fastly-client-ip', 'true-client-ip',
+  'x-cluster-client-ip', 'x-proxyuser-ip',
+]);
+
+function dashboardRuntimeDir(env) {
+  const configured = env.LATTICE_DASHBOARD_RUNTIME_DIR;
+  return typeof configured === 'string' && path.isAbsolute(configured)
+    ? configured : path.join(bridgeConfigPaths(env).root, 'dashboard');
+}
+
+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;
+}
+
+async function readDashboardDescriptor(ref) {
+  let before;
+  let handle;
+  try {
+    before = await lstat(ref);
+    if (!before.isFile() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o600 || before.size > 65_536) {
+      throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor is 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 > 65_536) {
+      throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor 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 BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor changed during read');
+    }
+    const errors = [];
+    const tree = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
+    if (errors.length > 0 || tree === undefined || duplicateJsonKey(tree)) {
+      throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor JSON is invalid');
+    }
+    return JSON.parse(text);
+  } catch (error) {
+    if (error instanceof BridgeConfigError) throw error;
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_UNAVAILABLE', 'dashboard descriptor is unavailable', undefined, error);
+  } finally { await handle?.close(); }
+}
+
+export async function resolveBridgeUpstream(upstream, { env = process.env } = {}) {
+  if (upstream.mode === 'url') return new URL(upstream.url);
+  let descriptor;
+  try {
+    descriptor = await readDashboardDescriptor(path.join(dashboardRuntimeDir(env), 'daemon.json'));
+  } catch (error) {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_UNAVAILABLE', 'dashboard descriptor is unavailable', undefined, error);
+  }
+  if (descriptor?.schema !== 'lattice.todo_dashboard_daemon.v1'
+    || Object.keys(descriptor).sort().join(',') !== 'pid,port,schema,started_at'
+    || !Number.isSafeInteger(descriptor.pid) || descriptor.pid <= 0
+    || !Number.isSafeInteger(descriptor.port) || descriptor.port <= 0 || descriptor.port > 65_535
+    || typeof descriptor.started_at !== 'string') {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor is invalid');
+  }
+  try {
+    const response = await fetch(`http://127.0.0.1:${descriptor.port}/__lattice/health`, {
+      signal: AbortSignal.timeout(500),
+    });
+    const health = response.status === 200 ? await response.json() : null;
+    if (health?.schema !== 'lattice.todo_dashboard_health.v1' || health.pid !== descriptor.pid
+      || health.port !== descriptor.port) throw new Error('dashboard health mismatch');
+  } catch (error) {
+    throw new BridgeConfigError('BRIDGE_UPSTREAM_UNAVAILABLE',
+      'dashboard descriptor could not be attested against loopback health', undefined, error);
+  }
+  return new URL(`http://127.0.0.1:${descriptor.port}/`);
+}
+
+function responseError(response, status, code) {
+  if (response.headersSent) {
+    response.destroy();
+    return;
+  }
+  response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  response.end(`${JSON.stringify({ schema: 'lattice.bridge_http_error.v1', code })}\n`);
+}
+
+function connectionTokens(headers) {
+  const value = headers.connection;
+  return new Set((Array.isArray(value) ? value.join(',') : value ?? '')
+    .split(',').map((entry) => entry.trim().toLowerCase()).filter(Boolean));
+}
+
+function forwardHeaders(headers) {
+  const nominated = connectionTokens(headers);
+  return Object.fromEntries(Object.entries(headers)
+    .filter(([name, value]) => value !== undefined && name !== 'host'
+      && name.toLowerCase() !== 'forwarded' && name.toLowerCase() !== 'x-real-ip'
+      && !name.toLowerCase().startsWith('x-forwarded-')
+      && !UNTRUSTED_CLIENT_IP_HEADERS.has(name.toLowerCase())
+      && !HOP_BY_HOP.has(name.toLowerCase()) && !nominated.has(name.toLowerCase())));
+}
+
+function validatedRequestHost(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 512
+    || /[\s\\/@,]/u.test(value)) {
+    throw new BridgeConfigError('BRIDGE_HOST_INVALID', 'request Host is invalid');
+  }
+  let parsed;
+  try { parsed = new URL(`http://${value}`); } catch {
+    throw new BridgeConfigError('BRIDGE_HOST_INVALID', 'request Host is invalid');
+  }
+  if (parsed.username !== '' || parsed.password !== '' || parsed.pathname !== '/'
+    || parsed.search !== '' || parsed.hash !== '') {
+    throw new BridgeConfigError('BRIDGE_HOST_INVALID', 'request Host is invalid');
+  }
+  const rawHostname = parsed.hostname.startsWith('[') && parsed.hostname.endsWith(']')
+    ? parsed.hostname.slice(1, -1) : parsed.hostname;
+  const hostname = normalizeBridgeAllowedHost(rawHostname);
+  const authorityHost = hostname.includes(':') ? `[${hostname}]` : hostname;
+  return { hostname, authority: parsed.port === '' ? authorityHost : `${authorityHost}:${parsed.port}` };
+}
+
+function forwardedHeaders(incoming, host) {
+  const remote = incoming.socket.remoteAddress ?? 'unknown';
+  const forwardedFor = remote.includes(':') ? `"[${remote}]"` : remote;
+  return {
+    forwarded: `for=${forwardedFor};host="${host.authority}";proto=http`,
+    'x-forwarded-for': remote,
+    'x-forwarded-host': host.authority,
+    'x-forwarded-proto': 'http',
+    'x-real-ip': remote,
+  };
+}
+
+function upstreamUrl(base, requestUrl) {
+  if (typeof requestUrl !== 'string' || requestUrl.includes('#') || !/^\/(?!\/)[^\s]*$/u.test(requestUrl)) {
+    throw new BridgeConfigError('BRIDGE_REQUEST_TARGET_INVALID', 'bridge requires an origin-form request target');
+  }
+  const rawPath = requestUrl.split('?', 1)[0];
+  if (rawPath.includes('\\') || rawPath.includes('%')) {
+    throw new BridgeConfigError('BRIDGE_REQUEST_TARGET_INVALID',
+      'bridge request target contains encoded path bytes or a backslash');
+  }
+  if (rawPath.split('/').some((segment) => segment === '.' || segment === '..')) {
+    throw new BridgeConfigError('BRIDGE_REQUEST_TARGET_INVALID', 'bridge request target contains a dot segment');
+  }
+  const basePath = base.pathname.endsWith('/') ? base.pathname : `${base.pathname}/`;
+  const target = new URL(requestUrl.slice(1), base);
+  if (target.origin !== base.origin || !target.pathname.startsWith(basePath)) {
+    throw new BridgeConfigError('BRIDGE_REQUEST_TARGET_INVALID', 'bridge request target escapes upstream base');
+  }
+  return target;
+}
+
+function decodedRequestPath(requestUrl) {
+  if (typeof requestUrl !== 'string') return null;
+  try { return decodeURIComponent(requestUrl.split('?', 1)[0]); } catch { return null; }
+}
+
+export async function startBridgeServer({
+  config, env = process.env,
+  instanceToken = null,
+  resolveUpstream = (upstream) => resolveBridgeUpstream(upstream, { env }),
+} = {}) {
+  if (config?.enabled !== true) throw new BridgeConfigError('BRIDGE_DISABLED', 'bridge is disabled');
+  if (!Array.isArray(config.allowed_hosts) || config.allowed_hosts.length === 0) {
+    throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'bridge allowed hosts are required');
+  }
+  let allowedHosts = new Set(config.allowed_hosts);
+  let currentConfig = config;
+  const handleRequest = async (incoming, response) => {
+    let requestHost;
+    try { requestHost = validatedRequestHost(incoming.headers.host); } catch (error) {
+      responseError(response, 400, error?.code ?? 'BRIDGE_HOST_INVALID');
+      return;
+    }
+    if (!allowedHosts.has(requestHost.hostname)) {
+      responseError(response, 421, 'BRIDGE_HOST_NOT_ALLOWED');
+      return;
+    }
+    if (incoming.url === '/__lattice/bridge-health') {
+      response.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+      const attested = typeof instanceToken === 'string'
+        && incoming.headers['x-lattice-bridge-instance-token'] === instanceToken;
+      response.end(`${JSON.stringify(attested
+        ? { schema: 'lattice.bridge_health.v1', pid: process.pid,
+          address: currentConfig.listen.address, port: currentConfig.listen.port,
+          updated_at: currentConfig.updated_at ?? null }
+        : { schema: 'lattice.bridge_health.v1', status: 'available' })}\n`);
+      return;
+    }
+    if (decodedRequestPath(incoming.url) === '/__lattice/health') {
+      responseError(response, 404, 'BRIDGE_INTERNAL_PATH_DENIED');
+      return;
+    }
+    let target;
+    try { target = upstreamUrl(await resolveUpstream(currentConfig.upstream), incoming.url); } catch (error) {
+      responseError(response, error?.code === 'BRIDGE_REQUEST_TARGET_INVALID' ? 400 : 503,
+        error?.code ?? 'BRIDGE_UPSTREAM_UNAVAILABLE');
+      return;
+    }
+    let upstreamResponse = null;
+    const request = (target.protocol === 'https:' ? httpsRequest : httpRequest)(target, {
+      method: incoming.method,
+      headers: { ...forwardHeaders(incoming.headers), ...forwardedHeaders(incoming, requestHost), host: target.host },
+    }, (incomingResponse) => {
+      upstreamResponse = incomingResponse;
+      response.writeHead(incomingResponse.statusCode ?? 502, forwardHeaders(incomingResponse.headers));
+      incomingResponse.once('error', () => response.destroy());
+      incomingResponse.pipe(response);
+    });
+    request.once('error', (error) => responseError(response, 502,
+      error?.code === 'ECONNREFUSED' ? 'BRIDGE_UPSTREAM_REFUSED' : 'BRIDGE_PROXY_FAILED'));
+    incoming.once('aborted', () => request.destroy());
+    response.once('close', () => {
+      if (!response.writableFinished) {
+        request.destroy();
+        upstreamResponse?.destroy();
+      }
+    });
+    incoming.pipe(request);
+  };
+  const server = createServer((incoming, response) => {
+    handleRequest(incoming, response).catch((error) => responseError(response, 500,
+      error?.code ?? 'BRIDGE_REQUEST_FAILED'));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen({ host: config.listen.address, port: config.listen.port, exclusive: true }, resolve);
+  }).catch((error) => {
+    throw new BridgeConfigError(error?.code === 'EADDRINUSE' ? 'BRIDGE_PORT_UNAVAILABLE' : 'BRIDGE_BIND_FAILED',
+      'bridge listen failed', { ...config.listen }, error);
+  });
+  let closed = false;
+  return Object.freeze({
+    address: config.listen.address,
+    port: config.listen.port,
+    updateConfig(next) {
+      if (next?.enabled !== true || next.listen.address !== config.listen.address
+        || next.listen.port !== config.listen.port) {
+        throw new BridgeConfigError('BRIDGE_RECONFIGURE_INVALID', 'live bridge binding cannot be mutated in place');
+      }
+      currentConfig = next;
+      allowedHosts = new Set(next.allowed_hosts);
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      const completion = new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+      server.closeAllConnections?.();
+      await completion;
+    },
+  });
+}
+
+export function bridgeRuntimeController({ env = process.env, instanceToken = null } = {}) {
+  let active = null;
+  let fingerprint = null;
+  return Object.freeze({
+    async reconcile() {
+      const config = await readBridgeConfig({ env });
+      const next = config === null || !config.enabled ? null : JSON.stringify(config);
+      if (next === fingerprint) return active;
+      if (next === null) {
+        await active?.close();
+        active = null;
+        fingerprint = null;
+        return null;
+      }
+      if (active !== null && active.address === config.listen.address && active.port === config.listen.port) {
+        active.updateConfig(config);
+        fingerprint = next;
+        return active;
+      }
+      const replacement = await startBridgeServer({ config, env, instanceToken });
+      const previous = active;
+      active = replacement;
+      fingerprint = next;
+      await previous?.close();
+      return active;
+    },
+    async close() {
+      await active?.close();
+      active = null;
+      fingerprint = null;
+    },
+  });
+}