nsauditor-ai 0.1.30 → 0.1.31

package/README.md

@@ -15,6 +15,43 @@ 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.31) — security release
+
+**MCP server authentication is now required.** Pre-0.1.31, the local MCP server (stdio transport) accepted any incoming JSON-RPC frames — any process running as your user could spawn it and use the Pro/Enterprise tools (which include the AWS-talking shadow-admin path detectors that ship in `@nsasoft/nsauditor-ai-ee@0.3.4`). 0.1.31 closes this gap with a per-operator shared-secret check at startup.
+
+**Breaking change for existing operators**: after upgrading, run `nsauditor-ai mcp install-key` once. Without this step, the MCP server refuses to start and Claude Desktop will report a connection failure. The error message points back at this command.
+
+```bash
+npm install -g nsauditor-ai@0.1.31
+nsauditor-ai mcp install-key   # generates a 256-bit key, persists it, prints Claude Desktop config snippet
+```
+
+**What's in the box (EE-SEC.1):**
+
+- `nsauditor-ai mcp install-key` — generates a 256-bit auth key, stores it in macOS Keychain (or `~/.nsauditor/.env` mode 0600 elsewhere), prints a paste-ready Claude Desktop config snippet. Run once per machine.
+- `nsauditor-ai mcp status` / `print-key --confirm` / `rotate-key --confirm` — inspect, reveal (TTY-only by default), and rotate the key.
+- **`keychain:` indirection on macOS** — the printed config snippet uses `"NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY"` instead of the literal key. The MCP server resolves the placeholder at startup; **the secret never lands in your `claude_desktop_config.json`** (which is mode 0644 on macOS by default — readable by other local users and any sandboxed app). On Linux/Windows where there's no Keychain equivalent, the snippet falls back to the literal key with a `chmod 600` warning.
+- **`NSA_MCP_AUTH_DISABLE=1`** escape hatch for CI / dev — emits a stderr warning every startup so you don't forget; a louder warning fires when DISABLE is set AND no key was ever installed.
+- Multi-source resolver mirrors the existing license-key pattern: env → Keychain → file. Constant-time key comparison via `crypto.timingSafeEqual`. Two-reviewer cycle (general code review + network-security-audit lens) caught and folded 2 CRITICAL + 5 MEDIUM findings same-session before commit; full threat model documented in [`utils/mcp_auth.mjs`](./utils/mcp_auth.mjs).
+
+See the [MCP Server § Authentication section](#authentication-required-new-in-0131) for the full setup walkthrough, troubleshooting, and the threat-model table.
+
+---
+
+## What's New in Enterprise Edition (0.3.3)
+
+The Enterprise Edition (`@nsasoft/nsauditor-ai-ee`) shipped a 0.3.3 point release on 2026-05-08. CE stays at 0.1.30 — no bump required, the EE upgrade is single-line: `npm install -g @nsasoft/nsauditor-ai-ee@latest`. The release closes a Critical false-clean SOC 2 reporting bug that mirrored the AWS-side bug fixed in 0.3.2 — this time in the Azure cloud scanner — and extends mapped SOC 2 coverage to multi-cloud:
+
+- **Azure plugin (022) finding-shape rewrite** — the EE-0.3.2.1 cloud-finding harvester only recognized one canonical shape (`{resource, severity, issues[]}`); plugin 022 was emitting `{severity, finding, resource}` (singular `finding`). Findings reached the engine but were silently dropped — Azure customers running `--compliance soc2` saw "6/6 covered controls passing" against subscriptions with real RBAC + NSG + Storage issues. Caught at internal dogfood against a live Azure subscription.
+- **GCP plugin (021) preventive shape port** — plugin 021 had the same `{finding}` singular shape; pre-emptively migrated to the canonical shape so the same bug doesn't re-emerge for GCP customers in v0.4.0 when GCP `mapsToFindings` rules ship.
+- **Azure → SOC 2 mapping rules added** — RBAC `Owner | Contributor | User Access Administrator at subscription scope` → CC6.1 (3 patterns); NSG `0.0.0.0/0 → port` anchored regex → CC6.6; Storage `allowBlobPublicAccess` + `enableHttpsTrafficOnly` → C1.1. CC6.1, CC6.6, and C1.1 now have *both* AWS-side and Azure-side evidence rows — actual multi-cloud SOC 2 evidence.
+- **Drift detector extended to all three cloud plugins** — every `azure-cloud-scanner` `titlePattern` in `soc2.json` is now asserted to match at least one canonical issue string the plugin emits, and vice versa. The class-of-bug that produced two false-clean variants in successive releases is now structurally closed.
+- **Pre-publish gate fixes** — `@azure/arm-authorization` peer-dep was pinned at `^10.0.0` (latest published is 9.0.0; clean installs would have failed); `@azure/arm-storage` was missing from `optionalDependencies` (Storage audit silently no-op'd on clean install). Both caught at the pre-publish clean-tarball smoke and corrected before ship.
+
+See [EE README](https://www.npmjs.com/package/@nsasoft/nsauditor-ai-ee) for the full 0.3.3 changelog and Azure scan walkthrough.
+
+---
+
 ## 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:
@@ -60,7 +97,7 @@ NSAuditor AI is available in three editions:
 | Advanced CTEM + trend analysis | — | ✅ | ✅ |
 | Cloud scanners (AWS/GCP/Azure) | — | — | ✅ |
 | Zero Trust assessment | — | — | ✅ |
-| SOC 2 compliance (8 covered + 5 partial controls) | — | — | ✅ |
+| SOC 2 compliance (8 covered + 5 partial controls; AWS + Azure evidence streams) | — | — | ✅ |
 | SLA/MTTR tracking + compensating controls | — | — | ✅ |
 | Recurring-scan attestation (Type II evidence) | — | — | ✅ |
 | GRC platform connector (Vanta) | — | — | ✅ |
@@ -182,7 +219,7 @@ Results land in `./out/<host>_<timestamp>/`:
 |---|---|---|---|
 | 020 | AWS Cloud Scanner | Enterprise | Security group + IAM policy analysis |
 | 021 | GCP Cloud Scanner | Enterprise | Firewall rules + IAM bindings |
-| 022 | Azure Cloud Scanner | Enterprise | NSG rules + RBAC analysis |
+| 022 | Azure Cloud Scanner | Enterprise | NSG rules + RBAC role assignments + Storage account hardening; SOC 2 mapping (CC6.1, CC6.6, C1.1) shipped in EE 0.3.3 |
 | 023 | Zero Trust Checker | Enterprise | Segmentation, encryption, identity, lateral movement scoring |
 | — | SOC 2 Compliance Engine | Enterprise | AICPA TSC 2017 control mapping, chain-of-custody, RFC 3161 timestamps, suppression workflow |
 | — | SLA & MTTR Tracking | Enterprise | Per-severity SLA targets, compensating-control flow, finding lifecycle |
@@ -292,7 +329,46 @@ npx nsauditor-ai-mcp
 | `compliance_check` | Compliance mapping with gap analysis |
 | `export_report` | Generate formatted compliance report |
 
-Security: SSRF protection on all host inputs (blocks RFC 1918, loopback, fc00::/7, cloud metadata), port validation (1–65535), CPE format enforcement, dependency injection for test isolation.
+Security: SSRF protection on all host inputs (blocks RFC 1918, loopback, fc00::/7, cloud metadata), port validation (1–65535), CPE format enforcement, dependency injection for test isolation. **Server-startup authentication required as of 0.1.31** — see next section.
+
+### Authentication (required, NEW in 0.1.31)
+
+The MCP server uses stdio transport, which means it runs as a child process of whatever client launches it. Without authentication, **any process running as your user could spawn the server and use its tools** — including the Pro/Enterprise tools that talk to AWS, generate compliance reports, and access your scan history. 0.1.31 closes this gap with a per-operator shared-secret check at server startup.
+
+**One-time setup** (run once per machine after `npm install -g nsauditor-ai`):
+
+```bash
+nsauditor-ai mcp install-key
+```
+
+This generates a 256-bit auth key, stores it in the macOS Keychain (or `~/.nsauditor/.env` mode 0600 on Linux/Windows), and prints the Claude Desktop config snippet for you to paste. **The MCP server refuses to start unless the env-presented key matches the stored key** (constant-time compare; mismatch produces an actionable error pointing at this command).
+
+**Inspect / verify**:
+
+```bash
+nsauditor-ai mcp status                  # shows storage source WITHOUT printing the key
+nsauditor-ai mcp print-key --confirm     # reveals the key (use sparingly; refuses non-TTY output)
+nsauditor-ai mcp rotate-key --confirm    # generates a new key (invalidates old one immediately)
+```
+
+**Why the Claude Desktop config snippet uses `keychain:` indirection on macOS**: the printed snippet looks like `"NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY"` rather than the literal key value. The MCP server resolves the placeholder from your Keychain at startup. Net effect: **the secret never lands in `~/Library/Application Support/Claude/claude_desktop_config.json`** (which is mode 0644 by default — readable by other local users and any macOS app with Documents/Application Support entitlement). On Linux/Windows where there's no Keychain equivalent, the snippet uses the literal key with an explicit `chmod 600` warning.
+
+**Threat model — what this defends, what it doesn't**:
+
+| Threat | Defended? |
+|---|---|
+| Malicious npm post-install / browser extension running as you spawning the server | ✅ — attacker cannot read your Keychain without GUI prompt |
+| Other users on a shared dev box / CI runner | ✅ — key is per-operator |
+| Future HTTP/SSE transport network exposure | ✅ — key gates server startup, not network |
+| Attacker with full operator code-exec AND can suppress macOS Keychain prompts | ⚠ partial — recent macOS versions log Keychain-access denial events |
+| Debugger-attach memory snooping | ⚠ out of scope (any shared-secret auth has this limit) |
+| Linux env-var visibility in `/proc/<pid>/environ` | ⚠ partial — only literal-key configs leak; the macOS keychain: indirection avoids this entirely |
+
+**Escape hatch for CI / dev** (operator-acknowledged risk; emits a stderr warning every startup):
+
+```bash
+NSA_MCP_AUTH_DISABLE=1 nsauditor-ai-mcp
+```
 
 ### Claude Desktop Setup
 
@@ -300,6 +376,7 @@ First install the package globally:
 
 ```bash
 npm install -g nsauditor-ai
+nsauditor-ai mcp install-key   # NEW in 0.1.31 — required before MCP server will start
 ```
 
 Then add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):
@@ -308,11 +385,11 @@ Then add this to your `claude_desktop_config.json` (Settings → Developer → E
 {
   "mcpServers": {
     "nsauditor-ai": {
-      "command": "node",
-      "args": ["/path/to/global/node_modules/nsauditor-ai/mcp_server.mjs"],
+      "command": "nsauditor-ai-mcp",
       "env": {
+        "NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY",
         "AI_PROVIDER": "claude",
-        "ANTHROPIC_API_KEY": "your-key-here",
+        "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY",
         "NSA_ALLOW_ALL_HOSTS": "1",
         "PLUGIN_TIMEOUT_MS": "5000"
       }
@@ -321,8 +398,9 @@ Then add this to your `claude_desktop_config.json` (Settings → Developer → E
 }
 ```
 
-Find your global install path with `npm root -g`, then append `/nsauditor-ai/mcp_server.mjs`.
+The exact `NSA_MCP_AUTH_KEY` value to paste is printed by `nsauditor-ai mcp install-key` — on macOS it's the `keychain:NSA_MCP_AUTH_KEY` placeholder shown above; on Linux/Windows it's the literal key value (and you should `chmod 600` your config file).
 
+- `NSA_MCP_AUTH_KEY` — **required as of 0.1.31** (see Authentication section above)
 - `NSA_ALLOW_ALL_HOSTS=1` — required to scan private/RFC 1918 addresses (e.g., `192.168.x.x`)
 - `PLUGIN_TIMEOUT_MS=5000` — reduces per-plugin timeout to 5s so the full scan completes within Claude Desktop's 60s MCP limit
 - `AI_PROVIDER` and API key — optional, enables AI-powered analysis of scan results
@@ -330,9 +408,24 @@ Find your global install path with `npm root -g`, then append `/nsauditor-ai/mcp
 ### Claude Code Setup
 
 ```bash
-claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp
+nsauditor-ai mcp install-key   # NEW in 0.1.31 — required before MCP server will start
+claude mcp add nsauditor-ai \
+  --env NSA_MCP_AUTH_KEY=keychain:NSA_MCP_AUTH_KEY \
+  -- npx nsauditor-ai-mcp
 ```
 
+(On Linux/Windows, replace the `keychain:NSA_MCP_AUTH_KEY` placeholder with the literal key printed by `install-key`.)
+
+### Troubleshooting MCP authentication
+
+**"MCP authentication is not configured"** at server startup → run `nsauditor-ai mcp install-key`. If you set `NSA_MCP_AUTH_DISABLE=1` in CI by intent, that's fine — but check that you didn't forget it in your shell rc.
+
+**"NSA_MCP_AUTH_KEY env var is not set, but a key is configured in storage"** → the server found a key in your Keychain (or `~/.nsauditor/.env`) but the spawning client didn't pass `NSA_MCP_AUTH_KEY` in the env block. Update your Claude Desktop / Claude Code config to include the env value (use `nsauditor-ai mcp install-key` output as a reference snippet).
+
+**"NSA_MCP_AUTH_KEY env var does not match the key configured in storage"** → most often means you ran `nsauditor-ai mcp rotate-key --confirm` but didn't update Claude Desktop config with the new key. Run `nsauditor-ai mcp status` to confirm storage source, then either re-paste the new key or use `keychain:NSA_MCP_AUTH_KEY` indirection (macOS only) so future rotations don't require a config change.
+
+**"MCP_AUTH uses keychain: indirection but the referenced Keychain entry could not be read"** → typically a headless macOS / SSH-only CI runner where there's no GUI session to approve Keychain access. Replace the `keychain:` placeholder with the literal key value (or move auth to `~/.nsauditor/.env` with mode 0600).
+
 ---
 
 ## Secure Credential Storage

package/cli.mjs

@@ -853,6 +853,18 @@ License subcommands:
   nsauditor-ai license --plugins        List discovered plugins grouped by source
                                         (CE / EE / custom) with active-or-required-tier
 
+MCP server-auth subcommands (EE-SEC.1):
+  nsauditor-ai mcp install-key          Generate a new MCP auth key, persist (Keychain
+                                        on macOS, ~/.nsauditor/.env elsewhere), print
+                                        Claude Desktop config snippet. Run ONCE per
+                                        machine; without this the MCP server refuses
+                                        to start (anti-spoofing for Pro/Enterprise tools).
+  nsauditor-ai mcp install-key <KEY>    Persist a caller-supplied key (e.g., enterprise-
+                                        managed secret). Validates shape before storing.
+  nsauditor-ai mcp print-key --confirm  Reveal the stored key (use with care)
+  nsauditor-ai mcp rotate-key           Replace the stored key with a fresh one
+  nsauditor-ai mcp status               Show storage source without revealing the key
+
 Security subcommands (macOS Keychain):
   nsauditor-ai security set <KEY>       Store a secret (read from stdin)
   nsauditor-ai security delete <KEY>    Remove a secret
@@ -861,6 +873,9 @@ Security subcommands (macOS Keychain):
 
 Environment:
   NSAUDITOR_LICENSE_KEY          Pro/Enterprise license JWT (env var; takes precedence)
+  NSA_MCP_AUTH_KEY               MCP server auth key — read by mcp_server at startup;
+                                 client supplies via Claude Desktop config env block
+  NSA_MCP_AUTH_DISABLE=1         Skip MCP auth check (CI/dev escape hatch — emits warn)
   NSA_ALLOW_ALL_HOSTS=1          Permit RFC1918 / loopback (local-network auditing)
   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
@@ -1051,6 +1066,218 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     process.exit(0);
   }
 
+  // EE-SEC.1: MCP server authentication management. Generates, stores,
+  // and inspects the shared secret that authorizes Claude Desktop (or
+  // any MCP client) to call the local MCP server. Without this, any
+  // process running as the operator could spawn the server and call
+  // the Pro/Enterprise tools — including the AWS-talking shadow-admin
+  // path detectors in EE 0.3.4. See utils/mcp_auth.mjs for the full
+  // threat model.
+  if (cmd === 'mcp') {
+    const {
+      generateMcpAuthKey,
+      validateMcpAuthKeyShape,
+      persistMcpAuthKey,
+      reportMcpAuthSource,
+      MCP_AUTH_ENV_VAR,
+      MCP_AUTH_DISABLE_ENV_VAR,
+    } = await import('./utils/mcp_auth.mjs');
+
+    const rawArgs = process.argv.slice(2);
+    const subCmd = rawArgs[1]; // install-key | print-key | rotate-key | status
+
+    function printConfigSnippet(key, persistedLocation) {
+      // Claude Desktop config snippet — the canonical client integration
+      // for stdio MCP servers. Operators paste this into
+      // ~/Library/Application Support/Claude/claude_desktop_config.json
+      // (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
+      //
+      // Reviewer 2 CRITICAL #2 fold: when the key was persisted to
+      // macOS Keychain, emit a `keychain:` indirection in the snippet
+      // instead of the literal key. Claude Desktop's config file is
+      // typically world-readable on macOS (default umask 0644); baking
+      // the secret into it defeats the per-operator threat model.
+      // The MCP server resolves `keychain:LABEL` at startup via
+      // resolveSecret() (utils/keychain.mjs:105), pulling the actual
+      // value from Keychain — secret never leaves the secure store.
+      //
+      // On Linux/Windows there's no equivalent secret store today; the
+      // snippet uses the literal key value with an explicit chmod warning.
+      const onKeychain = typeof persistedLocation === 'string' && persistedLocation.includes('Keychain');
+      const envValue = onKeychain ? `keychain:${MCP_AUTH_ENV_VAR}` : key;
+
+      console.log('');
+      console.log('Add this to your Claude Desktop config (claude_desktop_config.json):');
+      console.log('');
+      console.log('  {');
+      console.log('    "mcpServers": {');
+      console.log('      "nsauditor-ai": {');
+      console.log('        "command": "nsauditor-ai-mcp",');
+      console.log(`        "env": { "${MCP_AUTH_ENV_VAR}": "${envValue}" }`);
+      console.log('      }');
+      console.log('    }');
+      console.log('  }');
+      console.log('');
+      if (onKeychain) {
+        console.log(`The "${envValue}" placeholder tells the MCP server to resolve the actual`);
+        console.log('key from your macOS Keychain at startup. The secret value never leaves');
+        console.log("the Keychain and is never written to your Claude Desktop config file.");
+        console.log('');
+        console.log('On a headless macOS / CI runner where Keychain access is unavailable,');
+        console.log(`replace the placeholder with the literal key (run \`nsauditor-ai mcp`);
+        console.log(`print-key --confirm\` to retrieve it).`);
+      } else {
+        console.log(`⚠  The literal key value is now in your Claude Desktop config file.`);
+        console.log(`   On a multi-user system, ensure that file is mode 0600 (operator-only).`);
+        console.log(`   On Linux, also note that the spawned MCP server's env block is`);
+        console.log(`   visible to other users via /proc — same caveat as any env-based secret.`);
+      }
+      console.log('');
+      console.log(`The configured key is also stored at: ${persistedLocation || '<see install-key output>'}`);
+      console.log('The MCP server compares the env-resolved key against the stored key at');
+      console.log('startup and refuses to start on mismatch — so anyone trying to spawn the');
+      console.log('server without the right key fails immediately.');
+    }
+
+    if (subCmd === 'install-key') {
+      // Accept either a caller-supplied key (for restoring from backup
+      // or aligning with an enterprise-managed secret) or generate a
+      // fresh one. Both paths persist via the same multi-source storage
+      // chain used for license keys.
+      let key = rawArgs[2];
+      let generated = false;
+      if (!key || key.startsWith('-')) {
+        key = generateMcpAuthKey();
+        generated = true;
+      } else {
+        const validation = validateMcpAuthKeyShape(key);
+        if (!validation.ok) {
+          console.error(`✗ Key rejected: ${validation.reason}`);
+          console.error(`  Expected format: nsa_mcp_<43-char-base64url>`);
+          console.error(`  Generate a fresh key with: nsauditor-ai mcp install-key`);
+          process.exit(1);
+        }
+      }
+
+      const persisted = await persistMcpAuthKey(key);
+      if (!persisted.ok) {
+        console.error(`✗ Failed to persist MCP auth key: ${persisted.error}`);
+        console.error(`  Fall-back: set ${MCP_AUTH_ENV_VAR} env var manually:`);
+        console.error(`    export ${MCP_AUTH_ENV_VAR}="${key}"`);
+        process.exit(1);
+      }
+
+      if (persisted.warning) {
+        console.warn(`⚠  ${persisted.warning}`);
+      }
+      console.log(`✓ MCP auth key ${generated ? 'generated and ' : ''}installed`);
+      console.log(`  Stored at: ${persisted.location}`);
+      printConfigSnippet(key, persisted.location);
+    } else if (subCmd === 'rotate-key') {
+      // Generate a fresh key and persist over the old one. Old key is
+      // immediately invalid — operator must update Claude Desktop
+      // config to match. Reviewer 1 MEDIUM #3 fold: gate behind
+      // --confirm to prevent accidental Claude-disconnect when an
+      // operator typos `r` instead of `i` (rotate-key is keyboard-
+      // adjacent to install-key). For SOC 2 audit windows where
+      // availability matters, the extra keystroke is the right trade.
+      const confirmed = rawArgs.includes('--confirm');
+      if (!confirmed) {
+        console.error(`✗ \`mcp rotate-key\` immediately invalidates the existing key.`);
+        console.error(`  Any running Claude Desktop session will fail until you update`);
+        console.error(`  the config with the new key value. Re-run with --confirm:`);
+        console.error(`    nsauditor-ai mcp rotate-key --confirm`);
+        process.exit(2);
+      }
+      const key = generateMcpAuthKey();
+      const persisted = await persistMcpAuthKey(key);
+      if (!persisted.ok) {
+        console.error(`✗ Failed to persist rotated MCP auth key: ${persisted.error}`);
+        process.exit(1);
+      }
+      if (persisted.warning) {
+        console.warn(`⚠  ${persisted.warning}`);
+      }
+      console.log(`✓ MCP auth key rotated`);
+      console.log(`  Stored at: ${persisted.location}`);
+      console.log('');
+      console.log('  ⚠ The OLD key is now invalid. Update your Claude Desktop config NOW.');
+      printConfigSnippet(key, persisted.location);
+    } else if (subCmd === 'print-key') {
+      // Reveal the stored key — gated behind --confirm to defend
+      // against accidental shell-history capture. Reviewer 2 CRITICAL #1
+      // fold: write the key to STDERR (not stdout) so accidental output
+      // redirection (`> command.log`) doesn't slurp the secret into a
+      // log file. Also refuse when stdout is non-TTY (pipe) unless
+      // --force is added — guards against silent capture by command-
+      // substitution (e.g., `KEY=$(nsauditor-ai mcp print-key --confirm)`
+      // where the key is then echo'd into a script's history).
+      const confirmed = rawArgs.includes('--confirm');
+      const forced = rawArgs.includes('--force');
+      if (!confirmed) {
+        console.error(`✗ \`mcp print-key\` reveals a secret to your terminal.`);
+        console.error(`  Re-run with --confirm if that's what you intended:`);
+        console.error(`    nsauditor-ai mcp print-key --confirm`);
+        console.error(`  Note that the key will be captured in shell history and any`);
+        console.error(`  active screen-share / tmux scrollback. Prefer copying directly`);
+        console.error(`  from the install-key output, or use \`keychain:\` indirection`);
+        console.error(`  in your Claude Desktop config (see \`mcp install-key\` output).`);
+        process.exit(2);
+      }
+      if (!process.stderr.isTTY && !forced) {
+        console.error(`✗ \`mcp print-key --confirm\` refuses non-TTY output (likely a pipe`);
+        console.error(`  or redirection). Add --force to override; this almost certainly`);
+        console.error(`  means the key would land in a script/log file unintentionally.`);
+        process.exit(2);
+      }
+      const { resolveMcpAuthKey } = await import('./utils/mcp_auth.mjs');
+      const key = await resolveMcpAuthKey();
+      if (!key) {
+        console.error(`✗ No MCP auth key configured.`);
+        console.error(`  Generate one with: nsauditor-ai mcp install-key`);
+        process.exit(1);
+      }
+      // Write to STDERR (not stdout) so `> file.log` redirections don't
+      // capture the secret. The TTY-check above ensures stderr IS a
+      // visible terminal (otherwise we'd refuse). Operators copy from
+      // the visible terminal output, not from a redirected stdout.
+      process.stderr.write(`${key}\n`);
+    } else if (subCmd === 'status') {
+      // Report which storage source the resolver currently honors,
+      // WITHOUT printing the key value. Safe to run in screen-share,
+      // logs, etc.
+      const result = await reportMcpAuthSource();
+      if (result.source === 'unconfigured') {
+        console.log(`✗ MCP authentication is not configured.`);
+        console.log(`  Generate a key with: nsauditor-ai mcp install-key`);
+        if (process.env[MCP_AUTH_DISABLE_ENV_VAR] === '1') {
+          console.log('');
+          console.log(`  ⚠ ${MCP_AUTH_DISABLE_ENV_VAR}=1 is set — server will start without auth.`);
+        }
+        process.exit(1);
+      } else {
+        console.log(`✓ MCP auth key configured`);
+        console.log(`  Source: ${result.source}${result.detail ? ` (${result.detail})` : ''}`);
+        if (process.env[MCP_AUTH_DISABLE_ENV_VAR] === '1') {
+          console.log('');
+          console.log(`  ⚠ ${MCP_AUTH_DISABLE_ENV_VAR}=1 is set — server will start without auth.`);
+        }
+      }
+    } else {
+      console.log('Usage:');
+      console.log('  nsauditor-ai mcp install-key            Generate a new key, persist, print Claude config');
+      console.log('  nsauditor-ai mcp install-key <KEY>      Persist a caller-supplied key (e.g., from backup)');
+      console.log('  nsauditor-ai mcp print-key --confirm    Reveal the stored key (use with care)');
+      console.log('  nsauditor-ai mcp rotate-key             Replace the stored key with a fresh one');
+      console.log('  nsauditor-ai mcp status                 Show storage source without revealing the key');
+      console.log('');
+      console.log('Environment variables:');
+      console.log(`  ${MCP_AUTH_ENV_VAR}        Read by mcp_server.mjs at startup; client supplies via Claude config`);
+      console.log(`  ${MCP_AUTH_DISABLE_ENV_VAR}=1   Skip auth check (CI/dev escape hatch — emits stderr warning)`);
+    }
+    process.exit(0);
+  }
+
   if (cmd === 'security') {
     const { keychainSet, keychainDelete, keychainList, keychainGet } = await import('./utils/keychain.mjs');
     const rawArgs = process.argv.slice(2);

package/mcp_server.mjs

@@ -22,6 +22,7 @@ import {
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities } from './utils/capabilities.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
+import { authorizeMcpServerStartup } from './utils/mcp_auth.mjs';
 
 const _require = createRequire(import.meta.url);
 const { version: TOOL_VERSION } = _require('./package.json');
@@ -399,6 +400,42 @@ const isMainModule =
     process.argv[1].endsWith('mcp_server'));
 
 if (isMainModule) {
+  // EE-SEC.1: enforce MCP server authentication BEFORE accepting any
+  // tool calls. Pre-fold any process running as the operator could
+  // spawn the server and call Pro/Enterprise tools — including the
+  // AWS-talking shadow-admin path detectors that ship in EE 0.3.4.
+  // Now: refuse to start unless the env-provided NSA_MCP_AUTH_KEY
+  // matches the operator's configured key (set via
+  // `nsauditor-ai mcp install-key`). Constant-time compare; honors
+  // NSA_MCP_AUTH_DISABLE=1 escape hatch with stderr warning.
+  //
+  // Stdio-MCP: stdout is reserved for JSON-RPC frames, so all
+  // operator-facing diagnostic text MUST go to stderr.
+  const authResult = await authorizeMcpServerStartup();
+  if (!authResult.ok) {
+    process.stderr.write(`✗ ${authResult.error}\n`);
+    process.exit(1);
+  }
+  if (authResult.bypassed) {
+    if (authResult.bypassedReason === 'unconfigured') {
+      // CRITICAL #2 fold (Reviewer 1): louder signal when DISABLE=1
+      // is set but no key was ever installed — this is almost always
+      // an operator who set DISABLE in their shell rc and forgot.
+      process.stderr.write(
+        `⚠  MCP authentication disabled via NSA_MCP_AUTH_DISABLE=1, ` +
+        `AND no key has ever been installed. This is almost certainly ` +
+        `unintentional. Either run \`nsauditor-ai mcp install-key\` to set up ` +
+        `auth properly, or remove the DISABLE env var if you didn't mean to set it. ` +
+        `Anyone with code-execution as $USER can call MCP tools right now.\n`,
+      );
+    } else {
+      process.stderr.write(
+        `⚠  MCP authentication disabled via NSA_MCP_AUTH_DISABLE=1. ` +
+        `Anyone with code-execution as $USER can call MCP tools.\n`,
+      );
+    }
+  }
+
   // Verify license JWT before accepting MCP requests — upgrades _tier from
   // prefix-based to cryptographically verified.
   await loadLicense();

package/package.json

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

package/utils/mcp_auth.mjs

@@ -0,0 +1,532 @@
+// utils/mcp_auth.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// EE-SEC.1 — MCP server authentication.
+//
+// The MCP server (`mcp_server.mjs`) uses stdio transport, which means the
+// server runs as a subprocess of whatever client launched it (Claude
+// Desktop, Claude Code, custom IDE integration). Pre-EE-SEC.1, ANY
+// process running as the operator could `child_process.spawn('node',
+// ['mcp_server.mjs'])` and call the Pro/Enterprise tools — including
+// the AWS-talking shadow-admin path detectors that ship in EE 0.3.4.
+//
+// Threat model the gap enables:
+//   - Code-execution-as-operator escalation: a malicious npm post-install,
+//     a compromised browser extension, a hostile dev tool can spawn the
+//     server and use its tools to scan the operator's AWS account,
+//     mutate finding queues, or exfiltrate license-gated SOC 2 evidence.
+//   - Multi-user shared machines: any user on a shared dev box / CI
+//     runner can launch the MCP server as themselves.
+//   - Future HTTP transport risk: if SSE/HTTP is ever added, the same
+//     gap becomes network-exposed.
+//
+// Mitigation: shared-secret authentication. The operator runs
+// `nsauditor-ai mcp install-key` once, which generates a 256-bit
+// random key, persists it via the same multi-source storage chain
+// already used for license keys (env → macOS Keychain → ~/.nsauditor/.env),
+// and prints a Claude Desktop config snippet that places the key in
+// the spawned-process env. The MCP server resolves the EXPECTED key
+// at startup from storage, reads the PRESENTED key from
+// process.env.NSA_MCP_AUTH_KEY, and refuses to start unless they
+// match (constant-time compare).
+//
+// What this defends, what it doesn't:
+//   ✅ Defends against malicious code running as the operator that tries
+//      to spawn the MCP server — the attacker doesn't have the key
+//      because reading it requires Keychain GUI prompt approval (macOS)
+//      or read-access to ~/.nsauditor/.env (which is mode 0600).
+//   ✅ Defends against shared-machine other-user attacks — the key is
+//      per-operator in their Keychain, not in a world-readable file.
+//   ⚠ Does NOT defend against an attacker with full operator-level code
+//      execution AND the ability to suppress macOS Keychain prompts.
+//      Recent macOS versions log Keychain-access denial events; SIEM
+//      pipelines should alarm on those.
+//   ⚠ Does NOT defend against debugger-attach memory snooping — the
+//      resolved key lives in MCP server process memory. Out of scope
+//      for v1; same fundamental limitation as any shared-secret auth.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { promises as fsp } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import dotenv from 'dotenv';
+
+import { keychainGet, keychainSet, resolveSecret } from './keychain.mjs';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+// Storage key name. Kept distinct from NSAUDITOR_LICENSE_KEY so the two
+// secrets are independently rotatable and the env-var pollution in
+// `ps -ef` listings (Linux) is named explicitly enough that operators
+// understand what it is.
+export const MCP_AUTH_ENV_VAR = 'NSA_MCP_AUTH_KEY';
+
+// Escape hatch env var. When set to "1", the MCP server skips the auth
+// check entirely (with a stderr warning). For CI/dev environments where
+// the operator accepts the risk.
+export const MCP_AUTH_DISABLE_ENV_VAR = 'NSA_MCP_AUTH_DISABLE';
+
+// Keychain account name (under service=nsauditor-ai). Same value as the
+// env var name — keeps the storage and resolution paths symmetrically
+// named so operators don't have to remember two strings.
+const MCP_AUTH_KEYCHAIN_ACCOUNT = MCP_AUTH_ENV_VAR;
+
+// Key prefix. Lets operators distinguish from license keys (`pro_eyJ...`,
+// `enterprise_eyJ...`) at a glance. 32 bytes of entropy → 43 chars
+// base64url after the prefix.
+export const MCP_AUTH_KEY_PREFIX = 'nsa_mcp_';
+
+// Entropy width. 32 bytes = 256 bits, matches AES-256 / SHA-256 strength.
+const MCP_AUTH_KEY_ENTROPY_BYTES = 32;
+
+// One-shot permissive-mode warning per file path per process. Same
+// pattern as license.mjs so a license + MCP-auth resolution in the
+// same run doesn't double-warn on the shared file.
+const _permissiveWarnedPaths = new Set();
+
+// ── Key generation ───────────────────────────────────────────────────────────
+
+/**
+ * Generate a fresh MCP auth key.
+ *
+ * Format: `nsa_mcp_<43-char-base64url>`. 256 bits of entropy from
+ * crypto.randomBytes() — same entropy class as Anthropic's session
+ * tokens. URL-safe (no padding) so it's safe to paste into JSON
+ * config files and shell quoted strings without escaping.
+ *
+ * @returns {string} The new key.
+ */
+export function generateMcpAuthKey() {
+  const raw = randomBytes(MCP_AUTH_KEY_ENTROPY_BYTES).toString('base64url');
+  return `${MCP_AUTH_KEY_PREFIX}${raw}`;
+}
+
+/**
+ * Validate that a key has the expected shape. Used by the install
+ * command to reject typos before persisting them. Does NOT validate
+ * cryptographic provenance — there is none; the key is a shared
+ * secret, not a JWT.
+ *
+ * @param {string} key
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function validateMcpAuthKeyShape(key) {
+  if (typeof key !== 'string') {
+    return { ok: false, reason: 'key must be a string' };
+  }
+  if (!key.startsWith(MCP_AUTH_KEY_PREFIX)) {
+    return { ok: false, reason: `key must start with "${MCP_AUTH_KEY_PREFIX}"` };
+  }
+  const body = key.slice(MCP_AUTH_KEY_PREFIX.length);
+  // base64url body should be ~43 chars for 32 bytes (no padding).
+  // Accept 40-50 to allow for future entropy bumps; reject obvious typos.
+  if (body.length < 40 || body.length > 50) {
+    return { ok: false, reason: `key body length ${body.length} not in 40..50 (expected ~43 for 256-bit entropy)` };
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(body)) {
+    // Reviewer 1 MEDIUM #4 fold: the most common cause of this error
+    // in practice is paste-mistakes (trailing newline from a wrapped
+    // Slack message, surrounding quotes, leading whitespace). Call
+    // those out specifically so the operator doesn't go hunting for
+    // a base64url problem.
+    const hint = /\s/.test(body) || /[\r\n]/.test(body)
+      ? ' (likely a copy-paste issue: trailing newline or surrounding whitespace)'
+      : /["']/.test(body)
+        ? ' (likely a copy-paste issue: surrounding quotes)'
+        : '';
+    return { ok: false, reason: `key body must be base64url (A-Z, a-z, 0-9, _, -)${hint}` };
+  }
+  return { ok: true };
+}
+
+// ── Resolver chain ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve the MCP auth key from storage. Mirrors the license-key
+ * resolver (license.mjs:resolveLicenseKey) — same env → Keychain →
+ * file precedence so operators can use the same mental model and
+ * the same dotfile/keychain entries for both secrets.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. process.env.NSA_MCP_AUTH_KEY     — CI/CD takes precedence
+ *   2. macOS Keychain (service=nsauditor-ai, account=NSA_MCP_AUTH_KEY)
+ *      — set by `nsauditor-ai mcp install-key` on macOS
+ *   3. $XDG_CONFIG_HOME/nsauditor/.env (or ~/.nsauditor/.env)
+ *      — universal file fallback
+ *
+ * @param {object} [opts]
+ * @param {string} [opts._homeFileOverride] — test seam.
+ * @param {Function} [opts._keychainGet] — test seam.
+ * @returns {Promise<string|null>} The key, or null if no source had one.
+ */
+export async function resolveMcpAuthKey(opts = {}) {
+  // 1. env var
+  if (process.env[MCP_AUTH_ENV_VAR]) return process.env[MCP_AUTH_ENV_VAR];
+
+  // 2. macOS Keychain
+  const kget = opts._keychainGet ?? keychainGet;
+  try {
+    const fromKeychain = await kget(MCP_AUTH_KEYCHAIN_ACCOUNT);
+    if (fromKeychain) return fromKeychain;
+  } catch { /* keychain unavailable — fall through */ }
+
+  // 3. ~/.nsauditor/.env
+  const filePath = opts._homeFileOverride ?? defaultMcpAuthFilePath();
+  try {
+    const stat = await fsp.stat(filePath);
+    if (platform() !== 'win32' && stat.isFile() && (stat.mode & 0o077) !== 0) {
+      if (!_permissiveWarnedPaths.has(filePath)) {
+        const modeStr = (stat.mode & 0o777).toString(8).padStart(3, '0');
+        // Use stderr — stdio-MCP requires stdout to be JSON-RPC only.
+        process.stderr.write(`⚠  ${filePath} has permissive mode ${modeStr} — recommend chmod 0600\n`);
+        _permissiveWarnedPaths.add(filePath);
+      }
+    }
+    const buf = await fsp.readFile(filePath, 'utf8');
+    const parsed = dotenv.parse(buf);
+    if (parsed[MCP_AUTH_ENV_VAR]) return parsed[MCP_AUTH_ENV_VAR];
+  } catch { /* file missing / unreadable — fall through */ }
+
+  return null;
+}
+
+/**
+ * Report which source the resolver currently honors WITHOUT printing
+ * the key value. Used by `nsauditor-ai mcp status` so operators can
+ * verify their setup without exposing the secret to shell history /
+ * tmux scrollback / screen-share.
+ *
+ * @param {object} [opts] — same test seams as resolveMcpAuthKey.
+ * @returns {Promise<{ source: 'env'|'keychain'|'file'|'unconfigured', detail?: string }>}
+ */
+export async function reportMcpAuthSource(opts = {}) {
+  if (process.env[MCP_AUTH_ENV_VAR]) {
+    return { source: 'env', detail: MCP_AUTH_ENV_VAR };
+  }
+  const kget = opts._keychainGet ?? keychainGet;
+  try {
+    const fromKeychain = await kget(MCP_AUTH_KEYCHAIN_ACCOUNT);
+    if (fromKeychain) {
+      return { source: 'keychain', detail: 'macOS Keychain (service=nsauditor-ai)' };
+    }
+  } catch { /* fall through */ }
+  const filePath = opts._homeFileOverride ?? defaultMcpAuthFilePath();
+  try {
+    const buf = await fsp.readFile(filePath, 'utf8');
+    const parsed = dotenv.parse(buf);
+    if (parsed[MCP_AUTH_ENV_VAR]) {
+      return { source: 'file', detail: filePath };
+    }
+  } catch { /* fall through */ }
+  return { source: 'unconfigured' };
+}
+
+function defaultMcpAuthFilePath() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return join(process.env.XDG_CONFIG_HOME, 'nsauditor', '.env');
+  }
+  return join(homedir(), '.nsauditor', '.env');
+}
+
+// ── Persistence ──────────────────────────────────────────────────────────────
+
+/**
+ * Persist an MCP auth key to platform-appropriate storage. Mirrors
+ * persistLicenseKey in license.mjs — same Keychain-first-on-darwin
+ * routing with file fallback, same mode-0600 file write, same merge
+ * semantics that preserve other env vars in the dotenv file.
+ *
+ * @param {string} key — full prefixed key (`nsa_mcp_...`).
+ * @param {object} [opts]
+ * @param {string} [opts._platform]         — test seam.
+ * @param {Function} [opts._keychainSet]    — test seam.
+ * @param {string} [opts._homeFileOverride] — test seam.
+ * @returns {Promise<{ok: true, location: string, warning?: string} | {ok: false, error: string}>}
+ */
+export async function persistMcpAuthKey(key, opts = {}) {
+  const validation = validateMcpAuthKeyShape(key);
+  if (!validation.ok) {
+    return { ok: false, error: `persistMcpAuthKey: ${validation.reason}` };
+  }
+
+  const plat = opts._platform ?? platform();
+  const kset = opts._keychainSet ?? keychainSet;
+
+  // 1. macOS: try Keychain first.
+  let keychainFallbackReason = null;
+  if (plat === 'darwin') {
+    try {
+      await kset(MCP_AUTH_KEYCHAIN_ACCOUNT, key);
+      return { ok: true, location: 'macOS Keychain (service=nsauditor-ai)' };
+    } catch (err) {
+      keychainFallbackReason = err && err.message ? err.message : String(err);
+    }
+  }
+
+  // 2. File-based storage (Linux, Windows, macOS Keychain fallback).
+  try {
+    const filePath = opts._homeFileOverride ?? defaultMcpAuthFilePath();
+    const dir = dirname(filePath);
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    // Reviewer 2 MEDIUM #1 fold: `mkdir mode` only applies on FIRST
+    // creation (Node mirrors POSIX semantics). If the dir already
+    // existed (e.g., license-key flow created it as 0755), the 0700
+    // mode is silently ignored. Explicit chmod after mkdir guarantees
+    // the secret-bearing parent dir is operator-only on POSIX.
+    if (plat !== 'win32') {
+      try {
+        await fsp.chmod(dir, 0o700);
+      } catch { /* best effort; some FSes (NFS) reject chmod */ }
+    }
+
+    let existingContent = '';
+    try {
+      existingContent = await fsp.readFile(filePath, 'utf8');
+    } catch { /* missing file — create one */ }
+
+    const newContent = mergeMcpAuthIntoEnvFile(existingContent, key);
+    await fsp.writeFile(filePath, newContent, { mode: 0o600 });
+    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 an MCP auth key into a dotenv-format file content, preserving
+ * every OTHER line. Mirrors mergeLicenseIntoEnvFile (license.mjs:242)
+ * — same multi-occurrence safety and CRLF preservation.
+ *
+ * - If a NSA_MCP_AUTH_KEY line already exists, replace the first
+ *   occurrence and remove duplicates (corrupted-file defense).
+ * - If the file is empty, write a header comment.
+ * - Otherwise append.
+ *
+ * Exported for test coverage.
+ * @internal
+ */
+export function mergeMcpAuthIntoEnvFile(existingContent, key) {
+  // Reviewer 1 MEDIUM #5 fold: escape regex metacharacters in
+  // MCP_AUTH_ENV_VAR before interpolating. Today the constant is
+  // `NSA_MCP_AUTH_KEY` (no specials), so this is defense-in-depth
+  // — but a future rename to e.g. `NSA-MCP.AUTH+KEY` would silently
+  // break the merge without this guard. License version uses a
+  // literal regex, so it doesn't have this risk; this version
+  // interpolates because the env-var name is exported as a constant.
+  const escaped = MCP_AUTH_ENV_VAR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const KEY_LINE_RE = new RegExp(
+    `^[ \\t]*${escaped}[ \\t]*=[^\\r\\n]*$`,
+    'gm',
+  );
+  const newLine = `${MCP_AUTH_ENV_VAR}=${key}`;
+
+  const matches = existingContent.match(KEY_LINE_RE);
+  if (matches && matches.length > 0) {
+    let firstReplaced = false;
+    let merged = existingContent.replace(KEY_LINE_RE, () => {
+      if (firstReplaced) return '__NSAUDITOR_PURGE__';
+      firstReplaced = true;
+      return newLine;
+    });
+    merged = merged.replace(/__NSAUDITOR_PURGE__\r?\n?/g, '');
+    return merged;
+  }
+
+  if (existingContent.trim().length === 0) {
+    return `# NSAuditor AI MCP auth key — set via \`nsauditor-ai mcp install-key\`\n${newLine}\n`;
+  }
+
+  const sep = existingContent.endsWith('\n') ? '' : '\n';
+  return `${existingContent}${sep}${newLine}\n`;
+}
+
+// ── Constant-time comparison ─────────────────────────────────────────────────
+
+/**
+ * Compare two MCP auth keys in constant time. Prevents timing-channel
+ * attacks where an attacker measures comparison duration to learn
+ * shared-secret bytes. For stdio transport the timing channel is
+ * already noisy (IPC pipe scheduling) but this is free correctness
+ * and matters for the future HTTP transport branch.
+ *
+ * Returns false (not an exception) if either argument is not a string
+ * or lengths differ — same shape as a normal mismatch from the
+ * caller's perspective.
+ *
+ * @param {string} expected
+ * @param {string} presented
+ * @returns {boolean}
+ */
+export function constantTimeMcpKeyEquals(expected, presented) {
+  if (typeof expected !== 'string' || typeof presented !== 'string') return false;
+  if (expected.length !== presented.length) return false;
+  // Buffer.byteLength is needed because timingSafeEqual requires
+  // equal-byte-length buffers; for ASCII keys (which ours always are
+  // — base64url charset is ASCII) byteLength === length. Belt-and-
+  // suspenders: encode explicitly.
+  const a = Buffer.from(expected, 'utf8');
+  const b = Buffer.from(presented, 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+// ── Server-side enforcement ──────────────────────────────────────────────────
+
+/**
+ * Determine whether the MCP server should accept incoming requests.
+ * Called once at startup from mcp_server.mjs — if the result is
+ * `{ ok: false }`, the caller MUST exit before connecting transport.
+ *
+ * Routing:
+ *   - NSA_MCP_AUTH_DISABLE=1 → ok: true with `bypassed: true`. The
+ *     `bypassedReason` field distinguishes operator-acknowledged
+ *     bypass-with-key (`'configured'`) from bypass-without-any-key
+ *     (`'unconfigured'`) so the server stderr can flag the latter
+ *     loudly — that's the case where an operator forgot they had
+ *     DISABLE=1 in their shell rc and never ran install-key
+ *     (Reviewer 1 CRITICAL #2 fold).
+ *   - Storage has no key → ok: false with actionable error pointing
+ *     at `nsauditor-ai mcp install-key`. Refuse to start.
+ *   - Storage has key, NSA_MCP_AUTH_KEY env unset → ok: false with
+ *     "did you forget to update Claude Desktop config" hint.
+ *   - Storage has key, NSA_MCP_AUTH_KEY env set, mismatch → ok: false
+ *     with "did you forget to update after `mcp rotate-key`" hint.
+ *   - Match → ok: true.
+ *
+ * EE-SEC.1.1 fold (Reviewer 2 CRITICAL #2): the presented env value
+ * is passed through `resolveSecret()` so the operator can use the
+ * `keychain:LABEL` indirection in their Claude Desktop config —
+ * keeping the secret in the Keychain instead of baking it into the
+ * world-readable config file. macOS-only feature; on Linux/Windows
+ * the env var holds the literal key as before.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts._homeFileOverride] — test seam.
+ * @param {Function} [opts._keychainGet] — test seam.
+ * @param {Function} [opts._resolveSecret] — test seam for keychain: prefix resolution.
+ * @param {Record<string, string|undefined>} [opts._env] — test seam (default process.env).
+ * @returns {Promise<{ ok: true, bypassed?: boolean, bypassedReason?: 'configured'|'unconfigured' } | { ok: false, error: string }>}
+ */
+export async function authorizeMcpServerStartup(opts = {}) {
+  const env = opts._env ?? process.env;
+
+  // Resolve EXPECTED key from storage FIRST so the bypass branch can
+  // tell whether a key was ever installed. We deliberately do NOT use
+  // resolveMcpAuthKey here: that includes the env-var branch, but we
+  // want env-var to participate ONLY for the PRESENTED key, never for
+  // the "configured" baseline (using env for both would let an
+  // attacker self-validate by setting NSA_MCP_AUTH_KEY in the spawned
+  // server's env).
+  let expected = null;
+  const kget = opts._keychainGet ?? keychainGet;
+  try {
+    const fromKeychain = await kget(MCP_AUTH_KEYCHAIN_ACCOUNT);
+    if (fromKeychain) expected = fromKeychain;
+  } catch { /* keychain unavailable */ }
+
+  if (!expected) {
+    const filePath = opts._homeFileOverride ?? defaultMcpAuthFilePath();
+    try {
+      const buf = await fsp.readFile(filePath, 'utf8');
+      const parsed = dotenv.parse(buf);
+      // MEDIUM #1 fold (Reviewer 1): treat empty-string parsed value
+      // ("NSA_MCP_AUTH_KEY=") as "no key configured" — consistent with
+      // the env-var branch in resolveMcpAuthKey which uses falsy check.
+      if (parsed[MCP_AUTH_ENV_VAR]) expected = parsed[MCP_AUTH_ENV_VAR];
+    } catch { /* file missing — leaves expected null */ }
+  }
+
+  // CRITICAL #2 fold (Reviewer 1): bypass routing now distinguishes
+  // bootstrap-state (no key has ever been installed) from operational
+  // bypass (operator has a key but explicitly disabled). The server
+  // emits a different stderr warning for each case so an operator
+  // who forgot DISABLE=1 in their shell rc sees a louder signal.
+  if (env[MCP_AUTH_DISABLE_ENV_VAR] === '1') {
+    return {
+      ok: true,
+      bypassed: true,
+      bypassedReason: expected ? 'configured' : 'unconfigured',
+    };
+  }
+
+  if (!expected) {
+    return {
+      ok: false,
+      error:
+        `MCP authentication is not configured. Run \`nsauditor-ai mcp install-key\` ` +
+        `to generate a key, then add it to your Claude Desktop config under ` +
+        `env: { "${MCP_AUTH_ENV_VAR}": "..." }. ` +
+        `If you intentionally want to run without auth (e.g., in CI), set ` +
+        `${MCP_AUTH_DISABLE_ENV_VAR}=1 — note that anyone with code execution ` +
+        `as your user can then call MCP tools.`,
+    };
+  }
+
+  const presentedRaw = env[MCP_AUTH_ENV_VAR];
+  if (!presentedRaw) {
+    return {
+      ok: false,
+      error:
+        `MCP authentication failed: ${MCP_AUTH_ENV_VAR} env var is not set, but a key ` +
+        `is configured in storage. Did you forget to update your Claude Desktop config? ` +
+        `Run \`nsauditor-ai mcp print-key --confirm\` to retrieve the configured key, ` +
+        `or use the keychain: indirection (see \`nsauditor-ai mcp install-key\` output).`,
+    };
+  }
+
+  // EE-SEC.1.1: resolve `keychain:LABEL` prefix in the presented env
+  // value so operators can keep the secret in Keychain (macOS) and
+  // reference it from the world-readable Claude Desktop config file.
+  // For literal-string env values, resolveSecret returns the string
+  // unchanged. _resolveSecret test seam allows hermetic injection.
+  const _resolve = opts._resolveSecret ?? resolveSecret;
+  let presented;
+  try {
+    presented = await _resolve(presentedRaw);
+  } catch {
+    presented = null;
+  }
+  if (!presented) {
+    // The keychain: prefix was used but the Keychain entry is missing
+    // / locked / inaccessible. Distinguish from plain mismatch so the
+    // operator can debug.
+    if (typeof presentedRaw === 'string' && presentedRaw.startsWith('keychain:')) {
+      return {
+        ok: false,
+        error:
+          `MCP authentication failed: ${MCP_AUTH_ENV_VAR} uses keychain: indirection ` +
+          `but the referenced Keychain entry could not be read. ` +
+          `Run \`nsauditor-ai mcp status\` to verify the entry exists. ` +
+          `On a headless macOS / CI runner, replace the indirection with the literal ` +
+          `key value or move auth to ~/.nsauditor/.env.`,
+      };
+    }
+    return {
+      ok: false,
+      error: `MCP authentication failed: ${MCP_AUTH_ENV_VAR} env var resolved to empty.`,
+    };
+  }
+
+  if (!constantTimeMcpKeyEquals(expected, presented)) {
+    return {
+      ok: false,
+      error:
+        `MCP authentication failed: the ${MCP_AUTH_ENV_VAR} env var does not match the ` +
+        `key configured in storage. Did you forget to update Claude Desktop config after ` +
+        `\`nsauditor-ai mcp rotate-key\`? ` +
+        `Run \`nsauditor-ai mcp status\` to see which storage source is active.`,
+    };
+  }
+
+  return { ok: true };
+}