@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
407 lines (391 loc) • 20.8 kB
text/typescript
import { Agent, request, type IncomingMessage } from "node:http";
import type { Socket } from "node:net";
import { Readable, Transform } from "node:stream";
import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
import { serviceApiTokenFingerprint } from "../lib/service-secrets";
import { clearableDeadline } from "../lib/abort";
import { packageVersion } from "../lib/package-version";
import { linkPeerReportHeaders } from "../link/peer-report";
import { buildPeerFeatures } from "../remote/features";
import {
LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION, LINK_RELAY_CONNECTION_HEADER,
LINK_RELAY_CONNECTION_PROOF_HEADER, LINK_RELAY_PROBE_HEADER, LINK_RELAY_SESSION_HEADER, linkConnectionProof,
linkRelayChallenge, linkRelayProofMatches,
} from "../link/relay-auth";
import { forgetVerifiedHomeConnection, recordVerifiedHomeConnection } from "./link-connection";
import { linkChildReportFeatures } from "../link/compatibility";
import { childLinkTraffic, type LinkTrafficBook, type LinkTrafficFlow } from "../link/traffic";
import { LINK_HOME_FEATURES_HEADER } from "../link/request-compression";
import { recordLinkHomeFeatures } from "./link-home-features";
import { applyLinkWebsocketAnswer, linkWebsocketAnswer, nextLinkPreflightSequence, type LinkWebsocketAnswer } from "./link-ws-advertisement";
export interface BoundLinkRelayTarget {
tunnelPort: number;
admissionKey: string;
linkId?: string;
apiKeyId?: string;
}
export class LinkRelayAuthenticationError extends Error {
constructor(readonly unrecognized = false) {
super(unrecognized ? "link relay authentication unavailable; upgrade the Home and Child or re-link"
: "link relay authentication failed");
this.name = "LinkRelayAuthenticationError";
}
}
/** Only the credential-free preflight deadline expired; no data request has begun. */
export class LinkRelayAuthTimeoutError extends Error {
constructor() {
super("link relay authentication timed out");
this.name = "LinkRelayAuthTimeoutError";
}
}
/**
* One physical connection, ever. A closed keep-alive socket cannot trigger a silent reconnect.
* Exported for the link WebSocket's upgrade (link-ws-transport.ts), which runs on the same kind of connection.
*/
export class SingleConnectionAgent extends Agent {
socket: Socket | undefined;
private opened = false;
private closeFlight?: Promise<void>;
/** Drain the socket close event before the request reports a terminal outcome. */
close(): Promise<void> {
if (this.closeFlight) return this.closeFlight;
const socket = this.socket;
this.closeFlight = !socket || socket.closed ? Promise.resolve()
: new Promise<void>(resolve => { socket.once("close", () => resolve()); });
this.destroy();
return this.closeFlight;
}
override createConnection(...[options, callback]: Parameters<Agent["createConnection"]>): ReturnType<Agent["createConnection"]> {
if (this.opened) {
if (!callback) throw new LinkRelayAuthenticationError();
callback(new LinkRelayAuthenticationError(), this.socket!);
return undefined;
}
this.opened = true;
this.socket = super.createConnection(options, callback) as Socket;
return this.socket;
}
}
export function requestOnConnection(
url: URL, init: RequestInit, agent: SingleConnectionAgent, authenticatedSocket?: Socket, onSent?: (bytes: number) => void,
onUploadSettled?: (finished: boolean) => void, onBodySettled?: () => void,
): Promise<IncomingMessage> {
// Nothing below keeps `init`: listeners on the request live until its connection closes, and a
// prepared body must not stay reachable through them after its write completed.
const method = init.method ?? "GET", signal = init.signal ?? undefined, initHeaders = init.headers;
let pendingBody = init.body;
return new Promise((resolve, reject) => {
// Once: true when every body write completed, false when the request or its socket closed first.
// Response headers alone prove neither, since a Home may answer before it reads the upload, so
// the caller's body lease (onBodySettled) is released here too.
let uploadSettled = false;
const settleUpload = (finished: boolean) => {
if (uploadSettled) return;
uploadSettled = true;
onUploadSettled?.(finished);
onBodySettled?.();
};
const headers = Object.fromEntries(new Headers(initHeaders));
// No implicit decompression negotiation; handle an explicitly encoded response below anyway.
headers["accept-encoding"] = "identity";
const outgoing = request(url, {
method, headers, agent, signal,
maxHeaderSize: 64 * 1024,
}, resolve);
outgoing.on("error", reject);
outgoing.once("close", () => settleUpload(false));
outgoing.on("upgrade", (_response, socket) => { socket.destroy(); reject(new LinkRelayAuthenticationError()); });
outgoing.on("socket", socket => {
if (authenticatedSocket && socket !== authenticatedSocket) outgoing.destroy(new LinkRelayAuthenticationError());
// Before the agent's own close listener, so a cut upload is settled before the request reports its end.
socket.once("close", () => settleUpload(false));
});
void (async () => {
const body = pendingBody;
pendingBody = null;
if (body instanceof ReadableStream) {
const reader = body.getReader();
const abort = () => { void reader.cancel(signal?.reason).catch(() => {}); };
signal?.addEventListener("abort", abort, { once: true });
outgoing.once("close", abort);
try {
for (;;) {
signal?.throwIfAborted();
const next = await reader.read();
if (next.done) break;
// Await the write callback: upstream backpressure never buffers the whole upload.
await new Promise<void>((done, fail) => outgoing.write(next.value,
error => error ? fail(error) : done()));
onSent?.(next.value.byteLength);
}
settleUpload(true);
} finally {
signal?.removeEventListener("abort", abort);
outgoing.removeListener("close", abort);
try { await reader.cancel(); } catch { /* preserve the upload outcome */ }
reader.releaseLock();
}
} else if (body != null) {
if (typeof body === "string" || body instanceof Uint8Array) {
// Counted once the socket took it, like each streamed chunk; a write that never completes counts
// nothing, and the body settles with its write or with the request's close.
const bytes = typeof body === "string" ? Buffer.byteLength(body) : body.byteLength;
outgoing.write(body, error => {
if (error) { settleUpload(false); return; }
onSent?.(bytes);
settleUpload(true);
});
} else throw new TypeError("unsupported link relay body");
} else settleUpload(true);
outgoing.end();
})().catch(error => {
settleUpload(false);
outgoing.destroy(error instanceof Error ? error : new Error("link upload failed"));
reject(error);
});
});
}
/**
* A data request's flow that ends only once both halves settled: the response (through `end`) and
* the upload (through `uploaded`). It is complete only when both finished, so a Home that answered in
* full before reading the whole body still leaves the request incomplete and `toHomeBytes` flagged as
* a lower bound.
*/
function untilBothSettled(flow: LinkTrafficFlow): { flow: LinkTrafficFlow; uploaded(finished: boolean): void } {
let response: boolean | undefined, upload: boolean | undefined;
const settle = () => { if (response !== undefined && upload !== undefined) flow.end(response && upload); };
return {
flow: {
toHome: bytes => flow.toHome(bytes), fromHome: bytes => flow.fromHome(bytes), uncounted: () => flow.uncounted(),
end(complete) { if (response === undefined) { response = complete; settle(); } },
},
uploaded(finished) { if (upload === undefined) { upload = finished; settle(); } },
};
}
function responseHeaders(incoming: IncomingMessage): Headers {
const headers = new Headers();
for (let i = 0; i < incoming.rawHeaders.length; i += 2) {
headers.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);
}
return headers;
}
/**
* Node HTTP compatibility is confined here; the relay continues to expose a Web Response/stream.
* `flow` counts the response body as it arrives on the socket, before any decoding, and ends
* complete when the body reached its end, incomplete on a cancel or an error.
*/
async function responseOnConnection(
incoming: IncomingMessage, agent: SingleConnectionAgent, method: string, flow?: LinkTrafficFlow,
): Promise<Response> {
const headers = responseHeaders(incoming);
const status = incoming.statusCode ?? 502;
if (method === "HEAD" || status === 204 || status === 205 || status === 304) {
for await (const chunk of incoming) flow?.fromHome((chunk as Buffer).byteLength);
await agent.close();
flow?.end(true);
return new Response(null, { status, headers });
}
let source: Readable = incoming;
const encoding = headers.get("content-encoding")?.trim().toLowerCase();
const decoder = encoding === "gzip" ? createGunzip() : encoding === "deflate" ? createInflate()
: encoding === "br" ? createBrotliDecompress() : undefined;
if (encoding && encoding !== "identity" && !decoder) {
throw new Error("unsupported link response encoding");
}
// Counted as the bytes leave the socket's stream, before any adapter queue or decoder, so a
// cancel after they were read still counts them; pipe() keeps the caller's backpressure.
const counter = flow ? new Transform({
transform(chunk: Buffer, _encoding, done) { flow.fromHome(chunk.byteLength); done(null, chunk); },
}) : undefined;
if (counter) {
incoming.on("error", error => counter.destroy(error));
source = incoming.pipe(counter);
}
if (decoder) {
const upstream = source;
upstream.on("error", error => decoder.destroy(error));
source = upstream.pipe(decoder);
}
const reader = (Readable.toWeb(source) as unknown as ReadableStream<Uint8Array>).getReader();
let finished = false;
const finish = async () => {
if (finished) return agent.close();
finished = true;
if (source !== incoming) source.destroy();
counter?.destroy();
await agent.close();
try { reader.releaseLock(); } catch { /* a cancelled read may still be settling */ }
};
return new Response(new ReadableStream<Uint8Array>({
async pull(controller) {
try {
const next = await reader.read();
if (next.done) { flow?.end(true); await finish(); controller.close(); }
else controller.enqueue(next.value);
} catch (error) { flow?.end(false); await finish(); controller.error(error); }
},
async cancel(reason) {
flow?.end(false);
try { await reader.cancel(reason); } finally { await finish(); }
},
}, { highWaterMark: 0 }), { status, headers });
}
/** Test seam: the response half alone, over any readable that looks like an IncomingMessage. */
export const linkResponseOnConnectionForTests = (incoming: IncomingMessage, close: () => Promise<void>, method: string, flow?: LinkTrafficFlow) =>
responseOnConnection(incoming, { close } as SingleConnectionAgent, method, flow);
let peerReport: Record<string, string> | undefined;
/**
* The credential-free challenge for one connection; the proof binds this nonce to the link key. It
* takes its preflight number when it starts, which orders the Home's WebSocket advertisement.
*/
export function relayChallenge(target: BoundLinkRelayTarget, origin: URL) {
const preflight = nextLinkPreflightSequence();
const challenge = linkRelayChallenge(serviceApiTokenFingerprint(target.admissionKey), target.apiKeyId!, target.linkId!);
const probe = new URL(LINK_RELAY_AUTH_PATH, origin);
probe.search = new URLSearchParams({ version: LINK_RELAY_AUTH_VERSION, key: target.apiKeyId!,
link: target.linkId!, nonce: challenge.nonce, proof: challenge.caller }).toString();
// The challenge also carries this Child's version and features for the Home's link status.
peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), linkChildReportFeatures(buildPeerFeatures()));
return { challenge, probe, headers: peerReport, preflight };
}
/**
* Called only after the Home's relay proof verified. Keep its connection generation when its own
* proof binds it to this nonce and key; otherwise the connection is unknown, never the old value.
* Its Responses WebSocket state is applied under the preflight ordering rule (link-ws-advertisement.ts)
* and returned, so an upgrade decides from its own answer.
*/
export function noteHomeConnection(
target: BoundLinkRelayTarget, nonce: string, headers: IncomingMessage["headers"], preflight: number,
): { features: readonly string[] | null; websocket: LinkWebsocketAnswer } {
if (!target.linkId || !target.apiKeyId) return { features: null, websocket: "off" };
const fingerprint = serviceApiTokenFingerprint(target.admissionKey);
const websocket = linkWebsocketAnswer(headers, { fingerprint, keyId: target.apiKeyId, linkId: target.linkId, nonce });
applyLinkWebsocketAnswer(target.linkId, preflight, websocket);
// What this Home serves, as it named it on this verified answer (#3023). Recorded for the next
// request's decision and returned so this connection's own body can be chosen from it.
const named = headers[LINK_HOME_FEATURES_HEADER];
const features = recordLinkHomeFeatures(target.linkId, typeof named === "string" ? named : null);
const generation = headers[LINK_RELAY_CONNECTION_HEADER];
const proof = headers[LINK_RELAY_CONNECTION_PROOF_HEADER];
const expected = typeof generation === "string"
? linkConnectionProof(fingerprint, target.apiKeyId, target.linkId, nonce, generation)
: null;
if (typeof generation === "string" && typeof proof === "string" && linkRelayProofMatches(proof, expected)) {
recordVerifiedHomeConnection(target.linkId, generation);
} else forgetVerifiedHomeConnection(target.linkId);
return { features, websocket };
}
/**
* The outcome of the credential-free preflight alone: `ok` when the Home answered with a proof
* only the holder of the link key can make, `unrecognized` for a peer without the route (404),
* `auth_failed` for any other answer, and `unreachable` when nothing answered in time.
*/
export type LinkRelayPreflightResult = "ok" | "unreachable" | "auth_failed" | "unrecognized";
/**
* Run only the preflight a relayed request starts with, on its own connection, and close it. It
* sends no link key, no data request and no body; the Child's readiness uses it to learn whether
* the Home answers through the tunnel right now. It is marked probe-only, so the Home reserves no
* session for a data request that never comes. The response body is never read.
*/
export async function probeLinkRelayPreflight(
target: BoundLinkRelayTarget, options: { timeoutMs?: number } = {},
): Promise<LinkRelayPreflightResult> {
const timeoutMs = options.timeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new RangeError("invalid link relay preflight timeout");
if (!target.linkId || !target.apiKeyId) return "auth_failed";
const origin = new URL(`http://127.0.0.1:${target.tunnelPort}`);
let request: ReturnType<typeof relayChallenge>;
try { request = relayChallenge(target, origin); } catch { return "auth_failed"; }
const agent = new SingleConnectionAgent({ keepAlive: false, maxSockets: 1, maxFreeSockets: 0 });
const deadline = clearableDeadline(timeoutMs);
try {
const response = await requestOnConnection(request.probe, {
method: "GET", signal: deadline.signal, headers: { ...request.headers, [LINK_RELAY_PROBE_HEADER]: "1" },
}, agent);
const proof = response.headers["x-opencodex-link-proof"];
if (response.statusCode === 204 && typeof proof === "string" && linkRelayProofMatches(proof, request.challenge.expected)) {
noteHomeConnection(target, request.challenge.nonce, response.headers, request.preflight);
return "ok";
}
return response.statusCode === 404 ? "unrecognized" : "auth_failed";
} catch {
return "unreachable";
} finally {
deadline.clear();
await agent.close();
}
}
/**
* Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch.
* LinkRelayAuthTimeoutError certifies that only the credential-free preflight expired before
* data-request construction. Caller aborts and failures after that boundary keep their own errors.
*
* Every link body is counted here (#3023), so the relay and the Child's own reads of the Home
* count alike: a request from the moment its data request starts on the authenticated socket,
* each request-body chunk once the socket took it, and each response-body chunk as it arrives,
* before any decoding. A failed challenge or a refused connection sent no data and counts nothing.
*/
export async function fetchBoundLinkRelay(
target: BoundLinkRelayTarget, destination: string, init: RequestInit,
options: {
authTimeoutMs?: number;
traffic?: LinkTrafficBook;
/**
* Choose the request body once this connection's Home has proved itself and named its
* features: a prepared body's zstd form only when this very answer names the capability.
*/
selectBody?: (homeFeatures: readonly string[] | null) => { body: Uint8Array<ArrayBuffer>; headers: Record<string, string> };
/** Called once the data request's body was flushed to the socket or the request was torn down. */
onBodySettled?: () => void;
} = {},
): Promise<Response> {
const authTimeoutMs = options.authTimeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
if (!Number.isFinite(authTimeoutMs) || authTimeoutMs <= 0) throw new RangeError("invalid link relay auth timeout");
if (!target.linkId || !target.apiKeyId) throw new LinkRelayAuthenticationError();
const url = new URL(destination);
if (url.origin !== `http://127.0.0.1:${target.tunnelPort}`) throw new LinkRelayAuthenticationError();
const { challenge, probe, headers: preflightHeaders, preflight } = relayChallenge(target, url);
const agent = new SingleConnectionAgent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });
const deadline = clearableDeadline(authTimeoutMs, init.signal ?? undefined);
let dataRequestStarted = false;
let flow: ReturnType<typeof untilBothSettled> | undefined;
try {
const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: preflightHeaders }, agent);
const socket = agent.socket;
const proof = response.headers["x-opencodex-link-proof"];
if (response.statusCode !== 204 || typeof proof !== "string" || !linkRelayProofMatches(proof, challenge.expected)) {
throw new LinkRelayAuthenticationError(response.statusCode === 404);
}
const homeFeatures = noteHomeConnection(target, challenge.nonce, response.headers, preflight).features;
// Drain the credential-free response before the Agent can reuse its socket.
for await (const chunk of response) {
if (chunk.length) throw new LinkRelayAuthenticationError();
}
deadline.signal.throwIfAborted();
deadline.clear();
init.signal?.throwIfAborted();
if (!socket || socket.destroyed || socket !== agent.socket) throw new LinkRelayAuthenticationError();
const headers = new Headers(init.headers);
headers.set(LINK_RELAY_SESSION_HEADER, challenge.nonce);
let body = init.body;
if (options.selectBody) {
const chosen = options.selectBody(homeFeatures);
body = chosen.body;
for (const [name, value] of Object.entries(chosen.headers)) headers.set(name, value);
}
dataRequestStarted = true;
flow = target.linkId ? untilBothSettled((options.traffic ?? childLinkTraffic).begin(target.linkId)) : undefined;
const incoming = await requestOnConnection(url, { ...init, headers, body }, agent, socket, bytes => flow?.flow.toHome(bytes),
finished => flow?.uploaded(finished), options.onBodySettled);
return await responseOnConnection(incoming, agent, init.method ?? "GET", flow?.flow);
} catch (error) {
flow?.flow.end(false);
const authDeadlineExpired = !dataRequestStarted && deadline.didExpire()
&& !(error instanceof LinkRelayAuthenticationError);
await agent.close();
// The connection is gone, so an upload that has not settled yet never will.
flow?.uploaded(false);
if (authDeadlineExpired && !init.signal?.aborted) throw new LinkRelayAuthTimeoutError();
throw error;
} finally { deadline.clear(); }
}