node-command 2.0.3 → 2.0.5

package/bin/nc.mjs

@@ -8,10 +8,11 @@ import path from 'node:path';
 import os from 'node:os';
 import child_process from 'node:child_process';
 import readline from 'node:readline';
-import { Writable } from 'node:stream';
+import { Transform, Writable, pipeline } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import {
   canElevate,
+  canRepairUserApplication,
   captureBrowserDefaultBrand,
   normalizeBrowserBrand,
   browserBrandReexecArgs,
@@ -21,14 +22,18 @@ import {
   installerEnvForMode,
   isElevated,
   isUserInstallRoot,
+  probeInstallRoot,
+  resolveExecutable,
   setupTarget,
+  unreadableSystemInstallations,
   maintainLinuxIdentity,
   loadProtectedHelperProducer,
   LINUX_PAIRED_UNINSTALL_ENTRY,
   modeWarningFor,
   runUninstallerScript,
   uninstallFailureSuggestion,
-  uninstallerForRoot
+  uninstallerForRoot,
+  windowsExecutablePath
 } from '../lib/setup.mjs';
 
 const baseUrl = process.env.NC_BASE_URL || 'https://auth.nodecommand.app';
@@ -46,6 +51,7 @@ const clientId = 'nc-cli';
 
 export const DEFAULT_CLI_REQUEST_TIMEOUT_MS = 30_000;
 export const DEFAULT_CLI_MAX_RESPONSE_BYTES = 8 * 1024 * 1024; // 8 MiB
+export const CLI_MAX_PACKAGE_BYTES = 512 * 1024 * 1024; // 512 MiB
 
 export function getCliRequestTimeoutMs() {
   const envVal = Number(process.env.NC_CLI_TIMEOUT_MS || process.env.NC_TIMEOUT_MS);
@@ -57,6 +63,81 @@ export function getCliMaxResponseBytes() {
   return Number.isFinite(envVal) && envVal > 0 ? envVal : DEFAULT_CLI_MAX_RESPONSE_BYTES;
 }
 
+/**
+ * Hard ceiling for downloaded agent packages. Raised only through an explicit
+ * positive override so tests can exercise the streaming cap deterministically.
+ */
+export function getCliMaxPackageBytes() {
+  const envVal = Number(process.env.NC_CLI_MAX_PACKAGE_BYTES);
+  return Number.isSafeInteger(envVal) && envVal > 0 ? envVal : CLI_MAX_PACKAGE_BYTES;
+}
+
+/** Package downloads are bounded separately from ordinary JSON requests. */
+export const DEFAULT_CLI_DOWNLOAD_TIMEOUT_MS = 30 * 60_000; // 30 minutes
+export const MIN_CLI_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const MAX_CLI_DOWNLOAD_TIMEOUT_MS = 60 * 60_000;
+
+export function getCliDownloadTimeoutMs(env = process.env) {
+  const envVal = Number(env.NC_CLI_DOWNLOAD_TIMEOUT_MS);
+  if (!Number.isFinite(envVal) || envVal <= 0) return DEFAULT_CLI_DOWNLOAD_TIMEOUT_MS;
+  return Math.min(MAX_CLI_DOWNLOAD_TIMEOUT_MS, Math.max(MIN_CLI_DOWNLOAD_TIMEOUT_MS, Math.floor(envVal)));
+}
+
+/**
+ * Strips terminal control sequences and control characters from untrusted
+ * display text (server-provided versions, URLs, errors and messages) so a
+ * hostile field cannot forge logs or move the cursor. Line breaks collapse to
+ * spaces, keeping every rendered message on one line.
+ * @param {unknown} value
+ * @param {number} [maxLength]
+ */
+export function sanitizeForDisplay(value, maxLength = 512) {
+  let text = typeof value === 'string' ? value : String(value ?? '');
+  text = text.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+  text = text.replace(/\x1b[P^_X][\s\S]*?\x1b\\/g, '');
+  text = text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  text = text.replace(/\x1b[@-_]/g, '');
+  text = text.replace(/[\r\n\t]+/g, ' ');
+  text = text.replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+  if (text.length > maxLength) text = `${text.slice(0, maxLength)}…`;
+  return text;
+}
+
+/** Explicit insecure-HTTP opt-in for local testing only. */
+export const INSECURE_HTTP_OPT_IN_ENV = 'NC_ALLOW_INSECURE_HTTP';
+
+export function allowsInsecureCredentialHttp(env = process.env) {
+  return String(env[INSECURE_HTTP_OPT_IN_ENV] ?? '').trim() === '1';
+}
+
+/**
+ * Refuses credential-bearing origins that are not HTTPS unless the explicit
+ * local-testing opt-in is set. Mirrors the stricter maintenance-config check.
+ * @param {string} targetUrl
+ * @param {{ env?: NodeJS.ProcessEnv, label?: string, action?: string }} [options]
+ */
+export function assertCredentialOrigin(targetUrl, { env = process.env, label = 'server URL', action = 'send credentials' } = {}) {
+  let parsed;
+  try {
+    parsed = new URL(String(targetUrl));
+  } catch {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} with an invalid ${label}.`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} to a ${label} that embeds user credentials.`);
+  }
+  if (parsed.protocol === 'http:' && !allowsInsecureCredentialHttp(env)) {
+    throw new PairingError(
+      'INSECURE_SERVER_URL',
+      `Refusing to ${action} over plaintext http:// (${label}). Use an https:// URL; set ${INSECURE_HTTP_OPT_IN_ENV}=1 only for local testing.`
+    );
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to ${action} to a non-HTTP(S) ${label}.`);
+  }
+  return parsed;
+}
+
 /**
  * Sends a JSON HTTP request using node:https or node:http with timeout and response cap guards (NC-AUD-010).
  * @param {string} method
@@ -261,7 +342,19 @@ export function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}, options
           res.statusCode < 400 &&
           res.headers.location
         ) {
-          const redirectUrl = new URL(res.headers.location, targetUrl).toString();
+          /** @type {string} */
+          let redirectUrl;
+          try {
+            redirectUrl = new URL(res.headers.location, targetUrl).toString();
+          } catch (err) {
+            // A malformed Location header must reject the request, never throw
+            // out of the response callback as an uncaughtException.
+            res.resume();
+            return reject(new PairingError(
+              'INSTALL_DOWNLOAD_ERROR',
+              `The package response from ${targetUrl} contained an invalid redirect location: ${err instanceof Error ? err.message : String(err)}`
+            ));
+          }
           res.resume();
           const forwarded = isSameOrigin(targetUrl, redirectUrl) ? extraHeaders : {};
           return resolve(httpGet(redirectUrl, maxRedirects - 1, forwarded, { signal, timeoutMs }));
@@ -298,42 +391,111 @@ export async function fetchJson(targetUrl, extraHeaders = {}) {
 }
 
 /**
- * Downloads a remote file stream directly to disk.
+ * Downloads a remote file stream directly to disk with a hard byte ceiling and
+ * an incrementally computed SHA-256 digest. The archive is never loaded into
+ * the heap: bytes are hashed as they are written.
  * @param {string} targetUrl
  * @param {string} destinationPath
  * @param {Record<string, string>} [extraHeaders] Device headers for `/api/clients/...` package URLs; empty for public `/releases/...` URLs.
- * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options]
- * @returns {Promise<string>}
+ * @param {{ timeoutMs?: number, signal?: AbortSignal, maxBytes?: number }} [options]
+ * @returns {Promise<{ path: string, bytes: number, sha256: string }>}
  */
 export async function downloadToFile(targetUrl, destinationPath, extraHeaders = {}, options = {}) {
-  const res = await httpGet(targetUrl, 5, extraHeaders, options);
+  const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes > 0 ? options.maxBytes : getCliMaxPackageBytes();
+  const timeoutMs = options.timeoutMs ?? getCliDownloadTimeoutMs();
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer;
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+  }
+  const clearTimer = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+  const timeoutError = () => Object.assign(
+    new Error(`Agent package download timed out after ${timeoutMs}ms.`),
+    { code: 'CLI_DOWNLOAD_TIMEOUT', name: 'TimeoutError' }
+  );
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  let res;
+  try {
+    res = await httpGet(targetUrl, 5, extraHeaders, { ...options, timeoutMs: 0, signal });
+  } catch (err) {
+    clearTimer();
+    throw timedOut ? timeoutError() : err;
+  }
   return new Promise((resolve, reject) => {
-    const fileStream = fs.createWriteStream(destinationPath);
-    let resolved = false;
+    const tooLarge = () => Object.assign(
+      new Error(`Agent package exceeds the maximum supported size of ${maxBytes} bytes.`),
+      { code: 'CLI_PACKAGE_TOO_LARGE' }
+    );
+    const declaredLength = Number(res.headers?.['content-length']);
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+      res.resume();
+      clearTimer();
+      reject(tooLarge());
+      return;
+    }
+
+    const fileStream = fs.createWriteStream(destinationPath, { mode: 0o600 });
+    const hash = crypto.createHash('sha256');
+    let bytes = 0;
+    let settled = false;
+
+    const meter = new Transform({
+      transform(chunk, encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          callback(tooLarge());
+          return;
+        }
+        hash.update(chunk);
+        callback(null, chunk);
+      }
+    });
 
     const onError = (err) => {
-      if (resolved) return;
-      resolved = true;
+      if (settled) return;
+      settled = true;
+      clearTimer();
       fileStream.destroy();
       try {
         fs.unlinkSync(destinationPath);
       } catch {}
-      reject(err);
+      reject(timedOut ? timeoutError() : err);
     };
 
     res.on('error', onError);
+    meter.on('error', onError);
     fileStream.on('error', onError);
 
-    fileStream.on('finish', () => {
-      if (resolved) return;
-      resolved = true;
-      fileStream.close(() => resolve(destinationPath));
+    pipeline(res, meter, fileStream, (err) => {
+      if (err) return onError(err);
+      if (settled) return;
+      settled = true;
+      clearTimer();
+      resolve({ path: destinationPath, bytes, sha256: hash.digest('hex') });
     });
-
-    res.pipe(fileStream);
   });
 }
 
+/** Distinguishes an aborted/slow transfer from a credential or manifest failure. */
+function isCliTimeoutError(err) {
+  return Boolean(err) && (
+    err.name === 'TimeoutError' ||
+    err.name === 'AbortError' ||
+    err.code === 'ABORT_ERR' ||
+    err.code === 'CLI_DOWNLOAD_TIMEOUT'
+  );
+}
+
 /**
  * Determines the canonical installation root (NC_ROOT) dynamically based on
  * OS:
@@ -370,14 +532,81 @@ export function getNcRoot({ platform = os.platform(), env = process.env } = {})
  * @returns {string}
  */
 function getTarCommand() {
-  if (os.platform() === 'win32') {
-    const sysTar = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe');
-    if (fs.existsSync(sysTar)) {
-      return sysTar;
+  return resolveExecutable('tar');
+}
+
+/** Only pass GNU confinement flags when this tar actually advertises them. */
+function tarSupportsNoAbsoluteFilenames(tarCmd) {
+  try {
+    const help = child_process.execFileSync(tarCmd, ['--help'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+      maxBuffer: 256 * 1024,
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C' }
+    });
+    return /--no-absolute-filenames/.test(String(help));
+  } catch {
+    return false;
+  }
+}
+
+function tarInspectionError(tarCmd, err) {
+  const detail = err?.stderr ? err.stderr.toString().trim() : err?.message;
+  return new Error(
+    `Failed to inspect tarball (${tarCmd}): ${sanitizeForDisplay(detail, 300)}`,
+    { cause: err }
+  );
+}
+
+function rejectsTarEntry(name) {
+  const value = String(name).trim();
+  if (!value) return false;
+  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) return true;
+  return value.split(/[\\/]+/).includes('..');
+}
+
+/**
+ * Rejects traversal, absolute and link entries before extraction. This is
+ * defense-in-depth on top of GNU tar's --no-absolute-filenames; the archive is
+ * fully listed first so a hostile entry cannot be extracted at all.
+ */
+function assertSafeTarArchive(tarCmd, archivePath) {
+  let listing;
+  try {
+    listing = child_process.execFileSync(tarCmd, ['-tzf', archivePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30000,
+      maxBuffer: 4 * 1024 * 1024
+    });
+  } catch (err) {
+    throw tarInspectionError(tarCmd, err);
+  }
+  for (const name of String(listing).split(/\r?\n/)) {
+    if (rejectsTarEntry(name)) {
+      throw new Error(`Unsafe archive entry escapes the extraction root: ${sanitizeForDisplay(name, 200)}`);
+    }
+  }
+
+  let verbose;
+  try {
+    verbose = child_process.execFileSync(tarCmd, ['-tvzf', archivePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30000,
+      maxBuffer: 4 * 1024 * 1024
+    });
+  } catch (err) {
+    throw tarInspectionError(tarCmd, err);
+  }
+  for (const line of String(verbose).split(/\r?\n/)) {
+    // Symlink (l) and hardlink (h) entries can redirect later writes outside
+    // the extraction root even when their names look safe.
+    if (/^[lh][rwxStTs-]{9}/.test(line)) {
+      throw new Error(`Unsafe archive link entry is not permitted: ${sanitizeForDisplay(line, 200)}`);
     }
-    return 'tar.exe';
   }
-  return 'tar';
 }
 
 /**
@@ -386,14 +615,18 @@ function getTarCommand() {
  * @param {string} targetDir
  */
 function extractTarball(archivePath, targetDir) {
-  const tarCmd = getTarCommand();
+  let tarCmd = 'tar';
   try {
-    child_process.execFileSync(tarCmd, ['-xzf', archivePath, '-C', targetDir], {
+    tarCmd = getTarCommand();
+    assertSafeTarArchive(tarCmd, archivePath);
+    const args = ['-xzf', archivePath, '-C', targetDir];
+    if (tarSupportsNoAbsoluteFilenames(tarCmd)) args.unshift('--no-absolute-filenames');
+    child_process.execFileSync(tarCmd, args, {
       stdio: ['ignore', 'pipe', 'pipe']
     });
   } catch (err) {
     const details = err.stderr ? err.stderr.toString().trim() : err.message;
-    throw new Error(`Failed to extract tarball (${tarCmd}): ${details}`, { cause: err });
+    throw new Error(`Failed to extract tarball (${tarCmd}): ${sanitizeForDisplay(details, 300)}`, { cause: err });
   }
 }
 
@@ -440,33 +673,39 @@ export function findInstallerScript(tempDir) {
  */
 export function runInstallerScript(scriptPath, ncRoot, extraEnv = {}) {
   const platform = os.platform();
-  const installEnv = {
-    ...process.env,
-    NC_ROOT: ncRoot,
-    ...extraEnv
-  };
 
   if (platform === 'win32') {
     child_process.execFileSync(
-      'powershell.exe',
-      ['-ExecutionPolicy', 'Bypass', '-File', scriptPath],
+      windowsExecutablePath('powershell'),
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath],
       {
-        env: installEnv,
+        env: { ...process.env, NC_ROOT: ncRoot, ...extraEnv },
         stdio: 'inherit'
       }
     );
-  } else if (platform === 'darwin') {
-    child_process.execFileSync('bash', [scriptPath], {
-      env: installEnv,
-      stdio: 'inherit'
-    });
-  } else {
-    // Linux and other POSIX
-    child_process.execFileSync('bash', [scriptPath], {
-      env: installEnv,
-      stdio: 'inherit'
-    });
+    return;
   }
+
+  // The OS installer runs with root privileges, so it never inherits the
+  // caller's environment. Only a fixed base plus NC_* installer knobs and
+  // explicit extras reach it; BASH_ENV/ENV/SHELLOPTS/LD_*/NODE_OPTIONS cannot.
+  const installEnv = {
+    PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+    HOME: os.userInfo().homedir,
+    LANG: 'C',
+    LC_ALL: 'C'
+  };
+  for (const [name, value] of Object.entries(process.env)) {
+    if (name.startsWith('NC_') && typeof value === 'string') installEnv[name] = value;
+  }
+  Object.assign(installEnv, { NC_ROOT: ncRoot }, extraEnv);
+  // `-p` (privileged mode) plus --noprofile/--norc ignores BASH_ENV/ENV startup
+  // files; cwd '/' keeps a user-writable directory out of the root installer.
+  child_process.execFileSync(resolveExecutable('bash'), ['--noprofile', '--norc', '-p', '--', scriptPath], {
+    env: installEnv,
+    stdio: 'inherit',
+    cwd: '/'
+  });
 }
 
 /**
@@ -535,6 +774,214 @@ export function getEnrollStatePath(ncRoot = getNcRoot()) {
   return path.join(ncRoot, 'config', 'nc-enroll-state.json');
 }
 
+/**
+ * Serializes setup/install/uninstall for one installation root. The lock file
+ * lives under the root, is created with O_CREAT|O_EXCL and 0600 (O_EXCL
+ * refuses an existing file or symlink instead of following it), carries the
+ * owner PID, and is released by the exit handler as well as by the caller's
+ * finally block (so `process.exit` cannot leave it behind). A live owner is a
+ * clear SETUP_IN_PROGRESS refusal; a dead PID is stale and is reclaimed once.
+ * @param {string} ncRoot
+ * @returns {{ release: () => void }}
+ */
+export function acquireInstallLock(ncRoot) {
+  const configDir = path.join(ncRoot, 'config');
+  const lockPath = path.join(configDir, '.nc-cli.lock');
+  const createdConfig = !fs.existsSync(configDir);
+  const createdRoot = createdConfig && !fs.existsSync(ncRoot);
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o750 });
+
+  const readOwnerPid = () => {
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+      const info = fs.fstatSync(fd);
+      if (!info.isFile() || info.size > 32) return null;
+      const text = fs.readFileSync(fd, 'utf8').trim();
+      return /^\d+$/.test(text) ? Number(text) : null;
+    } catch {
+      return null;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  };
+
+  const pidIsAlive = (pid) => {
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      return err?.code === 'EPERM';
+    }
+  };
+
+  let acquired = false;
+  for (let attempt = 0; attempt < 2 && !acquired; attempt += 1) {
+    try {
+      // `wx` is O_WRONLY|O_CREAT|O_EXCL: an existing file OR symlink at the
+      // lock path fails with EEXIST instead of being followed or truncated.
+      fs.writeFileSync(lockPath, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+      if (process.platform !== 'win32') {
+        try {
+          fs.chmodSync(lockPath, 0o600);
+        } catch {}
+      }
+      acquired = true;
+    } catch (err) {
+      if (err?.code !== 'EEXIST') throw err;
+      const owner = readOwnerPid();
+      if (owner === null || pidIsAlive(owner)) {
+        throw new PairingError(
+          'SETUP_IN_PROGRESS',
+          `Another Node Command setup, install or uninstall is already running for ${ncRoot}${owner === null ? '' : ` (pid ${owner})`}. Wait for it to finish; no configuration was changed.`
+        );
+      }
+      // Stale owner: reclaim the lock exactly once.
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (unlinkErr) {
+        if (unlinkErr?.code !== 'ENOENT') throw unlinkErr;
+      }
+    }
+  }
+  if (!acquired) {
+    throw new PairingError('SETUP_IN_PROGRESS', `Could not acquire the setup lock for ${ncRoot}; no configuration was changed.`);
+  }
+
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    try {
+      const owner = readOwnerPid();
+      if (owner === process.pid) fs.unlinkSync(lockPath);
+    } catch {}
+    // Remove empty directories created only for the lock so a failed setup
+    // does not leave a root that blocks the next attempt.
+    if (createdConfig) {
+      try {
+        fs.rmdirSync(configDir);
+        if (createdRoot) fs.rmdirSync(ncRoot);
+      } catch {}
+    }
+  };
+  process.once('exit', release);
+  return {
+    release: () => {
+      process.removeListener('exit', release);
+      release();
+    }
+  };
+}
+
+/**
+ * Prepares the token transport used for legacy `setup <host_id> <token>`
+ * elevation: the secret goes to a 0600 owner-only temp file and only its path
+ * enters sudo/UAC argv.
+ * @param {string} token
+ */
+export function createEnrollmentTokenFile(token) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nc-enroll-'));
+  const filePath = path.join(dir, 'token');
+  fs.writeFileSync(filePath, String(token), { mode: 0o600, flag: 'wx' });
+  if (os.platform() !== 'win32') {
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {}
+  }
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  };
+  // process.exit() skips finally blocks, so the exit hook guarantees the
+  // secret file is removed even on the declined-elevation hard stops.
+  process.once('exit', cleanup);
+  return {
+    filePath,
+    cleanup: () => {
+      process.removeListener('exit', cleanup);
+      cleanup();
+    }
+  };
+}
+
+/**
+ * Reads the elevated-invocation token file (no symlinks, owner-only) and
+ * removes it immediately after use.
+ * @param {string} filePath
+ */
+function readEnrollmentTokenFile(filePath) {
+  if (typeof filePath !== 'string' || !path.isAbsolute(filePath)) {
+    throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file path is invalid.');
+  }
+  let fd;
+  let token;
+  try {
+    try {
+      fd = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    } catch {
+      throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is missing, unreadable, or a symlink.');
+    }
+    const info = fs.fstatSync(fd);
+    if (!info.isFile() || info.size <= 0 || info.size > 1024) {
+      throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not a valid token file.');
+    }
+    if (os.platform() !== 'win32') {
+      if ((info.mode & 0o077) !== 0) {
+        throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not owner-only.');
+      }
+      const currentUid = typeof process.getuid === 'function' ? process.getuid() : null;
+      if (currentUid !== null) {
+        const allowedUids = new Set([currentUid]);
+        // `sudo` runs the elevated reader as root while the pre-sudo writer
+        // owned the file as the invoking user. Trust SUDO_UID only when the
+        // reader is actually root, and only as a validated numeric uid.
+        if (currentUid === 0 && typeof process.env.SUDO_UID === 'string' && /^\d+$/.test(process.env.SUDO_UID)) {
+          const sudoUid = Number(process.env.SUDO_UID);
+          if (Number.isSafeInteger(sudoUid) && sudoUid >= 0) allowedUids.add(sudoUid);
+        }
+        if (!allowedUids.has(info.uid)) {
+          throw new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file is not owned by the invoking user.');
+        }
+      }
+    }
+    token = fs.readFileSync(fd, 'utf8');
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try {
+      fs.unlinkSync(filePath);
+      const dir = path.dirname(filePath);
+      if (path.basename(dir).startsWith('nc-enroll-')) fs.rmdirSync(dir);
+    } catch {}
+  }
+  return token;
+}
+
+/**
+ * Replaces the legacy enrollment token in the elevated argv with a file path.
+ * Pure so the no-secret-in-argv property is directly testable.
+ * @param {string[]} nodeArgs process.argv.slice(1)
+ * @param {string[]} setupArgs subcommand args (without a literal `setup`)
+ * @param {number} tokenIndex index of the token in setupArgs
+ * @param {string} tokenFile
+ * @returns {string[]}
+ */
+export function buildElevatedSetupArgs(nodeArgs, setupArgs, tokenIndex, tokenFile) {
+  if (!Array.isArray(nodeArgs) || !Array.isArray(setupArgs) || tokenIndex < 0 || tokenIndex >= setupArgs.length) return [...nodeArgs];
+  const prefixLength = nodeArgs.length - setupArgs.length;
+  const elevated = [...nodeArgs];
+  elevated.splice(prefixLength + tokenIndex, 1, '--enrollment-token-file', tokenFile);
+  // A bare `<host_id> <token>` invocation must route through the setup handler
+  // after elevation; adding the subcommand keeps dispatch unchanged.
+  if (prefixLength === 1) elevated.splice(1, 0, 'setup');
+  return elevated;
+}
+
 /**
  * Builds the canonical agent env file content from HOST credentials only.
  * There is deliberately no parameter for the OAuth token: by construction it
@@ -544,8 +991,23 @@ export function getEnrollStatePath(ncRoot = getNcRoot()) {
  * @param {{ serverUrl: string, hostId: string, hostToken: string, clientName?: string, browserBrand?: string }} options
  */
 export function buildHostEnvContent({ serverUrl, hostId, hostToken, clientName = os.hostname(), browserBrand = 'unknown' }) {
-  if (typeof serverUrl !== 'string' || !serverUrl) {
-    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config without a server URL.');
+  if (typeof serverUrl !== 'string' || !serverUrl || /[\x00-\x1f\x7f]/.test(serverUrl)) {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config without a valid server URL.');
+  }
+  let parsedServerUrl;
+  try {
+    parsedServerUrl = new URL(serverUrl);
+  } catch {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config: the server URL is not an absolute http(s) URL.');
+  }
+  if ((parsedServerUrl.protocol !== 'https:' && parsedServerUrl.protocol !== 'http:') || parsedServerUrl.username || parsedServerUrl.password) {
+    throw new PairingError('INVALID_SERVER_URL', 'Refusing to write agent config: the server URL must be http(s) and must not embed credentials.');
+  }
+  if (parsedServerUrl.protocol === 'http:' && !allowsInsecureCredentialHttp()) {
+    throw new PairingError('INVALID_SERVER_URL', `Refusing to write agent config: plaintext http:// is not allowed for a credential-bearing server URL; use https:// (set ${INSECURE_HTTP_OPT_IN_ENV}=1 only for local testing).`);
+  }
+  if (typeof clientName !== 'string' || /[\x00-\x1f\x7f]/.test(clientName)) {
+    throw new PairingError('INVALID_CLIENT_NAME', 'Refusing to write agent config: the client name contains control characters.');
   }
   if (!HOST_ID_RE.test(String(hostId || ''))) {
     throw new PairingError(
@@ -614,6 +1076,11 @@ export function loadValidHostEnv(envPath = getEnvFilePath()) {
   } catch {
     return null;
   }
+  // Duplicate required keys are ambiguous (a repeated line could shadow the
+  // verified identity), so the loader refuses the file instead of last-wins.
+  for (const name of ['NC_CLIENT_ID', 'NC_CLIENT_TOKEN', 'NC_SERVER_URL']) {
+    if (text.split(/\r?\n/).filter((line) => new RegExp(`^\\s*${name}\\s*=`).test(line)).length > 1) return null;
+  }
   const env = parseEnvFile(text);
   if (!HOST_ID_RE.test(String(env.NC_CLIENT_ID || ''))) return null;
   if (!HOST_TOKEN_RE.test(String(env.NC_CLIENT_TOKEN || ''))) return null;
@@ -878,6 +1345,7 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
     throw new PairingError('ENROLL_NO_OAUTH_TOKEN', 'Cannot request enrollment without a sign-in token. Re-run the device flow.');
   }
   const origin = String(baseUrl || '').replace(/\/$/, '');
+  assertCredentialOrigin(origin, { label: 'enrollment origin' });
   const body = { platform, ...(name ? { name } : {}), ...(tenantId ? { tenant_id: tenantId } : {}) };
   let res;
   try {
@@ -891,8 +1359,8 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
     }
     return res.data;
   }
-  const serverError = res.data?.error;
-  const serverMessage = typeof res.data?.message === 'string' ? `: ${res.data.message}` : '';
+  const serverError = sanitizeForDisplay(res.data?.error || '', 120);
+  const serverMessage = typeof res.data?.message === 'string' ? `: ${sanitizeForDisplay(res.data.message)}` : '';
   if (res.status === 401) {
     throw new PairingError('ENROLL_UNAUTHORIZED', 'Sign-in expired or was revoked. Re-run the device flow to sign in again.');
   }
@@ -925,6 +1393,7 @@ export async function requestEnrollment({ baseUrl, oauthToken, platform = 'linux
 export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPair, initialPermission = 'user' }) {
   if (!['user', 'admin'].includes(initialPermission)) throw new PairingError('INVALID_INITIAL_PERMISSION', 'Initial execution intent must be user or admin.');
   const origin = String(baseUrl || '').replace(/\/$/, '');
+  assertCredentialOrigin(origin, { label: 'redemption origin' });
   const redeemPath = `/api/enroll/redeem?initial_permission=${initialPermission}`;
   const proof = createDeviceProofCli({
     privateKey: keyPair.privateKey,
@@ -953,7 +1422,7 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
     }
     return r;
   }
-  const serverError = res.data?.error;
+  const serverError = sanitizeForDisplay(res.data?.error || '', 120);
   if (res.status === 410 && serverError === 'ENROLLMENT_ALREADY_USED') {
     throw new PairingError(
       'ENROLLMENT_ALREADY_USED',
@@ -987,6 +1456,7 @@ export async function redeemEnrollment({ baseUrl, hostId, enrollmentToken, keyPa
   */
 export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined, apiBase: apiBaseOpt = undefined, hostId, hostToken, privateKey, timeoutMs = 45000, intervalMs = 2000 }) {
   const origin = String(apiBaseOpt ?? baseUrlOpt ?? process.env.NC_API_URL ?? apiBase).replace(/\/$/, '');
+  assertCredentialOrigin(origin, { label: 'agent server origin' });
   const target = `/api/clients/${encodeURIComponent(hostId)}/policy`;
   const deadline = Date.now() + Math.max(1000, Number(timeoutMs) || 45000);
   const step = Math.max(250, Math.min(Number(intervalMs) || 2000, deadline - Date.now()));
@@ -999,20 +1469,25 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
         'NC-Device-Proof': proof
       });
       if (res.status === 200 && res.data?.policy) return { ok: true, hostId };
-      lastError = res.data?.error || `HTTP ${res.status}`;
+      lastError = sanitizeForDisplay(res.data?.error || `HTTP ${res.status}`, 200);
       // A missing client row will never appear by waiting: fail fast so the
       // user gets the real cause instead of a timeout.
       if (res.status === 404) {
-        throw new PairingError('VERIFY_FAILED', `Host ${hostId} is not registered on the server (${lastError}). Re-run to enroll again.`);
+        throw new PairingError('VERIFY_FAILED', `Host ${sanitizeForDisplay(hostId, 128)} is not registered on the server (${lastError}). Re-run to enroll again.`);
+      }
+      // A refused device credential cannot become valid by waiting: fail fast
+      // instead of polling until the verification timeout.
+      if (res.status === 401 || res.status === 403) {
+        throw new PairingError('VERIFY_FAILED', `Host ${sanitizeForDisplay(hostId, 128)} was refused at ${sanitizeForDisplay(origin, 256)} (${lastError}). The stored device credential is not accepted; re-run to enroll again.`);
       }
     } catch (err) {
       if (err instanceof PairingError) throw err;
-      lastError = err.message;
+      lastError = sanitizeForDisplay(err.message, 200);
     }
     if (Date.now() >= deadline) {
       throw new PairingError(
         'VERIFY_TIMEOUT',
-        `Could not confirm host ${hostId} on the server in time (last: ${lastError}). The credentials are stored; check connectivity and re-run to verify.`
+        `Could not confirm host ${sanitizeForDisplay(hostId, 128)} on the server in time (last: ${lastError}). The credentials are stored; check connectivity and re-run to verify.`
       );
     }
     await sleep(Math.min(step, Math.max(250, deadline - Date.now())));
@@ -1044,9 +1519,9 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
  * (`/releases/client/<version>/bootstrap.tar.gz`) stays anonymous. The
  * proof binds method GET + the full request URL + the redemption-issued
  * client token, exactly like redeemEnrollment.
- * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', rootConsent?: boolean, runInstaller?: (scriptPath: string, ncRoot: string) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject }} options
+ * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', rootConsent?: boolean, runInstaller?: (scriptPath: string, ncRoot: string) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject, downloadTimeoutMs?: number }} options
  */
-export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, rootConsent = false, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined } = {}) {
+export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, rootConsent = false, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined, downloadTimeoutMs = undefined } = {}) {
   ncRoot = ncRoot || (installMode ? getNcRootForMode(installMode) : getNcRoot());
   const modeEnv = { ...(installMode ? installerEnvForMode(installMode) : {}), NC_ROOT_COMMAND_CONSENT: rootConsent === true ? 'yes' : 'no' };
   const invokeInstaller =
@@ -1060,28 +1535,33 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
   // used here. NC_SERVER_URL remains the agent server address and is read
   // before the API origin so existing installs keep resolving as before.
   const defaultBaseUrl = serverUrl || process.env.NC_SERVER_URL || process.env.NC_API_URL || apiBase;
+  const hasDeviceIdentity =
+    typeof hostId === 'string' &&
+    hostId &&
+    typeof hostToken === 'string' &&
+    hostToken &&
+    privateKey;
+  // Device identity must never travel over plaintext HTTP, including the
+  // fresh-enrollment resume paths that skip the manifest above.
+  if (hasDeviceIdentity) {
+    assertCredentialOrigin(defaultBaseUrl, { label: 'agent server origin' });
+  }
   /** @type {Record<string, any>} */
   let activeRelease;
   if (release && typeof release === 'object') {
     // Redemption release wins: skip the manifest entirely, so its URL is
     // never logged as a misleading signal.
     activeRelease = /** @type {Record<string, any>} */ (release);
-    const releaseVersion = activeRelease.version ? ` ${activeRelease.version}` : '';
+    const releaseVersion = activeRelease.version ? ` ${sanitizeForDisplay(activeRelease.version, 120)}` : '';
     console.log(`📦 Using release${releaseVersion} from enrollment redemption; skipping update manifest.`);
-  } else if (
-    typeof hostId === 'string' &&
-    hostId &&
-    typeof hostToken === 'string' &&
-    hostToken &&
-    privateKey
-  ) {
+  } else if (hasDeviceIdentity) {
     // Resume paths (verified stored credentials, already-redeemed enrollment)
     // carry no redemption release, but they DO hold device identity. Resolve
     // the release from the client-authenticated per-host manifest the agent
     // updater itself uses, never from the admin-only /api/updates manifest
     // (which can only answer 401/404 to a non-admin CLI).
     const clientManifestUrl = `${defaultBaseUrl}/api/clients/${encodeURIComponent(hostId)}/update/manifest`;
-    console.log(`📡 Fetching client update manifest from ${clientManifestUrl}...`);
+    console.log(`📡 Fetching client update manifest from ${sanitizeForDisplay(clientManifestUrl, 256)}...`);
     let manifestData;
     try {
       manifestData = await fetchJson(
@@ -1092,14 +1572,17 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       const detail = err instanceof Error ? err.message : String(err);
       throw new PairingError(
         'INSTALL_MANIFEST_ERROR',
-        `Could not fetch the client update manifest: ${detail}`
+        `Could not fetch the client update manifest: ${sanitizeForDisplay(detail, 300)}`
       );
     }
     activeRelease = manifestData?.release || manifestData || {};
   } else {
     const manifestOrigin = String(process.env.NC_API_URL || apiBase).replace(/\/$/, '');
     const manifestUrl = updatesUrl || process.env.NC_UPDATES_URL || `${manifestOrigin}/api/updates`;
-    console.log(`📡 Fetching update manifest from ${manifestUrl}...`);
+    // The anonymous manifest controls sha256, size and package URLs; a MITM
+    // over plaintext HTTP could rewrite all three.
+    assertCredentialOrigin(manifestUrl, { label: 'update manifest URL', action: 'fetch' });
+    console.log(`📡 Fetching update manifest from ${sanitizeForDisplay(manifestUrl, 256)}...`);
     let manifestData;
     try {
       manifestData = await fetchJson(manifestUrl);
@@ -1108,10 +1591,10 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       if (/status 401\b/i.test(detail)) {
         throw new PairingError(
           'INSTALL_MANIFEST_ERROR',
-          `Update manifest refused with ADMIN_AUTH_REQUIRED (${detail}). The manifest endpoint is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, then re-run.`
+          `Update manifest refused with ADMIN_AUTH_REQUIRED (${sanitizeForDisplay(detail, 300)}). The manifest endpoint is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, then re-run.`
         );
       }
-      throw new PairingError('INSTALL_MANIFEST_ERROR', `Could not fetch the agent release manifest: ${detail}`);
+      throw new PairingError('INSTALL_MANIFEST_ERROR', `Could not fetch the agent release manifest: ${sanitizeForDisplay(detail, 300)}`);
     }
     if (manifestData && typeof manifestData === 'object' && manifestData.error === 'ADMIN_AUTH_REQUIRED') {
       throw new PairingError(
@@ -1136,6 +1619,15 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
     if (!tarballUrl.startsWith('http://') && !tarballUrl.startsWith('https://')) {
       tarballUrl = new URL(tarballUrl, defaultBaseUrl).toString();
     }
+    let parsedTarballUrl;
+    try {
+      parsedTarballUrl = new URL(tarballUrl);
+    } catch {
+      throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent package URL is not a valid absolute URL.');
+    }
+    if (parsedTarballUrl.username || parsedTarballUrl.password) {
+      throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent package URL must not embed user credentials.');
+    }
   } else {
     if (!version) {
       throw new PairingError('INSTALL_MANIFEST_ERROR', 'Unable to determine agent version from update manifest.');
@@ -1157,6 +1649,13 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
   if (!Number.isSafeInteger(expectedSize) || expectedSize <= 0) {
     throw new PairingError('INSTALL_MANIFEST_ERROR', 'Agent release manifest must provide a valid positive integer size before downloading or installing.');
   }
+  const maxPackageBytes = getCliMaxPackageBytes();
+  if (expectedSize > maxPackageBytes) {
+    throw new PairingError(
+      'INSTALL_MANIFEST_ERROR',
+      `Agent package size ${expectedSize} bytes exceeds the maximum supported ${maxPackageBytes} bytes; nothing was downloaded or installed.`
+    );
+  }
 
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nc-install-'));
   const archivePath = path.join(tempDir, 'bootstrap.tar.gz');
@@ -1169,40 +1668,58 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
 
   // Identity decision per endpoint: device headers only for the
   // device-authenticated per-client URLs; public release URLs stay bare so
-  // no credential is ever sent where it is not required (or valid).
+  // no credential is ever sent where it is not required (or valid). A
+  // device-authenticated URL that left the trusted origin is refused before
+  // any request, so a hostile manifest cannot redirect the credential.
   let downloadHeaders = {};
   if (isDeviceAuthenticatedPackageUrl(tarballUrl)) {
+    if (!isSameOrigin(tarballUrl, defaultBaseUrl)) {
+      throw new PairingError(
+        'INSTALL_MANIFEST_ERROR',
+        `Agent package URL ${sanitizeForDisplay(tarballUrl, 256)} is not on the trusted origin ${sanitizeForDisplay(defaultBaseUrl, 256)}; refusing to send device credentials.`
+      );
+    }
     if (typeof hostId === 'string' && typeof hostToken === 'string' && hostId && hostToken && privateKey) {
       downloadHeaders = buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, tarballUrl);
     }
   }
 
   try {
-    console.log(`⬇️ Downloading agent package from ${tarballUrl}...`);
+    console.log(`⬇️ Downloading agent package from ${sanitizeForDisplay(tarballUrl)}...`);
+    const effectiveDownloadTimeoutMs = downloadTimeoutMs ?? getCliDownloadTimeoutMs();
+    let download;
     try {
-      await downloadToFile(tarballUrl, archivePath, downloadHeaders);
+      download = await downloadToFile(tarballUrl, archivePath, downloadHeaders, {
+        maxBytes: getCliMaxPackageBytes(),
+        timeoutMs: effectiveDownloadTimeoutMs
+      });
     } catch (err) {
-      throw new PairingError('INSTALL_DOWNLOAD_ERROR', `Could not download the agent package: ${err.message}`);
+      if (isCliTimeoutError(err)) {
+        throw new PairingError(
+          'INSTALL_DOWNLOAD_TIMEOUT',
+          `The agent package download from ${sanitizeForDisplay(tarballUrl)} timed out after ${effectiveDownloadTimeoutMs}ms. No archive was installed; check network speed or raise NC_CLI_DOWNLOAD_TIMEOUT_MS (${MIN_CLI_DOWNLOAD_TIMEOUT_MS}-${MAX_CLI_DOWNLOAD_TIMEOUT_MS}), then re-run.`
+        );
+      }
+      throw new PairingError('INSTALL_DOWNLOAD_ERROR', `Could not download the agent package: ${sanitizeForDisplay(err.message, 300)}. No archive was installed.`);
     }
 
-    const archiveBytes = fs.readFileSync(archivePath);
-    if (archiveBytes.length !== expectedSize) {
+    if (download.bytes !== expectedSize) {
       try {
         fs.unlinkSync(archivePath);
       } catch {}
       throw new PairingError(
         'INSTALL_MANIFEST_ERROR',
-        `Agent package integrity check failed: size mismatch for ${tarballUrl} (expected ${expectedSize} bytes, got ${archiveBytes.length}). The download was discarded; nothing was installed.`
+        `Agent package integrity check failed: size mismatch for ${sanitizeForDisplay(tarballUrl, 256)} (expected ${expectedSize} bytes, got ${download.bytes}). The download was discarded; nothing was installed.`
       );
     }
-    const actualHash = crypto.createHash('sha256').update(archiveBytes).digest('hex');
+    const actualHash = download.sha256;
     if (actualHash.toLowerCase() !== expectedHash.toLowerCase()) {
       try {
         fs.unlinkSync(archivePath);
       } catch {}
       throw new PairingError(
         'INSTALL_MANIFEST_ERROR',
-        `Agent package integrity check failed: sha256 mismatch for ${tarballUrl}. The download was discarded; nothing was installed.`
+        `Agent package integrity check failed: sha256 mismatch for ${sanitizeForDisplay(tarballUrl, 256)}. The download was discarded; nothing was installed.`
       );
     }
 
@@ -1210,7 +1727,7 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
     try {
       extractTarball(archivePath, tempDir);
     } catch (err) {
-      throw new PairingError('INSTALL_EXTRACT_ERROR', `Could not extract the agent package: ${err.message}`);
+      throw new PairingError('INSTALL_EXTRACT_ERROR', `Could not extract the agent package: ${sanitizeForDisplay(err.message, 300)}`);
     }
 
     console.log('🚀 Running installation script...');
@@ -1223,7 +1740,7 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       invokeInstaller(scriptPath, root);
     } catch (err) {
       if (err instanceof PairingError) throw err;
-      throw new PairingError('INSTALL_FAILED', `Agent installer failed: ${err.message}. Re-running resumes from the stored host credentials.`);
+      throw new PairingError('INSTALL_FAILED', `Agent installer failed: ${sanitizeForDisplay(err.message, 300)}. Re-running resumes from the stored host credentials.`);
     }
   } finally {
     console.log('🧹 Cleaning up temporary directory...');
@@ -1240,9 +1757,10 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
  * the OAuth enrollment step is skipped and the supplied token is redeemed
  * directly. `installMode` is forwarded to the installer via NC_MODE.
  * Host split: enrollment (OAuth/redeem) uses the auth origin (`baseUrl` /
- * `NC_BASE_URL`); device-channel verification (`/api/clients/*`) uses the
- * agent origin (`apiBase` / `NC_API_URL`) for fresh enrollment. Local resume
- * binds verification and installation requests to the stored NC_SERVER_URL.
+ * `NC_BASE_URL`); fresh-enrollment verification, installation and the stored
+ * env bind to the enrollment `server_url` (the agent destination the host
+ * credential will actually use), never to the separate NC_API_URL/baseUrl.
+ * Local resume binds verification and installation to the stored NC_SERVER_URL.
  * @param {{ baseUrl?: string, apiBase?: string, oauthToken?: string|null, enrollment?: { host_id: string, enrollment_token: string, server_url?: string }|null, ncRoot?: string, serverUrl?: string, deviceName?: string, platform?: string, installMode?: 'system'|'user', rootConsent?: boolean|(() => Promise<boolean>), browserBrand?: string, verifyTimeoutMs?: number, verifyIntervalMs?: number, hooks?: { installAgent?: (options: { ncRoot: string, serverUrl: string, release?: Record<string, unknown>|null, hostId?: string, hostToken?: string, rootConsent?: boolean, privateKey?: import('node:crypto').KeyObject }) => Promise<void> } }} options
   */
 export async function pairDeviceAndInstall({
@@ -1274,7 +1792,6 @@ export async function pairDeviceAndInstall({
   }
   const root = ncRoot || getNcRoot();
   const origin = String(baseUrlParam ?? process.env.NC_BASE_URL ?? baseUrl).replace(/\/$/, '');
-  const apiOrigin = String(apiBaseParam ?? process.env.NC_API_URL ?? apiBase).replace(/\/$/, '');
   const defaultServerUrl = serverUrl || process.env.NC_SERVER_URL || 'https://agent.nodecommand.app';
   const envPath = getEnvFilePath(root);
   const keyPath = getDeviceKeyPath(root);
@@ -1389,7 +1906,7 @@ export async function pairDeviceAndInstall({
     }
     if (redemption.release?.version) {
       agentVersion = redemption.release.version;
-      console.log(`📦 Release: ${agentVersion}`);
+      console.log(`📦 Release: ${sanitizeForDisplay(agentVersion, 120)}`);
     }
   }
 
@@ -1403,9 +1920,12 @@ export async function pairDeviceAndInstall({
   await installAgent({ ncRoot: root, serverUrl: enrollServerUrl, release: redemptionRelease, hostId, hostToken, privateKey: keyPair.privateKey, rootConsent: selectedRootConsent });
   writePairState(statePath, { host_id: hostId, phase: 'installed' });
 
-  console.log('🔍 Verifying host registration...');
+  console.log(`🔍 Verifying host registration at ${sanitizeForDisplay(enrollServerUrl, 256)}...`);
+  // Verify against the origin stored in the env file and used by the installer:
+  // NC_API_URL/baseUrl only authenticated enrollment and is not the destination
+  // this host credential was bound to.
   await verifyHostRegistration({
-    apiBase: apiOrigin,
+    apiBase: enrollServerUrl,
     hostId,
     hostToken,
     privateKey: keyPair.privateKey,
@@ -1452,6 +1972,8 @@ function printCliHelp() {
       '  nodecommand                          pair this machine via the browser device flow',
       '  nodecommand <host_id>                install with a dashboard host id (prompts for the token, hidden input)',
       '  nodecommand setup [host_id token]    install the agent (auto system/user mode; no args = browser device flow)',
+      '  nodecommand setup --user             force a per-user install (never requests sudo/UAC)',
+      '  nodecommand --user                   same as `setup --user`',
       '  nodecommand [--allow-root-commands]  explicitly request privileged preparation (default No; independent binding required)',
       '  nodecommand uninstall [--yes]        remove the agent from the canonical root (alias: remove)',
       '  nodecommand remove [--yes]           uninstall the agent (asks for confirmation unless --yes)',
@@ -1559,7 +2081,7 @@ async function main() {
   // form the dashboard and install_command used to emit) to the `setup
   // <host_id> <token>` path instead of silently ignoring the arguments in the
   // device flow.
-  const enrollmentArgs = cliArgs.filter(arg => arg !== '--allow-root-commands');
+  const enrollmentArgs = cliArgs.filter(arg => arg !== '--allow-root-commands' && arg !== '--user');
   if (isBareEnrollmentInvocation(enrollmentArgs)) {
     await runSetup(cliArgs);
     return;
@@ -1612,12 +2134,20 @@ export function suggestedActionFor(code) {
       return 'The update manifest is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, or check network connectivity to the agent release host and re-run; stored credentials are reused.';
     case 'INSTALL_DOWNLOAD_ERROR':
       return 'The agent package endpoint requires the device credential issued at redemption; re-run `nodecommand setup <host_id> <token>` to redeem a fresh enrollment, then re-run; stored credentials are reused.';
+    case 'INSTALL_DOWNLOAD_TIMEOUT':
+      return 'The agent package download did not finish within the configured timeout. Check network speed/connectivity or raise NC_CLI_DOWNLOAD_TIMEOUT_MS (30000-3600000), then re-run; stored credentials are reused.';
+    case 'INSECURE_SERVER_URL':
+      return 'Use an https:// server URL. Set NC_ALLOW_INSECURE_HTTP=1 only for an isolated local test.';
     case 'INSTALL_FAILED':
     case 'INSTALL_EXTRACT_ERROR':
     case 'INSTALL_INTEGRITY_ERROR':
       return 'The agent install did not complete; check network connectivity to the agent release host and re-run; stored credentials are reused.';
     case 'VERIFY_TIMEOUT':
       return 'Check connectivity to the server and re-run to verify; credentials are already stored.';
+    case 'SETUP_IN_PROGRESS':
+      return 'Another setup, install or uninstall owns this installation root. Wait for it to finish (or remove a stale lock after confirming no setup is running) and re-run.';
+    case 'HELPER_BINDING_FAILED':
+      return 'Verify NC_ROOT, the protected management response and the signed challenge file, then re-run the binding maintenance; no binding state was changed.';
     default:
       return 'Re-run the command; use `nodecommand --help` for usage.';
   }
@@ -1669,11 +2199,11 @@ function getCliVersion() {
  * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null, rootConsent?: boolean, ncRoot?: string, executionInitialization?: any }} options
  */
 export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null }) {
-  console.log(`\n✅ Setup complete for host ${hostId}${resumed ? ' (resumed)' : ''}.`);
+  console.log(`\n✅ Setup complete for host ${sanitizeForDisplay(hostId, 128)}${resumed ? ' (resumed)' : ''}.`);
   if (installMode) console.log(`installed as ${installMode}`);
-  if (version) console.log(`agent version: ${version}`);
+  if (version) console.log(`agent version: ${sanitizeForDisplay(version, 120)}`);
   console.log(`cli version: ${getCliVersion()}`);
-  console.log(`server: ${serverUrl}`);
+  console.log(`server: ${sanitizeForDisplay(serverUrl, 256)}`);
   console.log('status: agent credentials verified online');
   if (ncRoot) console.log(`installation root: ${ncRoot}`);
   console.log('OS execution identity: not verified by this credential check; native service/readiness verification required');
@@ -1715,13 +2245,6 @@ export function printSetupSuccess({ hostId, serverUrl, installMode = undefined,
   }
 }
 
-/**
- * Guidance printed when Windows UAC elevation for a system-wide install is
- * unavailable (headless shell) or was declined by the operator.
- */
-const WINDOWS_ELEVATION_INSTALL_DECLINED =
-  'Elevation unavailable or declined. Please run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.';
-
 /**
  * Guidance printed when Windows UAC elevation for uninstallation is
  * unavailable (headless shell) or was declined by the operator.
@@ -1735,15 +2258,15 @@ const WINDOWS_ELEVATION_UNINSTALL_DECLINED =
  * console is visible) and returns the spawnSync result. Never throws: a
  * missing powershell or a declined prompt resolves to null/non-zero.
  */
-function requestWindowsElevation(browserBrand = undefined) {
-  const originalArgs = [...process.argv.slice(1)];
+function requestWindowsElevation(browserBrand = undefined, elevatedArgs = undefined) {
+  const originalArgs = elevatedArgs ? [...elevatedArgs] : [...process.argv.slice(1)];
   const args = browserBrand === undefined ? originalArgs : browserBrandReexecArgs(originalArgs, browserBrand);
   const literal = value => "'" + value.replace(/'/g, "''") + "'";
   const quote = value => '"' + String(value).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1') + '"';
   const script = `$p=Start-Process -FilePath ${literal(process.execPath)} -ArgumentList ${literal(args.map(quote).join(' '))} -Verb RunAs -Wait -PassThru; exit $p.ExitCode`;
   try {
     return child_process.spawnSync(
-      'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe',
+      windowsExecutablePath('powershell'),
       [
         '-NoProfile',
         '-NonInteractive',
@@ -1780,7 +2303,23 @@ function requestWindowsElevation(browserBrand = undefined) {
  * @param {{ allowHostIdOnly?: boolean, promptToken?: (io: { input: import('node:stream').Readable, output: import('node:stream').Writable }) => Promise<string> }} [options]
  */
 export async function runSetup(args = [], { allowHostIdOnly = false, promptToken = promptEnrollmentToken } = {}) {
+  // Elevated legacy enrollments receive the single-use token from an
+  // owner-only temp file, never through sudo/UAC argv.
+  let elevatedToken;
+  const tokenFileFlagIndex = args.indexOf('--enrollment-token-file');
+  if (tokenFileFlagIndex >= 0) {
+    const tokenFile = args[tokenFileFlagIndex + 1];
+    if (typeof tokenFile !== 'string' || tokenFile.startsWith('-')) {
+      reportSetupError(new PairingError('INVALID_ENROLL_TOKEN', 'The elevated enrollment token file argument is missing.'));
+      process.exit(1);
+      return;
+    }
+    elevatedToken = readEnrollmentTokenFile(tokenFile);
+    args = args.filter((_, index) => index !== tokenFileFlagIndex && index !== tokenFileFlagIndex + 1);
+  }
   const positionals = args.filter((a) => !a.startsWith('-'));
+  if (elevatedToken !== undefined) positionals.push(elevatedToken);
+  const positionalTokenInArgv = elevatedToken === undefined && positionals.length === 2;
   if (positionals.includes('help') || args.includes('--help') || args.includes('-h')) {
     console.log(
       [
@@ -1795,6 +2334,7 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
         'macOS: fresh non-root installs use the per-user LaunchAgent without sudo;',
         'explicit root uses system mode. Existing roots/modes are preserved or setup stops.',
         'Windows/Linux retain their existing automatic system/user elevation behavior.',
+        'Use the per-user switch documented by `nodecommand --help` to force a per-user install without sudo/UAC.',
         'Service installation authorization does not allow root commands through chat.',
         'New setup asks: Allow root/administrator commands through Node Command? [y/N]',
         'Noninteractive setup defaults to No; --allow-root-commands explicitly requests preparation.',
@@ -1803,19 +2343,40 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     );
     return;
   }
-  assertKnownFlags(args, ['--help', '-h', '--allow-root-commands', '--maintain-identity', '--configure-helper-binding', '--activate-initial-binding'], 'setup');
+  assertKnownFlags(args, ['--help', '-h', '--allow-root-commands', '--user', '--maintain-identity', '--configure-helper-binding', '--activate-initial-binding'], 'setup');
+  // Explicit per-user mode: never elevate, and never degrade silently into a
+  // competing user install beside a system tree the caller cannot inspect.
+  const forceUser = args.includes('--user');
+  if (forceUser && (args.includes('--maintain-identity') || args.includes('--configure-helper-binding'))) {
+    throw new PairingError('INVALID_SETUP_ARGS', '--user selects a per-user installation and cannot be combined with selected-installation maintenance.');
+  }
   if (args.includes('--configure-helper-binding')) {
     if (positionals.length !== 3 || !process.env.NC_ROOT || args.includes('--allow-root-commands') || args.includes('--maintain-identity'))
       throw new PairingError('INVALID_SETUP_ARGS', 'Selected helper binding maintenance needs NC_ROOT, existing host ID, protected management response and signed challenge.');
-    const producer = await loadProtectedHelperProducer(process.env.NC_ROOT);
-    const files = producer.protectedHelperPaths(process.env.NC_ROOT);
-    const selected = JSON.parse(fs.readFileSync(files.configFile, 'utf8'));
-    assertMatchingHostIdentity({ NC_CLIENT_ID: selected.client_id }, positionals[0]);
-    const result = await producer.configureProtectedHelperBinding({ root: process.env.NC_ROOT, bindingFile: path.resolve(positionals[1]),
-      challengeFile: path.resolve(positionals[2]), activateLocally: args.includes('--activate-initial-binding') });
-    console.log(JSON.stringify(result));
-    console.log('Local binding preparation is not execution readiness. The control plane must consume fresh proof, then complete signed sync and helper ACK.');
-    return;
+    try {
+      const producer = await loadProtectedHelperProducer(process.env.NC_ROOT);
+      const files = producer.protectedHelperPaths(process.env.NC_ROOT);
+      const selected = JSON.parse(fs.readFileSync(files.configFile, 'utf8'));
+      assertMatchingHostIdentity({ NC_CLIENT_ID: selected.client_id }, positionals[0]);
+      const result = await producer.configureProtectedHelperBinding({ root: process.env.NC_ROOT, bindingFile: path.resolve(positionals[1]),
+        challengeFile: path.resolve(positionals[2]), activateLocally: args.includes('--activate-initial-binding') });
+      console.log(JSON.stringify(result));
+      console.log('Local binding preparation is not execution readiness. The control plane must consume fresh proof, then complete signed sync and helper ACK.');
+      return;
+    } catch (err) {
+      // Never surface a raw stack (or JSON.parse input snippets) from helper
+      // binding maintenance; callers get the stable setup error shape.
+      if (err instanceof PairingError) {
+        reportSetupError(err);
+      } else {
+        const detail = err instanceof SyntaxError
+          ? 'the selected protected configuration is not valid JSON'
+          : err instanceof Error ? err.message : String(err);
+        reportSetupError(new PairingError('HELPER_BINDING_FAILED', `Protected helper binding maintenance failed: ${detail}. Existing binding state is unchanged.`));
+      }
+      process.exit(1);
+      return;
+    }
   }
   if (args.includes('--activate-initial-binding')) throw new PairingError('INVALID_SETUP_ARGS', 'Initial binding activation requires explicit --configure-helper-binding maintenance.');
   if (args.includes('--maintain-identity')) {
@@ -1848,72 +2409,152 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
     console.error('suggested_action: Re-run as `nodecommand setup` or `nodecommand setup <host_id> <token>`.');
     process.exit(1);
   }
+  if (positionalTokenInArgv) {
+    console.warn('warning: [ENROLL_TOKEN_IN_ARGV] The positional enrollment token is visible in shell history and process listings. Re-run without the token to use the masked prompt; continuing with the supplied token.');
+  }
   const browserBrand = captureBrowserDefaultBrand();
-  let installMode = decideInstallMode();
+  let installMode = forceUser ? 'user' : decideInstallMode();
   let ncRoot;
   let existingTarget;
   let existingEnv;
   let existingKey;
   let rootManagedPair;
   let protectedKeyContext;
-  {
+  let needsUserAppRepair = false;
+  // A non-root caller cannot stat a root-owned 0750 system tree. Escalate
+  // before setupTarget's fail-closed inspection so the elevated child inspects
+  // the real installation; an unreadable root must never look like "absent".
+  const unreadableSystemRoot = os.platform() === 'linux' && installMode === 'user' && !process.env.NC_ELEVATED
+    ? unreadableSystemInstallations()[0]
+    : undefined;
+  // config + device key alone are not a working agent: an empty/missing
+  // launcher is repaired for a per-user tree from stored credentials, and
+  // otherwise fails closed instead of being reported as an online
+  // installation. Stored credentials are preserved for repair.
+  const verifyExistingTarget = (root, { clientId = null, protectedContext = null, repairUserApplication = false } = {}) => {
+    const localEnv = loadValidHostEnv(getEnvFilePath(root));
+    if (!localEnv) throw new Error(`Existing host configuration at ${root} is incomplete; refusing a new enrollment or credential overwrite.`);
+    if (clientId && localEnv.NC_CLIENT_ID !== clientId) throw new Error('Existing ordinary host identity conflicts with the protected helper selection; explicit Root maintenance is required.');
+    assertMatchingHostIdentity(localEnv, positionals[0]);
+    // Missing/unreadable/invalid keys are not permission to regenerate an
+    // existing device identity. The normal verified resume flow is kept.
+    const keyPath = getDeviceKeyPath(root);
+    if (!protectedContext) {
+      const keyInfo = fs.lstatSync(keyPath);
+      if (!keyInfo.isFile() || keyInfo.isSymbolicLink() || keyInfo.size > 65536 ||
+          (os.platform() !== 'win32' && installMode === 'user' && keyInfo.uid !== process.getuid())) {
+        throw new Error(`Existing device key at ${root} has an unverifiable type/owner; refusing identity replacement.`);
+      }
+    }
     try {
+      existingKey = protectedContext ? loadRootManagedPairKey(root, protectedContext.ordinaryUid) : loadDeviceKeyPair(keyPath);
+    } catch {
+      throw new Error(`Existing device key at ${root} cannot be verified; preserve it for selected-installation maintenance.`);
+    }
+    existingEnv = localEnv;
+    const appInfo = fs.lstatSync(path.join(root, 'app'));
+    if (!appInfo.isDirectory() || appInfo.isSymbolicLink()) throw new Error(`Existing application at ${root} is incomplete; use selected-installation maintenance.`);
+    const launcherPath = path.join(root, 'app', 'launcher.mjs');
+    let launcherInfo;
+    try {
+      launcherInfo = fs.lstatSync(launcherPath);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw new Error(`Existing application at ${root} cannot be verified; use selected-installation maintenance.`, { cause: err });
+    }
+    if (!launcherInfo || !launcherInfo.isFile() || launcherInfo.isSymbolicLink() || launcherInfo.size === 0) {
+      // A partial per-user tree is repairable in place from the stored host
+      // identity; protected/system roots stay fail-closed for maintenance.
+      if (repairUserApplication && canRepairUserApplication({ mode: installMode, protectedContext })) {
+        needsUserAppRepair = true;
+        return;
+      }
+      throw new Error(`Existing application at ${root} is incomplete: app/launcher.mjs is missing or empty. Repair or reinstall the application from the existing root (config/nc-client.env and config/nc-device-key.pem are preserved); no new enrollment was attempted.`);
+    }
+  };
+  try {
+    if (!unreadableSystemRoot) {
       const target = setupTarget({ mode: installMode });
       ({ mode: installMode, ncRoot } = target);
       existingTarget = target.existing;
       rootManagedPair = target.rootManagedPair;
       protectedKeyContext = (process.getuid?.() === 0 || process.geteuid?.() === 0) ? target.protectedInstallation : null;
-      if (target.existing) {
-        const localEnv = loadValidHostEnv(getEnvFilePath(ncRoot));
-        if (!localEnv) throw new Error(`Existing host configuration at ${ncRoot} is incomplete; refusing a new enrollment or credential overwrite.`);
-        if (target.clientId && localEnv.NC_CLIENT_ID !== target.clientId) throw new Error('Existing ordinary host identity conflicts with the protected helper selection; explicit Root maintenance is required.');
-        assertMatchingHostIdentity(localEnv, positionals[0]);
-        // Missing/unreadable/invalid keys are not permission to regenerate an
-        // existing device identity. The normal verified resume flow is kept.
-        const keyPath = getDeviceKeyPath(ncRoot);
-        if (!protectedKeyContext) {
-          const keyInfo = fs.lstatSync(keyPath);
-          if (!keyInfo.isFile() || keyInfo.isSymbolicLink() || keyInfo.size > 65536 ||
-              (os.platform() !== 'win32' && installMode === 'user' && keyInfo.uid !== process.getuid())) {
-            throw new Error(`Existing device key at ${ncRoot} has an unverifiable type/owner; refusing identity replacement.`);
-          }
-        }
-        try {
-          existingKey = protectedKeyContext ? loadRootManagedPairKey(ncRoot, protectedKeyContext.ordinaryUid) : loadDeviceKeyPair(keyPath);
-        } catch {
-          throw new Error(`Existing device key at ${ncRoot} cannot be verified; preserve it for selected-installation maintenance.`);
-        }
-        existingEnv = localEnv;
-        const appInfo = fs.lstatSync(path.join(ncRoot, 'app'));
-        if (!appInfo.isDirectory() || appInfo.isSymbolicLink()) throw new Error(`Existing application at ${ncRoot} is incomplete; use selected-installation maintenance.`);
-      }
-    } catch (err) {
-      if (err instanceof PairingError && err.code === 'HOST_ID_MISMATCH') {
-        reportSetupError(err);
-      } else {
-        console.error(`error: [INSTALL_FAILED] ${err instanceof Error ? err.message : 'Cannot verify installation state.'}`);
-        console.error('suggested_action: Preserve the existing mode/root; resolve conflicting state through its existing maintenance flow, with explicit administrator rights for system installs.');
+      if (target.existing) verifyExistingTarget(ncRoot, { clientId: target.clientId, protectedContext: protectedKeyContext, repairUserApplication: installMode === 'user' && !target.rootManagedPair });
+    } else {
+      // A valid per-user installation is still usable beside an unreadable
+      // system tree: verify it as this user instead of demanding elevation.
+      const userRoot = path.resolve(getNcRootForMode('user'));
+      if (probeInstallRoot(userRoot) === 'install') {
+        verifyExistingTarget(userRoot);
+        installMode = 'user';
+        ncRoot = userRoot;
+        existingTarget = { existing: true, ncRoot: userRoot, mode: 'user' };
       }
-      process.exit(1);
-      return;
     }
+  } catch (err) {
+    if (err instanceof PairingError && err.code === 'HOST_ID_MISMATCH') {
+      reportSetupError(err);
+    } else {
+      console.error(`error: [INSTALL_FAILED] ${err instanceof Error ? err.message : 'Cannot verify installation state.'}`);
+      console.error('suggested_action: Preserve the existing mode/root; resolve conflicting state through its existing maintenance flow, with explicit administrator rights for system installs.');
+    }
+    process.exit(1);
+    return;
   }
   if (existingTarget) {
-    // An installed tree is verification-only here. In particular, a legacy
-    // tree without pairing-state metadata must not rerun OS installers that
-    // can replace shared services/helpers. Repair is selected maintenance.
-    console.log(`Verifying existing ${rootManagedPair ? 'Root-managed paired' : installMode} installation at ${ncRoot}, host: ${existingEnv.NC_CLIENT_ID}.`);
-    if (rootManagedPair) console.log(`Local management: Root; ordinary service scope: ${rootManagedPair.serviceScope}; selected UID: ${rootManagedPair.ordinaryUid} (credential verification only; no user impersonation).`);
+    // An installed tree is verification-only here, except that a partial
+    // per-user application is repaired from its stored host identity. In
+    // particular, a legacy tree without pairing-state metadata must not rerun
+    // OS installers that can replace shared services/helpers; system/protected
+    // repairs remain selected maintenance. The lock keeps a concurrent
+    // uninstall from removing the tree while this verification reads its
+    // credentials and keys.
+    let lock;
     try {
-      await verifyHostRegistration({ apiBase: existingEnv.NC_SERVER_URL, hostId: existingEnv.NC_CLIENT_ID, hostToken: existingEnv.NC_CLIENT_TOKEN, privateKey: existingKey.privateKey });
-      printSetupSuccess({ hostId: existingEnv.NC_CLIENT_ID, serverUrl: existingEnv.NC_SERVER_URL, installMode: rootManagedPair ? undefined : installMode, ncRoot, resumed: true });
-      if (args.includes('--allow-root-commands')) console.warn('Existing root consent unchanged. Enabling root requires explicit selected-installation privileged maintenance and independent management approval.');
+      lock = acquireInstallLock(ncRoot);
     } catch (err) {
-      const code = err instanceof PairingError ? err.code : 'INSTALL_FAILED';
-      const detail = code === 'VERIFY_FAILED' ? 'The existing host is not registered on the server; stored identity is unchanged.' : err.message;
-      console.error(`error: [${code}] ${detail}`);
-      console.error(`suggested_action: Preserve host/device credentials at ${ncRoot}; use this installation's maintenance flow to repair registration or connectivity. No new enrollment was requested.`);
+      reportSetupError(err);
       process.exit(1);
+      return;
+    }
+    try {
+      if (needsUserAppRepair) {
+        // Repair only the application payload from the stored host identity:
+        // no OAuth, no enrollment token and no new device key are involved.
+        console.log(`Repairing the existing user application at ${ncRoot} from stored host credentials (no new enrollment).`);
+        try {
+          await downloadAndInstallAgent({
+            ncRoot,
+            serverUrl: existingEnv.NC_SERVER_URL,
+            installMode: 'user',
+            rootConsent: false,
+            hostId: existingEnv.NC_CLIENT_ID,
+            hostToken: existingEnv.NC_CLIENT_TOKEN,
+            privateKey: existingKey.privateKey
+          });
+        } catch (err) {
+          const detail = err instanceof Error ? err.message : String(err);
+          console.error(`error: [INSTALL_FAILED] Repair of the existing user installation at ${ncRoot} failed: ${detail}`);
+          console.error(`suggested_action: Stored host/device credentials were preserved at ${ncRoot}; resolve the reported download/install problem and re-run setup. No new enrollment was requested.`);
+          process.exit(1);
+          return;
+        }
+      }
+      console.log(`Verifying existing ${rootManagedPair ? 'Root-managed paired' : installMode} installation at ${ncRoot}, host: ${existingEnv.NC_CLIENT_ID}.`);
+      if (rootManagedPair) console.log(`Local management: Root; ordinary service scope: ${rootManagedPair.serviceScope}; selected UID: ${rootManagedPair.ordinaryUid} (credential verification only; no user impersonation).`);
+      try {
+        await verifyHostRegistration({ apiBase: existingEnv.NC_SERVER_URL, hostId: existingEnv.NC_CLIENT_ID, hostToken: existingEnv.NC_CLIENT_TOKEN, privateKey: existingKey.privateKey });
+        printSetupSuccess({ hostId: existingEnv.NC_CLIENT_ID, serverUrl: existingEnv.NC_SERVER_URL, installMode: rootManagedPair ? undefined : installMode, ncRoot, resumed: true });
+        if (needsUserAppRepair) console.log('repair: application reinstalled from stored host credentials; host identity preserved.');
+        if (args.includes('--allow-root-commands')) console.warn('Existing root consent unchanged. Enabling root requires explicit selected-installation privileged maintenance and independent management approval.');
+      } catch (err) {
+        const code = err instanceof PairingError ? err.code : 'INSTALL_FAILED';
+        const detail = code === 'VERIFY_FAILED' ? 'The existing host is not registered on the server; stored identity is unchanged.' : err.message;
+        console.error(`error: [${code}] ${detail}`);
+        console.error(`suggested_action: Preserve host/device credentials at ${ncRoot}; use this installation's maintenance flow to repair registration or connectivity. No new enrollment was requested.`);
+        process.exit(1);
+      }
+    } finally {
+      lock.release();
     }
     return;
   }
@@ -1921,81 +2562,142 @@ export async function runSetup(args = [], { allowHostIdOnly = false, promptToken
   // elevation. Linux requests sudo; Windows requests UAC (Start-Process
   // -Verb RunAs) so the install lands machine-wide at the canonical system
   // root. A refused or unavailable Windows elevation is a hard stop: the CLI
-  // never silently degrades a system install into %LOCALAPPDATA%.
-  if (os.platform() !== 'darwin' && installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
-    if (os.platform() === 'win32') {
-      if (process.stdin.isTTY) {
-        console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
-        const elevated = requestWindowsElevation(browserBrand);
-        if (elevated && elevated.status === 0) process.exit(0);
+  // never silently degrades a system install into %LOCALAPPDATA%. An
+  // unreadable canonical system installation also forces this branch: without
+  // elevation it is unknowable and must not become a per-user competitor.
+  if (unreadableSystemRoot && (forceUser || !canElevate())) {
+    console.error(`error: [INSTALL_FAILED] An existing system installation at ${unreadableSystemRoot} cannot be inspected without administrator rights.`);
+    console.error(forceUser
+      ? 'suggested_action: --user cannot create a per-user installation beside it; re-run without --user with Administrator/root rights so the existing installation can be inspected. No per-user installation was created.'
+      : 'suggested_action: Re-run this setup with Administrator/root rights so the existing installation can be inspected; no per-user installation was created beside it.');
+    process.exit(1);
+    return;
+  }
+  if (!forceUser && os.platform() !== 'darwin' && installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
+    // A legacy positional token must never enter sudo/UAC argv: it travels in
+    // a 0600 owner-only temp file whose path alone is re-executed.
+    const tokenFile = positionals.length === 2 ? createEnrollmentTokenFile(positionals[1]) : null;
+    const elevatedArgs = tokenFile
+      ? buildElevatedSetupArgs(process.argv.slice(1), args, args.lastIndexOf(positionals[1]), tokenFile.filePath)
+      : undefined;
+    try {
+      if (os.platform() === 'win32') {
+        if (process.stdin.isTTY) {
+          console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
+          const elevated = requestWindowsElevation(browserBrand, elevatedArgs);
+          if (elevated && elevated.status === 0) {
+            tokenFile?.cleanup();
+            process.exit(0);
+          }
+        }
+        console.error('error: [INSTALL_FAILED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+        console.error('suggested_action: Re-run `nodecommand setup --user` for a per-user installation, or run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.');
+        process.exit(1);
+      }
+      console.log('Admin rights required for a system-wide install. Requesting sudo…');
+      // Preserve only the single signal the elevated re-exec depends on; sudo
+      // resets the rest of the environment instead of forwarding it wholesale.
+      // The caller's PATH is never forwarded into the privileged re-exec.
+      const elevationEnv = {
+        PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+        NC_ELEVATED: '1'
+      };
+      if (process.env.TERM) elevationEnv.TERM = process.env.TERM;
+      let sudo;
+      try {
+        sudo = resolveExecutable('sudo');
+      } catch (err) {
+        console.error(`error: [INSTALL_FAILED] ${err.message}`);
+        console.error('suggested_action: Install an absolute sudo binary or run the system installer explicitly with administrator rights; no per-user fallback was attempted for an unsafe elevation path.');
+        process.exit(1);
+      }
+      const elevated = child_process.spawnSync(
+        sudo,
+        ['--preserve-env=NC_ELEVATED', process.execPath, ...(elevatedArgs ?? process.argv.slice(1))],
+        { stdio: 'inherit', env: elevationEnv }
+      );
+      if (elevated && elevated.status === 0) {
+        tokenFile?.cleanup();
+        process.exit(0);
       }
-      console.error(WINDOWS_ELEVATION_INSTALL_DECLINED);
+    } finally {
+      tokenFile?.cleanup();
+    }
+    if (unreadableSystemRoot) {
+      console.error(`error: [INSTALL_FAILED] The elevated setup did not inspect or repair the existing system installation at ${unreadableSystemRoot}.`);
+      console.error('suggested_action: Preserve the existing system tree and re-run the system installer with explicit administrator rights; no per-user installation was attempted.');
       process.exit(1);
     }
-    console.log('Admin rights required for a system-wide install. Requesting sudo…');
-    const elevated = child_process.spawnSync(
-      'sudo',
-      ['-E', process.execPath, ...process.argv.slice(1)],
-      { stdio: 'inherit', env: { ...process.env, NC_ELEVATED: '1' } }
-    );
-    if (elevated && elevated.status === 0) process.exit(0);
     try {
       // A failed elevated child may already have created an installation.
-      // Recheck before falling back rather than creating a competing agent.
+      // Recheck before reporting the failure rather than creating a competing
+      // agent; a partially completed system install must be preserved.
       const target = setupTarget({ mode: installMode });
       if (target.existing) throw new Error(`An installation now exists at ${target.ncRoot}; preserve it through its maintenance flow.`);
-      ncRoot = target.ncRoot;
     } catch (err) {
       console.error(`error: [INSTALL_FAILED] ${err.message}`);
       console.error('suggested_action: Preserve existing roots and select their maintenance flow; declining elevation does not authorize a second installation.');
       process.exit(1);
       return;
     }
-    console.warn('Elevation unavailable or declined; continuing with a per-user install.');
+    // No silent fallback after an attempted elevation: a per-user install here
+    // would compete with the expected system install and could prompt for a
+    // second enrollment token in the same run. Fail closed instead.
+    console.error('error: [INSTALL_FAILED] Elevation was unavailable or declined; no system-wide installation was performed and no per-user fallback was attempted.');
+    console.error('suggested_action: Re-run `nodecommand setup --user` for a per-user installation, or provide administrator/root rights for a machine-wide installation.');
+    process.exit(1);
+    return;
   }
   // Mode-aware root: on win32 a system install lives in %ProgramData%\NC,
   // not the %LOCALAPPDATA% tree getNcRoot() returns, so credentials must be
   // written where the system installer will actually read them.
   ncRoot = ncRoot || getNcRootForMode(installMode);
-  console.log(installMode === 'system' ? `Installing as system (machine-wide), root: ${ncRoot}.` : `Installing as user (per-user), root: ${ncRoot}.`);
-  const warning = modeWarningFor(installMode);
-  if (warning) console.warn(warning);
-
-  // Canonical token-free form: prompt AFTER elevation so the token is typed
-  // on the elevated terminal and never enters argv (a sudo/UAC re-exec
-  // forwards only the host id). Masked input: the token is not echoed.
-  if (onePositionalOk) {
-    try {
-      assertMatchingHostIdentity(loadValidHostEnv(getEnvFilePath(ncRoot)), positionals[0]);
-      const enrollmentToken = await promptToken({ input: process.stdin, output: process.stderr });
-      positionals.push(String(enrollmentToken || ''));
-    } catch (err) {
-      reportSetupError(err);
-      process.exit(1);
+  // Serialize credential/key writes and the installer against any concurrent
+  // setup or uninstall for this root.
+  const lock = acquireInstallLock(ncRoot);
+  try {
+    console.log(installMode === 'system' ? `Installing as system (machine-wide), root: ${ncRoot}.` : `Installing as user (per-user), root: ${ncRoot}.`);
+    const warning = modeWarningFor(installMode);
+    if (warning) console.warn(warning);
+
+    // Canonical token-free form: prompt AFTER elevation so the token is typed
+    // on the elevated terminal and never enters argv (a sudo/UAC re-exec
+    // forwards only the host id). Masked input: the token is not echoed.
+    if (onePositionalOk) {
+      try {
+        assertMatchingHostIdentity(loadValidHostEnv(getEnvFilePath(ncRoot)), positionals[0]);
+        const enrollmentToken = await promptToken({ input: process.stdin, output: process.stderr });
+        positionals.push(String(enrollmentToken || ''));
+      } catch (err) {
+        reportSetupError(err);
+        process.exit(1);
+      }
     }
-  }
 
-  const rootConsent = () => promptRootCommandConsent({ explicitOptIn: args.includes('--allow-root-commands') });
-  if (positionals.length === 2) {
-    const [hostId, enrollmentToken] = positionals;
-    try {
-      const result = await pairDeviceAndInstall({
-        baseUrl,
-        apiBase,
-        enrollment: { host_id: hostId, enrollment_token: enrollmentToken },
-        browserBrand,
-        installMode,
-        rootConsent,
-        ncRoot
-      });
-      printSetupSuccess({ ...result, installMode, ncRoot });
-    } catch (err) {
-      reportSetupError(err);
-      process.exit(1);
+    const rootConsent = () => promptRootCommandConsent({ explicitOptIn: args.includes('--allow-root-commands') });
+    if (positionals.length === 2) {
+      const [hostId, enrollmentToken] = positionals;
+      try {
+        const result = await pairDeviceAndInstall({
+          baseUrl,
+          apiBase,
+          enrollment: { host_id: hostId, enrollment_token: enrollmentToken },
+          browserBrand,
+          installMode,
+          rootConsent,
+          ncRoot
+        });
+        printSetupSuccess({ ...result, installMode, ncRoot });
+      } catch (err) {
+        reportSetupError(err);
+        process.exit(1);
+      }
+      return;
     }
-    return;
+    await runDeviceFlow({ installMode, ncRoot, browserBrand, rootConsent });
+  } finally {
+    lock.release();
   }
-  await runDeviceFlow({ installMode, ncRoot, browserBrand, rootConsent });
 }
 
 export const ROOT_COMMAND_CONSENT_PROMPT = 'Allow root/administrator commands through Node Command? [y/N]';
@@ -2036,6 +2738,9 @@ export function promptEnrollmentToken({ input = process.stdin, output = process.
       );
       return;
     }
+    // Non-secret guidance: the operator must know paste/Enter are honored even
+    // though no character is echoed. The token itself is never rendered.
+    output.write('Paste the enrollment token from the dashboard. Input is hidden (nothing is echoed); press Enter to submit.\n');
     output.write(ENROLLMENT_TOKEN_PROMPT);
     const sink = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
     sink.isTTY = true;
@@ -2060,16 +2765,19 @@ export function promptEnrollmentToken({ input = process.stdin, output = process.
       close();
       reject(new PairingError('ENROLL_TOKEN_REQUIRED', message));
     };
-    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled.'));
+    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled; nothing was submitted.'));
     rl.on('close', () => {
-      if (!settled) abort('No enrollment token was entered (terminal closed). Re-run in a terminal and paste the token from the dashboard.');
+      if (!settled) abort('No enrollment token was entered (terminal closed); nothing was submitted. Re-run in a terminal and paste the token from the dashboard.');
     });
     rl.question('', (answer) => {
       const token = String(answer ?? '').trim();
       if (!token) {
-        abort('No enrollment token was entered. Re-run in a terminal and paste the token shown in the dashboard.');
+        abort('No enrollment token was entered; nothing was submitted. Re-run in a terminal and paste the token shown in the dashboard.');
         return;
       }
+      // Length-only acknowledgement: confirms the paste/Enter pair was received
+      // without revealing any token byte.
+      output.write(`Enrollment token received (${token.length} characters). Validating...\n`);
       finish(token);
     });
   });
@@ -2125,7 +2833,7 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], command);
   const stray = args.filter((a) => !a.startsWith('-') && a !== 'help');
   if (stray.length > 0) {
-    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got: ${stray.join(', ')}).`);
+    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got ${stray.length}).`);
     console.error(`suggested_action: Run \`nodecommand ${command} --yes\` (or plain \`nodecommand ${command}\` to be asked).`);
     process.exit(1);
   }
@@ -2167,7 +2875,7 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
   }
   if (unreadable.length > 0) {
     console.log(
-      `Elevated removal needed for system install(s): ${unreadable.join(', ')} (not readable as the current user).`
+      `Explicit root maintenance required for system install(s): ${unreadable.join(', ')} (not readable as the current user).`
     );
   }
   if (!yes) {
@@ -2192,6 +2900,14 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
       failed += 1;
       continue;
     }
+    let lock;
+    try {
+      lock = acquireInstallLock(root);
+    } catch (err) {
+      reportSetupError(err);
+      failed += 1;
+      continue;
+    }
     try {
       runUninstallerScript(script);
       console.log(`Removed ${root}${pair && pair.helperRoot !== root ? ` and paired protected helper ${pair.helperRoot}` : ''} (exit 0).`);
@@ -2204,20 +2920,17 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
         return;
       }
       failed += 1;
+    } finally {
+      lock.release();
     }
   }
-  // Unreadable system roots remain visible, but never trigger implicit sudo.
+  // Unreadable system roots remain visible, but are never executed: an
+  // ordinary caller cannot verify the tree, so removal is explicit root
+  // maintenance. This deliberately adds no implicit sudo.
   for (const root of unreadable) {
-    const script = uninstallerForRoot(root);
-    try {
-      runUninstallerScript(script);
-      console.log(`Removed ${root} (exit 0).`);
-    } catch (err) {
-      const rc = typeof err?.status === 'number' ? err.status : 1;
-      console.error(`error: [UNINSTALL_FAILED] uninstaller for ${root} exited with status ${rc}: ${err.message}`);
-      console.error(uninstallFailureSuggestion());
-      failed += 1;
-    }
+    console.error(`error: [TRUSTED_ROOT_MAINTENANCE_REQUIRED] The system installation at ${root} is not readable by the current user; it was not modified.`);
+    console.error('suggested_action: Run `sudo npx --yes node-command@latest uninstall --yes` to remove this trusted root installation explicitly.');
+    failed += 1;
   }
   if (failed > 0) process.exit(1);
   console.log(completionMessage);
@@ -2265,6 +2978,7 @@ export async function runUninstall(args = []) {
  * @param {{ installMode?: 'system'|'user', ncRoot?: string, browserBrand?: string, rootConsent?: boolean|(() => Promise<boolean>) }} [options]
  */
 async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, browserBrand = captureBrowserDefaultBrand(), rootConsent = false } = {}) {
+  assertCredentialOrigin(baseUrl, { label: 'NC_BASE_URL' });
   const deviceEndpoint = `${baseUrl}/oauth/device/code`;
   let initRes;
 
@@ -2281,17 +2995,20 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, brow
   try {
     initRes = await postJson(deviceEndpoint, {
       client_id: clientId,
+      // B4: scope is an explicit client request, never a server default.
+      // nc-cli enrollment/install needs the write/admin surface.
+      scope: 'mcp:all',
       code_challenge: deviceCodeChallenge,
       code_challenge_method: 'S256'
     });
   } catch (err) {
-    console.error(`error: [DEVICE_FLOW_CONNECT] Could not connect to ${deviceEndpoint}: ${err.message}`);
+    console.error(`error: [DEVICE_FLOW_CONNECT] Could not connect to ${sanitizeForDisplay(deviceEndpoint, 256)}: ${sanitizeForDisplay(err.message, 300)}`);
     console.error('suggested_action: Check network access to the control plane (or NC_BASE_URL), then re-run.');
     process.exit(1);
   }
 
   if (initRes.status !== 200 || !initRes.data || !initRes.data.device_code) {
-    const err = initRes.data?.error_description || initRes.data?.error || `HTTP ${initRes.status}`;
+    const err = sanitizeForDisplay(initRes.data?.error_description || initRes.data?.error || `HTTP ${initRes.status}`, 300);
     console.error(`error: [DEVICE_FLOW_START] Failed to start device flow: ${err}`);
     console.error('suggested_action: Re-run the command; if it persists, verify the control plane is reachable and NC_BASE_URL is correct.');
     process.exit(1);
@@ -2319,7 +3036,8 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, brow
   // has a manual 8-character code input; the deep-link form is useless here
   // because the login redirect strips the query (return_to=/device only), so
   // the code would never auto-fill after sign-in anyway.
-  const verifyUrl = verification_uri || `${baseUrl}/device`;
+  const verifyUrl = sanitizeForDisplay(verification_uri || `${baseUrl}/device`, 512);
+  const displayUserCode = sanitizeForDisplay(user_code, 64);
 
   printBox([
     { text: `${bold}Node Command — Device Authorization${reset}`, rawLength: 'Node Command — Device Authorization'.length },
@@ -2327,7 +3045,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, brow
     { text: 'To complete pairing, open this URL in your browser:', rawLength: 'To complete pairing, open this URL in your browser:'.length },
     { text: `${cyan}${bold}${verifyUrl}${reset}`, rawLength: verifyUrl.length },
     { text: '', rawLength: 0 },
-    { text: `Then enter this code on the page: ${yellow}${bold}${user_code}${reset}`, rawLength: `Then enter this code on the page: ${user_code}`.length },
+    { text: `Then enter this code on the page: ${yellow}${bold}${displayUserCode}${reset}`, rawLength: `Then enter this code on the page: ${displayUserCode}`.length },
     { text: '', rawLength: 0 },
     { text: `${dim}Waiting for approval in browser...${reset}`, rawLength: 'Waiting for approval in browser...'.length }
   ]);
@@ -2408,7 +3126,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, brow
         currentIntervalMs += 5000;
       } else {
         // Any fatal error (expired_token, access_denied, invalid_grant, etc.)
-        const errMsg = tokenRes.data?.error_description || tokenRes.data?.error || `HTTP ${tokenRes.status}`;
+        const errMsg = sanitizeForDisplay(tokenRes.data?.error_description || tokenRes.data?.error || `HTTP ${tokenRes.status}`, 300);
         console.error(`\nerror: [DEVICE_FLOW_AUTH_DENIED] Authorization failed: ${errMsg}`);
         console.error('suggested_action: Re-run the command and approve the prompt in the browser.');
         process.exit(1);
@@ -2419,7 +3137,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined, brow
       consecutiveNetErrors += 1;
       if (consecutiveNetErrors >= MAX_NET_ERROR_RETRIES) {
         const detail = pollErr instanceof Error ? pollErr.message : String(pollErr);
-        console.error(`\nerror: [DEVICE_FLOW_CONNECT] Could not reach ${tokenEndpoint} after ${consecutiveNetErrors} attempts: ${detail}`);
+        console.error(`\nerror: [DEVICE_FLOW_CONNECT] Could not reach ${sanitizeForDisplay(tokenEndpoint, 256)} after ${consecutiveNetErrors} attempts: ${sanitizeForDisplay(detail, 300)}`);
         console.error('suggested_action: Check network access to the control plane (or NC_BASE_URL), then re-run.');
         process.exit(1);
       }
@@ -2442,5 +3160,8 @@ const isMainModule = () => {
 };
 
 if (isMainModule()) {
-  main();
+  main().catch((err) => {
+    reportSetupError(err);
+    process.exitCode = 1;
+  });
 }