Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

20.3 KB
Raw Blame
const ENDPOINTS = {
  openai: "https://api.openai.com/v1/models",
  groq: "https://api.groq.com/openai/v1/models",
  xai: "https://api.x.ai/v1/models",
  mistral: "https://api.mistral.ai/v1/models",
  // The largest page each API allows, so a valid but older model is still listed.
  anthropic: "https://api.anthropic.com/v1/models?limit=1000",
  gemini: "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1000",
  // OpenRouter's model list is public, so it cannot vouch for a key. The key route
  // describes the key that calls it.
  openrouter: "https://openrouter.ai/api/v1/key",
  corti: "https://ai.eu.corti.app/v1/models",
  // Public too, so it vouches only for the model; testTinfoilKey checks the key.
  tinfoil: "https://inference.tinfoil.sh/v1/models",
  // Deepgram's model list answers without a key, so it cannot vouch for one. This is
  // Deepgram's documented key check.
  deepgram: "https://api.deepgram.com/v1/auth/token",
  // AssemblyAI exposes no model list; listing transcripts is its 200-vs-401 probe.
  assemblyai: "https://api.assemblyai.com/v2/transcript?limit=1",
};
// Listing the key's projects proves the key too: used only if Deepgram retires the route above.
const DEEPGRAM_PROJECTS_ENDPOINT = "https://api.deepgram.com/v1/projects";
// Turns a made-up key away before embedding anything; a valid key pays for one token.
const TINFOIL_KEY_ENDPOINT = "https://inference.tinfoil.sh/v1/embeddings";

// Renderers translate errorCode via onboarding.rehaul.provider.errors.*; the
// English `error` string stays for logs and older callers.
class ConnectionTestError extends Error {
  constructor(errorCode, message) {
    super(message);
    this.errorCode = errorCode;
  }
}

// --- CommonJS mirror of the URL helpers in src/config/constants.ts ---
// This file runs in the main process, which cannot import that Vite/TS
// module (it reads import.meta.env). Keep these in sync with
// normalizeBaseUrl / getModelListBaseCandidates over there.

// Mirror of isPrivateHost/parseIPv4Literal in src/utils/urlUtils.ts (same
// main-process constraint as above): the runtime refuses plain HTTP on public
// hosts via isSecureHttpEndpoint, so the connection test must refuse the same
// URLs or a passing test commits a config every real request rejects.

function parseIPv4Literal(hostname) {
  const parts = hostname.split(".");
  if (parts.length !== 4) return null;

  const octets = [];
  for (const part of parts) {
    if (!/^(0|[1-9]\d{0,2})$/.test(part)) return null;
    const value = Number(part);
    if (value > 255) return null;
    octets.push(value);
  }

  return octets;
}

function isPrivateHost(hostname) {
  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");

  if (h === "localhost" || h === "0.0.0.0") return true;
  if (h === "::1") return true;

  const ipv4 = parseIPv4Literal(h);
  if (ipv4) {
    const [a, b] = ipv4;
    if (a === 127) return true;
    if (a === 10) return true;
    if (a === 192 && b === 168) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 100 && b >= 64 && b <= 127) return true;
    if (a === 169 && b === 254) return true;
  }

  const isIPv6 = h.includes(":");
  if (isIPv6 && (h.startsWith("fe80") || h.startsWith("fc") || h.startsWith("fd"))) return true;
  if (h.endsWith(".local")) return true;
  if (h.endsWith(".ts.net")) return true;

  return false;
}

function splitUrlDecorators(value) {
  let path = value;
  let hash = "";
  const hashIndex = path.indexOf("#");
  if (hashIndex >= 0) {
    hash = path.slice(hashIndex);
    path = path.slice(0, hashIndex);
  }
  let query = "";
  const queryIndex = path.indexOf("?");
  if (queryIndex >= 0) {
    query = path.slice(queryIndex);
    path = path.slice(0, queryIndex);
  }
  return { path, query, hash };
}

function joinUrlDecorators(path, query, hash) {
  return `${path}${query}${hash}`;
}

function normalizeBaseUrl(value) {
  if (!value) return "";

  const trimmed = String(value).trim();
  if (!trimmed) return "";

  const { path: rawPath, query, hash } = splitUrlDecorators(trimmed);
  let normalized = rawPath;

  const suffixReplacements = [
    [/\/v1\/chat\/completions$/i, "/v1"],
    [/\/chat\/completions$/i, ""],
    [/\/v1\/responses$/i, "/v1"],
    [/\/responses$/i, ""],
    [/\/v1\/models$/i, "/v1"],
    [/\/models$/i, ""],
    [/\/v1\/audio\/transcriptions$/i, "/v1"],
    [/\/audio\/transcriptions$/i, ""],
    [/\/v1\/audio\/translations$/i, "/v1"],
    [/\/audio\/translations$/i, ""],
  ];

  for (const [pattern, replacement] of suffixReplacements) {
    if (pattern.test(normalized)) {
      normalized = normalized.replace(pattern, replacement).replace(/\/+$/, "");
    }
  }

  return joinUrlDecorators(normalized.replace(/\/+$/, ""), query, hash);
}

// Reference: getModelListBaseCandidates in src/config/constants.ts.
// Self-hosted servers (LM Studio, Ollama, vLLM) serve the API under /v1 even
// when users enter the bare origin, and LM Studio's native REST base
// (/api/v1 or /api/v0) has its OpenAI-compatible sibling at /v1.
function getModelListBaseCandidates(base) {
  const normalized = normalizeBaseUrl(base);
  if (!normalized) return [];
  const { path, query, hash } = splitUrlDecorators(normalized);
  const nativeApiMatch = path.match(/^(.+?)\/api\/v[01]$/i);
  if (nativeApiMatch) {
    return [normalized, joinUrlDecorators(`${nativeApiMatch[1]}/v1`, query, hash)];
  }
  if (path.endsWith("/v1")) return [normalized];
  return [normalized, joinUrlDecorators(`${path}/v1`, query, hash)];
}

function buildModelEndpoints(base) {
  return getModelListBaseCandidates(base).map((candidate) => {
    const { path, query, hash } = splitUrlDecorators(candidate);
    return joinUrlDecorators(`${path}/models`, query, hash);
  });
}

// Where the app sends a custom server's audio: buildApiUrl(normalizeBaseUrl(url),
// "/audio/transcriptions") in src/config/constants.ts and transcriptionRoute.ts.
// buildApiUrl normalises its base again, which strips a suffix a trailing slash hid
// from the first pass, so this address takes the same two passes.
function buildTranscriptionEndpoint(base) {
  const { path, query, hash } = splitUrlDecorators(normalizeBaseUrl(normalizeBaseUrl(base)));
  return joinUrlDecorators(`${path}/audio/transcriptions`, query, hash);
}

function resolveProviderRequest(config) {
  const provider = String(config?.provider || "").toLowerCase();
  const apiKey = typeof config?.apiKey === "string" ? config.apiKey.trim() : "";
  let endpoints = ENDPOINTS[provider] ? [ENDPOINTS[provider]] : [];
  // A hosted provider's fixed endpoint never redirects. Following one would carry
  // x-api-key or x-goog-api-key to whichever host it names (fetch drops only
  // Authorization across origins), so a redirect fails the check instead. Custom
  // servers may redirect within themselves, such as adding a trailing slash.
  let redirect = "error";
  let transcriptionEndpoint;

  if (provider === "openai") {
    const override = normalizeBaseUrl(
      process.env.OPENWHISPR_OPENAI_BASE_URL || process.env.OPENAI_BASE_URL
    );
    if (override) {
      endpoints = buildModelEndpoints(override);
      redirect = "follow";
    }
  }

  if (provider === "custom") {
    const raw = String(config?.baseUrl || "").trim();
    if (!raw) {
      throw new ConnectionTestError("endpointRequired", "Enter an endpoint URL before testing.");
    }
    let parsed;
    try {
      parsed = new URL(raw.includes("://") ? raw : `https://${raw}`);
    } catch {
      throw new ConnectionTestError("invalidUrl", "The endpoint must be a valid URL.");
    }
    if (!new Set(["http:", "https:"]).has(parsed.protocol)) {
      throw new ConnectionTestError("invalidUrl", "The endpoint must use HTTP or HTTPS.");
    }
    if (parsed.protocol === "http:" && !isPrivateHost(parsed.hostname)) {
      throw new ConnectionTestError(
        "httpsRequired",
        "Public endpoints must use HTTPS. HTTP is only allowed on private addresses."
      );
    }
    endpoints = buildModelEndpoints(parsed.toString());
    transcriptionEndpoint = buildTranscriptionEndpoint(parsed.toString());
    redirect = "follow";
  }

  if (endpoints.length === 0) {
    throw new ConnectionTestError(
      "unsupportedProvider",
      "Connection testing is not available for this provider."
    );
  }
  if (!apiKey && provider !== "custom") {
    throw new ConnectionTestError("apiKeyRequired", "Add an API key before testing.");
  }

  const headers = { Accept: "application/json" };
  if (apiKey) {
    if (provider === "anthropic") {
      headers["x-api-key"] = apiKey;
      headers["anthropic-version"] = "2023-06-01";
    } else if (provider === "gemini") {
      headers["x-goog-api-key"] = apiKey;
    } else if (provider === "deepgram") {
      headers.Authorization = `Token ${apiKey}`;
    } else if (provider === "assemblyai") {
      headers.Authorization = apiKey;
    } else {
      headers.Authorization = `Bearer ${apiKey}`;
    }
  }

  return { endpoint: endpoints[0], endpoints, headers, redirect, transcriptionEndpoint };
}

// When several candidate endpoints fail, report the most actionable failure. An answer that
// faults the setup outranks no answer (unverified), so a busy candidate never hides a refused
// key or a missing model. No answer outranks a candidate without a model list, which may only
// be an address the server doesn't use.
const FAILURE_PRIORITY = {
  credentialsRejected: 6,
  providerStatus: 5,
  modelNotFound: 4,
  endpointNotFound: 0,
};
const UNVERIFIED_PRIORITY = { providerStatus: 3, timeout: 2, network: 1 };

function pickFailure(current, next) {
  if (!current) return next;
  const rank = (failure) =>
    (failure.unverified ? UNVERIFIED_PRIORITY : FAILURE_PRIORITY)[failure.errorCode];
  return rank(next) > rank(current) ? next : current;
}

// A provider that is slow, busy or down gives no verdict on the credentials. Such a failure is
// marked unverified: the app may go ahead with them, and only a later check can tell.
function isUnverifiedStatus(status) {
  return status === 408 || status === 429 || status >= 500;
}

function describeStatusFailure(status, provider) {
  if (status === 401 || status === 403) {
    return {
      errorCode: "credentialsRejected",
      error: "The provider rejected these credentials.",
      status,
    };
  }
  if (status === 404 && provider === "custom") {
    return {
      errorCode: "endpointNotFound",
      error: "The endpoint does not expose an OpenAI-compatible model list.",
      status,
    };
  }
  const failure = {
    errorCode: "providerStatus",
    error: `The provider returned status ${status}.`,
    status,
  };
  return isUnverifiedStatus(status) ? { ...failure, unverified: true } : failure;
}

const MODEL_NOT_FOUND = {
  errorCode: "modelNotFound",
  error: "The selected model is not available from this provider.",
};
const TIMEOUT_FAILURE = {
  errorCode: "timeout",
  error: "The connection test timed out.",
  unverified: true,
};
const NETWORK_FAILURE = {
  errorCode: "network",
  error: "The provider could not be reached.",
  unverified: true,
};

// An empty or non-JSON body reads as undefined. A body that never arrives (the 12 s cap
// firing, a dropped connection) is not an answer, so its error goes on to probe's catch.
async function readJson(response) {
  try {
    return await response.json();
  } catch (error) {
    if (error instanceof SyntaxError) return undefined;
    throw error;
  }
}

// Gemini, xAI and Corti answer a made-up key with a 400, which on its own can also
// mean a malformed request. Their error bodies say which it was.
const KEY_REJECTED_BY_BODY = {
  gemini: (_, body) =>
    Array.isArray(body?.error?.details) &&
    body.error.details.some((detail) => detail?.reason === "API_KEY_INVALID"),
  xai: (status, body) =>
    status === 400 && typeof body?.error === "string" && /incorrect api key/i.test(body.error),
  // Corti's gateway turns an unknown key away before routing, with no body at all.
  corti: (status, body) => status === 400 && body === undefined,
};

async function describeResponseFailure(response, provider) {
  const failure = describeStatusFailure(response.status, provider);
  const keyRejected = KEY_REJECTED_BY_BODY[provider];
  // A 401 or 403 already says the key was refused; only a vaguer status needs the body.
  if (
    failure.errorCode !== "credentialsRejected" &&
    keyRejected &&
    keyRejected(response.status, await readJson(response))
  ) {
    return { ...describeStatusFailure(401, provider), status: response.status };
  }
  return failure;
}

function normalizeModelId(value) {
  return String(value || "")
    .trim()
    .replace(/^models\//i, "");
}

function responseModelIds(payload) {
  const models = Array.isArray(payload)
    ? payload
    : Array.isArray(payload?.data)
      ? payload.data
      : Array.isArray(payload?.models)
        ? payload.models
        : [];

  return models
    .map((model) => (typeof model === "string" ? model : model?.id || model?.name))
    .map(normalizeModelId)
    .filter(Boolean);
}

// Anthropic resolves an alias (claude-haiku-4-5) to a dated snapshot and lists only the
// snapshot (claude-haiku-4-5-20251001). Other servers match ids exactly.
function isDatedSnapshot(id, model) {
  return id.startsWith(model) && /^-\d{8}$/.test(id.slice(model.length));
}

async function responseOffersModel(response, model, provider) {
  if (!model) return true;
  const selected = normalizeModelId(model);
  return responseModelIds(await readJson(response)).some(
    (id) => id === selected || (provider === "anthropic" && isDatedSnapshot(id, selected))
  );
}

// One request (a GET unless `init` says otherwise) under the 12 s cap. `judge` reads the
// response inside that window, so a body that stalls cannot hold the check past the cap. It
// returns null when the check passes.
async function probe(endpoint, request, fetchImpl, judge, init = { method: "GET" }) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 12000);
  try {
    const response = await fetchImpl(endpoint, {
      ...init,
      headers: request.headers,
      redirect: request.redirect,
      signal: controller.signal,
    });
    return await judge(response);
  } catch (error) {
    return error?.name === "AbortError" ? TIMEOUT_FAILURE : NETWORK_FAILURE;
  } finally {
    clearTimeout(timeout);
  }
}

// `runPaidCheck(key, check)` runs a check that spends the user's credits. The main process
// passes one that runs it once per key (paidKeyCheck.js).
async function testProviderConnection(
  config,
  fetchImpl = fetch,
  runPaidCheck = (_key, check) => check()
) {
  let request;
  try {
    request = resolveProviderRequest(config);
  } catch (error) {
    return {
      success: false,
      errorCode: error.errorCode || "invalidUrl",
      error: error.message,
    };
  }

  const provider = String(config?.provider || "").toLowerCase();
  if (provider === "deepgram") return testDeepgramKey(request, fetchImpl);

  const model = String(config?.model || "").trim();
  let failure = null;
  let everyListMissing = true;
  for (const endpoint of request.endpoints) {
    const next = await probe(endpoint, request, fetchImpl, async (response) => {
      if (!response.ok) return describeResponseFailure(response, provider);
      if (provider === "openrouter") return describeOpenRouterKey(response);
      // AssemblyAI's probe lists transcripts, not models, so a 200 is the whole signal.
      if (provider === "assemblyai" || (await responseOffersModel(response, model, provider))) {
        return null;
      }
      return MODEL_NOT_FOUND;
    });
    if (!next) {
      return provider === "tinfoil"
        ? testTinfoilKey(request, config.apiKey.trim(), fetchImpl, runPaidCheck)
        : { success: true };
    }
    everyListMissing = everyListMissing && next.status === 404;
    failure = pickFailure(failure, next);
  }
  if (everyListMissing && provider === "custom" && config?.scope === "transcription") {
    return testTranscriptionEndpoint(request, model, fetchImpl);
  }
  return { success: false, ...failure };
}

// OpenRouter's key route describes the key that called it. A management key (formerly a
// provisioning key) only administers other keys and can never run a request. Only a 200
// carries that description; any other 2xx has no key to read, so it keeps its status.
async function describeOpenRouterKey(response) {
  if (response.status !== 200) return describeStatusFailure(response.status, "openrouter");
  const key = (await readJson(response))?.data;
  if (!key?.is_management_key && !key?.is_provisioning_key) return null;
  return { ...describeStatusFailure(401, "openrouter"), status: response.status };
}

// A speech-only server may publish no model list. Its transcription address answers a
// request that carries no audio with 400 or 422, which proves the address without
// transcribing anything. The model is not checked.
async function testTranscriptionEndpoint(request, model, fetchImpl) {
  const body = new FormData();
  body.append("model", model);
  const failure = await probe(
    request.transcriptionEndpoint,
    request,
    fetchImpl,
    async (response) => {
      if (response.status === 400 || response.status === 422) return null;
      // Nothing takes transcriptions at this address.
      if (response.status === 404 || response.status === 405) {
        return {
          errorCode: "transcriptionEndpointNotFound",
          error: "Nothing takes transcriptions at this address.",
          status: response.status,
        };
      }
      return describeStatusFailure(response.status, "custom");
    },
    { method: "POST", body }
  );
  return failure ? { success: false, ...failure } : { success: true };
}

// Deepgram is checked by key alone, since its model names don't match the app's model ids.
// A 404 means the key route was retired, not that the key is wrong, so the project list
// stands in.
async function testDeepgramKey(request, fetchImpl) {
  let retired = false;
  const failure = await probe(request.endpoint, request, fetchImpl, async (response) => {
    if (response.ok) return null;
    retired = response.status === 404;
    return describeStatusFailure(response.status, "deepgram");
  });
  if (!retired) return failure ? { success: false, ...failure } : { success: true };
  const fallback = await probe(DEEPGRAM_PROJECTS_ENDPOINT, request, fetchImpl, async (response) => {
    if (!response.ok) return describeStatusFailure(response.status, "deepgram");
    // No errorCode: the step shows its generic "could not be verified".
    return Array.isArray((await readJson(response))?.projects) ? null : {};
  });
  return fallback ? { success: false, ...fallback } : { success: true };
}

// Runs once Tinfoil's public model list has vouched for the model. A valid key pays for one
// embedded token, hence runPaidCheck. A 404 means this check's own model was retired, which
// says nothing about the key.
function testTinfoilKey(request, apiKey, fetchImpl, runPaidCheck) {
  const jsonRequest = {
    ...request,
    headers: { ...request.headers, "Content-Type": "application/json" },
  };
  return runPaidCheck(apiKey, async () => {
    const failure = await probe(
      TINFOIL_KEY_ENDPOINT,
      jsonRequest,
      fetchImpl,
      async (response) => {
        if (response.ok) return null;
        const statusFailure = describeStatusFailure(response.status, "tinfoil");
        return response.status === 404 ? { ...statusFailure, unverified: true } : statusFailure;
      },
      { method: "POST", body: JSON.stringify({ model: "nomic-embed-text", input: "." }) }
    );
    return failure ? { success: false, ...failure } : { success: true };
  });
}

// Corti's speech credentials are exchanged for a token (cortiAuth.js). Only an answer from
// Corti can refuse them, and getCortiToken prefixes those errors and attaches the status. A
// token request that never reached Corti, or found it busy or down, gives no verdict, and
// reporting it as "credentials rejected" sends the user to re-type a key that was never the
// issue.
function describeCortiTokenFailure(error) {
  if (error?.name === "AbortError") return { success: false, ...TIMEOUT_FAILURE };
  if (!/^(Corti authentication failed|Invalid Corti)/.test(error?.message || "")) {
    return { success: false, ...NETWORK_FAILURE };
  }
  if (isUnverifiedStatus(error.status)) {
    return { success: false, ...describeStatusFailure(error.status, "corti") };
  }
  return {
    success: false,
    errorCode: "credentialsRejected",
    error: "Corti rejected these credentials.",
  };
}

module.exports = { describeCortiTokenFailure, resolveProviderRequest, testProviderConnection };