Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

18.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

import type forge from "node-forge";
import { authFetch } from "@/features/auth/api";
import { formatFastApiDetail } from "@/lib/format-fastapi-error";
import type { ModelCatalogSnapshotEntry } from "../model-catalog-snapshot";
import type { CustomReasoningConfig } from "../custom-reasoning";


export type ProviderAuthKind = "api_key" | "chatgpt_oauth";
export type ProviderAuthStatus =
  | "disconnected"
  | "connected"
  | "reauthorization_required";

export interface ProviderRegistryEntry {
  provider_type: string;
  display_name: string;
  base_url: string;
  default_models: string[];

  model_capabilities?: Record<string, { vision?: boolean; studio_tools?: boolean }>;
  supports_streaming: boolean;
  supports_vision: boolean;
  supports_tool_calling: boolean;
  /** Unsloth runs its own tool loop (search/code/MCP/RAG) against this provider. */
  supports_studio_tools?: boolean;
  /** Backend-only entry, surfaced through a custom preset rather than the dropdown. */
  hidden?: boolean;
  /** remote = fetch /models; curated = huge catalogs — UI uses defaults + manual IDs only */
  model_list_mode?: "remote" | "curated";

  auth_kind?: ProviderAuthKind;
  base_url_editable?: boolean;
  model_ids_editable?: boolean;
}

export type ProviderApiType = "chat_completions" | "responses";
export type ConnectionApiType = ProviderApiType | "systemone";

export interface ProviderConfig {
  api_type?: ConnectionApiType;
  id: string;
  provider_type: string;
  display_name: string;
  base_url: string;
  is_enabled: boolean;

  has_api_key: boolean;

  auth_kind?: ProviderAuthKind;
  auth_status?: ProviderAuthStatus;
  models?: string[];
  available_models?: string[];
  max_output_tokens?: number | null;
  reasoning_config?: CustomReasoningConfig | null;
  extra_headers?: Record<string, string>;
  shared?: boolean;
  shared_by_owner?: boolean;
  created_at: string;
  updated_at: string;
}

export interface ProviderModelInfo {
  id: string;
  display_name: string;
  context_length?: number | null;
  owned_by?: string | null;
  /** Only the ChatGPT plan catalog reports this; the registry describes the rest. */
  vision?: boolean | null;
  /** Only Ollama's /api/tags reports these; absent is not the same as none. */
  capabilities?: string[] | null;
}

export interface ProviderModelReasoningInfo {
  supported_efforts?: string[] | null;
  mandatory?: boolean | null;
  default_effort?: string | null;
  default_enabled?: boolean | null;
}

export interface ProviderModelCapabilityInfo {
  id: string;
  input_modalities?: string[] | null;
  reasoning?: ProviderModelReasoningInfo | null;
  max_output_tokens?: number | null;
  supported_parameters?: string[] | null;
}

export interface ModelCatalogResponse {
  fetched_at: number;
  providers: Record<string, Record<string, ModelCatalogSnapshotEntry>>;
}

export interface ProviderTestResult {
  success: boolean;
  message: string;
  models_count?: number | null;
}

function parseErrorText(status: number, body: unknown): string {
  if (body && typeof body === "object") {
    const detail = (body as { detail?: unknown }).detail;
    const formatted = formatFastApiDetail(detail);
    if (formatted) return formatted;
    const message = (body as { message?: unknown }).message;
    if (typeof message === "string" && message) return message;
  }
  return `Request failed (${status})`;
}

async function parseJsonOrThrow<T>(response: Response): Promise<T> {
  const body = await response.json().catch(() => null);
  if (!response.ok) {
    throw new Error(parseErrorText(response.status, body));
  }
  return body as T;
}

export function isProviderKeyRotationError(error: unknown): boolean {
  if (!(error instanceof Error)) return false;
  const normalized = error.message.toLowerCase();
  return (
    normalized.includes("public key may have changed") ||
    normalized.includes("server key may have changed")
  );
}

// node-forge (~270 KB) loads with the first key encryption, not with the app.
function loadForge(): Promise<typeof forge> {
  return import("node-forge").then((module) => module.default);
}

let cachedPublicKeyPem: string | null = null;
let cachedForgeKey: forge.pki.rsa.PublicKey | null = null;

export function clearProviderPublicKeyCache(): void {
  cachedPublicKeyPem = null;
  cachedForgeKey = null;
}

async function importProviderPublicKey(
  forceRefresh = false,
): Promise<forge.pki.rsa.PublicKey> {
  if (!forceRefresh && cachedForgeKey) {
    return cachedForgeKey;
  }
  const response = await authFetch("/api/providers/public-key");
  const body = await parseJsonOrThrow<{ public_key: string }>(response);
  const publicKeyPem = body.public_key?.trim();
  if (!publicKeyPem) {
    throw new Error("Provider public key is missing.");
  }
  if (!forceRefresh && cachedPublicKeyPem === publicKeyPem && cachedForgeKey) {
    return cachedForgeKey;
  }
  const { pki } = await loadForge();
  const forgeKey = pki.publicKeyFromPem(publicKeyPem);
  cachedPublicKeyPem = publicKeyPem;
  cachedForgeKey = forgeKey;
  return forgeKey;
}

const ENVELOPE_VERSION = "v1";
const ENVELOPE_AAD = "unsloth-studio-provider-key-v1";
const AES_KEY_BYTES = 32;
const NONCE_BYTES = 12;

function randomBinaryString(byteLength: number): string {
  const bytes = new Uint8Array(byteLength);
  crypto.getRandomValues(bytes);
  return String.fromCharCode(...bytes);
}

/** RSA-OAEP wraps only the 32-byte content key: wrapping the API key itself caps it at 190 bytes. */
export async function encryptProviderApiKey(
  plaintextApiKey: string,
  forceRefresh = false,
): Promise<string> {
  const key = await importProviderPublicKey(forceRefresh);
  const forge = await loadForge();
  const aesKey = randomBinaryString(AES_KEY_BYTES);
  const nonce = randomBinaryString(NONCE_BYTES);

  const cipher = forge.cipher.createCipher("AES-GCM", aesKey);
  cipher.start({ iv: nonce, additionalData: ENVELOPE_AAD, tagLength: 128 });
  // forge ciphers take bytes: without encodeUtf8 a non-ASCII key loses all but each low byte.
  cipher.update(forge.util.createBuffer(forge.util.encodeUtf8(plaintextApiKey)));
  if (!cipher.finish()) {
    throw new Error("Failed to encrypt API key.");
  }

  const wrappedKey = key.encrypt(aesKey, "RSA-OAEP", {
    md: forge.md.sha256.create(),
    mgf1: { md: forge.md.sha256.create() },
  });
  return [
    ENVELOPE_VERSION,
    forge.util.encode64(wrappedKey),
    forge.util.encode64(nonce),
    forge.util.encode64(cipher.output.getBytes() + cipher.mode.tag.getBytes()),
  ].join(".");
}

export async function listProviderRegistry(): Promise<ProviderRegistryEntry[]> {
  // include_hidden returns the self-hosted presets carrying the studio-tools capability; older
  // backends ignore it, leaving the capability unknown.
  const response = await authFetch(
    "/api/providers/registry?include_hidden=true&include_oauth=true",
  );
  return parseJsonOrThrow<ProviderRegistryEntry[]>(response);
}

export async function listProviderConfigs(): Promise<ProviderConfig[]> {
  const response = await authFetch("/api/providers/");
  return parseJsonOrThrow<ProviderConfig[]>(response);
}

export async function createProviderConfig(payload: {
  providerType: string;
  displayName: string;
  baseUrl?: string | null;
  apiType?: ConnectionApiType;
  models?: string[];
  availableModels?: string[];
  maxOutputTokens?: number | null;
  reasoningConfig?: CustomReasoningConfig | null;
  extraHeaders?: Record<string, string>;
  shared?: boolean;
  apiKey?: string;
}): Promise<ProviderConfig> {
  return withApiKeyEncryptionRetry(payload.apiKey ?? "", async (encryptedApiKey) => {
    const response = await authFetch("/api/providers/", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        provider_type: payload.providerType,
        display_name: payload.displayName,
        base_url: payload.baseUrl ?? null,
        ...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
        models: payload.models ?? [],
        available_models: payload.availableModels ?? [],
        ...(payload.maxOutputTokens === undefined
          ? {}
          : { max_output_tokens: payload.maxOutputTokens }),
        ...(payload.reasoningConfig === undefined
          ? {}
          : { reasoning_config: payload.reasoningConfig }),
        ...(payload.extraHeaders === undefined
          ? {}
          : { extra_headers: payload.extraHeaders }),
        ...(payload.shared === undefined ? {} : { shared: payload.shared }),
        encrypted_api_key: encryptedApiKey,
      }),
    });
    return parseJsonOrThrow<ProviderConfig>(response);
  });
}

export async function deleteProviderConfig(providerId: string): Promise<void> {
  const response = await authFetch(`/api/providers/${providerId}`, {
    method: "DELETE",
  });
  // 404 means another tab deleted it; prune the cache instead of throwing.
  if (response.status === 404) {
    return;
  }
  if (!response.ok) {
    const body = await response.json().catch(() => null);
    throw new Error(parseErrorText(response.status, body));
  }
}

export async function updateProviderConfig(
  providerId: string,
  payload: {
    displayName?: string;
    baseUrl?: string | null;
    apiType?: ConnectionApiType;
    isEnabled?: boolean;
    models?: string[];
    availableModels?: string[];
    maxOutputTokens?: number | null;
    reasoningConfig?: CustomReasoningConfig | null;
    extraHeaders?: Record<string, string>;
    shared?: boolean;
    apiKey?: string;
    clearApiKey?: boolean;
  },
): Promise<ProviderConfig> {
  return withApiKeyEncryptionRetry(payload.apiKey ?? "", async (encryptedApiKey) => {
    const response = await authFetch(`/api/providers/${providerId}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        ...(payload.displayName === undefined ? {} : { display_name: payload.displayName }),
        ...(payload.baseUrl === undefined ? {} : { base_url: payload.baseUrl }),
        ...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
        ...(payload.isEnabled === undefined ? {} : { is_enabled: payload.isEnabled }),
        ...(payload.models === undefined ? {} : { models: payload.models }),
        ...(payload.availableModels === undefined
          ? {}
          : { available_models: payload.availableModels }),
        ...(payload.maxOutputTokens === undefined
          ? {}
          : { max_output_tokens: payload.maxOutputTokens }),
        ...(payload.reasoningConfig === undefined
          ? {}
          : { reasoning_config: payload.reasoningConfig }),
        ...(payload.extraHeaders === undefined
          ? {}
          : { extra_headers: payload.extraHeaders }),
        ...(payload.shared === undefined ? {} : { shared: payload.shared }),
        ...(payload.apiKey === undefined ? {} : { encrypted_api_key: encryptedApiKey }),
        ...(payload.clearApiKey === undefined ? {} : { clear_api_key: payload.clearApiKey }),
      }),
    });
    return parseJsonOrThrow<ProviderConfig>(response);
  });
}

export async function migrateProviderApiKey(
  providerId: string,
  apiKey: string,
): Promise<ProviderConfig> {
  return withApiKeyEncryptionRetry(apiKey, async (encryptedApiKey) => {
    const response = await authFetch(`/api/providers/${providerId}/api-key/migrate`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ encrypted_api_key: encryptedApiKey }),
    });
    return parseJsonOrThrow<ProviderConfig>(response);
  });
}


async function withApiKeyEncryptionRetry<T>(
  plaintextApiKey: string,
  call: (encryptedApiKey: string | null) => Promise<T>,
): Promise<T> {
  // Empty key (local providers): skip RSA round-trip and let the backend omit auth.
  if (!plaintextApiKey) {
    return await call(null);
  }
  try {
    const encrypted = await encryptProviderApiKey(plaintextApiKey, false);
    return await call(encrypted);
  } catch (error) {
    if (!isProviderKeyRotationError(error)) {
      throw error;
    }
    clearProviderPublicKeyCache();
    const encrypted = await encryptProviderApiKey(plaintextApiKey, true);
    return await call(encrypted);
  }
}

export async function testProviderConnection(payload: {
  providerType: string;

  providerId?: string | null;
  apiKey: string;
  baseUrl?: string | null;
  apiType?: ConnectionApiType;
  extraHeaders?: Record<string, string>;
  modelId?: string | null;
}): Promise<ProviderTestResult> {
  return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
    const response = await authFetch("/api/providers/test", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        provider_type: payload.providerType,

        provider_id: payload.providerId ?? null,
        encrypted_api_key: encryptedApiKey,
        base_url: payload.baseUrl ?? null,
        ...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
        ...(payload.extraHeaders === undefined
          ? {}
          : { extra_headers: payload.extraHeaders }),
        model_id: payload.modelId ?? null,
      }),
    });
    return parseJsonOrThrow<ProviderTestResult>(response);
  });
}

export async function listProviderModels(payload: {
  providerType: string;

  providerId?: string | null;
  apiKey: string;
  baseUrl?: string | null;
  apiType?: ConnectionApiType;
  extraHeaders?: Record<string, string>;
}): Promise<ProviderModelInfo[]> {
  return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
    const response = await authFetch("/api/providers/models", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        provider_type: payload.providerType,

        provider_id: payload.providerId ?? null,
        encrypted_api_key: encryptedApiKey,
        base_url: payload.baseUrl ?? null,
        ...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
        ...(payload.extraHeaders === undefined
          ? {}
          : { extra_headers: payload.extraHeaders }),
      }),
    });
    return parseJsonOrThrow<ProviderModelInfo[]>(response);
  });
}

export async function fetchModelCatalog(): Promise<ModelCatalogResponse> {
  const response = await authFetch("/api/providers/model-catalog");
  return parseJsonOrThrow<ModelCatalogResponse>(response);
}

export async function listProviderModelCapabilities(payload: {
  providerType: string;
  providerId?: string | null;
  apiKey: string;
  baseUrl?: string | null;
  apiType?: ProviderApiType;
}): Promise<ProviderModelCapabilityInfo[]> {
  return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
    const response = await authFetch("/api/providers/model-capabilities", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        provider_type: payload.providerType,
        provider_id: payload.providerId ?? null,
        encrypted_api_key: encryptedApiKey,
        base_url: payload.baseUrl ?? null,
        ...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
      }),
    });
    return parseJsonOrThrow<ProviderModelCapabilityInfo[]>(response);
  });
}


export interface CodexSubscriptionModels {
  models: ProviderModelInfo[];
  /** Every model the plan returned, offered or not: absent from this means the account cannot reach
   *  it, while present-but-unoffered only means it is no longer shown. */
  known?: ProviderModelInfo[];
  /** "reauthorization_required" is a curated answer that also says the connection has to be
   *  reconnected: the picker must not treat it as the plan's catalog. */
  source: "subscription" | "curated" | "reauthorization_required";
}

export async function fetchCodexSubscriptionModels(
  providerId: string,
  options?: { refresh?: boolean },
): Promise<CodexSubscriptionModels> {
  // An explicit reload asks about plan changes, so it must not be served from cache.
  const query = options?.refresh ? "?refresh=true" : "";
  const response = await authFetch(`/api/providers/${providerId}/codex/models${query}`);
  return parseJsonOrThrow<CodexSubscriptionModels>(response);
}


export interface CodexOAuthFlow {
  flow_id: string;
  method: "browser" | "device";
  status: "pending" | "connected" | "error" | "cancelled";
  expires_at: number;
  authorization_url?: string | null;
  verification_url?: string | null;
  user_code?: string | null;
  message?: string | null;
}

export async function startCodexOAuth(
  providerId: string,
  method: "browser" | "device",
): Promise<CodexOAuthFlow> {
  const response = await authFetch(`/api/providers/${providerId}/oauth/start`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ method }),
  });
  return parseJsonOrThrow<CodexOAuthFlow>(response);
}

export async function getCodexOAuthFlow(providerId: string, flowId: string): Promise<CodexOAuthFlow> {
  const response = await authFetch(`/api/providers/${providerId}/oauth/flows/${flowId}`);
  return parseJsonOrThrow<CodexOAuthFlow>(response);
}

export async function completeCodexOAuth(
  providerId: string,
  flowId: string,
  callbackUrl: string,
): Promise<CodexOAuthFlow> {
  const response = await authFetch(`/api/providers/${providerId}/oauth/flows/${flowId}/complete`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ callback_url: callbackUrl }),
  });
  return parseJsonOrThrow<CodexOAuthFlow>(response);
}

export async function cancelCodexOAuthFlow(
  providerId: string,
  flowId: string,
): Promise<void> {
  const response = await authFetch(
    `/api/providers/${providerId}/oauth/flows/${flowId}`,
    { method: "DELETE" },
  );
  if (!response.ok) {
    const body = await response.json().catch(() => null);
    throw new Error(parseErrorText(response.status, body));
  }
}



export async function disconnectCodexOAuth(providerId: string): Promise<void> {
  const response = await authFetch(`/api/providers/${providerId}/oauth`, { method: "DELETE" });
  if (!response.ok) {
    const body = await response.json().catch(() => null);
    throw new Error(parseErrorText(response.status, body));
  }
}