UNPKG

@bitkyc08/opencodex

Version:

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

802 lines (754 loc) • 38 kB
import { createHash } from "node:crypto"; import { lstatSync, readFileSync } from "node:fs"; import { join } from "node:path"; import * as z from "zod/v4"; import { compactionRecoveryConfigError } from "./schema/compaction-recovery"; import { blockedModelRedirectsError } from "./schema/blocked-model-redirects"; import type { OcxConfig } from "../types"; import { parseAnthropicModelRoutes } from "../oauth/anthropic-model-routes"; import { configReasoningPinsConfigError } from "./provider-validation"; import { loopbackCompanionAllowed } from "../codex/loopback-target"; import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../codex/upstream-host-health"; import { MAX_APP_OWNED_MEMORY_BUDGET_MB, MIN_APP_OWNED_MEMORY_BUDGET_MB } from "../lib/app-owned-memory"; import { isMissingPathError } from "./atomic-write"; import { getConfigPath } from "./paths"; import { getDefaultConfig } from "./proxy-env"; import { salvageConfigCandidate } from "./salvage"; import { sanitizeReasoningPinsForLoad, sanitizeRetryOn429ForLoad, sanitizeCapabilityDeclarationsForLoad, sanitizeModelCostsForLoad, sanitizeAutoReviewForLoad, degradedListenerWarnings, degradedCodexAccountPriorityWarnings, degradedCodexQuotaAutoRefreshWarning, normalizeApiKeyIds, CLAUDE_SUBAGENT_EFFORTS, isClaudeSubagentEffort, rawClaudeSubagentEffort, normalizeClaudeSubagentEffort, malformedUpstreamHostCircuitThresholdWarning, malformedPlaintextV2AgentMessagesWarning, malformedAgentTaskRecoveryWarning, malformedRuntimeRoleWarning, malformedOptionalRemoteBlockWarning, malformedClientConnectionWarning, malformedQuotaResetNotifyWarning, malformedCatalogAutoRefreshWarning, malformedCodexPoolWarning, malformedSpendWarning, rawConfigRecord, malformedNativeSubagentFields, malformedNativeSubagentFieldWarning, malformedCodexAccountPickerWarning, nativeSubagentSyncDisabledReason, normalizeNativeSubagentSync, inheritedFastWireConflictProviderNames, inheritedFastWireConflictWarning, sanitizeModelDisplayNamesForLoad, } from "./load-degrade"; import { configSchema } from "./schema/config-schema"; import { agentTaskRecoverySchema, catalogAutoRefreshSchema, clientConnectionSchema, CODEX_ACCOUNT_PIN_PATTERN, codexAccountPrioritiesSchema, codexAccountAutoSwitchThresholdsSchema, codexPoolSchema, codexQuotaAutoRefreshSchema, credentialGroupsSchema, hubConfigSchema, quotaResetNotifySchema, remoteGuiConfigSchema, runtimeRoleSchema, spendSchema, compactionRoutingSchema, skillsConfigSchema, memoryModelsSchema, } from "./schema/leaf-validators"; export type ConfigDiagnostics = { config: OcxConfig; source: "default" | "file" | "fallback"; error: string | null; /** Non-fatal config concerns; absent when there are no warnings. */ warnings?: string[]; }; export type ConfigFileSnapshot = { diagnostics: ConfigDiagnostics; /** Exact file contents, including a possible BOM, used as the optimistic revision. */ raw?: string; }; function configPlaceholderWarnings(config: OcxConfig): string[] { const warnings: string[] = []; for (const [name, provider] of Object.entries(config.providers)) { const placeholder = provider.baseUrl.match(/\{[^}]*\}/)?.[0]; if (placeholder) { warnings.push(`providers.${name}.baseUrl contains unresolved ${placeholder}; set the real provider URL`); } } return warnings; } function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): ConfigDiagnostics { // Unsafe hand-edited optional values are disabled in memory instead of rejecting // the entire config, which would hide unrelated providers/accounts. The next // ordinary save persists the normalized absence. const syncDisabledReason = nativeSubagentSyncDisabledReason(config, rawParsed); const rawEffort = rawClaudeSubagentEffort(rawParsed); const normalized = normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, rawParsed), rawParsed); const warnings = configPlaceholderWarnings(normalized); warnings.push(...inheritedFastWireConflictProviderNames(normalized).map(inheritedFastWireConflictWarning)); warnings.push(...degradedCodexAccountPriorityWarnings(rawParsed, normalized)); warnings.push(...degradedListenerWarnings(rawParsed, normalized)); if (blockedModelRedirectsError(rawParsed)) warnings.push("blockedModelRedirects ignored: expected a map of nonempty model keys to nonempty string targets"); const quotaAutoRefreshWarning = degradedCodexQuotaAutoRefreshWarning(rawParsed, normalized); if (quotaAutoRefreshWarning) warnings.push(quotaAutoRefreshWarning); if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) { warnings.push(`claudeCode.subagentEffort ignored: expected one of ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}`); } warnings.push(...malformedNativeSubagentFields(rawParsed).map(malformedNativeSubagentFieldWarning)); const pickerWarning = malformedCodexAccountPickerWarning(rawParsed); if (pickerWarning) warnings.push(pickerWarning); const hostCircuitWarning = malformedUpstreamHostCircuitThresholdWarning(rawParsed); if (hostCircuitWarning) warnings.push(hostCircuitWarning); const recoveryWarning = malformedAgentTaskRecoveryWarning(rawParsed); if (recoveryWarning) warnings.push(recoveryWarning); const runtimeRoleWarning = malformedRuntimeRoleWarning(rawParsed); if (runtimeRoleWarning) warnings.push(runtimeRoleWarning); const hubWarning = malformedOptionalRemoteBlockWarning(rawParsed, "hub"); if (hubWarning) warnings.push(hubWarning); const remoteGuiWarning = malformedOptionalRemoteBlockWarning(rawParsed, "remoteGui"); if (remoteGuiWarning) warnings.push(remoteGuiWarning); const clientWarning = malformedClientConnectionWarning(rawParsed); if (clientWarning) warnings.push(clientWarning); const notifyWarning = malformedQuotaResetNotifyWarning(rawParsed); if (notifyWarning) warnings.push(notifyWarning); const catalogRefreshWarning = malformedCatalogAutoRefreshWarning(rawParsed); if (catalogRefreshWarning) warnings.push(catalogRefreshWarning); const codexPoolWarning = malformedCodexPoolWarning(rawParsed); if (codexPoolWarning) warnings.push(codexPoolWarning); const spendWarning = malformedSpendWarning(rawParsed); if (spendWarning) warnings.push(spendWarning); const plaintextWarning = malformedPlaintextV2AgentMessagesWarning(rawParsed); if (plaintextWarning) warnings.push(plaintextWarning); if (syncDisabledReason) { warnings.push(`syncCodexSubagentDefaults ignored: ${syncDisabledReason}`); } return { config: normalized, source: "file", error: null, ...(warnings.length > 0 ? { warnings } : {}), }; } export function subagentDefaultSyncEffective( config: Pick<OcxConfig, "syncCodexSubagentDefaults" | "injectionModel">, ): boolean { return config.syncCodexSubagentDefaults === true && Boolean(config.injectionModel?.trim()); } export function mergeConfigDefaults(parsed: unknown): unknown { if (!parsed || typeof parsed !== "object") return parsed; const defaults = getDefaultConfig(); const raw = parsed as Record<string, unknown>; // Same absence-is-meaningful pin as the repair merge above. const merged: Record<string, unknown> = { ...defaults, ...raw, subagentModelsVersion: raw.subagentModelsVersion, multiAgentMode: raw.multiAgentMode, multiAgentSurfaceAdvisoryVersion: raw.multiAgentSurfaceAdvisoryVersion, }; if (raw.providers && typeof raw.providers === "object" && defaults.providers) { merged.providers = { ...defaults.providers, ...(raw.providers as Record<string, unknown>) }; } return merged; } function schemaDiagnosticsError(error: z.ZodError): string { const details = error.issues.map(issue => { const path = issue.path.join(".") || "config"; return `${path}: ${issue.message}`; }); return details.length > 0 ? `schema_invalid: ${details.join("; ")}` : "schema_invalid"; } /** * Reject a hostname the schema deliberately degrades on read. Load-time has to keep a * blank value non-fatal (see the `hostname` field comment), but an incoming write is a * live caller who can be told the value is wrong — silently rewriting it to loopback * would look like the bind succeeded on the address they asked for. */ function blankHostnameError(value: unknown): string | null { if (!value || typeof value !== "object" || Array.isArray(value)) return null; const hostname = (value as Record<string, unknown>).hostname; if (hostname === undefined) return null; if (typeof hostname !== "string" || !hostname.trim()) { return "schema_invalid: hostname: must be a nonblank bind address"; } return null; } function claudeSubagentEffortError(value: unknown): string | null { const effort = rawClaudeSubagentEffort(value); if (effort === undefined || isClaudeSubagentEffort(effort)) return null; return `schema_invalid: claudeCode.subagentEffort: must be one of ${CLAUDE_SUBAGENT_EFFORTS.join(", ")}`; } function appOwnedMemoryBudgetError(value: unknown): string | null { if (!value || typeof value !== "object" || Array.isArray(value)) return null; const budget = (value as Record<string, unknown>).appOwnedMemoryBudgetMb; if (budget === undefined) return null; if (typeof budget !== "number" || !Number.isInteger(budget) || budget < MIN_APP_OWNED_MEMORY_BUDGET_MB || budget > MAX_APP_OWNED_MEMORY_BUDGET_MB) { return `schema_invalid: appOwnedMemoryBudgetMb: must be an integer from ${MIN_APP_OWNED_MEMORY_BUDGET_MB} to ${MAX_APP_OWNED_MEMORY_BUDGET_MB}`; } return null; } function upstreamHostCircuitThresholdError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "upstreamHostCircuitThreshold")) return null; const threshold = raw.upstreamHostCircuitThreshold; if (threshold === undefined) return null; if (typeof threshold === "number" && Number.isInteger(threshold) && threshold >= 0 && threshold <= UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD) return null; return `schema_invalid: upstreamHostCircuitThreshold: must be an integer from 0 to ${UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD}`; } function plaintextV2AgentMessagesError(value: unknown): string | null { return malformedPlaintextV2AgentMessagesWarning(value) ? "schema_invalid: plaintextV2AgentMessages: must be a boolean or omitted" : null; } function agentTaskRecoveryError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "agentTaskRecovery") || raw.agentTaskRecovery === undefined) return null; const result = agentTaskRecoverySchema.safeParse(raw.agentTaskRecovery); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: agentTaskRecovery${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } function runtimeRoleError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "runtimeRole") || raw.runtimeRole === undefined) return null; if (runtimeRoleSchema.safeParse(raw.runtimeRole).success) return null; return 'schema_invalid: runtimeRole: must be one of "standalone", "hub", or "client"'; } function remoteGuiConfigError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw) return null; for (const [key, schema] of [ ["hub", hubConfigSchema], ["remoteGui", remoteGuiConfigSchema], ] as const) { if (!Object.hasOwn(raw, key) || raw[key] === undefined) continue; const result = schema.safeParse(raw[key]); if (result.success) continue; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: ${key}${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } return null; } function clientConnectionConfigError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "client") || raw.client === undefined) return null; const result = clientConnectionSchema.safeParse(raw.client); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: client${field ? `.${field}` : ""}: ${issue?.message ?? "invalid client connection"}`; } function clientRolePairError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw) return null; const hasClient = Object.hasOwn(raw, "client") && raw.client !== undefined; if (raw.runtimeRole === "client" && !hasClient) { return "schema_invalid: runtimeRole client requires a complete client connection"; } if (hasClient && raw.runtimeRole !== "client") { return "schema_invalid: client connection requires runtimeRole client"; } return null; } function quotaResetNotifyError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "quotaResetNotify") || raw.quotaResetNotify === undefined) return null; const result = quotaResetNotifySchema.safeParse(raw.quotaResetNotify); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: quotaResetNotify${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } function catalogAutoRefreshError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "catalogAutoRefresh") || raw.catalogAutoRefresh === undefined) return null; const result = catalogAutoRefreshSchema.safeParse(raw.catalogAutoRefresh); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: catalogAutoRefresh${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } /** * The read path degrades a malformed spend section to undefined, which means no ceiling is * enforced. Reject it on write so `ocx config set` cannot store a budget that reads back as * configured and refuses nothing -- a ceiling that is not enforced looks identical to one * nothing has reached. */ function spendError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "spend") || raw.spend === undefined) return null; const result = spendSchema.safeParse(raw.spend); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: spend${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } /** * The read path degrades a malformed pool policy to undefined, which for an exclusion policy means * the excluded accounts quietly keep serving traffic. Reject it on write so `ocx config set` cannot * create a policy that looks applied and is not. */ function codexPoolError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "codexPool") || raw.codexPool === undefined) return null; const result = codexPoolSchema.safeParse(raw.codexPool); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return `schema_invalid: codexPool${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`; } /** * Same reasoning as {@link blankHostnameError}, and more urgent: the read path degrades a * malformed selection-order map to undefined, which on a write would drop every entry the * user had accumulated and still report success. A load-time degrade leaves the raw map in * the file to be repaired by hand; a degraded write erases it. One bad `ocx config set` * must not cost the whole map, so a live caller is told instead. */ function codexAccountPrioritiesError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw) return null; if (raw.codexAccountPriorities !== undefined) { const parsed = codexAccountPrioritiesSchema.safeParse(raw.codexAccountPriorities); if (!parsed.success) { return schemaDiagnosticsError(parsed.error).replace("schema_invalid: ", "schema_invalid: codexAccountPriorities."); } } if (raw.codexAccountAutoSwitchThresholds !== undefined) { const parsed = codexAccountAutoSwitchThresholdsSchema.safeParse(raw.codexAccountAutoSwitchThresholds); if (!parsed.success) { return schemaDiagnosticsError(parsed.error) .replace("schema_invalid: ", "schema_invalid: codexAccountAutoSwitchThresholds."); } } // Tested as a string rather than coerced: `String(123)` matches the id pattern, so a // coercing guard waves a non-string pin through to the schema, where `.catch(undefined)` // drops it and reports the write as a success — the exact silent-degrade this guards. const pin = raw.activeCodexAccountPinned; if (pin !== undefined && (typeof pin !== "string" || !CODEX_ACCOUNT_PIN_PATTERN.test(pin))) { return "schema_invalid: activeCodexAccountPinned: must be an account id"; } return null; } function codexAccountPriorityFailbackError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "codexAccountPriorityFailback")) return null; const enabled = raw.codexAccountPriorityFailback; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: codexAccountPriorityFailback: must be a boolean or omitted"; } /** * Same reasoning as {@link codexAccountPrioritiesError}, plus one of its own. The read * path drops an invalid grouping, so a degraded write would erase a declaration the * operator is still editing and still report success. And an ambiguous declaration -- * one id used twice, one credential in two groups -- has no safe silent answer at all: * resolving it by list order would quietly merge two quota domains. A live caller is * told which group is the problem instead. */ export function poolCredentialGroupsError(value: unknown): string | null { const pool = rawConfigRecord(rawConfigRecord(value)?.pool); if (!pool || pool.credentialGroups === undefined) return null; const parsed = credentialGroupsSchema.safeParse(pool.credentialGroups); if (parsed.success) return null; const details = parsed.error.issues.map(issue => { const path = issue.path.join("."); return path ? `${path}: ${issue.message}` : issue.message; }).join("; "); return `schema_invalid: pool.credentialGroups: ${details}`; } function codexQuotaAutoRefreshError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || raw.codexQuotaAutoRefresh === undefined) return null; const parsed = codexQuotaAutoRefreshSchema.safeParse(raw.codexQuotaAutoRefresh); if (parsed.success) return null; const details = parsed.error.issues.map(issue => { const path = issue.path.join("."); const message = path === "" ? issue.message.replace(/^codexQuotaAutoRefresh\s*/, "") : issue.message; return `codexQuotaAutoRefresh${path ? `.${path}` : ""}: ${message}`; }); return `schema_invalid: ${details.join("; ")}`; } function googleAntigravityStaticCatalogVersionError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "googleAntigravityStaticCatalogVersion")) return null; const version = raw.googleAntigravityStaticCatalogVersion; if (version === undefined || version === 1 || version === 2) return null; return "schema_invalid: googleAntigravityStaticCatalogVersion: must be 1, 2, or omitted"; } function codexAccountPickerEnabledError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw) return null; const descriptor = Object.getOwnPropertyDescriptor(raw, "codexAccountPickerEnabled"); if (!descriptor) { return "codexAccountPickerEnabled" in raw ? "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted" : null; } if (!("value" in descriptor)) { return "schema_invalid: codexAccountPickerEnabled: must be an own boolean data property or omitted"; } const enabled = descriptor.value; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: codexAccountPickerEnabled: must be a boolean or omitted"; } function emptyCompletionRetryError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "emptyCompletionRetry")) return null; const enabled = raw.emptyCompletionRetry; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: emptyCompletionRetry: must be a boolean or omitted"; } function dropCodexSafetyBufferingError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "dropCodexSafetyBuffering")) return null; const enabled = raw.dropCodexSafetyBuffering; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: dropCodexSafetyBuffering: must be a boolean or omitted"; } function showCodexCreditsError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "showCodexCredits")) return null; const enabled = raw.showCodexCredits; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: showCodexCredits: must be a boolean or omitted"; } function oauthOpenBrowserError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "oauthOpenBrowser")) return null; const enabled = raw.oauthOpenBrowser; if (enabled === undefined || typeof enabled === "boolean") return null; return "schema_invalid: oauthOpenBrowser: must be a boolean or omitted"; } /** Validate an in-memory config candidate without touching disk. Used by headless CLI import/set. */ /** * Reject a loopback-listener port that collides with the proxy port (#1102), and a port-less * companion listener on a bind address that already owns 127.0.0.1 (#4236). * * The schema can only check the shape of each field on its own; the two ports being distinct — * and the port-less form being compatible with `hostname` — are relationships between fields. * Letting either through would surface as a startup failure after the public listener already * bound, which reads like an unrelated port conflict. * * Both keys are read from the same candidate, so `ocx config set hostname 127.0.0.1` on a host * whose listener is already the companion form is refused by this same check, with the same * message, rather than breaking the next start. * * This is write-time only, matching `blankHostnameError`: a live caller can be told the value * is wrong, whereas a hand-edited config on the read path degrades to undefined rather than * resetting the whole file. `assertLoopbackListenerBindable` repeats the decision at startup so * a hand edit that skipped this boundary fails with the same sentence instead of EADDRINUSE. */ function loopbackListenerPortError(value: unknown): string | null { if (!value || typeof value !== "object" || Array.isArray(value)) return null; const listener = (value as Record<string, unknown>).unauthenticatedLoopbackListener; if (listener === undefined) return null; if (!listener || typeof listener !== "object" || Array.isArray(listener)) { return "schema_invalid: unauthenticatedLoopbackListener: must be an object or omitted"; } const entry = listener as Record<string, unknown>; // `enabled` must be a real boolean. The schema's `.catch(undefined)` would otherwise DELETE // a `"true"` string entry and report success, leaving an operator convinced they enabled an // unauthenticated listener that is in fact off. Load-time still degrades quietly — a hand // edit must not reset the file — but a live caller gets told. if (typeof entry.enabled !== "boolean") { return "schema_invalid: unauthenticatedLoopbackListener.enabled: must be a boolean"; } if (entry.enabled !== true) return null; const hostname = typeof (value as Record<string, unknown>).hostname === "string" ? (value as Record<string, unknown>).hostname as string : undefined; const proxyPort = (value as Record<string, unknown>).port; const listenerPort = entry.port; // The companion form. `port` omitted means "same port as the public listener, on 127.0.0.1", // which only exists as a free address when the public listener is bound somewhere else. if (listenerPort === undefined) { return loopbackCompanionBindError( hostname, typeof proxyPort === "number" ? proxyPort : 10100, ); } if (typeof listenerPort !== "number" || !Number.isInteger(listenerPort) || listenerPort < 1 || listenerPort > 65535) { return "schema_invalid: unauthenticatedLoopbackListener.port: must be an integer port when enabled, or omitted to share the proxy port"; } if (typeof proxyPort === "number" && proxyPort === listenerPort) { return "schema_invalid: unauthenticatedLoopbackListener.port: must differ from the proxy port"; } return null; } /** * The one sentence both the write boundary and startup use for an impossible companion bind. * * Exported so `startServer` can fail with the identical text: an operator who hand-edited the * file past `validateConfigCandidate` must read the same diagnosis, not EADDRINUSE. */ export function loopbackCompanionBindError( hostname: string | undefined, proxyPort: number, ): string | null { if (loopbackCompanionAllowed(hostname)) return null; const bind = (hostname ?? "").trim() || "127.0.0.1"; return "schema_invalid: unauthenticatedLoopbackListener: a port-less listener binds " + `127.0.0.1:${proxyPort}, which the public listener on hostname "${bind}" already holds. ` + "Either set a distinct unauthenticatedLoopbackListener.port, or remove the listener — a " + "loopback bind already admits local callers without a credential."; } /** * Validate the hub management ingress at the live-write boundary. * * The persisted schema intentionally degrades a malformed hand edit to disabled so a typo in * this opt-in listener cannot discard providers or credentials. A live config mutation must not * get that leniency: it receives an exact field error before the degrading schema is applied. */ function managementIngressConfigError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw) return null; const hub = rawConfigRecord(raw.hub); if (!hub || !Object.hasOwn(hub, "managementIngress") || hub.managementIngress === undefined) return null; const ingress = rawConfigRecord(hub.managementIngress); if (!ingress) { return "schema_invalid: hub.managementIngress: must be an object or omitted"; } if (typeof ingress.enabled !== "boolean") { return "schema_invalid: hub.managementIngress.enabled: must be a boolean"; } const keys = Object.keys(ingress); if (ingress.enabled === false) { return keys.length === 1 ? null : "schema_invalid: hub.managementIngress: disabled ingress accepts only enabled"; } if (keys.some(key => key !== "enabled" && key !== "port")) { return "schema_invalid: hub.managementIngress: contains an unsupported field"; } const ingressPort = ingress.port; if (typeof ingressPort !== "number" || !Number.isInteger(ingressPort) || ingressPort < 1 || ingressPort > 65535) { return "schema_invalid: hub.managementIngress.port: must be an integer port when enabled"; } if (raw.runtimeRole !== "hub") { return "schema_invalid: hub.managementIngress: enabled ingress requires runtimeRole hub"; } const proxyPort = typeof raw.port === "number" ? raw.port : 10100; if (proxyPort === ingressPort) { return "schema_invalid: hub.managementIngress.port: must differ from the proxy port"; } const loopback = rawConfigRecord(raw.unauthenticatedLoopbackListener); if (loopback?.enabled === true && loopback.port === ingressPort) { return "schema_invalid: hub.managementIngress.port: must differ from unauthenticatedLoopbackListener.port"; } return null; } /** Load degrades malformed metrics export config to off; live writes reject the same shape. */ export function metricsExportConfigError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "metricsExport") || raw.metricsExport === undefined) return null; const metricsExport = rawConfigRecord(raw.metricsExport); if (!metricsExport) return "schema_invalid: metricsExport: must be an object or omitted"; if (Object.keys(metricsExport).some(key => key !== "enabled")) { return "schema_invalid: metricsExport: contains an unsupported field"; } if (metricsExport.enabled !== undefined && typeof metricsExport.enabled !== "boolean") { return "schema_invalid: metricsExport.enabled: must be a boolean"; } return null; } function skillsConfigError(value: unknown): string | null { const raw = rawConfigRecord(value); if (!raw || !Object.hasOwn(raw, "skills") || raw.skills === undefined) return null; const result = skillsConfigSchema.safeParse(raw.skills); if (result.success) return null; const issue = result.error.issues[0]; const field = issue?.path.join("."); return "schema_invalid: skills" + (field ? "." + field : "") + ": " + (issue?.message ?? "invalid configuration"); } export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } { const compactionRouting = rawConfigRecord(value)?.compactionRouting; if (compactionRouting !== undefined && !compactionRoutingSchema.safeParse(compactionRouting).success) { return { ok: false, error: "schema_invalid: compactionRouting: requires a nonblank model, an optional valid reasoningEffort, and optional non-repeating triggers drawn from \"manual\" and \"auto\"" }; } const memoryModels = rawConfigRecord(value)?.memoryModels; if (memoryModels !== undefined && !memoryModelsSchema.safeParse(memoryModels).success) { return { ok: false, error: "schema_invalid: memoryModels: requires a nonblank model and an optional declared reasoningEffort per configured phase, and no other fields" }; } const routeValue = (rawConfigRecord(value)?.anthropicAccountPool as Record<string, unknown> | undefined)?.routes; if (routeValue !== undefined) { const parsed = parseAnthropicModelRoutes(routeValue); if (!parsed.ok) return { ok: false, error: `schema_invalid: anthropicAccountPool.routes: ${parsed.error}` }; } const boundaryError = blockedModelRedirectsError(value) ?? compactionRecoveryConfigError(value) ?? configReasoningPinsConfigError(value) ?? blankHostnameError(value) ?? claudeSubagentEffortError(value) ?? appOwnedMemoryBudgetError(value) ?? upstreamHostCircuitThresholdError(value) ?? plaintextV2AgentMessagesError(value) ?? agentTaskRecoveryError(value) ?? quotaResetNotifyError(value) ?? catalogAutoRefreshError(value) ?? spendError(value) ?? codexPoolError(value) ?? googleAntigravityStaticCatalogVersionError(value) ?? codexAccountPrioritiesError(value) ?? codexAccountPriorityFailbackError(value) ?? poolCredentialGroupsError(value) ?? codexQuotaAutoRefreshError(value) ?? codexAccountPickerEnabledError(value) ?? emptyCompletionRetryError(value) ?? dropCodexSafetyBufferingError(value) ?? oauthOpenBrowserError(value) ?? showCodexCreditsError(value) ?? runtimeRoleError(value) ?? remoteGuiConfigError(value) ?? clientConnectionConfigError(value) ?? clientRolePairError(value) ?? loopbackListenerPortError(value) ?? managementIngressConfigError(value) ?? metricsExportConfigError(value) ?? skillsConfigError(value); if (boundaryError) return { ok: false, error: boundaryError }; const result = configSchema.safeParse(value); if (result.success) { const config = normalizeApiKeyIds(result.data as OcxConfig); return { ok: true, config }; } return { ok: false, error: schemaDiagnosticsError(result.error) }; } export function configDiagnosticsFromRaw(raw: string): ConfigDiagnostics { try { const parsed = JSON.parse(raw.replace(/^\uFEFF/, "")); sanitizeReasoningPinsForLoad(parsed); // Same degradation as loadConfig: a hand-edited invalid retryOn429 must not trip the // schema and send the caller a default-config fallback (the config command could then // persist that fallback over the user's providers/keys). sanitizeModelDisplayNamesForLoad(parsed); sanitizeAutoReviewForLoad(parsed); sanitizeRetryOn429ForLoad(parsed); sanitizeModelCostsForLoad(parsed); sanitizeCapabilityDeclarationsForLoad(parsed); const result = configSchema.safeParse(parsed); if (result.success) { return validFileConfigDiagnostics(normalizeApiKeyIds(result.data as OcxConfig), parsed); } const merged = mergeConfigDefaults(parsed); const retryResult = configSchema.safeParse(merged); if (retryResult.success) { return validFileConfigDiagnostics(normalizeApiKeyIds(retryResult.data as OcxConfig), parsed); } // #1785: one invalid routing profile must not make diagnostics report the built-in // defaults AS the config, because a later config write persists those defaults over the // operator's providers, keys and prices. // // The failure is still reported. `source` stays "fallback" and `error` keeps the real // schema message -- diagnostics is the surface that tells callers the file is invalid, // and every consumer that must refuse an invalid config (provider reload, catalog sync, // cost reconcile, codex admission) gates on exactly those two fields. Only `config` // changes: it carries the salvaged document instead of factory defaults, so a caller // that ignores the error and writes it back preserves what the operator configured. const salvaged = salvageConfigCandidate(merged, retryResult.error); if (salvaged) { const config = normalizeApiKeyIds(salvaged.parsed); const warnings = degradedListenerWarnings(parsed, config); return { config, source: "fallback", error: schemaDiagnosticsError(result.error), ...(warnings.length > 0 ? { warnings } : {}), }; } return { config: getDefaultConfig(), source: "fallback", error: schemaDiagnosticsError(result.error) }; } catch { return { config: getDefaultConfig(), source: "fallback", error: "invalid_json" }; } } export function readConfigFileSnapshot(): ConfigFileSnapshot { try { const raw = readFileSync(getConfigPath(), "utf-8"); return { diagnostics: configDiagnosticsFromRaw(raw), raw }; } catch (error) { if (isMissingPathError(error)) { return { diagnostics: { config: getDefaultConfig(), source: "default", error: null }, }; } return { diagnostics: { config: getDefaultConfig(), source: "fallback", error: "invalid_json" }, }; } } export function readConfigDiagnostics(): ConfigDiagnostics { return readConfigFileSnapshot().diagnostics; } /** Read-only init preflight. Occupied unsafe entries are never treated as absence. */ export function observeInitialConfigState(): "missing" | "exists" | "invalid" { try { if (!lstatSync(getConfigPath()).isFile()) return "invalid"; } catch (error) { return isMissingPathError(error) ? "missing" : "invalid"; } return readConfigFileSnapshot().diagnostics.source === "file" ? "exists" : "invalid"; } /** * The persisted config, plus a digest of the EXACT bytes it was parsed from. * * A union rather than a nullable digest, because `{ kind: "read" }` with no * digest is a state that cannot occur — and a state that cannot occur should * not be a state that can be written down. Refusing it at runtime is a check * somebody eventually forgets; making it unrepresentable is not. * * Why a byte digest at all: the Codex write lock compares an authority snapshot * taken before the lock against one taken while holding it, and its config * component used to hash the PARSED object. Two files that differ only in * whitespace or key order parse identically, so a non-cooperating writer could * rewrite the file between admission and commit and the comparison would see * nothing. Hashing what was actually read closes that. * * `readConfigFileSnapshot` stays private on purpose. Its `raw` carries provider * API keys and admission tokens, and `privacy:scan` reads tracked source text, * not runtime values — so it would not catch a caller that logged or serialized * that string. The digest travels; the bytes do not. */ export type ConfigAdmissionSnapshot = | Readonly<{ kind: "read"; diagnostics: ConfigDiagnostics; contentSha256: string }> | Readonly<{ kind: "unreadable"; diagnostics: ConfigDiagnostics; contentSha256: null }>; export function readConfigAdmissionSnapshot(): ConfigAdmissionSnapshot { let bytes: Buffer; try { // ONE read. Hashing the file and then reading it again to parse would leave // a window for the two to disagree, which is the exact hazard this exists // to detect — the check would become a second chance to be wrong. bytes = readFileSync(getConfigPath()); } catch (error) { return { kind: "unreadable", diagnostics: isMissingPathError(error) ? { config: getDefaultConfig(), source: "default", error: null } : { config: getDefaultConfig(), source: "fallback", error: "invalid_json" }, contentSha256: null, }; } return { kind: "read", // Decoded from the same buffer that was hashed, not re-read from disk. diagnostics: configDiagnosticsFromRaw(bytes.toString("utf-8")), contentSha256: createHash("sha256").update(bytes).digest("hex"), }; }