@aifabrix/builder 2.49.2 → 2.51.0

package/lib/utils/postgres-platform-bootstrap.js

@@ -68,29 +68,37 @@ function extractPasswordFromUrlOrValue(urlOrPassword) {
 }
 
 /**
- * Escape SQL for embedding in a double-quoted shell argument (-c "...").
- * Bash expands `$` and `$$` (PID) inside double quotes; backslash-escape every `$`.
+ * Run psql -c inside the Postgres container without a shell.
+ * Passes SQL as an argv element so dollar-quoting (DO $$ … $$) is not mangled.
  *
- * @param {string} s
- * @returns {string}
- */
-function escapeShellDoubleQuoted(s) {
-  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$');
-}
-
-/**
  * @async
  * @param {string} container
  * @param {string} sql
  * @param {string} adminPassword
+ * @param {string} [database='postgres']
  * @returns {Promise<void>}
  */
 async function runPsqlCommand(container, sql, adminPassword, database = 'postgres') {
-  const escapedSql = escapeShellDoubleQuoted(sql);
-  const cmd =
-    `docker exec -e PGPASSWORD -i ${container} psql -U ${SUPERUSER_ROLE} -d ${database} ` +
-    `-v ON_ERROR_STOP=1 -c "${escapedSql}"`;
-  await dockerExec.execWithDockerEnv(cmd, { env: { PGPASSWORD: adminPassword } });
+  await dockerExec.execFileWithDockerEnv(
+    'docker',
+    [
+      'exec',
+      '-e',
+      'PGPASSWORD',
+      '-i',
+      container,
+      'psql',
+      '-U',
+      SUPERUSER_ROLE,
+      '-d',
+      database,
+      '-v',
+      'ON_ERROR_STOP=1',
+      '-c',
+      sql
+    ],
+    { env: { PGPASSWORD: adminPassword } }
+  );
 }
 
 /**
@@ -194,6 +202,5 @@ module.exports = {
   PLATFORM_DATABASE_SLOTS,
   bootstrapPlatformPostgresDatabases,
   pgRoleName,
-  extractPasswordFromUrlOrValue,
-  escapeShellDoubleQuoted
+  extractPasswordFromUrlOrValue
 };

package/lib/utils/postgres-wipe.js

@@ -86,9 +86,12 @@ async function runPsql(container, sql, adminPassword) {
   if (!adminPassword || typeof adminPassword !== 'string') {
     throw new Error('Admin password is required');
   }
-  const escapedSql = sql.replace(/"/g, '\\"');
-  const cmd = `docker exec -e PGPASSWORD -i ${container} psql -U ${SUPERUSER_ROLE} -d postgres -tAc "${escapedSql}"`;
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(container)) {
+    throw new Error(`Unsafe Postgres container name: ${container}`);
+  }
   const env = { PGPASSWORD: adminPassword };
+  const safeSqlToken = JSON.stringify(String(sql));
+  const cmd = `docker exec -e PGPASSWORD -i ${container} psql -U ${SUPERUSER_ROLE} -d postgres -tAc ${safeSqlToken}`;
   const result = (await dockerExec.execWithDockerEnv(cmd, { env })) || {};
   return String(result.stdout || '').trim();
 }

package/lib/utils/remote-dev-auth.js

@@ -24,6 +24,17 @@ function expandConfiguredSecretsTilde(filePath) {
   return filePath;
 }
 
+/** One auto-renew attempt per CLI process (shared by concurrent getRemoteDevAuth callers). */
+let autoRenewPromise = null;
+
+/**
+ * Reset process-level auto-renew gate (tests only).
+ * @returns {void}
+ */
+function resetDevCertAutoRenewGateForTests() {
+  autoRenewPromise = null;
+}
+
 /**
  * Single API object so resolveSharedSecretsEndpoint and callers share one getRemoteDevAuth
  * (Jest spies and partial mocks work reliably).
@@ -39,12 +50,11 @@ const remoteDevAuth = {
   },
 
   /**
-   * Get Builder Server URL, client cert PEM, and optional dev root CA when remote is configured; otherwise null.
-   * serverCaPem comes from ca.pem (saved at dev init); required for Node TLS to private-CA servers.
-   * Use for cert-authenticated dev API calls (settings, users, ssh-keys, secrets).
+   * Read remote server URL + client cert from disk without auto-renew.
+   * Use when renewing (avoids recursion) or when only a local presence check is needed.
    * @returns {Promise<{ serverUrl: string, clientCertPem: string, serverCaPem: string|null }|null>}
    */
-  async getRemoteDevAuth() {
+  async readRemoteDevAuth() {
     const serverUrl = await config.getRemoteServer();
     if (!serverUrl) return null;
     const devId = await config.getDeveloperId();
@@ -55,6 +65,30 @@ const remoteDevAuth = {
     return { serverUrl, clientCertPem, serverCaPem };
   },
 
+  /**
+   * Get Builder Server URL, client cert PEM, and optional dev root CA when remote is configured; otherwise null.
+   * When the client cert is still valid but expires within 14 days, renews it once per process before returning.
+   * serverCaPem comes from ca.pem (saved at dev init); required for Node TLS to private-CA servers.
+   * Use for cert-authenticated dev API calls (settings, users, ssh-keys, secrets).
+   * @returns {Promise<{ serverUrl: string, clientCertPem: string, serverCaPem: string|null }|null>}
+   */
+  async getRemoteDevAuth() {
+    const existing = await remoteDevAuth.readRemoteDevAuth();
+    if (!existing) return null;
+    if (!autoRenewPromise) {
+      autoRenewPromise = (async() => {
+        const { ensureDevCertFreshIfDue } = require('../commands/dev-refresh');
+        return ensureDevCertFreshIfDue({ quiet: false });
+      })();
+    }
+    try {
+      await autoRenewPromise;
+    } catch {
+      // ensureDevCertFreshIfDue already handles failures; keep using current cert
+    }
+    return remoteDevAuth.readRemoteDevAuth();
+  },
+
   /**
    * Resolve where shared secrets read/write should go. After dev init, config may still hold a
    * server-side filesystem path from GET /api/dev/settings (not an http URL) if merge did not rewrite it.
@@ -148,3 +182,4 @@ function normalizeSharedSecretsFilePath(configured) {
 }
 
 module.exports = remoteDevAuth;
+module.exports.resetDevCertAutoRenewGateForTests = resetDevCertAutoRenewGateForTests;

package/lib/utils/resolve-docker-image-ref.js

@@ -12,6 +12,32 @@
 'use strict';
 
 const { parseImageOverride } = require('./parse-image-ref');
+const DOCKER_REPOSITORY_RE = /^[a-z0-9][a-z0-9._/-]*$/i;
+const DOCKER_TAG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/**
+ * @param {string} repository
+ * @returns {string}
+ */
+function assertSafeRepository(repository) {
+  const trimmed = String(repository || '').trim();
+  if (!trimmed || !DOCKER_REPOSITORY_RE.test(trimmed)) {
+    throw new Error(`Invalid Docker repository path: ${repository}`);
+  }
+  return trimmed;
+}
+
+/**
+ * @param {string} tag
+ * @returns {string}
+ */
+function assertSafeTag(tag) {
+  const trimmed = String(tag || '').trim();
+  if (!trimmed || !DOCKER_TAG_RE.test(trimmed)) {
+    throw new Error(`Invalid Docker image tag: ${tag}`);
+  }
+  return trimmed;
+}
 
 /**
  * Repository path without host (same rules as compose-generator getImageName).
@@ -59,7 +85,11 @@ function normalizeDockerRegistryPrefix(registry) {
   if (!t) {
     return '';
   }
-  return t.replace(/\/+$/, '');
+  let end = t.length;
+  while (end > 0 && t[end - 1] === '/') {
+    end -= 1;
+  }
+  return t.slice(0, end);
 }
 
 /**
@@ -81,18 +111,18 @@ function resolveDockerImageRef(appName, appConfig, runOptions = {}) {
   if (opts.image) {
     const parsed = parseImageOverride(opts.image);
     return {
-      imageName: parsed ? parsed.name : getRepositoryPathFromConfig(appConfig, appName),
-      imageTag: parsed ? parsed.tag : tagFromOpts || imageTagFromConfig(appConfig)
+      imageName: assertSafeRepository(parsed ? parsed.name : getRepositoryPathFromConfig(appConfig, appName)),
+      imageTag: assertSafeTag(parsed ? parsed.tag : tagFromOpts || imageTagFromConfig(appConfig))
     };
   }
 
-  const baseRepo = getRepositoryPathFromConfig(appConfig, appName);
-  const imageTag = tagFromOpts || imageTagFromConfig(appConfig);
+  const baseRepo = assertSafeRepository(getRepositoryPathFromConfig(appConfig, appName));
+  const imageTag = assertSafeTag(tagFromOpts || imageTagFromConfig(appConfig));
   const prefix =
     normalizeDockerRegistryPrefix(opts.registry) ||
     normalizeDockerRegistryPrefix(appConfig?.image?.registry ?? '');
   if (prefix) {
-    return { imageName: `${prefix}/${baseRepo}`, imageTag };
+    return { imageName: assertSafeRepository(`${prefix}/${baseRepo}`), imageTag };
   }
   return { imageName: baseRepo, imageTag };
 }

package/lib/utils/runtime-configuration-values.js

@@ -44,6 +44,65 @@ function collectSystemVariablePutRequests(systemConfiguration, envMap) {
   return requests;
 }
 
+/** OpenAPI path param names resolved from env.template (not valid configuration[] names). */
+const OPENAPI_PATH_PARAM_ENV_KEYS = ['systemKey', 'pillar'];
+
+const PATH_PARAM_FALLBACK_ENV_KEYS = {
+  systemKey: 'E2E_SYSTEM_KEY',
+  pillar: 'E2E_CERTIFY_PILLAR'
+};
+
+/**
+ * @param {unknown} raw
+ * @param {{ allowKv?: boolean }} [options]
+ * @returns {string|null}
+ */
+function resolvedEnvLiteral(raw, options = {}) {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  const value = String(raw).trim();
+  if (!value || value.includes('{{')) {
+    return null;
+  }
+  if (!options.allowKv && value.startsWith('kv://')) {
+    return null;
+  }
+  return value;
+}
+
+function resolvePathParamValue(envMap, name) {
+  const direct = resolvedEnvLiteral(envMap[name]);
+  if (direct) {
+    return direct;
+  }
+  const fallbackKey = PATH_PARAM_FALLBACK_ENV_KEYS[name];
+  if (!fallbackKey) {
+    return null;
+  }
+  return resolvedEnvLiteral(envMap[fallbackKey], { allowKv: true });
+}
+
+/**
+ * @param {Object.<string, string>} envMap
+ * @param {Set<string>} [alreadyPushed]
+ * @returns {Array<{ name: string, value: string }>}
+ */
+function collectOpenApiPathParamAliasPutRequests(envMap, alreadyPushed = new Set()) {
+  const requests = [];
+  for (const name of OPENAPI_PATH_PARAM_ENV_KEYS) {
+    if (alreadyPushed.has(name)) {
+      continue;
+    }
+    const value = resolvePathParamValue(envMap, name);
+    if (!value) {
+      continue;
+    }
+    requests.push({ name, value });
+  }
+  return requests;
+}
+
 /**
  * Datasource overrides are name+value only; values may already be resolved in upload payload.
  *
@@ -83,7 +142,7 @@ function collectDatasourceOverridePutRequests(datasourceConfiguration) {
  * @returns {Promise<{ pushed: number, names: string[] }>}
  */
 async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKey, payload) {
-  const { envMap } = await buildResolvedEnvMapForIntegration(systemKey);
+  const { envMap } = await buildResolvedEnvMapForIntegration(systemKey, { dataplaneRuntime: true });
   const names = [];
   let pushed = 0;
 
@@ -91,7 +150,9 @@ async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKe
     payload?.application?.configuration,
     envMap
   );
-  for (const body of systemRequests) {
+  const pushedNames = new Set(systemRequests.map((r) => r.name));
+  const aliasRequests = collectOpenApiPathParamAliasPutRequests(envMap, pushedNames);
+  for (const body of [...systemRequests, ...aliasRequests]) {
     await putExternalSystemConfiguration(dataplaneUrl, systemKey, authConfig, body);
     names.push(body.name);
     pushed += 1;
@@ -114,6 +175,7 @@ async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKe
 
 module.exports = {
   collectSystemVariablePutRequests,
+  collectOpenApiPathParamAliasPutRequests,
   collectDatasourceOverridePutRequests,
   pushRuntimeConfigurationValues
 };

package/lib/utils/secrets-helpers.js

@@ -226,7 +226,11 @@ function replaceKvInContent(content, secrets, envVars, scopedKv = null) {
           return envVars[envVar] || m;
         });
       }
-      return value !== null && value !== undefined ? String(value) : match;
+      if (value !== null && value !== undefined) {
+        const { formatDotenvSubstitutionValue } = require('./env-dotenv-format');
+        return formatDotenvSubstitutionValue(String(value));
+      }
+      return match;
     });
     return replaced + suffix;
   });

package/lib/utils/ssh-known-hosts.js

@@ -0,0 +1,130 @@
+/**
+ * Remove stale OpenSSH known_hosts entries after server reprovision or Host alias rename.
+ *
+ * @fileoverview ssh-keygen -R helpers for dev init / refresh
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const path = require('path');
+const { getDefaultSshDir } = require('./ssh-key-helper');
+const { getDevSshHostAlias, resolveDevSshHostAlias } = require('./dev-ssh-config-helper');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {string} baseUrl
+ * @returns {string|null}
+ */
+function hostnameFromBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== 'string') return null;
+  const s = baseUrl.trim().replace(/\/+$/, '');
+  const withProtocol = /^https?:\/\//i.test(s) ? s : `https://${s}`;
+  try {
+    return new URL(withProtocol).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} hostname
+ * @param {string} knownHostsPath
+ * @returns {Promise<{ hostname: string, ok: boolean, error?: string }>}
+ */
+async function removeKnownHostEntry(hostname, knownHostsPath) {
+  const host = String(hostname || '').trim();
+  if (!host) {
+    return { hostname: host, ok: false, error: 'empty hostname' };
+  }
+  try {
+    await execFileAsync('ssh-keygen', ['-R', host, '-f', knownHostsPath], {
+      encoding: 'utf8'
+    });
+    return { hostname: host, ok: true };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { hostname: host, ok: false, error: 'ssh-keygen not found' };
+    }
+    return { hostname: host, ok: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Hostnames that may appear in known_hosts for a Builder dev SSH connection.
+ * Includes current Host alias, HostName (sync-ssh-host), remote-server host, and legacy Host aliases.
+ *
+ * @param {Object} p
+ * @param {string} p.syncHost - sync-ssh-host / HostName
+ * @param {string} p.syncUser - sync-ssh-user
+ * @param {string} [p.hostAlias] - Preferred ssh config Host alias
+ * @param {string} [p.baseUrl] - remote-server URL
+ * @param {string} [p.developerId]
+ * @param {string} [p.developerRootDomain]
+ * @param {string[]} [p.legacyHostAliases] - Previous Host keywords from ~/.ssh/config
+ * @returns {string[]}
+ */
+function collectDevSshKnownHostCandidates(p) {
+  const syncHost = String(p.syncHost || '').trim();
+  const syncUser = String(p.syncUser || '').trim();
+  const candidates = new Set();
+  if (syncHost) {
+    candidates.add(syncHost);
+  }
+  if (p.hostAlias) {
+    candidates.add(String(p.hostAlias).trim());
+  }
+  const preferred = resolveDevSshHostAlias({
+    syncUser,
+    syncHost,
+    developerId: p.developerId,
+    developerRootDomain: p.developerRootDomain
+  });
+  if (preferred) {
+    candidates.add(preferred);
+  }
+  if (syncUser && syncHost) {
+    candidates.add(getDevSshHostAlias(syncUser, syncHost));
+  }
+  const fromUrl = hostnameFromBaseUrl(p.baseUrl);
+  if (fromUrl) {
+    candidates.add(fromUrl);
+  }
+  for (const alias of p.legacyHostAliases || []) {
+    const trimmed = String(alias || '').trim();
+    if (trimmed) {
+      candidates.add(trimmed);
+    }
+  }
+  return [...candidates].filter(Boolean);
+}
+
+/**
+ * @param {string[]} hostnames
+ * @param {string} [sshDir]
+ * @returns {Promise<{ cleared: string[], failed: Array<{ hostname: string, error: string }> }>}
+ */
+async function refreshDevSshKnownHosts(hostnames, sshDir) {
+  const knownHostsPath = path.join(sshDir || getDefaultSshDir(), 'known_hosts');
+  const cleared = [];
+  const failed = [];
+  for (const hostname of hostnames) {
+    const result = await removeKnownHostEntry(hostname, knownHostsPath);
+    if (result.ok) {
+      cleared.push(result.hostname);
+    } else if (result.error && result.error !== 'empty hostname') {
+      failed.push({ hostname: result.hostname, error: result.error });
+    }
+  }
+  return { cleared, failed };
+}
+
+module.exports = {
+  collectDevSshKnownHostCandidates,
+  removeKnownHostEntry,
+  refreshDevSshKnownHosts
+};

package/lib/utils/test-target-cli-options.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview CLI normalization for manifest version target and test sync policy (456.17).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYNC_MODES = new Set(['auto', 'never', 'force']);
+const VERSION_KEYWORDS = new Set(['latest', 'running']);
+
+/**
+ * @param {string|undefined|null} raw
+ * @param {string} [defaultValue='latest']
+ * @returns {string}
+ */
+function normalizeVersionTarget(raw, defaultValue = 'latest') {
+  const value = String(raw ?? defaultValue).trim();
+  if (!value) {
+    throw new Error('--version is required (latest, running, or explicit version id).');
+  }
+  const lower = value.toLowerCase();
+  if (VERSION_KEYWORDS.has(lower)) {
+    return lower;
+  }
+  if (!/^[a-zA-Z0-9._-]+$/.test(value)) {
+    throw new Error(
+      '--version must be latest, running, or an explicit version id (letters, numbers, ., _, -).'
+    );
+  }
+  return value;
+}
+
+/**
+ * @param {string|undefined|null} raw
+ * @param {string} [defaultValue='auto']
+ * @returns {string}
+ */
+function normalizeSyncMode(raw, defaultValue = 'auto') {
+  const value = String(raw ?? defaultValue).trim().toLowerCase();
+  if (!SYNC_MODES.has(value)) {
+    throw new Error('--sync-mode must be auto, never, or force.');
+  }
+  return value;
+}
+
+/**
+ * Merge versionTarget and syncMode from CLI options into e2eOptions for ValidationRunRequest.
+ *
+ * @param {Object} cliOptions - Commander-parsed options
+ * @param {Object} [e2eOptions={}]
+ * @returns {Object}
+ */
+function mergeTestTargetIntoE2eOptions(cliOptions, e2eOptions = {}) {
+  const merged = { ...e2eOptions };
+  if (cliOptions && cliOptions.version !== undefined && cliOptions.version !== null) {
+    merged.versionTarget = normalizeVersionTarget(cliOptions.version);
+  } else {
+    merged.versionTarget = normalizeVersionTarget(undefined, 'latest');
+  }
+  if (cliOptions && cliOptions.syncMode !== undefined && cliOptions.syncMode !== null) {
+    merged.syncMode = normalizeSyncMode(cliOptions.syncMode);
+  } else {
+    merged.syncMode = normalizeSyncMode(undefined, 'auto');
+  }
+  return merged;
+}
+
+module.exports = {
+  SYNC_MODES,
+  VERSION_KEYWORDS,
+  normalizeVersionTarget,
+  normalizeSyncMode,
+  mergeTestTargetIntoE2eOptions
+};

package/lib/utils/token-manager.js

@@ -409,13 +409,29 @@ function applyLabDataplaneApiKeyBearer(authConfig) {
 }
 
 function requireBearerForDataplanePipeline(authConfig) {
+  if (!authConfig || typeof authConfig !== 'object') {
+    return;
+  }
+
   if (authConfig.type === 'client-token' && authConfig.token) {
     return;
   }
 
+  // Token-forward (builder-api / bearerForward): never substitute lab API_KEY for the caller JWT.
+  if (authConfig.preserveBearer && authConfig.token) {
+    return;
+  }
+
   const preferAppClientToken =
     String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
 
+  const existing = authConfig.token ? String(authConfig.token) : '';
+  const looksLikeJwt = existing.split('.').length === 3 && existing.length > 80;
+  // Enterprise path: keep a real OAuth JWT; do not overwrite with process.env.API_KEY.
+  if (looksLikeJwt) {
+    return;
+  }
+
   if (!preferAppClientToken && process.env.API_KEY) {
     const apiKey = String(process.env.API_KEY);
     if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {

package/lib/utils/upload-sync-options.js

@@ -10,20 +10,38 @@
 
 /**
  * @param {Object} [options] - CLI options from test / sync callers
- * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true }}
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
  */
 function buildMinimalUploadSyncOptions(options = {}) {
+  const deployPreflight = options.uploadContext === 'deploy-preflight';
   const out = {
     minimal: true,
     // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
     verbose: false,
     silentResolve: true,
     syncMode: true,
-    suppressPipelineSpinner: options.suppressPipelineSpinner === true
+    skipDataSync: true,
+    suppressPipelineSpinner:
+      options.suppressPipelineSpinner === true || deployPreflight === true
   };
   if (options.force === true) {
     out.force = true;
   }
+  if (options.suppressSummary === true || deployPreflight === true) {
+    out.suppressSummary = true;
+  }
+  if (deployPreflight) {
+    out.uploadContext = 'deploy-preflight';
+  }
+  // Builder-api / programmatic callers: keep request Bearer — do not fall back to
+  // getDeploymentAuth against a stale mount AIFABRIX_CONFIG device token.
+  if (options.authConfig && options.dataplaneUrl) {
+    out.authConfig = options.authConfig;
+    out.dataplaneUrl = options.dataplaneUrl;
+    if (options.environment) {
+      out.environment = options.environment;
+    }
+  }
   return out;
 }
 

package/lib/utils/validation-run-request.js

@@ -4,6 +4,8 @@
  * @version 2.0.0
  */
 
+const { mergeTestTargetIntoE2eOptions, normalizeVersionTarget } = require('./test-target-cli-options');
+
 /**
  * Whether the unified validation request should set includeDebug (any `--debug` or `--debug <level>`).
  * @param {*} debugOpt - Commander `options.debug`
@@ -60,7 +62,7 @@ function buildE2eOptionsFromCli(options = {}) {
   if (options.e2eOptionsExtra && typeof options.e2eOptionsExtra === 'object') {
     Object.assign(e2e, options.e2eOptionsExtra);
   }
-  return e2e;
+  return mergeTestTargetIntoE2eOptions(options, e2e);
 }
 
 /**
@@ -73,6 +75,8 @@ function buildE2eOptionsFromCli(options = {}) {
  * @param {boolean} [params.asyncRun]
  * @param {boolean} [params.includeDebug]
  * @param {boolean} [params.explain]
+ * @param {boolean} [params.explainCertification]
+ * @param {boolean} [params.explainMetrics]
  * @param {Object} [params.e2eOptions] - Merged with buildE2eOptionsFromCli when both used by caller
  * @returns {import('../api/types/validation-run.types').ValidationRunRequestBody}
  */
@@ -85,6 +89,8 @@ function buildExternalDataSourceValidationRequest(params) {
     asyncRun,
     includeDebug,
     explain,
+    explainCertification,
+    explainMetrics,
     e2eOptions
   } = params;
   if (!systemKey || !datasourceKey || !runType) {
@@ -101,6 +107,8 @@ function buildExternalDataSourceValidationRequest(params) {
   if (asyncRun === true) body.asyncRun = true;
   if (includeDebug === true) body.includeDebug = true;
   if (explain === true) body.explain = true;
+  if (explainCertification === true) body.explainCertification = true;
+  if (explainMetrics === true) body.explainMetrics = true;
   if (e2eOptions && typeof e2eOptions === 'object' && Object.keys(e2eOptions).length > 0) {
     body.e2eOptions = e2eOptions;
   }
@@ -110,5 +118,6 @@ function buildExternalDataSourceValidationRequest(params) {
 module.exports = {
   includeDebugForRequest,
   buildE2eOptionsFromCli,
-  buildExternalDataSourceValidationRequest
+  buildExternalDataSourceValidationRequest,
+  normalizeVersionTarget
 };