@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
268 lines (248 loc) • 12.2 kB
text/typescript
import { projectLocalModelRefusalLog } from "./request-log-failure-detail";
import { clientFacingModelLabel, clientFacingModelText, type ClientFacingModelLabel } from "../lib/error-destination";
import { markProxyError } from "../lib/client-error-body";
import type { DataPlaneAdmission } from "./auth-cors";
import { isApiAuthRequired } from "./auth-cors";
import type { OcxApiKeyEntry, OcxConfig } from "../types";
import { markResponseNonReplayable } from "../lib/upstream-retry";
/**
* Per-admission-key model and provider scope.
*
* A hub that serves several clients with their own `ocx_data_…` keys needs a
* mail or cron key to be unable to spend a coding key's Grok or Claude quota.
* Hub-level model selection cannot express that: it hides a model from
* everyone or from no one (#5049).
*
* Two rules decide what this is and is not:
*
* A scope names DESTINATIONS, not selectors. It is evaluated against the
* resolved route — the provider and model a turn will actually bill — never
* against the string the client sent. A client-supplied label is not a
* permission subject: alias resolution, a combo pick, a policy fallback and a
* compaction override all rewrite that string, so a scope checked before them
* would authorize one destination and reach another.
*
* A scope is never management authority. It narrows which models an inference
* key may call and grants nothing else; reading or editing a scope stays on
* the management credential.
*/
export interface AdmissionModelScope {
/** Every inherited scope must also admit the final destination. */
readonly allOf?: readonly AdmissionModelScope[];
/** Resolved provider names this key may reach. Empty means every provider. */
readonly providers: readonly string[];
/** Resolved destinations this key may reach. Empty means every model. */
readonly models: readonly string[];
}
/** The resolved destination a scope decision is made about. */
export interface ScopedRoute {
readonly providerName: string;
readonly modelId: string;
}
const normalize = (value: string): string => value.trim().toLowerCase();
/** Does this scope admit this provider on its own terms? */
function providerAllowedByScope(scope: AdmissionModelScope, providerName: string): boolean {
return scope.providers.length === 0 || scope.providers.includes(normalize(providerName));
}
function unnamedDestinationAllowedByScope(scope: AdmissionModelScope, providerName: string): boolean {
return providerAllowedByScope(scope, providerName) && scope.models.length === 0
&& (scope.allOf?.every(part => unnamedDestinationAllowedByScope(part, providerName)) ?? true);
}
function normalizedList(values: readonly string[] | undefined): readonly string[] {
if (!Array.isArray(values)) return [];
const seen = new Set<string>();
for (const value of values) {
if (typeof value !== "string") continue;
const normalized = normalize(value);
if (normalized) seen.add(normalized);
}
return [...seen];
}
/** Read the scope a stored key declares. An entry with neither list is unrestricted. */
export function admissionModelScopeOf(entry: Pick<OcxApiKeyEntry, "allowedProviders" | "allowedModels">): AdmissionModelScope | undefined {
const providers = normalizedList(entry.allowedProviders);
const models = normalizedList(entry.allowedModels);
return providers.length === 0 && models.length === 0 ? undefined : { providers, models };
}
/**
* The scope that applies to one request, or undefined when nothing is scoped.
*
* Only a configured key carries a scope. The environment token and loopback
* admission have no stored record to attach one to, so they stay unrestricted;
* an operator who wants them narrowed issues a configured key instead.
*/
export function resolveAdmissionModelScope(
config: Pick<OcxConfig, "apiKeys">,
admission: DataPlaneAdmission | undefined,
): AdmissionModelScope | undefined {
const entry = admission?.kind === "configured"
? (config.apiKeys ?? []).find(key => key.id === admission.keyId) : undefined;
return intersectAdmissionModelScopes(entry ? admissionModelScopeOf(entry) : undefined, admission?.callerPolicy?.modelScope);
}
export function intersectAdmissionModelScopes(a: AdmissionModelScope | undefined, b: AdmissionModelScope | undefined): AdmissionModelScope | undefined {
return a && b ? { providers: [], models: [], allOf: [a, b] } : a ?? b;
}
/** Consent comes from stored operator config, never request headers. Use the full listener config. */
export function admissionMayUseMeteredComboTargets(
config: Pick<OcxConfig, "apiKeys" | "hostname">,
admission: DataPlaneAdmission | undefined,
combo?: { allowMeteredTargets?: boolean },
): boolean {
const caller = admission?.callerPolicy;
if (caller && (!caller.allowMeteredComboTargets || caller.meteredRequiresComboOptIn && combo?.allowMeteredTargets !== true)) return false;
if (admission?.kind === "configured") {
const entry = (config.apiKeys ?? []).find(key => key.id === admission.keyId);
return entry?.allowMeteredComboTargets === true;
}
// A loopback-admitted internal hop's captured policy already holds this branch's decision for
// its listener, or the consent of the validated key it presented (#7894); it was checked above.
if (admission?.kind === "loopback" && caller) return true;
// Linked ingress always carries keyed admission, even when the primary bind is loopback.
// A secondary loopback listener on a public proxy does not qualify either.
return (!admission || admission.kind === "loopback")
&& !isApiAuthRequired(config) && combo?.allowMeteredTargets === true;
}
/**
* Does this scope admit this resolved destination?
*
* The two lists are independent conditions and both must hold when both are
* declared: a key allowed one provider and one model may not reach that
* model on a different provider, which is what a combo child or a policy
* fallback would otherwise do while the requested selector stayed the same.
*
* A model entry matches the bare resolved model id or the fully qualified
* `provider/model` form, so an operator can scope one model everywhere or
* pin it to a single provider without a second field.
*/
export function routeAllowedByScope(
scope: AdmissionModelScope | undefined,
route: ScopedRoute,
): boolean {
if (!scope) return true;
if (scope.allOf?.some(part => !routeAllowedByScope(part, route))) return false;
const model = normalize(route.modelId);
if (!providerAllowedByScope(scope, route.providerName)) return false;
if (scope.models.length === 0) return true;
return scope.models.includes(model) || scope.models.includes(normalize(route.providerName) + "/" + model);
}
/**
* A request that asked for a destination its key may not reach.
*
* Carries the selector the client sent rather than the destination it resolved
* to: the caller needs to know which of its own requests was refused, and a
* key that may not reach a provider has no business learning that an alias it
* named points there. The resolved destination goes to the server log.
*/
export class AdmissionModelDeniedError extends Error {
readonly requestedModel: string;
readonly deniedProvider: string;
readonly deniedModel: string;
constructor(requestedModel: ClientFacingModelLabel, route: ScopedRoute) {
super("model " + clientFacingModelText(requestedModel) + " is not allowed for this API key");
this.name = "AdmissionModelDeniedError";
this.requestedModel = clientFacingModelText(requestedModel);
this.deniedProvider = route.providerName;
this.deniedModel = route.modelId;
}
}
/** Stable wire type for a scope refusal. */
export const MODEL_NOT_ALLOWED_FOR_KEY = "model_not_allowed_for_key";
/**
* How a refusal names a destination whose model nobody stated.
*
* This is message vocabulary, never a model id. It is not compared against
* `allowedModels`, so an operator who copies it out of a refusal into a list
* cannot grant "whatever the upstream picks" — the one destination a model list
* is unable to describe.
*/
export const UNNAMED_DESTINATION_MODEL = "(unnamed)";
/** The HTTP body a scope refusal returns. 403: authenticated, not permitted. */
export function admissionModelDeniedBody(error: AdmissionModelDeniedError): {
error: { type: string; message: string; model: string };
} {
return {
error: {
type: MODEL_NOT_ALLOWED_FOR_KEY,
message: error.message,
model: error.requestedModel,
},
};
}
/**
* The refusal a scoped request gets: 403, not 404.
*
* The key authenticated; it simply may not reach this destination. Reporting
* "not found" instead would tell a client its credential is wrong and invite
* it to retry with another, and would make an operator's own denial
* indistinguishable from a typo in the model name.
*/
/** Project scope refusals before any caller finalizes its request log. */
export function projectAdmissionModelDeniedLog(error: AdmissionModelDeniedError, logCtx: import("./request-log").RequestLogContext): AdmissionModelDeniedError {
projectLocalModelRefusalLog(logCtx, clientFacingModelLabel(error.requestedModel,
error.requestedModel === UNNAMED_DESTINATION_MODEL ? "unnamed" : "requested"));
logCtx.requestedModel = error.requestedModel;
return error;
}
export function admissionModelDeniedResponse(error: AdmissionModelDeniedError): Response {
const response = new Response(JSON.stringify(admissionModelDeniedBody(error)), {
status: 403,
headers: { "Content-Type": "application/json" },
});
markResponseNonReplayable(response);
return markProxyError(response, "scope");
}
/**
* Refuse a resolved destination this key may not reach.
*
* Every request-path site that produces or re-produces a route calls this, so
* the direct name, an alias, a combo child, a policy or subagent fallback and
* a compaction override are all checked at the point they become concrete
* rather than once at the front door.
*/
export function assertRouteAllowedByScope(
scope: AdmissionModelScope | undefined,
requestedModel: ClientFacingModelLabel,
route: ScopedRoute,
): void {
if (!routeAllowedByScope(scope, route)) {
throw new AdmissionModelDeniedError(requestedModel, route);
}
}
/**
* The refusal a non-routed data-plane surface returns, or undefined when the
* destination is permitted.
*
* The Responses path resolves a route inside a try/catch and throws from the
* point the destination becomes concrete. The endpoints beside it -- images,
* audio, voice and the search relay -- have no router and no such boundary:
* each picks its own upstream inline and returns a Response. This is the same
* predicate against the same kind of resolved destination, shaped for that
* control flow, so a key that may not reach a provider is refused identically
* whichever surface it asked through.
*
* `destination.modelId` is undefined when nobody named the model this request
* will run: the relay copies the body and the upstream picks, or a voice join
* attaches to a call this process never recorded. A key with a model list is
* then refused, because no entry in that list can describe the destination; a
* key scoped only by provider is judged on the provider alone.
*/
export function admissionScopeDenial(
config: Pick<OcxConfig, "apiKeys">,
admission: DataPlaneAdmission | undefined,
requestedModel: string | undefined,
destination: { readonly providerName: string; readonly modelId: string | undefined },
): Response | undefined {
const scope = resolveAdmissionModelScope(config, admission);
if (!scope) return undefined;
const allowed = destination.modelId === undefined
? unnamedDestinationAllowedByScope(scope, destination.providerName)
: routeAllowedByScope(scope, { providerName: destination.providerName, modelId: destination.modelId });
if (allowed) return undefined;
return admissionModelDeniedResponse(new AdmissionModelDeniedError(
clientFacingModelLabel(requestedModel, requestedModel === undefined ? "unnamed" : "requested"),
{
providerName: destination.providerName,
modelId: destination.modelId ?? UNNAMED_DESTINATION_MODEL,
},
));
}