@aifabrix/builder 2.47.4 → 2.49.0

package/lib/utils/compose-generator.js

@@ -116,7 +116,7 @@ function buildImageConfig(config, appName, imageOverride) {
  * @param {string|null|undefined} [readinessSuffix] - Path after vdir (default /health/ready or healthCheck.readinessPathSuffix)
  * @returns {string} Absolute path starting with /
  */
-function computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, readinessSuffix) {
+function computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, readinessSuffix, developerRootDomain) {
   const hc = config.healthCheck || {};
   let suffix = '/health/ready';
   if (
@@ -128,7 +128,7 @@ function computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, r
   } else if (typeof hc.readinessPathSuffix === 'string' && hc.readinessPathSuffix.startsWith('/')) {
     suffix = hc.readinessPathSuffix;
   }
-  const traefik = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer);
+  const traefik = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer, developerRootDomain);
   if (traefik.enabled === true) {
     const p = traefik.path;
     if (!p || p === '/') {
@@ -158,7 +158,7 @@ function computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, r
  * @param {{ skipVdirMergeWhenPathIsBareHealth?: boolean }} [opts] - When `skipVdirMergeWhenPathIsBareHealth`, path `/health` is left as-is (in-container probe; ingress strips vdir for miso/dataplane). Deployment JSON health paths do **not** use this helper — see `buildHealthCheck` in `builders.js` (YAML paths only).
  * @returns {string} Absolute path starting with /
  */
-function resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remoteServer, opts) {
+function resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remoteServer, opts, developerRootDomain) {
   const hc = config.healthCheck || {};
   const raw = typeof hc.path === 'string' && hc.path.startsWith('/') ? hc.path : '/health';
   const fd = config.frontDoorRouting;
@@ -168,7 +168,7 @@ function resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remot
   if (opts && opts.skipVdirMergeWhenPathIsBareHealth === true && raw === '/health') {
     return raw;
   }
-  const traefik = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer);
+  const traefik = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer, developerRootDomain);
   if (traefik.enabled !== true) {
     return raw;
   }
@@ -178,7 +178,7 @@ function resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remot
       ? ''
       : String(vdirRaw).replace(/\/+$/, '');
   if (!vdir) {
-    return computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, raw);
+    return computeAlignedHealthCheckPath(config, devId, scopeOpts, remoteServer, raw, developerRootDomain);
   }
   if (raw === vdir || raw.startsWith(`${vdir}/`)) {
     return raw;
@@ -192,13 +192,14 @@ function resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remot
  * @param {string|number} devId - Developer id
  * @param {Object|null} scopeOpts - Env-scoped compose options
  * @param {string|null|undefined} remoteServer - Remote server URL
+ * @param {string|null|undefined} [developerRootDomain] - App hostname root
  * @returns {Object} Health check configuration
  */
-function buildHealthCheckConfig(config, devId, scopeOpts, remoteServer) {
+function buildHealthCheckConfig(config, devId, scopeOpts, remoteServer, developerRootDomain) {
   const hc = config.healthCheck || {};
   const path = resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remoteServer, {
     skipVdirMergeWhenPathIsBareHealth: true
-  });
+  }, developerRootDomain);
   return {
     path,
     interval: hc.interval || 30,
@@ -230,10 +231,11 @@ function buildDevUsername(devId) {
  * @param {Object|null} scopeOpts - Env-scoped Traefik path
  * @param {string|null|undefined} remoteServer - From config (for ${REMOTE_HOST})
  * @param {string|undefined} [resolvedHealthPathForStrip] - Compose health path; when omitted, derived via resolveHealthCheckPathWithFrontDoorVdir (same as probe)
+ * @param {string|null|undefined} [developerRootDomain] - App hostname root from settings
  * @returns {Object} Traefik configuration object
  */
-function buildTraefikConfig(config, devId, scopeOpts = null, remoteServer = null, resolvedHealthPathForStrip) {
-  const base = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer);
+function buildTraefikConfig(config, devId, scopeOpts = null, remoteServer = null, resolvedHealthPathForStrip, developerRootDomain) {
+  const base = buildTraefikIngressBase(config, devId, scopeOpts, remoteServer, developerRootDomain);
   if (!base.enabled) {
     return { enabled: false };
   }
@@ -242,7 +244,7 @@ function buildTraefikConfig(config, devId, scopeOpts = null, remoteServer = null
       ? String(resolvedHealthPathForStrip)
       : resolveHealthCheckPathWithFrontDoorVdir(config, devId, scopeOpts, remoteServer, {
         skipVdirMergeWhenPathIsBareHealth: true
-      });
+      }, developerRootDomain);
   const devNum = parseDeveloperIdNum(devId);
   // Shared builder host: nginx terminates TLS on :443 and proxies HTTP to per-dev Traefik :80 (e.g. 280).
   // Traefik must only attach routers to `web` for developer-id > 0; `websecure`+tls labels without
@@ -282,6 +284,7 @@ function buildRequiresConfig(config) {
  * @param {string} [runExtras.imageOverride] - Full image reference for run (e.g. from --image)
  * @param {Object|null} [runExtras.scopeOpts] - Traefik / scoped compose options
  * @param {string|null|undefined} [runExtras.remoteServer] - For ${REMOTE_HOST} in frontDoorRouting.host
+ * @param {string|null|undefined} [runExtras.developerRootDomain] - App hostname root (overrides remote-server host)
  * @param {boolean} [runExtras.omitAppTraefikLabels] - When true (user config `traefik: false`), omit Traefik labels and BASE_PATH env from compose even if application.yaml enables frontDoorRouting
  * @returns {Object} Service configuration
  */
@@ -290,6 +293,7 @@ function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
     imageOverride = null,
     scopeOpts = null,
     remoteServer = null,
+    developerRootDomain = null,
     omitAppTraefikLabels = false
   } = runExtras;
   const containerPortValue = getContainerPort(config, 3000);
@@ -303,7 +307,7 @@ function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
     ? composeTraefikServiceKey(appName, scopeOpts.runEnvKey)
     : null;
   const scopeForHealthAndTraefik = useTraefikScope ? scopeOpts : null;
-  const healthCheck = buildHealthCheckConfig(config, devId, scopeForHealthAndTraefik, remoteServer);
+  const healthCheck = buildHealthCheckConfig(config, devId, scopeForHealthAndTraefik, remoteServer, developerRootDomain);
   return {
     app: buildAppConfig(appName, config, composeAppKey),
     image: buildImageConfig(config, appName, imageOverride),
@@ -319,7 +323,8 @@ function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
           devId,
           scopeForHealthAndTraefik,
           remoteServer,
-          healthCheck.path
+          healthCheck.path,
+          developerRootDomain
         ),
     ...buildRequiresConfig(config)
   };
@@ -379,20 +384,34 @@ function buildNetworkAndContainerNames(appName, devId, idNum, scopeOpts = null)
 }
 
 const { createGenerateDockerCompose } = require('./compose-generate-docker-compose');
-async function getRemoteServerForCompose() {
+async function getFrontDoorHostContextForCompose() {
   try {
     const rs = await config.getRemoteServer();
-    return rs && String(rs).trim() ? String(rs).trim() : null;
+    const remoteServer = rs && String(rs).trim() ? String(rs).trim() : null;
+    let developerRootDomain = null;
+    try {
+      const root = await config.getDeveloperRootDomain();
+      developerRootDomain = root && String(root).trim() ? String(root).trim() : null;
+    } catch {
+      developerRootDomain = null;
+    }
+    return { remoteServer, developerRootDomain };
   } catch {
-    return null;
+    return { remoteServer: null, developerRootDomain: null };
   }
 }
 
+async function getRemoteServerForCompose() {
+  const ctx = await getFrontDoorHostContextForCompose();
+  return ctx.remoteServer;
+}
+
 const generateDockerCompose = createGenerateDockerCompose({
   loadDockerComposeTemplate,
   resolveComposeImageOverrideString,
   getDeveloperIdAndNumeric,
   getRemoteServerForCompose,
+  getFrontDoorHostContextForCompose,
   buildNetworkAndContainerNames,
   buildServiceConfig,
   buildVolumesConfig,

package/lib/utils/compose-traefik-ingress-base.js

@@ -10,6 +10,10 @@ const {
   buildEnvScopedTraefikPath
 } = require('./environment-scoped-resources');
 const { parseDeveloperIdNum } = require('./declarative-url-ports');
+const {
+  resolveRemoteHostForFrontDoor,
+  hasFrontDoorRemoteHostContext
+} = require('./remote-host-for-front-door');
 
 /**
  * Derives base path from routing pattern by removing trailing wildcards
@@ -66,21 +70,15 @@ function buildDevUsernameForFrontDoorHost(devId) {
  * @param {string} template
  * @param {string|number|null|undefined} developerIdRaw
  * @param {string|null|undefined} remoteServer
+ * @param {string|null|undefined} [developerRootDomain] - App hostname root (overrides remote-server hostname for ${REMOTE_HOST})
  * @returns {string}
  */
-function expandFrontDoorHostPlaceholders(template, developerIdRaw, remoteServer) {
+function expandFrontDoorHostPlaceholders(template, developerIdRaw, remoteServer, developerRootDomain) {
   let t = String(template || '');
   t = t.replace(/\$\{DEV_USERNAME\}\$\{REMOTE_HOST\}/g, '${DEV_USERNAME}.${REMOTE_HOST}');
   const devU = buildDevUsernameForFrontDoorHost(developerIdRaw);
   t = t.replace(/\$\{DEV_USERNAME\}/g, devU);
-  let remoteHost = '';
-  try {
-    if (remoteServer && String(remoteServer).trim()) {
-      remoteHost = new URL(String(remoteServer).trim()).hostname;
-    }
-  } catch {
-    remoteHost = '';
-  }
+  const remoteHost = resolveRemoteHostForFrontDoor({ remoteServer, developerRootDomain });
   t = t.replace(/\$\{REMOTE_HOST\}/g, remoteHost);
   t = t.replace(/^\.+/g, '').replace(/\.{2,}/g, '.').replace(/\.+$/g, '').trim();
   return t;
@@ -90,13 +88,13 @@ function templateUsesRemoteHostPlaceholder(hostTemplate) {
   return /\$\{REMOTE_HOST\}/.test(String(hostTemplate || ''));
 }
 
-function resolveTraefikRouterHost(hostTemplate, developerIdRaw, remoteServer) {
+function resolveTraefikRouterHost(hostTemplate, developerIdRaw, remoteServer, developerRootDomain) {
   const usesRemote = templateUsesRemoteHostPlaceholder(hostTemplate);
-  const hasRemote = Boolean(remoteServer && String(remoteServer).trim());
+  const hasRemote = hasFrontDoorRemoteHostContext({ remoteServer, developerRootDomain });
   if (usesRemote && !hasRemote) {
     return 'localhost';
   }
-  return expandFrontDoorHostPlaceholders(hostTemplate, developerIdRaw, remoteServer);
+  return expandFrontDoorHostPlaceholders(hostTemplate, developerIdRaw, remoteServer, developerRootDomain);
 }
 
 /**
@@ -108,9 +106,10 @@ function resolveTraefikRouterHost(hostTemplate, developerIdRaw, remoteServer) {
  * @param {string|number} devId - Developer id for host expansion
  * @param {Object|null} scopeOpts - Env-scoped Traefik path (effectiveEnvironmentScopedResources, runEnvKey)
  * @param {string|null|undefined} remoteServer - For ${REMOTE_HOST}
+ * @param {string|null|undefined} [developerRootDomain] - App hostname root from settings
  * @returns {{ enabled: false } | { enabled: true, host: string, path: string, tls: boolean, certStore: string|null }}
  */
-function buildTraefikIngressBase(config, devId, scopeOpts, remoteServer) {
+function buildTraefikIngressBase(config, devId, scopeOpts, remoteServer, developerRootDomain) {
   const frontDoor = config.frontDoorRouting;
   if (!frontDoor || frontDoor.enabled !== true) {
     return { enabled: false };
@@ -118,7 +117,7 @@ function buildTraefikIngressBase(config, devId, scopeOpts, remoteServer) {
   if (!frontDoor.host || typeof frontDoor.host !== 'string') {
     throw new Error('frontDoorRouting.host is required when frontDoorRouting.enabled is true');
   }
-  const host = resolveTraefikRouterHost(frontDoor.host, devId, remoteServer);
+  const host = resolveTraefikRouterHost(frontDoor.host, devId, remoteServer, developerRootDomain);
   const basePath = derivePathFromPattern(frontDoor.pattern);
   let pathOut = basePath;
   if (

package/lib/utils/config-paths.js

@@ -22,6 +22,7 @@ const SETTINGS_RESPONSE_KEYS = [
   'aifabrix-env-config',
   'remote-server',
   'docker-endpoint',
+  'developer-root-domain',
   'docker-tls-skip-verify',
   'sync-ssh-user',
   'sync-ssh-host'
@@ -264,8 +265,8 @@ function createRemoteConfigGetters(getConfigFn) {
       return getPathConfig(getConfigFn, 'docker-endpoint');
     },
     /**
-     * When true, Docker CLI may use DOCKER_TLS_VERIFY=0 only when ca.pem is absent (no trust anchor).
-     * If ca.pem exists (e.g. after issue-cert), the daemon is always verified regardless of this flag.
+     * When true, Docker CLI uses DOCKER_TLS_VERIFY=0 (client certs still sent when present).
+     * Applies even when ca.pem exists (internal issue-cert CA vs public Docker daemon cert).
      */
     async getDockerTlsSkipVerify() {
       const envRaw = process.env.AIFABRIX_DOCKER_TLS_SKIP_VERIFY;
@@ -290,6 +291,9 @@ function createRemoteConfigGetters(getConfigFn) {
     },
     async getSyncSshHost() {
       return getPathConfig(getConfigFn, 'sync-ssh-host');
+    },
+    async getDeveloperRootDomain() {
+      return getPathConfig(getConfigFn, 'developer-root-domain');
     }
   };
 }
@@ -424,6 +428,7 @@ module.exports = {
   resolveEnvConfigPathToAbsolute,
   SETTINGS_RESPONSE_KEYS,
   applySecretsUrlFromRemote,
-  applySyncAndDockerFromHost
+  applySyncAndDockerFromHost,
+  hostnameFromUrl
 };
 

package/lib/utils/dev-ca-docker-augment.js

@@ -0,0 +1,54 @@
+/**
+ * Persist ca.pem after merging Docker daemon TLS trust (wildcard/public CA).
+ *
+ * @fileoverview Write augmented ca.pem for remote Docker
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+const { normalizePemNewlines, getCertDir } = require('./dev-cert-helper');
+const {
+  resolveDockerEndpointForCaAugment,
+  augmentCaPemWithDockerDaemonChain,
+  writeDockerDaemonCaMarker
+} = require('./docker-daemon-tls-ca');
+
+/**
+ * @param {string} configDir
+ * @param {string} devId
+ * @param {string|null|undefined} existingCaPem
+ * @param {{ settings?: Object|null, remoteServerUrl?: string|null, warn?: (msg: string) => void }} ctx
+ * @returns {Promise<string|null>}
+ */
+async function augmentAndSaveCaPemForRemoteDocker(configDir, devId, existingCaPem, ctx) {
+  const dockerEndpoint = resolveDockerEndpointForCaAugment({
+    settings: ctx && ctx.settings,
+    remoteServerUrl: ctx && ctx.remoteServerUrl
+  });
+  if (!dockerEndpoint) {
+    return existingCaPem || null;
+  }
+
+  const augmented = await augmentCaPemWithDockerDaemonChain(existingCaPem, dockerEndpoint, {
+    warn: ctx && ctx.warn
+  });
+  if (!augmented || augmented === existingCaPem) {
+    return existingCaPem || null;
+  }
+
+  const certDir = getCertDir(configDir, devId);
+  await fs.mkdir(certDir, { recursive: true });
+  await fs.writeFile(
+    path.join(certDir, 'ca.pem'),
+    normalizePemNewlines(augmented),
+    { mode: 0o600 }
+  );
+  await writeDockerDaemonCaMarker(certDir);
+  return augmented;
+}
+
+module.exports = { augmentAndSaveCaPemForRemoteDocker };

package/lib/utils/dev-user-groups.js

@@ -8,6 +8,7 @@
 const ALLOWED_DEV_GROUPS = Object.freeze([
   'admin',
   'secret-manager',
+  'secret-reader',
   'developer',
   'docker'
 ]);

package/lib/utils/docker-daemon-tls-ca.js

@@ -0,0 +1,363 @@
+/**
+ * Fetch Docker Engine TLS trust anchors when the daemon uses a public/wildcard server
+ * certificate (e.g. Sectigo *.aifabrix.dev) while issue-cert ca.pem holds the internal CA.
+ * Docker CLI verifies the daemon with ca.pem only (not the OS trust store).
+ *
+ * @fileoverview Docker daemon TLS CA chain for remote docker-endpoint
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const tls = require('tls');
+const { mergeCaPemBlocks } = require('./dev-cert-helper');
+
+const DEFAULT_DOCKER_TLS_PORT = 2376;
+const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+/** Written under ~/.aifabrix/certs/<developer-id>/ when ca.pem includes Docker daemon trust. */
+const DOCKER_DAEMON_CA_MARKER = '.docker-daemon-ca-augmented';
+
+/**
+ * @param {Buffer|string} der
+ * @returns {string}
+ */
+function derCertToPem(der) {
+  const buf = Buffer.isBuffer(der) ? der : Buffer.from(der);
+  const lines = buf.toString('base64').match(/.{1,64}/g) || [];
+  return `-----BEGIN CERTIFICATE-----\n${lines.join('\n')}\n-----END CERTIFICATE-----`;
+}
+
+/**
+ * @param {import('tls').PeerCertificate} peerCert
+ * @returns {string[]}
+ */
+function collectIssuerChainPems(peerCert) {
+  const pems = [];
+  const seen = new Set();
+  let cert = peerCert && peerCert.issuerCertificate;
+  while (cert && cert.raw) {
+    const fp = cert.fingerprint256 || cert.fingerprint;
+    if (fp) {
+      if (seen.has(fp)) break;
+      seen.add(fp);
+    }
+    if (peerCert.fingerprint && cert.fingerprint === peerCert.fingerprint) break;
+    pems.push(derCertToPem(cert.raw));
+    const next = cert.issuerCertificate;
+    if (!next || next === cert) break;
+    cert = next;
+  }
+  return pems;
+}
+
+/**
+ * @param {string} rest - Host[:port] after tcp://
+ * @returns {{ host: string, port: number }|null}
+ */
+function parseBracketedTcpHostPort(rest) {
+  if (!rest.startsWith('[')) return null;
+  const end = rest.indexOf(']');
+  if (end === -1) return null;
+  const host = rest.slice(1, end);
+  let port = DEFAULT_DOCKER_TLS_PORT;
+  const after = rest.slice(end + 1);
+  if (after.startsWith(':')) {
+    const p = parseInt(after.slice(1), 10);
+    if (!Number.isNaN(p)) port = p;
+  }
+  return { host, port };
+}
+
+/**
+ * @param {string} rest - Host[:port] after tcp://
+ * @returns {{ host: string, port: number }}
+ */
+function parsePlainTcpHostPort(rest) {
+  const colonIdx = rest.lastIndexOf(':');
+  if (colonIdx > 0 && /^\d+$/.test(rest.slice(colonIdx + 1))) {
+    return {
+      host: rest.slice(0, colonIdx),
+      port: parseInt(rest.slice(colonIdx + 1), 10)
+    };
+  }
+  return { host: rest, port: DEFAULT_DOCKER_TLS_PORT };
+}
+
+/**
+ * @param {string} trimmed
+ * @returns {{ host: string, port: number }|null}
+ */
+function parseTcpSchemeEndpoint(trimmed) {
+  const rest = trimmed.slice(6).split('/')[0];
+  return parseBracketedTcpHostPort(rest) || parsePlainTcpHostPort(rest);
+}
+
+/**
+ * @param {string} trimmed
+ * @returns {{ host: string, port: number }|null}
+ */
+function parseDockerEndpointViaUrl(trimmed) {
+  try {
+    const u = new URL(trimmed.includes('://') ? trimmed : `tcp://${trimmed}`);
+    const host = String(u.hostname || '').trim();
+    if (!host) return null;
+    let port = DEFAULT_DOCKER_TLS_PORT;
+    if (u.port) {
+      const p = parseInt(u.port, 10);
+      if (!Number.isNaN(p)) port = p;
+    }
+    return { host, port };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse docker-endpoint (tcp://host:port) into TLS connect parameters.
+ * @param {string} endpoint
+ * @returns {{ host: string, port: number, servername: string }|null}
+ */
+function parseDockerTlsEndpoint(endpoint) {
+  const trimmed = String(endpoint || '').trim();
+  if (!trimmed) return null;
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith('unix:')) return null;
+
+  const parsed = lower.startsWith('tcp://')
+    ? parseTcpSchemeEndpoint(trimmed)
+    : parseDockerEndpointViaUrl(trimmed);
+  if (!parsed || !parsed.host) return null;
+  return { host: parsed.host, port: parsed.port, servername: parsed.host };
+}
+
+/**
+ * @param {string} remoteServerUrl
+ * @returns {string|null}
+ */
+function dockerEndpointFromRemoteServer(remoteServerUrl) {
+  try {
+    const u = new URL(String(remoteServerUrl || '').trim().replace(/\/+$/, ''));
+    if (!u.hostname) return null;
+    return `tcp://${u.hostname}:${DEFAULT_DOCKER_TLS_PORT}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve docker-endpoint for CA augmentation (settings override, else derive from remote-server).
+ * @param {{ settings?: Object|null, remoteServerUrl?: string|null }} ctx
+ * @returns {string|null}
+ */
+function resolveDockerEndpointForCaAugment(ctx) {
+  const settings = ctx && ctx.settings;
+  const fromSettings = settings && settings['docker-endpoint'];
+  if (typeof fromSettings === 'string' && fromSettings.trim()) {
+    return fromSettings.trim();
+  }
+  return dockerEndpointFromRemoteServer(ctx && ctx.remoteServerUrl);
+}
+
+/**
+ * Connect to Docker Engine TLS port and return issuer-chain PEM for daemon server verification.
+ * @param {string} dockerEndpoint - e.g. tcp://builder01.aifabrix.dev:2376
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<string|null>}
+ */
+function fetchDockerDaemonTlsCaPem(dockerEndpoint, opts) {
+  const parsed = parseDockerTlsEndpoint(dockerEndpoint);
+  if (!parsed) {
+    return Promise.resolve(null);
+  }
+  const timeoutMs =
+    opts && typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : DEFAULT_FETCH_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const socket = tls.connect(
+      {
+        host: parsed.host,
+        port: parsed.port,
+        servername: parsed.servername,
+        rejectUnauthorized: false
+      },
+      () => {
+        try {
+          const peer = socket.getPeerCertificate(true);
+          const chain = collectIssuerChainPems(peer);
+          socket.end();
+          finish(resolve, chain.length ? chain.join('\n\n') : null);
+        } catch (err) {
+          socket.destroy();
+          finish(reject, err);
+        }
+      }
+    );
+
+    const timer = setTimeout(() => {
+      socket.destroy(new Error(`Timed out fetching Docker daemon TLS chain (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    function finish(fn, value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn(value);
+    }
+
+    socket.on('error', (err) => {
+      finish(reject, err);
+    });
+  });
+}
+
+/**
+ * Merge Docker daemon public/wildcard trust anchors into ca.pem blocks.
+ * @param {string|null|undefined} existingCaPem
+ * @param {string|null|undefined} dockerEndpoint
+ * @param {{ timeoutMs?: number, warn?: (msg: string) => void }} [opts]
+ * @returns {Promise<string|null>}
+ */
+async function augmentCaPemWithDockerDaemonChain(existingCaPem, dockerEndpoint, opts) {
+  if (!dockerEndpoint || typeof dockerEndpoint !== 'string' || !dockerEndpoint.trim()) {
+    return existingCaPem || null;
+  }
+  try {
+    const dockerCaPem = await fetchDockerDaemonTlsCaPem(dockerEndpoint.trim(), opts);
+    if (!dockerCaPem) {
+      return existingCaPem || null;
+    }
+    return mergeCaPemBlocks(existingCaPem, dockerCaPem);
+  } catch (err) {
+    const warn = opts && typeof opts.warn === 'function' ? opts.warn : null;
+    const msg = err && err.message ? err.message : String(err);
+    if (warn) {
+      warn(
+        `Could not fetch Docker daemon TLS chain from ${dockerEndpoint.trim()} (${msg}). ` +
+          'Remote docker may fail until ca.pem includes the daemon trust anchor (re-run dev init or dev refresh).'
+      );
+    }
+    return existingCaPem || null;
+  }
+}
+
+/**
+ * Split PEM file into individual certificate blocks.
+ * @param {string} pem
+ * @returns {string[]}
+ */
+function splitPemCertificateBlocks(pem) {
+  if (!pem || typeof pem !== 'string') return [];
+  return pem
+    .replace(/\r\n/g, '\n')
+    .split(/(?=-----BEGIN CERTIFICATE-----)/)
+    .map((block) => block.trim())
+    .filter(Boolean);
+}
+
+/**
+ * True when existing ca.pem already contains every issuer from the live Docker daemon chain.
+ * @param {string|null|undefined} existingCaPem
+ * @param {string|null|undefined} dockerEndpoint
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<boolean>}
+ */
+async function caPemTrustsDockerDaemon(existingCaPem, dockerEndpoint, opts) {
+  if (!existingCaPem || !dockerEndpoint) return false;
+  try {
+    const dockerChain = await fetchDockerDaemonTlsCaPem(dockerEndpoint.trim(), opts);
+    if (!dockerChain) return false;
+    const normalizedExisting = String(existingCaPem).replace(/\r\n/g, '\n');
+    const blocks = splitPemCertificateBlocks(dockerChain);
+    if (!blocks.length) return false;
+    return blocks.every((block) => normalizedExisting.includes(block));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} certDir
+ * @returns {Promise<void>}
+ */
+async function writeDockerDaemonCaMarker(certDir) {
+  const fs = require('fs').promises;
+  const markerPath = require('path').join(certDir, DOCKER_DAEMON_CA_MARKER);
+  await fs.writeFile(markerPath, `augmentedAt=${new Date().toISOString()}\n`, { mode: 0o600 });
+}
+
+/**
+ * @param {string} certDir
+ * @param {string} existingCaPem
+ * @param {string} dockerEndpoint
+ * @param {{ timeoutMs?: number }} fetchOpts
+ * @returns {Promise<boolean>}
+ */
+async function augmentCaPemForDockerVerify(certDir, existingCaPem, dockerEndpoint, fetchOpts) {
+  const fs = require('fs');
+  const path = require('path');
+  if (await caPemTrustsDockerDaemon(existingCaPem, dockerEndpoint, fetchOpts)) {
+    await writeDockerDaemonCaMarker(certDir);
+    return true;
+  }
+  const augmented = await augmentCaPemWithDockerDaemonChain(existingCaPem, dockerEndpoint, fetchOpts);
+  if (!augmented || augmented === existingCaPem) return false;
+  const { normalizePemNewlines } = require('./dev-cert-helper');
+  await fs.promises.writeFile(
+    path.join(certDir, 'ca.pem'),
+    normalizePemNewlines(augmented),
+    { mode: 0o600 }
+  );
+  await writeDockerDaemonCaMarker(certDir);
+  return true;
+}
+
+/**
+ * Decide whether Docker CLI should verify the daemon certificate (DOCKER_TLS_VERIFY=1).
+ * When ca.pem holds only the internal issue-cert CA but the daemon uses a public/wildcard cert,
+ * returns false so client mTLS still works with DOCKER_TLS_VERIFY=0.
+ *
+ * @param {{ certDir: string, existingCaPem: string, dockerEndpoint: string|null, remoteServerUrl?: string|null, settings?: Object|null, skipVerify?: boolean }} ctx
+ * @returns {Promise<boolean>}
+ */
+async function resolveRemoteDockerDaemonVerify(ctx) {
+  if (ctx && ctx.skipVerify) return false;
+  const certDir = ctx && ctx.certDir;
+  const existingCaPem = ctx && ctx.existingCaPem;
+  if (!certDir || !existingCaPem) return false;
+
+  const fs = require('fs');
+  const path = require('path');
+  const markerPath = path.join(certDir, DOCKER_DAEMON_CA_MARKER);
+  if (fs.existsSync(markerPath)) return true;
+
+  const dockerEndpoint = resolveDockerEndpointForCaAugment({
+    settings: ctx.settings,
+    remoteServerUrl: ctx.remoteServerUrl
+  }) || (ctx.dockerEndpoint && String(ctx.dockerEndpoint).trim()) || null;
+  if (!dockerEndpoint) return true;
+
+  const fetchOpts = { timeoutMs: DEFAULT_FETCH_TIMEOUT_MS };
+  return augmentCaPemForDockerVerify(certDir, existingCaPem, dockerEndpoint, fetchOpts);
+}
+
+module.exports = {
+  DEFAULT_DOCKER_TLS_PORT,
+  DEFAULT_FETCH_TIMEOUT_MS,
+  DOCKER_DAEMON_CA_MARKER,
+  parseDockerTlsEndpoint,
+  dockerEndpointFromRemoteServer,
+  resolveDockerEndpointForCaAugment,
+  fetchDockerDaemonTlsCaPem,
+  augmentCaPemWithDockerDaemonChain,
+  caPemTrustsDockerDaemon,
+  writeDockerDaemonCaMarker,
+  resolveRemoteDockerDaemonVerify,
+  splitPemCertificateBlocks,
+  derCertToPem,
+  collectIssuerChainPems
+};