unbound-cli 1.6.4 → 1.7.0

package/README.md

@@ -299,3 +299,28 @@ All list/get commands support `--json` for machine-readable JSON output.
 unbound policy list --json
 unbound users list --json | jq '.members[].email'
 ```
+
+## Onboarding failure reporting & telemetry
+
+So onboarding steps never fail silently, the CLI:
+
+- **Fails loud.** A failed setup or discovery step exits non-zero (no fake
+  successes). A broken script download (GitHub down/404/empty body) is detected
+  before the script runs, so it can no longer "succeed" with an empty script.
+- **Reports failures to the backend.** When a setup step fails, the CLI makes a
+  best-effort `POST /api/v1/setup/failed/` with the failing step name and exit
+  code so the failure is visible server-side. The device is identified by
+  `os.hostname()` (used only as an org-scoped key, not a true hardware serial).
+  This report is best-effort: if it can't be sent (offline / rate-limited), the
+  CLI still shows the real error and keeps its non-zero exit code.
+
+### Error reporting (Sentry) — opt-out
+
+Crash/error reporting is **off by default** and only activates when a DSN is
+configured. Secrets (API/discovery keys), home-directory paths, and your OS
+username are scrubbed before any event is sent.
+
+| Env var | Effect |
+|---------|--------|
+| `UNBOUND_CLI_SENTRY_DSN` | Set to enable error reporting. **Unset = fully disabled** (nothing initializes, no network). |
+| `UNBOUND_TELEMETRY` | Set to `0`, `false`, or `no` to disable error reporting even if a DSN is configured. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {
@@ -21,6 +21,7 @@
   "private": false,
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "@sentry/node": "^10.59.0",
     "commander": "^12.1.0",
     "open": "^10.1.0"
   },

package/src/api.js

@@ -29,7 +29,9 @@ class ApiError extends Error {
   }
 }
 
-function request(method, path, { body, query, apiKey, baseUrl } = {}) {
+const DEFAULT_TIMEOUT_MS = 30000;
+
+function request(method, path, { body, query, apiKey, baseUrl, timeoutMs } = {}) {
   // Explicit baseUrl wins over env-var-aware getBaseUrl(). Used by login /
   // setup / onboard so a user's just-passed --backend-url isn't shadowed by a
   // stale UNBOUND_API_URL env var from a prior shell session.
@@ -83,9 +85,13 @@ function request(method, path, { body, query, apiKey, baseUrl } = {}) {
       });
     });
 
-    req.setTimeout(30000, () => {
+    // Callers may bound a request more tightly than the default (e.g. the
+    // best-effort failure ledger uses 3s so a hung backend can't delay surfacing
+    // the user's real error).
+    const effectiveTimeout = Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    req.setTimeout(effectiveTimeout, () => {
       req.destroy();
-      reject(new Error(`Request to ${url.host} timed out after 30s. Please try again.`));
+      reject(new Error(`Request to ${url.host} timed out after ${Math.round(effectiveTimeout / 1000)}s. Please try again.`));
     });
 
     req.on('error', (err) => {
@@ -135,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),
@@ -142,4 +167,5 @@ module.exports = {
   put: (path, opts) => request('PUT', path, opts),
   del: (path, opts) => request('DELETE', path, opts),
   getRaw,
+  validateApiKey,
 };

package/src/auth.js

@@ -17,7 +17,7 @@ const { getDeviceSerial } = require('./device-serial');
  * @param {string} frontendUrl - The frontend URL to open
  * @returns {Promise<{email: string, orgName: string}>}
  */
-async function loginWithBrowser(frontendUrl) {
+async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   const server = http.createServer();
   let callbackResolve;
   let callbackReject;
@@ -27,11 +27,31 @@ async function loginWithBrowser(frontendUrl) {
     callbackReject = reject;
   });
 
+  // server.close() only stops accepting NEW connections; it does NOT destroy a
+  // socket the browser is holding open via HTTP/1.1 keep-alive. That socket stays
+  // ref'd and keeps the event loop (the whole CLI) alive ~60s until the browser
+  // drops it. Responses set `Connection: close` so the answered socket closes
+  // gracefully once its body flushes; this also force-drops any idle / pre-connected
+  // / timed-out socket so the process exits immediately. closeAllConnections is
+  // Node >=18.2 — guard for the package's >=18 engine floor.
+  //
+  // Calling this synchronously right after res.end() is safe ONLY because the
+  // callback responses are a few hundred bytes of static HTML — they fit in the
+  // socket send buffer, so the body reaches the kernel before closeAllConnections
+  // destroys the socket. If these pages ever grow to multi-KB (inline assets,
+  // styling), defer teardown to res.on('finish') to avoid truncating the response.
+  function shutdownServer() {
+    server.close();
+    if (typeof server.closeAllConnections === 'function') {
+      server.closeAllConnections();
+    }
+  }
+
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
 
     if (url.pathname !== '/callback') {
-      res.writeHead(404);
+      res.writeHead(404, { 'Connection': 'close' });
       res.end('Not found');
       return;
     }
@@ -41,10 +61,10 @@ async function loginWithBrowser(frontendUrl) {
     const orgName = url.searchParams.get('org');
 
     if (!apiKey) {
-      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.writeHead(400, { 'Content-Type': 'text/html', 'Connection': 'close' });
       res.end('<html><body><h2>Authentication failed</h2><p>No API key received. Please try again.</p></body></html>');
       callbackReject(new Error('No API key received in callback'));
-      server.close();
+      shutdownServer();
       return;
     }
 
@@ -54,11 +74,11 @@ async function loginWithBrowser(frontendUrl) {
     if (orgName) cfg.org_name = orgName;
     config.writeConfig(cfg);
 
-    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.writeHead(200, { 'Content-Type': 'text/html', 'Connection': 'close' });
     res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
 
     callbackResolve({ email, orgName });
-    server.close();
+    shutdownServer();
   });
 
   await new Promise((resolve, reject) => {
@@ -70,7 +90,7 @@ async function loginWithBrowser(frontendUrl) {
   const callbackUrl = `http://localhost:${port}/callback`;
   const authUrl = `${frontendUrl}/automations/api-key-callback?callback_url=${encodeURIComponent(callbackUrl)}&app_type=cli`;
 
-  const open = (await import('open')).default;
+  const open = openFn || (await import('open')).default;
 
   output.info('Opening browser for authentication...');
   output.info(`If the browser does not open, visit:\n${authUrl}`);
@@ -84,7 +104,7 @@ async function loginWithBrowser(frontendUrl) {
 
   const timeout = setTimeout(() => {
     callbackReject(new Error('Authentication timed out after 120 seconds'));
-    server.close();
+    shutdownServer();
   }, 120_000);
 
   const reminder = setInterval(() => {

package/src/commands/discover.js

@@ -4,7 +4,8 @@ const path = require('path');
 const os = require('os');
 const config = require('../config');
 const output = require('../output');
-const { shellEscape, downloadToFile, DISCOVER_BASE_URL } = require('../utils');
+const telemetry = require('../telemetry');
+const { shellEscape, downloadToFile, withSecureTempFile, DISCOVER_BASE_URL } = require('../utils');
 const LAUNCH_AGENT_LABEL = 'ai.getunbound.discovery';
 
 // install.sh exits with this code when the OS isn't supported for discovery
@@ -46,29 +47,46 @@ function isRoot() {
  * install.ps1 automatically; any other bash-only script (e.g.
  * setup-scheduled-scan.sh) remains unsupported on native Windows.
  */
-function runDiscoveryScript(scriptName, args) {
+async function runDiscoveryScript(scriptName, args) {
   if (isWindowsNative()) {
     return runDiscoveryScriptWindows(scriptName, args);
   }
-  return new Promise((resolve, reject) => {
-    const url = `${DISCOVER_BASE_URL}/${scriptName}`;
-    const cmd = `curl -fsSL "${url}" | bash -s -- ${args}`;
-
-    const child = spawn(cmd, { shell: true, stdio: 'inherit' });
-
-    child.on('close', (code) => {
-      const result = classifyDiscoveryExit(code);
-      if (result === 'failure') {
-        reject(new Error(`Discovery script failed with exit code ${code}`));
-        return;
-      }
-      if (result === 'unsupported') {
-        output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
-      }
-      resolve();
+  // Download-then-run instead of `curl -fsSL ... | bash -s --`. The pipe's exit
+  // code was bash's, not curl's, and /bin/sh=dash has no pipefail — so a failed
+  // download (GitHub down/404/partial) silently ran an empty/partial script and
+  // exited 0 = fake success. downloadToFile rejects on non-200/empty body BEFORE
+  // bash runs, closing that hole. Mirrors runDiscoveryScriptWindows.
+  const url = `${DISCOVER_BASE_URL}/${scriptName}`;
+  // The downloaded script is executed (as root under `sudo unbound …`), so it
+  // must live in a per-run PRIVATE temp dir an attacker can't pre-create or
+  // symlink. withSecureTempFile creates it (mode 0700) and cleans it up after.
+  return withSecureTempFile('.sh', async (tmp) => {
+    try {
+      await downloadToFile(url, tmp);
+    } catch (err) {
+      err.downloadFailed = true;
+      throw err;
+    }
+    return await new Promise((resolve, reject) => {
+      const child = spawn('bash', [tmp, ...parsePosixArgs(args)], {
+        stdio: 'inherit',
+        shell: false,
+      });
+      child.on('close', (code) => {
+        const result = classifyDiscoveryExit(code);
+        if (result === 'failure') {
+          const e = new Error(`Discovery script failed with exit code ${code}`);
+          e.exitCode = code;
+          reject(e);
+          return;
+        }
+        if (result === 'unsupported') {
+          output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
+        }
+        resolve();
+      });
+      child.on('error', reject);
     });
-
-    child.on('error', reject);
   });
 }
 
@@ -101,17 +119,18 @@ async function runDiscoveryScriptWindows(scriptName, args) {
   }
   const winScript = 'install.ps1';
   const url = `${DISCOVER_BASE_URL}/${winScript}`;
-  const tmp = path.join(os.tmpdir(), `unbound-discover-${Date.now()}-${Math.random().toString(36).slice(2)}.ps1`);
-  try {
-    await downloadToFile(url, tmp);
-  } catch (err) {
-    throw new Error(
-      `${err.message}. Native Windows support requires ${winScript} in the coding-discovery-tool repo.`
-    );
-  }
-  // Map posix flags to PowerShell-style parameter names (install.ps1's convention).
-  const argv = parsePosixArgs(args).map((a) => a === '--api-key' ? '-ApiKey' : a === '--domain' ? '-Domain' : a);
-  try {
+  // Same hardening as the bash path: download into a per-run private temp dir
+  // and run from there, then clean up.
+  return withSecureTempFile('.ps1', async (tmp) => {
+    try {
+      await downloadToFile(url, tmp);
+    } catch (err) {
+      throw new Error(
+        `${err.message}. Native Windows support requires ${winScript} in the coding-discovery-tool repo.`
+      );
+    }
+    // Map posix flags to PowerShell-style parameter names (install.ps1's convention).
+    const argv = parsePosixArgs(args).map((a) => a === '--api-key' ? '-ApiKey' : a === '--domain' ? '-Domain' : a);
     await new Promise((resolve, reject) => {
       const child = spawn(
         'powershell',
@@ -131,9 +150,7 @@ async function runDiscoveryScriptWindows(scriptName, args) {
       });
       child.on('error', reject);
     });
-  } finally {
-    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
-  }
+  });
 }
 
 /**
@@ -197,8 +214,10 @@ Examples:
   $ unbound discover --api-key KEY                   Scan current user only
   $ sudo unbound discover --api-key KEY --domain https://custom.backend.com
 `)
-    .action(async (opts) => {
+    .action(telemetry.wrapAction('discover', async (opts) => {
       let scanSucceeded = false;
+      // Register the discovery key so beforeSend redacts it from any event.
+      telemetry.rememberSecret(opts.apiKey);
       try {
         if (!opts.apiKey) {
           output.error('--api-key is required.');
@@ -224,6 +243,7 @@ Examples:
         console.log('');
         output.success('Discovery complete');
       } catch (err) {
+        telemetry.captureError(err, { tags: { flow: 'discover' } });
         output.error(err.message);
         // Hint only when the scan completed and the user actually asked for
         // cron setup — guards against a future code path between scanSucceeded
@@ -236,7 +256,7 @@ Examples:
         }
         process.exitCode = 1;
       }
-    });
+    }));
 
   // --- Schedule / Unschedule / Status ---
 

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

@@ -1,6 +1,7 @@
 const { Option } = require('commander');
 const config = require('../config');
 const output = require('../output');
+const telemetry = require('../telemetry');
 const { ensureLoggedIn } = require('../auth');
 const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
@@ -55,9 +56,13 @@ Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron
 `)
-    .action(async (opts) => {
+    .action(telemetry.wrapAction('onboard', async (opts) => {
       const apiKeyOpt = opts.apiKey || opts.adminApiKey || process.env.UNBOUND_API_KEY;
       const discoveryKeyOpt = opts.discoveryKey || process.env.UNBOUND_DISCOVERY_KEY;
+      // Register the concrete secret values so beforeSend redacts the exact
+      // strings (not just key-shaped guesses) from any captured event.
+      telemetry.rememberSecret(apiKeyOpt);
+      telemetry.rememberSecret(discoveryKeyOpt);
       const isMdm = hasRootPrivileges();
 
       if (!discoveryKeyOpt) {
@@ -109,7 +114,10 @@ Examples:
           const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
-          if (!ok) return;
+          // A failed setup must NOT report onboarding success. runBatch already
+          // reported the failure to the ledger and set exitCode; make the
+          // non-zero exit explicit here so onboard never returns 0 on failure.
+          if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
 
           console.log('');
@@ -131,7 +139,10 @@ Examples:
           const { ok, skipped } = await runSetupAllBundle(apiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
-          if (!ok) return;
+          // A failed setup must NOT report onboarding success. runBatch already
+          // reported the failure to the ledger and set exitCode; make the
+          // non-zero exit explicit here so onboard never returns 0 on failure.
+          if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
 
           console.log('');
@@ -173,6 +184,9 @@ Examples:
           ? 'Onboarding complete — tools managed by MDM were skipped (see above)'
           : 'Onboarding complete');
       } catch (err) {
+        // Capture the real onboarding error to Sentry (no-op unless enabled).
+        // The action catches its own errors, so capture here before we swallow.
+        telemetry.captureError(err, { tags: { flow: 'onboard' } });
         if (!err.displayed) output.error(err.message);
         const suffix = domainHintSuffix(discoveryDomain);
         const sudo = isMdm ? 'sudo ' : '';
@@ -193,7 +207,7 @@ Examples:
         }
         process.exitCode = 1;
       }
-    });
+    }));
 
   // --- onboard unschedule ---