@bitkyc08/opencodex 2.65.0 → 2.66.0

package/src/chat/outbound.ts

@@ -31,7 +31,7 @@ function uuid(): string {
   return crypto.randomUUID().replace(/-/g, "");
 }
 
-function completionId(): string {
+export function completionId(): string {
   return `chatcmpl-${uuid().slice(0, 24)}`;
 }
 
@@ -133,12 +133,12 @@ function streamErrorStatus(message: string): number {
   return 502;
 }
 
-function dataFrame(payload: Rec | "[DONE]"): string {
+export function dataFrame(payload: Rec | "[DONE]"): string {
   if (payload === "[DONE]") return "data: [DONE]\n\n";
   return `data: ${JSON.stringify(payload)}\n\n`;
 }
 
-function chunkBase(id: string, model: string, created: number): Rec {
+export function chunkBase(id: string, model: string, created: number): Rec {
   return {
     id,
     object: "chat.completion.chunk",
@@ -161,6 +161,90 @@ function appendedUtf8Bytes(previous: string, previousBytes: number, fragment: st
   return nextBytes;
 }
 
+/** Details a streamed Chat failure carries into its error frame. */
+export interface ChatCompletionsStreamFailure {
+  code?: string | null;
+  type?: string;
+  status?: number;
+}
+
+/**
+ * The `data: {error}` payload a streamed Chat failure ends with, and whether it is one of the
+ * fixed, bounded failures that must be delivered even when the translation budget is exhausted.
+ * Provider text is redacted; the two fixed failures carry no provider text at all.
+ */
+export function chatCompletionsStreamErrorPayload(
+  message: string,
+  details?: ChatCompletionsStreamFailure,
+): { payload: Rec; bounded: boolean } {
+  const translatorOverflow = details?.code === "translation_buffer_limit";
+  const safeMessage = translatorOverflow ? "upstream translation buffer exceeded the safe limit"
+    : details?.code === "invalid_refusal" ? "upstream refusal representations are inconsistent"
+    : redactSecretString(message);
+  const statusHint = details?.status ?? streamErrorStatus(safeMessage);
+  const classified = classifyError(statusHint, details?.type ?? "upstream_error", safeMessage);
+  if (translatorOverflow) {
+    classified.code = "translation_buffer_limit";
+    // Provider-controlled overflow is an upstream failure on every path:
+    // streaming frame, collector, and defensive JSON agree on 502.
+    classified.type = "upstream_error";
+  } else if (details?.code === "invalid_refusal") {
+    classified.code = details.code;
+    classified.type = "upstream_error";
+  } else if (isCyberPolicyCode(details?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
+    classified.code = CYBER_POLICY_ERROR_CODE;
+    classified.type = cyberPolicyErrorType(details?.type);
+  } else if (details?.code !== undefined && details.code !== null && !classified.code) {
+    classified.code = details.code;
+  }
+  return {
+    payload: {
+      error: {
+        message: classified.message,
+        type: classified.type,
+        param: null,
+        code: classified.code,
+      },
+    },
+    bounded: translatorOverflow || details?.code === "invalid_refusal",
+  };
+}
+
+/** How a Responses `response.failed` error object becomes a streamed Chat failure. */
+export function chatCompletionsFailedResponse(error: Rec): { message: string; details: ChatCompletionsStreamFailure } {
+  const message = typeof error.message === "string" ? error.message : "upstream request failed";
+  const code = typeof error.code === "string" ? error.code : null;
+  const type = typeof error.type === "string" ? error.type : undefined;
+  return {
+    message,
+    details: {
+      code,
+      ...(code === "translation_buffer_limit"
+        ? { status: 502, type: "upstream_error" }
+        : { type, ...(code === CYBER_POLICY_ERROR_CODE ? { status: 400 } : {}) }),
+    },
+  };
+}
+
+/**
+ * A Responses incomplete reason as the Chat client sees it: a truthful early finish for an
+ * output cap or a content filter, and a failure for every other reason (stall, adapter EOF,
+ * proxy-synthesized incompletes), which must never look like a clean stop.
+ */
+export function chatCompletionsIncompleteOutcome(
+  reason: unknown,
+  message: unknown,
+): { finishReason: "length" | "content_filter" } | { failMessage: string } {
+  if (reason === "max_output_tokens") return { finishReason: "length" };
+  if (reason === "content_filter") return { finishReason: "content_filter" };
+  const why = typeof reason === "string" ? reason : "unknown";
+  return {
+    failMessage: typeof message === "string" && message.length > 0
+      ? message
+      : `upstream stream ended early (${why})`,
+  };
+}
+
 function refusalTranslationError(): ChatCompletionsStreamError {
   // Never include provider-controlled refusal text or correlation IDs in diagnostics.
   return new ChatCompletionsStreamError("upstream refusal representations are inconsistent", {
@@ -506,38 +590,12 @@ export function responsesSseToChatCompletionsSse(
         // Deliver the error frame then close the stream abnormally (no [DONE]).
         // Do not controller.error() — that can drop already-enqueued bytes from consumers
         // like response.text().
-        const translatorOverflow = details?.code === "translation_buffer_limit";
-        const safeMessage = translatorOverflow ? "upstream translation buffer exceeded the safe limit"
-          : details?.code === "invalid_refusal" ? "upstream refusal representations are inconsistent"
-          : redactSecretString(message);
-        const statusHint = details?.status ?? streamErrorStatus(safeMessage);
-        const classified = classifyError(statusHint, details?.type ?? "upstream_error", safeMessage);
-        if (translatorOverflow) {
-          classified.code = "translation_buffer_limit";
-          // Provider-controlled overflow is an upstream failure on every path:
-          // streaming frame, collector, and defensive JSON agree on 502.
-          classified.type = "upstream_error";
-        } else if (details?.code === "invalid_refusal") {
-          classified.code = details.code;
-          classified.type = "upstream_error";
-        } else if (isCyberPolicyCode(details?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
-          classified.code = CYBER_POLICY_ERROR_CODE;
-          classified.type = cyberPolicyErrorType(details?.type);
-        } else if (details?.code !== undefined && details.code !== null && !classified.code) {
-          classified.code = details.code;
-        }
+        const { payload, bounded } = chatCompletionsStreamErrorPayload(message, details);
         try {
-          const frame = encoder.encode(dataFrame({
-            error: {
-              message: classified.message,
-              type: classified.type,
-              param: null,
-              code: classified.code,
-            },
-          }));
+          const frame = encoder.encode(dataFrame(payload));
           // These fixed, bounded failures must survive even when decoder-owned input
           // still fills the budget. They contain no provider text or IDs.
-          if (translatorOverflow || details?.code === "invalid_refusal") controller.enqueue(frame);
+          if (bounded) controller.enqueue(frame);
           else enqueueLiveFrame(frame);
           emittedFrames++;
         } catch {
@@ -552,8 +610,16 @@ export function responsesSseToChatCompletionsSse(
         }
         switch (eventName) {
           case "response.created":
+            ensureRole();
+            break;
           case "response.heartbeat":
             ensureRole();
+            // A typed Responses heartbeat carries transport liveness, not Chat content. Preserve
+            // that signal as an SSE comment so idle-sensitive Chat clients receive bytes without
+            // inventing a semantic chunk that parsers, usage counters, or progress watchdogs could
+            // mistake for model output.
+            enqueueLiveFrame(encoder.encode(": opencodex heartbeat\n\n"));
+            emittedFrames++;
             break;
           case "response.output_text.delta": {
             if (typeof data.delta === "string") emitContent(data.delta);
@@ -680,37 +746,23 @@ export function responsesSseToChatCompletionsSse(
           case "response.incomplete": {
             const response = isRec(data.response) ? data.response : {};
             const details = isRec(response.incomplete_details) ? response.incomplete_details : {};
-            const reason = details.reason === "max_output_tokens" ? "length"
-              : details.reason === "content_filter" ? "content_filter"
-              : undefined;
-            if (reason !== undefined) {
+            const outcome = chatCompletionsIncompleteOutcome(details.reason, details.message);
+            if ("finishReason" in outcome) {
               // Truthful OpenAI-compatible finish reasons: the turn ended, just early.
               snapshotRefusals(response);
-              finish(reason, response.usage);
+              finish(outcome.finishReason, response.usage);
             } else {
               // upstream_stall_timeout / adapter_eof / proxy-synthesized incompletes are
               // failures, not early finishes: emit an error frame and close WITHOUT
               // [DONE] instead of a success-looking stop/tool_calls + [DONE].
-              const why = typeof details.reason === "string" ? details.reason : "unknown";
-              const message = typeof details.message === "string" && details.message.length > 0
-                ? details.message
-                : `upstream stream ended early (${why})`;
-              fail(message);
+              fail(outcome.failMessage);
             }
             break;
           }
           case "response.failed": {
             const response = isRec(data.response) ? data.response : {};
-            const error = isRec(response.error) ? response.error : {};
-            const message = typeof error.message === "string" ? error.message : "upstream request failed";
-            const code = typeof error.code === "string" ? error.code : null;
-            const type = typeof error.type === "string" ? error.type : undefined;
-            fail(message, {
-              code,
-              ...(code === "translation_buffer_limit"
-                ? { status: 502, type: "upstream_error" }
-                : { type, ...(code === CYBER_POLICY_ERROR_CODE ? { status: 400 } : {}) }),
-            });
+            const failure = chatCompletionsFailedResponse(isRec(response.error) ? response.error : {});
+            fail(failure.message, failure.details);
             break;
           }
           default:

package/src/claude/claude-code-block.ts

@@ -0,0 +1,16 @@
+/**
+ * The one way a management route installs a new `claudeCode` block on the live config.
+ *
+ * Every writer stamps the auth-mode migration sentinel. `runClaudeAuthModeMigration` reads a
+ * block with no `authMode` and no sentinel as a pre-upgrade subscriber and pins it to literal
+ * subscription, so a route that CREATES the block (a bare `{ enabled }` toggle) without the
+ * sentinel silently converts an Auto user on the next start. Persisting stays with the caller,
+ * through `saveConfigPreservingClaudeCode`, whose baseline guard keeps a concurrent hand edit
+ * of the block unless this process changed it too.
+ */
+import type { OcxClaudeCodeConfig, OcxConfig } from "../types";
+
+export function commitClaudeCodeBlock(config: OcxConfig, next: OcxClaudeCodeConfig, now = new Date()): void {
+  if (!next.authModeMigratedAt) next.authModeMigratedAt = now.toISOString();
+  config.claudeCode = next;
+}

package/src/claude/context-windows.ts

@@ -7,14 +7,26 @@
  * the legacy claude-ocx-* spelling a saved selector may still carry —
  * with first-wins dedupe (mirrors the desktop3p registry collision policy).
  * Values are authoritative context windows only (native override table /
- * adapter-reported CatalogModel.contextWindow); nothing is guessed.
+ * adapter-reported CatalogModel.contextWindow / the Anthropic registry for passthrough ids);
+ * nothing is guessed.
  */
 import { aliasForNative, aliasForRoute, currentClaudeAliasSpelling, legacyAliasForNative, legacyAliasForRoute } from "./alias";
 import { desktop3pAlias } from "./desktop-3p";
 import { nativeOpenAiContextWindow, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
+import { ANTHROPIC_MODEL_CONTEXT_WINDOWS } from "../providers/registry/model-seeds";
+import type { OcxClaudeCodeConfig } from "../types";
 
 const ONE_MILLION = 1_000_000;
 
+/**
+ * The native id each Claude Code tier alias resolves to (2.1.282: `--model opus` sends
+ * `claude-opus-5-5`, `sonnet` sends `claude-sonnet-5`, `fable` sends `claude-fable-5-1`).
+ * Behind a gateway Claude Code accounts an unmarked id at 200k, so an unset tier slot is filled
+ * with this id when the map marks it (#5755). A marked alias cannot stand in: Claude Code sends
+ * `sonnet[1m]` upstream unresolved. Haiku has no entry; its 200k window never marks.
+ */
+const CLAUDE_CODE_NATIVE_TIERS = { opus: "claude-opus-5-5", sonnet: "claude-sonnet-5", fable: "claude-fable-5-1" } as const;
+
 /**
  * Auto-context defaults (devlog 260712 020, user-approved).
  *
@@ -124,6 +136,27 @@ export function shouldMarkOneMillion(window: number | undefined, auto: AutoConte
   return auto.enabled && window > AUTO_CONTEXT_FLOOR && window >= auto.compactWindow;
 }
 
+/** Present when bare Claude ids take the native passthrough on this launch (#5755). */
+export interface NativeClaudePassthrough {
+  /** `claudeCode.modelMap`: a mapped id is routed, not passed through. */
+  modelMap?: Readonly<Record<string, string>>;
+}
+
+/**
+ * On a local subscription launch with `nativePassthrough` on, a bare `claude-*` id goes straight
+ * to Anthropic under Claude Code's own login and never reaches the router
+ * (server/claude-messages.ts `wantsNativePassthrough`). Undefined when the router decides:
+ * proxy auth, passthrough off, or a connected client, which authenticates with an admission token.
+ */
+export function nativeClaudePassthroughFor(
+  claudeCode: OcxClaudeCodeConfig | undefined,
+  markerMode: "proxy" | "subscription",
+): NativeClaudePassthrough | undefined {
+  return markerMode === "subscription" && claudeCode?.nativePassthrough !== false
+    ? { modelMap: claudeCode?.modelMap }
+    : undefined;
+}
+
 export function buildClaudeContextWindows(
   nativeSlugs: readonly string[],
   routedModels: readonly CatalogModel[],
@@ -131,6 +164,7 @@ export function buildClaudeContextWindows(
   // it the Claude surface keeps advertising the uncapped authoritative window while the
   // Codex catalog advertises the capped one, and the two disagree about the same model.
   nativeContextCap?: NativeContextLimitsInput,
+  nativeClaude?: NativeClaudePassthrough,
 ): Record<string, number> {
   const out: Record<string, number> = {};
   const put = (key: string | null, value: number) => {
@@ -145,6 +179,16 @@ export function buildClaudeContextWindows(
     put(aliasForNative(slug), window);
     put(legacyAliasForNative(slug), window);
   }
+  // Passthrough ids never reach the router, so the registry speaks for them ahead of any routed
+  // row that shares the bare id (#5755). An anthropic row capped under 1M still keeps its id
+  // unmarked, and a modelMap entry routes its id elsewhere.
+  if (nativeClaude) {
+    const capped = new Set(routedModels.flatMap(m =>
+      m.provider === "anthropic" && typeof m.contextWindow === "number" && m.contextWindow < ONE_MILLION ? [m.id] : []));
+    for (const [id, window] of Object.entries(ANTHROPIC_MODEL_CONTEXT_WINDOWS)) {
+      if (window >= ONE_MILLION && !capped.has(id) && !nativeClaude.modelMap?.[id]) put(id, window);
+    }
+  }
   // Anthropic passthrough guard (audit 021 #3): canonical claude ids ride the
   // subscription passthrough — marking a sub-1M one would strap [1m]/1M-beta onto
   // a model that cannot host it. Register anthropic rows only at >=1M.
@@ -217,10 +261,14 @@ export function effectiveModelEnv(
     const marked = withOneMillionMarker(value === undefined ? undefined : currentClaudeAliasSpelling(value), windows, auto);
     if (marked) out[name] = marked;
   };
+  // An unset tier slot is filled only when its native id marks; otherwise Claude Code keeps
+  // choosing, as before.
+  const tier = (configured: string | undefined, native: string) =>
+    configured ?? (shouldMarkOneMillion(windows[native], auto) ? native : undefined);
   set("ANTHROPIC_MODEL", claudeCode?.model);
-  set("ANTHROPIC_DEFAULT_OPUS_MODEL", claudeCode?.tierModels?.opus);
-  set("ANTHROPIC_DEFAULT_SONNET_MODEL", claudeCode?.tierModels?.sonnet);
-  set("ANTHROPIC_DEFAULT_FABLE_MODEL", claudeCode?.tierModels?.fable);
+  set("ANTHROPIC_DEFAULT_OPUS_MODEL", tier(claudeCode?.tierModels?.opus, CLAUDE_CODE_NATIVE_TIERS.opus));
+  set("ANTHROPIC_DEFAULT_SONNET_MODEL", tier(claudeCode?.tierModels?.sonnet, CLAUDE_CODE_NATIVE_TIERS.sonnet));
+  set("ANTHROPIC_DEFAULT_FABLE_MODEL", tier(claudeCode?.tierModels?.fable, CLAUDE_CODE_NATIVE_TIERS.fable));
   const effectiveHaiku = claudeCode?.tierModels?.haiku ?? claudeCode?.smallFastModel;
   set("ANTHROPIC_DEFAULT_HAIKU_MODEL", effectiveHaiku);
   set("ANTHROPIC_SMALL_FAST_MODEL", effectiveHaiku);

package/src/claude/desktop-first-party.ts

@@ -24,6 +24,7 @@ import type { OcxConfig } from "../types";
 import { inspectDesktop3pConfigLibrary } from "./desktop-3p";
 import { claudeInterceptCaCertPath, ensureLocalInterceptCa } from "./intercept/local-ca";
 import { claudeInterceptEnabled, claudeInterceptProxyPort } from "./intercept/runtime";
+import { ensureClaudeInterceptProxyToken, readClaudeInterceptProxyToken } from "./intercept/proxy-auth";
 import {
   applyClaudeInterceptSettings,
   buildClaudeInterceptEnv,
@@ -115,14 +116,22 @@ export interface DesktopFirstPartyTarget {
   env: ClaudeInterceptEnv;
 }
 
-/** The settings env a first-party apply on this machine writes (CA is created on demand). */
-export function desktopFirstPartyTarget(
+function firstPartyTarget(
   config: Pick<OcxConfig, "claudeCode" | "port">,
-  opencodexConfigDir = getConfigDir(),
+  opencodexConfigDir: string,
+  authToken: string,
 ): DesktopFirstPartyTarget {
   const proxyPort = claudeInterceptProxyPort(config, config.port ?? 10100);
   const caCertPath = claudeInterceptCaCertPath(opencodexConfigDir);
-  return { proxyPort, caCertPath, env: buildClaudeInterceptEnv(proxyPort, caCertPath) };
+  return { proxyPort, caCertPath, env: buildClaudeInterceptEnv(proxyPort, caCertPath, authToken) };
+}
+
+/** The settings env a first-party apply on this machine writes (CA and token are created on demand). */
+export function desktopFirstPartyTarget(
+  config: Pick<OcxConfig, "claudeCode" | "port">,
+  opencodexConfigDir = getConfigDir(),
+): DesktopFirstPartyTarget {
+  return firstPartyTarget(config, opencodexConfigDir, ensureClaudeInterceptProxyToken(opencodexConfigDir));
 }
 
 export interface DesktopFirstPartyInspection {
@@ -147,8 +156,11 @@ export function captureDesktopFirstPartyRollback(
   config: Pick<OcxConfig, "claudeCode" | "port">,
   options: DesktopFirstPartyOptions = {},
 ): () => boolean {
+  // The expected env resolves at rollback time: the apply mints the proxy token, so capturing it
+  // here would both mint on a path that may never apply and throw when the intercept directory is
+  // unavailable — a failure the apply already reports as ca_unavailable.
   return captureClaudeInterceptSettingsRollback(
-    desktopFirstPartyTarget(config, options.opencodexConfigDir).env, options.claudeConfigDir,
+    () => desktopFirstPartyTarget(config, options.opencodexConfigDir).env, options.claudeConfigDir,
   );
 }
 
@@ -156,7 +168,11 @@ export function inspectDesktopFirstParty(
   config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole">,
   options: DesktopFirstPartyOptions = {},
 ): DesktopFirstPartyInspection {
-  const target = desktopFirstPartyTarget(config, options.opencodexConfigDir);
+  const opencodexConfigDir = options.opencodexConfigDir ?? getConfigDir();
+  // Inspection is read-only: a missing token means no apply or runtime start produced one,
+  // so an owned env can never match the empty credential — it classifies stale, and a real
+  // apply is what refreshes it.
+  const target = firstPartyTarget(config, opencodexConfigDir, readClaudeInterceptProxyToken(opencodexConfigDir) ?? "");
   const settings = inspectClaudeInterceptSettings(target.env, options.claudeConfigDir);
   return {
     interceptEnabled: claudeInterceptEnabled(config),
@@ -205,12 +221,13 @@ export function applyDesktopFirstParty(
   options: DesktopFirstPartyOptions = {},
 ): DesktopFirstPartyApplyResult {
   const opencodexConfigDir = options.opencodexConfigDir ?? getConfigDir();
-  const target = desktopFirstPartyTarget(config, opencodexConfigDir);
   if (!claudeInterceptEnabled(config)) return { ok: false, reason: "intercept_disabled", path: "" };
+  let target: DesktopFirstPartyTarget;
   try {
     ensureLocalInterceptCa(opencodexConfigDir);
+    target = desktopFirstPartyTarget(config, opencodexConfigDir);
   } catch {
-    return { ok: false, reason: "ca_unavailable", path: target.caCertPath };
+    return { ok: false, reason: "ca_unavailable", path: claudeInterceptCaCertPath(opencodexConfigDir) };
   }
   const written = applyClaudeInterceptSettings(target.env, options.claudeConfigDir);
   if (!written.ok) return { ok: false, reason: written.reason, path: written.path };

package/src/claude/inbound.ts

@@ -177,6 +177,28 @@ function blockedSkillCallIds(messages: readonly unknown[], blocked: readonly str
   return ids;
 }
 
+/**
+ * Whether translating this Messages body would elide a blocked skill bundle: a user text block
+ * `maybeElideSkillText` would stub, or a tool_result answering a blocked Skill call. Pure; the
+ * managed native Messages lane asks it so a request whose bundle the operator blocked keeps the
+ * translated path that applies the block.
+ */
+export function anthropicBodyElidesBlockedSkill(body: unknown, cc?: Pick<OcxClaudeCodeConfig, "blockedSkills">): boolean {
+  if (!isRec(body) || !Array.isArray(body.messages)) return false;
+  const names = effectiveBlockedSkillNames(cc);
+  if (names.length === 0) return false;
+  const callIds = blockedSkillCallIds(body.messages, names);
+  for (const msg of body.messages) {
+    if (!isRec(msg) || msg.role !== "user" || !Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (!isRec(block)) continue;
+      if (block.type === "text" && typeof block.text === "string" && maybeElideSkillText(block.text, names) !== block.text) return true;
+      if (block.type === "tool_result" && typeof block.tool_use_id === "string" && callIds.has(block.tool_use_id)) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Claude Code (observed 2026-07-11, real CLI smoke) sends `role:"system"` entries in
  * `messages` despite the published API having no system role. They are emitted as

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

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "node:crypto";
 import { BlockList, createServer, connect, isIP, type Server, type Socket } from "node:net";
 
 /**
@@ -23,6 +24,12 @@ const UPSTREAM_CONNECT_TIMEOUT_MS = 15_000;
 export interface ConnectProxyOptions {
   /** Loopback port of the TLS listener that terminates intercepted tunnels. */
   interceptPort: number;
+  /**
+   * Per-install bearer carried as HTTP Basic proxy credentials. Omit only for listeners whose
+   * clients cannot present proxy credentials at all; an unauthenticated CONNECT proxy stays an
+   * open loopback relay, so every consumer that can carry the credential must set this.
+   */
+  authToken?: string | (() => string | null);
   /** Hostnames (lowercase) whose 443 tunnels are spliced onto `interceptPort`. */
   interceptHosts?: readonly string[];
   /** Per-connection override, consulted before interceptHosts; null keeps the default. */
@@ -60,7 +67,7 @@ function connectRequestInfo(head: string): ConnectRequestInfo {
 }
 
 type ResolvedConnectProxyOptions = Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>
-  & Pick<ConnectProxyOptions, "selectTunnel">;
+  & Pick<ConnectProxyOptions, "selectTunnel" | "authToken">;
 
 export interface ConnectProxyHandle {
   port: number;
@@ -103,9 +110,10 @@ export function isLoopbackTarget(host: string): boolean {
   return /^(0x[0-9a-f]+|\d+)(\.(0x[0-9a-f]+|\d+))*$/.test(host);
 }
 
-function respond(socket: Socket, status: number, reason: string): void {
+function respond(socket: Socket, status: number, reason: string, headers: Readonly<Record<string, string>> = {}): void {
   if (socket.destroyed) return;
-  socket.end(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  const extra = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join("");
+  socket.end(`HTTP/1.1 ${status} ${reason}\r\n${extra}Connection: close\r\nContent-Length: 0\r\n\r\n`);
 }
 
 function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
@@ -125,6 +133,20 @@ function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
   upstream.pipe(client);
 }
 
+function proxyAuthorized(head: string, token: string): boolean {
+  const header = head.split("\r\n").find(line => /^proxy-authorization:/i.test(line));
+  const supplied = header?.slice(header.indexOf(":") + 1).trim();
+  const expected = `Basic ${Buffer.from(`opencodex:${token}`).toString("base64")}`;
+  if (!supplied) return false;
+  // Compare byte lengths, not string lengths: the head decodes latin1 and Buffer.from
+  // re-encodes utf-8, so a non-ASCII header can match in characters while differing in
+  // bytes — and timingSafeEqual throws on a length mismatch instead of returning false.
+  const suppliedBytes = Buffer.from(supplied);
+  const expectedBytes = Buffer.from(expected);
+  if (suppliedBytes.length !== expectedBytes.length) return false;
+  return timingSafeEqual(suppliedBytes, expectedBytes);
+}
+
 function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions): void {
   let head: Buffer = Buffer.alloc(0);
   socket.on("error", () => socket.destroy());
@@ -143,13 +165,23 @@ function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions):
     }
     socket.off("data", onData);
     socket.pause();
-    const target = parseConnectRequestLine(head.subarray(0, end).toString("latin1"));
+    const requestHead = head.subarray(0, end).toString("latin1");
+    const target = parseConnectRequestLine(requestHead);
     // Bytes after the head belong to the tunnel (a client may pipeline its TLS ClientHello).
     let pending = head.subarray(end + 4);
     if (!target) {
       respond(socket, 405, "Method Not Allowed");
       return;
     }
+    if (options.authToken !== undefined) {
+      let token: string | null = null;
+      try { token = typeof options.authToken === "function" ? options.authToken() : options.authToken; }
+      catch { /* unavailable credential must never fall back to an unauthenticated proxy */ }
+      if (!token || !proxyAuthorized(requestHead, token)) {
+        respond(socket, 407, "Proxy Authentication Required", { "Proxy-Authenticate": 'Basic realm="OpenCodex"' });
+        return;
+      }
+    }
     if (isLoopbackTarget(target.host)) {
       respond(socket, 403, "Forbidden");
       return;
@@ -228,6 +260,7 @@ function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions):
 export function startConnectProxy(port: number, options: ConnectProxyOptions): Promise<ConnectProxyHandle> {
   const resolved: ResolvedConnectProxyOptions = {
     interceptPort: options.interceptPort,
+    authToken: options.authToken,
     interceptHosts: options.interceptHosts ?? CLAUDE_INTERCEPT_HOSTS,
     selectTunnel: options.selectTunnel,
     dialUpstream: options.dialUpstream ?? ((host: string, targetPort: number) => connect({ host, port: targetPort })),