@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,693 lines • 79.3 kB
text/typescript
import { createHash } from "node:crypto";
import { readBoundedResponseBody } from "../lib/bounded-body";
import type { CodexAccountCredentialRecord, OcxConfig } from "../types";
import { isSelectableCodexPoolAccount } from "./account-id";
import {
beginCodexAccountGenerationLiveCheck,
getValidCodexToken,
loadCodexAccountRecordSnapshot,
} from "./account-store";
import {
getMainAccountToken,
getValidMainAccountToken,
MAIN_CODEX_ACCOUNT_ID,
type NativeMainRefreshDependencies,
} from "./main-account";
import { withNativeMainCredentialAdmission } from "./native-main-admission";
import {
ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
NATIVE_GPT6_ASTRA_MODEL,
} from "./catalog/native-models";
import { loadPersistedCodexRuntime } from "./runtime";
import { codexRuntimeStateEpoch } from "./runtime";
import { recordDiscoveredNativeModels, validateDiscoveredNativeRows } from "./catalog/discovered-natives";
import { pinnedNativeModelRows } from "./catalog/pinned-models";
import { codexCredentialMutationEpoch } from "./credential-mutation-epoch";
import {
clearObservedCodexModelDenial,
forgetObservedCodexModelDenialsForAccount,
observedDeniedCodexAccountIdsForModel,
recordObservedCodexModelDenial,
setObservedDenialGenerationCheck,
resetObservedCodexModelDenialsForTests,
} from "./observed-model-denials";
const CODEX_MODELS_ENDPOINT = "https://chatgpt.com/backend-api/codex/models";
/**
* Upstream filters this roster by the client version it is told, and `client_version` is a
* required parameter — a measured `0.60.0` returns zero models where `0.142.2` returns five
* (devlog/_fin/260817_native_gpt56_1m_context/001_measurement_evidence.md). Asking as
* `0.0.0` therefore describes what a prehistoric client may use, and treating that as the
* account's entitlement hides models the account genuinely owns (#2886).
*
* A version must be supplied by the caller. There is deliberately no default: inventing one
* either manufactures a confirmed negative (the defect) or advertises models the installed
* runtime cannot drive (#2548, from the opposite side).
*/
function codexModelsUrl(clientVersion: string): string {
return `${CODEX_MODELS_ENDPOINT}?client_version=${encodeURIComponent(clientVersion)}`;
}
/** A version string upstream can filter on. Rejects empty and the `0.0.0` placeholder. */
export function isUsableCodexClientVersion(value: string | null | undefined): value is string {
if (typeof value !== "string") return false;
const trimmed = value.trim();
if (!trimmed || trimmed === "0.0.0") return false;
// Bounded: the value reaches an outbound URL, and no real client version is this long.
if (trimmed.length > 64) return false;
if (!/^\d+(\.\d+)*([-+][0-9A-Za-z.-]+)?$/.test(trimmed)) return false;
// An all-zero numeric core is the same claim `0.0.0` makes — a client predating every gated
// model — so `0`, `0.0`, `00.0.0`, and `0.0.0-dev` must fail for the same reason, by value
// rather than by exact string.
const core = trimmed.split(/[-+]/, 1)[0]!;
if (core.split(".").every(segment => Number(segment) === 0)) return false;
return true;
}
/**
* Highest `minimal_client_version` this build's bundled roster records for the models that
* are account-gated. Derived, not hardcoded: if the snapshot is refreshed with a model that
* requires a newer client, the floor follows it, so the two can never drift apart.
*
* Used only as the last tier of version precedence, for background work that has no request
* and no resolved runtime to speak for. It answers "what does this build believe the gated
* models need?", which is a claim the repository can actually substantiate.
*/
export function deriveGatedClientVersionFloor(
rows: ReadonlyArray<Record<string, unknown>>,
gatedSlugs: ReadonlySet<string> = ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
): string | null {
const floors = rows
.filter(row => typeof row.slug === "string" && gatedSlugs.has(row.slug))
.map(row => (typeof row.minimal_client_version === "string" ? row.minimal_client_version : null))
.filter((value): value is string => isUsableCodexClientVersion(value));
return floors.reduce<string | null>(
(best, candidate) => (best === null || compareClientVersions(candidate, best) > 0 ? candidate : best),
null,
);
}
/**
* Lowest `client_version` MEASURED to actually return the account-gated rows.
*
* The bundled snapshot was not sufficient on its own. Until the 2026-09-23 re-pin it recorded
* `0.142.2` for the gpt-5.6 rows (upstream now records `0.144.0`), and `0.142.2` is a version
* upstream answers with 200 and five models, none of them gpt-5.6; `0.144.0` and above answer
* with the gated rows present
* (devlog/_fin/260817_native_gpt56_1m_context/001_measurement_evidence.md, independently
* reproduced by the #2886 and #3022 reporters). So a floor derived from the snapshot alone
* asks a question whose honest answer is an empty gated set — and the fail-closed gate then
* reads that absence as a confirmed denial, which is how 2.36.0 removed sol/terra/luna from
* accounts that own them (#3022).
*
* This is a measurement, not a preference, which is why it composes with the derivation
* instead of replacing it: see `composeGatedClientVersionFloor`.
*/
const MEASURED_GATED_CLIENT_VERSION_MINIMUM = "0.144.0";
/**
* Lowest versions measured to return each account-gated model when the account owns it.
*
* This is deliberately independent of the bundled upstream snapshot, which can lag or lead the
* live roster: live measurements show that upstream omits sol/terra/luna below 0.144.0.
* Daybreak's shipped row records 0.142.2 and has no independent measured minimum, so its omission remains
* authoritative instead of inheriting a guessed floor from another model.
*/
export const ACCOUNT_GATED_NATIVE_MODEL_MINIMUM_CLIENT_VERSIONS: ReadonlyMap<string, string> = new Map([
["gpt-5.6-sol", MEASURED_GATED_CLIENT_VERSION_MINIMUM],
["gpt-5.6-terra", MEASURED_GATED_CLIENT_VERSION_MINIMUM],
["gpt-5.6-luna", MEASURED_GATED_CLIENT_VERSION_MINIMUM],
]);
/**
* Fallback when the snapshot records no usable gated floor.
*
* Not every gated slug is guaranteed a `minimal_client_version` — `gpt-daybreak-blue-latest` had
* no row until the 2026-09-23 re-pin — so the derivation can legitimately come back empty as the
* gated set changes. This is the last resort behind it, and it is still a version upstream can
* filter on rather than the placeholder that caused #2886.
*/
const GATED_MODEL_CLIENT_VERSION_FLOOR_FALLBACK = "0.142.2";
/**
* The floor actually used: the highest of what the snapshot derives, what we have measured
* upstream to honour, and the fallback.
*
* Composed rather than hardcoded so the two sources cannot drift into a contradiction. The
* snapshot may raise the floor; it may never lower it below a measurement. When a future
* snapshot refresh records `0.144.0` or higher, the derivation takes over naturally and
* `MEASURED_GATED_CLIENT_VERSION_MINIMUM` goes inert instead of fighting it.
*/
function composeGatedClientVersionFloor(
rows: ReadonlyArray<Record<string, unknown>>,
gatedSlugs: ReadonlySet<string> = ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
): string {
const derived = deriveGatedClientVersionFloor(rows, gatedSlugs) ?? GATED_MODEL_CLIENT_VERSION_FLOOR_FALLBACK;
return compareClientVersions(derived, MEASURED_GATED_CLIENT_VERSION_MINIMUM) >= 0
? derived
: MEASURED_GATED_CLIENT_VERSION_MINIMUM;
}
// Reads every pinned row (codex-rs snapshot plus roster-captured rows), so a gated slug whose row
// arrives through roster-pinned-models.json still contributes its floor. None does today:
// gpt-6-sol/luna and gpt-6.1-sol are ungated, and gpt-6-astra-minor has no row and no measured minimum.
export const GATED_MODEL_CLIENT_VERSION_FLOOR: string = composeGatedClientVersionFloor(
pinnedNativeModelRows(),
);
/** Test-only seam: the composition on synthetic rows, so both directions can be proven. */
export function composeGatedClientVersionFloorForTests(
rows: ReadonlyArray<Record<string, unknown>>,
gatedSlugs?: ReadonlySet<string>,
): string {
return composeGatedClientVersionFloor(rows, gatedSlugs);
}
/** Test-only seam: the ordering the floor composition relies on. */
export function compareClientVersionsForTests(left: string, right: string): number {
return compareClientVersions(left, right);
}
/** Numeric-segment comparison. Only used to pick the highest floor in a known-good set. */
// Prerelease and build suffixes are deliberately NOT ordered. Splitting on [.+-] turns the
// suffix into a non-finite segment that reads as 0, so `0.144.0-rc.1` sorts at or above
// `0.144.0` rather than below it, the inverse of semver. That is tolerable because every
// version this ranks against is a release version: the gated floor, the measured minimum, and
// the snapshot's `minimal_client_version` rows. A prerelease runtime is therefore passed
// through exactly as it was before the floor bound tier 2, so this is not a new hazard. Order
// the suffix properly before reusing this anywhere a prerelease has to sort below its release.
function compareClientVersions(left: string, right: string): number {
const l = left.split(/[.+-]/).map(Number);
const r = right.split(/[.+-]/).map(Number);
for (let i = 0; i < Math.max(l.length, r.length); i += 1) {
const a = Number.isFinite(l[i]) ? l[i]! : 0;
const b = Number.isFinite(r[i]) ? r[i]! : 0;
if (a !== b) return a - b;
}
return 0;
}
/**
* Version authority, in precedence order:
*
* 1. the inbound request's own `client_version` — the only value certainly describing the
* client being answered;
* 2. the selected Codex runtime version, for callers with no request of their own — but never
* below `GATED_MODEL_CLIENT_VERSION_FLOOR`. Retained sync refreshes runtime evidence before
* discovery, which is what makes this usable here; the persisted file itself carries no
* freshness guarantee.
* 3. the floor this build's own bundled roster records for the models being gated
* (`GATED_MODEL_CLIENT_VERSION_FLOOR`).
*
* Tier 3 exists because background catalog sync has no request and, on a host where Codex
* has never been resolved, no persisted runtime either — yet it is exactly the path that
* publishes account-confirmed native rows. Skipping discovery there suppressed the rows this
* fix is meant to restore. The floor is not invented: it is the version this build's own
* snapshot states the gated models require, so asking under it is the narrowest question
* that can still return them.
*
* The floor binds tier 2 as well, and that is the whole of #3436. #3022 gave tier 3 the
* measured minimum but left tier 2 to speak for itself, so a host whose persisted runtime was
* REAL but OLD — 0.141.0 against a measured 0.144.0 — asked upstream under a version upstream
* filters on, got an honest roster with no gpt-5.6, and lost sol/terra/luna everywhere. That
* made an outdated CLI strictly worse than no CLI at all, since the runtime-less host already
* asked at the floor and kept its models. The clamp only ever raises: a runtime at or above
* the floor is preserved exactly, because a newer client can drive models the floor cannot
* name.
*
* Which tier answers is a question about WHICH QUESTION IS BEING ASKED, not about background
* versus request path — `isDirectCallerEntitledToCodexModel` and both authorization paths in
* `auth-context.ts` are inbound requests that reach tier 2 because they carry no version:
*
* - No inbound version: the caller is asking whether the ACCOUNT owns the model. Upstream
* only incidentally filters that answer by version, so ask at no less than the floor.
* - An inbound version: the caller is asking what THAT CLIENT may use. Answer verbatim, even
* when it is older than the floor. Clamping there would advertise rows the client told us
* it cannot drive (#2548) and would turn an honest `unknown` into a cached `denied`.
*
* There is deliberately no `0.0.0`-style fallback. A placeholder describes a client that
* predates every gated model, which is what made upstream answer with an empty roster and
* turned absent evidence into a manufactured confirmed negative (#2886).
*/
export function resolveCodexEntitlementClientVersion(
inbound?: string | null,
loadRuntime: () => { selectedVersion?: string | null } | null = loadPersistedCodexRuntime,
options: { readonly bypassRuntimeMemo?: boolean; readonly now?: number } = {},
): string {
if (isUsableCodexClientVersion(inbound)) return inbound.trim();
// The memo describes the real runtime file, so a caller supplying a different loader is asking
// a different question and must not be answered from it. Detected rather than left to the
// caller, because forgetting the flag would silently cross-answer.
const bypass = options.bypassRuntimeMemo === true || loadRuntime !== loadPersistedCodexRuntime;
const selected = bypass
? readRuntimeVersion(loadRuntime)
: memoizedPersistedRuntimeVersion(loadRuntime, options.now ?? Date.now());
return raisedToGatedFloor(selected);
}
/**
* The gated floor as a lower bound rather than a fallback.
*
* Applied only on the way out of the resolver. `readRuntimeVersion` and
* `memoizedPersistedRuntimeVersion` keep reporting what is actually on disk, because
* `selectedVersion` is probe evidence that runtime identity, catalog cache keys,
* `X-Codex-Version` and install provenance all read for their own reasons. Clamping the
* persisted value itself would corrupt every one of them to fix one question.
*/
function raisedToGatedFloor(selected: string | null): string {
if (selected === null) return GATED_MODEL_CLIENT_VERSION_FLOOR;
return compareClientVersions(selected, GATED_MODEL_CLIENT_VERSION_FLOOR) >= 0
? selected
: GATED_MODEL_CLIENT_VERSION_FLOOR;
}
const MODEL_ROSTER_TTL_MS = 5 * 60_000;
/**
* How long a persisted-runtime version read is reused.
*
* Tier 2 of the version chain reads `codex-runtime.json` from disk, and it is consulted on
* every gated Direct authorization and every `/v1/models` resolution — including when the
* five-minute roster cache is hot, so the entitlement answer needs no I/O at all. Left
* unmemoized that is a synchronous `readFileSync` on the request path under concurrent gated
* traffic. `persistCodexRuntime` is the only writer, and it clears the runtime's own resolve
* cache; this window is short enough that a runtime switch is picked up promptly either way.
*/
const RUNTIME_VERSION_MEMO_MS = 5_000;
let runtimeVersionMemo: { at: number; epoch: number; version: string | null } | null = null;
function readRuntimeVersion(
loadRuntime: () => { selectedVersion?: string | null } | null,
): string | null {
try {
const value = loadRuntime()?.selectedVersion;
return isUsableCodexClientVersion(value) ? value.trim() : null;
} catch {
// An unreadable or malformed runtime file is an absent version, not a failure worth
// propagating into entitlement resolution.
return null;
}
}
function memoizedPersistedRuntimeVersion(
loadRuntime: () => { selectedVersion?: string | null } | null,
now: number,
): string | null {
const epoch = codexRuntimeStateEpoch();
// Time bounds staleness; the epoch makes a runtime switch invalidate this immediately, so the
// window can never answer under the version that was just replaced.
if (
runtimeVersionMemo
&& runtimeVersionMemo.epoch === epoch
&& now - runtimeVersionMemo.at < RUNTIME_VERSION_MEMO_MS
) {
return runtimeVersionMemo.version;
}
const selected = readRuntimeVersion(loadRuntime);
runtimeVersionMemo = { at: now, epoch, version: selected };
return selected;
}
const MODEL_ROSTER_FAILURE_TTL_MS = 15_000;
const MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS = 5_000;
const MODEL_ROSTER_TIMEOUT_MS = 8_000;
const MODEL_ROSTER_MAX_BYTES = 2 * 1024 * 1024;
const MODEL_ROSTER_CACHE_MAX = 64;
/**
* Versions retained per account.
*
* `client_version` arrives on the inbound `/v1/models` request, so making it part of the cache
* key handed callers a knob on key cardinality. With a flat per-key budget, one account cycling
* 64 versions filled its whole class and pushed other accounts' confirmed grants out — the same
* fail-closed catalog flapping the two-class budget exists to prevent, reached by a different
* axis. A handful of versions per account is all any real deployment needs (a client, a runtime,
* the floor), and the budget below counts ACCOUNTS so one noisy account cannot spend another's
* share.
*/
const MODEL_ROSTER_VERSIONS_PER_ACCOUNT_MAX = 4;
/**
* Concurrent roster requests allowed per account.
*
* The cache is bounded on write, but an in-flight request is not a cache entry: distinct
* `client_version` values miss the flight key by design, so a caller cycling versions could open
* arbitrarily many concurrent upstream requests, each holding an eight-second timer. This bounds
* the concurrency itself. Exceeding it is reported as unconfirmed — the same fail-closed answer a
* discovery failure produces, and cheaper than either queueing or serving another version's
* roster.
*/
const MODEL_ROSTER_FLIGHTS_PER_ACCOUNT_MAX = 4;
/**
* Distinct caller-selected roster versions admitted per account in one roster window.
*
* The cache budget and the flight budget both bound STATE, not WORK. A caller that cycles
* `client_version` and waits for each answer misses the cache by design and misses the flight
* key by design, so it can renew an authenticated upstream request under EVERY stored account
* token as often as it likes, and the gated-model checks it displaces fail closed while it does.
*
* DISTINCT VERSIONS are counted, never attempts. One legitimate client retrying a single version
* through an upstream outage comes back every 15s on the failure TTL; charging each attempt would
* spend the whole allowance on that one version and then refuse it for the rest of the 5-minute
* window, turning a recovered upstream into several more minutes without gated models.
*/
const MODEL_ROSTER_VERSION_MISSES_PER_ACCOUNT_MAX = 4;
interface AccountVersionMissBudget {
credentialIdentity: string;
/** Version -> when this version stops occupying the allowance. */
versions: Map<string, number>;
}
/**
* One row per ACCOUNT, not per credential identity.
*
* A Pool access-token refresh increments the generation, so an identity-keyed map would gain a
* permanent row per generation for the lifetime of the process: a protection against renewable
* work would have introduced an unbounded cache. A generation change replaces the row instead,
* which is also the right budget semantics — new credential, new allowance.
*/
const accountModelsMisses = new Map<string, AccountVersionMissBudget>();
const DIRECT_CALLER_ACCOUNT_PREFIX = "__direct_codex__:";
export interface CodexModelEntitlementCredentialSnapshot {
readonly accountId: string;
readonly accessToken: string;
readonly chatgptAccountId: string;
/** Stable local identity for rejecting a catalog commit after credential replacement. */
readonly credentialIdentity: string;
}
export type CodexModelEntitlementProvenance =
| { readonly kind: "parsed-empty" }
| { readonly kind: "http-error"; readonly httpStatus: number }
| { readonly kind: "network-error" }
| { readonly kind: "timeout" }
| { readonly kind: "unparseable" };
export type CodexModelEntitlementStatus =
| { readonly status: "unavailable" }
| { readonly status: "fresh" }
| { readonly status: "unconfirmed-empty" }
| { readonly status: "failed"; readonly reason: "http-error"; readonly httpStatus: number }
| {
readonly status: "failed";
readonly reason: Exclude<CodexModelEntitlementProvenance["kind"], "parsed-empty" | "http-error">;
readonly httpStatus?: never;
}
| { readonly status: "expired-refresh-in-flight" };
interface CachedAccountModels {
readonly credentialIdentity: string;
/**
* Client version this roster was fetched under. Upstream filters by it, so a roster is
* only an answer for that version — an entry fetched under one must never satisfy a read
* for another (#2886).
*/
readonly clientVersion: string;
readonly expiresAt: number;
readonly models: ReadonlySet<string>;
readonly accessProgramsByModel?: ReadonlyMap<string, CodexAvailableAccessPrograms>;
readonly availabilityNuxByModel?: ReadonlyMap<string, { message: string }>;
readonly confirmed: boolean;
readonly provenance?: CodexModelEntitlementProvenance;
}
export interface CodexModelEntitlementSnapshot {
readonly modelsByAccount: ReadonlyMap<string, ReadonlySet<string>>;
readonly accessProgramsByAccount?: ReadonlyMap<string, ReadonlyMap<string, CodexAvailableAccessPrograms>>;
readonly availabilityNuxByAccount?: ReadonlyMap<string, ReadonlyMap<string, { message: string }>>;
readonly clientVersionByAccount: ReadonlyMap<string, string>;
readonly confirmedAccountIds: ReadonlySet<string>;
readonly credentialIdentities: ReadonlyMap<string, string>;
}
export type CodexAvailableAccessPrograms = Readonly<Record<string, readonly string[]>> | null;
export type CodexModelEntitlementState = "granted" | "denied" | "unknown";
export interface CodexModelEntitlementResolveOptions {
readonly fetcher?: typeof fetch;
/**
* Client version to ask upstream about. Absent means no trustworthy version was
* available, and discovery is skipped rather than asked under a placeholder.
*/
readonly clientVersion?: string | null;
/**
* Test-only seam for the persisted-runtime half of the version precedence chain, so a case
* can reach the no-trustworthy-version branch without depending on the host's own runtime
* state file.
*/
readonly loadPersistedRuntime?: () => { selectedVersion?: string | null } | null;
readonly nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
readonly now?: number;
readonly signal?: AbortSignal;
/** Test-only credential seam; production callers enumerate local main + Pool credentials. */
readonly credentials?: readonly CodexModelEntitlementCredentialSnapshot[];
/** Test-only seam for proving lifecycle exclusions happen before credential reads. */
readonly credentialSnapshot?: typeof accountCredentialSnapshot;
/** Accounts whose credentials must not be read while another lifecycle owns them. */
readonly excludeAccountIds?: ReadonlySet<string>;
/** Ensure-only fence; ordinary request resolvers retain their established flight identity. */
readonly credentialMutationEpoch?: number;
/**
* Internal plumbing from `withNativeMainCredentialAdmission`: releases the
* native-main lifecycle lease once the credential phase settles, before any
* upstream roster fetch, so a profile drain never waits on network work.
*/
readonly releaseNativeMainCredentialLease?: () => void;
}
export interface CodexEntitlementFreshnessOptions extends Pick<
CodexModelEntitlementResolveOptions,
| "clientVersion"
| "credentialSnapshot"
| "fetcher"
| "loadPersistedRuntime"
| "nativeMainRefreshDependencies"
| "now"
| "signal"
> {
readonly waitMs?: number;
/** Test seam for the native-main admission fence around the refresh workset. */
readonly nativeMainCredentialAdmission?: typeof withNativeMainCredentialAdmission;
}
const accountModelsCache = new Map<string, CachedAccountModels>();
const accountModelsFlights = new Map<string, Promise<CachedAccountModels>>();
interface NegativeCredentialMemo {
readonly credentialIdentity: string | null;
readonly mutationEpoch: number;
readonly expiresAt: number;
}
interface EntitlementEnsureFlight {
readonly startedAt: number;
readonly promise: Promise<void>;
readonly clientVersion: string;
readonly identityVector: ReadonlyMap<string, string | null>;
readonly workset: readonly string[];
}
const negativeCredentialMemo = new Map<string, NegativeCredentialMemo>();
const entitlementEnsureFlights = new Map<string, EntitlementEnsureFlight>();
/**
* Cache key. The roster is version-specific, so the version has to be part of the identity —
* with an account-only key, two versions in flight for one account race to overwrite each
* other, and the unversioned projection readers in `catalog/metadata.ts` then publish
* whichever landed last.
*/
function cacheKeyFor(accountId: string, clientVersion: string): string {
return `${accountId}\u0000${clientVersion}`;
}
/** Account component of a cache key, for eviction budgets and per-account invalidation. */
function accountIdOfCacheKey(key: string): string {
const separator = key.indexOf("\u0000");
return separator === -1 ? key : key.slice(0, separator);
}
/**
* Direct-caller entries are evicted separately from main/Pool entries.
*
* Direct keys are per-credential (`__direct_codex__:<hash>`) and unbounded in practice, while
* main/Pool keys are the evidence the CATALOG projects from. Sharing one LRU let 64 distinct
* Direct callers evict `__main__` and the Pool accounts, which makes the gated row vanish from
* the catalog until rediscovery — fail-closed flapping rather than a leak, but still a visible
* model disappearing for a reason the operator cannot see. Two budgets keep one class of caller
* from erasing the other's evidence.
*/
function boundedCacheSet(accountId: string, value: CachedAccountModels): void {
const key = cacheKeyFor(accountId, value.clientVersion);
accountModelsCache.delete(key);
accountModelsCache.set(key, value);
const isDirect = (candidate: string): boolean =>
accountIdOfCacheKey(candidate).startsWith(DIRECT_CALLER_ACCOUNT_PREFIX);
// First, bound THIS account's versions, so a caller cycling client_version evicts only its
// own older entries and never reaches another account's evidence.
const ownKeys = [...accountModelsCache.keys()].filter(k => accountIdOfCacheKey(k) === accountId);
for (const stale of ownKeys.slice(0, Math.max(0, ownKeys.length - MODEL_ROSTER_VERSIONS_PER_ACCOUNT_MAX))) {
accountModelsCache.delete(stale);
}
// Then bound the class by DISTINCT ACCOUNTS. Counting keys would let one account's versions
// consume the budget; counting accounts keeps each account's share independent of how many
// versions any other account is using.
const evictClass = (direct: boolean): void => {
const accountsInOrder: string[] = [];
for (const key of accountModelsCache.keys()) {
if (isDirect(key) !== direct) continue;
const account = accountIdOfCacheKey(key);
if (!accountsInOrder.includes(account)) accountsInOrder.push(account);
}
// Never evict the account just written, even if it is the least-recently-inserted.
for (const victim of accountsInOrder.slice(0, Math.max(0, accountsInOrder.length - MODEL_ROSTER_CACHE_MAX))) {
if (victim === accountId) continue;
for (const key of [...accountModelsCache.keys()]) {
if (accountIdOfCacheKey(key) === victim) accountModelsCache.delete(key);
}
}
};
evictClass(accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX));
}
/**
* An identity resolver scoped to one caller's pass, reading each backing store at most once.
*
* The identity check itself is unchanged -- same prefix rule, same tombstone and missing-credential
* rejection, same `pool:<generation>:<chatgptAccountId>` shape -- but the READ is hoisted. Per-id
* resolution reloads and reparses the whole `codex-accounts.json` every call, so a loop over cache
* entries paid one full-store read per entry: the denial reader admits 64 accounts with four client
* versions each, which is up to 256 synchronous reads to score a single warm flagship request.
*
* Both stores are read lazily, so a pass that touches only Direct callers, or only native main,
* still opens nothing it does not need. Neither backing read is memoized across passes: a resolver
* lives for one synchronous loop, and that loop has no suspension point, so nothing this process
* does can change the file underneath it. A snapshot is therefore not staler than per-entry reads
* would have been -- it is strictly more coherent, because a foreign writer landing mid-loop can no
* longer give the earlier entries one generation and the later ones another.
*/
function credentialIdentityResolver(): (accountId: string) => string | undefined {
let records: Readonly<Record<string, CodexAccountCredentialRecord>> | undefined;
let mainRead = false;
let mainIdentity: string | undefined;
return (accountId: string): string | undefined => {
if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) {
return `direct:${accountId.slice(DIRECT_CALLER_ACCOUNT_PREFIX.length)}`;
}
if (accountId === MAIN_CODEX_ACCOUNT_ID) {
if (!mainRead) {
const token = getMainAccountToken();
mainIdentity = token ? `main:${token.chatgptAccountId}` : undefined;
mainRead = true;
}
return mainIdentity;
}
records ??= loadCodexAccountRecordSnapshot();
const record = records[accountId];
if (!record?.credential || record.deletedAt != null) return undefined;
return `pool:${record.generation}:${record.credential.chatgptAccountId}`;
};
}
/** Single-id resolution. Identical to one call through a fresh {@link credentialIdentityResolver}. */
function currentCredentialIdentity(accountId: string): string | undefined {
return credentialIdentityResolver()(accountId);
}
async function accountCredentialSnapshot(
accountId: string,
options: Pick<
CodexModelEntitlementResolveOptions,
"nativeMainRefreshDependencies" | "releaseNativeMainCredentialLease" | "signal"
> = {},
): Promise<CodexModelEntitlementCredentialSnapshot | null> {
if (accountId === MAIN_CODEX_ACCOUNT_ID) {
try {
const token = await getValidMainAccountToken({
signal: options.signal,
...(options.nativeMainRefreshDependencies ?? {}),
});
return token
? {
accountId,
accessToken: token.accessToken,
chatgptAccountId: token.chatgptAccountId,
credentialIdentity: `main:${token.chatgptAccountId}`,
}
: null;
} finally {
// The lifecycle lease fences only this credential read; releasing here —
// on success and on a credential-ownership failure alike — keeps a
// profile drain from waiting on the roster fetches that follow.
options.releaseNativeMainCredentialLease?.();
}
}
try {
const token = await getValidCodexToken(accountId);
return {
accountId,
accessToken: token.accessToken,
chatgptAccountId: token.chatgptAccountId,
credentialIdentity: `pool:${token.generation}:${token.chatgptAccountId}`,
};
} catch {
return null;
}
}
const AVAILABILITY_MESSAGE_MAX_CODE_UNITS = 2_000;
// Codex parses the catalog with a strict JSON reader that rejects a lone surrogate escape.
const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
/** Trim and cap a prompt without leaving half of a surrogate pair at the cut or anywhere else. */
function boundedAvailabilityMessage(message: string): string {
return message.trim().slice(0, AVAILABILITY_MESSAGE_MAX_CODE_UNITS).replace(LONE_SURROGATE, "").trim();
}
/** Keep valid roster slugs while dropping malformed program and availability metadata. */
function parseAccountModels(text: string): {
discoveredRows: Record<string, unknown>[];
models: ReadonlySet<string>;
accessProgramsByModel: ReadonlyMap<string, CodexAvailableAccessPrograms>;
availabilityNuxByModel: ReadonlyMap<string, { message: string }>;
} | null {
try {
const payload = JSON.parse(text) as { models?: unknown };
if (!Array.isArray(payload.models)) return null;
const accessProgramsByModel = new Map<string, CodexAvailableAccessPrograms>();
const availabilityNuxByModel = new Map<string, { message: string }>();
const models = payload.models.flatMap(entry => {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
const row = entry as { slug?: unknown; supported_in_api?: unknown; visibility?: unknown; available_access_programs?: unknown; availability_nux?: unknown };
if (typeof row.slug !== "string" || row.supported_in_api !== true || row.visibility === "hide") return [];
const nux = row.availability_nux;
if (nux && typeof nux === "object" && !Array.isArray(nux)) {
const message = (nux as { message?: unknown }).message;
const bounded = typeof message === "string" ? boundedAvailabilityMessage(message) : "";
if (bounded) availabilityNuxByModel.set(row.slug, { message: bounded });
}
const programs = row.available_access_programs;
if (programs === null) accessProgramsByModel.set(row.slug, null);
else if (programs && typeof programs === "object" && !Array.isArray(programs)) {
const record = programs as Record<string, unknown>;
if (Array.isArray(record.cyber) && record.cyber.every(item => typeof item === "string")) {
const validPrograms = Object.fromEntries(Object.entries(record).filter(([, value]) =>
Array.isArray(value) && value.every(item => typeof item === "string"))) as Record<string, string[]>;
accessProgramsByModel.set(row.slug, validPrograms);
}
}
return [row.slug];
});
return { models: new Set(models), accessProgramsByModel, availabilityNuxByModel,
discoveredRows: validateDiscoveredNativeRows(payload.models) };
} catch {
return null;
}
}
function unconfirmedAccountModels(
credential: CodexModelEntitlementCredentialSnapshot,
clientVersion: string,
now: number,
provenance: CodexModelEntitlementProvenance,
): CachedAccountModels {
return {
credentialIdentity: credential.credentialIdentity,
clientVersion,
expiresAt: now + MODEL_ROSTER_FAILURE_TTL_MS,
models: new Set(),
confirmed: false,
provenance,
};
}
function isTimeoutError(error: unknown): boolean {
return error instanceof Error && error.name === "TimeoutError";
}
/** Fetch one bounded, version-scoped roster; failures and empty results remain unconfirmed for a short retry. */
async function fetchAccountModels(
credential: CodexModelEntitlementCredentialSnapshot,
fetcher: typeof fetch,
now: number,
clientVersion: string,
): Promise<CachedAccountModels> {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(new DOMException("Codex model discovery timed out", "TimeoutError")), MODEL_ROSTER_TIMEOUT_MS);
try {
const headers = new Headers({
Authorization: `Bearer ${credential.accessToken}`,
Accept: "application/json",
});
if (credential.chatgptAccountId) headers.set("ChatGPT-Account-Id", credential.chatgptAccountId);
const response = await fetcher(codexModelsUrl(clientVersion), {
headers,
redirect: "error",
signal: controller.signal,
});
if (!response.ok) {
return unconfirmedAccountModels(credential, clientVersion, now, {
kind: "http-error",
httpStatus: response.status,
});
}
const body = await readBoundedResponseBody(response, {
signal: controller.signal,
maxBytes: MODEL_ROSTER_MAX_BYTES,
fatalUtf8: true,
});
if (!body.displaySafe || body.truncated) {
return unconfirmedAccountModels(credential, clientVersion, now, { kind: "unparseable" });
}
const parsed = parseAccountModels(body.text);
if (parsed === null) {
return unconfirmedAccountModels(credential, clientVersion, now, { kind: "unparseable" });
}
// A roster is a confirmation only when it lists something usable. `models` is a Set, and an
// empty Set is truthy, so `models !== null` used to call `{"models":[]}` — and a response
// whose every row was hidden or api-disabled — a confirmed answer, and lock it in for the
// five-minute success TTL. Absence of evidence is not evidence of absence: an entitled
// account asked under too old a client version answers with no gated rows, and treating
// that as authoritative is exactly how 2.36.0 denied sol/terra/luna to accounts that own
// them (#3022). No usable rows means unconfirmed, on the 15s failure TTL, asked again.
const { models, accessProgramsByModel, availabilityNuxByModel } = parsed;
const usable = models.size > 0;
if (!usable) {
return unconfirmedAccountModels(credential, clientVersion, now, { kind: "parsed-empty" });
}
recordDiscoveredNativeModels(parsed.discoveredRows, clientVersion, now);
const hasUnknownGatedAbsence = [...ACCOUNT_GATED_NATIVE_MODEL_MINIMUM_CLIENT_VERSIONS]
// Reachable only through tier 1, an inbound client_version below the floor. Every other
// resolution is now structurally >= every recorded minimum, because the floor is the max
// of the derived value and the same measured constant these minimums hold. So this is the
// escape hatch for a self-declared old client, not live protection on the background path:
// there, an absence really was asked for at an adequate version and is a denial. If
// upstream ever raises its true requirement above the measured constant, that constant is
// the only thing standing between an entitled account and a five-minute cached denial.
.some(([modelId, minimum]) => (
!models.has(modelId) && compareClientVersions(clientVersion, minimum) < 0
));
return {
credentialIdentity: credential.credentialIdentity,
clientVersion,
expiresAt: now + (!hasUnknownGatedAbsence
? MODEL_ROSTER_TTL_MS
: MODEL_ROSTER_FAILURE_TTL_MS),
models,
accessProgramsByModel,
availabilityNuxByModel,
confirmed: true,
};
} catch (error) {
const provenance = isTimeoutError(error) || isTimeoutError(controller.signal.reason)
? { kind: "timeout" } as const
: { kind: "network-error" } as const;
return unconfirmedAccountModels(credential, clientVersion, now, provenance);
} finally {
clearTimeout(timer);
}
}
/**
* Client version the discovery-only roster request claims.
*
* Upstream filters `/models` by client version AND by a rollout gate the row's own
* `minimal_client_version` does not describe: on 2026-09-30 `gpt-6.1-sol` carried
* `minimal_client_version: "0.153.0"` yet was served only to `client_version >= 0.159.0`, while the
* installed Codex was 0.158.0-alpha. Asking under the installed version (what the entitlement path
* must do, #2886) therefore could not see the model at all. Discovery asks as a client newer than
* any release so it sees the whole roster; this proxy already serves pinned rows to older
* clients, so the version only widens what we learn, never what an account may call.
*/
export const CODEX_ROSTER_DISCOVERY_CLIENT_VERSION = "99.0.0";
export type CodexNativeRosterDiscoveryOutcome = "recorded" | "not-modified" | "unavailable";
export interface CodexNativeRosterDiscoveryOptions extends Pick<
CodexModelEntitlementResolveOptions,
"credentials" | "fetcher" | "signal" | "now" | "nativeMainRefreshDependencies"
> {
/** Checked right before publication; false means the caller's scheduler generation is gone. */
readonly isCurrent?: () => boolean;
}
/**
* Last ETag per credential identity, so an unchanged roster costs a 304 when upstream honours it.
* A 304 carries no rows and so cannot renew a discovery's last-seen time; a model visible only
* under the discovery version would then expire after its retention while still being served.
* The ETag is therefore used only within a day of the full fetch that earned it.
*/
const discoveryEtags = new Map<string, { etag: string; fetchedAt: number }>();
const DISCOVERY_ETAG_MAX_AGE_MS = 24 * 60 * 60 * 1000;
/**
* Background discovery of native rows this build does not pin, independent of entitlement.
*
* It never writes the entitlement cache: a roster fetched under the discovery version answers a
* different question than "may this client call this model", and letting it satisfy entitlement
* reads would reintroduce the cross-version leak #2548/#2886 closed. The first account that
* answers is enough to learn a row; whether a given account may call it stays with the
* entitlement path and, for ungated rows, with the upstream status the request receives.
*/
export async function discoverCodexNativeRoster(
config: Pick<OcxConfig, "codexAccounts">,
options: CodexNativeRosterDiscoveryOptions = {},
): Promise<CodexNativeRosterDiscoveryOutcome> {
const fetcher = options.fetcher ?? fetch;
const run = async (excluded: ReadonlySet<string>, releaseMainLease?: () => void) => {
const credentials: CodexModelEntitlementCredentialSnapshot[] = [...(options.credentials ?? [])];
for (const accountId of options.credentials ? [] : normalizedCandidateAccountIds(config)) {
if (excluded.has(accountId)) continue;
const credential = await accountCredentialSnapshot(accountId, {
nativeMainRefreshDependencies: options.nativeMainRefreshDependencies,
signal: options.signal,
}).catch(() => null);
if (credential) credentials.push(credential);
}
releaseMainLease?.();
for (const credential of credentials) {
const outcome = await fetchDiscoveryRoster(credential, fetcher, options).catch(() => "unavailable" as const);
if (outcome !== "unavailable") return outcome;
}
return "unavailable" as const;
};
try {
return await withNativeMainCredentialAdmission(run);
} catch {
return "unavailable";
}
}
async function fetchDiscoveryRoster(
credential: CodexModelEntitlementCredentialSnapshot,
fetcher: typeof fetch,
options: Pick<CodexNativeRosterDiscoveryOptions, "signal" | "now" | "isCurrent">,
): Promise<CodexNativeRosterDiscoveryOutcome> {
const controller = new AbortController();
const abort = () => controller.abort(options.signal?.reason);
options.signal?.addEventListener("abort", abort, { once: true });
const timer = setTimeout(() => controller.abort(new DOMException("Codex model discovery timed out", "TimeoutError")), MODEL_ROSTER_TIMEOUT_MS);
try {
const headers = new Headers({ Authorization: `Bearer ${credential.accessToken}`, Accept: "application/json" });
if (credential.chatgptAccountId) headers.set("ChatGPT-Account-Id", credential.chatgptAccountId);
const now = options.now ?? Date.now();
const cached = discoveryEtags.get(credential.credentialIdentity);
if (cached && now - cached.fetchedAt < DISCOVERY_ETAG_MAX_AGE_MS) headers.set("If-None-Match", cached.etag);
const response = await fetcher(codexModelsUrl(CODEX_ROSTER_DISCOVERY_CLIENT_VERSION), {
headers,
redirect: "error",
signal: controller.signal,
});
if (response.status === 304) return "not-modified";
if (!response.ok) return "unavailable";
const body = await readBoundedResponseBody(response, {
signal: controller.signal,
maxBytes: MODEL_ROSTER_MAX_BYTES,
fatalUtf8: true,
});
if (!body.displaySafe || body.truncated) return "unavailable";
const parsed = parseAccountModels(body.text);
if (parsed === null || parsed.models.size === 0) return "unavailable";
if (controller.signal.aborted || options.isCurrent?.() === false) return "unavailable";
recordDiscoveredNativeModels(parsed.discoveredRows, CODEX_ROSTER_DISCOVERY_CLIENT_VERSION, now);
const nextEtag = response.headers.get("etag");
if (nextEtag && nextEtag.length <= 256) discoveryEtags.set(credential.credentialIdentity, { etag: nextEtag, fetchedAt: now });
else discoveryEtags.delete(credential.credentialIdentity);
if (discoveryEtags.size > 64) discoveryEtags.delete(discoveryEtags.keys().next().value!);
return "recorded";
} finally {
clearTimeout(timer);
options.signal?.removeEventListener("abort", abort);
}
}
export function resetCodexNativeRosterDiscoveryForTests(): void {
discoveryEtags.clear();
}
function directCallerCredential(headers: Headers): CodexModelEntitlementCredentialSnapshot | null {
const match = /^Bearer\s+(\S+)$/i.exec(headers.get("authorization")?.trim() ?? "");
if (!match) return null;
const accessToken = match[1]!;
const chatgptAccountId = headers.get("chatgpt-account-id")?.trim() ?? "";
const fingerprint = createHash("sha256")
.update(accessToken)
.update("\0")
.update(chatgptAccountId)
.digest("hex");
return {
accountId: `${DIRECT_CALLER_ACCOUNT_PREFIX}${fingerprint}`,
accessToken,
chatgptAccountId,
credentialIdentity: `direct:${fingerprint}`,
};
}
async function modelsForCredential(
credential: CodexModelEntitlementCredentialSnapshot,
fetcher: typeof fetch,
now: number,
clientVersion: string,
trustedClientVersion: string,
credentialMutationEpoch?: number,
): Promise<CachedAccountModels> {
const cached = accountModelsCache.get(cacheKeyFor(credential.accountId, clientVersion));
if (
cached
&& cached.credentialIdentity === credential.credentialIdentity
&& cached.expiresAt > now
) return cached;
const flightKey = `${credential.accountId}\u0000${credential.credentialIdentity}\u0000${clientVersion}`
+ (credentialMutationEpoch === undefined ? "" : `\u0000${credentialMutationEpoch}`);
const existing = accountModelsFlights.get(flightKey);
if (existing) return existing;
// Bound concurrency per account before opening another upstream request.
let liveForAccount = 0;
for (const key of accountModelsFlights.keys()) {
if (accountIdOfCacheKey(key) === credential.accountId) liveForAccount += 1;
}
if (liveForAccount >= MODEL_ROSTER_FLIGHTS_PER_ACCOUNT_MAX) {
return {
credentialIdentity: credential.credentialIdentity,
clientVersion,
expiresAt: now,
models: new Set(),
confirmed: false,
};
}
// Cache hits, joined flights and capacity refusals start no upstream request. Charge only
// after capacity admission; the locally selected runtime version remains exempt.
if (
!credential.accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)
&& clientVersion !== trustedClientVersion
&& !admitVersionMiss(credential, clientVersion, now)
) {
return {
credentialIdentity: credential.credentialIdentity,
clientVersion,
expiresAt: now,
models: new Set(),
confirmed: false,
};
}
const flight = fetchAccountModels(credential, fetcher, now, clientVersion)
.then(result => {
if (
currentCredentialIdentity(credential.accountId) === credential.credentialIdentity
&& (credentialMutationEpoch === undefined
|| codexCredentialMutationEpoch() === credentialMutationEpoch)
) {
boundedCacheSet(credential.accountId, result);
}
return result;
})
.finally(() => {
if (accountModelsFlights.get(flightKey) === flight) accountModelsFlights.delete(flightKey);
});
accountModelsFlights.set(flightKey, flight);
return flight;
}
/** Whether this caller-selected version may open a new upstream request for the account. */
function admitVersionMiss(
credential: CodexModelEntitlementCredentialSnapshot,
clientVersion: string,
now: number,
): boolean {
const stored = accountModelsMisses.get(credential.accountId);
const budget = stored && stored.credentialIdentity === credential.credentialIdentity
? stored
: { credentialIdentity: credential.credentialIdentity, versions: new Map<string, number>() };
for (const [version, expiresAt] of budget.versions) {
if (expiresAt <= now) budget.versions.delete(version);
}
const alreadyCharged = budget.versions.has(clientVersion);
const admitted = alreadyCharged
|| budget.versions.size < MODEL_ROSTER_VERSION_MISSES_PER_ACCOUNT_MAX;
// A repeat keeps its ORIGINAL expiry. Refreshing it here would let a caller hold one version
// open indefinitely, and it is the retry case this distinction exists to protect.
if (admitted && !alreadyCharged) budget.versions.set(clientVersion, now + MODEL_ROSTER_TTL_MS);
if (budget.versions.size === 0) accountModelsMisses.delete(credential.accountId);
else accountModelsMisses.set(credential.accountId, budget);
return admitted;
}
function candidateAccountIds(config: Pick<OcxConfig, "codexAccounts">): string[] {
return [
MAIN_CODEX_ACCOUNT_ID,
...(config.codexAccounts ?? [])
.filter(isSelectableCodexPoolAccount)
.map(account => account.id),
];
}
function normalizedCandidateAccountIds(config: Pick<OcxConfig, "codexAccounts">): string[] {
return [...new Set(candidateAccountIds(config))].sort();
}
function freshNegativeCredentialMemo(
accountId: string,
credentialIdentity: string | null,
mutationEpoch: number,
now: number,
): boolean {
const memo = negativeCredentialMemo.get(accountId);
if (
memo
&& memo.credentialIdentity === credentialIdentity
&& memo.mutationEpoch === mutationEpoch
&& memo.expiresAt > now
) return true;
if (memo) negativeCredentialMemo.delete(accountId);
return false;
}
function boundedNegativeCredentialMemoSet(accountId: string, memo: NegativeCredentialMemo): void {
negativeCredentialMemo.delete(accountId);
negativeCredentialMemo.set(accountId, memo);
for (const oldest of [...negativeCredentialMemo.keys()].slice(0, Math.max(
0,
negativeCredentialMemo.size - MODEL_ROSTER_CACHE_MAX,
))) negativeCredentialMemo.delete(oldest);
}
function needsEntitlementRefresh(
accountId: string,
credentialIdentity: string | null,
clientVersion: string,
mutationEpoch: number,
now: number,
): boolean {
const cached = accountModelsCache.get(cacheKeyFor(accountId, clientVersion));
if (cached && cached.credentialIdentity !== credentialIdentity) {
invalidateCodexModelEntitlementsForAccount(accountId);
// The credential itself changed, so evidence gathered under the previous one answers for a
// different subscription. This is the only call site that knows that: the two gated-model
// sites in `core-codex-account.ts` invalidate a STALE roster for an unchanged credential,
// and clearing observed refusals there would discard the very evidence #4906 is about.
forgetObservedCodexModelDenialsForAccount(accountId);
} else if (cached && cached.expiresAt > now) {
return false;
}
return !freshNegativeCredentialMemo(accountId, credentialIdentity, mutationEpoch, now);
}
function entitlementEnsureFlightKey(
candidateAccountIds: readonly string[],
clientVersion: string,
mutationEpoch: number,
identityVector: readonly (readonly [string, string | null])[],
workset: readonly string[],
): string {
return JSON.stringify([candidateAccountIds, clientVersion, mutationEpoch, identityVector, workset]);
}
async function refreshCodexEntitlementWorkset(
config: Pick<OcxConfig, "codexAccounts">,
workset: readonly string[],
identityVector: ReadonlyMap<string, string | null>,
clientVersion: string,
mutationEpoch: number,
options: CodexEntitlementFreshnessOptions,
): Promise<void> {
const run = async (
excludedAccountIds: ReadonlySet<string>,
releaseMainLease?: () => void,
): Promise<void> => {
// An excluded main is filtered before the snapshot phase, not just before the
// roster fetch: it never produces an absence observation, so a denied
// admission cannot memoize a credential read that never happened.
const admittedWorkset = excludedAccountIds.size === 0
? workset
: workset.filter(accountId => !excludedAccountIds.has(accountId));
const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
const observations = await Promise.all(admittedWorkset.map(async accountId => {
const credential = await credentialSnapshot(accountId, {
...options,
releaseNativeMainCredentialLease: releaseMainLease,
});
return {
accountId,
credential,
absenceObservedAt: options.now ?? Date.now(),
};
}));
// The lease fences only the credential phase; release before roster fetches
// so a profile drain never waits on upstream network work.
releaseMainLease?.();
const credentials = observations.flatMap(observation => observation.credential
? [observation.credential]
: []);
if (credentials.length > 0) {
await resolveCodexModelEntitlements(config, {
...options,
clientVersion,
credentialMutationEpoch: mutationEpoch,
credentials,
});
}
for (const observation of observations) {
if (observation.credential) continue;
const capturedIdentity = identityVector.get(observation.accountId) ?? null;
if (codexCredentialMutationEpoch() !== mutationEpoch) continue;
if ((currentCredentialIdentity(observation.accountId) ?? null) !== capturedIdentity) continue;
boundedNegativeCredentialMemoSet(observation.accountId, {
credentialIdentity: capturedIdentity,
mutationEpoch,
expiresAt: observation.absenceObservedAt + MODEL_ROSTER_NEGATIVE_CREDENTIAL_TTL_MS,
});
}
};
if (!workset.includes(MAIN_CODEX_ACCOUNT_ID)) return run(new Set<string>());
const admission = options.nativeMainCredentialAdmission ?? withNativeMainCredentialAdmission;
return admission(run);
}
function waitForEntitlementEnsureFlight(
flight: EntitlementEnsureFlight,
waitMs: number,
): Promise<void> {
const remaining = Math.max(0, waitMs - Math.max(0, Date.now() - flight.startedAt));
if (remaining === 0) return Promise.resolve();
return new Promise(resolve => {
const timer = setTimeout(resolve, remaining);
void flight.promise.then(() => {
clearTimeout(timer);
resolve();
});
});
}
/**
* Refreshes only missing, expired, or credential-mismatched local entitlement entries.
* Management deadlines bound the wait, not the upstream work, so a timed-out poll still warms
* the cache for the first poll after the shared flight settles.
*/
export async function ensureCodexEntitlementFreshness(
config: Pick<OcxConfig, "codexAccounts">,
options: CodexEntitlementFreshnessOptions = {},
): Promise<void> {
try {
const now = options.now ?? Date.now();
const clientVersion = resolveCodexEntitlementClientVersion(
options.clientVersion,
options.loadPersistedRuntime ?? loadPersistedCodexRuntime,
);
const candidates = normalizedCandidateAccountIds(config);
const mutationEpoch = codexCredentialMutationEpoch();
// Same hoist as the denial pass: this prologue is synchronous and reads once per candidate.
const identityOf = credentialIdentityResolver();
const identityEntries = candidates.map(accountId => (
[accountId, identityOf(accountId) ?? null] as const
));
const identityVector = new Map(identityEntries);
const workset = candidates.filter(accountId => needsEntitlementRefresh(
accountId,
identityVector.get(accountId) ?? null,
clientVersion,
mutationEpoch,
now,
));
if (workset.length === 0) return;
const key = entitlementEnsureFlightKey(
candidates,
clientVersion,
mutationEpoch,
identityEntries,
workset,
);
let flight = entitlementEnsureFlights.get(key);
if (!flight) {
const startedAt = Date.now();
let created!: EntitlementEnsureFlight;
const promise = refreshCodexEntitlementWorkset(
config,
workset,
identityVector,
clientVersion,
mutationEpoch,
options,
).catch(() => {
// Entitlement discovery is fail-closed: callers project only confirmed cache entries.
}).finally(() => {
if (entitlementEnsureFlights.get(key) === created) entitlementEnsureFlights.delete(key);
});
created = { startedAt, promise, clientVersion, identityVector, workset };
entitlementEnsureFlights.set(key, created);
flight = created;
}
const requestedWaitMs = options.waitMs ?? 3_000;
const waitMs = Number.isFinite(requestedWaitMs) ? Math.max(0, requestedWaitMs) : 0;
await waitForEntitlementEnsureFlight(flight, waitMs);
} catch {
// The shared management boundary must degrade to the last confirmed fail-closed projection.
}
}
export function getCodexModelEntitlementStatus(
config: Pick<OcxConfig, "codexAccounts">,
now = Date.now(),
clientVersion?: string | null,
): CodexModelEntitlementStatus {
const version = resolveCodexEntitlementClientVersion(clientVersion);
const identityOf = credentialIdentityResolver();
const accounts = candidateAccountIds(config).flatMap(accountId => {
const credentialIdentity = identityOf(accountId);
return credentialIdentity ? [{ accountId, credentialIdentity }] : [];
});
if (accounts.length === 0) return { status: "unavailable" };
const entries = accounts.map(({ accountId, credentialIdentity }) => ({
accountId,
credentialIdentity,
entry: accountModelsCache.get(cacheKeyFor(accountId, version)),
}));
const hasRefreshFlight = (accountId: string, credentialIdentity: string): boolean => {
return [...entitlementEnsureFlights.values()].some(flight => (
flight.clientVersion === version
&& flight.identityVector.get(accountId) === credentialIdentity
&& flight.workset.includes(accountId)
));
};
if (entries.some(({ accountId, credentialIdentity, entry }) => (
entry
&& entry.credentialIdentity === credentialIdentity
&& entry.expiresAt <= now
&& hasRefreshFlight(accountId, credentialIdentity)
))) return { status: "expired-refresh-in-flight" };
const live = entries.flatMap(({ credentialIdentity, entry }) => (
entry && entry.credentialIdentity === credentialIdentity && entry.expiresAt > now ? [entry] : []
));
// Deliberate failure-first aggregation keeps a partial Pool refresh failure visible.
const failed = live.find(entry => entry.provenance && entry.provenance.kind !== "parsed-empty");
if (failed?.provenance?.kind === "http-error") {
return { status: "failed", reason: "http-error", httpStatus: failed.provenance.httpStatus };
}
if (failed?.provenance?.kind === "network-error") return { status: "failed", reason: "network-error" };
if (failed?.provenance?.kind === "timeout") return { status: "failed", reason: "timeout" };
if (failed?.provenance?.kind === "unparseable") return { status: "failed", reason: "unparseable" };
if (live.some(entry => entry.provenance?.kind === "parsed-empty")) {
return { status: "unconfirmed-empty" };
}
if (live.some(entry => entry.confirmed)) return { status: "fresh" };
return { status: "unavailable" };
}
/**
* Fetch the authenticated model roster for every locally usable Codex account.
*
* [Decision Log]
* - 목적과 의도: Account-gated native models must be advertised and selected only for accounts
* whose own authenticated upstream catalog confirms the model.
* - 기존 구현 및 제약 조건: The injected Codex catalog is static, while Pool may contain
* accounts with different entitlements. A global allowlist therefore exposed unusable rows.
* - 검토한 주요 대안: Infer access from plan labels, learn only after a failed prompt, or rewrite
* Daybreak to its current physical model.
* - 선택한 방식: Cache bounded authenticated `/models` rosters per credential generation and
* fail closed for unconfirmed accounts.
* - 다른 대안 대신 이 방식을 선택한 이유: Plan names do not prove grants, post-failure
* learning spends a real turn, and model rewriting changes the requested product identity.
* - 장점, 단점 및 영향: Catalog and routing share exact account evidence. Cold gated requests
* pay one bounded discovery call per account; discovery failure temporarily hides the gated row.
*/
export async function resolveCodexModelEntitlements(
config: Pick<OcxConfig, "codexAccounts">,
options: CodexModelEntitlementResolveOptions = {},
): Promise<CodexModelEntitlementSnapshot> {
const now = options.now ?? Date.now();
const fetcher = options.fetcher ?? fetch;
const clientVersion = resolveCodexEntitlementClientVersion(
options.clientVersion,
options.loadPersistedRuntime ?? loadPersistedCodexRuntime,
);
const allowedAccountIds = candidateAccountIds(config)
.filter(accountId => !options.excludeAccountIds?.has(accountId));
const credentialSnapshot = options.credentialSnapshot ?? accountCredentialSnapshot;
const credentials = options.credentials
? [...options.credentials].filter(credential => !options.excludeAccountIds?.has(credential.accountId))
: (await Promise.all(allowedAccountIds.map(accountId => credentialSnapshot(accountId, options))))
.filter((value): value is CodexModelEntitlementCredentialSnapshot => value !== null);
// The credential phase is the only part the native-main lease fences. The
// real snapshot releases it as soon as the main token settles; this boundary
// release keeps the guarantee when a seam snapshot never invokes it.
options.releaseNativeMainCredentialLease?.();
const results = await Promise.all(credentials.map(async credential => ({
credential,
result: await modelsForCredential(
credential,
fetcher,
now,
clientVersion,
resolveCodexEntitlementClientVersion(
null,
options.loadPersistedRuntime ?? loadPersistedCodexRuntime,
),
options.credentialMutationEpoch,
),
})));
return {
modelsByAccount: new Map(results.map(({ credential, result }) => [credential.accountId, result.models])),
accessProgramsByAccount: new Map(results.flatMap(({ credential, result }) => (
result.confirmed && result.accessProgramsByModel
? [[credential.accountId, result.accessProgramsByModel] as const] : []
))),
availabilityNuxByAccount: new Map(results.flatMap(({ credential, result }) => (
result.confirmed && result.availabilityNuxByModel
? [[credential.accountId, result.availabilityNuxByModel] as const] : []
))),
clientVersionByAccount: new Map(results.map(({ credential, result }) => (
[credential.accountId, result.clientVersion]
))),
confirmedAccountIds: new Set(results.flatMap(({ credential, result }) => result.confirmed ? [credential.accountId] : [])),
credentialIdentities: new Map(results.map(({ credential }) => [credential.accountId, credential.credentialIdentity])),
};
}
function codexModelEntitlementStateForRoster(
models: ReadonlySet<string> | undefined,
confirmed: boolean,
clientVersion: string | undefined,
modelId: string,
): CodexModelEntitlementState {
if (!models || !confirmed) return "unknown";
// Positive evidence is authoritative regardless of which client version asked for it.
if (models.has(modelId)) return "granted";
const minimum = ACCOUNT_GATED_NATIVE_MODEL_MINIMUM_CLIENT_VERSIONS.get(modelId);
if (minimum && (!clientVersion || compareClientVersions(clientVersion, minimum) < 0)) {
return "unknown";
}
return "denied";
}
/** Per-account tri-state authority. Positive projections admit only `granted`. */
export function codexModelEntitlementStateForAccount(
snapshot: CodexModelEntitlementSnapshot,
accountId: string,
modelId: string,
): CodexModelEntitlementState {
return codexModelEntitlementStateForRoster(
snapshot.modelsByAccount.get(accountId),
snapshot.confirmedAccountIds.has(accountId),
snapshot.clientVersionByAccount?.get(accountId),
modelId,
);
}
/** Fail-closed entitlement check for a Direct request's own forwarded ChatGPT credential. */
export async function isDirectCallerEntitledToCodexModel(
headers: Headers,
modelId: string,
options: Pick<CodexModelEntitlementResolveOptions, "fetcher" | "now" | "clientVersion"> = {},
): Promise<boolean> {
if (!ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(modelId)) return true;
const credential = directCallerCredential(headers);
if (!credential) return false;
const clientVersion = resolveCodexEntitlementClientVersion(options.clientVersion);
const result = await modelsForCredential(
credential,
options.fetcher ?? fetch,
options.now ?? Date.now(),
clientVersion,
clientVersion,
);
return codexModelEntitlementStateForRoster(
result.models,
result.confirmed,
result.clientVersion,
modelId,
) === "granted";
}
export function entitledCodexAccountIdsForModel(
snapshot: CodexModelEntitlementSnapshot,
modelId: string | undefined,
): ReadonlySet<string> | undefined {
if (!modelId || !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(modelId)) return undefined;
return new Set([...snapshot.modelsByAccount.keys()].flatMap(accountId => (
codexModelEntitlementStateForAccount(snapshot, accountId, modelId) === "granted"
? [accountId]
: []
)));
}
export function availableAccountGatedNativeModels(
snapshot: CodexModelEntitlementSnapshot,
eligibleAccountIds?: ReadonlySet<string>,
): ReadonlySet<string> {
return new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(modelId => (
[...snapshot.modelsByAccount.keys()].some(accountId => (
(!eligibleAccountIds || eligibleAccountIds.has(accountId))
&& codexModelEntitlementStateForAccount(snapshot, accountId, modelId) === "granted"
))
)));
}
/**
* Native models that stay unconditionally VISIBLE while their per-account availability still
* varies.
*
* This is deliberately not `ACCOUNT_GATED_NATIVE_OPENAI_MODELS` and must never become it. That set
* fails closed on ABSENCE of evidence: membership hides the row from the catalog and refuses the
* request before dispatch, which is exactly what the owner decision of 2026-09-04 removed the
* flagships from. A timed-out fetch or a shard that has not caught up would make the model vanish
* from the picker, and "opencodex lost my model" is a worse failure than one upstream 400.
*
* This set carries the opposite polarity. It admits only a CONFIRMED DENIAL as evidence, and it
* feeds an ordering preference rather than a refusal, so absent or stale evidence changes nothing.
* That is the distinction #4768 asked for: a pool holding a Plus account and a Free account should
* stop handing Sol/Astra to the Free account whose own authenticated roster already says it cannot
* serve them, without gating the model on evidence that may never arrive.
*/
export const ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
"gpt-5.6-sol",
"gpt-5.6-terra",
"gpt-5.6-luna",
NATIVE_GPT6_ASTRA_MODEL,
]);
/**
* Accounts whose OWN authenticated roster definitively omits `modelId`, read synchronously from
* evidence discovery has already gathered.
*
* Synchronous and cache-only by contract. The gated path may await `resolveCodexModelEntitlements`
* because a gated model is rare and already pays a bounded discovery call; the flagships are the
* most commonly requested models in the product, and putting an authenticated upstream fetch per
* account on that request path would trade one occasional 400 for latency on every turn. The cache
* this reads is warmed anyway: `modelsForCredential` stores each account's FULL roster, and
* background catalog sync (`src/codex/catalog/retained-sync.ts`) and convergence already resolve
* entitlements for every pool account.
*
* Returns `undefined` rather than an empty set when nothing is denied, so a caller cannot confuse
* "no account is denied" with "no evidence exists" — both mean the same thing here, which is that
* selection must be left exactly as it was.
*
* Only `denied` counts. `unknown` covers an unconfirmed account, a roster fetched under a client
* version too old to return the model, and an expired or credential-stale entry; none of those is
* proof that the account lacks the model, and treating them as proof is how 2.36.0 removed
* sol/terra/luna from accounts that owned them (#3022).
*/
export function cachedDeniedCodexAccountIdsForModel(
modelId: string | undefined,
now = Date.now(),
options: { excludeAccountIds?: ReadonlySet<string> } = {},
): ReadonlySet<string> | undefined {
if (!modelId || !ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return undefined;
const denied = new Set<string>();
const granted = new Set<string>();
// One resolver for the whole pass: the loop below runs once per cached (account, client version)
// entry, and resolving an identity per entry meant a full account-store read per entry.
const identityOf = credentialIdentityResolver();
for (const [key, entry] of accountModelsCache) {
const accountId = accountIdOfCacheKey(key);
// A forwarded Direct credential is one request's caller, never a pool candidate.
if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) continue;
// The caller's read fence, honoured BEFORE `identityOf` below, because that is the read: for
// native main it resolves the physical stored token. A request that is forbidden to read main
// -- a profile switch draining it, or a request-owned credential that owns no main state --
// must not reread account storage just to score an ordering preference. Dropping the account
// leaves it UNKNOWN rather than denied, which is the same outcome as having no cached roster
// for it and changes no selection. The resolver reads lazily for the same reason: an excluded
// account `continue`s here, so its store is never opened at all.
if (options.excludeAccountIds?.has(accountId)) continue;
if (entry.expiresAt <= now) continue;
// A credential we can currently read AND that differs is proof the entry answers for a
// different account than this id now names, so its denial is not evidence about the current
// one. An UNREADABLE credential is not proof of anything, and the same unknown-is-not-denied
// discipline that governs rosters governs identities: it leaves the entry in place rather
// than manufacturing a reason to ignore it.
const identity = identityOf(accountId);
if (identity !== undefined && identity !== entry.credentialIdentity) continue;
const state = codexModelEntitlementStateForRoster(
entry.models,
entry.confirmed,
entry.clientVersion,
modelId,
);
if (state === "granted") granted.add(accountId);
else if (state === "denied") denied.add(accountId);
}
// The roster is not the only evidence, and on this path it is usually the weaker one. A cached
// roster expires in five minutes and nothing on the flagship request path refetches it, so
// absent an ongoing catalog sync the loop above contributes nothing at all. An upstream
// refusal does not expire on that schedule and is not a snapshot of a pending answer: it is
// the account's own Codex surface naming this model and declining it (#4906).
// The caller's read fence is passed IN rather than applied to the result, so an excluded
// account is skipped before the credential-generation validation reads account storage
// (#4952). An excluded account must stay UNKNOWN rather than denied, so a profile switch or
// a request-owned credential produces the same selection it does today.
const observedDenied = observedDeniedCodexAccountIdsForModel(modelId, now, {
...(options.excludeAccountIds ? { excludeAccountIds: options.excludeAccountIds } : {}),
});
for (const accountId of observedDenied ?? []) denied.add(accountId);
// One account holds one entry per client version, and upstream filters the roster by that
// version. So the same account can legitimately carry a granted entry under a current client
// and a denied one under an older client that predates the model. Positive evidence is
// authoritative regardless of which version asked for it -- the same rule
// `codexModelEntitlementStateForRoster` applies within a single entry -- so a grant anywhere
// clears the denial rather than being outvoted by whichever entry the map happened to yield
// last. It outranks an observed refusal for the same reason: a confirmed roster that lists the
// model is the newer answer, and a rollout that reaches an account must not be held back by a
// refusal it has already superseded.
for (const accountId of granted) denied.delete(accountId);
return denied.size > 0 ? denied : undefined;
}
/**
* Record an authenticated upstream refusal as this account's own evidence about `modelId`.
*
* Scoped to {@link ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS} because that is the set whose
* availability varies per account while the row stays visible, and it is the set
* {@link cachedDeniedCodexAccountIdsForModel} will read back. A model outside it either has no
* per-account variance or is gated by the fail-closed roster path, where an ordering preference
* would change nothing.
*
* The caller must have matched the exact allow-listed refusal body first. A status alone is not
* admissible here: 400 covers every malformed request too, and remembering one of those as an
* entitlement fact would steer routing away from a perfectly capable account.
*/
// Denial evidence is credential-scoped (#4952). The store stays a leaf module, so the
// liveness predicate is injected here, where the account store is already a dependency.
setObservedDenialGenerationCheck(beginCodexAccountGenerationLiveCheck);
export function recordCodexModelDenialEvidence(
accountId: string | null | undefined,
modelId: string | undefined,
generation: number | null | undefined,
now = Date.now(),
): void {
if (!accountId || !modelId) return;
if (!ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return;
// A caller that cannot name a credential generation records ACCOUNT-scoped evidence rather
// than none. The one production context in that position is `main-pool`, whose credential
// lives in `auth.json` and has no pool generation; discarding its refusals would revert
// #4906 for the stored main login (#4952). Request-owned `main` never reaches here — its
// `accountId` is null and the guard above returns.
recordObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined, now);
}
/** Drop the refusal evidence for a pair the account has just served successfully. */
export function clearCodexModelDenialEvidence(
accountId: string | null | undefined,
modelId: string | undefined,
generation: number | null | undefined,
): void {
if (!accountId || !modelId) return;
// Mirror of the write: an account-scoped success clears account-scoped evidence. It cannot
// clear a credential-scoped entry that names a newer generation, and vice versa (#4952).
clearObservedCodexModelDenial(accountId, modelId, typeof generation === "number" ? generation : undefined);
}
/** Synchronous projection for management/catalog readers after a discovery pass. */
export function cachedAvailableAccountGatedNativeModels(
now = Date.now(),
eligibleAccountIds?: ReadonlySet<string>,
clientVersion?: string | null,
): ReadonlySet<string> {
// Entries fetched under a different client version answer a different question, so a caller
// that knows which version it is projecting for must say so — otherwise a newer client's
// roster leaks into an older client's projection (#2548 from the opposite direction).
//
// Omitting the argument deliberately does NOT filter. This is a synchronous read of
// whatever discovery already proved, and its callers (catalog metadata) are not
// request-scoped: resolving a version here would silently discard every entry fetched under
// a different one, which is a suppression this function has no evidence to justify.
const version = isUsableCodexClientVersion(clientVersion) ? clientVersion.trim() : null;
return new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(modelId => (
[...accountModelsCache].some(([accountId, entry]) => (
(!eligibleAccountIds || eligibleAccountIds.has(accountIdOfCacheKey(accountId)))
&& !accountIdOfCacheKey(accountId).startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)
&& (version === null || entry.clientVersion === version)
&& entry.expiresAt > now
&& codexModelEntitlementStateForRoster(
entry.models,
entry.confirmed,
entry.clientVersion,
modelId,
) === "granted"
))
)));
}
export function isCodexModelEntitlementSnapshotCurrent(snapshot: CodexModelEntitlementSnapshot): boolean {
for (const [accountId, identity] of snapshot.credentialIdentities) {
// Deliberately per-id, unlike the passes above. This is a fail-closed publication gate asking
// whether a snapshot is STILL current, so the freshest possible answer per account is the
// point of the read. A pass-wide snapshot would be a coherence win everywhere else and a
// small weakening here: it could answer "current" for a later account from a record a
// concurrent reauth had already replaced.
if (currentCredentialIdentity(accountId) !== identity) return false;
}
return true;
}
export function invalidateCodexModelEntitlementsForAccount(accountId: string | null | undefined): void {
if (!accountId) return;
// Every version's entry for this account, since a credential change invalidates the
// account's entitlement evidence regardless of which client version asked for it.
for (const key of [...accountModelsCache.keys()]) {
if (accountIdOfCacheKey(key) === accountId) accountModelsCache.delete(key);
}
accountModelsMisses.delete(accountId);
}
export function resetCodexModelEntitlementCacheForTests(): void {
accountModelsCache.clear();
accountModelsFlights.clear();
accountModelsMisses.clear();
negativeCredentialMemo.clear();
entitlementEnsureFlights.clear();
runtimeVersionMemo = null;
resetObservedCodexModelDenialsForTests();
}
/** Test-only snapshot for proving publication fences, which cache lookup intentionally masks. */
export function codexEntitlementNegativeMemoForTests(
accountId: string,
): Readonly<{
credentialIdentity: string | null;
mutationEpoch: number;
expiresAt: number;
}> | null {
const memo = negativeCredentialMemo.get(accountId);
return memo ? { ...memo } : null;
}
/**
* Test-only seam for the memoized tier-2 read.
*
* The memo is deliberately reachable only through the DEFAULT loader (a supplied loader is
* auto-bypassed, so it cannot be cross-answered), which leaves no way to observe memo behavior
* from a test without either touching the real state file or exposing this.
*/
export function memoizeRuntimeVersionForTests(
loadRuntime: () => { selectedVersion?: string | null } | null,
now: number,
): string | null {
return memoizedPersistedRuntimeVersion(loadRuntime, now);
}
export function seedCodexModelEntitlementsForTests(
accountId: string,
models: readonly string[],
now = Date.now(),
clientVersion = "0.146.0",
credentialIdentity = `test:${accountId}`,
): void {
boundedCacheSet(accountId, {
credentialIdentity,
clientVersion,
expiresAt: now + MODEL_ROSTER_TTL_MS,
models: new Set(models),
confirmed: true,
});
}