@aifabrix/builder 2.44.0 → 2.44.2

package/lib/external-system/deploy.js

@@ -27,6 +27,8 @@ const { parseControllerDeploymentOutcome } = require('../utils/controller-deploy
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateExternalSystemComplete } = require('../validation/validate');
 const { displayValidationResults } = require('../validation/validate-display');
+const { maybeSyncSystemCertificationFromDataplane } = require('../certification/sync-system-certification');
+const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
 
 /**
  * Lists datasources for a system and loads system record for docs URLs.
@@ -97,6 +99,54 @@ async function fetchDataplaneDeployReadiness(controllerUrl, environment, authCon
 /**
  * @param {Object} deploymentOutcome - from parseControllerDeploymentOutcome
  */
+/**
+ * Optional dataplane validation/run after external deploy (--probe).
+ * @async
+ * @param {{ dataplaneUrl: string|null, error: Error|null }} ctx
+ * @param {string} systemKey
+ * @param {Object} authConfig
+ * @param {Object} options
+ * @returns {Promise<Object|null>} Unwrapped probe payload or null
+ */
+async function runOptionalExternalDeployProbe(ctx, systemKey, authConfig, options) {
+  if (!options.probe || !ctx.dataplaneUrl || ctx.error) return null;
+  logger.log(chalk.blue('\nRunning runtime checks (--probe)...'));
+  try {
+    const pr = await testSystemViaPipeline(ctx.dataplaneUrl, systemKey, authConfig, {}, {
+      timeout: options.probeTimeout || 120000
+    });
+    if (pr.success === false) {
+      logger.log(chalk.yellow(`⚠ Probe request failed: ${pr.formattedError || pr.error || 'unknown error'}`));
+      return null;
+    }
+    return unwrapApiData(pr);
+  } catch (e) {
+    logger.log(chalk.yellow(`⚠ Probe failed: ${e.message}`));
+    return null;
+  }
+}
+
+/**
+ * @param {Object} deploymentOutcome
+ * @param {{ dataplaneUrl: string|null, error: Error|null }} ctx
+ * @param {Object} manifest
+ * @param {Object} options
+ * @param {Object} authConfig
+ * @returns {Promise<void>}
+ */
+async function maybeSyncCertificationAfterExternalDeploy(deploymentOutcome, ctx, manifest, options, authConfig) {
+  if (!deploymentOutcome.ok || !ctx.dataplaneUrl || ctx.error) return;
+  const dsKeys = (manifest.dataSources || []).map((ds) => ds && ds.key).filter(Boolean);
+  await maybeSyncSystemCertificationFromDataplane({
+    label: 'deploy',
+    noCertSync: cliOptsSkipCertSync(options),
+    systemKey: manifest.key,
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig,
+    datasourceKeys: dsKeys
+  });
+}
+
 function logImmediateControllerDeploymentOutcome(deploymentOutcome) {
   if (deploymentOutcome.ok) {
     logger.log(formatSuccessParagraph('Controller deployment OK'));
@@ -148,24 +198,7 @@ async function executeDeployAndDisplay(manifest, controllerUrl, environment, aut
     manifest.key
   );
 
-  let probeData = null;
-  if (options.probe && ctx.dataplaneUrl && !ctx.error) {
-    logger.log(chalk.blue('\nRunning runtime checks (--probe)...'));
-    try {
-      const pr = await testSystemViaPipeline(ctx.dataplaneUrl, manifest.key, authConfig, {}, {
-        timeout: options.probeTimeout || 120000
-      });
-      if (pr.success === false) {
-        logger.log(
-          chalk.yellow(`⚠ Probe request failed: ${pr.formattedError || pr.error || 'unknown error'}`)
-        );
-      } else {
-        probeData = unwrapApiData(pr);
-      }
-    } catch (e) {
-      logger.log(chalk.yellow(`⚠ Probe failed: ${e.message}`));
-    }
-  }
+  const probeData = await runOptionalExternalDeployProbe(ctx, manifest.key, authConfig, options);
 
   logDeployReadinessSummary({
     environment,
@@ -179,6 +212,8 @@ async function executeDeployAndDisplay(manifest, controllerUrl, environment, aut
     probeData
   });
 
+  await maybeSyncCertificationAfterExternalDeploy(deploymentOutcome, ctx, manifest, options, authConfig);
+
   return result;
 }
 

package/lib/infrastructure/compose.js

@@ -109,13 +109,23 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
   const template = handlebars.compile(templateContent);
   const networkName = idNum === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
   const serversJsonPath = path.join(infraDir, 'servers.json');
+  const serversJsonBind = toDockerBindMountSource(serversJsonPath);
   const pgpassPath = path.join(infraDir, 'pgpass');
   const traefikConfig = typeof options.traefik === 'object'
     ? options.traefik
     : buildTraefikConfig(!!options.traefik);
-  const pgadminConfig = options.pgadmin && typeof options.pgadmin.enabled === 'boolean'
+  const pgadminConfigRaw = options.pgadmin && typeof options.pgadmin.enabled === 'boolean'
     ? options.pgadmin
     : { enabled: true };
+  const pgadminEnabled = !!pgadminConfigRaw.enabled;
+  const pgpassBootstrapPath = path.join(infraDir, '.pgpass.bootstrap');
+  const pgadminConfig = {
+    ...pgadminConfigRaw,
+    enabled: pgadminEnabled,
+    ...(pgadminEnabled
+      ? { pgpassBootstrapBind: toDockerBindMountSource(pgpassBootstrapPath) }
+      : {})
+  };
   const redisCommanderConfig = options.redisCommander && typeof options.redisCommander.enabled === 'boolean'
     ? options.redisCommander
     : { enabled: true };
@@ -132,7 +142,6 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
     }
     : traefikConfig;
   const initScriptsBind = toDockerBindMountSource(path.join(infraDir, 'init-scripts'));
-  const infraDirBind = toDockerBindMountSource(infraDir);
   const composeContent = template({
     devId: devId,
     postgresPort: ports.postgres,
@@ -143,10 +152,10 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
     traefikHttpsPort: ports.traefikHttps,
     networkName: networkName,
     serversJsonPath: serversJsonPath,
+    serversJsonBind: serversJsonBind,
     pgpassPath: pgpassPath,
     infraDir: infraDir,
     initScriptsBind: initScriptsBind,
-    infraDirBind: infraDirBind,
     traefik: traefikForCompose,
     pgadmin: pgadminConfig,
     redisCommander: redisCommanderConfig

package/lib/infrastructure/helpers-docker-check.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Docker / Compose availability check and user-facing failure text for infra helpers.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const dockerUtils = require('../utils/docker');
+const { ensureDevCertsIfNeededForRemoteDocker } = require('../utils/ensure-dev-certs-for-remote-docker');
+
+/**
+ * User-facing error when Docker/Compose checks fail (tailored by underlying message).
+ * @param {string} detail - Error message from ensureDockerAndCompose / Docker CLI
+ * @returns {string}
+ */
+function formatDockerInfrastructureFailure(detail) {
+  const cause = (detail || '').trim() || 'unknown error';
+
+  if (/Docker Compose is not available/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: Docker Compose check failed (see Cause below).\n\n' +
+      `Cause: ${cause}\n\n` +
+      'If Cause mentions TLS, certificate, or handshake, fix client TLS for docker-endpoint (cert.pem, key.pem, ca.pem under ~/.aifabrix/certs/<developer-id>/) or docker-tls-skip-verify when appropriate. ' +
+      'If Cause suggests a missing plugin, install Docker Compose v2 for your user (docker CLI + plugin; no unix socket needed when using tcp:// docker-endpoint). ' +
+      'Or set AIFABRIX_COMPOSE_CMD. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  if (/AIFABRIX_COMPOSE_CMD/i.test(cause) && /is set but failed/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: AIFABRIX_COMPOSE_CMD failed.\n\n' +
+      `Cause: ${cause}\n\n` +
+      'Unset or fix AIFABRIX_COMPOSE_CMD, or install a working Compose. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  return (
+    'Cannot use Docker for infrastructure (Docker CLI missing, Compose missing, or remote Docker misconfigured).\n\n' +
+    `Cause: ${cause}\n\n` +
+    'Install Docker Engine and Compose on this machine (or set AIFABRIX_COMPOSE_CMD). ' +
+    'If you use docker-endpoint in dev config: install cert.pem, key.pem, and ca.pem for full TLS verify; use `aifabrix dev pin` / ' +
+    '`dev init --pin` as needed; or enable TLS skip-verify (config or AIFABRIX_DOCKER_TLS_SKIP_VERIFY) when appropriate. ' +
+    'Run `aifabrix doctor` for diagnostics.'
+  );
+}
+
+/**
+ * Check Docker availability (local daemon or remote via docker-endpoint + TLS).
+ * @async
+ * @returns {Promise<void>}
+ * @throws {Error} If Docker/Compose cannot be used (includes underlying cause)
+ */
+async function checkDockerAvailability() {
+  await ensureDevCertsIfNeededForRemoteDocker();
+  try {
+    await dockerUtils.ensureDockerAndCompose();
+  } catch (error) {
+    const detail = (error && error.message) || String(error);
+    throw new Error(formatDockerInfrastructureFailure(detail));
+  }
+}
+
+module.exports = {
+  formatDockerInfrastructureFailure,
+  checkDockerAvailability
+};

package/lib/infrastructure/helpers.js

@@ -17,7 +17,6 @@ const chalk = require('chalk');
 const handlebars = require('handlebars');
 const adminSecrets = require('../core/admin-secrets');
 const logger = require('../utils/logger');
-const dockerUtils = require('../utils/docker');
 const paths = require('../utils/paths');
 const secretsEnsure = require('../core/secrets-ensure');
 const {
@@ -25,7 +24,7 @@ const {
   getInfraParameterCatalog,
   readRelaxedCatalogDefaults
 } = require('../parameters/infra-parameter-catalog');
-const { ensureDevCertsIfNeededForRemoteDocker } = require('../utils/ensure-dev-certs-for-remote-docker');
+const { checkDockerAvailability } = require('./helpers-docker-check');
 
 /**
  * Lazy-load core/secrets at call time. A top-level require creates a circular dependency:
@@ -59,58 +58,6 @@ function getInfraProjectName(devId) {
   return idNum === 0 ? 'infra' : `infra-dev${devId}`;
 }
 
-/**
- * User-facing error when Docker/Compose checks fail (tailored by underlying message).
- * @param {string} detail - Error message from ensureDockerAndCompose / Docker CLI
- * @returns {string}
- */
-function formatDockerInfrastructureFailure(detail) {
-  const cause = (detail || '').trim() || 'unknown error';
-
-  if (/Docker Compose is not available/i.test(cause)) {
-    return (
-      'Cannot use Docker for infrastructure: Docker Compose check failed (see Cause below).\n\n' +
-      `Cause: ${cause}\n\n` +
-      'If Cause mentions TLS, certificate, or handshake, fix client TLS for docker-endpoint (cert.pem, key.pem, ca.pem under ~/.aifabrix/certs/<developer-id>/) or docker-tls-skip-verify when appropriate. ' +
-      'If Cause suggests a missing plugin, install Docker Compose v2 for your user (docker CLI + plugin; no unix socket needed when using tcp:// docker-endpoint). ' +
-      'Or set AIFABRIX_COMPOSE_CMD. Run `aifabrix doctor` for diagnostics.'
-    );
-  }
-
-  if (/AIFABRIX_COMPOSE_CMD/i.test(cause) && /is set but failed/i.test(cause)) {
-    return (
-      'Cannot use Docker for infrastructure: AIFABRIX_COMPOSE_CMD failed.\n\n' +
-      `Cause: ${cause}\n\n` +
-      'Unset or fix AIFABRIX_COMPOSE_CMD, or install a working Compose. Run `aifabrix doctor` for diagnostics.'
-    );
-  }
-
-  return (
-    'Cannot use Docker for infrastructure (Docker CLI missing, Compose missing, or remote Docker misconfigured).\n\n' +
-      `Cause: ${cause}\n\n` +
-      'Install Docker Engine and Compose on this machine (or set AIFABRIX_COMPOSE_CMD). ' +
-      'If you use docker-endpoint in dev config: install cert.pem, key.pem, and ca.pem for full TLS verify; use `aifabrix dev pin` / ' +
-      '`dev init --pin` as needed; or enable TLS skip-verify (config or AIFABRIX_DOCKER_TLS_SKIP_VERIFY) when appropriate. ' +
-      'Run `aifabrix doctor` for diagnostics.'
-  );
-}
-
-/**
- * Check Docker availability (local daemon or remote via docker-endpoint + TLS).
- * @async
- * @returns {Promise<void>}
- * @throws {Error} If Docker/Compose cannot be used (includes underlying cause)
- */
-async function checkDockerAvailability() {
-  await ensureDevCertsIfNeededForRemoteDocker();
-  try {
-    await dockerUtils.ensureDockerAndCompose();
-  } catch (error) {
-    const detail = (error && error.message) || String(error);
-    throw new Error(formatDockerInfrastructureFailure(detail));
-  }
-}
-
 /**
  * Fallback for admin password/email when validated catalog load failed but YAML is still readable.
  * @returns {Record<string, string>}
@@ -289,12 +236,37 @@ async function ensureAdminSecrets(options = {}) {
   return adminSecretsPath;
 }
 
+/** Host-side pgpass for pgAdmin bind mount (must exist before container starts so servers.json import succeeds). */
+const PGPASS_BOOTSTRAP_BASENAME = '.pgpass.bootstrap';
+
+/**
+ * Writes pgpass next to servers.json for Docker bind mount into /pgadmin4 (not under /var/lib/pgadmin volume).
+ * Prefer chown to pgAdmin UID so mode 600 is readable in the container; fall back to 644 if not root.
+ *
+ * @param {string} infraDir - Infrastructure directory path
+ * @param {string} postgresPassword - PostgreSQL password for the pgpass line
+ */
+function writePgpassBootstrap(infraDir, postgresPassword) {
+  const line = `postgres:5432:postgres:pgadmin:${postgresPassword}\n`;
+  const dest = path.join(infraDir, PGPASS_BOOTSTRAP_BASENAME);
+  fs.writeFileSync(dest, line, { mode: 0o600 });
+  try {
+    fs.chownSync(dest, 5050, 5050);
+  } catch {
+    try {
+      fs.chmodSync(dest, 0o644);
+    } catch {
+      // Ignore — container may still read depending on daemon / user namespace
+    }
+  }
+}
+
 /**
- * Generates pgAdmin4 servers.json only. pgpass is not written to disk (ISO 27K);
- * it is created temporarily in startDockerServicesAndConfigure and deleted after copy to container.
+ * Generates pgAdmin4 servers.json only. pgpass for the container is supplied via bind-mounted
+ * `.pgpass.bootstrap` (written by writePgpassBootstrap); not embedded in servers.json.
  *
  * @param {string} infraDir - Infrastructure directory path
- * @param {string} postgresPassword - PostgreSQL password (for servers.json PassFile reference only; password not stored in file)
+ * @param {string} postgresPassword - Used only for consistency / future template fields (password is not written into servers.json)
  */
 function generatePgAdminConfig(infraDir, postgresPassword) {
   const serversJsonTemplatePath = path.join(__dirname, '..', '..', 'templates', 'infra', 'servers.json.hbs');
@@ -401,9 +373,10 @@ psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "miso" -c "GRANT AL
  * @async
  * @param {string} devId - Developer ID
  * @param {string} adminSecretsPath - Path to admin secrets file
+ * @param {{ pgpassBootstrap?: boolean }} [prepOptions] - When pgpassBootstrap is false, skip/remove host pgpass bootstrap file (pgAdmin disabled)
  * @returns {Promise<Object>} Object with infraDir and postgresPassword
  */
-async function prepareInfraDirectory(devId, adminSecretsPath) {
+async function prepareInfraDirectory(devId, adminSecretsPath, prepOptions = {}) {
   const aifabrixDir = paths.getAifabrixSystemDir();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
@@ -427,6 +400,20 @@ async function prepareInfraDirectory(devId, adminSecretsPath) {
     '';
   generatePgAdminConfig(infraDir, postgresPassword);
 
+  const pgpassBootstrap = prepOptions.pgpassBootstrap !== false;
+  const bootstrapPath = path.join(infraDir, PGPASS_BOOTSTRAP_BASENAME);
+  if (pgpassBootstrap) {
+    writePgpassBootstrap(infraDir, postgresPassword);
+  } else {
+    try {
+      if (fs.existsSync(bootstrapPath)) {
+        fs.unlinkSync(bootstrapPath);
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
   return { infraDir, postgresPassword };
 }
 
@@ -483,6 +470,8 @@ module.exports = {
   checkDockerAvailability,
   ensureAdminSecrets,
   generatePgAdminConfig,
+  writePgpassBootstrap,
+  PGPASS_BOOTSTRAP_BASENAME,
   prepareInfraDirectory,
   resolveInfraStatePaths,
   ensureMisoInitScript,

package/lib/infrastructure/index.js

@@ -107,7 +107,9 @@ async function prepareInfrastructureEnvironment(developerId, options = {}) {
   }
 
   // Prepare infrastructure directory
-  const { infraDir } = await prepareInfraDirectory(devId, adminSecretsPath);
+  const { infraDir } = await prepareInfraDirectory(devId, adminSecretsPath, {
+    pgpassBootstrap: options.pgadmin !== false
+  });
   await ensureMisoInitScript(infraDir);
 
   return { devId, idNum, ports, templatePath, infraDir, adminSecretsPath, trustForwardedHeaders };

package/lib/infrastructure/services.js

@@ -50,30 +50,6 @@ async function startDockerServices(composePath, projectName, adminSecretsPath, i
   logger.log('Infrastructure services started successfully');
 }
 
-/**
- * Copy pgAdmin4 configuration files into container
- * @async
- * @param {string} pgadminContainerName - pgAdmin container name
- * @param {string} serversJsonPath - Path to servers.json file
- * @param {string} pgpassPath - Path to pgpass file
- */
-async function copyPgAdminConfig(pgadminContainerName, serversJsonPath, pgpassPath) {
-  const { execWithDockerEnv } = require('../utils/docker-exec');
-  try {
-    await new Promise(resolve => setTimeout(resolve, 2000)); // Wait for container to be ready
-    if (fs.existsSync(serversJsonPath)) {
-      await execWithDockerEnv(`docker cp "${serversJsonPath}" ${pgadminContainerName}:/pgadmin4/servers.json`);
-    }
-    if (fs.existsSync(pgpassPath)) {
-      await execWithDockerEnv(`docker cp "${pgpassPath}" ${pgadminContainerName}:/pgpass`);
-      await execWithDockerEnv(`docker exec ${pgadminContainerName} chmod 600 /pgpass`);
-    }
-  } catch (error) {
-    // Ignore copy errors - files might already be there or container not ready
-    logger.log('Note: Could not copy pgAdmin4 config files (this is OK if container was just restarted)');
-  }
-}
-
 /**
  * Prepare run env file from decrypted admin secrets.
  * @async
@@ -89,34 +65,12 @@ async function prepareRunEnv(infraDir) {
 }
 
 /**
- * Write pgpass file and copy pgAdmin config into container.
- * @async
- * @param {string} infraDir - Infrastructure directory
- * @param {Object} adminObj - Decrypted admin secrets object
- * @param {string} devId - Developer ID
- * @param {number} idNum - Developer ID number
- * @returns {Promise<string>} Path to pgpass run file
- */
-async function writePgpassAndCopyPgAdminConfig(infraDir, adminObj, devId, idNum) {
-  const pgpassRunPath = path.join(infraDir, '.pgpass.run');
-  const pgadminContainerName = idNum === 0 ? 'aifabrix-pgadmin' : `aifabrix-dev${devId}-pgadmin`;
-  const serversJsonPath = path.join(infraDir, 'servers.json');
-  const postgresPassword = adminObj.POSTGRES_PASSWORD || '';
-  const pgpassContent = `postgres:5432:postgres:pgadmin:${postgresPassword}\n`;
-  fs.writeFileSync(pgpassRunPath, pgpassContent, { mode: 0o600 });
-  await copyPgAdminConfig(pgadminContainerName, serversJsonPath, pgpassRunPath);
-  return pgpassRunPath;
-}
-
-/**
- * Remove temporary run files (env and pgpass) if they exist.
+ * Remove temporary run files (env) if they exist.
  * @param {string} runEnvPath - Path to .env.run
- * @param {string} [pgpassRunPath] - Path to .pgpass.run
  */
-function cleanupRunFiles(runEnvPath, pgpassRunPath) {
+function cleanupRunFiles(runEnvPath) {
   try {
     if (fs.existsSync(runEnvPath)) fs.unlinkSync(runEnvPath);
-    if (pgpassRunPath && fs.existsSync(pgpassRunPath)) fs.unlinkSync(pgpassRunPath);
   } catch {
     // Ignore unlink errors
   }
@@ -136,11 +90,9 @@ function cleanupRunFiles(runEnvPath, pgpassRunPath) {
  */
 async function startDockerServicesAndConfigure(composePath, devId, idNum, infraDir, opts = {}) {
   let runEnvPath;
-  let pgpassRunPath;
-  let adminObj;
   const { pgadmin = true, redisCommander = true, traefik = false } = opts;
   try {
-    ({ adminObj, runEnvPath } = await prepareRunEnv(infraDir));
+    ({ runEnvPath } = await prepareRunEnv(infraDir));
   } catch (err) {
     throw new Error(`Failed to prepare infra env: ${err.message}`);
   }
@@ -148,13 +100,10 @@ async function startDockerServicesAndConfigure(composePath, devId, idNum, infraD
   try {
     const projectName = getInfraProjectName(devId);
     await startDockerServices(composePath, projectName, runEnvPath, infraDir);
-    if (pgadmin) {
-      pgpassRunPath = await writePgpassAndCopyPgAdminConfig(infraDir, adminObj, devId, idNum);
-    }
     await waitForServices(devId, { pgadmin, redisCommander, traefik });
     logger.log('All services are healthy and ready');
   } finally {
-    cleanupRunFiles(runEnvPath, pgpassRunPath);
+    cleanupRunFiles(runEnvPath);
   }
 }
 
@@ -236,7 +185,6 @@ async function checkInfraHealth(devId = null, options = {}) {
 module.exports = {
   execAsyncWithCwd,
   startDockerServices,
-  copyPgAdminConfig,
   startDockerServicesAndConfigure,
   waitForServices,
   checkInfraHealth

package/lib/schema/external-system.schema.json

@@ -679,12 +679,15 @@
            "publicKey":{
               "type":"string",
               "minLength":1,
-              "description":"Public key used to verify RS256 signatures. Private key must never appear in schema."
+              "description":"Public verification material (SPKI PEM for RS256; dev placeholder for HS256). Private keys must never appear in config."
            },
            "algorithm":{
               "type":"string",
-              "const":"RS256",
-              "description":"Signing algorithm. Must be RS256."
+              "enum":[
+                 "RS256",
+                 "HS256"
+              ],
+              "description":"Signing algorithm for certificate verification (RS256 in production; HS256 only for local dev when the dataplane uses the dev HMAC signer)."
            },
            "issuer":{
               "type":"string",
@@ -695,6 +698,25 @@
               "type":"string",
               "minLength":1,
               "description":"Certification version identifier; must align with external system versioning."
+           },
+           "status":{
+              "type":"string",
+              "enum":[
+                 "passed",
+                 "not_passed",
+                 "pending"
+              ],
+              "description":"Outcome of certification evaluation for this block (aligns with DatasourceTestRun certificate.status)."
+           },
+           "level":{
+              "type":"string",
+              "enum":[
+                 "BRONZE",
+                 "SILVER",
+                 "GOLD",
+                 "PLATINUM"
+              ],
+              "description":"Achieved certification tier (aligns with integration certificate certificationLevel)."
            }
         },
         "additionalProperties":false

package/lib/schema/type/document-storage.json

@@ -7,12 +7,12 @@
     "key": "document-storage-schema",
     "name": "Document Storage Configuration Schema",
     "description": "JSON schema for validating document storage configurations",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "type": "schema",
     "category": "document-storage",
     "author": "AI Fabrix Team",
     "createdAt": "2026-01-02T00:00:00Z",
-    "updatedAt": "2026-03-31T00:00:00Z",
+    "updatedAt": "2026-04-22T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -63,6 +63,14 @@
           "Added optional securityLevel classification field (public/internal/restricted/confidential)"
         ],
         "breaking": false
+      },
+      {
+        "version": "1.3.0",
+        "date": "2026-04-22T00:00:00Z",
+        "changes": [
+          "Added optional parameterLookupCoalesceNestedItemScope (boolean, default true) for manifest-controlled binary parameter lookup enrichment"
+        ],
+        "breaking": false
       }
     ]
   },
@@ -120,6 +128,11 @@
       "default": false,
       "description": "If true, removes fetch.query when applying binary retrieval path override."
     },
+    "parameterLookupCoalesceNestedItemScope": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true, binary parameterMapping and HTTP path templates use a lookup view that merges metadata and coalesces storage-scope ids from a nested item parentReference when the row's parentReference omits them. Set false for strict manifest-only paths."
+    },
     "processing": {
       "type": "object",
       "properties": {

package/lib/utils/api.js

@@ -16,6 +16,26 @@ const auditLogger = require('../core/audit-logger');
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 
+/** Cap for optional per-request ``timeoutMs`` (validation run E2E can block on one POST). */
+const MAX_SINGLE_REQUEST_TIMEOUT_MS = 45 * 60 * 1000;
+
+/**
+ * Resolve per-request AbortSignal timeout from fetch options.
+ * @param {Object} options - Same object passed to fetch (may include timeoutMs / requestTimeoutMs)
+ * @returns {number}
+ */
+function resolveSingleRequestTimeoutMs(options) {
+  const raw = options?.requestTimeoutMs ?? options?.timeoutMs;
+  if (raw === undefined || raw === null || raw === '') {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  return Math.min(n, MAX_SINGLE_REQUEST_TIMEOUT_MS);
+}
+
 /**
  * Logs API request performance metrics and errors to audit log
  * @param {Object} params - Performance logging parameters
@@ -276,9 +296,11 @@ async function handleNetworkError(error, url, options, duration) {
 
 /**
  * Make an API call with proper error handling
- * Uses a 30s timeout to avoid hanging when the controller is unreachable (Azure cold start can exceed 5s).
+ * Uses a 30s timeout by default. Pass ``options.timeoutMs`` or ``options.requestTimeoutMs`` for
+ * longer single requests (e.g. dataplane validation run E2E POST); capped at 45 minutes.
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options (signal, method, headers, body, etc.)
+ * @param {number} [options.timeoutMs] - Optional per-request timeout (ms) when ``signal`` omitted
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
@@ -292,9 +314,12 @@ async function makeApiCall(url, options = {}) {
 
   const startTime = Date.now();
   const fetchOptions = { ...options };
+  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
   if (!fetchOptions.signal) {
-    fetchOptions.signal = AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
   }
+  delete fetchOptions.timeoutMs;
+  delete fetchOptions.requestTimeoutMs;
 
   try {
     const response = await fetch(url, fetchOptions);
@@ -309,7 +334,7 @@ async function makeApiCall(url, options = {}) {
     const duration = Date.now() - startTime;
     const error = err?.name === 'AbortError'
       ? new Error(
-        `Request timed out after ${DEFAULT_REQUEST_TIMEOUT_MS / 1000} seconds. The controller may be unreachable. Check the URL and network.`
+        `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The controller may be unreachable. Check the URL and network.`
       )
       : err;
     return await handleNetworkError(error, url, options, duration);