nc-agent 0.1.1 → 0.1.4

package/README.md

@@ -2,44 +2,15 @@
 
 Node Command device pairing and agent installer.
 
-## Install
+## Usage
 
 ```bash
+# Interactive RFC 8628 pairing (8-character code displayed in terminal)
 npx nc-agent
-```
 
-This starts the browser device authorization flow (RFC 8628). It prints a
-short confirmation code and a URL — open the URL in your browser, approve the
-prompt, and the agent is enrolled, downloaded from the control plane,
-installed, and verified automatically.
+# Direct pairing with host ID and enrollment token
+npx nc-agent <host_id> <enrollment_token>
 
-```bash
-npx nc-agent setup            # explicit setup (auto system/user mode)
-npx nc-agent setup --system   # force system-level service install
-npx nc-agent setup --user     # force non-elevated user install
-npx nc-agent remove           # uninstall the agent
-npx nc-agent --diagnostics    # preview a redacted support bundle
+# Uninstall the agent from the canonical system directory
+npx nc-agent uninstall
 ```
-
-The agent runtime is **not** bundled in this package. It is downloaded from
-the control plane at install time, so a fresh `npx nc-agent` always installs
-the latest release we serve. Updates after install flow through the Node
-Command OTA channel, not npm.
-
-## Environment
-
-- `NC_BASE_URL` — auth host for the browser device flow (default `https://auth.nodecommand.app`)
-- `NC_API_URL` — agent API host for device endpoints and package downloads (default `https://agent.nodecommand.app`)
-- `NC_SERVER_URL` — agent server address written to the client env
-
-## Manual install (fallback)
-
-```bash
-git clone https://github.com/huseyincig/nc-agent.git
-cd nc-agent
-npm start
-```
-
-## License
-
-MIT — see [LICENSE](LICENSE).

package/bin/nc.mjs

@@ -10,10 +10,12 @@ import child_process from 'node:child_process';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import {
+  canElevate,
   decideInstallMode,
   findRemovalTargets,
   getNcRootForMode,
   installerEnvForMode,
+  isElevated,
   modeWarningFor,
   runUninstallerScript,
   uninstallFailureSuggestion,
@@ -218,7 +220,7 @@ export function buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, ab
  * @param {Record<string, string>} [extraHeaders]
  * @returns {Promise<import('node:http').IncomingMessage>}
  */
-function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}) {
+export function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}, options = {}) {
   if (typeof maxRedirects === 'object' && maxRedirects !== null) {
     extraHeaders = /** @type {Record<string, string>} */ (maxRedirects);
     maxRedirects = 5;
@@ -229,10 +231,13 @@ function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}) {
     }
     const u = new URL(targetUrl);
     const client = u.protocol === 'http:' ? http : https;
+    const timeoutMs = options.timeoutMs ?? getCliRequestTimeoutMs();
+    const signal = options.signal ?? (timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined);
 
     const req = client.get(
       u,
       {
+        signal,
         headers: {
           'User-Agent': 'nc-cli/0.1.0',
           Accept: '*/*',
@@ -249,7 +254,7 @@ function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}) {
           const redirectUrl = new URL(res.headers.location, targetUrl).toString();
           res.resume();
           const forwarded = isSameOrigin(targetUrl, redirectUrl) ? extraHeaders : {};
-          return resolve(httpGet(redirectUrl, maxRedirects - 1, forwarded));
+          return resolve(httpGet(redirectUrl, maxRedirects - 1, forwarded, { signal, timeoutMs }));
         }
 
         if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
@@ -269,27 +274,17 @@ function httpGet(targetUrl, maxRedirects = 5, extraHeaders = {}) {
  * Fetches and parses a JSON endpoint. The update manifest (`/api/updates`)
  * is admin-only and never takes device headers, so this stays anonymous;
  * device identity is only attached to per-client package downloads.
+ * Delegates to requestJson to enforce request timeout and response byte limits.
  * @param {string} targetUrl
  * @param {Record<string, string>} [extraHeaders]
  * @returns {Promise<any>}
  */
-async function fetchJson(targetUrl, extraHeaders = {}) {
-  const res = await httpGet(targetUrl, 5, extraHeaders);
-  return new Promise((resolve, reject) => {
-    let raw = '';
-    res.setEncoding('utf8');
-    res.on('data', (chunk) => {
-      raw += chunk;
-    });
-    res.on('end', () => {
-      try {
-        resolve(JSON.parse(raw));
-      } catch (err) {
-        reject(new Error(`Failed to parse JSON from ${targetUrl}: ${err.message}`));
-      }
-    });
-    res.on('error', reject);
-  });
+export async function fetchJson(targetUrl, extraHeaders = {}) {
+  const res = await requestJson('GET', targetUrl, null, extraHeaders);
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error(`Request to ${targetUrl} failed with status ${res.status}`);
+  }
+  return res.data;
 }
 
 /**
@@ -297,10 +292,11 @@ async function fetchJson(targetUrl, extraHeaders = {}) {
  * @param {string} targetUrl
  * @param {string} destinationPath
  * @param {Record<string, string>} [extraHeaders] Device headers for `/api/clients/...` package URLs; empty for public `/releases/...` URLs.
+ * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options]
  * @returns {Promise<string>}
  */
-async function downloadToFile(targetUrl, destinationPath, extraHeaders = {}) {
-  const res = await httpGet(targetUrl, 5, extraHeaders);
+export async function downloadToFile(targetUrl, destinationPath, extraHeaders = {}, options = {}) {
+  const res = await httpGet(targetUrl, 5, extraHeaders, options);
   return new Promise((resolve, reject) => {
     const fileStream = fs.createWriteStream(destinationPath);
     let resolved = false;
@@ -329,21 +325,24 @@ async function downloadToFile(targetUrl, destinationPath, extraHeaders = {}) {
 }
 
 /**
- * Determines the installation root (NC_ROOT) dynamically based on OS:
- * - Windows: %LOCALAPPDATA%\nc
+ * Determines the canonical installation root (NC_ROOT) dynamically based on
+ * OS:
+ * - Windows: %ProgramData%\NC (the machine-wide root; user-space
+ *   %LOCALAPPDATA%\nc is never a default — see getNcRootForMode('user'))
  * - macOS: ~/Library/Application Support/nc
  * - Linux (root): /opt/nc
  * - Linux (non-root): ~/.local/share/nc
+ * An explicit NC_ROOT always wins. Probes are injectable for deterministic
+ * tests.
+ * @param {{ platform?: string, env?: NodeJS.ProcessEnv }} [options]
  * @returns {string}
  */
-export function getNcRoot() {
-  if (process.env.NC_ROOT) {
-    return process.env.NC_ROOT;
+export function getNcRoot({ platform = os.platform(), env = process.env } = {}) {
+  if (env.NC_ROOT) {
+    return env.NC_ROOT;
   }
-  const platform = os.platform();
   if (platform === 'win32') {
-    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-    return path.join(localAppData, 'nc');
+    return path.join(env.ProgramData || 'C:\\ProgramData', 'NC');
   }
   if (platform === 'darwin') {
     return path.join(os.homedir(), 'Library', 'Application Support', 'nc');
@@ -960,8 +959,13 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
  * admin-only GET /api/updates manifest is NEVER fetched: the release already
  * carries concrete per-client bootstrap/package URLs plus integrity pins,
  * and the CLI is not an admin so the manifest would answer 401 anyway.
- * Relative URLs resolve against `serverUrl`/`NC_SERVER_URL`. Without a
- * release the legacy manifest fetch is attempted, and an admin-auth refusal
+ * Relative URLs resolve against `serverUrl`/`NC_SERVER_URL`. When no release
+ * is present but host identity (`hostId` + `hostToken` + `privateKey`) is
+ * available — the resume and already-redeemed paths — the release is
+ * resolved from the client-authenticated per-host manifest
+ * (GET /api/clients/<id>/update/manifest with NC-Device + Device Proof v1,
+ * the same identity the agent updater sends); /api/updates stays reserved
+ * for callers with no device identity at all, and an admin-auth refusal
  * surfaces an explanatory error pointing at enrollment-based setup.
  * The /api/updates endpoint stays admin-only (Caddy and control-plane are
  * intentionally untouched): opening it on the agent edge would only trade a
@@ -974,11 +978,12 @@ export async function verifyHostRegistration({ baseUrl: baseUrlOpt = undefined,
  * client token, exactly like redeemEnrollment.
  * @param {{ ncRoot?: string, updatesUrl?: string, serverUrl?: string, release?: Record<string, unknown>|null, installMode?: 'system'|'user', runInstaller?: (scriptPath: string, ncRoot: string) => void, hostId?: string, hostToken?: string, privateKey?: import('node:crypto').KeyObject }} options
  */
-export async function downloadAndInstallAgent({ ncRoot = getNcRoot(), updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined } = {}) {
+export async function downloadAndInstallAgent({ ncRoot = undefined, updatesUrl = undefined, serverUrl = undefined, release = undefined, installMode = undefined, runInstaller = undefined, hostId = undefined, hostToken = undefined, privateKey = undefined } = {}) {
+  ncRoot = ncRoot || (installMode ? getNcRootForMode(installMode) : getNcRoot());
   const modeEnv = installMode ? installerEnvForMode(installMode) : {};
   const invokeInstaller =
     runInstaller || ((scriptPath, root) => runInstallerScript(scriptPath, root, modeEnv));
-  const root = ncRoot || getNcRoot();
+  const root = ncRoot;
   console.log(`📍 Installation root: ${root}`);
 
   // Package/release resolution stays on the agent edge: an explicit
@@ -990,11 +995,39 @@ export async function downloadAndInstallAgent({ ncRoot = getNcRoot(), updatesUrl
   /** @type {Record<string, any>} */
   let activeRelease;
   if (release && typeof release === 'object') {
-    // Redemption release wins: skip the admin-only manifest entirely, so its
-    // URL is never logged as a misleading signal.
+    // Redemption release wins: skip the manifest entirely, so its URL is
+    // never logged as a misleading signal.
     activeRelease = /** @type {Record<string, any>} */ (release);
     const releaseVersion = activeRelease.version ? ` ${activeRelease.version}` : '';
     console.log(`📦 Using release${releaseVersion} from enrollment redemption; skipping update manifest.`);
+  } else if (
+    typeof hostId === 'string' &&
+    hostId &&
+    typeof hostToken === 'string' &&
+    hostToken &&
+    privateKey
+  ) {
+    // Resume paths (verified stored credentials, already-redeemed enrollment)
+    // carry no redemption release, but they DO hold device identity. Resolve
+    // the release from the client-authenticated per-host manifest the agent
+    // updater itself uses, never from the admin-only /api/updates manifest
+    // (which can only answer 401/404 to a non-admin CLI).
+    const clientManifestUrl = `${defaultBaseUrl}/api/clients/${encodeURIComponent(hostId)}/update/manifest`;
+    console.log(`📡 Fetching client update manifest from ${clientManifestUrl}...`);
+    let manifestData;
+    try {
+      manifestData = await fetchJson(
+        clientManifestUrl,
+        buildDeviceDownloadHeaders({ hostId, hostToken, privateKey }, clientManifestUrl)
+      );
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new PairingError(
+        'INSTALL_MANIFEST_ERROR',
+        `Could not fetch the client update manifest: ${detail}`
+      );
+    }
+    activeRelease = manifestData?.release || manifestData || {};
   } else {
     const manifestOrigin = String(process.env.NC_API_URL || apiBase).replace(/\/$/, '');
     const manifestUrl = updatesUrl || process.env.NC_UPDATES_URL || `${manifestOrigin}/api/updates`;
@@ -1220,7 +1253,12 @@ export async function pairDeviceAndInstall({
         writePairState(statePath, { host_id: localEnv.NC_CLIENT_ID, phase: 'verified' });
         return { hostId: localEnv.NC_CLIENT_ID, serverUrl: localEnv.NC_SERVER_URL, resumed: true };
       } catch (err) {
-        if (err instanceof PairingError && (err.code === 'VERIFY_TIMEOUT' || err.code === 'VERIFY_FAILED')) {
+        // Only a definitive 404 (VERIFY_FAILED) falls through to a fresh
+        // enrollment. A timeout (VERIFY_TIMEOUT) rethrows with the timeout
+        // guidance: wiping stored credentials on a transient stall would
+        // orphan a healthy host identity. The caller reports the stored-
+        // credentials connectivity hint via suggestedActionFor.
+        if (err instanceof PairingError && err.code === 'VERIFY_FAILED') {
           // Stored credentials no longer authenticate (rotated, revoked, or
           // server reset): fall through to a fresh enrollment, which
           // overwrites the stale files below.
@@ -1341,6 +1379,7 @@ function printCliHelp() {
       'Usage:',
       '  nodecommand                          pair this machine via the browser device flow',
       '  nodecommand setup [host_id token]    install the agent (auto system/user mode; no args = browser device flow)',
+      '  nodecommand uninstall [--yes]        remove the agent from the canonical root (alias: remove)',
       '  nodecommand remove [--yes]           uninstall the agent (asks for confirmation unless --yes)',
       '  nodecommand --diagnostics            preview a redacted diagnostics bundle (dry-run, writes nothing)',
       '  nodecommand --diagnostics --apply    write the diagnostics bundle (.tar.gz) for a support ticket',
@@ -1372,6 +1411,10 @@ async function main() {
     await runSetup(subArgs);
     return;
   }
+  if (subcommand === 'uninstall') {
+    await runUninstall(subArgs);
+    return;
+  }
   if (subcommand === 'remove') {
     await runRemove(subArgs);
     return;
@@ -1491,11 +1534,53 @@ function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed
   console.log('status: agent credentials verified online');
 }
 
+/**
+ * Guidance printed when Windows UAC elevation for a system-wide install is
+ * unavailable (headless shell) or was declined by the operator.
+ */
+const WINDOWS_ELEVATION_INSTALL_DECLINED =
+  'Elevation unavailable or declined. Please run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.';
+
+/**
+ * Guidance printed when Windows UAC elevation for uninstallation is
+ * unavailable (headless shell) or was declined by the operator.
+ */
+const WINDOWS_ELEVATION_UNINSTALL_DECLINED =
+  'Elevation unavailable or declined. Please run as Administrator in an elevated shell to uninstall the agent from C:\\ProgramData\\NC.';
+
+/**
+ * Re-runs the current CLI invocation elevated through the Windows UAC prompt
+ * (`Start-Process -Verb RunAs -Wait`; stdio stays inherited so the elevated
+ * console is visible) and returns the spawnSync result. Never throws: a
+ * missing powershell or a declined prompt resolves to null/non-zero.
+ */
+function requestWindowsElevation() {
+  const args = [...process.argv.slice(1)];
+  try {
+    return child_process.spawnSync(
+      'powershell',
+      [
+        '-NoProfile',
+        '-Command',
+        `Start-Process -FilePath "${process.execPath}" -ArgumentList ${args
+          .map((a) => `"${String(a).replace(/"/g, '`"')}"`)
+          .join(',')} -Verb RunAs -Wait`
+      ],
+      { stdio: 'inherit' }
+    );
+  } catch {
+    return null;
+  }
+}
+
 /**
  * `nodecommand setup [host_id enrollment_token]`.
  *
- * Mode is automatic (never prompted): elevated processes install system-wide,
- * everything else installs per-user with a single-line capability notice.
+ * Mode is automatic (never prompted): elevated processes install machine-wide.
+ * POSIX: a non-root admin requests sudo; a refusal falls back to a per-user
+ * install with a single-line capability notice. Windows: a standard shell
+ * requests UAC elevation instead and hard-stops (exit 1) when elevation is
+ * unavailable or declined — never a silent %LOCALAPPDATA% degradation.
  * Without arguments a fresh enrollment is requested via the browser device
  * flow; with `host_id` + `token` (dashboard flow) the supplied enrollment is
  * redeemed directly. Enrollment always goes through POST /api/enroll with the
@@ -1527,7 +1612,32 @@ export async function runSetup(args = []) {
     console.error('suggested_action: Re-run as `nodecommand setup` or `nodecommand setup <host_id> <token>`.');
     process.exit(1);
   }
-  const installMode = decideInstallMode();
+  let installMode = decideInstallMode();
+  // A non-root admin must not silently fall back to a per-user install: the
+  // install root, service scope and privileged helper all differ. POSIX
+  // requests sudo and re-runs elevated; Windows requests UAC (Start-Process
+  // -Verb RunAs) so the install lands machine-wide at the canonical system
+  // root. A refused or unavailable Windows elevation is a hard stop: the CLI
+  // never silently degrades a system install into %LOCALAPPDATA%.
+  if (installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
+    if (os.platform() === 'win32') {
+      if (process.stdin.isTTY) {
+        console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
+        const elevated = requestWindowsElevation();
+        if (elevated && elevated.status === 0) process.exit(0);
+      }
+      console.error(WINDOWS_ELEVATION_INSTALL_DECLINED);
+      process.exit(1);
+    }
+    console.log('Admin rights required for a system-wide install. Requesting sudo…');
+    const elevated = child_process.spawnSync(
+      'sudo',
+      ['-E', process.execPath, ...process.argv.slice(1)],
+      { stdio: 'inherit', env: { ...process.env, NC_ELEVATED: '1' } }
+    );
+    if (elevated && elevated.status === 0) process.exit(0);
+    console.warn('Elevation unavailable or declined; continuing with a per-user install.');
+  }
   // Mode-aware root: on win32 a system install lives in %ProgramData%\NC,
   // not the %LOCALAPPDATA% tree getNcRoot() returns, so credentials must be
   // written where the system installer will actually read them.
@@ -1588,30 +1698,47 @@ export function confirmPrompt(question, openInterface = null) {
 }
 
 /**
- * `nodecommand remove [--yes]`. Idempotent: no install found means success
- * (exit 0). Otherwise the uninstaller living inside each installed tree is
- * executed (never a downloaded copy) and its exit status is reported.
+ * Shared engine for `remove`/`uninstall`: idempotent (no install found means
+ * success, exit 0); otherwise the uninstaller living inside each installed
+ * tree is executed (never a downloaded copy) and its exit status is reported.
+ * Target discovery is centered on the canonical root (candidateInstallRoots
+ * lists it first) and treats an unreadable system tree as installed, so a
+ * non-root shell routes it to the elevated uninstaller instead of reporting
+ * "nothing to remove".
  * @param {string[]} args
+ * @param {{ command: string, emptyMessage: string, elevateOnWindows?: boolean, completionMessage: string }} options
  */
-export async function runRemove(args = []) {
+async function runRemoval(args, { command, emptyMessage, elevateOnWindows = false, completionMessage }) {
   if (args.includes('--help') || args.includes('-h') || args.includes('help')) {
     printCliHelp();
     return;
   }
-  assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], 'remove');
+  assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], command);
   const stray = args.filter((a) => !a.startsWith('-') && a !== 'help');
   if (stray.length > 0) {
-    console.error(`error: [UNKNOWN_ARGUMENT] \`remove\` takes no positional arguments (got: ${stray.join(', ')}).`);
-    console.error('suggested_action: Run `nodecommand remove --yes` (or plain `nodecommand remove` to be asked).');
+    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got: ${stray.join(', ')}).`);
+    console.error(`suggested_action: Run \`nodecommand ${command} --yes\` (or plain \`nodecommand ${command}\` to be asked).`);
     process.exit(1);
   }
   const yes = args.includes('--yes') || args.includes('-y');
   const { install, unreadable } = findRemovalTargets();
   const targets = [...install, ...unreadable];
   if (targets.length === 0) {
-    console.log('No Node Command installation found (nothing to remove).');
+    console.log(emptyMessage);
     return;
   }
+  // Windows: a machine-wide tree at C:\ProgramData\NC cannot be removed from
+  // a standard shell — request UAC (Start-Process -Verb RunAs) and re-run this
+  // same command elevated. Declined or headless elevation is a hard stop.
+  if (elevateOnWindows && os.platform() === 'win32' && !isElevated()) {
+    if (process.stdin.isTTY) {
+      console.log('Admin rights required to remove the system-wide agent. Requesting UAC elevation…');
+      const elevated = requestWindowsElevation();
+      if (elevated && elevated.status === 0) process.exit(0);
+    }
+    console.error(WINDOWS_ELEVATION_UNINSTALL_DECLINED);
+    process.exit(1);
+  }
   console.log(`Found Node Command installation(s): ${targets.join(', ')}`);
   if (unreadable.length > 0) {
     console.log(
@@ -1620,11 +1747,11 @@ export async function runRemove(args = []) {
   }
   if (!yes) {
     if (!process.stdin.isTTY) {
-      console.error('error: [CONFIRMATION_REQUIRED] remove needs confirmation in non-interactive shells.');
-      console.error('suggested_action: Re-run as `nodecommand remove --yes`.');
+      console.error(`error: [CONFIRMATION_REQUIRED] ${command} needs confirmation in non-interactive shells.`);
+      console.error(`suggested_action: Re-run as \`nodecommand ${command} --yes\`.`);
       process.exit(1);
     }
-    const confirmed = await confirmPrompt(`Remove ${targets.length === 1 ? 'this installation' : 'these installations'}? [y/N] `);
+    const confirmed = await confirmPrompt(`${command === 'uninstall' ? 'Uninstall' : 'Remove'} ${targets.length === 1 ? 'this installation' : 'these installations'}? [y/N] `);
     if (!confirmed) {
       console.log('Aborted (nothing removed).');
       return;
@@ -1665,7 +1792,40 @@ export async function runRemove(args = []) {
     }
   }
   if (failed > 0) process.exit(1);
-  console.log('Remove complete.');
+  console.log(completionMessage);
+}
+
+/**
+ * `nodecommand remove [--yes]` — legacy name for the canonical uninstall.
+ * @param {string[]} args
+ */
+export async function runRemove(args = []) {
+  return runRemoval(args, {
+    command: 'remove',
+    emptyMessage: 'No Node Command installation found (nothing to remove).',
+    completionMessage: 'Remove complete.'
+  });
+}
+
+/**
+ * `nodecommand uninstall [--yes]` (alias: `remove`). Resolves the canonical
+ * install root (`getNcRoot()`), verifies an agent tree actually lives there
+ * (readable markers, or an unreadable system tree that requires elevation),
+ * and invokes the in-tree platform uninstaller:
+ * - Windows: `powershell -NoProfile -ExecutionPolicy Bypass -File <root>\uninstall.ps1`
+ *   after requesting UAC (`Start-Process -Verb RunAs`) when not elevated
+ * - POSIX: `sudo <root>/uninstall.sh`, run directly when already root
+ * When no agent is installed the command reports the canonical root and
+ * exits cleanly.
+ * @param {string[]} args
+ */
+export async function runUninstall(args = []) {
+  return runRemoval(args, {
+    command: 'uninstall',
+    emptyMessage: `No active NC agent installation found at ${getNcRoot()}.`,
+    elevateOnWindows: true,
+    completionMessage: 'Uninstall complete.'
+  });
 }
 
 /**
@@ -1712,7 +1872,8 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
     user_code,
     verification_uri_complete,
     verification_uri,
-    interval = 3
+    interval = 3,
+    expires_in = 600
   } = initRes.data;
 
   const bold = '\x1b[1m';
@@ -1745,9 +1906,20 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
 
   let isPolling = false;
   let currentIntervalMs = pollIntervalMs;
+  // Poll bounds (RFC 8628 §3.5): the device_code lives ~expires_in seconds
+  // server-side, and consecutive network failures must not spin forever.
+  const lifetimeSec = Number(expires_in) > 0 ? Number(expires_in) : 600;
+  const flowDeadline = Date.now() + lifetimeSec * 1000;
+  let consecutiveNetErrors = 0;
+  const MAX_NET_ERROR_RETRIES = 10;
 
   const poll = async () => {
     if (isPolling) return;
+    if (Date.now() >= flowDeadline) {
+      console.error(`\nerror: [DEVICE_FLOW_CONNECT] Device authorization window expired before approval (no approval within ~${lifetimeSec}s).`);
+      console.error('suggested_action: Re-run the command and approve the prompt in the browser within the time window.');
+      process.exit(1);
+    }
     isPolling = true;
 
     try {
@@ -1757,6 +1929,7 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
         client_id: clientId,
         code_verifier: deviceCodeVerifier
       });
+      consecutiveNetErrors = 0;
 
       if (tokenRes.status === 200 && tokenRes.data?.access_token) {
         // The OAuth token authorizes enrollment ONLY. It stays in memory:
@@ -1806,7 +1979,15 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
         process.exit(1);
       }
     } catch (pollErr) {
-      // Ephemeral network glitch during poll, continue polling
+      // Ephemeral network glitch during poll: retry a bounded number of
+      // times, then fail loudly instead of polling forever.
+      consecutiveNetErrors += 1;
+      if (consecutiveNetErrors >= MAX_NET_ERROR_RETRIES) {
+        const detail = pollErr instanceof Error ? pollErr.message : String(pollErr);
+        console.error(`\nerror: [DEVICE_FLOW_CONNECT] Could not reach ${tokenEndpoint} after ${consecutiveNetErrors} attempts: ${detail}`);
+        console.error('suggested_action: Check network access to the control plane (or NC_BASE_URL), then re-run.');
+        process.exit(1);
+      }
     } finally {
       isPolling = false;
       setTimeout(poll, currentIntervalMs);

package/lib/diagnostics-bundle.mjs

@@ -17,6 +17,7 @@ import os from 'node:os';
 import path from 'node:path';
 import zlib from 'node:zlib';
 import child_process from 'node:child_process';
+import { candidateInstallRoots, decideInstallMode, getNcRootForMode, probeInstallRoot } from './setup.mjs';
 
 export const CLI_DIAGNOSTICS_VERSION = '1.0.0';
 export const CLI_DIAGNOSTICS_MAX_LOG_BYTES = 65536;
@@ -485,21 +486,48 @@ export function renderCliSummary(bundle, { wrote = null, dryRun = true } = {}) {
  * @param {(file: string, data: Uint8Array) => void} [options.writeFile]
  * @param {string} [options.cwd]
  */
+/**
+ * Default agent root for diagnostics. Explicit roots win; otherwise the
+ * shared installer layout table is probed so machine-wide installs
+ * (`/opt/nc`, `%ProgramData%\\NC`) resolve instead of silently falling back
+ * to the per-user tree the agent never reads. `mode` overrides the
+ * privilege probe (deterministic tests); callers without one get the live
+ * `decideInstallMode()` fallback for the nothing-installed case.
+ * @param {{ env?: Record<string, string|undefined>, platform?: string, homedir?: string, mode?: 'system'|'user' }} [options]
+ */
+export function resolveDefaultCliRoot({ env = process.env, platform = os.platform(), homedir = undefined, mode = undefined } = {}) {
+  const e = env || {};
+  if (e.NC_ROOT) return e.NC_ROOT;
+  const base = { env: e, platform };
+  if (homedir !== undefined) base.homedir = homedir;
+  let roots = [];
+  try {
+    roots = candidateInstallRoots(base);
+  } catch {
+    roots = [];
+  }
+  for (const r of roots) {
+    let status = '';
+    try {
+      status = probeInstallRoot(r);
+    } catch {
+      status = '';
+    }
+    if (status === 'install' || status === 'unreadable') return r;
+  }
+  try {
+    const fallbackMode = mode === 'system' || mode === 'user' ? mode : decideInstallMode({ platform });
+    return getNcRootForMode(fallbackMode, base);
+  } catch {
+    return roots.length ? roots[roots.length - 1] : null;
+  }
+}
+
 export function runCliDiagnostics(argv = [], { ncRoot = null, env = process.env, cliVersion = '0.1.0', baseUrl = null, writeFile = null, cwd = null } = {}) {
   const parsed = parseCliDiagnosticsArgs(argv);
   if (!parsed.enabled) return { handled: false, ok: false, summary: '', outputPath: null };
   try {
-    let root = ncRoot;
-    if (!root) {
-      const e = env || {};
-      if (e.NC_ROOT) root = e.NC_ROOT;
-      else {
-        const plat = os.platform();
-        if (plat === 'win32') root = path.join(e.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'nc');
-        else if (plat === 'darwin') root = path.join(os.homedir(), 'Library', 'Application Support', 'nc');
-        else root = path.join(os.homedir(), '.local', 'share', 'nc');
-      }
-    }
+    const root = ncRoot || resolveDefaultCliRoot({ env });
     const bundle = collectCliDiagnostics({ ncRoot: root, env, cliVersion, baseUrl });
     if (!parsed.apply) {
       return { handled: true, ok: true, dryRun: true, outputPath: null, bundle, summary: renderCliSummary(bundle, { dryRun: true }) };

package/lib/setup.mjs

@@ -72,6 +72,30 @@ export function decideInstallMode(options = {}) {
   return isElevated(options) ? 'system' : 'user';
 }
 
+/**
+ * True when the current user CAN elevate to a machine-wide install even when
+ * the process is not root yet: an already-elevated process, a Windows
+ * standard shell (UAC `Start-Process -Verb RunAs` is always available), or
+ * POSIX admin groups (sudo/admin/wheel). Used so a non-root admin is asked
+ * for elevation instead of silently degrading to a per-user install
+ * (different root, service scope and no privileged helper).
+ * @param {{ platform?: string, getuid?: (() => number)|null, isAdmin?: boolean|null, runAdminCheck?: (() => boolean)|null }} [options]
+ */
+export function canElevate(options = {}) {
+  if (isElevated(options)) return true;
+  const platform = options.platform || os.platform();
+  // Windows: a non-elevated process can still relaunch itself through the
+  // UAC prompt, so elevation is available even when not administrator.
+  if (platform === 'win32') return true;
+  try {
+    const r = child_process.spawnSync('id', ['-nG'], { encoding: 'utf8' });
+    const groups = r && typeof r.stdout === 'string' ? r.stdout : '';
+    return /\b(sudo|admin|wheel)\b/.test(groups);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Warning text for the given mode: a single line for user mode, null for
  * system mode (callers assert presence/absence on this, not on stdout).

package/package.json

@@ -1,23 +1,15 @@
 {
   "name": "nc-agent",
-  "version": "0.1.1",
-  "license": "Apache-2.0",
+  "version": "0.1.4",
+  "description": "Node Command device pairing and agent installer. Run npx nc-agent to pair this machine with your Node Command workspace.",
   "type": "module",
+  "license": "Apache-2.0",
   "bin": {
-    "nc-agent": "bin/nc.mjs"
+    "nc-agent": "./bin/nc.mjs"
   },
   "files": [
-    "bin",
-    "lib",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=24"
-  },
-  "scripts": {
-    "start": "node src/client/launcher.mjs",
-    "test": "node --test tests/*.mjs"
-  },
-  "description": "Node Command device pairing and agent installer. Run npx nc-agent to pair this machine via the browser device flow; the agent is downloaded from the control plane."
+    "bin/",
+    "lib/",
+    "README.md"
+  ]
 }

package/LICENSE

@@ -1,176 +0,0 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1. Definitions.
-
-"License" shall mean the terms and conditions for use, reproduction,
-and distribution as defined by Sections 1 through 9 of this document.
-
-"Licensor" shall mean the copyright owner or entity authorized by
-the copyright owner that is granting the License.
-
-"Legal Entity" shall mean the union of the acting entity and all
-other entities that control, are controlled by, or are under common
-control with that entity. For the purposes of this definition,
-"control" means (i) the power, direct or indirect, to cause the
-direction or management of such entity, whether by contract or
-otherwise, or (ii) ownership of fifty percent (50%) or more of the
-outstanding shares, or (iii) beneficial ownership of such entity.
-
-"You" (or "Your") shall mean an individual or Legal Entity
-exercising permissions granted by this License.
-
-"Source" form shall mean the preferred form for making modifications,
-including but not limited to software source code, documentation
-source, and configuration files.
-
-"Object" form shall mean any form resulting from mechanical
-transformation or translation of a Source form, including but
-not limited to compiled object code, generated documentation,
-and conversions to other media types.
-
-"Work" shall mean the work of authorship, whether in Source or
-Object form, made available under the License, as indicated by a
-copyright notice that is included in or attached to the work
-(an example is provided in the Appendix below).
-
-"Derivative Works" shall mean any work, whether in Source or Object
-form, that is based on (or derived from) the Work and for which the
-editorial revisions, annotations, elaborations, or other modifications
-represent, as a whole, an original work of authorship. For the purposes
-of this License, Derivative Works shall not include works that remain
-separable from, or merely link (or bind by name) to the interfaces of,
-the Work and Derivative Works thereof.
-
-"Contribution" shall mean any work of authorship, including
-the original version of the Work and any modifications or additions
-to that Work or Derivative Works thereof, that is intentionally
-submitted to Licensor for inclusion in the Work by the copyright owner
-or by an individual or Legal Entity authorized to submit on behalf of
-the copyright owner. For the purposes of this definition, "submitted"
-means any form of electronic, verbal, or written communication sent
-to the Licensor or its representatives, including but not limited to
-communication on electronic mailing lists, source code control systems,
-and issue tracking systems that are managed by, or on behalf of, the
-Licensor for the purpose of discussing and improving the Work, but
-excluding communication that is conspicuously marked or otherwise
-designated in writing by the copyright owner as "Not a Contribution."
-
-"Contributor" shall mean Licensor and any individual or Legal Entity
-on behalf of whom a Contribution has been received by Licensor and
-subsequently incorporated within the Work.
-
-2. Grant of Copyright License. Subject to the terms and conditions of
-this License, each Contributor hereby grants to You a perpetual,
-worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-copyright license to reproduce, prepare Derivative Works of,
-publicly display, publicly perform, sublicense, and distribute the
-Work and such Derivative Works in Source or Object form.
-
-3. Grant of Patent License. Subject to the terms and conditions of
-this License, each Contributor hereby grants to You a perpetual,
-worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-(except as stated in this section) patent license to make, have made,
-use, offer to sell, sell, import, and otherwise transfer the Work,
-where such license applies only to those patent claims licensable
-by such Contributor that are necessarily infringed by their
-Contribution(s) alone or by combination of their Contribution(s)
-with the Work to which such Contribution(s) was submitted. If You
-institute patent litigation against any entity (including a
-cross-claim or counterclaim in a lawsuit) alleging that the Work
-or a Contribution incorporated within the Work constitutes direct
-or contributory patent infringement, then any patent licenses
-granted to You under this License for that Work shall terminate
-as of the date such litigation is filed.
-
-4. Redistribution. You may reproduce and distribute copies of the
-Work or Derivative Works thereof in any medium, with or without
-modifications, and in Source or Object form, provided that You
-meet the following conditions:
-
-(a) You must give any other recipients of the Work or
-Derivative Works a copy of this License; and
-
-(b) You must cause any modified files to carry prominent notices
-stating that You changed the files; and
-
-(c) You must retain, in the Source form of any Derivative Works
-that You distribute, all copyright, patent, trademark, and
-attribution notices from the Source form of the Work,
-excluding those notices that do not pertain to any part of
-the Derivative Works; and
-
-(d) If the Work includes a "NOTICE" text file as part of its
-distribution, then any Derivative Works that You distribute must
-include a readable copy of the attribution notices contained
-within such NOTICE file, excluding those notices that do not
-pertain to any part of the Derivative Works, in at least one
-of the following places: within a NOTICE text file distributed
-as part of the Derivative Works; within the Source form or
-documentation, if provided along with the Derivative Works; or,
-within a display generated by the Derivative Works, if and
-wherever such third-party notices normally appear. The contents
-of the NOTICE file are for informational purposes only and
-do not modify the License. You may add Your own attribution
-notices within Derivative Works that You distribute, alongside
-or as an addendum to the NOTICE text from the Work, provided
-that such additional attribution notices cannot be construed
-as modifying the License.
-
-You may add Your own copyright statement to Your modifications and
-may provide additional or different license terms and conditions
-for use, reproduction, or distribution of Your modifications, or
-for any such Derivative Works as a whole, provided Your use,
-reproduction, and distribution of the Work otherwise complies with
-the conditions stated in this License.
-
-5. Submission of Contributions. Unless You explicitly state otherwise,
-any Contribution intentionally submitted for inclusion in the Work
-by You to the Licensor shall be under the terms and conditions of
-this License, without any additional terms or conditions.
-Notwithstanding the above, nothing herein shall supersede or modify
-the terms of any separate license agreement you may have executed
-with Licensor regarding such Contributions.
-
-6. Trademarks. This License does not grant permission to use the trade
-names, trademarks, service marks, or product names of the Licensor,
-except as required for reasonable and customary use in describing the
-origin of the Work and reproducing the content of the NOTICE file.
-
-7. Disclaimer of Warranty. Unless required by applicable law or
-agreed to in writing, Licensor provides the Work (and each
-Contributor provides its Contributions) on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-implied, including, without limitation, any warranties or conditions
-of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-PARTICULAR PURPOSE. You are solely responsible for determining the
-appropriateness of using or redistributing the Work and assume any
-risks associated with Your exercise of permissions under this License.
-
-8. Limitation of Liability. In no event and under no legal theory,
-whether in tort (including negligence), contract, or otherwise,
-unless required by applicable law (such as deliberate and grossly
-negligent acts) or agreed to in writing, shall any Contributor be
-liable to You for damages, including any direct, indirect, special,
-incidental, or consequential damages of any character arising as a
-result of this License or out of the use or inability to use the
-Work (including but not limited to damages for loss of goodwill,
-work stoppage, computer failure or malfunction, or any and all
-other commercial damages or losses), even if such Contributor
-has been advised of the possibility of such damages.
-
-9. Accepting Warranty or Additional Liability. While redistributing
-the Work or Derivative Works thereof, You may choose to offer,
-and charge a fee for, acceptance of support, warranty, indemnity,
-or other liability obligations and/or rights consistent with this
-License. However, in accepting such obligations, You may act only
-on Your own behalf and on Your sole responsibility, not on behalf
-of any other Contributor, and only if You agree to indemnify,
-defend, and hold each Contributor harmless for any liability
-incurred by, or claims asserted against, such Contributor by reason
-of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS