unbound-cli 1.15.1 → 1.16.7

package/src/toolHealth.js

@@ -17,6 +17,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const claudePaths = require('./claudePaths');
 
 const HOME = os.homedir();
 const GATEWAY_DEFAULT = 'https://api.getunbound.ai';
@@ -30,6 +31,13 @@ function expand(p) {
   return p.startsWith('~') ? path.join(HOME, p.slice(1)) : p;
 }
 
+function claudePath(...parts) {
+  // The default dir is rendered as a literal ~ so the check labels doctor prints
+  // stay stable; expand() turns it back into a real path on read.
+  if (!claudePaths.isNonDefaultConfigDir()) return ['~/.claude', ...parts].join('/');
+  return path.join(claudePaths.resolveClaudeConfigDir(), ...parts);
+}
+
 function fileExists(p) {
   try {
     return fs.statSync(expand(p)).isFile();
@@ -84,17 +92,25 @@ function readEnvVar(name) {
     return { found: false };
   }
 
-  const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'm');
+  const persisted = rcEnvValues(name);
+  return persisted.length ? { found: true, ...persisted[0] } : { found: false };
+}
+
+// Every `export NAME=...` the rc files hold, in file order. Setup removes only the
+// exports it wrote, so a customer's own endpoint can sit alongside ours in another file
+// or another line -- one value is not enough to tell whether our wiring is intact.
+function rcEnvValues(name) {
+  if (process.platform === 'win32') return [];
+  const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'gm');
+  const values = [];
   for (const rc of rcFiles()) {
     const text = readText(rc);
     if (!text) continue;
-    const m = text.match(re);
-    if (m) {
-      const val = m[1].trim().replace(/^["']|["']$/g, '');
-      return { found: true, value: val, source: path.basename(expand(rc)) };
+    for (const m of text.matchAll(re)) {
+      values.push({ value: m[1].trim().replace(/^["']|["']$/g, ''), source: path.basename(expand(rc)) });
     }
   }
-  return { found: false };
+  return values;
 }
 
 // --- check builders. Each returns { name, ok, kind, detail, summary, warn? }. ---
@@ -121,6 +137,43 @@ function configCheck(label, file, marker, opts = {}) {
   return { name: label, ok, kind, detail, summary };
 }
 
+// The gateway setup writes exactly this helper, and points apiKeyHelper at exactly this
+// path. Matching on those rather than on the filename keeps someone's own key helper --
+// which the setup no longer removes -- from reading as a gateway install.
+const UNBOUND_KEY_HELPER = '~/.claude/anthropic_key.sh';
+// The helper reads UNBOUND_API_KEY; that reference is what makes it ours. Matched on the
+// token rather than the whole body so a shebang or trailing newline doesn't disown a real
+// install, and matched on the path's tail so an MDM install under another home still counts.
+const UNBOUND_KEY_HELPER_TOKEN = 'UNBOUND_API_KEY';
+
+const DEFAULT_KEY_HELPER_TAIL = '/.claude/anthropic_key.sh';
+
+function isUnboundKeyHelper(value) {
+  if (typeof value !== 'string') return false;
+  const v = value.trim();
+  if (v === UNBOUND_KEY_HELPER) return true;
+  // settings.json spells a Windows path with backslashes, so compare on forward
+  // slashes — and through samePath, since Windows ignores case.
+  const slashed = v.replace(/\\/g, '/');
+  if (claudePaths.samePath(slashed.slice(-DEFAULT_KEY_HELPER_TAIL.length), DEFAULT_KEY_HELPER_TAIL)) return true;
+  // A relocated CLAUDE_CONFIG_DIR is not named .claude, so the helper the gateway
+  // wrote there matches neither form above — check the active dir explicitly.
+  return claudePaths.samePath(path.resolve(v), path.join(claudePaths.resolveClaudeConfigDir(), 'anthropic_key.sh'));
+}
+
+function keyHelperCheck(label, file, kind = 'structural') {
+  const body = readText(file);
+  if (body == null) {
+    return { name: label, ok: false, kind, detail: `not found (${file})`, summary: `${label.toLowerCase()} missing` };
+  }
+  const ok = body.includes(UNBOUND_KEY_HELPER_TOKEN);
+  return {
+    name: label, ok, kind,
+    detail: ok ? file : `present but not written by Unbound (${file})`,
+    summary: ok ? `${label.toLowerCase()} missing` : `${label.toLowerCase()} not ours`,
+  };
+}
+
 function scriptCheck(label, file, kind = 'structural') {
   const ok = fileExists(file);
   return { name: label, ok, kind, detail: ok ? file : `not found (${file})`, summary: `${label.toLowerCase()} missing` };
@@ -154,27 +207,37 @@ function envCheck(label, name, expected, kind = 'aux') {
   // A value that doesn't match what setup wrote (stale key, wrong gateway URL) is a
   // real misconfiguration: mark it not-ok so the tool reports tampered, not healthy.
   if (expected && r.value !== expected) {
-    // process.env can be a stale snapshot from a shell loaded before setup re-wrote
-    // the rc, so consult the rc files as a fallback before declaring a mismatch.
-    if (r.source === 'process env' && process.platform !== 'win32') {
-      const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'm');
-      for (const rc of rcFiles()) {
-        const text = readText(rc);
-        if (!text) continue;
-        const m = text.match(re);
-        if (!m) continue;
-        const rcVal = m[1].trim().replace(/^["']|["']$/g, '');
-        if (rcVal === expected) {
-          const rcSource = path.basename(expand(rc));
-          return { name: label, ok: true, kind, detail: `${name} set (${rcSource})`, summary: `${base} set` };
-        }
-      }
+    // Any persisted export matching what setup wrote means the wiring is intact. The live
+    // process.env can be a stale snapshot from a shell loaded before setup rewrote the rc,
+    // and setup leaves a customer's own export in place beside ours, so the first value
+    // read is not the one to judge on.
+    const match = rcEnvValues(name).find((v) => v.value === expected);
+    if (match) {
+      return { name: label, ok: true, kind, detail: `${name} set (${match.source})`, summary: `${base} set` };
     }
     return { name: label, ok: false, kind, warn: true, summary: `${base} differs from setup`, detail: `${name} set (${r.source}) but differs from what setup configured` };
   }
   return { name: label, ok: true, kind, detail: `${name} set (${r.source})`, summary: `${base} set` };
 }
 
+// Machine-wide managed (MDM) directory per tool, mirroring each tool's
+// get_managed_settings_dir in the setup repo. On Windows the root is NOT uniform:
+// Claude Code and Codex install under Program Files, Cursor and Augment under
+// ProgramData. Augment uses /etc/augment on macOS as well as Linux.
+function managedDir(family, platform = process.platform, env = process.env) {
+  const mac = '/Library/Application Support';
+  const pd = env.ProgramData || 'C:\\ProgramData';
+  const pf = env.ProgramFiles || 'C:\\Program Files';
+  const dirs = {
+    cursor: { darwin: `${mac}/Cursor`, linux: '/etc/cursor', win32: path.join(pd, 'Cursor') },
+    'claude-code': { darwin: `${mac}/ClaudeCode`, linux: '/etc/claude-code', win32: path.join(pf, 'ClaudeCode') },
+    codex: { darwin: `${mac}/Codex`, linux: '/etc/codex', win32: path.join(pf, 'Codex') },
+    augment: { darwin: '/etc/augment', linux: '/etc/augment', win32: path.join(pd, 'Augment') },
+  };
+  if (!dirs[family]) return null;
+  return dirs[family][platform] || dirs[family].linux;
+}
+
 // MDM (org-wide) install detection. An Unbound MDM install is only real when the
 // system managed config REFERENCES the Unbound hook AND the hook script exists.
 // A plain managed-settings.json (Claude Enterprise / generic MDM) does NOT count,
@@ -184,24 +247,36 @@ function mdmDetect(family, dirOverride, binaryPath) {
   // Only Cursor / Claude Code / Codex / Augment have a managed (MDM) directory.
   // Copilot and Gemini have none — their org install writes the same per-user
   // config into every profile, so they're checked exactly like a user-level tool.
-  const configName = { cursor: 'hooks.json', 'claude-code': 'managed-settings.json', codex: 'managed-settings.json', augment: 'settings.json' };
+  const configName = { cursor: 'hooks.json', 'claude-code': 'managed-settings.json', codex: 'hooks.json', augment: 'settings.json' };
   if (!configName[family]) return { status: null, checks: [] };
 
-  const mac = '/Library/Application Support';
-  const win = process.env.ProgramData || 'C:\\ProgramData';
-  const dirs = {
-    cursor: { darwin: `${mac}/Cursor`, linux: '/etc/cursor', win32: path.join(win, 'Cursor') },
-    'claude-code': { darwin: `${mac}/ClaudeCode`, linux: '/etc/claude-code', win32: path.join(win, 'ClaudeCode') },
-    codex: { darwin: `${mac}/Codex`, linux: '/etc/codex', win32: path.join(win, 'Codex') },
-    // Augment's managed dir is /etc/augment on BOTH macOS and Linux (mirrors the
-    // setup repo's get_managed_settings_dir), not Library/Application Support.
-    augment: { darwin: '/etc/augment', linux: '/etc/augment', win32: path.join(win, 'Augment') },
-  };
-  const dir = dirOverride || dirs[family][process.platform] || dirs[family].linux;
-  const configPath = path.join(dir, configName[family]);
+  const dir = dirOverride || managedDir(family);
+  // Claude Code's MDM install prefers the managed-settings.d drop-in and only writes the
+  // flat file as a fallback, so a drop-in-only device must still register as managed.
+  const candidates = family === 'claude-code'
+    ? [path.join(dir, 'managed-settings.d', 'unbound.json'), path.join(dir, configName[family])]
+    : [path.join(dir, configName[family])];
   const scriptPath = path.join(dir, 'hooks', 'unbound.py');
 
-  const cfgText = readText(configPath);
+  // Candidates can disagree: a drop-in left by an earlier install may still name a hook
+  // that is gone while the flat file beside it names a working one. Rank by how complete
+  // each install looks so the healthiest candidate decides the verdict, rather than
+  // whichever happens to be read first.
+  const completeness = (text) => {
+    const binary = text.includes(BINARY_MARKER);
+    if (!binary && !text.includes('unbound.py')) return 0;
+    return fileExists(binary ? (binaryPath || BINARY_PATH) : scriptPath) ? 2 : 1;
+  };
+  let configPath = null;
+  let cfgText = null;
+  let best = -1;
+  for (const candidate of candidates) {
+    const text = readText(candidate);
+    if (text == null) continue;
+    const score = completeness(text);
+    if (score > best) { best = score; configPath = candidate; cfgText = text; }
+    if (best === 2) break;
+  }
   if (cfgText == null) return { status: null, checks: [] };
   const hasBinary = cfgText.includes(BINARY_MARKER);
   const hasPython = cfgText.includes('unbound.py');
@@ -258,16 +333,16 @@ function buildVariants(gatewayUrl, binaryPath) {
     {
       key: 'claude-code-subscription', label: 'Claude Code (subscription)', family: 'claude-code', mode: 'subscription',
       checks: () => [
-        configCheck('Config', '~/.claude/settings.json', { json: true, test: refsUnbound }),
-        scriptCheck('Hook script', '~/.claude/hooks/unbound.py'),
+        configCheck('Config', claudePath('settings.json'), { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', claudePath('hooks', 'unbound.py')),
         envKeyCheck('API key env', 'UNBOUND_CLAUDE_API_KEY'),
       ],
     },
     {
       key: 'claude-code-gateway', label: 'Claude Code (gateway)', family: 'claude-code', mode: 'gateway',
       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'),
+        configCheck('Config', claudePath('settings.json'), { json: true, test: (j) => isUnboundKeyHelper(j.apiKeyHelper) }),
+        keyHelperCheck('Key helper', claudePath('anthropic_key.sh')),
         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.
@@ -458,4 +533,4 @@ function countValidationSkipped(tools) {
   return n;
 }
 
-module.exports = { detectTools, statusOf, readEnvVar, validateToolKeys, countValidationSkipped, GATEWAY_DEFAULT };
+module.exports = { detectTools, managedDir, statusOf, readEnvVar, rcEnvValues, validateToolKeys, countValidationSkipped, GATEWAY_DEFAULT, isUnboundKeyHelper, keyHelperCheck };

package/test/analytics-export-job.test.js

@@ -126,7 +126,7 @@ test('a backend still on the streaming export (405) says so instead of "not foun
 
 test('describeError works with no dataset, for `download get`', () => {
   const message = describeError(new api.ApiError(403, {}));
-  assert.match(message, /Admin role required/);
+  assert.match(message, /not available to your role/);
 });
 
 // A 404 means different things on the two paths, and saying the wrong one sends

package/test/chat-internals.test.js

@@ -131,7 +131,7 @@ test('normalizeAssistantTurn: caps content length', () => {
 });
 
 test('friendlyChatError: maps status codes to role-specific guidance', () => {
-  assert.match(friendlyChatError({ statusCode: 403 }), /Admin or Manager/);
+  assert.match(friendlyChatError({ statusCode: 403 }), /Admin, Analytics Viewer or Manager/);
   assert.match(friendlyChatError({ statusCode: 401 }), /login/);
   assert.match(friendlyChatError({ statusCode: 429 }), /Rate limited/);
   assert.equal(friendlyChatError({ statusCode: 500, message: 'boom' }), 'boom');

package/test/claude-paths.test.js

@@ -0,0 +1,182 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('os');
+const path = require('path');
+
+function freshModule() {
+  delete require.cache[require.resolve('../src/claudePaths')];
+  return require('../src/claudePaths');
+}
+
+function withEnv(value, fn) {
+  const prev = process.env.CLAUDE_CONFIG_DIR;
+  if (value === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+  else process.env.CLAUDE_CONFIG_DIR = value;
+  try { fn(freshModule()); }
+  finally {
+    if (prev === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+    else process.env.CLAUDE_CONFIG_DIR = prev;
+  }
+}
+
+const DEFAULT_DIR = path.join(os.homedir(), '.claude');
+
+test('resolveClaudeConfigDir: env set absolute is returned absolutized', () => {
+  withEnv('/opt/cc', (cp) => assert.equal(cp.resolveClaudeConfigDir(), path.resolve('/opt/cc')));
+});
+
+test('resolveClaudeConfigDir: env relative is absolutized', () => {
+  withEnv('rel/cc', (cp) => assert.equal(cp.resolveClaudeConfigDir(), path.resolve('rel/cc')));
+});
+
+test('resolveClaudeConfigDir: env unset falls back to ~/.claude', () => {
+  withEnv(undefined, (cp) => assert.equal(cp.resolveClaudeConfigDir(), DEFAULT_DIR));
+});
+
+test('resolveClaudeConfigDir: empty/whitespace env falls back to ~/.claude', () => {
+  withEnv('   ', (cp) => assert.equal(cp.resolveClaudeConfigDir(), DEFAULT_DIR));
+});
+
+// Claude Code creates a literal "~" directory rather than expanding it, so the
+// tilde must stay literal here too or the hooks land where Claude never looks.
+test('resolveClaudeConfigDir: a leading ~ stays literal, as Claude Code treats it', () => {
+  withEnv('~/cc', (cp) => assert.equal(cp.resolveClaudeConfigDir(), path.resolve('~/cc')));
+  withEnv('~/cc', (cp) => assert.notEqual(cp.resolveClaudeConfigDir(), path.join(os.homedir(), 'cc')));
+});
+
+test('isNonDefaultConfigDir: true when env points elsewhere, false otherwise', () => {
+  withEnv('/opt/cc', (cp) => assert.equal(cp.isNonDefaultConfigDir(), true));
+  withEnv(undefined, (cp) => assert.equal(cp.isNonDefaultConfigDir(), false));
+});
+
+test('claudeHooksDir / claudeSettingsPath derive from the resolved dir', () => {
+  withEnv('/opt/cc', (cp) => {
+    assert.equal(cp.claudeHooksDir(), path.join('/opt/cc', 'hooks'));
+    assert.equal(cp.claudeSettingsPath(), path.join('/opt/cc', 'settings.json'));
+  });
+});
+
+test('detectConfigDirMismatch: null when default config dir', () => {
+  withEnv(undefined, (cp) => {
+    const fs = { existsSync: () => true };
+    assert.equal(cp.detectConfigDirMismatch([path.join('hooks', 'unbound.py')], { fs }), null);
+  });
+});
+
+test('detectConfigDirMismatch: object when required hook only in ~/.claude and env set', () => {
+  withEnv('/opt/cc', (cp) => {
+    const staleHook = path.join(DEFAULT_DIR, 'hooks', 'unbound.py');
+    const fs = { existsSync: (p) => p === staleHook };
+    assert.deepEqual(
+      cp.detectConfigDirMismatch([path.join('hooks', 'unbound.py')], { fs }),
+      { activeDir: path.resolve('/opt/cc'), staleDir: DEFAULT_DIR }
+    );
+  });
+});
+
+test('detectConfigDirMismatch: keys on the required hook, ignoring strays in active dir', () => {
+  withEnv('/opt/cc', (cp) => {
+    const activeStray = path.join('/opt/cc', 'hooks', 'oacb-enforce.sh');
+    const staleHook = path.join(DEFAULT_DIR, 'hooks', 'unbound.py');
+    const fs = { existsSync: (p) => p === activeStray || p === staleHook };
+    assert.deepEqual(
+      cp.detectConfigDirMismatch([path.join('hooks', 'unbound.py')], { fs }),
+      { activeDir: path.resolve('/opt/cc'), staleDir: DEFAULT_DIR }
+    );
+  });
+});
+
+test('detectConfigDirMismatch: default markers cover the hooks install', () => {
+  withEnv('/opt/cc', (cp) => {
+    const staleHook = path.join(DEFAULT_DIR, 'hooks', 'unbound.py');
+    const fs = { existsSync: (p) => p === staleHook };
+    assert.deepEqual(
+      cp.detectConfigDirMismatch(undefined, { fs }),
+      { activeDir: path.resolve('/opt/cc'), staleDir: DEFAULT_DIR }
+    );
+  });
+});
+
+test('detectConfigDirMismatch: null when hook present under active dir', () => {
+  withEnv('/opt/cc', (cp) => {
+    const fs = { existsSync: () => true };
+    assert.equal(cp.detectConfigDirMismatch([path.join('hooks', 'unbound.py')], { fs }), null);
+  });
+});
+
+test('detectConfigDirMismatch: null when hook absent everywhere', () => {
+  withEnv('/opt/cc', (cp) => {
+    const fs = { existsSync: () => false };
+    assert.equal(cp.detectConfigDirMismatch([path.join('hooks', 'unbound.py')], { fs }), null);
+  });
+});
+
+test('detectConfigDirMismatch: gateway-mode stale install (anthropic_key.sh) is detected by default markers', () => {
+  withEnv('/opt/cc', (cp) => {
+    const staleKeyHelper = path.join(DEFAULT_DIR, 'anthropic_key.sh');
+    const fs = { existsSync: (p) => p === staleKeyHelper };
+    assert.deepEqual(
+      cp.detectConfigDirMismatch(undefined, { fs }),
+      { activeDir: path.resolve('/opt/cc'), staleDir: DEFAULT_DIR }
+    );
+  });
+});
+
+test('detectConfigDirMismatch: gateway-mode present under active dir → null (default markers)', () => {
+  withEnv('/opt/cc', (cp) => {
+    const activeKeyHelper = path.join(path.resolve('/opt/cc'), 'anthropic_key.sh');
+    const fs = { existsSync: (p) => p === activeKeyHelper };
+    assert.equal(cp.detectConfigDirMismatch(undefined, { fs }), null);
+  });
+});
+
+test('displayPath: shortens a home-relative path and leaves others alone', () => {
+  const cp = freshModule();
+  assert.equal(cp.displayPath(path.join(os.homedir(), '.claude', 'settings.json')), '~/.claude/settings.json'.split('/').join(path.sep));
+  assert.equal(cp.displayPath(os.homedir()), '~');
+  assert.equal(cp.displayPath('/opt/cc/settings.json'), '/opt/cc/settings.json');
+});
+
+// A sibling dir that merely starts with the same characters is not under home.
+test('displayPath: does not shorten a sibling whose name shares the home prefix', () => {
+  const cp = freshModule();
+  const sibling = os.homedir() + '-backup/settings.json';
+  assert.equal(cp.displayPath(sibling), sibling);
+});
+
+// Claude Code resolves a set-but-empty CLAUDE_CONFIG_DIR against the cwd rather
+// than falling back to ~/.claude, so an install in the default dir is one it
+// never reads. We keep the safe fallback and flag the state instead.
+test('isBlankConfigDir: true only when the var is set and empty', () => {
+  withEnv('   ', (cp) => assert.equal(cp.isBlankConfigDir(), true));
+  withEnv('', (cp) => assert.equal(cp.isBlankConfigDir(), true));
+  withEnv(undefined, (cp) => assert.equal(cp.isBlankConfigDir(), false));
+  withEnv('/opt/cc', (cp) => assert.equal(cp.isBlankConfigDir(), false));
+});
+
+test('a blank dir still resolves to ~/.claude rather than the cwd', () => {
+  withEnv('', (cp) => assert.equal(cp.resolveClaudeConfigDir(), DEFAULT_DIR));
+  withEnv('   ', (cp) => assert.equal(cp.resolveClaudeConfigDir(), DEFAULT_DIR));
+});
+
+// Verified against real Windows path semantics (path.win32): resolve preserves
+// the case it was given, so a differently-cased spelling of the default dir
+// would otherwise read as relocated.
+test('samePath: a differently-cased default dir is not treated as relocated on Windows', function () {
+  if (process.platform !== 'win32') return; // POSIX paths are case-sensitive; nothing to assert
+  const prev = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = DEFAULT_DIR.toLowerCase();
+  try {
+    const cp = freshModule();
+    assert.equal(cp.isNonDefaultConfigDir(), false);
+    assert.equal(cp.detectConfigDirMismatch(undefined, { fs: { existsSync: () => true } }), null);
+  } finally {
+    if (prev === undefined) delete process.env.CLAUDE_CONFIG_DIR; else process.env.CLAUDE_CONFIG_DIR = prev;
+  }
+});
+
+// The guard must not fire on a sibling that merely shares the home prefix.
+test('displayPath: still leaves a non-home path alone', () => {
+  const cp = freshModule();
+  assert.equal(cp.displayPath('/opt/cc/settings.json'), '/opt/cc/settings.json');
+});

package/test/discover-exit-code.test.js

@@ -1,6 +1,21 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
-const { classifyDiscoveryExit } = require('../src/commands/discover');
+const { Command } = require('commander');
+const { classifyDiscoveryExit, register } = require('../src/commands/discover');
+
+// Existing crons can still pass a discovery key. With strict option parsing the
+// CLI would reject an unregistered flag, so discover keeps --discovery-key as an
+// accepted-but-ignored option — the scan runs off the API key. It must never throw.
+test('discover accepts --discovery-key so stale crons are ignored, not rejected', () => {
+  const program = new Command();
+  register(program);
+  const discover = program.commands.find((c) => c.name() === 'discover');
+  assert.ok(discover, 'discover command is registered');
+  assert.ok(
+    discover.options.some((o) => o.long === '--discovery-key'),
+    'discover must register --discovery-key (accept-but-ignore)',
+  );
+});
 
 test('classifyDiscoveryExit: 0 is a successful scan', () => {
   assert.equal(classifyDiscoveryExit(0), 'success');

package/test/onboard-cron.test.js

@@ -118,25 +118,27 @@ test('per-user onboard cron passes apiKey but NOT discoveryKey to setupScheduled
   assert.ok(!callArgs.toLowerCase().includes('backfill'), 'setupScheduledRun call must not include backfill');
 });
 
-// WEB-4891 core fix: the per-user discovery scan must run with the user's own
-// API key so the backend attributes the device to them at ingestion. Only the
-// MDM (sudo) branch — which scans every user and cannot be attributed from one
-// user's key — may scan with the org discovery key.
-test('per-user discovery scans with the user key; only MDM uses the discovery key', () => {
+// The per-user discovery scan runs with the user's own API
+// key; the MDM (sudo) branch resolves the device-owner key from the serial and
+// scans with THAT. Neither scan uses a separate org discovery key.
+test('per-user scans with the user key; MDM scans with the resolved device-owner key; no discovery key', () => {
   const userBranchStart = onboardSrc.indexOf('const apiKey = config.getApiKey();');
   assert.notEqual(userBranchStart, -1, 'expected the per-user branch in onboard.js');
   const userBranch = onboardSrc.slice(userBranchStart);
   assert.match(
     userBranch,
     /runDiscoveryScan\(\{\s*apiKey\s*,/,
-    'per-user onboarding must scan with the user apiKey, not the org discovery key'
+    'per-user onboarding must scan with the user apiKey'
   );
-  const discoveryKeyScans = (onboardSrc.match(/runDiscoveryScan\(\{\s*apiKey:\s*discoveryKeyOpt/g) || []).length;
-  assert.equal(
-    discoveryKeyScans,
-    1,
-    'exactly one runDiscoveryScan (the MDM branch) may use the org discovery key'
+  // MDM branch scans with the serial-resolved owner key (mdmScanKey), never the
+  // (now deprecated/ignored) discovery key.
+  assert.match(
+    onboardSrc,
+    /runDiscoveryScan\(\{\s*apiKey:\s*mdmScanKey/,
+    'MDM onboarding must scan with the resolved device-owner key'
   );
+  const discoveryKeyScans = (onboardSrc.match(/runDiscoveryScan\(\{\s*apiKey:\s*discoveryKeyOpt/g) || []).length;
+  assert.equal(discoveryKeyScans, 0, 'no discovery scan may use the org discovery key');
 });
 
 test('onboard imports setupScheduledRun from ../scheduled', () => {

package/test/onboard-owner-key.test.js

@@ -0,0 +1,38 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+// The owner key is minted from the hardware serial, which must come from a live
+// probe, not the user-writable cache — a planted value would mint the wrong
+// user's key.
+function freshAuth(mock) {
+  for (const m of ['../src/auth', '../src/api', '../src/device-serial']) {
+    delete require.cache[require.resolve(m)];
+  }
+  const api = require('../src/api');
+  const deviceSerial = require('../src/device-serial');
+  mock({ api, deviceSerial });
+  return require('../src/auth');
+}
+
+test('fetchDeviceOwnerKey mints from the LIVE serial, never the plantable cache', async () => {
+  let sentQuery;
+  const auth = freshAuth(({ api, deviceSerial }) => {
+    deviceSerial.getDeviceSerial = async () => 'PLANTED-COWORKER-SERIAL';   // cache
+    deviceSerial.probeDeviceSerialLive = async () => 'REAL-HW-SERIAL';       // live probe
+    api.get = async (_path, opts) => { sentQuery = opts.query; return { api_key: 'owner-key' }; };
+  });
+  const key = await auth.fetchDeviceOwnerKey('admin-key', { baseUrl: 'https://b' });
+  assert.equal(key, 'owner-key');
+  assert.equal(sentQuery.serial_number, 'REAL-HW-SERIAL', 'must use the live hardware serial');
+  assert.notEqual(sentQuery.serial_number, 'PLANTED-COWORKER-SERIAL', 'must NOT trust the cache');
+});
+
+test('fetchDeviceOwnerKey refuses to mint when no live serial can be read', async () => {
+  let called = false;
+  const auth = freshAuth(({ api, deviceSerial }) => {
+    deviceSerial.probeDeviceSerialLive = async () => null;
+    api.get = async () => { called = true; return { api_key: 'x' }; };
+  });
+  await assert.rejects(() => auth.fetchDeviceOwnerKey('admin-key', {}), /hardware serial/);
+  assert.equal(called, false, 'must not hit the mint endpoint without a live serial');
+});

package/test/onboard-scope.test.js

@@ -35,7 +35,7 @@ test('hasRootPrivileges: false when effective uid is not 0 (no sudo)', () => {
 // ---- 2. onboard routes by detected scope ----
 // Reloads the module graph with stubbed deps so we can observe which bundle
 // helper the single `onboard` command invokes.
-async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd' } = {}) {
+async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd', domain, ownerKeyThrows = false } = {}) {
   for (const m of [
     '../src/commands/onboard',
     '../src/commands/setup',
@@ -61,6 +61,13 @@ async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd' } = {})
   setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
   discover.runDiscoveryScan = async (o) => { calls.discovery++; calls.discoveryArgs = o; };
   auth.ensureLoggedIn = async () => { calls.loggedIn++; };
+  // MDM scope resolves the device-owner key from the serial and scans with it.
+  auth.fetchDeviceOwnerKey = async (adminKey, opts) => {
+    calls.ownerFetchedFrom = adminKey;
+    calls.ownerBaseUrl = opts && opts.baseUrl;
+    if (ownerKeyThrows) throw new Error('owner key resolution failed');
+    return 'owner-key';
+  };
   scheduled.setupScheduledRun = async (o) => { calls.cron = o; };
   config.setUrls = () => ({});
   config.getApiKey = () => 'resolved-key';
@@ -77,8 +84,13 @@ async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd' } = {})
   register(program);
   const argv = ['node', 'unbound', 'onboard', '--api-key', 'k'];
   if (discoveryKey) argv.push('--discovery-key', discoveryKey);
+  if (domain) argv.push('--domain', domain);
   if (setCron) argv.push('--set-cron');
+  const prevExit = process.exitCode;
+  process.exitCode = 0;
   await program.parseAsync(argv);
+  calls.exitCode = process.exitCode || 0;
+  process.exitCode = prevExit;
   return calls;
 }
 
@@ -88,7 +100,30 @@ test('onboard with sudo/root → installs the MDM bundle (all users), no login',
   assert.equal(calls.user, 0, 'user bundle NOT installed');
   assert.equal(calls.loggedIn, 0, 'MDM scope does not run ensureLoggedIn');
   assert.equal(calls.discovery, 1, 'discovery still runs');
-  assert.equal(calls.discoveryArgs.apiKey, 'd', 'MDM scope scans with the org discovery key');
+  assert.equal(calls.ownerFetchedFrom, 'k', 'MDM scope resolves the owner key from the admin key');
+  assert.equal(calls.discoveryArgs.apiKey, 'owner-key', 'MDM scope scans with the device-owner key resolved from the serial');
+});
+
+test('onboard MDM with a scheme-less --domain → normalized to an absolute URL for the owner lookup and scan', async () => {
+  const calls = await runOnboard(true, { domain: 'tenant.example.com' });
+  assert.equal(calls.ownerBaseUrl, 'https://tenant.example.com', 'owner lookup gets an absolute base URL');
+  assert.equal(calls.discoveryArgs.domain, 'https://tenant.example.com', 'scan reports to the same absolute URL');
+});
+
+test('onboard MDM: an owner-key failure aborts BEFORE the setup bundle (fail-fast, no partial onboard)', async () => {
+  const calls = await runOnboard(true, { ownerKeyThrows: true });
+  assert.equal(calls.mdm, 0, 'the MDM setup bundle must NOT install when the owner key cannot be resolved');
+  assert.equal(calls.discovery, 0, 'discovery must not run');
+  assert.equal(calls.exitCode, 1, 'onboard exits non-zero');
+});
+
+test('onboard MDM WITH --discovery-key → still resolves the owner key, warns that the flag is ignored', async () => {
+  const calls = await runOnboard(true, { discoveryKey: 'stale' });
+  assert.equal(calls.ownerFetchedFrom, 'k', 'MDM still resolves the owner key from the admin key');
+  assert.ok(
+    calls.warns.some((w) => /discovery-key is deprecated and ignored/.test(w)),
+    'warns that --discovery-key is ignored',
+  );
 });
 
 test('onboard without sudo → logs in and installs the user bundle', async () => {
@@ -103,13 +138,13 @@ test('onboard without sudo → logs in and installs the user bundle', async () =
 });
 
 // --set-cron under sudo schedules discovery only (not a daily full MDM
-// re-install) and stores the discovery key, never the admin key.
-test('onboard --set-cron with sudo → schedules discovery-only with the discovery key', async () => {
+// re-install) and stores the device-owner key, never the admin key.
+test('onboard --set-cron with sudo → schedules discovery-only with the device-owner key', async () => {
   const calls = await runOnboard(true, { setCron: true });
   assert.ok(calls.cron, 'a scheduled run was set up');
   assert.equal(calls.cron.command, 'discover', 'schedules discover, not full onboard');
-  assert.equal(calls.cron.apiKey, 'd', 'uses the discovery key, not the admin key');
-  assert.equal(calls.cron.discoveryKey, undefined, 'no separate admin/discovery key passed');
+  assert.equal(calls.cron.apiKey, 'owner-key', 'uses the resolved device-owner key, not the admin key');
+  assert.equal(calls.cron.discoveryKey, undefined, 'no separate discovery key passed');
 });
 
 test('onboard --set-cron without sudo → schedules the full onboard run', async () => {