UNPKG

@bitkyc08/opencodex

Version:

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

603 lines (566 loc) • 26.6 kB
import { extractWorkBuddyModels } from "./workbuddy-models"; import type { OcxProviderConfig } from "../types"; import { providerSkipsInvalidModelRows } from "./model-discovery-config"; import { isValidModelDiscoveryModelId, MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH, MODEL_DISCOVERY_MAX_MODELS, MODEL_DISCOVERY_MAX_RESPONSE_BYTES, } from "./model-discovery-limits"; export { isValidModelDiscoveryModelId, MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH, MODEL_DISCOVERY_MAX_MODELS, MODEL_DISCOVERY_MAX_RESPONSE_BYTES, } from "./model-discovery-limits"; import { getProviderRegistryEntry, providerMatchesRegistryTransport, registryEntryForProviderDestination, type ProviderModelDiscoveryFilter, type ProviderModelDiscoveryPredicate, type ProviderModelDiscoveryScalar, type ProviderModelDiscoverySpec, } from "./registry"; const MODEL_DISCOVERY_MAX_FILTER_VALUES = 256; const MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH = 1_024; const TRAILING_SLASHES = /\/+$/; const TRAILING_MODELS = /\/models$/; export interface ResolvedProviderModelDiscovery { spec?: ProviderModelDiscoverySpec; maxResponseBytes: number; maxModels: number; /** Operator opt-in `providers.<name>.modelDiscovery.skipInvalidRows` (#7910); absent means strict. */ skipInvalidRows?: true; } export type ProviderModelsApiItem = Record<string, unknown> & { id: string }; export type ModelDiscoveryResponseFailure = | "response_too_large" | "invalid_json" | "invalid_shape" | "too_many_models"; export type BoundedDiscoveryJsonResult = | { ok: true; value: unknown } | { ok: false; reason: "response_too_large" | "invalid_json" }; export type ProviderModelItemsResult = | { ok: true; items: ProviderModelsApiItem[]; rawCount: number; skippedInvalidRows?: number } | { ok: false; reason: "invalid_shape" | "too_many_models"; diagnostic?: string }; export type ModelEnvelopeRowsResult = | { ok: true; rows: unknown[] } | { ok: false; reason: "invalid_shape" | "too_many_models" }; /** * Build the default OpenAI-compatible model-discovery URL from a configured baseUrl. * * `baseUrl` is required on both `OcxProviderConfig` and the persisted-config schema, so a row * without one is not a state configuration loading can produce. It is deliberately not tolerated * here: the old template-literal join silently produced `"undefined/models"`, which is not a usable * fallback either — it only ever survived because a static row returns before the URL is parsed. */ export function providerModelsUrl(baseUrl: string): string { const trimmed = baseUrl.trim().replace(TRAILING_SLASHES, ""); const withoutEndpoint = trimmed.replace(TRAILING_MODELS, ""); return `${withoutEndpoint}/models`; } function positiveIntegerAtMost(value: number | undefined, hardLimit: number): number { if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return hardLimit; return Math.min(Math.floor(value), hardLimit); } function discoveryPredicateError(predicate: ProviderModelDiscoveryPredicate): string | null { if (!Array.isArray(predicate.path) || predicate.path.length === 0 || predicate.path.length > 8) { return "predicate path must contain 1-8 segments"; } if (predicate.path.some(segment => typeof segment !== "string" || !segment.trim() || segment.length > 64)) { return "predicate path segments must be nonblank strings up to 64 characters"; } // One projection is sufficient for providers[].id and avoids combinatorial traversal. if (predicate.path.filter(segment => segment === "*").length > 1) return "predicate path may contain at most one array projection"; const values = "equalsAny" in predicate ? predicate.equalsAny : "containsAny" in predicate ? predicate.containsAny : predicate.containsAll; if (!Array.isArray(values) || values.length === 0 || values.length > 32) { return "predicate values must contain 1-32 scalars"; } if (values.some(value => ( (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") || (typeof value === "string" && (!value.trim() || value.length > 128)) || (typeof value === "number" && !Number.isFinite(value)) ))) { return "predicate values must be finite booleans/numbers or nonblank strings up to 128 characters"; } return null; } /** Static registry validation used by parity tests; discovery metadata never comes from config. */ export function providerModelDiscoverySpecError(spec: ProviderModelDiscoverySpec): string | null { if (spec.url && spec.path) return "url and path are mutually exclusive"; if (spec.url !== undefined) { try { const parsed = new URL(spec.url); if (parsed.protocol !== "https:") return "absolute discovery url must use https"; if (parsed.username || parsed.password || parsed.hash) return "absolute discovery url must not contain credentials or a fragment"; } catch { return "absolute discovery url must be valid"; } } if (spec.path !== undefined) { const path = spec.path.trim(); if (!path || path.length > 512) return "discovery path must be 1-512 characters"; if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//") || path.includes("?") || path.includes("#")) { return "discovery path must be a query-free relative/origin path"; } if (path.includes("\\")) return "discovery path must use forward slashes"; const segments = path.split("/"); if (segments.some((segment, index) => { const decoded = segment.replace(/%2e/gi, "."); if (decoded !== "..") return false; return index !== 0 || segments.filter(s => s.replace(/%2e/gi, ".") === "..").length !== 1; })) { return "discovery path must not contain parent-directory segments"; } } const queryEntries = Object.entries(spec.query ?? {}); if (queryEntries.length > 32) return "discovery query may contain at most 32 entries"; if (queryEntries.some(([key, value]) => !key.trim() || key.length > 128 || typeof value !== "string" || value.length > 512)) { return "discovery query keys/values exceed their bounds"; } for (const [field, value] of [ ["envelopeKey", spec.envelopeKey], ["idField", spec.idField], ] as const) { if (value !== undefined && ( typeof value !== "string" || !value || value !== value.trim() || value.length > 128 )) return `${field} must be a nonblank field name up to 128 characters`; } for (const [field, value, hardLimit] of [ ["maxResponseBytes", spec.maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES], ["maxModels", spec.maxModels, MODEL_DISCOVERY_MAX_MODELS], ] as const) { if (value !== undefined && (!Number.isInteger(value) || value <= 0 || value > hardLimit)) { return `${field} must be a positive integer no greater than ${hardLimit}`; } } for (const [group, predicates] of Object.entries({ ...spec.filter, ...(spec.preferFirst === undefined ? {} : { preferFirst: spec.preferFirst }) })) { if (!Array.isArray(predicates) || predicates.length === 0 || predicates.length > 32) { return `${group} must contain 1-32 predicates`; } for (const predicate of predicates) { const error = discoveryPredicateError(predicate); if (error) return `${group}: ${error}`; } } return null; } export function resolveProviderModelDiscovery( providerName: string, provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode" | "modelDiscovery">>, ): ResolvedProviderModelDiscovery { // The dashboard permits a canonical preset to be saved under a different name. Recover its // registry-owned discovery policy by transport in that case. The destination helper is limited // to exact fixed-key baseUrl + adapter matches, so custom endpoints, OAuth rows, templates, and // overridable destinations cannot acquire another provider's discovery URL or filter. const namedEntry = getProviderRegistryEntry(providerName); const entry = namedEntry ? (providerMatchesRegistryTransport(providerName, provider) ? namedEntry : undefined) : registryEntryForProviderDestination(provider); const spec = entry?.modelDiscovery; return { ...(spec ? { spec } : {}), maxResponseBytes: positiveIntegerAtMost(spec?.maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES), maxModels: positiveIntegerAtMost(spec?.maxModels, MODEL_DISCOVERY_MAX_MODELS), // Operator configuration, never registry policy: the registry cannot relax row validation. ...(providerSkipsInvalidModelRows(provider) ? { skipInvalidRows: true as const } : {}), }; } function appendDiscoveryQuery(url: URL, query: Readonly<Record<string, string>> | undefined): URL { for (const [key, value] of Object.entries(query ?? {})) url.searchParams.set(key, value); return url; } /** * Whether a model-discovery request URL is a registry-owned fixed discovery * URL — the canonical-URL proof for the transparent fake-IP (Clash/Surge/ * Mihomo TUN) exception in provider-outbound. * * The proof is on the FINAL URL, not the provider name: an OAuth/forward name * matches any baseUrl by design (`providerMatchesRegistryTransport` returns * true regardless of destination), while the bearer is pinned to the registry * destination independently in `buildModelsRequest`. Comparing the fetched URL * against registry spec URLs keeps a renamed custom row fetching an * attacker-controlled URL from gaining the exception. * * Both spec shapes are covered: an absolute `url` spec matches its own URL * (plus the spec's fixed query), and a `path` spec matches the URL it resolves * to against the registry's own baseUrl (plus the spec's fixed query) — so the * `commandcode` key preset's `path: "models"` proves the same * `https://api.commandcode.ai/provider/v1/models` string the `command-code` * OAuth `url` spec proves, and the `nebius` `path: "models"` plus * `query: { verbose: "true" }` proves * `https://api.tokenfactory.nebius.com/v1/models?verbose=true`. * * Registry-owned fixed query parameters are canonical only on EXACT match: * a missing, changed, or additional parameter is not canonical, so `?token=` * smuggling on the right origin+path stays rejected. Fragments are never * canonical. */ export function isRegistryModelDiscoveryUrl(providerName: string, url: string): boolean { const entry = getProviderRegistryEntry(providerName); const spec = entry?.modelDiscovery; if (!spec) return false; let candidate: URL; try { candidate = new URL(url); } catch { return false; } if (candidate.protocol !== "https:") return false; if (candidate.username || candidate.password) return false; if (candidate.hash) return false; const sameUrl = (canonical: string): boolean => { let expected: URL; try { expected = new URL(canonical); } catch { return false; } return candidate.origin === expected.origin && candidate.pathname.replace(/\/+$/, "") === expected.pathname.replace(/\/+$/, "") && candidate.search === expected.search; }; // One shared construction with `resolveProviderModelDiscoveryUrl` below: the // absolute `url` form carries the spec's fixed query (if any), and the `path` // form resolves against the REGISTRY's own baseUrl (never a configured one) // before appending the spec's fixed query. The candidate's own query must // equal the registry-owned query exactly — no subset/superset matching. if ("url" in spec && spec.url) { try { return sameUrl(appendDiscoveryQuery(new URL(spec.url), spec.query).toString()); } catch { return false; } } if ("path" in spec && spec.path) { try { const base = new URL(entry.baseUrl.endsWith("/") ? entry.baseUrl : `${entry.baseUrl}/`); const resolved = spec.path.startsWith("/") ? new URL(spec.path, base.origin) : new URL(spec.path, base); return sameUrl(appendDiscoveryQuery(resolved, spec.query).toString()); } catch { return false; } } return false; } /** Apply a registry-owned URL/path/query policy to the adapter's normal discovery endpoint. */ export function resolveProviderModelDiscoveryUrl( providerName: string, configuredProvider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>, effectiveBaseUrl: string, defaultUrl: string, ): string { const { spec } = resolveProviderModelDiscovery(providerName, configuredProvider); if (!spec) return defaultUrl; let resolved: URL; if (spec.url) { resolved = new URL(spec.url); } else if (spec.path) { const base = new URL(effectiveBaseUrl.endsWith("/") ? effectiveBaseUrl : `${effectiveBaseUrl}/`); resolved = spec.path.startsWith("/") ? new URL(spec.path, base.origin) : new URL(spec.path, base); } else { resolved = new URL(defaultUrl); } return appendDiscoveryQuery(resolved, spec.query).toString(); } function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, reason: unknown): void { try { void reader.cancel(reason).catch(() => undefined); } catch { // A non-conforming stream may throw synchronously from cancel(). } } /** Read a discovery response under a strict byte ceiling before JSON.parse can allocate freely. */ export async function readBoundedDiscoveryJson( response: Response, maxResponseBytes: number, ): Promise<BoundedDiscoveryJsonResult> { const limit = positiveIntegerAtMost(maxResponseBytes, MODEL_DISCOVERY_MAX_RESPONSE_BYTES); const declaredLength = Number(response.headers.get("content-length")); if (Number.isFinite(declaredLength) && declaredLength > limit) { try { void response.body?.cancel(new DOMException("Model discovery response is too large", "QuotaExceededError")) .catch(() => undefined); } catch { // Best-effort cancellation only. } return { ok: false, reason: "response_too_large" }; } if (!response.body) return { ok: false, reason: "invalid_json" }; const reader = response.body.getReader(); const chunks: Uint8Array[] = []; let total = 0; try { while (true) { const { value, done } = await reader.read(); if (done) break; if (!value || value.byteLength === 0) continue; if (value.byteLength > limit - total) { cancelWithoutWaiting( reader, new DOMException("Model discovery response is too large", "QuotaExceededError"), ); return { ok: false, reason: "response_too_large" }; } chunks.push(value); total += value.byteLength; } } finally { try { reader.releaseLock(); } catch { // Cancellation may keep the lock briefly. } } const bytes = new Uint8Array(total); let offset = 0; for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; } try { const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); return { ok: true, value: JSON.parse(text) as unknown }; } catch { return { ok: false, reason: "invalid_json" }; } } function valueAtPath(item: Record<string, unknown>, path: readonly string[]): unknown { const visit = (current: unknown, index: number): unknown => { if (index === path.length) return current; const segment = path[index]; if (segment === "*") { if (!Array.isArray(current)) return undefined; return current.slice(0, MODEL_DISCOVERY_MAX_FILTER_VALUES).map(value => visit(value, index + 1)); } if (current === null || typeof current !== "object" || Array.isArray(current)) return undefined; return visit((current as Record<string, unknown>)[segment!], index + 1); }; return visit(item, 0); } function comparableScalar(value: unknown, caseInsensitive: boolean): ProviderModelDiscoveryScalar | undefined { if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return undefined; if (typeof value === "string" && value.length > MODEL_DISCOVERY_MAX_FILTER_STRING_LENGTH) return undefined; return caseInsensitive && typeof value === "string" ? value.toLowerCase() : value; } function comparableNeedles( values: readonly ProviderModelDiscoveryScalar[], caseInsensitive: boolean, ): ProviderModelDiscoveryScalar[] { return values.map(value => caseInsensitive && typeof value === "string" ? value.toLowerCase() : value); } function predicateMatches(item: ProviderModelsApiItem, predicate: ProviderModelDiscoveryPredicate): boolean { const caseInsensitive = predicate.caseInsensitive === true; const raw = valueAtPath(item, predicate.path); if ("equalsAny" in predicate) { const value = comparableScalar(raw, caseInsensitive); return value !== undefined && comparableNeedles(predicate.equalsAny, caseInsensitive).includes(value); } const collection = Array.isArray(raw); const values: ProviderModelDiscoveryScalar[] = []; if (collection) { for (let i = 0; i < raw.length && i < MODEL_DISCOVERY_MAX_FILTER_VALUES; i += 1) { const value = comparableScalar(raw[i], caseInsensitive); if (value !== undefined) values.push(value); } } else if (typeof raw === "string") { values.push(caseInsensitive ? raw.toLowerCase() : raw); } const needles = comparableNeedles( "containsAny" in predicate ? predicate.containsAny : predicate.containsAll, caseInsensitive, ); if ("containsAny" in predicate) { return needles.some(needle => values.some(value => ( !collection && typeof value === "string" && typeof needle === "string" ? value.includes(needle) : value === needle ))); } return needles.every(needle => values.some(value => ( !collection && typeof value === "string" && typeof needle === "string" ? value.includes(needle) : value === needle ))); } export function providerModelMatchesDiscoveryFilter( item: ProviderModelsApiItem, filter: ProviderModelDiscoveryFilter | undefined, ): boolean { if (!filter) return true; if (filter.allOf && !filter.allOf.every(predicate => predicateMatches(item, predicate))) return false; if (filter.anyOf && filter.anyOf.length > 0 && !filter.anyOf.some(predicate => predicateMatches(item, predicate))) return false; if (filter.noneOf?.some(predicate => predicateMatches(item, predicate))) return false; return true; } /** Extract one allowlisted array envelope while enforcing the raw-row ceiling. */ export function extractModelEnvelopeRows( value: unknown, maxModels: number, envelopeKeys: readonly string[], ): ModelEnvelopeRowsResult { if (value === null || typeof value !== "object" || Array.isArray(value)) { return { ok: false, reason: "invalid_shape" }; } const record = value as Record<string, unknown>; const rows = envelopeKeys.map(key => record[key]).find(Array.isArray); if (!rows) return { ok: false, reason: "invalid_shape" }; const limit = positiveIntegerAtMost(maxModels, MODEL_DISCOVERY_MAX_MODELS); if (rows.length > limit) return { ok: false, reason: "too_many_models" }; return { ok: true, rows }; } /** Validate, bound, deduplicate, and filter the declared envelope or a top-level array (Together `#617`). */ /** * Metadata a sibling `models[]` array may contribute to an ALREADY-ADMITTED * `data[]` row (#1797). * * llama.cpp serves a dual-envelope body: an Ollama-style `models[]` array * carrying `capabilities` alongside the OpenAI-style `data[]` array carrying * `meta`, so the two halves of one model's metadata never meet and a server * that truthfully advertises "multimodal" produced an image-blind row. * * Two boundaries make this safe, and both were added after review found the * first attempt unsound: * * 1. It runs AFTER admission filtering. Enriching first let a sibling supply * the exact field a provider filter requires — reproduced against the real * Chutes policy, where a row lacking `supported_features: ["tools"]` was * admitted once a same-id sibling provided it. Enrichment may change what is * KNOWN about a model, never WHICH models are published. * 2. Only the capability keys #1797 needs are copied. A blanket "fill every * absent key" made the untrusted `models[]` array a way into any field the * pipeline consumes. * * The list deliberately EXCLUDES `supported_features` and `features`, even * though both are capability-shaped: they are the two keys real provider * filters test (`registry.ts:1591` requires `supported_features` to contain * "tools"; `registry.ts:1883` tests `features.tool_use`). Ordering already * prevents a sibling from flipping an admission verdict, but a key that is * both enrichable and filter-relevant is one refactor away from becoming a * bypass again. #1797 does not need them. */ const SIBLING_ENRICHABLE_KEYS = new Set(["capabilities", "modalities", "input_modalities"]); type SiblingIndex = Map<string, Record<string, unknown> | null>; function buildSiblingIndex(value: unknown, limit: number): SiblingIndex | null { const record = plainObject(value); const sibling = record?.models; if (!Array.isArray(sibling) || sibling.length === 0 || sibling.length > limit) return null; const byId: SiblingIndex = new Map(); for (const raw of sibling) { const entry = plainObject(raw); if (!entry) continue; for (const key of ["id", "model", "name"]) { const id = entry[key]; if (typeof id !== "string" || id.length === 0) continue; // `null` marks an ambiguous id: two sibling entries claim it, so neither // can be attributed with confidence and both are ignored. byId.set(id, byId.has(id) && byId.get(id) !== entry ? null : entry); } } return byId.size > 0 ? byId : null; } function enrichAdmittedModel(item: ProviderModelsApiItem, siblings: SiblingIndex): ProviderModelsApiItem { const extra = siblings.get(item.id); if (!extra) return item; let merged: Record<string, unknown> | null = null; for (const key of SIBLING_ENRICHABLE_KEYS) { if (!(key in extra) || key in item) continue; merged ??= { ...(item as Record<string, unknown>) }; merged[key] = extra[key]; } return (merged ?? item) as ProviderModelsApiItem; } function plainObject(value: unknown): Record<string, unknown> | null { return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null; } /** Why one envelope row cannot become a model, phrased without any row content. */ function invalidRowReason(raw: unknown, idField: string): string | undefined { const row = plainObject(raw); if (!row) return "is not an object"; const id = row[idField]; if (isValidModelDiscoveryModelId(id)) return undefined; return typeof id !== "string" ? "has a non-string id" : !id.trim() ? "has an empty id" : "has an invalid id"; } /** * Strict discovery rejects a listing with any invalid row; `skipInvalidRows` (#7910) drops those rows * instead. Every row is still counted against the raw-row ceiling before this runs, and a listing * where invalid rows were skipped but nothing was admitted stays malformed: skipping must never turn * a broken listing into an authoritative empty roster. */ export function extractProviderModelItems( value: unknown, discovery: ResolvedProviderModelDiscovery, ): ProviderModelItemsResult { const limit = positiveIntegerAtMost(discovery.maxModels, MODEL_DISCOVERY_MAX_MODELS); if (discovery.spec?.format === "workbuddy") return extractWorkBuddyModels(value, limit); let data: unknown[]; let siblings: SiblingIndex | null = null; if (Array.isArray(value)) { // Together-style top-level /models arrays. The default contract must not treat a stray // `models` key on openai-chat responses as valid; only a provider spec may opt into it. if (value.length > limit) return { ok: false, reason: "too_many_models" }; data = value; } else { const envelopeKey = discovery.spec?.envelopeKey ?? "data"; const envelope = extractModelEnvelopeRows(value, discovery.maxModels, [envelopeKey]); if (!envelope.ok) return envelope; data = envelope.rows; siblings = envelopeKey === "data" ? buildSiblingIndex(value, limit) : null; } const items: ProviderModelsApiItem[] = []; const preferred: ProviderModelsApiItem[] = []; const seen = new Set<string>(); const idField = discovery.spec?.idField ?? "id"; const skipInvalidRows = discovery.skipInvalidRows === true; let invalidRows = 0; let firstInvalid = ""; for (const [index, raw] of data.entries()) { const invalid = invalidRowReason(raw, idField); if (invalid !== undefined) { if (invalidRows === 0) firstInvalid = `row ${index} ${invalid}`; invalidRows += 1; continue; } // A strict listing is already rejected; keep scanning only to count the invalid rows. if (invalidRows > 0 && !skipInvalidRows) continue; const id = (raw as Record<string, unknown>)[idField] as string; const prefix = discovery.spec?.stripIdPrefix; let finalId = id; if (prefix && finalId.startsWith(prefix)) { finalId = finalId.slice(prefix.length); if (!isValidModelDiscoveryModelId(finalId)) continue; } const item = finalId === id && idField === "id" ? raw as ProviderModelsApiItem : { ...(raw as Record<string, unknown>), id: finalId }; // Admission is decided on the ORIGINAL `data[]` row, before any sibling // enrichment. Merging first let a `models[]` entry supply the very field a // provider filter requires — reproduced against the real Chutes policy, // where a row lacking `supported_features: ["tools"]` was admitted once a // same-id sibling provided it. Enrichment must never change WHICH models // are published, only what is known about an already-admitted one. if (!providerModelMatchesDiscoveryFilter(item, discovery.spec?.filter) || seen.has(finalId)) continue; seen.add(finalId); // Preference, like admission, must not be supplied by sibling enrichment. const target = discovery.spec?.preferFirst?.some(predicate => predicateMatches(raw as ProviderModelsApiItem, predicate)) ? preferred : items; target.push(siblings ? enrichAdmittedModel(item, siblings) : item); } if (invalidRows > 0 && (!skipInvalidRows || items.length + preferred.length === 0)) { return { ok: false, reason: "invalid_shape", diagnostic: `${firstInvalid}; ${invalidRows} of ${data.length} rows invalid` }; } return { ok: true, items: [...preferred, ...items], rawCount: data.length, ...(invalidRows > 0 ? { skippedInvalidRows: invalidRows } : {}), }; }