nsauditor-ai 0.1.29 → 0.1.30

package/README.md

@@ -15,6 +15,17 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 **Zero Data Exfiltration by design.** NSAuditor AI works fully offline. AI analysis, CVE correlation, and continuous monitoring all happen locally. External calls (to AI APIs, NVD, etc.) are opt-in and use your own API keys. We never see your scan data.
 
+## What's New (0.1.30)
+
+The 0.1.30 line is a paired release with `@nsasoft/nsauditor-ai-ee@0.3.2` that closes the customer-onboarding gap and a critical false-clean SOC 2 reporting bug:
+
+- **`nsauditor-ai license install <KEY>`** — verifies the JWT *before* persisting; writes to macOS Keychain or `~/.nsauditor/.env` (mode 0600) depending on platform. Three-line install flow: `npm install -g` → `license install` → `license --status`. No more shell-rc edits.
+- **Multi-source license loader** — `loadLicense()` resolves keys from env var → platform Keychain → `~/.nsauditor/.env`, in that order. CI/CD env-var override still wins.
+- **`nsauditor-ai license --plugins`** — real enumeration of discovered plugins, grouped by source (CE / EE / custom), with active-or-required-tier status.
+- **`nsauditor-ai --version` / `-v`** — prints version and exits 0 (parallel to `--help`'s discovery-flag UX).
+- **Cloud-sentinel SSRF bypass** — `--host aws|gcp|azure` no longer requires `NSA_ALLOW_ALL_HOSTS=1`. The sentinel literals route to EE cloud-scanner plugins via the provider's API; the SSRF guard's RFC 1918 / loopback protection is preserved for real network targets.
+- **EE-0.3.2.1 hard dep** — CE forwards the per-plugin `results` array to `enrichScan()`. Without this, EE 0.3.2's cloud-finding harvester sees nothing and produces false-clean SOC 2 reports against AWS accounts. EE emits a runtime version-skew warning when this opt is missing.
+
 ## What It Does
 
 ```
@@ -49,7 +60,7 @@ NSAuditor AI is available in three editions:
 | Advanced CTEM + trend analysis | — | ✅ | ✅ |
 | Cloud scanners (AWS/GCP/Azure) | — | — | ✅ |
 | Zero Trust assessment | — | — | ✅ |
-| SOC 2 compliance (7 covered + 5 partial controls) | — | — | ✅ |
+| SOC 2 compliance (8 covered + 5 partial controls) | — | — | ✅ |
 | SLA/MTTR tracking + compensating controls | — | — | ✅ |
 | Recurring-scan attestation (Type II evidence) | — | — | ✅ |
 | GRC platform connector (Vanta) | — | — | ✅ |
@@ -70,6 +81,9 @@ NSAuditor AI is available in three editions:
 # Install globally
 npm install -g nsauditor-ai
 
+# See all flags, subcommands, and worked examples
+nsauditor-ai --help
+
 # Configure (optional — scans work fully offline without AI)
 cat > .env << 'EOF'
 AI_ENABLED=true
@@ -357,8 +371,16 @@ The `keychain:` prefix works anywhere an API key is read — CLI, MCP server, or
 
 ```
 nsauditor-ai scan [options]
+nsauditor-ai license install <KEY>
+nsauditor-ai license <--status | --capabilities | --plugins>
+nsauditor-ai security <set|delete|list|get> <KEY>
+nsauditor-ai validate
+nsauditor-ai --help        (or -h, or `help`)
+nsauditor-ai --version     (or -v, or `version`)
 ```
 
+> Run `nsauditor-ai --help` (or `-h`, or just `nsauditor-ai help`) for a quick reference of subcommands, flags, env vars, and worked examples — works without a license key configured. `--version` / `-v` (CE 0.1.30+) prints `nsauditor-ai <version>` and exits 0.
+
 | Flag | Description | Default |
 |---|---|---|
 | `--host <target>` | Target: IP, hostname, CIDR, dash range. Aliases: `--ip`, `--target` | *required*\* |
@@ -374,6 +396,10 @@ nsauditor-ai scan [options]
 | `--interval <min>` | Rescan interval in minutes (requires `--watch`) | `60` |
 | `--webhook-url <url>` | Webhook URL for delta alerts | — |
 | `--alert-severity <sev>` | Minimum severity for webhook alerts | `high` |
+| `--compliance <fw>` | Compliance framework to map findings into (e.g. `soc2`). **Enterprise license required.** See `@nsasoft/nsauditor-ai-ee` README for supported frameworks | — |
+| `--compliance-scope <path>` | Optional JSON file describing the assessment scope (passed to the compliance engine for cover-page attestation) | — |
+| `--help`, `-h` | Print usage block (subcommands, flags, env vars, examples) and exit 0 | — |
+| `--version`, `-v` | Print `nsauditor-ai <version>` and exit 0 (CE 0.1.30+) | — |
 
 \* Either `--host` or `--host-file` is required.
 

package/cli.mjs

@@ -15,7 +15,7 @@ import { buildCsv } from './utils/export_csv.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
 import { recordScan, getLastScan, computeDiff, formatDiffReport, pruneForCE, HISTORY_FILE } from './utils/scan_history.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
-import { resolveCapabilities, hasCapability } from './utils/capabilities.mjs';
+import { resolveCapabilities, hasCapability, inferRequiredTier } from './utils/capabilities.mjs';
 import { createScheduler } from './utils/scheduler.mjs';
 import { buildDeltaReport, formatDeltaSummary, hasSignificantChanges } from './utils/delta_reporter.mjs';
 import { sendWebhook, buildAlertPayload, isSafeWebhookUrl } from './utils/webhook.mjs';
@@ -525,11 +525,27 @@ async function parseArgs(argv) {
   // Help: bare `--help`/`-h`/`help` or completely empty invocation.
   // Recognized before the scan-default so it doesn't crash with
   // "--host or --host-file is required" on a help request.
+  //
+  // CE-0.1.30.1 reviewer M1: short flag `-h` only matches at `a[0]`. The
+  // long-flag `--help` matches anywhere in argv (typing `nsauditor-ai
+  // scan --help` should still print help). Pre-fix the parser had
+  // `a.includes('-h')` which would match `-h` as a value of another
+  // flag (e.g., `--alert-severity -h` would silently fire help instead
+  // of failing argv validation). Same fix mirrored in the version branch
+  // below.
   if (a.length === 0 || a[0] === '--help' || a[0] === '-h' || a[0] === 'help' ||
-      a.includes('--help') || a.includes('-h')) {
+      a.includes('--help')) {
     args.cmd = 'help';
     return args;
   }
+  // Version: bare `--version`/`-v`/`version`. CE-0.1.30.1 — same pre-license
+  // dispatch as help so a discovery flag never errors with
+  // "--host or --host-file is required" or with a missing-key fatal.
+  if (a[0] === '--version' || a[0] === '-v' || a[0] === 'version' ||
+      a.includes('--version')) {
+    args.cmd = 'version';
+    return args;
+  }
   if (a.length && !a[0].startsWith('--')) args.cmd = a[0];
 
   const get = (name) => {
@@ -588,10 +604,28 @@ async function parseArgs(argv) {
   return args;
 }
 
+// EE-0.3.2.5 (CE side): cloud-provider sentinel hosts ('aws' / 'gcp' /
+// 'azure', case-insensitive) are NOT real DNS names — they're scoping
+// tokens that EE cloud-scanner plugins (020/021/022/023/030) interpret
+// as "this run targets the cloud provider via its API, not a network
+// address." resolveAndValidate() returns ENOTFOUND for these, so pre-
+// 0.3.2.5 customers had to set NSA_ALLOW_ALL_HOSTS=1 to bypass — which
+// is undocumented AND disables the guard for legitimate RFC 1918 / IP
+// targets in the same scan. Whitelist the sentinels in scanSingleHost
+// so cloud scans Just Work and the env-var bypass remains scoped to
+// its documented use case (local-network auditing).
+//
+// Hoisted to module scope so the Set is built once at module load
+// rather than per scanSingleHost() call (reviewer L1 fold).
+const CLOUD_SENTINEL_HOSTS = new Set(['aws', 'gcp', 'azure']);
+
 async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // SSRF guard — block loopback, private ranges, cloud metadata endpoints.
   // Set NSA_ALLOW_ALL_HOSTS=1 to scan RFC 1918 / private ranges (local network auditing).
-  if (!process.env.NSA_ALLOW_ALL_HOSTS) {
+  // Cloud-sentinel hosts (see CLOUD_SENTINEL_HOSTS above) skip the guard.
+  const isCloudSentinel = typeof host === 'string' && CLOUD_SENTINEL_HOSTS.has(host.toLowerCase());
+
+  if (!process.env.NSA_ALLOW_ALL_HOSTS && !isCloudSentinel) {
     if (isBlockedIp(host)) {
       throw new Error(`Scanning blocked address range is not allowed: ${host}`);
     }
@@ -626,6 +660,17 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
   // EE enrichment hook — no-op if @nsasoft/nsauditor-ai-ee is not installed
   // or the license tier doesn't grant intelligenceEngine. Compliance + outDir
   // are forwarded so EE can write scan_finding_queue.json and SOC 2 artifacts.
+  //
+  // CE-0.1.30.5: forward the per-plugin `results` array. This is the hard
+  // dependency that makes EE-0.3.2.1's cloud-finding harvester actually
+  // work in production — pre-CE-0.1.30, EE only saw the concluder object
+  // (single plugin output) and could not harvest findings from cloud
+  // plugins (020/030/etc.) that live in pm.run().results[]. Without this
+  // line, EE 0.3.2 emits a runtime warning ("CE 0.1.30+ … running with
+  // older CE") AND continues to produce false-clean SOC 2 reports against
+  // AWS accounts. EE 0.3.2 + CE 0.1.30 ship as a paired release; mixing
+  // versions is supported but the EE-side cloud-harvest behavior requires
+  // CE-0.1.30+ to take effect.
   try {
     const { enrichScan } = await import('@nsasoft/nsauditor-ai-ee');
     const eeEnrichment = await enrichScan(conclusion, {
@@ -633,6 +678,7 @@ async function scanSingleHost(pm, host, plugins, opts, promptMode) {
       outDir,
       compliance:      opts.compliance ?? process.env.COMPLIANCE_FRAMEWORKS ?? null,
       complianceScope: opts.complianceScope ?? null,
+      results,
       onWarn: (msg) => console.warn(`[EE] ${msg}`),
     });
     if (eeEnrichment?.enrichedPrompt) {
@@ -758,6 +804,16 @@ function maxSeverityInConclusion(conclusion) {
 async function main() {
   const { cmd, host, plugins, insecureHttps, hostFile, parallel, failOn, outputFormat, watch, intervalMinutes, webhookUrl, alertSeverity, ports, compliance, complianceScope } = await parseArgs(process.argv);
 
+  // Version: handled before license verification so it works without a key.
+  // CE-0.1.30.1 — closes the discovery-flag UX gap where pre-fix
+  // `nsauditor-ai --version` errored with "Fatal: --host or --host-file
+  // is required". Output format mirrors GNU `--version` convention:
+  // "<tool> <version>" on a single line, then exit 0.
+  if (cmd === 'version') {
+    console.log(`nsauditor-ai ${TOOL_VERSION}`);
+    process.exit(0);
+  }
+
   // Help: handled before license verification so it works without a key.
   if (cmd === 'help') {
     console.log(`nsauditor-ai — Modular AI-assisted network security audit platform
@@ -768,7 +824,8 @@ Usage:
   nsauditor-ai license <subcommand>
   nsauditor-ai security <subcommand>
   nsauditor-ai validate
-  nsauditor-ai help
+  nsauditor-ai version          (or --version / -v)
+  nsauditor-ai help             (or --help / -h)
 
 Scan options:
   --host, --ip, --target <h>   Target host, IP, or CIDR
@@ -788,8 +845,13 @@ Scan options:
   --compliance-scope <path>    JSON file describing the assessment scope
 
 License subcommands:
+  nsauditor-ai license install <KEY>    Verify and persist a license key (Keychain
+                                        on macOS, ~/.nsauditor/.env on Linux/Windows
+                                        with mode 0600). Rejects invalid/expired keys.
   nsauditor-ai license --status         Show active tier, org, seats, expiry
   nsauditor-ai license --capabilities   List active capabilities for current tier
+  nsauditor-ai license --plugins        List discovered plugins grouped by source
+                                        (CE / EE / custom) with active-or-required-tier
 
 Security subcommands (macOS Keychain):
   nsauditor-ai security set <KEY>       Store a secret (read from stdin)
@@ -800,15 +862,24 @@ Security subcommands (macOS Keychain):
 Environment:
   NSAUDITOR_LICENSE_KEY          Pro/Enterprise license JWT (env var; takes precedence)
   NSA_ALLOW_ALL_HOSTS=1          Permit RFC1918 / loopback (local-network auditing)
-  CLOUD_PROVIDER=aws|gcp|azure   Required for cloud scanner plugins (020/021/022)
+  CLOUD_PROVIDER=aws|gcp|azure   Required for cloud scanner plugins (020/021/022/023/030)
   AI_PROVIDER=openai|claude|ollama   AI provider for report generation
   COMPLIANCE_TSA_URL             RFC 3161 timestamp authority for SOC 2 attestation
 
+Cloud-scan hosts:
+  --host aws | gcp | azure       Sentinel literals (case-insensitive). These are not
+                                 DNS-resolved; they route the scan to the matching
+                                 cloud-scanner plugin via the provider's control-plane
+                                 API. Pair with --plugins 020,030 (or similar) — using
+                                 --plugins all on a sentinel host produces noisy
+                                 unreachable-host findings from non-cloud plugins.
+
 Examples:
   nsauditor-ai scan --host 10.0.0.1 --plugins all
   CLOUD_PROVIDER=aws AWS_PROFILE=default \\
-    nsauditor-ai scan --host aws --plugins 020
+    nsauditor-ai scan --host aws --plugins 020 --compliance soc2
   nsauditor-ai scan --host 10.0.0.0/24 --plugins all --compliance soc2
+  nsauditor-ai license install enterprise_eyJhbGciOiJFUzI1NiIs...
   nsauditor-ai license --status
 
 Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/pricing/`);
@@ -848,8 +919,134 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       for (const [name, enabled] of Object.entries(caps)) {
         console.log(`  ${enabled ? '✓' : '✗'} ${name}`);
       }
+    } else if (rawArgs.includes('--plugins')) {
+      // CE-0.1.30.3 — real enumeration of discovered plugins, grouped by
+      // source (CE / EE / custom NSAUDITOR_PLUGIN_PATH). Pre-fix this
+      // branch crashed with `TypeError: p.toLowerCase is not a function`
+      // (since hotfixed in 0.1.28 to a Usage fallback). Now: discover
+      // plugins, group by `_source`, format with active/required-tier
+      // status. Output format matches the EE README "Quick Start" example.
+      const tier = getTierFromEnv();
+      const caps = resolveCapabilities(tier);
+      const pm = await PluginManager.create(`${__dirname}/plugins`);
+
+      const groups = { ce: [], ee: [], custom: [] };
+      for (const plugin of pm.plugins) {
+        const source = plugin._source ?? 'ce';
+        if (!groups[source]) groups[source] = [];
+        groups[source].push(plugin);
+      }
+
+      const sourceLabels = {
+        ce: 'CE plugins (from nsauditor-ai)',
+        ee: 'EE plugins (from @nsasoft/nsauditor-ai-ee)',
+        custom: 'Custom plugins (from NSAUDITOR_PLUGIN_PATH)',
+      };
+
+      // Render in fixed order: ce → ee → custom (then any unknown sources alphabetical).
+      const renderOrder = ['ce', 'ee', 'custom', ...Object.keys(groups).filter((k) => !['ce','ee','custom'].includes(k)).sort()];
+      let totalRendered = 0;
+      for (const source of renderOrder) {
+        const plugins = groups[source];
+        if (!plugins || plugins.length === 0) continue;
+        if (totalRendered > 0) console.log('');
+        console.log(`${sourceLabels[source] ?? `${source} plugins`}:`);
+
+        // Sort by id (string-compare keeps zero-padded ids in numeric order).
+        const sorted = [...plugins].sort((a, b) =>
+          String(a.id ?? '').localeCompare(String(b.id ?? ''))
+        );
+        for (const plugin of sorted) {
+          const required = Array.isArray(plugin.requiredCapabilities) ? plugin.requiredCapabilities : [];
+          const allMet = required.length === 0 || required.every((c) => Boolean(caps[c]));
+          // Reviewer M2 fold: derive the required tier from the unmet
+          // capability set so the "requires: …" label is accurate even
+          // when the plugin doesn't declare a `tier` field. EE plugins
+          // 021/022/023 (no `tier` declaration) require `cloudScanners`
+          // which is enterprise-gated — pre-fold they showed
+          // "requires: pro" misleadingly. Now they show "requires:
+          // enterprise" via inferRequiredTier(). plugin.tier is the
+          // operator-declared override; fall back to inference.
+          const inferredTier = inferRequiredTier(required);
+          const requiresLabel = plugin.tier ?? inferredTier ?? 'pro';
+          const status = allMet ? '✓ active' : `✗ requires: ${requiresLabel}`;
+          // Layout matches the EE README example:
+          //   "  003 SSH Scanner            ✓ active"
+          const idStr = String(plugin.id ?? '?').padEnd(3);
+          const nameStr = String(plugin.name ?? '<unnamed>').padEnd(28);
+          console.log(`  ${idStr} ${nameStr} ${status}`);
+        }
+        totalRendered += sorted.length;
+      }
+
+      if (totalRendered === 0) {
+        console.log('No plugins discovered. Re-install nsauditor-ai or check NSAUDITOR_PLUGIN_PATH.');
+      } else {
+        console.log('');
+        console.log(`  ${totalRendered} plugin${totalRendered === 1 ? '' : 's'} total · current tier: ${tier}`);
+      }
+    } else if (rawArgs.includes('install')) {
+      // CE-0.1.30.4 — install command. Verify the JWT FIRST, then persist
+      // to a platform-appropriate location (macOS Keychain / file).
+      // Closes the customer-onboarding gap where new customers had no
+      // friendly way to register a license without manually editing
+      // shell-rc / .env files.
+      const installIdx = rawArgs.indexOf('install');
+      const rawKey = rawArgs[installIdx + 1];
+      const installKey = typeof rawKey === 'string' ? rawKey.trim() : '';
+
+      if (!installKey || installKey.startsWith('-')) {
+        console.error('Usage: nsauditor-ai license install <KEY>');
+        console.error('  KEY is the JWT from your purchase confirmation (starts with `pro_` or `enterprise_`).');
+        console.error('  Verifies the signature before persisting; invalid keys are rejected.');
+        console.error('');
+        console.error('Storage locations (chosen by platform):');
+        console.error('  macOS:    Keychain — service "nsauditor-ai", account "NSAUDITOR_LICENSE_KEY"');
+        console.error('  Linux:    $XDG_CONFIG_HOME/nsauditor/.env (or ~/.nsauditor/.env), mode 0600');
+        console.error('  Windows:  %USERPROFILE%\\.nsauditor\\.env (DPAPI integration on roadmap)');
+        process.exit(2);
+      }
+
+      // 1. Verify the key BEFORE persisting. Bypasses the resolver chain
+      //    by passing the key explicitly to loadLicense().
+      const verified = await loadLicense(installKey);
+      if (!verified.valid) {
+        console.error(`✗ License key rejected: ${verified.reason}`);
+        console.error('  No changes made. Confirm the key matches your purchase email exactly.');
+        process.exit(1);
+      }
+
+      // 2. Persist (Keychain on macOS / file elsewhere). Lazy import to
+      //    avoid loading the persistor unless install is actually invoked.
+      const { persistLicenseKey } = await import('./utils/license.mjs');
+      const persisted = await persistLicenseKey(installKey);
+      if (!persisted.ok) {
+        console.error(`✗ Verification succeeded but storage failed: ${persisted.error}`);
+        console.error('  Fall-back: set NSAUDITOR_LICENSE_KEY env var manually:');
+        console.error('    export NSAUDITOR_LICENSE_KEY="<your-key>"');
+        process.exit(1);
+      }
+
+      // 3. Confirm. Same shape as `license --status` so customers see
+      //    the persisted key reflected back. NEVER print the key value
+      //    itself — it's a secret. Reviewer M1 fold: surface the
+      //    Keychain-fallback warning if the persistor returned one
+      //    (silent fallback would leave macOS users believing they
+      //    have Keychain protection when they don't).
+      const tierLabel = { ce: 'Community Edition (CE)', pro: 'Pro', enterprise: 'Enterprise' };
+      if (persisted.warning) {
+        console.warn(`⚠  ${persisted.warning}`);
+      }
+      console.log(`✓ ${tierLabel[verified.tier]} license installed`);
+      console.log(`  Stored at: ${persisted.location}`);
+      console.log(`  Org: ${verified.org}`);
+      console.log(`  Seats: ${verified.seats}`);
+      console.log(`  License ID: ${verified.licenseId}`);
+      console.log(`  Expires: ${verified.expiresAt}`);
+      console.log('');
+      console.log('  Verify with: nsauditor-ai license --status');
     } else {
-      console.log('Usage: nsauditor-ai license --status | --capabilities');
+      console.log('Usage: nsauditor-ai license --status | --capabilities | --plugins | install <KEY>');
     }
     process.exit(0);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/utils/capabilities.mjs

@@ -51,3 +51,29 @@ export function resolveCapabilities(tier = 'ce') {
 export function hasCapability(capabilities, cap) {
   return Boolean(capabilities?.[cap]);
 }
+
+// CE-0.1.30.3 reviewer M2 fold: derive the highest tier among a plugin's
+// required capabilities. Used by `license --plugins` to render
+// "✗ requires: <tier>" accurately when a plugin doesn't declare a `tier`
+// field. Pre-fold the CLI fell back to `'pro'` for plugins like 021/022/023
+// (no `tier` field, but require `cloudScanners` which is enterprise-gated)
+// — which misled customers about what license they needed.
+//
+// Returns 'ce' / 'pro' / 'enterprise' (the highest tier among all required
+// caps), or null when the plugin has no requiredCapabilities.
+const _TIER_RANK = { ce: 0, pro: 1, enterprise: 2 };
+const _RANK_TO_TIER = ['ce', 'pro', 'enterprise'];
+
+export function inferRequiredTier(requiredCapabilities) {
+  if (!Array.isArray(requiredCapabilities) || requiredCapabilities.length === 0) {
+    return null;
+  }
+  let maxRank = 0;
+  for (const cap of requiredCapabilities) {
+    const def = CAPABILITIES[cap];
+    if (!def) continue;
+    const rank = _TIER_RANK[def.tier] ?? 0;
+    if (rank > maxRank) maxRank = rank;
+  }
+  return _RANK_TO_TIER[maxRank];
+}

package/utils/license.mjs

@@ -7,6 +7,11 @@
 // become invalid. See license-manager docs/architecture.md for full procedure.
 
 import { jwtVerify, importSPKI } from 'jose';
+import { promises as fsp } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import dotenv from 'dotenv';
+import { keychainGet, keychainSet } from './keychain.mjs';
 
 // ES256 public key — embedded directly so it works in npm package (no file read).
 // Corresponding private key is in the license-manager service (NEVER shipped here).
@@ -41,6 +46,229 @@ export function getTierFromEnv() {
   return 'ce';
 }
 
+/**
+ * CE-0.1.30.2 — multi-source license-key resolution chain.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. process.env.NSAUDITOR_LICENSE_KEY   — CI/CD takes precedence
+ *   2. macOS Keychain (service=nsauditor-ai, account=NSAUDITOR_LICENSE_KEY)
+ *      — set by `nsauditor-ai license install <KEY>` on macOS
+ *   3. $XDG_CONFIG_HOME/nsauditor/.env (or ~/.nsauditor/.env) — universal
+ *      file fallback; set by `license install` on Linux/Windows OR
+ *      manually edited by the operator. Mode 0600 expected; permissive
+ *      mode triggers a warning (still loaded — operator's choice).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts._homeFileOverride]  — test seam. Path to a .env-format
+ *   file to read instead of ~/.nsauditor/.env. Bypasses XDG resolution.
+ * @param {Function} [opts._keychainGet]      — test seam. Replaces the macOS
+ *   Keychain reader.
+ * @returns {Promise<string|null>} The license key string, or null if no
+ *   source had one.
+ */
+export async function resolveLicenseKey(opts = {}) {
+  // 1. env var
+  if (process.env.NSAUDITOR_LICENSE_KEY) return process.env.NSAUDITOR_LICENSE_KEY;
+
+  // 2. platform secret store (macOS Keychain today; Linux/Windows skip)
+  const kget = opts._keychainGet ?? keychainGet;
+  try {
+    const fromKeychain = await kget('NSAUDITOR_LICENSE_KEY');
+    if (fromKeychain) return fromKeychain;
+  } catch { /* keychain unavailable — fall through */ }
+
+  // 3. ~/.nsauditor/.env (or $XDG_CONFIG_HOME/nsauditor/.env)
+  const filePath = opts._homeFileOverride ?? defaultLicenseFilePath();
+  try {
+    const stat = await fsp.stat(filePath);
+    // Warn (non-fatal) if mode is more permissive than 0600 on POSIX.
+    // Windows has no concept of POSIX file mode; skip the check there.
+    // Reviewer M10 fold: only warn once per path per process to avoid
+    // spamming the console under repeated CLI invocations.
+    if (platform() !== 'win32' && stat.isFile() && (stat.mode & 0o077) !== 0) {
+      if (!_permissiveWarnedPaths.has(filePath)) {
+        const modeStr = (stat.mode & 0o777).toString(8).padStart(3, '0');
+        console.warn(`⚠  ${filePath} has permissive mode ${modeStr} — recommend chmod 0600`);
+        _permissiveWarnedPaths.add(filePath);
+      }
+    }
+    const buf = await fsp.readFile(filePath, 'utf8');
+    const parsed = dotenv.parse(buf);
+    if (parsed.NSAUDITOR_LICENSE_KEY) return parsed.NSAUDITOR_LICENSE_KEY;
+  } catch { /* file missing / unreadable — fall through */ }
+
+  return null;
+}
+
+// CE-0.1.30.2 reviewer M10: one-shot permissive-mode warning per path per
+// process. Without this, every `loadLicense()` call against a 0644 file
+// emits a console.warn — and CE re-resolves on every CLI invocation
+// (plus the `cmd === 'license'` branch double-calls today, see reviewer
+// M7 follow-up). Module-scoped Set keeps memory bounded (~1 path per
+// install) and silences the noise without hiding the message from
+// operators who haven't seen it yet.
+const _permissiveWarnedPaths = new Set();
+
+function defaultLicenseFilePath() {
+  // Honor $XDG_CONFIG_HOME (Linux convention; some macOS users set it).
+  // Falls back to ~/.nsauditor/.env which is what the existing README
+  // method-2 docs already promise.
+  if (process.env.XDG_CONFIG_HOME) {
+    return join(process.env.XDG_CONFIG_HOME, 'nsauditor', '.env');
+  }
+  return join(homedir(), '.nsauditor', '.env');
+}
+
+/**
+ * CE-0.1.30.4 — persist a verified license key to a platform-appropriate
+ * location so subsequent `loadLicense()` calls find it via the resolver
+ * chain (CE-0.1.30.2).
+ *
+ * Platform routing:
+ *   - macOS:    keychainSet('NSAUDITOR_LICENSE_KEY', key) via the existing
+ *               utils/keychain.mjs helper. If Keychain is unavailable
+ *               (e.g., headless mac without `security` daemon, user
+ *               denied the prompt), falls back to the file path so
+ *               install does not silently fail.
+ *   - Linux:    write $XDG_CONFIG_HOME/nsauditor/.env (or ~/.nsauditor/.env)
+ *               with mode 0600 (parent dir 0700). Preserves any OTHER
+ *               env-vars the operator has in the file — only the
+ *               NSAUDITOR_LICENSE_KEY line is replaced/added.
+ *   - Windows:  same file path (%USERPROFILE%\.nsauditor\.env). No DPAPI
+ *               yet — defer to a future release; the file ACL inherits
+ *               from the user profile which is typically restrictive
+ *               enough on Windows 10+.
+ *
+ * The caller MUST verify the key via loadLicense() BEFORE calling
+ * persistLicenseKey() — this function does not validate. Persisting an
+ * invalid or expired key would store garbage and the next loadLicense()
+ * call would just reject it again, but doing so silently undermines the
+ * `install` command's contract ("we only persist verified keys").
+ *
+ * @param {string} key - The full prefixed key (`pro_eyJ...` or `enterprise_eyJ...`).
+ * @param {object} [opts]
+ * @param {string} [opts._platform]         - Test seam (override Node's platform()).
+ * @param {Function} [opts._keychainSet]    - Test seam (replace Keychain writer).
+ * @param {string} [opts._homeFileOverride] - Test seam (override the file path).
+ * @returns {Promise<{ok: true, location: string} | {ok: false, error: string}>}
+ *   On success, `location` is a human-readable string ("macOS Keychain
+ *   (service=nsauditor-ai)" or the filesystem path). The `install`
+ *   command surfaces this so the operator knows where the key landed.
+ */
+export async function persistLicenseKey(key, opts = {}) {
+  if (typeof key !== 'string' || key.length === 0) {
+    return { ok: false, error: 'persistLicenseKey: key must be a non-empty string' };
+  }
+
+  const plat = opts._platform ?? platform();
+  const kset = opts._keychainSet ?? keychainSet;
+
+  // 1. macOS: try Keychain first.
+  // Reviewer M1 fold: track Keychain-fallback reason so the caller can
+  // surface it to the operator. Pre-fix, the fallback was silent — the
+  // operator only learned about it implicitly via the `location` line
+  // showing a filesystem path instead of "macOS Keychain (...)".
+  let keychainFallbackReason = null;
+  if (plat === 'darwin') {
+    try {
+      await kset('NSAUDITOR_LICENSE_KEY', key);
+      return { ok: true, location: 'macOS Keychain (service=nsauditor-ai)' };
+    } catch (err) {
+      // Fall through to file-based storage. Examples: `security` daemon
+      // unavailable on headless mac; user denied the Keychain prompt;
+      // SIP-restricted environment.
+      keychainFallbackReason = err && err.message ? err.message : String(err);
+    }
+  }
+
+  // 2. File-based storage (Linux, Windows, macOS Keychain fallback).
+  try {
+    const filePath = opts._homeFileOverride ?? defaultLicenseFilePath();
+    const dir = dirname(filePath);
+    // Create dir with 0700 if missing (recursive=true is a no-op if it
+    // already exists; mode is only applied to NEW dirs along the path).
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+
+    // Preserve other env-vars in an existing file. Read-modify-write
+    // pattern: parse current contents, replace/add the
+    // NSAUDITOR_LICENSE_KEY line, write back.
+    let existingContent = '';
+    try {
+      existingContent = await fsp.readFile(filePath, 'utf8');
+    } catch { /* missing file — fine, we'll create one */ }
+
+    const newContent = mergeLicenseIntoEnvFile(existingContent, key);
+    await fsp.writeFile(filePath, newContent, { mode: 0o600 });
+
+    // Re-chmod in case the file pre-existed with a more permissive mode
+    // (writeFile only sets mode on CREATE, not overwrite).
+    if (plat !== 'win32') {
+      await fsp.chmod(filePath, 0o600);
+    }
+
+    const result = { ok: true, location: filePath };
+    if (keychainFallbackReason !== null) {
+      result.warning =
+        `macOS Keychain unavailable (${keychainFallbackReason}); fell back to file storage. ` +
+        `Re-run after granting Keychain access for stronger protection.`;
+    }
+    return result;
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Merge a license key into the existing dotenv-format file content,
+ * preserving every OTHER line. If a NSAUDITOR_LICENSE_KEY line already
+ * exists, replace it; otherwise append. If the file was empty/new,
+ * write a header comment.
+ *
+ * Reviewer M2 / M2b folds:
+ *  - **Multi-occurrence safety**: a corrupted file with TWO+ existing
+ *    `NSAUDITOR_LICENSE_KEY=` lines previously had only the first
+ *    replaced. dotenv parses last-wins, so `--status` would show the
+ *    OLD value while install reported success. Now we replace the first
+ *    occurrence and remove the rest, collapsing blank lines.
+ *  - **CRLF preservation**: the regex anchors on `[ \t]*` (not `\s*`,
+ *    which matches `\r`) and the value-tail uses `[^\r\n]*` so Windows-
+ *    style line endings are not mangled. The replacement line itself
+ *    uses `\n` regardless — Notepad and dotenv both accept mixed
+ *    endings, but this avoids producing them from `\r`-stripped tails.
+ *
+ * Exported for test coverage of the merge semantics specifically.
+ * @internal
+ */
+export function mergeLicenseIntoEnvFile(existingContent, key) {
+  const KEY_LINE_RE = /^[ \t]*NSAUDITOR_LICENSE_KEY[ \t]*=[^\r\n]*$/gm;
+  const newLine = `NSAUDITOR_LICENSE_KEY=${key}`;
+
+  // Count matches (regex needs the global flag for matchAll-equivalence).
+  const matches = existingContent.match(KEY_LINE_RE);
+  if (matches && matches.length > 0) {
+    // Replace the first occurrence in place; remove any duplicates
+    // (corrupted-file defense). Collapse the blank lines that result.
+    let firstReplaced = false;
+    let merged = existingContent.replace(KEY_LINE_RE, () => {
+      if (firstReplaced) return '__NSAUDITOR_PURGE__';   // sentinel for removal
+      firstReplaced = true;
+      return newLine;
+    });
+    // Drop sentinel lines + their trailing newline.
+    merged = merged.replace(/__NSAUDITOR_PURGE__\r?\n?/g, '');
+    return merged;
+  }
+
+  if (existingContent.trim().length === 0) {
+    // Empty/new file — write a header.
+    return `# NSAuditor AI license — set via \`nsauditor-ai license install\`\n${newLine}\n`;
+  }
+
+  // Append to existing content (with a separating newline if needed).
+  const sep = existingContent.endsWith('\n') ? '' : '\n';
+  return `${existingContent}${sep}${newLine}\n`;
+}
+
 /**
  * Full async JWT verification. Call once at startup.
  * On success, caches verified tier so subsequent getTierFromEnv() calls
@@ -48,12 +276,17 @@ export function getTierFromEnv() {
  *
  * Never throws — degrades to 'ce' on any failure.
  *
- * @param {string} [keyStr] - License key; defaults to NSAUDITOR_LICENSE_KEY env var.
+ * @param {string} [keyStr] - License key; if omitted, runs the multi-source
+ *   resolution chain (env var → Keychain → ~/.nsauditor/.env). See
+ *   resolveLicenseKey() above.
  * @returns {Promise<{valid: boolean, tier: string, org?: string, seats?: number,
  *   licenseId?: string, capabilities?: string[], expiresAt?: string, reason?: string}>}
  */
 export async function loadLicense(keyStr) {
-  const raw = keyStr ?? process.env.NSAUDITOR_LICENSE_KEY;
+  // Explicit keyStr argument wins (preserves the existing behavior for
+  // callers like the `license --status` subcommand which passes the env
+  // var directly). When omitted, run the multi-source resolution chain.
+  const raw = keyStr ?? (await resolveLicenseKey());
   if (!raw) return { valid: false, tier: 'ce', reason: 'no key provided' };
 
   // Strip tier prefix
@@ -124,4 +357,5 @@ export function _resetCache() {
     throw new Error('_resetCache is test-only and disabled in production');
   }
   _verifiedTier = null;
+  _permissiveWarnedPaths.clear();
 }

package/utils/oui.mjs

@@ -6,11 +6,19 @@ import { fileURLToPath } from "url";
 
 let OUI_DB = null;
 
+// CE-0.1.30.3 reviewer M1 fold: gate startup chatter behind NSA_VERBOSE so
+// operator-facing flags like `nsauditor-ai license --plugins` and
+// `nsauditor-ai --version` do not pollute stdout with debug banners.
+// Errors remain unconditional (console.error, stderr) — the operator
+// should still see real failure modes.
+const VERBOSE = /^(1|true|yes|on)$/i.test(String(process.env.NSA_VERBOSE || ''));
+const vlog = VERBOSE ? (...a) => console.log(...a) : () => {};
+
 // Try to import oui-data module, fall back to local file if it fails
 async function loadOuiData() {
   try {
     const ouiData = await import("oui-data", { with: { type: "json" } }).then(module => module.default);
-    console.log("[oui.mjs] Successfully loaded oui-data module with", Object.keys(ouiData).length, "entries");
+    vlog("[oui.mjs] Successfully loaded oui-data module with", Object.keys(ouiData).length, "entries");
     return ouiData;
   } catch (e) {
     console.error("[oui.mjs] Failed to load oui-data module:", e.message);
@@ -19,7 +27,7 @@ async function loadOuiData() {
       const __dirname = path.dirname(fileURLToPath(import.meta.url));
       const localPath = path.join(__dirname, "oui-data.json");
       const data = JSON.parse(await fs.readFile(localPath, "utf8"));
-      console.log("[oui.mjs] Loaded fallback oui-data.json from", localPath, "with", Object.keys(data).length, "entries");
+      vlog("[oui.mjs] Loaded fallback oui-data.json from", localPath, "with", Object.keys(data).length, "entries");
       return data;
     } catch (fallbackError) {
       console.error("[oui.mjs] Failed to load fallback oui-data.json:", fallbackError.message);
@@ -65,7 +73,7 @@ export function lookupVendor(mac) {
     const oui = macToOUI(mac);
     const entry = OUI_DB[oui];
     const vendor = pickOrgName(entry);
-    console.log(`[oui.mjs] Lookup for MAC ${mac} (OUI: ${oui}) -> Vendor: ${vendor || 'Not found'}`);
+    vlog(`[oui.mjs] Lookup for MAC ${mac} (OUI: ${oui}) -> Vendor: ${vendor || 'Not found'}`);
     return vendor;
   } catch (e) {
     console.error("[oui.mjs] Lookup error:", e.message);