@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,705 lines • 84.6 kB
text/typescript
import { codexAccountPriorityFailbackEnabled } from "./account-priority";
import type { PoolQuotaWriter } from "./quota-types";
import { createHash, timingSafeEqual } from "node:crypto";
import {
CodexCredentialGenerationConflictError,
CodexCredentialRefreshLockTimeoutError,
CodexCredentialRefreshBusyError,
CodexCredentialRefreshStaleError,
getCodexAccountCredential,
getValidCodexToken,
capturePoolQuotaWriter,
isCodexAccountGenerationLive,
readCodexAccountRecord,
} from "./account-store";
import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
import { ConfigMutationLockError } from "../config";
import { NativeProfileError } from "./native-profile-types";
import { isCodexAccountUsable } from "./account-usability";
import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
import {
MAIN_CODEX_ACCOUNT_ID,
MainAccountTokenRefreshError,
MainAuthJsonChangedDuringRefreshError,
getMainAccountToken,
getValidMainAccountToken,
isMainAccountTokenLive,
type NativeMainRefreshDependencies,
} from "./main-account";
import { isMainAccountPolicyBindingPending, isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./native-profile-startup";
import type { NativeMainStartupBlockReason } from "./native-profile-startup";
import { waitForMainAccountPolicyBinding } from "./main-account-policy-wait";
import {
codexQuotaScopeForModel,
computeCodexUsageScore,
getCodexQuotaHealthSnapshot,
isEffectiveCodexAccountPinned,
releaseCodexQuotaProbeLease,
releaseCodexQuotaScopeProbeLease,
tryAcquireCodexQuotaProbeLease,
tryAcquireCodexQuotaScopeProbeLease,
pickAlternateCodexAccount,
resolveCodexAccountForThreadDetailed,
type CodexAffinityDecision,
type CodexThreadResolution,
type TransientProbeGrant,
} from "./routing";
// The half-open TRANSIENT-HOLD lease (#4701). Not the quota-cooldown probe lease imported from
// ./routing above -- different module, different domain, and a request never holds both.
import { releaseTransientProbe } from "../routing/probe-lease";
import {
codexConversationIdentity,
recordCodexThreadLineage,
resolveCodexThreadLineage,
type CodexThreadLineage,
} from "./lineage";
import {
cachedDeniedCodexAccountIdsForModel,
entitledCodexAccountIdsForModel,
isDirectCallerEntitledToCodexModel,
resolveCodexModelEntitlements,
} from "./model-entitlements";
import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./catalog/native-models";
import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
import { maskAccountId } from "../lib/privacy";
import { formatErrorResponse } from "../bridge";
import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
import { FORWARD_HEADERS } from "../adapters/openai-responses";
import { captureConfigGeneration } from "../lib/state-store-sweeper";
import { extractAccountId, extractEmail } from "../oauth/chatgpt";
import {
MAIN_ACCOUNT_HARD_LOCK_PERCENT,
getMainAccountHardLockStatus,
isMainAccountHardLockEnabled,
isMainAccountHardLocked,
} from "./main-account-hard-lock";
import {
captureMainAccountIdentityGeneration,
captureMainQuotaWriter,
getObservedMainQuotaIdentityKey,
isMainQuotaWriterLive,
matchesMainQuotaCredential,
observeMainQuotaCredential,
type MainQuotaWriter,
} from "./main-account-cache";
import { CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE, isCodexReserveHelperUnsupported, isCodexReserveRequestEligible } from "./loopback-target";
import type { DataPlaneAdmission } from "../server/auth-cors";
import { getMainReserveAuthorization, isMainReserveAuthorizationLive, nativeUserIdClaims, type MainReserveAuthorization } from "./reserve-availability";
import { UpstreamRetryEvidenceError } from "../lib/upstream-retry";
import { getEffectiveCodexAutoSwitchThreshold } from "./account-auto-switch";
/**
* A request-owned bearer cannot inspect the physical main credential for its plan, but cached
* WHAM usage is still valid routing evidence for the same logical main account. Score it with
* the conservative unknown-plan rule: an unobserved governing window preserves the pin, while
* any known weekly/monthly/short value at the threshold releases it through the ordinary Pool
* path. This keeps the keyring boundary intact instead of reading auth.json just to classify a
* request that already brought its own credential (#3157).
*/
function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
const threshold = getEffectiveCodexAutoSwitchThreshold(config, MAIN_CODEX_ACCOUNT_ID);
if (threshold <= 0) return true;
const usage = computeCodexUsageScore(getAccountQuota(MAIN_CODEX_ACCOUNT_ID));
return usage >= CODEX_UNKNOWN_USAGE_SCORE || usage < threshold;
}
/**
* Whether a request carrying its OWN main credential still serves on main because the operator
* manually pinned it (#3166), split from the surrounding resolution so request preview can ask
* the identical question (#4850).
*
* Exported for exactly one reason: two copies of this fence is how #4850 happened. Final
* authentication honoured the ownership boundary while request preview, computing its fence from
* recovery and drain state alone, still handed pool eligibility the default liveness probe and
* opened the physical `auth.json` twice per spawn. A predicate one caller can forget is a
* predicate the other caller will eventually disagree with.
*
* Read-free by construction, which is what makes it usable on the fenced side. Every input is
* config, policy, or in-memory runtime state: the pin fields, the paused list, the cached quota
* score, and `callerMatchesObservedMain`, which compares HMAC digests against the observed
* credential record in `main-account-cache.ts`. Nothing here opens a file.
*
* `candidate` is the pin before the hard-lock question, because the caller still owes the
* pending-binding check that only final authentication can fail closed on.
*/
export function requestOwnedMainPinState(
headers: Headers,
config: OcxConfig,
policy: CodexAuthPolicyConfig,
requestScopedMainCredential: boolean,
fixedAccountId: string | undefined,
quotaScope?: CodexQuotaScope,
): { candidate: boolean; preserve: boolean } {
const candidate = requestScopedMainCredential
&& fixedAccountId === undefined
&& config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
&& isEffectiveCodexAccountPinned(config)
&& !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
&& requestOwnedMainPinHasQuotaHeadroom(config);
return {
candidate,
preserve: candidate && !(callerMatchesObservedMain(headers)
&& (isMainAccountHardLocked(policy)
|| getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope)?.cooldownUntil)),
};
}
/**
* One conversation tree keys as ONE cohort (#4780).
*
* Upstream keys its prompt cache on something the whole tree shares -- `prompt_cache_key` is the
* session id, or `{source}:{parent_thread_id}` for an internal session -- and one `AgentControl`
* whose `session_id` is the root thread's id is shared with every sub-agent. While the proxy
* keyed per thread, two requests could carry an identical `prompt_cache_key` and be served by
* different accounts, so the split member asserted a warm prefix that was deterministically cold
* on its account. Nothing failed; the prompt was replayed in full and the tokens burned.
*
* THIS IS NOT A REVERT OF #4546 wp8. wp8 fixed a different defect -- a child bound under the RAW
* parent id, an identity unrelated to the root's own binding, so siblings shared an entry the
* root was not on and a grandchild landed on a key nobody had bound. A cohort key has no such
* incoherence, because the root's own binding IS the cohort key. What wp8 additionally gave each
* thread, a binding of its own, is what this deliberately gives up.
*
* Which requests produce no key at all is unchanged, through both units.
*
* The derivation itself lives in ./lineage so a lineage record's conversation key and the key
* the thread actually binds under can never drift apart.
*/
export function codexPoolAffinityKey(headers: Headers, now = Date.now()): string | undefined {
// `now` is threaded rather than read inside because a parent-only turn resolves its key
// through the recorded lineage, and that record is TTL-bounded: a caller working against a
// fixed clock would otherwise see a live record as expired and fall back to a key the parent
// never bound under.
return codexConversationIdentity(headers, now)?.conversationKey;
}
/** What a caller needs to know to answer the Pool-state question below before auth has run. */
export interface CodexPoolStateEligibility {
/** An exact account selector from the route, i.e. `options.accountId` here. */
readonly accountId?: string;
readonly modelId?: string;
readonly admission?: Pick<DataPlaneAdmission, "source">;
/** The caller presented its own forwardable ChatGPT credential for this route. */
readonly requestScopedMainCredential?: boolean;
}
/** The one expression both the resolution below and any preview must agree on. */
function poolStateEligible(
fixedAccountId: string | undefined,
requestScopedMainCredential: boolean,
): boolean {
return fixedAccountId === undefined && !requestScopedMainCredential;
}
/**
* Does main have a live credential for a request that carries main's own bearer?
*
* The one expression final authentication and every preview must agree on, for the same reason
* `poolStateEligible` is: preview exists to predict the resolution, and a preview that scores main
* differently hands subagent fallback a different account than the one that serves (#4850).
*
* A forwardable request-owned bearer IS main's live credential -- it is exactly what would be
* sent if selection named main -- so the honest answer is yes, without reading the stored
* credential. An effective manual pin answers yes as it always did. The answer is no while the
* physical identity is fenced for a different reason, because retained recovery and a profile
* drain must keep main out of routing even for a request holding its own bearer.
*/
export function requestOwnedMainCredentialIsLive(inputs: {
preserveRequestOwnedMainPin: boolean;
requestScopedMainCredential: boolean;
nativeMainTrafficBlocked: boolean;
mainProfileDraining: boolean;
/**
* The caller's own credential is one of the Pool subscriptions currently in cooldown.
*
* Final authentication only. Cooldown identity is not modelled by preview and never was --
* `callerIsCooledPoolAccount` has no other caller -- because it decides a refusal rather than
* which account serves, so a preview that scores main while the resolution refuses still hands
* subagent fallback the right account. Passed explicitly at both preview sites so the asymmetry
* is stated rather than inherited from a default.
*/
callerOwnsCooledPoolSubscription: boolean;
}): boolean {
return inputs.preserveRequestOwnedMainPin
|| (inputs.requestScopedMainCredential
&& !inputs.nativeMainTrafficBlocked
&& !inputs.mainProfileDraining
&& !inputs.callerOwnsCooledPoolSubscription);
}
/**
* May this request own Pool affinity state at all?
*
* Two credentials authenticate outside the Pool: an exact account selector (including the
* Reserve pin) and a request-owned main bearer, which exists for one request and must never
* fold into durable account state. Neither may read or write a binding, so neither may read
* or write LINEAGE either.
*
* Exported so that a preview asks the question with the code that answers it, instead of a
* restatement that can drift. It drifted once already: preview read a family relation from raw
* request headers before this function had decided anything, so it could follow a Pool family
* binding while the resolution below deliberately created no affinity -- and model fallback then
* evaluated eligibility against an account the request would never be authenticated as.
*/
export function codexPoolStateEligible(
headers: Headers,
policy: CodexAuthPolicyConfig | undefined,
options: CodexPoolStateEligibility = {},
): boolean {
const reserve = requiresReserveAuthorization(policy, options.modelId, options.admission);
return poolStateEligible(
reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId,
options.requestScopedMainCredential === true && hasCallerCodexBearer(headers),
);
}
/**
* The lineage a PREVIEW is allowed to see: read-only, and only for a request that may hold Pool
* state. Recording is left to the resolution that actually binds, so a preview can never leave a
* record behind for a request that turned out to own no Pool state at all.
*/
export function previewCodexPoolLineage(
headers: Headers,
policy: CodexAuthPolicyConfig | undefined,
options: CodexPoolStateEligibility = {},
): CodexThreadLineage | undefined {
return codexPoolStateEligible(headers, policy, options)
? resolveCodexThreadLineage(headers)
: undefined;
}
export type CodexAuthContext =
| { kind: "main"; accountId: null; reserveAuthorization?: MainReserveAuthorization }
| {
kind: "pool";
accountId: string;
writerGeneration: number;
generation: number;
poolQuotaWriter?: PoolQuotaWriter;
accessToken: string;
chatgptAccountId: string;
/** Bypass Pool selection and suppress quota/transient failover for an exact selector. */
fixedAccount?: boolean;
/** Pool binding key; the Desktop fallback is an opaque process-local HMAC. */
affinityKey?: string;
/**
* Set when this request was admitted through an active quota cooldown as
* the account's single probe. Must be echoed into the upstream outcome so
* only this request can clear the cooldown (#433).
*/
probeLeaseId?: string;
/** Native model quota group selected for this request, when known. */
quotaScope?: CodexQuotaScope;
/** What happened to this thread's binding on this request (#4546). */
affinityDecision?: CodexAffinityDecision;
/** Scope that owns `probeLeaseId`, when it is a scoped recovery probe. */
probeQuotaScope?: CodexQuotaScope;
/**
* Set when this request is the ONE dispatch admitted to test an account held under a
* transient 5xx hold (#4701). Echo it into the upstream outcome so the trial is settled
* by the request that ran it, and release it on any path that never reaches upstream.
*/
transientProbe?: TransientProbeGrant;
}
| {
// Main Codex account participating in rotation: token injected from ~/.codex/auth.json
// (Option A). Distinct from "main" (request-owned passthrough or Direct mode).
kind: "main-pool";
accountId: string;
writerGeneration: number;
/** Captured before async credential work; never reconstructed after the upstream response. */
mainQuotaWriter?: MainQuotaWriter;
reserveAuthorization?: MainReserveAuthorization;
accessToken: string;
chatgptAccountId: string;
/** Bypass Pool selection and suppress quota/transient failover for an exact selector. */
fixedAccount?: boolean;
/** See `pool.affinityKey`. */
affinityKey?: string;
/** See `pool.probeLeaseId`. */
probeLeaseId?: string;
quotaScope?: CodexQuotaScope;
probeQuotaScope?: CodexQuotaScope;
/** See `pool.transientProbe`. */
transientProbe?: TransientProbeGrant;
};
/** Probe lease carried by this context, when it holds one. */
export function codexProbeLeaseId(ctx: CodexAuthContext | undefined): string | undefined {
return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeLeaseId : undefined;
}
/** Scope of a lease carried by this context, when it probes a model-specific quota. */
export function codexProbeQuotaScope(ctx: CodexAuthContext | undefined): CodexQuotaScope | undefined {
return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeQuotaScope : undefined;
}
/** The transient-hold recovery probe carried by this context, when it holds one (#4701). */
export function codexTransientProbeGrant(ctx: CodexAuthContext | undefined): TransientProbeGrant | undefined {
return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.transientProbe : undefined;
}
/**
* Hand back a probe lease for a request that will not reach upstream. Safe to
* call with a context that holds no lease.
*
* BOTH leases, deliberately. A context can carry the quota-cooldown probe or the transient-hold
* probe, and every one of the ~30 call sites that already hands back the first is a path where
* the second would leak too. Releasing them together is what makes those sites correct for the
* new lease without re-deriving the discard set by hand -- the failure mode being avoided is a
* held account nobody may probe because the request that held the trial went away quietly.
*/
export function releaseCodexAuthContextProbeLease(ctx: CodexAuthContext | undefined): void {
const transientProbe = codexTransientProbeGrant(ctx);
if (transientProbe) releaseTransientProbe(transientProbe.lease);
const leaseId = codexProbeLeaseId(ctx);
if (!ctx || ctx.kind === "main" || !leaseId) return;
if (ctx.probeQuotaScope) releaseCodexQuotaScopeProbeLease(ctx.accountId!, ctx.probeQuotaScope, leaseId);
else releaseCodexQuotaProbeLease(ctx.accountId!, leaseId);
}
export type OcxRuntimeProviderConfig = OcxProviderConfig & {
_codexAccountOverride?: { accessToken: string; chatgptAccountId: string };
_codexAccountRequired?: boolean;
};
export class CodexAuthContextError extends Error {
accountId: string;
constructor(accountId: string, cause: unknown) {
super("Codex pool account auth failed", { cause });
this.name = "CodexAuthContextError";
this.accountId = accountId;
}
}
export class CodexPoolAuthenticationError extends Error {
constructor(message = "OpenAI account pool has no usable account credential") {
super(message);
this.name = "CodexPoolAuthenticationError";
}
}
export type CodexModelAvailabilityReason = "unsupported" | "temporarily_unavailable";
/** A model/account compatibility failure is not a credential failure. */
export class CodexModelAvailabilityError extends CodexPoolAuthenticationError {
reason: CodexModelAvailabilityReason;
constructor(reason: CodexModelAvailabilityReason, message: string) {
super(message);
this.name = "CodexModelAvailabilityError";
this.reason = reason;
}
}
class CodexAccountValidationPendingError extends CodexPoolAuthenticationError {
constructor() {
super("Codex account validation is pending; refresh quota after recovery to validate it");
this.name = "CodexAccountValidationPendingError";
}
}
function assertCodexAccountValidationReady(accountId: string): void {
if (accountId !== MAIN_CODEX_ACCOUNT_ID && readCodexAccountRecord(accountId)?.codexValidationPending) {
throw new CodexAccountValidationPendingError();
}
}
export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
"OpenCodex local native-main profile maintenance is active; retry this request";
export class CodexMainProfileDrainingError extends Error {
/**
* Which startup-gate state fenced this request, when one did. Undefined means the
* fence came from somewhere other than the startup gate — the turn-drain claim race
* throws this same error while the gate reads `ready`, and inventing a reason there
* would point the next report at a gate that never closed.
*
* Captured here rather than at the throw sites because this is the last moment it is
* both in scope and still true: every catch site has already lost it, and re-reading
* the gate later can observe a recovery that completed in between (#2108).
*/
readonly reason?: NativeMainStartupBlockReason;
constructor() {
super(CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
this.name = "CodexMainProfileDrainingError";
const gate = nativeMainStartupGateSnapshot();
if (gate.status !== "blocked") return;
this.reason = gate.reason;
reportNativeMainFenceReason(gate.reason);
}
}
/**
* #2108: a reboot could leave this fence closed until `ocx restart`, and the report was
* unactionable because the settled reason was never written anywhere. It cannot ride the
* message (claude-messages.ts matches that string exactly to keep the fence a 503 rather
* than an Anthropic 529) and it cannot ride a header (/api/logs reads only error.message
* from the body, and the Claude surface rebuilds its response headers from scratch), so
* stdout is the one surface that covers every path this fence fires on.
*
* Deduped per distinct reason: the original report shows three 503s in eleven seconds and
* a real client retries harder than that, so a per-request line would bury the signal.
* Only the reason is emitted; the snapshot's homeId is derived from a profile directory.
*/
const reportedFenceReasons = new Set<NativeMainStartupBlockReason>();
function reportNativeMainFenceReason(reason: NativeMainStartupBlockReason): void {
if (reportedFenceReasons.has(reason)) return;
reportedFenceReasons.add(reason);
console.warn(
`native-main admission is fenced (reason: ${reason}); native model requests return 503 until it clears`,
);
}
/**
* Test-only reset for the dedup set above.
*
* The dedup is process-lifetime module state, so it is order-sensitive across test files
* sharing one Bun process: whichever file constructs this error first consumes the one-shot
* warn, and a later file asserting on it would see nothing and pass vacuously. Any test that
* asserts on the warn must call this first — an `afterEach` in the asserting file is not
* enough on its own, because the consuming file may not be the asserting one.
*/
export function __resetNativeMainFenceReasonLog(): void {
reportedFenceReasons.clear();
}
export function codexMainProfileDrainingResponse(): Response {
const response = formatErrorResponse(503, "server_busy", CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
const headers = new Headers(response.headers);
headers.set("Retry-After", "1");
return new Response(response.body, { status: response.status, headers });
}
export class CodexDirectAuthenticationError extends Error {
constructor() {
super("Codex Direct requires a caller Authorization bearer token");
this.name = "CodexDirectAuthenticationError";
}
}
export function hasCallerCodexBearer(headers: Headers): boolean {
return /^Bearer\s+\S+/i.test(headers.get("authorization")?.trim() ?? "");
}
export class CodexAccountCooldownError extends Error {
accountId: string;
cooldownUntil: number;
cooldownSource?: CodexCooldownSource;
quotaScope?: CodexQuotaScope;
constructor(
accountId: string,
cooldownUntil: number,
cooldownSource?: CodexCooldownSource,
quotaScope?: CodexQuotaScope,
) {
super("Selected Codex account is cooling down");
this.name = "CodexAccountCooldownError";
this.accountId = accountId;
this.cooldownUntil = cooldownUntil;
this.cooldownSource = cooldownSource;
this.quotaScope = quotaScope;
}
}
export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
readonly resetAt?: number;
constructor(resetAt?: number) {
super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
this.name = "CodexMainAccountHardLockError";
this.resetAt = resetAt;
this.message = `Codex main account is blocked by the ${MAIN_ACCOUNT_HARD_LOCK_PERCENT}% main-account quota policy.`
+ " Choose another account, wait for quota to reset, or disable codexMainAccountHardLock in Settings.";
}
}
export class CodexReserveUnavailableError extends CodexAccountCooldownError {
constructor() {
super(MAIN_CODEX_ACCOUNT_ID, 0);
this.name = "CodexReserveUnavailableError";
this.message = "Codex Reserve is unavailable for this main credential."
+ " Use the stored main login or its matching caller credential, and retry when OpenAI grants Reserve access."
+ " Reserve compatibility requires the effective local Desktop authless opt-in; it cannot switch accounts automatically.";
}
}
/** A local unsupported-helper refusal; retain Reserve policy error mapping on delayed sends. */
export class CodexReserveHelperUnsupportedError extends CodexReserveUnavailableError {
constructor() {
super();
this.name = "CodexReserveHelperUnsupportedError";
this.message = CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE;
}
}
/**
* Every account bound to this conversation is held after upstream failures, the recovery
* budget for this window is spent, and there is no detour left -- so this request is refused
* BEFORE any upstream I/O (#4701).
*
* This is not a quota cooldown, and the message below says so. It subclasses
* {@link CodexAccountCooldownError} for one reason: the deadline-carrying refusal has exactly
* one representation in this codebase, and roughly a dozen transports already map it to a 429
* with `Retry-After` and treat it as an expected terminal answer rather than a credential
* fault. Introducing a parallel type would mean either re-deriving that handling in every one
* of them or silently falling through to a 500 in the ones that were missed.
*
* What must NOT be inherited is the quota wording -- "cooling down", `ocx account
* clear-cooldown` -- because none of it describes a 5xx hold and following it would do
* nothing. {@link cooldownErrorMessage} therefore returns this class's own message verbatim,
* the same escape hatch {@link CodexMainAccountHardLockError} and
* {@link CodexReserveUnavailableError} already use.
*
* `cooldownUntil` carries the limiter's own change point, which is strictly in the future:
* either the moment the held account may next be probed or the moment the recovery window
* moves, whichever is later. A refusal that answered `now` would busy-loop the caller into
* the same load it just declined.
*/
export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
/** The sibling still remembered for this thread, when one exists but is itself unusable. */
readonly detourAccountId?: string;
constructor(accountId: string, retryAt: number, detourAccountId?: string) {
super(accountId, retryAt);
this.name = "CodexRecoveryWithheldError";
this.detourAccountId = detourAccountId;
this.message = `Codex account (${cooldownAccountLabel(accountId)}) is held after repeated upstream`
+ ` failures and the pool's recovery budget for this window is spent, so nothing was sent`
+ ` upstream. Retry after ${new Date(retryAt).toISOString()}.`
+ " This clears on its own as the account recovers; no cooldown to lift and no account to switch.";
}
}
export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
"codexMainAccountHardLock" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
>>;
interface CodexAuthMaterializationOptions {
substituteMainCredential?: boolean;
config?: CodexAuthPolicyConfig;
modelId?: string;
/** Trusted receiving-listener admission; never inferred from request headers or config. */
admission?: Pick<DataPlaneAdmission, "source">;
signal?: AbortSignal;
nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
}
function requiresReserveAuthorization(
config: CodexAuthPolicyConfig | undefined,
modelId: string | undefined,
admission: Pick<DataPlaneAdmission, "source"> | undefined,
): boolean {
return modelId === NATIVE_RESERVE_MODEL && !!config && isCodexReserveRequestEligible(config, admission);
}
function assertReserveAdmission(config: CodexAuthPolicyConfig): void {
if (config.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID) || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) {
throw new CodexReserveUnavailableError();
}
assertMainAccountPolicy(config);
const cooldown = getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, "reserve");
if (cooldown?.cooldownUntil) {
throw new CodexAccountCooldownError(MAIN_CODEX_ACCOUNT_ID, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope);
}
}
async function authorizeReserveCredential(
token: { accessToken: string; chatgptAccountId: string },
writer: MainQuotaWriter | undefined,
config: CodexAuthPolicyConfig,
signal?: AbortSignal,
existing?: MainReserveAuthorization,
writerGeneration = captureConfigGeneration(),
): Promise<MainReserveAuthorization> {
assertReserveAdmission(config);
if (!writer || !isMainQuotaWriterLive(writer)
|| !matchesMainQuotaCredential(token.accessToken, token.chatgptAccountId)) {
throw new CodexReserveUnavailableError();
}
const authorization = isMainReserveAuthorizationLive(existing, token) ? existing
: await getMainReserveAuthorization({
token, writer, signal,
observeOrdinaryQuota(data, capturedWriter) {
setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, parseUsageQuota(data), writerGeneration,
capturedWriter, parseMainPolicyUsageQuota(data));
},
});
// The capability read also publishes ordinary quota. A new 99% reading or cooldown wins.
assertReserveAdmission(config);
if (signal?.aborted) throw signal.reason;
if (!authorization || !isMainReserveAuthorizationLive(authorization, token)) throw new CodexReserveUnavailableError();
return authorization;
}
function selectedCodexToken(headers: Headers): { accessToken: string; chatgptAccountId: string } {
return {
accessToken: headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim() ?? "",
chatgptAccountId: headers.get("chatgpt-account-id") ?? "",
};
}
/**
* The workspace account id a request-owned `main` credential materializes under, or
* `undefined` when the caller's headers carry none. This is the `chatgpt-account-id`
* `materializeCodexUpstreamAuth` would set for a caller-owned `{ kind: "main" }` context,
* read here without touching a credential store so a rotation gate can compare workspace
* scope before a send is ever built.
*/
export function callerCodexWorkspaceAccountId(headers: Headers): string | undefined {
const explicit = headers.get("chatgpt-account-id");
if (explicit) return explicit;
const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
return bearer ? extractAccountId(undefined, bearer) : undefined;
}
function assertMaterializedReserve(headers: Headers, ctx: CodexAuthContext, options: CodexAuthMaterializationOptions): void {
if (!requiresReserveAuthorization(options.config, options.modelId, options.admission)) return;
assertReserveAdmission(options.config!);
if (ctx.kind === "pool" || !isMainReserveAuthorizationLive(ctx.reserveAuthorization, selectedCodexToken(headers))) {
throw new CodexReserveUnavailableError();
}
}
/** A dispatch never renews permission: the next request may obtain a fresh bounded proof. */
export function createCodexReserveDispatchGuard(
ctx: CodexAuthContext,
config: CodexAuthPolicyConfig,
modelId: string,
admission?: Pick<DataPlaneAdmission, "source">,
terminalHelper = false,
): ((headers: Headers) => void) | undefined {
// Snapshot the resolved source value, not the caller's mutable admission object. Config stays
// live so policy changes remain visible after pacing and retry backoff.
const source = admission?.source;
if (modelId !== NATIVE_RESERVE_MODEL || source !== "loopback") return undefined;
// Only immutable request facts decide whether to install the callback. Flag/role eligibility
// is checked inside it, including an opt-in enabled while a send waits for pacing or WS open.
const ingress = Object.freeze({ source });
return headers => {
if (isCodexReserveHelperUnsupported(config, modelId, ingress, terminalHelper)) {
throw new CodexReserveHelperUnsupportedError();
}
assertMaterializedReserve(headers, ctx, { config, modelId, admission: ingress });
};
}
/** Retry history must not turn a later local admission refusal into a network failure. */
export function unwrapUpstreamRetryEvidenceError(error: unknown): unknown {
const seen = new Set<unknown>();
while (error instanceof UpstreamRetryEvidenceError && !seen.has(error)) {
seen.add(error);
error = error.cause;
}
return error;
}
function assertMainAccountPolicy(config: Pick<OcxConfig, "codexMainAccountHardLock"> | undefined): void {
if (!config) return;
const status = getMainAccountHardLockStatus(config);
if (status.state === "blocked") throw new CodexMainAccountHardLockError(status.resetAt);
}
/** No auth-file I/O: an unsigned claim alone never identifies a caller as stored main. */
function callerMatchesObservedMain(headers: Headers): boolean {
const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
if (!bearer) return false;
const effectiveAccountId = headers.get("chatgpt-account-id")
?? extractAccountId(undefined, bearer);
return matchesMainQuotaCredential(bearer, effectiveAccountId);
}
/** Constant-time digest comparison so bearer bytes never drive branch timing. */
function sameCredentialMaterial(a: string, b: string): boolean {
return timingSafeEqual(createHash("sha256").update(a).digest(), createHash("sha256").update(b).digest());
}
/**
* The early-cooldown caller-main fallback must not resurrect the subscription that is cooling
* down. Fail closed on ambiguity: an unreadable caller identity cannot be distinguished from the
* cooled account. A distinct workspace account id is always safe; an exact materialized
* bearer + account tuple marks the same subscription. Beyond that, the stable native user id is
* the strongest available evidence: it survives an email change and a token rotation, and it
* separates members who share one workspace account id even when neither credential carries an
* email. Email remains the fallback when no comparable user id exists on both sides. Coexisting
* personal/business registrations with the same email and account id over-deny during the
* cooldown — the safe direction.
*/
function callerIsCooledPoolAccount(headers: Headers, config: OcxConfig, accountId: string): boolean {
const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
if (!bearer) return true;
const callerAccountId = headers.get("chatgpt-account-id") ?? extractAccountId(undefined, bearer);
if (callerAccountId === undefined) return true;
if (accountId === MAIN_CODEX_ACCOUNT_ID) {
// No physical-main read to identify the caller: the observed-main equality tag suffices.
return callerMatchesObservedMain(headers);
}
const stored = getCodexAccountCredential(accountId);
const entry = config.codexAccounts?.find(account => account.id === accountId);
const cooledAccountId = stored?.chatgptAccountId || entry?.chatgptAccountId;
if (!cooledAccountId) return true;
if (cooledAccountId !== callerAccountId) return false;
if (stored?.accessToken && sameCredentialMaterial(bearer, stored.accessToken)) return true;
// Same namespace on both sides, never `sub`: this is the ChatGPT per-user identity the reserve
// path already trusts. A credential whose own two encodings of it disagree cannot identify
// anyone, so it fails closed even when the disagreement is on the stored side.
const callerUser = nativeUserIdClaims(bearer);
const cooledUser = stored?.accessToken
? nativeUserIdClaims(stored.accessToken)
: { userId: undefined, conflict: false };
if (callerUser.conflict || cooledUser.conflict) return true;
if (callerUser.userId !== undefined && cooledUser.userId !== undefined) {
return callerUser.userId === cooledUser.userId;
}
const callerEmail = extractEmail(undefined, bearer)?.trim().toLowerCase() || undefined;
const cooledEmail = entry?.email?.trim().toLowerCase() || undefined;
if (callerEmail !== undefined && cooledEmail !== undefined) return callerEmail === cooledEmail;
return true;
}
/**
* Does the caller's own credential belong to a Pool subscription that is currently cooled?
*
* The cooldown fallback below asks this of the SELECTED account, which was sufficient while a
* request-owned bearer could not make main a candidate: the cooled account was the selection, so
* the question and the refusal sat at the same place. Once main takes part in ordering (#5019) the
* cooled account is no longer selected, and serving its own credential as main would resurrect the
* cooldown it is inside — so eligibility has to ask the same question of every cooled sibling.
*
* `callerIsCooledPoolAccount` fails closed on an unreadable caller identity, which is preserved
* here: an opaque bearer counts as owning any cooled subscription rather than escaping it.
*/
function callerOwnsAnyCooledPoolSubscription(
headers: Headers,
config: OcxConfig,
quotaScope: CodexQuotaScope | undefined,
): boolean {
for (const account of config.codexAccounts ?? []) {
if (account.id === MAIN_CODEX_ACCOUNT_ID) continue;
if (!getCodexQuotaHealthSnapshot(account.id, quotaScope)?.cooldownUntil) continue;
if (callerIsCooledPoolAccount(headers, config, account.id)) return true;
}
return false;
}
function captureObservedMainWriter(): MainQuotaWriter | undefined {
const identityKey = getObservedMainQuotaIdentityKey();
return identityKey === undefined ? undefined : {
identityKey,
identityGeneration: captureMainAccountIdentityGeneration(),
};
}
function observeSelectedMainCredential(
token: { accessToken: string; chatgptAccountId: string },
writer: MainQuotaWriter | undefined,
): MainQuotaWriter | undefined {
if (!writer) return undefined;
// Carry an explicitly stale writer through to quota's rejection fence; turning it into an
// untagged write would instead invalidate the replacement account's trusted observation.
if (!isMainQuotaWriterLive(writer)) return writer;
const observed = observeMainQuotaCredential(token.accessToken, token.chatgptAccountId);
return observed?.identityKey === writer.identityKey ? writer : undefined;
}
/**
* Human-readable account label for a client-visible error. NEVER the raw id: the proxy
* supports non-loopback binds (auth-cors.ts `isApiAuthRequired` requires a token there
* rather than refusing), so data-plane bodies can reach remote authenticated clients.
* The main login has no secret id, so it renders as the literal alias users type.
*/
export function cooldownAccountLabel(accountId: string): string {
return accountId === MAIN_CODEX_ACCOUNT_ID ? "main" : maskAccountId(accountId) ?? "account-…????";
}
/**
* Actionable message for a cooled-down account: until when, why, and how to escape.
* Shared by every transport so the WebSocket surface (Codex Desktop) says the same thing
* as HTTP. The bare "cooling down" string left users with no route but commenting out the
* injected `openai_base_url` in config.toml.
*/
export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSelector?: string): string {
if (err instanceof CodexMainAccountHardLockError
|| err instanceof CodexReserveUnavailableError
// A transient-hold refusal is not a quota cooldown. Its own wording is the only accurate
// one, and the quota recovery advice below would send the operator after a cooldown that
// does not exist (#4701).
|| err instanceof CodexRecoveryWithheldError) return err.message;
const until = new Date(err.cooldownUntil).toISOString();
const scopeLabels: Record<CodexQuotaScope, string> = {
shared: "shared native quota", reserve: "Reserve quota",
};
const scope = err.quotaScope ? scopeLabels[err.quotaScope] : null;
const selected = accountSelector
? `Selected Codex account selector (${accountSelector})`
: `Selected Codex account (${cooldownAccountLabel(err.accountId)})`;
const recovery = accountSelector
? " This request is pinned to that selector and will not switch accounts; choose another account-qualified model or retry later."
: " Run 'ocx account list openai' to find the id, then"
+ " 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.";
return `${selected}${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
+ ` (source: ${err.cooldownSource ?? "default"}).${recovery}`;
}
/** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
export function cooldownErrorResponse(
err: CodexAccountCooldownError,
now = Date.now(),
accountSelector?: string,
): Response {
const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
const headers = new Headers(res.headers);
if (!(err instanceof CodexReserveUnavailableError)
&& (!(err instanceof CodexMainAccountHardLockError) || err.resetAt !== undefined)) {
headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
}
return new Response(res.body, { status: res.status, headers });
}
export class CodexThreadAffinityExpiredError extends Error {
accountId: string;
constructor(accountId: string) {
super("Codex thread account affinity expired");
this.name = "CodexThreadAffinityExpiredError";
this.accountId = accountId;
}
}
export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
return !(cause instanceof CodexMainAccountHardLockError)
&& !(cause instanceof CodexAccountValidationPendingError)
&& !(cause instanceof CodexReserveUnavailableError)
&& !(cause instanceof CodexCredentialGenerationConflictError)
&& !(cause instanceof CodexCredentialRefreshLockTimeoutError)
&& !(cause instanceof CodexCredentialRefreshBusyError)
&& !(cause instanceof CodexCredentialRefreshStaleError)
&& !(cause instanceof MainAuthJsonChangedDuringRefreshError)
&& !(cause instanceof MainAccountTokenRefreshError && cause.reason === "transient")
&& !(cause instanceof NativeProfileError && cause.retryable)
&& !(cause instanceof DOMException && cause.name === "AbortError")
&& !(cause instanceof ConfigMutationLockError);
}
export interface ResolveCodexAuthContextOptions {
admission?: Pick<DataPlaneAdmission, "source">;
/** Live policy owner when the routing config is a caller-specific replay snapshot. */
codexAuthPolicy?: CodexAuthPolicyConfig;
excludeAccountId?: string;
/** Resolve exactly this account without consulting or mutating Pool selection. */
accountId?: string;
/** Final native model selected for this request, used to select its quota group. */
modelId?: string;
/** Short reservation converted to turn ownership before native `__main__` token materialization. */
beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
/** Test-only native credential read seams. */
isMainAccountTokenLive?: () => boolean;
getMainAccountToken?: typeof getMainAccountToken;
getValidMainAccountToken?: typeof getValidMainAccountToken;
nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
signal?: AbortSignal;
/** Test seam: overrides the bounded startup policy-binding wait before the hard-lock fence. */
mainAccountPolicyBindingWaitMs?: number;
primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void>;
/** Test seam for account-gated native model discovery. */
resolveCodexModelEntitlements?: typeof resolveCodexModelEntitlements;
/** Direct requests admitted with a proxy bearer substitute the stored native-main credential. */
substituteMainCredentialForDirect?: boolean;
/** A validated native Codex bearer may serve this request without entering Pool state. */
requestScopedMainCredential?: boolean;
/** Test seam for a Direct request's own forwarded ChatGPT credential. */
isDirectCallerEntitledToCodexModel?: (headers: Headers, modelId: string) => Promise<boolean>;
/**
* This request's conversation carries live uploaded-file references (#4778). Retains the bound
* account across a VOLUNTARY quota move; involuntary release is untouched.
*/
retainAccountForUploadedFiles?: boolean;
}
export interface CodexAccountSelectionAdmission {
readonly mainProfileDraining: boolean;
claimMainProfile(): boolean;
release(): void;
}
/**
* Wait, bounded, for an owned startup's main-policy binding, then fail closed while it is still
* in flight.
*
* #5694 turned `codexMainAccountHardLock` on by default, so this fence stopped being an opt-in
* rarity and started intercepting ordinary requests: for the seconds a Windows startup spends
* recovering, sweeping stages, and binding the pinned home, every caller-owned direct request
* was answered with a 503 "native-main profile maintenance is active; retry". Waiting is the
* right answer for a window that closes on its own -- the request resumes and the hard lock
* below still decides on identity and quota, exactly as it does after startup. A gate still
* pending at the deadline (retained recovery, a manual-recovery requirement) is a real refusal,
* and that is the one case that keeps the draining error.
*
* Both reads are memory-only: neither this fence nor the wait probes a foreign home.
*/
async function awaitMainAccountPolicyBindingSettled(
options: ResolveCodexAuthContextOptions,
): Promise<void> {
if (!isMainAccountPolicyBindingPending()) return;
const settled = await waitForMainAccountPolicyBinding({
signal: options.signal,
timeoutMs: options.mainAccountPolicyBindingWaitMs,
});
if (!settled) throw new CodexMainProfileDrainingError();
}
export async function resolveCodexAuthContext(
headers: Headers,
config: OcxConfig,
mode: CodexAccountMode,
options: ResolveCodexAuthContextOptions = {},
): Promise<CodexAuthContext> {
const writerGeneration = captureConfigGeneration();
const policy = options.codexAuthPolicy ?? config;
const requestScopedMainCredential = options.requestScopedMainCredential === true
&& hasCallerCodexBearer(headers);
const reserve = requiresReserveAuthorization(policy, options.modelId, options.admission);
if (reserve && (options.excludeAccountId !== undefined
|| (options.accountId !== undefined && options.accountId !== MAIN_CODEX_ACCOUNT_ID))) {
throw new CodexReserveUnavailableError();
}
const fixedAccountId = reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId;
const quotaScope = codexQuotaScopeForModel(options.modelId);
// Pool pins and fallback must not resurrect an observed main credential that is cooling
// down. Unrelated caller-owned credentials and explicit Direct keep their own policy.
// The identity match and scoped health read are memory-only; never probe the auth file.
const callerOwnedMainPoolCooldown = () => mode === "pool" && callerMatchesObservedMain(headers)
? getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope)
: null;
const assertCallerOwnedMainPoolNotCooled = () => {
const cooldown = callerOwnedMainPoolCooldown();
if (cooldown?.cooldownUntil) {
throw new CodexAccountCooldownError(
MAIN_CODEX_ACCOUNT_ID, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope,
);
}
};
const mainPinState = () => requestOwnedMainPinState(
headers, config, policy, requestScopedMainCredential, fixedAccountId, quotaScope,
);
const requestOwnedMainPinCandidate = mainPinState().candidate;
// During an owned startup, equality cannot be established until recovery and the
// memory-only policy binding finish. This read-only fence never probes a foreign home, and it
// waits out a window that closes on its own instead of refusing a request that arrived inside
// it. Only a binding still pending at the deadline fails closed.
if (isMainAccountHardLockEnabled(policy) && requestOwnedMainPinCandidate) {
await awaitMainAccountPolicyBindingSettled(options);
}
const preserveRequestOwnedMainPin = () => mainPinState().preserve;
if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
throw new Error("Codex auth context cannot select and exclude an account simultaneously");
}
const resolveCallerOwnedMainContext = async (): Promise<CodexAuthContext> => {
const substituteStoredMain = options.substituteMainCredentialForDirect === true;
// An internal route change can strip the admission bearer before this point.
// Trusted substitution still has to claim and validate stored main below.
if (!substituteStoredMain && !hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
if (!substituteStoredMain) {
if (isMainAccountHardLockEnabled(policy)) await awaitMainAccountPolicyBindingSettled(options);
if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
assertCallerOwnedMainPoolNotCooled();
if (reserve) {
const selected = materializeCodexUpstreamAuth(headers, { kind: "main", accountId: null }, { config: policy });
const token = selectedCodexToken(selected);
const reserveAuthorization = await authorizeReserveCredential(token, captureMainQuotaWriter(token.chatgptAccountId),
policy, options.signal, undefined, writerGeneration);
return { kind: "main", accountId: null, reserveAuthorization };
}
if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
const entitled = await (
options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel
)(headers, options.modelId);
if (!entitled) {
throw new CodexModelAvailabilityError(
"unsupported",
"The selected ChatGPT account does not support this model",
);
}
}
if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
assertCallerOwnedMainPoolNotCooled();
return { kind: "main", accountId: null };
}
// Admission-bearer Direct requests later replace the proxy secret with the stored
// native-main credential. Reserve and claim that physical profile before entitlement
// discovery or materialization can read it; caller-owned Direct credentials never enter
// this branch. A missing turn admission must fail closed instead of recreating an
// untracked native-main read.
if (isNativeMainTrafficBlocked()) throw new CodexMainProfileDrainingError();
const directSelectionAdmission = options.beginCodexAccountSelection?.();
if (!directSelectionAdmission) throw new CodexMainProfileDrainingError();
try {
if (
directSelectionAdmission.mainProfileDraining
|| !directSelectionAdmission.claimMainProfile()
|| isNativeMainTrafficBlocked()
) {
throw new CodexMainProfileDrainingError();
}
if (isMainAccountHardLockEnabled(policy)) reconcileMainCodexAccountRuntimeState();
assertMainAccountPolicy(policy);
if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
const entitled = entitledCodexAccountIdsForModel(
await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config, {
signal: options.signal,
nativeMainRefreshDependencies: options.nativeMainRefreshDependencies,
}),
options.modelId,
)?.has(MAIN_CODEX_ACCOUNT_ID) === true;
if (!entitled) {
throw new CodexModelAvailabilityError(
"unsupported",
"The selected ChatGPT account does not support this model",
);
}
}
assertMainAccountPolicy(policy);
return { kind: "main", accountId: null };
} finally {
// The short selector reservation ends here. A successful claim remains owned by
// the enclosing turn lease until the request or transferred stream settles.
directSelectionAdmission.release();
}
};
// Pool discovery excludes request-owned main credentials by design: they must never be folded
// into stored-account entitlement, affinity, or persistence state. An effective manual main pin
// is the one exception where that exclusion is selection evidence in the opposite direction.
// Validate the caller's own gated-model roster before using it, and fall through to a Pool model
// detour when it lacks the grant. This branch performs no physical-main credential read.
if (preserveRequestOwnedMainPin()) {
const callerEntitled = !options.modelId
|| !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
|| await (
options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel
)(headers, options.modelId);
if (callerEntitled && preserveRequestOwnedMainPin()) {
return { kind: "main", accountId: null };
}
}
// An explicit namespace binding is stronger than the provider's default mode. It must use the
// selected stored credential even while the canonical OpenAI provider is globally Direct.
// A request-owned bearer is deliberately not represented as `main-pool`: Pool account ids own
// durable health, quota, and affinity state, while this credential exists for one request only.
if ((reserve && hasCallerCodexBearer(headers) && !options.substituteMainCredentialForDirect
&& (requestScopedMainCredential || mode === "direct"))
|| (mode === "direct" && fixedAccountId === undefined)
|| (requestScopedMainCredential && fixedAccountId === MAIN_CODEX_ACCOUNT_ID)) {
return resolveCallerOwnedMainContext();
}
// A caller bearer can still accompany a request that selects a configured Pool account. Do not
// let that request read, delete, or create a file-main affinity binding while deciding whether a
// stored account is available; only the stored credential selected below may own Pool state.
const affinityKey = poolStateEligible(fixedAccountId, requestScopedMainCredential)
? codexPoolAffinityKey(headers)
: undefined;
// The thread's family relation, recorded under the same condition as the key itself. A
// first-placing child consults it; a request-owned or fixed credential never enters Pool
// state, so it never enters lineage either.
const lineage = affinityKey !== undefined
? recordCodexThreadLineage(headers)
: undefined;
// Why this request is on this account, carried to the request log so a move reads as an event
// instead of something inferred from account labels across lines (#4546).
let affinityDecision: CodexAffinityDecision | undefined;
// The half-open trial this request was granted, if it is the one allowed to test a held
// account. Declared out here because the release paths below and the returned context are on
// opposite sides of several throws (#4701).
let transientProbe: TransientProbeGrant | undefined;
const releaseTransientProbeGrant = (): void => {
if (!transientProbe) return;
releaseTransientProbe(transientProbe.lease);
transientProbe = undefined;
};
// Retained startup recovery makes the physical main identity ineligible. Routing
// can still preserve service by selecting a healthy configured pool account. A
// request-owned bearer likewise cannot inspect or reconcile file-main state.
const nativeMainTrafficBlocked = isNativeMainTrafficBlocked();
const selectionAdmission = options.beginCodexAccountSelection?.();
const nativeMainReadsForbidden = requestScopedMainCredential
|| nativeMainTrafficBlocked
|| selectionAdmission?.mainProfileDraining === true;
const nativeMainSelectionOnly = !nativeMainTrafficBlocked
&& selectionAdmission?.mainProfileDraining === true;
let accountId: string;
// Answering this with the manual-pin predicate made `codexAccountUnusableReason` report
// `main_credential_unavailable` for every UNPINNED request, so `getEligiblePoolAccounts` never
// listed main and the strategy compared only the stored accounts. With one stored sibling the
// pool degraded to "stored account until it cannot serve, then main", discarding the usage,
// priority and reset ordering the operator configured (#5019).
const requestOwnedMainCredentialLive = () => requestOwnedMainCredentialIsLive({
preserveRequestOwnedMainPin: preserveRequestOwnedMainPin(),
requestScopedMainCredential,
nativeMainTrafficBlocked,
mainProfileDraining: selectionAdmission?.mainProfileDraining === true,
// Keeps the cooled account as the selection when the caller owns it, so the refusal is still
// produced by the cooldown machinery below rather than by a second rule beside it.
callerOwnsCooledPoolSubscription: requestScopedMainCredential
&& callerOwnsAnyCooledPoolSubscription(headers, config, quotaScope),
});
try {
const excludeAccountIds = nativeMainReadsForbidden
? new Set([MAIN_CODEX_ACCOUNT_ID])
: undefined;
const mainModelGrantUnobserved = excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID) === true;
const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config, {
excludeAccountIds,
signal: options.signal,
nativeMainRefreshDependencies: options.nativeMainRefreshDependencies,
})
: undefined;
const entitledAccountIds = entitlementSnapshot
? entitledCodexAccountIdsForModel(entitlementSnapshot, options.modelId)
: undefined;
const modelEligibleAccountIds = entitledAccountIds
? new Set([...entitledAccountIds].filter(candidate => !excludeAccountIds?.has(candidate)))
: undefined;
// #4768: the flagships stay visible and never fail closed, so this is evidence routing may
// ORDER by, not evidence it may refuse on. Read synchronously from rosters discovery has
// already gathered -- no upstream fetch joins the request path for the most commonly
// requested models in the product -- and passed to selection as a preference that is dropped
// whenever honouring it would leave no candidate.
//
// Under the SAME exclusion the entitlement snapshot above uses. The reader validates each
// cached roster against the account's current credential, and for native main that is a
// synchronous read of the physical stored token -- exactly what this request is forbidden to
// touch while a profile switch drains it or while it is served by a request-owned credential.
// Excluding main here costs nothing: the preference is an ordering hint, so main becomes
// unknown rather than denied, and unknown leaves selection exactly as it was.
const deniedModelAccountIds = cachedDeniedCodexAccountIdsForModel(
options.modelId,
undefined,
{ excludeAccountIds },
);
const selectionOptions = {
// Temporary switch drain keeps the candidate until the atomic claim rejects
// it. Retained recovery makes main wholly ineligible so pool routing continues.
nativeMainSelectionOnly,
isMainAccountTokenLive: requestScopedMainCredential
// Main stays excluded from this request's model roster below, so an account-gated model
// still cannot be served from a candidacy this answer creates. Everything else -- pool
// eligibility, shared-state preservation, and a caller-owned pin surviving a model detour
// -- is answered without reading or selecting the physical main credential.
? requestOwnedMainCredentialLive
: options.isMainAccountTokenLive,
modelEligibleAccountIds,
deniedModelAccountIds,
requestOwnedMainCredential: requestScopedMainCredential,
// Request-scoped and deliberately absent from `sharedStateSelectionOptions`: one
// conversation's attachments say nothing about where unrelated threads should be served.
retainAccountForUploadedFiles: options.retainAccountForUploadedFiles === true,
};
// A pre-drain selector reserves the native identity while reconciliation and
// routing inspect it. Selectors arriving after the fence skip reconciliation
// and may still route to non-main pool accounts without touching switch state.
if (reserve && !nativeMainReadsForbidden && !selectionAdmission) throw new CodexMainProfileDrainingError();
if (!nativeMainReadsForbidden) reconcileMainCodexAccountRuntimeState();
// Annotated, not inferred. The two literals below carry neither `affinity` nor
// `transientProbe`, so an inferred union makes `"k" in resolution` widen those reads to
// `unknown` and a discriminant narrowing fail outright. Contextually typing every branch to
// the resolver's own union is what lets the reads below stay total.
const resolution: CodexThreadResolution = fixedAccountId !== undefined
? { status: "selected" as const, accountId: fixedAccountId }
: options.excludeAccountId
? (() => {
const selected = pickAlternateCodexAccount(
config,
options.excludeAccountId!,
Date.now(),
quotaScope,
selectionOptions,
);
return selected
? { status: "selected" as const, accountId: selected }
: { status: "none" as const };
})()
: resolveCodexAccountForThreadDetailed(
affinityKey ?? null,
config,
Date.now(),
quotaScope,
selectionOptions,
options.modelId,
lineage,
);
if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
// THE REFUSAL. Every candidate is held, the recovery budget is spent, and no detour is
// left -- so this request must not reach upstream at all. Returning the held account here
// is what #4701 is about: under a provider-wide 503 that is every bound request piling
// onto an account already known to be failing. Thrown before any credential is read, so
// nothing is sent and nothing is spent.
if (resolution.status === "withheld") {
throw new CodexRecoveryWithheldError(resolution.accountId, resolution.retryAt, resolution.detourAccountId);
}
const selected = resolution.status === "selected" ? resolution.accountId : null;
affinityDecision = resolution.affinity;
transientProbe = resolution.status === "selected" ? resolution.transientProbe : undefined;
// Main now takes part in ordering when the request carries its own main bearer (#5019), so
// selection can name it outright rather than only through the no-candidate fallback below.
// Serve that selection from the credential the request arrived with: the read fence above
// forbids this request from claiming, reading or reconciling the stored main profile, and a
// request-owned credential owns no Pool state, so there is nothing here to claim, prime or
// cool down. Hand back any trial first -- no Pool account is being sent to.
if (selected === MAIN_CODEX_ACCOUNT_ID && requestScopedMainCredential) {
releaseTransientProbeGrant();
return await resolveCallerOwnedMainContext();
}
if (!selected) {
// A retry that excluded a failed Pool account may still use the validated caller-owned
// main credential. Treating every exclusion as if main itself had failed strands a healthy
// native bearer after the first Pool attempt. Preserve the exactly-once boundary by refusing
// this fallback only when the excluded credential is main.
if (
requestScopedMainCredential
&& fixedAccountId === undefined
&& options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
) {
return await resolveCallerOwnedMainContext();
}
if (fixedAccountId !== undefined) {
if (modelEligibleAccountIds && !modelEligibleAccountIds.has(fixedAccountId)) {
throw new CodexModelAvailabilityError(
"unsupported",
"Selected Codex account does not support this model",
);
}
throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
}
// Recovery or a turn drain deliberately makes physical main unobservable.
// If no healthy pool route is available, report the temporary fence rather
// than turning a credential we were forbidden to inspect into a permanent
// model-entitlement denial.
// A configured pool retry/exclusion that finds no alternate preserves its
// ordinary pool-auth failure instead of being mislabeled as a main fence.
if (nativeMainReadsForbidden && !options.excludeAccountId) {
throw new CodexMainProfileDrainingError();
}
if (!nativeMainReadsForbidden && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
&& !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
&& (!modelEligibleAccountIds || modelEligibleAccountIds.has(MAIN_CODEX_ACCOUNT_ID))) {
assertMainAccountPolicy(policy);
}
if (modelEligibleAccountIds !== undefined) {
const unsupported = entitledAccountIds?.size === 0 && !mainModelGrantUnobserved;
throw new CodexModelAvailabilityError(
unsupported ? "unsupported" : "temporarily_unavailable",
unsupported
? "No eligible Codex account supports this model"
: "Codex accounts that support this model are currently unavailable",
);
}
throw new CodexPoolAuthenticationError();
}
accountId = selected;
if (accountId === MAIN_CODEX_ACCOUNT_ID) assertMainAccountPolicy(policy);
if (accountId === MAIN_CODEX_ACCOUNT_ID && nativeMainTrafficBlocked) {
throw new CodexMainProfileDrainingError();
}
if (
accountId === MAIN_CODEX_ACCOUNT_ID
&& selectionAdmission
&& !selectionAdmission.claimMainProfile()
) {
throw new CodexMainProfileDrainingError();
}
// Some legacy Pool fallbacks preserve a configured active account even when it is not
// currently selectable, so token/cooldown code can produce the historical actionable error.
// Model entitlement is different: sending the request would spend a turn on an account whose
// authenticated roster already denied the model. Reassert this boundary after every selector.
if (modelEligibleAccountIds && !modelEligibleAccountIds.has(accountId)) {
throw new CodexModelAvailabilityError(
"unsupported",
fixedAccountId !== undefined
? "Selected Codex account does not support this model"
: "No eligible Codex account supports this model",
);
}
if (fixedAccountId !== undefined) {
if (policy.pausedCodexAccountIds?.includes(accountId)) {
throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
}
if (isAccountNeedsReauth(accountId)) {
throw new CodexPoolAuthenticationError("Selected Codex account needs reauthentication");
}
if (!isCodexAccountUsable(config, accountId, selectionOptions)) {
throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
}
}
} catch (cause) {
// Selection granted a trial and then a later policy check refused the account. The trial
// never runs, so hand it back instead of leaving the held account unprobeable until its
// deadline lapses (#4701).
releaseTransientProbeGrant();
throw cause;
} finally {
selectionAdmission?.release();
}
// Legacy selectors may retain an unusable account for actionable errors. A
// deferred credential must never become request auth through that fallback.
try {
assertCodexAccountValidationReady(accountId);
} catch (cause) {
// Nothing will reach upstream, so give the trial back instead of leaving the held account
// unprobeable until the lease deadline lapses (#4701).
releaseTransientProbeGrant();
throw cause;
}
// Lazy prime: if the selected account has no quota yet, the pool is likely
// unprimed (dashboard never opened, or startup prime was blocked). Kick a
// best-effort prime so the NEXT routing decision has real scores. This never
// blocks the current request, and the helper's single-flight guard collapses
// repeated triggers into one pass. Opt-in priority failback also refreshes inactive
// accounts; that path has a five-minute attempt limit inside the prime helper.
const priorityFailback = codexAccountPriorityFailbackEnabled(config, accountId);
if (fixedAccountId === undefined && !nativeMainReadsForbidden
&& (!getAccountQuota(accountId) || priorityFailback)) {
const reason = priorityFailback ? "priority-failback" : "pre-route";
if (options.primeCodexPoolQuotas) {
void options.primeCodexPoolQuotas(config, reason).catch(() => {});
} else {
import("./auth-api")
.then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, reason))
.catch(() => {});
}
}
// Snapshot (not just the deadline) so a refused request can report WHY it is cooled:
// a literal Retry-After reads very differently to a user than a reset-derived guess.
const cooldown = getCodexQuotaHealthSnapshot(accountId, quotaScope);
const cooldownUntil = cooldown?.cooldownUntil;
// A transient-hold trial and a quota cooldown cannot both describe this account:
// `isTransientOnlyAffinityBlock` refuses to recognise a transient hold on an account carrying
// quota health, so the cooldown branch below is unreachable while a trial is held. That is
// also why no request pays two recovery permits for one send. The release is defensive --
// should that invariant ever move, the trial is handed back rather than stranded behind a
// refusal that belongs to the other domain.
if (cooldownUntil && transientProbe) releaseTransientProbeGrant();
// A cooled-down account never sends traffic, so upstream recovery can never be
// observed and the cooldown outlives the real limit. Admit one probe per
// interval; its outcome decides whether the cooldown ends (#433).
let probeLeaseId: string | undefined;
let probeQuotaScope: CodexQuotaScope | undefined;
if (cooldownUntil) {
// Exact bindings are not Pool recovery traffic. Fail closed instead of consuming the Pool's
// one probe lease or selecting another account.
if (fixedAccountId !== undefined) {
throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
}
probeQuotaScope = cooldown?.quotaScope;
probeLeaseId = probeQuotaScope
? tryAcquireCodexQuotaScopeProbeLease(accountId, probeQuotaScope) ?? undefined
: tryAcquireCodexQuotaProbeLease(accountId) ?? undefined;
if (!probeLeaseId) {
// The selector can retain the configured Pool account when no stored
// alternate is eligible. A validated caller may still serve this request,
// just as it can after an upstream rejection, without changing Pool state.
if (requestScopedMainCredential && fixedAccountId === undefined
&& options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
&& !callerIsCooledPoolAccount(headers, config, accountId)) {
return await resolveCallerOwnedMainContext();
}
throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
}
}
if (accountId === MAIN_CODEX_ACCOUNT_ID) {
// Main account in rotation: refresh auth.json before upstream I/O and fail closed if it vanished.
let token: { accessToken: string; chatgptAccountId: string } | null;
let mainQuotaWriter = captureObservedMainWriter();
try {
token = await (options.getValidMainAccountToken ?? getValidMainAccountToken)({
signal: options.signal,
...(options.nativeMainRefreshDependencies ?? {}),
});
if (token) mainQuotaWriter = observeSelectedMainCredential(token, mainQuotaWriter);
assertMainAccountPolicy(policy);
} catch (cause) {
releaseTransientProbeGrant();
if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
if (cause instanceof CodexMainAccountHardLockError) throw cause;
if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
markAccountNeedsReauth(accountId, writerGeneration);
}
throw new CodexAuthContextError(accountId, cause);
}
if (!token) {
// Nothing will reach upstream, so give the probe back instead of burning it.
releaseTransientProbeGrant();
if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
throw new CodexPoolAuthenticationError(
fixedAccountId !== undefined ? "Selected Codex account is unavailable" : undefined,
);
}
let reserveAuthorization: MainReserveAuthorization | undefined;
try {
reserveAuthorization = reserve
? await authorizeReserveCredential(token, mainQuotaWriter, policy, options.signal, undefined, writerGeneration)
: undefined;
} catch (cause) {
// A Reserve refusal ends the request here, so the trial it was holding never runs.
releaseTransientProbeGrant();
throw cause;
}
return {
kind: "main-pool",
accountId,
writerGeneration,
mainQuotaWriter,
...(reserveAuthorization ? { reserveAuthorization } : {}),
accessToken: token.accessToken,
chatgptAccountId: token.chatgptAccountId,
...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
...(affinityKey ? { affinityKey } : {}),
...(quotaScope ? { quotaScope } : {}),
...(probeLeaseId ? { probeLeaseId } : {}),
...(probeQuotaScope ? { probeQuotaScope } : {}),
...(transientProbe ? { transientProbe } : {}),
};
}
try {
const token = await getValidCodexToken(accountId, { signal: options.signal });
assertCodexAccountValidationReady(accountId);
return {
kind: "pool",
accountId,
writerGeneration,
generation: token.generation,
poolQuotaWriter: capturePoolQuotaWriter(accountId, token),
accessToken: token.accessToken,
chatgptAccountId: token.chatgptAccountId,
...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
...(affinityKey ? { affinityKey } : {}),
...(quotaScope ? { quotaScope } : {}),
...(probeLeaseId ? { probeLeaseId } : {}),
...(probeQuotaScope ? { probeQuotaScope } : {}),
...(affinityDecision ? { affinityDecision } : {}),
...(transientProbe ? { transientProbe } : {}),
};
} catch (cause) {
releaseTransientProbeGrant();
if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
markAccountNeedsReauth(accountId, writerGeneration);
}
throw new CodexAuthContextError(accountId, cause);
}
}
export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefined): void {
if (ctx?.kind !== "pool" && ctx?.kind !== "main-pool") return;
// A context holding the probe lease was deliberately admitted through the cooldown.
if (ctx.probeLeaseId) return;
const cooldown = getCodexQuotaHealthSnapshot(ctx.accountId, ctx.quotaScope);
if (cooldown?.cooldownUntil) {
throw new CodexAccountCooldownError(ctx.accountId, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope);
}
}
export function applyCodexAuthContextToProvider(
provider: OcxProviderConfig,
ctx: CodexAuthContext,
mode: CodexAccountMode | undefined,
): OcxRuntimeProviderConfig {
if (mode !== "pool" || (ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
assertCodexAccountValidationReady(ctx.accountId);
return {
...provider,
_codexAccountOverride: {
accessToken: ctx.accessToken,
chatgptAccountId: ctx.chatgptAccountId,
},
_codexAccountRequired: true,
};
}
export class CodexMainSubstitutionUnavailableError extends Error {
constructor() {
super("No usable Codex main credential to substitute for an admission bearer");
this.name = "CodexMainSubstitutionUnavailableError";
}
}
/**
* Build the upstream auth headers for one Codex turn.
*
* The two credential domains meet here, and only here:
*
* - `pool` / `main-pool` always OVERWRITE with the stored account credential. Whatever the
* caller sent is irrelevant to what we send upstream.
* - `main` with an admission-bearer caller (#1686) must substitute the stored main credential.
* The caller proved admission with one of OUR secrets, which must never leave the process, so
* the only two acceptable outcomes are replaced-with-stored-main or fail-before-any-IO.
* Silently forwarding would be the leak validateForwardAdmissionCredential exists to prevent.
* - `main` with a dedicated-header caller keeps the existing intentional passthrough: the bearer
* there is the user's own ChatGPT credential, not ours.
*/
export function materializeCodexUpstreamAuth(
headers: Headers,
ctx: CodexAuthContext,
options: CodexAuthMaterializationOptions = {},
): Headers {
const selected = new Headers();
for (const name of FORWARD_HEADERS) {
const value = headers.get(name);
if (value) selected.set(name, value);
}
if (ctx.kind === "pool" || ctx.kind === "main-pool") {
assertCodexAccountValidationReady(ctx.accountId);
selected.set("authorization", `Bearer ${ctx.accessToken}`);
selected.set("chatgpt-account-id", ctx.chatgptAccountId);
if (ctx.kind === "main-pool") {
ctx.mainQuotaWriter = observeSelectedMainCredential(ctx, ctx.mainQuotaWriter);
assertMainAccountPolicy(options.config);
}
assertMaterializedReserve(selected, ctx, options);
return selected;
}
if (ctx.kind === "main" && options.substituteMainCredential !== true
&& !selected.has("chatgpt-account-id")) {
const bearer = selected.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
const accountId = bearer ? extractAccountId(undefined, bearer) : undefined;
if (accountId) selected.set("chatgpt-account-id", accountId);
}
if (ctx.kind === "main" && options.substituteMainCredential === true) {
// No config object is "no policy input", not the persisted opt-out: only a config that
// actually says `false` disables the default-on lock (#5694).
if (options.config !== undefined && isMainAccountHardLockEnabled(options.config)) {
reconcileMainCodexAccountRuntimeState();
}
const writer = captureObservedMainWriter();
const stored = getMainAccountToken();
// Fail BEFORE any upstream I/O. Falling through here would send the admission secret.
if (!stored?.accessToken || !isMainAccountTokenLive()) {
throw new CodexMainSubstitutionUnavailableError();
}
selected.delete("chatgpt-account-id");
selected.set("authorization", `Bearer ${stored.accessToken}`);
if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
observeSelectedMainCredential(stored, writer);
assertMainAccountPolicy(options.config);
assertMaterializedReserve(selected, ctx, options);
return selected;
}
if (callerMatchesObservedMain(selected)) assertMainAccountPolicy(options.config);
assertMaterializedReserve(selected, ctx, options);
return selected;
}
/** The model producer, not an optional context marker, decides whether a grant is required. */
async function materializeReserveUpstreamAuth(
headers: Headers,
ctx: CodexAuthContext,
options: CodexAuthMaterializationOptions,
): Promise<Headers> {
if (ctx.kind === "pool") throw new CodexReserveUnavailableError();
const config = options.config!;
assertReserveAdmission(config);
const writerGeneration = ctx.kind === "main-pool" ? ctx.writerGeneration : captureConfigGeneration();
const storedMain = ctx.kind === "main"
&& (options.substituteMainCredential === true || !hasCallerCodexBearer(headers));
let admission: CodexAccountSelectionAdmission | undefined;
let writer = ctx.kind === "main-pool" ? ctx.mainQuotaWriter : undefined;
try {
if (storedMain) {
if (isNativeMainTrafficBlocked()) throw new CodexMainProfileDrainingError();
admission = options.beginCodexAccountSelection?.();
if (!admission || admission.mainProfileDraining || !admission.claimMainProfile() || isNativeMainTrafficBlocked()) {
throw new CodexMainProfileDrainingError();
}
reconcileMainCodexAccountRuntimeState();
writer = captureObservedMainWriter();
assertReserveAdmission(config);
}
// Build the real credential first, without recursively requiring a not-yet-fetched proof.
// The ordinary hard lock remains enabled, including the post-refresh check.
const selected = await materializeCodexUpstreamAuthAsync(headers, ctx, {
...options, modelId: undefined, substituteMainCredential: storedMain,
});
const token = selectedCodexToken(selected);
if (ctx.kind === "main-pool") writer = ctx.mainQuotaWriter;
else if (!storedMain) writer = captureMainQuotaWriter(token.chatgptAccountId);
ctx.reserveAuthorization = await authorizeReserveCredential(token, writer, config, options.signal,
ctx.reserveAuthorization, writerGeneration);
assertMaterializedReserve(selected, ctx, options);
return selected;
} finally {
admission?.release();
}
}
export async function materializeCodexUpstreamAuthAsync(
headers: Headers,
ctx: CodexAuthContext,
options: CodexAuthMaterializationOptions = {},
): Promise<Headers> {
if (requiresReserveAuthorization(options.config, options.modelId, options.admission)) {
return materializeReserveUpstreamAuth(headers, ctx, options);
}
if (ctx.kind !== "main" || options.substituteMainCredential !== true) {
return materializeCodexUpstreamAuth(headers, ctx, options);
}
const selected = new Headers();
for (const name of FORWARD_HEADERS) {
const value = headers.get(name);
if (value) selected.set(name, value);
}
if (options.config !== undefined && isMainAccountHardLockEnabled(options.config)) {
reconcileMainCodexAccountRuntimeState();
}
const writer = captureObservedMainWriter();
const stored = await getValidMainAccountToken({
signal: options.signal,
...(options.nativeMainRefreshDependencies ?? {}),
});
if (!stored?.accessToken) throw new CodexMainSubstitutionUnavailableError();
selected.delete("chatgpt-account-id");
selected.set("authorization", `Bearer ${stored.accessToken}`);
if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
observeSelectedMainCredential(stored, writer);
assertMainAccountPolicy(options.config);
// An opt-in enabled during token refresh must not turn a proof-less context into Reserve.
assertMaterializedReserve(selected, ctx, options);
return selected;
}
/** @deprecated Prefer materializeCodexUpstreamAuth; kept for call sites without admission context. */
export function headersForCodexAuthContext(
headers: Headers,
ctx: CodexAuthContext,
config?: CodexAuthPolicyConfig,
modelId?: string,
admission?: Pick<DataPlaneAdmission, "source">,
): Headers {
return materializeCodexUpstreamAuth(headers, ctx, { config, modelId, admission });
}
export function isCodexAuthContextUsable(ctx: CodexAuthContext, config: OcxConfig): boolean {
if (ctx.kind === "main") return true;
if (ctx.kind === "main-pool") return isCodexAccountUsable(config, ctx.accountId);
return isCodexAccountUsable(config, ctx.accountId) && isCodexAccountGenerationLive(ctx.accountId, ctx.generation);
}
export function stripCodexRuntimeProviderFields(provider: OcxProviderConfig): OcxProviderConfig {
const {
_codexAccountOverride: _override,
_codexAccountRequired: _required,
...safeProvider
} = provider as OcxRuntimeProviderConfig;
return safeProvider;
}