node-command 2.0.0 → 2.0.2

package/bin/nc.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import os from 'node:os';
 import child_process from 'node:child_process';
 import readline from 'node:readline';
+import { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import {
   canElevate,
@@ -1378,6 +1379,7 @@ function printCliHelp() {
       '',
       'Usage:',
       '  nodecommand                          pair this machine via the browser device flow',
+      '  nodecommand <host_id>                install with a dashboard host id (prompts for the token, hidden input)',
       '  nodecommand setup [host_id token]    install the agent (auto system/user mode; no args = browser device flow)',
       '  nodecommand uninstall [--yes]        remove the agent from the canonical root (alias: remove)',
       '  nodecommand remove [--yes]           uninstall the agent (asks for confirmation unless --yes)',
@@ -1402,6 +1404,48 @@ function printCliHelp() {
   );
 }
 
+/**
+ * True when the invocation is exactly the bare enrollment form
+ * `nodecommand <host_id> <token>` — the legacy positional shape accepted for
+ * backward compatibility with already-published dashboards and docs.
+ *
+ * Exactly two non-flag arguments with plausible shapes route to the same path
+ * as `setup <host_id> <token>`. The guards stay deliberately loose (host id
+ * >= 3 chars, token >= 8 chars): both values are re-validated canonically
+ * inside pairDeviceAndInstall (HOST_ID_RE / ENROLL_TOKEN_RE), so a
+ * malformed-but-intended enrollment surfaces the setup error codes
+ * (INVALID_HOST_ID / INVALID_ENROLL_TOKEN) instead of silently starting the
+ * interactive device flow. Zero or one positional argument, or any flag, is
+ * never mapped to setup and keeps its previous behavior.
+ * @param {string[]} args
+ */
+export function isBareEnrollmentInvocation(args = []) {
+  if (!Array.isArray(args) || args.length !== 2) return false;
+  const [hostId, token] = args;
+  if (typeof hostId !== 'string' || typeof token !== 'string') return false;
+  if (hostId.startsWith('-') || token.startsWith('-')) return false;
+  return hostId.length >= 3 && token.length >= 8;
+}
+
+/**
+ * True when the invocation is exactly the token-free enrollment form
+ * `nodecommand <host_id>` — the canonical shape the control-plane
+ * install_command emits. The single-use token is NOT accepted on the command
+ * line for this form: runSetup prompts for it with masked (non-echoing)
+ * input, so it never lands in argv, shell history, `ps`, terminal
+ * recordings, or telemetry.
+ *
+ * Only a canonical host id (`nc_<64hex>`) qualifies: a stray single word
+ * keeps its previous behavior (browser device flow) instead of being
+ * misread as an enrollment.
+ * @param {string[]} args
+ */
+export function isBareHostIdInvocation(args = []) {
+  if (!Array.isArray(args) || args.length !== 1) return false;
+  const [hostId] = args;
+  return typeof hostId === 'string' && !hostId.startsWith('-') && HOST_ID_RE.test(hostId);
+}
+
 async function main() {
   const cliArgs = process.argv.slice(2);
   // Subcommands route FIRST: otherwise `setup --diagnostics` or a stray flag
@@ -1439,6 +1483,21 @@ async function main() {
     if (!result.ok) process.exit(1);
     return;
   }
+  // Bare enrollment: route `nodecommand <host_id> <token>` (legacy positional
+  // form the dashboard and install_command used to emit) to the `setup
+  // <host_id> <token>` path instead of silently ignoring the arguments in the
+  // device flow.
+  if (isBareEnrollmentInvocation(cliArgs)) {
+    await runSetup(cliArgs);
+    return;
+  }
+  // Canonical token-free form: the single-use token is typed at a masked
+  // interactive prompt inside runSetup, so it never enters argv (shell
+  // history, `ps`, recordings, telemetry).
+  if (isBareHostIdInvocation(cliArgs)) {
+    await runSetup(cliArgs, { allowHostIdOnly: true });
+    return;
+  }
   await runDeviceFlow();
 }
 
@@ -1465,6 +1524,8 @@ export function suggestedActionFor(code) {
     case 'INVALID_ENROLL_TOKEN':
     case 'INVALID_HOST_ID':
       return 'Re-run `nodecommand setup` without arguments for a fresh enrollment.';
+    case 'ENROLL_TOKEN_REQUIRED':
+      return 'Re-run in an interactive terminal so the token can be typed with hidden input, or pass the token as the second argument.';
     case 'INSTALL_MANIFEST_ERROR':
       return 'The update manifest is admin-only; run with an enrollment (setup <host_id> <token>) so the release ships with the redemption, or check network connectivity to the agent release host and re-run; stored credentials are reused.';
     case 'INSTALL_DOWNLOAD_ERROR':
@@ -1582,21 +1643,25 @@ function requestWindowsElevation() {
  * 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
+ * flow; with `host_id` + `token` (legacy dashboard flow) the supplied
+ * enrollment is redeemed directly; with a bare canonical `host_id`
+ * (`allowHostIdOnly`, the canonical install_command form) the single-use
+ * token is read from a masked interactive prompt and never touches argv.
+ * Enrollment always goes through POST /api/enroll with the
  * OAuth user grant — the same tested chain as the default pairing flow — not
  * through the dashboard shell snippets, because this CLI already embeds
  * download, install, and device-auth verification.
  * @param {string[]} args
+ * @param {{ allowHostIdOnly?: boolean, promptToken?: (io: { input: import('node:stream').Readable, output: import('node:stream').Writable }) => Promise<string> }} [options]
  */
-export async function runSetup(args = []) {
+export async function runSetup(args = [], { allowHostIdOnly = false, promptToken = promptEnrollmentToken } = {}) {
   const positionals = args.filter((a) => !a.startsWith('-'));
   if (positionals.includes('help') || args.includes('--help') || args.includes('-h')) {
     console.log(
       [
         'Usage:',
         '  nodecommand setup                  install via the browser device flow (auto system/user mode)',
-        '  nodecommand setup <host_id> <token>  install with a dashboard enrollment token',
+        '  nodecommand setup <host_id> <token>  install with a dashboard enrollment token (legacy positional form)',
         '',
         'The install mode is chosen automatically: administrator/root installs',
         'machine-wide (system), anything else installs per-user (user).'
@@ -1607,7 +1672,10 @@ export async function runSetup(args = []) {
   assertKnownFlags(args, ['--help', '-h'], 'setup');
   // Arity is validated BEFORE any mode/root output: an invalid invocation
   // must fail without printing an installation plan it will not execute.
-  if (positionals.length !== 0 && positionals.length !== 2) {
+  // One positional (host id) is valid only for the bare `nodecommand
+  // <host_id>` form; `setup <host_id>` stays a loud usage error.
+  const onePositionalOk = allowHostIdOnly && positionals.length === 1;
+  if (positionals.length !== 0 && positionals.length !== 2 && !onePositionalOk) {
     console.error('error: [INVALID_SETUP_ARGS] setup takes either no arguments or `<host_id> <token>`.');
     console.error('suggested_action: Re-run as `nodecommand setup` or `nodecommand setup <host_id> <token>`.');
     process.exit(1);
@@ -1646,6 +1714,19 @@ export async function runSetup(args = []) {
   const warning = modeWarningFor(installMode);
   if (warning) console.warn(warning);
 
+  // Canonical token-free form: prompt AFTER elevation so the token is typed
+  // on the elevated terminal and never enters argv (a sudo/UAC re-exec
+  // forwards only the host id). Masked input: the token is not echoed.
+  if (onePositionalOk) {
+    try {
+      const enrollmentToken = await promptToken({ input: process.stdin, output: process.stderr });
+      positionals.push(String(enrollmentToken || ''));
+    } catch (err) {
+      reportSetupError(err);
+      process.exit(1);
+    }
+  }
+
   if (positionals.length === 2) {
     const [hostId, enrollmentToken] = positionals;
     try {
@@ -1666,6 +1747,75 @@ export async function runSetup(args = []) {
   await runDeviceFlow({ installMode, ncRoot });
 }
 
+/**
+ * Prompt text for the masked enrollment-token prompt. Printed to stderr (the
+ * CLI's human channel) so stdout stays clean for machine payloads.
+ */
+export const ENROLLMENT_TOKEN_PROMPT = 'Enrollment token (input hidden): ';
+
+/**
+ * Reads a single-use enrollment token from an interactive terminal WITHOUT
+ * echoing it. Node-stdlib only, no new deps: readline drives the input (line
+ * editing, paste, Ctrl+C, raw mode) while its echo/cursor frames are written
+ * into a sink stream, so the typed token never reaches the terminal,
+ * scrollback, or a session recording.
+ *
+ * Fails closed (PairingError ENROLL_TOKEN_REQUIRED) instead of hanging when
+ * stdin is not an interactive terminal, on EOF, on Ctrl+C, or on an empty
+ * submission. The caller maps the code to a suggested_action line.
+ * @param {{ input?: import('node:stream').Readable, output?: import('node:stream').Writable }} [streams]
+ * @returns {Promise<string>} the typed token (trimmed)
+ */
+export function promptEnrollmentToken({ input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve, reject) => {
+    if (!input || input.isTTY !== true) {
+      reject(
+        new PairingError(
+          'ENROLL_TOKEN_REQUIRED',
+          'No enrollment token was provided and stdin is not an interactive terminal. Re-run in a terminal so the token can be typed with hidden input, or pass the token as the second argument.'
+        )
+      );
+      return;
+    }
+    output.write(ENROLLMENT_TOKEN_PROMPT);
+    const sink = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
+    sink.isTTY = true;
+    sink.columns = 80;
+    let settled = false;
+    const rl = readline.createInterface({ input, output: sink, terminal: true });
+    const close = () => {
+      try {
+        rl.close();
+      } catch {}
+      output.write('\n');
+    };
+    const finish = (token) => {
+      if (settled) return;
+      settled = true;
+      close();
+      resolve(token);
+    };
+    const abort = (message) => {
+      if (settled) return;
+      settled = true;
+      close();
+      reject(new PairingError('ENROLL_TOKEN_REQUIRED', message));
+    };
+    rl.on('SIGINT', () => abort('Enrollment token entry was cancelled.'));
+    rl.on('close', () => {
+      if (!settled) abort('No enrollment token was entered (terminal closed). Re-run in a terminal and paste the token from the dashboard.');
+    });
+    rl.question('', (answer) => {
+      const token = String(answer ?? '').trim();
+      if (!token) {
+        abort('No enrollment token was entered. Re-run in a terminal and paste the token shown in the dashboard.');
+        return;
+      }
+      finish(token);
+    });
+  });
+}
+
 /**
  * Asks a yes/no question on the terminal. Resolves false on EOF/empty. The
  * first resolution wins: readline emits 'close' synchronously inside
@@ -1873,7 +2023,9 @@ async function runDeviceFlow({ installMode = undefined, ncRoot = undefined } = {
     verification_uri_complete,
     verification_uri,
     interval = 3,
-    expires_in = 600
+    // Platform contract: the server always returns expires_in and grants live
+    // 300s. Keep the fallback at the mandated 300s TTL, never the old 600s.
+    expires_in = 300
   } = initRes.data;
 
   const bold = '\x1b[1m';
@@ -1907,8 +2059,9 @@ 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;
+  // server-side (300s mandated TTL), and consecutive network failures must
+  // not spin forever. Fallback mirrors the same 300s contract.
+  const lifetimeSec = Number(expires_in) > 0 ? Number(expires_in) : 300;
   const flowDeadline = Date.now() + lifetimeSec * 1000;
   let consecutiveNetErrors = 0;
   const MAX_NET_ERROR_RETRIES = 10;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-command",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Node Command agent CLI — connect this machine to your AI assistant fleet",
   "type": "module",
   "license": "Apache-2.0",