@aifabrix/builder 2.42.1 → 2.44.0

package/lib/core/secrets.js

@@ -24,10 +24,14 @@ const {
   rewriteInfraEndpoints,
   readYamlAtPath,
   applyCanonicalSecretsOverride,
-  ensureNonEmptySecrets,
   validateSecrets
 } = require('../utils/secrets-helpers');
 const { buildEnvVarMap } = require('../utils/env-map');
+const {
+  mergeInfraParameterDefaultsForCli,
+  getInfraParameterCatalog,
+  readRelaxedCatalogDefaults
+} = require('../parameters/infra-parameter-catalog');
 const { resolveServicePortsInEnvContent } = require('../utils/secrets-url');
 const {
   updatePortForDocker,
@@ -35,7 +39,7 @@ const {
   applyDockerEnvOverride,
   getContainerPortFromDockerEnv
 } = require('./secrets-docker-env');
-const { getContainerPortFromPath } = require('../utils/port-resolver');
+const { getContainerPortFromPath, loadVariablesFromPath } = require('../utils/port-resolver');
 const {
   generateMissingSecrets,
   createDefaultSecrets
@@ -48,10 +52,21 @@ const {
 const {
   loadUserSecrets,
   loadPrimaryUserSecrets,
-  loadDefaultSecrets
+  loadDefaultSecrets,
+  ensurePrimaryUserSecretsFileExists
 } = require('../utils/secrets-utils');
 const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
 const pathsUtil = require('../utils/paths');
+const { ensureSecureFilePermissions } = require('../utils/secure-file-permissions');
+const { readAppEnvironmentScopedFlagForAppPath } = require('../utils/app-scoped-config');
+const { computeEffectiveEnvironmentScopedResources, redisDbIndexForScopedRunEnv } = require('../utils/environment-scoped-resources');
+const { applyRedisDbIndexToEnvContent } = require('../utils/redis-env-scope');
+const { expandDeclarativeUrlsInEnvContent } = require('../utils/url-declarative-resolve');
+const { rewriteInactiveDeclarativeVdirPublicContent } = require('../utils/url-declarative-vdir-inactive-env');
+const {
+  mergeDockerManifestPublishedPort,
+  rewriteDockerManifestPublicPortEnvLine
+} = require('../utils/docker-manifest-public-port');
 
 /**
  * Generates a canonical secret name from an environment variable key.
@@ -127,8 +142,8 @@ async function decryptSecretsObject(secrets) {
  * @function loadSecrets
  * @param {string} [secretsPath] - Path to secrets file (optional, for explicit override)
  * @param {string} [appName] - Application name (optional, for backward compatibility)
- * @returns {Promise<Object>} Loaded secrets object with decrypted values
- * @throws {Error} If no secrets file found and no fallback available
+ * @returns {Promise<Object>} Loaded secrets object with decrypted values (may be empty after bootstrap file create)
+ * @throws {Error} If explicit secretsPath is set but file is missing or invalid
  *
  * @example
  * const secrets = await loadSecrets('../../secrets.local.yaml');
@@ -150,6 +165,7 @@ function mergeUserWithConfigFile(userSecrets, resolvedConfigPath) {
   if (!fs.existsSync(resolvedConfigPath)) {
     return null;
   }
+  ensureSecureFilePermissions(resolvedConfigPath);
   let configSecrets;
   try {
     configSecrets = readYamlAtPath(resolvedConfigPath);
@@ -170,16 +186,17 @@ function mergeUserWithConfigFile(userSecrets, resolvedConfigPath) {
 
 /**
  * Loads config secrets path, merges with user secrets (user/master wins, public fills missing).
- * User/master = primary home (AIFABRIX_HOME or ~/.aifabrix) secrets.local.yaml.
+ * User/master = getPrimaryUserSecretsLocalPath() (config dir; same file as loadPrimaryUserSecrets).
  * Public = aifabrix-secrets path from config. Used by loadSecrets cascade.
- * When aifabrix-secrets is an http(s) URL, fetches shared secrets from API (never persisted to disk).
+ * When the effective shared-secrets target (after remote-dev resolution) is an http(s) URL,
+ * fetches shared secrets from API (never persisted to disk).
  *
  * @async
  * @returns {Promise<Object|null>} Merged secrets object or null
  */
 async function loadMergedConfigAndUserSecrets() {
   const { loadRemoteSharedSecrets, mergeUserWithRemoteSecrets } = require('../utils/remote-secrets-loader');
-  const { isRemoteSecretsUrl } = require('../utils/remote-dev-auth');
+  const remoteDevAuth = require('../utils/remote-dev-auth');
   const userSecrets = loadPrimaryUserSecrets();
   const hasKeys = (obj) => obj && Object.keys(obj).length > 0;
   const userOrNull = () => (hasKeys(userSecrets) ? userSecrets : null);
@@ -188,7 +205,8 @@ async function loadMergedConfigAndUserSecrets() {
     if (!configSecretsPath) {
       return userOrNull();
     }
-    if (isRemoteSecretsUrl(configSecretsPath)) {
+    const effectiveShared = await remoteDevAuth.resolveSharedSecretsEndpoint(configSecretsPath);
+    if (remoteDevAuth.isRemoteSecretsUrl(effectiveShared)) {
       const remoteSecrets = await loadRemoteSharedSecrets();
       const merged = mergeUserWithRemoteSecrets(userSecrets, remoteSecrets);
       return hasKeys(merged) ? merged : userOrNull();
@@ -225,6 +243,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,15 +263,19 @@ 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}`);
     }
     return await decryptSecretsObject(explicitSecrets);
   }
-  const mergedSecrets = await loadSecretsWithFallbacks();
-  ensureNonEmptySecrets(mergedSecrets);
-  return await decryptSecretsObject(mergedSecrets);
+  let mergedSecrets = await loadSecretsWithFallbacks();
+  if (!mergedSecrets || Object.keys(mergedSecrets).length === 0) {
+    ensurePrimaryUserSecretsFileExists();
+    mergedSecrets = await loadSecretsWithFallbacks();
+  }
+  return await decryptSecretsObject(mergedSecrets || {});
 }
 
 /**
@@ -275,7 +298,7 @@ async function loadSecrets(secretsPath, _appName) {
  * const resolved = await resolveKvReferences(template, secrets, 'local');
  * // Returns: 'DATABASE_URL=postgresql://user:pass@localhost:5432/db'
  */
-async function resolveKvReferences(envTemplate, secrets, environment = 'local', secretsFilePaths = null, appName = null) {
+async function resolveKvReferences(envTemplate, secrets, environment = 'local', secretsFilePaths = null, appName = null, scopedKv = null) {
   const os = require('os');
 
   // Get developer-id for port variables (local and docker: *_PUBLIC_PORT = base + devId*100)
@@ -286,25 +309,56 @@ async function resolveKvReferences(envTemplate, secrets, environment = 'local',
     // ignore, buildEnvVarMap will use default
   }
 
-  let envVars = await buildEnvVarMap(environment, os, developerId);
+  const envKey = String(environment || 'local').toLowerCase();
+  const mapContext = envKey === 'docker' || envKey === 'local' ? envKey : 'local';
+
+  let envVars = await buildEnvVarMap(mapContext, os, developerId);
   if (!envVars || Object.keys(envVars).length === 0) {
     // Fallback to local environment variables if requested environment does not exist
     envVars = await buildEnvVarMap('local', os, developerId);
   }
   const resolved = interpolateEnvVars(envTemplate, envVars);
-  const missing = collectMissingSecrets(resolved, secrets);
+  const missing = collectMissingSecrets(resolved, secrets, scopedKv);
   if (missing.length > 0) {
     const fileInfo = formatMissingSecretsFileInfo(secretsFilePaths);
     const resolveCommand = appName ? `aifabrix resolve ${appName}` : 'aifabrix resolve <app-name>';
     throw new Error(`Missing secrets: ${missing.join(', ')}${fileInfo}\n\nRun "${resolveCommand}" to generate missing secrets.`);
   }
-  return replaceKvInContent(resolved, secrets, envVars);
+  return replaceKvInContent(resolved, secrets, envVars, scopedKv);
 }
 
-/** Docker env transformations: ports, infra endpoints, PORT. */
-async function applyDockerTransformations(resolved, variablesPath) {
-  resolved = await resolveServicePortsInEnvContent(resolved, 'docker');
-  resolved = await rewriteInfraEndpoints(resolved, 'docker');
+/**
+ * Resolve run env key and effective env-scoped kv/redis behavior for generateEnvContent.
+ *
+ * @async
+ * @param {string} appPath - Builder application directory
+ * @param {Object} [options] - generateEnvContent options; may set runEnvKey
+ * @returns {Promise<{ runEnvKey: string, effective: boolean }>}
+ */
+async function buildScopedKvContext(appPath, options = {}) {
+  let runEnvKey;
+  if (options.runEnvKey !== undefined && options.runEnvKey !== null) {
+    runEnvKey = String(options.runEnvKey).toLowerCase();
+  } else if (typeof config.getCurrentEnvironment === 'function') {
+    runEnvKey = String((await config.getCurrentEnvironment()) || 'dev').toLowerCase();
+  } else {
+    runEnvKey = 'dev';
+  }
+  const userCfg =
+    typeof config.getConfig === 'function'
+      ? await config.getConfig()
+      : { useEnvironmentScopedResources: false };
+  const useGate = Boolean(userCfg.useEnvironmentScopedResources);
+  const appFlag = readAppEnvironmentScopedFlagForAppPath(appPath);
+  const effective = computeEffectiveEnvironmentScopedResources(useGate, appFlag, runEnvKey);
+  return { runEnvKey, effective };
+}
+
+/**
+ * Redis/DB service endpoints for docker env interpolation.
+ * @returns {Promise<{ redisHost: string, redisPort: number, dbHost: string, dbPort: number }>}
+ */
+async function getDockerRedisDbEndpoints() {
   const { getEnvHosts, getServiceHost, getServicePort, getLocalhostOverride } = require('../utils/env-endpoints');
   const hosts = await getEnvHosts('docker');
   const localhostOverride = getLocalhostOverride('docker');
@@ -312,16 +366,97 @@ async function applyDockerTransformations(resolved, variablesPath) {
   const redisPort = await getServicePort('REDIS_PORT', 'redis', hosts, 'docker', null);
   const dbHost = getServiceHost(hosts.DB_HOST, 'docker', 'postgres', localhostOverride);
   const dbPort = await getServicePort('DB_PORT', 'postgres', hosts, 'docker', null);
+  return { redisHost, redisPort, dbHost, dbPort };
+}
+
+/**
+ * Config inputs for declarative url:// expansion (keeps expandDeclarativeUrlsIfPresent small).
+ * @param {string} appPath
+ * @returns {Promise<Object>}
+ */
+async function loadDeclarativeUrlExpandInputs(appPath) {
+  const userCfg = await config.getConfig();
+  let remoteServer = null;
+  try {
+    const rs = await config.getRemoteServer();
+    if (rs && String(rs).trim()) {
+      remoteServer = String(rs).trim();
+    }
+  } catch {
+    remoteServer = null;
+  }
+  let developerIdRaw = null;
+  try {
+    developerIdRaw = await config.getDeveloperId();
+  } catch {
+    developerIdRaw = null;
+  }
+  let infraTlsEnabled = false;
+  try {
+    infraTlsEnabled = await config.getTlsEnabled();
+  } catch {
+    infraTlsEnabled = false;
+  }
+  return {
+    userCfg,
+    remoteServer,
+    developerIdRaw,
+    infraTlsEnabled,
+    appScopedFlag: readAppEnvironmentScopedFlagForAppPath(appPath)
+  };
+}
+
+/**
+ * After kv:// resolution, expand url:// references when application config exists.
+ * @param {string} resolved
+ * @param {string} appName
+ * @param {string} appPath
+ * @param {string|null} variablesPath
+ * @param {string} environment
+ * @param {boolean} envOnly
+ * @returns {Promise<string>}
+ */
+async function expandDeclarativeUrlsIfPresent(resolved, appName, appPath, variablesPath, environment, envOnly) {
+  if (envOnly || !variablesPath) {
+    return resolved;
+  }
+  const { userCfg, remoteServer, developerIdRaw, infraTlsEnabled, appScopedFlag } =
+    await loadDeclarativeUrlExpandInputs(appPath);
+  resolved = rewriteInactiveDeclarativeVdirPublicContent(resolved, variablesPath, userCfg);
+  if (!resolved.includes('url://')) {
+    return resolved;
+  }
+  return expandDeclarativeUrlsInEnvContent(resolved, {
+    profile: environment === 'docker' ? 'docker' : 'local',
+    currentAppKey: appName,
+    variablesPath,
+    useEnvironmentScopedResources: Boolean(userCfg.useEnvironmentScopedResources),
+    appEnvironmentScopedResources: appScopedFlag,
+    remoteServer,
+    developerIdRaw,
+    traefik: Boolean(userCfg.traefik),
+    infraTlsEnabled
+  });
+}
+
+/** Docker env transformations: ports, infra endpoints, PORT. */
+async function applyDockerTransformations(resolved, variablesPath) {
+  resolved = await resolveServicePortsInEnvContent(resolved, 'docker');
+  resolved = await rewriteInfraEndpoints(resolved, 'docker');
+  const { redisHost, redisPort, dbHost, dbPort } = await getDockerRedisDbEndpoints();
   let dockerEnv = await getBaseDockerEnv();
   dockerEnv = applyDockerEnvOverride(dockerEnv);
   const containerPort = getContainerPortFromPath(variablesPath) ?? getContainerPortFromDockerEnv(dockerEnv) ?? 3000;
   const envVars = await buildEnvVarMap('docker', null, null, { appPort: containerPort });
+  const appDoc = loadVariablesFromPath(variablesPath);
+  await mergeDockerManifestPublishedPort(envVars, appDoc);
   envVars.REDIS_HOST = redisHost;
   envVars.REDIS_PORT = String(redisPort);
   envVars.DB_HOST = dbHost;
   envVars.DB_PORT = String(dbPort);
   envVars.PORT = String(containerPort);
   resolved = interpolateEnvVars(resolved, envVars);
+  resolved = rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc);
   return updatePortForDocker(resolved, variablesPath);
 }
 /** Environment-specific transformations to resolved content. */
@@ -353,8 +488,22 @@ async function generateEnvContent(appName, secretsPath, environment = 'local', f
     await secretsEnsure.ensureSecretsFromEnvTemplate(templatePath, { preferredFilePath: preferredPath });
   }
   const secrets = await loadSecrets(secretsPath, appName);
-  let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName);
+  const { runEnvKey, effective } = await buildScopedKvContext(appPath, options);
+  const scopedKv = { envKey: runEnvKey, effective };
+  let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName, scopedKv);
+  resolved = await expandDeclarativeUrlsIfPresent(
+    resolved,
+    appName,
+    appPath,
+    variablesPath,
+    environment,
+    Boolean(options.envOnly)
+  );
   resolved = await applyEnvironmentTransformations(resolved, environment, variablesPath);
+  if (effective) {
+    const idx = redisDbIndexForScopedRunEnv(runEnvKey);
+    resolved = applyRedisDbIndexToEnvContent(resolved, idx);
+  }
 
   return resolved;
 }
@@ -516,40 +665,76 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   return envPath;
 }
 
-/** Generates admin secrets for infrastructure (~/.aifabrix/admin-secrets.env). Uses admin123 when no postgres password. */
-async function generateAdminSecretsEnv(secretsPath) {
-  let secrets;
+/**
+ * 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');
+}
 
+async function loadSecretsOrBootstrapForAdmin(secretsPath) {
   try {
-    secrets = await loadSecrets(secretsPath);
+    return await loadSecrets(secretsPath);
   } catch (error) {
     const defaultSecretsPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
     if (!fs.existsSync(defaultSecretsPath)) {
       logger.log('Creating default secrets file...');
       await createDefaultSecrets(defaultSecretsPath);
-      secrets = await loadSecrets(secretsPath);
-    } else {
-      throw error;
+      return await loadSecrets(secretsPath);
     }
+    throw error;
   }
-  const aifabrixDir = pathsUtil.getAifabrixHome();
-  const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
-  if (!fs.existsSync(aifabrixDir)) {
-    fs.mkdirSync(aifabrixDir, { recursive: true, mode: 0o700 });
+}
+
+function getInfraDefaultsMergedForAdmin() {
+  try {
+    return mergeInfraParameterDefaultsForCli(getInfraParameterCatalog().data, {});
+  } catch {
+    return {};
   }
+}
 
+function buildLocalAdminSecretsObject(secrets, infraDefaults) {
   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 relaxed = readRelaxedCatalogDefaults();
+  const postgresPassword =
+    (raw && String(raw).trim()) ||
+    infraDefaults.adminPassword ||
+    relaxed.adminPassword ||
+    '';
+  const pgAdminEmail = infraDefaults.adminEmail || relaxed.adminEmail || '';
+  return {
+    POSTGRES_PASSWORD: postgresPassword,
+    PGADMIN_DEFAULT_EMAIL: pgAdminEmail,
+    PGADMIN_DEFAULT_PASSWORD: postgresPassword,
+    REDIS_HOST: 'local:redis:6379:0:',
+    REDIS_COMMANDER_USER: 'admin',
+    REDIS_COMMANDER_PASSWORD: postgresPassword
+  };
+}
 
+/** Generates admin secrets for infrastructure (beside config.yaml, typically ~/.aifabrix/admin-secrets.env). Defaults from infra.parameter.yaml `defaults`. */
+async function generateAdminSecretsEnv(secretsPath) {
+  const secrets = await loadSecretsOrBootstrapForAdmin(secretsPath);
+  const infraDefaults = getInfraDefaultsMergedForAdmin();
+  const adminObj = buildLocalAdminSecretsObject(secrets, infraDefaults);
+  const aifabrixDir = pathsUtil.getAifabrixSystemDir();
+  const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
+  if (!fs.existsSync(aifabrixDir)) {
+    fs.mkdirSync(aifabrixDir, { recursive: true, mode: 0o700 });
+  }
+  const adminSecrets = await formatAdminSecretsContent(adminObj);
   fs.writeFileSync(adminEnvPath, adminSecrets, { mode: 0o600 });
   return adminEnvPath;
 }
@@ -560,6 +745,7 @@ module.exports = {
   generateEnvContent,
   generateMissingSecrets,
   generateAdminSecretsEnv,
+  formatAdminSecretsContent,
   validateSecrets,
   createDefaultSecrets,
   getCanonicalSecretName,

package/lib/core/templates-env.js

@@ -106,9 +106,10 @@ function buildMonitoringEnv(config) {
   return {
     'MISO_CONTROLLER_URL': config.controllerUrl || 'https://controller.aifabrix.dev',
     'MISO_ENVIRONMENT': 'dev',
-    'MISO_CLIENTID': 'kv://miso-controller-client-idKeyVault',
-    'MISO_CLIENTSECRET': 'kv://miso-controller-client-secretKeyVault',
-    'MISO_WEB_SERVER_URL': 'kv://miso-controller-web-server-url'
+    // Filled after `aifabrix register <app>`; empty avoids bogus kv placeholders in new apps
+    'MISO_CLIENTID': '',
+    'MISO_CLIENTSECRET': '',
+    'MISO_WEB_SERVER_URL': 'url://miso-controller-public'
   };
 }
 

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,148 @@
+/**
+ * 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, 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
+    ));
+  }
+
+  if (abac.crossSystemJson) {
+    errors.push(...validateCrossSystemJson(abac.crossSystemJson));
+  }
+
+  return errors;
+}
+
+module.exports = {
+  validateAbac,
+  validateDimensionsObject,
+  validateCrossSystemJson
+};