@tavily/cli 0.0.0-stage → 1.0.0

package/dist/chunk-AERAIFZU.js

@@ -0,0 +1,691 @@
+#!/usr/bin/env node
+import {
+  OAuthError,
+  isObject,
+  messageOf
+} from "./chunk-5JXZZSLS.js";
+
+// src/core/oauth.ts
+import { createHash, randomBytes, randomInt } from "crypto";
+import { createServer } from "http";
+var MCP_ISSUER = "https://mcp.tavily.com/";
+var MCP_RESOURCE = "https://mcp.tavily.com/mcp";
+var OAUTH_METADATA_URL = "https://mcp.tavily.com/.well-known/oauth-authorization-server";
+var PRM_URL = "https://mcp.tavily.com/.well-known/oauth-protected-resource/mcp";
+var DEFAULT_SCOPES = "openid offline_access";
+var CLIENT_NAME = "Tavily CLI";
+var LOGIN_TIMEOUT_SECONDS = 180;
+var HTTP_TIMEOUT_MS = 3e4;
+var EXPIRY_SKEW_SECONDS = 60;
+var FALLBACK_METADATA = {
+  authorization_endpoint: "https://mcp.tavily.com/authorize",
+  token_endpoint: "https://mcp.tavily.com/token",
+  registration_endpoint: "https://mcp.tavily.com/register",
+  revocation_endpoint: "https://mcp.tavily.com/revoke"
+};
+var PKCE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+function generatePkce() {
+  let verifier = "";
+  for (let i = 0; i < 128; i++) verifier += PKCE_ALPHABET[randomInt(PKCE_ALPHABET.length)];
+  const challenge = createHash("sha256").update(verifier, "ascii").digest("base64url");
+  return { verifier, challenge };
+}
+var nowSeconds = () => Date.now() / 1e3;
+function expiresAtFromNow(expiresIn, now = nowSeconds()) {
+  const lifetime = typeof expiresIn === "number" && Number.isInteger(expiresIn) && expiresIn > 0 ? expiresIn : 3600;
+  return now + lifetime - EXPIRY_SKEW_SECONDS;
+}
+function tokenIsExpired(expiresAt, now = nowSeconds()) {
+  if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return true;
+  return now >= expiresAt;
+}
+function validatedHttpsUrl(value, field) {
+  const invalid = new OAuthError(
+    `OAuth discovery returned an invalid ${field}; expected a secure HTTPS URL.`
+  );
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw invalid;
+  }
+  if (url.protocol !== "https:" || !url.host || url.username || url.password || url.hash) {
+    throw invalid;
+  }
+  return value;
+}
+function timeout() {
+  return AbortSignal.timeout(HTTP_TIMEOUT_MS);
+}
+async function send(fetchImpl, url, init) {
+  return transport(() => fetchImpl(url, { ...init, signal: timeout(), redirect: "manual" }));
+}
+async function transport(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    const cause = e instanceof Error && e.cause instanceof Error ? e.cause.message : "";
+    const message = messageOf(e);
+    throw new OAuthError(
+      `Could not reach the Tavily OAuth server: ${message}${cause ? `: ${cause}` : ""}`
+    );
+  }
+}
+async function fetchMetadata(fetchImpl = globalThis.fetch) {
+  const data = { ...FALLBACK_METADATA };
+  const discoveredJson = async (url) => {
+    try {
+      const resp = await fetchImpl(url, { signal: timeout(), redirect: "manual" });
+      if (!resp.ok) return void 0;
+      return await resp.json();
+    } catch {
+      return void 0;
+    }
+  };
+  const discovered = await discoveredJson(OAUTH_METADATA_URL);
+  if (isObject(discovered)) {
+    if (discovered.issuer !== MCP_ISSUER) {
+      throw new OAuthError("OAuth discovery issuer does not match the configured Tavily issuer.");
+    }
+    for (const field of Object.keys(data)) {
+      const value = discovered[field];
+      if (typeof value === "string") data[field] = validatedHttpsUrl(value, field);
+    }
+  }
+  let resource = MCP_RESOURCE;
+  const prm = await discoveredJson(PRM_URL);
+  if (isObject(prm) && typeof prm.resource === "string") {
+    const discoveredResource = validatedHttpsUrl(prm.resource, "resource");
+    if (discoveredResource !== MCP_RESOURCE) {
+      throw new OAuthError(
+        "OAuth protected-resource metadata does not match the Tavily MCP resource."
+      );
+    }
+    resource = discoveredResource;
+  }
+  return {
+    authorizationEndpoint: data.authorization_endpoint,
+    tokenEndpoint: data.token_endpoint,
+    registrationEndpoint: data.registration_endpoint,
+    revocationEndpoint: data.revocation_endpoint,
+    resource
+  };
+}
+async function jsonObjectResponse(resp, operation) {
+  const text = await transport(() => resp.text());
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new OAuthError(`${operation} returned invalid JSON (HTTP ${resp.status}).`);
+  }
+  if (!isObject(data)) {
+    throw new OAuthError(
+      `${operation} returned an invalid response (HTTP ${resp.status}; expected a JSON object).`
+    );
+  }
+  return data;
+}
+async function httpError(prefix, resp) {
+  let detail = (await transport(() => resp.text())).trim().replaceAll("\n", " ");
+  if (detail.length > 280) detail = `${detail.slice(0, 277)}...`;
+  const status = `${prefix} (HTTP ${resp.status})`;
+  return new OAuthError(detail ? `${status}: ${detail}` : `${status}.`);
+}
+async function registerClient(metadata, redirectUri, fetchImpl = globalThis.fetch) {
+  const payload = {
+    client_name: CLIENT_NAME,
+    redirect_uris: [redirectUri],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    scope: DEFAULT_SCOPES,
+    application_type: "native"
+  };
+  const resp = await send(fetchImpl, metadata.registrationEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  if (!resp.ok) throw await httpError("Client registration failed", resp);
+  const data = await jsonObjectResponse(resp, "OAuth client registration");
+  const clientId = data.client_id;
+  if (typeof clientId !== "string" || !clientId) {
+    throw new OAuthError("OAuth registration did not return a client_id.");
+  }
+  const method = data.token_endpoint_auth_method || "none";
+  if (method !== "none" && method !== "client_secret_post" && method !== "client_secret_basic") {
+    throw new OAuthError(
+      `Authorization server registered the CLI with unsupported token_endpoint_auth_method '${String(method)}'.`
+    );
+  }
+  const secret = data.client_secret;
+  if (method !== "none" && (typeof secret !== "string" || !secret)) {
+    throw new OAuthError(
+      `Authorization server registered the CLI for '${method}' but issued no valid client_secret.`
+    );
+  }
+  return {
+    clientId,
+    clientSecret: typeof secret === "string" ? secret : null,
+    tokenEndpointAuthMethod: method,
+    redirectUri
+  };
+}
+function buildAuthorizeUrl(metadata, client, { state, codeChallenge }) {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: client.clientId,
+    redirect_uri: client.redirectUri,
+    scope: DEFAULT_SCOPES,
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256",
+    resource: metadata.resource
+  });
+  return `${metadata.authorizationEndpoint}?${params}`;
+}
+function tokenAuth(client) {
+  if (client.tokenEndpointAuthMethod === "client_secret_post" && client.clientSecret) {
+    return {
+      extra: { client_id: client.clientId, client_secret: client.clientSecret },
+      basic: null
+    };
+  }
+  if (client.tokenEndpointAuthMethod === "client_secret_basic" && client.clientSecret) {
+    const creds = Buffer.from(`${client.clientId}:${client.clientSecret}`).toString("base64");
+    return { extra: {}, basic: `Basic ${creds}` };
+  }
+  return { extra: { client_id: client.clientId }, basic: null };
+}
+function formRequest(body, basic) {
+  const headers = {
+    "content-type": "application/x-www-form-urlencoded"
+  };
+  if (basic) headers.authorization = basic;
+  return { method: "POST", headers, body: new URLSearchParams(body).toString() };
+}
+async function requestTokens(tokenEndpoint, body, basic, fetchImpl) {
+  const resp = await send(fetchImpl, tokenEndpoint, formRequest(body, basic));
+  if (!resp.ok) throw await httpError("Token request failed", resp);
+  const data = await jsonObjectResponse(resp, "OAuth token endpoint");
+  const access = data.access_token;
+  if (typeof access !== "string" || !access) {
+    throw new OAuthError("OAuth token response did not include a valid access_token.");
+  }
+  const refresh = data.refresh_token;
+  const tokenType = data.token_type;
+  return {
+    accessToken: access,
+    refreshToken: typeof refresh === "string" ? refresh : null,
+    expiresAt: expiresAtFromNow(data.expires_in),
+    tokenType: typeof tokenType === "string" && tokenType ? tokenType : "Bearer"
+  };
+}
+async function exchangeCode(metadata, client, { code, codeVerifier }, fetchImpl = globalThis.fetch) {
+  const { extra, basic } = tokenAuth(client);
+  const body = {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: client.redirectUri,
+    code_verifier: codeVerifier,
+    resource: metadata.resource,
+    ...extra
+  };
+  return requestTokens(metadata.tokenEndpoint, body, basic, fetchImpl);
+}
+async function refreshTokens(metadata, client, refreshToken, fetchImpl = globalThis.fetch) {
+  const { extra, basic } = tokenAuth(client);
+  const body = {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    resource: metadata.resource,
+    ...extra
+  };
+  const tokens = await requestTokens(metadata.tokenEndpoint, body, basic, fetchImpl);
+  return tokens.refreshToken === null ? { ...tokens, refreshToken } : tokens;
+}
+async function revokeToken(metadata, client, token, { tokenTypeHint }, fetchImpl = globalThis.fetch) {
+  if (!metadata.revocationEndpoint) {
+    throw new OAuthError("OAuth server does not advertise a token revocation endpoint.");
+  }
+  const { extra, basic } = tokenAuth(client);
+  const body = { token, token_type_hint: tokenTypeHint, ...extra };
+  let resp = await send(fetchImpl, metadata.revocationEndpoint, formRequest(body, basic));
+  if (resp.status === 400 && client.tokenEndpointAuthMethod === "none") {
+    resp = await send(
+      fetchImpl,
+      metadata.revocationEndpoint,
+      formRequest({ ...body, client_secret: "" }, basic)
+    );
+  }
+  if (!resp.ok) throw await httpError("Token revocation failed", resp);
+}
+function looksHeadless(env, platform) {
+  if (env.SSH_CONNECTION || env.SSH_TTY) return true;
+  return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+function callbackHtml({ success }) {
+  const message = success ? "You're signed in. You can close this tab and return to the terminal." : "Sign-in didn't complete. Return to the terminal for details.";
+  const color = success ? "#9BC0AE" : "#FAA2FB";
+  return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Tavily CLI</title></head>
+<body style="font-family: system-ui, sans-serif; background:#111; color:#eee;
+             display:flex; min-height:100vh; align-items:center; justify-content:center;">
+  <div style="max-width:32rem; text-align:center;">
+    <p style="color:${color}; font-size:1.25rem; font-weight:600;">tavily</p>
+    <p>${message}</p>
+  </div>
+</body></html>`;
+}
+async function runBrowserLogin(opts) {
+  const { timeoutSeconds = LOGIN_TIMEOUT_SECONDS, fetchImpl } = opts;
+  const metadata = await fetchMetadata(fetchImpl);
+  let resolveCallback = () => {
+  };
+  const callback = new Promise((r) => {
+    resolveCallback = r;
+  });
+  let handled = false;
+  const server = createServer((req, res) => {
+    let url;
+    try {
+      url = new URL(req.url ?? "/", "http://127.0.0.1");
+    } catch {
+    }
+    if (!url || req.method !== "GET" || url.pathname !== "/callback" || handled) {
+      res.writeHead(404).end();
+      return;
+    }
+    handled = true;
+    const q = url.searchParams;
+    const params = {
+      code: q.get("code"),
+      state: q.get("state"),
+      error: q.get("error"),
+      errorDescription: q.get("error_description")
+    };
+    const ok = Boolean(params.code) && !params.error;
+    const body = Buffer.from(callbackHtml({ success: ok }), "utf8");
+    res.writeHead(ok ? 200 : 400, {
+      "content-type": "text/html; charset=utf-8",
+      "content-length": body.length
+    });
+    res.end(body);
+    resolveCallback(params);
+  });
+  let timer;
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const port = server.address().port;
+    const client = await registerClient(metadata, `http://127.0.0.1:${port}/callback`, fetchImpl);
+    const { verifier, challenge } = generatePkce();
+    const state = randomBytes(32).toString("base64url");
+    const authorizeUrl = buildAuthorizeUrl(metadata, client, { state, codeChallenge: challenge });
+    opts.onStatus?.(authorizeUrl);
+    if (opts.openBrowser) opts.openImpl(authorizeUrl);
+    const timeout2 = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(
+          new OAuthError(
+            `Timed out after ${timeoutSeconds}s waiting for browser authorization. Open the login URL printed above, or use: tvly login --api-key tvly-YOUR_KEY`
+          )
+        ),
+        timeoutSeconds * 1e3
+      );
+    });
+    const result = await Promise.race([callback, timeout2]);
+    if (result.error) {
+      throw new OAuthError(`Authorization was denied: ${result.errorDescription || result.error}`);
+    }
+    if (result.state !== state) {
+      throw new OAuthError("OAuth state mismatch; aborting to prevent CSRF.");
+    }
+    if (!result.code) throw new OAuthError("Authorization callback did not include a code.");
+    const tokens = await exchangeCode(
+      metadata,
+      client,
+      { code: result.code, codeVerifier: verifier },
+      fetchImpl
+    );
+    return { tokens, client };
+  } finally {
+    clearTimeout(timer);
+    server.close();
+    server.closeAllConnections();
+  }
+}
+
+// src/core/config.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import { readdirSync, readFileSync, rmSync } from "fs";
+import fs from "fs/promises";
+import path from "path";
+import { isDeepStrictEqual } from "util";
+import lockfile from "proper-lockfile";
+function configPaths(home) {
+  const dir = path.join(home, ".tavily");
+  return {
+    dir,
+    file: path.join(dir, "config.json"),
+    mcpAuthDir: path.join(home, ".mcp-auth")
+  };
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value !== "";
+}
+function readConfig(host) {
+  try {
+    const data = JSON.parse(readFileSync(configPaths(host.home).file, "utf8"));
+    return isObject(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+async function chmod(target, mode, platform) {
+  try {
+    await fs.chmod(target, mode);
+  } catch (e) {
+    if (platform !== "win32") throw e;
+  }
+}
+async function ensureConfigDir(dir, platform) {
+  await fs.mkdir(dir, { recursive: true, mode: 448 });
+  await chmod(dir, 448, platform);
+}
+async function writeConfigUnlocked(config, host) {
+  const { dir, file } = configPaths(host.home);
+  await ensureConfigDir(dir, host.platform);
+  if (Object.keys(config).length === 0) {
+    await fs.rm(file, { force: true });
+    return;
+  }
+  const temp = path.join(dir, `.config.json.${randomBytes2(6).toString("hex")}.tmp`);
+  try {
+    const handle = await fs.open(temp, "wx", 384);
+    try {
+      await handle.writeFile(`${JSON.stringify(config, null, 2)}
+`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await chmod(temp, 384, host.platform);
+    await fs.rename(temp, file);
+  } finally {
+    await fs.rm(temp, { force: true });
+  }
+}
+async function withConfigLock(fn, host) {
+  const { dir, file } = configPaths(host.home);
+  await ensureConfigDir(dir, host.platform);
+  const release = await lockfile.lock(file, {
+    lockfilePath: path.join(dir, ".config.lock"),
+    stale: 3e4,
+    // Backoff starts at 20 ms and is capped so a waiter polls at least once per second.
+    retries: { retries: 50, minTimeout: 20, maxTimeout: 1e3 },
+    realpath: false,
+    // The write is an atomic rename, so a lock that goes stale mid-transaction (e.g. the
+    // laptop sleeps) can at worst lose one update; that beats crashing the CLI, which is
+    // what proper-lockfile's default handler does.
+    onCompromised: () => {
+    }
+  });
+  try {
+    const { config, result } = await fn(readConfig(host));
+    if (config !== void 0) await writeConfigUnlocked(config, host);
+    return result;
+  } finally {
+    await release().catch((e) => {
+      if (e.code !== "ERELEASED") throw e;
+    });
+  }
+}
+function oauthSessionData(session) {
+  return {
+    access_token: session.tokens.accessToken,
+    refresh_token: session.tokens.refreshToken,
+    expires_at: session.tokens.expiresAt,
+    token_type: session.tokens.tokenType,
+    client_id: session.client.clientId,
+    client_secret: session.client.clientSecret,
+    token_endpoint_auth_method: session.client.tokenEndpointAuthMethod,
+    redirect_uri: session.client.redirectUri
+  };
+}
+function withoutKeys(config, ...keys) {
+  const copy = { ...config };
+  for (const key of keys) delete copy[key];
+  return copy;
+}
+async function saveApiKey(apiKey, host) {
+  await withConfigLock(async (config) => {
+    if (isObject(config.oauth)) {
+      try {
+        await revokeStoredOauth(config.oauth, host);
+      } catch {
+      }
+    }
+    return { config: { ...withoutKeys(config, "oauth"), api_key: apiKey }, result: void 0 };
+  }, host);
+}
+async function saveOauthSession(session, host) {
+  const replacement = oauthSessionData(session);
+  await withConfigLock(async (config) => {
+    const previous = config.oauth;
+    if (isObject(previous) && !isDeepStrictEqual(previous, replacement)) {
+      try {
+        await revokeStoredOauth(previous, host);
+      } catch (previousError) {
+        if (!(previousError instanceof OAuthError)) throw previousError;
+        try {
+          await revokeStoredOauth(replacement, host);
+        } catch (cleanupError) {
+          if (!(cleanupError instanceof OAuthError)) throw cleanupError;
+          throw new OAuthError(
+            `Could not replace the previous OAuth session: ${previousError.message} The new OAuth session also could not be revoked: ${cleanupError.message}`
+          );
+        }
+        throw new OAuthError(
+          `Could not replace the previous OAuth session: ${previousError.message}`
+        );
+      }
+    }
+    return { config: { ...withoutKeys(config, "api_key"), oauth: replacement }, result: void 0 };
+  }, host);
+}
+function hasStoredOauth(host) {
+  const data = readConfig(host).oauth;
+  return isObject(data) && typeof data.access_token === "string";
+}
+function getHumanId(host) {
+  const value = host.env.TAVILY_HUMAN_ID;
+  if (value) return value;
+  const configured = readConfig(host).human_id;
+  return typeof configured === "string" ? configured : null;
+}
+function getApiBaseUrl(host) {
+  const stripSlashes = (url) => url.replace(/\/+$/, "");
+  const value = host.env.TAVILY_API_BASE_URL;
+  if (value) return stripSlashes(value);
+  const configured = readConfig(host).api_base_url;
+  return nonEmptyString(configured) ? stripSlashes(configured) : null;
+}
+async function clearCredentials(host) {
+  const result = await withConfigLock(async (config) => {
+    const outcome = { serverRevoked: null };
+    if (isObject(config.oauth)) {
+      try {
+        if (await revokeStoredOauth(config.oauth, host)) outcome.serverRevoked = true;
+      } catch (e) {
+        outcome.serverRevoked = false;
+        outcome.revocationError = e instanceof Error && (e.message || e.name) || String(e);
+      }
+    }
+    return { config: withoutKeys(config, "api_key", "oauth"), result: outcome };
+  }, host);
+  clearMcpTokens(host);
+  return result;
+}
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[1] === void 0) return null;
+  try {
+    const payload = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(parts[1], "base64url"))
+    );
+    return isObject(payload) ? payload : null;
+  } catch {
+    return null;
+  }
+}
+function isTavilyToken(token) {
+  return decodeJwtPayload(token)?.iss === MCP_ISSUER;
+}
+function isValidTavilyToken(token) {
+  const payload = decodeJwtPayload(token);
+  if (payload?.iss !== MCP_ISSUER) return false;
+  const exp = payload.exp;
+  if (exp === void 0 || exp === null) return true;
+  return typeof exp === "number" && Date.now() / 1e3 < exp;
+}
+function mcpTokenFiles(host) {
+  const root = configPaths(host.home).mcpAuthDir;
+  let names;
+  try {
+    names = readdirSync(root, { recursive: true, encoding: "utf8" });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const name of names) {
+    if (!path.basename(name).endsWith("_tokens.json")) continue;
+    const file = path.join(root, name);
+    try {
+      const data = JSON.parse(readFileSync(file, "utf8"));
+      if (isObject(data)) found.push({ file, token: data.access_token });
+    } catch {
+    }
+  }
+  return found;
+}
+function getMcpToken(host) {
+  for (const { token } of mcpTokenFiles(host)) {
+    if (nonEmptyString(token) && isValidTavilyToken(token)) return token;
+  }
+  return null;
+}
+function clearMcpTokens(host) {
+  for (const { file, token } of mcpTokenFiles(host)) {
+    if (!nonEmptyString(token) || !isTavilyToken(token)) continue;
+    try {
+      rmSync(file);
+    } catch {
+    }
+  }
+}
+function oauthClientFromConfig(data) {
+  const clientId = data.client_id;
+  if (!nonEmptyString(clientId)) return null;
+  const { client_secret: secret, token_endpoint_auth_method: method, redirect_uri: uri } = data;
+  return {
+    clientId,
+    clientSecret: typeof secret === "string" ? secret : null,
+    tokenEndpointAuthMethod: nonEmptyString(method) ? method : "none",
+    redirectUri: nonEmptyString(uri) ? uri : "http://127.0.0.1/callback"
+  };
+}
+async function revokeStoredOauth(data, host) {
+  const present = ["refresh_token", "access_token"].flatMap((key) => {
+    const token = data[key];
+    return nonEmptyString(token) ? [{ key, token }] : [];
+  });
+  if (present.length === 0) return false;
+  const client = oauthClientFromConfig(data);
+  if (client === null) {
+    throw new OAuthError(
+      "Stored OAuth client metadata is incomplete; server revocation was not attempted."
+    );
+  }
+  const metadata = await fetchMetadata(host.fetch);
+  const errors = [];
+  for (const { key, token } of present) {
+    try {
+      await revokeToken(metadata, client, token, { tokenTypeHint: key }, host.fetch);
+    } catch (e) {
+      if (!(e instanceof OAuthError)) throw e;
+      errors.push(`${key}: ${e.message}`);
+    }
+  }
+  if (errors.length > 0) throw new OAuthError(errors.join("; "));
+  return true;
+}
+async function oauthAccessToken(config, host) {
+  const data = config.oauth;
+  if (!isObject(data)) return null;
+  const access = data.access_token;
+  if (!nonEmptyString(access)) return null;
+  if (!tokenIsExpired(data.expires_at)) return access;
+  const refresh = data.refresh_token;
+  const client = oauthClientFromConfig(data);
+  if (!nonEmptyString(refresh) || client === null) return null;
+  try {
+    const tokens = await refreshTokens(
+      await fetchMetadata(host.fetch),
+      client,
+      refresh,
+      host.fetch
+    );
+    const oauth = oauthSessionData({ tokens, client });
+    await writeConfigUnlocked({ ...withoutKeys(config, "api_key"), oauth }, host);
+    return tokens.accessToken;
+  } catch (e) {
+    throw new OAuthError(
+      `Could not refresh the stored Tavily OAuth session. The stored credentials were not removed; retry the command, and run \`tvly login\` only if it continues. Details: ${messageOf(e)}`
+    );
+  }
+}
+async function getApiKey(host) {
+  const envKey = host.env.TAVILY_API_KEY;
+  if (envKey) return envKey;
+  const config = readConfig(host);
+  if (nonEmptyString(config.api_key)) return config.api_key;
+  const oauth = config.oauth;
+  const needsRefresh = isObject(oauth) && nonEmptyString(oauth.access_token) && tokenIsExpired(oauth.expires_at);
+  const stored = needsRefresh ? await withConfigLock(async (fresh) => {
+    if (nonEmptyString(fresh.api_key)) return { result: fresh.api_key };
+    return { result: await oauthAccessToken(fresh, host) };
+  }, host) : await oauthAccessToken(config, host);
+  return stored ?? getMcpToken(host);
+}
+function isOauthToken(key) {
+  return !key.startsWith("tvly-") && decodeJwtPayload(key) !== null;
+}
+function authMethod(key, host) {
+  if (host.env.TAVILY_API_KEY) return "env";
+  if (isOauthToken(key)) return hasStoredOauth(host) ? "oauth" : "oauth_legacy";
+  return "api_key";
+}
+function authSource(key, env) {
+  if (env.TAVILY_API_KEY) return "TAVILY_API_KEY";
+  if (isOauthToken(key)) return "OAuth (tvly login)";
+  return "API key";
+}
+
+export {
+  looksHeadless,
+  runBrowserLogin,
+  configPaths,
+  saveApiKey,
+  saveOauthSession,
+  getHumanId,
+  getApiBaseUrl,
+  clearCredentials,
+  getApiKey,
+  isOauthToken,
+  authMethod,
+  authSource
+};