UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,568 lines • 94.3 kB
import { hasHumanDashboardSession } from "./consent-session";
import { runPassiveReadSync } from "../../lib/passive-read";
import { isAnthropicOAuthInstance, configuredAnthropicInstance, type AnthropicInstanceId } from "../../providers/anthropic-instance";
import { resolveAnthropicAccountPoolConfig } from "../../oauth/anthropic-pool-config";
import { persistAnthropicPoolPatch, writeAnthropicPoolSettings } from "./anthropic-pool-settings";
import { parseAnthropicModelRoutes, readAnthropicModelRoutes } from "../../oauth/anthropic-model-routes";
import { effectiveAnthropicAccountThresholdForInstance } from "../../oauth/anthropic-account-threshold";
import { handleAnthropicAccountThreshold } from "./anthropic-account-threshold";
import { randomBytes, randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import type { CatalogModel } from "../../codex/catalog";
import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
import {
  DEFAULT_SUBAGENT_MODELS,
  codexAutoStartEnabled,
  hasOwnProvider,
  isValidProviderName,
  multiAgentGuidanceEnabled,
  providerBaseUrlConfigError,
  providerHeadersConfigError,
  readConfigDiagnostics,
  reconcileLiveConfigFromDisk,
  saveConfigPreservingClaudeCode,
} from "../../config";
import {
  clearLoginState,
  getLoginStatus,
  isCodeLoginFlow,
  isPublicOAuthProvider,
  listOAuthProviders,
  loginFlowAccountId,
  OAUTH_PROVIDERS,
  publicOAuthAuthenticationErrorMessage,
  startLoginFlow,
  submitLoginCode,
  submitManualLoginCode,
  supportsCodeLoginMode,
  supportsDeviceLoginMode,
  waitForLoginSettled,
} from "../../oauth";
import { OAuthMutationBusyError, removeCredential } from "../../oauth/store";
import { isOAuthCredentialSiblingOf, oauthCredentialSiblingsOf, oauthCredentialSlot } from "../../oauth/credential-siblings";
import {
  ANTIGRAVITY_RISK_PROVIDER,
  ANTIGRAVITY_RISK_REFUSAL_CODE,
  antigravityRiskRefusalBody,
  hasAntigravityRiskAcknowledgement,
  requiresAntigravityRiskAcknowledgement,
} from "../../oauth/antigravity-risk";
import { cancelKiroDeviceLogin, kiroDeviceConfigBaseline, selectKiroDeviceProfile, startKiroDeviceLogin, statusKiroDeviceLogin, type KiroDeviceMethod } from "../../oauth/kiro-device-login";
import { parseKiroIamOptions } from "../../oauth/kiro-iam-identity-center";
import { providerDestinationResolvedError } from "../../lib/destination-policy";
import { accountDisplayLabel, emailMaskingEnabled, maskedAccountLabel } from "../../lib/privacy";
import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
import { deriveProviderPresets } from "../../providers/derive";
import { providerCodexAccountMode } from "../../providers/registry";
import { routedSlug, slugEquals } from "../../providers/slug-codec";
import { clearAccountQuotaCache, clearProviderQuotaCache, clearProviderQuotaCacheFor, fetchProviderAccountQuotas, fetchProviderApiKeyQuotas, fetchProviderQuotaReports, providerOAuthAccountQuotaMode, providerApiKeyQuotaMode, readPassiveProviderAccountQuotas } from "../../providers/quota";
import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import { clearThreadAccountMap } from "../../codex/routing";
import {
  normalizeAccountPoolStickyLimit,
  normalizeAccountPoolStrategy,
  parseAccountPoolStickyLimit,
  parseAccountPoolStrategy,
  parseCodexAccountPoolStrategy,
} from "../../codex/pool-rotation";
import { normalizeAccountPoolQuotaWindow, parseAccountPoolQuotaWindow } from "../../oauth/anthropic-routing";
import { primeCodexPoolQuotas } from "../../codex/auth-api";
import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
import { resolveCodexHomeDir } from "../../codex/home";
import { readUsageEntries } from "../../usage/log";
import { getUsageDebugLogEntries } from "../../usage/debug";
import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
import { getProviderRegistryEntry } from "../../providers/registry";
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
import {
  clearDebugSettings,
  clearDebugSetting,
  getDebugSettings,
  setDebugSettings,
  type DebugFlag,
} from "../../lib/debug-settings";
import type { OcxApiKeyEntry, OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
import { drainAndShutdown } from "../lifecycle";
import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
import type { PersistedUsageAttempt } from "../../usage/log";
import { AUTH_MATRIX, isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
import { applySystemEnvToggle } from "../system-env";
import { buildApiAccessEndpoints } from "./api-access";
import {
  abortApiKeyRotation,
  commitApiKeyRotation,
  removeExpiredApiKeyRotations,
  startApiKeyRotation,
} from "./api-key-rotation";

import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
import type { ManagementContext } from "./context";
import { readManagementJsonBody, readManagementJsonBodyOr, rethrowManagementBodyTooLarge } from "./body";
import { codexAccountNamespaceProviderCollisionError } from "../../codex/account-namespace-match";

/**
 * Provider ids that share the Devin cloud-direct client, and therefore share its
 * process-memory caches.
 *
 * `devin-cli` is a deprecated alias for the merged `devin` provider, but a
 * config row the startup migration has not rekeyed yet can still arrive here —
 * and its logout/removal must clear the same caches, because both ids hand the
 * same api_key to the same client and one cache serves both.
 */
function isDevinCloudDirectProvider(provider: string): boolean {
  return provider === "devin" || provider === "devin-cli";
}

/**
 * Quota invalidation after an account mutation. A B mutation retires only B's provider-level
 * report, routing row and per-account rows; A's cache, epochs and in-flight probes survive.
 * Other providers keep the global clear; `accountRows` also drops that provider's account rows.
 */
function clearQuotaCachesAfterAccountMutation(provider: string, accountRows: boolean): void {
  if (provider === "anthropic2") {
    clearProviderQuotaCacheFor(provider);
    clearAccountQuotaCache(provider);
    return;
  }
  clearProviderQuotaCache();
  if (accountRows) clearAccountQuotaCache(provider);
}

async function clearDevinCloudDirectCaches(): Promise<void> {
  const { clearCachedUserJwt, clearCachedCatalog } = await import("../../adapters/devin/cloud-direct");
  clearCachedUserJwt();
  clearCachedCatalog();
}
import { ACCOUNT_IMPORT_DEADLINE_MS, ACCOUNT_IMPORT_MAX_REQUEST_BYTES } from "../../oauth/account-import";
import { readBoundedJsonRequestBody } from "../request-decompress";

// ACCOUNT_IMPORT_DEADLINE_MS is the shared CLI/server import window. Individual
// provider requests keep their own shorter timeouts; this is only the server-side
// backstop for the admitted batch. A disconnected request aborts immediately
// through req.signal below.

/**
 * Parses a bounded JSON object body, or null. Malformed JSON is swallowed; an
 * oversized body still throws so the management dispatcher can return 413.
 * a malformed body, which used to surface as a 500 from the key routes.
 */
async function readJsonBody(req: Request): Promise<Record<string, unknown> | null> {
  try {
    const parsed: unknown = await readManagementJsonBody(req);
    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
      ? parsed as Record<string, unknown>
      : null;
  } catch (error) {
    rethrowManagementBodyTooLarge(error);
    return null;
  }
}

/**
 * The single place key-name rules live. The config read schema is deliberately
 * permissive so an existing config can never become unloadable; this is the write
 * boundary that keeps new junk out. A non-string name used to reach `.trim()` and
 * throw.
 */
function validateKeyName(
  raw: unknown,
  opts: { required: boolean },
): { value: string } | { error: string } {
  if (raw === undefined || raw === null) {
    return opts.required ? { error: "name required" } : { value: "" };
  }
  if (typeof raw !== "string") return { error: "name must be a string" };
  // Check the RAW string: trimming first would silently accept "deploy\n" by
  // deleting the very character being rejected.
  // eslint-disable-next-line no-control-regex
  if (/[\u0000-\u001f\u007f]/.test(raw)) return { error: "invalid name" };
  const value = raw.trim();
  if (opts.required && !value) return { error: "name required" };
  if (value.length > 64) return { error: "name too long" };
  return { value };
}

export type IssuedApiKey = Pick<OcxApiKeyEntry, "id" | "name" | "key" | "createdAt">;

/** Shared one-time data-key issuance used by the dashboard and link transactions. */
export function issueApiKeyInProcess(config: OcxConfig, name: string, reservedId?: string): IssuedApiKey {
  const checked = validateKeyName(name, { required: true });
  if ("error" in checked) throw new Error(checked.error);
  // An operation journal reserves the id before it issues the key, so a crash can be matched to it later.
  if (reservedId !== undefined && (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(reservedId) || (config.apiKeys ?? []).some(key => key.id === reservedId))) {
    throw new Error("The reserved key id is invalid or already in use.");
  }
  const entry: IssuedApiKey = {
    id: reservedId ?? randomUUID(),
    name: checked.value,
    key: `ocx_data_${randomBytes(20).toString("hex")}`,
    createdAt: new Date().toISOString(),
  };
  const previous = config.apiKeys;
  config.apiKeys = [...(previous ?? []), entry];
  try {
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
  } catch (error) {
    config.apiKeys = previous;
    throw error;
  }
  return entry;
}

/** Revoke and persist one data key; callers can retain their own record on false. */
export function revokeApiKeyInProcess(config: OcxConfig, id: string): boolean {
  const before = config.apiKeys ?? [];
  if (!before.some(key => key.id === id)) return false;
  config.apiKeys = before.filter(key => key.id !== id);
  try {
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
  } catch (error) {
    config.apiKeys = before;
    throw error;
  }
  return true;
}

function canStartManagementOAuth(provider: string, ctx: ManagementContext): boolean {
  return provider !== "meta-muse" || hasHumanDashboardSession(ctx);
}

function metaMuseConsentRequired(provider: string, ctx: ManagementContext): Response | null {
  if (canStartManagementOAuth(provider, ctx)) return null;
  return jsonResponse({
    error: "Meta Muse login requires acknowledgement in the OpenCodex dashboard.",
    code: "oauth_consent_required",
  }, 403);
}

function genericOAuthProviderConfig(provider: string, config: ManagementContext["config"]) {
  const configured = config.providers[provider];
  if (provider === "anthropic2" && !configuredAnthropicInstance(config, provider)) return undefined;
  if (configured) return configured;
  const definition = OAUTH_PROVIDERS[provider];
  return definition?.resolveProviderConfig?.(config) ?? definition?.providerConfig;
}

let accountProbeRunning = false;

export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<Response | null> {
  const { req, url, config, deps, principal, syncClaudeAgentDefsBestEffort } = ctx;

  if (url.pathname === "/api/accounts/events" && req.method === "GET") {
    const { accountSelectionStream } = await import("./account-selection-stream");
    return accountSelectionStream(req, () => ctx.sessionControl?.isCurrent(req, config) === true);
  }

  // Which providers support real OAuth login (drives the GUI's "Log in with …" buttons).
  if (url.pathname === "/api/oauth/providers" && req.method === "GET") {
    // Discovery reflects this principal's admission; hiding a button is not the
    // consent boundary, which remains independently enforced on both POST routes.
    return jsonResponse({ providers: listOAuthProviders().filter(provider => canStartManagementOAuth(provider, ctx)) });
  }

  // API-key "login" providers (open dashboard → paste key). Drives the GUI's key-provider picker.
  if (url.pathname === "/api/key-providers" && req.method === "GET") {
    return jsonResponse({ providers: listKeyLoginProviders() });
  }

  // OAuth login (xai now; anthropic/kimi in cycle 2). Starts the flow and returns the auth URL;
  // the provider's loopback callback server (inside this process) captures the redirect in the
  // background, then the credential is persisted. The GUI opens the URL and polls /api/oauth/status.
  if (url.pathname === "/api/oauth/login" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; row?: unknown; addAccount?: boolean; accountId?: string; reauth?: boolean; openBrowser?: unknown; method?: unknown; mode?: unknown; device?: unknown; startUrl?: unknown; region?: unknown; flowId?: unknown; profileArn?: unknown };
    const provider = (body.provider ?? "").trim().toLowerCase();
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    // `row`: the sibling provider row this login publishes (Kimi (Responses) through the Kimi login).
    if (body.row !== undefined && (typeof body.row !== "string" || !isOAuthCredentialSiblingOf(body.row, provider))) {
      return jsonResponse({ error: "row must be a provider that shares this login" }, 400);
    }
    // Antigravity sign-in can get the Google account disabled. Every client asks first; this is
    // the check none of them can skip, and it runs before any flow state is created.
    if (requiresAntigravityRiskAcknowledgement(provider) && !hasAntigravityRiskAcknowledgement(body)) {
      return jsonResponse(antigravityRiskRefusalBody(), 403);
    }
    if (provider === "m365-copilot") {
      const { shouldOpenBrowserForLogin } = await import("../../oauth/open-browser-choice");
      if (!shouldOpenBrowserForLogin(body.openBrowser, config)) {
        return jsonResponse({ error: "Microsoft 365 Copilot sign-in requires an isolated window in a supported local browser." }, 400);
      }
    }
    // Omitted mode is the localhost-callback flow this route has always run.
    if (body.mode !== undefined && body.mode !== "callback" && body.mode !== "code") {
      return jsonResponse({ error: "mode must be \"callback\" or \"code\"" }, 400);
    }
    const codeMode = body.mode === "code";
    if (codeMode && !supportsCodeLoginMode(provider)) {
      return jsonResponse({ error: "code_mode_unsupported" }, 400);
    }
    // `device: true` picks the provider's device grant over its browser callback (xAI).
    if (body.device !== undefined && body.device !== true) return jsonResponse({ error: "device must be true" }, 400);
    const device = body.device === true;
    if (device && (codeMode || !supportsDeviceLoginMode(provider))) {
      return jsonResponse({ error: "device_login_unsupported" }, 400);
    }
    // Muse may import a local Keychain credential or start a device grant; add-account
    // and reauth skip the import. All management login paths require the dashboard
    // principal before credential acquisition. A raw token proves administration,
    // not acknowledgement; caller-supplied headers are not consent evidence.
    const consentRequired = metaMuseConsentRequired(provider, ctx);
    if (consentRequired) return consentRequired;
    const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, provider);
    if (namespaceCollision) return jsonResponse({ error: namespaceCollision }, 409);
    const accountId = body.accountId?.trim();
    const reauth = body.reauth === true || Boolean(accountId);
    if (provider === "kiro") {
      if (reauth && !accountId) return jsonResponse({ error: "Kiro reauth requires an accountId" }, 400);
      if (body.flowId !== undefined) {
        if (reauth || body.method !== undefined || typeof body.flowId !== "string" || body.flowId.length > 128
          || typeof body.profileArn !== "string" || body.profileArn.length > 256) return jsonResponse({ error: "invalid Kiro profile selection" }, 400);
        const owner = principal ?? "admin-token";
        const baseline = kiroDeviceConfigBaseline(body.flowId, owner);
        const status = await selectKiroDeviceProfile(body.flowId, owner, body.profileArn);
        if (!status) return jsonResponse({ error: "unknown Kiro profile selection" }, 404);
        if (status.state === "done") {
          reconcileLiveConfigFromDisk(config, baseline ?? structuredClone(config));
          reconcileLiveStateStores();
        }
        return jsonResponse(status);
      }
      if (body.method !== undefined) {
        if (body.method !== "builder-id" && body.method !== "google" && body.method !== "github" && body.method !== "iam-identity-center") {
          return jsonResponse({ error: "invalid Kiro device method" }, 400);
        }
        if (reauth) return jsonResponse({ error: "native_login_is_add_only" }, 400);
        const iam = body.method === "iam-identity-center" ? parseKiroIamOptions(body) : undefined;
        if (body.method === "iam-identity-center" && !iam) return jsonResponse({ error: "invalid Kiro IAM portal or region" }, 400);
        try {
          return jsonResponse(await startKiroDeviceLogin(body.method as KiroDeviceMethod, principal ?? "admin-token", readConfigDiagnostics().config, iam));
        } catch {
          return jsonResponse({ error: "Kiro device login could not start" }, 409);
        }
      }
    }
    try {
      if (accountId) {
        const { getAccountSet } = await import("../../oauth/store");
        const set = getAccountSet(provider);
        if (!set?.accounts.some(a => a.id === accountId)) {
          return jsonResponse({ error: "Unknown account for reauth" }, 404);
        }
      }
      // Use persisted state, not the live object, as the merge base: another management
      // request may already have mutated live config and yielded before its save.
      const persistedBaseline = readConfigDiagnostics().config;
      // addAccount / reauth forces a fresh browser identity (skips local-CLI token import).
      // The xAI device caller also needs its own flow identity for polling.
      const flowId = codeMode || provider === "m365-copilot" || (provider === "xai" && device) ? randomUUID() : undefined;
      const { url: authUrl, instructions, deviceCode, expiresAt } = await startLoginFlow(provider, {
        forceLogin: body.addAccount === true || reauth,
        ...(accountId ? { reauthAccountId: accountId } : {}),
        ...(codeMode ? { codeMode: true } : {}),
        ...(device ? { flow: "device" as const } : {}),
        ...(typeof body.row === "string" ? { publishRow: body.row } : {}),
      }, {
        ...(flowId ? { flowId } : {}),
        // startLoginFlow returns the authorization URL before background persistence completes.
        // Three-way reconcile settled disk changes so a failed login cannot leave a provider
        // live-only and an in-flight management mutation cannot be erased before it saves.
        onSettled: () => {
          reconcileLiveConfigFromDisk(config, persistedBaseline);
          reconcileLiveStateStores();
        },
      });
      // Open the browser server-side (the proxy runs on the user's machine) — the GUI's
      // window.open is popup-blocked because it runs after an await, not a direct click.
      //
      // The operator can decline, which is the only way to finish a login in a
      // browser profile other than the OS default, or on a different machine
      // than the proxy. Declining changes nothing else: the URL is still
      // returned below and every login surface renders it with a copy button.
      //
      // The launch outcome is returned rather than discarded, the same contract the Codex
      // account login already keeps: a login whose browser never opened otherwise reads as one
      // that did, and the dashboard can only say so if it is told. `openUrl` answers within its
      // short settle window and never rejects.
      const { shouldOpenBrowserForLogin } = await import("../../oauth/open-browser-choice");
      let browserLaunch: "started" | "failed" | "skipped" = "skipped";
      if (authUrl && !deviceCode && shouldOpenBrowserForLogin(body.openBrowser, config)) {
        const { openUrl } = await import("../../lib/open-url");
        browserLaunch = (await openUrl(authUrl)).status === "started" ? "started" : "failed";
      }
      return jsonResponse({
        url: authUrl,
        instructions,
        deviceCode,
        browserLaunch,
        ...(codeMode ? { mode: "code", flowId, expiresAt } : flowId ? { flowId } : {}),
      });
    } catch (err) {
      if (err instanceof OAuthMutationBusyError) throw err;
      const message = err instanceof Error ? err.message : String(err);
      const duplicateLoginMessage = `A login for ${provider} is already in progress`;
      return jsonResponse({
        error: message === duplicateLoginMessage
          ? duplicateLoginMessage
          : publicOAuthAuthenticationErrorMessage(err),
      }, 409);
    }
  }

  // Cancel an in-progress browser/device OAuth login (GUI "Cancel" / modal close). Guarded by
  // the same public predicate as /api/oauth/login — only publicly startable flows are cancellable.
  if (url.pathname === "/api/oauth/login/cancel" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; flowId?: unknown };
    const provider = (body.provider ?? "").trim().toLowerCase();
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (provider === "kiro" && body.flowId !== undefined) {
      if (typeof body.flowId !== "string") return jsonResponse({ error: "unknown login flow" }, 404);
      const result = cancelKiroDeviceLogin(body.flowId, principal ?? "admin-token");
      return result ? jsonResponse(result) : jsonResponse({ error: "unknown login flow" }, 404);
    }
    if ((provider === "m365-copilot" || (provider === "xai" && body.flowId !== undefined))
      && (typeof body.flowId !== "string" || !body.flowId.trim() || body.flowId.length > 128)) return jsonResponse({ error: "unknown login flow" }, 404);
    const { cancelLoginFlow } = await import("../../oauth");
    // Without a flow id this cancels the provider's newest in-flight login, which is what the
    // single-user GUI has always meant by "Cancel". A host running concurrent code logins for
    // several users passes the flowId it was given at /api/oauth/login.
    const cancelled = cancelLoginFlow(provider, typeof body.flowId === "string" ? body.flowId : undefined,
      { dismissSettledFailure: true });
    return jsonResponse({ ok: true, cancelled });
  }

  // Manual fallback for browser OAuth: paste the final redirect URL (or authorization code)
  // when the browser cannot reach the loopback callback (remote/SSH/blocked localhost).
  //
  // A code-display flow (started with mode:"code", or identified by its flowId) gets the
  // richer contract instead: the paste is answered with the OUTCOME of the token exchange,
  // not merely with "accepted". A hosted caller has one paste box and no second channel, so
  // "accepted" is indistinguishable from "worked" to the person typing.
  if (url.pathname === "/api/oauth/login/code" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; input?: string; code?: string; flowId?: unknown };
    const provider = (body.provider ?? "").trim().toLowerCase();
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    const consentRequired = metaMuseConsentRequired(provider, ctx);
    if (consentRequired) return consentRequired;
    if (provider === "m365-copilot") return jsonResponse({ ok: false, error: "no_pending_login" }, 409);
    const flowId = typeof body.flowId === "string" ? body.flowId : undefined;
    const maskEmails = emailMaskingEnabled(config);
    // Only a code flow of THIS provider gets the outcome-waiting contract; that flow is single-use,
    // so at most one request ever waits on it. A flow id naming anything else (a callback flow,
    // another provider's flow, nothing) has no code login to complete.
    const codeFlow = isCodeLoginFlow(provider, flowId);
    if (flowId !== undefined && !codeFlow) return jsonResponse({ ok: false, error: "no_pending_login" }, 409);
    const input = typeof body.input === "string" ? body.input : typeof body.code === "string" ? body.code : "";
    // Authorization responses are measured in hundreds of bytes; never accept the
    // generic management-body allowance here.
    if (input.length > 4096) {
      return codeFlow
        ? jsonResponse({ ok: false, error: "malformed_input" }, 400)
        : jsonResponse({ error: "input too long" }, 400);
    }
    if (!codeFlow) {
      const result = submitManualLoginCode(provider, input);
      if (!result.ok) return jsonResponse({ error: result.error }, 409);
      return jsonResponse({ ok: true });
    }
    const submitted = submitLoginCode(provider, input, flowId);
    // Rejected before any token request: the flow stays alive so the user can paste again.
    if (!submitted.ok) {
      return jsonResponse({ ok: false, error: submitted.code }, submitted.code === "no_pending_login" ? 409 : 400);
    }
    // The exchange itself times out at 30s inside the provider client; this only has to
    // outlast it so a hung socket surfaces as an answer rather than as a hung request.
    // Pinned to the flow this paste actually landed in: with several code logins in flight for
    // one provider, "the newest flow" by the time this resolves may be somebody else's.
    const settled = await waitForLoginSettled(provider, 60_000, submitted.flowId);
    const status = getLoginStatus(provider, maskEmails, submitted.flowId);
    if (!settled) return jsonResponse({ ok: false, error: "provider_unreachable" }, 400);
    if (status.error) {
      const failure = status.errorCode ?? "invalid_or_expired_code";
      return jsonResponse({ ok: false, error: failure }, failure === "no_pending_login" ? 409 : 400);
    }
    // A flow dropped while waiting (logout, clear) never completed, whatever the store now holds.
    if (status.status !== "complete") return jsonResponse({ ok: false, error: "no_pending_login" }, 409);
    // The account THIS flow wrote, which need not be the active one (reauth of an inactive account,
    // or a concurrent login that finished later).
    const savedId = loginFlowAccountId(provider, submitted.flowId);
    const account = savedId === undefined ? undefined : status.accounts?.find(entry => entry.id === savedId);
    return jsonResponse({ ok: true, ...(account ? { account: { id: account.id, email: account.email } } : {}) });
  }

  if (url.pathname === "/api/oauth/status" && req.method === "GET") {
    const provider = oauthCredentialSlot((url.searchParams.get("provider") ?? "").trim().toLowerCase());
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (provider === "kiro" && url.searchParams.has("flowId")) {
      const flowId = url.searchParams.get("flowId") ?? "";
      const baseline = kiroDeviceConfigBaseline(flowId, principal ?? "admin-token");
      const status = await statusKiroDeviceLogin(flowId, principal ?? "admin-token");
      if (!status) return jsonResponse({ error: "unknown login flow" }, 404);
      if (status.state === "done") {
        reconcileLiveConfigFromDisk(config, baseline ?? structuredClone(config));
        reconcileLiveStateStores();
      }
      return jsonResponse(status);
    }
    // Resolved here, at the request boundary that already holds the config, and passed down.
    // getLoginStatus stays free of config I/O. This route does not re-mask afterwards: it
    // consumes the already-projected status rather than redacting a second time.
    const flowId = url.searchParams.get("flowId") ?? undefined;
    if (provider === "m365-copilot") {
      const maskEmails = emailMaskingEnabled(config);
      if (flowId === undefined && url.searchParams.get("summary") === "1") {
        return jsonResponse(getLoginStatus(provider, maskEmails, ""));
      }
      if (!flowId || flowId.length > 128) return jsonResponse({ error: "unknown login flow" }, 404);
      const status = getLoginStatus(provider, maskEmails, flowId);
      return status.flowId === flowId ? jsonResponse(status) : jsonResponse({ error: "unknown login flow" }, 404);
    }
    const status = getLoginStatus(provider, emailMaskingEnabled(config), provider === "xai" ? flowId : undefined);
    return jsonResponse(status);
  }

  if (url.pathname === "/api/oauth/logout" && req.method === "POST") {
    // A sibling row (kimi-responses) has no login of its own: logging out of it removes the
    // active account of the shared slot, exactly as the neighbouring account routes map it.
    const provider = oauthCredentialSlot((url.searchParams.get("provider") ?? "").trim().toLowerCase());
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    await removeCredential(provider);
    reconcileLiveStateStores();
    clearLoginState(provider);
    const { clearModelCache } = await import("../../codex/model-cache");
    const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
    clearModelCache(provider);
    for (const row of oauthCredentialSiblingsOf(provider)) clearModelCache(row);
    clearGatherRoutedModelsInflight();
    // Drop cached/last-good quota rows tied to the removed credential.
    clearQuotaCachesAfterAccountMutation(provider, true);
    // The cached user_jwt's payload contains the api_key, and the catalog is
    // keyed by that key. Without this they outlive the credential in process
    // memory until the JWT's own ~24 minute expiry. `devin-cli` is a deprecated
    // alias whose unmigrated rows share the one cache, so gating on `devin`
    // alone left a CLI-imported key's JWT resident after its own logout.
    if (isDevinCloudDirectProvider(provider)) await clearDevinCloudDirectCaches();
    return jsonResponse({ success: true });
  }

  // Multiauth account management: list a provider's logged-in accounts, switch the active
  // one, or remove one. Emails and accountLabel follow privacy.maskEmails, maskedLabel is always
  // masked, and tokens never leave the store.
  if (url.pathname === "/api/oauth/accounts" && req.method === "GET") {
    const provider = oauthCredentialSlot((url.searchParams.get("provider") ?? "").trim().toLowerCase());
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    const showOrganizationName = principal === "gui-session" || principal === "admin-token";
    const quotaMode = providerOAuthAccountQuotaMode(provider);
    const quotaProvider = config.providers[provider];
    const { getAccountSet } = await import("../../oauth/store");
    const { isGenericFailoverProvider, kiroAutoSelection } = await import("../../oauth/generic-account-failover");
    const effectiveProvider = genericOAuthProviderConfig(provider, config);
    const supportsPause = effectiveProvider !== undefined
      && (isAnthropicOAuthInstance(provider) && effectiveProvider.authMode === "oauth"
        || isGenericFailoverProvider(provider, effectiveProvider));
    const {
      oauthAccountHealthFields,
      projectOAuthAccountHealth,
      projectStoredOAuthAccountHealth,
    } = await import("../../oauth/health");
    const projectAccounts = () => {
      const set = getAccountSet(provider);
      const maskEmails = emailMaskingEnabled(config);
      const current = getLoginStatus(provider, maskEmails);
      return {
        ...(provider === "anthropic2" ? { provider } : {}), activeAccountId: current.activeAccountId ?? null,
        accounts: (current.accounts ?? []).map(({ organizationName, ...summary }) => {
          const full = set?.accounts.find(account => account.id === summary.id);
          const health = full
            ? projectStoredOAuthAccountHealth(provider, full)
            : projectOAuthAccountHealth({
              needsReauth: summary.needsReauth === true,
              reauthReason: summary.needsReauth === true ? "refresh_failed" : undefined,
            });
          const maskedLabel = maskedAccountLabel(full?.credential.email);
          // `maskedLabel` stays masked for tray surfaces; `accountLabel` follows privacy.maskEmails.
          const accountLabel = accountDisplayLabel(full?.credential.email, maskEmails);
          return { ...summary, ...(maskedLabel ? { maskedLabel } : {}), ...(accountLabel ? { accountLabel } : {}),
            ...(showOrganizationName && organizationName ? { organizationName } : {}),
            ...oauthAccountHealthFields(provider, summary.id, health), quotaMode,
            ...(supportsPause ? { paused: full?.paused === true, ...(full?.pauseDetails ? { pauseDetails: full.pauseDetails,
              ...(full.pauseEvidence ? { pauseEvidence: full.pauseEvidence } : {}) } : {}) } : {}),
            ...(isAnthropicOAuthInstance(provider) && supportsPause ? { autoSwitchThresholdOverride: full?.autoSwitchThresholdOverride ?? null,
              effectiveAutoSwitchThreshold: effectiveAnthropicAccountThresholdForInstance(provider as AnthropicInstanceId, config, full),
              autoSwitchThreshold: effectiveAnthropicAccountThresholdForInstance(provider as AnthropicInstanceId, config) } : {}),
            ...(provider === "kiro" && full ? kiroAutoSelection(full) : {}) };
        }),
      };
    };
    // Per-account rate limits: Anthropic reports usage per credential, so every logged-in
    // account can show its own 5h/weekly bars (not just the active one). Opt-in via ?quota=1
    // so the plain account list stays a cheap local read; ?refresh=1 bypasses the TTL.
    const wantQuota = url.searchParams.get("quota") === "1" && quotaMode === "probe";
    // Meta publishes no quota endpoint: its usage is observed in-band on streaming turns
    // and read back from the cache here. `?refresh=1` is accepted and ignored on this
    // path rather than rejected -- the GUI sends it for every provider on a manual
    // refresh, and a 400 would report an error for what is simply a no-op.
    const passiveQuota = url.searchParams.get("quota") === "1" && quotaMode === "passive";
    if (!wantQuota && !passiveQuota) {
      // The Antigravity CLI probe resolves its target through this GET before posting the probe.
      const projected = provider === "google-antigravity" ? runPassiveReadSync(projectAccounts) : projectAccounts();
      return jsonResponse(projected);
    }
    const forceRefresh = url.searchParams.get("refresh") === "1";
    // Probing may refresh the active credential and mark needsReauth — project health
    // from the post-probe store so the response is not stale.
    const rows = passiveQuota
      ? readPassiveProviderAccountQuotas(provider)
      : await fetchProviderAccountQuotas(provider, forceRefresh, quotaProvider, config);
    const byId = new Map(rows.map(row => [row.accountId, row]));
    const projected = projectAccounts();
    return jsonResponse({
      ...(provider === "anthropic2" ? { provider } : {}), activeAccountId: projected.activeAccountId,
      accounts: projected.accounts.map(account => {
        const row = byId.get(account.id);
        // #8397: a passive provider with no observation for this account yet says so.
        if (!row) return passiveQuota ? { ...account, quotaUnknownReason: "passive_not_observed" } : account;
        if (config.providers[provider] !== quotaProvider || row.isCurrent?.() === false) {
          return { ...account, quota: null, quotaUnavailable: true };
        }
        return {
          ...account,
          quota: row.quota,
          ...(quotaMode === "probe" ? { quotaUnavailable: row.unavailable === true,
            ...(row.unavailable && row.quotaFailure && row.quotaFailureIsCurrent?.() === true ? { quotaFailure: row.quotaFailure } : {}),
          } : {}),
        };
      }),
    });
  }
  if (url.pathname === "/api/oauth/accounts/affinity-reset" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {});
    if (!isPlainRecord(body)) return jsonResponse({ error: "body must be an object" }, 400);
    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
    if (!isPublicOAuthProvider(provider) || !isAnthropicOAuthInstance(provider)) {
      return jsonResponse({ error: "session-affinity reset is only supported for Anthropic OAuth instances" }, 400);
    }
    const { anthropicRoutingFor } = await import("../../oauth/anthropic-routing");
    if (!await anthropicRoutingFor(provider).resetAnthropicSessionAffinityConfirmed()) {
      return jsonResponse({ code: "affinity_reset_not_persisted", provider, retryable: true }, 503);
    }
    return jsonResponse({ ok: true, provider, affinityResetConfirmed: true });
  }
  if (url.pathname === "/api/oauth/accounts/active" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; accountId?: string };
    const provider = oauthCredentialSlot((body.provider ?? "").trim().toLowerCase());
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (provider === "anthropic2" && !configuredAnthropicInstance(config, provider)) return jsonResponse({ error: "Anthropic pool instance is not configured" }, 409);
    if (!body.accountId) return jsonResponse({ error: "missing accountId" }, 400);
    const { getAccountCredentialWithStatus, setActiveAccount } = await import("../../oauth/store");
    const current = getAccountCredentialWithStatus(provider, body.accountId);
    if (!current) return jsonResponse({ error: "account not found" }, 404);
    if (current.paused) return jsonResponse({ error: "account is paused" }, 409);
    if (!(await setActiveAccount(provider, body.accountId))) {
      const latest = getAccountCredentialWithStatus(provider, body.accountId);
      if (!latest) return jsonResponse({ error: "account not found" }, 404);
      return jsonResponse({ error: latest.paused ? "account is paused" : "account selection changed" }, 409);
    }
    const { forgetGenericFailoverRoster, seedGenericPoolSelection } = await import("../../oauth/generic-account-failover");
    forgetGenericFailoverRoster(provider);
    // Seed the rotation cursor on the operator's pick, or a sticky round-robin ring hands the
    // very next dispatch back to whatever the pool had chosen. forgetGenericFailoverRoster
    // only drops the presence count; it has never touched the cursor. Same defect the Codex
    // side carries resetCodexRoutingForManualSelection for.
    seedGenericPoolSelection(provider, body.accountId);
    const anthropicRouting = isAnthropicOAuthInstance(provider)
      ? (await import("../../oauth/anthropic-routing")).anthropicRoutingFor(provider) : undefined;
    anthropicRouting?.resetAnthropicRoutingForManualSelection(body.accountId);
    const affinityReset = anthropicRouting?.flushAnthropicManualSelectionReset();
    const { clearModelCache } = await import("../../codex/model-cache");
    const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
    clearModelCache(provider);
    // A shared-login row (kimi-responses) caches its roster under its own name.
    for (const row of oauthCredentialSiblingsOf(provider)) clearModelCache(row);
    clearGatherRoutedModelsInflight();
    clearQuotaCachesAfterAccountMutation(provider, false);
    if (affinityReset && !await affinityReset) {
      return jsonResponse({ error: "Account selection was saved, but its session-affinity reset was not persisted. Retry the selection.",
        code: "affinity_reset_not_persisted", provider, activeAccountId: body.accountId,
        selectionCommitted: true, retryable: true }, 503);
    }
    return jsonResponse({ ok: true, provider, activeAccountId: body.accountId });
  }

  if (url.pathname === "/api/oauth/accounts/auto-switch" && req.method === "PUT") return handleAnthropicAccountThreshold(req, config);
  if (url.pathname === "/api/oauth/accounts/pause" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {});
    if (!isPlainRecord(body)) return jsonResponse({ error: "body must be an object" }, 400);
    const provider = oauthCredentialSlot(typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "");
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (typeof body.accountId !== "string" || body.accountId.length === 0) {
      return jsonResponse({ error: "missing accountId" }, 400);
    }
    if (typeof body.paused !== "boolean") return jsonResponse({ error: "paused must be a boolean" }, 400);
    if (body.retryAffinityReset !== undefined && typeof body.retryAffinityReset !== "boolean") {
      return jsonResponse({ error: "retryAffinityReset must be a boolean" }, 400);
    }
    if (body.ifHealthy !== undefined && typeof body.ifHealthy !== "boolean") {
      return jsonResponse({ error: "ifHealthy must be a boolean" }, 400);
    }
    if (body.ifHealthy === true && body.paused !== false) {
      return jsonResponse({ error: "ifHealthy applies only to a resume (paused: false)" }, 400);
    }

    const { isGenericFailoverProvider } = await import("../../oauth/generic-account-failover");
    const effectiveProvider = genericOAuthProviderConfig(provider, config);
    if (!effectiveProvider || !(isAnthropicOAuthInstance(provider) && effectiveProvider.authMode === "oauth"
      || isGenericFailoverProvider(provider, effectiveProvider))) {
      return jsonResponse({ error: "account pause is not supported for this OAuth provider" }, 400);
    }

    const { setAccountPaused } = await import("../../oauth/store");
    let resumeGuard: { generation: string; pauseRevision: string | undefined } | undefined;
    if (body.ifHealthy === true) {
      // Explicit resume gated on an account-bound health read (#8398); an unpaused account needs none.
      const { checkOAuthResumeHealth } = await import("../../oauth/account-resume-health");
      const verdict = await checkOAuthResumeHealth(provider, body.accountId);
      if (verdict && !verdict.ok) {
        return jsonResponse({ error: `account was not resumed: ${verdict.reason}`, code: "resume_refused", reason: verdict.reason,
          provider, accountId: body.accountId }, 409);
      }
      if (!verdict) {
        // Not paused when checked: write nothing, so a pause that lands meanwhile is never cleared unchecked.
        const { getAccountSet } = await import("../../oauth/store");
        const set = getAccountSet(provider);
        if (!set?.accounts.some(account => account.id === body.accountId)) return jsonResponse({ error: "account not found" }, 404);
        return jsonResponse({ ok: true, provider, accountId: body.accountId, paused: false, unchanged: true,
          activeAccountId: set.activeAccountId, activeAccountChanged: false });
      }
      resumeGuard = { generation: verdict.generation, pauseRevision: verdict.pauseRevision };
    }
    const result = await setAccountPaused(provider, body.accountId, body.paused, undefined, resumeGuard);
    if (result.status === "not-found") return jsonResponse({ error: "account not found" }, 404);
    if (result.status === "changed") {
      return jsonResponse({ error: "account was not resumed: account_changed", code: "resume_refused", reason: "account_changed",
        provider, accountId: body.accountId }, 409);
    }

    const anthropicRouting = isAnthropicOAuthInstance(provider)
      ? (await import("../../oauth/anthropic-routing")).anthropicRoutingFor(provider) : undefined;
    let affinityReset: Promise<boolean> | undefined;
    // Explicit retries rebuild reset intent after a server restart lost the in-memory marker.
    if (anthropicRouting && result.activeAccountChanged) {
      anthropicRouting.resetAnthropicRoutingForManualSelection(result.activeAccountId);
      affinityReset = anthropicRouting.flushAnthropicManualSelectionReset();
    } else if (anthropicRouting && body.retryAffinityReset === true) {
      affinityReset = anthropicRouting.resetAnthropicSessionAffinityConfirmed();
    }
    if (result.activeAccountChanged) {
      if (!anthropicRouting) {
        const { seedGenericPoolSelection } = await import("../../oauth/generic-account-failover");
        seedGenericPoolSelection(provider, result.activeAccountId);
      }
      const { clearModelCache } = await import("../../codex/model-cache");
      const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
      clearModelCache(provider);
      for (const row of oauthCredentialSiblingsOf(provider)) clearModelCache(row);
      clearGatherRoutedModelsInflight();
      clearQuotaCachesAfterAccountMutation(provider, false);
    }

    // Inactive pauses also publish invalidation before success; an unchanged retry drains it.
    affinityReset ??= anthropicRouting?.flushAnthropicAccountPause();
    if (affinityReset && !await affinityReset) {
      return jsonResponse({ error: "Account pause was saved, but its session-affinity reset was not persisted. Retry with the same pause state and retryAffinityReset: true.",
        code: "affinity_reset_not_persisted", provider, accountId: body.accountId, paused: body.paused,
        activeAccountId: result.activeAccountId, activeAccountChanged: result.activeAccountChanged,
        pauseCommitted: true, retryable: true }, 503);
    }
    return jsonResponse({
      ok: true,
      provider,
      accountId: body.accountId,
      paused: body.paused,
      activeAccountId: result.activeAccountId,
      activeAccountChanged: result.activeAccountChanged,
    });
  }

  // The unified pool-settings contract (#695 wp5c). The three legacy paths keep working and
  // keep their own shapes -- goldens pin them -- but this is the one an operator or a dashboard
  // should read, because it answers with the same keys for every kind and DECLARES which of
  // them that kind honours.
  if (url.pathname === "/api/pool/settings" && (req.method === "GET" || req.method === "PUT" || req.method === "PATCH")) {
    const {
      poolSettingsCapability, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold, parseGenericStickyLimit, parseKiroAccountCap,
      unifiedPoolSettingsDto,
    } = await import("../../oauth/pool-settings-capability");
    const rawBody = req.method === "GET" ? {} : await readManagementJsonBodyOr(req, {});
    if (req.method !== "GET" && !isPlainRecord(rawBody)) {
      return jsonResponse({ error: "body must be an object" }, 400);
    }
    const fields = rawBody as { provider?: unknown; enabled?: unknown; strategy?: unknown; stickyLimit?: unknown; autoSwitchThreshold?: unknown; quotaWindow?: unknown; maxConcurrentPerAccount?: unknown; routes?: unknown; nativeMessages?: unknown };
    const provider = req.method === "GET"
      ? (url.searchParams.get("provider") ?? "").trim().toLowerCase()
      : (typeof fields.provider === "string" ? fields.provider.trim().toLowerCase() : "");
    const kind = provider ? poolSettingsCapability(provider, config.providers?.[provider]) : null;
    if (!provider || !kind) {
      return jsonResponse({ error: "pool settings are only available for the codex, anthropic and generic OAuth pools" }, 400);
    }
    if (Object.hasOwn(fields, "nativeMessages")) {
      if (kind !== "anthropic") return jsonResponse({ error: "nativeMessages is only part of the anthropic pool contract" }, 400);
      if (typeof fields.nativeMessages !== "boolean") return jsonResponse({ error: "nativeMessages must be a boolean" }, 400);
    }
    // Validate the strategy for this pool kind before any write.
    let strategy: string | undefined;
    if (fields.strategy !== undefined) {
      const parsed = kind === "codex" ? parseCodexAccountPoolStrategy(fields.strategy)
        : kind === "generic" ? parseGenericPoolStrategy(fields.strategy, provider)
        : parseAccountPoolStrategy(fields.strategy);
      if (parsed === null) {
        const extra = kind === "anthropic" ? "reset-near-weighted"
          : kind === "codex" ? "reset-first, reset-near-weighted"
          : provider === "kiro" ? "reset-first, least-loaded" : "reset-first";
        return jsonResponse({ error: `strategy must be one of: quota, round-robin, fill-first, ${extra}` }, 400);
      }
      strategy = parsed;
    }
    let stickyLimit: number | undefined;
    if (fields.stickyLimit !== undefined) {
      const parsed = parseGenericStickyLimit(fields.stickyLimit);
      if (parsed === null) return jsonResponse({ error: "stickyLimit must be an integer 1-100" }, 400);
      stickyLimit = parsed;
    }
    let autoSwitchThreshold: number | undefined;
    if (fields.autoSwitchThreshold !== undefined) {
      const parsed = parseGenericAutoSwitchThreshold(fields.autoSwitchThreshold);
      if (parsed === null) return jsonResponse({ error: "autoSwitchThreshold must be an integer 0-100" }, 400);
      autoSwitchThreshold = parsed;
    }
    if (Object.hasOwn(fields, "routes") && kind !== "anthropic") return jsonResponse({ error: "routes are only part of the anthropic pool contract" }, 400);
    const parsedRoutes = Object.hasOwn(fields, "routes") && fields.routes !== null
      ? parseAnthropicModelRoutes(fields.routes) : null;
    if (parsedRoutes && !parsedRoutes.ok) return jsonResponse({ error: parsedRoutes.error }, 400);
    if (fields.quotaWindow !== undefined && kind !== "anthropic") {
      return jsonResponse({ error: "quotaWindow is only part of the anthropic pool contract" }, 400);
    }
    let quotaWindow: string | undefined;
    if (fields.quotaWindow !== undefined) {
      const parsed = parseAccountPoolQuotaWindow(fields.quotaWindow);
      if (parsed === null) return jsonResponse({ error: "quotaWindow must be one of: five-hour, weekly, max-utilization" }, 400);
      quotaWindow = parsed;
    }
    if (fields.enabled !== undefined) {
      if (kind === "codex") return jsonResponse({ error: "enabled is not part of the codex pool contract" }, 400);
      if (typeof fields.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
    }
    let accountCap: number | null | undefined;
    if (fields.maxConcurrentPerAccount !== undefined) {
      if (provider !== "kiro" || kind !== "generic") return jsonResponse({ error: "maxConcurrentPerAccount is only supported for Kiro OAuth" }, 400);
      accountCap = fields.maxConcurrentPerAccount === null ? null : parseKiroAccountCap(fields.maxConcurrentPerAccount);
      if (accountCap === null && fields.maxConcurrentPerAccount !== null) return jsonResponse({ error: "maxConcurrentPerAccount must be an integer 1-100 or null" }, 400);
    }

    if (req.method !== "GET") {
      if (kind === "codex") {
        if (strategy !== undefined) config.accountPoolStrategy = strategy as never;
        if (stickyLimit !== undefined) config.accountPoolStickyLimit = stickyLimit;
        if (autoSwitchThreshold !== undefined) config.autoSwitchThreshold = autoSwitchThreshold;
      } else if (kind === "anthropic") {
        const patchPool = (target: OcxConfig) => {
          const pool = { ...resolveAnthropicAccountPoolConfig(target, provider as AnthropicInstanceId) };
          if (fields.nativeMessages !== undefined) pool.nativeMessages = fields.nativeMessages as boolean;
          if (fields.enabled !== undefined) pool.enabled = fields.enabled as boolean;
          if (strategy !== undefined) pool.strategy = strategy as never;
          if (stickyLimit !== undefined) pool.stickyLimit = stickyLimit;
          if (autoSwitchThreshold !== undefined) pool.autoSwitchThreshold = autoSwitchThreshold;
          if (quotaWindow !== undefined) pool.quotaWindow = quotaWindow as never;
          if (Object.hasOwn(fields, "routes")) {
            if (fields.routes === null) delete pool.routes;
            else if (parsedRoutes?.ok) pool.routes = parsedRoutes.routes;
          }
          writeAnthropicPoolSettings(target, provider as AnthropicInstanceId, pool);
          return { changed: true, value: pool };
        };
        const saved = persistAnthropicPoolPatch(config, provider as AnthropicInstanceId, patchPool);
        if (saved.status === "failed") return saved.response;
        return jsonResponse({ ...unifiedPoolSettingsDto(config, provider, kind), ...(saved.warning ? { warning: saved.warning } : {}) });
      } else {
        const prov = config.providers[provider]!;
        const next = { ...(prov.oauthAccountFailover ?? {}) };
        if (fields.enabled !== undefined) next.enabled = fields.enabled as boolean;
        if (strategy !== undefined) next.strategy = strategy as never;
        if (accountCap === null) delete next.maxConcurrentPerAccount;
        else if (accountCap !== undefined) next.maxConcurrentPerAccount = accountCap;
        if (stickyLimit !== undefined) next.stickyLimit = stickyLimit;
        if (autoSwitchThreshold !== undefined) next.autoSwitchThreshold = autoSwitchThreshold;
        if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
        else delete prov.oauthAccountFailover;
      }
      saveConfigPreservingClaudeCode(config);
      reconcileLiveStateStores();
    }
    return jsonResponse(unifiedPoolSettingsDto(config, provider, kind));
  }


  // Opt-in Anthropic OAuth account pool (#294): enable/threshold/strategy + clear cooldown.
  if (url.pathname === "/api/oauth/accounts/pool" && req.method === "GET") {
    const provider = (url.searchParams.get("provider") ?? "").trim().toLowerCase();
    if (!isAnthropicOAuthInstance(provider)) {
      // Generic OAuth pool-settings contract (#695 slice 1): persisted per provider. `strategy`
      // and `autoSwitchThreshold` stay inert until the selector consumes them; `enabled` already
      // governs the pre-dispatch account preference. Codex keeps /api/codex-auth; api-key
      // providers have no pool.
      const { poolSettingsCapability, genericPoolSettingsDto } = await import("../../oauth/pool-settings-capability");
      const prov = config.providers[provider];
      if (!provider || !prov || poolSettingsCapability(provider, prov) !== "generic") {
        return jsonResponse({ error: "pool config is only supported for anthropic and generic OAuth providers" }, 400);
      }
      return jsonResponse(genericPoolSettingsDto(provider, prov, config.pool?.kernel === true));
    }
    if (provider === "anthropic2" && !configuredAnthropicInstance(config, provider)) return jsonResponse({ error: "Anthropic pool instance is not configured" }, 409);
    const pool = resolveAnthropicAccountPoolConfig(config, provider);
    return jsonResponse({
      provider,
      enabled: pool.enabled === true,
      autoSwitchThreshold: typeof pool.autoSwitchThreshold === "number" ? pool.autoSwitchThreshold : 80,
      strategy: normalizeAccountPoolStrategy(pool.strategy),
      stickyLimit: normalizeAccountPoolStickyLimit(pool.stickyLimit),
      quotaWindow: normalizeAccountPoolQuotaWindow(pool.quotaWindow),
      ...readAnthropicModelRoutes(pool.routes),
      nativeMessages: !Object.hasOwn(pool, "nativeMessages") || pool.nativeMessages === true,
      experimental: true,
    });
  }
  if (url.pathname === "/api/oauth/accounts/pool" && (req.method === "PUT" || req.method === "PATCH")) {
    const parsedBody = await readManagementJsonBodyOr(req, {});
    if (!isPlainRecord(parsedBody)) {
      return jsonResponse({ error: "body must be an object" }, 400);
    }
    const body = parsedBody as {
      provider?: unknown;
      enabled?: unknown;
      autoSwitchThreshold?: unknown;
      strategy?: unknown;
      stickyLimit?: unknown;
      quotaWindow?: unknown;
      maxConcurrentPerAccount?: unknown;
      routes?: unknown;
      nativeMessages?: unknown;
    };
    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
    if (Object.hasOwn(body, "nativeMessages")) {
      if (!isAnthropicOAuthInstance(provider)) return jsonResponse({ error: "nativeMessages is only part of the anthropic pool contract" }, 400);
      if (typeof body.nativeMessages !== "boolean") return jsonResponse({ error: "nativeMessages must be a boolean" }, 400);
    }
    if (!isAnthropicOAuthInstance(provider)) {
      const {
        poolSettingsCapability, genericPoolSettingsDto, parseGenericPoolStrategy, parseGenericAutoSwitchThreshold,
        parseGenericStickyLimit, parseKiroAccountCap,
      } = await import("../../oauth/pool-settings-capability");
      const prov = config.providers[provider];
      if (!provider || !prov || poolSettingsCapability(provider, prov) !== "generic") {
        return jsonResponse({ error: "pool config is only supported for anthropic and generic OAuth providers" }, 400);
      }
      if (Object.hasOwn(body, "routes")) return jsonResponse({ error: "routes are only part of the anthropic pool contract" }, 400);
      if (body.quotaWindow !== undefined) {
        return jsonResponse({ error: "quotaWindow is not part of the generic pool contract yet" }, 400);
      }
      const next = { ...(prov.oauthAccountFailover ?? {}) };
      if (body.enabled !== undefined) {
        if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
        next.enabled = body.enabled;
      }
      if (body.strategy !== undefined) {
        if (body.strategy === null) delete next.strategy;
        else {
          const parsed = parseGenericPoolStrategy(body.strategy, provider);
          if (parsed === null) return jsonResponse({ error: `strategy must be one of: quota, round-robin, fill-first, reset-first${provider === "kiro" ? ", least-loaded" : ""}` }, 400);
          next.strategy = parsed;
        }
      }
      if (body.autoSwitchThreshold !== undefined) {
        if (body.autoSwitchThreshold === null) delete next.autoSwitchThreshold;
        else {
          const parsed = parseGenericAutoSwitchThreshold(body.autoSwitchThreshold);
          if (parsed === null) return jsonResponse({ error: "autoSwitchThreshold must be an integer 0-100" }, 400);
          next.autoSwitchThreshold = parsed;
        }
      }
      if (body.stickyLimit !== undefined) {
        if (body.stickyLimit === null) delete next.stickyLimit;
        else {
          const parsed = parseGenericStickyLimit(body.stickyLimit);
          if (parsed === null) return jsonResponse({ error: "stickyLimit must be an integer 1-100" }, 400);
          next.stickyLimit = parsed;
        }
      }
      if (body.maxConcurrentPerAccount !== undefined) {
        if (provider !== "kiro") return jsonResponse({ error: "maxConcurrentPerAccount is only supported for Kiro OAuth" }, 400);
        const cap = body.maxConcurrentPerAccount === null ? null : parseKiroAccountCap(body.maxConcurrentPerAccount);
        if (cap === null && body.maxConcurrentPerAccount !== null) return jsonResponse({ error: "maxConcurrentPerAccount must be an integer 1-100 or null" }, 400);
        if (cap === null) delete next.maxConcurrentPerAccount;
        else next.maxConcurrentPerAccount = cap;
      }
      if (Object.keys(next).length > 0) prov.oauthAccountFailover = next;
      else delete prov.oauthAccountFailover;
      saveConfigPreservingClaudeCode(config);
      return jsonResponse({ ok: true, ...genericPoolSettingsDto(provider, prov, config.pool?.kernel === true) });
    }
    if (provider === "anthropic2" && !configuredAnthropicInstance(config, provider)) return jsonResponse({ error: "Anthropic pool instance is not configured" }, 409);
    let enabled = resolveAnthropicAccountPoolConfig(config, provider)?.enabled === true;
    if (body.enabled !== undefined) {
      if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
      enabled = body.enabled;
    }
    let threshold = resolveAnthropicAccountPoolConfig(config, provider)?.autoSwitchThreshold ?? 80;
    if (body.autoSwitchThreshold !== undefined) {
      if (
        typeof body.autoSwitchThreshold !== "number"
        || !Number.isInteger(body.autoSwitchThreshold)
        || body.autoSwitchThreshold < 0
        || body.autoSwitchThreshold > 100
      ) {
        return jsonResponse({ error: "autoSwitchThreshold must be an integer 0-100" }, 400);
      }
      threshold = body.autoSwitchThreshold;
    }
    let strategy = resolveAnthropicAccountPoolConfig(config, provider)?.strategy;
    if (body.strategy !== undefined) {
      const parsed = parseAccountPoolStrategy(body.strategy);
      if (parsed === null) {
        return jsonResponse({ error: "strategy must be one of: quota, round-robin, fill-first, reset-near-weighted" }, 400);
      }
      strategy = parsed;
    }
    let stickyLimit = resolveAnthropicAccountPoolConfig(config, provider)?.stickyLimit;
    if (body.stickyLimit !== undefined) {
      const parsed = parseAccountPoolStickyLimit(body.stickyLimit);
      if (parsed === null) {
        return jsonResponse({ error: "stickyLimit must be an integer 1-100" }, 400);
      }
      stickyLimit = parsed;
    }
    let quotaWindow = resolveAnthropicAccountPoolConfig(config, provider)?.quotaWindow;
    if (body.quotaWindow !== undefined) {
      const parsed = parseAccountPoolQuotaWindow(body.quotaWindow);
      if (parsed === null) {
        return jsonResponse({ error: "quotaWindow must be one of: five-hour, weekly, max-utilization" }, 400);
      }
      quotaWindow = parsed;
    }
    const parsedLegacyRoutes = Object.hasOwn(body, "routes") && body.routes !== null
      ? parseAnthropicModelRoutes(body.routes) : null;
    if (parsedLegacyRoutes && !parsedLegacyRoutes.ok) return jsonResponse({ error: parsedLegacyRoutes.error }, 400);
    const legacyPatch = (target: OcxConfig) => {
      const pool = { ...resolveAnthropicAccountPoolConfig(target, provider as AnthropicInstanceId) };
      if (body.enabled !== undefined) pool.enabled = enabled;
      else if (pool.enabled === undefined) pool.enabled = false;
      if (body.nativeMessages !== undefined) pool.nativeMessages = body.nativeMessages as boolean;
      if (body.autoSwitchThreshold !== undefined) pool.autoSwitchThreshold = threshold;
      else if (pool.autoSwitchThreshold === undefined) pool.autoSwitchThreshold = 80;
      if (body.strategy !== undefined) pool.strategy = strategy;
      if (body.stickyLimit !== undefined) pool.stickyLimit = stickyLimit;
      if (body.quotaWindow !== undefined) pool.quotaWindow = quotaWindow;
      if (Object.hasOwn(body, "routes")) {
        if (body.routes === null) delete pool.routes;
        else if (parsedLegacyRoutes?.ok) pool.routes = parsedLegacyRoutes.routes;
      }
      writeAnthropicPoolSettings(target, provider as AnthropicInstanceId, pool);
      return { changed: true, value: pool };
    };
    const saved = persistAnthropicPoolPatch(config, provider as AnthropicInstanceId, legacyPatch);
    if (saved.status === "failed") return saved.response;
    return jsonResponse({
      ok: true,
      provider,
      enabled: resolveAnthropicAccountPoolConfig(config, provider)?.enabled === true,
      autoSwitchThreshold: resolveAnthropicAccountPoolConfig(config, provider)?.autoSwitchThreshold ?? 80,
      strategy: normalizeAccountPoolStrategy(resolveAnthropicAccountPoolConfig(config, provider)?.strategy),
      stickyLimit: normalizeAccountPoolStickyLimit(resolveAnthropicAccountPoolConfig(config, provider)?.stickyLimit),
      quotaWindow: normalizeAccountPoolQuotaWindow(resolveAnthropicAccountPoolConfig(config, provider)?.quotaWindow),
      routes: resolveAnthropicAccountPoolConfig(config, provider)?.routes ?? null,
      nativeMessages: !Object.hasOwn(resolveAnthropicAccountPoolConfig(config, provider), "nativeMessages") || resolveAnthropicAccountPoolConfig(config, provider)?.nativeMessages === true,
      ...(saved.warning ? { warning: saved.warning } : {}),
      experimental: true,
    });
  }
  if (url.pathname === "/api/oauth/accounts/clear-cooldown" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: unknown; accountId?: unknown };
    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
    const accountId = typeof body.accountId === "string" ? body.accountId.trim() : "";
    if (!isAnthropicOAuthInstance(provider)) return jsonResponse({ error: "clear-cooldown is only supported for anthropic" }, 400);
    if (provider === "anthropic2" && !configuredAnthropicInstance(config, provider)) return jsonResponse({ error: "Anthropic pool instance is not configured" }, 409);
    if (!accountId) return jsonResponse({ error: "missing accountId" }, 400);
    const { anthropicRoutingFor } = await import("../../oauth/anthropic-routing");
    const cleared = anthropicRoutingFor(provider).clearAnthropicAccountCooldown(accountId);
    return jsonResponse({ ok: true, cleared });
  }

  // Read-only per-account probe: each stored account's own access token, one upstream request,
  // no refresh and no store write. Omitting accountId probes the whole roster.
  if (url.pathname === "/api/oauth/accounts/probe" && req.method === "POST") {
    if (principal !== "admin-token" && principal !== "gui-session") {
      return jsonResponse({ error: "account probe requires management authorization" }, 403);
    }
    const body = await readManagementJsonBodyOr(req, {});
    if (!isPlainRecord(body)) return jsonResponse({ error: "body must be an object" }, 400);
    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
    if (provider !== "google-antigravity") return jsonResponse({ error: "account probe is not supported for this provider" }, 400);
    if (body.accountId !== undefined && (typeof body.accountId !== "string" || !body.accountId.trim())) {
      return jsonResponse({ error: "accountId must be a non-empty string" }, 400);
    }
    const accountId = typeof body.accountId === "string" ? body.accountId.trim() : undefined;
    if (accountProbeRunning) return jsonResponse({ error: "an account probe is already running" }, 409);
    accountProbeRunning = true;
    try {
      const { probeAntigravityAccounts } = await import("../../providers/quota/antigravity-account-probe");
      const results = await probeAntigravityAccounts({ accountId, signal: req.signal });
      if (!results) return jsonResponse({ error: "account not found" }, 404);
      return jsonResponse({ provider, probedAt: new Date().toISOString(), results });
    } finally {
      accountProbeRunning = false;
    }
  }

  if (url.pathname === "/api/oauth/accounts/import" && req.method === "POST") {
    const controller = new AbortController();
    const abortRequest = () => controller.abort();
    if (req.signal.aborted) abortRequest();
    else req.signal.addEventListener("abort", abortRequest, { once: true });
    const deadline = setTimeout(abortRequest, ACCOUNT_IMPORT_DEADLINE_MS);
    try {
      let rawBody: unknown;
      try {
        rawBody = await readBoundedJsonRequestBody(
          req,
          ACCOUNT_IMPORT_MAX_REQUEST_BYTES,
          undefined,
          { signal: controller.signal },
        );
      } catch {
        if (controller.signal.aborted) return jsonResponse({ code: "import_cancelled" }, 408);
        return jsonResponse({ code: "invalid_document" }, 400);
      }
      if (!isPlainRecord(rawBody)) return jsonResponse({ code: "invalid_document" }, 400);
      const provider = typeof rawBody.provider === "string" ? rawBody.provider : "";
      const format = typeof rawBody.format === "string" ? rawBody.format : "";
      // An imported Antigravity credential carries the same account risk as a fresh login. Import
      // admits only the exact provider id, so the gate matches it exactly too; other spellings
      // keep their unsupported_provider answer.
      if (provider === ANTIGRAVITY_RISK_PROVIDER && !hasAntigravityRiskAcknowledgement(rawBody)) {
        return jsonResponse({ code: ANTIGRAVITY_RISK_REFUSAL_CODE }, 403);
      }
      const { importAccounts } = await import("../../oauth/account-import");
      const imported = await importAccounts({
        provider,
        format,
        document: rawBody.document,
        signal: controller.signal,
      });
      const changed = imported.ok
        ? imported.result.importedCount > 0 || imported.result.updatedCount > 0
        : imported.changed === true;
      if (changed) {
        reconcileLiveStateStores();
        const { clearModelCache } = await import("../../codex/model-cache");
        const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
        clearModelCache(provider);
        clearGatherRoutedModelsInflight();
        clearQuotaCachesAfterAccountMutation(provider, true);
      }
      if (!imported.ok) return jsonResponse({ code: imported.code }, imported.status);
      return jsonResponse(imported.result);
    } finally {
      clearTimeout(deadline);
      req.signal.removeEventListener("abort", abortRequest);
    }
  }

  if (url.pathname === "/api/oauth/accounts/alias" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {}) as { provider?: unknown; accountId?: unknown; alias?: unknown };
    const provider = oauthCredentialSlot(typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "");
    const accountId = typeof body.accountId === "string" ? body.accountId.trim() : "";
    const alias = typeof body.alias === "string" ? body.alias.trim() : "";
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (!accountId) return jsonResponse({ error: "missing accountId" }, 400);
    if (typeof body.alias !== "string" || alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) {
      return jsonResponse({ error: "alias must be at most 80 printable characters" }, 400);
    }
    const { setAccountAlias } = await import("../../oauth/store");
    if (!(await setAccountAlias(provider, accountId, alias || undefined))) return jsonResponse({ error: "account not found" }, 404);
    return jsonResponse({ ok: true, provider, accountId, alias: alias || null });
  }
  if (url.pathname === "/api/oauth/accounts" && req.method === "DELETE") {
    const provider = oauthCredentialSlot((url.searchParams.get("provider") ?? "").trim().toLowerCase());
    const id = url.searchParams.get("id") ?? "";
    if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
    if (!id) return jsonResponse({ error: "missing id" }, 400);
    const retryReset = url.searchParams.get("retryAffinityReset");
    if (retryReset !== null && retryReset !== "true" && retryReset !== "false") {
      return jsonResponse({ error: "retryAffinityReset must be true or false" }, 400);
    }
    if (retryReset === "true" && !isAnthropicOAuthInstance(provider)) {
      return jsonResponse({ error: "session-affinity reset is only supported for Anthropic OAuth instances" }, 400);
    }
    const { removeAccount, getAccountSet } = await import("../../oauth/store");
    if (!(await removeAccount(provider, id))) return jsonResponse({ error: "account not found" }, 404);
    reconcileLiveStateStores();
    let affinityReset: Promise<boolean> | undefined;
    if (isAnthropicOAuthInstance(provider)) {
      const { anthropicRoutingFor } = await import("../../oauth/anthropic-routing");
      const routing = anthropicRoutingFor(provider);
      routing.clearAnthropicAccountCooldown(id);
      routing.clearAnthropicSessionAffinityForAccount(id);
      affinityReset = retryReset === "true" ? routing.resetAnthropicSessionAffinityConfirmed()
        : routing.flushAnthropicManualSelectionReset();
    }
    if (!getAccountSet(provider)) clearLoginState(provider);
    const { clearModelCache } = await import("../../codex/model-cache");
    const { clearGatherRoutedModelsInflight } = await import("../../codex/catalog");
    clearModelCache(provider);
    for (const row of oauthCredentialSiblingsOf(provider)) clearModelCache(row);
    clearGatherRoutedModelsInflight();
    clearQuotaCachesAfterAccountMutation(provider, true);
    // Same reasoning as logout. Removing the last account for a provider used to
    // leave the JWT and catalog in memory, because only the logout route cleared
    // them.
    if (isDevinCloudDirectProvider(provider)) await clearDevinCloudDirectCaches();
    if (affinityReset && !await affinityReset) {
      return jsonResponse({ code: "affinity_reset_not_persisted", provider, accountId: id,
        deletionCommitted: true, retryable: true }, 503);
    }
    return jsonResponse({ ok: true, ...(retryReset === "true" ? { affinityResetConfirmed: true } : {}) });
  }

  // Multi-key pool for API-key providers (same GUI dropdown as OAuth multiauth): list masked
  // keys, add one (upserts + activates), switch the active key, or remove one. `apiKey` always
  // mirrors the active entry so routing is untouched.
  if (url.pathname === "/api/providers/keys" && req.method === "GET") {
    const name = (url.searchParams.get("name") ?? "").trim();
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    const { listProviderApiKeys } = await import("../../providers/api-keys");
    const projectKeys = () => {
      const listed = listProviderApiKeys(config, name);
      const provider = config.providers[name];
      const quotaMode = provider ? providerApiKeyQuotaMode(name, provider) : "unsupported";
      // #8397: say why a balance is unknown; a destination without a reader has no balance source.
      return { ...listed, keys: listed.keys.map(key => ({ ...key, quotaMode,
        ...(quotaMode === "unsupported" ? { quotaUnknownReason: "no_balance_source" as const } : {}) })) };
    };
    const initial = projectKeys();
    if (url.searchParams.get("quota") !== "1" || !initial.keys.some(key => key.quotaMode === "probe")) {
      return jsonResponse(initial);
    }
    const rows = await fetchProviderApiKeyQuotas(config, name, url.searchParams.get("refresh") === "1");
    const byId = new Map(rows.map(row => [row.keyId, row]));
    const current = projectKeys();
    return jsonResponse({
      activeId: current.activeId,
      keys: current.keys.map(key => {
        const row = byId.get(key.id);
        if (key.quotaMode !== "probe") return key;
        // A key added while the read was in flight was never read.
        if (!row) return { ...key, quotaUnknownReason: "not_read" };
        if (!row.isCurrent()) return { ...key, quota: null, quotaUnavailable: true, quotaUnknownReason: "not_read" };
        const readAt = row.readAt === undefined ? {} : { quotaReadAt: row.readAt };
        // A successful read with no meterable balance (authoritative empty) still names why it is unknown.
        const reason = row.unavailable ? (row.readAt === undefined ? "not_read" : "read_failed")
          : row.quota === null && row.readAt !== undefined ? "not_reported" : undefined;
        // Internal identity/epoch checks never enter the JSON DTO.
        return { ...key, quota: row.quota, quotaUnavailable: row.unavailable === true, ...readAt,
          ...(reason ? { quotaUnknownReason: reason } : {}) };
      }),
    });
  }
  if (url.pathname === "/api/providers/keys" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { name?: string; key?: string; label?: string };
    const name = (body.name ?? "").trim();
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    if (typeof body.key !== "string" || !body.key.trim()) return jsonResponse({ error: "key is required" }, 400);
    const { addProviderApiKey } = await import("../../providers/api-keys");
    const result = addProviderApiKey(config, name, body.key, body.label);
    if ("error" in result) return jsonResponse({ error: result.error }, 400);
    const { clearModelCache } = await import("../../codex/model-cache");
    clearModelCache(name);
    const { clearProviderQuotaCache } = await import("../../providers/quota");
    clearProviderQuotaCache();
    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
    clearKeyCooldowns(name); // manual key management resets 429 cooldown state
    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
    // hand the next proactive pick straight back to whichever key the pool had reached.
    forgetApiKeyRotationCursor(name);
    return jsonResponse({ ok: true, id: result.id }, 201);
  }
  // Opt-in OS keychain storage (#1221): move the active key and pool into the OS credential
  // store (config keeps references), or restore plaintext. Store verifies the keychain before
  // touching config so an unavailable store refuses instead of half-migrating.
  if (url.pathname === "/api/providers/keychain" && req.method === "GET") {
    const name = (url.searchParams.get("name") ?? "").trim();
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    const { probeProviderKeychain, providerKeyStoreKind } = await import("../../providers/key-store");
    const probe = probeProviderKeychain();
    return jsonResponse({
      name,
      store: providerKeyStoreKind(config.providers[name]),
      keychainAvailable: probe.available,
      ...(probe.available ? {} : { keychainUnavailableReason: probe.reason }),
    });
  }
  if (url.pathname === "/api/providers/keychain" && req.method === "POST") {
    const body = await readManagementJsonBodyOr(req, {}) as { name?: unknown; action?: unknown };
    const name = typeof body.name === "string" ? body.name.trim() : "";
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    if (body.action !== "store" && body.action !== "restore") return jsonResponse({ error: "action must be store or restore" }, 400);
    const { storeProviderKeyInKeychain, restoreProviderKeyFromKeychain, providerKeyStoreKind } = await import("../../providers/key-store");
    const result = body.action === "store"
      ? storeProviderKeyInKeychain(config, name)
      : restoreProviderKeyFromKeychain(config, name);
    if (!result.ok) return jsonResponse({ error: result.error }, result.status);
    (await import("../../providers/passive-key-observation")).clearPassiveKeyLimits(name);
    const { clearProviderQuotaCache } = await import("../../providers/quota");
    clearProviderQuotaCache();
    return jsonResponse({ ...result, name, store: providerKeyStoreKind(config.providers[name]) });
  }
  if (url.pathname === "/api/providers/keys/pause" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {});
    if (!isPlainRecord(body)) return jsonResponse({ error: "body must be an object" }, 400);
    if (typeof body.name !== "string" || typeof body.id !== "string" || typeof body.paused !== "boolean") return jsonResponse({ error: "name, id and paused required" }, 400);
    if (!isValidProviderName(body.name) || !hasOwnProvider(config.providers, body.name)) return jsonResponse({ error: "unknown provider" }, 404);
    const { setProviderApiKeyPausedWithResult } = await import("../../providers/api-key-pause");
    const result = setProviderApiKeyPausedWithResult(config, body.name, body.id, body.paused);
    return result.ok ? jsonResponse(result) : jsonResponse({ error: "key not found" }, 404);
  }
  if (url.pathname === "/api/providers/keys/active" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {}) as { name?: string; id?: string };
    const name = (body.name ?? "").trim();
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    if (!body.id) return jsonResponse({ error: "missing id" }, 400);
    const { setActiveProviderApiKey } = await import("../../providers/api-keys");
    if (!setActiveProviderApiKey(config, name, body.id)) return jsonResponse({ error: "key not found" }, 404);
    const { clearModelCache } = await import("../../codex/model-cache");
    clearModelCache(name);
    const { clearProviderQuotaCache } = await import("../../providers/quota");
    clearProviderQuotaCache();
    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
    clearKeyCooldowns(name); // manual key management resets 429 cooldown state
    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
    // hand the next proactive pick straight back to whichever key the pool had reached.
    forgetApiKeyRotationCursor(name);
    return jsonResponse({ ok: true, name, activeId: body.id });
  }
  if (url.pathname === "/api/providers/keys/alias" && req.method === "PUT") {
    const body = await readManagementJsonBodyOr(req, {}) as { name?: unknown; id?: unknown; alias?: unknown };
    const name = typeof body.name === "string" ? body.name.trim() : "";
    const id = typeof body.id === "string" ? body.id.trim() : "";
    const alias = typeof body.alias === "string" ? body.alias.trim() : "";
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    if (!id) return jsonResponse({ error: "missing id" }, 400);
    if (typeof body.alias !== "string" || alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) {
      return jsonResponse({ error: "alias must be at most 80 printable characters" }, 400);
    }
    const { setProviderApiKeyLabel } = await import("../../providers/api-keys");
    if (!setProviderApiKeyLabel(config, name, id, alias || undefined)) return jsonResponse({ error: "key not found" }, 404);
    return jsonResponse({ ok: true, name, id, alias: alias || null });
  }
  if (url.pathname === "/api/providers/keys" && req.method === "DELETE") {
    const name = (url.searchParams.get("name") ?? "").trim();
    const id = url.searchParams.get("id") ?? "";
    if (!name || !isValidProviderName(name) || !hasOwnProvider(config.providers, name)) return jsonResponse({ error: "unknown provider" }, 404);
    if (!id) return jsonResponse({ error: "missing id" }, 400);
    const { removeProviderApiKey } = await import("../../providers/api-keys");
    if (!removeProviderApiKey(config, name, id)) return jsonResponse({ error: "key not found" }, 404);
    const { clearModelCache } = await import("../../codex/model-cache");
    clearModelCache(name);
    const { clearProviderQuotaCache } = await import("../../providers/quota");
    clearProviderQuotaCache();
    const { clearKeyCooldowns, forgetApiKeyRotationCursor } = await import("../../providers/key-failover");
    clearKeyCooldowns(name); // manual key management resets 429 cooldown state
    // ...and the rotation cursor with it. A cursor that predates the operator's choice would
    // hand the next proactive pick straight back to whichever key the pool had reached.
    forgetApiKeyRotationCursor(name);
    return jsonResponse({ ok: true });
  }

  // ---------------------------------------------------------------------------
  // API Keys management
  // ---------------------------------------------------------------------------
  if (url.pathname === "/api/keys" && req.method === "GET") {
    if (removeExpiredApiKeyRotations(config)) {
      saveConfigPreservingClaudeCode(config);
      reconcileLiveStateStores();
    }
    const keys = config.apiKeys ?? [];
    const endpoints = buildApiAccessEndpoints(config, {
      requestUrl: req.url,
      requestHost: req.headers.get("host"),
      requestOrigin: req.headers.get("origin"),
    });
    const { readApiKeyUsageRollup } = await import("./api-key-usage");
    const { rollup, attributionSince, historyTruncated, usageIncomplete, usageIncompleteReason } = await readApiKeyUsageRollup(keys.map(k => k.id), config.managementUsageMaxReadBytes);
    return jsonResponse({
      // 8 random hex past the fixed `ocx_data_` literal: enough to tell two keys
      // apart in a list, with 128 bits of the tail still unrevealed. Masking only
      // 8 characters showed `ocx_data...` for every key ever generated.
      keys: keys.map(k => ({
        id: k.id,
        name: k.name,
        prefix: k.key.slice(0, 17) + "...",
        createdAt: k.createdAt,
        // Scope is metadata, not secret: an operator has to be able to read
        // what a key may reach without minting a replacement to find out.
        ...(k.allowedProviders ? { allowedProviders: [...k.allowedProviders] } : {}),
        ...(k.allowedModels ? { allowedModels: [...k.allowedModels] } : {}),
        ...(k.pendingRotation ? { pendingRotation: {
          id: k.pendingRotation.id,
          createdAt: k.pendingRotation.createdAt,
          expiresAt: k.pendingRotation.expiresAt,
        } } : {}),
        usage: rollup.get(k.id) ?? { requests7d: 0, totalRequests: 0 },
      })),
      // Dataset-level and singular: it describes the usage log, not any one key.
      ...(attributionSince ? { attributionSince } : {}),
      ...(historyTruncated ? { historyTruncated: true } : {}),
      ...(usageIncomplete ? { usageIncomplete: true, usageIncompleteReason } : {}),
      authMatrix: AUTH_MATRIX,
      ...endpoints,
    }, 200, req, config);
  }

  if (url.pathname === "/api/keys/reveal" && req.method === "POST") {
    if (principal !== "gui-session") {
      return jsonResponse({ error: "dashboard session required" }, 403, req, config);
    }
    // Local page bootstrap is sufficient for the dashboard, not stored-secret disclosure.
    const authorized = () => ctx.sessionControl?.canRevealDataKeys?.(req, config) === true;
    const denied = () => jsonResponse({ error: "operator-authorized dashboard session required" }, 403, req, config);
    if (!authorized()) return denied();
    const body = await readJsonBody(req);
    // Body reception can outlive the session or its revocation; do not trust cached admission.
    if (!authorized()) return denied();
    if (!body || Object.keys(body).length !== 1 || typeof body.id !== "string" || !body.id) {
      return jsonResponse({ error: "invalid body" }, 400, req, config);
    }
    const entry = config.apiKeys?.find(key => key.id === body.id);
    if (!entry) return jsonResponse({ error: "key not found" }, 404, req, config);
    const response = jsonResponse({ key: entry.key }, 200, req, config);
    response.headers.set("Cache-Control", "no-store");
    return response;
  }

  if (url.pathname === "/api/keys/rotate" && req.method === "POST") {
    const body = await readJsonBody(req);
    if (!body || Object.keys(body).length !== 1 || typeof body.id !== "string" || !body.id) {
      return jsonResponse({ error: "invalid body" }, 400, req, config);
    }
    const result = startApiKeyRotation(config, body.id);
    if ("error" in result) {
      return jsonResponse({ error: result.error === "not-found" ? "key not found" : "rotation already pending" }, result.error === "not-found" ? 404 : 409, req, config);
    }
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
    return jsonResponse(result, 201, req, config);
  }

  if (url.pathname === "/api/keys/rotate/commit" && req.method === "POST") {
    const body = await readJsonBody(req);
    if (!body || Object.keys(body).length !== 2 || typeof body.id !== "string" || !body.id
      || typeof body.rotationId !== "string" || !body.rotationId) {
      return jsonResponse({ error: "invalid body" }, 400, req, config);
    }
    const result = commitApiKeyRotation(config, body.id, body.rotationId);
    if ("error" in result) {
      if (result.error === "expired") saveConfigPreservingClaudeCode(config);
      return jsonResponse({ error: result.error === "not-found" ? "key rotation not found" : `rotation ${result.error}` }, result.error === "not-found" ? 404 : 409, req, config);
    }
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
    return jsonResponse({ ok: true }, 200, req, config);
  }

  if (url.pathname === "/api/keys/rotate" && req.method === "DELETE") {
    const body = await readJsonBody(req);
    if (!body || Object.keys(body).length !== 2 || typeof body.id !== "string" || !body.id
      || typeof body.rotationId !== "string" || !body.rotationId) {
      return jsonResponse({ error: "invalid body" }, 400, req, config);
    }
    if (!abortApiKeyRotation(config, body.id, body.rotationId)) {
      return jsonResponse({ error: "key rotation not found or mismatched" }, 409, req, config);
    }
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
    return jsonResponse({ ok: true }, 200, req, config);
  }

  if (url.pathname === "/api/keys" && req.method === "POST") {
    const body = await readJsonBody(req);
    if (!body) return jsonResponse({ error: "invalid body" }, 400, req, config);
    const nameField = validateKeyName(body.name, { required: false });
    if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
    const name = nameField.value || "default";
    const entry = issueApiKeyInProcess(config, name); // shared helper uses randomBytes(20)
    return jsonResponse({ id: entry.id, name: entry.name, key: entry.key, createdAt: entry.createdAt }, 201, req, config);
  }

  if (url.pathname === "/api/keys" && req.method === "PATCH") {
    const body = await readJsonBody(req);
    if (!body) return jsonResponse({ error: "invalid body" }, 400, req, config);
    if (typeof body.id !== "string" || !body.id) return jsonResponse({ error: "id required" }, 400, req, config);
    const existing = (config.apiKeys ?? []).find(k => k.id === body.id);
    if (!existing) return jsonResponse({ error: "key not found" }, 404, req, config);
    const entry = { ...existing };
    // Rename and scope are independent edits. A scope-only PATCH must not have
    // to restate the name, and a rename must not silently widen a scope, so
    // each field is applied only when the caller actually sent it.
    const renaming = body.name !== undefined;
    const scopingProviders = body.allowedProviders !== undefined;
    const scopingModels = body.allowedModels !== undefined;
    if (!renaming && !scopingProviders && !scopingModels) {
      return jsonResponse({ error: "name, allowedProviders or allowedModels required" }, 400, req, config);
    }
    if (renaming) {
      const nameField = validateKeyName(body.name, { required: true });
      if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
      entry.name = nameField.value;
    }
    for (const [field, sent] of [["allowedProviders", scopingProviders], ["allowedModels", scopingModels]] as const) {
      if (!sent) continue;
      const value = body[field];
      // `null` and `[]` both clear the list back to unrestricted; anything else
      // must be a list of non-empty strings, because a silently ignored malformed
      // scope would read as "allowed everything" to whoever set it.
      if (value === null) { delete entry[field]; continue; }
      if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim() || item.length > 256)) {
        return jsonResponse({ error: `${field} must be a list of non-empty names` }, 400, req, config);
      }
      const normalized = [...new Set((value as string[]).map(item => item.trim()))];
      if (normalized.length === 0) delete entry[field];
      else entry[field] = normalized;
    }
    // Publish the validated replacement only after every field is accepted.
    config.apiKeys = config.apiKeys!.map(key => key === existing ? entry : key);
    saveConfigPreservingClaudeCode(config);
    reconcileLiveStateStores();
    // Never echo key material from a rename.
    return jsonResponse({
      id: entry.id,
      name: entry.name,
      createdAt: entry.createdAt,
      ...(entry.allowedProviders ? { allowedProviders: [...entry.allowedProviders] } : {}),
      ...(entry.allowedModels ? { allowedModels: [...entry.allowedModels] } : {}),
    }, 200, req, config);
  }

  if (url.pathname === "/api/keys" && req.method === "DELETE") {
    const body = await readJsonBody(req);
    if (!body) return jsonResponse({ error: "invalid body" }, 400, req, config);
    if (typeof body.id !== "string" || !body.id) return jsonResponse({ error: "id required" }, 400, req, config);
    // A stale id must not read as a successful revocation.
    if (!revokeApiKeyInProcess(config, body.id)) return jsonResponse({ error: "key not found" }, 404, req, config);
    return jsonResponse({ success: true }, 200, req, config);
  }
  return null;
}