@sigma4life/mysql-mcp-server 1.0.0

package/src/core/security/access-control.ts

@@ -0,0 +1,321 @@
+/**
+ * Access Control Validation for execute_query
+ *
+ * Validates SQL queries against access control configuration:
+ * - Database access (must be configured)
+ * - Table whitelist/blacklist
+ * - Column access (inclusion/exclusion modes)
+ * - SELECT * blocking
+ */
+
+import {
+  AccessControlConfig,
+  AccessViolation,
+  AccessControlError,
+  QualifiedTableRef,
+  QualifiedColumnRef,
+} from "./types.js";
+import { getTableConfigForSchema } from "./config-loader.js";
+import { parseQuery } from "../sql-parser.js";
+import { logger } from "../logger.js";
+
+/**
+ * Validate a query against access control configuration
+ * @throws AccessControlError if validation fails
+ */
+export function validateQueryAccess(
+  query: string,
+  database: string,
+  config: AccessControlConfig,
+): void {
+  const violations: AccessViolation[] = [];
+
+  // Step 1: Check if database is configured
+  const dbViolation = validateDatabaseAccess(database, config);
+  if (dbViolation) {
+    throw new AccessControlError([dbViolation]);
+  }
+
+  // Step 2: Parse the query
+  const parsed = parseQuery(query, database);
+  logger.debug(
+    `Parsed query info: tables=${parsed.tables.length}, columns=${parsed.columns.length}, hasSelectStar=${parsed.hasSelectStar}`,
+  );
+
+  // Step 3: Validate SELECT * usage
+  if (config.requireExplicitColumns && parsed.hasSelectStar) {
+    violations.push(...validateSelectStar(parsed.selectStarTables));
+  }
+
+  // Step 4: Validate table access
+  for (const table of parsed.tables) {
+    const tableViolation = validateTableAccess(table, config);
+    if (tableViolation) {
+      violations.push(tableViolation);
+    }
+  }
+
+  // Step 5: Validate column access (only if no SELECT *)
+  // If SELECT * is used, we can't know which columns will be returned
+  // so we already blocked it above
+  if (!parsed.hasSelectStar) {
+    for (const column of parsed.columns) {
+      const columnViolation = validateColumnAccess(column, config);
+      if (columnViolation) {
+        violations.push(columnViolation);
+      }
+    }
+  }
+
+  // Throw if any violations found
+  if (violations.length > 0) {
+    logger.warn(
+      `Access control violations: ${violations.map((v) => v.message).join("; ")}`,
+    );
+    throw new AccessControlError(violations);
+  }
+
+  logger.debug("Query passed access control validation");
+}
+
+/**
+ * Validate database is configured
+ */
+function validateDatabaseAccess(
+  database: string,
+  config: AccessControlConfig,
+): AccessViolation | null {
+  const dbUpper = database.toUpperCase();
+  if (!config.databases[dbUpper]) {
+    return {
+      type: "database_not_configured",
+      database,
+      message:
+        `Database '${database}' is not configured for query access. ` +
+        `Add it to QUERY_ACCESS_CONFIG to enable queries.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Validate SELECT * usage
+ */
+function validateSelectStar(selectStarTables: string[]): AccessViolation[] {
+  const violations: AccessViolation[] = [];
+
+  for (const tableRef of selectStarTables) {
+    if (tableRef === "*") {
+      violations.push({
+        type: "select_star",
+        message:
+          "SELECT * is not allowed. All SELECT statements must explicitly list columns. " +
+          "Example: SELECT name, email FROM customers",
+      });
+    } else {
+      violations.push({
+        type: "select_star",
+        table: tableRef,
+        message:
+          `SELECT ${tableRef}.* is not allowed. ` +
+          `Please specify columns explicitly instead of using table.* syntax.`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Validate table access against whitelist/blacklist
+ */
+function validateTableAccess(
+  table: QualifiedTableRef,
+  config: AccessControlConfig,
+): AccessViolation | null {
+  // Skip subquery pseudo-tables
+  if (table.schema === "__subquery__") {
+    return null;
+  }
+
+  // Skip CTE references (they're query-scoped aliases, not real tables)
+  if (table.schema === "__cte__") {
+    return null;
+  }
+
+  const schemaConfig = getTableConfigForSchema(
+    config,
+    table.database,
+    table.schema,
+  );
+
+  if (!schemaConfig) {
+    return {
+      type: "schema_not_configured",
+      database: table.database,
+      schema: table.schema,
+      table: table.table,
+      message:
+        `Schema '${table.schema}' in database '${table.database}' is not configured for query access. ` +
+        `Add schema rules to QUERY_ACCESS_CONFIG.`,
+    };
+  }
+
+  const { tableConfig } = schemaConfig;
+  const tableNameLower = table.table.toLowerCase();
+
+  // Check whitelist/blacklist
+  const listLower = tableConfig.list.map((t) => t.toLowerCase());
+
+  switch (tableConfig.mode) {
+    case "whitelist":
+      if (!listLower.includes(tableNameLower)) {
+        return {
+          type: "table_not_allowed",
+          database: table.database,
+          schema: table.schema,
+          table: table.table,
+          message:
+            `Table '${table.database}.${table.schema}.${table.table}' is not in the allowed tables list. ` +
+            `Allowed tables for ${table.database}.${table.schema}: ${tableConfig.list.join(", ") || "(none)"}`,
+        };
+      }
+      break;
+
+    case "blacklist":
+      if (listLower.includes(tableNameLower)) {
+        return {
+          type: "table_not_allowed",
+          database: table.database,
+          schema: table.schema,
+          table: table.table,
+          message:
+            `Table '${table.database}.${table.schema}.${table.table}' cannot be queried. ` +
+            `This table is in the exclusion list for database '${table.database}', schema '${table.schema}'.`,
+        };
+      }
+      break;
+
+    case "none":
+      // No table-level restrictions
+      break;
+  }
+
+  return null;
+}
+
+/**
+ * Validate column access against inclusion/exclusion rules
+ */
+function validateColumnAccess(
+  column: QualifiedColumnRef,
+  config: AccessControlConfig,
+): AccessViolation | null {
+  // Skip unknown table columns (can't validate)
+  if (column.table === "__unknown__") {
+    return null;
+  }
+
+  const schemaConfig = getTableConfigForSchema(
+    config,
+    column.database,
+    column.schema,
+  );
+  if (!schemaConfig) {
+    // Schema not configured - already caught in table validation
+    return null;
+  }
+
+  const { columnAccess } = schemaConfig;
+  const tableNameLower = column.table.toLowerCase();
+  const columnNameLower = column.column.toLowerCase();
+
+  // Find policy for this table (case-insensitive)
+  let policy = null;
+  let policyTableName = "";
+  for (const [table, tablePolicy] of Object.entries(columnAccess)) {
+    if (table.toLowerCase() === tableNameLower) {
+      policy = tablePolicy;
+      policyTableName = table;
+      break;
+    }
+  }
+
+  // No policy = allow all columns
+  if (!policy) {
+    return null;
+  }
+
+  const columnsLower = policy.columns.map((c) => c.toLowerCase());
+
+  if (policy.mode === "inclusion") {
+    // Whitelist: column must be in the list
+    if (!columnsLower.includes(columnNameLower)) {
+      return {
+        type: "column_not_allowed",
+        database: column.database,
+        schema: column.schema,
+        table: column.table,
+        column: column.column,
+        message:
+          `Column '${column.column}' from '${column.database}.${column.schema}.${column.table}' cannot be selected. ` +
+          `Allowed columns for ${policyTableName}: ${policy.columns.join(", ")}`,
+      };
+    }
+  } else {
+    // Blacklist: column must NOT be in the list
+    if (columnsLower.includes(columnNameLower)) {
+      return {
+        type: "column_excluded",
+        database: column.database,
+        schema: column.schema,
+        table: column.table,
+        column: column.column,
+        message:
+          `Column '${column.column}' from '${column.database}.${column.schema}.${column.table}' cannot be selected. ` +
+          `Excluded columns: ${policy.columns.join(", ")}`,
+      };
+    }
+  }
+
+  return null;
+}
+
+// Singleton config holder
+let globalConfig: AccessControlConfig | null = null;
+
+/**
+ * Initialize the global access control config
+ * Called once at startup from index.ts
+ */
+export function initAccessControl(config: AccessControlConfig): void {
+  globalConfig = config;
+  logger.info("Access control initialized");
+}
+
+/**
+ * Get the global access control config
+ * @throws Error if not initialized
+ */
+export function getAccessControlConfig(): AccessControlConfig {
+  if (!globalConfig) {
+    throw new Error(
+      "Access control not initialized. Ensure QUERY_ACCESS_CONFIG is set and valid.",
+    );
+  }
+  return globalConfig;
+}
+
+/**
+ * Check if access control is initialized
+ */
+export function isAccessControlInitialized(): boolean {
+  return globalConfig !== null;
+}
+
+// Re-export types for convenience
+export { AccessControlConfig, AccessControlError } from "./types.js";
+export {
+  loadAccessControlConfig,
+  getTableConfigForSchema,
+} from "./config-loader.js";

package/src/core/security/config-loader.ts

@@ -0,0 +1,315 @@
+/**
+ * Access Control Configuration Loader
+ *
+ * Loads configuration from JSON file specified by QUERY_ACCESS_CONFIG env var.
+ * Validates configuration structure and provides helpful error messages.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  AccessControlConfig,
+  DatabaseConfig,
+  TableConfig,
+  SchemaConfig,
+  ColumnAccessPolicy,
+} from './types.js';
+import { logger } from '../logger.js';
+
+// Environment variable for config file path
+const CONFIG_ENV_VAR = 'QUERY_ACCESS_CONFIG';
+
+/**
+ * Load and validate access control configuration
+ * @throws Error if config is invalid or missing (restrictive default)
+ */
+export function loadAccessControlConfig(): AccessControlConfig {
+  const configPath = process.env[CONFIG_ENV_VAR];
+
+  if (!configPath) {
+    throw new Error(
+      `Access control configuration not found. ` +
+        `Set ${CONFIG_ENV_VAR} environment variable to the path of your config file. ` +
+        `Example: ${CONFIG_ENV_VAR}=/path/to/query-access.json`
+    );
+  }
+
+  // Resolve path (handle relative paths)
+  const resolvedPath = path.resolve(configPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Access control config file not found at: ${resolvedPath}. ` +
+        `Create the config file or update ${CONFIG_ENV_VAR} to point to the correct location.`
+    );
+  }
+
+  logger.info(`Loading access control config from: ${resolvedPath}`);
+
+  let rawConfig: any;
+  try {
+    const content = fs.readFileSync(resolvedPath, 'utf-8');
+    rawConfig = JSON.parse(content);
+  } catch (error: any) {
+    throw new Error(`Failed to parse access control config: ${error.message}`);
+  }
+
+  // Validate and normalize the configuration
+  const config = validateConfig(rawConfig);
+
+  logger.info(
+    `Access control config loaded: ${Object.keys(config.databases).length} database(s) configured`
+  );
+
+  return config;
+}
+
+/**
+ * Validate configuration structure
+ */
+function validateConfig(raw: any): AccessControlConfig {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error('Access control config must be a JSON object');
+  }
+
+  // Validate requireExplicitColumns
+  if (typeof raw.requireExplicitColumns !== 'boolean') {
+    throw new Error("Access control config must have 'requireExplicitColumns' (boolean)");
+  }
+
+  // Validate databases
+  if (typeof raw.databases !== 'object' || raw.databases === null) {
+    throw new Error("Access control config must have 'databases' object");
+  }
+
+  const databases: Record<string, DatabaseConfig> = {};
+
+  for (const [dbName, dbConfig] of Object.entries(raw.databases)) {
+    databases[dbName.toUpperCase()] = validateDatabaseConfig(dbName, dbConfig);
+  }
+
+  return {
+    requireExplicitColumns: raw.requireExplicitColumns,
+    databases,
+  };
+}
+
+/**
+ * Validate database configuration
+ */
+function validateDatabaseConfig(dbName: string, raw: any): DatabaseConfig {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error(`Database config for '${dbName}' must be an object`);
+  }
+
+  // Error on deprecated columnExclusions format
+  if (raw.columnExclusions) {
+    throw new Error(
+      `Database '${dbName}' uses deprecated 'columnExclusions' format. ` +
+        `Please migrate to 'columnAccess' with { mode: 'exclusion' | 'inclusion', columns: [...] } per table. ` +
+        `See documentation for the new format.`
+    );
+  }
+
+  const result: DatabaseConfig = {};
+
+  // Check for schema-level config (full format)
+  if (raw.schemas) {
+    if (typeof raw.schemas !== 'object') {
+      throw new Error(`'schemas' in database '${dbName}' must be an object`);
+    }
+
+    result.schemas = {};
+    for (const [schemaName, schemaConfig] of Object.entries(raw.schemas)) {
+      result.schemas[schemaName.toLowerCase()] = validateSchemaConfig(
+        dbName,
+        schemaName,
+        schemaConfig
+      );
+    }
+  }
+
+  // Check for compact format (tables at database level)
+  if (raw.tables) {
+    result.tables = validateTableConfig(dbName, '_default_', raw.tables);
+  }
+
+  // Must have either schemas or tables
+  if (!result.schemas && !result.tables) {
+    throw new Error(
+      `Database '${dbName}' must have either 'schemas' or 'tables' configuration`
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Validate schema configuration
+ */
+function validateSchemaConfig(dbName: string, schemaName: string, raw: any): SchemaConfig {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error(`Schema config for '${dbName}.${schemaName}' must be an object`);
+  }
+
+  if (!raw.tables) {
+    throw new Error(`Schema '${dbName}.${schemaName}' must have 'tables' configuration`);
+  }
+
+  return {
+    tables: validateTableConfig(dbName, schemaName, raw.tables),
+  };
+}
+
+/**
+ * Validate table configuration
+ */
+function validateTableConfig(dbName: string, schemaName: string, raw: any): TableConfig {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error(`Table config for '${dbName}.${schemaName}' must be an object`);
+  }
+
+  // Error on deprecated columnExclusions format
+  if (raw.columnExclusions) {
+    throw new Error(
+      `Table config for '${dbName}.${schemaName}' uses deprecated 'columnExclusions' format. ` +
+        `Please migrate to 'columnAccess' with { mode: 'exclusion' | 'inclusion', columns: [...] } per table. ` +
+        `See documentation for the new format.`
+    );
+  }
+
+  // Validate mode
+  const validModes = ['whitelist', 'blacklist', 'none'];
+  if (!validModes.includes(raw.mode)) {
+    throw new Error(
+      `Table mode for '${dbName}.${schemaName}' must be one of: ${validModes.join(', ')}`
+    );
+  }
+
+  // Validate list
+  if (!Array.isArray(raw.list)) {
+    throw new Error(`Table list for '${dbName}.${schemaName}' must be an array`);
+  }
+
+  const list = raw.list.map((t: any) => {
+    if (typeof t !== 'string') {
+      throw new Error(`Table list for '${dbName}.${schemaName}' must contain only strings`);
+    }
+    return t; // Keep original case for display, but compare case-insensitively
+  });
+
+  const result: TableConfig = {
+    mode: raw.mode as 'whitelist' | 'blacklist' | 'none',
+    list,
+  };
+
+  // Optional column access policies
+  if (raw.columnAccess) {
+    result.columnAccess = validateColumnAccess(`${dbName}.${schemaName}`, raw.columnAccess);
+  }
+
+  return result;
+}
+
+/**
+ * Validate column access policies
+ */
+function validateColumnAccess(
+  context: string,
+  raw: any
+): Record<string, ColumnAccessPolicy> {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error(`Column access for '${context}' must be an object`);
+  }
+
+  const result: Record<string, ColumnAccessPolicy> = {};
+
+  for (const [tableName, policy] of Object.entries(raw)) {
+    if (typeof policy !== 'object' || policy === null) {
+      throw new Error(
+        `Column access for '${context}.${tableName}' must be an object with 'mode' and 'columns'`
+      );
+    }
+
+    const p = policy as any;
+
+    // Validate mode
+    const validModes = ['inclusion', 'exclusion'];
+    if (!validModes.includes(p.mode)) {
+      throw new Error(
+        `Column access mode for '${context}.${tableName}' must be 'inclusion' or 'exclusion'`
+      );
+    }
+
+    // Validate columns
+    if (!Array.isArray(p.columns)) {
+      throw new Error(`Column access for '${context}.${tableName}' must have 'columns' array`);
+    }
+
+    const columns = p.columns.map((c: any) => {
+      if (typeof c !== 'string') {
+        throw new Error(
+          `Column access for '${context}.${tableName}' columns must contain only strings`
+        );
+      }
+      return c;
+    });
+
+    result[tableName] = {
+      mode: p.mode as 'inclusion' | 'exclusion',
+      columns,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Get the effective table config for a database/schema combination
+ */
+export function getTableConfigForSchema(
+  config: AccessControlConfig,
+  database: string,
+  schema: string
+): { tableConfig: TableConfig; columnAccess: Record<string, ColumnAccessPolicy> } | null {
+  const dbConfig = config.databases[database.toUpperCase()];
+  if (!dbConfig) {
+    return null;
+  }
+
+  const schemaLower = schema.toLowerCase();
+
+  // Check schema-level config first
+  if (dbConfig.schemas) {
+    // Try exact match
+    if (dbConfig.schemas[schemaLower]) {
+      const schemaConfig = dbConfig.schemas[schemaLower];
+      return {
+        tableConfig: schemaConfig.tables,
+        columnAccess: schemaConfig.tables.columnAccess || {},
+      };
+    }
+
+    // Try wildcard
+    if (dbConfig.schemas['*']) {
+      const schemaConfig = dbConfig.schemas['*'];
+      return {
+        tableConfig: schemaConfig.tables,
+        columnAccess: schemaConfig.tables.columnAccess || {},
+      };
+    }
+
+    // No matching schema config
+    return null;
+  }
+
+  // Use compact format (database-level tables config)
+  if (dbConfig.tables) {
+    return {
+      tableConfig: dbConfig.tables,
+      columnAccess: dbConfig.tables.columnAccess || {},
+    };
+  }
+
+  return null;
+}