Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Custom Endpoints Loader — reads `config.customEndpoints` and registers each
* valid entry as a runtime ProviderDefinition + ProviderProfile.
*
* Phase 3 of the LiteLLM-demotion refactor. Users declare custom OpenAI- or
* Anthropic-compatible endpoints in ~/.claudish/config.json and they become
* first-class providers that work with `--model my-endpoint@some-model`.
*
* Validation: each entry is parsed via `CustomEndpointSchema` (Zod). Invalid
* entries are collected into `result.errors` and reported to stderr — never
* fatal, so one typo doesn't crash startup.
*
* Idempotency: calling twice with the same config is safe. The runtime
* registry is a Map keyed on endpoint name, so re-registration overwrites.
*
* `registerEndpoint()` is the single validate→build→register sequence, and it
* takes an optional `EndpointDefinitionOverrides`. User config never passes one
* — the overrides exist so a BUNDLED endpoint can carry the vendor's own env
* var and an optional base-URL override while travelling this exact path.
* Every generated field falls back to today's expression when the argument is
* absent, so the user-authored result is unchanged field for field.
*/
import { z } from "zod";
import { AnthropicAPIFormat } from "../adapters/anthropic-api-format.js";
import type { BaseAPIFormat } from "../adapters/base-api-format.js";
import { CodexAPIFormat } from "../adapters/codex-api-format.js";
import { LiteLLMAPIFormat } from "../adapters/litellm-api-format.js";
import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
import { credentials } from "../auth/credentials/authority.js";
import {
type CustomEndpoint,
type CustomEndpointComplex,
CustomEndpointSchema,
type CustomEndpointSimple,
} from "../config-schema.js";
import { realValue } from "../env-placeholder.js";
import { ComposedHandler } from "../handlers/composed-handler.js";
import type { RemoteProvider } from "../handlers/shared/remote-provider-types.js";
import type { ModelHandler } from "../handlers/types.js";
import type { ClaudishProfileConfig } from "../profile-config.js";
import type { WireApi } from "./connection-wire.js";
import { declaredConnection, declaredWire } from "./declared-wire.js";
import { clearEndpointUnavailable, recordEndpointUnavailable } from "./endpoint-diagnostics.js";
import { customEndpointKeyEnvVar } from "./endpoint-key-env.js";
import {
type RouteTier,
type TieredProviderDefinition,
type TransportType,
baseUrlOverrideCandidates,
runtimeHandler,
} from "./provider-definitions.js";
import type { ProfileContext, ProviderProfile } from "./provider-profiles.js";
import { reservedNamespaceOwner } from "./reserved-namespace.js";
import { registerRuntimeProfile, registerRuntimeProvider } from "./runtime-providers.js";
import { AnthropicProviderTransport } from "./transport/anthropic-compat.js";
import { LiteLLMProviderTransport } from "./transport/litellm.js";
import { OpenAIProviderTransport } from "./transport/openai.js";
/**
* Result of loading custom endpoints from a config object.
*/
export interface LoadResult {
/** Number of endpoints successfully registered. */
registered: number;
/** Names of endpoints that failed validation, with their error messages. */
errors: Array<{ name: string; message: string }>;
/**
* Entries refused for a reason that is NOT a validation failure — today only
* a collision with a builtin provider's namespace (#191).
*
* Kept separate from `errors` because the two need different words. An
* invalid entry is a typo in the user's JSON; a refused one is a perfectly
* well-formed entry that claudish will not honour, and telling someone to
* "fix the validation error" in that case sends them looking at the wrong
* thing.
*/
refused: Array<{ name: string; reason: string }>;
}
/**
* The handful of generated fields a BUNDLED endpoint needs to differ on.
*
* A predefined catalog row compiles to exactly the `CustomEndpointComplex`
* object a user would have hand-written, which is what lets the whole feature
* reuse this already-tested request path instead of adding one. Four things a
* hand-written entry cannot express are all that remain, and they all live
* here: the vendor's own env var (`GROQ_API_KEY` rather than the synthesized
* `CUSTOM_GROQ_KEY`), extra accepted spellings, a run-time base-URL override,
* and the key-signup URL a missing-key error should point at.
*
* EVERY field falls back to today's exact expression when the overrides
* argument is absent, so `loadCustomEndpoints` — which never passes it —
* produces a definition and profile that behave identically. That is the
* contract, and `custom-endpoints-loader.test.ts` passing unmodified is how it
* is checked.
*
* "Identically", not "byte-identically" — the object is measurably different in
* one harmless way: it now ALWAYS carries `apiKeyAliases` and `baseUrlEnvVars`
* keys, valued `undefined`, where the old literals omitted them, and
* `registerEndpoint` passes `aliases: undefined` to the authority (same as the
* field being absent). `toEqual` ignores that; `toStrictEqual` would not, and
* no current test uses it. The distinction is written down because an
* overclaiming comment is how a future reader stops checking.
*/
export interface EndpointDefinitionOverrides {
/** Primary credential env var. Default: `CUSTOM_<SANITIZED_NAME>_KEY`. */
apiKeyEnvVar?: string;
/** Additional accepted env vars, tried after the primary. */
apiKeyAliases?: string[];
/** Env vars that override `baseUrl` at run time (R12). */
baseUrlEnvVars?: string[];
/** Where a user obtains a key. Default: `""`. */
apiKeyUrl?: string;
/** Credential label shown in the TUI. Default: `<name> (custom endpoint)`. */
apiKeyDescription?: string;
/** Picker/TUI description. Default: `Custom endpoint: <name>`. */
description?: string;
}
/**
* Validate → build definition → build profile → register in all three
* registries. The ONE sequence, used by both the user-authored path below and
* (from a later phase) the bundled catalog.
*
* It is extracted rather than inlined twice because the two paths registering
* a provider slightly differently is the failure this codebase keeps paying
* for: a definition without its profile silently routes to OpenRouter, and a
* definition without its credential registration fails the routing pre-flight
* before the handler that could have resolved the key is ever built. One
* function means the catalog cannot drift from the path users already exercise.
*
* THROWS on invalid input (Zod or otherwise) — deliberately, so each caller
* decides how to report it. Nothing here writes to stderr or exits.
*/
export function registerEndpoint(
name: string,
entry: unknown,
ovr?: EndpointDefinitionOverrides
): void {
const validated = CustomEndpointSchema.parse(entry);
const def = buildProviderDefinition(name, validated, ovr);
const profile = buildProviderProfile(validated, ovr);
registerRuntimeProvider(def);
registerRuntimeProfile(name, profile);
// Register the custom endpoint in the credential authority too, so its key
// (CUSTOM_<NAME>_KEY — including op:// values) resolves through the single
// authority like every other provider, instead of an out-of-band env read.
//
// `declaredKey` closes over the endpoint's own `apiKey` field so a literal
// or `${VAR}` declaration ALSO counts as a credential. The authority is the
// routing pre-flight's oracle (hasCredentialsForProvider / getRequestAuth);
// registering only the CUSTOM_<NAME>_KEY env var made every `${VAR}` and
// literal endpoint look uncredentialed, so it was rejected before its
// handler — which could have resolved the key — was ever constructed.
credentials.registerApiKeyProvider({
name: def.name,
envVar: def.apiKeyEnvVar,
aliases: def.apiKeyAliases,
// Passed THROUGH, not narrowed here. This site used to inline
// `=== "x-api-key" ? "x-api-key" : "bearer"`, which collapsed `"none"` into
// bearer and left a keyless endpoint failing the routing pre-flight with
// "CUSTOM_<NAME>_KEY is required" — a demand for a key the user had
// correctly declared they do not have. The authority normalizes.
authScheme: def.authScheme,
declaredKey: () => resolveDeclaredEndpointKey(validated),
});
// This name now has a definition, a profile and a credential, so whatever
// reason it was previously unavailable for is stale. Clearing here (rather
// than at each recording site) means a re-registration — a fixed URL, a key
// imported in the config TUI — cannot leave the user reading a dead reason.
clearEndpointUnavailable(name);
}
/**
* Validate and register all customEndpoints from a config.
*
* Invalid entries are collected into `result.errors` and skipped. Entries whose
* NAME collides with a builtin provider are collected into `result.refused` and
* skipped — see below.
*
* ── Why a name collision is refused rather than merged (#191) ───────────────
*
* `credentials.registerApiKeyProvider` is a plain `Map.set` with no guard, so
* before this check an entry keyed `openrouter` landed in a split state:
*
* definition (`getProviderByName`) → BUILTIN wins, baseUrl stays openrouter.ai
* profile (`PROVIDER_PROFILES[name]`) → BUILTIN wins
* credential (`registerApiKeyProvider`) → the CUSTOM ENDPOINT, last write, no check
*
* So the user got neither half of what they asked for. Their endpoint was
* shadowed AND the builtin's credential was replaced, with real requests to
* openrouter.ai signed by `CUSTOM_OPENROUTER_KEY`, and nothing anywhere
* reporting either.
*
* Refusing is strictly better than any merge. There is no reading of
* "customEndpoints.openrouter" under which sending the user's key to the
* builtin's URL is what they meant, and the bundled catalog has refused exactly
* this since it shipped — so the two paths now agree instead of one being
* guarded and the other not.
*
* The refusal is LOUD by design. A provider that fails to appear is diagnosable
* from one warning line; a provider that appears and signs requests to someone
* else's host with your key is not diagnosable at all.
*/
export function loadCustomEndpoints(config: ClaudishProfileConfig): LoadResult {
const result: LoadResult = { registered: 0, errors: [], refused: [] };
const raw = config.customEndpoints;
if (!raw || typeof raw !== "object") return result;
for (const [name, entry] of Object.entries(raw)) {
const owner = reservedNamespaceOwner(name);
if (owner) {
const reason =
`'${name}' is already claimed by builtin provider '${owner}' ` +
"(as its name, a shortcut, or a legacy prefix)";
result.refused.push({ name, reason });
recordEndpointUnavailable(name, `custom endpoint was skipped because ${reason}`);
continue;
}
try {
registerEndpoint(name, entry);
result.registered++;
} catch (err) {
const message =
err instanceof z.ZodError
? err.issues.map((i) => i.message).join(", ")
: err instanceof Error
? err.message
: String(err);
result.errors.push({ name, message });
}
}
return result;
}
/**
* The routing tier of EVERY endpoint that arrives from config — user-authored or
* bundled.
*
* `gateway`, and deliberately the weakest true thing claudish can say. A row
* carries CONNECTION FACTS ONLY (see predefined-endpoint-schema.ts): a URL, a
* path, a wire format and the vendor's env var. Nothing in it distinguishes
* Together AI reselling forty vendors from Cohere serving its own models, so
* classifying one as `native` would be a guess, and guessing UPWARDS would sort a
* third-party endpoint ahead of the vendor's own. `gateway` is the last tier
* before the fallback, so an endpoint claudish cannot classify sorts last among
* the ones it can — which is the recoverable direction.
*
* Not `fallback`: that tier is a POSITION held by whichever provider
* `defaultProvider` names, and no definition may claim it.
*
* Exported for the route-binding guard: a bundled row gets a definition only when
* it registers, which needs its key, so a hermetic test reads the tier here.
*/
export const CUSTOM_ENDPOINT_TIER: RouteTier = "gateway";
/**
* Build a ProviderDefinition for a custom endpoint so it appears in lookups
* (getProviderByName, getAllProviders, etc.). The definition is minimal —
* real handler construction happens in the profile.
*
* `ovr` is absent for user-authored endpoints; every field below then evaluates
* to the same expression it always did.
*/
function buildProviderDefinition(
name: string,
ep: CustomEndpoint,
ovr?: EndpointDefinitionOverrides
): TieredProviderDefinition {
const apiKeyEnvVar = ovr?.apiKeyEnvVar ?? customEndpointKeyEnvVar(name);
const apiKeyAliases = ovr?.apiKeyAliases;
const baseUrlEnvVars = ovr?.baseUrlEnvVars;
const apiKeyUrl = ovr?.apiKeyUrl ?? "";
if (ep.kind === "simple") {
return {
createHandler: runtimeHandler(name),
tier: CUSTOM_ENDPOINT_TIER,
name,
displayName: name,
transport: ep.format as TransportType,
baseUrl: stripTrailingSlash(ep.url),
baseUrlEnvVars,
apiPath: "/chat/completions",
apiKeyEnvVar,
apiKeyAliases,
apiKeyDescription: ovr?.apiKeyDescription ?? `${name} (custom endpoint)`,
apiKeyUrl,
shortcuts: [name],
legacyPrefixes: [],
isDirectApi: true,
shortestPrefix: name,
description: ovr?.description ?? `Custom endpoint: ${name}`,
// Was a hardcoded "bearer", which silently discarded the `authScheme` the
// simple schema now accepts — so `authScheme: "none"` validated, registered,
// and then demanded a key anyway. Bearer stays the DEFAULT (that is what
// every simple endpoint got before), but a declared scheme now survives.
authScheme: ep.authScheme ?? "bearer",
};
}
return {
createHandler: runtimeHandler(name),
tier: CUSTOM_ENDPOINT_TIER,
name,
displayName: ep.displayName,
transport: ep.transport as TransportType,
baseUrl: stripTrailingSlash(ep.baseUrl),
baseUrlEnvVars,
apiPath: ep.apiPath ?? "/v1/chat/completions",
apiKeyEnvVar,
apiKeyAliases,
apiKeyDescription: ovr?.apiKeyDescription ?? `${ep.displayName} (custom endpoint)`,
apiKeyUrl,
shortcuts: [name],
legacyPrefixes: [],
isDirectApi: true,
shortestPrefix: name,
description: ovr?.description ?? `Custom endpoint: ${ep.displayName}`,
headers: ep.headers,
authScheme: ep.authScheme ?? "bearer",
};
}
/**
* Build a ProviderProfile for a custom endpoint that creates a ComposedHandler
* on demand. Modeled after litellmProfile in provider-profiles.ts.
*
* `ovr` is absent for user-authored endpoints, and the base URL is then the
* endpoint's own field, read exactly as before.
*/
function buildProviderProfile(
ep: CustomEndpoint,
ovr?: EndpointDefinitionOverrides
): ProviderProfile {
return {
createHandler(ctx: ProfileContext): ModelHandler | null {
// The key is resolved through the credential authority (proxy-server passes
// it as ctx.apiKey via getRequestAuth — env → config → op://, lazy SDK).
// Fall back to the literal/${VAR} resolver only when the authority yielded
// nothing (e.g. a plain ${VAR} apiKey the authority's env read also covers,
// or a non-routed construction path). This is the single source of truth —
// an op:// custom apiKey now resolves correctly instead of signing the
// literal "op://…" string.
const apiKey = ctx.apiKey || resolveCustomEndpointApiKey(ep);
// Resolved per handler build rather than captured at registration, so a
// base URL exported after startup is honoured without a restart.
const declaredBaseUrl = ep.kind === "simple" ? ep.url : ep.baseUrl;
const resolved = classifyEndpointBaseUrl(declaredBaseUrl, ovr?.baseUrlEnvVars);
if (!resolved.ok) {
const reason = describeBadBaseUrlOverride(resolved, declaredBaseUrl);
console.error(`[claudish] ${reason}`);
// The caller of createHandler() sees only `null`, and the routing
// pre-flight renders that as "no credential" — the wrong cause, which
// sends the user hunting for a key they already have. Record the real
// one so the error can name it.
recordEndpointUnavailable(ctx.provider.name, `its ${reason}`);
return null;
}
const baseUrl = resolved.url;
if (ep.kind === "simple") {
return buildSimpleHandler(ep, ctx, apiKey, baseUrl);
}
return buildComplexHandler(ep, ctx, apiKey, baseUrl);
},
};
}
/** A resolved base URL, or the override that made resolution impossible. */
export type EndpointBaseUrl =
| { ok: true; url: string }
| { ok: false; envVar: string; value: string; source: "config" | "env" };
/**
* The base URL to actually use: an override when one is declared AND set,
* otherwise the endpoint's own.
*
* The override chain is NOT re-implemented here. It is
* `baseUrlOverrideCandidates()` — the same function `getEffectiveBaseUrl()`
* uses — so `config.endpoints[VAR]` (what the config TUI's URL editor and
* `claudish config` actually persist) and `process.env[VAR]` are consulted in
* one order, decided in one place. An earlier revision walked `process.env`
* only: the TUI writes BOTH the config entry and the env var, so it looked
* right for the rest of the session and diverged after a restart, at which
* point the TUI kept DISPLAYING the saved private URL while requests went to
* the bundled public host.
*
* Reports `ok: false` — meaning "build no handler, register nothing" — when an
* override IS set to a concrete value that is not an http(s) URL. It
* deliberately does NOT fall back to the bundled default in that case: a
* base-URL override exists so a customer can point a gateway-shaped vendor at
* their own instance, and silently sending that instance's prompts, file
* contents and API key to the PUBLIC vendor hostname turns a typo into a
* data-egress incident. Absence with an exact reason beats a wrong destination.
* That rule applies to a CONFIG-sourced value exactly as it does to an
* env-sourced one — the hazard is the destination, not the storage.
*
* An UNEXPANDED `${VAR}` placeholder means the variable is unset, not wrong, so
* `realValue()` drops it and the NEXT candidate (or the declared URL) stands —
* the override was never really set. Without that distinction the strict rule
* would bite exactly the user it is meant to protect, since a declarative host
* passes placeholders through verbatim.
*
* I/O-free in the sense that matters: `new URL()` parses, it does not connect,
* and nothing here writes to stderr — the two callers (registration gate and
* handler build) want to phrase the same fact differently, so the phrasing
* stays with them. It does read `~/.claudish/config.json` via
* `getConfigEndpoint`, but ONLY for an endpoint that declares
* `baseUrlEnvVars`; a row without one still touches nothing.
*/
export function classifyEndpointBaseUrl(
declared: string,
baseUrlEnvVars?: string[]
): EndpointBaseUrl {
for (const candidate of baseUrlOverrideCandidates(baseUrlEnvVars)) {
const value = realValue(candidate.value)?.trim();
if (!value) continue;
if (!isHttpUrl(value)) {
return { ok: false, envVar: candidate.envVar, value, source: candidate.source };
}
return { ok: true, url: stripTrailingSlash(value) };
}
return { ok: true, url: stripTrailingSlash(declared) };
}
/**
* One sentence describing a bad override, shared by both callers so the stderr
* warning and the routing error cannot drift into two different explanations of
* the same fact.
*
* The `source` decides only the NOUN and the remedy — "unset it" is not
* actionable advice for a value that lives in a config file the user edited in
* a TUI. Absent or `"env"` renders the original sentence byte for byte, which
* is what the recorded validation run and its stderr transcript pin.
*/
export function describeBadBaseUrlOverride(
bad: { envVar: string; value: string; source?: "config" | "env" },
declared: string
): string {
const where =
bad.source === "config"
? `config.endpoints["${bad.envVar}"] is set to '${bad.value}'`
: `${bad.envVar} is set to '${bad.value}'`;
const remedy =
bad.source === "config"
? "Fix or remove it (claudish config -> Providers)."
: "Fix or unset it.";
return (
`${where}, which is not a valid http(s) URL. ` +
`${remedy} (Not falling back to ${declared} — the override was set on purpose.)`
);
}
function isHttpUrl(value: string): boolean {
try {
const parsed = new URL(value);
return parsed.protocol === "http:" || parsed.protocol === "https:";
} catch {
return false;
}
}
function buildSimpleHandler(
ep: CustomEndpointSimple,
ctx: ProfileContext,
apiKey: string,
baseUrl: string
): ModelHandler | null {
const finalModel = ep.modelPrefix ? `${ep.modelPrefix}${ctx.modelName}` : ctx.modelName;
// The request is shaped from what the endpoint DECLARES (its `wire` block,
// or the documented defaults), never from the model name.
const wire = declaredWire(
ep.format === "openai" ? "chat-completions" : "anthropic-messages",
ep.wire
);
const connection = declaredConnection(ctx.provider.name, finalModel, baseUrl, wire);
if (ep.format === "openai") {
const remoteProvider: RemoteProvider = {
name: ctx.provider.name,
baseUrl,
apiPath: wire.api === "responses" ? "/responses" : "/chat/completions",
apiKeyEnvVar: ctx.provider.apiKeyEnvVar,
prefixes: ctx.provider.prefixes ?? [],
headers: ctx.provider.headers,
authScheme: "bearer",
};
const transport = new OpenAIProviderTransport(remoteProvider, finalModel, apiKey);
return new ComposedHandler(transport, ctx.targetModel, finalModel, ctx.port, {
adapter: openAiFamilyAdapter(wire.api, finalModel),
tokenStrategy: "delta-aware",
...ctx.sharedOpts,
connection,
});
}
// anthropic
const remoteProvider: RemoteProvider = {
name: ctx.provider.name,
baseUrl,
apiPath: "/v1/messages",
apiKeyEnvVar: ctx.provider.apiKeyEnvVar,
prefixes: ctx.provider.prefixes ?? [],
headers: ctx.provider.headers,
authScheme: ctx.provider.authScheme ?? "x-api-key",
};
const transport = new AnthropicProviderTransport(remoteProvider, apiKey);
const adapter = new AnthropicAPIFormat(finalModel, ctx.provider.name);
return new ComposedHandler(transport, ctx.targetModel, finalModel, ctx.port, {
adapter,
...ctx.sharedOpts,
connection,
});
}
/** Chat Completions or the generic Responses body, as the declared wire says. */
function openAiFamilyAdapter(api: WireApi, model: string): BaseAPIFormat {
return api === "responses"
? new CodexAPIFormat(model, undefined, { codexExtras: false })
: new OpenAIAPIFormat(model);
}
function buildComplexHandler(
ep: CustomEndpointComplex,
ctx: ProfileContext,
apiKey: string,
baseUrl: string
): ModelHandler | null {
const finalModel = ep.modelPrefix ? `${ep.modelPrefix}${ctx.modelName}` : ctx.modelName;
const wire = declaredWire(
ep.transport === "anthropic" ? "anthropic-messages" : "chat-completions",
ep.wire
);
const connection = declaredConnection(ctx.provider.name, finalModel, baseUrl, wire);
const apiPath =
ep.apiPath ?? (wire.api === "responses" ? "/v1/responses" : "/v1/chat/completions");
switch (ep.transport) {
case "litellm": {
const transport = new LiteLLMProviderTransport(baseUrl, apiKey, finalModel);
const adapter = new LiteLLMAPIFormat(finalModel, baseUrl);
return new ComposedHandler(transport, ctx.targetModel, finalModel, ctx.port, {
adapter,
...ctx.sharedOpts,
connection,
});
}
case "openai": {
const remoteProvider: RemoteProvider = {
name: ctx.provider.name,
baseUrl,
apiPath,
apiKeyEnvVar: ctx.provider.apiKeyEnvVar,
prefixes: ctx.provider.prefixes ?? [],
headers: ep.headers,
authScheme: ep.authScheme ?? "bearer",
streamFormatOverride: ep.streamFormat,
};
const transport = new OpenAIProviderTransport(remoteProvider, finalModel, apiKey);
return new ComposedHandler(transport, ctx.targetModel, finalModel, ctx.port, {
adapter: openAiFamilyAdapter(wire.api, finalModel),
tokenStrategy: "delta-aware",
...ctx.sharedOpts,
connection,
});
}
case "anthropic": {
const remoteProvider: RemoteProvider = {
name: ctx.provider.name,
baseUrl,
apiPath,
apiKeyEnvVar: ctx.provider.apiKeyEnvVar,
prefixes: ctx.provider.prefixes ?? [],
headers: ep.headers,
authScheme: ep.authScheme ?? "x-api-key",
streamFormatOverride: ep.streamFormat,
};
const transport = new AnthropicProviderTransport(remoteProvider, apiKey);
const adapter = new AnthropicAPIFormat(finalModel, ctx.provider.name);
return new ComposedHandler(transport, ctx.targetModel, finalModel, ctx.port, {
adapter,
...ctx.sharedOpts,
connection,
});
}
case "gemini":
case "ollamacloud": {
// Phase 3 supports openai/anthropic/litellm transports. Gemini and
// ollamacloud need dedicated transport classes that accept URL+key
// directly — those signatures aren't currently available. Deferred.
console.error(
`[claudish] Custom endpoint '${ep.displayName}' uses transport='${ep.transport}' which is not yet supported by runtime registration. Use transport in {openai, anthropic, litellm}.`
);
return null;
}
}
}
/**
* Resolve a custom endpoint's API key, expanding ${VAR_NAME} env var references.
*
* Resolution order:
* 1. `${VAR_NAME}` → process.env[VAR_NAME] (empty string if unset).
* 2. Anything else → returned as-is (a literal key).
*
* NOTE: `op://...` apiKeys are NOT resolved here. They are pre-resolved at
* startup (index.ts `applyCustomEndpointOpKeys()`) via the SDK into the
* `CUSTOM_<NAME>_KEY` env var, which `createHandler` reads FIRST. This keeps
* this function synchronous (handler construction can't await the async SDK).
* A bare `op://...` literal that reaches here (no pre-resolved env value) is
* returned verbatim — which the upstream provider will reject as an invalid key.
*
* Exported for unit testing.
*/
export function resolveCustomEndpointApiKey(ep: CustomEndpoint): string {
// Absent for `authScheme: "none"`, where the schema requires it to be omitted.
// An empty string is the correct answer there: every transport treats a falsy
// key as "emit no auth header".
const literal = ep.apiKey ?? "";
const match = literal.match(/^\$\{([A-Z_][A-Z0-9_]*)\}$/i);
if (match) {
return process.env[match[1]] ?? "";
}
return literal;
}
/**
* The endpoint's CONFIG-DECLARED key, shaped for the credential authority's
* sync chain (env → aliases → config.apiKeys → declared).
*
* Returns `undefined` — meaning "no declared key, keep resolving" — for:
* - an `op://` ref: the authority's ASYNC op-source step owns those (it resolves
* them into CUSTOM_<NAME>_KEY). Returning the literal ref here would satisfy
* the sync chain and short-circuit that step, signing requests with the
* string "op://…" → 401.
* - an unset `${VAR}`: resolveCustomEndpointApiKey yields "" — genuinely no
* credential, so the endpoint must stay unavailable.
*
* Exported for unit testing.
*/
export function resolveDeclaredEndpointKey(ep: CustomEndpoint): string | undefined {
const declared = ep.apiKey?.trim();
if (!declared) return undefined;
if (declared.startsWith("op://")) return undefined;
return resolveCustomEndpointApiKey(ep) || undefined;
}
function stripTrailingSlash(url: string): string {
return url.replace(/\/+$/, "");
}