db-mcp 3.0.2 → 5.0.0

package/dist/chunk-2TYICG7B.js

@@ -0,0 +1,1183 @@
+import { ConfigurationError, SCOPES, ValidationError, DbMcpError, ErrorCategory } from './chunk-XLIYO3YA.js';
+import { createRequire } from 'module';
+import { resolve, parse, dirname, relative, join, sep, isAbsolute, basename, normalize } from 'path';
+import { realpathSync, lstatSync, existsSync } from 'fs';
+import { z } from 'zod';
+
+var _require = createRequire(import.meta.url);
+var pkg = _require("../package.json");
+var VERSION = pkg.version;
+var NAME = pkg.name;
+var IoPathError = class extends DbMcpError {
+  constructor(message) {
+    super(message, "SECURITY_ERROR", ErrorCategory.VALIDATION, {
+      suggestion: "Check that the target path is within the allowed IO roots.",
+      recoverable: false
+    });
+    this.name = "IoPathError";
+  }
+};
+function assertSafeIoPath(targetPath, allowedRoots, validateExtension = true) {
+  if (targetPath.includes("\0")) {
+    throw new IoPathError("Security: path must not contain null bytes.");
+  }
+  if (targetPath.startsWith("file:") || targetPath.includes("?")) {
+    throw new IoPathError(
+      "Security: SQLite URIs and query parameters are not allowed."
+    );
+  }
+  const normalized = targetPath.replace(/\\/g, "/");
+  const segments = normalized.split("/");
+  if (segments.some((s) => s === "..")) {
+    throw new IoPathError("Security: Path traversal (..) detected.");
+  }
+  const base = segments[segments.length - 1];
+  if (!base) {
+    throw new IoPathError("Security: Invalid path structure.");
+  }
+  if (base.startsWith(".")) {
+    throw new IoPathError("Security: Cannot access hidden files or dotfiles.");
+  }
+  if (validateExtension) {
+    const validExtensions = [
+      ".db",
+      ".sqlite",
+      ".sqlite3",
+      ".sql",
+      ".csv",
+      ".tsv"
+    ];
+    const hasValidExt = validExtensions.some(
+      (ext) => base.toLowerCase().endsWith(ext)
+    );
+    if (!hasValidExt) {
+      throw new IoPathError(
+        `Security: Invalid file extension. Allowed extensions are: ${validExtensions.join(", ")}`
+      );
+    }
+  }
+  const resolved = resolve(targetPath);
+  let currentDir = resolved;
+  let existingRealPath = "";
+  while (currentDir !== parse(currentDir).root) {
+    try {
+      existingRealPath = realpathSync(currentDir);
+      break;
+    } catch {
+      currentDir = dirname(currentDir);
+    }
+  }
+  if (!existingRealPath) {
+    try {
+      existingRealPath = realpathSync(currentDir);
+    } catch {
+      existingRealPath = currentDir;
+    }
+  }
+  const remainder = relative(currentDir, resolved);
+  const finalTargetPath = remainder ? join(existingRealPath, remainder) : existingRealPath;
+  if (allowedRoots.length === 0) {
+    throw new IoPathError(
+      "No allowed input/output roots configured for sandbox boundary. Please configure ALLOWED_IO_ROOTS env variable or pass --allowed-io-roots with absolute paths to enable filesystem operations."
+    );
+  }
+  const safeRoots = [];
+  for (const root of allowedRoots) {
+    try {
+      safeRoots.push(realpathSync(resolve(root)));
+    } catch {
+      safeRoots.push(resolve(root));
+    }
+  }
+  const isAllowed = safeRoots.some((root) => {
+    const rel = relative(root, finalTargetPath);
+    return rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel);
+  });
+  if (!isAllowed) {
+    throw new IoPathError(
+      `Directory path escapes allowed sandbox boundaries: ${targetPath}`
+    );
+  }
+  let isSymlink = false;
+  try {
+    const stats = lstatSync(resolved);
+    if (stats.isSymbolicLink()) {
+      isSymlink = true;
+    }
+  } catch {
+  }
+  if (isSymlink) {
+    throw new IoPathError(
+      `Symlinks are strictly forbidden for file operations: ${targetPath}`
+    );
+  }
+}
+function parseAllowedIoRoots(raw) {
+  if (!raw) return void 0;
+  if (raw.length > 51200) {
+    throw new ConfigurationError(
+      "ALLOWED_IO_ROOTS configuration exceeds size limit (50KB)"
+    );
+  }
+  let paths;
+  try {
+    if (raw.trim().startsWith("[")) {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed) && parsed.every((p) => typeof p === "string" && isAbsolute(p))) {
+        paths = parsed;
+      } else {
+        throw new ConfigurationError("Must be an array of absolute paths");
+      }
+    } else {
+      paths = raw.split(",").map((s) => s.trim()).filter(Boolean);
+      if (paths.some((p) => !isAbsolute(p))) {
+        throw new ConfigurationError("All paths must be absolute");
+      }
+    }
+  } catch (e) {
+    const errName = e instanceof Error ? e.message : String(e);
+    throw new ConfigurationError(
+      `Invalid ALLOWED_IO_ROOTS configuration: ${errName}`,
+      "CONFIG_ERROR",
+      {
+        cause: e instanceof Error ? e : void 0
+      }
+    );
+  }
+  for (const p of paths) {
+    try {
+      if (!existsSync(p)) {
+        console.warn(`
+[WARN] ALLOWED_IO_ROOTS path does not exist: ${p}
+`);
+      }
+    } catch {
+    }
+  }
+  return paths;
+}
+
+// src/utils/annotations.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  sensitiveHint: false
+};
+var WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: false,
+  sensitiveHint: false
+};
+var DESTRUCTIVE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false,
+  sensitiveHint: false
+};
+var IDEMPOTENT = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+  sensitiveHint: false
+};
+var ADMIN = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false,
+  sensitiveHint: true
+  // System maintenance may expose internal db structures
+};
+function readOnly(title) {
+  return { title, ...READ_ONLY };
+}
+function write(title) {
+  return { title, ...WRITE };
+}
+function destructive(title) {
+  return { title, ...DESTRUCTIVE };
+}
+function idempotent(title) {
+  return { title, ...IDEMPOTENT };
+}
+function admin(title) {
+  return { title, ...ADMIN };
+}
+var ADMIN_FS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: true,
+  sensitiveHint: true
+};
+var WRITE_FS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: true,
+  sensitiveHint: true
+};
+function adminFs(title) {
+  return { title, ...ADMIN_FS };
+}
+function writeFs(title) {
+  return { title, ...WRITE_FS };
+}
+function toSDK(annotations) {
+  return annotations;
+}
+
+// src/utils/icons.ts
+var MDI_BASE = "https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg";
+var SERVER_ICONS = [
+  {
+    src: `${MDI_BASE}/server.svg`,
+    mimeType: "image/svg+xml"
+  }
+];
+var TOOL_GROUP_ICONS = {
+  core: [{ src: `${MDI_BASE}/database.svg`, mimeType: "image/svg+xml" }],
+  json: [{ src: `${MDI_BASE}/code-json.svg`, mimeType: "image/svg+xml" }],
+  text: [{ src: `${MDI_BASE}/format-text.svg`, mimeType: "image/svg+xml" }],
+  stats: [{ src: `${MDI_BASE}/chart-bar.svg`, mimeType: "image/svg+xml" }],
+  vector: [
+    { src: `${MDI_BASE}/vector-polyline.svg`, mimeType: "image/svg+xml" }
+  ],
+  admin: [{ src: `${MDI_BASE}/cog.svg`, mimeType: "image/svg+xml" }],
+  transactions: [
+    { src: `${MDI_BASE}/swap-horizontal.svg`, mimeType: "image/svg+xml" }
+  ],
+  geo: [{ src: `${MDI_BASE}/earth.svg`, mimeType: "image/svg+xml" }],
+  introspection: [
+    { src: `${MDI_BASE}/graph-outline.svg`, mimeType: "image/svg+xml" }
+  ],
+  migration: [
+    { src: `${MDI_BASE}/source-branch.svg`, mimeType: "image/svg+xml" }
+  ],
+  codemode: [{ src: `${MDI_BASE}/code-braces.svg`, mimeType: "image/svg+xml" }]
+};
+function getToolGroupIcon(group) {
+  return TOOL_GROUP_ICONS[group];
+}
+
+// src/utils/redaction.ts
+var SENSITIVE_KEY_PATTERN = /(?:sk-|Bearer |token\s*[:=]\s*|password\s*[:=]\s*|secret\s*[:=]\s*|apikey\s*[:=]\s*|api_key\s*[:=]\s*|AWS_SECRET_ACCESS_KEY\s*[:=]\s*|GITHUB_TOKEN\s*[:=]\s*|ghp_|gho_|ghu_|ghs_|xoxb-|xoxp-|xoxs-|AZURE_[A-Z_]*\s*[:=]\s*|DATABASE_URL\s*[:=]\s*|AKIA|sk-ant-api[a-zA-Z0-9_-]+|sk_live_[a-zA-Z0-9_]+|rk_live_[a-zA-Z0-9_]+|SG\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+|npm_[a-zA-Z0-9]{30,}|dpl_[a-zA-Z0-9]{30,}|hvs\.[a-zA-Z0-9_-]+)[^\s'",;)}\]]{2,}/i;
+var SENSITIVE_VALUE_REGEX = new RegExp(SENSITIVE_KEY_PATTERN.source, "gi");
+var SENSITIVE_KEY_REGEX = /^(password|passwd|token|secret|authorization|api_?key|credential|private_?key|access_?token|refresh_?token|database_url)$/i;
+function redactObject(obj, depth = 0, maxDepth = 15) {
+  if (depth > maxDepth || obj === null || obj === void 0) {
+    return obj;
+  }
+  if (typeof obj === "string") {
+    return obj.replace(SENSITIVE_VALUE_REGEX, "[REDACTED]");
+  }
+  if (typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => redactObject(item, depth + 1, maxDepth));
+  }
+  const redacted = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (SENSITIVE_KEY_REGEX.test(key)) {
+      redacted[key] = "[REDACTED]";
+    } else {
+      redacted[key] = redactObject(value, depth + 1, maxDepth);
+    }
+  }
+  return redacted;
+}
+
+// src/auth/scope-map.ts
+var toolScopeMap = /* @__PURE__ */ new Map();
+function registerToolScope(toolName, scope) {
+  toolScopeMap.set(toolName, scope);
+  if (!toolName.startsWith("sqlite_")) {
+    toolScopeMap.set(`sqlite_${toolName}`, scope);
+  } else {
+    toolScopeMap.set(toolName.slice(7), scope);
+  }
+}
+function getRequiredScope(toolName) {
+  return toolScopeMap.get(toolName) ?? SCOPES.ADMIN;
+}
+
+// src/utils/where-clause.ts
+var UnsafeWhereClauseError = class extends Error {
+  constructor(reason) {
+    super(`Unsafe WHERE clause: ${reason}`);
+    this.name = "UnsafeWhereClauseError";
+  }
+};
+var DANGEROUS_PATTERNS = [
+  // Statement terminators and new statements
+  // Comprehensive keyword list including statements missed in earlier versions:
+  // REPLACE, VACUUM, ANALYZE, BEGIN, COMMIT, ROLLBACK, SAVEPOINT, RELEASE
+  {
+    pattern: /;\s*(DROP|DELETE|TRUNCATE|INSERT|UPDATE|CREATE|ALTER|ATTACH|DETACH|SELECT|REPLACE|VACUUM|ANALYZE|BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|REINDEX|EXPLAIN)\b/i,
+    reason: "contains statement terminator followed by SQL keyword"
+  },
+  // Trailing semicolons (potential statement injection)
+  {
+    pattern: /;\s*$/,
+    reason: "contains trailing semicolon"
+  },
+  // SQL comments (can be used to comment out security checks)
+  {
+    pattern: /--/,
+    reason: "contains SQL line comment"
+  },
+  {
+    pattern: /\/\*/,
+    reason: "contains SQL block comment"
+  },
+  // REGEXP and MATCH injection (blind extraction oracles)
+  {
+    pattern: /\bREGEXP\s+/i,
+    reason: "contains REGEXP (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bMATCH\s+/i,
+    reason: "contains MATCH (potential blind extraction oracle)"
+  },
+  // UNION injection (data exfiltration)
+  {
+    pattern: /\bUNION\s+(ALL\s+)?SELECT\b/i,
+    reason: "contains UNION SELECT"
+  },
+  // SQLite-specific: Extension loading (code execution)
+  {
+    pattern: /\bload_extension\s*\(/i,
+    reason: "contains load_extension (code execution)"
+  },
+  // SQLite-specific: ATTACH database (file system access)
+  {
+    pattern: /\bATTACH\s+(DATABASE\s+)?['"`]/i,
+    reason: "contains ATTACH DATABASE (file system access)"
+  },
+  // SQLite-specific: Pragma manipulation
+  {
+    pattern: /\bPRAGMA\s+/i,
+    reason: "contains PRAGMA statement"
+  },
+  // SQLite-specific: writefile/readfile (if using fileio extension)
+  {
+    pattern: /\b(writefile|readfile)\s*\(/i,
+    reason: "contains file I/O function"
+  },
+  // SQLite-specific: fts3_tokenizer (potential code execution)
+  {
+    pattern: /\bfts3_tokenizer\s*\(/i,
+    reason: "contains FTS tokenizer function"
+  },
+  // Subquery injection (data exfiltration via boolean-based blind)
+  {
+    pattern: /\(\s*SELECT\b/i,
+    reason: "contains subquery (potential data exfiltration)"
+  },
+  // Generic: Hexadecimal string injection
+  {
+    pattern: /\bX'[0-9A-Fa-f]+'/,
+    reason: "contains hex string literal (potential binary injection)"
+  },
+  // CASE WHEN (potential blind injection without subqueries)
+  {
+    pattern: /\bCASE\s+WHEN\b/i,
+    reason: "contains CASE WHEN (potential blind injection)"
+  },
+  // IIF() — conditional bypass alternative to CASE WHEN
+  {
+    pattern: /\bIIF\s*\(/i,
+    reason: "contains IIF() (potential blind injection)"
+  },
+  // GROUP_CONCAT() — data aggregation for exfiltration
+  {
+    pattern: /\bGROUP_CONCAT\s*\(/i,
+    reason: "contains GROUP_CONCAT() (potential data exfiltration)"
+  },
+  // GLOB — case-sensitive wildcard operator usable for character extraction oracles
+  {
+    pattern: /\bGLOB\b/i,
+    reason: "contains GLOB (potential case-sensitive oracle)"
+  },
+  // Conditional functions — blind injection oracles (bypass for CASE WHEN / IIF)
+  {
+    pattern: /\bCOALESCE\s*\(/i,
+    reason: "contains COALESCE() (potential blind injection oracle)"
+  },
+  {
+    pattern: /\bNULLIF\s*\(/i,
+    reason: "contains NULLIF() (potential blind injection oracle)"
+  },
+  {
+    pattern: /\bTYPEOF\s*\(/i,
+    reason: "contains TYPEOF() (potential blind injection oracle)"
+  },
+  {
+    pattern: /\bIFNULL\s*\(/i,
+    reason: "contains IFNULL() (potential blind injection oracle)"
+  },
+  // Memory allocation DoS — RANDOMBLOB(N) / ZEROBLOB(N) can allocate large blocks (CWE-400)
+  {
+    pattern: /\bRANDOMBLOB\s*\(/i,
+    reason: "contains RANDOMBLOB() (potential memory allocation DoS)"
+  },
+  {
+    pattern: /\bZEROBLOB\s*\(/i,
+    reason: "contains ZEROBLOB() (potential memory allocation DoS)"
+  },
+  // Blind extraction oracle functions — can be composed for character-by-character
+  // data extraction without subqueries or CASE WHEN (CWE-89, H-1 audit finding).
+  // Example: INSTR('abc...', SUBSTR(sqlite_version(), 1, 1)) = N
+  {
+    pattern: /\bINSTR\s*\(/i,
+    reason: "contains INSTR() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bSUBSTR\s*\(/i,
+    reason: "contains SUBSTR() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bSUBSTRING\s*\(/i,
+    reason: "contains SUBSTRING() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bLENGTH\s*\(/i,
+    reason: "contains LENGTH() (potential blind extraction oracle)"
+  },
+  // TRIM functions — blind extraction oracle (bypass for LIKE / SUBSTR)
+  {
+    pattern: /\b(?:L|R)?TRIM\s*\(/i,
+    reason: "contains TRIM() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bUNICODE\s*\(/i,
+    reason: "contains UNICODE() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bCHAR\s*\(/i,
+    reason: "contains CHAR() (potential blind extraction oracle)"
+  },
+  {
+    pattern: /\bREPLACE\s*\(/i,
+    reason: "contains REPLACE() (potential blind extraction oracle)"
+  },
+  // ABS() — can be combined with subtraction to create numeric oracles (CWE-89)
+  {
+    pattern: /\bABS\s*\(/i,
+    reason: "contains ABS() (potential blind extraction oracle)"
+  },
+  // HEX() — encodes values for character-by-character extraction (CWE-89)
+  {
+    pattern: /\bHEX\s*\(/i,
+    reason: "contains HEX() (potential blind extraction oracle)"
+  },
+  // QUOTE() — returns SQL-literal representation, can leak type/value info (CWE-89)
+  {
+    pattern: /\bQUOTE\s*\(/i,
+    reason: "contains QUOTE() (potential blind extraction oracle)"
+  },
+  // PRINTF() — format-string based extraction of internal values (CWE-89)
+  {
+    pattern: /\bPRINTF\s*\(/i,
+    reason: "contains PRINTF() (potential blind extraction oracle)"
+  },
+  // FORMAT() — SQLite 3.38.0+ alias for printf() (CWE-89)
+  {
+    pattern: /\bFORMAT\s*\(/i,
+    reason: "contains FORMAT() (potential blind extraction oracle)"
+  },
+  // CAST() — can be used to convert text to numeric oracles (CWE-89)
+  {
+    pattern: /\bCAST\s*\(/i,
+    reason: "contains CAST() (potential blind extraction oracle)"
+  }
+];
+var FULLWIDTH_START = 65281;
+var FULLWIDTH_END = 65374;
+var FULLWIDTH_ASCII_OFFSET = 65248;
+function normalizeForPatternMatching(input) {
+  let normalized = input.normalize("NFC");
+  let hasFullwidth = false;
+  for (let i = 0; i < normalized.length; i++) {
+    const code = normalized.charCodeAt(i);
+    if (code >= FULLWIDTH_START && code <= FULLWIDTH_END) {
+      hasFullwidth = true;
+      break;
+    }
+  }
+  if (hasFullwidth) {
+    const chars = [];
+    for (let i = 0; i < normalized.length; i++) {
+      const code = normalized.charCodeAt(i);
+      if (code >= FULLWIDTH_START && code <= FULLWIDTH_END) {
+        chars.push(String.fromCharCode(code - FULLWIDTH_ASCII_OFFSET));
+      } else {
+        chars.push(normalized.charAt(i));
+      }
+    }
+    normalized = chars.join("");
+  }
+  return normalized;
+}
+function sanitizeWhereClause(where) {
+  if (!where || typeof where !== "string") {
+    throw new UnsafeWhereClauseError("WHERE clause must be a non-empty string");
+  }
+  const MAX_WHERE_LENGTH = 10240;
+  if (where.length > MAX_WHERE_LENGTH) {
+    throw new UnsafeWhereClauseError(
+      `WHERE clause exceeds maximum length of ${String(MAX_WHERE_LENGTH)} characters`
+    );
+  }
+  const normalized = normalizeForPatternMatching(where);
+  for (const { pattern, reason } of DANGEROUS_PATTERNS) {
+    if (pattern.test(normalized)) {
+      throw new UnsafeWhereClauseError(reason);
+    }
+  }
+  return where;
+}
+function buildWhereClause(conditions, whereClause) {
+  let finalSql = "";
+  const params = [];
+  const clauses = [];
+  if (conditions !== void 0 && conditions !== null && conditions.length > 0) {
+    const allowedOperators = /* @__PURE__ */ new Set([
+      "=",
+      "!=",
+      ">",
+      ">=",
+      "<",
+      "<=",
+      "LIKE",
+      "IN",
+      "IS",
+      "IS NOT",
+      "NOT LIKE"
+    ]);
+    for (const cond of conditions) {
+      if (!allowedOperators.has(cond.operator.toUpperCase())) {
+        throw new ValidationError(`Invalid operator: ${cond.operator}`);
+      }
+      const col = `"${cond.column.replace(/"/g, '""')}"`;
+      if (cond.operator.toUpperCase() === "IN" && Array.isArray(cond.value)) {
+        const placeholders = cond.value.map(() => "?").join(", ");
+        clauses.push(`${col} IN (${placeholders})`);
+        params.push(...cond.value);
+      } else {
+        clauses.push(`${col} ${cond.operator} ?`);
+        params.push(cond.value);
+      }
+    }
+    finalSql = clauses.join(" AND ");
+  }
+  if (whereClause) {
+    const safeWhere = sanitizeWhereClause(whereClause);
+    if (finalSql) {
+      finalSql = `${finalSql} AND ${safeWhere}`;
+    } else {
+      finalSql = safeWhere;
+    }
+  }
+  return { sql: finalSql, params };
+}
+
+// src/utils/identifiers.ts
+var IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 255;
+var InvalidIdentifierError = class extends Error {
+  constructor(identifier, reason) {
+    super(`Invalid identifier "${identifier}": ${reason}`);
+    this.identifier = identifier;
+    this.reason = reason;
+    this.name = "InvalidIdentifierError";
+  }
+  identifier;
+  reason;
+};
+function validateIdentifier(name) {
+  if (!name || typeof name !== "string") {
+    throw new InvalidIdentifierError(
+      name,
+      "Identifier must be a non-empty string"
+    );
+  }
+  if (name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new InvalidIdentifierError(
+      name,
+      `Identifier exceeds maximum length of ${String(MAX_IDENTIFIER_LENGTH)} characters`
+    );
+  }
+  if (!IDENTIFIER_PATTERN.test(name)) {
+    throw new InvalidIdentifierError(
+      name,
+      "Identifier contains invalid characters. Must start with a letter or underscore and contain only letters, digits, or underscores"
+    );
+  }
+}
+function sanitizeIdentifier(name) {
+  validateIdentifier(name);
+  const escaped = name.replace(/"/g, '""');
+  return `"${escaped}"`;
+}
+function sanitizeIdentifiers(names) {
+  return names.map(sanitizeIdentifier);
+}
+function createColumnList(columns) {
+  return sanitizeIdentifiers(columns).join(", ");
+}
+
+// src/utils/tokens.ts
+function estimateTokens(text, contentType = "text") {
+  const bytes = Buffer.byteLength(text, "utf8");
+  switch (contentType) {
+    case "json":
+      return Math.ceil(bytes / 3);
+    case "sql":
+      return Math.ceil(bytes / 3.5);
+    case "text":
+    default:
+      return Math.ceil(bytes / 4);
+  }
+}
+
+// src/utils/progress-utils.ts
+function buildProgressContext(ctx) {
+  if (ctx?.server === void 0 || ctx.progressToken === void 0) {
+    return void 0;
+  }
+  return {
+    server: ctx.server,
+    progressToken: ctx.progressToken
+  };
+}
+async function sendProgress(ctx, progress, total, message) {
+  if (ctx === void 0) return;
+  if (ctx.progressToken === void 0) return;
+  try {
+    const notification = {
+      method: "notifications/progress",
+      params: {
+        progressToken: ctx.progressToken,
+        progress,
+        ...total !== void 0 && { total },
+        ...message !== void 0 && message !== "" && { message }
+      }
+    };
+    await ctx.server.notification(notification);
+  } catch {
+  }
+}
+
+// src/utils/stream-utils.ts
+var STREAM_CHUNK_SIZE = 10;
+async function streamResultRows(ctx, rows, chunkSize = STREAM_CHUNK_SIZE) {
+  if (rows.length === 0) {
+    return 0;
+  }
+  const effectiveChunkSize = Math.max(1, chunkSize);
+  const totalChunks = Math.ceil(rows.length / effectiveChunkSize);
+  for (let i = 0; i < totalChunks; i++) {
+    const start = i * effectiveChunkSize;
+    const end = Math.min(start + effectiveChunkSize, rows.length);
+    const chunk = rows.slice(start, end);
+    await sendProgress(ctx, i + 1, totalChunks, JSON.stringify(chunk));
+  }
+  return totalChunks;
+}
+function validateSameDirPath(targetPath, dbPath) {
+  if (targetPath.includes("\0")) {
+    return {
+      valid: false,
+      error: "Security: path must not contain null bytes.",
+      dbDir: dbPath === ":memory:" ? "" : dirname(resolve(dbPath))
+    };
+  }
+  if (targetPath.startsWith("file:") || targetPath.includes("?")) {
+    return {
+      valid: false,
+      error: "Security: SQLite URIs and query parameters are not allowed.",
+      dbDir: dbPath === ":memory:" ? "" : dirname(resolve(dbPath))
+    };
+  }
+  const base = basename(targetPath);
+  if (base.startsWith(".")) {
+    return {
+      valid: false,
+      error: "Security: Cannot access hidden files or dotfiles.",
+      dbDir: dbPath === ":memory:" ? "" : dirname(resolve(dbPath))
+    };
+  }
+  const validExtensions = [
+    ".db",
+    ".sqlite",
+    ".sqlite3",
+    ".sql",
+    ".csv",
+    ".tsv"
+  ];
+  const hasValidExt = validExtensions.some(
+    (ext) => base.toLowerCase().endsWith(ext)
+  );
+  if (!hasValidExt) {
+    return {
+      valid: false,
+      error: `Security: Invalid file extension. Allowed extensions are: ${validExtensions.join(", ")}`,
+      dbDir: dbPath === ":memory:" ? "" : dirname(resolve(dbPath))
+    };
+  }
+  if (dbPath === ":memory:") {
+    return {
+      valid: false,
+      error: "Security: Filesystem operations are not permitted for :memory: databases.",
+      dbDir: ""
+    };
+  }
+  const dbDir = dirname(resolve(dbPath));
+  let resolvedTarget = resolve(targetPath);
+  try {
+    resolvedTarget = realpathSync(resolvedTarget);
+  } catch {
+    try {
+      const parentDir = realpathSync(dirname(resolvedTarget));
+      resolvedTarget = resolve(parentDir, basename(resolvedTarget));
+    } catch {
+      return {
+        valid: false,
+        error: "Security: Target parent directory must exist.",
+        dbDir
+      };
+    }
+  }
+  let resolvedDbDir;
+  try {
+    resolvedDbDir = realpathSync(dbDir);
+  } catch {
+    return {
+      valid: false,
+      error: "Security: Database directory must exist.",
+      dbDir
+    };
+  }
+  const normalizedTarget = normalize(resolvedTarget);
+  const normalizedDir = normalize(resolvedDbDir);
+  const targetDir = normalize(dirname(resolvedTarget));
+  if (relative(normalizedDir, targetDir) !== "") {
+    return {
+      valid: false,
+      error: `Security: path must be within the database directory. Path traversal is not allowed.`,
+      dbDir
+    };
+  }
+  return { valid: true, resolvedPath: normalizedTarget };
+}
+
+// src/utils/validate-json-path.ts
+var VALID_JSON_PATH_PATTERN = /^\$(\.[a-zA-Z_][a-zA-Z0-9_ -]*|\[\d+\]|\[#\]|\[\*\])*$/;
+var MAX_JSON_PATH_LENGTH = 500;
+function validateJsonPath(path, param = "path") {
+  if (!path.startsWith("$")) {
+    throw new ValidationError(
+      `JSON ${param} must start with $`,
+      "INVALID_JSON_PATH",
+      {
+        suggestion: "Use a valid JSON path starting with $. For example: $.key or $[0]"
+      }
+    );
+  }
+  if (path.length > MAX_JSON_PATH_LENGTH) {
+    throw new ValidationError(
+      `JSON ${param} exceeds maximum length of ${MAX_JSON_PATH_LENGTH} characters`,
+      "INVALID_JSON_PATH"
+    );
+  }
+  if (!VALID_JSON_PATH_PATTERN.test(path)) {
+    throw new ValidationError(
+      `Invalid JSON ${param} syntax: ${path}`,
+      "INVALID_JSON_PATH",
+      {
+        suggestion: "Use $.key, $[0], or $[*] patterns. Member names must start with a letter or underscore."
+      }
+    );
+  }
+}
+var ALLOWED_AGGREGATE_FUNCTIONS = /* @__PURE__ */ new Set([
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "group_concat",
+  "total"
+]);
+var AGGREGATE_FUNCTION_PATTERN = /^([A-Za-z_]+)\(\s*(\*|"[a-zA-Z_][a-zA-Z0-9_]*"|[a-zA-Z_][a-zA-Z0-9_]*)(?:\s*,\s*'[^']*')?\s*\)$/;
+function validateAggregateFunction(fn) {
+  const match = AGGREGATE_FUNCTION_PATTERN.exec(fn.trim());
+  if (!match) {
+    throw new ValidationError(
+      `Invalid aggregate function syntax: ${fn}`,
+      "INVALID_AGGREGATE_FUNCTION",
+      {
+        suggestion: "Use a standard aggregate function like COUNT(*), SUM(column), AVG(column), MIN(column), MAX(column), GROUP_CONCAT(column), or TOTAL(column)."
+      }
+    );
+  }
+  const funcName = match[1]?.toLowerCase();
+  if (!funcName || !ALLOWED_AGGREGATE_FUNCTIONS.has(funcName)) {
+    throw new ValidationError(
+      `Disallowed aggregate function: ${match[1]}. Allowed: ${[...ALLOWED_AGGREGATE_FUNCTIONS].join(", ").toUpperCase()}`,
+      "INVALID_AGGREGATE_FUNCTION"
+    );
+  }
+}
+var ErrorResponseFields = z.object({
+  error: z.string().optional().describe("Error message (human-readable)"),
+  code: z.string().optional().describe("Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)"),
+  category: z.string().optional().describe("Error category (validation, query, connection, internal)"),
+  recoverable: z.boolean().optional().describe("Whether the error is recoverable"),
+  suggestion: z.string().optional().describe("Suggested fix for the error"),
+  details: z.record(z.string(), z.unknown()).optional().describe("Additional error context")
+});
+var coerceNumber = (val) => {
+  if (typeof val === "string") {
+    if (val.trim() === "") return void 0;
+    const num = Number(val);
+    return isNaN(num) ? val : num;
+  }
+  return val;
+};
+var BackupSchema = z.object({
+  targetPath: z.string().describe("Path for backup file")
+});
+var AnalyzeSchema = z.object({
+  table: z.string().optional().describe("Specific table to analyze (default: all)")
+});
+var IntegrityCheckSchema = z.object({
+  maxErrors: z.preprocess(
+    coerceNumber,
+    z.number().int().optional().default(100).describe("Maximum errors to report")
+  )
+});
+var OptimizeSchema = z.object({
+  table: z.string().optional().describe("Specific table to optimize"),
+  reindex: z.boolean().optional().default(false),
+  analyze: z.boolean().optional().default(true)
+});
+var RestoreSchema = z.object({
+  sourcePath: z.string().describe("Path to backup file to restore from"),
+  allowTriggers: z.boolean().optional().default(false).describe(
+    "If true, allows triggers in the backup file to be restored. This is a security risk if the backup file is untrusted."
+  )
+});
+var VerifyBackupSchema = z.object({
+  backupPath: z.string().describe("Path to backup file to verify")
+});
+var IndexStatsSchema = z.object({
+  table: z.string().optional().describe("Filter indexes by table name (default: all tables)"),
+  excludeSystemIndexes: z.boolean().optional().default(true).describe(
+    "Exclude SpatiaLite system indexes (default: true). Set to false to include all indexes."
+  )
+});
+var PragmaOptimizeSchema = z.object({
+  mask: z.preprocess(
+    coerceNumber,
+    z.number().int().optional().describe("Optional optimization mask (default: 0xfffe)")
+  )
+});
+var PragmaSettingsSchema = z.object({
+  pragma: z.string().describe("PRAGMA name (e.g., 'cache_size', 'journal_mode')"),
+  value: z.union([z.string(), z.number().int()]).optional().describe("Value to set (omit to only read)")
+});
+var PragmaTableInfoSchema = z.object({
+  table: z.string().describe("Table name to get column information for")
+});
+var PragmaCompileOptionsSchema = z.object({
+  filter: z.string().optional().describe(
+    "Optional filter pattern (case-insensitive substring match) to limit returned options"
+  )
+});
+var PragmaDatabaseListSchema = z.object({}).strict();
+z.object({
+  analyze: z.boolean().optional().default(true).describe("Run ANALYZE after VACUUM")
+});
+var AttachDatabaseSchema = z.object({
+  filepath: z.string().describe("Path to the database file to attach"),
+  alias: z.string().regex(
+    /^[a-zA-Z_]\w*$/,
+    "Alias must start with a letter or underscore and contain only alphanumeric characters"
+  ).describe("Schema alias for the attached database (e.g., 'analytics')")
+});
+var DetachDatabaseSchema = z.object({
+  alias: z.string().describe("Schema alias of the database to detach (cannot be 'main')")
+});
+var VacuumIntoCopySchema = z.object({
+  outputPath: z.string().describe(
+    "Path for the output database file. Creates a compacted copy of the database."
+  )
+});
+var AuditListBackupsSchema = z.object({
+  limit: z.preprocess(
+    coerceNumber,
+    z.number().int().min(1).max(100).optional().default(10).describe("Maximum number of snapshots to return (default 10, max 100)")
+  ),
+  offset: z.preprocess(
+    coerceNumber,
+    z.number().int().min(0).optional().default(0).describe("Pagination offset")
+  )
+});
+z.object({
+  filename: z.string().describe(
+    "Snapshot filename from sqlite_audit_list_backups results (e.g., '2025-01-01T00-00-00-000Z_sqlite_drop_table_users.snapshot.json.gz')"
+  ),
+  dryRun: z.boolean().optional().default(false).describe(
+    "If true, returns the DDL that would be executed without applying changes"
+  )
+});
+z.object({
+  filename: z.string().describe("Snapshot filename to compare against the live database schema")
+});
+var AuditSearchSchema = z.object({
+  tool: z.string().optional().describe("Filter by exact tool name"),
+  category: z.enum(["read", "write", "admin", "auth", "error"]).optional().describe("Filter by operation category"),
+  success: z.boolean().optional().describe("Filter by success status"),
+  requestId: z.string().optional().describe("Filter by exact request ID"),
+  fromTimestamp: z.string().optional().describe("Filter by start timestamp (ISO 8601)"),
+  toTimestamp: z.string().optional().describe("Filter by end timestamp (ISO 8601)"),
+  limit: z.preprocess(
+    coerceNumber,
+    z.number().int().min(1).max(1e3).optional().default(10).describe("Maximum number of entries to return (default 10)")
+  ),
+  offset: z.preprocess(
+    coerceNumber,
+    z.number().int().min(0).optional().default(0).describe("Pagination offset")
+  )
+});
+var SqlDumpSchema = z.object({
+  outputPath: z.string().describe(
+    "Absolute path where the SQL text dump file will be written (e.g. '/path/to/dump.sql')"
+  )
+});
+var AuditListBackupsOutputSchema = z.object({
+  success: z.boolean(),
+  snapshots: z.array(z.unknown()).optional(),
+  count: z.number().optional(),
+  totalCount: z.number().optional(),
+  _meta: z.object({ tokenEstimate: z.number() }).optional()
+}).extend(ErrorResponseFields.shape);
+var AuditGetBackupOutputSchema = z.object({
+  success: z.boolean(),
+  metadata: z.unknown().optional(),
+  ddl: z.string().optional(),
+  data: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var AuditCleanupOutputSchema = z.object({
+  success: z.boolean(),
+  deletedCount: z.number().optional(),
+  message: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var AuditDiffBackupOutputSchema = z.object({
+  success: z.boolean(),
+  diffs: z.array(z.unknown()).optional(),
+  snapshotTimestamp: z.string().optional(),
+  snapshotTarget: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var AuditRestoreBackupOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  ddl: z.string().optional(),
+  dryRun: z.boolean().optional(),
+  changesApplied: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var AuditSearchOutputSchema = z.object({
+  success: z.boolean(),
+  entries: z.array(z.unknown()).optional(),
+  count: z.number().optional(),
+  totalCount: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var VacuumOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  durationMs: z.number().optional(),
+  wasmLimitation: z.boolean().optional(),
+  sizeChange: z.object({
+    before: z.number(),
+    after: z.number(),
+    saved: z.number()
+  }).optional()
+}).extend(ErrorResponseFields.shape);
+var BackupOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  path: z.string().optional(),
+  sizeBytes: z.number().optional(),
+  durationMs: z.number().optional(),
+  wasmLimitation: z.boolean().optional(),
+  note: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var SqlDumpOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  path: z.string().optional(),
+  durationMs: z.number().optional(),
+  wasmLimitation: z.boolean().optional()
+}).extend(ErrorResponseFields.shape);
+var AnalyzeOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  tablesAnalyzed: z.number().optional(),
+  durationMs: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var OptimizeOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  operations: z.array(z.string()).optional(),
+  durationMs: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var IntegrityCheckOutputSchema = z.object({
+  success: z.boolean(),
+  integrity: z.enum(["ok", "errors_found"]).optional(),
+  errorCount: z.number().optional(),
+  messages: z.array(z.string()).optional()
+}).extend(ErrorResponseFields.shape);
+var RestoreOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  sourcePath: z.string().optional(),
+  durationMs: z.number().optional(),
+  wasmLimitation: z.boolean().optional(),
+  skippedTables: z.array(z.string()).optional(),
+  note: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var VerifyBackupOutputSchema = z.object({
+  success: z.boolean(),
+  valid: z.boolean().optional(),
+  pageCount: z.number().optional(),
+  pageSize: z.number().optional(),
+  integrity: z.enum(["ok", "errors_found"]).optional(),
+  messages: z.array(z.string()).optional(),
+  message: z.string().optional(),
+  wasmLimitation: z.boolean().optional(),
+  backupPath: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var IndexColumnSchema = z.object({
+  name: z.string(),
+  seqno: z.number()
+});
+var IndexStatsEntrySchema = z.object({
+  name: z.string(),
+  table: z.string(),
+  unique: z.boolean(),
+  partial: z.boolean(),
+  columns: z.array(IndexColumnSchema)
+});
+var IndexStatsOutputSchema = z.object({
+  success: z.boolean(),
+  indexes: z.array(IndexStatsEntrySchema).optional()
+}).extend(ErrorResponseFields.shape);
+var PragmaCompileOptionsOutputSchema = z.object({
+  success: z.boolean(),
+  options: z.array(z.string()).optional()
+}).extend(ErrorResponseFields.shape);
+var DatabaseListEntrySchema = z.object({
+  seq: z.number(),
+  name: z.string(),
+  file: z.string()
+});
+var PragmaDatabaseListOutputSchema = z.object({
+  success: z.boolean(),
+  databases: z.array(DatabaseListEntrySchema).optional(),
+  configuredPath: z.string().optional(),
+  note: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var PragmaOptimizeOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  durationMs: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var PragmaSettingsOutputSchema = z.object({
+  success: z.boolean(),
+  pragma: z.string().optional(),
+  value: z.unknown().optional(),
+  oldValue: z.unknown().optional(),
+  newValue: z.unknown().optional()
+}).extend(ErrorResponseFields.shape);
+var PragmaTableInfoColumnSchema = z.object({
+  cid: z.number(),
+  name: z.string(),
+  type: z.string(),
+  notNull: z.boolean(),
+  defaultValue: z.unknown().nullable(),
+  pk: z.number()
+});
+var PragmaTableInfoOutputSchema = z.object({
+  success: z.boolean(),
+  table: z.string().optional(),
+  columns: z.array(PragmaTableInfoColumnSchema).optional()
+}).extend(ErrorResponseFields.shape);
+var AttachDatabaseOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  alias: z.string().optional(),
+  filepath: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var DetachDatabaseOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  alias: z.string().optional()
+}).extend(ErrorResponseFields.shape);
+var VacuumIntoCopyOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  outputPath: z.string().optional(),
+  sizeBytes: z.number().optional(),
+  durationMs: z.number().optional(),
+  wasmLimitation: z.boolean().optional()
+}).extend(ErrorResponseFields.shape);
+var ReindexSchema = z.object({
+  target: z.string().optional().describe(
+    "Index name, table name, or collation name to reindex. Omit to reindex the entire database."
+  )
+});
+var ReindexOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  sql: z.string().optional(),
+  durationMs: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+var WalSchema = z.object({
+  action: z.enum(["status", "enable", "disable", "checkpoint"]).describe(
+    "WAL action: 'status' = check journal_mode, 'enable' = switch to WAL, 'disable' = switch to DELETE (default journal mode), 'checkpoint' = force WAL checkpoint"
+  ),
+  checkpointMode: z.enum(["PASSIVE", "FULL", "RESTART", "TRUNCATE"]).optional().default("PASSIVE").describe(
+    "Checkpoint mode (only used with 'checkpoint' action). PASSIVE = checkpoint without blocking readers (default). FULL = wait for readers to finish. RESTART = same as FULL but restart WAL file. TRUNCATE = same as RESTART but truncate WAL file to zero bytes."
+  )
+});
+var WalOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  journalMode: z.string().optional(),
+  previousMode: z.string().optional(),
+  walPages: z.number().optional(),
+  checkpointedPages: z.number().optional()
+}).extend(ErrorResponseFields.shape);
+
+// src/utils/resource-annotations.ts
+var HIGH_PRIORITY = {
+  audience: ["user", "assistant"],
+  priority: 0.9
+};
+var MEDIUM_PRIORITY = {
+  audience: ["user", "assistant"],
+  priority: 0.6
+};
+var LOW_PRIORITY = {
+  audience: ["user", "assistant"],
+  priority: 0.4
+};
+var ASSISTANT_FOCUSED = {
+  audience: ["assistant"],
+  priority: 0.5
+};
+
+export { ASSISTANT_FOCUSED, AnalyzeOutputSchema, AnalyzeSchema, AttachDatabaseOutputSchema, AttachDatabaseSchema, AuditCleanupOutputSchema, AuditDiffBackupOutputSchema, AuditGetBackupOutputSchema, AuditListBackupsOutputSchema, AuditListBackupsSchema, AuditRestoreBackupOutputSchema, AuditSearchOutputSchema, AuditSearchSchema, BackupOutputSchema, BackupSchema, DetachDatabaseOutputSchema, DetachDatabaseSchema, ErrorResponseFields, HIGH_PRIORITY, IndexStatsOutputSchema, IndexStatsSchema, IntegrityCheckOutputSchema, IntegrityCheckSchema, LOW_PRIORITY, MEDIUM_PRIORITY, NAME, OptimizeOutputSchema, OptimizeSchema, PragmaCompileOptionsOutputSchema, PragmaCompileOptionsSchema, PragmaDatabaseListOutputSchema, PragmaDatabaseListSchema, PragmaOptimizeOutputSchema, PragmaOptimizeSchema, PragmaSettingsOutputSchema, PragmaSettingsSchema, PragmaTableInfoOutputSchema, PragmaTableInfoSchema, READ_ONLY, ReindexOutputSchema, ReindexSchema, RestoreOutputSchema, RestoreSchema, SENSITIVE_KEY_PATTERN, SERVER_ICONS, SqlDumpOutputSchema, SqlDumpSchema, VERSION, VacuumIntoCopyOutputSchema, VacuumIntoCopySchema, VacuumOutputSchema, VerifyBackupOutputSchema, VerifyBackupSchema, WalOutputSchema, WalSchema, admin, adminFs, assertSafeIoPath, buildProgressContext, buildWhereClause, createColumnList, destructive, estimateTokens, getRequiredScope, getToolGroupIcon, idempotent, parseAllowedIoRoots, readOnly, redactObject, registerToolScope, sanitizeIdentifier, sanitizeWhereClause, sendProgress, streamResultRows, toSDK, validateAggregateFunction, validateIdentifier, validateJsonPath, validateSameDirPath, write, writeFs };