@pan-sec/notebooklm-mcp 2026.3.3 → 2026.4.0

package/dist/library/notebook-library.js

@@ -10,9 +10,22 @@
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
+import os from "os";
 import { CONFIG } from "../config.js";
 import { log } from "../utils/logger.js";
 import { writeFileSecure, PERMISSION_MODES } from "../utils/file-permissions.js";
+/**
+ * Maximum number of parent directories to walk when detecting a project.
+ * An attacker who controls the launch directory could otherwise force a very
+ * deep walk; bound it to fail safe to the global library. (M26)
+ */
+const MAX_PROJECT_WALK_DEPTH = 10;
+/**
+ * Maximum package.json size we are willing to read+parse during project
+ * detection. An attacker controlling the launch dir could drop a huge file to
+ * cause a memory spike; cap it and fail safe. (M26)
+ */
+const MAX_PACKAGE_JSON_BYTES = 1024 * 1024; // 1 MB
 /**
  * Detect project from current working directory
  */
@@ -33,10 +46,26 @@ function detectProject() {
     if (pkgRoot) {
         try {
             const pkgPath = path.join(pkgRoot, "package.json");
+            // Cap the file size before reading to avoid a memory spike from an
+            // attacker-controlled launch directory. (M26)
+            const stat = fs.statSync(pkgPath);
+            if (stat.size > MAX_PACKAGE_JSON_BYTES) {
+                log.debug(`notebook-library: package.json too large (${stat.size} bytes) — falling back to directory name`);
+                return {
+                    id: hashPath(pkgRoot),
+                    name: path.basename(pkgRoot),
+                    path: pkgRoot,
+                    type: "npm",
+                };
+            }
             const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            // Only trust pkg.name when it is actually a string. (M26)
+            const name = typeof pkg.name === "string" && pkg.name.length > 0
+                ? pkg.name
+                : path.basename(pkgRoot);
             return {
                 id: hashPath(pkgRoot),
-                name: pkg.name || path.basename(pkgRoot),
+                name,
                 path: pkgRoot,
                 type: "npm",
             };
@@ -61,7 +90,9 @@ function detectProject() {
 function findGitRoot(startPath) {
     let currentPath = startPath;
     const root = path.parse(currentPath).root;
-    while (currentPath !== root) {
+    // Bound the upward walk so an attacker-controlled launch dir can't force a
+    // deep traversal. (M26)
+    for (let depth = 0; depth < MAX_PROJECT_WALK_DEPTH && currentPath !== root; depth++) {
         const gitPath = path.join(currentPath, ".git");
         if (fs.existsSync(gitPath)) {
             return currentPath;
@@ -76,7 +107,9 @@ function findGitRoot(startPath) {
 function findPackageJson(startPath) {
     let currentPath = startPath;
     const root = path.parse(currentPath).root;
-    while (currentPath !== root) {
+    // Bound the upward walk so an attacker-controlled launch dir can't force a
+    // deep traversal. (M26)
+    for (let depth = 0; depth < MAX_PROJECT_WALK_DEPTH && currentPath !== root; depth++) {
         const pkgPath = path.join(currentPath, "package.json");
         if (fs.existsSync(pkgPath)) {
             return currentPath;
@@ -95,12 +128,152 @@ function hashPath(filePath) {
         .digest("hex")
         .substring(0, 12);
 }
+/**
+ * Synchronous advisory file lock.
+ *
+ * The library save path is fully synchronous (callers consume the returned
+ * NotebookEntry immediately), so the async withLock() in utils/file-lock.ts
+ * cannot be used here. This helper mirrors that utility's on-disk convention
+ * (a "<file>.lock" sentinel created with the exclusive "wx" flag, JSON body
+ * with pid/timestamp, stale-lock reclamation) so the two interoperate safely,
+ * but acquires the lock with a blocking spin instead of awaiting. (M25)
+ */
+const SYNC_LOCK_TIMEOUT_MS = 10000;
+const SYNC_LOCK_RETRY_MS = 25;
+const SYNC_LOCK_STALE_MS = 900000;
+function withLockSync(filePath, operation) {
+    const lockPath = filePath + ".lock";
+    const lockDir = path.dirname(lockPath);
+    if (!fs.existsSync(lockDir)) {
+        fs.mkdirSync(lockDir, { recursive: true, mode: 0o700 });
+    }
+    const lockBody = JSON.stringify({
+        pid: process.pid,
+        timestamp: Date.now(),
+        hostname: os.hostname(),
+    });
+    const start = Date.now();
+    let acquired = false;
+    while (Date.now() - start < SYNC_LOCK_TIMEOUT_MS) {
+        try {
+            // Reclaim a stale lock left behind by a crashed process.
+            if (fs.existsSync(lockPath)) {
+                try {
+                    const existing = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+                    const age = Date.now() - (existing.timestamp ?? 0);
+                    if (age > SYNC_LOCK_STALE_MS) {
+                        log.warning(`🔓 Removing stale library lock (age: ${Math.round(age / 1000)}s)`);
+                        fs.unlinkSync(lockPath);
+                    }
+                }
+                catch {
+                    // Corrupt lock file — remove it so we can make progress.
+                    try {
+                        fs.unlinkSync(lockPath);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            fs.writeFileSync(lockPath, lockBody, { flag: "wx", mode: 0o600 });
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "EEXIST") {
+                throw error;
+            }
+            // Lock held by another process; sleep briefly (no CPU spin) and retry.
+            sleepSync(SYNC_LOCK_RETRY_MS);
+        }
+    }
+    if (!acquired) {
+        throw new Error(`Could not acquire library lock for ${filePath} within timeout`);
+    }
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            if (fs.existsSync(lockPath)) {
+                const owner = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+                if (owner.pid === process.pid) {
+                    fs.unlinkSync(lockPath);
+                }
+            }
+        }
+        catch (err) {
+            log.debug(`notebook-library: releasing library lock: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Deep-clone a Library so that mutations to the copy never alias the original
+ * (the previous {...library} shallow copy shared the notebooks array, so a
+ * failed write could leave this.library mutated-but-unpersisted). (M25)
+ */
+function cloneLibrary(library) {
+    return {
+        ...library,
+        notebooks: library.notebooks.map((n) => ({
+            ...n,
+            topics: [...n.topics],
+            content_types: [...n.content_types],
+            use_cases: [...n.use_cases],
+            tags: n.tags ? [...n.tags] : n.tags,
+        })),
+    };
+}
+/**
+ * Block the current thread for `ms` without busy-spinning a CPU core.
+ * Uses Atomics.wait on a throwaway SharedArrayBuffer; the wait always times out
+ * (no one ever notifies index 0). Only hit on the contended retry path. (M25)
+ */
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_BUFFER, 0, 0, ms);
+}
+const SLEEP_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Module-level shutdown registry. (M25)
+ *
+ * Each NotebookLibrary instance registers itself here; a single set of
+ * process listeners (one per signal) flushes every live instance on shutdown.
+ * This avoids 3×N process listeners (and the MaxListeners warning) and shrinks
+ * the surface that overrides Node's default signal handling. The flush is
+ * flush-only — src/index.ts owns the actual SIGINT/SIGTERM exit. (M25)
+ */
+const LIVE_LIBRARIES = new Set();
+let shutdownHooksInstalled = false;
+function flushAllLibraries() {
+    for (const lib of LIVE_LIBRARIES) {
+        try {
+            lib.flushSave();
+        }
+        catch (err) {
+            log.debug(`notebook-library: shutdown flush failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function registerForShutdownFlush(lib) {
+    LIVE_LIBRARIES.add(lib);
+    if (!shutdownHooksInstalled) {
+        shutdownHooksInstalled = true;
+        process.once("SIGTERM", flushAllLibraries);
+        process.once("SIGINT", flushAllLibraries);
+        process.once("beforeExit", flushAllLibraries);
+    }
+}
+function unregisterFromShutdownFlush(lib) {
+    LIVE_LIBRARIES.delete(lib);
+}
 export class NotebookLibrary {
     libraryPath;
     library;
     projectInfo;
     useProjectLibrary;
     saveTimer = null;
+    /** Pending use-count deltas keyed by notebook id, flushed by the debounced save. (M25) */
+    pendingUseCounts = new Map();
     constructor(options) {
         // Determine if we should use per-project libraries
         this.useProjectLibrary = options?.useProjectLibrary ?? false;
@@ -131,6 +304,9 @@ export class NotebookLibrary {
             fs.mkdirSync(libraryDir, { recursive: true, mode: 0o700 });
         }
         this.library = this.loadLibrary();
+        // Flush any pending (debounced) use-count updates synchronously on shutdown
+        // so they aren't lost when the process exits within the debounce window. (M25)
+        registerForShutdownFlush(this);
         log.info("📚 NotebookLibrary initialized");
         log.info(`  Library path: ${this.libraryPath}`);
         log.info(`  Notebooks: ${this.library.notebooks.length}`);
@@ -236,9 +412,45 @@ export class NotebookLibrary {
         }
     }
     /**
-     * Generate a unique ID from a string (slug format)
+     * Read the library file from disk without mutating in-memory state.
+     * Used inside the lock to pick up changes made by concurrent sessions. (M25)
      */
-    generateId(name) {
+    readLibraryFromDisk() {
+        try {
+            if (fs.existsSync(this.libraryPath)) {
+                const data = fs.readFileSync(this.libraryPath, "utf-8");
+                return JSON.parse(data);
+            }
+        }
+        catch (error) {
+            log.warning(`  ⚠️  Failed to reload library from disk: ${error}`);
+        }
+        // Fall back to a deep copy of the in-memory library if the file is gone.
+        return cloneLibrary(this.library);
+    }
+    /**
+     * Atomically apply a read-modify-write to the library file.
+     *
+     * Holds a cross-process lock, reloads the latest library from disk (so a
+     * concurrent session's notebooks aren't clobbered), applies `mutate` to a
+     * deep copy, persists it, and only then commits it to this.library. If the
+     * write throws, this.library is left untouched. (M25)
+     */
+    mutateLibrary(mutate) {
+        return withLockSync(this.libraryPath, () => {
+            const working = cloneLibrary(this.readLibraryFromDisk());
+            const result = mutate(working);
+            this.saveLibrary(working);
+            return result;
+        });
+    }
+    /**
+     * Generate a unique ID from a string (slug format).
+     * Uniqueness is checked against the supplied library (defaults to the
+     * in-memory one) so callers inside mutateLibrary can de-dupe against the
+     * freshly-reloaded disk state. (M25)
+     */
+    generateId(name, library = this.library) {
         const base = name
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, "-")
@@ -247,7 +459,7 @@ export class NotebookLibrary {
         // Ensure uniqueness
         let id = base;
         let counter = 1;
-        while (this.library.notebooks.some((n) => n.id === id)) {
+        while (library.notebooks.some((n) => n.id === id)) {
             id = `${base}-${counter}`;
             counter++;
         }
@@ -258,35 +470,36 @@ export class NotebookLibrary {
      */
     addNotebook(input) {
         log.info(`📝 Adding notebook: ${input.name}`);
-        // Generate ID
-        const id = this.generateId(input.name);
-        // Create entry
-        const notebook = {
-            id,
-            url: input.url,
-            name: input.name,
-            description: input.description,
-            topics: input.topics,
-            content_types: input.content_types || ["documentation", "examples"],
-            use_cases: input.use_cases || [
-                `Learning about ${input.name}`,
-                `Implementing features with ${input.name}`,
-            ],
-            added_at: new Date().toISOString(),
-            last_used: new Date().toISOString(),
-            use_count: 0,
-            tags: input.tags || [],
-        };
-        // Add to library
-        const updated = { ...this.library };
-        updated.notebooks.push(notebook);
-        // Set as active if it's the first notebook
-        if (updated.notebooks.length === 1) {
-            updated.active_notebook_id = id;
-        }
-        this.saveLibrary(updated);
-        log.success(`✅ Notebook added: ${id}`);
-        return notebook;
+        // Locked read-modify-write against the latest on-disk library so a
+        // concurrent session's notebooks are preserved. (M25)
+        return this.mutateLibrary((library) => {
+            // Generate ID unique within the freshly-reloaded library.
+            const id = this.generateId(input.name, library);
+            // Create entry
+            const notebook = {
+                id,
+                url: input.url,
+                name: input.name,
+                description: input.description,
+                topics: input.topics,
+                content_types: input.content_types || ["documentation", "examples"],
+                use_cases: input.use_cases || [
+                    `Learning about ${input.name}`,
+                    `Implementing features with ${input.name}`,
+                ],
+                added_at: new Date().toISOString(),
+                last_used: new Date().toISOString(),
+                use_count: 0,
+                tags: input.tags || [],
+            };
+            library.notebooks.push(notebook);
+            // Set as active if it's the first notebook
+            if (library.notebooks.length === 1) {
+                library.active_notebook_id = id;
+            }
+            log.success(`✅ Notebook added: ${id}`);
+            return notebook;
+        });
     }
     /**
      * List all notebooks in library
@@ -313,67 +526,67 @@ export class NotebookLibrary {
      * Select a notebook as active
      */
     selectNotebook(id) {
-        const notebook = this.getNotebook(id);
-        if (!notebook) {
-            throw new Error(`Notebook not found: ${id}`);
-        }
         log.info(`🎯 Selecting notebook: ${id}`);
-        const updated = { ...this.library };
-        updated.active_notebook_id = id;
-        // Update last_used
-        const notebookIndex = updated.notebooks.findIndex((n) => n.id === id);
-        updated.notebooks[notebookIndex] = {
-            ...notebook,
-            last_used: new Date().toISOString(),
-        };
-        this.saveLibrary(updated);
-        log.success(`✅ Active notebook: ${id}`);
-        return updated.notebooks[notebookIndex];
+        // Locked read-modify-write against the latest on-disk library. (M25)
+        return this.mutateLibrary((library) => {
+            const notebookIndex = library.notebooks.findIndex((n) => n.id === id);
+            if (notebookIndex === -1) {
+                throw new Error(`Notebook not found: ${id}`);
+            }
+            library.active_notebook_id = id;
+            library.notebooks[notebookIndex] = {
+                ...library.notebooks[notebookIndex],
+                last_used: new Date().toISOString(),
+            };
+            log.success(`✅ Active notebook: ${id}`);
+            return library.notebooks[notebookIndex];
+        });
     }
     /**
      * Update notebook metadata
      */
     updateNotebook(input) {
-        const notebook = this.getNotebook(input.id);
-        if (!notebook) {
-            throw new Error(`Notebook not found: ${input.id}`);
-        }
         log.info(`📝 Updating notebook: ${input.id}`);
-        const updated = { ...this.library };
-        const index = updated.notebooks.findIndex((n) => n.id === input.id);
-        updated.notebooks[index] = {
-            ...notebook,
-            ...(input.name && { name: input.name }),
-            ...(input.description && { description: input.description }),
-            ...(input.topics && { topics: input.topics }),
-            ...(input.content_types && { content_types: input.content_types }),
-            ...(input.use_cases && { use_cases: input.use_cases }),
-            ...(input.tags && { tags: input.tags }),
-            ...(input.url && { url: input.url }),
-        };
-        this.saveLibrary(updated);
-        log.success(`✅ Notebook updated: ${input.id}`);
-        return updated.notebooks[index];
+        // Locked read-modify-write against the latest on-disk library. (M25)
+        return this.mutateLibrary((library) => {
+            const index = library.notebooks.findIndex((n) => n.id === input.id);
+            if (index === -1) {
+                throw new Error(`Notebook not found: ${input.id}`);
+            }
+            library.notebooks[index] = {
+                ...library.notebooks[index],
+                ...(input.name && { name: input.name }),
+                ...(input.description && { description: input.description }),
+                ...(input.topics && { topics: input.topics }),
+                ...(input.content_types && { content_types: input.content_types }),
+                ...(input.use_cases && { use_cases: input.use_cases }),
+                ...(input.tags && { tags: input.tags }),
+                ...(input.url && { url: input.url }),
+            };
+            log.success(`✅ Notebook updated: ${input.id}`);
+            return library.notebooks[index];
+        });
     }
     /**
      * Remove notebook from library
      */
     removeNotebook(id) {
-        const notebook = this.getNotebook(id);
-        if (!notebook) {
-            return false;
-        }
         log.info(`🗑️  Removing notebook: ${id}`);
-        const updated = { ...this.library };
-        updated.notebooks = updated.notebooks.filter((n) => n.id !== id);
-        // If we removed the active notebook, select another one
-        if (updated.active_notebook_id === id) {
-            updated.active_notebook_id =
-                updated.notebooks.length > 0 ? updated.notebooks[0].id : null;
-        }
-        this.saveLibrary(updated);
-        log.success(`✅ Notebook removed: ${id}`);
-        return true;
+        // Locked read-modify-write against the latest on-disk library. (M25)
+        return this.mutateLibrary((library) => {
+            const exists = library.notebooks.some((n) => n.id === id);
+            if (!exists) {
+                return false;
+            }
+            library.notebooks = library.notebooks.filter((n) => n.id !== id);
+            // If we removed the active notebook, select another one
+            if (library.active_notebook_id === id) {
+                library.active_notebook_id =
+                    library.notebooks.length > 0 ? library.notebooks[0].id : null;
+            }
+            log.success(`✅ Notebook removed: ${id}`);
+            return true;
+        });
     }
     /**
      * Increment use count for a notebook
@@ -390,6 +603,9 @@ export class NotebookLibrary {
             last_used: new Date().toISOString(),
         };
         this.library.notebooks[notebookIndex] = updatedNotebook;
+        // Track the delta so the debounced flush can re-apply it additively to the
+        // latest on-disk state instead of clobbering concurrent sessions. (M25)
+        this.pendingUseCounts.set(id, (this.pendingUseCounts.get(id) ?? 0) + 1);
         this.debouncedSave();
         return updatedNotebook;
     }
@@ -401,10 +617,55 @@ export class NotebookLibrary {
             return;
         this.saveTimer = setTimeout(() => {
             this.saveTimer = null;
-            this.saveLibrary(this.library);
+            this.flushSave();
         }, 5000);
         this.saveTimer.unref();
     }
+    /**
+     * Synchronously flush any pending debounced use-count updates to disk under
+     * the cross-process lock, re-applying the accumulated deltas to the latest
+     * on-disk library so concurrent sessions' notebooks and counts survive. (M25)
+     */
+    flushSave() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.pendingUseCounts.size === 0) {
+            return;
+        }
+        const deltas = new Map(this.pendingUseCounts);
+        this.pendingUseCounts.clear();
+        try {
+            this.mutateLibrary((library) => {
+                const now = new Date().toISOString();
+                for (const [id, delta] of deltas) {
+                    const idx = library.notebooks.findIndex((n) => n.id === id);
+                    if (idx === -1)
+                        continue;
+                    library.notebooks[idx] = {
+                        ...library.notebooks[idx],
+                        use_count: library.notebooks[idx].use_count + delta,
+                        last_used: now,
+                    };
+                }
+            });
+        }
+        catch (error) {
+            // Restore the deltas so a later flush can retry rather than lose them. (M25)
+            for (const [id, delta] of deltas) {
+                this.pendingUseCounts.set(id, (this.pendingUseCounts.get(id) ?? 0) + delta);
+            }
+            log.error(`  ❌ Failed to flush library use-count updates: ${error}`);
+        }
+    }
+    /**
+     * Release resources: flush pending writes and detach shutdown handlers. (M25)
+     */
+    close() {
+        this.flushSave();
+        unregisterFromShutdownFlush(this);
+    }
     /**
      * Get library statistics
      */
@@ -430,4 +691,3 @@ export class NotebookLibrary {
             n.tags?.some((t) => t.toLowerCase().includes(lowerQuery)));
     }
 }
-//# sourceMappingURL=notebook-library.js.map

package/dist/library/types.d.ts

@@ -79,4 +79,3 @@ export interface ProjectInfo {
 export interface ProjectLibrary extends Library {
     project?: ProjectInfo;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/library/types.js

@@ -5,4 +5,3 @@
  * in a persistent library that Claude can manage autonomously.
  */
 export {};
-//# sourceMappingURL=types.js.map

package/dist/logging/index.d.ts

@@ -4,4 +4,3 @@
  * Query logging for NotebookLM MCP Server
  */
 export { QueryLogger, getQueryLogger, logQuery, type QueryLogEntry, type QueryLoggerConfig, type QuerySearchOptions, } from "./query-logger.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -4,4 +4,3 @@
  * Query logging for NotebookLM MCP Server
  */
 export { QueryLogger, getQueryLogger, logQuery, } from "./query-logger.js";
-//# sourceMappingURL=index.js.map

package/dist/logging/query-logger.d.ts

@@ -69,6 +69,19 @@ export declare class QueryLogger {
      * severity so we don't redact legitimate base64 payloads (images, PDFs,
      * JWT payloads) that frequently appear in NotebookLM answers. Real
      * credentials live at critical/high/medium severity.
+     *
+     * ACCEPTED RISK (L11): the only `severity: "low"` rule in the scanner is the
+     * "High Entropy String" pattern (/\b[A-Za-z0-9+/]{32,}={0,2}\b/, see
+     * secrets-scanner.ts). It is DELIBERATELY NOT redacted at rest because
+     * NotebookLM answers routinely contain long, high-entropy base64 that is NOT
+     * a secret — inline image/PDF data-URIs, JWT payload segments, GCS object
+     * names, CSRF tokens, document hashes. Redacting at "low" would shred this
+     * legitimate research content (high false-positive rate) for marginal gain:
+     * genuine credentials (API keys, bearer tokens, private keys, connection
+     * strings) already match dedicated critical/high/medium rules and are
+     * redacted regardless. The base64 false-positive cost outweighs the residual
+     * risk of an unstructured low-confidence entropy hit slipping through, so the
+     * threshold stays at "medium" by design.
      */
     private scanner;
     private stats;
@@ -89,6 +102,13 @@ export declare class QueryLogger {
      * Write entry to log file
      */
     private writeEntry;
+    /**
+     * Determine the next sequence-suffixed log file for `date` when the base file (or a
+     * prior rotation) has hit the size cap (M9). Scans the directory for the highest
+     * existing query-log-DATE.NNN.jsonl suffix and returns the next one, so rotation is
+     * correct across writers and restarts rather than relying on a per-process counter.
+     */
+    private nextRotatedFile;
     /**
      * Log a query (Q&A pair).
      *
@@ -158,4 +178,3 @@ export declare function getQueryLogger(): QueryLogger;
  * Convenience function for quick query logging
  */
 export declare function logQuery(entry: Omit<QueryLogEntry, "timestamp" | "queryId">): Promise<string>;
-//# sourceMappingURL=query-logger.d.ts.map