sneakoscope 8.1.2 → 8.2.0

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

@@ -1,13 +1,11 @@
 import dns from 'node:dns/promises';
 import net from 'node:net';
-import { DesktopBridgeError } from './types.js';
-import { assertProviderModeModel } from '../../codex-app/provider-mode.js';
-import { parseProviderPolicySnapshot, stableArchitectureHash, } from '../../architecture-hardening/contracts/contracts.js';
-import { decideProviderRoute } from '../provider-routing/provider-router.js';
-import { decideChildSelection } from '../../codex-app/child-policy/child-policy.js';
-import { assertSessionRequest, resumeSessionPin, sessionPinHash, } from '../../codex-app/session-policy/session-pinning.js';
+import { canonicalizeBridgeModelId, normalizeBridgeUpstreamModelId, } from '../route-index.js';
+import { DESKTOP_BRIDGE_CLIENT_PATH_PREFIX, DesktopBridgeError } from './types.js';
 const MIN_HIGH_PORT = 49_152;
 const MAX_PORT = 65_535;
+const MAX_SESSION_PINS = 10_000;
+const sessionPinMutationQueues = new WeakMap();
 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');
@@ -15,12 +13,7 @@ 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');
@@ -28,133 +21,103 @@ 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') {
+    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') {
+    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}/`);
-    });
+    const allowed = prefixes.some((prefix) => prefix.endsWith('/')
+        ? pathname.startsWith(prefix)
+        : pathname === prefix || pathname.startsWith(`${prefix}/`));
     if (!allowed)
         throw new DesktopBridgeError('bridge_path_not_allowed');
 }
+export function desktopBridgeClientPath(capability, canonicalPath) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(capability))
+        throw new DesktopBridgeError('bridge_client_capability_invalid');
+    if (!canonicalPath.startsWith('/') || canonicalPath.includes('\\') || /[\r\n\0]/.test(canonicalPath)) {
+        throw new DesktopBridgeError('bridge_request_target_invalid');
+    }
+    return `${DESKTOP_BRIDGE_CLIENT_PATH_PREFIX}/${capability}${canonicalPath}`;
+}
 function headerValues(value) {
-    return (Array.isArray(value) ? value : value === undefined ? [] : [value])
-        .map((entry) => entry.trim())
-        .filter(Boolean);
+    return (Array.isArray(value) ? value : value === undefined ? [] : [value]).map((v) => v.trim()).filter(Boolean);
 }
-function singlePolicyHeader(headers, name) {
-    const values = headerValues(headers[name]);
+export function singleBridgeHeader(headers, name) {
+    const values = headerValues(headers[name.toLowerCase()]);
     if (values.length > 1)
         throw new DesktopBridgeError('bridge_policy_header_ambiguous');
     return values[0] || null;
 }
-export function assertDesktopBridgeRequestPolicy(input) {
-    const { config } = input;
-    if (!config.providerMode)
-        return;
-    const requestedMode = singlePolicyHeader(input.headers, 'x-sks-provider-mode');
-    if (requestedMode && requestedMode !== config.providerMode) {
-        throw new DesktopBridgeError('bridge_provider_route_cross_mode_forbidden');
-    }
-    const policy = config.providerPolicy;
-    if (!policy) {
-        if (input.model !== undefined) {
-            try {
-                assertProviderModeModel(config.providerMode, input.model, config.allowedModels || []);
-            }
-            catch (error) {
-                throw new DesktopBridgeError(`bridge_${error.message}`);
-            }
+function codexMetadataObject(value, source) {
+    if (value === undefined || value === null)
+        return null;
+    let parsed = value;
+    if (source === 'header') {
+        if (typeof value !== 'string' || Buffer.byteLength(value) > 16 * 1024) {
+            throw new DesktopBridgeError('bridge_codex_turn_metadata_invalid');
+        }
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            throw new DesktopBridgeError('bridge_codex_turn_metadata_invalid');
         }
-        if (config.requireSessionPin)
-            throw new DesktopBridgeError('bridge_session_policy_missing');
-        return;
     }
-    const credential = config.credentialReadiness || {
-        status: 'unavailable',
-        reason_code: 'bridge_credential_readiness_missing',
-    };
-    if (input.model !== undefined) {
-        const route = decideProviderRoute({
-            policy,
-            credential,
-            requestedMode: (requestedMode || config.providerMode),
-            model: String(input.model || ''),
-        });
-        if (!route.ok)
-            throw new DesktopBridgeError(`bridge_${route.blockers[0] || 'provider_route_blocked'}`);
-    }
-    const sessionId = singlePolicyHeader(input.headers, 'x-sks-session-id');
-    if (!sessionId) {
-        if (config.requireSessionPin)
-            throw new DesktopBridgeError('bridge_session_pin_required');
-        return;
-    }
-    const pin = (config.sessionPins || []).find((entry) => entry.session_id === sessionId);
-    if (!pin)
-        throw new DesktopBridgeError('bridge_session_pin_unknown');
-    const resume = resumeSessionPin(pin, policy);
-    if (!resume.ok)
-        throw new DesktopBridgeError(`bridge_${resume.blocker || 'session_pin_blocked'}`);
-    const childFlag = singlePolicyHeader(input.headers, 'x-sks-child-request');
-    if (childFlag && childFlag !== '1')
-        throw new DesktopBridgeError('bridge_child_request_header_invalid');
-    const childHash = singlePolicyHeader(input.headers, 'x-sks-child-policy-hash') || policy.child_policy_hash;
-    const requestModel = String(input.model === undefined ? pin.model : input.model || '');
-    try {
-        assertSessionRequest(pin, {
-            mode: config.providerMode,
-            model: childFlag === '1' ? pin.model : requestModel,
-            childPolicyHash: childHash,
-        });
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new DesktopBridgeError(source === 'header'
+            ? 'bridge_codex_turn_metadata_invalid'
+            : 'bridge_codex_client_metadata_invalid');
     }
-    catch (error) {
-        throw new DesktopBridgeError(`bridge_${error.message}`);
-    }
-    if (childFlag !== '1')
-        return;
-    const childPolicy = config.childPolicy;
-    if (!childPolicy)
-        throw new DesktopBridgeError('bridge_child_policy_missing');
-    const parentHash = singlePolicyHeader(input.headers, 'x-sks-parent-snapshot-hash');
-    if (!parentHash || parentHash !== sessionPinHash(pin)) {
-        throw new DesktopBridgeError('bridge_child_parent_snapshot_mismatch');
-    }
-    const requestedChildModel = singlePolicyHeader(input.headers, 'x-sks-child-model') || requestModel;
-    const child = decideChildSelection({ session: pin, policy: childPolicy, requestedModel: requestedChildModel });
-    if (!child.ok)
-        throw new DesktopBridgeError(`bridge_${child.blockers[0] || 'child_policy_blocked'}`);
+    return parsed;
+}
+function oneCodexIdentity(values, kind) {
+    const canonical = values
+        .filter((value) => value !== undefined && value !== null && value !== '')
+        .map(canonicalSessionId);
+    if (new Set(canonical).size > 1)
+        throw new DesktopBridgeError('bridge_codex_session_identity_conflict');
+    return canonical[0] || null;
+}
+export function resolveCodexSessionIdentity(headers, payload = null) {
+    const turnMetadataValue = singleBridgeHeader(headers, 'x-codex-turn-metadata');
+    const turnMetadata = turnMetadataValue === null ? null : codexMetadataObject(turnMetadataValue, 'header');
+    const clientMetadataValue = payload?.client_metadata;
+    const clientMetadata = clientMetadataValue === undefined ? null : codexMetadataObject(clientMetadataValue, 'body');
+    const threadId = oneCodexIdentity([
+        singleBridgeHeader(headers, 'thread-id'),
+        turnMetadata?.thread_id,
+        clientMetadata?.thread_id,
+    ], 'thread');
+    const sessionId = oneCodexIdentity([
+        singleBridgeHeader(headers, 'session-id'),
+        turnMetadata?.session_id,
+        clientMetadata?.session_id,
+    ], 'session');
+    if (sessionId && !threadId)
+        throw new DesktopBridgeError('bridge_codex_thread_id_missing');
+    if (threadId && sessionId && threadId !== sessionId) {
+        throw new DesktopBridgeError('bridge_codex_session_identity_mismatch');
+    }
+    return { thread_id: threadId, session_id: sessionId };
 }
 function comparableOrigin(value, referer) {
     if (value === 'null')
-        return 'null';
+        return value;
     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');
-        }
+        if (!referer && ((parsed.pathname !== '/' && parsed.pathname !== '') || parsed.search || parsed.hash))
+            throw new Error();
         return parsed.origin !== 'null' ? parsed.origin : `${parsed.protocol}//${parsed.host}`;
     }
     catch {
@@ -167,140 +130,180 @@ export function normalizeAllowedOrigin(value) {
 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)))
+    for (const value of origins)
+        if (!allowed.has(comparableOrigin(value, false)))
             throw new DesktopBridgeError('bridge_origin_forbidden');
-    }
-    for (const referer of referers) {
-        if (!allowed.has(comparableOrigin(referer, true)))
+    for (const value of referers)
+        if (!allowed.has(comparableOrigin(value, 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) {
+    const connection = headerValues(headers.connection).join(',').toLowerCase().split(',').map((v) => v.trim());
+    if (method !== 'GET' || !connection.includes('upgrade') || headerValues(headers.upgrade)[0]?.toLowerCase() !== 'websocket'
+        || headerValues(headers['sec-websocket-key']).length !== 1 || headerValues(headers['sec-websocket-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');
+function canonicalPublicModel(value) {
+    const model = canonicalizeBridgeModelId(value);
+    if (!model)
+        throw new DesktopBridgeError('catalog_model_route_missing');
+    return model;
 }
-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.providerMode !== undefined) {
-        if (config.providerMode !== 'codex-lb' && config.providerMode !== 'openrouter') {
-            throw new DesktopBridgeError('bridge_provider_mode_invalid');
+export function resolveBridgeRequestRoute(request, policy, pins) {
+    const publicModel = canonicalPublicModel(request.public_model);
+    const sessionId = request.session_id ? canonicalSessionId(request.session_id) : null;
+    const pin = sessionId ? pins.find((entry) => entry.thread_id === sessionId) || null : null;
+    if (pin && pin.public_model === publicModel) {
+        if (pin.public_model !== publicModel
+            || pin.catalog_generation !== policy.catalog_generation
+            || pin.route_policy_generation !== policy.policy_generation) {
+            throw new DesktopBridgeError('session_pin_route_unavailable');
         }
-        if (!Array.isArray(config.allowedModels) || config.allowedModels.length === 0) {
-            throw new DesktopBridgeError('bridge_provider_model_allowlist_empty');
+        const current = policy.model_routes[publicModel];
+        if (!current || current.provider_id !== pin.provider_id || current.upstream_model !== pin.upstream_model) {
+            throw new DesktopBridgeError('session_pin_route_unavailable');
         }
-        for (const model of config.allowedModels) {
-            try {
-                assertProviderModeModel(config.providerMode, model, config.allowedModels);
-            }
-            catch (error) {
-                throw new DesktopBridgeError(`bridge_${error.message}`);
-            }
-        }
-        if (config.providerPolicy) {
-            const policy = parseProviderPolicySnapshot(config.providerPolicy);
-            if (policy.mode !== config.providerMode)
-                throw new DesktopBridgeError('bridge_provider_policy_mode_mismatch');
-            if (stableArchitectureHash([...policy.allowed_models].sort()) !== stableArchitectureHash([...(config.allowedModels || [])].sort())) {
-                throw new DesktopBridgeError('bridge_provider_policy_model_allowlist_mismatch');
-            }
-            if (!config.credentialReadiness)
-                throw new DesktopBridgeError('bridge_credential_readiness_missing');
-            if (config.childPolicy) {
-                if (config.childPolicy.mode !== policy.mode)
-                    throw new DesktopBridgeError('bridge_child_policy_mode_mismatch');
-                if (config.childPolicy.policy_hash !== policy.child_policy_hash)
-                    throw new DesktopBridgeError('bridge_child_policy_snapshot_mismatch');
-            }
-            const sessionIds = new Set();
-            for (const pin of config.sessionPins || []) {
-                if (!pin || pin.schema !== 'sks.session-pin.v1')
-                    throw new DesktopBridgeError('bridge_session_pin_invalid');
-                if (sessionIds.has(pin.session_id))
-                    throw new DesktopBridgeError('bridge_session_pin_duplicate');
-                sessionIds.add(pin.session_id);
-                const resume = resumeSessionPin(pin, policy);
-                if (!resume.ok)
-                    throw new DesktopBridgeError(`bridge_${resume.blocker || 'session_pin_invalid'}`);
-            }
-        }
-        else if (config.requireSessionPin) {
-            throw new DesktopBridgeError('bridge_session_policy_missing');
+        return {
+            provider_id: pin.provider_id,
+            public_model: publicModel,
+            upstream_model: pin.upstream_model,
+            catalog_generation: pin.catalog_generation,
+            route_policy_generation: pin.route_policy_generation,
+            session_pin: pin,
+        };
+    }
+    const route = policy.model_routes[publicModel];
+    if (!route)
+        throw new DesktopBridgeError('catalog_model_route_missing');
+    const nextPin = sessionId ? {
+        thread_id: sessionId,
+        provider_id: route.provider_id,
+        public_model: publicModel,
+        upstream_model: route.upstream_model,
+        catalog_generation: policy.catalog_generation,
+        route_policy_generation: policy.policy_generation,
+        created_at: new Date().toISOString(),
+    } : null;
+    return {
+        provider_id: route.provider_id,
+        public_model: publicModel,
+        upstream_model: route.upstream_model,
+        catalog_generation: policy.catalog_generation,
+        route_policy_generation: policy.policy_generation,
+        session_pin: nextPin,
+    };
+}
+export function assertDesktopBridgeRouteContext(request, config) {
+    const resolver = config.resolveRequestRoute || resolveBridgeRequestRoute;
+    const route = resolver(request, config.routePolicy, config.providerSessionPins);
+    const policy = config.routePolicy;
+    const expected = policy.model_routes[route.public_model];
+    if (!expected || expected.provider_id !== route.provider_id || expected.upstream_model !== route.upstream_model) {
+        throw new DesktopBridgeError('catalog_model_route_missing');
+    }
+    if (route.catalog_generation !== policy.catalog_generation || route.route_policy_generation !== policy.policy_generation) {
+        throw new DesktopBridgeError('session_pin_route_unavailable');
+    }
+    if (request.session_id) {
+        const sessionId = canonicalSessionId(request.session_id);
+        if (!route.session_pin
+            || route.session_pin.thread_id !== sessionId
+            || route.session_pin.provider_id !== route.provider_id
+            || route.session_pin.public_model !== route.public_model
+            || route.session_pin.upstream_model !== route.upstream_model
+            || route.session_pin.catalog_generation !== route.catalog_generation
+            || route.session_pin.route_policy_generation !== route.route_policy_generation) {
+            throw new DesktopBridgeError('bridge_session_pin_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');
+    else if (route.session_pin) {
+        throw new DesktopBridgeError('bridge_session_pin_invalid');
     }
-    if (!Number.isFinite(config.connectTimeoutMs) || config.connectTimeoutMs < 100 || config.connectTimeoutMs > 120_000) {
-        throw new DesktopBridgeError('bridge_connect_timeout_invalid');
+    const provider = config.providers[route.provider_id];
+    if (!provider || !provider.enabled)
+        throw new DesktopBridgeError('bridge_provider_route_unavailable');
+    if (provider.credential_state !== 'ready')
+        throw new DesktopBridgeError(`${route.provider_id.replace('-', '_')}_credential_unavailable`);
+    if (provider.source_catalog_generation !== null && !provider.source_catalog_generation.trim()) {
+        throw new DesktopBridgeError('bridge_provider_source_catalog_generation_invalid');
     }
-    if (!Number.isFinite(config.idleTimeoutMs) || config.idleTimeoutMs < 1_000 || config.idleTimeoutMs > 86_400_000) {
-        throw new DesktopBridgeError('bridge_idle_timeout_invalid');
+    if (!provider.allowed_origins.map(normalizeAllowedOrigin).includes(provider.remote.origin)) {
+        throw new DesktopBridgeError('bridge_provider_origin_forbidden');
     }
-    for (const prefix of config.allowedPathPrefixes) {
-        if (!prefix.startsWith('/') || prefix.includes('?') || prefix.includes('#') || prefix.includes('\\')) {
-            throw new DesktopBridgeError('bridge_path_allowlist_invalid');
+    return route;
+}
+export async function resolveAndBindDesktopBridgeRouteContext(request, config) {
+    return withSessionPinMutation(config, async () => {
+        const route = assertDesktopBridgeRouteContext(request, config);
+        const pin = route.session_pin;
+        if (!pin)
+            return route;
+        const existing = config.providerSessionPins.find((entry) => entry.thread_id === pin.thread_id) || null;
+        if (existing && sameSessionPin(existing, pin))
+            return route;
+        const nextPins = [
+            ...config.providerSessionPins.filter((entry) => entry.thread_id !== pin.thread_id),
+            pin,
+        ];
+        const retainedPins = nextPins.length > MAX_SESSION_PINS
+            ? nextPins
+                .sort((left, right) => Date.parse(left.created_at) - Date.parse(right.created_at)
+                || left.thread_id.localeCompare(right.thread_id))
+                .slice(nextPins.length - MAX_SESSION_PINS)
+            : nextPins;
+        const persistedPins = retainedPins.sort((left, right) => left.thread_id.localeCompare(right.thread_id));
+        if (config.persistProviderSessionPins) {
+            await config.persistProviderSessionPins(persistedPins);
         }
+        config.providerSessionPins = persistedPins;
+        return route;
+    });
+}
+async function withSessionPinMutation(config, action) {
+    const previous = sessionPinMutationQueues.get(config) || Promise.resolve();
+    const run = previous.catch(() => undefined).then(action);
+    const tail = run.then(() => undefined, () => undefined);
+    sessionPinMutationQueues.set(config, tail);
+    try {
+        return await run;
     }
-    for (const origin of config.allowedOrigins)
-        normalizeAllowedOrigin(origin);
+    finally {
+        if (sessionPinMutationQueues.get(config) === tail)
+            sessionPinMutationQueues.delete(config);
+    }
+}
+function sameSessionPin(left, right) {
+    return left.thread_id === right.thread_id
+        && left.provider_id === right.provider_id
+        && left.public_model === right.public_model
+        && left.upstream_model === right.upstream_model
+        && left.catalog_generation === right.catalog_generation
+        && left.route_policy_generation === right.route_policy_generation;
+}
+function canonicalSessionId(value) {
+    const sessionId = typeof value === 'string' ? value.trim() : '';
+    if (!sessionId || sessionId.length > 256 || !/^[A-Za-z0-9._:/-]+$/.test(sessionId)) {
+        throw new DesktopBridgeError('bridge_session_id_invalid');
+    }
+    return sessionId;
+}
+function stripIpv6Brackets(hostname) { return hostname.replace(/^\[/, '').replace(/\]$/, ''); }
+function isLoopbackAddress(address) {
+    const value = address.replace(/^::ffff:/i, '');
+    return value === '::1' || (net.isIP(value) === 4 && Number(value.split('.')[0]) === 127);
+}
+function isExplicitLoopbackHostname(hostname) {
+    const value = stripIpv6Brackets(hostname).replace(/\.$/, '').toLowerCase();
+    return value === 'localhost' || isLoopbackAddress(value);
+}
+function validateRemoteUrl(raw) {
     let remote;
     try {
-        remote = new URL(config.remoteBaseUrl);
+        remote = new URL(raw);
     }
     catch {
         throw new DesktopBridgeError('bridge_remote_url_invalid');
@@ -322,74 +325,170 @@ const defaultLookup = async (hostname) => {
         return { address: row.address, family: row.family };
     });
 };
-export async function prepareDesktopBridgeConfig(config, lookup = defaultLookup) {
-    const remote = validateDesktopBridgeConfig(config);
+export async function resolveDesktopBridgeRemoteTarget(raw, lookup = defaultLookup) {
+    const remote = validateRemoteUrl(raw);
     const hostname = stripIpv6Brackets(remote.hostname);
-    const literalFamily = net.isIP(hostname);
+    const family = net.isIP(hostname);
     let addresses;
     try {
-        addresses = literalFamily
-            ? [{ address: hostname, family: literalFamily }]
-            : await lookup(hostname);
+        addresses = family ? [{ address: hostname, family: family }] : 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)) {
+    if (!addresses.length || 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))) {
+    const loopback = isExplicitLoopbackHostname(hostname);
+    if (loopback && addresses.some((row) => !isLoopbackAddress(row.address)))
+        throw new DesktopBridgeError('bridge_remote_dns_rebinding_blocked');
+    if (!loopback && addresses.some((row) => FORBIDDEN_REMOTE_ADDRESSES.check(row.address, row.family === 4 ? 'ipv4' : 'ipv6'))) {
         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 }),
+    const target = {
+        baseUrl: remote.toString().replace(/\/$/, ''), origin: remote.origin, hostname,
+        port: Number(remote.port || (remote.protocol === 'https:' ? 443 : 80)), secure: remote.protocol === 'https:',
+        address: selected.address, family: selected.family, ...(family ? {} : { tlsServername: hostname }),
     };
-    return { ...config, remoteBaseUrl: remoteTarget.baseUrl, remote: remoteTarget };
+    return target;
 }
-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');
+async function prepareProvider(provider, lookup) {
+    const remote = validateRemoteUrl(provider.base_url);
+    const hostname = stripIpv6Brackets(remote.hostname);
+    if (!provider.allowed_origins.map(normalizeAllowedOrigin).includes(remote.origin))
+        throw new DesktopBridgeError('bridge_provider_origin_forbidden');
+    if (!provider.enabled) {
+        return {
+            ...provider,
+            base_url: remote.toString().replace(/\/$/, ''),
+            remote: {
+                baseUrl: remote.toString().replace(/\/$/, ''), origin: remote.origin, hostname,
+                port: Number(remote.port || (remote.protocol === 'https:' ? 443 : 80)), secure: remote.protocol === 'https:',
+                address: '0.0.0.0', family: 4, ...(net.isIP(hostname) ? {} : { tlsServername: hostname }),
+            },
+        };
+    }
+    const target = await resolveDesktopBridgeRemoteTarget(provider.base_url, lookup);
+    return { ...provider, base_url: target.baseUrl, remote: target };
+}
+function assertRegistryAndPolicy(config, registry) {
+    if (registry.schema !== 'sks.desktop-bridge-provider-registry.v1' || !registry.generation || !Number.isFinite(Date.parse(registry.created_at))) {
+        throw new DesktopBridgeError('bridge_provider_registry_invalid');
+    }
+    const ids = ['codex-lb', 'openrouter'];
+    if (Object.keys(registry.providers).length !== ids.length)
+        throw new DesktopBridgeError('bridge_provider_registry_invalid');
+    for (const id of ids) {
+        const provider = registry.providers[id];
+        if (!provider || provider.provider_id !== id || !provider.credential_generation || !Array.isArray(provider.allowed_origins) || !provider.allowed_origins.length) {
+            throw new DesktopBridgeError('bridge_provider_registry_invalid');
+        }
+        if (provider.source_catalog_generation !== null
+            && (typeof provider.source_catalog_generation !== 'string' || !provider.source_catalog_generation.trim())) {
+            throw new DesktopBridgeError('bridge_provider_source_catalog_generation_invalid');
+        }
+        if (id === 'openrouter' && provider.auth_transport !== 'openrouter-bearer')
+            throw new DesktopBridgeError('bridge_provider_auth_transport_mismatch');
+        if (id === 'codex-lb' && provider.auth_transport === 'openrouter-bearer')
+            throw new DesktopBridgeError('bridge_provider_auth_transport_mismatch');
+        validateRemoteUrl(provider.base_url);
+    }
+    const policy = config.routePolicy;
+    if (policy.schema !== 'sks.bridge-routing-policy.v1' || policy.fallback !== 'none' || !policy.catalog_generation || !policy.policy_generation) {
+        throw new DesktopBridgeError('bridge_route_policy_invalid');
+    }
+    for (const [model, route] of Object.entries(policy.model_routes)) {
+        if (canonicalizeBridgeModelId(model) !== model
+            || !ids.includes(route.provider_id)
+            || normalizeBridgeUpstreamModelId(route.upstream_model) !== route.upstream_model) {
+            throw new DesktopBridgeError('bridge_route_policy_invalid');
         }
     }
-    else if (isForbiddenRemoteAddress(config.remote.address, config.remote.family)) {
-        throw new DesktopBridgeError('bridge_remote_dns_private_address');
+    const pinIds = new Set();
+    for (const pin of config.providerSessionPins) {
+        const keys = Object.keys(pin);
+        if (keys.some((key) => ![
+            'thread_id', 'provider_id', 'public_model', 'upstream_model',
+            'catalog_generation', 'route_policy_generation', 'created_at',
+        ].includes(key))
+            || canonicalSessionId(pin.thread_id) !== pin.thread_id
+            || pinIds.has(pin.thread_id)
+            || !ids.includes(pin.provider_id)
+            || canonicalizeBridgeModelId(pin.public_model) !== pin.public_model
+            || normalizeBridgeUpstreamModelId(pin.upstream_model) !== pin.upstream_model
+            || !pin.catalog_generation
+            || !pin.route_policy_generation
+            || !Number.isFinite(Date.parse(pin.created_at))) {
+            throw new DesktopBridgeError('bridge_session_pin_invalid');
+        }
+        pinIds.add(pin.thread_id);
+    }
+}
+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.allowedPathPrefixes.length)
+        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');
+    if (config.requestTimeoutMs !== undefined
+        && (!Number.isFinite(config.requestTimeoutMs) || config.requestTimeoutMs < 1_000 || config.requestTimeoutMs > 120_000)) {
+        throw new DesktopBridgeError('bridge_request_timeout_invalid');
+    }
+    if (config.maxConcurrentRequests !== undefined
+        && (!Number.isInteger(config.maxConcurrentRequests) || config.maxConcurrentRequests < 1 || config.maxConcurrentRequests > 1_024)) {
+        throw new DesktopBridgeError('bridge_concurrent_request_limit_invalid');
+    }
+    if (config.maxConnections !== undefined
+        && (!Number.isInteger(config.maxConnections) || config.maxConnections < 1 || config.maxConnections > 2_048)) {
+        throw new DesktopBridgeError('bridge_connection_limit_invalid');
+    }
+    for (const origin of config.allowedOrigins)
+        normalizeAllowedOrigin(origin);
+    if (!config.providerRegistry)
+        throw new DesktopBridgeError('bridge_provider_registry_missing');
+    if (!config.routePolicy)
+        throw new DesktopBridgeError('bridge_route_policy_invalid');
+    if (!Array.isArray(config.providerSessionPins))
+        throw new DesktopBridgeError('bridge_session_pin_invalid');
+    if (!/^[a-f0-9]{64}$/.test(config.clientCapabilitySha256))
+        throw new DesktopBridgeError('bridge_client_capability_invalid');
+    if (typeof config.resolveProviderCredential !== 'function')
+        throw new DesktopBridgeError('bridge_provider_credential_resolver_missing');
+    assertRegistryAndPolicy(config, config.providerRegistry);
+    if (!Object.values(config.providerRegistry.providers).some((provider) => provider.enabled)) {
+        throw new DesktopBridgeError('bridge_provider_registry_no_enabled_provider');
+    }
+}
+export async function prepareDesktopBridgeConfig(config, lookup = defaultLookup) {
+    validateDesktopBridgeConfig(config);
+    const entries = await Promise.all(Object.keys(config.providerRegistry.providers).map(async (id) => {
+        const provider = config.providerRegistry.providers[id];
+        if (!provider)
+            throw new DesktopBridgeError('bridge_provider_registry_invalid');
+        const prepared = await prepareProvider({ ...provider, remote: {} }, lookup);
+        return [id, prepared];
+    }));
+    const providers = Object.fromEntries(entries);
+    return { ...config, providers };
+}
+export function validatePreparedDesktopBridgeConfig(config) {
+    validateDesktopBridgeConfig(config);
+    for (const id of Object.keys(config.providers)) {
+        const provider = config.providers[id];
+        if (!provider || provider.provider_id !== id || provider.remote.origin !== new URL(provider.base_url).origin)
+            throw new DesktopBridgeError('bridge_prepared_config_invalid');
     }
 }
 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)) {
+    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');
@@ -397,7 +496,22 @@ export function resolveDesktopBridgeTarget(rawRequestUrl, remote) {
     catch {
         throw new DesktopBridgeError('bridge_request_target_invalid');
     }
-    return new URL(`${inbound.pathname}${inbound.search}`, remote.origin);
+    const base = new URL(remote.baseUrl);
+    const basePath = base.pathname.replace(/\/+$/, '');
+    const providerRelative = providerRelativePath(inbound.pathname);
+    const pathname = providerRelative === null
+        ? inbound.pathname
+        : `${basePath}${providerRelative}` || '/';
+    return new URL(`${pathname}${inbound.search}`, remote.origin);
+}
+function providerRelativePath(pathname) {
+    for (const prefix of ['/backend-api/codex', '/api/v1', '/v1']) {
+        if (pathname === prefix)
+            return '';
+        if (pathname.startsWith(`${prefix}/`))
+            return pathname.slice(prefix.length);
+    }
+    return null;
 }
 export function safeBridgeErrorCode(error) {
     if (error instanceof DesktopBridgeError)