@bitkyc08/opencodex 2.90.0 → 2.91.0

package/src/remote/served-by.ts

@@ -0,0 +1,57 @@
+/**
+ * The served-by response header, the Home instance id it carries, and whether this build sends it.
+ *
+ * Every `GET /v1/models` response the server answers itself names the serving Home in
+ * `x-opencodex-served-by`, and `GET /healthz` publishes the same value as `instanceId`, so a peer
+ * (GOAT's parity check P4) can prove which Home answered without reading logs. A Remote Link Child
+ * never answers `/v1/models` itself: its relay copies the Home's response headers, so the value a
+ * Child returns is the Home's. A Hub-mode client's Codex calls the Hub's data listener directly, so
+ * the Hub stamps its own response.
+ *
+ * The instance id is the install's `homeId` from `src/quota-pool/identity.ts`: a random
+ * `home_<32 hex>` minted once per install, persisted owner-only, and stable across restarts. It is
+ * never a hostname and is not derived from one. Until the identity exists (it is created in the
+ * background after the listener starts) or when its file is unreadable, the header and the
+ * `/healthz` field are omitted; an empty or malformed value is never sent.
+ *
+ * `SERVED_BY_HEADER_EMITTED` tells `/readyz` to advertise `served-by-header`
+ * (`src/remote/features.ts`); `tests/server/readyz-features.test.ts` fails if the advertisement
+ * and live responses disagree.
+ */
+import { readQuotaPoolIdentity } from "../quota-pool/identity";
+
+export const SERVED_BY_HEADER = "x-opencodex-served-by";
+
+/** Whether responses from this build carry {@link SERVED_BY_HEADER}. */
+export const SERVED_BY_HEADER_EMITTED: boolean = true;
+
+const INSTANCE_ID = /^home_[0-9a-f]{32}$/;
+
+/** This Home's opaque instance id, or undefined while the install identity is unavailable. */
+export function homeInstanceId(): string | undefined {
+  let homeId: unknown;
+  try { homeId = readQuotaPoolIdentity()?.homeId; } catch { return undefined; }
+  return typeof homeId === "string" && INSTANCE_ID.test(homeId) ? homeId : undefined;
+}
+
+/** Stamp {@link SERVED_BY_HEADER} with this Home's instance id; leaves the response alone without one. */
+export function withServedBy(response: Response, instanceId = homeInstanceId()): Response {
+  if (!instanceId) return response;
+  try {
+    response.headers.set(SERVED_BY_HEADER, instanceId);
+    return response;
+  } catch {
+    const headers = new Headers(response.headers);
+    headers.set(SERVED_BY_HEADER, instanceId);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+  }
+}
+
+/**
+ * The server's last step for every answered request: `GET /v1/models` names the serving Home,
+ * whichever branch produced the response. `pathname` is the dispatch path the router matched.
+ */
+export function stampServedBy(method: string, pathname: string, response: Response): Response {
+  if (!response || method !== "GET" || pathname !== "/v1/models") return response;
+  return withServedBy(response);
+}

package/src/responses/parser.ts

@@ -329,6 +329,13 @@ export function parseRequest(
         continue;
       }
 
+      if (effectiveType === "configuration_update") {
+        // Codex 0.164 positional reasoning-effort control. It is not a turn, so a translated route
+        // drops it without touching pending reasoning; the native passthrough keeps it verbatim in
+        // _rawBody. Mapping its effort onto the routed request is deliberately not done (#6895).
+        continue;
+      }
+
       if (isCompactionItemType(effectiveType)) {
         // A stored summary from a previous compaction. Decode our ocx1/ocx2 envelopes into plain text so
         // the routed model keeps the compacted context; real OpenAI-encrypted blobs degrade to a note.

package/src/responses/reasoning-envelope.ts

@@ -121,6 +121,18 @@ export function isProviderIssuedThinkingSignature(
   }
 }
 
+/**
+ * Whether a value has the spelling of a signature Anthropic issued. An allow-list on top of
+ * `isProviderIssuedThinkingSignature`: Anthropic's signature is base64, so item ids and the
+ * parser's serialized placeholder never pass. Shared by the adapter, which forwards only such a
+ * signature, and the Chat `reasoning_details` carrier, which accepts and emits only such a one.
+ */
+export function isLikelyRealAnthropicThinkingSignature(signature: string | undefined): signature is string {
+  if (typeof signature !== "string" || signature.length < 16) return false;
+  if (/^(fc|call|msg|rs|resp|reasoning|item|ws|tool|func|function)[-_]/i.test(signature)) return false;
+  return /^[A-Za-z0-9+/_=-]+$/.test(signature);
+}
+
 /** Decode an ocxr1 envelope; returns null for native (OpenAI-encrypted) blobs or garbage. */
 export function decodeReasoningEnvelope(encryptedContent: string, budget?: TranslatorBudget): ReasoningEnvelope | null {
   if (!encryptedContent.startsWith(OCX_REASONING_PREFIX)) return null;

package/src/routing/fallback-policy.ts

@@ -0,0 +1,290 @@
+/**
+ * OCX-11 fallback policy: one resolver, one guard, one record.
+ *
+ * A fallback is a hop that serves a request from a different model or a different provider than
+ * the one chosen or requested. Rotation among the accounts or keys of one provider pool for the
+ * same model is intra-pool resilience and never passes through here (see
+ * `structure/fallback-policy.md`). Every hop site calls {@link guardFallbackHop} at the point it
+ * would switch targets; nothing else reads `config.fallback`.
+ *
+ * Precedence: a device scope set to false refuses regardless; otherwise route, then provider,
+ * then global decide, most specific first; absence allows (today's behavior).
+ *
+ * Privacy: events carry public selectors, coarse trigger codes and device ids only. No request
+ * body, credential, account id, label or email reaches the ring or the refusal body.
+ */
+import type { OcxConfig } from "../types";
+import type { OcxFallbackConfig, OcxFallbackKind, OcxFallbackSwitches } from "../types/fallback";
+import { FALLBACK_DEVICE_ID, FALLBACK_SELECTOR } from "../config/schema/fallback-policy";
+
+export type FallbackScope = "device" | "route" | "provider" | "global" | "default";
+export type FallbackSite = "combo" | "subagent" | "hard-lock" | "routing-profile";
+export type FallbackTrigger =
+  | "rate_limited" | "quota_exhausted" | "auth_refused" | "upstream_5xx" | "upstream_error"
+  | "cooldown" | "unavailable" | "hard_lock";
+
+export interface FallbackTarget { provider: string; model: string }
+
+export interface FallbackDecision {
+  allowed: boolean;
+  scope: FallbackScope;
+  scopeKey?: string;
+}
+
+export interface FallbackEvent {
+  at: string;
+  site: FallbackSite;
+  route: string;
+  kind: OcxFallbackKind;
+  from: string;
+  to: string;
+  trigger: FallbackTrigger;
+  outcome: "taken" | "refused";
+  scope: FallbackScope;
+  scopeKey?: string;
+  deviceId?: string;
+}
+
+/** The admission slice this module reads; a configured key is the only device identity. */
+export type FallbackAdmission = { kind: string; keyId?: string } | null | undefined;
+
+const RING_SIZE = 20;
+const ring: FallbackEvent[] = [];
+
+function switches(value: unknown): OcxFallbackSwitches | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as OcxFallbackSwitches : undefined;
+}
+
+function policyOf(config: Pick<OcxConfig, "fallback"> | undefined): OcxFallbackConfig | undefined {
+  const value = config?.fallback;
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+
+function entry(map: Record<string, unknown> | undefined, key: string, pattern: RegExp): OcxFallbackSwitches | undefined {
+  if (!map || typeof map !== "object" || !pattern.test(key) || !Object.hasOwn(map, key)) return undefined;
+  return switches(map[key]);
+}
+
+export function selector(target: FallbackTarget): string {
+  return target.provider + "/" + target.model;
+}
+
+/** The kind of a hop, or null when the target does not change. */
+export function fallbackHopKind(from: FallbackTarget, to: FallbackTarget): OcxFallbackKind | null {
+  if (from.provider !== to.provider) return "provider";
+  return from.model === to.model ? null : "model";
+}
+
+/** Resolve one hop against the configured scopes. Pure; device ids are passed in. */
+export function resolveFallbackPolicy(
+  config: Pick<OcxConfig, "fallback"> | undefined,
+  query: { kind: OcxFallbackKind; routes?: readonly string[]; provider?: string; deviceIds?: readonly string[] },
+): FallbackDecision {
+  const policy = policyOf(config);
+  if (!policy) return { allowed: true, scope: "default" };
+  for (const id of query.deviceIds ?? []) {
+    if (entry(policy.devices, id, FALLBACK_DEVICE_ID)?.[query.kind] === false) {
+      return { allowed: false, scope: "device", scopeKey: id };
+    }
+  }
+  for (const route of query.routes ?? []) {
+    const value = entry(policy.routes, route, FALLBACK_SELECTOR)?.[query.kind];
+    if (typeof value === "boolean") return { allowed: value, scope: "route", scopeKey: route };
+  }
+  if (query.provider) {
+    const value = entry(policy.providers, query.provider, FALLBACK_SELECTOR)?.[query.kind];
+    if (typeof value === "boolean") return { allowed: value, scope: "provider", scopeKey: query.provider };
+  }
+  const global = policy[query.kind];
+  if (typeof global === "boolean") return { allowed: global, scope: "global" };
+  return { allowed: true, scope: "default" };
+}
+
+/**
+ * Core-owned slot (AGENTS.md "optional subsystems stay off the core path"): the link listener
+ * lifecycle registers how a data key id maps to its Remote Link id, so this request-path module
+ * never imports link state. With nothing registered a key id is its own device id (a Hub client).
+ */
+export type FallbackLinkResolver = (keyId: string) => string | undefined;
+let linkResolver: FallbackLinkResolver | undefined;
+
+/** Register the key-to-link resolver; returns a disposer that clears it if still current. */
+export function registerFallbackLinkResolver(resolver: FallbackLinkResolver): () => void {
+  linkResolver = resolver;
+  linkCache = undefined;
+  return () => {
+    if (linkResolver === resolver) linkResolver = undefined;
+    linkCache = undefined;
+  };
+}
+
+let linkCache: { at: number; byKey: Map<string, string | undefined> } | undefined;
+const LINK_CACHE_MS = 5_000;
+
+/** Test seam: forget the cached link-key map. */
+export function resetFallbackLinkCacheForTests(): void {
+  linkCache = undefined;
+}
+
+function linkIdForKey(keyId: string, now: number): string | undefined {
+  if (!linkResolver) return undefined;
+  if (!linkCache || now - linkCache.at > LINK_CACHE_MS) linkCache = { at: now, byKey: new Map() };
+  if (!linkCache.byKey.has(keyId)) {
+    let linkId: string | undefined;
+    try { linkId = linkResolver(keyId); } catch { /* unreadable store: the key id alone still identifies the device */ }
+    linkCache.byKey.set(keyId, linkId);
+  }
+  return linkCache.byKey.get(keyId);
+}
+
+/**
+ * Device ids for a request: the Remote Link id its data key belongs to, then the key id itself
+ * (a Hub client). The registered link resolver runs only when a device override exists.
+ */
+export function fallbackDeviceIds(config: Pick<OcxConfig, "fallback">, admission: FallbackAdmission, now = Date.now()): string[] {
+  const devices = policyOf(config)?.devices;
+  if (!devices || Object.keys(devices).length === 0) return [];
+  if (!admission || admission.kind !== "configured" || typeof admission.keyId !== "string") return [];
+  const linkId = linkIdForKey(admission.keyId, now);
+  return linkId ? [linkId, admission.keyId] : [admission.keyId];
+}
+
+/** A coarse trigger code for a failed upstream status. */
+export function fallbackTriggerForStatus(status: number): FallbackTrigger {
+  if (status === 429) return "rate_limited";
+  if (status === 402) return "quota_exhausted";
+  if (status === 401 || status === 403) return "auth_refused";
+  if (status >= 500) return "upstream_5xx";
+  return "upstream_error";
+}
+
+function record(event: FallbackEvent): void {
+  ring.push(event);
+  if (ring.length > RING_SIZE) ring.splice(0, ring.length - RING_SIZE);
+}
+
+export function recentFallbackEvents(): FallbackEvent[] {
+  return ring.map(event => ({ ...event }));
+}
+
+export function clearFallbackEventsForTests(): void {
+  ring.length = 0;
+}
+
+export interface FallbackHop {
+  site: FallbackSite;
+  /** The public selector the client asked for (combo/<id>, policy/<id>, a model). */
+  route: string;
+  /** Further selectors that name the same route, such as a resolved alias. */
+  aliases?: readonly string[];
+  from: FallbackTarget;
+  to: FallbackTarget;
+  trigger: FallbackTrigger;
+  admission?: FallbackAdmission;
+  /** Status of the failure that triggered the hop; absent for a proactive hop. */
+  failureStatus?: number;
+  retryAfter?: string | null;
+  now?: number;
+}
+
+export type FallbackGuardResult =
+  | {
+    ok: true;
+    kind: OcxFallbackKind | null;
+    /**
+     * Record the hop as taken. A site calls it once the fallback dispatch is admitted (send
+     * budget reserved, candidate not locally skipped), so the ring never claims a target that was
+     * never contacted. Idempotent; a no-op for a same-target retry.
+     */
+    commit: () => void;
+  }
+  | { ok: false; kind: OcxFallbackKind; decision: FallbackDecision; response: Response };
+
+const NO_COMMIT = (): void => {};
+
+/**
+ * Check one hop. A refusal is recorded at once; an allowed hop is recorded only through the
+ * returned `commit`. A same-target retry is not a hop and always passes unrecorded.
+ */
+export function guardFallbackHop(config: OcxConfig, hop: FallbackHop): FallbackGuardResult {
+  const kind = fallbackHopKind(hop.from, hop.to);
+  if (kind === null) return { ok: true, kind: null, commit: NO_COMMIT };
+  const now = hop.now ?? Date.now();
+  const deviceIds = fallbackDeviceIds(config, hop.admission, now);
+  const routes = [hop.route, ...(hop.aliases ?? [])].filter((value, index, all) => value && all.indexOf(value) === index);
+  const decision = resolveFallbackPolicy(config, { kind, routes, provider: hop.from.provider, deviceIds });
+  const event: FallbackEvent = {
+    at: new Date(now).toISOString(),
+    site: hop.site,
+    route: hop.route,
+    kind,
+    from: selector(hop.from),
+    to: selector(hop.to),
+    trigger: hop.trigger,
+    outcome: decision.allowed ? "taken" : "refused",
+    scope: decision.scope,
+    ...(decision.scopeKey !== undefined ? { scopeKey: decision.scopeKey } : {}),
+    ...(deviceIds[0] !== undefined ? { deviceId: deviceIds[0] } : {}),
+  };
+  if (decision.allowed) {
+    let committed = false;
+    return { ok: true, kind, commit: () => { if (!committed) { committed = true; record(event); } } };
+  }
+  record(event);
+  return { ok: false, kind, decision, response: fallbackRefusedResponse(event, hop) };
+}
+
+function scopeFlag(event: FallbackEvent): string {
+  switch (event.scope) {
+    case "device": return " --device " + event.scopeKey;
+    case "route": return " --route " + event.scopeKey;
+    case "provider": return " --provider " + event.scopeKey;
+    default: return "";
+  }
+}
+
+function scopePhrase(event: FallbackEvent): string {
+  return event.scope === "global" ? "globally" : "for " + event.scope + " " + event.scopeKey;
+}
+
+/** The stable `fallback_refused` error. Status follows the triggering failure. */
+export function fallbackRefusedResponse(event: FallbackEvent, hop: Pick<FallbackHop, "failureStatus" | "retryAfter">): Response {
+  const status = typeof hop.failureStatus === "number" && hop.failureStatus >= 400 && hop.failureStatus <= 599
+    ? hop.failureStatus
+    : event.trigger === "cooldown" || event.trigger === "quota_exhausted" || event.trigger === "rate_limited"
+      || event.trigger === "hard_lock" ? 429 : 503;
+  const kindWord = event.kind === "provider" ? "Provider" : "Model";
+  const message = event.route + ": " + event.from + " failed (" + event.trigger + "). " + kindWord
+    + " fallback to " + event.to + " is off " + scopePhrase(event) + ", so OpenCodex did not send the request there."
+    + " To allow it: ocx fallback on --kind " + event.kind + scopeFlag(event);
+  const headers = new Headers({ "x-opencodex-fallback": "refused", "cache-control": "no-store" });
+  if (hop.retryAfter) headers.set("retry-after", hop.retryAfter);
+  return Response.json({
+    error: {
+      message,
+      type: "fallback_refused",
+      code: "fallback_refused",
+      fallback: {
+        kind: event.kind,
+        scope: event.scope,
+        ...(event.scopeKey !== undefined ? { scopeKey: event.scopeKey } : {}),
+        from: event.from,
+        to: event.to,
+        trigger: event.trigger,
+      },
+    },
+  }, { status, headers });
+}
+
+/** Whether a response is this module's refusal. */
+export function isFallbackRefusal(response: Response): boolean {
+  return response.headers.get("x-opencodex-fallback") === "refused";
+}
+
+/** Carries a refusal out of a site that cannot return a Response itself. */
+export class FallbackRefusedError extends Error {
+  constructor(readonly response: Response) {
+    super("fallback_refused");
+    this.name = "FallbackRefusedError";
+  }
+}

package/src/routing/fallback-state.ts

@@ -0,0 +1,179 @@
+/**
+ * OCX-11 fallback state: the `ocx.fallback/1` read model and the one scoped write.
+ *
+ * Off the request path: the management route, `ocx fallback` and `ocx status --json` use it.
+ * The request path only resolves (`src/routing/fallback-policy.ts`).
+ */
+import type { OcxConfig } from "../types";
+import type { OcxFallbackConfig, OcxFallbackDeviceConfig, OcxFallbackSwitches } from "../types/fallback";
+import { FALLBACK_DEVICE_ID, FALLBACK_SELECTOR } from "../config/schema/fallback-policy";
+import type { LinkRecord } from "../link/store";
+import { recentFallbackEvents, type FallbackEvent } from "./fallback-policy";
+
+export const FALLBACK_STATE_SCHEMA = "ocx.fallback/1";
+
+export interface FallbackDeviceView {
+  id: string;
+  kind: "link" | "key";
+  alias?: string;
+  /** Permission for GOAT to move this device's work to its own providers while the Home is down. */
+  localFallback: boolean;
+  /** false: refused for this device whatever the other scopes say; null: not set. */
+  model: boolean | null;
+  provider: boolean | null;
+}
+
+export interface FallbackStateView {
+  schema: typeof FALLBACK_STATE_SCHEMA;
+  /** Effective global switches; absence reads true, today's behavior. */
+  global: { model: boolean; provider: boolean };
+  providers: Record<string, OcxFallbackSwitches>;
+  routes: Record<string, OcxFallbackSwitches>;
+  devices: FallbackDeviceView[];
+  last: FallbackEvent | null;
+  recent: FallbackEvent[];
+}
+
+function cleanSwitches(value: unknown): OcxFallbackSwitches {
+  const out: OcxFallbackSwitches = {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return out;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.model === "boolean") out.model = raw.model;
+  if (typeof raw.provider === "boolean") out.provider = raw.provider;
+  return out;
+}
+
+function cleanMap(value: unknown, pattern: RegExp): Record<string, OcxFallbackSwitches> {
+  const out: Record<string, OcxFallbackSwitches> = {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return out;
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (!pattern.test(key)) continue;
+    const switches = cleanSwitches(entry);
+    if (Object.keys(switches).length > 0) out[key] = switches;
+  }
+  return out;
+}
+
+/**
+ * Build the read model. `passive` (a Remote Link Child's read through the management relay)
+ * drops link aliases and per-event device ids, so a Child learns its own row by link id only.
+ */
+export function buildFallbackState(
+  config: Pick<OcxConfig, "fallback">,
+  options: { links?: readonly Pick<LinkRecord, "id" | "alias" | "apiKeyId">[]; passive?: boolean } = {},
+): FallbackStateView {
+  const policy: OcxFallbackConfig = config.fallback ?? {};
+  const devicesRaw = policy.devices && typeof policy.devices === "object" ? policy.devices : {};
+  const rows = new Map<string, FallbackDeviceView>();
+  const deviceRow = (id: string, kind: "link" | "key", alias?: string): FallbackDeviceView => {
+    const raw = (Object.hasOwn(devicesRaw, id) ? devicesRaw[id] : undefined) as OcxFallbackDeviceConfig | undefined;
+    return {
+      id,
+      kind,
+      ...(alias && !options.passive ? { alias } : {}),
+      localFallback: raw?.localFallback === true,
+      model: typeof raw?.model === "boolean" ? raw.model : null,
+      provider: typeof raw?.provider === "boolean" ? raw.provider : null,
+    };
+  };
+  for (const link of options.links ?? []) rows.set(link.id, deviceRow(link.id, "link", link.alias));
+  for (const id of Object.keys(devicesRaw)) {
+    if (!FALLBACK_DEVICE_ID.test(id) || rows.has(id)) continue;
+    rows.set(id, deviceRow(id, id.startsWith("lnk_") ? "link" : "key"));
+  }
+  const recent = recentFallbackEvents().map(event => {
+    if (!options.passive || event.deviceId === undefined) return event;
+    const { deviceId: _omitted, ...rest } = event;
+    return rest;
+  });
+  return {
+    schema: FALLBACK_STATE_SCHEMA,
+    global: { model: policy.model !== false, provider: policy.provider !== false },
+    providers: cleanMap(policy.providers, FALLBACK_SELECTOR),
+    routes: cleanMap(policy.routes, FALLBACK_SELECTOR),
+    devices: [...rows.values()],
+    last: recent.at(-1) ?? null,
+    recent,
+  };
+}
+
+export type FallbackWriteScope = "global" | "provider" | "route" | "device";
+export type FallbackWriteSetting = "model" | "provider" | "localFallback";
+
+export interface FallbackWrite {
+  scope: FallbackWriteScope;
+  key?: string;
+  setting: FallbackWriteSetting;
+  /** true or false sets the leaf; null removes it so the scope inherits again. */
+  value: boolean | null;
+}
+
+/** Validate a write body; the error text is operator-facing. */
+export function parseFallbackWrite(body: unknown): { ok: true; write: FallbackWrite } | { ok: false; error: string } {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: "expected a JSON object" };
+  const raw = body as Record<string, unknown>;
+  const scope = raw.scope;
+  const setting = raw.setting;
+  const value = raw.value;
+  if (scope !== "global" && scope !== "provider" && scope !== "route" && scope !== "device") {
+    return { ok: false, error: "scope must be global, provider, route or device" };
+  }
+  if (setting !== "model" && setting !== "provider" && setting !== "localFallback") {
+    return { ok: false, error: "setting must be model, provider or localFallback" };
+  }
+  if (value !== true && value !== false && value !== null) return { ok: false, error: "value must be true, false or null" };
+  if (setting === "localFallback" && scope !== "device") return { ok: false, error: "localFallback is set per device" };
+  if (scope === "global") {
+    if (raw.key !== undefined) return { ok: false, error: "a global write takes no key" };
+    return { ok: true, write: { scope, setting, value } };
+  }
+  const key = raw.key;
+  const pattern = scope === "device" ? FALLBACK_DEVICE_ID : FALLBACK_SELECTOR;
+  if (typeof key !== "string" || !pattern.test(key)) return { ok: false, error: scope + " key is missing or malformed" };
+  return { ok: true, write: { scope, key, setting, value } };
+}
+
+/** Up to 8 writes applied in one config mutation: `{ writes: [...] }`, or a single write. */
+export const MAX_FALLBACK_WRITES = 8;
+
+export function parseFallbackWrites(body: unknown): { ok: true; writes: FallbackWrite[] } | { ok: false; error: string } {
+  const list = body && typeof body === "object" && !Array.isArray(body) && Object.hasOwn(body, "writes")
+    ? (body as { writes: unknown }).writes
+    : [body];
+  if (!Array.isArray(list) || list.length === 0 || list.length > MAX_FALLBACK_WRITES) {
+    return { ok: false, error: "writes must hold 1 to " + MAX_FALLBACK_WRITES + " entries" };
+  }
+  const writes: FallbackWrite[] = [];
+  for (const entry of list) {
+    const parsed = parseFallbackWrite(entry);
+    if (!parsed.ok) return parsed;
+    writes.push(parsed.write);
+  }
+  return { ok: true, writes };
+}
+
+function setLeaf(target: Record<string, unknown>, setting: string, value: boolean | null): void {
+  if (value === null) delete target[setting];
+  else target[setting] = value;
+}
+
+/** Apply one write to a config in place; reports whether anything changed. */
+export function applyFallbackWrite(config: OcxConfig, write: FallbackWrite): boolean {
+  const before = JSON.stringify(config.fallback ?? null);
+  const policy: Record<string, unknown> = { ...(config.fallback ?? {}) };
+  if (write.scope === "global") {
+    setLeaf(policy, write.setting, write.value);
+  } else {
+    const mapName = write.scope === "provider" ? "providers" : write.scope === "route" ? "routes" : "devices";
+    const map: Record<string, Record<string, unknown>> = { ...((policy[mapName] as Record<string, Record<string, unknown>> | undefined) ?? {}) };
+    const entry = { ...(Object.hasOwn(map, write.key!) ? map[write.key!] : {}) };
+    setLeaf(entry, write.setting, write.value);
+    if (Object.keys(entry).length > 0) map[write.key!] = entry;
+    else delete map[write.key!];
+    if (Object.keys(map).length > 0) policy[mapName] = map;
+    else delete policy[mapName];
+  }
+  if (Object.keys(policy).length > 0) config.fallback = policy as OcxFallbackConfig;
+  else delete config.fallback;
+  return JSON.stringify(config.fallback ?? null) !== before;
+}

package/src/server/audio-client.ts

@@ -4,6 +4,7 @@ import type { OcxConfig } from "../types";
 import { captureExplicitOpenAiCallerAuth, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
 import { isProxyAdmissionSecret, type DataPlaneAdmission, type DataPlaneAdmissionOptions } from "./auth-cors";
 import { resolveAudioAdmission } from "./audio-upstream";
+import { authorizationCredential } from "../lib/authorization-scheme";
 
 export const AUDIO_WEBSOCKET_PROTOCOL = "opencodex-audio";
 const KEY_PROTOCOL_PREFIX = "opencodex-key.";
@@ -61,7 +62,7 @@ export function resolveAudioClient(
       : null;
   }
   const credential = admission.source === "dedicated" ? headers.get("x-opencodex-api-key")
-    : admission.source === "x-api-key" ? headers.get("x-api-key") : headers.get("authorization")?.replace(/^Bearer\s+/i, "");
+    : admission.source === "x-api-key" ? headers.get("x-api-key") : authorizationCredential(headers);
   const owner = admission.kind === "configured"
     ? JSON.stringify(["configured", admission.keyId])
     : JSON.stringify(["environment", createHash("sha256").update(credential?.trim() ?? "").digest("hex")]);

package/src/server/audio-dictation.ts

@@ -4,6 +4,7 @@ import type { OcxConfig } from "../types";
 import type { AudioClient } from "./audio-client";
 import { resolveAudioUpstream, TRANSCRIPTION_MODEL, type AudioUpstream } from "./audio-upstream";
 import type { RequestLogContext } from "./request-log";
+import { authorizationCredential } from "../lib/authorization-scheme";
 
 export const DICTATION_SESSION_MAX_MS = 300_000;
 const DICTATION_FRAME_MAX_BYTES = 64 * 1024;
@@ -74,7 +75,7 @@ export async function resolveDictationSocket(
     return formatErrorResponse(400, "invalid_request_error", "Streaming dictation requires a connected ChatGPT account");
   }
   const headers = new Headers(relay.headers);
-  const token = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const token = authorizationCredential(headers);
   if (!token || /[\s,]/.test(token)) {
     relay.release();
     return formatErrorResponse(401, "authentication_error", "Dictation account authentication unavailable");

package/src/server/audio-upstream.ts

@@ -24,6 +24,7 @@ import {
 } from "./auth-cors";
 import { codexAccountSelectionForTurn } from "./lifecycle";
 import type { RequestLogContext } from "./request-log";
+import { authorizationCredential } from "../lib/authorization-scheme";
 
 export const TRANSCRIPTION_MODEL = "gpt-4o-transcribe";
 export const LIVE_AUDIO_MODEL = "gpt-live-1-codex";
@@ -77,7 +78,7 @@ export async function resolveAudioUpstream(
     if (candidates.keyed?.providerName !== options.providerName) delete candidates.keyed;
   }
   const headers = new Headers(incoming);
-  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(headers);
   if (bearer && isProxyAdmissionSecret(bearer, config)) {
     headers.delete("authorization");
     headers.delete("chatgpt-account-id");

package/src/server/auth-cors.ts

@@ -47,6 +47,7 @@ import { modelAutoCompactTokenLimitsConfigError } from "../providers/auto-compac
 import { vercelGatewayRoutingConfigError } from "../providers/vercel-gateway-routing";
 import { googleVertexLocationConfigError } from "../providers/google-vertex-location";
 import { xaiResponsesOptInState } from "../providers/xai-responses-opt-in";
+import { authorizationCredential } from "../lib/authorization-scheme";
 
 let _corsOrigin = "http://localhost:10100";
 // Listener identity is process-local. Never infer this trust from forwarded headers: the
@@ -501,7 +502,7 @@ export function resolveContextPrincipal(req: Request, config: OcxConfig, admissi
   if (named) return named;
   if (admission?.kind !== "loopback") return undefined;
   const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
-  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(req.headers);
   const apiKey = req.headers.get("x-api-key")?.trim();
   for (const [token, source] of [[dedicated, "dedicated"], [bearer, "bearer"], [apiKey, "x-api-key"]] as const) {
     if (!token) continue;
@@ -600,13 +601,13 @@ export class ForwardAdmissionCredentialError extends Error {
 }
 
 export function validateForwardAdmissionCredential(headers: Headers, config: OcxConfig): void {
-  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(headers);
   if (bearer && isProxyAdmissionSecret(bearer, config)) throw new ForwardAdmissionCredentialError();
 }
 
 /** Whether Authorization carries a caller-owned native Codex credential safe to forward. */
 export function hasForwardableCodexBearer(headers: Headers, config: OcxConfig): boolean {
-  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(headers);
   const accountId = headers.get("chatgpt-account-id")?.trim()
     || (bearer ? extractAccountId(undefined, bearer) : undefined);
   return !!bearer && !!accountId && !isProxyAdmissionSecret(bearer, config);
@@ -621,7 +622,7 @@ export function resolveApiAuth(req: Request, config: RequestPolicyView): DataPla
   if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
   const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
   if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
-  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(req.headers);
   if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
   // Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
   const apiKey = req.headers.get("x-api-key")?.trim();
@@ -653,7 +654,7 @@ export function resolveResponsesApiAuth(req: Request, config: RequestPolicyView)
   // safe because the upstream credential is then SUBSTITUTED rather than forwarded -- see
   // materializeCodexUpstreamAuth. A bearer that is NOT our secret stays unadmitted here and
   // remains Codex Direct passthrough, so the two bearer domains still never mix.
-  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const bearer = authorizationCredential(req.headers);
   if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
   // `x-api-key` is deliberately NOT accepted on this transport.
   return null;