@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
364 lines (346 loc) • 15.9 kB
text/typescript
import { resolveProviderApiKey } from "./key-store";
import { isProviderApiKeyPaused, ProviderApiKeyPausedError } from "./api-key-pause";
import { createOpenAiSidecarCreditGuard } from "./openai-sidecar-credit";
import {
CodexPoolAuthenticationError,
headersForCodexAuthContext,
hasCallerCodexBearer,
isCodexAuthContextUsable,
resolveCodexAuthContext,
releaseCodexAuthContextProbeLease,
type CodexAccountSelectionAdmission,
type CodexAuthContext,
type CodexAuthPolicyConfig,
} from "../codex/auth-context";
import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
import { codexFailureWindowOutcomeMeta } from "../codex/routing/failure-window";
import { inspectChatGptDomainClaim } from "../oauth/chatgpt";
import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "../server/auth-cors";
import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
import {
CODEX_FORWARD_BASE_URL,
isCanonicalOpenAiForwardProvider,
OPENAI_API_PROVIDER_ID,
OPENAI_CODEX_PROVIDER_ID,
} from "./openai-tiers";
import { getProviderRegistryEntry, providerCodexAccountMode } from "./registry";
export interface OpenAiForwardSidecarCandidate {
providerName: typeof OPENAI_CODEX_PROVIDER_ID;
provider: OcxProviderConfig;
accountMode: CodexAccountMode;
}
export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandidate {
authContext: CodexAuthContext;
headers: Headers;
beforeDispatch?: () => void;
recordOutcome?: (outcome: CodexUpstreamOutcome) => void;
/** Hand back an acquired recovery probe when no sidecar request reached upstream. */
releaseProbeLease?: () => void;
}
/**
* Server-resolved exact account selection for a ChatGPT sidecar call.
* `accountId` must come from a validated account-qualified route; request headers
* are never trusted as account ids. `modelId` is the sidecar's actual upstream
* model so cooldown admission and outcome recording use the correct quota scope.
*/
export interface ExactOpenAiSidecarAccount {
accountId: string;
modelId: string;
}
export interface OpenAiImagesProviderSelection {
forwardCandidates: OpenAiForwardSidecarCandidate[];
keyed?: {
providerName: string;
provider: OcxProviderConfig;
apiKey: string;
};
paused?: boolean;
error?: string;
}
export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
if (!provider || provider.disabled === true) return [];
// The built-in registry defaults an omitted authMode to forward. Normalize only that
// missing field before the strict adapter/destination check; explicit key mode and
// noncanonical destinations remain ineligible for ChatGPT credential injection.
const canonicalProvider = provider.authMode === undefined
? { ...provider, authMode: "forward" as const }
: provider;
if (!isCanonicalOpenAiForwardProvider(canonicalProvider)) return [];
// The predicate accepts harmless trailing-slash variants. Pin the provider returned
// to credential-bearing sidecars so every consumer builds one exact ChatGPT path
// instead of independently concatenating the operator's equivalent spelling.
const pinnedProvider = canonicalProvider.baseUrl === CODEX_FORWARD_BASE_URL
? canonicalProvider
: { ...canonicalProvider, baseUrl: CODEX_FORWARD_BASE_URL };
return [{
providerName: OPENAI_CODEX_PROVIDER_ID,
provider: pinnedProvider,
accountMode: providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, pinnedProvider) ?? "pool",
}];
}
/** An explicit caller bearer/account pair for canonical OpenAI destinations; never persist. */
export type ExplicitOpenAiCallerAuth = Readonly<{ authorization: string; chatgptAccountId: string }>;
function explicitSidecarAuth(incomingHeaders: Headers): ExplicitOpenAiCallerAuth | null {
// Combined Authorization values must not smuggle a second credential into a snapshot,
// and only a well-formed ChatGPT-specific account marker is domain evidence — a generic
// organizations claim is not.
const bearer = /^Bearer[\t ]+([^\s,]+)$/i.exec(incomingHeaders.get("authorization")?.trim() ?? "")?.[1];
if (!bearer) return null;
const claim = inspectChatGptDomainClaim(bearer);
if (claim.kind !== "valid") return null;
const derivedAccountId = claim.accountId;
const requestedAccountId = incomingHeaders.get("chatgpt-account-id")?.trim();
// JWT payloads are decoded locally but not signature-verified. Requiring the caller's
// explicit account header, and checking it against the token claim, makes forwarding an
// intentional ChatGPT-auth operation instead of silently reclassifying any JWT-shaped
// provider credential as a Codex bearer.
if (!requestedAccountId || requestedAccountId !== derivedAccountId) return null;
return { authorization: incomingHeaders.get("authorization")!, chatgptAccountId: requestedAccountId };
}
export function captureExplicitOpenAiCallerAuth(incomingHeaders: Headers, config: OcxConfig): ExplicitOpenAiCallerAuth | null {
const auth = explicitSidecarAuth(incomingHeaders);
if (!auth) return null;
try {
validateForwardAdmissionCredential(incomingHeaders, config);
} catch (error) {
if (error instanceof ForwardAdmissionCredentialError) return null;
throw error;
}
return auth;
}
function directSidecarHeaders(
incomingHeaders: Headers,
config: CodexAuthPolicyConfig,
admission?: Pick<DataPlaneAdmission, "source">,
): Headers | undefined {
if (!explicitSidecarAuth(incomingHeaders)) return undefined;
const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null }, config, undefined, admission);
return selected;
}
/**
* The caller's own ChatGPT credential for a call the caller created itself.
*
* A V3 `existingCall` sideband join attaches to a WebRTC call that ChatGPT voice or Codex Desktop
* created with the caller's login, so only that login can join it; a Pool-selected account is a
* different ChatGPT account and the upstream refuses the handshake. This hands the join the same
* caller-owned headers Codex Direct mode forwards: an explicit bearer whose token claim matches
* its `chatgpt-account-id`, never the proxy admission secret, materialized through the same main
* policy (hard lock, credits), whose refusals surface as `CodexAccountCooldownError`.
* Returns undefined when the caller presents no such credential.
*/
export function resolveCallerOwnedOpenAiSidecar(
candidates: readonly OpenAiForwardSidecarCandidate[],
incomingHeaders: Headers,
config: OcxConfig,
options: { admission?: Pick<DataPlaneAdmission, "source">; codexAuthPolicy?: CodexAuthPolicyConfig } = {},
): ResolvedOpenAiForwardSidecar | undefined {
const candidate = candidates[0];
if (!candidate) return undefined;
try {
validateForwardAdmissionCredential(incomingHeaders, config);
} catch (error) {
if (error instanceof ForwardAdmissionCredentialError) return undefined;
throw error;
}
if (!hasCallerCodexBearer(incomingHeaders)) return undefined;
const headers = directSidecarHeaders(incomingHeaders, options.codexAuthPolicy ?? config, options.admission);
if (!headers) return undefined;
return { ...candidate, authContext: { kind: "main", accountId: null }, headers };
}
export async function resolveFirstUsableOpenAiSidecar(
candidates: readonly OpenAiForwardSidecarCandidate[],
incomingHeaders: Headers,
config: OcxConfig,
options: {
exactAccount?: ExactOpenAiSidecarAccount;
admission?: Pick<DataPlaneAdmission, "source">;
codexAuthPolicy?: CodexAuthPolicyConfig;
beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
signal?: AbortSignal;
} = {},
): Promise<ResolvedOpenAiForwardSidecar | undefined> {
const { exactAccount } = options;
const policy = options.codexAuthPolicy ?? config;
let callerBearerMayBeForwarded = true;
try {
validateForwardAdmissionCredential(incomingHeaders, config);
} catch (error) {
if (!(error instanceof ForwardAdmissionCredentialError)) throw error;
callerBearerMayBeForwarded = false;
}
for (const candidate of candidates) {
if (exactAccount) {
// An account-qualified model is an explicit user choice. Resolve the stored
// credential directly even when the provider is globally Direct, and never
// consult Pool active state, affinity, probes, or alternates.
const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
codexAuthPolicy: policy,
accountId: exactAccount.accountId,
modelId: exactAccount.modelId,
admission: options.admission,
beginCodexAccountSelection: options.beginCodexAccountSelection,
signal: options.signal,
});
let selectedHeaders: Headers;
try {
options.signal?.throwIfAborted();
selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, exactAccount.modelId, options.admission);
} catch (error) {
releaseCodexAuthContextProbeLease(authContext);
throw error;
}
if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
|| !isCodexAuthContextUsable(authContext, config)) {
// Exact selection is fail-closed. A generation/runtime-state race must not fall through
// to the caller-bearer error or let a later candidate select another account.
releaseCodexAuthContextProbeLease(authContext);
throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
}
const windowMeta = codexFailureWindowOutcomeMeta(authContext);
return {
...candidate,
authContext,
headers: selectedHeaders,
beforeDispatch: createOpenAiSidecarCreditGuard(authContext, policy),
recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
config,
authContext.accountId,
outcome,
{
modelId: exactAccount.modelId,
fixedAccount: true,
probeLeaseId: authContext.probeLeaseId,
probeQuotaScope: authContext.probeQuotaScope,
writerGeneration: authContext.writerGeneration,
...windowMeta,
// 401/403 here is evidence about this exact stored credential; without the generation a
// replacement inherits the quarantine (#2892 gap 4).
...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
},
),
releaseProbeLease: () => releaseCodexAuthContextProbeLease(authContext),
};
}
if (candidate.accountMode === "direct") {
if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
const headers = directSidecarHeaders(incomingHeaders, policy, options.admission);
if (!headers) continue;
return {
...candidate,
authContext: { kind: "main", accountId: null },
headers,
};
}
const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode, {
codexAuthPolicy: policy,
admission: options.admission,
beginCodexAccountSelection: options.beginCodexAccountSelection,
signal: options.signal,
});
let selectedHeaders: Headers;
try {
options.signal?.throwIfAborted();
selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, undefined, options.admission);
} catch (error) {
releaseCodexAuthContextProbeLease(authContext);
throw error;
}
if (!isCodexAuthContextUsable(authContext, config)) {
releaseCodexAuthContextProbeLease(authContext);
continue;
}
const windowMeta = codexFailureWindowOutcomeMeta(authContext);
return {
...candidate,
authContext,
headers: selectedHeaders,
beforeDispatch: createOpenAiSidecarCreditGuard(authContext, policy),
...(authContext.kind === "pool" || authContext.kind === "main-pool"
? {
recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
config,
authContext.accountId,
outcome,
{
threadId: authContext.affinityKey,
probeLeaseId: authContext.probeLeaseId,
writerGeneration: authContext.writerGeneration,
...windowMeta,
// Same fence as the exact-account recorder above (#2892 gap 4).
...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
},
),
releaseProbeLease: () => releaseCodexAuthContextProbeLease(authContext),
}
: {}),
};
}
return undefined;
}
export function selectOpenAiImagesProvider(config: OcxConfig, allowPausedActiveRecovery = false): OpenAiImagesProviderSelection {
const selection: OpenAiImagesProviderSelection = {
forwardCandidates: listOpenAiForwardSidecarCandidates(config),
};
const provider = config.providers[OPENAI_API_PROVIDER_ID];
if (
provider
&& provider.disabled !== true
&& provider.adapter === "openai-responses"
&& provider.authMode !== "forward"
&& provider.baseUrl.replace(/\/+$/, "") === "https://api.openai.com/v1"
) {
const canRecover = allowPausedActiveRecovery && provider.apiKeyPool?.some(entry => !entry.disabled);
if (isProviderApiKeyPaused(provider) && !canRecover) {
if (allowPausedActiveRecovery) {
selection.paused = true;
selection.error = new ProviderApiKeyPausedError().message;
}
return selection;
}
const apiKey = resolveProviderApiKey(provider.apiKey)?.trim();
if (apiKey) selection.keyed = { providerName: OPENAI_API_PROVIDER_ID, provider, apiKey };
}
return selection;
}
/** Resolve an explicit custom Images provider, otherwise preserve the existing OpenAI fallback. */
export function selectImagesProvider(config: OcxConfig): OpenAiImagesProviderSelection {
const configuredProvider = config.images?.provider;
if (configuredProvider === undefined) return selectOpenAiImagesProvider(config, true);
if (typeof configuredProvider !== "string" || !configuredProvider.trim()) {
return { forwardCandidates: [], error: "images.provider must be a nonblank provider name" };
}
const providerName = configuredProvider.trim();
if (getProviderRegistryEntry(providerName)) {
return {
forwardCandidates: [],
error: `images.provider "${providerName}" must name a custom provider; omit it to use built-in OpenAI tiers`,
};
}
const provider = Object.prototype.hasOwnProperty.call(config.providers, providerName)
? config.providers[providerName]
: undefined;
if (!provider) {
return { forwardCandidates: [], error: `images.provider "${providerName}" is not configured` };
}
if (provider.disabled === true) {
return { forwardCandidates: [], error: `images.provider "${providerName}" is disabled` };
}
if (provider.adapter !== "openai-responses" || (provider.authMode !== undefined && provider.authMode !== "key")) {
return {
forwardCandidates: [],
error: `images.provider "${providerName}" must be an API-key openai-responses provider`,
};
}
if (provider.apiKeyPool?.length && provider.apiKeyPool.every(entry => entry.disabled === true)) {
return { forwardCandidates: [], paused: true, error: new ProviderApiKeyPausedError().message };
}
const apiKey = resolveProviderApiKey(provider.apiKey)?.trim();
if (!apiKey) {
return { forwardCandidates: [], error: `images.provider "${providerName}" has no usable API key` };
}
return {
forwardCandidates: [],
keyed: { providerName, provider, apiKey },
};
}