node-command 2.0.8 → 2.0.10

package/bin/nc.mjs

@@ -21,9 +21,11 @@ import {
   getNcRootForMode,
   installerEnvForMode,
   isElevated,
+  isPartialSystemRemovalCandidate,
   isPartialUserRemovalCandidate,
   isUserInstallRoot,
   probeInstallRoot,
+  removePartialSystemRoot,
   removePartialUserRoot,
   resolveExecutable,
   setupTarget,
@@ -1527,6 +1529,75 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
   }
 }
 
+/**
+ * Fetches the device-authenticated install context for the protected helper.
+ * The control plane supplies only client/tenant/control-plane identity; the
+ * trust anchor (pin + digest) is the OTA-signed runtime release. The response
+ * must be exactly {tenant_id, control_plane_id}: any pin or extra field is
+ * rejected. A missing/incomplete response is a non-fatal warning: ordinary
+ * enrollment continues without the helper.
+ */
+async function fetchPrivilegedInstallContext({ baseUrl, hostId, hostToken, privateKey }) {
+  const contextUrl = `${baseUrl}/api/clients/${encodeURIComponent(hostId)}/privileged-helper/context`;
+  try {
+    assertCredentialOrigin(contextUrl, { label: 'helper context URL', action: 'fetch' });
+    const data = await fetchJson(contextUrl, buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, contextUrl));
+    const fields = ['tenant_id', 'control_plane_id'];
+    const tenantId = typeof data?.tenant_id === 'string' ? data.tenant_id.trim() : '';
+    const controlPlaneId = typeof data?.control_plane_id === 'string' ? data.control_plane_id.trim() : '';
+    if (!data || typeof data !== 'object' || Array.isArray(data) ||
+        Object.keys(data).length !== fields.length || !fields.every((field) => Object.hasOwn(data, field)) ||
+        !tenantId || !controlPlaneId || tenantId.length > 256 || controlPlaneId.length > 256) {
+      console.warn('Warning: the control plane did not return the identity-only helper install context (tenant id, control-plane id) and no pin is accepted from device auth. Continuing ordinary enrollment without the privileged helper; re-run setup after the control plane advertises the helper context endpoint.');
+      return null;
+    }
+    return { client_id: hostId, tenant_id: tenantId, control_plane_id: controlPlaneId };
+  } catch (err) {
+    const detail = sanitizeForDisplay(err instanceof Error ? err.message : String(err), 200);
+    console.warn(`Warning: could not obtain the helper install context (${detail}). Continuing ordinary enrollment without the privileged helper; re-run setup with root consent after the control plane adds the /privileged-helper/context endpoint.`);
+    return null;
+  }
+}
+
+/**
+ * Publishes the locally generated helper public key as a pending candidate.
+ * Only the public key is sent; a failure never rolls back the installed agent.
+ */
+async function publishPrivilegedHelperCandidate({ root, baseUrl, hostId, hostToken, privateKey }) {
+  const publicKeyPath = path.join(root, 'libexec', 'privileged-helper', 'privileged-helper-public.pem');
+  let pem;
+  try {
+    const info = fs.lstatSync(publicKeyPath);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('not a regular file');
+    pem = fs.readFileSync(publicKeyPath, 'utf8');
+  } catch {
+    return { published: false, warning: 'Admin remains pending; candidate publication failed: protected helper public key not found.' };
+  }
+  try {
+    const publicKey = crypto.createPublicKey(pem);
+    if (publicKey.asymmetricKeyType !== 'ed25519') throw new Error('helper public key is not Ed25519');
+    const candidateUrl = `${baseUrl}/api/clients/${encodeURIComponent(hostId)}/privileged-helper/candidate`;
+    assertCredentialOrigin(candidateUrl, { label: 'helper candidate URL', action: 'publish' });
+    const proof = createDeviceProofCli({ privateKey, hostId, method: 'POST', url: candidateUrl, credential: hostToken });
+    const res = await postJson(
+      candidateUrl,
+      { public_key: pem },
+      { Authorization: `NC-Device ${hostToken}`, 'NC-Device-Proof': proof }
+    );
+    if (res.status < 200 || res.status >= 300) {
+      throw new Error(sanitizeForDisplay(res.data?.error || `HTTP ${res.status}`, 120));
+    }
+    const keyId = crypto.createHash('sha256').update(publicKey.export({ type: 'spki', format: 'der' })).digest('hex');
+    return { published: true, fingerprint: `sha256:${keyId}` };
+  } catch (err) {
+    const detail = sanitizeForDisplay(err instanceof Error ? err.message : String(err), 200);
+    return {
+      published: false,
+      warning: `Admin remains pending; candidate publication failed: ${detail}. The agent is installed without the Admin helper; approve the helper candidate from the dashboard once the control plane accepts it.`
+    };
+  }
+}
+
 /**
  * Downloads, verifies, extracts, and installs the agent package. Writes NO
  * credentials — the env file must already exist before this runs.
@@ -1552,13 +1623,15 @@ 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, downloadTimeoutMs?: number }} options
+ * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', rootConsent?: boolean, runInstaller?: (scriptPath: string, ncRoot: string, env?: Record<string, string>) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject, downloadTimeoutMs?: number }} options
+ * @returns {Promise<{ helperCandidate: { published: boolean, fingerprint?: string, warning?: string }|null }>} `helperCandidate` is null when no helper was requested.
  */
 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 =
-    runInstaller || ((scriptPath, root) => runInstallerScript(scriptPath, root, modeEnv));
+  const helperRequested = rootConsent === true && installMode !== 'user' && os.platform() === 'linux';
+  const invokeInstaller = (scriptPath, installRoot) =>
+    runInstaller ? runInstaller(scriptPath, installRoot, modeEnv) : runInstallerScript(scriptPath, installRoot, modeEnv);
   const root = ncRoot;
   console.log(`📍 Installation root: ${root}`);
 
@@ -1769,6 +1842,68 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
       throw new PairingError('INSTALL_SCRIPT_MISSING', `Installation script not found: ${scriptPath}.`);
     }
 
+    if (helperRequested) {
+      const runtimePackageUrl = (() => {
+        const raw = usableUrl(activeRelease.package_url) || usableUrl(activeRelease.download_url);
+        if (!raw) return null;
+        try {
+          return new URL(raw, defaultBaseUrl).toString();
+        } catch {
+          return null;
+        }
+      })();
+      const runtimeSha = typeof activeRelease.sha256 === 'string' ? activeRelease.sha256.toLowerCase() : '';
+      const runtimeSize = activeRelease.size_bytes;
+      const runtimeSignature = typeof activeRelease.signature === 'string' ? activeRelease.signature.trim() : '';
+      const runtimeVersion = typeof version === 'string' ? version : '';
+      const helperPrereqsReady =
+        hasDeviceIdentity &&
+        runtimePackageUrl &&
+        /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(runtimeVersion) &&
+        /^[a-f0-9]{64}$/.test(runtimeSha) &&
+        Number.isSafeInteger(runtimeSize) && runtimeSize > 0 &&
+        /^[A-Za-z0-9_-]{86}$/.test(runtimeSignature);
+      if (!helperPrereqsReady) {
+        console.warn('Warning: the release does not carry a complete signed runtime package (version, package URL, sha256, size, signature) or this setup has no device identity. Continuing ordinary User enrollment without the privileged helper.');
+      } else {
+        const context = await fetchPrivilegedInstallContext({ baseUrl: defaultBaseUrl, hostId, hostToken, privateKey });
+        if (context) {
+          // Fetch the runtime archive with the device credential here; the root
+          // installer must never need a client token and cannot fetch the
+          // authenticated package endpoint itself.
+          const runtimeArchivePath = path.join(tempDir, 'client.tar.gz');
+          try {
+            assertCredentialOrigin(runtimePackageUrl, { label: 'runtime release URL', action: 'fetch' });
+            if (!isSameOrigin(runtimePackageUrl, defaultBaseUrl)) {
+              throw new Error('runtime release URL is not on the trusted enrollment origin');
+            }
+            const download = await downloadToFile(
+              runtimePackageUrl,
+              runtimeArchivePath,
+              buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, runtimePackageUrl),
+              { maxBytes: getCliMaxPackageBytes(), timeoutMs: downloadTimeoutMs ?? getCliDownloadTimeoutMs() }
+            );
+            if (download.bytes !== runtimeSize || download.sha256.toLowerCase() !== runtimeSha) {
+              throw new Error('runtime release archive does not match the signed digest/size');
+            }
+            modeEnv.NC_PRIVILEGED_INSTALL_CONTEXT = JSON.stringify(context);
+            modeEnv.NC_PRIVILEGED_ARCHIVE_FILE = runtimeArchivePath;
+            modeEnv.NC_PRIVILEGED_RELEASE_VERSION = runtimeVersion;
+            modeEnv.NC_PRIVILEGED_RELEASE_URL = runtimePackageUrl;
+            modeEnv.NC_PRIVILEGED_RELEASE_SHA256 = runtimeSha;
+            modeEnv.NC_PRIVILEGED_RELEASE_SIZE = String(runtimeSize);
+            modeEnv.NC_PRIVILEGED_RELEASE_SIGNATURE = runtimeSignature;
+            // The installer compares the archive URL origin with the enrollment
+            // server origin. modeEnv values win over inherited NC_* variables.
+            modeEnv.NC_SERVER_URL = defaultBaseUrl;
+          } catch (err) {
+            const detail = sanitizeForDisplay(err instanceof Error ? err.message : String(err), 200);
+            console.warn(`Warning: could not prepare the signed runtime release for the privileged helper (${detail}). Continuing ordinary User enrollment without the privileged helper.`);
+          }
+        }
+      }
+    }
+
     try {
       invokeInstaller(scriptPath, root);
     } catch (err) {
@@ -1783,6 +1918,21 @@ export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl =
     console.log('🧹 Cleaning up temporary directory...');
     cleanup();
   }
+
+  let helperCandidate = null;
+  if (helperRequested && hasDeviceIdentity) {
+    helperCandidate = await publishPrivilegedHelperCandidate({
+      root,
+      baseUrl: defaultBaseUrl,
+      hostId,
+      hostToken,
+      privateKey
+    });
+    if (helperCandidate.published === false && helperCandidate.warning) {
+      console.warn(`Warning: ${helperCandidate.warning}`);
+    }
+  }
+  return { helperCandidate };
 }
 
 /**
@@ -1837,7 +1987,7 @@ export async function pairDeviceAndInstall({
   const installAgent =
     hooks.installAgent ||
     (async ({ ncRoot: installRoot, serverUrl: installServerUrl, release: installRelease = undefined, hostId: installHostId = undefined, hostToken: installHostToken = undefined, privateKey: installPrivateKey = undefined }) => {
-      await downloadAndInstallAgent({ ncRoot: installRoot, serverUrl: installServerUrl, installMode, rootConsent: selectedRootConsent, release: installRelease, hostId: installHostId, hostToken: installHostToken, privateKey: installPrivateKey });
+      return await downloadAndInstallAgent({ ncRoot: installRoot, serverUrl: installServerUrl, installMode, rootConsent: selectedRootConsent, release: installRelease, hostId: installHostId, hostToken: installHostToken, privateKey: installPrivateKey });
     });
   let selectedRootConsent = false;
 
@@ -1874,7 +2024,7 @@ export async function pairDeviceAndInstall({
           return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true };
         }
         console.log(`🔁 Resuming installation for host ${localEnv.NC_CLIENT_ID} (stored credentials verified)...`);
-        await installAgent({ ncRoot: root, serverUrl: storedServerUrl, hostId: localEnv.NC_CLIENT_ID, hostToken: localEnv.NC_CLIENT_TOKEN, privateKey: localKey.privateKey });
+        const installOutcome = await installAgent({ ncRoot: root, serverUrl: storedServerUrl, hostId: localEnv.NC_CLIENT_ID, hostToken: localEnv.NC_CLIENT_TOKEN, privateKey: localKey.privateKey });
         writePairState(statePath, { host_id: localEnv.NC_CLIENT_ID, phase: 'installed' });
         await verifyHostRegistration({
           apiBase: localEnv.NC_SERVER_URL,
@@ -1885,7 +2035,8 @@ export async function pairDeviceAndInstall({
           intervalMs: verifyIntervalMs
         });
         writePairState(statePath, { host_id: localEnv.NC_CLIENT_ID, phase: 'verified' });
-        return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true };
+        return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true,
+          helperCandidate: installOutcome?.helperCandidate ?? null };
       } catch (err) {
         // Failure at the bound destination is not permission to enroll on
         // another server or replace this installed host identity.
@@ -1954,7 +2105,7 @@ export async function pairDeviceAndInstall({
   writePairState(statePath, { host_id: hostId, phase: 'redeemed' });
 
   console.log('🚀 Installing agent...');
-  await installAgent({ ncRoot: root, serverUrl: enrollServerUrl, release: redemptionRelease, hostId, hostToken, privateKey: keyPair.privateKey, rootConsent: selectedRootConsent });
+  const installOutcome = 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 at ${sanitizeForDisplay(enrollServerUrl, 256)}...`);
@@ -1971,7 +2122,8 @@ export async function pairDeviceAndInstall({
   });
   writePairState(statePath, { host_id: hostId, phase: 'verified' });
   return { hostId, serverUrl: enrollServerUrl, resumed: false, version: agentVersion, rootConsent: selectedRootConsent,
-    privilegeReadiness: selectedRootConsent ? 'pending' : 'unavailable', executionInitialization };
+    privilegeReadiness: selectedRootConsent ? 'pending' : 'unavailable', executionInitialization,
+    helperCandidate: installOutcome?.helperCandidate ?? null };
 }
 
 /**
@@ -2233,9 +2385,9 @@ function getCliVersion() {
 /**
  * Prints the one-line install summary required after a successful setup:
  * host id, install mode, CLI version, and verification status.
- * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null, rootConsent?: boolean, ncRoot?: string, executionInitialization?: any }} options
+ * @param {{ hostId: string, serverUrl: string, installMode?: 'system'|'user', resumed?: boolean, version?: string|null, rootConsent?: boolean, ncRoot?: string, executionInitialization?: any, helperCandidate?: { published: boolean, fingerprint?: string, warning?: string }|null }} options
  */
-export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null }) {
+export function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed = false, version = null, rootConsent = false, ncRoot = undefined, executionInitialization = null, helperCandidate = null }) {
   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: ${sanitizeForDisplay(version, 120)}`);
@@ -2249,7 +2401,17 @@ export function printSetupSuccess({ hostId, serverUrl, installMode = undefined,
     console.log('execution permission: existing choice preserved; no privilege maintenance performed');
   } else {
     console.log(`root command consent: ${rootConsent === true ? 'Yes' : 'No'}`);
-    console.log(`local privilege readiness: ${rootConsent === true ? 'pending independent management approval and protected helper binding' : 'unavailable (not requested)'}`);
+    if (rootConsent !== true) {
+      console.log('local privilege readiness: unavailable (not requested)');
+    } else if (helperCandidate && helperCandidate.published === true) {
+      const match = /^sha256:([0-9a-f]{64})$/i.exec(String(helperCandidate.fingerprint || ''));
+      const shortFingerprint = match ? `sha256:${match[1].slice(0, 16).toLowerCase()}` : null;
+      console.log(`local privilege readiness: Admin pending: approve the helper candidate in the dashboard${shortFingerprint ? ` (fingerprint: ${shortFingerprint})` : ''}`);
+    } else if (helperCandidate && typeof helperCandidate.warning === 'string' && helperCandidate.warning) {
+      console.log(`local privilege readiness: ${helperCandidate.warning}`);
+    } else {
+      console.log('local privilege readiness: pending independent management approval and protected helper binding');
+    }
     const receipt = executionInitialization;
     const fields = ['outcome', 'reason', 'subject_user_id', 'permission'];
     const reasons = { requested: ['admin_requested'], preserved: ['existing_permission_preserved', 'existing_host_preserved'],
@@ -2960,11 +3122,17 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
     // A failed per-user install can leave its own tree (config plus partial
     // payload) without the packaged uninstaller. Only the canonical user root
     // is eligible, and the bounded removal revalidates ancestry, ownership and
-    // every top-level entry. System/protected roots never use this fallback.
+    // every top-level entry. Real system installs never use this fallback;
+    // the exact /opt/nc partial tree has its own narrower root-only exception.
     const scriptExists = pair || fs.existsSync(script);
-    const boundedUserTree = !scriptExists &&
-      (command === 'uninstall' || command === 'remove') && isPartialUserRemovalCandidate(root);
-    if (!scriptExists && !boundedUserTree) {
+    const explicitRemoval = command === 'uninstall' || command === 'remove';
+    const partialUserTree = !scriptExists && explicitRemoval && isPartialUserRemovalCandidate(root);
+    // The narrow system exception is /opt/nc only, requires real+effective
+    // root, and refuses app/, uninstall.sh, units, libexec/ and lifecycle
+    // metadata inside removePartialSystemRoot.
+    const partialSystemTree = !scriptExists && explicitRemoval && isPartialSystemRemovalCandidate(root);
+    const boundedTree = partialUserTree || partialSystemTree;
+    if (!scriptExists && !boundedTree) {
       console.error(`error: [UNINSTALLER_MISSING] uninstaller not found at ${script}; skipping ${root}.`);
       console.error(uninstallFailureSuggestion());
       failed += 1;
@@ -2979,13 +3147,19 @@ async function runRemoval(args, { command, emptyMessage, elevateOnWindows = fals
       continue;
     }
     try {
-      if (boundedUserTree) {
+      if (boundedTree) {
         try {
-          removePartialUserRoot(root);
-          console.log(`Removed partial per-user Node Command installation at ${root} (no packaged uninstaller was present).`);
+          if (partialSystemTree) removePartialSystemRoot(root);
+          else removePartialUserRoot(root);
+          console.log(partialSystemTree
+            ? `Removed partial system Node Command installation at ${root} (no packaged uninstaller, unit or application payload).`
+            : `Removed partial per-user Node Command installation at ${root} (no packaged uninstaller was present).`);
         } catch (err) {
-          console.error(`error: [USER_TREE_REMOVAL_REFUSED] ${sanitizeForDisplay(err instanceof Error ? err.message : String(err), 300)}`);
-          console.error('suggested_action: The tree was left untouched. Repair it with `nodecommand --user`, or remove it yourself after confirming it is your own Node Command directory.');
+          const code = typeof err?.code === 'string' && /_REFUSED$/.test(err.code) ? err.code : 'PARTIAL_ROOT_REMOVAL_REFUSED';
+          console.error(`error: [${code}] ${sanitizeForDisplay(err instanceof Error ? err.message : String(err), 300)}`);
+          console.error(partialSystemTree
+            ? 'suggested_action: The system tree was left untouched. Inspect /opt/nc and complete or repair the failed system installation through explicit root maintenance; credentials/config were preserved.'
+            : 'suggested_action: The tree was left untouched. Repair it with `nodecommand --user`, or remove it yourself after confirming it is your own Node Command directory.');
           failed += 1;
         }
         continue;

package/lib/setup.mjs

@@ -450,6 +450,26 @@ const USER_INSTALL_ENTRIES = new Set([
   'uninstall.sh'
 ]);
 
+/** Canonical system root eligible only for a narrow, root-only cleanup. */
+export const PARTIAL_SYSTEM_ROOT = '/opt/nc';
+
+/** A failed system install may leave only these payload/config directories. */
+const PARTIAL_SYSTEM_ENTRIES = new Set(['config', 'tools', 'logs', 'tmp', 'releases', 'backups']);
+
+/** Artifacts that prove a real system installation exists; never bypassed. */
+const PARTIAL_SYSTEM_FORBIDDEN_PATHS = [
+  '/etc/systemd/system/nc-client.service',
+  '/etc/systemd/system/nc-client.service.d',
+  '/etc/systemd/user/nc-client.service',
+  '/etc/systemd/user/nc-client.service.d',
+  '/etc/systemd/system/multi-user.target.wants/nc-client.service',
+  '/etc/systemd/system/nc-privileged-helper.service',
+  '/etc/systemd/system/nc-privileged-helper.socket',
+  '/etc/tmpfiles.d/nc-privileged-helper.conf',
+  '/var/lib/nc-lifecycle',
+  '/var/lib/nodecommand/nc'
+];
+
 /**
  * True when `root` is the canonical per-user tree for the current account and
  * is not a protected system root. This is the cheap path/ownership gate; the
@@ -475,6 +495,52 @@ export function isPartialUserRemovalCandidate(root, { platform = os.platform(),
   );
 }
 
+/**
+ * True only for the exact Linux system root when the process holds real AND
+ * effective root. The tree contents and every real-install artifact are
+ * checked again inside `removePartialSystemRoot`.
+ * @param {string} root
+ * @param {{ platform?: string, getuid?: (() => number)|null, geteuid?: (() => number)|null }} [options]
+ */
+export function isPartialSystemRemovalCandidate(root, { platform = os.platform(), getuid = process.getuid, geteuid = process.geteuid } = {}) {
+  if (platform !== 'linux') return false;
+  if (typeof getuid !== 'function' || typeof geteuid !== 'function') return false;
+  try {
+    if (getuid() !== 0 || geteuid() !== 0) return false;
+  } catch {
+    return false;
+  }
+  return path.resolve(root) === PARTIAL_SYSTEM_ROOT;
+}
+
+/** Shared bounded removal of an already-authorized root. */
+function removeBoundedRoot(root, { uid, allowedEntries, io, refused, owner }) {
+  const resolved = path.resolve(root);
+  if (io.realpathSync(resolved) !== resolved) throw refused('a symlinked ancestor is not removable');
+  const rootInfo = io.lstatSync(resolved);
+  if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) throw refused('the root is not a regular directory');
+  if (rootInfo.uid !== uid) throw refused(`the root is not owned by ${owner}`);
+  const entries = io.readdirSync(resolved);
+  for (const name of entries) {
+    if (!allowedEntries.has(name)) throw refused(`unexpected top-level entry "${name}"`);
+    const info = io.lstatSync(path.join(resolved, name));
+    if (info.isSymbolicLink()) throw refused(`top-level entry "${name}" is a symlink`);
+    if (info.uid !== uid) throw refused(`top-level entry "${name}" is not owned by ${owner}`);
+  }
+  for (const [file, directory] of [['config', true], [path.join('config', 'nc-client.env'), false]]) {
+    const info = io.lstatSync(path.join(resolved, file));
+    if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())) {
+      throw refused(`the ${file} marker is missing or not a regular ${directory ? 'directory' : 'file'}`);
+    }
+    if (info.uid !== uid) throw refused(`the ${file} marker is not owned by ${owner}`);
+  }
+  io.accessSync(path.join(resolved, 'config', 'nc-client.env'), fs.constants.R_OK);
+  for (const name of entries) {
+    io.rmSync(path.join(resolved, name), { recursive: true, force: true });
+  }
+  io.rmdirSync(resolved);
+}
+
 /**
  * Bounded removal of a per-user Node Command tree whose packaged `uninstall.sh`
  * is missing (a partial/failed install). Only the canonical per-user root is
@@ -494,33 +560,55 @@ export function removePartialUserRoot(root, { platform = os.platform(), env = pr
   if (!isPartialUserRemovalCandidate(root, { platform, env, homedir, uid })) {
     throw refused('it is not the canonical per-user Node Command root');
   }
-  const resolved = path.resolve(root);
   try {
-    if (io.realpathSync(resolved) !== resolved) throw refused('a symlinked ancestor is not removable');
-    const rootInfo = io.lstatSync(resolved);
-    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) throw refused('the root is not a regular directory');
-    if (rootInfo.uid !== uid) throw refused('the root is not owned by the current user');
-    const entries = io.readdirSync(resolved);
-    for (const name of entries) {
-      if (!USER_INSTALL_ENTRIES.has(name)) throw refused(`unexpected top-level entry "${name}"`);
-      const info = io.lstatSync(path.join(resolved, name));
-      if (info.isSymbolicLink()) throw refused(`top-level entry "${name}" is a symlink`);
-      if (info.uid !== uid) throw refused(`top-level entry "${name}" is not owned by the current user`);
-    }
-    for (const [file, directory] of [['config', true], [path.join('config', 'nc-client.env'), false]]) {
-      const info = io.lstatSync(path.join(resolved, file));
-      if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())) {
-        throw refused(`the ${file} marker is missing or not a regular ${directory ? 'directory' : 'file'}`);
+    removeBoundedRoot(root, {
+      uid,
+      allowedEntries: USER_INSTALL_ENTRIES,
+      io,
+      refused,
+      owner: 'the current user'
+    });
+  } catch (err) {
+    if (err?.code === 'USER_TREE_REMOVAL_REFUSED') throw err;
+    throw refused(err instanceof Error ? err.message : 'the tree could not be verified');
+  }
+}
+
+/**
+ * Root-only bounded removal of a failed SYSTEM install at /opt/nc. This is not
+ * a general system-root fallback: it requires real+effective root, the exact
+ * canonical root, no unit/helper/lifecycle artifact, and only the known partial
+ * payload directories. A real or unverifiable installation stays fail-closed.
+ * @param {string} root
+ * @param {{ platform?: string, getuid?: (() => number)|null, geteuid?: (() => number)|null, io?: typeof fs }} [options]
+ */
+export function removePartialSystemRoot(root, { platform = os.platform(), getuid = process.getuid, geteuid = process.geteuid, io = fs } = {}) {
+  const refused = (reason) => Object.assign(
+    new Error(`Refusing bounded removal of ${root}: ${reason}.`),
+    { code: 'PARTIAL_SYSTEM_REMOVAL_REFUSED' }
+  );
+  if (!isPartialSystemRemovalCandidate(root, { platform, getuid, geteuid })) {
+    throw refused('it is not the canonical partial system root');
+  }
+  try {
+    for (const file of PARTIAL_SYSTEM_FORBIDDEN_PATHS) {
+      try {
+        io.lstatSync(file);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw refused(`existing installation state at ${file} cannot be verified`);
       }
-      if (info.uid !== uid) throw refused(`the ${file} marker is not owned by the current user`);
+      throw refused(`${file} exists; a real installation requires its packaged maintenance`);
     }
-    io.accessSync(path.join(resolved, 'config', 'nc-client.env'), fs.constants.R_OK);
-    for (const name of entries) {
-      io.rmSync(path.join(resolved, name), { recursive: true, force: true });
-    }
-    io.rmdirSync(resolved);
+    removeBoundedRoot(path.resolve(root), {
+      uid: 0,
+      allowedEntries: PARTIAL_SYSTEM_ENTRIES,
+      io,
+      refused,
+      owner: 'root'
+    });
   } catch (err) {
-    if (err?.code === 'USER_TREE_REMOVAL_REFUSED') throw err;
+    if (err?.code === 'PARTIAL_SYSTEM_REMOVAL_REFUSED') throw err;
     throw refused(err instanceof Error ? err.message : 'the tree could not be verified');
   }
 }

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "node-command",
-  "version": "2.0.8",
+  "version": "2.0.10",
+  "description": "Node Command CLI installer for the Node Command agent",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "bin": {
     "nc": "bin/nc.mjs",
-    "nodecommand": "bin/nc.mjs",
     "nc-agent": "bin/nc.mjs",
+    "nodecommand": "bin/nc.mjs",
     "node-command": "bin/nc.mjs"
   },
   "files": [
     "bin/",
-    "lib/"
-  ]
+    "lib/",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }