unbound-cli 1.6.3 → 1.6.5

package/src/setup-report.js

@@ -0,0 +1,119 @@
+/**
+ * Best-effort reporting of onboarding/setup step failures to the backend's
+ * setup-failure ledger (POST /api/v1/setup/failed/).
+ *
+ * This is the client half of "no onboarding step fails silently": when a setup
+ * step fails (script exits non-zero, throws, or its download fails) the CLI
+ * records the failure against the device so it shows up server-side instead of
+ * vanishing.
+ *
+ * CONTRACT (do not change here — backend owns it):
+ *   POST {backendUrl}/api/v1/setup/failed/
+ *   body: { serial_number: string (<=255, required),
+ *           step: string (<=64, required),
+ *           exit_code: integer }
+ *   auth: same as /setup/complete/ — gateway API key in Authorization header,
+ *         User-Agent "UnboundCLI/<version>". install_mode/managed are forced
+ *         server-side, so we never send them.
+ *
+ * BEST-EFFORT, ALWAYS: a telemetry POST failure (offline, 429, 4xx, timeout)
+ * must NEVER mask or replace the real error shown to the user, and must NOT
+ * change the CLI's exit code. Every path here swallows its own errors.
+ */
+
+const os = require('os');
+const api = require('./api');
+const config = require('./config');
+
+// The failure report is best-effort telemetry that runs while the user is
+// already waiting on a real setup failure. Bound it tightly (well under the
+// default 30s API timeout) so a hung/slow backend can't delay surfacing the
+// user's error. On timeout the POST rejects and the catch below swallows it.
+const REPORT_TIMEOUT_MS = 3000;
+
+// JS-thrown error (no process exit code available).
+const EXIT_THROWN = 1;
+// Download/transport failure before any process ran.
+const EXIT_DOWNLOAD_FAILED = -1;
+
+/**
+ * Best-effort device identifier for the failure ledger. The Node CLI can't read
+ * the hardware serial reliably, so we use os.hostname() — the backend only uses
+ * serial_number as an org-scoped upsert key, not as a true hardware serial.
+ * Truncated to the backend's 255-char limit; falls back to "unknown-device".
+ */
+function deviceIdentifier() {
+  let name;
+  try { name = os.hostname(); } catch { name = null; }
+  if (!name || typeof name !== 'string' || !name.trim()) return 'unknown-device';
+  return name.trim().slice(0, 255);
+}
+
+// Normalize a step name to the backend's 64-char limit so an over-long stage
+// label can't cause a 400 that we'd then (silently) drop.
+function normalizeStep(step) {
+  const s = (step == null ? '' : String(step)).trim() || 'unknown';
+  return s.slice(0, 64);
+}
+
+// Coerce to an integer exit code; default to the thrown-error sentinel.
+function normalizeExitCode(code) {
+  const n = Number(code);
+  return Number.isInteger(n) ? n : EXIT_THROWN;
+}
+
+// Maps a caught error to the exit code we report to the ledger: a download
+// failure uses the download sentinel, a script exit uses its real code, and
+// anything else falls back to the thrown sentinel.
+function exitCodeForError(err) {
+  if (err && err.downloadFailed) return EXIT_DOWNLOAD_FAILED;
+  if (err && Number.isInteger(err.exitCode)) return err.exitCode;
+  return EXIT_THROWN;
+}
+
+/**
+ * Reports a single failed setup step. Resolves to true if the POST succeeded,
+ * false otherwise — but NEVER rejects, so callers can `await` it inline in an
+ * error path without risk of masking the original failure.
+ *
+ * @param {object} args
+ * @param {string} args.step      - the tool/stage that failed (<=64 chars).
+ * @param {number} args.exitCode  - the process exit code (or a sentinel).
+ * @param {string} [args.apiKey]  - gateway API key (defaults to stored key).
+ * @param {string} [args.backendUrl] - explicit backend URL override.
+ */
+async function reportSetupFailure({ step, exitCode, apiKey, backendUrl } = {}) {
+  try {
+    const key = apiKey || config.getApiKey();
+    // No key → nothing to authenticate with; the ledger upserts by org, so a
+    // keyless report can't be attributed. Skip quietly.
+    if (!key) return false;
+
+    await api.post('/api/v1/setup/failed/', {
+      apiKey: key,
+      baseUrl: backendUrl,
+      timeoutMs: REPORT_TIMEOUT_MS,
+      body: {
+        serial_number: deviceIdentifier(),
+        step: normalizeStep(step),
+        exit_code: normalizeExitCode(exitCode),
+      },
+    });
+    return true;
+  } catch {
+    // Offline / 429 / 4xx / timeout — all swallowed. Telemetry must never
+    // surface over the real error or change the exit code.
+    return false;
+  }
+}
+
+module.exports = {
+  reportSetupFailure,
+  deviceIdentifier,
+  exitCodeForError,
+  EXIT_THROWN,
+  EXIT_DOWNLOAD_FAILED,
+  // Exported for tests:
+  _normalizeStep: normalizeStep,
+  _normalizeExitCode: normalizeExitCode,
+};

package/src/telemetry.js

@@ -0,0 +1,201 @@
+/**
+ * Opt-out Sentry error reporting for the CLI.
+ *
+ * Design constraints (see onboarding-failure-observability spec):
+ *  - No DSN env var (UNBOUND_CLI_SENTRY_DSN) → fully disabled. Nothing inits,
+ *    no network, no throw. The DSN is filled in later by the maintainer.
+ *  - UNBOUND_TELEMETRY in {0,false,no} → disabled even if a DSN is present.
+ *  - beforeSend scrubs secrets (API/discovery keys), home-dir file paths, and
+ *    the OS username before anything leaves the machine.
+ *  - The CLI is short-lived, so callers must flush() before the process exits
+ *    or queued events are dropped.
+ *
+ * Everything here is best-effort: a Sentry failure must never change the CLI's
+ * own behavior or exit code. All entry points swallow their own errors.
+ */
+
+const os = require('os');
+const { version } = require('../package.json');
+
+let Sentry = null;        // lazily required only when we actually init
+let initialized = false;
+
+// Opt-out: any of these values (case-insensitive) for UNBOUND_TELEMETRY disables
+// telemetry entirely. Unset / any other value leaves it enabled (subject to DSN).
+function telemetryOptedOut() {
+  const v = (process.env.UNBOUND_TELEMETRY || '').trim().toLowerCase();
+  return v === '0' || v === 'false' || v === 'no';
+}
+
+function isEnabled() {
+  return !!process.env.UNBOUND_CLI_SENTRY_DSN && !telemetryOptedOut();
+}
+
+// Matches secret-key-shaped tokens so a value that slips into a message/path is
+// redacted even when we don't know which flag produced it. Conservative on
+// length so ordinary words aren't clobbered.
+const KEY_RE = /\b(?:sk|pk|ub|unb|gw|disc)[-_][A-Za-z0-9_-]{8,}\b/gi;
+
+// Redacts known-sensitive substrings from an arbitrary string: the concrete
+// key values we were handed, then key-shaped tokens, then home-dir paths and
+// the OS username. Returns the input unchanged when not a string.
+function scrubString(str, secrets) {
+  if (typeof str !== 'string' || !str) return str;
+  let out = str;
+  for (const secret of secrets) {
+    if (secret) out = out.split(secret).join('[redacted]');
+  }
+  out = out.replace(KEY_RE, '[redacted]');
+  try {
+    const home = os.homedir();
+    if (home) out = out.split(home).join('~');
+  } catch { /* ignore */ }
+  try {
+    const username = os.userInfo().username;
+    if (username && username.length >= 3) {
+      out = out.split(username).join('[user]');
+    }
+  } catch { /* ignore */ }
+  return out;
+}
+
+// Recursively scrub strings in nested event structures (messages, exception
+// values, stack frame paths, breadcrumbs). Depth-bounded so a pathological
+// event can't blow the stack.
+function scrubDeep(value, secrets, depth) {
+  if (depth > 8 || value == null) return value;
+  if (typeof value === 'string') return scrubString(value, secrets);
+  if (Array.isArray(value)) return value.map((v) => scrubDeep(v, secrets, depth + 1));
+  if (typeof value === 'object') {
+    for (const k of Object.keys(value)) {
+      value[k] = scrubDeep(value[k], secrets, depth + 1);
+    }
+  }
+  return value;
+}
+
+// Collects the concrete secret values passed on the command line so beforeSend
+// can redact the exact strings (not just key-shaped guesses). Mutated by
+// rememberSecret(); kept tiny.
+const knownSecrets = new Set();
+
+function rememberSecret(value) {
+  if (typeof value === 'string' && value.length >= 6) knownSecrets.add(value);
+}
+
+function beforeSend(event) {
+  try {
+    const secrets = [...knownSecrets];
+    // Drop server_name (often the hostname) and the user object before scrub.
+    delete event.server_name;
+    if (event.user) delete event.user.username;
+    scrubDeep(event, secrets, 0);
+  } catch {
+    // Never let scrubbing throw — if we can't scrub safely, drop the event.
+    return null;
+  }
+  return event;
+}
+
+/**
+ * Initializes Sentry if (and only if) a DSN is configured and telemetry is not
+ * opted out. Safe to call once at startup. Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.runId] - shared onboard/setup/discover run id (tag).
+ * @param {string} [opts.flow]  - flow name tag (defaults to 'onboard').
+ */
+function init({ runId, flow = 'onboard' } = {}) {
+  if (initialized || !isEnabled()) return;
+  try {
+    Sentry = require('@sentry/node');
+    Sentry.init({
+      dsn: process.env.UNBOUND_CLI_SENTRY_DSN,
+      release: `unbound-cli@${version}`,
+      // We only want explicit captures, not unrelated auto-instrumentation noise.
+      integrations: [],
+      defaultIntegrations: false,
+      tracesSampleRate: 0,
+      sendDefaultPii: false,
+      beforeSend,
+    });
+    Sentry.setTags({
+      flow,
+      cli_version: version,
+      platform: process.platform,
+      ...(runId ? { run_id: runId } : {}),
+    });
+    initialized = true;
+  } catch {
+    // Missing module / bad DSN / anything — telemetry just stays off.
+    Sentry = null;
+    initialized = false;
+  }
+}
+
+/**
+ * Captures an error if telemetry is active. No-op otherwise. Never throws and
+ * never changes the caller's control flow — callers rethrow/exit on their own.
+ */
+function captureError(err, context = {}) {
+  if (!initialized || !Sentry) return;
+  try {
+    Sentry.captureException(err, context.tags ? { tags: context.tags } : undefined);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Flushes queued events with a short bound, then closes the client. Must be
+ * awaited before the process exits or short-lived runs lose their events.
+ * Never throws.
+ */
+async function flush(timeoutMs = 2000) {
+  if (!initialized || !Sentry) return;
+  try {
+    // close() flushes queued events and then disables the client. Calling
+    // flush() first would only double the worst-case exit latency (2x
+    // timeoutMs) for a short-lived CLI, so close() alone is enough.
+    await Sentry.close(timeoutMs);
+  } catch { /* best-effort */ }
+  initialized = false;
+}
+
+/**
+ * Wraps a command action so any thrown error is captured to Sentry (before
+ * being rethrown) and queued events are flushed before the process exits.
+ * Because the CLI is short-lived, the flush is the only thing keeping events
+ * alive — so it runs on BOTH the success and error paths.
+ *
+ * The wrapper preserves the action's own error handling: it rethrows, so the
+ * existing try/catch inside the action (which sets process.exitCode and prints
+ * the message) still runs exactly as before. Telemetry never changes behavior.
+ *
+ * @param {string} flow - flow tag for captured events (e.g. 'setup').
+ * @param {(...args:any[])=>Promise<any>} action - the commander action handler.
+ */
+function wrapAction(flow, action) {
+  return async (...args) => {
+    try {
+      const result = await action(...args);
+      await flush();
+      return result;
+    } catch (err) {
+      captureError(err, { tags: { flow } });
+      await flush();
+      throw err;
+    }
+  };
+}
+
+module.exports = {
+  init,
+  captureError,
+  flush,
+  wrapAction,
+  rememberSecret,
+  isEnabled,
+  // Exported for tests:
+  _beforeSend: beforeSend,
+  _scrubString: scrubString,
+  _telemetryOptedOut: telemetryOptedOut,
+};

package/src/utils.js

@@ -1,5 +1,8 @@
 const readline = require('readline');
 const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
 const https = require('https');
 
 function formatDate(dateStr) {
@@ -31,14 +34,38 @@ function shellEscape(str) {
 }
 
 /**
- * Downloads a URL to a local file, following up to 3 redirects.
- * Forwards response-stream errors to the Promise rejection so callers
- * (and their finally blocks) can clean up partial downloads.
+ * Downloads a URL to a local file, following up to 3 redirects. This is the
+ * ONE secure implementation — setup.js and discover.js both import it so the
+ * download-then-run paths (which `sudo unbound …` executes as ROOT) share a
+ * single hardened code path instead of drifted copies.
+ *
+ * SECURITY: the script file we are about to EXECUTE must not be attacker-
+ * controllable. `destPath` is expected to live inside a per-run private temp dir
+ * (see withSecureTempFile / mkdtempSync, mode 0700) so it can't be pre-created
+ * or symlinked by a local attacker. As defense in depth we ALSO open the file
+ * with O_EXCL|O_NOFOLLOW via createWriteStream({ flags: 'wx' }) and mode 0o600:
+ * an existing path or symlink at destPath yields EEXIST/ELOOP and rejects rather
+ * than being followed or overwritten. This closes the TOCTOU root-privesc window.
+ *
+ * Verifies BOTH a 200 status AND a non-empty body before resolving: a 200 with
+ * zero bytes is a failed download (the script never arrived), not a runnable
+ * empty script. This is what lets the download-then-run paths close the old
+ * `curl | bash` / `curl | python3` pipe hole, where a failed download still
+ * exited 0.
+ *
+ * On any transport/stream error the partner stream is destroyed and the partial
+ * file is unlinked before rejecting, so a one-shot CLI doesn't leak a socket or
+ * leave a partial temp file behind (the mkdtemp-dir cleanup also covers it).
+ *
+ * Injectable transport (tests only): pass `{ transport }` to use a custom
+ * https-like module exposing `.get(url, cb)`, so the SHIPPED function can be
+ * exercised against a local server instead of real network/TLS.
  */
-function downloadToFile(url, destPath) {
+function downloadToFile(url, destPath, { transport } = {}) {
+  const client = transport || https;
   return new Promise((resolve, reject) => {
     const request = (u, remaining) => {
-      https.get(u, (res) => {
+      client.get(u, (res) => {
         if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && remaining > 0) {
           res.resume();
           return request(res.headers.location, remaining - 1);
@@ -47,17 +74,66 @@ function downloadToFile(url, destPath) {
           res.resume();
           return reject(new Error(`Failed to download ${u}: HTTP ${res.statusCode}`));
         }
-        const file = fs.createWriteStream(destPath);
+        // wx = O_CREAT|O_EXCL (fail if it already exists, never follow a symlink
+        // into it); mode 0o600 keeps the downloaded script owner-only.
+        const file = fs.createWriteStream(destPath, { flags: 'wx', mode: 0o600 });
+        let bytes = 0;
+        let settled = false;
+        const fail = (err) => {
+          if (settled) return;
+          settled = true;
+          // Tear down both ends so a one-shot CLI doesn't leak a socket.
+          res.destroy();
+          file.destroy();
+          // Remove the partial file we wrote — but NOT when the open itself
+          // failed (EEXIST from `wx` / ELOOP from a symlink): that file/symlink
+          // is pre-existing and attacker-controlled, so we must never delete it.
+          if (err && (err.code === 'EEXIST' || err.code === 'ELOOP')) {
+            reject(err);
+            return;
+          }
+          fs.unlink(destPath, () => reject(err));
+        };
+        res.on('data', (chunk) => { bytes += chunk.length; });
+        res.on('error', fail);
+        file.on('error', fail);
         res.pipe(file);
-        res.on('error', reject);
-        file.on('finish', () => file.close(resolve));
-        file.on('error', reject);
+        file.on('finish', () => file.close(() => {
+          if (settled) return;
+          if (bytes === 0) {
+            settled = true;
+            fs.unlink(destPath, () => reject(new Error(`Failed to download ${u}: empty response body`)));
+            return;
+          }
+          settled = true;
+          resolve();
+        }));
       }).on('error', reject);
     };
     request(url, 3);
   });
 }
 
+/**
+ * Runs `fn(filePath)` with `filePath` pointing inside a freshly-created PRIVATE
+ * temp directory (fs.mkdtempSync, mode 0700), then removes the whole directory
+ * (and the file) afterward — success or failure. A private dir defeats symlink/
+ * pre-creation attacks on the predictable old /tmp path, and the random file
+ * name uses crypto.randomUUID() rather than Date.now()+Math.random().
+ *
+ * @param {string} suffix       file extension incl. dot, e.g. '.py' or '.sh'.
+ * @param {(p:string)=>Promise} fn  receives the absolute temp file path.
+ */
+async function withSecureTempFile(suffix, fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-'));
+  const file = path.join(dir, `${crypto.randomUUID()}${suffix}`);
+  try {
+    return await fn(file);
+  } finally {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+}
+
 const DISCOVER_BASE_URL = 'https://raw.githubusercontent.com/websentry-ai/coding-discovery-tool/refs/heads/main';
 
-module.exports = { formatDate, confirm, parseCommaSeparated, shellEscape, downloadToFile, DISCOVER_BASE_URL };
+module.exports = { formatDate, confirm, parseCommaSeparated, shellEscape, downloadToFile, withSecureTempFile, DISCOVER_BASE_URL };

package/test/auth-server-leak.test.js

@@ -0,0 +1,201 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const { URL } = require('url');
+
+// WEB-4941, root cause #1: loginWithBrowser's local callback server leaked a
+// keep-alive socket. server.close() stops accepting NEW connections but does NOT
+// destroy the socket the browser holds open via HTTP/1.1 keep-alive, so the
+// process stayed alive ~60s. The fix sets `Connection: close` on every response
+// and force-drops lingering sockets via closeAllConnections (shutdownServer).
+//
+// These tests drive the REAL loginWithBrowser through its injected `open` seam,
+// reproducing the exact leaking condition with a keepAlive agent, and assert
+// (a) the success result, (b) every response carries `connection: close`, and
+// (c) the server actually stopped listening (fresh connect → ECONNREFUSED).
+// No real ~/.unbound write, no real network beyond loopback, no real browser.
+
+const auth = require('../src/auth');
+const config = require('../src/config');
+
+// Issues a single GET over a keepAlive agent and resolves with status, headers,
+// and the underlying client socket. keepAlive is the load-bearing detail: it
+// reproduces the exact socket the browser holds open, so this test FAILS against
+// the pre-fix code (which left that socket — and the event loop — open).
+function getKeepAlive(agent, url) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, { agent }, (res) => {
+      res.resume(); // drain the body so the response completes
+      res.on('end', () => resolve({ statusCode: res.statusCode, headers: res.headers, socket: req.socket }));
+    });
+    req.on('error', reject);
+  });
+}
+
+// The actual leak-proof: post-fix the server force-closes the answered socket
+// (Connection: close + closeAllConnections), so the client socket emits 'close'
+// promptly. Against the pre-fix code the socket stayed in keep-alive limbo and
+// this would time out — so THIS assertion (with the Connection: close header) is
+// what distinguishes the fix. expectConnectionRefused below only proves the
+// server stopped listening, which a bare server.close() already did pre-fix.
+function expectSocketClosed(socket, ms) {
+  if (socket.destroyed) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`socket was not closed within ${ms}ms — keep-alive leak`)),
+      ms,
+    );
+    socket.once('close', () => { clearTimeout(timer); resolve(); });
+  });
+}
+
+// Confirms shutdownServer ran: a fresh connection to the port is refused.
+function expectConnectionRefused(port) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`http://localhost:${port}/callback`, (res) => {
+      res.resume();
+      reject(new Error(`expected ECONNREFUSED but got HTTP ${res.statusCode}`));
+    });
+    req.on('error', (err) => {
+      if (err.code === 'ECONNREFUSED') resolve();
+      else reject(err);
+    });
+  });
+}
+
+// Pulls the callback_url the server told the browser to redirect to, then
+// appends the success params the /callback handler reads (api_key/email/org).
+function buildSuccessCallback(authUrl) {
+  const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+  return `${callbackUrl}?api_key=sk-test&email=a@b.co&org=Acme`;
+}
+
+// Monkeypatch config so no real ~/.unbound write happens. Restored in finally.
+function withStubbedConfig(fn) {
+  const saved = {
+    setApiKey: config.setApiKey,
+    writeConfig: config.writeConfig,
+    readConfig: config.readConfig,
+  };
+  config.setApiKey = () => {};
+  config.writeConfig = () => {};
+  config.readConfig = () => ({});
+  return Promise.resolve()
+    .then(fn)
+    .finally(() => {
+      config.setApiKey = saved.setApiKey;
+      config.writeConfig = saved.writeConfig;
+      config.readConfig = saved.readConfig;
+    });
+}
+
+// Hard safety net so a regression that reintroduces the leak can't hang CI.
+function withTimeout(promise, ms, label) {
+  let timer;
+  const guard = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, guard]).finally(() => clearTimeout(timer));
+}
+
+test('loginWithBrowser: success path resolves, sets Connection: close, and stops listening', async () => {
+  await withStubbedConfig(async () => {
+    const agent = new http.Agent({ keepAlive: true });
+    let port;
+    let successHeaders;
+    let successSocket;
+
+    const fakeOpen = async (authUrl) => {
+      port = Number(new URL(new URL(authUrl).searchParams.get('callback_url')).port);
+      const res = await getKeepAlive(agent, buildSuccessCallback(authUrl));
+      successHeaders = res.headers;
+      successSocket = res.socket;
+    };
+
+    try {
+      const result = await withTimeout(
+        auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+        10_000,
+        'loginWithBrowser success path',
+      );
+
+      assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+      assert.equal(successHeaders.connection, 'close', 'success response must set Connection: close');
+
+      // The leak-proof: the held keep-alive socket is actually closed by the
+      // server. This times out (fails) against the pre-fix code.
+      await expectSocketClosed(successSocket, 5_000);
+
+      // Secondary: the server also stopped listening (fresh connect refused).
+      await withTimeout(expectConnectionRefused(port), 5_000, 'fresh connect after shutdown');
+    } finally {
+      agent.destroy();
+    }
+  });
+});
+
+test('loginWithBrowser: 404 path also sets Connection: close', async () => {
+  await withStubbedConfig(async () => {
+    const agent = new http.Agent({ keepAlive: true });
+    let notFoundHeaders;
+
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      const origin = new URL(callbackUrl).origin;
+      // 404 first (non-/callback path) — the server is still up; then the real
+      // /callback to let loginWithBrowser resolve and shut the server down.
+      const notFound = await getKeepAlive(agent, `${origin}/nope`);
+      notFoundHeaders = notFound.headers;
+      await getKeepAlive(agent, buildSuccessCallback(authUrl));
+    };
+
+    try {
+      await withTimeout(
+        auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+        10_000,
+        'loginWithBrowser 404-then-success',
+      );
+
+      assert.equal(notFoundHeaders.connection, 'close', '404 response must set Connection: close');
+    } finally {
+      agent.destroy();
+    }
+  });
+});
+
+test('loginWithBrowser: missing-api-key path rejects, sets Connection: close, and tears down', async () => {
+  await withStubbedConfig(async () => {
+    const agent = new http.Agent({ keepAlive: true });
+    let resolveCallback;
+    let rejectCallback;
+    const callbackDone = new Promise((res, rej) => { resolveCallback = res; rejectCallback = rej; });
+
+    // Mirror the real `open`: it returns after launching the browser, and the
+    // /callback request arrives over HTTP a tick LATER — after loginWithBrowser
+    // is already awaiting callbackPromise. Firing it inline (before that await)
+    // would reject an unhandled promise. Hitting /callback with no api_key drives
+    // the 400 reject + shutdown path. Forward a client error to callbackDone so a
+    // failed request surfaces as a test failure rather than a hang.
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(() => { getKeepAlive(agent, callbackUrl).then(resolveCallback, rejectCallback); });
+    };
+
+    try {
+      await withTimeout(
+        assert.rejects(
+          () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+          /No API key received/,
+        ),
+        10_000,
+        'loginWithBrowser missing-api-key path',
+      );
+
+      const res = await withTimeout(callbackDone, 5_000, 'missing-api-key callback');
+      assert.equal(res.headers.connection, 'close', '400 response must set Connection: close');
+      await expectSocketClosed(res.socket, 5_000);
+    } finally {
+      agent.destroy();
+    }
+  });
+});