Skip to content

Commit df3dd3f

Browse files
fix(claude): preserve bounded large headers in picker relay (#6551)
Claude Desktop picker HTTP relay rejects ordinary 24 KiB browser session headers at the runtime's default parser limit. Set a bounded 64 KiB allowance on incoming requests and ordinary upstream responses, preserving cookies and streamed body bytes. Oversized upstream headers still return an empty 502 with the fixed `upstream:headers-too-large` diagnostic. Replacement for #6524 at `0c258acd496aef26735ab6a61d65cce611e8ff88`: carries both parser limits, fixed overflow diagnostic, all three regressions and both documentation changes. Adds inbound overflow and large-header streaming/upgrade coverage. No source behavior deliberately dropped. Raw upgraded transport remains unchanged; its upstream bytes do not use the ordinary HTTP response parser. Related to #6511. No captured Desktop request proves large headers caused that issue; actual Desktop merged-chat/Cowork acceptance remains outstanding. This PR does not close it. Verified current head 9b44b1c with CI 37175007465 and scoped independent technical/security review. Co-authored-by: Yuxin Qiao <[email protected]>
1 parent be297a5 commit df3dd3f

4 files changed

Lines changed: 208 additions & 72 deletions

File tree

‎docs-site/src/content/docs/guides/claude-code.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,11 @@ picker lists Anthropic's own models until the removal succeeds. OpenCodex rememb
266266
still needs removal and retries on the next restart; `ocx claude desktop picker status` shows the
267267
picker as unavailable meanwhile.
268268

269+
Picker mode allows up to 64 KiB of headers on incoming requests and ordinary HTTP
270+
responses, preserving browser session cookies. Larger upstream response headers return
271+
502 and log `upstream:headers-too-large`, without cookie values or request paths.
272+
Upgraded connections continue to relay bytes directly after the request handshake.
273+
269274
While picker mode is on, Claude Desktop reaches the network through OpenCodex. If OpenCodex stops,
270275
Desktop is offline until you fully restart it or turn picker mode off. Check the state with
271276
`ocx claude desktop picker status`; use `ocx claude desktop picker trust` to repeat the trust step,

‎src/claude/intercept/picker-listener.ts‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ export interface PickerListenerOptions {
2323
}
2424
export interface PickerListenerHandle { port: number; close(): Promise<void> }
2525

26+
// Browser session cookies can exceed the HTTP compatibility layer's 16 KiB default.
27+
// Keep both sides bounded, while allowing ordinary desktop session headers through.
28+
export const PICKER_MAX_HEADER_BYTES = 64 * 1024;
29+
2630
const HOP_HEADERS = new Set([
2731
"connection", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization",
2832
"te", "trailer", "transfer-encoding", "upgrade",
@@ -65,7 +69,7 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
6569
const upstream = options.upstream ?? { host: "claude.ai", port: 443, servername: "claude.ai" };
6670
const cap = options.maxEncodedBytes ?? BOOTSTRAP_MAX_ENCODED_BYTES;
6771
const upgrades = new Set<Duplex>();
68-
const server = createServer({ cert: options.leaf.certPem, key: options.leaf.keyPem, ALPNProtocols: ["http/1.1"] });
72+
const server = createServer({ cert: options.leaf.certPem, key: options.leaf.keyPem, ALPNProtocols: ["http/1.1"], maxHeaderSize: PICKER_MAX_HEADER_BYTES });
6973

7074
server.on("request", (req: IncomingMessage, res: ServerResponse) => {
7175
const method = req.method ?? "GET";
@@ -87,7 +91,7 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
8791
const upReq = httpsRequest({
8892
host: upstream.host, port: upstream.port, servername: upstream.servername,
8993
ca: upstream.ca, rejectUnauthorized: true, agent: false,
90-
method, path: req.url, headers,
94+
method, path: req.url, headers, maxHeaderSize: PICKER_MAX_HEADER_BYTES,
9195
}, upRes => {
9296
const status = upRes.statusCode ?? 502;
9397
const originalHeaders = filteredHeaders(upRes.rawHeaders);
@@ -132,7 +136,12 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
132136
res.end(rewritten ?? original);
133137
});
134138
});
135-
upReq.on("error", fail);
139+
upReq.on("error", error => {
140+
if ((error as NodeJS.ErrnoException).code === "HPE_HEADER_OVERFLOW") {
141+
options.log?.(`picker ${method} ${category} upstream:headers-too-large`);
142+
}
143+
fail();
144+
});
136145
req.on("error", () => upReq.destroy());
137146
res.on("close", () => { if (!res.writableEnded) upReq.destroy(); });
138147
req.pipe(upReq);

‎structure/clients/claude-desktop.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,9 @@ The User-Agent is a routing hint, not a trust boundary: a client that fakes it r
198198
any local process already reaches (the `api.anthropic.com` intercept is on the Claude Code proxy
199199
too; the `claude.ai` relay verifies upstream and adds no credential) and breaks only its own TLS,
200200
because each terminator presents a certificate only its intended client trusts. `claude.ai:443` is
201-
terminated by a `node:https` HTTP/1.1 relay (`picker-listener.ts`) only while the runtime's cached
201+
terminated by a `node:https` HTTP/1.1 relay (`picker-listener.ts`) with a bounded 64 KiB
202+
incoming-request and ordinary upstream-response header allowance for browser session cookies,
203+
only while the runtime's cached
202204
decision is armed: macOS, persisted resolved Desktop mode first-party, Desktop intent on,
203205
`claudeCode.intercept.picker !== false`, no disarm latch, listener up, and the current picker CA
204206
trusted in the login keychain (`picker-trust.ts`). The picker CA (`picker-ca.ts`) carries critical
@@ -242,8 +244,12 @@ remote `ccr` (`picker-bootstrap.ts`), failing open to the original bytes; the mo
242244
comes from a persisted snapshot (`picker-models.ts`), so a bootstrap never waits on discovery. Picker aliases carry `[1m]` only for authoritative windows of at least 1M, using the shared context marker helper with auto-context disabled. Sub-million opt-ins remain unmarked because the picker cannot guarantee the Desktop runner's compaction environment. A
243245
CONNECT to claude.ai that arrives before the first refresh waits at most 3 s, then goes blind. A
244246
picker proxy bind failure only disables picker mode; a picker construction or start failure closes
245-
every socket the start had bound before rethrowing. Nothing is logged but method, bootstrap or
246-
other, and status.
247+
every socket the start had bound before rethrowing. Ordinary session cookies within the header
248+
allowance relay unchanged. Upstream header overflow returns an empty 502 and logs the fixed
249+
reason `upstream:headers-too-large`; other records contain only method, bootstrap or other,
250+
status, and fixed bootstrap rewrite outcomes. Header values and request paths are not logged.
251+
Upgraded connections retain raw TLS relay semantics; their upstream bytes do not pass through
252+
the ordinary HTTP response parser.
247253

248254
### Picker catalog rewrite bounds
249255

0 commit comments

Comments
 (0)