tokentracker-cli 0.89.0 → 0.90.0

package/src/lib/proxy-env.js

@@ -1,4 +1,25 @@
 const cp = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { normalizeProxyConfig, buildProxyUrl } = require("./proxy-settings");
+
+// scutil --proxy is a sync spawn (2s timeout) that blocks the event loop.
+// resolveEffectiveProxySource runs on GET /proxy-config, and
+// applyUndiciProxyIfNeeded now uses the same probe on the system-mode path.
+// A 30s TTL (including negative / null results) keeps the settings UI and
+// the dispatcher aligned without re-spawning on every request.
+const SYSTEM_PROXY_CACHE_TTL_MS = 30_000;
+
+let systemProxyCache = { filled: false, at: 0, value: null };
+
+function invalidateSystemProxyCache() {
+  systemProxyCache = { filled: false, at: 0, value: null };
+}
+
+function resetSystemProxyCacheForTests() {
+  invalidateSystemProxyCache();
+}
 
 function hasProxyEnv(env = process.env) {
   return Boolean(
@@ -21,27 +42,131 @@ function parseMacProxyOutput(output) {
   return `http://${values.HTTPSProxy}:${values.HTTPSPort}`;
 }
 
-function resolveSystemProxyEnv({ env = process.env, platform = process.platform, commandRunner = cp.spawnSync } = {}) {
-  const out = {};
-  if (hasProxyEnv(env)) {
-    out.NODE_USE_ENV_PROXY = env.NODE_USE_ENV_PROXY || "1";
-    return out;
-  }
-
-  if (platform !== "darwin") return null;
+function probeMacSystemProxyUrl(commandRunner) {
   const result = commandRunner("scutil", ["--proxy"], {
     encoding: "utf8",
     timeout: 2000,
   });
   if (result?.error || result?.status !== 0) return null;
-  const proxyUrl = parseMacProxyOutput(result.stdout);
-  if (!proxyUrl) return null;
+  return parseMacProxyOutput(result.stdout);
+}
 
-  return {
-    NODE_USE_ENV_PROXY: "1",
-    HTTPS_PROXY: proxyUrl,
-    HTTP_PROXY: proxyUrl,
-  };
+function getCachedMacSystemProxyUrl({
+  platform = process.platform,
+  commandRunner = cp.spawnSync,
+} = {}) {
+  if (platform !== "darwin") return null;
+  const now = Date.now();
+  if (systemProxyCache.filled && now - systemProxyCache.at < SYSTEM_PROXY_CACHE_TTL_MS) {
+    return systemProxyCache.value;
+  }
+  const value = probeMacSystemProxyUrl(commandRunner);
+  systemProxyCache = { filled: true, at: now, value };
+  return value;
+}
+
+function isDeclaredManual(raw) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return false;
+  return String(raw.mode || "").trim().toLowerCase() === "manual";
+}
+
+function defaultConfigPath() {
+  return path.join(os.homedir(), ".tokentracker", "tracker", "config.json");
+}
+
+function readPersistedProxyConfig({ configPath } = {}) {
+  const file = configPath || defaultConfigPath();
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed.proxy : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function pickProxyUrl(env = process.env) {
+  return (
+    env.HTTPS_PROXY ||
+    env.https_proxy ||
+    env.HTTP_PROXY ||
+    env.http_proxy ||
+    env.ALL_PROXY ||
+    env.all_proxy ||
+    null
+  );
+}
+
+/**
+ * Shared resolution of the currently effective proxy URL.
+ * Used by both applyUndiciProxyIfNeeded (dispatcher) and
+ * resolveEffectiveProxySource (UI label) so the two cannot drift.
+ *
+ * System-mode order: process env (pickProxyUrl) → macOS scutil.
+ */
+function resolveEffectiveProxyUrl({
+  env = process.env,
+  proxyConfig,
+  platform = process.platform,
+  commandRunner = cp.spawnSync,
+} = {}) {
+  const config = normalizeProxyConfig(proxyConfig);
+  if (config.mode === "off") {
+    return { source: "none", proxyUrl: null, config };
+  }
+  // Dirty persisted "manual" normalizes to system; do not pretend a system
+  // proxy is in effect. apply() fail-closes this case, so report "blocked"
+  // rather than "none" — the UI must not say "connecting directly" while
+  // outbound traffic is actually being refused.
+  if (isDeclaredManual(proxyConfig) && config.mode !== "manual") {
+    return { source: "blocked", proxyUrl: null, config };
+  }
+  if (config.mode === "manual") {
+    const proxyUrl = buildProxyUrl(config);
+    return { source: proxyUrl ? "manual" : "blocked", proxyUrl, config };
+  }
+  const envUrl = pickProxyUrl(env);
+  if (envUrl) return { source: "env", proxyUrl: envUrl, config };
+  const systemUrl = getCachedMacSystemProxyUrl({ platform, commandRunner });
+  if (systemUrl) return { source: "system", proxyUrl: systemUrl, config };
+  return { source: "none", proxyUrl: null, config };
+}
+
+/**
+ * Display-only resolution of the currently effective proxy source.
+ * Includes macOS scutil so the settings UI can label "system".
+ */
+function resolveEffectiveProxySource(opts) {
+  return resolveEffectiveProxyUrl(opts);
+}
+
+function resolveSystemProxyEnv({
+  env = process.env,
+  platform = process.platform,
+  commandRunner = cp.spawnSync,
+  proxyConfig,
+} = {}) {
+  const normalized = normalizeProxyConfig(proxyConfig);
+  // Manual mode is applied only via applyUndiciProxyIfNeeded's ProxyAgent.
+  // Injecting HTTPS_PROXY here would relaunch serve and leak the URL into
+  // process.env, so a later switch back to system still picks the old proxy.
+  // Invalid persisted "manual" still counts as declared-manual so we do not
+  // relaunch into a system-proxy env while apply() is about to fail-closed.
+  if (normalized.mode === "off" || normalized.mode === "manual" || isDeclaredManual(proxyConfig)) {
+    return null;
+  }
+
+  const resolved = resolveEffectiveProxyUrl({ env, proxyConfig, platform, commandRunner });
+  if (resolved.source === "env") {
+    return { NODE_USE_ENV_PROXY: env.NODE_USE_ENV_PROXY || "1" };
+  }
+  if (resolved.source === "system" && resolved.proxyUrl) {
+    return {
+      NODE_USE_ENV_PROXY: "1",
+      HTTPS_PROXY: resolved.proxyUrl,
+      HTTP_PROXY: resolved.proxyUrl,
+    };
+  }
+  return null;
 }
 
 function shouldRelaunchForProxy(argv, env = process.env) {
@@ -57,9 +182,10 @@ function relaunchWithProxyEnvIfNeeded({
   platform = process.platform,
   commandRunner = cp.spawnSync,
   nodePath = process.execPath,
+  proxyConfig,
 } = {}) {
   if (!shouldRelaunchForProxy(argv, env)) return null;
-  const proxyEnv = resolveSystemProxyEnv({ env, platform, commandRunner });
+  const proxyEnv = resolveSystemProxyEnv({ env, platform, commandRunner, proxyConfig });
   if (!proxyEnv || proxyEnv.NODE_USE_ENV_PROXY === env.NODE_USE_ENV_PROXY) return null;
 
   const childEnv = {
@@ -73,16 +199,168 @@ function relaunchWithProxyEnvIfNeeded({
   });
 }
 
-function pickProxyUrl(env = process.env) {
-  return (
-    env.HTTPS_PROXY ||
-    env.https_proxy ||
-    env.HTTP_PROXY ||
-    env.http_proxy ||
-    env.ALL_PROXY ||
-    env.all_proxy ||
-    null
-  );
+// Dispatchers created by this module. setGlobalDispatcher only swaps the
+// global symbol and does not recycle the previous agent, so we keep our own
+// handle and close() it after a successful replacement.
+let ownedDispatcher = null;
+let lastManualApplyError = null;
+
+function getLastProxyApplyError() {
+  return lastManualApplyError;
+}
+
+function resetProxyApplyStateForTests() {
+  ownedDispatcher = null;
+  lastManualApplyError = null;
+  resetSystemProxyCacheForTests();
+}
+
+function closeDispatcherQuietly(dispatcher) {
+  if (!dispatcher || typeof dispatcher.close !== "function") return;
+  Promise.resolve()
+    .then(() => dispatcher.close())
+    .catch(() => {});
+}
+
+function warnManualApplyFailure(message, warn) {
+  const text = `[proxy] Failed to apply manual proxy; outbound traffic is blocked: ${message}`;
+  if (typeof warn === "function") {
+    warn(text);
+    return;
+  }
+  console.error(text);
+}
+
+const FAIL_CLOSED_MESSAGE = "manual proxy is not applied; outbound traffic is blocked";
+
+function createFailClosedDispatcher(reason) {
+  const message = reason ? `${FAIL_CLOSED_MESSAGE}: ${reason}` : FAIL_CLOSED_MESSAGE;
+  const error = () => Object.assign(new Error(message), { code: "PROXY_FAIL_CLOSED" });
+  try {
+    // eslint-disable-next-line global-require
+    const undici = require("undici");
+    if (typeof undici.Agent === "function") {
+      return new undici.Agent({
+        connect(_options, callback) {
+          if (typeof callback === "function") callback(error(), null);
+        },
+      });
+    }
+  } catch (_e) {
+    /* fall through to a minimal dispatcher */
+  }
+  return {
+    dispatch(_options, handler) {
+      if (handler && typeof handler.onError === "function") {
+        queueMicrotask(() => handler.onError(error()));
+      }
+      return true;
+    },
+    close() {
+      return Promise.resolve();
+    },
+    destroy() {
+      return Promise.resolve();
+    },
+  };
+}
+
+function installFailClosedDispatcher(parts, reason) {
+  if (!parts || typeof parts.setter !== "function") return false;
+  const next = createFailClosedDispatcher(reason);
+  try {
+    swapOwnedDispatcher(parts.setter, next);
+    return true;
+  } catch (_e) {
+    closeDispatcherQuietly(next);
+    return false;
+  }
+}
+
+/**
+ * Build an undici ProxyAgent for a user-configured proxy URL.
+ *
+ * CodeQL "Outbound network request depends on file data"
+ * (security/code-scanning/227): proxyUrl is the hop the user explicitly
+ * configured in Settings / config.json `proxy` (or HTTPS_PROXY / scutil).
+ * It reaches this function only after parseProxyPayload or
+ * normalizeProxyConfig + buildProxyUrl (manual) or pickProxyUrl /
+ * parseMacProxyOutput (system). This is the intended CONNECT/SOCKS target,
+ * not an unsanitized server-side request URL.
+ */
+function createProxyDispatcher(proxyUrl, { ProxyAgent } = {}) {
+  if (!proxyUrl) return null;
+  if (typeof ProxyAgent !== "function") return null;
+  return new ProxyAgent(proxyUrl);
+}
+
+function loadUndiciParts({ setGlobalDispatcher, ProxyAgent, Agent } = {}) {
+  let setter = setGlobalDispatcher;
+  let Proxy = ProxyAgent;
+  let Direct = Agent;
+  if (!setter || !Proxy || !Direct) {
+    try {
+      // eslint-disable-next-line global-require
+      const undici = require("undici");
+      setter = setter || undici.setGlobalDispatcher;
+      Proxy = Proxy || undici.ProxyAgent;
+      Direct = Direct || undici.Agent;
+    } catch (_e) {
+      return { setter: null, ProxyAgent: null, Agent: null };
+    }
+  }
+  return { setter, ProxyAgent: Proxy, Agent: Direct };
+}
+
+function resolveFetchImpl(fetchImpl) {
+  if (typeof fetchImpl === "function") return fetchImpl;
+  try {
+    // eslint-disable-next-line global-require
+    const undiciFetch = require("undici").fetch;
+    if (typeof undiciFetch === "function") return undiciFetch;
+  } catch (_e) {
+    /* fall through to the global */
+  }
+  return fetch;
+}
+
+const PROXY_TEST_TIMEOUT_MS = 5000;
+
+async function runProxyConnectivityTest({
+  proxyUrl,
+  targetUrl,
+  timeoutMs = PROXY_TEST_TIMEOUT_MS,
+  fetchImpl,
+  ProxyAgent,
+  Agent,
+  setGlobalDispatcher,
+} = {}) {
+  const started = Date.now();
+  const latency = () => Date.now() - started;
+  if (!proxyUrl) return { ok: false, error: "no proxy url", latencyMs: latency() };
+  if (!targetUrl) return { ok: false, error: "no test target", latencyMs: latency() };
+
+  let dispatcher = null;
+  try {
+    const parts = loadUndiciParts({ ProxyAgent, Agent, setGlobalDispatcher });
+    dispatcher = createProxyDispatcher(proxyUrl, parts);
+    if (!dispatcher) {
+      return { ok: false, error: "unsupported proxy protocol", latencyMs: latency() };
+    }
+    // Prefer undici.fetch: global fetch on some Node versions ignores the
+    // `dispatcher` option and would probe via the process-global agent.
+    const doFetch = resolveFetchImpl(fetchImpl);
+    const res = await doFetch(targetUrl, {
+      method: "GET",
+      dispatcher,
+      signal: AbortSignal.timeout(Math.min(timeoutMs, PROXY_TEST_TIMEOUT_MS)),
+    });
+    return { ok: true, status: res.status, latencyMs: latency() };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error), latencyMs: latency() };
+  } finally {
+    closeDispatcherQuietly(dispatcher);
+  }
 }
 
 // Node's built-in NODE_USE_ENV_PROXY support only landed in v22.21 / v24.5.
@@ -91,34 +369,101 @@ function pickProxyUrl(env = process.env) {
 // var is silently ignored and fetch() bypasses the proxy. Setting an undici
 // ProxyAgent dispatcher at startup gives us proxy support on every Node ≥ 18
 // regardless of the env-proxy flag.
+function swapOwnedDispatcher(setter, next) {
+  setter(next);
+  const previous = ownedDispatcher;
+  ownedDispatcher = next;
+  closeDispatcherQuietly(previous);
+}
+
+function installDirectAgent(parts) {
+  if (typeof parts.Agent !== "function" || typeof parts.setter !== "function") return false;
+  let next;
+  try {
+    next = new parts.Agent();
+  } catch (_e) {
+    return false;
+  }
+  try {
+    swapOwnedDispatcher(parts.setter, next);
+  } catch (_e) {
+    closeDispatcherQuietly(next);
+    return false;
+  }
+  return true;
+}
+
+function failManual(message, warn, parts) {
+  lastManualApplyError = message;
+  const installed = installFailClosedDispatcher(parts, message);
+  warnManualApplyFailure(message, warn);
+  if (!installed) return { ok: false, error: message, unprotected: true };
+  return { ok: false, error: message };
+}
+
 function applyUndiciProxyIfNeeded({
   env = process.env,
   setGlobalDispatcher,
   ProxyAgent,
+  Agent,
+  proxyConfig,
+  warn,
+  platform = process.platform,
+  commandRunner = cp.spawnSync,
 } = {}) {
-  const proxyUrl = pickProxyUrl(env);
-  if (!proxyUrl) return null;
+  const normalized = normalizeProxyConfig(proxyConfig);
+  const parts = loadUndiciParts({ setGlobalDispatcher, ProxyAgent, Agent });
 
-  let setter = setGlobalDispatcher;
-  let Agent = ProxyAgent;
-  if (!setter || !Agent) {
-    try {
-      // eslint-disable-next-line global-require
-      const undici = require("undici");
-      setter = setter || undici.setGlobalDispatcher;
-      Agent = Agent || undici.ProxyAgent;
-    } catch (_e) {
-      return null;
-    }
+  if (isDeclaredManual(proxyConfig) && normalized.mode !== "manual") {
+    return failManual(normalized.reason || "invalid manual proxy config", warn, parts);
   }
-  if (typeof setter !== "function" || typeof Agent !== "function") return null;
 
-  try {
-    setter(new Agent(proxyUrl));
-    return proxyUrl;
-  } catch (_e) {
+  if (normalized.mode === "off") {
+    if (typeof parts.setter !== "function") return null;
+    installDirectAgent(parts);
+    lastManualApplyError = null;
+    return null;
+  }
+
+  const resolved = resolveEffectiveProxyUrl({ env, proxyConfig, platform, commandRunner });
+  const proxyUrl = resolved.proxyUrl;
+  const manual = normalized.mode === "manual";
+
+  if (manual && !proxyUrl) {
+    return failManual("invalid manual proxy config", warn, parts);
+  }
+
+  if (!proxyUrl) {
+    if (ownedDispatcher) installDirectAgent(parts);
+    lastManualApplyError = null;
     return null;
   }
+
+  if (typeof parts.setter !== "function") {
+    return manual ? failManual("undici dispatcher is unavailable", warn, parts) : null;
+  }
+
+  let dispatcher;
+  try {
+    dispatcher = createProxyDispatcher(proxyUrl, parts);
+  } catch (error) {
+    const message = error?.message || String(error);
+    return manual ? failManual(message, warn, parts) : null;
+  }
+  if (!dispatcher) {
+    return manual ? failManual("failed to construct proxy dispatcher", warn, parts) : null;
+  }
+
+  try {
+    swapOwnedDispatcher(parts.setter, dispatcher);
+  } catch (error) {
+    closeDispatcherQuietly(dispatcher);
+    const message = error?.message || String(error);
+    return manual ? failManual(message, warn, parts) : null;
+  }
+
+  lastManualApplyError = null;
+  return { ok: true, proxyUrl };
 }
 
 module.exports = {
@@ -128,4 +473,12 @@ module.exports = {
   resolveSystemProxyEnv,
   relaunchWithProxyEnvIfNeeded,
   applyUndiciProxyIfNeeded,
+  createProxyDispatcher,
+  readPersistedProxyConfig,
+  resolveEffectiveProxySource,
+  runProxyConnectivityTest,
+  getLastProxyApplyError,
+  resetProxyApplyStateForTests,
+  invalidateSystemProxyCache,
+  resetSystemProxyCacheForTests,
 };

package/src/lib/proxy-settings.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const net = require("node:net");
+
+const PROXY_MODES = new Set(["system", "manual", "off"]);
+const PROXY_PROTOCOLS = new Set(["http", "https", "socks5"]);
+
+function defaultProxyConfig() {
+  return {
+    mode: "system",
+    protocol: "http",
+    host: "",
+    port: 0,
+  };
+}
+
+function normalizeMode(value) {
+  if (typeof value !== "string") return null;
+  const mode = value.trim().toLowerCase();
+  return PROXY_MODES.has(mode) ? mode : null;
+}
+
+function normalizeProtocol(value) {
+  if (typeof value !== "string") return null;
+  const protocol = value.trim().toLowerCase();
+  if (protocol === "socks") return "socks5";
+  return PROXY_PROTOCOLS.has(protocol) ? protocol : null;
+}
+
+function normalizeHost(value) {
+  if (typeof value !== "string") return null;
+  const host = value.trim();
+  if (!host) return null;
+  if (/:\/\//.test(host) || host.includes("/")) return null;
+  // Reject credentials, query/hash fragments, Windows-style paths, and
+  // internal whitespace so a host cannot reshape the assembled proxy URL.
+  if (/[@?#\\]/.test(host) || /\s/.test(host)) return null;
+  return host;
+}
+
+function normalizePort(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed)) return null;
+    value = Number(trimmed);
+  }
+  if (typeof value !== "number" || !Number.isInteger(value)) return null;
+  if (value < 1 || value > 65535) return null;
+  return value;
+}
+
+function fallbackSystem(reason) {
+  return { ...defaultProxyConfig(), reason };
+}
+
+/**
+ * Normalize a persisted or inbound proxy object.
+ * Invalid values fall back to mode=system and never throw.
+ */
+function normalizeProxyConfig(raw) {
+  if (raw == null) return defaultProxyConfig();
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return fallbackSystem("proxy config must be an object");
+  }
+
+  const mode = raw.mode == null || raw.mode === ""
+    ? "system"
+    : normalizeMode(raw.mode);
+  if (!mode) return fallbackSystem("invalid mode");
+
+  const protocol = normalizeProtocol(raw.protocol) || "http";
+  const host = typeof raw.host === "string" ? raw.host.trim() : "";
+  const port = normalizePort(raw.port) ?? 0;
+
+  if (mode !== "manual") {
+    return { mode, protocol, host, port };
+  }
+
+  const manualProtocol = normalizeProtocol(raw.protocol);
+  if (!manualProtocol) return fallbackSystem("invalid protocol");
+  const manualHost = normalizeHost(raw.host);
+  if (!manualHost) return fallbackSystem("invalid host");
+  const manualPort = normalizePort(raw.port);
+  if (manualPort == null) return fallbackSystem("invalid port");
+  return {
+    mode: "manual",
+    protocol: manualProtocol,
+    host: manualHost,
+    port: manualPort,
+  };
+}
+
+/**
+ * Strict payload check for POST /proxy-config.
+ * Rejects illegal values instead of coercing them.
+ */
+function parseProxyPayload(raw) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "proxy payload must be an object" };
+  }
+  const mode = normalizeMode(raw.mode);
+  if (!mode) {
+    return { ok: false, error: "mode must be system, manual, or off" };
+  }
+  if (mode !== "manual") {
+    return {
+      ok: true,
+      value: {
+        mode,
+        protocol: normalizeProtocol(raw.protocol) || "http",
+        host: typeof raw.host === "string" ? raw.host.trim() : "",
+        port: normalizePort(raw.port) ?? 0,
+      },
+    };
+  }
+  const protocol = normalizeProtocol(raw.protocol);
+  if (!protocol) {
+    return { ok: false, error: "protocol must be http, https, or socks5" };
+  }
+  const host = normalizeHost(raw.host);
+  if (!host) {
+    return { ok: false, error: "host must be a hostname or IP without a protocol prefix" };
+  }
+  const port = normalizePort(raw.port);
+  if (port == null) {
+    return { ok: false, error: "port must be an integer from 1 to 65535" };
+  }
+  return { ok: true, value: { mode, protocol, host, port } };
+}
+
+function bracketProxyHost(host) {
+  if (net.isIPv6(host)) return `[${host}]`;
+  if (host.startsWith("[") && host.endsWith("]")) {
+    const inner = host.slice(1, -1);
+    if (net.isIPv6(inner)) return `[${inner}]`;
+  }
+  // Bare or malformed hosts that merely contain a colon are not IPv6.
+  if (host.includes(":")) return null;
+  return host;
+}
+
+function buildProxyUrl(normalized) {
+  if (!normalized || normalized.mode !== "manual") return null;
+  const protocol = normalizeProtocol(normalized.protocol);
+  const host = normalizeHost(normalized.host);
+  const port = normalizePort(normalized.port);
+  if (!protocol || !host || port == null) return null;
+  const hostPart = bracketProxyHost(host);
+  if (!hostPart) return null;
+  return `${protocol}://${hostPart}:${port}`;
+}
+
+module.exports = {
+  PROXY_MODES,
+  PROXY_PROTOCOLS,
+  defaultProxyConfig,
+  normalizeProxyConfig,
+  parseProxyPayload,
+  buildProxyUrl,
+  normalizeProtocol,
+  normalizeHost,
+  normalizePort,
+};