@bitkyc08/opencodex 2.64.0-preview.20260923 → 2.65.0-preview.20260925

package/src/claude/desktop-risk.ts

@@ -0,0 +1,20 @@
+/**
+ * Account-risk notice for Claude Desktop first-party mode.
+ *
+ * First-party mode sends the Claude subscription's Claude Code traffic through the local
+ * interception proxy. Every surface that offers, applies or reports first-party shows this text
+ * (CLI, management status, native toggle, dashboard, docs), so it has one owner and cannot drift.
+ */
+export const FIRST_PARTY_ACCOUNT_RISK = {
+  code: "first_party_account_suspension_risk",
+  message: "First-party mode sends Claude subscription traffic through a local interception proxy. "
+    + "Anthropic may treat this as a violation of its terms and suspend the account. "
+    + "Use it at your own risk; gateway mode is the default.",
+} as const;
+
+export type FirstPartyAccountRisk = { code: typeof FIRST_PARTY_ACCOUNT_RISK.code; message: string };
+
+/** A fresh copy for JSON payloads, so no caller can mutate the shared constant. */
+export function firstPartyAccountRisk(): FirstPartyAccountRisk {
+  return { code: FIRST_PARTY_ACCOUNT_RISK.code, message: FIRST_PARTY_ACCOUNT_RISK.message };
+}

package/src/claude/gateway-cache.ts

@@ -6,9 +6,12 @@
  * subscription-preserving launch deliberately sets no token, so the CLI can never
  * refresh its picker list itself — it reads whatever cache exists. We therefore
  * pre-write the cache in the exact on-disk schema the CLI uses:
- *   { baseUrl, fetchedAt, models: [{ id, display_name? }] }  (mode 0600)
- * mirroring its `/^(claude|anthropic)/i` usable-id filter. The picker validates
+ *   { baseUrl, fetchedAt, models: [{ id, display_name?, description? }] }  (mode 0600)
+ * mirroring the picker rule that the id must contain `claude` or `anthropic`.
+ * Current aliases are `ocx-claude-*`, so an anchored `^(claude|anthropic)` filter
+ * would drop every newly minted routed model. The picker validates
  * only `baseUrl === ANTHROPIC_BASE_URL`, so a foreign base URL is simply ignored.
+ * `description` replaces the picker's generic "From gateway" line (Claude Code >= 2.1.257).
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -19,6 +22,7 @@ import type { OcxConfig } from "../types";
 export interface GatewayModelRow {
   id: string;
   display_name?: string;
+  description?: string;
 }
 
 export interface GatewayModelCacheRefreshOptions {
@@ -49,14 +53,18 @@ export function claudeConfigDir(): string {
 export function writeGatewayModelCache(baseUrl: string, models: readonly GatewayModelRow[], configDir = claudeConfigDir()): string | null {
   try {
     // Mirror the CLI's usable-id filter so our file matches what it would cache.
-    const usable = models.filter(m => /^(claude|anthropic)/i.test(m.id));
+    const usable = models.filter(m => /(claude|anthropic)/i.test(m.id));
     const cacheDir = join(configDir, "cache");
     mkdirSync(cacheDir, { recursive: true });
     const path = join(cacheDir, "gateway-models.json");
     const payload = {
       baseUrl,
       fetchedAt: Date.now(),
-      models: usable.map(m => (m.display_name === undefined ? { id: m.id } : { id: m.id, display_name: m.display_name })),
+      models: usable.map(m => ({
+        id: m.id,
+        ...(m.display_name === undefined ? {} : { display_name: m.display_name }),
+        ...(m.description === undefined ? {} : { description: m.description }),
+      })),
     };
     writeFileSync(path, JSON.stringify(payload), { encoding: "utf8", mode: 0o600 });
     return path;
@@ -110,6 +118,7 @@ export async function refreshGatewayModelCacheFromProxy(
       .map(m => ({
         id: m.id as string,
         display_name: typeof m.display_name === "string" ? m.display_name : undefined,
+        description: typeof m.description === "string" ? m.description : undefined,
       }));
     return writeGatewayModelCache(baseUrl, models, options.configDir);
   } catch {

package/src/claude/inbound.ts

@@ -442,13 +442,16 @@ function translateAnthropicRequest(
   if (outputConfigFormat) body.text = { format: outputConfigFormat };
   let cacheKeySource: ClaudeCacheKeySource = null;
   if (isRec(raw.metadata) && typeof raw.metadata.user_id === "string") {
-    body.user = raw.metadata.user_id;
+    const userIdHash = createHash("sha256").update(raw.metadata.user_id).digest("hex");
+    // OpenAI and Azure reject `user` longer than 64 chars, and Claude Code's metadata.user_id
+    // is a JSON blob well past that; send its 64-char hash instead of the raw value.
+    body.user = raw.metadata.user_id.length <= 64 ? raw.metadata.user_id : userIdHash;
     // OpenAI-side prompt caching is routed by prompt_cache_key (Codex clients send
     // their session id; without it consecutive /v1/messages turns reported
     // cached_tokens: 0 on the ChatGPT backend — devlog 090). Claude Code's
     // metadata.user_id embeds the session uuid, so hashing it yields a stable
     // per-session key with a bounded length/charset.
-    body.prompt_cache_key = createHash("sha256").update(raw.metadata.user_id).digest("hex").slice(0, 32);
+    body.prompt_cache_key = userIdHash.slice(0, 32);
     cacheKeySource = "metadata";
   } else if (systemParts.length > 0) {
     // Claude Desktop sends no metadata.user_id (H1, devlog 130): without any key the

package/src/claude/intercept/connect-proxy.ts

@@ -6,7 +6,8 @@ import { BlockList, createServer, connect, isIP, type Server, type Socket } from
  * Claude Code honours `HTTPS_PROXY` and opens `CONNECT <host>:443` for every upstream. This
  * proxy splices tunnels for the intercepted hosts onto the local TLS listener (which holds a
  * leaf certificate for them) and blindly relays every other tunnel to its real destination,
- * so telemetry, OAuth refresh and claude.ai traffic stay native and opaque to opencodex.
+ * so telemetry and OAuth refresh stay native and opaque to opencodex. Picker mode may
+ * terminate only claude.ai tunnels, selected independently for each connection.
  *
  * Only CONNECT is served. Plain proxied HTTP requests are refused: Claude Code never sends
  * them, and answering them would turn this socket into a generic forward proxy.
@@ -15,6 +16,7 @@ import { BlockList, createServer, connect, isIP, type Server, type Socket } from
 export const CLAUDE_INTERCEPT_HOSTS = ["api.anthropic.com"] as const;
 
 const MAX_HEAD_BYTES = 8 * 1024;
+const MAX_PENDING_BYTES = 16 * 1024 * 1024;
 const HEAD_TIMEOUT_MS = 10_000;
 const UPSTREAM_CONNECT_TIMEOUT_MS = 15_000;
 
@@ -23,10 +25,43 @@ export interface ConnectProxyOptions {
   interceptPort: number;
   /** Hostnames (lowercase) whose 443 tunnels are spliced onto `interceptPort`. */
   interceptHosts?: readonly string[];
+  /** Per-connection override, consulted before interceptHosts; null keeps the default. */
+  selectTunnel?: (host: string, port: number, request: ConnectRequestInfo) => TunnelDecision | null | Promise<TunnelDecision | null>;
   /** Test seam: dial the real destination for a blind tunnel. */
   dialUpstream?: (host: string, port: number) => Socket;
 }
 
+export type TunnelDecision = { kind: "intercept"; port: number } | { kind: "blind" };
+
+/** What the CONNECT head says about its client, for tunnel choice only. Never logged. */
+export interface ConnectRequestInfo {
+  /** The CONNECT request's User-Agent header, or null when it sent none. */
+  userAgent: string | null;
+}
+
+/**
+ * Chromium (Claude Desktop's app) sends its browser User-Agent on CONNECT; the Claude Code
+ * processes Desktop spawns send none. The two trust different CAs, so the tunnel choice uses it.
+ *
+ * This is a routing hint, not a trust boundary: a local client can send any User-Agent. Neither
+ * answer grants anything a local process lacks already. A non-browser tunnel reaches the
+ * api.anthropic.com intercept, which the Claude Code proxy offers every local process; a browser
+ * tunnel reaches the claude.ai relay, which verifies upstream and injects no credential. A client
+ * that lies only breaks its own TLS, because each terminator presents a certificate only its
+ * intended client trusts.
+ */
+export function isBrowserConnect(request: ConnectRequestInfo): boolean {
+  return request.userAgent !== null && /^Mozilla\//.test(request.userAgent);
+}
+
+function connectRequestInfo(head: string): ConnectRequestInfo {
+  const match = /\r\nuser-agent:[ \t]*([^\r\n]*)/i.exec(head);
+  return { userAgent: match ? match[1]!.trim() : null };
+}
+
+type ResolvedConnectProxyOptions = Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>
+  & Pick<ConnectProxyOptions, "selectTunnel">;
+
 export interface ConnectProxyHandle {
   port: number;
   close(): Promise<void>;
@@ -90,7 +125,7 @@ function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
   upstream.pipe(client);
 }
 
-function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>): void {
+function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions): void {
   let head: Buffer = Buffer.alloc(0);
   socket.on("error", () => socket.destroy());
   socket.setTimeout(HEAD_TIMEOUT_MS, () => respond(socket, 408, "Request Timeout"));
@@ -98,7 +133,8 @@ function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOpt
   const onData = (chunk: Buffer) => {
     head = head.length === 0 ? chunk : Buffer.concat([head, chunk]);
     const end = head.indexOf("\r\n\r\n");
-    if (end === -1) {
+    // The cap holds however the head arrives: across reads or in one oversized read.
+    if (end === -1 || end + 4 > MAX_HEAD_BYTES) {
       if (head.length > MAX_HEAD_BYTES) {
         socket.off("data", onData);
         respond(socket, 431, "Request Header Fields Too Large");
@@ -109,7 +145,7 @@ function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOpt
     socket.pause();
     const target = parseConnectRequestLine(head.subarray(0, end).toString("latin1"));
     // Bytes after the head belong to the tunnel (a client may pipeline its TLS ClientHello).
-    const pending = head.subarray(end + 4);
+    let pending = head.subarray(end + 4);
     if (!target) {
       respond(socket, 405, "Method Not Allowed");
       return;
@@ -118,31 +154,71 @@ function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOpt
       respond(socket, 403, "Forbidden");
       return;
     }
-    const intercept = target.port === 443 && options.interceptHosts.includes(target.host);
-    const upstream = intercept
-      ? connect({ host: "127.0.0.1", port: options.interceptPort })
-      : options.dialUpstream(target.host, target.port);
-    let established = false;
-    const connectTimer = setTimeout(() => {
-      if (!established) {
-        upstream.destroy();
-        respond(socket, 504, "Gateway Timeout");
-      }
-    }, UPSTREAM_CONNECT_TIMEOUT_MS);
-    upstream.once("error", () => {
-      clearTimeout(connectTimer);
-      if (!established) respond(socket, 502, "Bad Gateway");
-    });
-    upstream.once("connect", () => {
-      established = true;
-      clearTimeout(connectTimer);
-      if (socket.destroyed) {
-        upstream.destroy();
-        return;
+    const dialFor = (selected: TunnelDecision | null): void => {
+      if (socket.destroyed) return;
+      const choice = selected ?? (target.port === 443 && options.interceptHosts.includes(target.host)
+        ? { kind: "intercept" as const, port: options.interceptPort }
+        : { kind: "blind" as const });
+      const upstream = choice.kind === "intercept"
+        ? connect({ host: "127.0.0.1", port: choice.port })
+        : options.dialUpstream(target.host, target.port);
+      let established = false;
+      const connectTimer = setTimeout(() => {
+        if (!established) {
+          upstream.destroy();
+          respond(socket, 504, "Gateway Timeout");
+        }
+      }, UPSTREAM_CONNECT_TIMEOUT_MS);
+      upstream.once("error", () => {
+        clearTimeout(connectTimer);
+        if (!established) respond(socket, 502, "Bad Gateway");
+      });
+      upstream.once("connect", () => {
+        established = true;
+        clearTimeout(connectTimer);
+        if (socket.destroyed) {
+          upstream.destroy();
+          return;
+        }
+        socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+        splice(socket, upstream, pending);
+        socket.resume();
+      });
+    };
+    if (!options.selectTunnel) {
+      dialFor(null);
+      return;
+    }
+    let decision: ReturnType<NonNullable<ConnectProxyOptions["selectTunnel"]>>;
+    try {
+      decision = options.selectTunnel(target.host, target.port, connectRequestInfo(head.subarray(0, end).toString("latin1")));
+    } catch {
+      dialFor({ kind: "blind" });
+      return;
+    }
+    if (!decision || typeof (decision as Promise<TunnelDecision | null>).then !== "function") {
+      dialFor(decision as TunnelDecision | null);
+      return;
+    }
+    // A paused socket does not notice a peer FIN until its readable side is drained.
+    // Hold later tunnel bytes here so a departing client cannot trigger a stale dial.
+    const onPendingReadable = () => {
+      let chunk: Buffer | null;
+      while ((chunk = socket.read() as Buffer | null) !== null) {
+        if (pending.length + chunk.length > MAX_PENDING_BYTES) {
+          socket.destroy();
+          return;
+        }
+        pending = Buffer.concat([pending, chunk]);
       }
-      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
-      splice(socket, upstream, pending);
-      socket.resume();
+    };
+    const onPendingEnd = () => socket.destroy();
+    socket.on("readable", onPendingReadable);
+    socket.once("end", onPendingEnd);
+    void Promise.resolve(decision).catch(() => ({ kind: "blind" as const })).then(choice => {
+      socket.off("readable", onPendingReadable);
+      socket.off("end", onPendingEnd);
+      dialFor(choice);
     });
   };
   socket.on("data", onData);
@@ -150,9 +226,10 @@ function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOpt
 
 /** Bind the CONNECT proxy on 127.0.0.1. Rejects when the port is unavailable. */
 export function startConnectProxy(port: number, options: ConnectProxyOptions): Promise<ConnectProxyHandle> {
-  const resolved = {
+  const resolved: ResolvedConnectProxyOptions = {
     interceptPort: options.interceptPort,
     interceptHosts: options.interceptHosts ?? CLAUDE_INTERCEPT_HOSTS,
+    selectTunnel: options.selectTunnel,
     dialUpstream: options.dialUpstream ?? ((host: string, targetPort: number) => connect({ host, port: targetPort })),
   };
   return new Promise((resolve, reject) => {

package/src/claude/intercept/local-ca.ts

@@ -91,6 +91,7 @@ const OID = {
   organization: "2.5.4.10",
   ecdsaWithSha256: "1.2.840.10045.4.3.2",
   basicConstraints: "2.5.29.19",
+  nameConstraints: "2.5.29.30",
   keyUsage: "2.5.29.15",
   subjectAltName: "2.5.29.17",
   extendedKeyUsage: "2.5.29.37",
@@ -112,6 +113,23 @@ function extension(oid: string, critical: boolean, value: Uint8Array): Uint8Arra
     : sequence(objectIdentifier(oid), octetString(value));
 }
 
+/** iPAddress bases (address + mask, all zero) that cover every IPv4 and every IPv6 address. */
+export const ALL_IP_ADDRESS_BASES: readonly Uint8Array[] = [new Uint8Array(8), new Uint8Array(32)];
+
+/**
+ * RFC 5280 NameConstraints. permittedSubtrees holds one dNSName base per name. A DNS-only permitted
+ * list leaves other name forms unconstrained, so excludedSubtrees names every IPv4 and IPv6
+ * address unless the caller opts out.
+ */
+function nameConstraints(permitted: readonly string[], excludeAllIpAddresses: boolean): Uint8Array {
+  const subtrees = permitted.map(name => sequence(contextTag(2, new TextEncoder().encode(name), false)));
+  const excluded = ALL_IP_ADDRESS_BASES.map(base => sequence(contextTag(7, base, false)));
+  return sequence(
+    contextTag(0, concat(...subtrees)),
+    ...(excludeAllIpAddresses ? [contextTag(1, concat(...excluded))] : []),
+  );
+}
+
 function subjectPublicKeyInfo(key: KeyObject): Uint8Array {
   return new Uint8Array(key.export({ type: "spki", format: "der" }));
 }
@@ -173,9 +191,16 @@ export interface LocalInterceptCa extends PemKeyPair {
   privateKey: KeyObject;
 }
 
-export function createLocalInterceptCa(): LocalInterceptCa {
+export interface AuthorityOptions {
+  commonName: string;
+  permittedDnsNames?: readonly string[];
+  /** With permittedDnsNames: also exclude every IP address (default true). */
+  excludeAllIpAddresses?: boolean;
+}
+
+export function createCertificateAuthority(options: AuthorityOptions): LocalInterceptCa {
   const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
-  const name = distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME);
+  const name = distinguishedName(options.commonName);
   const der = issueCertificate({
     subject: name,
     issuer: name,
@@ -187,6 +212,9 @@ export function createLocalInterceptCa(): LocalInterceptCa {
       // keyCertSign | cRLSign
       extension(OID.keyUsage, true, bitString(Uint8Array.of(0x06), 1)),
       extension(OID.subjectKeyIdentifier, false, octetString(keyIdentifier(publicKey))),
+      ...(options.permittedDnsNames?.length
+        ? [extension(OID.nameConstraints, true, nameConstraints(options.permittedDnsNames, options.excludeAllIpAddresses !== false))]
+        : []),
     ],
   });
   return {
@@ -197,13 +225,27 @@ export function createLocalInterceptCa(): LocalInterceptCa {
   };
 }
 
-/** Issue a serverAuth leaf for `hosts` (first entry becomes the CN; all become SAN dNSNames). */
-export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly string[]): PemKeyPair {
+export function createLocalInterceptCa(): LocalInterceptCa {
+  return createCertificateAuthority({ commonName: CLAUDE_INTERCEPT_CA_COMMON_NAME });
+}
+
+/** IPv4 literal to its four octets, or null. Only the leaf SAN encoder needs it. */
+function ipv4Octets(host: string): Uint8Array | null {
+  const parts = host.split(".");
+  if (parts.length !== 4 || !parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)) return null;
+  return Uint8Array.from(parts.map(Number));
+}
+
+/**
+ * Issue a serverAuth leaf for `hosts` (first entry becomes the CN). Names become SAN dNSNames and
+ * IPv4 literals become iPAddress entries.
+ */
+export function issueServerLeaf(ca: LocalInterceptCa, issuerCommonName: string, hosts: readonly string[]): PemKeyPair {
   if (hosts.length === 0) throw new Error("intercept leaf requires at least one host");
   const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
   const der = issueCertificate({
     subject: distinguishedName(hosts[0]!),
-    issuer: distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME),
+    issuer: distinguishedName(issuerCommonName),
     subjectKey: publicKey,
     signingKey: ca.privateKey,
     validityDays: LEAF_VALIDITY_DAYS,
@@ -213,7 +255,10 @@ export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly st
       extension(OID.keyUsage, true, bitString(Uint8Array.of(0x80), 7)),
       extension(OID.extendedKeyUsage, false, sequence(objectIdentifier(OID.serverAuth))),
       extension(OID.subjectAltName, false, sequence(
-        ...hosts.map(host => contextTag(2, new TextEncoder().encode(host), false)),
+        ...hosts.map(host => {
+          const octets = ipv4Octets(host);
+          return octets ? contextTag(7, octets, false) : contextTag(2, new TextEncoder().encode(host), false);
+        }),
       )),
       extension(OID.authorityKeyIdentifier, false, sequence(contextTag(0, keyIdentifier(ca.publicKey), false))),
     ],
@@ -224,6 +269,10 @@ export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly st
   };
 }
 
+export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly string[]): PemKeyPair {
+  return issueServerLeaf(ca, CLAUDE_INTERCEPT_CA_COMMON_NAME, hosts);
+}
+
 // ── Persistence ─────────────────────────────────────────────────────────────────
 
 export const CLAUDE_INTERCEPT_STATE_DIR = "claude-intercept";
@@ -246,7 +295,7 @@ function writeFileAtomic(path: string, contents: string, mode: number): void {
   renameSync(tmp, path);
 }
 
-function loadPersistedCa(dir: string): LocalInterceptCa | null {
+function loadPersistedCa(dir: string, accept?: (cert: X509Certificate) => boolean): LocalInterceptCa | null {
   const certPath = join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE);
   const keyPath = join(dir, CA_KEY_FILE);
   if (!existsSync(certPath) || !existsSync(keyPath)) return null;
@@ -256,32 +305,41 @@ function loadPersistedCa(dir: string): LocalInterceptCa | null {
     const privateKey = createPrivateKey(keyPem);
     const publicKey = createPublicKey(keyPem);
     const certificate = new X509Certificate(certPem);
-    if (!certificate.ca || !certificate.checkPrivateKey(privateKey) || !certificate.verify(publicKey)) return null;
+    if (!certificate.ca || !certificate.checkPrivateKey(privateKey) || !certificate.verify(publicKey)
+      || (accept && !accept(certificate))) return null;
     return { certPem, keyPem, publicKey, privateKey };
   } catch { // no-excuse-ok: catch -- an unreadable or corrupt authority is regenerated below.
     return null;
   }
 }
 
-/**
- * Load the persisted authority under `<configDir>/claude-intercept/`, minting one when absent
- * or unreadable. The private key is written 0600; the certificate is world-readable because
- * `NODE_EXTRA_CA_CERTS` only needs the public half.
- */
-export function ensureLocalInterceptCa(configDir: string): LocalInterceptCa {
-  const dir = claudeInterceptStateDir(configDir);
+/** Persist an authority under its own lease, replacing unreadable or rejected pairs. */
+export function ensurePersistedAuthority(
+  dir: string,
+  options: AuthorityOptions,
+  lockName = "ca-publication.sqlite",
+  accept?: (cert: X509Certificate) => boolean,
+): LocalInterceptCa {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   // A separate SQLite namespace binds exclusion to the explicit CA directory.
   // The OS releases it on crash; a contending caller fails before touching either
   // PEM. Readers also take the lease so they cannot observe half a publication.
   return withClientLifecycleSync(() => {
-    const existing = loadPersistedCa(dir);
+    const existing = loadPersistedCa(dir, accept);
     if (existing) return existing;
-    const ca = createLocalInterceptCa();
+    const ca = createCertificateAuthority(options);
     writeFileAtomic(join(dir, CA_KEY_FILE), ca.keyPem, 0o600);
     writeFileAtomic(join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE), ca.certPem, 0o644);
     return ca;
-  }, { lockPath: join(dir, "ca-publication.sqlite") });
+  }, { lockPath: join(dir, lockName) });
+}
+
+/** Preserve the original intercept CA path, name, permissions and extension set. */
+export function ensureLocalInterceptCa(configDir: string): LocalInterceptCa {
+  return ensurePersistedAuthority(
+    claudeInterceptStateDir(configDir),
+    { commonName: CLAUDE_INTERCEPT_CA_COMMON_NAME },
+  );
 }
 
 /** Startup may race a settings apply publishing the same CA. Retry only lease

package/src/claude/intercept/model-bindings.ts

@@ -0,0 +1,145 @@
+import type { OcxClaudeCodeConfig } from "../../types";
+
+/**
+ * First-party model bindings for Claude Code traffic that reaches opencodex through the local
+ * intercept pair (Claude Desktop's Code tab and the standalone `claude` CLI in first-party mode).
+ *
+ * In first-party mode Claude Desktop's Code tab picker is owned by claude.ai: its rows come from
+ * the account's model selector config and no local setting can add one. What opencodex does see
+ * is the picker's Anthropic model id on every Messages request. A binding maps such an id
+ * (`claude-sonnet-4-6`) to an opencodex route (`xai/grok-4.7`), so picking that row in Desktop is
+ * served by the bound model. The picker keeps Anthropic's label; the binding only changes which
+ * model answers.
+ *
+ * Bindings live in `claudeCode.intercept.modelMap` and apply ONLY to requests that arrived on the
+ * `claude-intercept` ingress. They are overlaid on the global `claudeCode.modelMap` for that one
+ * request (binding wins per key), so every existing resolution rule still applies: alias first,
+ * Desktop 3P alias, exact key, date-suffix-stripped key, `[1m]` strip and `--fast` decode. The
+ * overlay is a request-scoped view of `claudeCode`; the live config object is never copied or
+ * persisted with the merged map.
+ */
+
+/** Anthropic picker id shape. Desktop only ever sends `claude-*` ids from its picker. */
+const BINDING_ID_PATTERN = /^claude-[a-z0-9][a-z0-9.\-]*$/i;
+const MAX_BINDING_ID_LENGTH = 128;
+const MAX_BINDING_ROUTE_LENGTH = 256;
+const NATIVE_ROUTE_PREFIX = "native/";
+
+/**
+ * Picker ids Claude Desktop's Code tab offered on 2026-09-23 (the claude.ai model selector config
+ * for a Max account). claude.ai owns this list; it is a suggestion for the dashboard, never a
+ * restriction, so any `claude-` id is accepted.
+ */
+export const DESKTOP_PICKER_ID_SUGGESTIONS: readonly string[] = [
+  "claude-opus-5-5",
+  "claude-sonnet-5",
+  "claude-fable-5-1",
+  "claude-haiku-4-5",
+  "claude-opus-5",
+  "claude-fable-5",
+  "claude-opus-4-8",
+  "claude-opus-4-7",
+  "claude-opus-4-6",
+  "claude-sonnet-4-6",
+];
+
+export function isInterceptBindingId(value: unknown): value is string {
+  return typeof value === "string" && value.length <= MAX_BINDING_ID_LENGTH && BINDING_ID_PATTERN.test(value);
+}
+
+export function isInterceptBindingRoute(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_BINDING_ROUTE_LENGTH && !/\s/.test(value);
+}
+
+/**
+ * Router model id for a binding target written in the Desktop route vocabulary. `native/<slug>`
+ * is the native OpenAI pool's pseudo-provider and resolves to the bare slug, exactly like a
+ * Desktop 3P alias does (src/claude/inbound-model-options.ts); every other route is used as is.
+ */
+export function normalizeBindingTarget(route: string): string {
+  return route.startsWith(NATIVE_ROUTE_PREFIX) && route.length > NATIVE_ROUTE_PREFIX.length
+    ? route.slice(NATIVE_ROUTE_PREFIX.length)
+    : route;
+}
+
+/** Valid bindings from a config value; malformed entries are ignored rather than routed. */
+export function readInterceptBindings(cc: OcxClaudeCodeConfig | undefined): Record<string, string> {
+  const raw = cc?.intercept?.modelMap;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out: Record<string, string> = {};
+  for (const [id, route] of Object.entries(raw)) {
+    if (isInterceptBindingId(id) && isInterceptBindingRoute(route)) out[id] = route;
+  }
+  return out;
+}
+
+/**
+ * The `claudeCode` view a Messages or count_tokens handler resolves models against. Requests on
+ * any other ingress, or with no bindings, get the live object back unchanged. Only binding
+ * targets are normalized; global `modelMap` values keep their verbatim semantics.
+ */
+export function claudeCodeForIngress(
+  cc: OcxClaudeCodeConfig | undefined,
+  claudeIntercept: boolean,
+): OcxClaudeCodeConfig | undefined {
+  if (!claudeIntercept) return cc;
+  const bindings = readInterceptBindings(cc);
+  const ids = Object.keys(bindings);
+  if (ids.length === 0) return cc;
+  const overlay: Record<string, string> = { ...(cc?.modelMap ?? {}) };
+  for (const id of ids) overlay[id] = normalizeBindingTarget(bindings[id]!);
+  return { ...(cc ?? {}), modelMap: overlay };
+}
+
+export interface InterceptBindingPatch {
+  set?: Record<string, string>;
+  remove?: string[];
+}
+
+export type InterceptBindingPatchResult =
+  | { ok: true; bindings: Record<string, string>; changed: boolean }
+  | { ok: false; error: string };
+
+/** Parse an untrusted PUT body into a patch. */
+export function parseInterceptBindingPatch(body: unknown): InterceptBindingPatch | { error: string } {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { error: "body must be an object" };
+  const { set, remove, ...rest } = body as Record<string, unknown>;
+  const unknown = Object.keys(rest);
+  if (unknown.length > 0) return { error: `unknown field: ${unknown[0]}` };
+  if (set === undefined && remove === undefined) return { error: "set or remove is required" };
+  const patch: InterceptBindingPatch = {};
+  if (set !== undefined) {
+    if (!set || typeof set !== "object" || Array.isArray(set)) return { error: "set must be an object of picker id to route" };
+    const entries: Record<string, string> = {};
+    for (const [id, route] of Object.entries(set as Record<string, unknown>)) {
+      if (!isInterceptBindingId(id)) return { error: `invalid picker id: ${id} (expected a claude- model id)` };
+      if (!isInterceptBindingRoute(route)) return { error: `invalid route for ${id}` };
+      entries[id] = route;
+    }
+    patch.set = entries;
+  }
+  if (remove !== undefined) {
+    if (!Array.isArray(remove) || remove.some(id => typeof id !== "string")) return { error: "remove must be an array of picker ids" };
+    patch.remove = remove as string[];
+  }
+  return patch;
+}
+
+/**
+ * Apply a patch to the current bindings. Routes must be in `availableRoutes` (the Desktop route
+ * vocabulary, native routes included); removing an unbound id is a no-op.
+ */
+export function applyInterceptBindingPatch(
+  current: Record<string, string>,
+  patch: InterceptBindingPatch,
+  availableRoutes: ReadonlySet<string>,
+): InterceptBindingPatchResult {
+  const next: Record<string, string> = { ...current };
+  for (const [id, route] of Object.entries(patch.set ?? {})) {
+    if (!availableRoutes.has(route)) return { ok: false, error: `route is not available: ${route}` };
+    next[id] = route;
+  }
+  for (const id of patch.remove ?? []) delete next[id];
+  const changed = JSON.stringify(Object.entries(next).sort()) !== JSON.stringify(Object.entries(current).sort());
+  return { ok: true, bindings: next, changed };
+}