node-command 2.0.1 → 2.0.3

package/lib/setup.mjs

@@ -8,6 +8,42 @@ import child_process from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import crypto from 'node:crypto';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+/** Enrollment metadata is a brand, never an executable, profile or command. */
+export function normalizeBrowserBrand(value) {
+  return value === 'edge' || value === 'chrome' ? value : 'unknown';
+}
+
+/** Capture HKCU before UAC; forwarded unknown must not query another account.
+ * @param {{platform?: string, forwarded?: string, run?: typeof child_process.spawnSync}} [options]
+ */
+export function captureBrowserDefaultBrand({ platform = os.platform(), forwarded = process.env.NC_BROWSER_ENROLL_BRAND, run = child_process.spawnSync } = {}) {
+  if (platform !== 'win32') return 'unknown';
+  if (forwarded !== undefined) return normalizeBrowserBrand(forwarded);
+  try {
+    const result = run('C:\\Windows\\System32\\reg.exe', [
+      'query', 'HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\https\\UserChoice', '/v', 'ProgId'
+    ], { encoding: 'utf8', timeout: 1500, maxBuffer: 4096, windowsHide: true, shell: false });
+    if (result.error || result.status !== 0 || typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > 4096) return 'unknown';
+    const values = [...result.stdout.matchAll(/^\s*ProgId\s+REG_SZ\s+(\S+)\s*$/gim)];
+    if (values.length !== 1) return 'unknown';
+    if (/^MSEdgeHTM$/i.test(values[0][1])) return 'edge';
+    if (/^ChromeHTML$/i.test(values[0][1])) return 'chrome';
+  } catch {}
+  return 'unknown';
+}
+
+/** Re-exec carries only a validated brand, including across credential UAC.
+ * Original CLI argv/dispatch are restored; no new public CLI flag is added.
+ * @param {string[]} args
+ * @param {string} brand
+ */
+export function browserBrandReexecArgs(args, brand) {
+  const script = `process.env.NC_BROWSER_ENROLL_BRAND=${JSON.stringify(normalizeBrowserBrand(brand))};process.argv=[process.execPath,...${JSON.stringify(args)}];await import(${JSON.stringify(pathToFileURL(path.resolve(args[0])).href)});`;
+  return ['--input-type=module', '--eval', script];
+}
 
 /** Single-line notice printed when setup falls back to user mode. */
 export const LIMITED_CAPS_WARNING =
@@ -134,10 +170,10 @@ export function candidateInstallRoots({ platform = os.platform(), env = process.
     const localAppData = env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');
     roots.push(path.join(programData, 'NC'), path.join(localAppData, 'nc'));
   } else if (platform === 'darwin') {
-    roots.push('/opt/nc', path.join(homedir, 'Library', 'Application Support', 'nc'));
+    roots.push('/Library/Application Support/nc', '/opt/nc', path.join(homedir, 'Library', 'Application Support', 'nc'));
   } else {
     const dataHome = env.XDG_DATA_HOME || path.join(homedir, '.local', 'share');
-    roots.push('/opt/nc', path.join(dataHome, 'nc'));
+    roots.push('/opt/nc', path.join(dataHome, 'nc'), '/var/lib/nodecommand/nc');
   }
   return [...new Set(roots)];
 }
@@ -158,20 +194,119 @@ export function isInstallRoot(root, existsSync = fs.existsSync) {
   }
 }
 
+/** Read-only recognition of the fixed protected single/dual-root producer.
+ * Protected records establish discovery, never permission to execute a tree.
+ */
+function linuxPairedInstallation(io = fs) {
+  io = { ...fs, ...io };
+  const helperRoot = '/opt/nc', pairedRoot = '/var/lib/nodecommand/nc';
+  const app = helperRoot + '/libexec/privileged-helper';
+  const lstat = io.lstatSync || fs.lstatSync;
+  const present = file => {
+    try { lstat(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  };
+  const fail = () => { throw Object.assign(new Error('TRUSTED_ROOT_MAINTENANCE_REQUIRED: paired Linux installation metadata is missing, unreadable, conflicting or unprotected; preserve both roots for independently authorized local Root maintenance.'), { code: 'TRUSTED_ROOT_MAINTENANCE_REQUIRED' }); };
+  try {
+    if (!present(app)) {
+      if (present(helperRoot + '/libexec/nc-linux-peercred')) fail();
+      return null;
+    }
+    const check = (file, directory = false, protectedPath = true) => {
+      if (io.realpathSync(file) !== file) fail();
+      for (let current = file; ; current = path.dirname(current)) {
+        const st = lstat(current);
+        if (io.realpathSync(current) !== current || st.isSymbolicLink() || (protectedPath && (st.uid !== 0 || st.gid !== 0 || (st.mode & 0o022))) ||
+            (current === file && !directory ? !st.isFile() || st.nlink !== 1 : !st.isDirectory())) fail();
+        if (current === path.dirname(current)) return;
+      }
+    };
+    const read = (file, protectedPath = true, mode = 0o600) => {
+      check(file, false, protectedPath);
+      const fd = io.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      try {
+        const before = io.fstatSync(fd), named = lstat(file);
+        if (!before.isFile() || before.nlink !== 1 || before.dev !== named.dev || before.ino !== named.ino ||
+            !Number.isSafeInteger(before.size) || before.size <= 0 || before.size > 65536 ||
+            (protectedPath && (before.uid !== 0 || before.gid !== 0 || (before.mode & 0o7777) !== mode))) fail();
+        const text = io.readFileSync(fd, 'utf8'), after = io.fstatSync(fd);
+        if (Buffer.byteLength(text) !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) fail();
+        return text;
+      } finally { io.closeSync(fd); }
+    };
+    check(app, true);
+    if (io.readdirSync(helperRoot + '/libexec').sort().join('\n') !== 'nc-linux-peercred\nprivileged-helper') fail();
+    check(helperRoot + '/libexec/nc-linux-peercred');
+    const bootstrap = JSON.parse(read(app + '/helper-bootstrap.json'));
+    const selection = JSON.parse(read('/var/lib/nc-lifecycle/selected.json'));
+    const exact = (value, fields) => value && typeof value === 'object' && !Array.isArray(value) &&
+      Object.keys(value).length === fields.length && fields.every(field => Object.hasOwn(value, field));
+    const id = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/.test(value);
+    const controlPlaneId = value => typeof value === 'string' && value.length > 0 && value.length <= 256 &&
+      value.trim() === value && !/[\x00-\x1f\x7f]/.test(value);
+    const canonical = value => typeof value === 'string' && path.isAbsolute(value) && path.resolve(value) === value && !/[\x00-\x1f\x7f]/.test(value);
+    if (!exact(bootstrap, ['client_id', 'control_plane_id', 'tenant_id', 'root_consent', 'ack_private_key_file', 'helper_key_id',
+      'helper_key_binding_id', 'binding_state', 'node_bin', 'ordinary_root', 'ordinary_service_scope', 'lifecycle_custody_state']) ||
+        !/^nc_[0-9a-f]{64}$/.test(bootstrap.client_id) || !controlPlaneId(bootstrap.control_plane_id) || !id(bootstrap.tenant_id) ||
+        !id(bootstrap.helper_key_id) || bootstrap.root_consent !== true || ![helperRoot, pairedRoot].includes(bootstrap.ordinary_root) || bootstrap.lifecycle_custody_state !== 'prepared' ||
+        !['system', 'user'].includes(bootstrap.ordinary_service_scope) || !canonical(bootstrap.node_bin) ||
+        bootstrap.ack_private_key_file !== app + '/privileged-helper-ack-key.pem' || bootstrap.helper_key_binding_id !== null || bootstrap.binding_state !== 'pending') fail();
+    const ncRoot = bootstrap.ordinary_root;
+    if (ncRoot === helperRoot) {
+      const ordinaryEntries = ['app', 'config', 'data', 'logs', 'releases', 'backups', 'tmp', 'tools', 'libexec', 'uninstall.sh', 'install-linux.sh'];
+      if (present(pairedRoot) || !io.readdirSync(ncRoot).every(entry => ordinaryEntries.includes(entry))) fail();
+    } else if (io.readdirSync(helperRoot).sort().join('\n') !== 'libexec') fail();
+    if (!exact(selection, ['version', 'control_plane_id', 'tenant_id', 'client_id', 'helper_key_binding_id', 'helper_key_id',
+      'installation_root', 'ordinary_uid', 'ordinary_service_scope', 'ordinary_service_unit', 'artifacts', 'bundle']) || selection.version !== 1 ||
+        ['control_plane_id', 'tenant_id', 'client_id', 'helper_key_id'].some(field => selection[field] !== bootstrap[field]) ||
+        !id(selection.helper_key_binding_id) || selection.installation_root !== ncRoot || selection.ordinary_service_scope !== bootstrap.ordinary_service_scope ||
+        selection.ordinary_service_unit !== 'nc-client.service' || !Number.isSafeInteger(selection.ordinary_uid) || selection.ordinary_uid <= 0 || selection.ordinary_uid > 0xfffffffe) fail();
+    const serviceFile = '/etc/systemd/' + selection.ordinary_service_scope + '/nc-client.service';
+    const artifacts = [serviceFile, '/etc/systemd/system/nc-privileged-helper.service', '/etc/systemd/system/nc-privileged-helper.socket', '/etc/tmpfiles.d/nc-privileged-helper.conf'].sort();
+    const bundle = ['finalize-linux-uninstall.mjs', 'nc-linux-managed-work', 'node', 'privileged-helper-contract.mjs', 'privileged-helper-linux-managed-work.mjs', 'privileged-helper-protected-config.mjs'];
+    const validFile = (file, name, mode) => exact(file, ['path', 'sha256', 'size', 'mode']) && file.path === name && file.mode === mode &&
+      typeof file.sha256 === 'string' && /^[0-9a-f]{64}$/.test(file.sha256) && Number.isSafeInteger(file.size) && file.size > 0 && file.size <= 256 * 1024 * 1024;
+    if (!Array.isArray(selection.artifacts) || selection.artifacts.length !== artifacts.length ||
+        !selection.artifacts.every((file, index) => validFile(file, artifacts[index], 0o644)) ||
+        !Array.isArray(selection.bundle) || selection.bundle.length !== bundle.length ||
+        !selection.bundle.every((file, index) => validFile(file, bundle[index], ['node', 'nc-linux-managed-work'].includes(bundle[index]) ? 0o755 : 0o644))) fail();
+    const serviceArtifact = selection.artifacts.find(file => file.path === serviceFile);
+    const unit = read(serviceFile, true, 0o644);
+    const directories = [...unit.matchAll(/^\s*WorkingDirectory\s*=\s*(.+?)\s*$/gm)];
+    const launches = [...unit.matchAll(/^\s*ExecStart\s*=\s*(.+?)\s*$/gm)];
+    const launch = launches[0]?.[1].match(/^(?:"([^"\n]+)"|([^\s]+))\s+(?:"([^"\n]+)"|([^\s]+))$/);
+    if (directories.length !== 1 || ![ncRoot, ncRoot + '/app'].includes(directories[0][1]) || launches.length !== 1 ||
+        !launch || !canonical(launch[1] || launch[2]) || (launch[3] || launch[4]) !== ncRoot + '/app/launcher.mjs' ||
+        Buffer.byteLength(unit) !== serviceArtifact.size || crypto.createHash('sha256').update(unit).digest('hex') !== serviceArtifact.sha256) fail();
+    check(path.dirname(ncRoot), true);
+    check(ncRoot, true, ncRoot === helperRoot);
+    if (![0, selection.ordinary_uid].includes(lstat(ncRoot).uid)) fail();
+    check(ncRoot + '/config', true, false);
+    if (lstat(ncRoot + '/config').uid !== selection.ordinary_uid) fail();
+    const content = read(ncRoot + '/config/nc-client.env', false);
+    const ids = content.split(/\r?\n/).filter(line => /^\s*NC_CLIENT_ID\s*=/.test(line));
+    const clientId = ids[0]?.match(/^\s*NC_CLIENT_ID\s*=\s*(?:"(nc_[0-9a-f]{64})"|'(nc_[0-9a-f]{64})'|(nc_[0-9a-f]{64}))\s*$/);
+    if (ids.length !== 1 || !clientId || (clientId[1] || clientId[2] || clientId[3]) !== bootstrap.client_id) fail();
+    check(ncRoot + '/app/launcher.mjs', false, false);
+    return { ncRoot, helperRoot, clientId: bootstrap.client_id, ordinaryUid: selection.ordinary_uid,
+      serviceScope: selection.ordinary_service_scope, serviceFile, serviceArtifact };
+  } catch { fail(); }
+}
+
 /**
- * Tri-state install-tree probe. A root-owned system tree (0750/0700) is
+ * Install-tree probe. A root-owned system tree (0750/0700) is
  * unreadable to a non-root caller: a plain boolean would report "nothing to
  * remove" for a machine-wide install that clearly exists, and the sudo path
  * would never be reached. Distinguishes:
  *   - 'install'    markers readable → normal removal path
  *   - 'absent'     root directory does not exist
  *   - 'foreign'    root exists and is traversable but carries no markers
+ *   - 'paired-helper' protected metadata binds this helper to one ordinary root
  *   - 'unreadable' root exists but markers cannot be stat'ed (EACCES/EPERM)
  *                  → needs elevation; the uninstaller's own safety guard
  *                    still refuses non-NC trees when run under sudo.
  * @param {string} root
  * @param {{ statSync?: (p: string) => { isDirectory(): boolean }, accessSync?: (p: string, mode?: number) => void }} [io]
- * @returns {'install'|'absent'|'foreign'|'unreadable'}
+ * @returns {'install'|'absent'|'foreign'|'unreadable'|'paired-helper'}
  */
 export function probeInstallRoot(root, io = {}) {
   const statSync = io.statSync || fs.statSync;
@@ -190,25 +325,35 @@ export function probeInstallRoot(root, io = {}) {
       if (err && (err.code === 'EACCES' || err.code === 'EPERM')) return 'unreadable';
     }
   }
+  if (os.platform() === 'linux' && root === '/opt/nc' && linuxPairedInstallation(io)) return 'paired-helper';
   return 'foreign';
 }
 
 /**
  * Removal targets split by accessibility. `install` roots are removed by the
  * local flow; `unreadable` roots (system installs seen from a non-root shell)
- * are routed to the elevated runUninstallerScript path instead of being
+ * report explicit trusted-maintenance requirements instead of being
  * silently reported as "nothing to remove".
  * @param {{ platform?: string, env?: NodeJS.ProcessEnv, homedir?: string, io?: object }} [options]
- * @returns {{ install: string[], unreadable: string[] }}
+ * @returns {{ install: string[], unreadable: string[], paired?: { ncRoot: string, helperRoot: string, clientId: string }[] }}
  */
 export function findRemovalTargets({ io = {}, ...rest } = {}) {
   const install = [];
   const unreadable = [];
-  for (const root of candidateInstallRoots(rest)) {
+  const pair = (rest.platform || os.platform()) === 'linux' ? linuxPairedInstallation(io) : null;
+  const env = rest.env || process.env;
+  if (pair && env.NC_ROOT && ![pair.ncRoot, pair.helperRoot].includes(env.NC_ROOT)) throw new Error('TRUSTED_ROOT_MAINTENANCE_REQUIRED: NC_ROOT conflicts with the protected paired installation.');
+  const roots = candidateInstallRoots(pair ? { ...rest, env: { ...env, NC_ROOT: undefined } } : rest);
+  for (const root of pair ? [...new Set([...roots, pair.ncRoot])] : roots) {
+    if (root === pair?.helperRoot && root !== pair.ncRoot) continue;
     const status = probeInstallRoot(root, io);
     if (status === 'install') install.push(root);
     else if (status === 'unreadable') unreadable.push(root);
   }
+  if (pair) {
+    if (install.length !== 1 || install[0] !== pair.ncRoot || unreadable.length) throw new Error('TRUSTED_ROOT_MAINTENANCE_REQUIRED: conflicting paired installation inventory; preserve all roots.');
+    return { install, unreadable, paired: [pair] };
+  }
   return { install, unreadable };
 }
 
@@ -217,6 +362,7 @@ export function findRemovalTargets({ io = {}, ...rest } = {}) {
  * @param {{ platform?: string, env?: NodeJS.ProcessEnv, homedir?: string, existsSync?: (p: string) => boolean }} [options]
  */
 export function findInstallations({ existsSync = fs.existsSync, ...rest } = {}) {
+  if ((rest.platform || os.platform()) === 'linux' && linuxPairedInstallation(rest.io || fs)) return findRemovalTargets(rest).install;
   return candidateInstallRoots(rest).filter((r) => isInstallRoot(r, existsSync));
 }
 
@@ -236,12 +382,526 @@ export function getNcRootForMode(mode, { platform = os.platform(), env = process
     const localAppData = env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');
     return path.join(localAppData, 'nc');
   }
-  if (mode === 'system') return '/opt/nc';
+  if (mode === 'system') return platform === 'darwin' ? '/Library/Application Support/nc' : '/opt/nc';
   if (platform === 'darwin') return path.join(homedir, 'Library', 'Application Support', 'nc');
   const dataHome = env.XDG_DATA_HOME || path.join(homedir, '.local', 'share');
   return path.join(dataHome, 'nc');
 }
 
+/**
+ * Resolve setup state before enrollment. Markers can prevent setup
+ * or preserve a root; they never authorize elevation or another user's mode.
+ * An explicit override does not hide an existing canonical tree or service.
+ * @param {{ platform?: string, mode?: 'system'|'user', env?: NodeJS.ProcessEnv, homedir?: string, uid?: number, io?: Pick<typeof fs, 'lstatSync'|'readFileSync'>, run?: typeof child_process.spawnSync }} [options]
+ * @returns {{ mode: 'system'|'user', ncRoot: string, existing: boolean, clientId?: string, protectedInstallation?: { ordinaryUid: number, serviceScope: string }, rootManagedPair?: { ordinaryUid: number, serviceScope: string } }}
+ */
+export function setupTarget({ platform = os.platform(), mode = decideInstallMode({ platform }), env = process.env, homedir = os.homedir(), uid = process.getuid?.(), io = fs, run = child_process.spawnSync } = {}) {
+  const stop = (reason) => { throw new Error(`${platform === 'darwin' ? 'macOS' : platform} setup stopped: ${reason}`); };
+  if (platform !== 'win32' && (!Number.isInteger(uid) || uid < 0)) stop('cannot verify the invoking user.');
+  const canonicalEnv = { ...env };
+  delete canonicalEnv.NC_ROOT;
+  const systemRoot = path.resolve(getNcRootForMode('system', { platform, env: canonicalEnv, homedir }));
+  const legacySystemRoot = platform === 'darwin' ? '/opt/nc' : null;
+  const userRoot = path.resolve(getNcRootForMode('user', { platform, env: canonicalEnv, homedir }));
+  if (env.NC_ROOT && !path.isAbsolute(env.NC_ROOT)) stop('NC_ROOT must be an absolute existing or new installation path.');
+  const explicitRoot = env.NC_ROOT ? path.resolve(env.NC_ROOT) : null;
+  const roots = [...new Set([systemRoot, legacySystemRoot, userRoot, ...(platform === 'linux' ? ['/var/lib/nodecommand/nc'] : []), explicitRoot].filter(Boolean))];
+  const pair = platform === 'linux' ? linuxPairedInstallation(io) : null;
+  const stat = (file) => {
+    try { return io.lstatSync(file); } catch (err) {
+      if (err?.code === 'ENOENT') return null;
+      stop(`existing installation state is unreadable or unverifiable at ${file}.`);
+    }
+  };
+  const read = (file) => {
+    const info = stat(file);
+    if (!info) return null;
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 65536) stop('installation metadata is ambiguous.');
+    try {
+      const content = io.readFileSync(file, { encoding: 'utf8', flag: fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW });
+      if (Buffer.byteLength(content) > 65536) stop('installation metadata exceeds the supported bound.');
+      return content;
+    } catch { stop('existing installation metadata cannot be read safely.'); }
+  };
+  const installs = [];
+  for (const root of roots) {
+    if (root === pair?.helperRoot && root !== pair.ncRoot) continue;
+    const info = stat(root);
+    if (!info) continue;
+    if (!info.isDirectory() || info.isSymbolicLink()) stop('an installation root is not a regular directory.');
+    const config = stat(path.join(root, 'config'));
+    if (!config?.isDirectory() || config.isSymbolicLink()) stop('an existing root has no verifiable NC configuration.');
+    const content = read(path.join(root, 'config', 'nc-client.env'));
+    if (content === null) stop('an existing root has no verifiable NC configuration.');
+    const entries = content.split(/\r?\n/).filter(line => /^\s*NC_SERVICE_MODE\s*=/.test(line));
+    const match = entries[0]?.match(/^\s*NC_SERVICE_MODE\s*=\s*(?:"(user|system)"|'(user|system)'|(user|system))\s*$/);
+    if (entries.length > 1 || (entries.length && !match)) stop('stored installation mode is ambiguous.');
+    const storedMode = match ? match[1] || match[2] || match[3] : null;
+    // Legacy canonical trees retain their installer ownership/layout. Linux
+    // custom trees can also identify their mode by owner; other custom trees
+    // require the persisted mode rather than guessing from current privilege.
+    const detectedMode = storedMode || (root === pair?.ncRoot ? info.uid === 0 ? 'system' : info.uid === uid && uid !== 0 ? 'user' : null : platform === 'win32'
+      ? root === userRoot ? 'user' : root === systemRoot ? 'system' : null
+      : root === userRoot && info.uid === uid && uid !== 0 ? 'user' : (root === systemRoot || root === legacySystemRoot) && info.uid === 0 ? 'system'
+        : platform === 'linux' && root === explicitRoot ? info.uid === 0 ? 'system' : info.uid === uid ? 'user' : null : null);
+    // Root may verify this independently selected restricted pair, not adopt
+    // its user identity or execute a user installer. Management mode stays system.
+    const rootManagedPair = root === pair?.ncRoot && uid === 0 && process.getuid?.() === 0 && process.geteuid?.() === 0 && mode === 'system' &&
+      storedMode === 'user' && pair.serviceScope === 'user' && info.uid === pair.ordinaryUid && config.uid === pair.ordinaryUid;
+    if (!detectedMode || (!rootManagedPair && platform !== 'win32' && (detectedMode === 'user' ? info.uid !== uid || uid === 0 || config.uid !== uid : info.uid !== 0))) stop(`existing mode/ownership cannot be preserved safely at ${root}.`);
+    if (((root === systemRoot || root === legacySystemRoot) && detectedMode !== 'system') || (root === userRoot && detectedMode !== 'user')) stop(`stored mode conflicts with the installation root ${root}.`);
+    for (const name of ['NC_CLIENT_ID', 'NC_CLIENT_TOKEN', 'NC_SERVER_URL']) {
+      if (content.split(/\r?\n/).filter(line => new RegExp(`^\\s*${name}\\s*=`).test(line)).length > 1) stop(`duplicate host metadata at ${root}.`);
+    }
+    installs.push({ mode: detectedMode, ncRoot: root, rootManagedPair });
+  }
+  const services = [];
+  for (const [file, serviceMode, owner] of platform === 'darwin' ? [
+    ['/Library/LaunchDaemons/com.nc.client.plist', 'system', 0],
+    [path.join(homedir, 'Library', 'LaunchAgents', 'com.nc.client.plist'), 'user', uid]
+  ] : []) {
+    const info = stat(file);
+    if (!info) continue;
+    const content = read(file);
+    const labels = [...content.matchAll(/<key>Label<\/key>\s*<string>([^<]*)<\/string>/g)];
+    const directories = [...content.matchAll(/<key>WorkingDirectory<\/key>\s*<string>([^<]*)<\/string>/g)];
+    if (info.uid !== owner || labels.length !== 1 || labels[0][1] !== 'com.nc.client' || directories.length !== 1) stop('existing service metadata is ambiguous.');
+    const directory = directories[0][1].replace(/&(amp|lt|gt|quot|apos);/g, (_, entity) => ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" })[entity]);
+    if (!path.isAbsolute(directory) || path.basename(directory) !== 'app') stop('existing service root cannot be verified.');
+    const serviceRoot = path.dirname(path.resolve(directory));
+    if (!installs.some(install => install.ncRoot === serviceRoot && install.mode === serviceMode)) stop('an existing service targets a different or unverifiable root. Preserve it through its maintenance flow.');
+    services.push(serviceRoot);
+  }
+  if (platform === 'linux') {
+    for (const [file, serviceMode] of [
+      ['/etc/systemd/system/nc-client.service', 'system'],
+      ['/etc/systemd/user/nc-client.service', 'user'],
+      [path.join(homedir, '.config/systemd/user/nc-client.service'), 'user'],
+      ...(env.XDG_CONFIG_HOME ? [[path.join(env.XDG_CONFIG_HOME, 'systemd/user/nc-client.service'), 'user']] : [])
+    ]) {
+      const content = read(file);
+      if (content === null) continue;
+      if (pair && file !== pair.serviceFile) stop(`another ordinary service exists at ${file}; preserve the paired installation through explicit Root maintenance.`);
+      const directories = [...content.matchAll(/^\s*WorkingDirectory\s*=\s*(.+?)\s*$/gm)];
+      const directory = directories[0]?.[1];
+      if (directories.length !== 1 || !path.isAbsolute(directory)) stop(`existing service metadata is ambiguous at ${file}.`);
+      const pairedService = pair && file === pair.serviceFile;
+      const serviceRoot = pairedService && directory === pair.ncRoot ? pair.ncRoot : path.basename(directory) === 'app' ? path.dirname(path.resolve(directory)) : null;
+      if (pairedService) {
+        if (Buffer.byteLength(content) !== pair.serviceArtifact.size || crypto.createHash('sha256').update(content).digest('hex') !== pair.serviceArtifact.sha256) stop(`paired service ${file} changed; explicit Root maintenance is required.`);
+      }
+      if (!installs.some(install => install.ncRoot === serviceRoot && (pairedService || install.mode === serviceMode))) stop(`existing service ${file} targets a different or unverifiable root; use its maintenance flow.`);
+      services.push(serviceRoot);
+    }
+    if (pair && !services.includes(pair.ncRoot)) stop('paired ordinary service is missing; explicit Root maintenance is required.');
+  }
+  if (platform === 'win32') {
+    // Discovery only: never start/stop tasks or services to identify a target.
+    const script = "$ErrorActionPreference='Stop'; $s=@(Get-CimInstance Win32_Service -Filter \"Name='NCClient'\" | Select-Object PathName); $t=@(Get-ScheduledTask -TaskPath '\\' | Where-Object { $_.TaskName -eq 'NC Client' } | ForEach-Object { $_.Actions | Select-Object WorkingDirectory }); ConvertTo-Json -Compress -Depth 4 @{services=$s;tasks=$t}";
+    let state;
+    try {
+      const result = run('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', timeout: 10000, maxBuffer: 65536, windowsHide: true });
+      if (result.status !== 0) stop('Windows service/task state is unreadable; inspect NCClient and the NC Client task through administrator maintenance.');
+      state = JSON.parse(String(result.stdout));
+      if (!Array.isArray(state.services) || !Array.isArray(state.tasks)) throw new Error('invalid service state');
+    } catch { stop('Windows service/task state cannot be verified; inspect NCClient and the NC Client task through administrator maintenance.'); }
+    for (const service of state.services) {
+      const executable = service.PathName?.match(/^"([^"]+\\service\\nc-service\.exe)"\s/i)?.[1];
+      const root = executable && path.resolve(path.dirname(path.dirname(executable)));
+      if (!root || !installs.some(install => install.ncRoot.toLowerCase() === root.toLowerCase() && install.mode === 'system')) stop('NCClient targets a different or unverifiable root; use its maintenance flow.');
+      services.push(root);
+    }
+    for (const task of state.tasks) {
+      const root = typeof task.WorkingDirectory === 'string' && path.isAbsolute(task.WorkingDirectory) ? path.resolve(task.WorkingDirectory) : null;
+      if (!root || !installs.some(install => install.ncRoot.toLowerCase() === root.toLowerCase())) stop('the NC Client task targets a different or unverifiable root; use its maintenance flow.');
+      services.push(root);
+    }
+  }
+  if (installs.length > 1 || new Set(services.map(root => platform === 'win32' ? root.toLowerCase() : root)).size > 1) stop(`conflicting installations/services exist at ${installs.map(install => install.ncRoot).join(', ')}; select a maintenance target; no competing agent will be created.`);
+  const existing = installs[0];
+  if (existing && explicitRoot && explicitRoot !== existing.ncRoot) stop('NC_ROOT would replace an existing installation root.');
+  if (existing && existing.mode !== mode && !existing.rootManagedPair) stop('preserve the existing mode/root; system maintenance requires an explicitly elevated invocation, not a second user install or user impersonation.');
+  if ((env.NC_MODE && env.NC_MODE !== mode) || (env.NC_USER_INSTALL === '1' && mode !== 'user') || (env.NC_SYSTEM_INSTALL === '1' && mode !== 'system')) stop('installer environment conflicts with the invoking privilege/mode.');
+  return { mode, ncRoot: existing?.ncRoot || explicitRoot || (mode === 'system' ? systemRoot : userRoot), existing: !!existing,
+    ...(pair ? { clientId: pair.clientId, protectedInstallation: { ordinaryUid: pair.ordinaryUid, serviceScope: pair.serviceScope } } : {}),
+    ...(existing?.rootManagedPair ? { rootManagedPair: { ordinaryUid: pair.ordinaryUid, serviceScope: pair.serviceScope } } : {}) };
+}
+
+/** Preserve the macOS entry used by existing callers and fixtures. */
+export function macosSetupTarget({ uid = process.getuid?.(), ...options } = {}) {
+  return setupTarget({ ...options, platform: 'darwin', uid, mode: uid === 0 ? 'system' : 'user' });
+}
+
+/** Parse installation metadata as bounded data, NEVER as a root shell script. */
+export function parseMaintenanceEnv(text) {
+  if (Buffer.byteLength(text) > 65536) throw new Error('IDENTITY_MAINTENANCE_CONFIG_INVALID');
+  const result = Object.create(null);
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const match = line.match(/^(NC_[A-Z0-9_]+)=(.*)$/);
+    if (!match || Object.hasOwn(result, match[1]) || /[\x00-\x1f]/.test(match[2])) throw new Error('IDENTITY_MAINTENANCE_CONFIG_INVALID');
+    let value = match[2];
+    if (/^["']/.test(value)) {
+      if (value.at(-1) !== value[0]) throw new Error('IDENTITY_MAINTENANCE_CONFIG_INVALID');
+      value = value.slice(1, -1);
+    }
+    result[match[1]] = value;
+  }
+  if (!/^nc_[0-9a-f]{64}$/.test(result.NC_CLIENT_ID || '') || !result.NC_CLIENT_TOKEN ||
+      new URL(result.NC_SERVER_URL).protocol !== 'https:') throw new Error('IDENTITY_MAINTENANCE_CONFIG_INVALID');
+  return result;
+}
+
+/** Import only an already provisioned root-protected producer. Neither npx
+ * ordinary cache code nor an agent-writable helper module may hold ACK keys.
+ */
+export async function loadProtectedHelperProducer(root) {
+  if (process.geteuid?.() !== 0 || !path.isAbsolute(root) || process.env.NODE_OPTIONS || process.env.NODE_PATH)
+    throw new Error('PRIVILEGED_HELPER_ROOT_MAINTENANCE_REQUIRED');
+  const check = file => {
+    for (let p = file; ; p = path.dirname(p)) {
+      const st = fs.lstatSync(p);
+      if (st.isSymbolicLink() || st.uid !== 0 || (st.mode & 0o022)) throw new Error('PRIVILEGED_HELPER_UNPROTECTED_PATH');
+      if (path.dirname(p) === p) break;
+    }
+  };
+  check(fs.realpathSync(process.execPath)); check(fileURLToPath(import.meta.url)); check(fs.realpathSync(process.argv[1]));
+  const app = path.join(root, 'libexec/privileged-helper');
+  const visit = file => {
+    check(file); const st = fs.lstatSync(file);
+    if (st.isDirectory()) for (const name of fs.readdirSync(file)) visit(path.join(file, name));
+    else if (!st.isFile()) throw new Error('PRIVILEGED_HELPER_UNPROTECTED_PATH');
+  };
+  visit(app);
+  return import(pathToFileURL(path.join(app, 'privileged-helper-provision.mjs')).href);
+}
+
+/**
+ * Selected Linux identity maintenance. All OS mutation is behind complete
+ * target/identity/rollback preflight. The caller is explicitly privileged;
+ * verifyReconnection must independently confirm the same target in normal
+ * authenticated management, not merely accept a local agent status claim.
+ * home/io/run are injectable solely for the existing disposable fixtures.
+ */
+export async function maintainLinuxIdentity({ ncRoot, hostId, operatorUser, authorizeMaintenance, verifyReconnection,
+  home = '/var/lib/nodecommand', systemUnit = '/etc/systemd/system/nc-client.service', io = fs, run = child_process.spawnSync, uid = process.geteuid?.() } = {}) {
+  if (uid !== 0 || os.platform() !== 'linux') throw new Error('IDENTITY_MAINTENANCE_ROOT_REQUIRED');
+  const fail = reason => { throw new Error(`IDENTITY_MAINTENANCE_REFUSED:${reason}`); };
+  if (!/^nc_[0-9a-f]{64}$/.test(hostId || '') || !ncRoot || path.resolve(ncRoot) !== ncRoot ||
+      !path.isAbsolute(home) || /[\n\r\x00$%"\\]/.test(ncRoot + home) || typeof authorizeMaintenance !== 'function' || typeof verifyReconnection !== 'function') fail('select the exact root, host and authenticated maintenance/reconnection verification first');
+  const command = (exe, args, { optional = false } = {}) => {
+    const result = run(exe, args, { encoding: 'utf8', shell: false, timeout: 60000, maxBuffer: 65536,
+      env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin', LANG: 'C' } });
+    if (result.error || result.status !== 0) { if (optional && !result.error && result.status === 2) return null; fail(`${path.basename(exe)} failed; preserve this installation and repair explicitly`); }
+    return String(result.stdout || '');
+  };
+  const exists = file => { try { return io.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+  const directoryFd = directory => {
+    let fd = io.openSync('/', fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
+    try {
+      for (const component of path.resolve(directory).split('/').filter(Boolean)) {
+        const next = io.openSync(`/proc/self/fd/${fd}/${component}`, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+        io.closeSync(fd); fd = next;
+      }
+      return fd;
+    } catch (error) { io.closeSync(fd); throw error; }
+  };
+  const read = file => {
+    const parent = directoryFd(path.dirname(file));
+    let fd;
+    try { fd = io.openSync(`/proc/self/fd/${parent}/${path.basename(file)}`, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK); }
+    finally { io.closeSync(parent); }
+    try { const st = io.fstatSync(fd); if (!st.isFile() || st.size > 65536) fail('unsafe installation metadata'); return io.readFileSync(fd, 'utf8'); }
+    finally { io.closeSync(fd); }
+  };
+  const write = (file, text, mode) => {
+    const parent = directoryFd(path.dirname(file)); let fd;
+    try {
+      fd = io.openSync(`/proc/self/fd/${parent}/${path.basename(file)}`, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, mode);
+      const st = io.fstatSync(fd);
+      if (!st.isFile() || st.nlink !== 1) fail('maintenance destination is not a single regular file');
+      io.ftruncateSync(fd, 0); io.writeFileSync(fd, text); io.fsyncSync(fd);
+    } finally { if (fd !== undefined) io.closeSync(fd); io.closeSync(parent); }
+  };
+  const envPath = path.join(ncRoot, 'config/nc-client.env');
+  const envText = read(envPath), env = parseMaintenanceEnv(envText);
+  if (env.NC_CLIENT_ID !== hostId) fail('host ID mismatch; no token was consumed');
+  const identity = root => {
+    const data = parseMaintenanceEnv(read(path.join(root, 'config/nc-client.env')));
+    const key = crypto.createPrivateKey(read(path.join(root, 'config/nc-device-key.pem')));
+    return { client_id: data.NC_CLIENT_ID, server_url: data.NC_SERVER_URL,
+      device_key_id: crypto.createHash('sha256').update(crypto.createPublicKey(key).export({ type: 'spki', format: 'der' })).digest('hex') };
+  };
+  const protectedDirectory = directory => {
+    for (let current = directory; ; current = path.dirname(current)) {
+      const st = io.lstatSync(current);
+      if (!st.isDirectory() || st.isSymbolicLink() || st.uid !== 0 || (st.mode & 0o022)) fail('maintenance/rollback ancestry is not root-protected');
+      if (path.dirname(current) === current) break;
+    }
+  };
+  const rootInfo = io.lstatSync(ncRoot);
+  if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) fail('source root is not a directory');
+  const loginMove = env.NC_SERVICE_MODE === 'user';
+  const oldUser = loginMove ? operatorUser : '_nc';
+  if (!/^[a-z_][a-z0-9_-]*[$]?$/.test(oldUser || '') || oldUser === 'root' || oldUser === 'nodecommand') fail('select the existing ordinary account explicitly');
+  const account = command('/usr/bin/getent', ['passwd', oldUser]).trim().split(':');
+  if (account.length !== 7 || account[0] !== oldUser || !/^\d+$/.test(account[2]) || !/^\d+$/.test(account[3])) fail('account inventory is ambiguous');
+  const oldUid = Number(account[2]), oldGid = Number(account[3]), oldHome = account[5];
+  if (oldUid === 0 || oldGid === 0 || (!loginMove && !/\/(?:nologin|false)$/.test(account[6]))) fail('selected account is not a dedicated non-root identity');
+  if (command('/usr/bin/getent', ['passwd', 'nodecommand'], { optional: true }) !== null ||
+      command('/usr/bin/getent', ['group', 'nodecommand'], { optional: true }) !== null) fail('nodecommand already exists; never merge an unrelated identity');
+  if (loginMove && (ncRoot === '/opt/nc' || !ncRoot.startsWith(oldHome + '/') || rootInfo.uid !== oldUid)) fail('the selected user tree does not belong to the selected login identity');
+  if (!loginMove && rootInfo.uid !== 0) fail('legacy dedicated system root is not protected');
+  const keyFdParent = directoryFd(path.join(ncRoot, 'config'));
+  let keyFd, selectedPrivateKey;
+  try {
+    keyFd = io.openSync(`/proc/self/fd/${keyFdParent}/nc-device-key.pem`, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const st = io.fstatSync(keyFd);
+    if (!st.isFile() || st.uid !== oldUid || st.size > 65536) fail('device key is not owned by the selected ordinary identity');
+    selectedPrivateKey = crypto.createPrivateKey(io.readFileSync(keyFd, 'utf8'));
+  } finally { if (keyFd !== undefined) io.closeSync(keyFd); io.closeSync(keyFdParent); }
+  const originalIdentity = { client_id: env.NC_CLIENT_ID, server_url: env.NC_SERVER_URL,
+    device_key_id: crypto.createHash('sha256').update(crypto.createPublicKey(selectedPrivateKey).export({ type: 'spki', format: 'der' })).digest('hex') };
+  if (!loginMove) protectedDirectory(ncRoot);
+  protectedDirectory(path.dirname(home));
+  const unit = loginMove ? path.join(oldHome, '.config/systemd/user/nc-client.service') : systemUnit;
+  if (!loginMove) {
+    protectedDirectory(path.dirname(unit));
+    const st = io.lstatSync(unit);
+    if (!st.isFile() || st.isSymbolicLink() || st.uid !== 0 || st.nlink !== 1 || (st.mode & 0o022)) fail('selected system unit is not root-protected');
+  }
+  const unitText = read(unit);
+  if (!unitText.split(/\r?\n/).includes(`WorkingDirectory=${ncRoot}/app`) ||
+      (!loginMove && (!unitText.split(/\r?\n/).includes('User=_nc') || !unitText.split(/\r?\n/).includes('Group=_nc')))) fail('selected service does not match this root/account');
+  if (loginMove && exists(systemUnit)) {
+    // A held global instance is inventory only. Never stop, adopt or rewrite it.
+    if (read(systemUnit).includes(`WorkingDirectory=${ncRoot}/app`)) fail('both managers claim this selected tree; repair the ambiguity first');
+  }
+  if (!loginMove) {
+    const aliases = command('/usr/bin/getent', ['passwd']).trim().split('\n').filter(line => Number(line.split(':')[2]) === oldUid);
+    if (aliases.length !== 1 || aliases[0].split(':')[0] !== '_nc') fail('legacy UID is shared; explicit identity reconciliation is required');
+    if (/^\s*(?:AmbientCapabilities|SupplementaryGroups|CapabilityBoundingSet)\s*=\s*\S/m.test(unitText)) fail('legacy service has additional privilege channels; repair explicitly first');
+    const group = command('/usr/bin/getent', ['group', '_nc']).trim().split(':');
+    if (Number(group[2]) !== oldGid) fail('legacy primary group mismatch');
+    const groupAliases = command('/usr/bin/getent', ['group']).trim().split('\n').filter(line => Number(line.split(':')[2]) === oldGid);
+    if (groupAliases.length !== 1 || groupAliases[0].split(':')[0] !== '_nc') fail('legacy GID is shared; no identity rename performed');
+    const journal = command('/usr/bin/getent', ['group', 'systemd-journal'], { optional: true });
+    const allowed = [oldGid, ...(journal ? [Number(journal.trim().split(':')[2])] : [])];
+    if (command('/usr/bin/id', ['-G', '_nc']).trim().split(/\s+/).some(gid => !allowed.includes(Number(gid)))) fail('legacy account has unapproved supplementary authority');
+  }
+  const helperEdits = [];
+  if (!loginMove && exists('/etc/systemd/system/nc-privileged-helper.socket')) {
+    const helperService = read('/etc/systemd/system/nc-privileged-helper.service');
+    if (!helperService.includes(`${ncRoot}/libexec/privileged-helper/privileged-helper-linux-daemon.mjs`)) fail('helper resources belong to another or unprotected installation');
+    const helperConfigPath = path.join(ncRoot, 'libexec/privileged-helper/privileged-helper.json');
+    protectedDirectory(path.dirname(helperConfigPath));
+    const helperConfig = JSON.parse(read(helperConfigPath));
+    if (helperConfig.client_id !== hostId || helperConfig.service_uid !== oldUid || helperConfig.service_gid !== oldGid) fail('helper peer binding is not this selected identity');
+    for (const file of ['/etc/systemd/system/nc-privileged-helper.socket', '/etc/tmpfiles.d/nc-privileged-helper.conf']) {
+      if (exists(file)) {
+        protectedDirectory(path.dirname(file));
+        const text = read(file);
+        helperEdits.push({ file, text, replacement: text.replace(/^SocketGroup=_nc$/m, 'SocketGroup=nodecommand').replace(/^(d\s+\/run\/nc\s+\S+\s+root\s+)_nc(\s)/m, '$1nodecommand$2') });
+      }
+    }
+  }
+  const destination = loginMove ? path.join(home, 'nc') : ncRoot;
+  if (exists(home)) fail('restricted home/destination already occupied');
+  if (exists(unit + '.identity-backup')) fail('an old service recovery copy is already present');
+  if (loginMove && exists(envPath + '.identity-backup')) fail('an old configuration recovery copy is already present');
+  const runtimeMatch = unitText.match(/^ExecStart=(?:"([^"\n]+)"|([^\s]+))\s+(?:"([^"\n]+)"|([^\s]+))\s*$/m);
+  const oldNode = runtimeMatch?.[1] || runtimeMatch?.[2];
+  if (!oldNode || (runtimeMatch[3] || runtimeMatch[4]) !== `${ncRoot}/app/launcher.mjs` || !path.isAbsolute(oldNode)) fail('runtime launch cannot be preserved safely');
+  const node = loginMove && oldNode.startsWith(ncRoot + '/') ? destination + oldNode.slice(ncRoot.length) : oldNode;
+  if (loginMove && oldNode.startsWith(oldHome + '/') && !oldNode.startsWith(ncRoot + '/')) fail('runtime belongs to the former login home; select an isolated runtime before migration');
+  const sudo = run('/usr/bin/sudo', ['-n', '-l', '-U', oldUser], { encoding: 'utf8', shell: false, timeout: 10000,
+    env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin', LANG: 'C' } });
+  if (!loginMove && !sudo.error && (sudo.status === 0 || sudo.status !== 1)) fail('legacy account has sudo authority or its sudo rules cannot be verified');
+  if (!loginMove && sudo.error && sudo.error.code !== 'ENOENT') fail('legacy sudo authority is unknown');
+  const manager = (user, userId, userHome, args) => command('/usr/sbin/runuser', ['-u', user, '--', '/usr/bin/env', '-i',
+    'PATH=/usr/sbin:/usr/bin:/sbin:/bin', `HOME=${userHome}`, `XDG_RUNTIME_DIR=/run/user/${userId}`,
+    `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/${userId}/bus`, '/usr/bin/systemctl', '--user', ...args]);
+  const oldManager = args => loginMove ? manager(oldUser, oldUid, oldHome, args) : command('/usr/bin/systemctl', args);
+  oldManager(['is-active', 'nc-client.service']);
+  // Check all rollback tools and manager reachability BEFORE stopping anything.
+  for (const exe of loginMove ? ['/usr/sbin/useradd', '/usr/sbin/userdel', '/usr/sbin/groupadd', '/usr/sbin/groupdel'] : ['/usr/sbin/usermod', '/usr/sbin/groupmod']) command(exe, ['--help']);
+  if (loginMove) {
+    const before = command('/usr/bin/loginctl', ['show-user', oldUser, '--property=Linger', '--value']).trim();
+    if (!['yes', 'no'].includes(before)) fail('old linger inventory is unknown');
+  } else if (exists(`/var/lib/systemd/linger/${oldUser}`)) fail('legacy user-manager/linger requires selected reconciliation before rename');
+  if (await authorizeMaintenance({ ...originalIdentity, ncRoot, old_user: oldUser, uid: oldUid, gid: oldGid,
+    privateKey: selectedPrivateKey, hostToken: env.NC_CLIENT_TOKEN }) !== true) fail('selected target maintenance was not authorized; held installations remain untouched');
+  const recovery = loginMove ? home : path.join(ncRoot, 'libexec');
+  if (!loginMove) {
+    io.mkdirSync(recovery, { recursive: true, mode: 0o755 });
+    const st = io.lstatSync(recovery); if (st.uid !== 0 || st.isSymbolicLink() || (st.mode & 0o022)) fail('rollback directory is not protected');
+  } else io.mkdirSync(home, { mode: 0o750 });
+  const journalPath = path.join(recovery, '.identity-maintenance.json');
+  if (exists(journalPath)) fail('an earlier identity maintenance needs recovery first');
+  const recoveryRecord = { host_id: hostId, source: ncRoot, destination, old_user: oldUser,
+    old_home: oldHome, uid: oldUid, gid: oldGid, identity: originalIdentity, unit, original_unit: unitText, original_env: envText, helper_edits: helperEdits };
+  const recordRecovery = (record, initial = false) => {
+    const target = initial ? journalPath : journalPath + '.next';
+    const fd = io.openSync(target, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try { io.writeFileSync(fd, JSON.stringify(record) + '\n'); io.fsyncSync(fd); } finally { io.closeSync(fd); }
+    if (!initial) io.renameSync(target, journalPath);
+    const directory = directoryFd(recovery);
+    try { io.fsyncSync(directory); } finally { io.closeSync(directory); }
+  };
+  recordRecovery({ ...recoveryRecord, state: 'prepared' }, true);
+  let stopped = false, accountCreated = false, groupCreated = false, renamedUser = false, renamedGroup = false, newStarted = false, managerStarted = false, retiredUnit = false, retiredEnv = false, changedHome = false;
+  const newUnit = loginMove ? path.join(home, '.config/systemd/user/nc-client.service') : unit;
+  let newUid = oldUid, newGid = oldGid;
+  try {
+    stopped = true; oldManager(['stop', 'nc-client.service']);
+    if (JSON.stringify(identity(ncRoot)) !== JSON.stringify(originalIdentity)) fail('source identity changed during preflight');
+    if (loginMove) {
+      // Open every source component with O_NOFOLLOW; root never follows a
+      // login-user replacement/symlink into another home or credential file.
+      const copy = (sourceFd, target, relative = '') => {
+        io.mkdirSync(target, { mode: 0o700 });
+        for (const name of io.readdirSync(`/proc/self/fd/${sourceFd}`)) {
+          if (!relative && !['app', 'config', 'data', 'logs', 'releases', 'backups', 'tmp', 'tools', 'install.sh', 'uninstall.sh'].includes(name)) continue;
+          const source = `/proc/self/fd/${sourceFd}/${name}`, dest = path.join(target, name);
+          const st = io.lstatSync(source);
+          if (st.isSymbolicLink()) {
+            const link = io.readlinkSync(source);
+            if (path.isAbsolute(link) || !path.resolve(ncRoot, relative, link).startsWith(ncRoot + '/')) fail('external source symlink; explicitly export the selected dependency first');
+            io.symlinkSync(link, dest); continue;
+          }
+          const fd = io.openSync(source, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+          try {
+            const before = io.fstatSync(fd);
+            if (before.uid !== oldUid && !(before.uid === 0 && (before.mode & 0o004))) fail('unrelated private source ownership');
+            if (before.isDirectory()) copy(fd, dest, path.join(relative, name));
+            else if (before.isFile()) {
+              const output = io.openSync(dest, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, before.mode & 0o777);
+              try {
+                const buffer = Buffer.alloc(65536); let count;
+                while ((count = io.readSync(fd, buffer, 0, buffer.length, null)) > 0) {
+                  let offset = 0; while (offset < count) offset += io.writeSync(output, buffer, offset, count - offset);
+                }
+              } finally { io.closeSync(output); }
+              const after = io.fstatSync(fd);
+              if (before.size !== after.size || before.ctimeMs !== after.ctimeMs) fail('source changed while copying');
+            } else fail('special files cannot be relocated');
+          } finally { io.closeSync(fd); }
+        }
+      };
+      const sourceFd = directoryFd(ncRoot);
+      const pinned = io.fstatSync(sourceFd);
+      if (pinned.ino !== rootInfo.ino || pinned.dev !== rootInfo.dev) { io.closeSync(sourceFd); fail('selected source root was replaced'); }
+      try { copy(sourceFd, destination); } finally { io.closeSync(sourceFd); }
+      if (JSON.stringify(identity(destination)) !== JSON.stringify(originalIdentity)) fail('relocation identity mismatch');
+      command('/usr/sbin/groupadd', ['--system', 'nodecommand']); groupCreated = true;
+      command('/usr/sbin/useradd', ['--system', '--gid', 'nodecommand', '--home-dir', home, '--shell', '/usr/sbin/nologin', 'nodecommand']); accountCreated = true;
+      const created = command('/usr/bin/getent', ['passwd', 'nodecommand']).trim().split(':');
+      newUid = Number(created[2]); newGid = Number(created[3]);
+      if (!Number.isSafeInteger(newUid) || newUid <= 0 || !Number.isSafeInteger(newGid) || newGid <= 0 || created[5] !== home) fail('new account inventory mismatch');
+      const rewritten = { ...parseMaintenanceEnv(read(path.join(destination, 'config/nc-client.env'))), NC_SERVICE_MODE: 'user',
+        NC_ROOT: destination, NC_SERVICE_UNIT: 'nc-client.service', NC_OPERATOR_USER: 'nodecommand', NC_SERVICE_USER: 'nodecommand', NC_SERVICE_GROUP: 'nodecommand' };
+      for (const name of ['NC_ENV_FILE', 'NC_LOG_FILE', 'NC_DEVICE_KEY_FILE', 'NC_NODE_BIN']) {
+        if (rewritten[name]?.startsWith(ncRoot + '/')) rewritten[name] = destination + rewritten[name].slice(ncRoot.length);
+      }
+      // Keep server, host, token, device key, private runtime and policy roots.
+      write(path.join(destination, 'config/nc-client.env'), Object.entries(rewritten).map(([key, value]) => `${key}=${value}`).join('\n') + '\n', 0o600);
+      const own = dir => { for (const entry of io.readdirSync(dir)) { const file = path.join(dir, entry); const st = io.lstatSync(file);
+        if (st.isSymbolicLink()) { const actual = io.realpathSync(file); if (!actual.startsWith(destination + '/')) fail('relocated symlink escapes installation'); io.lchownSync(file, newUid, newGid); }
+        else { if (st.isDirectory()) own(file); io.chownSync(file, newUid, newGid); } } };
+      own(destination); io.chownSync(destination, newUid, newGid);
+      io.chownSync(home, 0, newGid);
+      io.mkdirSync(path.join(home, 'workspace'), { mode: 0o700 }); io.chownSync(path.join(home, 'workspace'), newUid, newGid);
+      for (const relative of ['.config', '.config/systemd', '.config/systemd/user', '.cache', '.local', '.local/share']) {
+        const directory = path.join(home, relative); io.mkdirSync(directory, { mode: 0o700 }); io.chownSync(directory, newUid, newGid);
+      }
+      io.writeFileSync(newUnit, `[Unit]\nDescription=Node Command Agent\nAfter=network-online.target\n[Service]\nType=simple\nWorkingDirectory=${destination}/app\nExecStart="${node}" "${destination}/app/launcher.mjs"\nEnvironmentFile=${destination}/config/nc-client.env\nEnvironment=HOME=${home}\nEnvironment=XDG_RUNTIME_DIR=/run/user/${newUid}\nEnvironment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/${newUid}/bus\nUnsetEnvironment=SSH_AUTH_SOCK SSH_AGENT_PID SUDO_ASKPASS NODE_OPTIONS NODE_PATH LD_PRELOAD LD_LIBRARY_PATH\nNoNewPrivileges=yes\nRestart=always\nRestartSec=5\n[Install]\nWantedBy=default.target\n`, { mode: 0o600 });
+      io.chownSync(newUnit, newUid, newGid);
+      for (const socket of ['/var/run/docker.sock', '/run/podman/podman.sock', '/run/containerd/containerd.sock', '/var/lib/lxd/unix.socket', '/run/libvirt/libvirt-sock']) {
+        if (!exists(socket)) continue;
+        const access = run('/usr/sbin/runuser', ['-u', 'nodecommand', '--', '/usr/bin/test', '-w', socket], {
+          encoding: 'utf8', shell: false, timeout: 10000, env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin' } });
+        if (access.error || access.status !== 1) fail('restricted identity can access a root-equivalent IPC endpoint or its access cannot be verified');
+      }
+      command('/usr/bin/loginctl', ['enable-linger', 'nodecommand']);
+      managerStarted = true;
+      command('/usr/bin/systemctl', ['start', `user@${newUid}.service`]);
+    } else {
+      const processes = run('/usr/bin/ps', ['-u', String(oldUid), '-o', 'pid='], { encoding: 'utf8', shell: false, timeout: 10000,
+        env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin', LANG: 'C' } });
+      if (processes.error || ![0, 1].includes(processes.status) || String(processes.stdout || '').trim() || String(processes.stderr || '').trim()) fail('other legacy-account processes remain or inventory is unknown; no account rename performed');
+      command('/usr/sbin/usermod', ['--login', 'nodecommand', '_nc']); renamedUser = true;
+      command('/usr/sbin/groupmod', ['--new-name', 'nodecommand', '_nc']); renamedGroup = true;
+      const renamed = command('/usr/bin/getent', ['passwd', 'nodecommand']).trim().split(':');
+      if (renamed[0] !== 'nodecommand' || Number(renamed[2]) !== oldUid || Number(renamed[3]) !== oldGid ||
+          Number(command('/usr/bin/getent', ['group', 'nodecommand']).trim().split(':')[2]) !== oldGid) fail('account rename did not preserve UID/GID');
+      io.mkdirSync(home, { mode: 0o750 }); changedHome = true; io.chownSync(home, 0, oldGid);
+      // Change only passwd home metadata; never move an arbitrary former
+      // account home or recursively change its files/permissions.
+      command('/usr/sbin/usermod', ['--home', home, 'nodecommand']);
+      const relocated = command('/usr/bin/getent', ['passwd', 'nodecommand']).trim().split(':');
+      if (relocated[5] !== home || Number(relocated[2]) !== oldUid || Number(relocated[3]) !== oldGid) fail('new home metadata or stable UID/GID could not be verified');
+      for (const relative of ['workspace', '.config', '.config/systemd', '.config/systemd/user', '.cache', '.local', '.local/share']) {
+        const directory = path.join(home, relative); io.mkdirSync(directory, { mode: 0o700 }); io.chownSync(directory, oldUid, oldGid);
+      }
+      // Regenerate the ordinary service rather than retaining root-capable
+      // ExecStartPre/credential hooks or an old login environment.
+      write(unit, `[Unit]\nDescription=Node Command Agent\nAfter=network-online.target\n[Service]\nType=simple\nUser=nodecommand\nGroup=nodecommand\nWorkingDirectory=${ncRoot}/app\nEnvironmentFile=${envPath}\nEnvironment=HOME=${home}\nEnvironment=XDG_RUNTIME_DIR=/run/user/${oldUid}\nEnvironment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/${oldUid}/bus\nUnsetEnvironment=SSH_AUTH_SOCK SSH_AGENT_PID SUDO_ASKPASS NODE_OPTIONS NODE_PATH LD_PRELOAD LD_LIBRARY_PATH\nExecStart="${node}" "${ncRoot}/app/launcher.mjs"\nNoNewPrivileges=yes\nCapabilityBoundingSet=\nAmbientCapabilities=\nRestart=always\nRestartSec=5\n[Install]\nWantedBy=multi-user.target\n`, 0o644);
+      write(envPath, envText.replace(/^(NC_SERVICE_USER|NC_SERVICE_GROUP|NC_OPERATOR_USER)=(?:"_nc"|'_nc'|_nc)$/gm, '$1=nodecommand'), 0o600);
+      for (const edit of helperEdits) write(edit.file, edit.replacement, 0o644);
+      command('/usr/bin/loginctl', ['enable-linger', 'nodecommand']);
+      managerStarted = true;
+      command('/usr/bin/systemctl', ['start', `user@${newUid}.service`]);
+    }
+    const newManager = args => loginMove ? manager('nodecommand', newUid, home, args) : command('/usr/bin/systemctl', args);
+    newManager(['daemon-reload']); newStarted = true; newManager(['enable', '--now', 'nc-client.service']);
+    newManager(['is-active', 'nc-client.service']);
+    const currentIdentity = identity(destination);
+    if (JSON.stringify(currentIdentity) !== JSON.stringify(originalIdentity) || await verifyReconnection({ ...currentIdentity, ncRoot: destination, service_user: 'nodecommand', uid: newUid, gid: newGid,
+      privateKey: selectedPrivateKey, hostToken: env.NC_CLIENT_TOKEN }) !== true) fail('same-host reconnection not independently confirmed');
+    if (loginMove) {
+      oldManager(['disable', 'nc-client.service']);
+      const retire = (file, text) => {
+        const parent = directoryFd(path.dirname(file)); let fd;
+        try {
+          fd = io.openSync(`/proc/self/fd/${parent}/${path.basename(file)}.identity-backup`, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+          io.writeFileSync(fd, text); io.fsyncSync(fd);
+          io.unlinkSync(`/proc/self/fd/${parent}/${path.basename(file)}`);
+        } finally { if (fd !== undefined) io.closeSync(fd); io.closeSync(parent); }
+      };
+      retire(unit, unitText); retiredUnit = true;
+      retire(envPath, envText); retiredEnv = true;
+    }
+    recordRecovery({ ...recoveryRecord, state: 'verified', new_uid: newUid, new_gid: newGid });
+    return { ...currentIdentity, ncRoot: destination, service_user: 'nodecommand', uid: newUid, gid: newGid,
+      workspace: path.join(home, 'workspace'), helper_readiness: 'unavailable', existing_permission: 'preserved', rollback_journal: journalPath };
+  } catch (error) {
+    try {
+      if (newStarted) {
+        if (loginMove) manager('nodecommand', newUid, home, ['disable', '--now', 'nc-client.service']);
+        else command('/usr/bin/systemctl', ['stop', 'nc-client.service']);
+      }
+      if (loginMove) {
+        if (accountCreated) { command('/usr/bin/loginctl', ['disable-linger', 'nodecommand']); command('/usr/bin/systemctl', ['stop', `user@${newUid}.service`]); command('/usr/sbin/userdel', ['nodecommand']); }
+        if (groupCreated) command('/usr/sbin/groupdel', ['nodecommand']);
+        io.rmSync(home, { recursive: true });
+        if (retiredUnit) { write(unit, unitText, 0o600); io.chownSync(unit, oldUid, oldGid); io.unlinkSync(unit + '.identity-backup'); }
+        if (retiredEnv) { write(envPath, envText, 0o600); io.chownSync(envPath, oldUid, oldGid); io.unlinkSync(envPath + '.identity-backup'); }
+      } else {
+        if (managerStarted) { command('/usr/bin/loginctl', ['disable-linger', 'nodecommand']); command('/usr/bin/systemctl', ['stop', `user@${oldUid}.service`]); }
+        if (changedHome) { command('/usr/sbin/usermod', ['--home', oldHome, 'nodecommand']); io.rmSync(home, { recursive: true }); }
+        if (renamedGroup) command('/usr/sbin/groupmod', ['--new-name', '_nc', 'nodecommand']);
+        if (renamedUser) command('/usr/sbin/usermod', ['--login', '_nc', 'nodecommand']);
+        write(unit, unitText, 0o644); write(envPath, envText, 0o600);
+        for (const edit of helperEdits) write(edit.file, edit.text, 0o644);
+        command('/usr/bin/systemctl', ['daemon-reload']);
+      }
+      if (stopped) oldManager(['start', 'nc-client.service']);
+      if (!loginMove) io.rmSync(journalPath);
+    } catch { throw new Error('IDENTITY_MAINTENANCE_ROLLBACK_REQUIRED: preserve the protected recovery journal; do not rerun installation or replace credentials', { cause: error }); }
+    throw error;
+  }
+}
+
 /**
  * Uninstaller script living inside an installed tree. The scripts are
  * self-locating ($ROOT derived from their own path), so no root argument is
@@ -255,8 +915,8 @@ export function uninstallerForRoot(root, platform = os.platform()) {
 }
 
 /**
- * Suggested-action line printed when an uninstaller fails. The unix text
- * names the direct recovery command; win32 keeps the generic wording because
+ * Suggested-action line printed when an uninstaller fails. The Unix text
+ * requires trusted maintenance, never implicit sudo; win32 keeps the generic wording because
  * the .ps1 uninstaller already runs with the caller's own rights (no sudo
  * equivalent is attempted there).
  * @param {string} [platform]
@@ -264,31 +924,28 @@ export function uninstallerForRoot(root, platform = os.platform()) {
 export function uninstallFailureSuggestion(platform = os.platform()) {
   const base = 'Re-run with administrator/root rights, then retry.';
   if (platform === 'win32') return `suggested_action: ${base}`;
-  return `suggested_action: ${base} (or run: sudo nodecommand remove --yes)`;
+  return 'suggested_action: Use explicitly trusted root maintenance for system removal. Do not sudo an ordinary-writable CLI or uninstall script; preserve the protected tree/journal until managed-work cleanup is verified.';
 }
 
+/** User-mode authority comes from the selected tree, not the caller's UID. */
+export function isUserInstallRoot(root) {
+  try {
+    return /^NC_SERVICE_MODE=user\r?$/m.test(fs.readFileSync(path.join(root, 'config', 'nc-client.env'), 'utf8').replace(/^\uFEFF/, ''));
+  } catch {
+    return false;
+  }
+}
+
+export const LINUX_PAIRED_UNINSTALL_ENTRY = '/opt/nc/libexec/privileged-helper/install/uninstall-linux.sh';
+
 /**
- * Runs one uninstaller script, forwarding the inherited environment.
- *
- * Unix elevation: a system-wide tree is installed by root, so its
- * uninstaller is root-owned (mode 0700) and a non-root caller cannot even
- * read it — plain `bash <script>` always fails there with status 126. When
- * the caller is not root the script is therefore run via `sudo -E bash`,
- * keeping `stdio: 'inherit'` so the sudo password prompt stays visible.
- * When sudo itself is missing (ENOENT) the direct call is retried once so
- * user-owned trees stay removable without sudo; any other sudo failure
- * propagates unchanged and the caller reports the usual [UNINSTALL_FAILED]
- * guidance — behavior never gets worse, it only starts working when sudo
- * exists. Already-root callers run the script directly (no sudo).
- *
- * Security boundary: the caller (runRemove) only ever passes the
- * uninstallerForRoot() path of a tree that already passed the
- * isInstallRoot() check inside findInstallations() — elevation is never
- * applied to an arbitrary path. Windows is untouched: the .ps1 uninstaller
- * runs with the caller's own rights, so no elevation is attempted there.
+ * Discovery markers are not execution trust. POSIX removal never elevates:
+ * an ordinary caller may execute only its own user tree; root may execute
+ * only a protected system script through a protected absolute interpreter.
+ * Never forward startup hooks or loader/environment authority to that shell.
  * @param {string} scriptPath
  * @param {string|{ platform?: string, execFile?: (cmd: string, args: string[], opts?: object) => unknown, getuid?: (() => number)|null }} [platform]
- * @param {{ execFile?: (cmd: string, args: string[], opts?: object) => unknown, getuid?: (() => number)|null }} [options]
+  * @param {{ execFile?: (cmd: string, args: string[], opts?: object) => unknown, getuid?: (() => number)|null, geteuid?: (() => number)|null, io?: typeof fs }} [options]
  */
 export function runUninstallerScript(scriptPath, platform = os.platform(), options = {}) {
   let opts = options || {};
@@ -309,7 +966,7 @@ export function runUninstallerScript(scriptPath, platform = os.platform(), optio
     typeof opts.getuid === 'function'
       ? opts.getuid
       : typeof process.getuid === 'function'
-        ? () => process.getuid()
+         ? () => process.geteuid?.() ?? process.getuid()
         : null;
   let uid = null;
   try {
@@ -317,17 +974,48 @@ export function runUninstallerScript(scriptPath, platform = os.platform(), optio
   } catch {
     uid = null;
   }
-  if (uid === 0) {
-    execFile('bash', [scriptPath], { stdio: 'inherit' });
-    return;
-  }
+  const io = opts.io || fs;
+  const denied = () => Object.assign(new Error('TRUSTED_ROOT_MAINTENANCE_REQUIRED: refusing untrusted uninstall execution; preserve the selected tree and use explicitly trusted maintenance.'), { code: 'TRUSTED_ROOT_MAINTENANCE_REQUIRED' });
+  const pairedEntry = platform === 'linux' && scriptPath === LINUX_PAIRED_UNINSTALL_ENTRY;
+  if (!Number.isSafeInteger(uid) || uid < 0 || !path.isAbsolute(scriptPath) || path.resolve(scriptPath) !== scriptPath || (!pairedEntry && path.basename(scriptPath) !== 'uninstall.sh')) throw denied();
+  const root = path.dirname(scriptPath);
+  let userMode = false;
+  if (!pairedEntry) try { userMode = /^NC_SERVICE_MODE=user\r?$/m.test(io.readFileSync(path.join(root, 'config/nc-client.env'), 'utf8').replace(/^\uFEFF/, '')); } catch {}
+  const env = { PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'C', LC_ALL: 'C' };
+  const protectedPath = (file, executable = false, checkAcl = true) => {
+    if (io.realpathSync(file) !== file) throw denied();
+    for (let current = file; ; current = path.dirname(current)) {
+      const st = io.lstatSync(current);
+      // Linux POSIX ACL write grants are bounded by the group-class mask.
+      if (st.isSymbolicLink() || st.uid !== 0 || (pairedEntry && st.gid !== 0) || (st.mode & 0o022) ||
+          (current === file ? !st.isFile() || st.nlink !== 1 || (executable && !(st.mode & 0o111)) : !st.isDirectory())) throw denied();
+      if (platform === 'darwin' && checkAcl) {
+        const ls = io.realpathSync('/bin/ls');
+        protectedPath(ls, true, false);
+        const acl = execFile(ls, ['-lde', current], { env, encoding: 'utf8' });
+        if (typeof acl !== 'string' || !acl.trim() || acl.trim().split(/\r?\n/).length !== 1) throw denied();
+      }
+      if (current === path.dirname(current)) break;
+    }
+  };
   try {
-    execFile('sudo', ['-E', 'bash', scriptPath], { stdio: 'inherit' });
-  } catch (err) {
-    // Without a sudo binary there is nothing to elevate with: retry the
-    // historical direct call so user-owned trees stay removable. Any other
-    // sudo failure (denied, wrong password, script error) propagates.
-    if (!err || err.code !== 'ENOENT') throw err;
-    execFile('bash', [scriptPath], { stdio: 'inherit' });
+    if (pairedEntry && ((opts.getuid || process.getuid)?.() !== 0 || (opts.geteuid || process.geteuid)?.() !== 0)) throw denied();
+    if (uid === 0) {
+      if (userMode) throw denied();
+      protectedPath(scriptPath);
+    } else {
+      if (!userMode || io.realpathSync(root) !== root) throw denied();
+      for (const [file, directory] of [[root, true], [scriptPath, false]]) {
+        const st = io.lstatSync(file);
+        if (st.isSymbolicLink() || st.uid !== uid || (directory ? !st.isDirectory() : !st.isFile() || st.nlink !== 1)) throw denied();
+      }
+      env.HOME = os.userInfo().homedir;
+    }
+    const bash = io.realpathSync('/bin/bash');
+    protectedPath(bash, true);
+    execFile(bash, ['--noprofile', '--norc', '-p', '--', scriptPath], { stdio: 'inherit', env, cwd: '/' });
+  } catch (error) {
+    if (error?.status !== undefined || error?.code === 'TRUSTED_ROOT_MAINTENANCE_REQUIRED') throw error;
+    throw denied();
   }
 }