nsauditor-ai 0.1.31 → 0.1.33

package/README.md

@@ -15,6 +15,64 @@ 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.33) — ⚠ MCP integration with Claude Desktop is unreliable
+
+**Critical advisory for customers using NSAuditor AI through Claude Desktop's MCP integration.** During the maintainer's own integration test on 2026-05-10, we discovered that **Claude Desktop's AI fabricates scan results, plugin lists, vulnerability findings, and tier information without actually invoking the MCP tools** for our specific server. Other MCP servers in the same Claude Desktop config receive real `tools/call` invocations; ours does not.
+
+**Empirical evidence**:
+- `~/Library/Logs/Claude/main.log` shows multiple permission grants for `mcp__nsauditor-ai__list_plugins` and `mcp__nsauditor-ai__scan_host` on 2026-05-10
+- `~/Library/Logs/Claude/mcp-server-nsauditor-ai.log` shows **zero** `"method":"tools/call"` entries on the same day
+- Other servers in the same config logged real calls (ns-ftp:29, wp-publisher-netsecmag:14, ai-pr-distribution:6, sendgrid:3)
+- When asked to scan 1.1.1.1, Claude Desktop returned a detailed report with plugin breakdown + Zero Trust score — entirely fabricated
+
+**Likely cause**: Claude Desktop's MCP client appears to time out our server (which loads PluginManager + 32 plugins + license verify before responding). Claude (the AI) silently substitutes fabricated responses from training rather than surfacing the timeout. The hallucinations are convincingly formatted and indistinguishable from real output without log inspection.
+
+**Mandatory verification — for any output you'd act on**:
+
+```bash
+# Tier check (ground truth bypassing Claude AI synthesis):
+nsauditor-ai mcp tier
+
+# Real plugin scan (always hits the network):
+nsauditor-ai scan --host <X> --plugins all --out <dir>
+
+# Confirm Claude Desktop actually called the MCP server:
+grep '"method":"tools/call"' ~/Library/Logs/Claude/mcp-server-nsauditor-ai.log | tail -5
+# If main.log shows recent permission grants for nsauditor-ai tools but
+# THIS file shows no matching tools/call entries, the responses you saw
+# in Claude Desktop were AI-generated, NOT real.
+```
+
+**SOC 2 evidence and any compliance report MUST be generated via the CLI** — never via the Claude Desktop MCP integration — until this is resolved upstream. We're working on it (Thread L in `tasks/todo.md`): a per-call cryptographic sentinel, lazy-loaded plugin discovery to reduce startup latency, a `mcp verify-recent-call` diagnostic, and a bug report to Anthropic.
+
+This advisory will be removed when the upstream Claude Desktop MCP routing issue is fixed and we ship a CE release whose `tools/call` invocations land reliably.
+
+---
+
+## What's New (0.1.32) — Claude Desktop integration overhaul + ground-truth diagnostics
+
+The 0.1.32 line bundles three operational improvements driven by real customer-onboarding friction surfaced during the developer's own Claude Desktop integration test (2026-05-10):
+
+- **`nsauditor-ai mcp install-key` now auto-generates a machine-specific Claude Desktop config snippet.** Reads `process.execPath` (the Node binary actually running) and derives the script path from `import.meta.url` — the printed JSON has absolute paths that work whether you're on system Node, homebrew, nvm, fnm, local-project install, Linux, or Windows. No install-type detective work, no PATH-misalignment failures. On macOS, the snippet uses `keychain:` indirection for **both** auth and license — secrets never land in the world-readable Claude Desktop config file.
+- **License `keychain:` indirection.** `loadLicense()` and `resolveLicenseKey()` honor the `keychain:LABEL` prefix on the env-supplied value (mirrors the EE-SEC.1 MCP-auth pattern). Operators can put `"NSAUDITOR_LICENSE_KEY": "keychain:NSAUDITOR_LICENSE_KEY"` in their Claude Desktop env block; the JWT stays in macOS Keychain. Backward-compat: literal JWTs continue to work unchanged.
+- **`nsauditor-ai mcp tier` ground-truth subcommand.** Customer-side check that prints the EXACT tier the spawned MCP server resolves to. We discovered Claude Desktop reports of "Current tier: CE" despite verified Pro/Enterprise license were caused by Claude (the AI) **synthesizing the tier text from training data + context** instead of actually calling `list_plugins` via MCP. The MCP server's resolution was always correct. `mcp tier` bypasses Claude's interpretive layer — paste the output into a support ticket to distinguish "MCP genuinely broken" from "Claude misreading."
+- **MCP key rotation cadence (Thread I).** Optional 90-day rotation soft warning at server startup + `mcp status` (override via `NSA_MCP_AUTH_KEY_ROTATION_DAYS`, clamped to [7, 365]). SOC 2 CC6.1/CC6.7 reviewers expect a credential-rotation cadence; an unrotated MCP auth key is treated the same way as an unrotated IAM access key.
+- **Keychain-locked vs Keychain-empty distinction.** New `keychain-locked` source variant in `mcp status` for headless macOS / SSH-only CI runners — instead of falling through silently to "unconfigured", operators get an actionable error with three GUI-free workarounds.
+- **Atomic file writes** for `~/.nsauditor/.env` (`.tmp` + POSIX-rename) so concurrent readers + crash recovery never observe a truncated file.
+- **Auto-mirror license file→Keychain on `mcp install-key`** (macOS) when the license is configured in `~/.nsauditor/.env` but absent from Keychain. Lets the printed snippet's `keychain:` indirection actually resolve, with original storage location preserved unchanged.
+
+**Breaking change for existing 0.1.31 operators**: nothing breaks, but the recommended Claude Desktop config snippet has changed. Re-run `nsauditor-ai mcp install-key` after upgrading to get the new auto-generated snippet with absolute paths + license indirection. Old configs continue to work.
+
+```bash
+npm install -g nsauditor-ai@0.1.32
+nsauditor-ai mcp install-key   # prints the new snippet — paste into Claude Desktop config
+nsauditor-ai mcp tier          # confirm the actual MCP server tier (ground truth)
+```
+
+See [Authentication](#authentication-required-new-in-0131) and [Troubleshooting MCP authentication](#troubleshooting-mcp-authentication) for full setup + diagnostics.
+
+---
+
 ## 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.
@@ -295,6 +353,25 @@ nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
 
 ## MCP Server
 
+> ## ⚠ CRITICAL ADVISORY (2026-05-10) — Claude Desktop hallucinates responses for this MCP server
+>
+> When you use NSAuditor AI through **Claude Desktop's** MCP integration, the AI may **fabricate scan results, plugin lists, vulnerability findings, and tier information without actually invoking the MCP tools**. We've confirmed this empirically: Claude Desktop's permission system shows tool calls being approved, but the actual `tools/call` JSON-RPC messages never reach our server (other MCP servers in the same config receive their calls correctly).
+>
+> **Mandatory verification for any output you'd act on**:
+>
+> ```bash
+> # Real tier check (ground truth — bypasses Claude AI synthesis):
+> nsauditor-ai mcp tier
+>
+> # Real scan (always hits the network):
+> nsauditor-ai scan --host <X> --plugins all --out <dir>
+>
+> # Confirm Claude Desktop actually called the MCP server today:
+> grep '"method":"tools/call"' ~/Library/Logs/Claude/mcp-server-nsauditor-ai.log | tail -5
+> ```
+>
+> **SOC 2 evidence + compliance reports MUST be generated via the CLI** — never via the Claude Desktop MCP integration — until this is resolved upstream. Other MCP clients (Claude Code, custom MCP clients via the SDK) appear unaffected. See [What's New (0.1.33)](#whats-new-0133----mcp-integration-with-claude-desktop-is-unreliable) for full details.
+
 Expose scanning capabilities to AI assistants via [Model Context Protocol](https://modelcontextprotocol.io):
 
 ```bash
@@ -362,7 +439,17 @@ nsauditor-ai mcp rotate-key --confirm    # generates a new key (invalidates old
 | 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 |
+| Linux env-var visibility in `/proc/<pid>/environ` | ⚠ partial — see Linux note below |
+
+**Linux note (`/proc/<pid>/environ`)**: on modern Linux, `/proc/<pid>/environ` is readable only by the process owner (the same user that spawned the MCP server). Other users on a multi-user system **cannot** read your MCP auth key from `/proc` under default kernel settings. The realistic remaining risks are:
+
+- Container scenarios where multiple "users" share the same kernel UID (e.g., a Docker container running as root, with multiple processes inside) — the secret is visible to any process in the same UID namespace. Mitigation: run the MCP server in its own container / user.
+- Audit/SIEM agents with broad read access (e.g., `auditd` configured to log child-process env). Mitigation: review your `auditd` rules; modern setups exclude env from logs by default.
+- The legacy `ps eww` command on older POSIX systems (modern `ps` respects `/proc` permissions).
+
+A shell-wrapper indirection script (read key from `~/.nsauditor/.env` at exec time, pass to child) was considered for v1 but does NOT solve the underlying issue: the spawned MCP server still needs the key in its env to perform the auth check, so it appears in `/proc/<server-pid>/environ` regardless of how the parent process obtained it. v2 may add libsecret integration on Linux to mirror the macOS Keychain indirection model.
+
+**Rotation cadence (NEW in 0.1.32)**: keys older than 90 days emit a soft warning at every server startup AND in `nsauditor-ai mcp status` output. SOC 2 CC6.1 / CC6.7 reviewers expect a credential-rotation cadence; rotate with `nsauditor-ai mcp rotate-key --confirm` and update Claude Desktop config with the new key.
 
 **Escape hatch for CI / dev** (operator-acknowledged risk; emits a stderr warning every startup):
 
@@ -426,6 +513,29 @@ claude mcp add nsauditor-ai \
 
 **"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).
 
+**`mcp status` reports `keychain-locked`** (NEW in 0.1.32) → distinct from `unconfigured`: the Keychain entry exists but the security daemon refused to unlock without a GUI prompt. Same workarounds as the previous error: approve a Keychain GUI prompt, replace `keychain:` indirection with the literal key, or move auth to `~/.nsauditor/.env`. Pre-0.1.32 the resolver silently fell through to the file branch and reported `unconfigured` — the new state distinguishes "operator never ran install-key" from "operator did run it but Keychain is locked right now".
+
+**`mcp status` shows `⚠ Created: ... — > 90d threshold`** (NEW in 0.1.32) → key is older than the 90-day rotation cadence. Run `nsauditor-ai mcp rotate-key --confirm` and update Claude Desktop config with the new key. Server emits the same warning to stderr at every startup.
+
+**Claude Desktop reports "Current tier: CE" despite `nsauditor-ai license --status` showing Enterprise** (NEW in 0.1.32) → first run `nsauditor-ai mcp tier` to get the **ground-truth tier** the MCP server actually resolves at startup. If `mcp tier` reports `enterprise` but Claude Desktop's `list_plugins` says CE, **Claude (the AI) is synthesizing the tier text from context rather than calling the tool**. Force a real call by asking in a NEW Claude Desktop conversation:
+
+> Use the `list_plugins` MCP tool right now and show me the raw tool response verbatim, including the exact text after the JSON.
+
+Then check the MCP log to verify a real call happened:
+
+```bash
+grep '"method":"tools/call"' ~/Library/Logs/Claude/mcp-server-nsauditor-ai.log | tail -5
+```
+
+If `mcp tier` itself reports CE → genuine resolution failure. Inspect the license storage:
+
+```bash
+nsauditor-ai license --status
+security find-generic-password -s nsauditor-ai -a NSAUDITOR_LICENSE_KEY -w 2>&1 | head -c 30
+```
+
+If license is in `~/.nsauditor/.env` but not in Keychain on macOS, re-run `nsauditor-ai mcp install-key` — the auto-mirror writes the license to Keychain so Claude Desktop's child process can read it via the `keychain:` indirection.
+
 ---
 
 ## Secure Credential Storage

package/cli.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 import path from 'node:path';
+import { platform } from 'node:os';
 import { openaiSimplePrompt, openaiPrompt as openaiProPrompt, openaiPromptOptimized } from './utils/prompts.mjs';
 import { parseHostArg, parseHostFile } from './utils/host_iterator.mjs';
 import { buildSarifLog } from './utils/sarif.mjs';
@@ -864,6 +865,9 @@ MCP server-auth subcommands (EE-SEC.1):
   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
+  nsauditor-ai mcp tier                 Print actual MCP server tier (ground truth — bypasses
+                                        Claude AI synthesis when "list_plugins" reports
+                                        unexpected CE despite verified Pro/Enterprise license)
 
 Security subcommands (macOS Keychain):
   nsauditor-ai security set <KEY>       Store a secret (read from stdin)
@@ -1086,57 +1090,159 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
     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).
+    async function printConfigSnippet(key, persistedLocation) {
+      // Thread K (CE 0.1.32): generate a MACHINE-SPECIFIC config snippet
+      // so customers don't have to figure out:
+      //   - which Node binary Claude Desktop should call (system /
+      //     homebrew / nvm / fnm — Claude Desktop's launchd PATH does
+      //     NOT include nvm/fnm bin dirs reliably)
+      //   - which absolute path to the .mjs script
+      //   - whether to use `keychain:` indirection (macOS only) or
+      //     literal value (Linux/Windows)
+      //   - whether to also include the license env line (only if
+      //     license is configured AND we can avoid baking the JWT
+      //     into the world-readable config file)
       //
-      // 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.
+      // This eliminates the install-type matrix that was the #1
+      // source of customer-onboarding friction.
+      const isDarwin = platform() === 'darwin';
+
+      // process.execPath is the actual Node binary executing this CLI.
+      // For nvm: /Users/<u>/.nvm/versions/node/vX.Y.Z/bin/node
+      // For homebrew: /opt/homebrew/bin/node
+      // For system: /usr/local/bin/node or /usr/bin/node
+      // Always absolute; always the right binary that loaded our code.
+      const nodeBin = process.execPath;
+
+      // The script path: derive from where THIS cli.mjs file lives,
+      // then walk to the bin/ directory. cli.mjs is at the package
+      // root; bin/nsauditor-ai-mcp.mjs is its sibling.
+      // import.meta.url gives the file:// URL of THIS cli.mjs.
+      const cliUrl = new URL(import.meta.url);
+      const cliPath = fileURLToPath(cliUrl);
+      const pkgRoot = path.dirname(cliPath);
+      const mcpScriptPath = path.join(pkgRoot, 'bin', 'nsauditor-ai-mcp.mjs');
+
+      // MCP auth: keychain: indirection on macOS (no plaintext in
+      // config file). Literal value on Linux/Windows where there's
+      // no system secret store equivalent.
       const onKeychain = typeof persistedLocation === 'string' && persistedLocation.includes('Keychain');
-      const envValue = onKeychain ? `keychain:${MCP_AUTH_ENV_VAR}` : key;
+      const authEnvValue = onKeychain ? `keychain:${MCP_AUTH_ENV_VAR}` : key;
+
+      // License: detect whether configured and where it lives. On
+      // macOS, prefer the keychain: indirection — same no-plaintext
+      // pattern as auth. If license is in file (~/.nsauditor/.env)
+      // but NOT in Keychain, we'll prompt the operator to migrate
+      // (handled by the caller; this fn just emits the snippet).
+      const { loadLicense } = await import('./utils/license.mjs');
+      const licenseStatus = await loadLicense();
+      const licenseConfigured = licenseStatus.valid;
+
+      // Build the env block as a JSON-serializable object so the
+      // snippet output is valid JSON the operator can paste verbatim.
+      const envBlock = {};
+      envBlock[MCP_AUTH_ENV_VAR] = authEnvValue;
+      if (licenseConfigured) {
+        if (isDarwin) {
+          // Indirection — secret stays in Keychain. Requires that
+          // the license actually IS in Keychain (or in a place
+          // resolveSecret can reach). Caller is responsible for
+          // ensuring this is true before printing the snippet.
+          envBlock['NSAUDITOR_LICENSE_KEY'] = 'keychain:NSAUDITOR_LICENSE_KEY';
+        }
+        // On Linux/Windows we deliberately OMIT NSAUDITOR_LICENSE_KEY
+        // from the env block — the MCP server will fall through to
+        // the file fallback (~/.nsauditor/.env). Including a literal
+        // JWT would expose it in the world-readable config file.
+      }
+
+      const snippet = {
+        mcpServers: {
+          'nsauditor-ai': {
+            command: nodeBin,
+            args: [mcpScriptPath],
+            env: envBlock,
+          },
+        },
+      };
 
       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('═'.repeat(70));
+      console.log('Claude Desktop config — paste this into:');
+      if (isDarwin) {
+        console.log('  ~/Library/Application Support/Claude/claude_desktop_config.json');
+      } else if (platform() === 'win32') {
+        console.log('  %APPDATA%\\Claude\\claude_desktop_config.json');
+      } else {
+        console.log('  ~/.config/Claude/claude_desktop_config.json');
+      }
+      console.log('═'.repeat(70));
+      // Pretty-print with 2-space indent. If the operator already has
+      // mcpServers, they merge the inner "nsauditor-ai" block.
+      console.log(JSON.stringify(snippet, null, 2));
+      console.log('═'.repeat(70));
       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.");
+        // macOS + Keychain reachable: the snippet uses indirection
+        // for both auth and license. Secret never lands in the
+        // world-readable Claude Desktop config file.
+        console.log('Security notes:');
+        console.log(`  • Auth key uses "keychain:${MCP_AUTH_ENV_VAR}" indirection — the actual`);
+        console.log('    secret stays in macOS Keychain. The config file contains only the');
+        console.log('    placeholder string, NOT the secret.');
+        if (licenseConfigured) {
+          console.log('  • License key uses the same indirection — JWT never lands in the config.');
+        } else {
+          console.log('  • No license configured. To activate Pro/Enterprise features:');
+          console.log('      nsauditor-ai license install <YOUR-KEY>');
+          console.log('    Then re-run `nsauditor-ai mcp install-key` to get a snippet that');
+          console.log('    includes the license line.');
+        }
         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).`);
+        console.log('  • On a HEADLESS macOS / SSH-only CI runner where Keychain GUI prompts');
+        console.log("    won't reach you, replace the placeholder values with the literal");
+        console.log('    secrets (run `nsauditor-ai mcp print-key --confirm` for the auth');
+        console.log('    key). Move the config file to mode 0600 in that case.');
       } 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.`);
+        // Linux/Windows OR macOS-with-Keychain-unavailable: snippet
+        // contains literal secret. chmod warning required.
+        console.log('Security notes:');
+        console.log(`  • Auth key value is the LITERAL secret in the config file.`);
+        console.log('    chmod 600 your Claude Desktop config file to keep other local users');
+        console.log('    from reading it:');
+        if (platform() === 'win32') {
+          console.log('      icacls "%APPDATA%\\Claude\\claude_desktop_config.json" /inheritance:r /grant:r "%USERNAME%:F"');
+        } else if (isDarwin) {
+          console.log('      chmod 600 ~/Library/Application\\ Support/Claude/claude_desktop_config.json');
+        } else {
+          console.log('      chmod 600 ~/.config/Claude/claude_desktop_config.json');
+        }
+        if (licenseConfigured) {
+          console.log('  • License key is NOT in the env block — the MCP server reads it from');
+          console.log('    ~/.nsauditor/.env (mode 0600) at startup. No JWT in the config.');
+        } else {
+          console.log('  • No license configured. To activate Pro/Enterprise features:');
+          console.log('      nsauditor-ai license install <YOUR-KEY>');
+        }
+      }
+
+      console.log('');
+      console.log('After pasting:');
+      console.log('  1. Save the config file');
+      console.log('  2. Cmd+Q Claude Desktop (full quit) and re-launch');
+      if (isDarwin) {
+        console.log('  3. macOS will prompt for Keychain access on first launch — click "Always Allow"');
+        console.log('     for both NSA_MCP_AUTH_KEY and NSAUDITOR_LICENSE_KEY entries.');
       }
+      console.log('  4. Verify in Claude: ask "list nsauditor plugins"');
+      console.log(`     Tier should report as "${licenseConfigured ? licenseStatus.tier : 'ce'}"`);
       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.');
+      console.log('Diagnostic if it doesn\'t work:');
+      console.log('  nsauditor-ai mcp status     # confirm storage source');
+      if (licenseConfigured) {
+        console.log('  nsauditor-ai license --status   # confirm license still verified');
+      }
     }
 
     if (subCmd === 'install-key') {
@@ -1172,7 +1278,43 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       }
       console.log(`✓ MCP auth key ${generated ? 'generated and ' : ''}installed`);
       console.log(`  Stored at: ${persisted.location}`);
-      printConfigSnippet(key, persisted.location);
+
+      // Thread K: if license is configured but NOT in Keychain (e.g.,
+      // operator has it in ~/.nsauditor/.env from a pre-0.1.30 install
+      // or from manual editing), back-fill to Keychain on macOS so the
+      // `keychain:NSAUDITOR_LICENSE_KEY` indirection in the printed
+      // snippet actually resolves. Without this, the snippet would
+      // include the indirection but the MCP server would fail to find
+      // the license and report CE — exactly the customer-onboarding
+      // friction Thread K eliminates.
+      if (platform() === 'darwin') {
+        try {
+          const { resolveLicenseKey } = await import('./utils/license.mjs');
+          const { keychainGetDetailed, keychainSet } = await import('./utils/keychain.mjs');
+          const licenseKey = await resolveLicenseKey();
+          if (licenseKey) {
+            const keychainState = await keychainGetDetailed('NSAUDITOR_LICENSE_KEY');
+            if (keychainState.state !== 'ok') {
+              // License is reachable via env or file but not Keychain.
+              // Mirror it into Keychain so the indirection works.
+              await keychainSet('NSAUDITOR_LICENSE_KEY', licenseKey);
+              console.log('');
+              console.log('  ✓ License key mirrored from file/env to macOS Keychain');
+              console.log('    so the snippet below can use keychain: indirection.');
+              console.log('    Original storage location is preserved unchanged.');
+            }
+          }
+        } catch (err) {
+          // Best-effort: if the mirror fails, the snippet's keychain:
+          // indirection won't resolve, but the operator can fall back
+          // to literal-key configuration. Don't block install-key.
+          console.warn(`  ⚠ Could not mirror license to Keychain (${err.message}).`);
+          console.warn(`    The snippet below uses keychain: indirection — if Claude Desktop`);
+          console.warn(`    reports CE tier, replace the indirection with the literal license JWT.`);
+        }
+      }
+
+      await 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
@@ -1202,7 +1344,7 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       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);
+      await 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
@@ -1242,10 +1384,62 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       // 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 === 'tier') {
+      // Thread K (CE 0.1.32): customer-side ground-truth check for the
+      // tier the MCP server WOULD resolve to at startup. Customers
+      // (including the maintainer 2026-05-10) reported "Claude Desktop
+      // shows tier=CE" — but on investigation, Claude (the AI) was
+      // synthesizing the tier text from training data + context
+      // without actually calling list_plugins via MCP. The real MCP
+      // server's _tier was correct (enterprise), only Claude's
+      // narration was wrong. `mcp tier` runs the same loadLicense()
+      // path the MCP server uses and prints the unambiguous result —
+      // customers can paste this output into a support ticket and
+      // distinguish "MCP genuinely broken" from "Claude misreading".
+      const { loadLicense, getTierFromEnv } = await import('./utils/license.mjs');
+      const result = await loadLicense();
+      const tier = getTierFromEnv();
+      const tierLabels = {
+        ce: 'Community Edition (CE)',
+        pro: 'Pro',
+        enterprise: 'Enterprise',
+      };
+      const symbol = tier === 'ce' ? '✗' : '✓';
+      console.log(`${symbol} MCP server tier: ${tier} — ${tierLabels[tier] ?? tier}`);
+      if (result.valid) {
+        console.log(`  Org:        ${result.org}`);
+        console.log(`  Seats:      ${result.seats}`);
+        console.log(`  License ID: ${result.licenseId}`);
+        console.log(`  Expires:    ${result.expiresAt}`);
+        if (result.daysUntilExpiry !== undefined) {
+          console.log(`  Renews in:  ${result.daysUntilExpiry} days`);
+        }
+        if (result.expiryWarning) {
+          console.log(`  ⚠ ${result.expiryWarning}`);
+        }
+      } else {
+        console.log(`  Reason: ${result.reason}`);
+        console.log('');
+        console.log('  Diagnose with: nsauditor-ai license --status');
+        console.log('  Install with:  nsauditor-ai license install <KEY>');
+      }
+      console.log('');
+      console.log('This is the EXACT tier the spawned MCP server resolves to. If Claude');
+      console.log("Desktop reports a different tier, Claude isn't calling list_plugins —");
+      console.log('it\'s synthesizing from context. Force a real call by asking:');
+      console.log('  "Use the list_plugins MCP tool right now and show the raw response."');
+      // Exit 0 if any tier resolved (success), 1 if CE/no key (operator action needed).
+      process.exit(tier === 'ce' ? 1 : 0);
     } 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.
+      // logs, etc. EE-SEC.1.1 (Thread I): also surfaces key age + the
+      // keychain-locked state distinction (so headless macOS / SSH
+      // sessions get an actionable error rather than a generic
+      // "unconfigured" fallthrough). MEDIUM #4 fold: rotation
+      // threshold respects NSA_MCP_AUTH_KEY_ROTATION_DAYS env override.
+      const { getRotationWarningDays: _grwd } = await import('./utils/mcp_auth.mjs');
+      const _rwd = _grwd();
       const result = await reportMcpAuthSource();
       if (result.source === 'unconfigured') {
         console.log(`✗ MCP authentication is not configured.`);
@@ -1255,9 +1449,57 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
           console.log(`  ⚠ ${MCP_AUTH_DISABLE_ENV_VAR}=1 is set — server will start without auth.`);
         }
         process.exit(1);
+      } else if (result.source === 'keychain-locked') {
+        // EE-SEC.1.1 (Reviewer 2 MEDIUM #3 from EE-SEC.1): Keychain
+        // entry exists but the security daemon refused to unlock —
+        // GUI prompt unavailable. Common on SSH sessions, headless
+        // CI runners, and login-keychain-not-unlocked-yet scenarios.
+        // MEDIUM #3 fold (post-EE-SEC.1.1): operators triggering this
+        // branch are by construction in a no-GUI context. Reorder
+        // workarounds to put the GUI-FREE options first; "approve
+        // GUI prompt" demoted to the fallback for operators who DO
+        // have GUI access (rare given they hit this branch).
+        console.log(`⚠ MCP auth key is configured in macOS Keychain, but Keychain access`);
+        console.log(`  is currently locked (security daemon refused without GUI prompt).`);
+        console.log(`  This is normal on SSH sessions and headless CI runners.`);
+        console.log('');
+        console.log(`  Detail: ${result.detail}`);
+        console.log('');
+        console.log(`  Workarounds (GUI-free paths first):`);
+        console.log(`    1. Replace the keychain: indirection in Claude Desktop config`);
+        console.log(`       with the literal key value (run \`mcp print-key --confirm\`).`);
+        console.log(`    2. Move auth to the file fallback by setting NSA_MCP_AUTH_KEY`);
+        console.log(`       in ~/.nsauditor/.env directly (mode 0600).`);
+        console.log(`    3. If you have GUI access: approve a Keychain prompt in the`);
+        console.log(`       macOS GUI session.`);
+        process.exit(1);
       } else {
         console.log(`✓ MCP auth key configured`);
         console.log(`  Source: ${result.source}${result.detail ? ` (${result.detail})` : ''}`);
+        // EE-SEC.1.1: surface key age when known. Older installs
+        // (predating the timestamp companion) get null and the
+        // CRITICAL #1 hint below instead.
+        if (typeof result.ageDays === 'number') {
+          const ageStr = result.ageDays === 0 ? 'today' : `${result.ageDays} day${result.ageDays === 1 ? '' : 's'} ago`;
+          if (result.ageDays > _rwd) {
+            console.log(`  ⚠ Created: ${result.createdAt} (${ageStr}) — > ${_rwd}d threshold`);
+            console.log(`     Consider: nsauditor-ai mcp rotate-key --confirm`);
+            console.log(`     SOC 2 CC6.1 / CC6.7 reviewers flag unrotated shared secrets.`);
+          } else {
+            console.log(`  Created: ${result.createdAt} (${ageStr})`);
+          }
+        } else if (result.legacyTimestampMissing) {
+          // CRITICAL #1 fold (post-review): existing CE 0.1.31
+          // operators upgrading have a key but no timestamp →
+          // ageDays is null → silent. Distinct hint pointing at
+          // backfill so SOC 2 evidence isn't dark for the installed base.
+          console.log(`  ⚠ Created: unknown (pre-0.1.32 install — no rotation timestamp)`);
+          console.log(`     Backfill the timestamp without invalidating the key:`);
+          console.log(`       nsauditor-ai mcp print-key --confirm   # retrieve current key`);
+          console.log(`       nsauditor-ai mcp install-key <KEY>      # re-install with timestamp`);
+          console.log(`     Or rotate to a fresh key:`);
+          console.log(`       nsauditor-ai mcp rotate-key --confirm`);
+        }
         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.`);
@@ -1270,6 +1512,7 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       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('  nsauditor-ai mcp tier                   Print actual MCP server tier (ground truth, bypasses Claude AI synthesis)');
       console.log('');
       console.log('Environment variables:');
       console.log(`  ${MCP_AUTH_ENV_VAR}        Read by mcp_server.mjs at startup; client supplies via Claude config`);

package/mcp_server.mjs

@@ -22,7 +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';
+import { authorizeMcpServerStartup, getMcpAuthKeyAge, getRotationWarningDays, reportMcpAuthSource } from './utils/mcp_auth.mjs';
 
 const _require = createRequire(import.meta.url);
 const { version: TOOL_VERSION } = _require('./package.json');
@@ -436,6 +436,47 @@ if (isMainModule) {
     }
   }
 
+  // EE-SEC.1.1 (Thread I): rotation-cadence soft warning. SOC 2 CC6.1 /
+  // CC6.7 reviewers expect a credential-rotation cadence; an unrotated
+  // shared secret is treated the same way as an unrotated IAM access
+  // key.
+  //
+  // Design note (LOW #1 from Reviewer 2): soft warning, not hard
+  // refusal. Hard-refuse would break Claude Desktop integration mid-
+  // session for operators who haven't seen 30 days of warnings (Claude
+  // Desktop buries MCP server stderr in a log file most operators
+  // never check). Soft warning + `mcp status` operator-runnable
+  // evidence path is the right SOC 2 posture — auditor sees the warning
+  // fires AND that the operator chose to defer rotation.
+  //
+  // Reviewer 2 CRITICAL #1 fold: when a key is configured but the
+  // NSA_MCP_AUTH_KEY_CREATED companion is missing (operator upgraded
+  // from CE 0.1.31 without re-installing), we surface a DIFFERENT
+  // stderr message pointing at `mcp install-key <existing-key>` to
+  // backfill the timestamp. Without this hint, EE-SEC.1.1 ships dark
+  // for the entire installed base of CE 0.1.31 deployments.
+  try {
+    const status = await reportMcpAuthSource();
+    const threshold = getRotationWarningDays();
+    if (status.legacyTimestampMissing) {
+      process.stderr.write(
+        `⚠  MCP auth key is configured but the rotation-cadence timestamp ` +
+        `is missing (likely a pre-0.1.32 install). Rotation warnings will ` +
+        `not fire until you backfill the timestamp. Either:\n` +
+        `   (1) re-run \`nsauditor-ai mcp install-key <KEY>\` with your existing key ` +
+        `(use \`mcp print-key --confirm\` to retrieve it), OR\n` +
+        `   (2) rotate to a fresh key with \`nsauditor-ai mcp rotate-key --confirm\` ` +
+        `and update Claude Desktop config.\n`,
+      );
+    } else if (typeof status.ageDays === 'number' && status.ageDays > threshold) {
+      process.stderr.write(
+        `⚠  MCP auth key is ${status.ageDays} days old (> ${threshold}d threshold). ` +
+        `Consider \`nsauditor-ai mcp rotate-key --confirm\` and update Claude Desktop config. ` +
+        `SOC 2 CC6.1 / CC6.7 reviewers flag unrotated shared secrets.\n`,
+      );
+    }
+  } catch { /* age check is non-fatal — never block startup on it */ }
+
   // 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.31",
+  "version": "0.1.33",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/utils/keychain.mjs

@@ -33,6 +33,61 @@ export async function keychainGet(account) {
   }
 }
 
+/**
+ * Diagnostic variant of keychainGet that distinguishes failure modes.
+ * Used by EE-SEC.1.1 (Thread I) to surface a different error message
+ * for "Keychain locked / GUI prompt needed" (headless macOS / SSH-only
+ * CI) vs "no entry exists" (operator never ran install-key).
+ *
+ * Returns { value, state, raw }:
+ *   - state='ok'           — value is the secret
+ *   - state='not-found'    — Keychain has no entry for this account
+ *   - state='locked'       — Keychain entry exists but GUI approval needed
+ *   - state='unavailable'  — security daemon error (non-mac platform,
+ *                            timeout, etc.)
+ *
+ * On non-macOS platforms, returns { value: null, state: 'unavailable' }.
+ *
+ * @param {string} account
+ * @returns {Promise<{ value: string|null, state: 'ok'|'not-found'|'locked'|'unavailable', raw?: string }>}
+ */
+export async function keychainGetDetailed(account) {
+  if (!isMac) {
+    return { value: null, state: 'unavailable', raw: 'not-macos' };
+  }
+  try {
+    const value = await exec('security', [
+      'find-generic-password', '-s', SERVICE, '-a', account, '-w'
+    ]);
+    return { value, state: 'ok' };
+  } catch (err) {
+    const raw = (err && err.message) ? err.message : String(err);
+    // `security` returns specific stderr per failure mode. We pattern-
+    // match on the stable English text — the underlying SecKeychain
+    // API error codes (errSecInteractionNotAllowed=-25308,
+    // errSecItemNotFound=-25300) are also embedded but the strings
+    // are more reliable across macOS versions.
+    // EE-SEC.1.1 LOW #2 fold (post-review): also pattern-match numeric
+    // SecKeychain error codes (-25300 errSecItemNotFound, -25308
+    // errSecInteractionNotAllowed). The English-text patterns are
+    // stable on US-locale macOS but break on localized installs
+    // (French/Japanese/etc.); the numeric codes appear in the security
+    // command's stderr regardless of locale.
+    if (/could not be found in the keychain/i.test(raw)
+        || /SecKeychainSearchCopyNext: The specified item could not be found/i.test(raw)
+        || /errSecItemNotFound/i.test(raw)
+        || /-25300\b/.test(raw)) {
+      return { value: null, state: 'not-found', raw };
+    }
+    if (/User interaction is not allowed/i.test(raw)
+        || /errSecInteractionNotAllowed/i.test(raw)
+        || /-25308\b/.test(raw)) {
+      return { value: null, state: 'locked', raw };
+    }
+    return { value: null, state: 'unavailable', raw };
+  }
+}
+
 /**
  * Store a secret in the macOS Keychain.
  * Updates existing entry if present.

package/utils/license.mjs

@@ -11,7 +11,7 @@ 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';
+import { keychainGet, keychainSet, resolveSecret } 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).
@@ -286,9 +286,24 @@ export async function loadLicense(keyStr) {
   // 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());
+  let raw = keyStr ?? (await resolveLicenseKey());
   if (!raw) return { valid: false, tier: 'ce', reason: 'no key provided' };
 
+  // Thread K (CE 0.1.32): support `keychain:LABEL` indirection on the
+  // resolved value. Mirrors the EE-SEC.1 MCP-auth pattern — operators
+  // can put `"NSAUDITOR_LICENSE_KEY": "keychain:NSAUDITOR_LICENSE_KEY"`
+  // in their Claude Desktop config env block; the literal JWT never
+  // lands in the world-readable config file. resolveSecret is a no-op
+  // (returns input unchanged) for non-`keychain:` strings, so literal
+  // JWT keys continue to work for backward compat.
+  if (typeof raw === 'string' && raw.startsWith('keychain:')) {
+    const resolved = await resolveSecret(raw);
+    if (!resolved) {
+      return { valid: false, tier: 'ce', reason: 'license keychain: indirection could not be resolved (entry missing or Keychain locked)' };
+    }
+    raw = resolved;
+  }
+
   // Strip tier prefix
   let token = raw;
   let prefixTier = null;

package/utils/mcp_auth.mjs

@@ -51,7 +51,7 @@ import { dirname, join } from 'node:path';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import dotenv from 'dotenv';
 
-import { keychainGet, keychainSet, resolveSecret } from './keychain.mjs';
+import { keychainGet, keychainSet, keychainGetDetailed, resolveSecret } from './keychain.mjs';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -71,6 +71,43 @@ export const MCP_AUTH_DISABLE_ENV_VAR = 'NSA_MCP_AUTH_DISABLE';
 // named so operators don't have to remember two strings.
 const MCP_AUTH_KEYCHAIN_ACCOUNT = MCP_AUTH_ENV_VAR;
 
+// EE-SEC.1.1: created-at timestamp companion. Stored alongside the key
+// so `mcp status` and the server-startup stderr can emit a soft warning
+// when the key has been in use for more than ROTATION_WARNING_DAYS.
+// SOC 2 CC6.1 / CC6.7 reviewers expect a credential rotation cadence;
+// an unrotated MCP auth key is a finding the same way an unrotated
+// IAM access key is a finding.
+export const MCP_AUTH_CREATED_ENV_VAR = 'NSA_MCP_AUTH_KEY_CREATED';
+const MCP_AUTH_CREATED_KEYCHAIN_ACCOUNT = MCP_AUTH_CREATED_ENV_VAR;
+export const ROTATION_WARNING_DAYS = 90;
+// EE-SEC.1.1 MEDIUM #4 fold (post-review): operator override env var.
+// SOC 2 doesn't fix a number — common interpretations span 30/60/90/180.
+// PCI-DSS pushes for 90d hard; NIST SP 800-63B prefers event-based rotation.
+// An operator whose customer auditor demands 60 days needs a knob; clamping
+// to [7, 365] prevents pathological values (sub-week = constant-warn-noise;
+// > 1 year = effectively no rotation).
+export const ROTATION_WARNING_DAYS_ENV_VAR = 'NSA_MCP_AUTH_KEY_ROTATION_DAYS';
+
+/**
+ * Resolve the effective rotation-warning threshold. Reads
+ * NSA_MCP_AUTH_KEY_ROTATION_DAYS from the env (or `opts._env`),
+ * clamps to [7, 365], falls back to ROTATION_WARNING_DAYS (90).
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts._env]
+ * @returns {number}
+ */
+export function getRotationWarningDays(opts = {}) {
+  const env = opts._env ?? process.env;
+  const raw = env[ROTATION_WARNING_DAYS_ENV_VAR];
+  if (!raw) return ROTATION_WARNING_DAYS;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) return ROTATION_WARNING_DAYS;
+  return Math.max(7, Math.min(365, parsed));
+}
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
 // 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.
@@ -196,29 +233,153 @@ export async function resolveMcpAuthKey(opts = {}) {
  * 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 }>}
+ * EE-SEC.1.1: extended with `ageDays` (when a created-at timestamp is
+ * available) so `mcp status` and the server-startup stderr can emit a
+ * soft warning when the key has been in use for more than
+ * ROTATION_WARNING_DAYS. Also distinguishes Keychain-locked from
+ * Keychain-empty so headless macOS / SSH-only CI runners get an
+ * actionable error rather than a generic "unconfigured" fallthrough.
+ *
+ * @param {object} [opts] — same test seams as resolveMcpAuthKey, plus
+ *   `_keychainGetDetailed` for the lock-state distinction and `_now`
+ *   for hermetic age computation.
+ * @returns {Promise<{
+ *   source: 'env'|'keychain'|'file'|'unconfigured'|'keychain-locked',
+ *   detail?: string,
+ *   ageDays?: number|null,
+ *   createdAt?: string|null,
+ * }>}
  */
 export async function reportMcpAuthSource(opts = {}) {
+  const now = opts._now ? new Date(opts._now).getTime() : Date.now();
+
   if (process.env[MCP_AUTH_ENV_VAR]) {
-    return { source: 'env', detail: MCP_AUTH_ENV_VAR };
+    // No createdAt available for env-supplied keys — operator-managed,
+    // we don't know the rotation history. EE-SEC.1.1 CRITICAL #1 fold:
+    // surface a `legacyTimestampMissing: false` here so callers don't
+    // mis-interpret env-supplied as "old install missing timestamp".
+    return {
+      source: 'env',
+      detail: MCP_AUTH_ENV_VAR,
+      ageDays: null,
+      createdAt: null,
+      legacyTimestampMissing: false,
+    };
   }
-  const kget = opts._keychainGet ?? keychainGet;
+
+  // EE-SEC.1.1: use detailed Keychain lookup so lock-state is preserved.
+  // Backward-compat: legacy callers (and EE-SEC.1 tests) supply
+  // _keychainGet which returns just `string|null`. Wrap it into the
+  // detailed shape so the resolver works for both APIs.
+  let kgetDetailed;
+  if (opts._keychainGetDetailed) {
+    kgetDetailed = opts._keychainGetDetailed;
+  } else if (opts._keychainGet) {
+    const legacyKget = opts._keychainGet;
+    kgetDetailed = async (account) => {
+      try {
+        const value = await legacyKget(account);
+        return value
+          ? { value, state: 'ok' }
+          : { value: null, state: 'not-found' };
+      } catch (err) {
+        return { value: null, state: 'unavailable', raw: err && err.message ? err.message : String(err) };
+      }
+    };
+  } else {
+    kgetDetailed = keychainGetDetailed;
+  }
+  let detailedResult = null;
   try {
-    const fromKeychain = await kget(MCP_AUTH_KEYCHAIN_ACCOUNT);
-    if (fromKeychain) {
-      return { source: 'keychain', detail: 'macOS Keychain (service=nsauditor-ai)' };
+    detailedResult = await kgetDetailed(MCP_AUTH_KEYCHAIN_ACCOUNT);
+  } catch { /* defensive — should never throw, but tolerate test seams that do */ }
+  if (detailedResult && detailedResult.state === 'ok' && detailedResult.value) {
+    // Read the companion timestamp (best-effort; old installs may not
+    // have it). EE-SEC.1.1: skip the timestamp lookup when the caller
+    // only supplied the legacy `_keychainGet` seam — that seam returns
+    // the same value for any account name (it's a single-account stub),
+    // so calling it for the timestamp contaminates the result with the
+    // key value. Real `keychainGetDetailed` properly distinguishes by
+    // account.
+    let createdAt = null;
+    const usedLegacySeam = !opts._keychainGetDetailed && opts._keychainGet;
+    if (!usedLegacySeam) {
+      try {
+        const ts = await kgetDetailed(MCP_AUTH_CREATED_KEYCHAIN_ACCOUNT);
+        if (ts && ts.state === 'ok' && ts.value) createdAt = ts.value;
+      } catch { /* fall through */ }
     }
-  } catch { /* fall through */ }
+    return {
+      source: 'keychain',
+      detail: 'macOS Keychain (service=nsauditor-ai)',
+      createdAt,
+      ageDays: _ageDaysFromIso(createdAt, now),
+      // EE-SEC.1.1 CRITICAL #1 fold: existing CE 0.1.31 operators
+      // upgrading to 0.1.32 have a key but no NSA_MCP_AUTH_KEY_CREATED
+      // companion — `getMcpAuthKeyAge` returns null and the rotation
+      // warning silently never fires. The auditor evidence story is
+      // broken until the operator happens to rotate. Distinguish
+      // "legacy install missing timestamp" from "env-supplied (no
+      // history known)" so cli.mjs `mcp status` and the server-startup
+      // stderr can prompt operators to backfill via `mcp install-key
+      // <existing-key>` (which preserves the key but writes the
+      // timestamp companion).
+      legacyTimestampMissing: createdAt === null,
+    };
+  }
+  if (detailedResult && detailedResult.state === 'locked') {
+    // Keychain has the entry but the security daemon refused to
+    // unlock — operator's GUI is unavailable (SSH / headless CI /
+    // login-keychain not unlocked yet).
+    return {
+      source: 'keychain-locked',
+      detail: 'macOS Keychain (service=nsauditor-ai) — entry exists but interaction not allowed',
+      ageDays: null,
+      createdAt: null,
+    };
+  }
+
   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 };
+      const createdAt = parsed[MCP_AUTH_CREATED_ENV_VAR] || null;
+      return {
+        source: 'file',
+        detail: filePath,
+        createdAt,
+        ageDays: _ageDaysFromIso(createdAt, now),
+        // CRITICAL #1 fold: same legacy-install signal as the keychain
+        // branch above.
+        legacyTimestampMissing: createdAt === null,
+      };
     }
   } catch { /* fall through */ }
-  return { source: 'unconfigured' };
+  return { source: 'unconfigured', ageDays: null, createdAt: null };
+}
+
+/**
+ * Get the age of the configured MCP auth key, in days. Returns null
+ * when no key is configured or the timestamp is missing/unparseable
+ * (older installs predating EE-SEC.1.1 won't have the timestamp).
+ *
+ * @param {object} [opts] — same test seams as reportMcpAuthSource.
+ * @returns {Promise<number|null>}
+ */
+export async function getMcpAuthKeyAge(opts = {}) {
+  const status = await reportMcpAuthSource(opts);
+  return status.ageDays ?? null;
+}
+
+// Internal: parse an ISO-8601 timestamp and return age in days from
+// the reference time. Returns null on parse failure or future dates.
+function _ageDaysFromIso(isoString, nowMs) {
+  if (typeof isoString !== 'string' || isoString.length === 0) return null;
+  const ms = Date.parse(isoString);
+  if (Number.isNaN(ms)) return null;
+  if (ms > nowMs) return null; // clock skew — don't emit a misleading negative
+  return Math.floor((nowMs - ms) / MS_PER_DAY);
 }
 
 function defaultMcpAuthFilePath() {
@@ -251,13 +412,34 @@ export async function persistMcpAuthKey(key, opts = {}) {
 
   const plat = opts._platform ?? platform();
   const kset = opts._keychainSet ?? keychainSet;
+  // EE-SEC.1.1: timestamp the key for rotation cadence tracking.
+  // ISO-8601 UTC for unambiguous parsing across timezones / locales.
+  // Test seam allows hermetic injection of "now".
+  // Reviewer 1 MEDIUM #1 fold (post-EE-SEC.1.1): normalize _now via
+  // `new Date(...).toISOString()` so callers passing an epoch-ms
+  // number (valid in reportMcpAuthSource via `new Date(opts._now).getTime()`)
+  // don't write an unparseable literal. Production callers always
+  // omit _now; this guards the hermetic-test path symmetrically.
+  const createdAt = opts._now
+    ? new Date(opts._now).toISOString()
+    : new Date().toISOString();
 
   // 1. macOS: try Keychain first.
   let keychainFallbackReason = null;
   if (plat === 'darwin') {
     try {
+      // Reviewer 2 MEDIUM #2 fold (post-EE-SEC.1.1): write timestamp
+      // FIRST, then key. A half-write where the timestamp succeeds
+      // but the key fails leaves no usable key — auth check refuses
+      // the next startup → fail-CLOSED. Pre-fold the order was
+      // reversed: a half-write left a usable key with no timestamp,
+      // silently disabling rotation-cadence warnings forever.
+      // Companion writes use the same kset; if the FIRST one fails
+      // we fall through to file storage (full reset) rather than
+      // leaving partial state.
+      await kset(MCP_AUTH_CREATED_KEYCHAIN_ACCOUNT, createdAt);
       await kset(MCP_AUTH_KEYCHAIN_ACCOUNT, key);
-      return { ok: true, location: 'macOS Keychain (service=nsauditor-ai)' };
+      return { ok: true, location: 'macOS Keychain (service=nsauditor-ai)', createdAt };
     } catch (err) {
       keychainFallbackReason = err && err.message ? err.message : String(err);
     }
@@ -284,13 +466,35 @@ export async function persistMcpAuthKey(key, opts = {}) {
       existingContent = await fsp.readFile(filePath, 'utf8');
     } catch { /* missing file — create one */ }
 
-    const newContent = mergeMcpAuthIntoEnvFile(existingContent, key);
-    await fsp.writeFile(filePath, newContent, { mode: 0o600 });
+    // EE-SEC.1.1: write BOTH the key and the created-at timestamp.
+    // Same merge semantics — preserves other env-vars, replaces
+    // existing values, drops duplicates. The two writes are atomic
+    // at the file level (single writeFile call after merging both
+    // into the new content).
+    //
+    // Reviewer 2 MEDIUM #1 fold (post-EE-SEC.1.1): write to a
+    // sibling .tmp file first, then rename() — POSIX rename is
+    // atomic, so concurrent readers see either the OLD file or the
+    // NEW file, never a truncated mid-write state. Fixes the race
+    // where `mcp status` running simultaneously with `mcp install-key`
+    // could observe an empty file → "unconfigured" → operator
+    // confusion. Also defends against host-crash mid-write losing
+    // both the key AND the timestamp.
+    let newContent = mergeMcpAuthIntoEnvFile(existingContent, key);
+    newContent = mergeMcpAuthCreatedIntoEnvFile(newContent, createdAt);
+    const tmpPath = `${filePath}.tmp`;
+    await fsp.writeFile(tmpPath, newContent, { mode: 0o600 });
+    if (plat !== 'win32') {
+      await fsp.chmod(tmpPath, 0o600);
+    }
+    await fsp.rename(tmpPath, filePath);
     if (plat !== 'win32') {
+      // rename preserves source mode on POSIX, but a chmod after is
+      // belt-and-suspenders if the source mode was somehow changed.
       await fsp.chmod(filePath, 0o600);
     }
 
-    const result = { ok: true, location: filePath };
+    const result = { ok: true, location: filePath, createdAt };
     if (keychainFallbackReason !== null) {
       result.warning =
         `macOS Keychain unavailable (${keychainFallbackReason}); fell back to file storage. ` +
@@ -316,34 +520,86 @@ export async function persistMcpAuthKey(key, opts = {}) {
  * @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, '\\$&');
+  return mergeKeyValueIntoEnvFile(
+    existingContent,
+    MCP_AUTH_ENV_VAR,
+    key,
+    `# NSAuditor AI MCP auth key — set via \`nsauditor-ai mcp install-key\``,
+  );
+}
+
+/**
+ * Merge a created-at timestamp companion line. EE-SEC.1.1 — used by
+ * persistMcpAuthKey to write `NSA_MCP_AUTH_KEY_CREATED=<ISO-8601>`
+ * alongside the auth key for rotation-cadence tracking.
+ *
+ * Exported for test coverage.
+ * @internal
+ */
+export function mergeMcpAuthCreatedIntoEnvFile(existingContent, createdAt) {
+  return mergeKeyValueIntoEnvFile(
+    existingContent,
+    MCP_AUTH_CREATED_ENV_VAR,
+    createdAt,
+    null, // no header — already present from the key line
+  );
+}
+
+/**
+ * Generic dotenv-format merge: replace `${name}=...` line if present
+ * (collapsing duplicates per the corrupted-file defense), append at
+ * end if absent, write a header for empty input.
+ *
+ * EE-SEC.1.1 (Thread I refactor): the original merge logic was
+ * copy-pasted between the auth-key and (now) created-at lines; this
+ * factor-out also addresses Reviewer 2 LOW #2 from EE-SEC.1 (the
+ * universal-exclusion + sentinel-string duplication concern — both
+ * are now contained in a single helper).
+ *
+ * Reviewer 1 MEDIUM #5 fold (preserved): regex metacharacters in
+ * `name` are escaped before interpolation. Today the names are
+ * `NSA_MCP_AUTH_KEY` and `NSA_MCP_AUTH_KEY_CREATED` (no specials),
+ * so this is defense-in-depth — but a future rename containing
+ * `.+?^${}()|[]\\` would silently break the merge without this guard.
+ *
+ * @param {string} existingContent — current dotenv file content.
+ * @param {string} name — env-var name to write/replace.
+ * @param {string} value — value to assign.
+ * @param {string|null} headerComment — optional header to write when
+ *   the file is empty (e.g., `# NSAuditor AI MCP auth key — ...`).
+ * @internal
+ */
+export function mergeKeyValueIntoEnvFile(existingContent, name, value, headerComment = null) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const KEY_LINE_RE = new RegExp(
     `^[ \\t]*${escaped}[ \\t]*=[^\\r\\n]*$`,
     'gm',
   );
-  const newLine = `${MCP_AUTH_ENV_VAR}=${key}`;
+  const newLine = `${name}=${value}`;
+  // Sentinel includes the env-var name to avoid the (astronomical
+  // but possible) collision concern Reviewer 2 LOW #2 raised — the
+  // sentinel is now per-key rather than global.
+  const PURGE_SENTINEL = `__NSAUDITOR_PURGE_${name}__`;
 
   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__';
+      if (firstReplaced) return PURGE_SENTINEL;
       firstReplaced = true;
       return newLine;
     });
-    merged = merged.replace(/__NSAUDITOR_PURGE__\r?\n?/g, '');
+    const sentinelRe = new RegExp(
+      PURGE_SENTINEL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\r?\\n?',
+      'g',
+    );
+    merged = merged.replace(sentinelRe, '');
     return merged;
   }
 
   if (existingContent.trim().length === 0) {
-    return `# NSAuditor AI MCP auth key — set via \`nsauditor-ai mcp install-key\`\n${newLine}\n`;
+    const header = headerComment ? `${headerComment}\n` : '';
+    return `${header}${newLine}\n`;
   }
 
   const sep = existingContent.endsWith('\n') ? '' : '\n';