@aifabrix/builder 2.42.1 → 2.43.0

package/lib/commands/service-user.js

@@ -12,7 +12,14 @@ const logger = require('../utils/logger');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
 const { normalizeControllerUrl } = require('../core/config');
-const { createServiceUser } = require('../api/service-users.api');
+const {
+  createServiceUser,
+  listServiceUsers,
+  regenerateSecretServiceUser,
+  deleteServiceUser,
+  updateGroupsServiceUser,
+  updateRedirectUrisServiceUser
+} = require('../api/service-users.api');
 
 const ONE_TIME_WARNING =
   'Save this secret now; it will not be shown again.';
@@ -54,6 +61,12 @@ function extractCreateResponse(response) {
   return { clientId, clientSecret };
 }
 
+const ID_WIDTH = 38;
+const USERNAME_WIDTH = 22;
+const EMAIL_WIDTH = 28;
+const CLIENT_ID_WIDTH = 24;
+const TABLE_SEPARATOR_LENGTH = 130;
+
 /**
  * Log error for failed create response and exit
  * @param {Object} response - API response with success: false
@@ -74,6 +87,86 @@ function handleCreateError(response) {
   process.exit(1);
 }
 
+/**
+ * Log error for service-user API response and exit
+ * @param {Object} response - API response with success: false
+ * @param {string} permissionScope - Permission hint: 'read' | 'update' | 'delete'
+ */
+function handleServiceUserApiError(response, permissionScope) {
+  const status = response.status;
+  const msg = response.formattedError || response.error || 'Request failed';
+  if (status === 400) {
+    logger.error(chalk.red(`❌ Validation error: ${msg}`));
+  } else if (status === 401) {
+    logger.error(chalk.red('❌ Unauthorized. Run "aifabrix login" and try again.'));
+  } else if (status === 403) {
+    logger.error(chalk.red(`❌ Missing permission: service-user:${permissionScope}`));
+    logger.error(chalk.gray(`Your account needs the service-user:${permissionScope} permission on the controller.`));
+  } else if (status === 404) {
+    logger.error(chalk.red('❌ Service user not found.'));
+    const detail = response.error || '';
+    if (detail) {
+      logger.error(chalk.gray(detail));
+    }
+  } else {
+    logger.error(chalk.red(`❌ Request failed: ${msg}`));
+  }
+  process.exit(1);
+}
+
+/**
+ * Resolve controller URL and auth for list/rotate/delete/update (no create-specific validation)
+ * @async
+ * @param {Object} options - CLI options (controller optional)
+ * @returns {Promise<{ controllerUrl: string, authConfig: Object }>}
+ */
+async function resolveControllerAndAuth(options) {
+  const controllerUrl = options.controller || (await resolveControllerUrl());
+  if (!controllerUrl) {
+    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" first.'));
+    process.exit(1);
+  }
+  const authResult = await getServiceUserAuth(controllerUrl);
+  if (!authResult || !authResult.token) {
+    logger.error(chalk.red(`❌ No authentication token for controller: ${controllerUrl}`));
+    logger.error(chalk.gray('Run: aifabrix login'));
+    process.exit(1);
+  }
+  return {
+    controllerUrl: authResult.controllerUrl,
+    authConfig: { type: 'bearer', token: authResult.token }
+  };
+}
+
+/**
+ * Display service user list as a table (id, username, email, clientId, active).
+ * API shape: items have id, username, email, status, federatedIdentity.keycloakClientId.
+ * @param {Array<{ id?: string, username?: string, email?: string, status?: string, active?: boolean, clientId?: string, federatedIdentity?: { keycloakClientId?: string } }>} items - Service users
+ */
+function displayServiceUserList(items) {
+  logger.log(chalk.bold('\n📋 Service users:\n'));
+  if (!items || items.length === 0) {
+    logger.log(chalk.gray('  No service users found.\n'));
+    return;
+  }
+  const idCol = 'Id'.padEnd(ID_WIDTH);
+  const usernameCol = 'Username'.padEnd(USERNAME_WIDTH);
+  const emailCol = 'Email'.padEnd(EMAIL_WIDTH);
+  const clientIdCol = 'ClientId'.padEnd(CLIENT_ID_WIDTH);
+  const activeCol = 'Active';
+  logger.log(chalk.gray(`${idCol}${usernameCol}${emailCol}${clientIdCol}${activeCol}`));
+  logger.log(chalk.gray('-'.repeat(TABLE_SEPARATOR_LENGTH)));
+  items.forEach((row) => {
+    const id = (row.id ?? '').toString().padEnd(ID_WIDTH);
+    const username = (row.username ?? '—').padEnd(USERNAME_WIDTH);
+    const email = (row.email ?? '—').padEnd(EMAIL_WIDTH);
+    const clientId = (row.federatedIdentity?.keycloakClientId ?? row.clientId ?? '—').padEnd(CLIENT_ID_WIDTH);
+    const active = row.status === 'active' ? 'yes' : (row.status ?? (row.active === true ? 'yes' : row.active === false ? 'no' : '—'));
+    logger.log(`${id}${username}${email}${clientId}${active}`);
+  });
+  logger.log('');
+}
+
 /**
  * Display success output with clientId, clientSecret and one-time warning
  * @param {string} clientId - Service user client ID
@@ -194,6 +287,142 @@ async function runServiceUserCreate(options = {}) {
   displayCreateSuccess(clientId, clientSecret);
 }
 
+/**
+ * Require service user id option; exit with message if missing
+ * @param {string} [id] - Service user ID from options
+ * @returns {string} Trimmed id
+ */
+function requireServiceUserId(id) {
+  const trimmed = (id && typeof id === 'string' ? id.trim() : '') || '';
+  if (!trimmed) {
+    logger.error(chalk.red('❌ Service user ID is required. Use --id <uuid>.'));
+    process.exit(1);
+  }
+  return trimmed;
+}
+
+/**
+ * Run service-user list: call GET /api/v1/service-users and display table
+ * @async
+ * @param {Object} options - CLI options (controller, page, pageSize, sort, filter, search)
+ * @returns {Promise<void>}
+ */
+async function runServiceUserList(options = {}) {
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+  const listOptions = {
+    page: options.page,
+    pageSize: options.pageSize,
+    sort: options.sort,
+    filter: options.filter,
+    search: options.search
+  };
+  const response = await listServiceUsers(controllerUrl, authConfig, listOptions);
+  if (response && response.success === false) {
+    handleServiceUserApiError(response, 'read');
+    return;
+  }
+  const body = response?.data?.data ?? response?.data ?? response ?? {};
+  const items = Array.isArray(body) ? body : (body.data ?? []);
+  displayServiceUserList(items);
+}
+
+/**
+ * Run service-user rotate-secret: call POST .../regenerate-secret and print new secret once with warning
+ * @async
+ * @param {Object} options - CLI options (controller, id required)
+ * @returns {Promise<void>}
+ */
+async function runServiceUserRotateSecret(options = {}) {
+  const id = requireServiceUserId(options.id);
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+  const response = await regenerateSecretServiceUser(controllerUrl, authConfig, id);
+  if (response && response.success === false) {
+    handleServiceUserApiError(response, 'update');
+    return;
+  }
+  const payload = response?.data?.data ?? response?.data ?? response ?? {};
+  const clientSecret = payload?.clientSecret ?? '';
+  if (response && response.success === true) {
+    logger.log(chalk.bold('\n✓ Secret rotated\n'));
+    logger.log(chalk.cyan('  clientSecret: ') + clientSecret);
+    logger.log('');
+    logger.log(chalk.yellow('⚠ ' + ONE_TIME_WARNING));
+    logger.log('');
+  }
+}
+
+/**
+ * Run service-user delete: call DELETE .../service-users/{id} (deactivates the user)
+ * @async
+ * @param {Object} options - CLI options (controller, id required)
+ * @returns {Promise<void>}
+ */
+async function runServiceUserDelete(options = {}) {
+  const id = requireServiceUserId(options.id);
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+  const response = await deleteServiceUser(controllerUrl, authConfig, id);
+  if (response && response.success === false) {
+    handleServiceUserApiError(response, 'delete');
+    return;
+  }
+  if (response && response.success === true) {
+    logger.log(chalk.green('✓ Service user deactivated.\n'));
+  }
+}
+
+/**
+ * Run service-user update-groups: call PUT .../groups with groupNames
+ * @async
+ * @param {Object} options - CLI options (controller, id, groupNames required)
+ * @returns {Promise<void>}
+ */
+async function runServiceUserUpdateGroups(options = {}) {
+  const id = requireServiceUserId(options.id);
+  const groupNames = parseList(options.groupNames);
+  if (groupNames.length === 0) {
+    logger.error(chalk.red('❌ At least one group name is required. Use --group-names <name1,name2,...>.'));
+    process.exit(1);
+  }
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+  const response = await updateGroupsServiceUser(controllerUrl, authConfig, id, { groupNames });
+  if (response && response.success === false) {
+    handleServiceUserApiError(response, 'update');
+    return;
+  }
+  if (response && response.success === true) {
+    logger.log(chalk.green('✓ Service user groups updated.\n'));
+  }
+}
+
+/**
+ * Run service-user update-redirect-uris: call PUT .../redirect-uris (min 1 URI)
+ * @async
+ * @param {Object} options - CLI options (controller, id, redirectUris required, min 1)
+ * @returns {Promise<void>}
+ */
+async function runServiceUserUpdateRedirectUris(options = {}) {
+  const id = requireServiceUserId(options.id);
+  const redirectUris = parseList(options.redirectUris);
+  if (redirectUris.length === 0) {
+    logger.error(chalk.red('❌ At least one redirect URI is required. Use --redirect-uris <uri1,uri2,...>.'));
+    process.exit(1);
+  }
+  const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+  const response = await updateRedirectUrisServiceUser(controllerUrl, authConfig, id, { redirectUris });
+  if (response && response.success === false) {
+    handleServiceUserApiError(response, 'update');
+    return;
+  }
+  if (response && response.success === true) {
+    logger.log(chalk.green('✓ Service user redirect URIs updated.\n'));
+  }
+}
+
 module.exports = {
-  runServiceUserCreate
+  runServiceUserCreate,
+  runServiceUserList,
+  runServiceUserRotateSecret,
+  runServiceUserDelete,
+  runServiceUserUpdateGroups,
+  runServiceUserUpdateRedirectUris
 };

package/lib/commands/up-common.js

@@ -165,6 +165,30 @@ function patchEnvOutputPathForDeployOnly(appName) {
   }
 }
 
+/**
+ * Removes builder app directories for the given app names. Only removes paths under the builder root
+ * to prevent path traversal. Uses getBuilderPath for each app and validates before removal.
+ *
+ * @param {string[]} appNames - Application names (e.g. ['keycloak', 'miso-controller', 'dataplane'])
+ * @returns {Promise<void>}
+ * @throws {Error} If any path is outside builder root (path traversal attempt)
+ */
+async function cleanBuilderAppDirs(appNames) {
+  if (!Array.isArray(appNames) || appNames.length === 0) return;
+  const builderRoot = path.resolve(pathsUtil.getBuilderRoot());
+  for (const appName of appNames) {
+    if (!appName || typeof appName !== 'string') continue;
+    const appPath = path.resolve(pathsUtil.getBuilderPath(appName));
+    if (!appPath.startsWith(builderRoot + path.sep) && appPath !== builderRoot) {
+      throw new Error(`Path ${appPath} is outside builder root ${builderRoot}; refusing to clean`);
+    }
+    if (fs.existsSync(appPath)) {
+      fs.rmSync(appPath, { recursive: true });
+      logger.log(chalk.blue(`Cleaned builder/${appName}`));
+    }
+  }
+}
+
 /**
  * Ensures builder app directory exists from template if application config is missing.
  * If builder/<appName>/application config does not exist, copies from templates/applications/<appName>.
@@ -206,6 +230,7 @@ async function ensureAppFromTemplate(appName) {
 }
 
 module.exports = {
+  cleanBuilderAppDirs,
   ensureAppFromTemplate,
   patchEnvOutputPathForDeployOnly,
   validateEnvOutputPathFolderOrNull,

package/lib/commands/up-dataplane.js

@@ -80,7 +80,7 @@ async function resolveControllerUrlWithHealthCheck() {
   logger.log(chalk.yellow(`\nController at ${controllerUrl} is not responding (health check failed).\n`));
   const newUrl = await promptForControllerUrl(controllerUrl);
   if (!newUrl) {
-    throw new Error('Controller URL is required. Run "aifabrix up-dataplane" again and enter a valid controller URL, or set it with: aifabrix auth config --set-controller <url>');
+    throw new Error('Controller URL is required. Run "aifabrix up-dataplane" again and enter a valid controller URL, or set it with: aifabrix auth --set-controller <url>');
   }
 
   try {
@@ -179,7 +179,7 @@ async function handleUpDataplane(options = {}) {
   const environment = (cfg && cfg.environment) ? cfg.environment : 'dev';
   if (environment !== 'dev') {
     throw new Error(
-      'Dataplane is only supported in dev environment. Set with: aifabrix auth config --set-environment dev.'
+      'Dataplane is only supported in dev environment. Set with: aifabrix auth --set-environment dev.'
     );
   }
   logger.log(chalk.green('✓ Logged in and environment is dev'));

package/lib/core/admin-secrets.js

@@ -14,6 +14,7 @@ const path = require('path');
 const fs = require('fs');
 const config = require('./config');
 const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
+const { ensureSecureFilePermissions } = require('../utils/secure-file-permissions');
 
 /**
  * Parse .env-style content into key-value map (excludes comments and empty lines).
@@ -57,6 +58,7 @@ async function readAndDecryptAdminSecrets(adminSecretsPath) {
   if (!fs.existsSync(resolvedPath)) {
     throw new Error(`Admin secrets file not found: ${resolvedPath}. Run 'aifabrix up-infra' or ensure admin-secrets.env exists.`);
   }
+  ensureSecureFilePermissions(resolvedPath);
   const content = fs.readFileSync(resolvedPath, 'utf8');
   const raw = parseAdminEnvContent(content);
   const encryptionKey = await config.getSecretsEncryptionKey();

package/lib/core/config.js

@@ -13,6 +13,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const os = require('os');
 const { encryptToken, decryptToken, isTokenEncrypted } = require('../utils/token-encryption');
+const { ensureSecureFilePermissions, ensureSecureDirPermissions } = require('../utils/secure-file-permissions');
 // Avoid importing paths here to prevent circular dependency.
 // Config location (first match wins):
 //   1. AIFABRIX_CONFIG env = full path to config.yaml
@@ -111,7 +112,7 @@ function applyConfigDefaults(config) {
     config.device = {};
   }
   // Ensure controller field exists (but don't set defaults)
-  // It will be set by login or auth config commands
+  // It will be set by login or auth --set-controller
   return config;
 }
 
@@ -133,6 +134,8 @@ function getDefaultConfig() {
 
 async function getConfig() {
   try {
+    ensureSecureDirPermissions(RUNTIME_CONFIG_DIR);
+    ensureSecureFilePermissions(RUNTIME_CONFIG_FILE);
     const configContent = await fs.readFile(RUNTIME_CONFIG_FILE, 'utf8');
     let config = yaml.load(configContent);
 
@@ -233,6 +236,7 @@ async function getDeveloperId() {
  */
 async function verifyDeveloperIdSaved(devIdString) {
   await new Promise(resolve => setTimeout(resolve, 100));
+  ensureSecureFilePermissions(RUNTIME_CONFIG_FILE);
   const savedContent = await fs.readFile(RUNTIME_CONFIG_FILE, 'utf8');
   const savedConfig = yaml.load(savedContent);
   const savedDevIdString = String(savedConfig['developer-id']);
@@ -427,11 +431,11 @@ async function getSecretsPath() {
 }
 
 async function setSecretsPath(secretsPath) {
-  if (!secretsPath || typeof secretsPath !== 'string') {
+  if (typeof secretsPath !== 'string') {
     throw new Error('Secrets path is required and must be a string');
   }
   const config = await getConfig();
-  config['aifabrix-secrets'] = secretsPath;
+  config['aifabrix-secrets'] = secretsPath.trim() || undefined;
   await saveConfig(config);
 }
 
@@ -489,10 +493,8 @@ Object.assign(exportsObj, tokenFunctions);
 const { createPathConfigFunctions } = require('../utils/config-paths');
 const pathConfigFunctions = createPathConfigFunctions(getConfig, saveConfig);
 Object.assign(exportsObj, pathConfigFunctions);
-
 // Format preference functions
 const { createFormatFunctions } = require('../utils/config-format-preference');
 const formatFunctions = createFormatFunctions(getConfig, saveConfig);
 Object.assign(exportsObj, formatFunctions);
-
 module.exports = exportsObj;

package/lib/core/ensure-encryption-key.js

@@ -12,7 +12,6 @@ const fs = require('fs');
 const yaml = require('js-yaml');
 const crypto = require('crypto');
 const pathsUtil = require('../utils/paths');
-const { saveLocalSecret } = require('../utils/local-secrets');
 
 const ENCRYPTION_KEY = 'secrets-encryptionKeyVault';
 
@@ -30,7 +29,7 @@ function readKeyFromFile(filePath) {
 
 /**
  * Ensure secrets encryption key exists. If config already has it, do nothing.
- * If key exists in user or project secrets file, set config. Otherwise generate, write to user secrets, set config.
+ * If key exists in user or project secrets file, set config. Otherwise generate and store only in config (not in secrets file).
  * @param {Object} config - Config module (getSecretsEncryptionKey, setSecretsEncryptionKey, getSecretsPath)
  * @returns {Promise<void>}
  */
@@ -49,7 +48,6 @@ async function ensureSecretsEncryptionKey(config) {
   }
 
   const newKey = crypto.randomBytes(32).toString('hex');
-  await saveLocalSecret(ENCRYPTION_KEY, newKey);
   await config.setSecretsEncryptionKey(newKey);
 }
 

package/lib/core/secrets.js

@@ -52,6 +52,7 @@ const {
 } = require('../utils/secrets-utils');
 const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
 const pathsUtil = require('../utils/paths');
+const { ensureSecureFilePermissions } = require('../utils/secure-file-permissions');
 
 /**
  * Generates a canonical secret name from an environment variable key.
@@ -150,6 +151,7 @@ function mergeUserWithConfigFile(userSecrets, resolvedConfigPath) {
   if (!fs.existsSync(resolvedConfigPath)) {
     return null;
   }
+  ensureSecureFilePermissions(resolvedConfigPath);
   let configSecrets;
   try {
     configSecrets = readYamlAtPath(resolvedConfigPath);
@@ -225,6 +227,7 @@ async function loadSecretsWithFallbacks() {
     if (projectRoot) {
       const builderPath = path.join(projectRoot, 'builder', 'secrets.local.yaml');
       if (fs.existsSync(builderPath)) {
+        ensureSecureFilePermissions(builderPath);
         const builderSecrets = mergeUserWithConfigFile(merged || {}, builderPath);
         if (builderSecrets) merged = builderSecrets;
       }
@@ -244,6 +247,7 @@ async function loadSecrets(secretsPath, _appName) {
     if (!fs.existsSync(resolvedPath)) {
       throw new Error(`Secrets file not found: ${resolvedPath}`);
     }
+    ensureSecureFilePermissions(resolvedPath);
     const explicitSecrets = readYamlAtPath(resolvedPath);
     if (!explicitSecrets || typeof explicitSecrets !== 'object') {
       throw new Error(`Invalid secrets file format: ${resolvedPath}`);
@@ -516,6 +520,24 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   return envPath;
 }
 
+/**
+ * Writes admin env key-value pairs to content; encrypts values when encryption key is set.
+ * @async
+ * @param {Object.<string, string>} adminObj - Key-value object (e.g. POSTGRES_PASSWORD, ...)
+ * @returns {Promise<string>} .env-style content (plaintext or secure:// for secrets)
+ */
+async function formatAdminSecretsContent(adminObj) {
+  const encryptionKey = await config.getSecretsEncryptionKey();
+  const { encryptSecret } = require('../utils/secrets-encryption');
+  const lines = ['# Infrastructure Admin Credentials'];
+  for (const [k, v] of Object.entries(adminObj)) {
+    const value = (v === null || v === undefined) ? '' : String(v).replace(/\n/g, ' ').trim();
+    const valueToWrite = encryptionKey ? encryptSecret(value, encryptionKey) : value;
+    lines.push(`${k}=${valueToWrite}`);
+  }
+  return lines.join('\n');
+}
+
 /** Generates admin secrets for infrastructure (~/.aifabrix/admin-secrets.env). Uses admin123 when no postgres password. */
 async function generateAdminSecretsEnv(secretsPath) {
   let secrets;
@@ -541,15 +563,15 @@ async function generateAdminSecretsEnv(secretsPath) {
   const raw = secrets['postgres-passwordKeyVault'];
   const postgresPassword = (raw && String(raw).trim()) || 'admin123';
 
-  const adminSecrets = `# Infrastructure Admin Credentials
-POSTGRES_PASSWORD=${postgresPassword}
-PGADMIN_DEFAULT_EMAIL=admin@aifabrix.dev
-PGADMIN_DEFAULT_PASSWORD=${postgresPassword}
-REDIS_HOST=local:redis:6379:0:
-REDIS_COMMANDER_USER=admin
-REDIS_COMMANDER_PASSWORD=${postgresPassword}
-`;
-
+  const adminObj = {
+    POSTGRES_PASSWORD: postgresPassword,
+    PGADMIN_DEFAULT_EMAIL: 'admin@aifabrix.dev',
+    PGADMIN_DEFAULT_PASSWORD: postgresPassword,
+    REDIS_HOST: 'local:redis:6379:0:',
+    REDIS_COMMANDER_USER: 'admin',
+    REDIS_COMMANDER_PASSWORD: postgresPassword
+  };
+  const adminSecrets = await formatAdminSecretsContent(adminObj);
   fs.writeFileSync(adminEnvPath, adminSecrets, { mode: 0o600 });
   return adminEnvPath;
 }
@@ -560,6 +582,7 @@ module.exports = {
   generateEnvContent,
   generateMissingSecrets,
   generateAdminSecretsEnv,
+  formatAdminSecretsContent,
   validateSecrets,
   createDefaultSecrets,
   getCanonicalSecretName,

package/lib/core/templates.js

@@ -268,7 +268,7 @@ function generateSecretsYaml(config, existingSecrets = {}) {
   Object.entries(existingSecrets).forEach(([key, value]) => {
     secrets.data[key] = Buffer.from(value).toString('base64');
   });
-  return yaml.dump(secrets, { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false });
+  return yaml.dump(secrets, { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false });
 }
 
 module.exports = {

package/lib/datasource/abac-validator.js

@@ -0,0 +1,157 @@
+/**
+ * ABAC (Attribute-Based Access Control) validator for external datasources.
+ *
+ * Validates config.abac.dimensions (dimension-to-attribute references),
+ * config.abac.crossSystemJson (allowed operators, one per path, value types),
+ * and errors on legacy config.abac.crossSystem.
+ *
+ * @fileoverview ABAC validation for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const DIMENSION_KEY_PATTERN = /^[a-zA-Z0-9_]+$/;
+const ATTRIBUTE_PATH_PATTERN = /^[a-zA-Z0-9_.]+$/;
+const CROSS_SYSTEM_JSON_PATH_PATTERN = /^[a-zA-Z0-9_.]+$/;
+const ALLOWED_CROSS_SYSTEM_OPERATORS = new Set([
+  'eq', 'ne', 'gt', 'lt', 'gte', 'lte', 'in', 'nin', 'contains', 'like', 'isNull', 'isNotNull'
+]);
+
+/**
+ * Validates dimension keys and attribute path values for a dimensions object.
+ *
+ * @param {Object} dimensions - Object mapping dimension keys to attribute paths
+ * @param {string} source - Label for error messages (e.g. "config.abac.dimensions")
+ * @param {Set<string>} validAttributeNames - Set of valid attribute names (from fieldMappings.attributes)
+ * @returns {string[]} Error messages
+ */
+function validateDimensionsObject(dimensions, source, validAttributeNames) {
+  const errors = [];
+  if (!dimensions || typeof dimensions !== 'object' || Array.isArray(dimensions)) {
+    return errors;
+  }
+  for (const [dimKey, attrPath] of Object.entries(dimensions)) {
+    if (!DIMENSION_KEY_PATTERN.test(dimKey)) {
+      errors.push(
+        `${source}: dimension key '${dimKey}' must contain only letters, numbers, and underscores. Add '${dimKey}' to fieldMappings.attributes or fix the key.`
+      );
+    }
+    if (typeof attrPath !== 'string' || !ATTRIBUTE_PATH_PATTERN.test(attrPath)) {
+      errors.push(
+        `${source}: attribute path for dimension '${dimKey}' must be a string with letters, numbers, underscores, and dots only.`
+      );
+    } else if (validAttributeNames && validAttributeNames.size > 0) {
+      const normalizedName = attrPath.includes('.') ? attrPath.split('.').pop() : attrPath;
+      if (!validAttributeNames.has(attrPath) && !validAttributeNames.has(normalizedName)) {
+        errors.push(
+          `${source}: dimension '${dimKey}' maps to '${attrPath}' which is not in fieldMappings.attributes. Add the attribute or remove from dimensions.`
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Validates crossSystemJson: path format, exactly one operator per path, allowed operators and value types.
+ *
+ * @param {Object} crossSystemJson - Object mapping field paths to operator objects
+ * @returns {string[]} Error messages
+ */
+function validateCrossSystemJson(crossSystemJson) {
+  const errors = [];
+  if (!crossSystemJson || typeof crossSystemJson !== 'object' || Array.isArray(crossSystemJson)) {
+    return errors;
+  }
+  for (const [path, opObj] of Object.entries(crossSystemJson)) {
+    if (!CROSS_SYSTEM_JSON_PATH_PATTERN.test(path)) {
+      errors.push(
+        `config.abac.crossSystemJson: path '${path}' must contain only letters, numbers, underscores, and dots.`
+      );
+      continue;
+    }
+    if (typeof opObj !== 'object' || opObj === null || Array.isArray(opObj)) {
+      errors.push(
+        `config.abac.crossSystemJson.${path}: value must be an object with exactly one operator (e.g. { "eq": "user.country" }).`
+      );
+      continue;
+    }
+    const keys = Object.keys(opObj);
+    if (keys.length === 0) {
+      errors.push(
+        `config.abac.crossSystemJson.${path}: object must have exactly one operator. Allowed: ${[...ALLOWED_CROSS_SYSTEM_OPERATORS].join(', ')}.`
+      );
+    } else if (keys.length > 1) {
+      errors.push(
+        `config.abac.crossSystemJson.${path}: must have exactly one operator per path, got ${keys.join(', ')}. Use one of: ${[...ALLOWED_CROSS_SYSTEM_OPERATORS].join(', ')}.`
+      );
+    } else {
+      const op = keys[0];
+      if (!ALLOWED_CROSS_SYSTEM_OPERATORS.has(op)) {
+        errors.push(
+          `config.abac.crossSystemJson.${path}: unknown operator '${op}'. Allowed: ${[...ALLOWED_CROSS_SYSTEM_OPERATORS].join(', ')}.`
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Validates ABAC configuration for a parsed datasource.
+ * Checks dimensions (from config.abac or fieldMappings), crossSystemJson, and rejects legacy crossSystem.
+ *
+ * @function validateAbac
+ * @param {Object} parsed - Parsed datasource object (after JSON parse)
+ * @returns {string[]} Array of error messages; empty if valid
+ *
+ * @example
+ * const errors = validateAbac(parsed);
+ * if (errors.length > 0) errors.forEach(e => console.error(e));
+ */
+function validateAbac(parsed) {
+  const errors = [];
+  const abac = parsed?.config?.abac;
+  if (!abac || typeof abac !== 'object') {
+    return errors;
+  }
+
+  if ('crossSystem' in abac) {
+    errors.push(
+      'config.abac.crossSystem is deprecated. Use config.abac.crossSystemJson or config.abac.crossSystemSql instead.'
+    );
+  }
+
+  const attributeNames = new Set(
+    Object.keys(parsed?.fieldMappings?.attributes ?? {})
+  );
+
+  if (abac.dimensions) {
+    errors.push(...validateDimensionsObject(
+      abac.dimensions,
+      'config.abac.dimensions',
+      attributeNames
+    ));
+  }
+
+  const fieldMappingsDimensions = parsed?.fieldMappings?.dimensions;
+  if (fieldMappingsDimensions && typeof fieldMappingsDimensions === 'object') {
+    errors.push(...validateDimensionsObject(
+      fieldMappingsDimensions,
+      'fieldMappings.dimensions',
+      attributeNames
+    ));
+  }
+
+  if (abac.crossSystemJson) {
+    errors.push(...validateCrossSystemJson(abac.crossSystemJson));
+  }
+
+  return errors;
+}
+
+module.exports = {
+  validateAbac,
+  validateDimensionsObject,
+  validateCrossSystemJson
+};