@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/providers/registry.ts

@@ -17,11 +17,79 @@ import {
 export type ProviderAuthKind = "forward" | "oauth" | "key" | "local";
 export type MetadataModelIdNormalize = "case-insensitive";
 
+export type ProviderModelDiscoveryScalar = string | number | boolean;
+
+export type ProviderModelDiscoveryPredicate =
+  | {
+      path: readonly string[];
+      equalsAny: readonly ProviderModelDiscoveryScalar[];
+      caseInsensitive?: boolean;
+    }
+  | {
+      path: readonly string[];
+      /**
+       * A string-valued upstream target uses substring matching; an array-valued target uses
+       * exact element matching. Use `equalsAny` when the string must match in full.
+       */
+      containsAny: readonly ProviderModelDiscoveryScalar[];
+      caseInsensitive?: boolean;
+    }
+  | {
+      path: readonly string[];
+      /** Uses the same string-substring and array-element semantics as `containsAny`. */
+      containsAll: readonly ProviderModelDiscoveryScalar[];
+      caseInsensitive?: boolean;
+    };
+
+export interface ProviderModelDiscoveryFilter {
+  /** Every predicate must match. */
+  allOf?: readonly ProviderModelDiscoveryPredicate[];
+  /** At least one predicate must match. */
+  anyOf?: readonly ProviderModelDiscoveryPredicate[];
+  /** No predicate may match. */
+  noneOf?: readonly ProviderModelDiscoveryPredicate[];
+}
+
+interface ProviderModelDiscoverySharedSpec {
+  /** Query parameters applied to the resolved discovery URL. */
+  query?: Readonly<Record<string, string>>;
+  /** Declarative eligibility rules evaluated against each untrusted model row. */
+  filter?: ProviderModelDiscoveryFilter;
+  /** Optional lower byte ceiling; the process-wide hard ceiling still wins. */
+  maxResponseBytes?: number;
+  /** Optional lower raw-row ceiling; the process-wide hard ceiling still wins. */
+  maxModels?: number;
+}
+
+type ProviderModelDiscoveryLocation =
+  | {
+      /** Registry-owned absolute endpoint. Mutually exclusive with `path`. */
+      url: string;
+      path?: never;
+    }
+  | {
+      /** Resource path relative to baseUrl; query strings and fragments are disallowed. */
+      path: string;
+      url?: never;
+    }
+  | {
+      /** Keep the adapter-derived default discovery endpoint. */
+      url?: never;
+      path?: never;
+    };
+
+/**
+ * Trusted live-model discovery policy. This metadata is registry-only: it must never be copied
+ * into config.json, where a same-named custom provider could otherwise redirect a stored key.
+ */
+export type ProviderModelDiscoverySpec = ProviderModelDiscoverySharedSpec & ProviderModelDiscoveryLocation;
+
 export interface ProviderRegistryEntry {
   id: string;
   label: string;
   adapter: string;
   baseUrl: string;
+  apiKeyTransport?: OcxProviderConfig["apiKeyTransport"];
   authKind: ProviderAuthKind;
   codexAccountMode?: CodexAccountMode;
   /** OAuth preset may explicitly honor a persisted API-key billing mode. */
@@ -34,6 +102,11 @@ export interface ProviderRegistryEntry {
    */
   freeTier?: boolean;
   allowBaseUrlOverride?: boolean;
+  /**
+   * Do not claim an existing same-named key provider whose fixed destination differs from this
+   * preset. Enable for newly promoted ids so an older custom key cannot be silently retargeted.
+   */
+  preserveCustomDestination?: boolean;
   /**
    * Optional endpoint picker for providers with multiple official hosts
    * (e.g. Qwen Cloud token plan vs pay-as-you-go). Requires `allowBaseUrlOverride`
@@ -50,6 +123,7 @@ export interface ProviderRegistryEntry {
   defaultModel?: string;
   models?: string[];
   liveModels?: boolean;
+  modelDiscovery?: ProviderModelDiscoverySpec;
   contextWindow?: number;
   modelContextWindows?: Record<string, number>;
   modelInputModalities?: Record<string, string[]>;
@@ -88,7 +162,7 @@ export interface ProviderRegistryEntry {
 
 export type ProviderConfigSeed = Pick<
   OcxProviderConfig,
-  "adapter" | "baseUrl" | "authMode" | "keyOptional" | "freeTier" | "modelSuffixBracketStrip" | "defaultModel" | "models"
+  "adapter" | "baseUrl" | "apiKeyTransport" | "authMode" | "keyOptional" | "freeTier" | "modelSuffixBracketStrip" | "defaultModel" | "models"
   | "liveModels" | "contextWindow" | "modelContextWindows" | "modelInputModalities"
   | "modelMaxInputTokens" | "defaultMaxOutputTokens" | "modelMaxOutputTokens"
   | "reasoningEfforts" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts" | "reasoningEffortMap" | "modelReasoningEffortMap"
@@ -383,6 +457,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: cursorModelContextWindows(CURSOR_STATIC_MODELS),
     modelInputModalities: cursorModelInputModalities(CURSOR_STATIC_MODELS),
     modelReasoningEfforts: cursorModelReasoningEfforts(CURSOR_STATIC_MODELS),
+    // Kimi K3 documents `max` as its API default, and its Cursor ladder has no `medium`
+    // rung — so applyReasoningLevels' medium->high->first fallback would settle the catalog
+    // default on `high`, the picker would send `high` explicitly, and the request builder's
+    // no-effort fallback to `kimi-k3-max` would never be reached. Mirrors the other K3
+    // routes (kimi, kimi-code, opencode-go).
+    modelDefaultReasoningEfforts: { "kimi-k3": "max" },
     // Cursor's wire protocol never forwards image parts (request-builder emits an unsupported-
     // content marker), so the vision sidecar covers ALL cursor models regardless of what the
     // upstream model could natively do. Live-discovered models outside the static list fall back
@@ -480,6 +560,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     baseUrl: "https://api.kimi.com/coding/v1",
     authKind: "oauth",
     modelSuffixBracketStrip: true,
+    // Kimi Code Plan documents a stable session/task prompt_cache_key as required to improve
+    // cache hit rates.
+    // The chat adapter only forwards a key already on the internal request (Codex's session key,
+    // or the one the Claude /v1/messages inbound derives); the adapter itself never invents one.
+    // Evidence: https://platform.kimi.com/docs/api/chat
+    promptCacheKey: true,
     featured: true,
     oauthId: "kimi",
     jawcodeBundle: "moonshot",
@@ -506,7 +592,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     baseUrl: "https://runtime.us-east-1.kiro.dev",
     authKind: "oauth",
     oauthId: "kiro",
-    note: "Import-first: reuses your installed Kiro CLI login — requires kiro-cli installed and signed in (`kiro-cli login`). Experimental third-party harness — see Kiro ToS.",
+    note: "Import-first: reuses your installed and signed-in Kiro CLI session (requires `kiro-cli login`). Add account logs `kiro-cli` out, switches it through a fresh browser login, stores the account by profile ARN, and restores the previous CLI session on cancellation or failure. Experimental third-party harness — see Kiro ToS.",
     models: KIRO_MODELS,
     defaultModel: "kiro-auto",
     // Kiro speaks CodeWhisperer wire, not OpenAI-style GET /models. Keep the static
@@ -978,7 +1064,6 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     authKind: "key",
     dashboardUrl: "https://ollama.com/settings/keys",
     // Live IDs verified 2026-07-10; qwen3-coder:480b retires 2026-07-15.
-    // Evidence: .codexclaw/evidence/260710_wp9_ollama_cloud_model_ids.md.
     models: ["glm-5.2", "deepseek-v4-pro", "qwen3-coder:480b", "gpt-oss:120b", "kimi-k2.6", "minimax-m3", "qwen3.5:397b", "gemma4:31b"],
     defaultModel: "glm-5.2",
     noVisionModels: [
@@ -1019,6 +1104,8 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     id: "kimi-code", label: "Kimi (coding)", baseUrl: "https://api.kimi.com/coding/v1", adapter: "openai-chat", authKind: "key",
     dashboardUrl: "https://platform.moonshot.cn/console/api-keys", defaultModel: "kimi-k2.7-code",
     modelSuffixBracketStrip: true,
+    // API-key form of the same Kimi Code Plan transport; keep cache affinity identical to OAuth.
+    promptCacheKey: true,
     models: KIMI_CODING_MODELS,
     modelContextWindows: KIMI_CODING_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: KIMI_CODING_MODEL_INPUT_MODALITIES,
@@ -1113,6 +1200,41 @@ export function getProviderRegistryEntry(id: string): ProviderRegistryEntry | un
   return PROVIDER_REGISTRY.find(entry => entry.id === id);
 }
 
+function normalizedProviderEndpoint(value: string): string {
+  const trimmed = value.trim();
+  try {
+    const parsed = new URL(trimmed);
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+}
+
+/**
+ * Whether registry transport defaults own this configured row.
+ *
+ * OAuth/forward providers stay pinned because their credentials must never be sent to an
+ * arbitrary same-named host. Existing key presets keep their historical pinning behavior; a new
+ * preset can opt into collision preservation, in which case its fixed endpoint owns only rows
+ * that still match that destination.
+ */
+export function providerMatchesRegistryTransport(
+  id: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): boolean {
+  const entry = getProviderRegistryEntry(id);
+  if (!entry) return false;
+  if (entry.authKind !== "key" || entry.preserveCustomDestination !== true) return true;
+  // The opt-in is intentionally limited to fixed key destinations. Fail closed if a future
+  // registry edit combines it with an override/template despite the registry parity tests.
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (typeof provider.baseUrl !== "string") return false;
+  if (provider.adapter !== entry.adapter) return false;
+  if (provider.authMode !== undefined && provider.authMode !== "key") return false;
+  return normalizedProviderEndpoint(provider.baseUrl) === normalizedProviderEndpoint(entry.baseUrl);
+}
+
 /**
  * Effective Codex account mode for a provider. For canonical `openai`, a valid persisted
  * `codexAccountMode` on the provider config wins and a missing/invalid value defaults to

package/src/responses/parser.ts

@@ -16,6 +16,7 @@ import { compactionItemToText } from "./compaction";
 import { previousResponseReplayPrefixLength } from "./state";
 import { decodeReasoningEnvelope } from "./reasoning-envelope";
 import { extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
+import { extractHostedImageGeneration, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
 
 function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -107,6 +108,10 @@ function mapToolChoice(value: unknown): OcxRequestOptions["toolChoice"] {
     if ((t === "function" || t === "custom") && "name" in value) {
       return { name: (value as { name: string }).name };
     }
+    // Hosted image tool types (with or without a name) map to the synthetic image_gen wire name.
+    if (t === "image_generation" || t === "image_gen") {
+      return { name: IMAGE_GEN_TOOL_NAME };
+    }
     if (t === "allowed_tools" && Array.isArray(value.tools)) {
       const names = value.tools
         .map(allowedToolName)
@@ -124,6 +129,7 @@ function allowedToolName(tool: unknown): string | undefined {
   if (!isObj(tool)) return undefined;
   if (typeof tool.name === "string" && tool.name.length > 0) return tool.name;
   if (tool.type === "web_search" || tool.type === "web_search_preview") return WEB_SEARCH_TOOL_NAME;
+  if (tool.type === "image_generation" || tool.type === "image_gen") return IMAGE_GEN_TOOL_NAME;
   if (tool.type === "tool_search") return "tool_search";
   return undefined;
 }
@@ -612,6 +618,10 @@ export function parseRequest(body: unknown): OcxParsedRequest {
   // gpt-mini sidecar for routed providers. buildTools still drops the hosted tool; the sidecar path
   // re-injects a synthetic function tool only when it will actually handle the call.
   const webSearch = extractHostedWebSearch(data.tools as unknown[] | undefined);
+  const imageGen = extractHostedImageGeneration([
+    ...(data.tools as unknown[] ?? []),
+    ...loadedToolSpecs,
+  ]);
   // Detect structured-output mode (Responses `text.format`) so the web-search sidecar can render its
   // tool_result as JSON rather than prose that could corrupt the model's schema-constrained answer.
   const structuredOutput = detectStructuredOutput(data.text);
@@ -625,6 +635,7 @@ export function parseRequest(body: unknown): OcxParsedRequest {
     _rawBody: body,
     ...(replayedInputPrefixLength > 0 ? { _replayPrefixLen: replayedInputPrefixLength } : {}),
     ...(webSearch ? { _webSearch: webSearch } : {}),
+    ...(imageGen ? { _imageGeneration: imageGen } : {}),
     ...(structuredOutput ? { _structuredOutput: true } : {}),
     ...(compactionRequest ? { _compactionRequest: true } : {}),
     ...(contextCompactionBoundary ? { _contextCompactionBoundary: true } : {}),

package/src/responses/state.ts

@@ -1,6 +1,6 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { atomicWriteFile, getConfigDir } from "../config";
+import { atomicWriteFileAsync, getConfigDir } from "../config";
 import type { OcxProviderContinuationState } from "../types";
 
 const MAX_STORED_RESPONSES = 1_000;
@@ -83,6 +83,8 @@ const replayedInputPrefixLengths = new WeakMap<object, number>();
 let loaded = false;
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
 let pendingPersistPath: string | null = null;
+/** Single-flight gate: overlapping response-state writes serialize (#612). */
+let persistGate: Promise<void> = Promise.resolve();
 
 function now(): number {
   return Date.now();
@@ -247,12 +249,18 @@ function ensureLoaded(): void {
   }
 }
 
-function persistNow(path: string): void {
+async function persistNow(path: string): Promise<void> {
   if (persistTimer) {
     clearTimeout(persistTimer);
     persistTimer = null;
   }
   pendingPersistPath = null;
+
+  // Serialize writers so concurrent flush + debounce cannot race on temps / ACL (#612).
+  const previous = persistGate;
+  let release!: () => void;
+  persistGate = new Promise<void>(resolve => { release = resolve; });
+  await previous;
   try {
     const entries: [string, StoredResponseState][] = [];
     let total = 0;
@@ -273,9 +281,11 @@ function persistNow(path: string): void {
     // mkdirSync's mode only applies on creation — re-harden an existing config dir so the
     // conversation-content snapshot never lands in a group/world-readable directory.
     try { chmodSync(dirname(path), 0o700); } catch { /* best-effort (e.g. Windows) */ }
-    atomicWriteFile(path, JSON.stringify({ version: 2, states: entries }));
+    await atomicWriteFileAsync(path, JSON.stringify({ version: 2, states: entries }));
   } catch {
     /* best-effort: disk trouble must never affect request handling */
+  } finally {
+    release();
   }
 }
 
@@ -285,15 +295,18 @@ function schedulePersist(): void {
   // debounce fires, and a late write must land in the home that owned the recorded state.
   pendingPersistPath = snapshotPath();
   const path = pendingPersistPath;
-  persistTimer = setTimeout(() => persistNow(path), SNAPSHOT_DEBOUNCE_MS);
+  persistTimer = setTimeout(() => { void persistNow(path); }, SNAPSHOT_DEBOUNCE_MS);
   (persistTimer as { unref?: () => void }).unref?.();
 }
 
 /** Flush any pending debounced snapshot write (graceful shutdown / deterministic tests). */
-export function flushResponseState(): void {
-  if (!persistTimer) return;
-  // Use the path captured when the write was scheduled — OPENCODEX_HOME may have moved since.
-  persistNow(pendingPersistPath ?? snapshotPath());
+export async function flushResponseState(): Promise<void> {
+  if (persistTimer) {
+    await persistNow(pendingPersistPath ?? snapshotPath());
+    return;
+  }
+  // No pending timer: still await any in-flight write so shutdown does not race (#612).
+  await persistGate;
 }
 
 function inputItems(input: unknown): unknown[] {
@@ -448,6 +461,7 @@ export function clearResponseStateMemoryForTests(): void {
     clearTimeout(persistTimer);
     persistTimer = null;
   }
+  pendingPersistPath = null;
   states.clear();
   storedResponseBytes = 0;
   loaded = false;

package/src/responses/tool-groups.ts

@@ -0,0 +1,19 @@
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Collect top-level and Responses Lite tool containers without altering their order. */
+export function collectResponsesToolGroups(body: unknown): unknown[][] {
+  if (!isPlainObject(body)) return [];
+
+  const groups: unknown[][] = [];
+  if (Array.isArray(body.tools)) groups.push(body.tools);
+  if (!Array.isArray(body.input)) return groups;
+
+  for (const item of body.input) {
+    if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
+      groups.push(item.tools);
+    }
+  }
+  return groups;
+}

package/src/router.ts

@@ -3,7 +3,7 @@ import { preservesPhysicalComboProvider, tryPickComboModel, type ComboPick } fro
 import { hasOwnProvider, resolveEnvValue } from "./config";
 import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
-import { PROVIDER_REGISTRY, providerCodexAccountMode } from "./providers/registry";
+import { PROVIDER_REGISTRY, providerCodexAccountMode, providerMatchesRegistryTransport } from "./providers/registry";
 import { LEGACY_CHATGPT_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
 import { decodeRoutedModelId, encodeRoutedModelId } from "./providers/slug-codec";
 import { getStaleCached } from "./codex/model-cache";
@@ -40,7 +40,9 @@ const MODEL_PROVIDER_PATTERNS: Array<{ providerNames: string[]; prefixes: string
 export function knownModelIdsForProvider(provName: string, prov: OcxProviderConfig): string[] {
   const ids = new Set<string>();
   for (const id of prov.models ?? []) ids.add(id);
-  const registry = PROVIDER_REGISTRY.find(entry => entry.id === provName);
+  const registry = providerMatchesRegistryTransport(provName, prov)
+    ? PROVIDER_REGISTRY.find(entry => entry.id === provName)
+    : undefined;
   for (const id of registry?.models ?? []) ids.add(id);
   // Registry model-keyed hint maps double as known native ids (e.g. NVIDIA carries no
   // static models list but names `moonshotai/kimi-k2.6` in its effort/window maps).
@@ -185,15 +187,22 @@ function warnIfBaseUrlDiscarded(providerName: string, userBaseUrl: string, effec
   );
 }
 
+function usableResolvedApiKey(apiKey: string | undefined): string | undefined {
+  const resolved = resolveEnvValue(apiKey);
+  return typeof resolved === "string" && resolved.trim().length > 0 ? resolved : undefined;
+}
+
 function routedProviderConfig(providerName: string, provider: OcxProviderConfig): OcxProviderConfig {
   const registryEntry = PROVIDER_REGISTRY.find(entry => entry.id === providerName);
-  if (!registryEntry) {
+  if (!registryEntry || !providerMatchesRegistryTransport(providerName, provider)) {
     assertProviderDestinationAllowed(providerName, provider);
-    return { ...provider, apiKey: resolveEnvValue(provider.apiKey) };
+    return { ...provider, apiKey: usableResolvedApiKey(provider.apiKey) };
   }
+  const resolvedApiKey = usableResolvedApiKey(provider.apiKey);
   const explicitKeyOverride = registryEntry.authKind === "oauth"
     && registryEntry.allowKeyAuthOverride === true
-    && provider.authMode === "key";
+    && provider.authMode === "key"
+    && resolvedApiKey !== undefined;
   const canonicalAuthMode = explicitKeyOverride
     ? "key"
     : registryEntry.authKind === "forward" || registryEntry.authKind === "oauth"
@@ -239,7 +248,7 @@ function routedProviderConfig(providerName: string, provider: OcxProviderConfig)
     adapter: registryEntry.adapter,
     baseUrl,
     authMode: canonicalAuthMode,
-    apiKey: resolveEnvValue(provider.apiKey),
+    apiKey: resolvedApiKey,
     // Backfill the Google wire mode + Vertex project/location from the registry when the user
     // config omits them, so a minimal `google-vertex`/`google-antigravity` entry still routes
     // through the correct branch (CCA/Vertex) instead of falling back to AI Studio.
@@ -286,7 +295,10 @@ function activeProviderEntries(config: OcxConfig): [string, OcxProviderConfig][]
 
 export class NoEnabledOpenAiProviderError extends Error {
   constructor(modelId: string) {
-    super(`No enabled OpenAI provider for model: ${modelId}. Run 'ocx init' to configure a provider, or check that your config has an enabled 'openai' provider.`);
+    super(
+      `Model ${modelId} requires the canonical openai provider. `
+      + `Run: ocx provider add openai && ocx sync && ocx restart`,
+    );
     this.name = "NoEnabledOpenAiProviderError";
   }
 }

package/src/server/auth-cors.ts

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { formatErrorResponse } from "../bridge";
 import {
+  apiKeyTransportConfigError,
   booleanRecordConfigError,
   modelAdapterRecordConfigError,
   codexAutoStartEnabled,
@@ -11,13 +12,14 @@ import {
   reasoningSummaryDeliveryRecordConfigError,
 } from "../config";
 import { providerDestinationConfigError } from "../lib/destination-policy";
-import { getProviderRegistryEntry, providerCodexAccountMode } from "../providers/registry";
+import { getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
 
 let _corsOrigin = "http://localhost:10100";
 export function setCorsOrigin(port: number): void { _corsOrigin = `http://localhost:${port}`; }
+/** The proxy's own listening port. No admission check uses it: both loopback predicates key on hostname alone. */
 export function configuredPort(): string {
   try { return new URL(_corsOrigin).port; } catch { return "10100"; }
 }
@@ -35,8 +37,18 @@ export function parseHttpHost(value: string | null): { hostname: string; port: s
 export function isLoopbackRequestHost(value: string | null): boolean {
   const parsed = parseHttpHost(value);
   if (!parsed) return true;
-  if (!isLoopbackHostname(parsed.hostname)) return false;
-  return parsed.port === "" || parsed.port === configuredPort();
+  // Loopback is a trust boundary by hostname, not by port. `ssh -L 20100:localhost:10100`
+  // legitimately arrives as `Host: localhost:20100`, and refusing it took the whole /v1/*
+  // data plane down with it, not just CORS. The sibling isLoopbackOriginValue() dropped its
+  // own port check for the same reason in e4e06125b ("same-trust-boundary"). Port equality
+  // was never the rebinding defense: a rebinding browser connects to the real port and sends
+  // it verbatim, so the hostname check below is what rejected it then and now.
+  //
+  // Scope of that guarantee: it holds for Hosts `parseHttpHost` can parse. An unparseable
+  // Host still returns true above — pre-existing behavior, not browser-reachable (a browser
+  // composes Host from its own connection), and pinned by a characterization test in
+  // tests/server-loopback-host-gate.test.ts. Tightening it is separate work.
+  return isLoopbackHostname(parsed.hostname);
 }
 
 export function isLoopbackOriginValue(value: string): boolean {
@@ -76,6 +88,34 @@ export function isAllowedRequestOrigin(req: Request, config: OcxConfig): boolean
   return !origin || isLoopbackOriginValue(origin) || isSameOriginAsRequest(req, origin) || isExtraAllowedOrigin(origin, config);
 }
 
+export function managementRequestOrigin(req: Request, config: OcxConfig): string | null {
+  const host = req.headers.get("Host");
+  const parsedHost = parseHttpHost(host);
+  if (!host || !parsedHost) return null;
+  if (!isApiAuthRequired(config) && !isLoopbackHostname(parsedHost.hostname)) return null;
+  try {
+    const protocol = new URL(req.url).protocol;
+    if (protocol !== "http:" && protocol !== "https:") return null;
+    return new URL(`${protocol}//${host}`).origin;
+  } catch {
+    return null;
+  }
+}
+
+export function isAllowedManagementOrigin(req: Request, config: OcxConfig): boolean {
+  const requestOrigin = managementRequestOrigin(req, config);
+  if (!requestOrigin) return false;
+  const origin = req.headers.get("Origin");
+  return !origin || origin === requestOrigin;
+}
+
+export function browserSecurityHeaders(): Record<string, string> {
+  return {
+    "X-Frame-Options": "DENY",
+    "Content-Security-Policy": "frame-ancestors 'none'",
+  };
+}
+
 export function corsHeaders(req?: Request, config?: OcxConfig): Record<string, string> {
   const origin = req?.headers.get("Origin");
   const allowOrigin = origin && req && config && isAllowedRequestOrigin(req, config) ? origin : _corsOrigin;
@@ -87,9 +127,19 @@ export function corsHeaders(req?: Request, config?: OcxConfig): Record<string, s
     // block covers GPT-Live voice protocol headers relayed by the /v1/live call-create path.
     "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key, X-Api-Key, Anthropic-Version, Anthropic-Beta, ChatGPT-Account-Id, OpenAI-Alpha, X-Session-Id, Session-Id, Thread-Id, Originator, X-OAI-Attestation",
     "Vary": "Origin",
+    ...browserSecurityHeaders(),
   };
 }
 
+export function managementCorsHeaders(req?: Request, config?: OcxConfig): Record<string, string> {
+  const headers = corsHeaders();
+  const origin = req?.headers.get("Origin");
+  if (origin && req && config && isAllowedManagementOrigin(req, config)) {
+    headers["Access-Control-Allow-Origin"] = origin;
+  }
+  return headers;
+}
+
 export function withCors(response: Response, req: Request, config: OcxConfig): Response {
   const headers = new Headers(response.headers);
   for (const [name, value] of Object.entries(corsHeaders(req, config))) {
@@ -102,6 +152,18 @@ export function withCors(response: Response, req: Request, config: OcxConfig): R
   });
 }
 
+export function withManagementCors(response: Response, req: Request, config: OcxConfig): Response {
+  const headers = new Headers(response.headers);
+  for (const [name, value] of Object.entries(managementCorsHeaders(req, config))) {
+    headers.set(name, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 export function jsonResponse(data: unknown, status = 200, req?: Request, config?: OcxConfig): Response {
   return new Response(JSON.stringify(data), {
     status,
@@ -114,8 +176,15 @@ export function configuredApiAuthToken(_config: OcxConfig): string | undefined {
   return token || undefined;
 }
 
+export function configuredAdminAuthToken(): string | undefined {
+  const token = process.env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim();
+  return token || undefined;
+}
+
 export function isLoopbackHostname(hostname: string | undefined): boolean {
-  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
+  // A fully-qualified "localhost." is the same host as "localhost": curl and some clients
+  // send the trailing dot verbatim, and refusing it 403s a legitimate loopback caller.
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase().replace(/\.$/, "");
   return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
 }
 
@@ -124,31 +193,48 @@ export function isApiAuthRequired(config: OcxConfig): boolean {
 }
 
 export function assertServerAuthConfig(config: OcxConfig): void {
-  if (isApiAuthRequired(config) && !configuredApiAuthToken(config)) {
-    throw new Error("OPENCODEX_API_AUTH_TOKEN is required when binding opencodex to a non-loopback hostname");
+  const hasConfiguredDataCredential = !!configuredApiAuthToken(config)
+    || (config.apiKeys ?? []).some(entry => !!entry.key.trim());
+  if (isApiAuthRequired(config) && !hasConfiguredDataCredential) {
+    throw new Error(
+      "A data-plane credential (OPENCODEX_API_AUTH_TOKEN or config.apiKeys) is required when binding opencodex to a non-loopback hostname",
+    );
   }
 }
 
-/** Whether `token` is one of the proxy's own admission secrets (env token or config API keys). */
-export function isProxyAdmissionSecret(token: string, config: OcxConfig): boolean {
-  const actual = token.trim();
-  if (!actual) return false;
+function secretEquals(actual: string, expected: string | undefined): boolean {
+  if (!expected) return false;
   const enc = new TextEncoder();
   const actualBytes = enc.encode(actual);
-  // Check env-based token
-  const expected = configuredApiAuthToken(config);
-  if (expected) {
-    const expectedBytes = enc.encode(expected);
-    if (expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes)) return true;
-  }
-  // Check config-based API keys
+  const expectedBytes = enc.encode(expected);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+
+/** Whether `token` is a data-plane admission secret. */
+export function isDataPlaneAdmissionSecret(token: string, config: OcxConfig): boolean {
+  const actual = token.trim();
+  if (!actual) return false;
+  if (secretEquals(actual, configuredApiAuthToken(config))) return true;
   for (const k of config.apiKeys ?? []) {
-    const keyBytes = enc.encode(k.key);
-    if (keyBytes.length === actualBytes.length && timingSafeEqual(actualBytes, keyBytes)) return true;
+    if (secretEquals(actual, k.key)) return true;
   }
   return false;
 }
 
+/** Whether `token` is the environment-provided management secret. */
+export function isManagementAdmissionSecret(token: string): boolean {
+  const actual = token.trim();
+  return !!actual && secretEquals(actual, configuredAdminAuthToken());
+}
+
+/** Whether `token` is one of the proxy's own admission secrets and must never reach an upstream. */
+export function isProxyAdmissionSecret(token: string, config: OcxConfig): boolean {
+  const actual = token.trim();
+  if (!actual) return false;
+  if (/^ocx_(?:data|admin|session)_/.test(actual) || /^ocx_[0-9a-f]{40}$/.test(actual)) return true;
+  return isDataPlaneAdmissionSecret(actual, config) || isManagementAdmissionSecret(actual);
+}
+
 export class ForwardAdmissionCredentialError extends Error {
   constructor() {
     super("OpenCodex admission credentials cannot be forwarded upstream");
@@ -168,12 +254,11 @@ export function hasValidApiAuth(req: Request, config: OcxConfig): boolean {
     // Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
     || req.headers.get("x-api-key")?.trim();
   if (!actual) return false;
-  return isProxyAdmissionSecret(actual, config);
+  return isDataPlaneAdmissionSecret(actual, config);
 }
 
-export function requireApiAuth(req: Request, config: OcxConfig, kind: "management" | "data-plane"): Response | null {
+export function requireApiAuth(req: Request, config: OcxConfig, _kind: "data-plane"): Response | null {
   if (hasValidApiAuth(req, config)) return null;
-  if (kind === "management") return jsonResponse({ error: "opencodex API key required" }, 401);
   return formatErrorResponse(401, "authentication_error", "opencodex API key required");
 }
 
@@ -185,7 +270,7 @@ export function requireApiAuth(req: Request, config: OcxConfig, kind: "managemen
 export function requireResponsesApiAuth(req: Request, config: OcxConfig): Response | null {
   if (!isApiAuthRequired(config)) return null;
   const actual = req.headers.get("x-opencodex-api-key")?.trim();
-  if (actual && isProxyAdmissionSecret(actual, config)) return null;
+  if (actual && isDataPlaneAdmissionSecret(actual, config)) return null;
   return formatErrorResponse(401, "authentication_error", "opencodex API key required");
 }
 
@@ -232,6 +317,8 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
   if (destinationError) return `provider ${name} ${destinationError}`;
   const headersError = providerHeadersConfigError(typed.headers);
   if (headersError) return `provider ${name} ${headersError}`;
+  const apiKeyTransportError = apiKeyTransportConfigError(typed);
+  if (apiKeyTransportError) return `provider ${name} ${apiKeyTransportError}`;
   const maxInputError = positiveIntegerRecordConfigError(raw.modelMaxInputTokens, "modelMaxInputTokens");
   if (maxInputError) return `provider ${name} ${maxInputError}`;
   const reasoningSummariesError = booleanRecordConfigError(raw.modelSupportsReasoningSummaries, "modelSupportsReasoningSummaries");
@@ -307,6 +394,7 @@ export function safeConfigDTO(config: OcxConfig): unknown {
       "disabled",
       "allowPrivateNetwork",
       "authMode",
+      "apiKeyTransport",
       "keyOptional",
       "freeTier",
       "liveModels",
@@ -330,7 +418,9 @@ export function safeConfigDTO(config: OcxConfig): unknown {
     ] as const) {
       copyIfDefined(dto, provider, key);
     }
-    const registryNote = getProviderRegistryEntry(name)?.note;
+    const registryNote = providerMatchesRegistryTransport(name, provider)
+      ? getProviderRegistryEntry(name)?.note
+      : undefined;
     if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
     const codexAccountMode = providerCodexAccountMode(name, provider);
     if (codexAccountMode) dto.codexAccountMode = codexAccountMode;