import { providerRelativeSendPathConfigError } from "../config/provider-relative-send-path";
import { contextTierRecordConfigError, modelCapabilitiesConfigError } from "../config/provider-validation";
import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
import { initialModelSelection } from "../providers/initial-model-selection";
import { extractAccountId } from "../oauth/chatgpt";
import { formatErrorResponse } from "../bridge";
import {
  codexAutoStartEnabled,
  modelPreferHostedToolsConfigError,
  providerModelCostsConfigError,
  providerWebSearchBridgeConfigError,
  requestPacingConfigError,
  retryOn429PolicyConfigError,
  retryOnResetPolicyConfigError,
  sanitizeModelCostsForDisplay,
} from "../config";
import {
  apiKeyTransportConfigError,
  projectContextConfigError,
  autoReviewModelOverridesConfigError,
  autoReviewModelTargetConfigError,
  booleanRecordConfigError,
  providerReasoningPinsConfigError,
  modelAdapterRecordConfigError,
  nonBlankStringArrayConfigError,
  positiveIntegerConfigError,
  positiveIntegerRecordConfigError,
  providerBaseUrlConfigError,
  providerHeadersConfigError,
  reasoningSummaryDeliveryRecordConfigError,
  upstreamHttpVersionConfigError,
} from "../config/provider-validation";
import { providerDestinationConfigError } from "../lib/destination-policy";
import { providerEgressConfigError } from "../lib/provider-egress";
import { redactSecretString } from "../lib/redact";
import { DECLARABLE_HOSTED_TOOL_TYPES } from "../responses/hosted-tool-policy";
import { effectiveGoogleMode, getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport, registryEntryForProviderDestination } from "../providers/registry";
import { providerConfigSeed } from "../providers/derive";
import type { OcxConfig, OcxProviderConfig } from "../types";
import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
import { modelAutoCompactTokenLimitsConfigError } from "../providers/auto-compact-budget";
import { vercelGatewayRoutingConfigError } from "../providers/vercel-gateway-routing";
import { googleVertexLocationConfigError } from "../providers/google-vertex-location";
import { xaiResponsesOptInState } from "../providers/xai-responses-opt-in";

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"; }
}

export function parseHttpHost(value: string | null): { hostname: string; port: string } | null {
  if (!value) return null;
  try {
    const parsed = new URL(`http://${value}`);
    return { hostname: parsed.hostname.toLowerCase(), port: parsed.port };
  } catch {
    return null;
  }
}

export function isLoopbackRequestHost(value: string | null): boolean {
  const parsed = parseHttpHost(value);
  if (!parsed) return true;
  // 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/server-loopback-host-gate.test.ts. Tightening it is separate work.
  return isLoopbackHostname(parsed.hostname);
}

export function isLoopbackOriginValue(value: string): boolean {
  try {
    const parsed = new URL(value);
    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
    return isLoopbackHostname(parsed.hostname);
  } catch {
    return false;
  }
}

export function isSameOriginAsRequest(req: Request, origin: string): boolean {
  try {
    return origin === new URL(req.url).origin;
  } catch {
    return false;
  }
}

export function isAllowedRequestOrigin(req: Request, config: RequestPolicyView): boolean {
  const origin = req.headers.get("Origin");
  if (!isApiAuthRequired(config)) {
    if (!isLoopbackRequestHost(req.headers.get("Host"))) return false;
    return !origin || isLoopbackOriginValue(origin) || isExtraAllowedOrigin(origin, config);
  }
  return !origin || isLoopbackOriginValue(origin) || isSameOriginAsRequest(req, origin) || isExtraAllowedOrigin(origin, config);
}

function isExtraAllowedOrigin(origin: string, cfg: RequestPolicyView): boolean {
  if (!cfg.corsAllowOrigins?.length) return false;
  const parsedOrigin = comparableOrigin(origin);
  return cfg.corsAllowOrigins.some(allowed => {
    const parsedAllowed = comparableOrigin(allowed);
    return parsedOrigin !== null && parsedAllowed !== null
      ? parsedAllowed === parsedOrigin
      : allowed === origin;
  });
}

function comparableOrigin(value: string): string | null {
  try {
    const parsed = new URL(value);
    if (parsed.origin !== "null") return parsed.origin;
    // WHATWG URL exposes authority-based custom schemes (for example browser
    // extensions) as opaque `null` origins. Compare their scheme + authority so
    // one allowlisted extension cannot admit every other opaque origin.
    return parsed.host ? `${parsed.protocol}//${parsed.host}` : null;
  } catch {
    return null;
  }
}

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 (isLoopbackHostname(parsedHost.hostname)) {
    try {
      const protocol = new URL(req.url).protocol;
      if (protocol !== "http:" && protocol !== "https:") return null;
      return new URL(`${protocol}//${host}`).origin;
    } catch {
      return null;
    }
  }
  if (!isApiAuthRequired(config)) return null;
  if (config.runtimeRole === "hub" && config.hub?.managementPublicOrigin) {
    try {
      const configured = new URL(config.hub.managementPublicOrigin);
      if (
        (configured.protocol === "http:" || configured.protocol === "https:")
        && !configured.username
        && !configured.password
        && configured.pathname === "/"
        && !configured.search
        && !configured.hash
      ) return configured.origin;
    } catch { /* malformed direct fixture: fall through to observed origin */ }
  }
  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");
  // Exact match against the process-derived origin, or an operator-listed corsAllowOrigins
  // entry (covers TLS-terminator https://… when the process observes http://…).
  return !origin || origin === requestOrigin || isExtraAllowedOrigin(origin, config);
}

export function browserSecurityHeaders(): Record<string, string> {
  return {
    "X-Frame-Options": "DENY",
    "Content-Security-Policy": "frame-ancestors 'none'",
  };
}

/**
 * Baseline data-plane request headers. ChatGPT-Account-Id is required for browser/Electron
 * ChatGPT & Codex App voice preflights (direct forward auth matches the bearer to this account
 * id). The OpenAI-Alpha .. X-OAI-Attestation block covers GPT-Live voice protocol headers
 * relayed by the /v1/live call-create path.
 */
const STATIC_ALLOWED_REQUEST_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";

/**
 * A fixed allow-list cannot enumerate vendor telemetry headers: the OpenAI and Anthropic
 * browser SDKs send `X-Stainless-*` describing runtime and retry state, and the browser blocks
 * the real request when the preflight omits even one of them (#1773).
 *
 * Echo what an already-allowed origin asked for, and fall back to the static list otherwise.
 * The echo is deliberately gated on the origin check that ran first: this widens which headers
 * an admitted caller may send, never which origins are admitted, and it grants nothing to an
 * origin that would have been rejected anyway. Authentication is unchanged — the preflight
 * itself carries no credential and produces no auth or account-pool side effect.
 */
function allowedRequestHeaders(req?: Request): string {
  const requested = req?.headers.get("Access-Control-Request-Headers")?.trim();
  if (!requested) return STATIC_ALLOWED_REQUEST_HEADERS;
  const seen = new Set(STATIC_ALLOWED_REQUEST_HEADERS.split(",").map(h => h.trim().toLowerCase()));
  const extra: string[] = [];
  for (const raw of requested.split(",")) {
    const name = raw.trim();
    // Header names are case-insensitive on the wire, so normalize before de-duplicating;
    // echo the caller's spelling for the ones we add.
    if (!name || seen.has(name.toLowerCase())) continue;
    seen.add(name.toLowerCase());
    extra.push(name);
  }
  return extra.length === 0 ? STATIC_ALLOWED_REQUEST_HEADERS : `${STATIC_ALLOWED_REQUEST_HEADERS}, ${extra.join(", ")}`;
}

export function corsHeaders(req?: Request, config?: RequestPolicyView): Record<string, string> {
  const origin = req?.headers.get("Origin");
  const originAllowed = Boolean(origin && req && config && isAllowedRequestOrigin(req, config));
  const allowOrigin = originAllowed && origin ? origin : _corsOrigin;
  return {
    "Access-Control-Allow-Origin": allowOrigin,
    "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
    "Access-Control-Allow-Headers": allowedRequestHeaders(originAllowed ? req : undefined),
    // A response that varies by the request's headers must say so, or a shared cache can
    // replay one client's allow-list to a client that asked for different headers.
    "Vary": "Origin, Access-Control-Request-Headers",
    ...browserSecurityHeaders(),
  };
}

export function managementCorsHeaders(req?: Request, config?: OcxConfig): Record<string, string> {
  const headers = corsHeaders();
  headers["Access-Control-Allow-Headers"] = `${STATIC_ALLOWED_REQUEST_HEADERS}, X-OpenCodex-GUI-Origin, X-OpenCodex-CSRF-Token`;
  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: RequestPolicyView): Response {
  const headers = new Headers(response.headers);
  for (const [name, value] of Object.entries(corsHeaders(req, config))) {
    headers.set(name, value);
  }
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  });
}

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?: RequestPolicyView): Response {
  return new Response(JSON.stringify(data), {
    status,
    headers: { "Content-Type": "application/json", ...corsHeaders(req, config) },
  });
}

// The parameter is vestigial — the token has always come from the environment — but callers
// pass a config, so keep accepting one. Typed as `unknown` rather than `OcxConfig` so a narrow
// policy view can reach it too (#1102); widening to OcxConfig here would force every caller in
// the admission path back to the full config.
export function configuredApiAuthToken(_config?: unknown): string | undefined {
  const token = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
  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 {
  // 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]";
}

export function isApiAuthRequired(config: Pick<OcxConfig, "hostname">): boolean {
  return !isLoopbackHostname(config.hostname);
}

/**
 * The slice of config that decides admission and CORS, and nothing else (#1102).
 *
 * The unauthenticated loopback listener shares this process with the public one: same routing,
 * same account pool, same drain. The only thing it must see differently is its own bind
 * address, because `isApiAuthRequired` reads `hostname` and the shared config says "0.0.0.0".
 *
 * Two ways to express that were rejected. Passing the whole config with `hostname` rewritten
 * and holding it for the listener's lifetime would go stale the moment the management API
 * changes a setting. Adding an `allowUnauthenticated` parameter to the resolvers would create a
 * callable admission bypass that the PUBLIC listener could also reach — the switch would exist
 * on the wrong side of the boundary.
 *
 * So this type is deliberately narrow: it cannot masquerade as a business config, and a policy
 * view that leaks into a routing path fails to typecheck rather than silently taking effect.
 */
export interface LinkIngressPolicy {
  allowedKeyIds: ReadonlySet<string>;
}

export type RequestPolicyView = Pick<OcxConfig, "hostname" | "corsAllowOrigins" | "apiKeys"> & {
  linkIngress?: LinkIngressPolicy;
};

export type DataPlaneAdmissionOptions = {
  linkIngress?: ReadonlySet<string>;
};

/** Derive the per-request policy view for a listener. Cheap enough to build per request. */
export function requestPolicyView(
  config: OcxConfig,
  bindHostname: string,
  linkIngress?: LinkIngressPolicy,
): RequestPolicyView {
  return {
    hostname: bindHostname,
    ...(config.corsAllowOrigins ? { corsAllowOrigins: config.corsAllowOrigins } : {}),
    ...(config.apiKeys ? { apiKeys: config.apiKeys } : {}),
    ...(linkIngress ? { linkIngress } : {}),
  };
}

export function assertServerAuthConfig(config: OcxConfig): void {
  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",
    );
  }
}

function secretEquals(actual: string, expected: string | undefined): boolean {
  if (!expected) return false;
  const enc = new TextEncoder();
  const actualBytes = enc.encode(actual);
  const expectedBytes = enc.encode(expected);
  return expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes);
}

/**
 * Which admission a data-plane request used.
 *
 * `configured` carries the matched key's id so a request can be attributed to
 * the key that opened it. The other two exist so an unattributed request is a
 * stated fact rather than a missing field: neither has a configured entry to
 * point at, and a sentinel string in the id would collide with a hand-edited
 * entry that happens to be named `loopback`.
 */
/**
 * HOW an admission credential was presented.
 *
 * The credential IDENTITY (which key matched) and its PRESENTATION (which header carried it)
 * are different facts, and #1686 needs both: a proxy secret arriving as a bearer on the
 * Responses transport is admissible, but only if the upstream credential is then guaranteed to
 * be substituted. Collapsing the two is what made that flow unexpressible.
 */
export type DataPlaneAdmissionSource = "loopback" | "dedicated" | "bearer" | "x-api-key";

/**
 * Process-local, salted identity of the admission secret that was actually matched.
 *
 * Context-relay ownership is partitioned by this value, so two operators holding different
 * keys cannot reach each other's sessions even when both resolve to the same upstream
 * workspace. `source` is deliberately excluded: the same key arriving as a bearer or in the
 * dedicated header is one principal. Rotating or replacing a secret mints a new principal and
 * drops continuity, which is the safe direction — a reused key id or a replaced environment
 * secret must not inherit the previous holder's sessions. Loopback admission carries no caller
 * identity and mints nothing, so the relay refuses it rather than treating every local process
 * as one user.
 */
const CONTEXT_PRINCIPAL_SALT = randomBytes(32);

function mintContextPrincipal(kind: string, keyId: string, credential: string): string {
  return createHmac("sha256", CONTEXT_PRINCIPAL_SALT)
    .update(kind).update("\0").update(keyId).update("\0").update(credential)
    .digest("hex");
}

export type DataPlaneAdmission =
  | { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
  | { kind: "environment"; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
  | { kind: "loopback"; source: "loopback" };

/**
 * Which admission secret `token` is, or null when it is none of them.
 *
 * Identical comparisons in an identical order to the boolean form this replaces —
 * `secretEquals` still length-guards before `timingSafeEqual`. The only
 * difference is that the matched entry's id survives the loop instead of being
 * discarded, which is what makes per-key attribution possible without touching
 * the admission decision itself.
 */
export function resolveDataPlaneAdmissionSecret(
  token: string,
  config: Pick<OcxConfig, "apiKeys">,
  source: DataPlaneAdmissionSource = "dedicated",
  options: DataPlaneAdmissionOptions = {},
): DataPlaneAdmission | null {
  const actual = token.trim();
  if (!actual) return null;
  if (!options.linkIngress && secretEquals(actual, configuredApiAuthToken(config))) {
    return { kind: "environment", source, contextPrincipalId: mintContextPrincipal("environment", "", actual) };
  }
  for (const k of config.apiKeys ?? []) {
    if (options.linkIngress && !options.linkIngress.has(k.id)) continue;
    if (secretEquals(actual, k.key)) {
      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, actual) };
    }
    const pending = k.pendingRotation;
    if (pending && Date.parse(pending.expiresAt) > Date.now() && secretEquals(actual, pending.key)) {
      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, pending.key) };
    }
  }
  return null;
}

/** The principal an authenticated admission belongs to, or undefined for loopback. */
export function contextPrincipalIdOf(admission: DataPlaneAdmission | undefined): string | undefined {
  return admission && "contextPrincipalId" in admission ? admission.contextPrincipalId : undefined;
}

/**
 * The caller principal for a context-relay request, which is a stricter question than admission.
 *
 * The default bind is loopback, where admission deliberately never reads a token, so an admitted
 * request carries no caller identity. History ownership needs one, so the relay asks separately:
 * a caller that presents a real opencodex API key gets that key’s principal even on loopback,
 * and a caller that presents none gets nothing and is refused. This adds identity where the caller
 * volunteered it; it does not admit anyone who was not already admitted, and it does not change
 * which credential goes upstream.
 */
export function resolveContextPrincipal(req: Request, config: OcxConfig, admission: DataPlaneAdmission | undefined): string | undefined {
  const named = contextPrincipalIdOf(admission);
  if (named) return named;
  if (admission?.kind !== "loopback") return undefined;
  const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
  const apiKey = req.headers.get("x-api-key")?.trim();
  for (const [token, source] of [[dedicated, "dedicated"], [bearer, "bearer"], [apiKey, "x-api-key"]] as const) {
    if (!token) continue;
    const resolved = resolveDataPlaneAdmissionSecret(token, config, source);
    const principal = contextPrincipalIdOf(resolved ?? undefined);
    if (principal) return principal;
  }
  return undefined;
}

/** Whether `token` is a data-plane admission secret. */
export function isDataPlaneAdmissionSecret(token: string, config: OcxConfig): boolean {
  return resolveDataPlaneAdmissionSecret(token, config) !== null;
}

/**
 * Split an admission into the fields a log row records.
 *
 * `apiKeyId` is set only for a configured key. The other two kinds have no
 * configured entry to name, and folding them into the id as sentinel strings
 * would collide with a hand-edited entry that happens to be called `loopback` —
 * ids are only validated as non-empty strings.
 */
export function admissionFields(admission: DataPlaneAdmission): {
  admissionKind: DataPlaneAdmission["kind"];
  apiKeyId?: string;
} {
  return admission.kind === "configured"
    ? { admissionKind: "configured", apiKeyId: admission.keyId }
    : { admissionKind: admission.kind };
}

export type ApiAuthDisposition = "required" | "accepted" | "rejected";

export interface ApiAuthMatrixRow {
  endpoint: string;
  bearer: ApiAuthDisposition;
  dedicated: ApiAuthDisposition;
  xApiKey: ApiAuthDisposition;
}

/**
 * Which headers each data-plane endpoint actually accepts, shipped to the GUI so
 * it stops describing the rule from memory. The dashboard has been telling users
 * that Chat Completions takes `Authorization: Bearer`, which this file has never
 * allowed — that route uses the dedicated-header-only wrapper because
 * `Authorization` there may belong to Codex Direct passthrough.
 *
 * It lives next to the wrappers it describes, and a test drives real requests
 * against every cell rather than reading the table back to itself.
 */
export const AUTH_MATRIX: readonly ApiAuthMatrixRow[] = [
  { endpoint: "/v1/audio/transcriptions", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  { endpoint: "/v1/live", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  { endpoint: "/v1/realtime/calls", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  // #1686: a bearer that is one of OUR admission secrets is now accepted here. It is safe
  // because materializeCodexUpstreamAuth substitutes the stored main credential rather than
  // forwarding it; a bearer that is NOT our secret stays unadmitted and remains Codex Direct
  // passthrough, so the two bearer domains still never mix. `x-api-key` is still rejected.
  { endpoint: "/v1/responses", bearer: "accepted", dedicated: "accepted", xApiKey: "rejected" },
  { endpoint: "/v1/chat/completions", bearer: "accepted", dedicated: "accepted", xApiKey: "rejected" },
  { endpoint: "/v1/messages", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  { endpoint: "/v1/models", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  // #809: least-privilege catalog read for remote Codex clients. Same admission set as
  // /v1/models and for the same reason — it forwards no caller credential upstream — so a
  // remote client no longer needs an admin token just to read the model catalog.
  { endpoint: "/v1/catalog", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  // #4236: the hub-state read a connected client uses instead of reporting its own empty
  // credential store. Same admission set and the same justification as the two rows above —
  // it forwards no caller credential upstream and its body is booleans plus model ids — and it
  // 404s on any host whose runtimeRole is not "hub", so no standalone install gains a surface.
  { endpoint: "/v1/hub-state", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
  // Usage additionally requires a configured key identity; unscoped environment keys are refused.
  { endpoint: "/v1/usage", bearer: "rejected", dedicated: "accepted", xApiKey: "rejected" },
];

/** 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");
    this.name = "ForwardAdmissionCredentialError";
  }
}

export function validateForwardAdmissionCredential(headers: Headers, config: OcxConfig): void {
  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
  if (bearer && isProxyAdmissionSecret(bearer, config)) throw new ForwardAdmissionCredentialError();
}

/** Whether Authorization carries a caller-owned native Codex credential safe to forward. */
export function hasForwardableCodexBearer(headers: Headers, config: OcxConfig): boolean {
  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
  const accountId = headers.get("chatgpt-account-id")?.trim()
    || (bearer ? extractAccountId(undefined, bearer) : undefined);
  return !!bearer && !!accountId && !isProxyAdmissionSecret(bearer, config);
}

/**
 * Resolving form of `hasValidApiAuth`: identical header precedence, identical
 * decision, but it names the admission instead of collapsing it to a boolean.
 */
export function resolveApiAuth(req: Request, config: RequestPolicyView): DataPlaneAdmission | null {
  // A loopback bind never reads a token at all, so there is no key to name.
  if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
  const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
  // Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
  const apiKey = req.headers.get("x-api-key")?.trim();
  if (apiKey) return resolveDataPlaneAdmissionSecret(apiKey, config, "x-api-key", { linkIngress: config.linkIngress?.allowedKeyIds });
  return null;
}

export function hasValidApiAuth(req: Request, config: RequestPolicyView): boolean {
  return resolveApiAuth(req, config) !== null;
}

export function requireApiAuth(req: Request, config: RequestPolicyView, _kind: "data-plane"): Response | null {
  if (hasValidApiAuth(req, config)) return null;
  return formatErrorResponse(401, "authentication_error", "opencodex API key required");
}

/**
 * Admission for OpenAI Responses transports whose Authorization header belongs to
 * Codex Direct. Remote binds must use the dedicated proxy header so the two bearer
 * domains can never be confused.
 */
export function resolveResponsesApiAuth(req: Request, config: RequestPolicyView): DataPlaneAdmission | null {
  if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
  // The dedicated header still WINS, because it is unambiguous.
  const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
  // #1686: a bearer may also be one of OUR admission secrets. Rejecting it outright meant a
  // Codex client configured with `env_key` could not reach Direct at all. Admitting it is only
  // safe because the upstream credential is then SUBSTITUTED rather than forwarded -- see
  // materializeCodexUpstreamAuth. A bearer that is NOT our secret stays unadmitted here and
  // remains Codex Direct passthrough, so the two bearer domains still never mix.
  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
  // `x-api-key` is deliberately NOT accepted on this transport.
  return null;
}



export function requireResponsesApiAuth(req: Request, config: RequestPolicyView): Response | null {
  if (resolveResponsesApiAuth(req, config)) return null;
  return formatErrorResponse(401, "authentication_error", "opencodex API key required");
}

const FORBIDDEN_PROVIDER_RUNTIME_FIELDS = [
  "virtualModels", "codexAuthContext", "selectedForwardHeaders",
  "sidecarOutcomeRecorder", "_codexAccountOverride", "_codexAccountRequired",
  "_apiKeyAttempt",
] as const;

function sameCanonicalProviderSeed(actual: Record<string, unknown>, expected: OcxProviderConfig): boolean {
  const actualKeys = Object.keys(actual).sort();
  const expectedKeys = Object.keys(expected).sort();
  if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, i) => key !== expectedKeys[i])) return false;
  return actualKeys.every(key => JSON.stringify(actual[key]) === JSON.stringify((expected as unknown as Record<string, unknown>)[key]));
}

/**
 * Operator-overlay tolerant variant of the canonical seed check: every key the registry
 * seed defines must still match the submitted provider verbatim, but keys the seed never
 * defines are ignored instead of failing the comparison. Field-masked writes (PATCH,
 * the provider editor, reload) merge onto the persisted row, so the submitted candidate
 * legitimately carries stored operator overlays like `selectedModels` or `disabled`.
 * Those fields are validated by their own write boundaries and cannot widen what the
 * forward proxy claims. Full-object writes (POST) keep the strict exact-key comparison
 * so a forged overlay cannot ride in on a canonical transport seed.
 */
function matchesCanonicalProviderSeed(actual: Record<string, unknown>, expected: OcxProviderConfig): boolean {
  return Object.keys(expected).every(
    key => Object.hasOwn(actual, key)
      && JSON.stringify(actual[key]) === JSON.stringify((expected as unknown as Record<string, unknown>)[key]),
  );
}

function positiveWindowValue(value: unknown): boolean {
  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
}

/**
 * Shape-check the two context overlays before the canonical seed comparison drops them.
 *
 * `null` means "clear this" and is normalized by the PATCH field mask, but this validator
 * also runs for POST and reload, where a whole provider object lands on disk verbatim. A
 * `null` surviving there would be a value no reader expects, so full objects must carry a
 * real number or omit the field.
 */
function nativeContextOverlayError(raw: Record<string, unknown>): string | null {
  if (Object.hasOwn(raw, "contextWindow") && !positiveWindowValue(raw.contextWindow)) {
    return "provider openai contextWindow must be a positive safe integer";
  }
  if (Object.hasOwn(raw, "modelContextWindows")) {
    const windows = raw.modelContextWindows;
    if (typeof windows !== "object" || windows === null || Array.isArray(windows)) {
      return "provider openai modelContextWindows must be a plain object";
    }
    for (const [model, value] of Object.entries(windows as Record<string, unknown>)) {
      if (model.trim() === "") return "provider openai modelContextWindows keys must be nonblank model ids";
      if (!positiveWindowValue(value)) {
        return "provider openai modelContextWindows values must be positive safe integers";
      }
    }
  }
  return null;
}

/**
 * Validate a provider object arriving at the management write boundary. Returns an error
 * string, or null when the provider may be persisted. Caller-controlled names/fields are
 * redacted and JSON-escaped so secrets never reach the response.
 */
export function providerManagementConfigError(
  name: unknown,
  provider: unknown,
  options?: { allowOperatorOverlays?: boolean },
): string | null {
  if (typeof name !== "string" || !provider || typeof provider !== "object" || Array.isArray(provider)) {
    return "provider must be a plain object";
  }
  const raw = provider as Record<string, unknown>;
  const contextTiersError = contextTierRecordConfigError(raw.modelContextTiers);
  if (contextTiersError) return contextTiersError;
  const capabilitiesError = modelCapabilitiesConfigError(raw.modelCapabilities);
  if (capabilitiesError) return capabilitiesError;
  const pinsError = providerReasoningPinsConfigError(raw);
  if (pinsError) return pinsError;
  if (name === "openai" && (Object.hasOwn(raw, "autoReviewModel") || Object.hasOwn(raw, "autoReviewModelOverrides"))) {
    return "provider openai must not include autoReviewModel or autoReviewModelOverrides";
  }
  // Canonical OpenAI is the ChatGPT forward seed. allowPrivateNetwork is the explicit
  // opt-in that skips destination DNS classification (loopback, RFC1918, metadata).
  // Overlay-tolerant comparison would otherwise treat it as an extra key and persist it.
  if (name === "openai" && Object.hasOwn(raw, "allowPrivateNetwork")) {
    return "provider openai must not include allowPrivateNetwork";
  }
  // The same reasoning applies to `headers`, and it is not hypothetical. Canonical OpenAI
  // has no registry `staticHeaders`, so any header block on this row is operator-authored,
  // and the forward adapter copies it onto the ChatGPT request BEFORE the incoming forward
  // headers — a persisted value therefore wins whenever the caller omits that header. The
  // exact-key comparison rejected it as an extra key; overlay tolerance would silently admit
  // it on every merge-based write path while POST still refused it.
  if (name === "openai" && Object.hasOwn(raw, "headers")) {
    return "provider openai must not include headers";
  }
  const autoReviewTargetError = autoReviewModelTargetConfigError(raw.autoReviewModel, "autoReviewModel", true);
  if (autoReviewTargetError) return autoReviewTargetError;
  const autoReviewMapError = autoReviewModelOverridesConfigError(raw.autoReviewModelOverrides, "autoReviewModelOverrides", true);
  if (autoReviewMapError) return autoReviewMapError;
  for (const field of FORBIDDEN_PROVIDER_RUNTIME_FIELDS) {
    if (Object.hasOwn(raw, field)) return `provider ${name} must not include runtime field "${field}"`;
  }
  if (name === "chatgpt") return "provider chatgpt is reserved for internal credential compatibility";
  if (name === "openai-multi") return "provider openai-multi is reserved for legacy config migration";
  if (name === "openai") {
    const entry = getProviderRegistryEntry(name);
    const seed = entry ? providerConfigSeed(entry) : undefined;
    if (!Object.hasOwn(raw, "codexAccountMode") || (raw.codexAccountMode !== "pool" && raw.codexAccountMode !== "direct")) {
      return "provider openai codexAccountMode must be pool or direct";
    }
    if (seed) seed.codexAccountMode = raw.codexAccountMode;
    const canonicalCandidate = { ...raw };
    // Validated operator overlays do not change the canonical auth/transport seed.
    delete canonicalCandidate.pinnedReasoningEffort;
    delete canonicalCandidate.modelPinnedReasoningEfforts;
    delete canonicalCandidate.responsesSnapshotRepair;
    // modelCosts is a user-owned display overlay, not part of the canonical
    // forward seed; it is validated separately below (providerModelCostsConfigError).
    delete canonicalCandidate.modelCosts;
    // requestPacing is a user-owned transport overlay, not part of the canonical seed.
    delete canonicalCandidate.requestPacing;
    // retryOnReset is the same kind of overlay: it tunes how this provider's own Responses
    // sends recover, not what the canonical forward seed is. Validated below
    // (retryOnResetPolicyConfigError).
    delete canonicalCandidate.retryOnReset;
    // Context windows are the same kind of user-owned overlay as requestPacing: the operator
    // narrowing what their own native rows advertise. They can only ever LOWER the measured
    // window (see nativeOpenAiContextWindow), so admitting them cannot widen what the proxy
    // claims. Validated first — this function also guards POST/reload, where nothing
    // normalizes the shape afterwards, so a bad value would reach disk.
    const contextOverlayError = nativeContextOverlayError(raw);
    if (contextOverlayError) return contextOverlayError;
    delete canonicalCandidate.contextWindow;
    delete canonicalCandidate.modelContextWindows;
    // User-owned soft compaction policy; it does not alter the canonical transport seed.
    delete canonicalCandidate.modelAutoCompactTokenLimits;
    // Same category: annotating empty tool outputs is a user-owned request-shaping preference,
    // not part of the canonical transport seed. Without this the field is accepted by
    // validation and then rejected by the seed comparison, so canonical OpenAI could never
    // set OR clear it — the value was admitted and then refused in the same request.
    delete canonicalCandidate.annotateEmptyToolOutputs;
    // Canonical ChatGPT keeps WebSocket as the default, but an operator may
    // select the existing HTTP/SSE path without changing its auth or endpoint.
    if (raw.upstreamWebsocket !== undefined) {
      if (raw.upstreamWebsocket !== false) return "provider openai upstreamWebsocket must be false or omitted";
      delete canonicalCandidate.upstreamWebsocket;
    }
    const canonical = seed && (options?.allowOperatorOverlays
      ? matchesCanonicalProviderSeed(canonicalCandidate, seed)
      : sameCanonicalProviderSeed(canonicalCandidate, seed));
    if (!canonical) {
      return `provider ${name} must equal the canonical built-in provider seed`;
    }
  } else if (Object.hasOwn(raw, "codexAccountMode")) {
    return `provider ${name} must not include codexAccountMode`;
  }
  const typed = provider as unknown as OcxProviderConfig;
  const baseUrlError = providerBaseUrlConfigError(typed.baseUrl);
  if (baseUrlError) return `provider ${name} ${baseUrlError}`;
  if (effectiveGoogleMode(name, typed) === "vertex" && typed.location !== undefined) {
    const locationError = googleVertexLocationConfigError(typed.location);
    if (locationError) return `provider ${name} ${locationError}`;
  }
  const destinationError = providerDestinationConfigError(name, typed);
  if (destinationError) return `provider ${name} ${destinationError}`;
  for (const field of ["responsesPath", "chatCompletionsPath"] as const) {
    const sendPathError = providerRelativeSendPathConfigError(field, raw[field]);
    if (sendPathError) return `provider ${JSON.stringify(redactSecretString(name))} ${sendPathError}`;
  }
  const headersError = providerHeadersConfigError(typed.headers);
  if (headersError) return `provider ${name} ${headersError}`;
  const retryOn429Error = retryOn429PolicyConfigError(raw.retryOn429);
  if (retryOn429Error) {
    // The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
    // it before it reaches the management API response.
    return `provider ${JSON.stringify(redactSecretString(name))} ${retryOn429Error}`;
  }
  const retryOnResetError = retryOnResetPolicyConfigError(raw.retryOnReset);
  if (retryOnResetError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${retryOnResetError}`;
  }
  const requestPacingError = requestPacingConfigError(raw.requestPacing);
  if (requestPacingError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${requestPacingError}`;
  }
  const webSearchBridgeError = providerWebSearchBridgeConfigError(raw.webSearchBridge, name, typed);
  if (webSearchBridgeError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${webSearchBridgeError}`;
  }
  const upstreamHttpVersionError = upstreamHttpVersionConfigError(raw.upstreamHttpVersion);
  if (upstreamHttpVersionError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${upstreamHttpVersionError}`;
  }
  // Per-provider egress shares one definition with the transports and the config loader, so a
  // value the dashboard accepts is one a request can actually leave by. The message never
  // echoes the value: a proxy URL routinely embeds `user:password@`.
  const egressError = providerEgressConfigError(typed);
  if (egressError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${egressError}`;
  }
  const modelCostsError = providerModelCostsConfigError(raw.modelCosts);
  if (modelCostsError) {
    // The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
    // it before it reaches the management API response (same rule as retryOn429 above).
    return `provider ${JSON.stringify(redactSecretString(name))} ${modelCostsError}`;
  }
  const apiKeyTransportError = apiKeyTransportConfigError(typed);
  if (apiKeyTransportError) return `provider ${name} ${apiKeyTransportError}`;
  const projectContextError = projectContextConfigError(typed);
  if (projectContextError) return `provider ${JSON.stringify(redactSecretString(name))} ${projectContextError}`;
  const maxInputError = positiveIntegerRecordConfigError(raw.modelMaxInputTokens, "modelMaxInputTokens");
  if (maxInputError) return `provider ${name} ${maxInputError}`;
  const autoCompactError = modelAutoCompactTokenLimitsConfigError(
    raw.modelAutoCompactTokenLimits,
    { requireNativeIds: name === "openai" },
  );
  if (autoCompactError) {
    return `provider ${JSON.stringify(redactSecretString(name))} ${autoCompactError}`;
  }
  const reasoningSummariesError = booleanRecordConfigError(raw.modelSupportsReasoningSummaries, "modelSupportsReasoningSummaries");
  if (reasoningSummariesError) return `provider ${name} ${reasoningSummariesError}`;
  const suppressSyntheticMaxError = booleanRecordConfigError(raw.modelSuppressSyntheticMax, "modelSuppressSyntheticMax");
  if (suppressSyntheticMaxError) return `provider ${name} ${suppressSyntheticMaxError}`;
  const verbositySupportError = booleanRecordConfigError(raw.modelSupportsVerbosity, "modelSupportsVerbosity");
  if (verbositySupportError) return `provider ${name} ${verbositySupportError}`;
  const reasoningSummaryDeliveryError = reasoningSummaryDeliveryRecordConfigError(
    raw.modelReasoningSummaryDelivery,
    raw.modelSupportsReasoningSummaries,
  );
  if (reasoningSummaryDeliveryError) return `provider ${name} ${reasoningSummaryDeliveryError}`;
  const modelAdaptersError = modelAdapterRecordConfigError(raw.modelAdapters, "modelAdapters", name, typed);
  if (modelAdaptersError) return `provider ${name} ${modelAdaptersError}`;
  const preferHostedToolsError = modelPreferHostedToolsConfigError(
    raw.modelPreferHostedTools,
    "modelPreferHostedTools",
    name,
    typed,
  );
  if (preferHostedToolsError) return `provider ${name} ${preferHostedToolsError}`;
  if (raw.responsesSnapshotRepair !== undefined && typeof raw.responsesSnapshotRepair !== "boolean") {
    return `provider ${name} responsesSnapshotRepair must be a boolean`;
  }
  if (raw.xaiResponsesXSearch !== undefined && typeof raw.xaiResponsesXSearch !== "boolean") {
    return `provider ${name} xaiResponsesXSearch must be a boolean`;
  }
  const defaultMaxOutputError = positiveIntegerConfigError(raw.defaultMaxOutputTokens, "defaultMaxOutputTokens");
  if (defaultMaxOutputError) return `provider ${name} ${defaultMaxOutputError}`;
  const maxOutputError = positiveIntegerRecordConfigError(raw.modelMaxOutputTokens, "modelMaxOutputTokens");
  if (maxOutputError) return `provider ${name} ${maxOutputError}`;
  const structuredOutputOptOutError = nonBlankStringArrayConfigError(
    raw.noStructuredOutputModels,
    "noStructuredOutputModels",
  );
  if (structuredOutputOptOutError) return `provider ${name} ${structuredOutputOptOutError}`;
  const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
    raw.noJsonSchemaModels,
    "noJsonSchemaModels",
  );
  if (jsonSchemaOptOutError) return `provider ${name} ${jsonSchemaOptOutError}`;
  const retainModelsError = nonBlankStringArrayConfigError(raw.retainModels, "retainModels");
  if (retainModelsError) return `provider ${name} ${retainModelsError}`;
  const toolReasoningOptOutError = nonBlankStringArrayConfigError(
    raw.omitReasoningEffortWithToolsModels,
    "omitReasoningEffortWithToolsModels",
  );
  if (toolReasoningOptOutError) return `provider ${name} ${toolReasoningOptOutError}`;
  const unsupportedHostedToolsError = nonBlankStringArrayConfigError(
    raw.unsupportedHostedTools,
    "unsupportedHostedTools",
  );
  if (unsupportedHostedToolsError) return `provider ${name} ${unsupportedHostedToolsError}`;
  if (Array.isArray(raw.unsupportedHostedTools)) {
    // Closed vocabulary, same reason as the config schema: an unrecognized name would be
    // stored and then strip nothing, so the operator would keep getting the upstream 400
    // this field exists to prevent.
    const unknownTool = (raw.unsupportedHostedTools as unknown[])
      .find(tool => typeof tool === "string" && !DECLARABLE_HOSTED_TOOL_TYPES.has(tool.trim()));
    if (unknownTool !== undefined) {
      return `provider ${name} unsupportedHostedTools must name only hosted tool types: `
        + `${[...DECLARABLE_HOSTED_TOOL_TYPES].join(", ")}`;
    }
  }
  const openRouterError = openRouterRoutingConfigError(typed);
  if (openRouterError) return `provider ${name} ${openRouterError}`;
  const vercelError = vercelGatewayRoutingConfigError(typed);
  if (vercelError) return `provider ${name} ${vercelError}`;
  if (typed.authMode === "local") {
    // "local" bypasses key-requirement enforcement (api-keys/key-failover treat non-oauth/
    // forward as key auth; openai-chat skips credential checks for local). Only providers
    // whose registry entry is genuinely local (Ollama/vLLM/LM Studio) may claim it.
    const entry = getProviderRegistryEntry(name);
    if (entry && entry.authKind !== "local") {
      return `provider ${name} cannot use authMode "local" — its registry entry requires ${entry.authKind} auth`;
    }
  }
  if (typed.authMode === "forward") {
    const normalizedName = name.trim().toLowerCase();
    const base = typed.baseUrl.replace(/\/+$/, "");
    const isBuiltInChatGptForward = normalizedName === "openai"
      && typed.adapter === "openai-responses"
      && base === "https://chatgpt.com/backend-api/codex";
    if (isBuiltInChatGptForward) return null;
    return `provider ${name} uses reserved authMode "forward"; configure ChatGPT passthrough via the built-in provider`;
  }
  return null;
}

export function publicProviderBaseUrl(baseUrl: string): string {
  try {
    const parsed = new URL(baseUrl.trim());
    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "(invalid URL)";
    parsed.username = "";
    parsed.password = "";
    parsed.search = "";
    parsed.hash = "";
    return parsed.toString().replace(/\/$/, baseUrl.endsWith("/") ? "/" : "");
  } catch {
    return "(invalid URL)";
  }
}

export function copyIfDefined<K extends keyof OcxProviderConfig>(
  out: Record<string, unknown>,
  provider: OcxProviderConfig,
  key: K,
): void {
  const value = provider[key];
  if (value !== undefined) out[key as string] = value as unknown;
}

/**
 * Exhaustive provider-field policy shared by dashboard redaction and editor
 * admission. `satisfies Record<keyof OcxProviderConfig, ...>` makes a newly added
 * provider field fail typecheck until it is deliberately classified.
 *
 * `editor` fields are user-authored, `redacted` fields may contain credentials,
 * and `runtime` fields are observations/limits that must never become editor write
 * authority. MCP and desktop executor blocks are redacted as a whole because both
 * contain arbitrary environment variables and/or headers.
 */
type ProviderConfigFieldPolicy = "editor" | "redacted" | "runtime";

const PROVIDER_CONFIG_FIELD_POLICY = {
  alias: "editor",
  modelAliases: "editor",
  modelDisplayNames: "editor",
  defaultAliases: "editor",
  adapter: "editor",
  codexToolMode: "editor",
  projectContext: "editor",
  requestPacing: "editor",
  mcpMaxTools: "editor",
  mcpMaxSchemaBytes: "editor",
  mcpMaxResultBytes: "editor",
  modelAdapters: "editor",
  fastWire: "editor",
  responseTierAuthoritative: "editor",
  fastEnabled: "editor",
  baseUrl: "editor",
  responsesPath: "editor",
  chatCompletionsPath: "editor",
  commandCodeVersion: "editor",
  statelessResponses: "editor",
  requiresAdjacentResponsesToolResults: "editor",
  requiresPairedResponsesToolResults: "editor",
  annotateEmptyToolOutputs: "editor",
  supportsServiceTier: "editor",
  modelSupportsServiceTier: "editor",
  preserveResponsesReasoningContent: "editor",
  dropResponsesReasoningItems: "editor",
  modelReasoningEffortsAuthoritative: "editor",
  decodesNativeCompactionBlobs: "editor",
  allowEncryptedV2AgentTasks: "editor",
  allowPrivateNetwork: "editor",
  // A proxy URL routinely embeds `user:password@`, so it never reaches the dashboard DTO and
  // the editor may not write it. `ocx config set` and the config file remain the way to set
  // it, which is the same boundary `apiKey` sits behind and for the same reason.
  proxy: "redacted",
  // A bypass list names destinations, carries no credential, and is only meaningful next to a
  // route the operator can already see.
  noProxy: "editor",
  upstreamHttpVersion: "editor",
  upstreamWebsocket: "editor",
  directGeminiWireRenames: "editor",
  googleToolSchemaPolicy: "editor",
  disabled: "editor",
  codexAccountMode: "editor",
  apiKey: "redacted",
  apiKeyTransport: "editor",
  apiKeyPool: "redacted",
  // Ordering preference only; it names no key material, so an editor may read and set it.
  apiKeyPoolStrategy: "editor",
  apiKeySelectionRevision: "runtime",
  _apiKeyAttempt: "runtime",
  defaultModel: "editor",
  models: "editor",
  liveModels: "editor",
  selectedModels: "editor",
  initialModelSelection: "runtime",
  retainModels: "editor",
  newModelPolicy: "editor",
  modelPreset: "editor",
  contextWindow: "editor",
  modelContextWindows: "editor",
  modelContextTiers: "editor",
  modelInputModalities: "editor",
  modelCapabilities: "editor",
  modelMaxInputTokens: "runtime",
  modelAutoCompactTokenLimits: "editor",
  defaultMaxOutputTokens: "editor",
  modelMaxOutputTokens: "editor",
  modelCosts: "editor",
  headers: "redacted",
  openRouterRouting: "editor",
  modelOpenRouterRouting: "editor",
  vercelGatewayRouting: "editor",
  modelVercelGatewayRouting: "editor",
  authMode: "editor",
  oauthAccountFailover: "editor",
  keyOptional: "editor",
  freeTier: "editor",
  note: "editor",
  modelSuffixBracketStrip: "editor",
  refreshPolicy: "editor",
  reasoningEfforts: "editor",
  modelReasoningEfforts: "editor",
  modelSuppressSyntheticMax: "editor",
  modelDefaultReasoningEfforts: "editor",
  pinnedReasoningEffort: "editor",
  modelPinnedReasoningEfforts: "editor",
  autoReviewModel: "editor",
  autoReviewModelOverrides: "editor",
  modelSupportsReasoningSummaries: "editor",
  modelSupportsVerbosity: "editor",
  supportsVerbosity: "editor",
  modelReasoningSummaryDelivery: "editor",
  modelPreferHostedTools: "editor",
  supportsOpenAiWebSearchToolFields: "editor",
  xaiResponsesXSearch: "editor",
  xaiResponsesDefaultVersion: "runtime",
  zaiResponsesDefaultVersion: "runtime",
  supportsResponsesCustomTools: "editor",
  unsupportedHostedTools: "editor",
  responsesSnapshotRepair: "editor",
  webSearchBridge: "editor",
  reasoningEffortMap: "editor",
  modelReasoningEffortMap: "editor",
  reasoningWireFormat: "editor",
  noReasoningModels: "editor",
  noTemperatureModels: "editor",
  noTopPModels: "editor",
  noStopModels: "editor",
  noPenaltyModels: "editor",
  noStructuredOutputModels: "editor",
  noJsonSchemaModels: "editor",
  omitReasoningEffortWithToolsModels: "editor",
  parallelToolCalls: "editor",
  pinParallelToolCallsFalse: "editor",
  terminalContinuationGuard: "editor",
  openaiChatEofTolerance: "editor",
  foldDeveloperRoleToSystem: "editor",
  promptCacheKey: "editor",
  chatServiceTier: "editor",
  responsesItemIdRepair: "editor",
  autoToolChoiceOnlyModels: "editor",
  preserveReasoningContentModels: "editor",
  requiresReasoningPlaceholderModels: "editor",
  showThinkingSummary: "editor",
  hideRawReasoning: "editor",
  retryOn429: "editor",
  transientRetryOn5xx: "editor",
  retryOnReset: "editor",
  reasoningSplitModels: "editor",
  inlineThinkTagModels: "editor",
  reasoningDetailsModels: "editor",
  thinkingToggleModels: "editor",
  thinkingBudgetModels: "editor",
  escapeBuiltinToolNames: "editor",
  anthropicEofTolerance: "editor",
  noVisionModels: "editor",
  googleMode: "editor",
  project: "editor",
  location: "editor",
  mcpServers: "redacted",
  desktopExecutor: "redacted",
  unsafeAllowNativeLocalExec: "editor",
  nativeLocalExec: "editor",
} as const satisfies Record<keyof OcxProviderConfig, ProviderConfigFieldPolicy>;

type ProviderFieldWithPolicy<Policy extends ProviderConfigFieldPolicy> = {
  [Field in keyof typeof PROVIDER_CONFIG_FIELD_POLICY]:
    typeof PROVIDER_CONFIG_FIELD_POLICY[Field] extends Policy ? Field : never;
}[keyof typeof PROVIDER_CONFIG_FIELD_POLICY];

type RedactedProviderField = ProviderFieldWithPolicy<"redacted">;
type RuntimeProviderField = ProviderFieldWithPolicy<"runtime">;
export const REDACTED_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
  .filter(([, policy]) => policy === "redacted")
  .map(([field]) => field as RedactedProviderField));
const RUNTIME_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
  .filter(([, policy]) => policy === "runtime")
  .map(([field]) => field as RuntimeProviderField));

const PROVIDER_EDITOR_DERIVED_FIELDS = [
  ...RUNTIME_PROVIDER_FIELDS,
  ...FORBIDDEN_PROVIDER_RUNTIME_FIELDS,
  "fetch",
  "hasApiKey",
  "hasHeaders",
  "xaiResponsesOptInState",
] as const;

export const PROVIDER_EDITOR_DENIED_FIELDS = [
  ...REDACTED_PROVIDER_FIELDS,
  ...PROVIDER_EDITOR_DERIVED_FIELDS,
] as const;

export type ProviderEditorProviderDTO = Omit<OcxProviderConfig, RedactedProviderField | RuntimeProviderField>
  & Record<string, unknown>;

export interface ProviderEditorConfigDTO {
  defaultProvider: string;
  providers: Record<string, ProviderEditorProviderDTO>;
}

export type ProviderEditorConfigParseResult =
  | { ok: true; value: ProviderEditorConfigDTO }
  | { ok: false; error: string; code: "invalid_provider_editor_body" | "invalid_provider_editor_field" };

const PROVIDER_EDITOR_DENIED_FIELD_SET = new Set<string>(PROVIDER_EDITOR_DENIED_FIELDS);
const PROVIDER_CONFIG_FIELD_SET = new Set<string>(Object.keys(PROVIDER_CONFIG_FIELD_POLICY));

function isPlainDataRecord(value: unknown): value is Record<string, unknown> {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const prototype = Object.getPrototypeOf(value);
  return prototype === Object.prototype || prototype === null;
}

/**
 * Project one provider through the same redaction path used by both the public
 * config DTO and the raw editor. Persisted unknown fields remain on disk but are
 * not exposed until OcxProviderConfig classifies them as editor-safe.
 */
function providerEditorProviderDTO(name: string, provider: OcxProviderConfig): ProviderEditorProviderDTO {
  const dto = Object.fromEntries(Object.entries(provider)
    .filter(([field]) => PROVIDER_CONFIG_FIELD_SET.has(field) && !PROVIDER_EDITOR_DENIED_FIELD_SET.has(field))
    .map(([field, value]) => [field, structuredClone(value)])) as Record<string, unknown>;
  dto.baseUrl = publicProviderBaseUrl(provider.baseUrl);
  const modelCosts = sanitizeModelCostsForDisplay(provider.modelCosts);
  if (modelCosts) dto.modelCosts = modelCosts;
  else delete dto.modelCosts;

  const registryNote = (providerMatchesRegistryTransport(name, provider)
    ? getProviderRegistryEntry(name)
    : registryEntryForProviderDestination(provider))?.note;
  if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
  const codexAccountMode = providerCodexAccountMode(name, provider);
  if (codexAccountMode) dto.codexAccountMode = codexAccountMode;
  return dto as ProviderEditorProviderDTO;
}

/** The complete non-secret provider shape the raw GUI editor may round-trip. */
export function providerEditorConfigDTO(config: OcxConfig): ProviderEditorConfigDTO {
  const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
  for (const [name, provider] of Object.entries(config.providers)) {
    providers[name] = providerEditorProviderDTO(name, provider);
  }
  return { defaultProvider: config.defaultProvider, providers };
}

/** Parse an editor snapshot; unknown, redacted, and derived fields fail closed. */
export function parseProviderEditorConfigDTO(value: unknown): ProviderEditorConfigParseResult {
  if (!isPlainDataRecord(value)) {
    return { ok: false, error: "provider editor config must be a plain object", code: "invalid_provider_editor_body" };
  }
  const rootKeys = Object.keys(value);
  if (rootKeys.length !== 2 || !Object.hasOwn(value, "defaultProvider") || !Object.hasOwn(value, "providers")) {
    return { ok: false, error: "provider editor config must contain only defaultProvider and providers", code: "invalid_provider_editor_body" };
  }
  if (typeof value.defaultProvider !== "string" || value.defaultProvider.trim() === "") {
    return { ok: false, error: "defaultProvider must be a non-empty string", code: "invalid_provider_editor_body" };
  }
  if (!isPlainDataRecord(value.providers)) {
    return { ok: false, error: "providers must be a plain object", code: "invalid_provider_editor_body" };
  }

  const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
  for (const [name, provider] of Object.entries(value.providers)) {
    if (!isPlainDataRecord(provider)) {
      return { ok: false, error: `provider ${JSON.stringify(redactSecretString(name))} must be a plain object`, code: "invalid_provider_editor_body" };
    }
    const deniedField = Object.keys(provider).find(field =>
      !PROVIDER_CONFIG_FIELD_SET.has(field) || PROVIDER_EDITOR_DENIED_FIELD_SET.has(field));
    if (deniedField) {
      return {
        ok: false,
        error: `provider ${JSON.stringify(redactSecretString(name))} contains non-editable field ${JSON.stringify(redactSecretString(deniedField))}`,
        code: "invalid_provider_editor_field",
      };
    }
    providers[name] = structuredClone(provider) as ProviderEditorProviderDTO;
  }
  return {
    ok: true,
    value: { defaultProvider: value.defaultProvider, providers },
  };
}

/** Public dashboard DTO for config.json: provider entries with secrets stripped and documented fields exposed (including `modelCosts`). */
export function safeConfigDTO(config: OcxConfig): unknown {
  const editor = providerEditorConfigDTO(config);
  const providers: Record<string, Record<string, unknown>> = {};
  for (const [name, provider] of Object.entries(config.providers)) {
    const dto: Record<string, unknown> = {
      ...editor.providers[name],
      hasApiKey: !!provider.apiKey,
      hasHeaders: !!provider.headers && Object.keys(provider.headers).length > 0,
    };
    if (name === "xai") {
      dto.xaiResponsesOptInState = xaiResponsesOptInState(provider);
    }
    const selection = initialModelSelection(provider);
    if (selection) dto.initialModelSelection = selection;
    providers[name] = dto;
  }
  return {
    port: config.port,
    hostname: config.hostname ?? "127.0.0.1",
    defaultProvider: config.defaultProvider,
    defaultModelAliases: config.defaultModelAliases,
    codexAutoStart: codexAutoStartEnabled(config),
    websockets: config.websockets,
    // The GUI's browser-open toggle reads and writes this; absent means the
    // historical auto-open behavior.
    oauthOpenBrowser: config.oauthOpenBrowser !== false,
    showCodexCredits: config.showCodexCredits === true,
    providers,
  };
}
