unbound-cli 1.6.5 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.6.5",
+  "version": "1.7.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/api.js

@@ -141,6 +141,25 @@ function getRaw(url) {
   });
 }
 
+// WEB-4949: Probe whether a key is tenant-valid by hitting the same endpoint
+// `unbound login` uses. 200 -> valid, 401/403 -> invalid, anything else
+// (timeout, DNS, 5xx) -> unknown. Callers in status/doctor fail open on
+// 'unknown' so an offline laptop doesn't false-tamper. Short default timeout
+// (3s) keeps `unbound status` snappy even when N keys are validated in
+// parallel against a slow link.
+async function validateApiKey(apiKey, { baseUrl, timeoutMs = 3000 } = {}) {
+  if (!apiKey) return 'invalid';
+  try {
+    await request('GET', '/api/v1/users/privileges/', { apiKey, baseUrl, timeoutMs });
+    return 'valid';
+  } catch (err) {
+    if (err instanceof ApiError && (err.statusCode === 401 || err.statusCode === 403)) {
+      return 'invalid';
+    }
+    return 'unknown';
+  }
+}
+
 module.exports = {
   ApiError,
   get: (path, opts) => request('GET', path, opts),
@@ -148,4 +167,5 @@ module.exports = {
   put: (path, opts) => request('PUT', path, opts),
   del: (path, opts) => request('DELETE', path, opts),
   getRaw,
+  validateApiKey,
 };

package/src/commands/doctor.js

@@ -3,7 +3,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
-const { detectTools } = require('../toolHealth');
+const { detectTools, validateToolKeys, countValidationSkipped } = require('../toolHealth');
 const { hasRootPrivileges } = require('./setup');
 
 // Validate the stored API key against the backend. Returns one of:
@@ -61,12 +61,16 @@ Examples:
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       try {
-        const apiKey = config.getApiKey();
         const gatewayUrl = config.getGatewayUrl();
+        const baseUrl = config.getBaseUrl();
 
         const spin = output.spinner('Running diagnostics...');
         const key = await checkApiKey();
-        const tools = detectTools({ gatewayUrl, apiKey });
+        const tools = detectTools({ gatewayUrl });
+        // WEB-4949: per-tool API keys are validated against the gateway in
+        // parallel (fail-open on network errors).
+        await validateToolKeys(tools, (k) => api.validateApiKey(k, { baseUrl }));
+        const keySkippedCount = countValidationSkipped(tools);
         spin.stop();
 
         const tampered = tools.filter((t) => t.status === 'tampered');
@@ -81,9 +85,13 @@ Examples:
               mode: t.mode,
               status: t.status,
               conflict: !!t.conflict,
-              checks: t.checks.map((c) => ({ name: c.name, ok: c.ok, kind: c.kind, detail: c.detail, warn: !!c.warn })),
+              checks: t.checks.map((c) => ({
+                name: c.name, ok: c.ok, kind: c.kind, detail: c.detail,
+                warn: !!c.warn, validation_skipped: !!c.validationSkipped,
+              })),
             })),
             healthy: !unhealthy,
+            key_validations_skipped: keySkippedCount,
           });
           if (unhealthy) process.exitCode = 1;
           return;
@@ -116,6 +124,11 @@ Examples:
           } else s = C.dim('○ Not set up');
           console.log(`  ${labelOf(t).padEnd(W)}   ${s}`);
         }
+        // WEB-4949: surface fail-open so CI/operators don't read an offline
+        // run as "everything verified". Mirrors the unverified-key-state line.
+        if (keySkippedCount > 0) {
+          console.log(`  ${C.dim(`Note: ${keySkippedCount} per-tool API key validation${keySkippedCount === 1 ? '' : 's'} skipped (gateway unreachable).`)}`);
+        }
         console.log('');
 
         // Fix routing. User-level tools are fixable by anyone (`unbound doctor

package/src/commands/status.js

@@ -2,7 +2,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
-const { detectTools } = require('../toolHealth');
+const { detectTools, validateToolKeys, countValidationSkipped } = require('../toolHealth');
 
 function roleFromPrivileges(p) {
   if (!p) return null;
@@ -76,8 +76,17 @@ Examples:
         pairs.push(['API status', connectivity]);
 
         // Locally detected AI tools wired through Unbound, with their mode.
-        const connected = detectTools({ gatewayUrl: config.getGatewayUrl(), apiKey: config.getApiKey() })
-          .filter((t) => t.status !== 'not-installed');
+        // WEB-4949: per-tool API keys are validated against the gateway in
+        // parallel (fail-open on network errors) — see toolHealth.validateToolKeys.
+        // The spinner is essential — N keys × 3s timeout on a slow link would
+        // otherwise look like the command had frozen.
+        const baseUrl = config.getBaseUrl();
+        const detected = detectTools({ gatewayUrl: config.getGatewayUrl() });
+        const keySpin = output.spinner('Validating tool API keys...');
+        await validateToolKeys(detected, (k) => api.validateApiKey(k, { baseUrl }));
+        keySpin.stop();
+        const connected = detected.filter((t) => t.status !== 'not-installed');
+        const skippedCount = countValidationSkipped(connected);
 
         if (opts.json) {
           const cfg = loggedIn ? config.readConfig() : {};
@@ -92,6 +101,7 @@ Examples:
             gateway_url: config.getGatewayUrl(),
             api_status: connectivity,
             connected_tools: connected.map((t) => ({ tool: t.key, label: t.label, mode: t.mode, status: t.status })),
+            key_validations_skipped: skippedCount,
           });
           return;
         }
@@ -113,6 +123,11 @@ Examples:
             console.log(`  ${mark} ${t.label}${mode}${note}`);
           }
         }
+        // WEB-4949: tell the operator when fail-open masked a real check.
+        // Without this, an offline run looks identical to a fully-validated one.
+        if (skippedCount > 0) {
+          console.log(`  ${C.dim(`Note: ${skippedCount} API key validation${skippedCount === 1 ? '' : 's'} skipped (gateway unreachable).`)}`);
+        }
         console.log('');
       } catch (err) {
         output.error(err.message);

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/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);
+    }
+  );
+});

package/test/tool-health.test.js

@@ -79,15 +79,19 @@ test('detectTools: cursor config + script present but env key blank → tampered
   });
 });
 
-test('detectTools: cursor env key differs from the configured key → tampered, not healthy', () => {
+// WEB-4949: per-tool API keys are no longer equality-checked against the
+// stored config key — different valid keys for the same tenant are legal.
+// detectTools just verifies presence; validateToolKeys (separately tested
+// below) handles tenant-validity.
+test('detectTools: cursor env key differs from the configured key → still healthy (no equality check)', () => {
   withHome((tmp, th) => {
     const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
     writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
     writeFile(script, '# unbound');
-    process.env.UNBOUND_CURSOR_API_KEY = 'stale-key';
+    process.env.UNBOUND_CURSOR_API_KEY = 'different-but-presumed-valid';
     try {
-      const cursor = th.detectTools({ apiKey: 'current-key' }).find((t) => t.key === 'cursor');
-      assert.equal(cursor.status, 'tampered');
+      const cursor = th.detectTools().find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
     } finally {
       delete process.env.UNBOUND_CURSOR_API_KEY;
     }
@@ -302,20 +306,242 @@ test('detectTools: codex binary regression (wrapper at ~/.codex/hooks/unbound.py
   });
 });
 
-test('detectTools: envCheck rc-file fallback (process.env stale, shell rc holds expected value) → healthy', () => {
+// envCheck's rc-file fallback applies to the gateway URL check
+// (ANTHROPIC_BASE_URL is still equality-checked since tenants share one
+// gateway URL). API keys are no longer equality-checked — see WEB-4949 — so
+// this test is repointed at the gateway-URL case to keep the rc-fallback
+// path covered. Stale process.env + fresh rc value → still healthy.
+test('detectTools: envCheck rc-file fallback (gateway URL env stale, rc holds the configured URL) → healthy', () => {
   withHome((tmp, th) => {
+    const settings = { apiKeyHelper: '/Users/whatever/.claude/anthropic_key.sh' };
+    writeFile(path.join(tmp, '.claude', 'settings.json'), JSON.stringify(settings));
+    writeFile(path.join(tmp, '.claude', 'anthropic_key.sh'), '#!/bin/sh\necho $UNBOUND_API_KEY\n');
+    process.env.UNBOUND_API_KEY = 'k';
+    // rcFiles() lists different files per platform; .bashrc is in both.
+    writeFile(path.join(tmp, '.bashrc'),
+      'export ANTHROPIC_BASE_URL="https://gateway.example.com"\n');
+    process.env.ANTHROPIC_BASE_URL = 'https://stale.example.com';
+    try {
+      const t = th.detectTools({ gatewayUrl: 'https://gateway.example.com' })
+        .find((x) => x.family === 'claude-code');
+      assert.equal(t.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_API_KEY;
+      delete process.env.ANTHROPIC_BASE_URL;
+    }
+  });
+});
+
+// WEB-4949: validateToolKeys post-processes detectTools output. Verify the
+// three branches: valid → unchanged healthy; invalid → flips to tampered with
+// a meaningful summary; unknown (network error / 5xx) → fail-open healthy.
+
+test('validateToolKeys: valid verdict leaves the tool healthy', async () => {
+  await withHome(async (tmp, th) => {
     const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
     writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
     writeFile(script, '# unbound');
-    // rcFiles() lists different files per platform (zprofile on darwin,
-    // zshrc/bashrc/profile on linux). Write to .bashrc — both lists include it.
-    writeFile(path.join(tmp, '.bashrc'), 'export UNBOUND_CURSOR_API_KEY="fresh-key"\n');
-    process.env.UNBOUND_CURSOR_API_KEY = 'stale-key';
+    process.env.UNBOUND_CURSOR_API_KEY = 'valid-key';
     try {
-      const t = th.detectTools({ apiKey: 'fresh-key' }).find((x) => x.key === 'cursor');
-      assert.equal(t.status, 'healthy');
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'valid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.ok, true);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: invalid verdict flips the tool to tampered', async () => {
+  await withHome(async (tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'rejected-key';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'invalid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'tampered');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.ok, false);
+      assert.match(keyCheck.summary, /invalid/);
+      assert.match(keyCheck.detail, /not valid for this tenant/);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: unknown verdict fails open — tool stays healthy', async () => {
+  await withHome(async (tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'cant-reach-gateway';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'unknown');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: distinct keys across tools are each validated once', async () => {
+  await withHome(async (tmp, th) => {
+    // Two tools with two distinct env-var values + one shared value.
+    const cursorScript = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: cursorScript }] } }));
+    writeFile(cursorScript, '# unbound');
+    const copilotCfg = path.join(tmp, '.copilot', 'hooks', 'unbound.json');
+    const copilotScript = path.join(tmp, '.copilot', 'hooks', 'unbound.py');
+    writeFile(copilotCfg, JSON.stringify({ hooks: { PreToolUse: [{ command: copilotScript }] } }));
+    writeFile(copilotScript, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'key-A';
+    process.env.UNBOUND_COPILOT_API_KEY = 'key-B';
+    try {
+      const tools = th.detectTools();
+      const seen = [];
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return 'valid'; });
+      // Each unique key is validated exactly once, regardless of how many
+      // tools reference it. Order isn't asserted.
+      assert.deepEqual(new Set(seen), new Set(['key-A', 'key-B']));
+      assert.equal(seen.length, 2);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+// Real-world common case: one tool's key was rotated and the env wasn't
+// updated. The valid tool stays healthy; the invalid one flips. They share
+// the same fan-out, so a partial verdict must round-trip correctly.
+test('validateToolKeys: mixed verdicts — invalid tool flips, valid tool unchanged', async () => {
+  await withHome(async (tmp, th) => {
+    const cursorScript = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: cursorScript }] } }));
+    writeFile(cursorScript, '# unbound');
+    const copilotCfg = path.join(tmp, '.copilot', 'hooks', 'unbound.json');
+    const copilotScript = path.join(tmp, '.copilot', 'hooks', 'unbound.py');
+    writeFile(copilotCfg, JSON.stringify({ hooks: { PreToolUse: [{ command: copilotScript }] } }));
+    writeFile(copilotScript, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'good';
+    process.env.UNBOUND_COPILOT_API_KEY = 'bad';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => k === 'good' ? 'valid' : 'invalid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      const copilot = tools.find((t) => t.key === 'copilot');
+      assert.equal(cursor.status, 'healthy');
+      assert.equal(copilot.status, 'tampered');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+// Defensive: a validator that throws (a future api.validateApiKey bug, a
+// transport regression) must NOT take down `unbound status`/`doctor`. Each
+// thrown key is coerced to 'unknown' so the tool stays healthy and the skip
+// counter surfaces the issue to the operator.
+test('validateToolKeys: throwing validator coerces to unknown (does not propagate)', async () => {
+  await withHome(async (tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'k';
+    try {
+      const tools = th.detectTools();
+      await assert.doesNotReject(
+        th.validateToolKeys(tools, async () => { throw new Error('boom'); })
+      );
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.validationSkipped, true);
+      assert.equal(th.countValidationSkipped(tools), 1);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+// Tag for offline surfacing — without this the operator can't distinguish a
+// fully-validated run from one that silently failed open.
+test('validateToolKeys: unknown verdict tags the check with validationSkipped + countValidationSkipped reports it', async () => {
+  await withHome(async (tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'k';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'unknown');
+      assert.equal(th.countValidationSkipped(tools), 1);
+      const cursor = tools.find((t) => t.key === 'cursor');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.validationSkipped, true);
+      assert.equal(keyCheck.ok, true); // fail-open: still healthy
     } finally {
       delete process.env.UNBOUND_CURSOR_API_KEY;
     }
   });
 });
+
+// Bot regression (Bugbot Medium / Greptile P1): validateToolKeys was
+// unconditionally re-running statusOf, which overwrites `managed-by-mdm`
+// (since `statusOf` doesn't know about that sentinel) back to `healthy`,
+// erasing the MDM badge from both human + JSON output. The fix is to only
+// re-derive status when a check's `ok` actually flipped.
+test('validateToolKeys: managed-by-mdm status survives validation when nothing flips', async () => {
+  await withHome(async (tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    writeFile(path.join(mdmDir, 'managed-settings.json'),
+      JSON.stringify({ hooks: { PreToolUse: [{ command: path.join(mdmDir, 'hooks', 'unbound.py') }] } }));
+    writeFile(path.join(mdmDir, 'hooks', 'unbound.py'), '#');
+    const tools = th.detectTools({ _mdmDirs: { 'claude-code': mdmDir } });
+    const claude = tools.find((t) => t.family === 'claude-code');
+    assert.equal(claude.status, 'managed-by-mdm', 'pre-validation sanity');
+    // No keyCheck entries on the MDM variant, so the validator is never
+    // consulted. Status must NOT collapse to plain 'healthy'.
+    let called = false;
+    await th.validateToolKeys(tools, async () => { called = true; return 'valid'; });
+    assert.equal(claude.status, 'managed-by-mdm', 'MDM badge was overwritten');
+    assert.equal(claude.scope, 'mdm');
+    assert.equal(called, false);
+  });
+});
+
+// W2 defensive guards.
+test('validateToolKeys: null/empty tools — no throw, no validator calls', async () => {
+  const th = require('../src/toolHealth');
+  let called = false;
+  await th.validateToolKeys(null, async () => { called = true; });
+  await th.validateToolKeys(undefined, async () => { called = true; });
+  await th.validateToolKeys([], async () => { called = true; });
+  assert.equal(called, false);
+});
+
+test('validateToolKeys: missing key (no env var) → tampered without consulting the validator', async () => {
+  await withHome(async (tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    delete process.env.UNBOUND_CURSOR_API_KEY;
+    let called = false;
+    const tools = th.detectTools();
+    await th.validateToolKeys(tools, async () => { called = true; return 'valid'; });
+    const cursor = tools.find((t) => t.key === 'cursor');
+    assert.equal(cursor.status, 'tampered');
+    // The validator is never called for missing keys — there's no value to check.
+    assert.equal(called, false);
+  });
+});