unbound-cli 1.6.4 → 1.7.0

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/toolHealth.js

@@ -126,6 +126,26 @@ function scriptCheck(label, file, kind = 'structural') {
   return { name: label, ok, kind, detail: ok ? file : `not found (${file})`, summary: `${label.toLowerCase()} missing` };
 }
 
+// Set-but-non-empty check + value capture, intended for per-tool API key envs.
+// WEB-4949: API keys are not equality-checked against the stored
+// `config.api_key` — per-tool keys can legitimately differ for the same tenant
+// (different keys for Cursor vs Codex, dashboard-rotated key, etc.). The
+// `keyCheck`/`envName`/`value` tags let `validateToolKeys` revisit each
+// captured value and flip the check not-ok when the gateway rejects it.
+function envKeyCheck(label, name, kind = 'aux') {
+  const base = label.replace(/ env$/, '');
+  const r = readEnvVar(name);
+  if (!r.found || !r.value) {
+    return { name: label, ok: false, kind, detail: `${name} is not set`, summary: `${base} not set` };
+  }
+  return {
+    name: label, ok: true, kind,
+    detail: `${name} set (${r.source})`,
+    summary: `${base} set`,
+    keyCheck: true, envName: name, value: r.value,
+  };
+}
+
 function envCheck(label, name, expected, kind = 'aux') {
   const base = label.replace(/ env$/, '');
   const r = readEnvVar(name);
@@ -217,8 +237,11 @@ function refsUnbound(obj) {
 }
 
 // One descriptor per (tool, mode). `family` groups the two-mode tools so the
-// collapsed view shows a single line per product.
-function buildVariants(gatewayUrl, apiKey, binaryPath) {
+// collapsed view shows a single line per product. `apiKey` is no longer
+// equality-checked (WEB-4949) — per-tool keys can legitimately differ from
+// the stored login key. Use `validateToolKeys` post-detection to verify each
+// captured key against the gateway.
+function buildVariants(gatewayUrl, binaryPath) {
   const gw = (gatewayUrl || GATEWAY_DEFAULT).replace(/\/+$/, ''); // setup rstrips too
   return [
     {
@@ -226,7 +249,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       checks: () => [
         configCheck('Config', '~/.cursor/hooks.json', { json: true, test: refsUnbound }),
         scriptCheck('Hook script', '~/.cursor/hooks/unbound.py'),
-        envCheck('API key env', 'UNBOUND_CURSOR_API_KEY', apiKey),
+        envKeyCheck('API key env', 'UNBOUND_CURSOR_API_KEY'),
       ],
     },
     {
@@ -234,7 +257,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       checks: () => [
         configCheck('Config', '~/.claude/settings.json', { json: true, test: refsUnbound }),
         scriptCheck('Hook script', '~/.claude/hooks/unbound.py'),
-        envCheck('API key env', 'UNBOUND_CLAUDE_API_KEY', apiKey),
+        envKeyCheck('API key env', 'UNBOUND_CLAUDE_API_KEY'),
       ],
     },
     {
@@ -242,7 +265,9 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       checks: () => [
         configCheck('Config', '~/.claude/settings.json', { json: true, test: (j) => typeof j.apiKeyHelper === 'string' && j.apiKeyHelper.includes('anthropic_key.sh') }),
         scriptCheck('Key helper', '~/.claude/anthropic_key.sh'),
-        envCheck('API key env', 'UNBOUND_API_KEY', apiKey),
+        envKeyCheck('API key env', 'UNBOUND_API_KEY'),
+        // Gateway URL is a real equality check — the hook must point at the
+        // configured backend; tenants don't generate different gateway URLs.
         envCheck('Gateway URL env', 'ANTHROPIC_BASE_URL', gw),
       ],
     },
@@ -252,14 +277,14 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
         configCheck('Config', '~/.codex/hooks.json', { json: true, test: refsUnbound }),
         configCheck('Hooks feature flag', '~/.codex/config.toml', { json: false, test: (t) => /codex_hooks\s*=\s*true/.test(t) }, { short: 'codex hooks not enabled' }),
         scriptCheck('Hook script', '~/.codex/hooks/unbound.py'),
-        envCheck('API key env', 'UNBOUND_CODEX_API_KEY', apiKey),
+        envKeyCheck('API key env', 'UNBOUND_CODEX_API_KEY'),
       ],
     },
     {
       key: 'codex-gateway', label: 'Codex (gateway)', family: 'codex', mode: 'gateway',
       checks: () => [
         configCheck('Config', '~/.codex/config.toml', { json: false, test: (t) => /openai_base_url\s*=/.test(t) }),
-        envCheck('API key env', 'OPENAI_API_KEY', apiKey),
+        envKeyCheck('API key env', 'OPENAI_API_KEY'),
       ],
     },
     {
@@ -276,7 +301,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
         const checks = [configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound })];
         if (hasBinary) checks.push(scriptCheck('Hook binary', binaryPath || BINARY_PATH));
         else checks.push(scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'));
-        checks.push(envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey));
+        checks.push(envKeyCheck('API key env', 'UNBOUND_COPILOT_API_KEY'));
         return checks;
       },
     },
@@ -305,8 +330,8 @@ function detectVariant(variant) {
 // org-managed scenarios can be exercised without writing under /Library or /etc.
 // `_binaryPath` (test-only) overrides the system hook-binary path so binary-mode
 // scenarios can be exercised without writing under /opt.
-function detectTools({ gatewayUrl, apiKey, _mdmDirs, _binaryPath } = {}) {
-  const variants = buildVariants(gatewayUrl, apiKey, _binaryPath).map(detectVariant);
+function detectTools({ gatewayUrl, _mdmDirs, _binaryPath } = {}) {
+  const variants = buildVariants(gatewayUrl, _binaryPath).map(detectVariant);
   const families = [];
   const seen = new Set();
   for (const v of variants) {
@@ -337,4 +362,80 @@ function detectTools({ gatewayUrl, apiKey, _mdmDirs, _binaryPath } = {}) {
   return families;
 }
 
-module.exports = { detectTools, statusOf, readEnvVar, GATEWAY_DEFAULT };
+// WEB-4949: Validate each tool's captured env-var key against the gateway and
+// mutate the corresponding `keyCheck: true` entries in place. Fail-open: an
+// 'unknown' verdict (network error, timeout, 5xx) leaves the check healthy
+// but tags it `validationSkipped: true` so status/doctor can surface
+// "gateway unreachable — N key(s) not verified" instead of silently lying.
+// Unique keys are fanned out in parallel so N tools share one round-trip's
+// worth of latency. `validateKey` is
+// `(key) => Promise<'valid'|'invalid'|'unknown'>` — injected from
+// status/doctor (which wrap `api.validateApiKey`) so tests can stub it. A
+// validator that throws is coerced to 'unknown' so a regression in the api
+// client can never wipe out the local-state view callers depend on.
+async function validateToolKeys(tools, validateKey) {
+  if (!tools?.length) return tools;
+  const unique = new Set();
+  for (const t of tools) {
+    for (const c of t.checks || []) {
+      if (c.keyCheck && c.value) unique.add(c.value);
+    }
+  }
+  if (!unique.size) return tools;
+  const entries = await Promise.all(
+    [...unique].map(async (k) => {
+      try {
+        return [k, await validateKey(k)];
+      } catch {
+        return [k, 'unknown'];
+      }
+    })
+  );
+  const validity = new Map(entries);
+  for (const t of tools) {
+    if (!t.checks?.length) continue;
+    let okFlipped = false;
+    for (const c of t.checks) {
+      if (!c.keyCheck) continue;
+      const verdict = validity.get(c.value);
+      if (verdict === 'invalid') {
+        c.ok = false;
+        c.warn = true;
+        const base = c.name.replace(/ env$/, '');
+        c.summary = `${base} invalid`;
+        c.detail = `${c.envName} set but not valid for this tenant`;
+        okFlipped = true;
+      } else if (verdict === 'unknown') {
+        // Stay healthy (fail-open), but record the skip so the caller can
+        // surface it. Without this tag the operator can't tell an offline
+        // run from a fully-validated one — that's the WEB-4922 lesson.
+        // Does NOT flip `ok`, so the `statusOf` re-derivation stays guarded.
+        c.validationSkipped = true;
+        c.detail = `${c.detail}; validation skipped — gateway unreachable`;
+      }
+    }
+    // ONLY re-derive when a check's `ok` actually flipped. Without this guard,
+    // `statusOf` overwrites `managed-by-mdm` (the sentinel `detectTools` sets
+    // for MDM-managed tools) back to a plain 'healthy', erasing the MDM badge
+    // from both human + JSON output. MDM checks have no `keyCheck` entries so
+    // this guard naturally excludes them — no MDM-specific carve-out needed.
+    if (okFlipped) t.status = statusOf(t.checks);
+  }
+  return tools;
+}
+
+// WEB-4949: Convenience accessor for status/doctor. Returns the count of
+// `keyCheck` entries flagged `validationSkipped: true` across all tools.
+// Used to render a one-line "N key(s) not verified" note when the validator
+// failed open. Returns 0 when validation ran cleanly or no key checks exist.
+function countValidationSkipped(tools) {
+  let n = 0;
+  for (const t of tools || []) {
+    for (const c of t.checks || []) {
+      if (c.keyCheck && c.validationSkipped) n += 1;
+    }
+  }
+  return n;
+}
+
+module.exports = { detectTools, statusOf, readEnvVar, validateToolKeys, countValidationSkipped, GATEWAY_DEFAULT };

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/api-validate-key.test.js

@@ -0,0 +1,107 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const api = require('../src/api');
+
+// WEB-4949: validateApiKey wraps the /api/v1/users/privileges/ probe with the
+// fail-open semantics status/doctor need. Stand up a real local HTTP server
+// per case so we exercise the actual transport (timeout, status mapping, no
+// throw on 4xx) instead of mocking the api client.
+function withServer(handler, fn) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(handler);
+    server.listen(0, '127.0.0.1', async () => {
+      const { address, port } = server.address();
+      const baseUrl = `http://${address}:${port}`;
+      try {
+        await fn(baseUrl);
+        resolve();
+      } catch (err) {
+        reject(err);
+      } finally {
+        server.close();
+      }
+    });
+    server.on('error', reject);
+  });
+}
+
+test('validateApiKey: 200 → valid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(200, { 'content-type': 'application/json' }); res.end('{}'); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'valid');
+    }
+  );
+});
+
+test('validateApiKey: 401 → invalid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(401, { 'content-type': 'application/json' }); res.end('{"error":"bad key"}'); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'invalid');
+    }
+  );
+});
+
+test('validateApiKey: 403 → invalid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(403); res.end(''); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'invalid');
+    }
+  );
+});
+
+test('validateApiKey: 500 → unknown (fail-open)', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(500); res.end(''); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'unknown');
+    }
+  );
+});
+
+test('validateApiKey: timeout → unknown (fail-open)', async () => {
+  // Handler never responds; short timeout forces the unknown branch.
+  await withServer(
+    (_req, _res) => { /* hang */ },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl, timeoutMs: 100 }), 'unknown');
+    }
+  );
+});
+
+test('validateApiKey: connection refused → unknown (fail-open)', async () => {
+  // Pick a localhost port nothing is listening on. 1 is reliably refused.
+  assert.equal(
+    await api.validateApiKey('k', { baseUrl: 'http://127.0.0.1:1', timeoutMs: 500 }),
+    'unknown'
+  );
+});
+
+test('validateApiKey: missing key → invalid without a network call', async () => {
+  // baseUrl points at a dead port; if we made a network call the test would
+  // hang or take ages. A short timeout would also work but is unnecessary
+  // because the function should short-circuit before any IO.
+  assert.equal(await api.validateApiKey('', { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+  assert.equal(await api.validateApiKey(null, { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+  assert.equal(await api.validateApiKey(undefined, { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+});
+
+test('validateApiKey: sends the key as bearer + hits /api/v1/users/privileges/', async () => {
+  let observedAuth = null;
+  let observedPath = null;
+  await withServer(
+    (req, res) => {
+      observedAuth = req.headers['authorization'];
+      observedPath = req.url;
+      res.writeHead(200, { 'content-type': 'application/json' }); res.end('{}');
+    },
+    async (baseUrl) => {
+      await api.validateApiKey('sk-abc123', { baseUrl });
+      assert.equal(observedAuth, 'Bearer sk-abc123');
+      assert.ok(observedPath.startsWith('/api/v1/users/privileges/'), observedPath);
+    }
+  );
+});