@nexusmcp/cli 1.1.0 → 1.1.2

package/README.md

@@ -15,8 +15,14 @@ token copy/paste is needed. The CLI creates a protected `.env.nexus`, project-lo
 `.mcp.json`, `.nexus/project.json`, and agent guidance without printing or embedding the
 credential in MCP configuration. For Codex, a local header helper reads `.env.nexus` at
 connection time, so a restarted client does not depend on a globally exported token.
-Existing configuration is preserved; conflicting project or credential context fails
-closed.
+Existing configuration is preserved; conflicting project or credential context fails
+closed.
+
+The CLI restricts `.env.nexus` to the current account (`0600` on POSIX and an
+inheritance-disabled user/SYSTEM ACL on Windows). `doctor` fails when that protection
+cannot be verified. The generated Codex setting uses the supported
+`http_headers_helper` contract; it emits the Authorization header only to Codex and
+never prints the credential in normal CLI output.
 
 During the private beta the CLI connects to the hosted Cloud Run service by default.
 Use `--server=<https-url>` only for an explicitly approved alternate deployment.

package/bin/cli.js

@@ -3,7 +3,7 @@
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -25,7 +25,9 @@ const EXTENSION_TOOLS = [
   'save_skill',
   'search_skills',
 ].sort();
-const CODEX_AUTH_HELPER_PATH = path.join('.nexus', 'auth-headers.cjs');
+const CODEX_AUTH_HELPER_PATH = path.join('.nexus', 'auth-headers.cjs');
+const CODEX_AUTH_HELPER_SETTING = 'http_headers_helper = "node .nexus/auth-headers.cjs"';
+const CODEX_LEGACY_ENV_SETTING = 'bearer_token_env_var = "NEXUS_API_KEY"';
 const CODEX_AUTH_HELPER_CONTENT = `#!/usr/bin/env node
 // Nexus-owned Codex HTTP header helper. The bearer secret stays in .env.nexus.
 const fs = require('node:fs');
@@ -105,6 +107,61 @@ function writeJsonFile(filePath, value) {
 function sha256(content) {
   return crypto.createHash('sha256').update(content).digest('hex');
 }
+
+function windowsUserSid() {
+  const result = spawnSync('whoami.exe', ['/user', '/fo', 'csv', '/nh'], {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) return '';
+  return result.stdout.match(/S-1-(?:\d+-)+\d+/)?.[0] || '';
+}
+
+function protectCredentialFile(filePath) {
+  const absolutePath = path.resolve(filePath);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(absolutePath, 0o600);
+    return;
+  }
+
+  const userSid = windowsUserSid();
+  if (!userSid) throw new Error('Unable to resolve the current Windows account SID.');
+  const result = spawnSync('icacls.exe', [
+    absolutePath,
+    '/inheritance:r',
+    '/grant:r', `*${userSid}:(F)`,
+    '/grant:r', '*S-1-5-18:(F)',
+    '/remove:g', '*S-1-1-0', '*S-1-5-11', '*S-1-5-32-545',
+  ], {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error('Windows refused the restricted credential-file ACL.');
+  }
+}
+
+function credentialProtectionStatus(filePath) {
+  if (!fs.existsSync(filePath)) return { ok: false, detail: 'credential file is missing' };
+  if (process.platform !== 'win32') {
+    const permissions = fs.statSync(filePath).mode & 0o777;
+    return {
+      ok: (permissions & 0o077) === 0,
+      detail: `mode ${permissions.toString(8).padStart(3, '0')}`,
+    };
+  }
+  const result = spawnSync('icacls.exe', [path.resolve(filePath), '/verify'], {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    ok: result.status === 0,
+    detail: result.status === 0 ? 'restricted Windows ACL is readable and valid' : 'Windows ACL verification failed',
+  };
+}
 
 function writeTextIfAbsent(filePath, content, label) {
   if (fs.existsSync(filePath) && !force) {
@@ -142,7 +199,7 @@ function ensureRemoteMcpJson(filePath, entry, label, explicitHttpType = false) {
   }
 }
 
-function ensureCodexAuthHelper() {
+function ensureCodexAuthHelper() {
   const helperDir = path.dirname(CODEX_AUTH_HELPER_PATH);
   if (!fs.existsSync(helperDir)) fs.mkdirSync(helperDir, { recursive: true });
   if (fs.existsSync(CODEX_AUTH_HELPER_PATH)) {
@@ -154,17 +211,27 @@ function ensureCodexAuthHelper() {
   }
   fs.writeFileSync(CODEX_AUTH_HELPER_PATH, CODEX_AUTH_HELPER_CONTENT, { encoding: 'utf-8', mode: 0o700 });
   try { fs.chmodSync(CODEX_AUTH_HELPER_PATH, 0o700); } catch (_) { /* Windows ACLs may ignore POSIX mode. */ }
-  console.log('  [OK] Created the local Codex credential helper.');
-}
+  console.log('  [OK] Created the local Codex credential helper.');
+}
+
+function inspectCodexAuthHelper() {
+  if (!fs.existsSync(CODEX_AUTH_HELPER_PATH)) {
+    return { action: 'create credential helper', label: '.nexus/auth-headers.cjs' };
+  }
+  const content = fs.readFileSync(CODEX_AUTH_HELPER_PATH, 'utf-8');
+  return content === CODEX_AUTH_HELPER_CONTENT
+    ? { action: 'healthy', label: '.nexus/auth-headers.cjs' }
+    : { action: 'refused', label: '.nexus/auth-headers.cjs', detail: 'existing helper is not Nexus-owned' };
+}
 
 function ensureCodexProjectConfig(apiUrl) {
-  const codexDir = '.codex';
-  const configPath = path.join(codexDir, 'config.toml');
-  const block = `[mcp_servers.nexus-mcp]\nurl = "${apiUrl}/mcp"\nbearer_token_env_var = "NEXUS_API_KEY"\nstartup_timeout_sec = 10\ntool_timeout_sec = 60\n`;
-  if (!fs.existsSync(codexDir)) fs.mkdirSync(codexDir, { recursive: true });
-  if (!fs.existsSync(configPath) || force) {
-    fs.writeFileSync(configPath, block, 'utf-8');
-    console.log('  [OK] Created project-scoped Codex MCP configuration.');
+  const codexDir = '.codex';
+  const configPath = path.join(codexDir, 'config.toml');
+  const block = `[mcp_servers.nexus-mcp]\nurl = "${apiUrl}/mcp"\n${CODEX_AUTH_HELPER_SETTING}\nstartup_timeout_sec = 10\ntool_timeout_sec = 60\n`;
+  if (!fs.existsSync(codexDir)) fs.mkdirSync(codexDir, { recursive: true });
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, block, 'utf-8');
+    console.log('  [OK] Created project-scoped Codex MCP configuration.');
     return;
   }
   const existing = fs.readFileSync(configPath, 'utf-8');
@@ -175,23 +242,28 @@ function ensureCodexProjectConfig(apiUrl) {
       console.error('[NEXUS-CLI] Existing Nexus Codex entry points to another server; refusing to replace it.');
       process.exit(1);
     }
-    if (existingSection[1].includes('bearer_token_env_var = "NEXUS_API_KEY"')) {
-      console.log('  [NOTE] Preserved existing Nexus entry in .codex/config.toml.');
-      return;
-    }
-    const prefix = existingSection[0].startsWith('\n') ? '\n' : '';
-    fs.writeFileSync(configPath, existing.replace(sectionPattern, `${prefix}${block.trimEnd()}`), 'utf-8');
-    console.log('  [OK] Updated the Nexus Codex entry to use its project-local credential helper.');
+    if (existingSection[1].includes(CODEX_AUTH_HELPER_SETTING)) {
+      console.log('  [NOTE] Preserved existing Nexus entry in .codex/config.toml.');
+      return;
+    }
+    if (!existingSection[1].includes(CODEX_LEGACY_ENV_SETTING)) {
+      console.error('[NEXUS-CLI] Existing Nexus Codex entry has an unrecognized credential source; refusing to replace it.');
+      process.exit(1);
+    }
+    const prefix = existingSection[0].startsWith('\n') ? '\n' : '';
+    fs.writeFileSync(configPath, existing.replace(sectionPattern, `${prefix}${block.trimEnd()}`), 'utf-8');
+    console.log('  [OK] Migrated the Nexus Codex entry to its project-local credential helper.');
     return;
   }
   fs.appendFileSync(configPath, `${existing.endsWith('\n') ? '' : '\n'}\n${block}`, 'utf-8');
   console.log('  [OK] Added Nexus to existing .codex/config.toml without changing other servers.');
 }
 
-function readEnvCredential() {
-  if (process.env.NEXUS_API_KEY) return process.env.NEXUS_API_KEY.trim();
-  if (!fs.existsSync('.env.nexus')) return '';
-  return fs.readFileSync('.env.nexus', 'utf-8').match(/^NEXUS_API_KEY=(.*)$/m)?.[1]?.trim() || '';
+function readEnvCredential() {
+  if (fs.existsSync('.env.nexus')) {
+    return fs.readFileSync('.env.nexus', 'utf-8').match(/^NEXUS_API_KEY=(.*)$/m)?.[1]?.trim() || '';
+  }
+  return process.env.NEXUS_API_KEY?.trim() || '';
 }
 
 function doctorCheck(ok, label, detail) {
@@ -420,8 +492,8 @@ function removeCodexEntry(apiUrl, apply) {
   const sectionPattern = /(?:^|\n)\[mcp_servers\.nexus-mcp\]\s*\n([\s\S]*?)(?=\n\s*\[|(?![\s\S]))/m;
   const match = content.match(sectionPattern);
   if (!match) return { action: 'absent', label };
-  const ownedCredentialSource = match[1].includes('http_headers_helper = "node .nexus/auth-headers.cjs"')
-    || match[1].includes('bearer_token_env_var = "NEXUS_API_KEY"');
+  const ownedCredentialSource = match[1].includes(CODEX_AUTH_HELPER_SETTING)
+    || match[1].includes(CODEX_LEGACY_ENV_SETTING);
   if (!match[1].includes(`url = "${apiUrl}/mcp"`) || !ownedCredentialSource) {
     return { action: 'refused', label, detail: 'Nexus section does not match the recorded server and credential contract' };
   }
@@ -578,18 +650,24 @@ function runRepair(title = 'Repair') {
     repairJsonEntry(path.join('.cursor', 'mcp.json'), { url: `${project.api_url}/mcp`, headers: { Authorization: 'Bearer ${env:NEXUS_API_KEY}' } }, project.api_url, '.cursor/mcp.json', shouldApply),
     repairJsonEntry(path.join('.agents', 'mcp_config.json'), { serverUrl: `${project.api_url}/mcp`, headers: { Authorization: 'Bearer ${NEXUS_API_KEY}' } }, project.api_url, '.agents/mcp_config.json', shouldApply),
   ];
-  let operations = collectJsonOperations(false);
-  const codexPath = path.join('.codex', 'config.toml');
+  let operations = collectJsonOperations(false);
+  const helperOperation = inspectCodexAuthHelper();
+  operations.push(helperOperation);
+  const codexPath = path.join('.codex', 'config.toml');
   const codexContent = fs.existsSync(codexPath) ? fs.readFileSync(codexPath, 'utf-8') : '';
   const codexHasSection = /^\s*\[mcp_servers\.nexus-mcp\]\s*$/m.test(codexContent);
   const codexHealthy = codexHasSection
     && codexContent.includes(`url = "${project.api_url}/mcp"`)
-    && codexContent.includes('bearer_token_env_var = "NEXUS_API_KEY"');
-  operations.push(codexHealthy
-    ? { action: 'healthy', label: '.codex/config.toml' }
-    : codexHasSection
-      ? { action: 'refused', label: '.codex/config.toml', detail: 'existing Nexus section is not owned by the recorded project context' }
-      : { action: 'add missing Nexus section', label: '.codex/config.toml' });
+    && codexContent.includes(CODEX_AUTH_HELPER_SETTING);
+  const codexOwned = !codexHasSection || (
+    codexContent.includes(`url = "${project.api_url}/mcp"`)
+    && (codexContent.includes(CODEX_AUTH_HELPER_SETTING) || codexContent.includes(CODEX_LEGACY_ENV_SETTING))
+  );
+  operations.push(codexHealthy
+    ? { action: 'healthy', label: '.codex/config.toml' }
+    : codexOwned
+      ? { action: codexHasSection ? 'migrate credential helper' : 'add missing Nexus section', label: '.codex/config.toml' }
+      : { action: 'refused', label: '.codex/config.toml', detail: 'existing Nexus section is not owned by the recorded project context' });
 
   const skillPath = path.join('.agents', 'skills', 'nexus', 'SKILL.md');
   const skillContent = provisionedNexusSkillContent();
@@ -600,8 +678,10 @@ function runRepair(title = 'Repair') {
     console.error(`[NEXUS-CLI] ${title} refused before making changes because ownership checks failed.`);
     process.exit(1);
   }
-  if (apply) {
+  if (apply) {
     operations = collectJsonOperations(true);
+    if (helperOperation.action !== 'healthy') ensureCodexAuthHelper();
+    operations.push({ action: helperOperation.action === 'healthy' ? 'healthy' : 'create credential helper', label: '.nexus/auth-headers.cjs' });
     if (!codexHealthy) {
       ensureCodexProjectConfig(project.api_url);
     }
@@ -636,8 +716,21 @@ async function runDoctor() {
     healthy = doctorCheck(false, 'Project binding', 'run nexus init first') && healthy;
   }
 
-  const token = readEnvCredential();
-  healthy = doctorCheck(Boolean(token), 'Scoped credential', token ? 'available without printing it' : 'set NEXUS_API_KEY or initialize .env.nexus') && healthy;
+  const token = readEnvCredential();
+  healthy = doctorCheck(Boolean(token), 'Scoped credential', token ? 'available without printing it' : 'set NEXUS_API_KEY or initialize .env.nexus') && healthy;
+  const credentialProtection = fs.existsSync('.env.nexus')
+    ? credentialProtectionStatus('.env.nexus')
+    : {
+        ok: Boolean(process.env.NEXUS_API_KEY),
+        detail: process.env.NEXUS_API_KEY
+          ? 'credential supplied by the process environment'
+          : 'credential file is missing',
+      };
+  healthy = doctorCheck(
+    credentialProtection.ok,
+    'Credential file permissions',
+    credentialProtection.detail,
+  ) && healthy;
 
   let mcpConfigured = false;
   if (fs.existsSync('.mcp.json')) {
@@ -658,8 +751,9 @@ async function runDoctor() {
     && nexusRemoteEntryIsOwned(cursorEntry, apiUrl)
     && nexusRemoteEntryIsOwned(agentsEntry, apiUrl)
     && codexContent.includes(`url = "${apiUrl}/mcp"`)
-    && codexContent.includes('bearer_token_env_var = "NEXUS_API_KEY"');
-  healthy = doctorCheck(clientAuthHealthy, 'Supported client auth', clientAuthHealthy ? 'Cursor, agents, and Codex use environment-based credentials' : 'run repair to restore supported environment-based auth contracts') && healthy;
+    && codexContent.includes(CODEX_AUTH_HELPER_SETTING)
+    && inspectCodexAuthHelper().action === 'healthy';
+  healthy = doctorCheck(clientAuthHealthy, 'Supported client auth', clientAuthHealthy ? 'Cursor and agents use environment expansion; Codex uses the project-local header helper' : 'run repair to restore supported credential contracts') && healthy;
 
   const gitignore = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf-8') : '';
   const secretsIgnored = gitignore.split(/\r?\n/).some((line) => line.trim() === '.env.nexus');
@@ -714,19 +808,28 @@ if (command === 'uninstall') runUninstall();
 if (command === 'init') {
   console.log('[NEXUS-CLI] 🚀 Initializing Nexus MCP in current repository...');
   
-  const apiUrl = (flags.server || flags.url || process.env.NEXUS_API_URL || DEFAULT_API_URL).replace(/\/$/, '');
-  let token = flags.token || process.env.NEXUS_API_KEY;
-  let projectId = flags['project-id'] || process.env.NEXUS_PROJECT_ID;
-
-  if (flags.token) {
-    console.warn('[NEXUS-CLI] Warning: --token may be retained in shell history. Prefer setting NEXUS_API_KEY in the process environment.');
-  }
-
-  if (!token || token === 'nx_live_default_token') {
-    const authorized = await authorizeDevice(apiUrl);
-    token = authorized.token;
-    projectId = authorized.projectId;
-  }
+  const apiUrl = (flags.server || flags.url || process.env.NEXUS_API_URL || DEFAULT_API_URL).replace(/\/$/, '');
+  let token = flags.token || process.env.NEXUS_API_KEY;
+  let projectId = flags['project-id'] || process.env.NEXUS_PROJECT_ID;
+  const manualCredentialFlagProvided = Boolean(flags.token || flags['project-id']);
+
+  if (flags.token) {
+    console.warn('[NEXUS-CLI] Warning: --token may be retained in shell history. Prefer setting NEXUS_API_KEY in the process environment.');
+  }
+
+  if (manualCredentialFlagProvided && (!token || !projectId)) {
+    console.error('[NEXUS-CLI] Manual credential mode requires both --token and --project-id (or the missing matching environment value).');
+    process.exit(1);
+  }
+
+  if (!token || !projectId || token === 'nx_live_default_token') {
+    if (token || projectId) {
+      console.log('[NEXUS-CLI] Ignoring incomplete Nexus environment credentials and starting browser authorization.');
+    }
+    const authorized = await authorizeDevice(apiUrl);
+    token = authorized.token;
+    projectId = authorized.projectId;
+  }
   if (!projectId) {
     console.error('[NEXUS-CLI] Missing project id. Pass --project-id or set NEXUS_PROJECT_ID so hooks cannot ingest into the wrong tenant.');
     process.exit(1);
@@ -758,22 +861,36 @@ if (command === 'init') {
     },
     '.agents/mcp_config.json'
   );
-  ensureCodexProjectConfig(apiUrl);
-
-  // 2. Write .env.nexus file with actual token
+  // 2. Write .env.nexus file with actual token
   const envContent = `NEXUS_API_KEY=${token}\nNEXUS_API_URL=${apiUrl}\n`;
-  if (fs.existsSync('.env.nexus') && !force) {
-    const existingEnv = fs.readFileSync('.env.nexus', 'utf-8').match(/^NEXUS_API_KEY=(.*)$/m)?.[1]?.trim();
-    if (existingEnv && existingEnv !== token) {
+  if (fs.existsSync('.env.nexus') && !force) {
+    const existingEnv = fs.readFileSync('.env.nexus', 'utf-8').match(/^NEXUS_API_KEY=(.*)$/m)?.[1]?.trim();
+    if (!existingEnv) {
+      console.error('[NEXUS-CLI] Existing .env.nexus has no valid Nexus credential; refusing to preserve it.');
+      process.exit(1);
+    }
+    if (existingEnv && existingEnv !== token) {
       console.error('[NEXUS-CLI] Existing .env.nexus contains a different credential; refusing to replace it.');
       process.exit(1);
     }
-    console.log('  [NOTE] Preserved existing .env.nexus credential file.');
-  } else {
-    fs.writeFileSync('.env.nexus', envContent, { encoding: 'utf-8', mode: 0o600 });
-    try { fs.chmodSync('.env.nexus', 0o600); } catch (_) { /* Windows ACLs may ignore POSIX mode. */ }
-    console.log('  [OK] Created .env.nexus credential file.');
-  }
+    try {
+      protectCredentialFile('.env.nexus');
+    } catch (error) {
+      console.error(`[NEXUS-CLI] ${error.message} Refusing to continue with an unprotected credential.`);
+      process.exit(1);
+    }
+    console.log('  [NOTE] Preserved existing .env.nexus credential file and refreshed its protection.');
+  } else {
+    fs.writeFileSync('.env.nexus', envContent, { encoding: 'utf-8', mode: 0o600 });
+    try {
+      protectCredentialFile('.env.nexus');
+    } catch (error) {
+      try { fs.unlinkSync('.env.nexus'); } catch (_) { /* best-effort secret cleanup */ }
+      console.error(`[NEXUS-CLI] ${error.message} The credential file was removed.`);
+      process.exit(1);
+    }
+    console.log('  [OK] Created protected .env.nexus credential file.');
+  }
 
   // 3. Shield credentials in .gitignore
   const gitignorePath = '.gitignore';
@@ -782,11 +899,16 @@ if (command === 'init') {
     gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
   }
   
-  if (!gitignoreContent.includes('.env.nexus')) {
+  if (!gitignoreContent.includes('.env.nexus')) {
     gitignoreContent += '\n# Nexus Secrets & Cache Shielding\n.env.nexus\n.nexus/\n';
     fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
-    console.log('  [OK] Updated .gitignore to shield .env.nexus credentials.');
-  }
+    console.log('  [OK] Updated .gitignore to shield .env.nexus credentials.');
+  }
+
+  // Codex supports a local HTTP-header helper. It reads the protected project
+  // credential at connection time, so Codex does not require a global env var.
+  ensureCodexAuthHelper();
+  ensureCodexProjectConfig(apiUrl);
 
   // 4. Create .nexus/project.json
   const nexusDir = '.nexus';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nexusmcp/cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Nexus MCP Lightweight Onboarding CLI & Session Hook Assistant",
   "main": "bin/cli.js",
-  "files": [
-    "bin",
-    "templates",
-    "README.md",
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
     "LICENSE"
   ],
   "bin": {
@@ -26,9 +26,9 @@
     "directory": "packages/cli"
   },
   "scripts": {
-    "test": "node test/guidance-sync.cjs && node test/smoke.cjs && node test/session-end.cjs && node test/upgrade-doctor.cjs",
+    "test": "node test/guidance-sync.cjs && node test/smoke.cjs && node test/session-end.cjs && node test/upgrade-doctor.cjs",
     "test:package": "node test/package-install.cjs",
-    "prepublishOnly": "npm test && npm run test:package && node --check bin/cli.js"
+    "prepublishOnly": "npm test && npm run test:package && node --check bin/cli.js"
   },
   "keywords": [
     "mcp",