nsauditor-ai 0.1.31 → 0.1.32

package/README.md

@@ -15,6 +15,30 @@ 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.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.
@@ -362,7 +386,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 +460,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.32",
   "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';