sneakoscope 7.3.0 → 7.6.0

package/dist/core/codex-lb/desktop-bridge/launchd.js

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DesktopBridgeError } from './types.js';
+export const DESKTOP_BRIDGE_LAUNCHD_LABEL = 'com.sneakoscope.codex-lb-desktop-bridge';
+export function desktopBridgeLaunchdPlistPath(home = os.homedir()) {
+    return path.join(home, 'Library', 'LaunchAgents', `${DESKTOP_BRIDGE_LAUNCHD_LABEL}.plist`);
+}
+function xml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function assertSafeLaunchdValue(value) {
+    if (!value || /[\0\r\n]/.test(value))
+        throw new DesktopBridgeError('bridge_launchd_value_invalid');
+}
+export function renderDesktopBridgeLaunchdPlist(options) {
+    assertSafeLaunchdValue(options.executablePath);
+    if (!path.isAbsolute(options.executablePath))
+        throw new DesktopBridgeError('bridge_launchd_executable_not_absolute');
+    for (const argument of options.arguments) {
+        assertSafeLaunchdValue(argument);
+        if (/^(?:--?(?:(?:api|gateway|access|auth|bearer)[-_]?(?:key|token)|authorization|x-codex-lb-api-key)(?:=|$)|gatewayKey(?:=|$)|(?:CODEX_LB_API_KEY|SKS_CODEX_LB_API_KEY|AUTHORIZATION|ACCESS_TOKEN)=)/i
+            .test(argument)) {
+            throw new DesktopBridgeError('bridge_launchd_secret_argument_forbidden');
+        }
+    }
+    for (const logPath of [options.stdoutPath, options.stderrPath]) {
+        assertSafeLaunchdValue(logPath);
+        if (!path.isAbsolute(logPath))
+            throw new DesktopBridgeError('bridge_launchd_log_path_not_absolute');
+    }
+    const programArguments = [options.executablePath, ...options.arguments]
+        .map((value) => `      <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>${DESKTOP_BRIDGE_LAUNCHD_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+${programArguments}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+    <key>StandardOutPath</key>
+    <string>${xml(options.stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xml(options.stderrPath)}</string>
+  </dict>
+</plist>
+`;
+}
+export async function writeDesktopBridgeLaunchdPlist(file, options) {
+    const contents = renderDesktopBridgeLaunchdPlist(options);
+    const directory = path.dirname(file);
+    await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
+    const temp = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await fsp.writeFile(temp, contents, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await fsp.rename(temp, file);
+        await fsp.chmod(file, 0o600);
+    }
+    finally {
+        await fsp.rm(temp, { force: true }).catch(() => undefined);
+    }
+}

package/dist/core/codex-lb/desktop-bridge/location-rewrite.js

@@ -0,0 +1,27 @@
+import { DesktopBridgeError } from './types.js';
+export function rewriteLocationHeader(value, remoteBaseUrl, localOrigin) {
+    const remote = new URL(remoteBaseUrl);
+    const location = new URL(value, remote.origin);
+    const remoteWebSocketProtocol = remote.protocol === 'https:' ? 'wss:' : 'ws:';
+    const allowedProtocol = location.protocol === remote.protocol || location.protocol === remoteWebSocketProtocol;
+    const remotePort = remote.port || (remote.protocol === 'https:' ? '443' : '80');
+    const locationPort = location.port
+        || (location.protocol === 'https:' || location.protocol === 'wss:' ? '443' : '80');
+    if (!allowedProtocol
+        || location.hostname.toLowerCase() !== remote.hostname.toLowerCase()
+        || locationPort !== remotePort) {
+        throw new DesktopBridgeError('bridge_location_origin_forbidden');
+    }
+    const local = new URL(localOrigin);
+    local.pathname = location.pathname;
+    local.search = location.search;
+    local.hash = '';
+    if (location.protocol === 'wss:' || location.protocol === 'ws:')
+        local.protocol = 'ws:';
+    else if (location.protocol === 'https:' || location.protocol === 'http:')
+        local.protocol = 'http:';
+    else {
+        throw new DesktopBridgeError('bridge_location_protocol_forbidden');
+    }
+    return local.toString();
+}

package/dist/core/codex-lb/desktop-bridge/security.js

@@ -0,0 +1,274 @@
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import { DesktopBridgeError } from './types.js';
+const MIN_HIGH_PORT = 49_152;
+const MAX_PORT = 65_535;
+const FORBIDDEN_REMOTE_ADDRESSES = new net.BlockList();
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('0.0.0.0', 8, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('10.0.0.0', 8, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('100.64.0.0', 10, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('169.254.0.0', 16, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('172.16.0.0', 12, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('192.0.0.0', 24, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('192.0.2.0', 24, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('192.168.0.0', 16, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('198.18.0.0', 15, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('198.51.100.0', 24, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('203.0.113.0', 24, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('224.0.0.0', 4, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('240.0.0.0', 4, 'ipv4');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('::', 128, 'ipv6');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('::1', 128, 'ipv6');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('fc00::', 7, 'ipv6');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('fe80::', 10, 'ipv6');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('ff00::', 8, 'ipv6');
+FORBIDDEN_REMOTE_ADDRESSES.addSubnet('2001:db8::', 32, 'ipv6');
+export function assertLoopbackPeer(address) {
+    const normalized = String(address || '').replace(/^::ffff:/i, '');
+    if (!net.isIP(normalized))
+        throw new DesktopBridgeError('bridge_peer_not_ip');
+    if (normalized !== '127.0.0.1' && normalized !== '::1') {
+        throw new DesktopBridgeError('bridge_non_loopback_peer');
+    }
+}
+export function assertLoopbackListenHost(host) {
+    if (host !== '127.0.0.1' && host !== '::1') {
+        throw new DesktopBridgeError('bridge_listen_host_not_loopback');
+    }
+}
+export function assertAllowedPath(pathname, prefixes) {
+    if (!pathname.startsWith('/') || pathname.includes('\\') || /%(?:2f|5c)/i.test(pathname)) {
+        throw new DesktopBridgeError('bridge_path_invalid');
+    }
+    const allowed = prefixes.some((prefix) => {
+        if (!prefix.startsWith('/'))
+            return false;
+        if (prefix.endsWith('/'))
+            return pathname.startsWith(prefix);
+        return pathname === prefix || pathname.startsWith(`${prefix}/`);
+    });
+    if (!allowed)
+        throw new DesktopBridgeError('bridge_path_not_allowed');
+}
+function headerValues(value) {
+    return (Array.isArray(value) ? value : value === undefined ? [] : [value])
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function comparableOrigin(value, referer) {
+    if (value === 'null')
+        return 'null';
+    try {
+        const parsed = new URL(value);
+        if (referer) {
+            return parsed.origin !== 'null' ? parsed.origin : `${parsed.protocol}//${parsed.host}`;
+        }
+        if ((parsed.pathname !== '/' && parsed.pathname !== '') || parsed.search || parsed.hash) {
+            throw new Error('origin_has_path');
+        }
+        return parsed.origin !== 'null' ? parsed.origin : `${parsed.protocol}//${parsed.host}`;
+    }
+    catch {
+        throw new DesktopBridgeError('bridge_origin_invalid');
+    }
+}
+export function normalizeAllowedOrigin(value) {
+    return comparableOrigin(String(value || '').trim(), false);
+}
+export function assertAllowedOrigin(headers, allowedOrigins) {
+    const origins = headerValues(headers.origin);
+    const referers = headerValues(headers.referer);
+    if (origins.length === 0 && referers.length === 0)
+        return;
+    if (origins.length > 1 || referers.length > 1)
+        throw new DesktopBridgeError('bridge_origin_forbidden');
+    const allowed = new Set(allowedOrigins.map(normalizeAllowedOrigin));
+    for (const origin of origins) {
+        if (!allowed.has(comparableOrigin(origin, false)))
+            throw new DesktopBridgeError('bridge_origin_forbidden');
+    }
+    for (const referer of referers) {
+        if (!allowed.has(comparableOrigin(referer, true)))
+            throw new DesktopBridgeError('bridge_origin_forbidden');
+    }
+}
+export function assertWebSocketUpgrade(headers, method) {
+    const connection = headerValues(headers.connection).join(',').toLowerCase().split(',').map((part) => part.trim());
+    const upgrade = headerValues(headers.upgrade);
+    const key = headerValues(headers['sec-websocket-key']);
+    const version = headerValues(headers['sec-websocket-version']);
+    if (method !== 'GET'
+        || !connection.includes('upgrade')
+        || upgrade.length !== 1
+        || upgrade[0]?.toLowerCase() !== 'websocket'
+        || key.length !== 1
+        || version.length !== 1) {
+        throw new DesktopBridgeError('bridge_websocket_upgrade_invalid');
+    }
+}
+function stripIpv6Brackets(hostname) {
+    return hostname.replace(/^\[/, '').replace(/\]$/, '');
+}
+function isLoopbackAddress(address) {
+    const normalized = address.replace(/^::ffff:/i, '');
+    if (normalized === '::1')
+        return true;
+    if (net.isIP(normalized) !== 4)
+        return false;
+    return Number(normalized.split('.')[0]) === 127;
+}
+function isExplicitLoopbackHostname(hostname) {
+    const normalized = stripIpv6Brackets(hostname).replace(/\.$/, '').toLowerCase();
+    return normalized === 'localhost' || isLoopbackAddress(normalized);
+}
+function isForbiddenRemoteAddress(address, family) {
+    const dottedMapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1];
+    const hexMapped = address.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    const mapped = dottedMapped || (hexMapped
+        ? [
+            Number.parseInt(hexMapped[1] || '0', 16) >> 8,
+            Number.parseInt(hexMapped[1] || '0', 16) & 0xff,
+            Number.parseInt(hexMapped[2] || '0', 16) >> 8,
+            Number.parseInt(hexMapped[2] || '0', 16) & 0xff,
+        ].join('.')
+        : undefined);
+    if (mapped)
+        return FORBIDDEN_REMOTE_ADDRESSES.check(mapped, 'ipv4');
+    return FORBIDDEN_REMOTE_ADDRESSES.check(address, family === 4 ? 'ipv4' : 'ipv6');
+}
+export function validateDesktopBridgeConfig(config) {
+    assertLoopbackListenHost(config.listenHost);
+    if (!Number.isInteger(config.listenPort) || config.listenPort < MIN_HIGH_PORT || config.listenPort > MAX_PORT) {
+        throw new DesktopBridgeError('bridge_listen_port_not_high');
+    }
+    if (!config.gatewayKey || /[\r\n\0]/.test(config.gatewayKey)) {
+        throw new DesktopBridgeError('bridge_gateway_key_invalid');
+    }
+    if (config.gatewayAuthTransport !== 'x-codex-lb-api-key' && config.gatewayAuthTransport !== 'authorization-bearer-compat') {
+        throw new DesktopBridgeError('bridge_gateway_auth_transport_invalid');
+    }
+    if (!Array.isArray(config.allowedPathPrefixes) || config.allowedPathPrefixes.length === 0) {
+        throw new DesktopBridgeError('bridge_path_allowlist_empty');
+    }
+    if (!Number.isFinite(config.connectTimeoutMs) || config.connectTimeoutMs < 100 || config.connectTimeoutMs > 120_000) {
+        throw new DesktopBridgeError('bridge_connect_timeout_invalid');
+    }
+    if (!Number.isFinite(config.idleTimeoutMs) || config.idleTimeoutMs < 1_000 || config.idleTimeoutMs > 86_400_000) {
+        throw new DesktopBridgeError('bridge_idle_timeout_invalid');
+    }
+    for (const prefix of config.allowedPathPrefixes) {
+        if (!prefix.startsWith('/') || prefix.includes('?') || prefix.includes('#') || prefix.includes('\\')) {
+            throw new DesktopBridgeError('bridge_path_allowlist_invalid');
+        }
+    }
+    for (const origin of config.allowedOrigins)
+        normalizeAllowedOrigin(origin);
+    let remote;
+    try {
+        remote = new URL(config.remoteBaseUrl);
+    }
+    catch {
+        throw new DesktopBridgeError('bridge_remote_url_invalid');
+    }
+    if (remote.username || remote.password)
+        throw new DesktopBridgeError('bridge_remote_userinfo_forbidden');
+    if (remote.hash || remote.search)
+        throw new DesktopBridgeError('bridge_remote_base_url_query_forbidden');
+    if (remote.protocol !== 'https:' && !(remote.protocol === 'http:' && isExplicitLoopbackHostname(remote.hostname))) {
+        throw new DesktopBridgeError('bridge_remote_transport_forbidden');
+    }
+    return remote;
+}
+const defaultLookup = async (hostname) => {
+    const rows = await dns.lookup(hostname, { all: true, verbatim: true });
+    return rows.map((row) => {
+        if (row.family !== 4 && row.family !== 6)
+            throw new DesktopBridgeError('bridge_remote_dns_invalid');
+        return { address: row.address, family: row.family };
+    });
+};
+export async function prepareDesktopBridgeConfig(config, lookup = defaultLookup) {
+    const remote = validateDesktopBridgeConfig(config);
+    const hostname = stripIpv6Brackets(remote.hostname);
+    const literalFamily = net.isIP(hostname);
+    let addresses;
+    try {
+        addresses = literalFamily
+            ? [{ address: hostname, family: literalFamily }]
+            : await lookup(hostname);
+    }
+    catch (error) {
+        throw new DesktopBridgeError('bridge_remote_dns_failed', { cause: error });
+    }
+    if (addresses.length === 0)
+        throw new DesktopBridgeError('bridge_remote_dns_empty');
+    if (addresses.some((row) => net.isIP(row.address) !== row.family)) {
+        throw new DesktopBridgeError('bridge_remote_dns_invalid');
+    }
+    const explicitLoopback = isExplicitLoopbackHostname(hostname);
+    if (explicitLoopback) {
+        if (addresses.some((row) => !isLoopbackAddress(row.address))) {
+            throw new DesktopBridgeError('bridge_remote_dns_rebinding_blocked');
+        }
+    }
+    else if (addresses.some((row) => isForbiddenRemoteAddress(row.address, row.family))) {
+        throw new DesktopBridgeError('bridge_remote_dns_private_address');
+    }
+    const selected = addresses[0];
+    if (!selected)
+        throw new DesktopBridgeError('bridge_remote_dns_empty');
+    const port = Number(remote.port || (remote.protocol === 'https:' ? 443 : 80));
+    const remoteTarget = {
+        baseUrl: remote.toString().replace(/\/$/, ''),
+        origin: remote.origin,
+        hostname,
+        port,
+        secure: remote.protocol === 'https:',
+        address: selected.address,
+        family: selected.family,
+        ...(literalFamily ? {} : { tlsServername: hostname }),
+    };
+    return { ...config, remoteBaseUrl: remoteTarget.baseUrl, remote: remoteTarget };
+}
+export function validatePreparedDesktopBridgeConfig(config) {
+    const remoteUrl = validateDesktopBridgeConfig(config);
+    const expectedHostname = stripIpv6Brackets(remoteUrl.hostname);
+    const expectedPort = Number(remoteUrl.port || (remoteUrl.protocol === 'https:' ? 443 : 80));
+    if (config.remote.origin !== remoteUrl.origin
+        || config.remote.hostname !== expectedHostname
+        || config.remote.port !== expectedPort
+        || config.remote.secure !== (remoteUrl.protocol === 'https:')
+        || net.isIP(config.remote.address) !== config.remote.family) {
+        throw new DesktopBridgeError('bridge_prepared_config_invalid');
+    }
+    if (isExplicitLoopbackHostname(expectedHostname)) {
+        if (!isLoopbackAddress(config.remote.address)) {
+            throw new DesktopBridgeError('bridge_remote_dns_rebinding_blocked');
+        }
+    }
+    else if (isForbiddenRemoteAddress(config.remote.address, config.remote.family)) {
+        throw new DesktopBridgeError('bridge_remote_dns_private_address');
+    }
+}
+export function resolveDesktopBridgeTarget(rawRequestUrl, remote) {
+    const raw = String(rawRequestUrl || '/');
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) || raw.startsWith('//') || /[\r\n\0]/.test(raw)) {
+        throw new DesktopBridgeError('bridge_request_target_invalid');
+    }
+    let inbound;
+    try {
+        inbound = new URL(raw, 'http://bridge.invalid');
+    }
+    catch {
+        throw new DesktopBridgeError('bridge_request_target_invalid');
+    }
+    return new URL(`${inbound.pathname}${inbound.search}`, remote.origin);
+}
+export function safeBridgeErrorCode(error) {
+    if (error instanceof DesktopBridgeError)
+        return error.code;
+    if (error instanceof Error && /^bridge_[a-z0-9_]+$/.test(error.message))
+        return error.message;
+    return 'bridge_upstream_unavailable';
+}

package/dist/core/codex-lb/desktop-bridge/server.js

@@ -0,0 +1,179 @@
+import { randomInt } from 'node:crypto';
+import http, {} from 'node:http';
+import net, {} from 'node:net';
+import { forwardHttp } from './http-forward.js';
+import { assertAllowedOrigin, assertAllowedPath, assertLoopbackPeer, assertLoopbackListenHost, assertWebSocketUpgrade, prepareDesktopBridgeConfig, safeBridgeErrorCode, validatePreparedDesktopBridgeConfig, } from './security.js';
+import { createDesktopBridgePublicState, desktopBridgeStatePath, removeDesktopBridgeStateIfOwned, writeDesktopBridgeState, } from './state.js';
+import { DesktopBridgeError } from './types.js';
+import { forwardWebSocket } from './websocket-forward.js';
+function pathnameFromRequest(req) {
+    try {
+        return new URL(req.url || '/', 'http://bridge.invalid').pathname;
+    }
+    catch {
+        throw new DesktopBridgeError('bridge_request_target_invalid');
+    }
+}
+function rejectionStatus(code) {
+    if (code === 'bridge_path_not_allowed')
+        return 404;
+    if (code.includes('origin') || code.includes('peer') || code.includes('loopback'))
+        return 403;
+    return 400;
+}
+function writeBridgeRejection(res, error) {
+    if (res.headersSent) {
+        res.destroy(error instanceof Error ? error : undefined);
+        return;
+    }
+    const code = safeBridgeErrorCode(error);
+    res.writeHead(rejectionStatus(code), {
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+        connection: 'close',
+    });
+    res.end(JSON.stringify({ error: { type: 'sks_bridge_rejection', code, message: code } }));
+}
+function writeUpgradeRejection(socket, error) {
+    if (socket.destroyed)
+        return;
+    const code = safeBridgeErrorCode(error);
+    const status = rejectionStatus(code);
+    socket.end(`HTTP/1.1 ${status} ${status === 404 ? 'Not Found' : status === 403 ? 'Forbidden' : 'Bad Request'}\r\n`
+        + 'Content-Type: application/json\r\n'
+        + 'Cache-Control: no-store\r\n'
+        + 'Connection: close\r\n'
+        + '\r\n'
+        + JSON.stringify({ error: { type: 'sks_bridge_rejection', code, message: code } }));
+}
+async function listenExact(server, host, port) {
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            if (error.code === 'EADDRINUSE')
+                reject(new DesktopBridgeError('bridge_port_conflict', { cause: error }));
+            else
+                reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen({ host, port, exclusive: true });
+    });
+}
+async function closeServer(server, sockets) {
+    for (const socket of sockets)
+        socket.destroy();
+    if (!server.listening)
+        return;
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+export async function selectAvailableDesktopBridgePort(host, attempts = 64) {
+    assertLoopbackListenHost(host);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const port = randomInt(49_152, 65_536);
+        const probe = net.createServer();
+        try {
+            await listenExact(probe, host, port);
+            await closeServer(probe, new Set());
+            return port;
+        }
+        catch (error) {
+            await closeServer(probe, new Set()).catch(() => undefined);
+            if (error instanceof DesktopBridgeError && error.code === 'bridge_port_conflict')
+                continue;
+            throw error;
+        }
+    }
+    throw new DesktopBridgeError('bridge_no_available_high_port');
+}
+export const preflightDesktopBridge = prepareDesktopBridgeConfig;
+export async function startPreparedDesktopBridge(input, options = {}) {
+    validatePreparedDesktopBridgeConfig(input);
+    const sockets = new Set();
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            try {
+                assertLoopbackPeer(req.socket.remoteAddress);
+                assertAllowedOrigin(req.headers, input.allowedOrigins);
+                assertAllowedPath(pathnameFromRequest(req), input.allowedPathPrefixes);
+                await forwardHttp(req, res, input);
+            }
+            catch (error) {
+                req.resume();
+                writeBridgeRejection(res, error);
+            }
+        })();
+    });
+    server.requestTimeout = 0;
+    server.headersTimeout = Math.max(5_000, input.connectTimeoutMs);
+    server.keepAliveTimeout = Math.min(input.idleTimeoutMs, 60_000);
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    });
+    server.on('clientError', (_error, socket) => {
+        if (!socket.destroyed)
+            socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+    });
+    server.on('upgrade', (req, socket, head) => {
+        try {
+            assertLoopbackPeer(req.socket.remoteAddress);
+            assertAllowedOrigin(req.headers, input.allowedOrigins);
+            assertAllowedPath(pathnameFromRequest(req), input.allowedPathPrefixes);
+            assertWebSocketUpgrade(req.headers, req.method);
+            forwardWebSocket(req, socket, head, input);
+        }
+        catch (error) {
+            writeUpgradeRejection(socket, error);
+        }
+    });
+    await listenExact(server, input.listenHost, input.listenPort);
+    const state = createDesktopBridgePublicState(input, {
+        ...(options.pid === undefined ? {} : { pid: options.pid }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const shouldWriteState = options.writeState !== false;
+    const statePath = shouldWriteState ? (options.statePath || desktopBridgeStatePath()) : null;
+    try {
+        if (statePath)
+            await writeDesktopBridgeState(statePath, state);
+    }
+    catch (error) {
+        await closeServer(server, sockets);
+        throw error;
+    }
+    let stopped = false;
+    const handle = {
+        server,
+        state,
+        statePath,
+        sockets,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            await closeServer(server, sockets);
+            if (statePath)
+                await removeDesktopBridgeStateIfOwned(statePath, state);
+        },
+    };
+    return handle;
+}
+export async function startDesktopBridge(input, options = {}) {
+    const prepared = await preflightDesktopBridge(input);
+    return startPreparedDesktopBridge(prepared, options);
+}
+export async function stopDesktopBridge(handle) {
+    await handle.stop();
+}

package/dist/core/codex-lb/desktop-bridge/state.js

@@ -0,0 +1,119 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DESKTOP_BRIDGE_STATE_SCHEMA, DesktopBridgeError } from './types.js';
+export function desktopBridgeStatePath(home = os.homedir()) {
+    return path.join(home, '.codex', 'sks', 'codex-lb-desktop-bridge.json');
+}
+export function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function desktopBridgeListenOrigin(config) {
+    const host = config.listenHost === '::1' ? '[::1]' : config.listenHost;
+    return `http://${host}:${config.listenPort}`;
+}
+export function desktopBridgeConfigGeneration(config) {
+    const stable = JSON.stringify({
+        listenHost: config.listenHost,
+        listenPort: config.listenPort,
+        remoteBaseUrl: new URL(config.remoteBaseUrl).toString().replace(/\/$/, ''),
+        gatewayKeySha256: sha256Hex(config.gatewayKey),
+        gatewayAuthTransport: config.gatewayAuthTransport,
+        allowedPathPrefixes: [...config.allowedPathPrefixes],
+        allowedOrigins: [...config.allowedOrigins],
+        connectTimeoutMs: config.connectTimeoutMs,
+        idleTimeoutMs: config.idleTimeoutMs,
+    });
+    return sha256Hex(stable);
+}
+export function createDesktopBridgePublicState(config, options = {}) {
+    const listenOrigin = desktopBridgeListenOrigin(config);
+    const remote = new URL(config.remoteBaseUrl);
+    return {
+        schema: DESKTOP_BRIDGE_STATE_SCHEMA,
+        pid: options.pid ?? process.pid,
+        started_at: (options.now ?? new Date()).toISOString(),
+        listen_origin: listenOrigin,
+        codex_base_url: `${listenOrigin}/backend-api/codex`,
+        remote_origin_sha256: sha256Hex(remote.origin),
+        gateway_key_sha256: sha256Hex(config.gatewayKey),
+        gateway_auth_transport: config.gatewayAuthTransport,
+        config_generation: desktopBridgeConfigGeneration(config),
+    };
+}
+export function isDesktopBridgePublicState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return row.schema === DESKTOP_BRIDGE_STATE_SCHEMA
+        && Number.isInteger(row.pid)
+        && Number(row.pid) > 0
+        && typeof row.started_at === 'string'
+        && Number.isFinite(Date.parse(row.started_at))
+        && typeof row.listen_origin === 'string'
+        && /^http:\/\/(?:127\.0\.0\.1|\[::1\]):\d+$/.test(row.listen_origin)
+        && typeof row.codex_base_url === 'string'
+        && row.codex_base_url === `${row.listen_origin}/backend-api/codex`
+        && typeof row.remote_origin_sha256 === 'string'
+        && /^[a-f0-9]{64}$/.test(row.remote_origin_sha256)
+        && typeof row.gateway_key_sha256 === 'string'
+        && /^[a-f0-9]{64}$/.test(row.gateway_key_sha256)
+        && (row.gateway_auth_transport === 'x-codex-lb-api-key' || row.gateway_auth_transport === 'authorization-bearer-compat')
+        && typeof row.config_generation === 'string'
+        && /^[a-f0-9]{64}$/.test(row.config_generation);
+}
+export async function writeDesktopBridgeState(file, state) {
+    if (!isDesktopBridgePublicState(state))
+        throw new DesktopBridgeError('bridge_state_invalid');
+    const directory = path.dirname(file);
+    await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
+    const temp = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await fsp.writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await fsp.chmod(temp, 0o600);
+        await fsp.rename(temp, file);
+        await fsp.chmod(file, 0o600);
+    }
+    finally {
+        await fsp.rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+export async function readDesktopBridgeState(file) {
+    let stat;
+    try {
+        stat = await fsp.lstat(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!stat.isFile())
+        throw new DesktopBridgeError('bridge_state_not_file');
+    if ((stat.mode & 0o077) !== 0)
+        throw new DesktopBridgeError('bridge_state_permissions_unsafe');
+    const raw = await fsp.readFile(file, 'utf8');
+    if (raw.length > 64 * 1024)
+        throw new DesktopBridgeError('bridge_state_too_large');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new DesktopBridgeError('bridge_state_invalid_json');
+    }
+    if (!isDesktopBridgePublicState(value))
+        throw new DesktopBridgeError('bridge_state_invalid');
+    return value;
+}
+export async function removeDesktopBridgeStateIfOwned(file, expected) {
+    const current = await readDesktopBridgeState(file).catch(() => null);
+    if (!current || current.pid !== expected.pid || current.config_generation !== expected.config_generation)
+        return false;
+    await fsp.unlink(file).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    });
+    return true;
+}