node-command 2.0.9 → 2.0.11

package/bin/nc.mjs

@@ -1529,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.
@@ -1554,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}`);
 
@@ -1771,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) {
@@ -1785,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 };
 }
 
 /**
@@ -1839,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;
 
@@ -1876,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,
@@ -1887,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.
@@ -1956,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)}...`);
@@ -1973,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 };
 }
 
 /**
@@ -2235,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)}`);
@@ -2251,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'],

package/lib/setup.mjs

@@ -296,7 +296,16 @@ function linuxPairedInstallation(io = fs) {
       } finally { io.closeSync(fd); }
     };
     check(app, true);
-    if (io.readdirSync(helperRoot + '/libexec').sort().join('\n') !== 'nc-linux-peercred\nprivileged-helper') fail();
+    const libexec = helperRoot + '/libexec';
+    const requiredLibexecEntries = ['nc-linux-peercred', 'privileged-helper'];
+    const managedSealedSnapshot = name => {
+      if (!/^privileged-helper-sealed-[0-9a-f]{64}$/.test(name)) return false;
+      const st = lstat(libexec + '/' + name);
+      return st.isDirectory() && !st.isSymbolicLink() && st.uid === 0 && st.gid === 0 && (st.mode & 0o7777) === 0o700;
+    };
+    const libexecEntries = io.readdirSync(libexec).sort();
+    if (!requiredLibexecEntries.every(name => libexecEntries.includes(name)) ||
+        !libexecEntries.every(name => requiredLibexecEntries.includes(name) || managedSealedSnapshot(name))) 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'));

package/package.json

@@ -1,16 +1,14 @@
 {
   "name": "node-command",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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",
-    "node-command": "bin/nc.mjs"
+    "nc": "./bin/nc.mjs",
+    "nodecommand": "./bin/nc.mjs"
   },
   "files": [
     "bin/",