@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
190 lines (181 loc) • 10.3 kB
text/typescript
/**
* Where a process running ON THE HUB ITSELF dials the hub (#4236).
*
* There are TWO destinations here, not one base URL substituted everywhere, and conflating
* them is what broke every local integration on a tailnet-bound hub:
*
* 1. `localManagementOrigin` — authenticated management discovery/state (`/api/*`). It is
* served by the public listener and, on a hub, additionally by the loopback-only
* `hub.managementIngress`. Callers must still send a management credential: management
* authentication has no loopback bypass (structure/gui-and-management-api.md), and the unauthenticated loopback
* listener deliberately does not serve `/api/*` at all.
* 2. `localInferenceDestination` — the data plane a client wire actually speaks.
*
* Both resolvers have the SAME three-branch shape, because the bind address is the thing that
* decides. The first review of this module got that wrong for inference: it returned
* `http://127.0.0.1:<public port>` unconditionally whenever the loopback listener was off, so a
* hub with `hostname: <tailnet IP>` and no listener handed all eight call sites a socket that
* does not exist. The bind address has to be the fallback, exactly as it already was for
* management:
*
* loopback listener enabled → `127.0.0.1:<effective listener port>`, no credential
* loopback/absent `hostname` → `127.0.0.1:<public port>`, no credential
* wildcard `hostname` → `127.0.0.1:<public port>`, ADMISSION CREDENTIAL REQUIRED
* literal non-loopback IP → `<probeHostname(hostname)>:<public port>`, credential REQUIRED
* DNS bind name → `127.0.0.1:<public port>`, credential REQUIRED (fail closed)
*
* A wildcard bind does answer on 127.0.0.1, which is why its origin stays loopback, but the
* public listener demands data-plane admission regardless of which address received the
* request — so it lands in the same credential bucket as a tailnet bind. That is why the
* resolver returns a STRUCT rather than a string: a caller that cannot see
* `requiresAdmissionToken` cannot tell a free socket from one that will 401, and the only
* honest answers are "attach the data-plane credential" or "say so in a log line".
*
* The credential in question is the DATA-PLANE one — `OPENCODEX_API_AUTH_TOKEN`, the hardened
* service token file, or a configured `apiKeys` entry, the same ladder
* `standaloneCodexRoutingTarget` / the Codex provider table already uses. Never the admin
* token: no exported client configuration may carry management authority (reviewer constraint
* on #4236).
*/
import { isIP } from "node:net";
import { effectiveLoopbackListenerPort, isLoopbackHostname, isWildcardHostname, shouldInjectApiAuthHeader } from "../codex/loopback-target";
import { probeHostname } from "../server/proxy-liveness";
import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "./service-secrets";
import type { OcxConfig } from "../types";
export type LocalInferenceConfig = Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener">;
export type LocalManagementConfig = Pick<OcxConfig, "hostname" | "runtimeRole" | "hub">;
export interface LocalInferenceDestination {
/** Origin a local client wire dials, e.g. `http://127.0.0.1:10104`. */
origin: string;
/** Port component of `origin`. */
port: number;
/**
* Does the listener at `origin` demand `x-opencodex-api-key`?
*
* False only for the unauthenticated loopback listener and a genuinely loopback public bind.
* A caller that cannot attach a credential must log that it is degrading rather than write a
* destination that answers 401.
*/
requiresAdmissionToken: boolean;
}
/**
* Turn a bind setting into an address that is safe to combine with local credentials.
*
* Bun resolves a DNS bind name when the listener starts, but a later client lookup can receive
* a different answer. Local integrations therefore use only literal addresses; a DNS bind falls
* back to loopback and fails closed when the listener does not answer there. Operators who need
* local integrations on a DNS-bound listener can enable the dedicated loopback listener.
*
* `localhost` is deliberately NOT treated as a DNS bind here, even though it is a name. It is
* reserved to loopback by RFC 6761, so a second lookup cannot select a peer off this machine —
* the thing this function exists to prevent. Rewriting it to `127.0.0.1` would buy no safety and
* would change what every existing loopback install writes into its exported client
* configuration, which is a contract `tests/claude-integration/claude-cli.test.ts` pins.
* `isLoopbackHostname` is the existing encoding of "this name is loopback", so the two stay in
* agreement by construction rather than by a second list.
*/
export function localCredentialDestinationHostname(hostname: string | undefined): string {
const probed = probeHostname(hostname);
if (isLoopbackHostname(probed)) return probed;
const literal = probed.startsWith("[") && probed.endsWith("]")
? probed.slice(1, -1)
: probed;
return isIP(literal) !== 0 ? probed : "127.0.0.1";
}
/**
* The one answer for "where does a local client send inference, and does it need a key?".
*
* Kept in one place so the day the resolution changes a forgotten site cannot point a client
* config at a closed socket — which is precisely the defect this module exists to close.
*/
export function localInferenceDestination(
config: LocalInferenceConfig | undefined,
publicPort: number,
): LocalInferenceDestination {
const listenerPort = effectiveLoopbackListenerPort(config, publicPort);
if (listenerPort !== null) {
// Always bound to 127.0.0.1 and admits local callers with no credential, which is what
// lets an exported client configuration stay credential-free.
return { origin: `http://127.0.0.1:${listenerPort}`, port: listenerPort, requiresAdmissionToken: false };
}
const hostname = config?.hostname;
// A loopback bind keeps the byte-identical string every call site wrote before this module
// existed, including the `localhost`/`::1` spellings that `probeHostname` would preserve.
if (isLoopbackHostname(hostname)) {
return { origin: `http://127.0.0.1:${publicPort}`, port: publicPort, requiresAdmissionToken: false };
}
// `probeHostname` turns every all-zero spelling into 127.0.0.1 and brackets a bare IPv6
// literal; `shouldInjectApiAuthHeader` is the existing encoding of "this bind demands a
// data-plane credential", so the two stay in agreement by construction.
return {
origin: `http://${localCredentialDestinationHostname(hostname)}:${publicPort}`,
port: publicPort,
requiresAdmissionToken: shouldInjectApiAuthHeader(config),
};
}
/**
* Every port this proxy's data plane answers on at 127.0.0.1 — the set an inherited
* `http://127.0.0.1:<port>` base URL must hit to count as one of OURS.
*
* On a tailnet bind with no loopback listener the set is EMPTY, and that is the point: a
* leftover `http://127.0.0.1:10100` from a previous loopback-bound install is a dead socket
* there, so `ocx claude` must replace it rather than preserve it as its own destination.
*/
export function localLoopbackInferencePorts(
config: LocalInferenceConfig | undefined,
publicPort: number,
): number[] {
const ports: number[] = [];
// A wildcard bind owns loopback on the public port too, so a URL naming it is still ours.
if (isLoopbackHostname(config?.hostname) || isWildcardHostname(config?.hostname)) ports.push(publicPort);
const listenerPort = effectiveLoopbackListenerPort(config, publicPort);
if (listenerPort !== null && !ports.includes(listenerPort)) ports.push(listenerPort);
return ports;
}
/**
* The DATA-PLANE admission credential this host can present to its own public listener.
*
* Same ladder the Codex provider table and `ocx opencode` already use — environment token,
* hardened service token file, first configured `apiKeys` entry — and deliberately NOT the
* admin token, which must never leave the management surface. `undefined` means the caller has
* nothing to attach and has to degrade loudly.
*/
export function localAdmissionToken(
config: Pick<OcxConfig, "apiKeys"> | undefined,
env: NodeJS.ProcessEnv = process.env,
): string | undefined {
const envToken = env.OPENCODEX_API_AUTH_TOKEN?.trim();
if (envToken) return envToken;
const lookup = env.OCX_API_TOKEN_FILE?.trim()
? env
: { ...env, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
const fileToken = loadServiceTokenFromFile(lookup as Record<string, string | undefined>)?.trim();
// Shape-check the FILE candidate only. The env var and `apiKeys` are values an operator set
// deliberately and pass through verbatim; a path, by contrast, can be pointed at or replaced
// by something that is not a credential at all, and sending that as one leaks file contents
// into a request header. Configured keys are never checked, so no existing key can be broken.
if (fileToken && ADMISSION_TOKEN_SHAPE.test(fileToken)) return fileToken;
const configured = config?.apiKeys?.find(entry => entry.key.trim().length > 0)?.key.trim();
return configured || undefined;
}
/** An admission credential is an opaque printable token — never JSON, a path, or multi-line. */
const ADMISSION_TOKEN_SHAPE = /^[A-Za-z0-9._~+/=-]{8,4096}$/;
/**
* The origin a local CLI dials for `/api/*`.
*
* A hub's management ingress is loopback-only and exists precisely so the operator's own
* machine has a management address when the proxy listener is bound elsewhere. Everything else
* keeps dialing a literal public bind address it can actually reach. DNS bind names fail closed
* to loopback because resolving them again could select a different peer after startup.
*
* The caller still supplies the management credential. Never write that credential into an
* exported client configuration.
*/
export function localManagementOrigin(
config: LocalManagementConfig | undefined,
publicPort: number,
): string {
const ingress = config?.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
if (ingress?.enabled) return `http://127.0.0.1:${ingress.port}`;
return `http://${localCredentialDestinationHostname(config?.hostname)}:${publicPort}`;
}