@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,265 lines • 61.7 kB
text/typescript
import { providerRelativeSendPathConfigError } from "../config/provider-relative-send-path";
import { contextTierRecordConfigError, modelCapabilitiesConfigError } from "../config/provider-validation";
import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
import { initialModelSelection } from "../providers/initial-model-selection";
import { extractAccountId } from "../oauth/chatgpt";
import { formatErrorResponse } from "../bridge";
import {
codexAutoStartEnabled,
modelPreferHostedToolsConfigError,
providerModelCostsConfigError,
providerWebSearchBridgeConfigError,
requestPacingConfigError,
retryOn429PolicyConfigError,
retryOnResetPolicyConfigError,
sanitizeModelCostsForDisplay,
} from "../config";
import {
apiKeyTransportConfigError,
projectContextConfigError,
autoReviewModelOverridesConfigError,
autoReviewModelTargetConfigError,
booleanRecordConfigError,
providerReasoningPinsConfigError,
modelAdapterRecordConfigError,
nonBlankStringArrayConfigError,
positiveIntegerConfigError,
positiveIntegerRecordConfigError,
providerBaseUrlConfigError,
providerHeadersConfigError,
reasoningSummaryDeliveryRecordConfigError,
upstreamHttpVersionConfigError,
} from "../config/provider-validation";
import { providerDestinationConfigError } from "../lib/destination-policy";
import { providerEgressConfigError } from "../lib/provider-egress";
import { redactSecretString } from "../lib/redact";
import { DECLARABLE_HOSTED_TOOL_TYPES } from "../responses/hosted-tool-policy";
import { effectiveGoogleMode, getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport, registryEntryForProviderDestination } from "../providers/registry";
import { providerConfigSeed } from "../providers/derive";
import type { OcxConfig, OcxProviderConfig } from "../types";
import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
import { modelAutoCompactTokenLimitsConfigError } from "../providers/auto-compact-budget";
import { vercelGatewayRoutingConfigError } from "../providers/vercel-gateway-routing";
import { googleVertexLocationConfigError } from "../providers/google-vertex-location";
import { xaiResponsesOptInState } from "../providers/xai-responses-opt-in";
let _corsOrigin = "http://localhost:10100";
export function setCorsOrigin(port: number): void { _corsOrigin = `http://localhost:${port}`; }
/** The proxy's own listening port. No admission check uses it: both loopback predicates key on hostname alone. */
export function configuredPort(): string {
try { return new URL(_corsOrigin).port; } catch { return "10100"; }
}
export function parseHttpHost(value: string | null): { hostname: string; port: string } | null {
if (!value) return null;
try {
const parsed = new URL(`http://${value}`);
return { hostname: parsed.hostname.toLowerCase(), port: parsed.port };
} catch {
return null;
}
}
export function isLoopbackRequestHost(value: string | null): boolean {
const parsed = parseHttpHost(value);
if (!parsed) return true;
// Loopback is a trust boundary by hostname, not by port. `ssh -L 20100:localhost:10100`
// legitimately arrives as `Host: localhost:20100`, and refusing it took the whole /v1/*
// data plane down with it, not just CORS. The sibling isLoopbackOriginValue() dropped its
// own port check for the same reason in e4e06125b ("same-trust-boundary"). Port equality
// was never the rebinding defense: a rebinding browser connects to the real port and sends
// it verbatim, so the hostname check below is what rejected it then and now.
//
// Scope of that guarantee: it holds for Hosts `parseHttpHost` can parse. An unparseable
// Host still returns true above — pre-existing behavior, not browser-reachable (a browser
// composes Host from its own connection), and pinned by a characterization test in
// tests/server/server-loopback-host-gate.test.ts. Tightening it is separate work.
return isLoopbackHostname(parsed.hostname);
}
export function isLoopbackOriginValue(value: string): boolean {
try {
const parsed = new URL(value);
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
return isLoopbackHostname(parsed.hostname);
} catch {
return false;
}
}
export function isSameOriginAsRequest(req: Request, origin: string): boolean {
try {
return origin === new URL(req.url).origin;
} catch {
return false;
}
}
export function isAllowedRequestOrigin(req: Request, config: RequestPolicyView): boolean {
const origin = req.headers.get("Origin");
if (!isApiAuthRequired(config)) {
if (!isLoopbackRequestHost(req.headers.get("Host"))) return false;
return !origin || isLoopbackOriginValue(origin) || isExtraAllowedOrigin(origin, config);
}
return !origin || isLoopbackOriginValue(origin) || isSameOriginAsRequest(req, origin) || isExtraAllowedOrigin(origin, config);
}
function isExtraAllowedOrigin(origin: string, cfg: RequestPolicyView): boolean {
if (!cfg.corsAllowOrigins?.length) return false;
const parsedOrigin = comparableOrigin(origin);
return cfg.corsAllowOrigins.some(allowed => {
const parsedAllowed = comparableOrigin(allowed);
return parsedOrigin !== null && parsedAllowed !== null
? parsedAllowed === parsedOrigin
: allowed === origin;
});
}
function comparableOrigin(value: string): string | null {
try {
const parsed = new URL(value);
if (parsed.origin !== "null") return parsed.origin;
// WHATWG URL exposes authority-based custom schemes (for example browser
// extensions) as opaque `null` origins. Compare their scheme + authority so
// one allowlisted extension cannot admit every other opaque origin.
return parsed.host ? `${parsed.protocol}//${parsed.host}` : null;
} catch {
return null;
}
}
export function managementRequestOrigin(req: Request, config: OcxConfig): string | null {
const host = req.headers.get("Host");
const parsedHost = parseHttpHost(host);
if (!host || !parsedHost) return null;
if (isLoopbackHostname(parsedHost.hostname)) {
try {
const protocol = new URL(req.url).protocol;
if (protocol !== "http:" && protocol !== "https:") return null;
return new URL(`${protocol}//${host}`).origin;
} catch {
return null;
}
}
if (!isApiAuthRequired(config)) return null;
if (config.runtimeRole === "hub" && config.hub?.managementPublicOrigin) {
try {
const configured = new URL(config.hub.managementPublicOrigin);
if (
(configured.protocol === "http:" || configured.protocol === "https:")
&& !configured.username
&& !configured.password
&& configured.pathname === "/"
&& !configured.search
&& !configured.hash
) return configured.origin;
} catch { /* malformed direct fixture: fall through to observed origin */ }
}
try {
const protocol = new URL(req.url).protocol;
if (protocol !== "http:" && protocol !== "https:") return null;
return new URL(`${protocol}//${host}`).origin;
} catch {
return null;
}
}
export function isAllowedManagementOrigin(req: Request, config: OcxConfig): boolean {
const requestOrigin = managementRequestOrigin(req, config);
if (!requestOrigin) return false;
const origin = req.headers.get("Origin");
// Exact match against the process-derived origin, or an operator-listed corsAllowOrigins
// entry (covers TLS-terminator https://… when the process observes http://…).
return !origin || origin === requestOrigin || isExtraAllowedOrigin(origin, config);
}
export function browserSecurityHeaders(): Record<string, string> {
return {
"X-Frame-Options": "DENY",
"Content-Security-Policy": "frame-ancestors 'none'",
};
}
/**
* Baseline data-plane request headers. ChatGPT-Account-Id is required for browser/Electron
* ChatGPT & Codex App voice preflights (direct forward auth matches the bearer to this account
* id). The OpenAI-Alpha .. X-OAI-Attestation block covers GPT-Live voice protocol headers
* relayed by the /v1/live call-create path.
*/
const STATIC_ALLOWED_REQUEST_HEADERS =
"Content-Type, Authorization, X-OpenCodex-API-Key, X-Api-Key, Anthropic-Version, Anthropic-Beta, ChatGPT-Account-Id, OpenAI-Alpha, X-Session-Id, Session-Id, Thread-Id, Originator, X-OAI-Attestation";
/**
* A fixed allow-list cannot enumerate vendor telemetry headers: the OpenAI and Anthropic
* browser SDKs send `X-Stainless-*` describing runtime and retry state, and the browser blocks
* the real request when the preflight omits even one of them (#1773).
*
* Echo what an already-allowed origin asked for, and fall back to the static list otherwise.
* The echo is deliberately gated on the origin check that ran first: this widens which headers
* an admitted caller may send, never which origins are admitted, and it grants nothing to an
* origin that would have been rejected anyway. Authentication is unchanged — the preflight
* itself carries no credential and produces no auth or account-pool side effect.
*/
function allowedRequestHeaders(req?: Request): string {
const requested = req?.headers.get("Access-Control-Request-Headers")?.trim();
if (!requested) return STATIC_ALLOWED_REQUEST_HEADERS;
const seen = new Set(STATIC_ALLOWED_REQUEST_HEADERS.split(",").map(h => h.trim().toLowerCase()));
const extra: string[] = [];
for (const raw of requested.split(",")) {
const name = raw.trim();
// Header names are case-insensitive on the wire, so normalize before de-duplicating;
// echo the caller's spelling for the ones we add.
if (!name || seen.has(name.toLowerCase())) continue;
seen.add(name.toLowerCase());
extra.push(name);
}
return extra.length === 0 ? STATIC_ALLOWED_REQUEST_HEADERS : `${STATIC_ALLOWED_REQUEST_HEADERS}, ${extra.join(", ")}`;
}
export function corsHeaders(req?: Request, config?: RequestPolicyView): Record<string, string> {
const origin = req?.headers.get("Origin");
const originAllowed = Boolean(origin && req && config && isAllowedRequestOrigin(req, config));
const allowOrigin = originAllowed && origin ? origin : _corsOrigin;
return {
"Access-Control-Allow-Origin": allowOrigin,
"Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
"Access-Control-Allow-Headers": allowedRequestHeaders(originAllowed ? req : undefined),
// A response that varies by the request's headers must say so, or a shared cache can
// replay one client's allow-list to a client that asked for different headers.
"Vary": "Origin, Access-Control-Request-Headers",
...browserSecurityHeaders(),
};
}
export function managementCorsHeaders(req?: Request, config?: OcxConfig): Record<string, string> {
const headers = corsHeaders();
headers["Access-Control-Allow-Headers"] = `${STATIC_ALLOWED_REQUEST_HEADERS}, X-OpenCodex-GUI-Origin, X-OpenCodex-CSRF-Token`;
const origin = req?.headers.get("Origin");
if (origin && req && config && isAllowedManagementOrigin(req, config)) {
headers["Access-Control-Allow-Origin"] = origin;
}
return headers;
}
export function withCors(response: Response, req: Request, config: RequestPolicyView): Response {
const headers = new Headers(response.headers);
for (const [name, value] of Object.entries(corsHeaders(req, config))) {
headers.set(name, value);
}
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers,
});
}
export function withManagementCors(response: Response, req: Request, config: OcxConfig): Response {
const headers = new Headers(response.headers);
for (const [name, value] of Object.entries(managementCorsHeaders(req, config))) {
headers.set(name, value);
}
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers,
});
}
export function jsonResponse(data: unknown, status = 200, req?: Request, config?: RequestPolicyView): Response {
return new Response(JSON.stringify(data), {
status,
headers: { "Content-Type": "application/json", ...corsHeaders(req, config) },
});
}
// The parameter is vestigial — the token has always come from the environment — but callers
// pass a config, so keep accepting one. Typed as `unknown` rather than `OcxConfig` so a narrow
// policy view can reach it too (#1102); widening to OcxConfig here would force every caller in
// the admission path back to the full config.
export function configuredApiAuthToken(_config?: unknown): string | undefined {
const token = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
return token || undefined;
}
export function configuredAdminAuthToken(): string | undefined {
const token = process.env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim();
return token || undefined;
}
export function isLoopbackHostname(hostname: string | undefined): boolean {
// A fully-qualified "localhost." is the same host as "localhost": curl and some clients
// send the trailing dot verbatim, and refusing it 403s a legitimate loopback caller.
const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase().replace(/\.$/, "");
return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
}
export function isApiAuthRequired(config: Pick<OcxConfig, "hostname">): boolean {
return !isLoopbackHostname(config.hostname);
}
/**
* The slice of config that decides admission and CORS, and nothing else (#1102).
*
* The unauthenticated loopback listener shares this process with the public one: same routing,
* same account pool, same drain. The only thing it must see differently is its own bind
* address, because `isApiAuthRequired` reads `hostname` and the shared config says "0.0.0.0".
*
* Two ways to express that were rejected. Passing the whole config with `hostname` rewritten
* and holding it for the listener's lifetime would go stale the moment the management API
* changes a setting. Adding an `allowUnauthenticated` parameter to the resolvers would create a
* callable admission bypass that the PUBLIC listener could also reach — the switch would exist
* on the wrong side of the boundary.
*
* So this type is deliberately narrow: it cannot masquerade as a business config, and a policy
* view that leaks into a routing path fails to typecheck rather than silently taking effect.
*/
export interface LinkIngressPolicy {
allowedKeyIds: ReadonlySet<string>;
}
export type RequestPolicyView = Pick<OcxConfig, "hostname" | "corsAllowOrigins" | "apiKeys"> & {
linkIngress?: LinkIngressPolicy;
};
export type DataPlaneAdmissionOptions = {
linkIngress?: ReadonlySet<string>;
};
/** Derive the per-request policy view for a listener. Cheap enough to build per request. */
export function requestPolicyView(
config: OcxConfig,
bindHostname: string,
linkIngress?: LinkIngressPolicy,
): RequestPolicyView {
return {
hostname: bindHostname,
...(config.corsAllowOrigins ? { corsAllowOrigins: config.corsAllowOrigins } : {}),
...(config.apiKeys ? { apiKeys: config.apiKeys } : {}),
...(linkIngress ? { linkIngress } : {}),
};
}
export function assertServerAuthConfig(config: OcxConfig): void {
const hasConfiguredDataCredential = !!configuredApiAuthToken(config)
|| (config.apiKeys ?? []).some(entry => !!entry.key.trim());
if (isApiAuthRequired(config) && !hasConfiguredDataCredential) {
throw new Error(
"A data-plane credential (OPENCODEX_API_AUTH_TOKEN or config.apiKeys) is required when binding opencodex to a non-loopback hostname",
);
}
}
function secretEquals(actual: string, expected: string | undefined): boolean {
if (!expected) return false;
const enc = new TextEncoder();
const actualBytes = enc.encode(actual);
const expectedBytes = enc.encode(expected);
return expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes);
}
/**
* Which admission a data-plane request used.
*
* `configured` carries the matched key's id so a request can be attributed to
* the key that opened it. The other two exist so an unattributed request is a
* stated fact rather than a missing field: neither has a configured entry to
* point at, and a sentinel string in the id would collide with a hand-edited
* entry that happens to be named `loopback`.
*/
/**
* HOW an admission credential was presented.
*
* The credential IDENTITY (which key matched) and its PRESENTATION (which header carried it)
* are different facts, and #1686 needs both: a proxy secret arriving as a bearer on the
* Responses transport is admissible, but only if the upstream credential is then guaranteed to
* be substituted. Collapsing the two is what made that flow unexpressible.
*/
export type DataPlaneAdmissionSource = "loopback" | "dedicated" | "bearer" | "x-api-key";
/**
* Process-local, salted identity of the admission secret that was actually matched.
*
* Context-relay ownership is partitioned by this value, so two operators holding different
* keys cannot reach each other's sessions even when both resolve to the same upstream
* workspace. `source` is deliberately excluded: the same key arriving as a bearer or in the
* dedicated header is one principal. Rotating or replacing a secret mints a new principal and
* drops continuity, which is the safe direction — a reused key id or a replaced environment
* secret must not inherit the previous holder's sessions. Loopback admission carries no caller
* identity and mints nothing, so the relay refuses it rather than treating every local process
* as one user.
*/
const CONTEXT_PRINCIPAL_SALT = randomBytes(32);
function mintContextPrincipal(kind: string, keyId: string, credential: string): string {
return createHmac("sha256", CONTEXT_PRINCIPAL_SALT)
.update(kind).update("\0").update(keyId).update("\0").update(credential)
.digest("hex");
}
export type DataPlaneAdmission =
| { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
| { kind: "environment"; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
| { kind: "loopback"; source: "loopback" };
/**
* Which admission secret `token` is, or null when it is none of them.
*
* Identical comparisons in an identical order to the boolean form this replaces —
* `secretEquals` still length-guards before `timingSafeEqual`. The only
* difference is that the matched entry's id survives the loop instead of being
* discarded, which is what makes per-key attribution possible without touching
* the admission decision itself.
*/
export function resolveDataPlaneAdmissionSecret(
token: string,
config: Pick<OcxConfig, "apiKeys">,
source: DataPlaneAdmissionSource = "dedicated",
options: DataPlaneAdmissionOptions = {},
): DataPlaneAdmission | null {
const actual = token.trim();
if (!actual) return null;
if (!options.linkIngress && secretEquals(actual, configuredApiAuthToken(config))) {
return { kind: "environment", source, contextPrincipalId: mintContextPrincipal("environment", "", actual) };
}
for (const k of config.apiKeys ?? []) {
if (options.linkIngress && !options.linkIngress.has(k.id)) continue;
if (secretEquals(actual, k.key)) {
return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, actual) };
}
const pending = k.pendingRotation;
if (pending && Date.parse(pending.expiresAt) > Date.now() && secretEquals(actual, pending.key)) {
return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, pending.key) };
}
}
return null;
}
/** The principal an authenticated admission belongs to, or undefined for loopback. */
export function contextPrincipalIdOf(admission: DataPlaneAdmission | undefined): string | undefined {
return admission && "contextPrincipalId" in admission ? admission.contextPrincipalId : undefined;
}
/**
* The caller principal for a context-relay request, which is a stricter question than admission.
*
* The default bind is loopback, where admission deliberately never reads a token, so an admitted
* request carries no caller identity. History ownership needs one, so the relay asks separately:
* a caller that presents a real opencodex API key gets that key’s principal even on loopback,
* and a caller that presents none gets nothing and is refused. This adds identity where the caller
* volunteered it; it does not admit anyone who was not already admitted, and it does not change
* which credential goes upstream.
*/
export function resolveContextPrincipal(req: Request, config: OcxConfig, admission: DataPlaneAdmission | undefined): string | undefined {
const named = contextPrincipalIdOf(admission);
if (named) return named;
if (admission?.kind !== "loopback") return undefined;
const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
const apiKey = req.headers.get("x-api-key")?.trim();
for (const [token, source] of [[dedicated, "dedicated"], [bearer, "bearer"], [apiKey, "x-api-key"]] as const) {
if (!token) continue;
const resolved = resolveDataPlaneAdmissionSecret(token, config, source);
const principal = contextPrincipalIdOf(resolved ?? undefined);
if (principal) return principal;
}
return undefined;
}
/** Whether `token` is a data-plane admission secret. */
export function isDataPlaneAdmissionSecret(token: string, config: OcxConfig): boolean {
return resolveDataPlaneAdmissionSecret(token, config) !== null;
}
/**
* Split an admission into the fields a log row records.
*
* `apiKeyId` is set only for a configured key. The other two kinds have no
* configured entry to name, and folding them into the id as sentinel strings
* would collide with a hand-edited entry that happens to be called `loopback` —
* ids are only validated as non-empty strings.
*/
export function admissionFields(admission: DataPlaneAdmission): {
admissionKind: DataPlaneAdmission["kind"];
apiKeyId?: string;
} {
return admission.kind === "configured"
? { admissionKind: "configured", apiKeyId: admission.keyId }
: { admissionKind: admission.kind };
}
export type ApiAuthDisposition = "required" | "accepted" | "rejected";
export interface ApiAuthMatrixRow {
endpoint: string;
bearer: ApiAuthDisposition;
dedicated: ApiAuthDisposition;
xApiKey: ApiAuthDisposition;
}
/**
* Which headers each data-plane endpoint actually accepts, shipped to the GUI so
* it stops describing the rule from memory. The dashboard has been telling users
* that Chat Completions takes `Authorization: Bearer`, which this file has never
* allowed — that route uses the dedicated-header-only wrapper because
* `Authorization` there may belong to Codex Direct passthrough.
*
* It lives next to the wrappers it describes, and a test drives real requests
* against every cell rather than reading the table back to itself.
*/
export const AUTH_MATRIX: readonly ApiAuthMatrixRow[] = [
{ endpoint: "/v1/audio/transcriptions", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
{ endpoint: "/v1/live", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
{ endpoint: "/v1/realtime/calls", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
// #1686: a bearer that is one of OUR admission secrets is now accepted here. It is safe
// because materializeCodexUpstreamAuth substitutes the stored main credential rather than
// forwarding it; a bearer that is NOT our secret stays unadmitted and remains Codex Direct
// passthrough, so the two bearer domains still never mix. `x-api-key` is still rejected.
{ endpoint: "/v1/responses", bearer: "accepted", dedicated: "accepted", xApiKey: "rejected" },
{ endpoint: "/v1/chat/completions", bearer: "accepted", dedicated: "accepted", xApiKey: "rejected" },
{ endpoint: "/v1/messages", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
{ endpoint: "/v1/models", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
// #809: least-privilege catalog read for remote Codex clients. Same admission set as
// /v1/models and for the same reason — it forwards no caller credential upstream — so a
// remote client no longer needs an admin token just to read the model catalog.
{ endpoint: "/v1/catalog", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
// #4236: the hub-state read a connected client uses instead of reporting its own empty
// credential store. Same admission set and the same justification as the two rows above —
// it forwards no caller credential upstream and its body is booleans plus model ids — and it
// 404s on any host whose runtimeRole is not "hub", so no standalone install gains a surface.
{ endpoint: "/v1/hub-state", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
// Usage additionally requires a configured key identity; unscoped environment keys are refused.
{ endpoint: "/v1/usage", bearer: "rejected", dedicated: "accepted", xApiKey: "rejected" },
];
/** Whether `token` is the environment-provided management secret. */
export function isManagementAdmissionSecret(token: string): boolean {
const actual = token.trim();
return !!actual && secretEquals(actual, configuredAdminAuthToken());
}
/** Whether `token` is one of the proxy's own admission secrets and must never reach an upstream. */
export function isProxyAdmissionSecret(token: string, config: OcxConfig): boolean {
const actual = token.trim();
if (!actual) return false;
if (/^ocx_(?:data|admin|session)_/.test(actual) || /^ocx_[0-9a-f]{40}$/.test(actual)) return true;
return isDataPlaneAdmissionSecret(actual, config) || isManagementAdmissionSecret(actual);
}
export class ForwardAdmissionCredentialError extends Error {
constructor() {
super("OpenCodex admission credentials cannot be forwarded upstream");
this.name = "ForwardAdmissionCredentialError";
}
}
export function validateForwardAdmissionCredential(headers: Headers, config: OcxConfig): void {
const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
if (bearer && isProxyAdmissionSecret(bearer, config)) throw new ForwardAdmissionCredentialError();
}
/** Whether Authorization carries a caller-owned native Codex credential safe to forward. */
export function hasForwardableCodexBearer(headers: Headers, config: OcxConfig): boolean {
const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
const accountId = headers.get("chatgpt-account-id")?.trim()
|| (bearer ? extractAccountId(undefined, bearer) : undefined);
return !!bearer && !!accountId && !isProxyAdmissionSecret(bearer, config);
}
/**
* Resolving form of `hasValidApiAuth`: identical header precedence, identical
* decision, but it names the admission instead of collapsing it to a boolean.
*/
export function resolveApiAuth(req: Request, config: RequestPolicyView): DataPlaneAdmission | null {
// A loopback bind never reads a token at all, so there is no key to name.
if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
// Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
const apiKey = req.headers.get("x-api-key")?.trim();
if (apiKey) return resolveDataPlaneAdmissionSecret(apiKey, config, "x-api-key", { linkIngress: config.linkIngress?.allowedKeyIds });
return null;
}
export function hasValidApiAuth(req: Request, config: RequestPolicyView): boolean {
return resolveApiAuth(req, config) !== null;
}
export function requireApiAuth(req: Request, config: RequestPolicyView, _kind: "data-plane"): Response | null {
if (hasValidApiAuth(req, config)) return null;
return formatErrorResponse(401, "authentication_error", "opencodex API key required");
}
/**
* Admission for OpenAI Responses transports whose Authorization header belongs to
* Codex Direct. Remote binds must use the dedicated proxy header so the two bearer
* domains can never be confused.
*/
export function resolveResponsesApiAuth(req: Request, config: RequestPolicyView): DataPlaneAdmission | null {
if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
// The dedicated header still WINS, because it is unambiguous.
const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
// #1686: a bearer may also be one of OUR admission secrets. Rejecting it outright meant a
// Codex client configured with `env_key` could not reach Direct at all. Admitting it is only
// safe because the upstream credential is then SUBSTITUTED rather than forwarded -- see
// materializeCodexUpstreamAuth. A bearer that is NOT our secret stays unadmitted here and
// remains Codex Direct passthrough, so the two bearer domains still never mix.
const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
// `x-api-key` is deliberately NOT accepted on this transport.
return null;
}
export function requireResponsesApiAuth(req: Request, config: RequestPolicyView): Response | null {
if (resolveResponsesApiAuth(req, config)) return null;
return formatErrorResponse(401, "authentication_error", "opencodex API key required");
}
const FORBIDDEN_PROVIDER_RUNTIME_FIELDS = [
"virtualModels", "codexAuthContext", "selectedForwardHeaders",
"sidecarOutcomeRecorder", "_codexAccountOverride", "_codexAccountRequired",
"_apiKeyAttempt",
] as const;
function sameCanonicalProviderSeed(actual: Record<string, unknown>, expected: OcxProviderConfig): boolean {
const actualKeys = Object.keys(actual).sort();
const expectedKeys = Object.keys(expected).sort();
if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, i) => key !== expectedKeys[i])) return false;
return actualKeys.every(key => JSON.stringify(actual[key]) === JSON.stringify((expected as unknown as Record<string, unknown>)[key]));
}
/**
* Operator-overlay tolerant variant of the canonical seed check: every key the registry
* seed defines must still match the submitted provider verbatim, but keys the seed never
* defines are ignored instead of failing the comparison. Field-masked writes (PATCH,
* the provider editor, reload) merge onto the persisted row, so the submitted candidate
* legitimately carries stored operator overlays like `selectedModels` or `disabled`.
* Those fields are validated by their own write boundaries and cannot widen what the
* forward proxy claims. Full-object writes (POST) keep the strict exact-key comparison
* so a forged overlay cannot ride in on a canonical transport seed.
*/
function matchesCanonicalProviderSeed(actual: Record<string, unknown>, expected: OcxProviderConfig): boolean {
return Object.keys(expected).every(
key => Object.hasOwn(actual, key)
&& JSON.stringify(actual[key]) === JSON.stringify((expected as unknown as Record<string, unknown>)[key]),
);
}
function positiveWindowValue(value: unknown): boolean {
return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
}
/**
* Shape-check the two context overlays before the canonical seed comparison drops them.
*
* `null` means "clear this" and is normalized by the PATCH field mask, but this validator
* also runs for POST and reload, where a whole provider object lands on disk verbatim. A
* `null` surviving there would be a value no reader expects, so full objects must carry a
* real number or omit the field.
*/
function nativeContextOverlayError(raw: Record<string, unknown>): string | null {
if (Object.hasOwn(raw, "contextWindow") && !positiveWindowValue(raw.contextWindow)) {
return "provider openai contextWindow must be a positive safe integer";
}
if (Object.hasOwn(raw, "modelContextWindows")) {
const windows = raw.modelContextWindows;
if (typeof windows !== "object" || windows === null || Array.isArray(windows)) {
return "provider openai modelContextWindows must be a plain object";
}
for (const [model, value] of Object.entries(windows as Record<string, unknown>)) {
if (model.trim() === "") return "provider openai modelContextWindows keys must be nonblank model ids";
if (!positiveWindowValue(value)) {
return "provider openai modelContextWindows values must be positive safe integers";
}
}
}
return null;
}
/**
* Validate a provider object arriving at the management write boundary. Returns an error
* string, or null when the provider may be persisted. Caller-controlled names/fields are
* redacted and JSON-escaped so secrets never reach the response.
*/
export function providerManagementConfigError(
name: unknown,
provider: unknown,
options?: { allowOperatorOverlays?: boolean },
): string | null {
if (typeof name !== "string" || !provider || typeof provider !== "object" || Array.isArray(provider)) {
return "provider must be a plain object";
}
const raw = provider as Record<string, unknown>;
const contextTiersError = contextTierRecordConfigError(raw.modelContextTiers);
if (contextTiersError) return contextTiersError;
const capabilitiesError = modelCapabilitiesConfigError(raw.modelCapabilities);
if (capabilitiesError) return capabilitiesError;
const pinsError = providerReasoningPinsConfigError(raw);
if (pinsError) return pinsError;
if (name === "openai" && (Object.hasOwn(raw, "autoReviewModel") || Object.hasOwn(raw, "autoReviewModelOverrides"))) {
return "provider openai must not include autoReviewModel or autoReviewModelOverrides";
}
// Canonical OpenAI is the ChatGPT forward seed. allowPrivateNetwork is the explicit
// opt-in that skips destination DNS classification (loopback, RFC1918, metadata).
// Overlay-tolerant comparison would otherwise treat it as an extra key and persist it.
if (name === "openai" && Object.hasOwn(raw, "allowPrivateNetwork")) {
return "provider openai must not include allowPrivateNetwork";
}
// The same reasoning applies to `headers`, and it is not hypothetical. Canonical OpenAI
// has no registry `staticHeaders`, so any header block on this row is operator-authored,
// and the forward adapter copies it onto the ChatGPT request BEFORE the incoming forward
// headers — a persisted value therefore wins whenever the caller omits that header. The
// exact-key comparison rejected it as an extra key; overlay tolerance would silently admit
// it on every merge-based write path while POST still refused it.
if (name === "openai" && Object.hasOwn(raw, "headers")) {
return "provider openai must not include headers";
}
const autoReviewTargetError = autoReviewModelTargetConfigError(raw.autoReviewModel, "autoReviewModel", true);
if (autoReviewTargetError) return autoReviewTargetError;
const autoReviewMapError = autoReviewModelOverridesConfigError(raw.autoReviewModelOverrides, "autoReviewModelOverrides", true);
if (autoReviewMapError) return autoReviewMapError;
for (const field of FORBIDDEN_PROVIDER_RUNTIME_FIELDS) {
if (Object.hasOwn(raw, field)) return `provider ${name} must not include runtime field "${field}"`;
}
if (name === "chatgpt") return "provider chatgpt is reserved for internal credential compatibility";
if (name === "openai-multi") return "provider openai-multi is reserved for legacy config migration";
if (name === "openai") {
const entry = getProviderRegistryEntry(name);
const seed = entry ? providerConfigSeed(entry) : undefined;
if (!Object.hasOwn(raw, "codexAccountMode") || (raw.codexAccountMode !== "pool" && raw.codexAccountMode !== "direct")) {
return "provider openai codexAccountMode must be pool or direct";
}
if (seed) seed.codexAccountMode = raw.codexAccountMode;
const canonicalCandidate = { ...raw };
// Validated operator overlays do not change the canonical auth/transport seed.
delete canonicalCandidate.pinnedReasoningEffort;
delete canonicalCandidate.modelPinnedReasoningEfforts;
delete canonicalCandidate.responsesSnapshotRepair;
// modelCosts is a user-owned display overlay, not part of the canonical
// forward seed; it is validated separately below (providerModelCostsConfigError).
delete canonicalCandidate.modelCosts;
// requestPacing is a user-owned transport overlay, not part of the canonical seed.
delete canonicalCandidate.requestPacing;
// retryOnReset is the same kind of overlay: it tunes how this provider's own Responses
// sends recover, not what the canonical forward seed is. Validated below
// (retryOnResetPolicyConfigError).
delete canonicalCandidate.retryOnReset;
// Context windows are the same kind of user-owned overlay as requestPacing: the operator
// narrowing what their own native rows advertise. They can only ever LOWER the measured
// window (see nativeOpenAiContextWindow), so admitting them cannot widen what the proxy
// claims. Validated first — this function also guards POST/reload, where nothing
// normalizes the shape afterwards, so a bad value would reach disk.
const contextOverlayError = nativeContextOverlayError(raw);
if (contextOverlayError) return contextOverlayError;
delete canonicalCandidate.contextWindow;
delete canonicalCandidate.modelContextWindows;
// User-owned soft compaction policy; it does not alter the canonical transport seed.
delete canonicalCandidate.modelAutoCompactTokenLimits;
// Same category: annotating empty tool outputs is a user-owned request-shaping preference,
// not part of the canonical transport seed. Without this the field is accepted by
// validation and then rejected by the seed comparison, so canonical OpenAI could never
// set OR clear it — the value was admitted and then refused in the same request.
delete canonicalCandidate.annotateEmptyToolOutputs;
// Canonical ChatGPT keeps WebSocket as the default, but an operator may
// select the existing HTTP/SSE path without changing its auth or endpoint.
if (raw.upstreamWebsocket !== undefined) {
if (raw.upstreamWebsocket !== false) return "provider openai upstreamWebsocket must be false or omitted";
delete canonicalCandidate.upstreamWebsocket;
}
const canonical = seed && (options?.allowOperatorOverlays
? matchesCanonicalProviderSeed(canonicalCandidate, seed)
: sameCanonicalProviderSeed(canonicalCandidate, seed));
if (!canonical) {
return `provider ${name} must equal the canonical built-in provider seed`;
}
} else if (Object.hasOwn(raw, "codexAccountMode")) {
return `provider ${name} must not include codexAccountMode`;
}
const typed = provider as unknown as OcxProviderConfig;
const baseUrlError = providerBaseUrlConfigError(typed.baseUrl);
if (baseUrlError) return `provider ${name} ${baseUrlError}`;
if (effectiveGoogleMode(name, typed) === "vertex" && typed.location !== undefined) {
const locationError = googleVertexLocationConfigError(typed.location);
if (locationError) return `provider ${name} ${locationError}`;
}
const destinationError = providerDestinationConfigError(name, typed);
if (destinationError) return `provider ${name} ${destinationError}`;
for (const field of ["responsesPath", "chatCompletionsPath"] as const) {
const sendPathError = providerRelativeSendPathConfigError(field, raw[field]);
if (sendPathError) return `provider ${JSON.stringify(redactSecretString(name))} ${sendPathError}`;
}
const headersError = providerHeadersConfigError(typed.headers);
if (headersError) return `provider ${name} ${headersError}`;
const retryOn429Error = retryOn429PolicyConfigError(raw.retryOn429);
if (retryOn429Error) {
// The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
// it before it reaches the management API response.
return `provider ${JSON.stringify(redactSecretString(name))} ${retryOn429Error}`;
}
const retryOnResetError = retryOnResetPolicyConfigError(raw.retryOnReset);
if (retryOnResetError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${retryOnResetError}`;
}
const requestPacingError = requestPacingConfigError(raw.requestPacing);
if (requestPacingError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${requestPacingError}`;
}
const webSearchBridgeError = providerWebSearchBridgeConfigError(raw.webSearchBridge, name, typed);
if (webSearchBridgeError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${webSearchBridgeError}`;
}
const upstreamHttpVersionError = upstreamHttpVersionConfigError(raw.upstreamHttpVersion);
if (upstreamHttpVersionError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${upstreamHttpVersionError}`;
}
// Per-provider egress shares one definition with the transports and the config loader, so a
// value the dashboard accepts is one a request can actually leave by. The message never
// echoes the value: a proxy URL routinely embeds `user:password@`.
const egressError = providerEgressConfigError(typed);
if (egressError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${egressError}`;
}
const modelCostsError = providerModelCostsConfigError(raw.modelCosts);
if (modelCostsError) {
// The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
// it before it reaches the management API response (same rule as retryOn429 above).
return `provider ${JSON.stringify(redactSecretString(name))} ${modelCostsError}`;
}
const apiKeyTransportError = apiKeyTransportConfigError(typed);
if (apiKeyTransportError) return `provider ${name} ${apiKeyTransportError}`;
const projectContextError = projectContextConfigError(typed);
if (projectContextError) return `provider ${JSON.stringify(redactSecretString(name))} ${projectContextError}`;
const maxInputError = positiveIntegerRecordConfigError(raw.modelMaxInputTokens, "modelMaxInputTokens");
if (maxInputError) return `provider ${name} ${maxInputError}`;
const autoCompactError = modelAutoCompactTokenLimitsConfigError(
raw.modelAutoCompactTokenLimits,
{ requireNativeIds: name === "openai" },
);
if (autoCompactError) {
return `provider ${JSON.stringify(redactSecretString(name))} ${autoCompactError}`;
}
const reasoningSummariesError = booleanRecordConfigError(raw.modelSupportsReasoningSummaries, "modelSupportsReasoningSummaries");
if (reasoningSummariesError) return `provider ${name} ${reasoningSummariesError}`;
const suppressSyntheticMaxError = booleanRecordConfigError(raw.modelSuppressSyntheticMax, "modelSuppressSyntheticMax");
if (suppressSyntheticMaxError) return `provider ${name} ${suppressSyntheticMaxError}`;
const verbositySupportError = booleanRecordConfigError(raw.modelSupportsVerbosity, "modelSupportsVerbosity");
if (verbositySupportError) return `provider ${name} ${verbositySupportError}`;
const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
raw.modelReasoningSummaryDelivery,
raw.modelSupportsReasoningSummaries,
);
if (reasoningSummaryDeliveryError) return `provider ${name} ${reasoningSummaryDeliveryError}`;
const modelAdaptersError = modelAdapterRecordConfigError(raw.modelAdapters, "modelAdapters", name, typed);
if (modelAdaptersError) return `provider ${name} ${modelAdaptersError}`;
const preferHostedToolsError = modelPreferHostedToolsConfigError(
raw.modelPreferHostedTools,
"modelPreferHostedTools",
name,
typed,
);
if (preferHostedToolsError) return `provider ${name} ${preferHostedToolsError}`;
if (raw.responsesSnapshotRepair !== undefined && typeof raw.responsesSnapshotRepair !== "boolean") {
return `provider ${name} responsesSnapshotRepair must be a boolean`;
}
if (raw.xaiResponsesXSearch !== undefined && typeof raw.xaiResponsesXSearch !== "boolean") {
return `provider ${name} xaiResponsesXSearch must be a boolean`;
}
const defaultMaxOutputError = positiveIntegerConfigError(raw.defaultMaxOutputTokens, "defaultMaxOutputTokens");
if (defaultMaxOutputError) return `provider ${name} ${defaultMaxOutputError}`;
const maxOutputError = positiveIntegerRecordConfigError(raw.modelMaxOutputTokens, "modelMaxOutputTokens");
if (maxOutputError) return `provider ${name} ${maxOutputError}`;
const structuredOutputOptOutError = nonBlankStringArrayConfigError(
raw.noStructuredOutputModels,
"noStructuredOutputModels",
);
if (structuredOutputOptOutError) return `provider ${name} ${structuredOutputOptOutError}`;
const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
raw.noJsonSchemaModels,
"noJsonSchemaModels",
);
if (jsonSchemaOptOutError) return `provider ${name} ${jsonSchemaOptOutError}`;
const retainModelsError = nonBlankStringArrayConfigError(raw.retainModels, "retainModels");
if (retainModelsError) return `provider ${name} ${retainModelsError}`;
const toolReasoningOptOutError = nonBlankStringArrayConfigError(
raw.omitReasoningEffortWithToolsModels,
"omitReasoningEffortWithToolsModels",
);
if (toolReasoningOptOutError) return `provider ${name} ${toolReasoningOptOutError}`;
const unsupportedHostedToolsError = nonBlankStringArrayConfigError(
raw.unsupportedHostedTools,
"unsupportedHostedTools",
);
if (unsupportedHostedToolsError) return `provider ${name} ${unsupportedHostedToolsError}`;
if (Array.isArray(raw.unsupportedHostedTools)) {
// Closed vocabulary, same reason as the config schema: an unrecognized name would be
// stored and then strip nothing, so the operator would keep getting the upstream 400
// this field exists to prevent.
const unknownTool = (raw.unsupportedHostedTools as unknown[])
.find(tool => typeof tool === "string" && !DECLARABLE_HOSTED_TOOL_TYPES.has(tool.trim()));
if (unknownTool !== undefined) {
return `provider ${name} unsupportedHostedTools must name only hosted tool types: `
+ `${[...DECLARABLE_HOSTED_TOOL_TYPES].join(", ")}`;
}
}
const openRouterError = openRouterRoutingConfigError(typed);
if (openRouterError) return `provider ${name} ${openRouterError}`;
const vercelError = vercelGatewayRoutingConfigError(typed);
if (vercelError) return `provider ${name} ${vercelError}`;
if (typed.authMode === "local") {
// "local" bypasses key-requirement enforcement (api-keys/key-failover treat non-oauth/
// forward as key auth; openai-chat skips credential checks for local). Only providers
// whose registry entry is genuinely local (Ollama/vLLM/LM Studio) may claim it.
const entry = getProviderRegistryEntry(name);
if (entry && entry.authKind !== "local") {
return `provider ${name} cannot use authMode "local" — its registry entry requires ${entry.authKind} auth`;
}
}
if (typed.authMode === "forward") {
const normalizedName = name.trim().toLowerCase();
const base = typed.baseUrl.replace(/\/+$/, "");
const isBuiltInChatGptForward = normalizedName === "openai"
&& typed.adapter === "openai-responses"
&& base === "https://chatgpt.com/backend-api/codex";
if (isBuiltInChatGptForward) return null;
return `provider ${name} uses reserved authMode "forward"; configure ChatGPT passthrough via the built-in provider`;
}
return null;
}
export function publicProviderBaseUrl(baseUrl: string): string {
try {
const parsed = new URL(baseUrl.trim());
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "(invalid URL)";
parsed.username = "";
parsed.password = "";
parsed.search = "";
parsed.hash = "";
return parsed.toString().replace(/\/$/, baseUrl.endsWith("/") ? "/" : "");
} catch {
return "(invalid URL)";
}
}
export function copyIfDefined<K extends keyof OcxProviderConfig>(
out: Record<string, unknown>,
provider: OcxProviderConfig,
key: K,
): void {
const value = provider[key];
if (value !== undefined) out[key as string] = value as unknown;
}
/**
* Exhaustive provider-field policy shared by dashboard redaction and editor
* admission. `satisfies Record<keyof OcxProviderConfig, ...>` makes a newly added
* provider field fail typecheck until it is deliberately classified.
*
* `editor` fields are user-authored, `redacted` fields may contain credentials,
* and `runtime` fields are observations/limits that must never become editor write
* authority. MCP and desktop executor blocks are redacted as a whole because both
* contain arbitrary environment variables and/or headers.
*/
type ProviderConfigFieldPolicy = "editor" | "redacted" | "runtime";
const PROVIDER_CONFIG_FIELD_POLICY = {
alias: "editor",
modelAliases: "editor",
modelDisplayNames: "editor",
defaultAliases: "editor",
adapter: "editor",
codexToolMode: "editor",
projectContext: "editor",
requestPacing: "editor",
mcpMaxTools: "editor",
mcpMaxSchemaBytes: "editor",
mcpMaxResultBytes: "editor",
modelAdapters: "editor",
fastWire: "editor",
responseTierAuthoritative: "editor",
fastEnabled: "editor",
baseUrl: "editor",
responsesPath: "editor",
chatCompletionsPath: "editor",
commandCodeVersion: "editor",
statelessResponses: "editor",
requiresAdjacentResponsesToolResults: "editor",
requiresPairedResponsesToolResults: "editor",
annotateEmptyToolOutputs: "editor",
supportsServiceTier: "editor",
modelSupportsServiceTier: "editor",
preserveResponsesReasoningContent: "editor",
dropResponsesReasoningItems: "editor",
modelReasoningEffortsAuthoritative: "editor",
decodesNativeCompactionBlobs: "editor",
allowEncryptedV2AgentTasks: "editor",
allowPrivateNetwork: "editor",
// A proxy URL routinely embeds `user:password@`, so it never reaches the dashboard DTO and
// the editor may not write it. `ocx config set` and the config file remain the way to set
// it, which is the same boundary `apiKey` sits behind and for the same reason.
proxy: "redacted",
// A bypass list names destinations, carries no credential, and is only meaningful next to a
// route the operator can already see.
noProxy: "editor",
upstreamHttpVersion: "editor",
upstreamWebsocket: "editor",
directGeminiWireRenames: "editor",
googleToolSchemaPolicy: "editor",
disabled: "editor",
codexAccountMode: "editor",
apiKey: "redacted",
apiKeyTransport: "editor",
apiKeyPool: "redacted",
// Ordering preference only; it names no key material, so an editor may read and set it.
apiKeyPoolStrategy: "editor",
apiKeySelectionRevision: "runtime",
_apiKeyAttempt: "runtime",
defaultModel: "editor",
models: "editor",
liveModels: "editor",
selectedModels: "editor",
initialModelSelection: "runtime",
retainModels: "editor",
newModelPolicy: "editor",
modelPreset: "editor",
contextWindow: "editor",
modelContextWindows: "editor",
modelContextTiers: "editor",
modelInputModalities: "editor",
modelCapabilities: "editor",
modelMaxInputTokens: "runtime",
modelAutoCompactTokenLimits: "editor",
defaultMaxOutputTokens: "editor",
modelMaxOutputTokens: "editor",
modelCosts: "editor",
headers: "redacted",
openRouterRouting: "editor",
modelOpenRouterRouting: "editor",
vercelGatewayRouting: "editor",
modelVercelGatewayRouting: "editor",
authMode: "editor",
oauthAccountFailover: "editor",
keyOptional: "editor",
freeTier: "editor",
note: "editor",
modelSuffixBracketStrip: "editor",
refreshPolicy: "editor",
reasoningEfforts: "editor",
modelReasoningEfforts: "editor",
modelSuppressSyntheticMax: "editor",
modelDefaultReasoningEfforts: "editor",
pinnedReasoningEffort: "editor",
modelPinnedReasoningEfforts: "editor",
autoReviewModel: "editor",
autoReviewModelOverrides: "editor",
modelSupportsReasoningSummaries: "editor",
modelSupportsVerbosity: "editor",
supportsVerbosity: "editor",
modelReasoningSummaryDelivery: "editor",
modelPreferHostedTools: "editor",
supportsOpenAiWebSearchToolFields: "editor",
xaiResponsesXSearch: "editor",
xaiResponsesDefaultVersion: "runtime",
zaiResponsesDefaultVersion: "runtime",
supportsResponsesCustomTools: "editor",
unsupportedHostedTools: "editor",
responsesSnapshotRepair: "editor",
webSearchBridge: "editor",
reasoningEffortMap: "editor",
modelReasoningEffortMap: "editor",
reasoningWireFormat: "editor",
noReasoningModels: "editor",
noTemperatureModels: "editor",
noTopPModels: "editor",
noStopModels: "editor",
noPenaltyModels: "editor",
noStructuredOutputModels: "editor",
noJsonSchemaModels: "editor",
omitReasoningEffortWithToolsModels: "editor",
parallelToolCalls: "editor",
pinParallelToolCallsFalse: "editor",
terminalContinuationGuard: "editor",
openaiChatEofTolerance: "editor",
foldDeveloperRoleToSystem: "editor",
promptCacheKey: "editor",
chatServiceTier: "editor",
responsesItemIdRepair: "editor",
autoToolChoiceOnlyModels: "editor",
preserveReasoningContentModels: "editor",
requiresReasoningPlaceholderModels: "editor",
showThinkingSummary: "editor",
hideRawReasoning: "editor",
retryOn429: "editor",
transientRetryOn5xx: "editor",
retryOnReset: "editor",
reasoningSplitModels: "editor",
inlineThinkTagModels: "editor",
reasoningDetailsModels: "editor",
thinkingToggleModels: "editor",
thinkingBudgetModels: "editor",
escapeBuiltinToolNames: "editor",
anthropicEofTolerance: "editor",
noVisionModels: "editor",
googleMode: "editor",
project: "editor",
location: "editor",
mcpServers: "redacted",
desktopExecutor: "redacted",
unsafeAllowNativeLocalExec: "editor",
nativeLocalExec: "editor",
} as const satisfies Record<keyof OcxProviderConfig, ProviderConfigFieldPolicy>;
type ProviderFieldWithPolicy<Policy extends ProviderConfigFieldPolicy> = {
[Field in keyof typeof PROVIDER_CONFIG_FIELD_POLICY]:
typeof PROVIDER_CONFIG_FIELD_POLICY[Field] extends Policy ? Field : never;
}[keyof typeof PROVIDER_CONFIG_FIELD_POLICY];
type RedactedProviderField = ProviderFieldWithPolicy<"redacted">;
type RuntimeProviderField = ProviderFieldWithPolicy<"runtime">;
export const REDACTED_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
.filter(([, policy]) => policy === "redacted")
.map(([field]) => field as RedactedProviderField));
const RUNTIME_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
.filter(([, policy]) => policy === "runtime")
.map(([field]) => field as RuntimeProviderField));
const PROVIDER_EDITOR_DERIVED_FIELDS = [
...RUNTIME_PROVIDER_FIELDS,
...FORBIDDEN_PROVIDER_RUNTIME_FIELDS,
"fetch",
"hasApiKey",
"hasHeaders",
"xaiResponsesOptInState",
] as const;
export const PROVIDER_EDITOR_DENIED_FIELDS = [
...REDACTED_PROVIDER_FIELDS,
...PROVIDER_EDITOR_DERIVED_FIELDS,
] as const;
export type ProviderEditorProviderDTO = Omit<OcxProviderConfig, RedactedProviderField | RuntimeProviderField>
& Record<string, unknown>;
export interface ProviderEditorConfigDTO {
defaultProvider: string;
providers: Record<string, ProviderEditorProviderDTO>;
}
export type ProviderEditorConfigParseResult =
| { ok: true; value: ProviderEditorConfigDTO }
| { ok: false; error: string; code: "invalid_provider_editor_body" | "invalid_provider_editor_field" };
const PROVIDER_EDITOR_DENIED_FIELD_SET = new Set<string>(PROVIDER_EDITOR_DENIED_FIELDS);
const PROVIDER_CONFIG_FIELD_SET = new Set<string>(Object.keys(PROVIDER_CONFIG_FIELD_POLICY));
function isPlainDataRecord(value: unknown): value is Record<string, unknown> {
if (!value || typeof value !== "object" || Array.isArray(value)) return false;
const prototype = Object.getPrototypeOf(value);
return prototype === Object.prototype || prototype === null;
}
/**
* Project one provider through the same redaction path used by both the public
* config DTO and the raw editor. Persisted unknown fields remain on disk but are
* not exposed until OcxProviderConfig classifies them as editor-safe.
*/
function providerEditorProviderDTO(name: string, provider: OcxProviderConfig): ProviderEditorProviderDTO {
const dto = Object.fromEntries(Object.entries(provider)
.filter(([field]) => PROVIDER_CONFIG_FIELD_SET.has(field) && !PROVIDER_EDITOR_DENIED_FIELD_SET.has(field))
.map(([field, value]) => [field, structuredClone(value)])) as Record<string, unknown>;
dto.baseUrl = publicProviderBaseUrl(provider.baseUrl);
const modelCosts = sanitizeModelCostsForDisplay(provider.modelCosts);
if (modelCosts) dto.modelCosts = modelCosts;
else delete dto.modelCosts;
const registryNote = (providerMatchesRegistryTransport(name, provider)
? getProviderRegistryEntry(name)
: registryEntryForProviderDestination(provider))?.note;
if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
const codexAccountMode = providerCodexAccountMode(name, provider);
if (codexAccountMode) dto.codexAccountMode = codexAccountMode;
return dto as ProviderEditorProviderDTO;
}
/** The complete non-secret provider shape the raw GUI editor may round-trip. */
export function providerEditorConfigDTO(config: OcxConfig): ProviderEditorConfigDTO {
const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
for (const [name, provider] of Object.entries(config.providers)) {
providers[name] = providerEditorProviderDTO(name, provider);
}
return { defaultProvider: config.defaultProvider, providers };
}
/** Parse an editor snapshot; unknown, redacted, and derived fields fail closed. */
export function parseProviderEditorConfigDTO(value: unknown): ProviderEditorConfigParseResult {
if (!isPlainDataRecord(value)) {
return { ok: false, error: "provider editor config must be a plain object", code: "invalid_provider_editor_body" };
}
const rootKeys = Object.keys(value);
if (rootKeys.length !== 2 || !Object.hasOwn(value, "defaultProvider") || !Object.hasOwn(value, "providers")) {
return { ok: false, error: "provider editor config must contain only defaultProvider and providers", code: "invalid_provider_editor_body" };
}
if (typeof value.defaultProvider !== "string" || value.defaultProvider.trim() === "") {
return { ok: false, error: "defaultProvider must be a non-empty string", code: "invalid_provider_editor_body" };
}
if (!isPlainDataRecord(value.providers)) {
return { ok: false, error: "providers must be a plain object", code: "invalid_provider_editor_body" };
}
const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
for (const [name, provider] of Object.entries(value.providers)) {
if (!isPlainDataRecord(provider)) {
return { ok: false, error: `provider ${JSON.stringify(redactSecretString(name))} must be a plain object`, code: "invalid_provider_editor_body" };
}
const deniedField = Object.keys(provider).find(field =>
!PROVIDER_CONFIG_FIELD_SET.has(field) || PROVIDER_EDITOR_DENIED_FIELD_SET.has(field));
if (deniedField) {
return {
ok: false,
error: `provider ${JSON.stringify(redactSecretString(name))} contains non-editable field ${JSON.stringify(redactSecretString(deniedField))}`,
code: "invalid_provider_editor_field",
};
}
providers[name] = structuredClone(provider) as ProviderEditorProviderDTO;
}
return {
ok: true,
value: { defaultProvider: value.defaultProvider, providers },
};
}
/** Public dashboard DTO for config.json: provider entries with secrets stripped and documented fields exposed (including `modelCosts`). */
export function safeConfigDTO(config: OcxConfig): unknown {
const editor = providerEditorConfigDTO(config);
const providers: Record<string, Record<string, unknown>> = {};
for (const [name, provider] of Object.entries(config.providers)) {
const dto: Record<string, unknown> = {
...editor.providers[name],
hasApiKey: !!provider.apiKey,
hasHeaders: !!provider.headers && Object.keys(provider.headers).length > 0,
};
if (name === "xai") {
dto.xaiResponsesOptInState = xaiResponsesOptInState(provider);
}
const selection = initialModelSelection(provider);
if (selection) dto.initialModelSelection = selection;
providers[name] = dto;
}
return {
port: config.port,
hostname: config.hostname ?? "127.0.0.1",
defaultProvider: config.defaultProvider,
defaultModelAliases: config.defaultModelAliases,
codexAutoStart: codexAutoStartEnabled(config),
websockets: config.websockets,
// The GUI's browser-open toggle reads and writes this; absent means the
// historical auto-open behavior.
oauthOpenBrowser: config.oauthOpenBrowser !== false,
showCodexCredits: config.showCodexCredits === true,
providers,
};
}