db-mcp 1.1.0 → 2.0.0

package/dist/{http-VSB7DBJR.js → http-6KF4ULDI.js}

@@ -1,5 +1,6 @@
-import './chunk-4IA3DB5C.js';
-import { createModuleLogger, DbMcpError, ERROR_CODES } from './chunk-AOUL5SHS.js';
+import { runWithAuthContext, SUPPORTED_SCOPES, scopesGrantToolAccess, BASE_SCOPES, SCOPE_PATTERNS, parseScopes } from './chunk-SFJQCNG7.js';
+import './chunk-X3MUUOWM.js';
+import { createModuleLogger, DbMcpError, ERROR_CODES } from './chunk-645ZEFLA.js';
 import express from 'express';
 import { localhostHostValidation } from '@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js';
 import cors from 'cors';
@@ -88,6 +89,20 @@ var InvalidSignatureError = class extends OAuthError {
     this.name = "InvalidSignatureError";
   }
 };
+var InsufficientScopeError = class extends OAuthError {
+  constructor(requiredScope, providedScopes) {
+    const required = Array.isArray(requiredScope) ? requiredScope : [requiredScope];
+    const scopeValue = required.join(" ");
+    super(
+      `Insufficient scope. Required: ${scopeValue}`,
+      ERROR_CODES.AUTH.SCOPE_DENIED.full,
+      403,
+      { requiredScope: required, providedScopes },
+      `Bearer error="insufficient_scope", scope="${scopeValue}"`
+    );
+    this.name = "InsufficientScopeError";
+  }
+};
 var AuthServerDiscoveryError = class extends OAuthError {
   constructor(serverUrl, cause) {
     super(
@@ -120,60 +135,6 @@ function isOAuthError(error) {
   return error instanceof OAuthError;
 }
 
-// src/auth/scopes/constants.ts
-var SCOPES = {
-  /** Read-only access to all databases */
-  READ: "read",
-  /** Read and write access to all databases */
-  WRITE: "write",
-  /** Administrative access */
-  ADMIN: "admin"};
-var BASE_SCOPES = ["read", "write", "admin", "full"];
-var SCOPE_PATTERNS = {
-  /** Database-specific access pattern */
-  DATABASE: /^db:([a-zA-Z0-9_-]+)$/,
-  /** Table-specific access pattern */
-  TABLE: /^table:([a-zA-Z0-9_-]+):([a-zA-Z0-9_-]+)$/
-};
-var SUPPORTED_SCOPES = [
-  "read",
-  "write",
-  "admin",
-  "full",
-  "db:{database}",
-  "table:{database}:{table}"
-];
-function parseScopes(scopeString) {
-  return scopeString.split(/\s+/).map((s) => s.trim()).filter((s) => s.length > 0);
-}
-
-// src/auth/scopes/mapping.ts
-var TOOL_GROUP_SCOPES = {
-  core: SCOPES.READ,
-  json: SCOPES.READ,
-  text: SCOPES.READ,
-  stats: SCOPES.READ,
-  vector: SCOPES.READ,
-  geo: SCOPES.READ,
-  introspection: SCOPES.READ,
-  migration: SCOPES.WRITE,
-  admin: SCOPES.ADMIN,
-  codemode: SCOPES.ADMIN
-};
-var groupsForScope = (maxScope) => {
-  const hierarchy = {
-    read: 0,
-    write: 1,
-    admin: 2,
-    full: 3
-  };
-  const maxLevel = hierarchy[maxScope];
-  return Object.entries(TOOL_GROUP_SCOPES).filter(([, scope]) => hierarchy[scope] <= maxLevel).map(([group]) => group);
-};
-groupsForScope(SCOPES.READ);
-groupsForScope(SCOPES.WRITE);
-groupsForScope(SCOPES.ADMIN);
-
 // src/auth/middleware/express-auth.ts
 var logger = createModuleLogger("AUTH");
 function isPublicPath(path, publicPaths) {
@@ -412,6 +373,30 @@ function asServerResponse(res) {
 
 // src/transports/http/session.ts
 var logger3 = createModuleLogger("HTTP");
+var Mutex = class {
+  queue = [];
+  locked = false;
+  async acquire() {
+    return new Promise((resolve) => {
+      const lock = () => {
+        this.locked = true;
+        resolve(() => {
+          this.locked = false;
+          if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            next?.();
+          }
+        });
+      };
+      if (this.locked) {
+        this.queue.push(lock);
+      } else {
+        lock();
+      }
+    });
+  }
+};
+var connectionMutex = new Mutex();
 async function setupStatelessEndpoints(state) {
   if (!state.app || !state.mcpServer) {
     throw new DbMcpError(
@@ -514,16 +499,47 @@ function setupStatefulEndpoints(state) {
               state.transports.delete(sid);
             }
           };
-          try {
-            await server.connect(
-              newTransport
-            );
-          } catch {
-            await server.close();
-            await server.connect(
-              newTransport
-            );
-          }
+          await connectionMutex.acquire().then(async (release) => {
+            try {
+              if (server.server.transport) {
+                const oldTransport = server.server.transport;
+                logger3.info("Captured oldTransport in /mcp", {
+                  hasOldTransport: oldTransport !== void 0,
+                  hasOnclose: oldTransport.onclose !== void 0
+                });
+                try {
+                  await Promise.race([
+                    server.close(),
+                    new Promise(
+                      (_, reject) => setTimeout(
+                        () => reject(new Error("server.close timeout")),
+                        2e3
+                      )
+                    )
+                  ]);
+                  logger3.info("server.close() succeeded in /mcp");
+                } catch (closeErr) {
+                  logger3.error("server.close() failed or timed out in /mcp", {
+                    error: closeErr instanceof Error ? closeErr : new Error(String(closeErr))
+                  });
+                }
+                if (server.server.transport === oldTransport && oldTransport.onclose !== void 0) {
+                  logger3.info(
+                    "Manually invoking oldTransport.onclose() to clear Protocol state in /mcp"
+                  );
+                  oldTransport.onclose();
+                }
+                delete oldTransport.onclose;
+              }
+              logger3.info("Attempting server.connect(newTransport)");
+              await server.connect(
+                newTransport
+              );
+              logger3.info("server.connect succeeded in /mcp");
+            } finally {
+              release();
+            }
+          });
           await newTransport.handleRequest(
             asIncoming(req),
             asServerResponse(res),
@@ -622,16 +638,59 @@ function setupLegacySSEEndpoints(state) {
           });
           state.sseTransports.delete(sseTransport.sessionId);
         };
-        try {
-          await server.connect(
-            sseTransport
-          );
-        } catch {
-          await server.close();
-          await server.connect(
-            sseTransport
-          );
-        }
+        const origSend = sseTransport.send.bind(sseTransport);
+        sseTransport.send = async (message) => {
+          try {
+            logger3.info("SSE SEND", {
+              sessionId: sseTransport.sessionId,
+              msg: JSON.stringify(message).substring(0, 1e3)
+            });
+          } catch (e) {
+            logger3.error("SSE SEND Stringify Error", {
+              error: e instanceof Error ? e : new Error(String(e))
+            });
+          }
+          return origSend(message);
+        };
+        await connectionMutex.acquire().then(async (release) => {
+          try {
+            if (server.server.transport) {
+              const oldTransport = server.server.transport;
+              logger3.info("Captured oldTransport", {
+                hasOldTransport: oldTransport !== void 0,
+                hasOnclose: oldTransport.onclose !== void 0
+              });
+              try {
+                await Promise.race([
+                  server.close(),
+                  new Promise(
+                    (_, reject) => setTimeout(
+                      () => reject(new Error("server.close timeout")),
+                      2e3
+                    )
+                  )
+                ]);
+                logger3.info("server.close() succeeded");
+              } catch (closeErr) {
+                logger3.error("server.close() failed or timed out", {
+                  error: closeErr instanceof Error ? closeErr : new Error(String(closeErr))
+                });
+              }
+              if (server.server.transport === oldTransport && oldTransport.onclose !== void 0) {
+                logger3.info(
+                  "Manually invoking oldTransport.onclose() to clear Protocol state"
+                );
+                oldTransport.onclose();
+              }
+              delete oldTransport.onclose;
+            }
+            logger3.info("Attempting server.connect(sseTransport)");
+            await server.connect(sseTransport);
+            logger3.info("server.connect succeeded");
+          } finally {
+            release();
+          }
+        });
       } catch (error) {
         logger3.error("Error starting SSE transport", {
           code: ERROR_CODES.SERVER.TRANSPORT_ERROR.full,
@@ -675,7 +734,13 @@ function setupLegacySSEEndpoints(state) {
       asIncoming(req),
       asServerResponse(res),
       req.body
-    );
+    ).then(() => {
+      logger3.info("handlePostMessage completed", { sessionId });
+    }).catch((e) => {
+      logger3.error("handlePostMessage error", {
+        error: e instanceof Error ? e : new Error(String(e))
+      });
+    });
   });
 }
 
@@ -1256,6 +1321,48 @@ function createSimpleBearerAuth(expectedToken) {
     next();
   };
 }
+function applyScopeEnforcementMiddleware(state) {
+  if (!state.app) return;
+  state.app.use((req, res, next) => {
+    const body = req.body;
+    if (req.method !== "POST" || body?.method !== "tools/call") {
+      next();
+      return;
+    }
+    const toolName = body.params?.name;
+    if (!toolName) {
+      next();
+      return;
+    }
+    if (!req.auth) {
+      next();
+      return;
+    }
+    const hasAccess = scopesGrantToolAccess(req.auth.scopes, toolName);
+    if (!hasAccess) {
+      const error = new InsufficientScopeError(
+        `Tool access: ${toolName}`,
+        req.auth.scopes
+      );
+      logger7.warning(`Insufficient scope for tool: ${toolName}`, {
+        code: ERROR_CODES.AUTH.SCOPE_DENIED.full,
+        toolName,
+        providedScopes: req.auth.scopes
+      });
+      res.status(error.httpStatus);
+      if (error.wwwAuthenticate) {
+        res.setHeader("WWW-Authenticate", error.wwwAuthenticate);
+      }
+      res.json({
+        error: "insufficient_scope",
+        error_description: `Access to tool '${toolName}' denied`,
+        tool: toolName
+      });
+      return;
+    }
+    next();
+  });
+}
 async function setupOAuth(state, resourceUri) {
   logger7.info("Setting up OAuth 2.1...", { code: "HTTP_OAUTH_SETUP" });
   state.resourceServer = new OAuthResourceServer({
@@ -1382,6 +1489,21 @@ var HttpTransport = class {
       });
     });
     applyAuthMiddleware(this.state);
+    applyScopeEnforcementMiddleware(this.state);
+    this.state.app.use((req, _res, next) => {
+      if (req.auth) {
+        const authCtx = {
+          authenticated: true,
+          claims: req.auth,
+          scopes: req.auth.scopes
+        };
+        runWithAuthContext(authCtx, () => {
+          next();
+        });
+      } else {
+        next();
+      }
+    });
     if (this.state.config.stateless) {
       await setupStatelessEndpoints(this.state);
     } else {

package/dist/index.d.ts

@@ -174,6 +174,67 @@ interface RequestContext {
     progressToken?: string | number;
 }
 
+/** Audit log configuration */
+interface AuditConfig {
+    /** Master switch — false means no interceptor is created */
+    enabled: boolean;
+    /** Absolute path to the JSONL output file */
+    logPath: string;
+    /** When true, tool arguments are omitted from entries */
+    redact: boolean;
+    /** When true, read-scoped tools are also logged (default: false) */
+    auditReads: boolean;
+    /** Maximum log file size in bytes before rotation (default: 10MB). 0 = no rotation. */
+    maxSizeBytes: number;
+    /** Pre-mutation backup configuration (optional — backup disabled when absent). */
+    backup?: BackupConfig | undefined;
+}
+/** Pre-mutation backup configuration */
+interface BackupConfig {
+    /** Enable pre-mutation snapshots */
+    enabled: boolean;
+    /** Include sample data rows in snapshots (default: schema-only) */
+    includeData: boolean;
+    /** Maximum snapshot age in days before cleanup (default: 30) */
+    maxAgeDays: number;
+    /** Maximum number of snapshots to retain (default: 1000) */
+    maxCount: number;
+    /** Maximum table size in bytes for data capture (default: 50MB). Tables exceeding this get DDL-only snapshots. */
+    maxDataSizeBytes: number;
+}
+/** Snapshot metadata stored alongside the DDL capture */
+interface SnapshotMetadata {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Tool that triggered the snapshot */
+    tool: string;
+    /** Target object (table, index, view) */
+    target: string;
+    /** Snapshot type: ddl-only or ddl+data */
+    type: "ddl" | "ddl+data";
+    /** Original audit requestId for correlation */
+    requestId: string;
+    /** Size of snapshot file in bytes */
+    sizeBytes: number;
+    /** Snapshot filename (populated by listSnapshots for getSnapshot lookup) */
+    filename?: string;
+    /** Approximate row count at snapshot time */
+    rowCount?: number;
+    /** Whether data capture was skipped due to size exceeding threshold */
+    dataSkipped?: boolean;
+    /** Reason data capture was skipped */
+    dataSkippedReason?: string;
+}
+/** Stored snapshot file content */
+interface SnapshotContent {
+    /** Snapshot metadata */
+    metadata: SnapshotMetadata;
+    /** CREATE TABLE / CREATE INDEX / CREATE VIEW DDL from sqlite_master */
+    ddl: string;
+    /** Optional INSERT statements for sample data */
+    data?: string | undefined;
+}
+
 /**
  * db-mcp — MCP Server Types
  *
@@ -214,6 +275,8 @@ interface McpServerConfig {
      */
     statelessHttp?: boolean;
     enableHSTS?: boolean;
+    /** Audit logging configuration */
+    audit?: AuditConfig;
 }
 
 /**
@@ -224,7 +287,7 @@ interface McpServerConfig {
 /**
  * Tool group identifiers
  */
-type ToolGroup = "core" | "json" | "text" | "stats" | "vector" | "admin" | "geo" | "introspection" | "migration" | "codemode";
+type ToolGroup = "core" | "json" | "text" | "stats" | "vector" | "admin" | "transactions" | "geo" | "introspection" | "migration" | "codemode";
 /**
  * Meta-group identifiers for common multi-group selections.
  * These are shortcuts that expand to multiple ToolGroups.
@@ -328,7 +391,7 @@ interface ToolDefinition {
     /** Tool group for filtering */
     group: ToolGroup;
     /** Zod schema for input validation */
-    inputSchema: unknown;
+    inputSchema?: unknown;
     /** Zod schema for output validation (MCP 2025-11-25) */
     outputSchema?: unknown;
     /** Required OAuth scopes */
@@ -524,6 +587,134 @@ declare class AuthorizationError extends DbMcpError {
     });
 }
 
+/**
+ * db-mcp — Backup Manager
+ *
+ * Pre-mutation snapshot capture for the audit trail.
+ * Creates DDL snapshots (+ optional data) of database objects
+ * before write/admin tools modify them. Snapshots are stored
+ * as gzip-compressed JSON files in a `snapshots/` directory
+ * alongside the audit log.
+ *
+ * DDL is captured from sqlite_master (`SELECT sql FROM sqlite_master`).
+ * Volume metadata uses `COUNT(*)` and page-count pragmas.
+ *
+ * Non-throwing by design: snapshot failures log to stderr
+ * but never block tool execution.
+ */
+
+/**
+ * Interface for database queries needed by the backup manager.
+ * Avoids circular imports from the full adapter.
+ */
+interface SnapshotQueryAdapter {
+    executeQuery(sql: string, params?: unknown[]): Promise<{
+        rows?: Record<string, unknown>[];
+    }>;
+}
+declare class BackupManager {
+    readonly config: BackupConfig;
+    private readonly snapshotDir;
+    private dirEnsured;
+    private readonly pendingWrites;
+    constructor(config: BackupConfig, auditLogPath: string);
+    /**
+     * Check if a tool should receive a pre-mutation snapshot.
+     */
+    shouldSnapshot(toolName: string): boolean;
+    /**
+     * Create a pre-mutation snapshot of the target object.
+     *
+     * @returns Relative path to the snapshot file, or undefined if skipped/failed
+     */
+    createSnapshot(toolName: string, args: Record<string, unknown>, requestId: string, adapter: SnapshotQueryAdapter, logAs?: string): Promise<string | undefined>;
+    /**
+     * List available snapshots with metadata.
+     */
+    listSnapshots(): Promise<SnapshotMetadata[]>;
+    /**
+     * Read a specific snapshot by filename.
+     */
+    getSnapshot(filename: string): Promise<SnapshotContent | null>;
+    /**
+     * Apply retention policy — delete oldest snapshots that exceed limits.
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Flush all pending async snapshot writes.
+     * Call during graceful shutdown to ensure all snapshots are persisted.
+     */
+    flush(): Promise<void>;
+    getStats(): Promise<{
+        count: number;
+        oldestAge?: string;
+        totalSizeKB: number;
+    }>;
+    private captureObjectSnapshot;
+    /**
+     * Build a DDL string from sqlite_master for the given object.
+     * Works for tables, views, indexes, and triggers.
+     */
+    private buildDdl;
+    /**
+     * Capture row count using COUNT(*).
+     * Near-zero cost for small tables; failures are silently ignored (best-effort).
+     */
+    private captureVolumeMetadata;
+    /**
+     * Capture row data as INSERT statements, subject to config limits.
+     * Returns empty output when `includeData` is disabled.
+     */
+    private captureTableData;
+    private writeSnapshot;
+    /**
+     * Read and decompress a snapshot file (supports both gzip and legacy JSON).
+     */
+    private readSnapshotFile;
+    private ensureDirectory;
+}
+
+/**
+ * db-mcp — Audit Interceptor
+ *
+ * Wraps tool execution to produce audit entries for all tool
+ * invocations. Write/admin tools are always logged; read-scoped
+ * tools are logged only when `--audit-reads` is enabled.
+ *
+ * Each entry includes a `tokenEstimate` (~4 bytes per token)
+ * computed from the serialized result size.
+ *
+ * When a BackupManager is provided, captures pre-mutation
+ * snapshots of target objects before destructive tool execution.
+ *
+ * The interceptor is injected into the registration layer
+ * so that all tool handlers are audited without per-handler changes.
+ *
+ * OAuth identity (`user`/`scopes`) is read from AsyncLocalStorage
+ * via `getAuthContext()`. When OAuth is configured, the HTTP
+ * transport binds the validated auth context before MCP dispatch.
+ * When OAuth is not configured (stdio, no auth), fields are `null`/`[]`.
+ */
+
+/**
+ * Audit interceptor interface — used by the registration layer.
+ */
+interface AuditInterceptor {
+    /**
+     * Wrap a tool invocation with audit logging.
+     * Returns the tool result unchanged; re-throws any errors.
+     *
+     * @param toolName  MCP tool name
+     * @param args      Tool input arguments
+     * @param requestId Request ID from RequestContext
+     * @param fn        The actual tool handler to execute
+     * @param options   Optional configuration, such as overriding the recorded tool name
+     */
+    around<T>(toolName: string, args: unknown, requestId: string, fn: () => Promise<T>, options?: {
+        logAs?: string;
+    }): Promise<T>;
+}
+
 /**
  * db-mcp - Database Adapter Interface
  *
@@ -611,6 +802,20 @@ declare abstract class DatabaseAdapter {
      * Get supported tool groups for this adapter
      */
     abstract getSupportedToolGroups(): ToolGroup[];
+    protected auditInterceptor: AuditInterceptor | null;
+    protected backupManager: BackupManager | null;
+    /**
+     * Inject the audit interceptor.
+     */
+    setAuditInterceptor(interceptor: AuditInterceptor): void;
+    /**
+     * Inject the backup manager for tools to use natively.
+     */
+    setBackupManager(manager: BackupManager): void;
+    /**
+     * Get the audit interceptor (used by registration layer and Code Mode).
+     */
+    getAuditInterceptor(): AuditInterceptor | null;
     /**
      * Get all tool definitions for this adapter
      */
@@ -696,6 +901,10 @@ declare class DbMcpServer {
     private adapters;
     private toolFilter;
     private config;
+    private auditLogger;
+    private backupManager;
+    private auditInterceptor;
+    private auditInitPromise;
     constructor(config: McpServerConfig);
     /**
      * Register a database adapter
@@ -735,6 +944,19 @@ declare class DbMcpServer {
      * Gracefully shut down the server
      */
     shutdown(): Promise<void>;
+    /**
+     * Initialize the audit subsystem: logger, interceptor, backup manager,
+     * sqlite://audit resource, and audit backup tools.
+     */
+    private initializeAudit;
+    /**
+     * Register the sqlite://audit resource for agent access to audit log.
+     */
+    private registerAuditResource;
+    /**
+     * Register audit backup tools for snapshot management.
+     */
+    private registerAuditBackupTools;
 }
 /**
  * Create and configure a db-mcp server instance
@@ -751,17 +973,18 @@ declare const DEFAULT_CONFIG: Partial<McpServerConfig>;
  * Defines the tool groups and meta-groups used for filtering.
  *
  * Actual tool groups (from code audit):
- *   core: 9 tools (core/queries.ts, core/tables.ts, core/indexes.ts)
- *   json: 23 tools (json-operations/crud+query+transform.ts, json-helpers/read+write.ts)
- *   text: 13 WASM / 17 Native (text/regex+formatting+search+validate.ts, fts.ts)
- *   stats: 13 WASM / 19 Native (stats/basic+advanced.ts, native: window.ts)
+ *   core: 14 tools (core/queries.ts, core/tables.ts, core/indexes.ts, core/convenience.ts)
+ *   json: 24 tools (json-operations/crud+query+transform+security.ts, json-helpers/read+write.ts)
+ *   text: 14 WASM / 19 Native (text/regex+formatting+search+validate+sentiment.ts, fts.ts)
+ *   stats: 16 WASM / 22 Native (stats/basic+advanced.ts, inference/, anomaly-detection.ts, schema-risks.ts, native: window.ts)
  *   vector: 11 tools (vector/storage+search+metadata.ts)
- *   admin: 26 WASM / 33 Native (admin/backup+verify+pragma.ts, virtual/views+vtable+extensions+analysis.ts, native: transactions.ts)
+ *   admin: 26 WASM / 26 Native (admin/backup+verify+pragma.ts, virtual/views+vtable+extensions+analysis.ts)
+ *   transactions: 8 Native (native: transactions.ts)
  *   geo: 4 WASM / 11 Native (geo.ts, native: spatialite/tools+analysis.ts)
  *   introspection: 9 tools (introspection/graph/tools.ts, analysis/constraints+risks+snapshot.ts, diagnostics/storage+indexes+query-plan.ts)
  *   migration: 6 tools (migration/tracking.ts) — opt-in
  *   codemode: 1 tool (codemode.ts)
- *   Total: 115 WASM / 139 Native tools
+ *   Total: 125 WASM / 151 Native tools
  *
  * Note: 3 built-in server tools (server_info, server_health, list_adapters)
  * are always available regardless of filter settings.

package/dist/index.js

@@ -1,5 +1,6 @@
-export { DEFAULT_CONFIG, DbMcpServer, NAME, VERSION, createServer } from './chunk-DZQLDEQS.js';
-export { DatabaseAdapter } from './chunk-Z2GFQU3G.js';
-import './chunk-S5IDDSSB.js';
-export { AuthenticationError, AuthorizationError, ConnectionError, QueryError, ValidationError } from './chunk-4IA3DB5C.js';
-export { ALL_TOOL_GROUPS, DbMcpError, META_GROUPS, TOOL_GROUPS, filterTools, getFilterSummary, getToolFilterFromEnv, isToolEnabled, parseToolFilter } from './chunk-AOUL5SHS.js';
+export { DEFAULT_CONFIG, DbMcpServer, createServer } from './chunk-WBER5YY4.js';
+import './chunk-SFJQCNG7.js';
+export { DatabaseAdapter } from './chunk-Z7C2TM4L.js';
+export { NAME, VERSION } from './chunk-VIDSICEL.js';
+export { AuthenticationError, AuthorizationError, ConnectionError, QueryError, ValidationError } from './chunk-X3MUUOWM.js';
+export { ALL_TOOL_GROUPS, DbMcpError, META_GROUPS, TOOL_GROUPS, filterTools, getFilterSummary, getToolFilterFromEnv, isToolEnabled, parseToolFilter } from './chunk-645ZEFLA.js';