@oscharko-dev/keiko-server 0.2.0

package/dist/gateway-setup.js

@@ -0,0 +1,896 @@
+// First-run gateway setup for non-technical UI users. The browser provides a base URL, API token,
+// and optionally a Figma PAT; the loopback BFF builds the local provider config, performs a real
+// chat-completions smoke call, stores the resulting config on disk with private permissions, and
+// updates the in-memory runtime config without exposing credentials back to the browser.
+import { resolveEvidenceDir } from "@oscharko-dev/keiko-evidence";
+import { apiKeyHeaderValue, ConfigInvalidError, DEFAULT_API_KEY_HEADER_NAME, Gateway, createDefaultChatCapability, listConfiguredCapabilities, normalizeApiKeyHeaderName, parseGatewayConfig, toSafeObject, validateBaseUrl, } from "@oscharko-dev/keiko-model-gateway";
+import { gatewayFetch, readJsonCapped } from "@oscharko-dev/keiko-model-gateway/internal/http";
+import { redact } from "@oscharko-dev/keiko-security";
+import { errorBody } from "./routes.js";
+import { currentGatewayConfig, currentGatewayEgressConfig } from "./deps.js";
+import { CONVERSATION_SYSTEM_PROMPT } from "./conversation-prompt.js";
+import { classifyFigmaTransportError, FigmaConnectorError, } from "./qualityIntelligence/figma/figmaConnectorErrors.js";
+import { classifyTokenFailure } from "./qualityIntelligence/figma/figmaTokenSource.js";
+import { persistSealedGatewayConfig } from "./credentialPersistence.js";
+const MAX_BODY_BYTES = 64_000;
+// Issue #144: exported so discovery-normalization tests can pin the slice cap
+// without hardcoding the number. The discovery surface is a public seam.
+export const MAX_DISCOVERED_MODELS = 100;
+const MAX_DEPLOYMENT_NAMES = 100;
+const MAX_MODEL_ID_LENGTH = 160;
+const DISCOVERED_MODEL_SMOKE_TIMEOUT_MS = 15_000;
+const DEPLOYMENT_SMOKE_TIMEOUT_MS = 30_000;
+const FIGMA_CREDENTIAL_SMOKE_TIMEOUT_MS = 15_000;
+const FIGMA_CREDENTIAL_SMOKE_RESPONSE_BYTES = 64_000;
+const SETUP_SMOKE_CONCURRENCY = 4;
+const CHAT_COMPATIBLE_MODES = new Set(["chat", "completion", "responses"]);
+const EMBEDDING_ID_PATTERN = /(?:^|[-_/. ])(?:text-)?embed(?:ding)?s?(?:[-_/. ]|$)|ada-002(?:$|[-_/. ])/i;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRouteResult(value) {
+    return isRecord(value) && typeof value.status === "number";
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped) {
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function normalizeBaseUrl(raw) {
+    let value = raw.trim().replace(/\/+$/u, "");
+    if (value.endsWith("/chat/completions")) {
+        value = value.slice(0, -"/chat/completions".length).replace(/\/+$/u, "");
+    }
+    return value;
+}
+function candidateBaseUrls(baseUrl) {
+    const primary = normalizeBaseUrl(baseUrl);
+    const candidates = [primary];
+    try {
+        const url = new URL(primary);
+        if (url.hostname.endsWith(".services.ai.azure.com")) {
+            const openAiV1 = `${url.origin}/openai/v1`;
+            if (url.pathname === "" || url.pathname === "/") {
+                candidates.push(`${url.origin}/openai/v1`);
+            }
+            else if (primary.endsWith("/openai")) {
+                candidates.push(`${primary}/v1`);
+            }
+            else if (primary !== openAiV1 && !primary.endsWith("/openai/v1")) {
+                candidates.push(openAiV1);
+            }
+        }
+        else if (!primary.endsWith("/v1")) {
+            candidates.push(`${primary}/v1`);
+        }
+    }
+    catch {
+        if (!primary.endsWith("/v1")) {
+            candidates.push(`${primary}/v1`);
+        }
+    }
+    return Array.from(new Set(candidates));
+}
+function isAzureFoundryBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        return url.hostname.endsWith(".services.ai.azure.com");
+    }
+    catch {
+        return false;
+    }
+}
+function providerRaw(modelId, baseUrl, apiKey, options = {}) {
+    const defaultCapability = options.embeddingModelIds?.includes(modelId) === true
+        ? createDefaultEmbeddingCapabilityForSetup(modelId)
+        : createDefaultChatCapability(modelId);
+    return {
+        modelId,
+        baseUrl,
+        apiKey,
+        apiKeyHeaderName: options.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME,
+        capability: options.imageInputModelIds?.includes(modelId) === true
+            ? { ...defaultCapability, supportsImageInput: true }
+            : defaultCapability,
+        timeoutMs: options.timeoutMs ?? 30_000,
+        maxRetries: options.maxRetries ?? 2,
+        retryBaseDelayMs: options.retryBaseDelayMs ?? 500,
+    };
+}
+function isLikelyEmbeddingModelId(modelId) {
+    return EMBEDDING_ID_PATTERN.test(modelId);
+}
+function createDefaultEmbeddingCapabilityForSetup(modelId) {
+    return {
+        id: modelId,
+        kind: "embedding",
+        contextWindow: 8_191,
+        maxOutputTokens: 0,
+        toolCalling: false,
+        structuredOutput: false,
+        streaming: false,
+        supportsImageInput: false,
+        supportsDocumentInput: false,
+        workflowEligible: false,
+        costClass: "low",
+        latencyClass: "fast",
+        throughputHint: "runtime-configured embedding endpoint",
+        preferredUseCases: ["Embeddings"],
+        knownLimitations: [
+            "Runtime-configured capability; validate against the target endpoint before production use",
+        ],
+    };
+}
+function mergeChatAndEmbeddingModelIds(chatModelIds, deploymentNames) {
+    const merged = [...chatModelIds];
+    const seen = new Set(merged);
+    for (const modelId of deploymentNames) {
+        if (!isLikelyEmbeddingModelId(modelId) || seen.has(modelId)) {
+            continue;
+        }
+        seen.add(modelId);
+        merged.push(modelId);
+    }
+    return merged;
+}
+function embeddingModelIdsFromDeployments(deploymentNames) {
+    return deploymentNames.filter(isLikelyEmbeddingModelId);
+}
+function buildRawConfig(baseUrl, apiKey, modelIds, options = {}) {
+    return {
+        providers: modelIds.map((modelId) => providerRaw(modelId, baseUrl, apiKey, options)),
+        circuitBreaker: { failureThreshold: 5, cooldownMs: 30_000, halfOpenProbes: 2 },
+    };
+}
+function currentImageInputModelIds(config) {
+    return (config?.capabilities
+        ?.filter((capability) => capability.kind === "chat" && capability.supportsImageInput)
+        .map((capability) => capability.id) ?? []);
+}
+function rawConfigFromCurrent(config, figmaAccessToken) {
+    return {
+        providers: config.providers.map((provider) => {
+            const capability = config.capabilities?.find((item) => item.id === provider.modelId);
+            return {
+                modelId: provider.modelId,
+                baseUrl: provider.baseUrl,
+                apiKey: provider.apiKey,
+                apiKeyHeaderName: provider.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME,
+                timeoutMs: provider.timeoutMs,
+                maxRetries: provider.maxRetries,
+                retryBaseDelayMs: provider.retryBaseDelayMs,
+                ...(capability === undefined ? {} : { capability }),
+            };
+        }),
+        circuitBreaker: config.circuitBreaker,
+        ...(config.capabilities === undefined ? {} : { capabilities: config.capabilities }),
+        ...(config.grounding === undefined ? {} : { grounding: config.grounding }),
+        ...(figmaAccessToken === undefined ? {} : { figma: { accessToken: figmaAccessToken } }),
+    };
+}
+function withInheritedEgress(rawConfig, egress) {
+    if (egress === undefined || Object.hasOwn(rawConfig, "egress")) {
+        return rawConfig;
+    }
+    return { ...rawConfig, egress };
+}
+function modelsEndpoint(baseUrl) {
+    return `${baseUrl}/models`;
+}
+function modelInfoEndpointCandidates(baseUrl) {
+    const normalized = normalizeBaseUrl(baseUrl);
+    return [`${normalized}/model/info`];
+}
+function apiKeyHeaders(apiKey, apiKeyHeaderName) {
+    return { [apiKeyHeaderName]: apiKeyHeaderValue(apiKeyHeaderName, apiKey) };
+}
+function hasDisallowedModelIdCharacter(id) {
+    for (let index = 0; index < id.length; index += 1) {
+        const code = id.charCodeAt(index);
+        if (code <= 31 || code === 127) {
+            return true;
+        }
+    }
+    return false;
+}
+function isUsableModelId(id) {
+    return id.length > 0 && id.length <= MAX_MODEL_ID_LENGTH && !hasDisallowedModelIdCharacter(id);
+}
+function modelIdFromKnownFields(item) {
+    for (const field of ["id", "model_name", "model", "deployment_name", "deploymentName"]) {
+        const value = item[field];
+        if (typeof value === "string") {
+            const id = value.trim();
+            if (isUsableModelId(id)) {
+                return id;
+            }
+        }
+    }
+    return undefined;
+}
+function nestedRecord(value, key) {
+    const nested = value[key];
+    return isRecord(nested) ? nested : undefined;
+}
+function modelModeFromDiscoveryItem(item) {
+    const modelInfo = nestedRecord(item, "model_info");
+    const litellmParams = nestedRecord(item, "litellm_params");
+    const candidates = [item.mode, modelInfo?.mode, litellmParams?.mode];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim().length > 0) {
+            return candidate.trim().toLowerCase();
+        }
+    }
+    return undefined;
+}
+// Issue #144: exported as part of the discovery-normalization seam so a
+// sibling test file can drive it with synthetic payloads. Behaviour unchanged
+// — only the visibility is widened.
+export function isExplicitlyNonChatModel(item) {
+    const capabilities = isRecord(item.capabilities) ? item.capabilities : undefined;
+    if (capabilities?.chat_completion === false) {
+        return true;
+    }
+    const mode = modelModeFromDiscoveryItem(item);
+    return mode !== undefined && !CHAT_COMPATIBLE_MODES.has(mode);
+}
+// Issue #144: exported as part of the discovery-normalization seam. Behaviour
+// unchanged. Returns undefined for unknown/non-record/non-chat/malformed input
+// so callers can drop the entry silently and keep healthy peers.
+export function modelIdFromDiscoveryItem(item) {
+    if (!isRecord(item) || isExplicitlyNonChatModel(item)) {
+        return undefined;
+    }
+    return modelIdFromKnownFields(item);
+}
+// Issue #144: exported as part of the discovery-normalization seam. Behaviour
+// unchanged. Throws on schema-level malformation (no data array) and on the
+// "every entry filtered" terminal case so the caller (production path) returns
+// an honest error rather than a silently-empty model list.
+export function parseModelList(payload) {
+    if (!isRecord(payload) || !Array.isArray(payload.data)) {
+        throw new Error("model discovery response must contain a data array");
+    }
+    const ids = [];
+    for (const item of payload.data) {
+        const id = modelIdFromDiscoveryItem(item);
+        if (id !== undefined) {
+            ids.push(id);
+        }
+    }
+    const unique = Array.from(new Set(ids));
+    if (unique.length === 0) {
+        throw new Error("model discovery returned no model ids");
+    }
+    return unique.slice(0, MAX_DISCOVERED_MODELS);
+}
+// Issue #144 AC #4: the public discovery-normalization seam. Test target. Pure
+// wrapper around `parseModelList` so the AC ("Discovery handles additional
+// customer gateway models without requiring code changes for each model name")
+// can be pinned against a stable export name even if the internal helper is
+// reshaped later.
+export function normalizeDiscoveryPayload(payload) {
+    return parseModelList(payload);
+}
+async function fetchDiscoveryJson(url, apiKey, apiKeyHeaderName, egress) {
+    const response = await gatewayFetch(url, {
+        method: "GET",
+        headers: apiKeyHeaders(apiKey, apiKeyHeaderName),
+        signal: AbortSignal.timeout(30_000),
+        ...(egress !== undefined ? { egress } : {}),
+    });
+    if (!response.ok) {
+        throw new Error(`model discovery returned HTTP ${String(response.status)}`);
+    }
+    try {
+        return await readJsonCapped(response);
+    }
+    catch {
+        throw new Error("model discovery response was not readable JSON");
+    }
+}
+async function discoverLiteLlmModelInfo(baseUrl, apiKey, apiKeyHeaderName, egress) {
+    for (const endpoint of modelInfoEndpointCandidates(baseUrl)) {
+        try {
+            return parseModelList(await fetchDiscoveryJson(endpoint, apiKey, apiKeyHeaderName, egress));
+        }
+        catch {
+            // /model/info is a LiteLLM-specific enrichment endpoint. If it is absent or blocked,
+            // continue with OpenAI-compatible /models discovery so customer gateways are not broken.
+        }
+    }
+    return undefined;
+}
+async function defaultGatewayModelDiscovery(baseUrl, apiKey, apiKeyHeaderName = DEFAULT_API_KEY_HEADER_NAME, egress) {
+    const litellmModels = await discoverLiteLlmModelInfo(baseUrl, apiKey, apiKeyHeaderName, egress);
+    if (litellmModels !== undefined) {
+        return litellmModels;
+    }
+    return parseModelList(await fetchDiscoveryJson(modelsEndpoint(baseUrl), apiKey, apiKeyHeaderName, egress));
+}
+function deploymentNameValues(value) {
+    if (typeof value === "string") {
+        return value.split(/[\n,]/u);
+    }
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return value;
+    }
+    return undefined;
+}
+function normalizeDeploymentNames(values) {
+    return Array.from(new Set(values.map((item) => item.trim()).filter((item) => item.length > 0)));
+}
+function parseDeploymentNames(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const values = deploymentNameValues(value);
+    if (values === undefined) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "deploymentNames must be a string or an array of strings."),
+        };
+    }
+    const names = normalizeDeploymentNames(values);
+    if (names.length > MAX_DEPLOYMENT_NAMES) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "deploymentNames exceeds the model setup limit."),
+        };
+    }
+    if (names.some((name) => !isUsableModelId(name))) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "deploymentNames contains an invalid model id."),
+        };
+    }
+    return names;
+}
+function parseImageInputModelIds(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const values = deploymentNameValues(value);
+    if (values === undefined) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "imageInputModelIds must be a string or an array of strings."),
+        };
+    }
+    const names = normalizeDeploymentNames(values);
+    if (names.length > MAX_DEPLOYMENT_NAMES) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "imageInputModelIds exceeds the model setup limit."),
+        };
+    }
+    if (names.some((name) => !isUsableModelId(name))) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "imageInputModelIds contains an invalid model id."),
+        };
+    }
+    return names;
+}
+function validateSetupConnection(baseUrl, apiKey, apiKeyHeaderName, env) {
+    try {
+        parseGatewayConfig(buildRawConfig(baseUrl, apiKey, ["setup-validation"], { apiKeyHeaderName }), env);
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof ConfigInvalidError) {
+            return { status: 400, body: errorBody("BAD_REQUEST", error.message) };
+        }
+        throw error;
+    }
+}
+// Issue #144: pure smoke-test loop extracted from `defaultGatewaySetupTester`
+// for testability. Concurrency is a parameter so callers (tests) can pin peak
+// in-flight count deterministically. Original-order preservation among
+// survivors is part of the observable contract — pinned by gateway-setup tests
+// that assert tested-model-id order matches input order with failed entries
+// dropped.
+//
+// Throws with the exact error message that `defaultGatewaySetupTester` has
+// always thrown so existing call sites and tests keep compiling.
+export async function smokeTestCandidates(candidates, probe, concurrency) {
+    const tested = Array(candidates.length).fill(undefined);
+    let next = 0;
+    async function worker() {
+        while (next < candidates.length) {
+            const index = next;
+            next += 1;
+            const modelId = candidates[index];
+            if (modelId === undefined) {
+                continue;
+            }
+            try {
+                await probe(modelId);
+                tested[index] = modelId;
+            }
+            catch {
+                // Probe rejection is the documented signal that this candidate is not
+                // chat-callable. We drop it silently so healthy peers still surface.
+            }
+        }
+    }
+    const workerCount = Math.max(1, Math.min(concurrency, candidates.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    const accepted = tested.filter((modelId) => modelId !== undefined);
+    if (accepted.length === 0) {
+        throw new Error("no discovered model accepted the chat-completions smoke test");
+    }
+    return accepted;
+}
+async function defaultGatewaySetupTester(config, candidateModelIds) {
+    const gateway = new Gateway(config);
+    return smokeTestCandidates(candidateModelIds, async (modelId) => {
+        await gateway.chat({
+            modelId,
+            messages: [
+                { role: "system", content: CONVERSATION_SYSTEM_PROMPT },
+                { role: "user", content: "Reply with exactly: OK" },
+            ],
+        });
+    }, SETUP_SMOKE_CONCURRENCY);
+}
+const FIGMA_ME_ENDPOINT = "https://api.figma.com/v1/me";
+function figmaReason(body) {
+    if (!isRecord(body))
+        return undefined;
+    const reason = body.err ?? body.message;
+    return typeof reason === "string" ? reason : undefined;
+}
+async function defaultFigmaCredentialTester(accessToken, egress) {
+    try {
+        const response = await gatewayFetch(FIGMA_ME_ENDPOINT, {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                "X-Figma-Token": accessToken,
+            },
+            redirect: "manual",
+            signal: AbortSignal.timeout(FIGMA_CREDENTIAL_SMOKE_TIMEOUT_MS),
+            ...(egress !== undefined ? { egress } : {}),
+        });
+        let body;
+        try {
+            body = await readJsonCapped(response, FIGMA_CREDENTIAL_SMOKE_RESPONSE_BYTES);
+        }
+        catch {
+            throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+        }
+        if (!response.ok) {
+            throw classifyTokenFailure(response.status, figmaReason(body));
+        }
+        if (!isRecord(body)) {
+            throw new FigmaConnectorError("FIGMA_INTERNAL");
+        }
+    }
+    catch (error) {
+        if (error instanceof FigmaConnectorError) {
+            throw error;
+        }
+        throw new FigmaConnectorError(classifyFigmaTransportError(error));
+    }
+}
+// Seals the verified raw config's secrets into their local vaults and writes a credential-free
+// keiko.config.json (Issue #1320). `deps.evidenceDir` is the resolved evidence root used by the
+// encrypted Figma PAT vault; it is resolved defensively so persistence never depends on the optional
+// field being pre-populated.
+function persistGatewayConfig(raw, storagePath, deps) {
+    persistSealedGatewayConfig(raw, {
+        env: deps.env,
+        storagePath,
+        evidenceDir: resolveEvidenceDir(deps.evidenceDir, deps.env),
+    });
+}
+function normalizeSetupApiKeyHeaderName(value) {
+    try {
+        return normalizeApiKeyHeaderName(value, "apiKeyHeaderName", DEFAULT_API_KEY_HEADER_NAME);
+    }
+    catch (error) {
+        if (error instanceof ConfigInvalidError) {
+            return { status: 400, body: errorBody("BAD_REQUEST", error.message) };
+        }
+        throw error;
+    }
+}
+function readSetupModelLists(raw) {
+    const deploymentNames = parseDeploymentNames(raw.deploymentNames);
+    if (isRouteResult(deploymentNames)) {
+        return deploymentNames;
+    }
+    const imageInputModelIds = parseImageInputModelIds(raw.imageInputModelIds);
+    if (isRouteResult(imageInputModelIds)) {
+        return imageInputModelIds;
+    }
+    return { deploymentNames, imageInputModelIds };
+}
+function optionalSetupSecret(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        return { status: 400, body: errorBody("BAD_REQUEST", `${path} must be a string.`) };
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function hasNonBlankStringField(raw, key) {
+    const value = raw[key];
+    return typeof value === "string" && value.trim().length > 0;
+}
+function hasNonEmptyListField(raw, key) {
+    const value = raw[key];
+    if (typeof value === "string") {
+        return normalizeDeploymentNames(deploymentNameValues(value) ?? []).length > 0;
+    }
+    return Array.isArray(value) && value.some((item) => typeof item === "string" && item.trim());
+}
+function shouldPreserveExisting(raw, current) {
+    return raw.preserveExisting === true && current !== undefined;
+}
+function firstProvider(current) {
+    return current?.providers[0];
+}
+function trimmedSubmittedString(raw, key) {
+    const value = raw[key];
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function submittedOrInheritedString(raw, key, inherited, preserveExisting) {
+    return trimmedSubmittedString(raw, key) ?? (preserveExisting ? (inherited ?? "") : "");
+}
+function setupApiKeyHeaderSource(raw, provider, preserveExisting) {
+    if (raw.apiKeyHeaderName !== undefined || !preserveExisting) {
+        return raw.apiKeyHeaderName;
+    }
+    return provider?.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME;
+}
+function readSetupGatewayCredentials(raw, env, current, preserveExisting) {
+    const provider = firstProvider(current);
+    const baseUrl = submittedOrInheritedString(raw, "baseUrl", provider?.baseUrl, preserveExisting);
+    const apiKey = submittedOrInheritedString(raw, "apiKey", provider?.apiKey, preserveExisting);
+    if (baseUrl.length === 0 || apiKey.length === 0) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "baseUrl and apiKey are required.") };
+    }
+    const apiKeyHeaderSource = setupApiKeyHeaderSource(raw, provider, preserveExisting);
+    const apiKeyHeaderName = normalizeSetupApiKeyHeaderName(apiKeyHeaderSource);
+    if (isRouteResult(apiKeyHeaderName)) {
+        return apiKeyHeaderName;
+    }
+    const invalidConnection = validateSetupConnection(baseUrl, apiKey, apiKeyHeaderName, env);
+    if (invalidConnection !== undefined) {
+        return invalidConnection;
+    }
+    return { baseUrl, apiKey, apiKeyHeaderName };
+}
+function resolveSetupModelLists(modelLists, current, preserveExisting) {
+    const existing = preserveExisting ? current : undefined;
+    return {
+        deploymentNames: existing !== undefined && modelLists.deploymentNames.length === 0
+            ? existing.providers.map((item) => item.modelId)
+            : modelLists.deploymentNames,
+        imageInputModelIds: existing !== undefined && modelLists.imageInputModelIds.length === 0
+            ? currentImageInputModelIds(existing)
+            : modelLists.imageInputModelIds,
+    };
+}
+function setupRequiresGatewayVerification(raw, preserveExisting) {
+    return (!preserveExisting ||
+        hasNonBlankStringField(raw, "baseUrl") ||
+        hasNonBlankStringField(raw, "apiKey") ||
+        hasNonBlankStringField(raw, "apiKeyHeaderName") ||
+        hasNonEmptyListField(raw, "deploymentNames") ||
+        hasNonEmptyListField(raw, "imageInputModelIds"));
+}
+function readSetupRequest(raw, env, current) {
+    if (!isRecord(raw)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    const preserveExisting = shouldPreserveExisting(raw, current);
+    const credentials = readSetupGatewayCredentials(raw, env, current, preserveExisting);
+    if (isRouteResult(credentials)) {
+        return credentials;
+    }
+    const modelLists = readSetupModelLists(raw);
+    if (isRouteResult(modelLists)) {
+        return modelLists;
+    }
+    const figmaAccessToken = optionalSetupSecret(raw.figmaAccessToken, "figmaAccessToken");
+    if (isRouteResult(figmaAccessToken)) {
+        return figmaAccessToken;
+    }
+    const resolvedModelLists = resolveSetupModelLists(modelLists, current, preserveExisting);
+    return {
+        ...credentials,
+        deploymentNames: resolvedModelLists.deploymentNames,
+        imageInputModelIds: resolvedModelLists.imageInputModelIds,
+        figmaAccessToken: figmaAccessToken ?? current?.figma?.accessToken,
+        verifyGateway: setupRequiresGatewayVerification(raw, preserveExisting),
+        verifyFigmaCredential: figmaAccessToken !== undefined,
+    };
+}
+function safeError(error, secrets) {
+    const concreteSecrets = secrets.filter((secret) => secret !== undefined);
+    if (error instanceof Error) {
+        return redact(error.message, concreteSecrets);
+    }
+    return "Gateway setup failed.";
+}
+function assertImageInputModelsWereTested(imageInputModelIds, testedModelIds) {
+    if (imageInputModelIds.length === 0)
+        return;
+    const tested = new Set(testedModelIds);
+    if (imageInputModelIds.some((modelId) => !tested.has(modelId))) {
+        throw new Error("imageInputModelIds must match tested chat-callable model ids.");
+    }
+}
+function validationConfigForSetup(input) {
+    const validationRawConfig = buildRawConfig(input.baseUrl, input.apiKey, ["setup-validation"], {
+        apiKeyHeaderName: input.apiKeyHeaderName,
+        imageInputModelIds: input.imageInputModelIds,
+    });
+    return parseGatewayConfig(withInheritedEgress(validationRawConfig, input.egress), input.env);
+}
+async function candidateModelIdsForSetup(input, validationConfig) {
+    return input.deploymentNames.length > 0
+        ? input.deploymentNames
+        : input.discovery(input.baseUrl, input.apiKey, input.apiKeyHeaderName, validationConfig.egress);
+}
+function finalRawConfigForSetup(input, testedModelIds) {
+    const embeddingModelIds = embeddingModelIdsFromDeployments(input.deploymentNames);
+    const configuredModelIds = mergeChatAndEmbeddingModelIds(testedModelIds, input.deploymentNames);
+    const rawConfig = buildRawConfig(input.baseUrl, input.apiKey, configuredModelIds, {
+        apiKeyHeaderName: input.apiKeyHeaderName,
+        imageInputModelIds: input.imageInputModelIds,
+        embeddingModelIds,
+    });
+    return {
+        ...rawConfig,
+        ...(input.current?.grounding === undefined ? {} : { grounding: input.current.grounding }),
+        ...(input.figmaAccessToken === undefined
+            ? {}
+            : { figma: { accessToken: input.figmaAccessToken } }),
+    };
+}
+function skippedModelIdsForSetup(candidateModelIds, testedModelIds, deploymentNames) {
+    const acceptedModelIds = new Set([
+        ...testedModelIds,
+        ...embeddingModelIdsFromDeployments(deploymentNames),
+    ]);
+    return candidateModelIds.filter((modelId) => !acceptedModelIds.has(modelId));
+}
+async function verifySetupCandidate(input) {
+    // Defence-in-depth: never send the credential to a candidate URL that has not passed the same
+    // scheme/credential/loopback validation as the originally submitted base URL.
+    validateBaseUrl(input.baseUrl, "candidate");
+    const validationConfig = validationConfigForSetup(input);
+    const candidateModelIds = await candidateModelIdsForSetup(input, validationConfig);
+    const smokeTimeoutMs = input.deploymentNames.length > 0
+        ? DEPLOYMENT_SMOKE_TIMEOUT_MS
+        : DISCOVERED_MODEL_SMOKE_TIMEOUT_MS;
+    const candidateRawConfig = buildRawConfig(input.baseUrl, input.apiKey, candidateModelIds, {
+        apiKeyHeaderName: input.apiKeyHeaderName,
+        timeoutMs: smokeTimeoutMs,
+        // One retry (not zero) so a single transient blip — 429 rate-limit, brief timeout, momentary
+        // content-filter — does not permanently exclude an otherwise-working model from the setup and
+        // brand it to the user as incompatible. Still bounded so setup latency stays predictable.
+        maxRetries: 1,
+        imageInputModelIds: input.imageInputModelIds,
+    });
+    const candidateConfig = parseGatewayConfig(withInheritedEgress(candidateRawConfig, input.egress), input.env);
+    const testedModelIds = await input.tester(candidateConfig, candidateModelIds);
+    assertImageInputModelsWereTested(input.imageInputModelIds, testedModelIds);
+    const rawConfigWithOptionalBlocks = finalRawConfigForSetup(input, testedModelIds);
+    const config = parseGatewayConfig(withInheritedEgress(rawConfigWithOptionalBlocks, input.egress), input.env);
+    return {
+        rawConfig: rawConfigWithOptionalBlocks,
+        config,
+        testedModelIds,
+        skippedModelIds: skippedModelIdsForSetup(candidateModelIds, testedModelIds, input.deploymentNames),
+    };
+}
+function setupSuccessResult(config, testedModelIds, skippedModelIds) {
+    const testedModelId = testedModelIds[0] ?? "unknown";
+    return {
+        status: 200,
+        body: {
+            ok: true,
+            testedModelId,
+            testedModelIds,
+            skippedModelIds,
+            providerCount: config.providers.length,
+            models: listConfiguredCapabilities(config),
+            config: toSafeObject(config),
+        },
+    };
+}
+function setupFailureResult(errors) {
+    return {
+        status: 502,
+        body: errorBody("GATEWAY_SETUP_FAILED", `Credentials could not be verified. ${errors.join(" ")}`),
+    };
+}
+function figmaFailureStatus(code) {
+    switch (code) {
+        case "FIGMA_TOKEN_INVALID":
+        case "FIGMA_TOKEN_EXPIRED":
+        case "FIGMA_TOKEN_REVOKED":
+        case "FIGMA_INSUFFICIENT_SCOPE":
+        case "FIGMA_CONSENT_REQUIRED":
+            return 400;
+        case "FIGMA_RATE_LIMITED":
+            return 429;
+        default:
+            return 502;
+    }
+}
+function figmaCredentialFailureResult(error, request) {
+    if (error instanceof FigmaConnectorError) {
+        return {
+            status: figmaFailureStatus(error.code),
+            body: errorBody(error.code, error.message),
+        };
+    }
+    return {
+        status: 502,
+        body: errorBody("FIGMA_EGRESS_FAILED", safeError(error, [request.figmaAccessToken, request.apiKey, request.baseUrl])),
+    };
+}
+async function verifySubmittedFigmaCredential(request, deps) {
+    if (!request.verifyFigmaCredential || request.figmaAccessToken === undefined) {
+        return undefined;
+    }
+    const tester = deps.figmaCredentialTester ?? defaultFigmaCredentialTester;
+    try {
+        await tester(request.figmaAccessToken, currentGatewayEgressConfig(deps));
+        return undefined;
+    }
+    catch (error) {
+        return figmaCredentialFailureResult(error, request);
+    }
+}
+function deploymentNamesRequiredResult() {
+    return {
+        status: 400,
+        body: errorBody("GATEWAY_DEPLOYMENTS_REQUIRED", "Azure AI Foundry endpoints require deployment names from the Deployments tab."),
+    };
+}
+async function readJsonSetupBody(ctx) {
+    let bodyText;
+    try {
+        bodyText = await readBody(ctx.req);
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return {
+                status: 413,
+                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+            };
+        }
+        throw error;
+    }
+    try {
+        return { parsed: JSON.parse(bodyText) };
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+    }
+}
+function gatewayUnavailableResult() {
+    return {
+        status: 500,
+        body: errorBody("GATEWAY_SETUP_UNAVAILABLE", "Gateway setup is unavailable."),
+    };
+}
+async function trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery, current) {
+    const verified = await verifySetupCandidate({
+        baseUrl,
+        apiKey: request.apiKey,
+        apiKeyHeaderName: request.apiKeyHeaderName,
+        deploymentNames: request.deploymentNames,
+        imageInputModelIds: request.imageInputModelIds,
+        tester,
+        discovery,
+        env: deps.env,
+        egress: currentGatewayEgressConfig(deps),
+        figmaAccessToken: request.figmaAccessToken,
+        current,
+    });
+    persistGatewayConfig(verified.rawConfig, gatewayConfig.storagePath, deps);
+    gatewayConfig.set(verified.config, true);
+    return setupSuccessResult(verified.config, verified.testedModelIds, verified.skippedModelIds);
+}
+function setupCandidateError(error, request, baseUrl) {
+    return safeError(error, [request.apiKey, request.baseUrl, baseUrl, request.figmaAccessToken]);
+}
+function saveExistingConfigUpdate(request, current, deps, gatewayConfig) {
+    const rawConfig = rawConfigFromCurrent(current, request.figmaAccessToken);
+    const config = parseGatewayConfig(withInheritedEgress(rawConfig, currentGatewayEgressConfig(deps)), deps.env);
+    persistGatewayConfig(rawConfig, gatewayConfig.storagePath, deps);
+    gatewayConfig.set(config, true);
+    return setupSuccessResult(config, config.providers.map((provider) => provider.modelId), []);
+}
+async function verifyAndSaveExistingConfigUpdate(request, current, deps, gatewayConfig) {
+    const figmaFailure = await verifySubmittedFigmaCredential(request, deps);
+    if (figmaFailure !== undefined) {
+        return figmaFailure;
+    }
+    return saveExistingConfigUpdate(request, current, deps, gatewayConfig);
+}
+function shouldRequireDeploymentNames(request, baseUrlCandidates) {
+    return (request.deploymentNames.length === 0 &&
+        baseUrlCandidates.some((baseUrl) => isAzureFoundryBaseUrl(baseUrl)));
+}
+async function verifyAndSaveGatewaySetup(request, current, deps, gatewayConfig) {
+    const tester = deps.gatewaySetupTester ?? defaultGatewaySetupTester;
+    const discovery = deps.gatewayModelDiscovery ?? defaultGatewayModelDiscovery;
+    const figmaFailure = await verifySubmittedFigmaCredential(request, deps);
+    if (figmaFailure !== undefined) {
+        return figmaFailure;
+    }
+    const baseUrlCandidates = candidateBaseUrls(request.baseUrl);
+    if (shouldRequireDeploymentNames(request, baseUrlCandidates)) {
+        return deploymentNamesRequiredResult();
+    }
+    const errors = [];
+    for (const baseUrl of baseUrlCandidates) {
+        try {
+            return await trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery, current);
+        }
+        catch (error) {
+            errors.push(`candidate ${String(errors.length + 1)}: ${setupCandidateError(error, request, baseUrl)}`);
+        }
+    }
+    return setupFailureResult(errors);
+}
+export async function handleGatewaySetup(ctx, deps) {
+    if (deps.gatewayConfig === undefined) {
+        return gatewayUnavailableResult();
+    }
+    const { gatewayConfig } = deps;
+    const current = currentGatewayConfig(deps);
+    const bodyResult = await readJsonSetupBody(ctx);
+    if ("status" in bodyResult) {
+        return bodyResult;
+    }
+    const request = readSetupRequest(bodyResult.parsed, deps.env, current);
+    if ("status" in request) {
+        return request;
+    }
+    if (!request.verifyGateway && current !== undefined) {
+        return verifyAndSaveExistingConfigUpdate(request, current, deps, gatewayConfig);
+    }
+    return verifyAndSaveGatewaySetup(request, current, deps, gatewayConfig);
+}