@pan-sec/notebooklm-mcp 1.4.0

package/docs/SECURITY_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,437 @@
+# Security Implementation Plan - High Priority Features
+
+## Overview
+
+This plan outlines the implementation of 5 high-priority security features for the notebooklm-mcp-secure fork.
+
+**Target Version**: 1.3.0-secure
+**Status**: ✅ ALL PHASES COMPLETE
+**Estimated Files**: 8 new, 6 modified
+
+### Implementation Status
+
+| Phase | Feature | Status |
+|-------|---------|--------|
+| 1 | Audit Logging | ✅ Complete |
+| 2 | Session Timeout | ✅ Complete |
+| 3 | MCP Authentication | ✅ Complete |
+| 4 | Response Validation | ✅ Complete |
+| 5 | Post-Quantum Encrypted Storage | ✅ Complete |
+
+---
+
+## Feature 1: Post-Quantum Encrypted Credential Storage ✅
+
+### Problem
+Chrome profile stores session cookies and auth state in plaintext on disk at:
+- `~/.local/share/notebooklm-mcp/chrome_profile/`
+- `~/.local/share/notebooklm-mcp/browser_state/state.json`
+
+Anyone with disk access can steal the Google session. Additionally, classical encryption may be vulnerable to future quantum computer attacks.
+
+### Solution
+Encrypt sensitive files at rest using **hybrid post-quantum encryption**:
+- **ML-KEM-768 (Kyber)** for quantum-resistant key encapsulation
+- **AES-256-GCM** for symmetric encryption
+- **PBKDF2** for classical key derivation from passwords
+
+This hybrid approach provides both current security and future quantum resistance.
+
+### Implementation (COMPLETE)
+
+```
+src/utils/crypto.ts (NEW) ✅
+├── deriveKey(passphrase, salt) → Key derivation using PBKDF2
+├── getMachineKey() → Derive key from machine ID (fallback)
+├── generatePQKeyPair() → Generate ML-KEM-768 key pair
+├── encryptPQ(data, publicKey) → Hybrid PQ+AES-256-GCM encryption
+├── decryptPQ(ciphertext, secretKey) → Hybrid PQ decryption
+├── encryptClassical(data, key) → AES-256-GCM encryption (fallback)
+├── decryptClassical(ciphertext, key) → AES-256-GCM decryption
+└── SecureStorage class
+    ├── initialize() → Load/generate PQ keys
+    ├── save(filename, data) → Encrypt with ML-KEM-768 + AES-256-GCM
+    ├── load(filename) → Decrypt and return data
+    ├── loadJSON<T>(filename) → Parse JSON after decryption
+    ├── delete(filename) → Remove all encrypted versions
+    ├── exists(filename) → Check any version exists
+    ├── getStatus() → Return encryption status
+    └── getPublicKey() → Export PQ public key
+```
+
+### Encrypted File Format
+```json
+{
+  "version": 2,
+  "algorithm": "aes-256-gcm",
+  "pqAlgorithm": "ML-KEM-768",
+  "encapsulatedKey": "<base64>",
+  "iv": "<base64>",
+  "salt": "<base64>",
+  "tag": "<base64>",
+  "ciphertext": "<base64>"
+}
+```
+
+### Files Modified
+- `src/auth/auth-manager.ts` ✅ - Use SecureStorage for state.json, session.json
+- `package.json` ✅ - Added `@noble/post-quantum` dependency
+
+### Environment Variables
+```
+NLMCP_ENCRYPTION_ENABLED=true         # Default: true
+NLMCP_ENCRYPTION_KEY=<base64-key>     # Optional: User-provided classical key
+NLMCP_USE_POST_QUANTUM=true           # Default: true
+NLMCP_USE_MACHINE_KEY=true            # Default: true (fallback)
+NLMCP_PBKDF2_ITERATIONS=100000        # Default: 100000
+```
+
+### Dependencies
+- Node.js `crypto` module (built-in)
+- `@noble/post-quantum` v0.2.1 - ML-KEM (Kyber) implementation
+
+### Security Properties
+1. **Quantum Resistance**: ML-KEM-768 provides ~192-bit post-quantum security
+2. **Hybrid Security**: Even if PQ crypto is broken, AES-256-GCM remains secure
+3. **Forward Secrecy**: New encapsulated key per file save
+4. **Automatic Migration**: Unencrypted files are automatically encrypted on load
+
+---
+
+## Feature 2: Session Timeout Enforcement
+
+### Problem
+Sessions can remain active indefinitely. Stale sessions with valid cookies pose security risk.
+
+### Solution
+Implement configurable hard timeout that:
+1. Forces session closure after max lifetime (e.g., 8 hours)
+2. Forces re-authentication after inactivity (e.g., 30 minutes)
+3. Clears sensitive memory on timeout
+
+### Implementation
+
+```
+src/session/session-timeout.ts (NEW)
+├── SessionTimeoutManager class
+│   ├── startSession(sessionId)
+│   ├── touchSession(sessionId) → Reset inactivity timer
+│   ├── isExpired(sessionId) → boolean
+│   ├── getTimeRemaining(sessionId) → { lifetime, inactivity }
+│   └── onTimeout callback → Cleanup handler
+└── TimeoutConfig interface
+    ├── maxLifetimeMs: number (default: 8 hours)
+    ├── inactivityTimeoutMs: number (default: 30 min)
+    └── warningBeforeMs: number (default: 5 min)
+```
+
+### Files Modified
+- `src/session/session-manager.ts` - Integrate timeout checks
+- `src/session/browser-session.ts` - Call touchSession on activity
+- `src/tools/handlers.ts` - Return timeout warnings in responses
+- `src/config.ts` - Add timeout config options
+
+### Environment Variables
+```
+NLMCP_SESSION_MAX_LIFETIME=28800      # 8 hours in seconds
+NLMCP_SESSION_INACTIVITY_TIMEOUT=1800 # 30 minutes in seconds
+```
+
+---
+
+## Feature 3: Audit Logging
+
+### Problem
+No record of what operations were performed, when, or by whom. Critical for:
+- Security incident investigation
+- Compliance requirements
+- Debugging production issues
+
+### Solution
+Comprehensive audit log with:
+- All tool invocations with sanitized parameters
+- Authentication events (login, logout, failures)
+- Session lifecycle events
+- Security events (validation failures, rate limits)
+
+### Implementation
+
+```
+src/utils/audit-logger.ts (NEW)
+├── AuditLogger class
+│   ├── logToolCall(tool, args, result, duration)
+│   ├── logAuthEvent(event, success, details)
+│   ├── logSessionEvent(event, sessionId, details)
+│   ├── logSecurityEvent(event, severity, details)
+│   └── flush() → Force write to disk
+├── AuditEvent interface
+│   ├── timestamp: ISO8601 string
+│   ├── eventType: 'tool' | 'auth' | 'session' | 'security'
+│   ├── eventName: string
+│   ├── success: boolean
+│   ├── duration_ms?: number
+│   ├── details: Record<string, any> (sanitized)
+│   └── hash: SHA256 of previous entry (tamper detection)
+└── Log rotation and retention config
+```
+
+### Log Format (JSONL)
+```json
+{"timestamp":"2025-11-28T10:30:00Z","eventType":"tool","eventName":"ask_question","success":true,"duration_ms":3420,"details":{"question_length":150,"session_id":"abc123"},"hash":"a1b2c3..."}
+{"timestamp":"2025-11-28T10:30:05Z","eventType":"security","eventName":"rate_limit_exceeded","success":false,"details":{"session_id":"abc123","remaining":0},"hash":"d4e5f6..."}
+```
+
+### Files Modified
+- `src/tools/handlers.ts` - Add audit logging to all handlers
+- `src/auth/auth-manager.ts` - Log auth events
+- `src/session/session-manager.ts` - Log session events
+- `src/index.ts` - Initialize audit logger on startup
+
+### Log Location
+```
+~/.local/share/notebooklm-mcp/audit/
+├── audit-2025-11-28.jsonl
+├── audit-2025-11-27.jsonl
+└── ...
+```
+
+### Environment Variables
+```
+NLMCP_AUDIT_ENABLED=true
+NLMCP_AUDIT_DIR=~/.local/share/notebooklm-mcp/audit
+NLMCP_AUDIT_RETENTION_DAYS=30
+```
+
+---
+
+## Feature 4: Content Security Policy (Response Validation)
+
+### Problem
+NotebookLM responses could potentially contain:
+- Malicious links
+- Prompt injection attempts targeting Claude
+- Encoded payloads
+- Exfiltration URLs
+
+### Solution
+Validate and sanitize all responses before returning to the MCP client.
+
+### Implementation
+
+```
+src/utils/response-validator.ts (NEW)
+├── ResponseValidator class
+│   ├── validate(response) → { safe: boolean, warnings: string[], sanitized: string }
+│   ├── detectMaliciousUrls(text) → URLs to untrusted domains
+│   ├── detectPromptInjection(text) → Injection patterns
+│   ├── detectEncodedPayloads(text) → Base64, hex, etc.
+│   ├── sanitizeResponse(text) → Cleaned text
+│   └── getStats() → { blocked, warned, passed }
+└── ValidationConfig
+    ├── blockMaliciousUrls: boolean
+    ├── blockPromptInjection: boolean
+    ├── warnOnSuspicious: boolean
+    └── allowedDomains: string[]
+```
+
+### Detection Patterns
+```typescript
+// Prompt injection patterns (from MEDUSA AI security scanner)
+const PROMPT_INJECTION_PATTERNS = [
+  /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?)/i,
+  /disregard\s+(all\s+)?(previous|prior|above)/i,
+  /you\s+are\s+now\s+in\s+(\w+)\s+mode/i,
+  /forget\s+(everything|all|your)\s+(you|instructions)/i,
+  /new\s+instructions?:/i,
+  /system\s*:\s*/i,
+  /\[INST\]/i,
+  /<\|im_start\|>/i,
+];
+
+// Suspicious URL patterns
+const SUSPICIOUS_URL_PATTERNS = [
+  /bit\.ly|tinyurl|t\.co/i,  // URL shorteners
+  /pastebin|hastebin/i,       // Paste services
+  /file:\/\//i,               // File protocol
+  /javascript:/i,             // JS protocol
+];
+```
+
+### Files Modified
+- `src/tools/handlers.ts` - Validate responses before returning
+- `src/session/browser-session.ts` - Optional: validate at capture time
+
+### Environment Variables
+```
+NLMCP_RESPONSE_VALIDATION=true
+NLMCP_BLOCK_PROMPT_INJECTION=true
+NLMCP_BLOCK_SUSPICIOUS_URLS=true
+```
+
+---
+
+## Feature 5: MCP Authentication
+
+### Problem
+Any process on the local machine can connect to the MCP server via stdio. No authentication means:
+- Malicious processes can use your Google session
+- No accountability for requests
+- Shared machines are especially vulnerable
+
+### Solution
+Require authentication token for MCP requests.
+
+### Implementation Options
+
+#### Option A: Environment Token (Simple)
+```
+NLMCP_AUTH_TOKEN=<random-32-char-token>
+```
+Client must include in request metadata.
+
+#### Option B: Unix Socket Permissions (Linux/Mac)
+Instead of stdio, use Unix socket with file permissions.
+
+#### Option C: Challenge-Response (Most Secure)
+1. Server generates challenge on connect
+2. Client signs challenge with shared secret
+3. Server validates signature
+
+### Chosen: Option A (Environment Token) + Option B (Unix Socket)
+
+```
+src/auth/mcp-auth.ts (NEW)
+├── MCPAuthenticator class
+│   ├── validateToken(token) → boolean
+│   ├── generateToken() → string (for initial setup)
+│   ├── hashToken(token) → string (stored hash, not plaintext)
+│   └── isEnabled() → boolean
+└── Token storage in encrypted config
+```
+
+### Files Modified
+- `src/index.ts` - Add auth middleware to MCP server
+- `src/config.ts` - Add auth config options
+
+### Environment Variables
+```
+NLMCP_AUTH_ENABLED=true
+NLMCP_AUTH_TOKEN=<token>              # Or auto-generated on first run
+NLMCP_AUTH_TOKEN_FILE=~/.config/notebooklm-mcp/token
+```
+
+### Client Configuration (Claude Code)
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "npx",
+      "args": ["notebooklm-mcp-secure"],
+      "env": {
+        "NLMCP_AUTH_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Implementation Order
+
+| Phase | Feature | Complexity | Dependencies |
+|-------|---------|------------|--------------|
+| 1 | Audit Logging | Medium | None |
+| 2 | Session Timeout | Low | None |
+| 3 | MCP Authentication | Medium | None |
+| 4 | Response Validation | Medium | MEDUSA patterns |
+| 5 | Encrypted Storage | High | Phase 1 (for key storage) |
+
+### Rationale
+1. **Audit Logging first** - Enables monitoring of all subsequent changes
+2. **Session Timeout second** - Quick win, low risk
+3. **MCP Auth third** - Critical for shared environments
+4. **Response Validation fourth** - Leverages MEDUSA patterns
+5. **Encrypted Storage last** - Most complex, benefits from audit logs
+
+---
+
+## Testing Plan
+
+### Unit Tests
+```
+tests/
+├── crypto.test.ts
+├── session-timeout.test.ts
+├── audit-logger.test.ts
+├── response-validator.test.ts
+└── mcp-auth.test.ts
+```
+
+### Integration Tests
+- Full flow with all security features enabled
+- Timeout behavior under load
+- Audit log integrity verification
+- Auth token rotation
+
+### Security Tests
+- Attempt to bypass auth
+- Inject malicious responses
+- Tamper with audit logs
+- Access encrypted data without key
+
+---
+
+## Rollout
+
+### Version 1.3.0-secure.1
+- Audit Logging
+- Session Timeout
+
+### Version 1.3.0-secure.2
+- MCP Authentication
+- Response Validation
+
+### Version 1.3.0-secure.3
+- Encrypted Storage
+- Full integration testing
+
+---
+
+## Success Metrics
+
+| Feature | Metric |
+|---------|--------|
+| Encrypted Storage | 0 plaintext credentials on disk |
+| Session Timeout | 100% sessions expire correctly |
+| Audit Logging | All events logged with <1ms overhead |
+| Response Validation | 0 prompt injections passed through |
+| MCP Auth | 0 unauthorized requests processed |
+
+---
+
+## Appendix: File Structure After Implementation
+
+```
+src/
+├── auth/
+│   ├── auth-manager.ts (modified)
+│   └── mcp-auth.ts (NEW)
+├── session/
+│   ├── browser-session.ts (modified)
+│   ├── session-manager.ts (modified)
+│   └── session-timeout.ts (NEW)
+├── utils/
+│   ├── security.ts (existing)
+│   ├── crypto.ts (NEW)
+│   ├── audit-logger.ts (NEW)
+│   └── response-validator.ts (NEW)
+├── config.ts (modified)
+└── index.ts (modified)
+```
+
+---
+
+**Document Version**: 1.0
+**Created**: 2025-11-28
+**Author**: Pantheon Security

package/docs/configuration.md

@@ -0,0 +1,94 @@
+## Configuration
+
+**No config files needed!** The server works out of the box with sensible defaults.
+
+### Configuration Priority (highest to lowest):
+1. **Tool Parameters** - Claude passes settings like `browser_options` at runtime
+2. **Environment Variables** - Optional overrides for advanced users
+3. **Hardcoded Defaults** - Sensible defaults that work for most users
+
+---
+
+## Tool Parameters (Runtime Configuration)
+
+Claude can control browser behavior via the `browser_options` parameter in tools like `ask_question`, `setup_auth`, and `re_auth`:
+
+```typescript
+browser_options: {
+  show: boolean,              // Show browser window (overrides headless)
+  headless: boolean,          // Run in headless mode (default: true)
+  timeout_ms: number,         // Browser timeout in ms (default: 30000)
+
+  stealth: {
+    enabled: boolean,         // Master switch (default: true)
+    random_delays: boolean,   // Random delays between actions (default: true)
+    human_typing: boolean,    // Human-like typing (default: true)
+    mouse_movements: boolean, // Realistic mouse movements (default: true)
+    typing_wpm_min: number,   // Min typing speed (default: 160)
+    typing_wpm_max: number,   // Max typing speed (default: 240)
+    delay_min_ms: number,     // Min delay between actions (default: 100)
+    delay_max_ms: number,     // Max delay between actions (default: 400)
+  },
+
+  viewport: {
+    width: number,            // Viewport width (default: 1024)
+    height: number,           // Viewport height (default: 768)
+  }
+}
+```
+
+**Example usage:**
+- "Research this and show me the browser" → Sets `show: true`
+- "Use slow typing for this query" → Adjusts typing WPM via stealth settings
+
+---
+
+## Environment Variables (Optional)
+
+For advanced users who want to set global defaults:
+- Auth
+  - `AUTO_LOGIN_ENABLED` — `true|false` (default `false`)
+  - `LOGIN_EMAIL`, `LOGIN_PASSWORD` — for auto‑login if enabled
+  - `AUTO_LOGIN_TIMEOUT_MS` (default `120000`)
+- Stealth / Human-like behavior
+  - `STEALTH_ENABLED` — `true|false` (default `true`) — Master switch for all stealth features
+  - `STEALTH_RANDOM_DELAYS` — `true|false` (default `true`)
+  - `STEALTH_HUMAN_TYPING` — `true|false` (default `true`)
+  - `STEALTH_MOUSE_MOVEMENTS` — `true|false` (default `true`)
+- Typing speed (human‑like)
+  - `TYPING_WPM_MIN` (default 160), `TYPING_WPM_MAX` (default 240)
+- Delays (human‑like)
+  - `MIN_DELAY_MS` (default 100), `MAX_DELAY_MS` (default 400)
+- Browser
+  - `HEADLESS` (default `true`), `BROWSER_TIMEOUT` (ms, default `30000`)
+- Sessions
+  - `MAX_SESSIONS` (default 10), `SESSION_TIMEOUT` (s, default 900)
+- Multi‑instance profile strategy
+  - `NOTEBOOK_PROFILE_STRATEGY` — `auto|single|isolated` (default `auto`)
+  - `NOTEBOOK_CLONE_PROFILE` — clone base profile into isolated dir (default `false`)
+- Cleanup (to prevent disk bloat)
+  - `NOTEBOOK_CLEANUP_ON_STARTUP` (default `true`)
+  - `NOTEBOOK_CLEANUP_ON_SHUTDOWN` (default `true`)
+  - `NOTEBOOK_INSTANCE_TTL_HOURS` (default `72`)
+  - `NOTEBOOK_INSTANCE_MAX_COUNT` (default `20`)
+- Library metadata (optional hints)
+  - `NOTEBOOK_DESCRIPTION`, `NOTEBOOK_TOPICS`, `NOTEBOOK_CONTENT_TYPES`, `NOTEBOOK_USE_CASES`
+  - `NOTEBOOK_URL` — optional; leave empty and manage notebooks via the library
+
+---
+
+## Storage Paths
+
+The server uses platform-specific paths via [env-paths](https://github.com/sindresorhus/env-paths)
+- **Linux**: `~/.local/share/notebooklm-mcp/`
+- **macOS**: `~/Library/Application Support/notebooklm-mcp/`
+- **Windows**: `%LOCALAPPDATA%\notebooklm-mcp\`
+
+**What's stored:**
+- `chrome_profile/` - Persistent Chrome browser profile with login session
+- `browser_state/` - Browser context state and cookies
+- `library.json` - Your notebook library with metadata
+- `chrome_profile_instances/` - Isolated Chrome profiles for concurrent sessions
+
+**No config.json file** - Configuration is purely via environment variables or tool parameters!
+

package/docs/tools.md

@@ -0,0 +1,34 @@
+## Tools
+
+### Core
+- `ask_question`
+  - Parameters: `question` (string, required), optional `session_id`, `notebook_id`, `notebook_url`, `show_browser`.
+  - Returns NotebookLM's answer plus the follow-up reminder.
+- `list_sessions`, `close_session`, `reset_session`
+  - Inspect or manage active browser sessions.
+- `get_health`
+  - Summaries auth status, active sessions, and configuration.
+- `setup_auth`
+  - Opens the persistent Chrome profile so you can log in manually.
+- `re_auth`
+  - Switch to a different Google account or re-authenticate.
+  - Use when NotebookLM rate limit is reached (50 queries/day for free accounts).
+  - Closes all sessions, clears auth data, and opens browser for fresh login.
+
+### Notebook library
+- `add_notebook` – Safe conversational add; expects confirmation before writing.
+- `list_notebooks` – Returns id, name, topics, URL, metadata for every entry.
+- `get_notebook` – Fetch a single notebook by id.
+- `select_notebook` – Set the active default notebook.
+- `update_notebook` – Modify metadata fields.
+- `remove_notebook` – Removes entries from the library (not the original NotebookLM notebook).
+- `search_notebooks` – Simple query across name/description/topics/tags.
+- `get_library_stats` – Aggregate statistics (total notebooks, usage counts, etc.).
+
+### Resources
+- `notebooklm://library`
+  - JSON representation of the full library: active notebook, stats, individual notebooks.
+- `notebooklm://library/{id}`
+  - Fetch metadata for a specific notebook. The `{id}` completion pulls from the library automatically.
+
+**Remember:** Every `ask_question` response ends with a reminder that nudges your agent to keep asking until the user’s task is fully addressed.

package/docs/troubleshooting.md

@@ -0,0 +1,59 @@
+## Troubleshooting
+
+### Fresh start / Deep cleanup
+If you're experiencing persistent issues, corrupted data, or want to start completely fresh:
+
+**⚠️ CRITICAL: Close ALL Chrome/Chromium instances before cleanup!** Open browsers can prevent cleanup and cause issues.
+
+**Recommended workflow:**
+1. Close all Chrome/Chromium windows and instances
+2. Ask: "Run NotebookLM cleanup and preserve my library"
+3. Review the preview - you'll see exactly what will be deleted
+4. Confirm deletion
+5. Re-authenticate: "Open NotebookLM auth setup"
+
+**What gets cleaned:**
+- Browser data, cache, Chrome profiles
+- Temporary files and logs
+- Old installation data
+- **Preserved:** Your notebook library (when using preserve option)
+
+**Useful for:**
+- Authentication problems
+- Browser session conflicts
+- Corrupted browser profiles
+- Clean reinstalls
+- Switching between accounts
+
+### Browser closed / `newPage` errors
+- Symptom: `browserContext.newPage: Target page/context/browser has been closed`.
+- Fix: The server auto‑recovers (recreates context and page). Re‑run the tool.
+
+### Profile lock / `ProcessSingleton` errors
+- Cause: Another Chrome is using the base profile.
+- Fix: `NOTEBOOK_PROFILE_STRATEGY=auto` (default) falls back to isolated per‑instance profiles; or set `isolated`.
+
+### Authentication issues
+**Quick fix:** Ask the agent to repair authentication; it will run `get_health` → `setup_auth` → `get_health`.
+
+**For persistent auth failures:**
+1. Close ALL Chrome/Chromium instances
+2. Ask: "Run NotebookLM cleanup with library preservation"
+3. After cleanup completes, ask: "Open NotebookLM auth setup"
+4. This creates a completely fresh browser session while keeping your notebooks
+
+**Auto-login (optional):**
+- Set `AUTO_LOGIN_ENABLED=true` with `LOGIN_EMAIL`, `LOGIN_PASSWORD` environment variables
+- For automation workflows only
+
+### Typing speed too slow/fast
+- Adjust `TYPING_WPM_MIN`/`MAX`; or disable stealth typing by setting `STEALTH_ENABLED=false`.
+
+### Rate limit reached
+- Symptom: "NotebookLM rate limit reached (50 queries/day for free accounts)".
+- Fix: Use `re_auth` tool to switch to a different Google account, or wait until tomorrow.
+- Upgrade: Google AI Pro/Ultra gives 5x higher limits.
+
+### No notebooks found
+- Ask to add the NotebookLM link you need.
+- Ask to list the stored notebooks, then choose the one to activate.