@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/secrets-utils.js

@@ -14,29 +14,23 @@ const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
+const { ensureSecureFilePermissions } = require('./secure-file-permissions');
 const { getContainerPort } = require('./port-resolver');
 const { loadYamlTolerantOfDuplicateKeys } = require('./secrets-generator');
 
 /**
- * Parses secrets YAML content with fallback for duplicate keys.
+ * Parses secrets YAML content with fallback for duplicate keys and broken concat files
+ * (e.g. empty map `{}` then appended key lines — invalid without `---`).
  * @param {string} content - Raw file content
  * @returns {Object} Parsed secrets object
  */
 function parseSecretsContent(content) {
-  try {
-    return yaml.load(content);
-  } catch (yamlErr) {
-    const msg = yamlErr.message || '';
-    if (msg.includes('duplicate') || msg.includes('duplicated mapping')) {
-      return loadYamlTolerantOfDuplicateKeys(content);
-    }
-    throw yamlErr;
-  }
+  return loadYamlTolerantOfDuplicateKeys(content);
 }
 
 /**
  * Loads secrets from file with cascading lookup support
- * First checks ~/.aifabrix/secrets.local.yaml, then aifabrix-secrets from config.yaml
+ * First checks the primary user secrets file (see getPrimaryUserSecretsLocalPath in paths.js), then aifabrix-secrets from config.yaml
  *
  * @async
  * @function loadSecretsFromFile
@@ -50,7 +44,7 @@ async function loadSecretsFromFile(filePath) {
 
   try {
     const content = fs.readFileSync(filePath, 'utf8');
-    const secrets = yaml.load(content);
+    const secrets = parseSecretsContent(content);
 
     if (!secrets || typeof secrets !== 'object') {
       return {};
@@ -64,20 +58,19 @@ async function loadSecretsFromFile(filePath) {
 }
 
 /**
- * Loads user secrets from the primary config directory (AIFABRIX_HOME or ~/.aifabrix).
+ * Loads user secrets from getPrimaryUserSecretsLocalPath() (same dir as config.yaml resolution).
  * Used as the master source when merging with project/public secrets: user values win,
  * missing keys are filled from the public (aifabrix-secrets) file.
- * Does not use config.yaml aifabrix-home so the merge always sees the actual user file.
  *
  * @function loadPrimaryUserSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
 function loadPrimaryUserSecrets() {
-  const primaryDir = pathsUtil.getConfigDirForPaths();
-  const userSecretsPath = path.join(primaryDir, 'secrets.local.yaml');
+  const userSecretsPath = pathsUtil.getPrimaryUserSecretsLocalPath();
   if (!fs.existsSync(userSecretsPath)) {
     return {};
   }
+  ensureSecureFilePermissions(userSecretsPath);
 
   try {
     const content = fs.readFileSync(userSecretsPath, 'utf8');
@@ -96,31 +89,12 @@ function loadPrimaryUserSecrets() {
 }
 
 /**
- * Loads user secrets from ~/.aifabrix/secrets.local.yaml
- * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
+ * Same as {@link loadPrimaryUserSecrets} (legacy name; kept for callers).
  * @function loadUserSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
 function loadUserSecrets() {
-  const userSecretsPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
-  if (!fs.existsSync(userSecretsPath)) {
-    return {};
-  }
-
-  try {
-    const content = fs.readFileSync(userSecretsPath, 'utf8');
-    const secrets = parseSecretsContent(content);
-    if (!secrets || typeof secrets !== 'object') {
-      throw new Error(`Invalid secrets file format: ${userSecretsPath}`);
-    }
-    return secrets;
-  } catch (error) {
-    if (error.message.includes('Invalid secrets file format')) {
-      throw error;
-    }
-    logger.warn(`Warning: Could not read secrets file ${userSecretsPath}: ${error.message}`);
-    return {};
-  }
+  return loadPrimaryUserSecrets();
 }
 
 /**
@@ -134,6 +108,7 @@ function loadDefaultSecrets() {
   if (!fs.existsSync(defaultPath)) {
     return {};
   }
+  ensureSecureFilePermissions(defaultPath);
 
   try {
     const content = fs.readFileSync(defaultPath, 'utf8');
@@ -151,6 +126,28 @@ function loadDefaultSecrets() {
   }
 }
 
+/**
+ * Creates the primary user secrets file if missing (empty map) for first-run installs.
+ * Uses the same directory as {@link loadPrimaryUserSecrets} (config dir / ~/.aifabrix).
+ *
+ * @function ensurePrimaryUserSecretsFileExists
+ */
+function ensurePrimaryUserSecretsFileExists() {
+  const userSecretsPath = pathsUtil.getPrimaryUserSecretsLocalPath();
+  const primaryDir = path.dirname(userSecretsPath);
+  if (fs.existsSync(userSecretsPath)) {
+    return;
+  }
+  if (!fs.existsSync(primaryDir)) {
+    fs.mkdirSync(primaryDir, { recursive: true, mode: 0o700 });
+  }
+  const header =
+    '# Local secrets for AI Fabrix CLI (kv:// references in env.template resolve here)\n' +
+    '# Keys are appended by `aifabrix resolve` / ensure — do not prefix with JSON `{}`.\n';
+  fs.writeFileSync(userSecretsPath, header, { mode: 0o600 });
+  ensureSecureFilePermissions(userSecretsPath);
+}
+
 /**
  * Builds a map of hostname to service name from environment config
  * @function buildHostnameToServiceMap
@@ -210,6 +207,7 @@ module.exports = {
   loadPrimaryUserSecrets,
   loadUserSecrets,
   loadDefaultSecrets,
+  ensurePrimaryUserSecretsFileExists,
   buildHostnameToServiceMap,
   resolveUrlPort
 };

package/lib/utils/secrets-validation.js

@@ -63,7 +63,9 @@ function validateSecretsFile(filePath, options = {}) {
   if (!filePath || typeof filePath !== 'string') {
     return { valid: false, errors: ['Path is required'], path: '' };
   }
-  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  // Always normalize to an OS-resolved absolute path. This makes behavior consistent
+  // on Windows when callers pass POSIX-style absolute paths like "/nonexistent/foo".
+  const resolvedPath = path.resolve(filePath);
   if (!fs.existsSync(resolvedPath)) {
     return { valid: false, errors: [`File not found: ${resolvedPath}`], path: resolvedPath };
   }

package/lib/utils/secrets-yaml-preserve.js

@@ -0,0 +1,109 @@
+/**
+ * YAML merge utilities that preserve comments/blank lines for flat secrets files.
+ *
+ * Intended for `secrets.local.yaml` which is typically a simple `key: value` mapping
+ * with user-owned comments. When the file isn't flat (complex YAML), callers should
+ * fall back to a full YAML rewrite.
+ *
+ * @fileoverview Comment-preserving YAML merge helpers
+ */
+
+const keyLineRe = /^(\s*)([^#:\n]+):\s*(.*)$/;
+
+function isCommentOrBlank(line) {
+  const t = line.trim();
+  return !t || t.startsWith('#');
+}
+
+function parseFlatKeyLine(line) {
+  const m = line.match(keyLineRe);
+  if (!m) return null;
+  const indent = m[1] || '';
+  const key = (m[2] || '').trim();
+  const rest = m[3] || '';
+  if (!key) return null;
+  return { indent, key, rest };
+}
+
+function splitInlineComment(rest) {
+  const idx = rest.indexOf(' #');
+  return { inlineComment: idx >= 0 ? rest.slice(idx) : '' };
+}
+
+function formatYamlScalarForFlatLine(yaml, dumpOpts, value) {
+  const dumped = yaml.dump({ _k: value }, dumpOpts);
+  const lines = dumped.split(/\r?\n/).filter(Boolean);
+  if (lines.length !== 1) return null;
+  const idx = lines[0].indexOf(':');
+  if (idx < 0) return null;
+  return lines[0].slice(idx + 1).trimStart();
+}
+
+function appendMissingKeys(out, seen, desiredSecrets, yaml, dumpOpts) {
+  for (const key of Object.keys(desiredSecrets)) {
+    if (seen.has(key)) continue;
+    const scalar = formatYamlScalarForFlatLine(yaml, dumpOpts, desiredSecrets[key]);
+    if (scalar === null) return null;
+    out.push(`${key}: ${scalar}`.trimEnd());
+    seen.add(key);
+  }
+  return out;
+}
+
+function mergeExistingLinesPreservingComments(lines, desiredSecrets, yaml, dumpOpts) {
+  const out = [];
+  const seen = new Set();
+  const encountered = new Set();
+
+  for (const line of lines) {
+    if (isCommentOrBlank(line)) {
+      out.push(line);
+      continue;
+    }
+    const parsed = parseFlatKeyLine(line);
+    if (!parsed) return null;
+    const { indent, key, rest } = parsed;
+
+    if (encountered.has(key)) continue;
+    encountered.add(key);
+
+    if (!Object.prototype.hasOwnProperty.call(desiredSecrets, key)) continue;
+
+    const { inlineComment } = splitInlineComment(rest);
+    const scalar = formatYamlScalarForFlatLine(yaml, dumpOpts, desiredSecrets[key]);
+    if (scalar === null) return null;
+    seen.add(key);
+    out.push(`${indent}${key}: ${scalar}${inlineComment}`.trimEnd());
+  }
+
+  return { out, seen };
+}
+
+/**
+ * Merge a desired flat secrets object into existing file content while preserving comments/blank lines.
+ * Supports deletes: keys present in existing content but absent in desired are removed.
+ *
+ * Returns null when content cannot be treated as a flat key-value file.
+ *
+ * @param {string} existingContent
+ * @param {Record<string, any>} desiredSecrets
+ * @param {{ yaml: any, dumpOpts: any }} yamlCtx
+ * @returns {string|null}
+ */
+function mergeFlatSecretsYamlPreservingComments(existingContent, desiredSecrets, yamlCtx) {
+  if (typeof existingContent !== 'string') return null;
+  if (!desiredSecrets || typeof desiredSecrets !== 'object') return null;
+  if (!yamlCtx || !yamlCtx.yaml) return null;
+
+  const { yaml, dumpOpts } = yamlCtx;
+  const lines = existingContent.split(/\r?\n/);
+  const merged = mergeExistingLinesPreservingComments(lines, desiredSecrets, yaml, dumpOpts);
+  if (!merged) return null;
+
+  const appended = appendMissingKeys(merged.out, merged.seen, desiredSecrets, yaml, dumpOpts);
+  if (appended === null) return null;
+  return appended.join('\n');
+}
+
+module.exports = { mergeFlatSecretsYamlPreservingComments };
+

package/lib/utils/secure-file-permissions.js

@@ -0,0 +1,91 @@
+/**
+ * Secure file permissions for secrets and config (ISO 27001).
+ * Ensures sensitive files are restricted to owner-only (0o600) when read or written.
+ *
+ * @fileoverview Enforce restrictive permissions on secrets and config files
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Mode for secrets and admin files: owner read/write only (no group/other). */
+const SECRET_FILE_MODE = 0o600;
+
+/** Mode for config file (may contain tokens): owner read/write only. */
+const CONFIG_FILE_MODE = 0o600;
+
+/**
+ * Ensures a file has restrictive permissions (0o600) when it exists.
+ * If the file has group or other read/write/execute bits set, chmods to owner-only.
+ * Safe to call on every read path; no-op when file is missing or already 0o600.
+ * On Windows, chmod restricts write access; mode bits are not fully supported.
+ *
+ * @param {string} filePath - Absolute or relative path to the file
+ * @param {number} [mode=0o600] - Desired mode (default SECRET_FILE_MODE)
+ * @returns {boolean} True if file existed and permissions were (or are now) secure
+ */
+function ensureSecureFilePermissions(filePath, mode = SECRET_FILE_MODE) {
+  if (!filePath || typeof filePath !== 'string') {
+    return false;
+  }
+  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+  try {
+    if (!fs.existsSync(resolved)) {
+      return false;
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isFile()) {
+      return false;
+    }
+    const currentMode = stat.mode & 0o777;
+    if ((currentMode & 0o77) === 0) {
+      return true;
+    }
+    fs.chmodSync(resolved, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensures a directory has restrictive permissions (0o700) when it exists.
+ * No-op when directory is missing or already 0o700 (no group/other).
+ *
+ * @param {string} dirPath - Absolute or relative path to the directory
+ * @returns {boolean} True if directory existed and permissions were (or are now) secure
+ */
+function ensureSecureDirPermissions(dirPath) {
+  if (!dirPath || typeof dirPath !== 'string') {
+    return false;
+  }
+  const resolved = path.isAbsolute(dirPath) ? dirPath : path.resolve(dirPath);
+  try {
+    if (!fs.existsSync(resolved)) {
+      return false;
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+      return false;
+    }
+    const currentMode = stat.mode & 0o777;
+    if ((currentMode & 0o77) === 0) {
+      return true;
+    }
+    fs.chmodSync(resolved, 0o700);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  ensureSecureFilePermissions,
+  ensureSecureDirPermissions,
+  SECRET_FILE_MODE,
+  CONFIG_FILE_MODE
+};

package/lib/utils/ssh-key-helper.js

@@ -5,6 +5,7 @@
  */
 
 const fs = require('fs');
+const { nodeFs } = require('../internal/node-fs');
 const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
@@ -40,9 +41,10 @@ function getDefaultEd25519PrivateKeyPath() {
  * @returns {string} Resolved SSH dir path
  */
 function ensureSshDir(sshDir) {
+  const syncFs = nodeFs();
   const dir = sshDir || getDefaultSshDir();
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (!syncFs.existsSync(dir)) {
+    syncFs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
   return dir;
 }

package/lib/utils/template-helpers.js

@@ -35,7 +35,7 @@ async function loadTemplateVariables(templateName) {
   } catch (error) {
     // Template application.yaml not found or invalid, continue without it
     if (error.code !== 'ENOENT') {
-      logger.warn(chalk.yellow(`⚠️  Warning: Could not load template application.yaml: ${error.message}`));
+      logger.warn(chalk.yellow(`⚠  Warning: Could not load template application.yaml: ${error.message}`));
     }
     return null;
   }
@@ -125,7 +125,7 @@ async function updateTemplateVariables(appPath, appName, options, config) {
     writeConfigFile(variablesPath, variables);
   } catch (error) {
     if (error.message && !error.message.includes('not found')) {
-      logger.warn(chalk.yellow(`⚠️  Warning: Could not update application config: ${error.message}`));
+      logger.warn(chalk.yellow(`⚠  Warning: Could not update application config: ${error.message}`));
     }
   }
 }

package/lib/utils/test-log-writer.js

@@ -1,5 +1,5 @@
 /**
- * Test log writer - writes debug logs to integration/<appKey>/logs/
+ * Test log writer - writes debug logs to integration/<systemKey>/logs/
  * Sanitization (tokens, secrets) is done by dataplane before responses are returned.
  *
  * @fileoverview Write test request/response logs for debugging
@@ -29,9 +29,9 @@ function sanitizeForLog(obj, seen = new Set()) {
 }
 
 /**
- * Write test log to integration/<appKey>/logs/<logType>-<timestamp>.json
+ * Write test log to integration/<systemKey>/logs/<logType>-<timestamp>.json
  * @async
- * @param {string} appKey - Application key (used for path)
+ * @param {string} appKey - Integration folder name under integration/ (used for path)
  * @param {Object} data - Log data (request, response) - will be sanitized
  * @param {string} [logType] - Log type prefix (default: test-integration)
  * @param {string} [integrationBaseDir] - Base dir for integration (default: cwd/integration)

package/lib/utils/token-manager.js

@@ -10,7 +10,6 @@
  */
 
 const fs = require('fs');
-const path = require('path');
 const yaml = require('js-yaml');
 const config = require('../core/config');
 const logger = require('./logger');
@@ -21,12 +20,43 @@ const {
 } = require('./token-manager-refresh');
 const { warnRefreshFailureOnce, warnRefreshTokenExpiredOnce } = require('./token-manager-messages');
 
+/** App key used for dataplane client credentials in secrets.local.yaml */
+const DATAPLANE_APP_KEY = 'dataplane';
+
 function getSecretsFilePath() {
-  return path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
+  return pathsUtil.getPrimaryUserSecretsLocalPath();
+}
+
+/**
+ * Validate that secrets.local.yaml contains dataplane client credentials.
+ * If missing, the developer should run: aifabrix app rotate-secret dataplane
+ * @param {string} [secretsFilePath] - Path to secrets file; defaults to ~/.aifabrix/secrets.local.yaml
+ * @returns {{ valid: boolean, hint?: string }}
+ */
+function validateDataplaneSecrets(secretsFilePath) {
+  const filePath = secretsFilePath || getSecretsFilePath();
+  const hint = 'Dataplane credentials are missing. Run: aifabrix app rotate-secret dataplane';
+  try {
+    if (!fs.existsSync(filePath)) {
+      return { valid: false, hint };
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const secrets = yaml.load(content) || {};
+    const clientIdKey = `${DATAPLANE_APP_KEY}-client-idKeyVault`;
+    const clientSecretKey = `${DATAPLANE_APP_KEY}-client-secretKeyVault`;
+    const hasId = secrets[clientIdKey] !== null && secrets[clientIdKey] !== undefined && String(secrets[clientIdKey]).trim() !== '';
+    const hasSecret = secrets[clientSecretKey] !== null && secrets[clientSecretKey] !== undefined && String(secrets[clientSecretKey]).trim() !== '';
+    if (hasId && hasSecret) {
+      return { valid: true };
+    }
+    return { valid: false, hint };
+  } catch {
+    return { valid: false, hint };
+  }
 }
 
 /**
- * Load client credentials from secrets.local.yaml or process.env (e.g. integration/hubspot/.env).
+ * Load client credentials from secrets.local.yaml or process.env (e.g. integration/hubspot-test/.env).
  * Reads secrets file using pattern: <app-name>-client-idKeyVault and <app-name>-client-secretKeyVault.
  * If not found, checks process.env.CLIENTID and process.env.CLIENTSECRET (set when .env is loaded).
  * @param {string} appName - Application name
@@ -60,7 +90,7 @@ async function loadClientCredentials(appName) {
     logger.warn(`Failed to load credentials from secrets.local.yaml: ${error.message}`);
   }
 
-  // Fallback: use CLIENTID/CLIENTSECRET from process.env (e.g. from integration/hubspot/.env)
+  // Fallback: use CLIENTID/CLIENTSECRET from process.env (e.g. from integration/hubspot-test/.env)
   const envClientId = process.env.CLIENTID || process.env.CLIENT_ID;
   const envClientSecret = process.env.CLIENTSECRET || process.env.CLIENT_SECRET;
   if (envClientId && envClientSecret) {
@@ -439,6 +469,7 @@ function requireBearerForDataplanePipeline(authConfig) {
 }
 
 module.exports = {
+  DATAPLANE_APP_KEY,
   getDeviceToken,
   getClientToken,
   isTokenExpired,
@@ -452,5 +483,6 @@ module.exports = {
   getDeploymentAuth,
   getDeviceOnlyAuth,
   extractClientCredentials,
-  requireBearerForDataplanePipeline
+  requireBearerForDataplanePipeline,
+  validateDataplaneSecrets
 };

package/lib/utils/url-declarative-public-base.js

@@ -0,0 +1,188 @@
+/**
+ * Public URL base for url:// expansion when Traefik + frontDoorRouting.host (plan 122 phase 2).
+ *
+ * @fileoverview Traefik host template vs remote-server vs localhost+port (no app-specific rules)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { expandFrontDoorHostPlaceholders } = require('./compose-generator');
+const { publishedHostPort, localHostPort } = require('./declarative-url-ports');
+
+/**
+ * Expand frontDoorRouting.host placeholders for url:// (same rules as Traefik labels in compose-generator).
+ *
+ * @param {string} template
+ * @param {Object} opts
+ * @param {string|number|null|undefined} opts.developerIdRaw
+ * @param {string|null|undefined} opts.remoteServer
+ * @returns {string}
+ */
+function expandFrontDoorHostTemplateForUrls(template, opts) {
+  const { developerIdRaw, remoteServer } = opts || {};
+  return expandFrontDoorHostPlaceholders(template, developerIdRaw, remoteServer);
+}
+
+function hostPortForProfile(profile, listenPort, developerIdNum) {
+  return profile === 'docker'
+    ? publishedHostPort(listenPort, developerIdNum)
+    : localHostPort(listenPort, developerIdNum);
+}
+
+/**
+ * Local profile: workstation `+10` applies only to the app being resolved (`currentAppKey`).
+ * Cross-app tokens (e.g. `url://keycloak-public` from miso-controller) use `publishedHostPort`
+ * (manifest + dev*100, no +10) so sibling services keep compose-published offsets only.
+ *
+ * @param {Object} opts
+ * @param {'docker'|'local'} opts.profile
+ * @param {number} opts.listenPort - published/manifest basis for public URLs
+ * @param {number} opts.developerIdNum
+ * @param {string|undefined} opts.declarativeTargetAppKey - target of the url:// token
+ * @param {string|undefined} opts.declarativeCurrentAppKey - app whose env is being generated
+ * @returns {number}
+ */
+function resolveHostPortForDeclarativePublic(opts) {
+  const {
+    profile,
+    listenPort,
+    developerIdNum,
+    declarativeTargetAppKey,
+    declarativeCurrentAppKey
+  } = opts;
+  if (profile !== 'local') {
+    return hostPortForProfile(profile, listenPort, developerIdNum);
+  }
+  const cur = String(declarativeCurrentAppKey || '').trim();
+  const tgt = String(declarativeTargetAppKey || '').trim();
+  const isCurrentApp = !cur || !tgt || tgt === cur;
+  return isCurrentApp ? localHostPort(listenPort, developerIdNum) : publishedHostPort(listenPort, developerIdNum);
+}
+
+/**
+ * Without Traefik, `remote-server` is the dev machine host. Apps bind published host ports, not 443 + path.
+ * If the URL already has an explicit port, keep host:port but **scheme follows `infraTlsEnabled`**, not the
+ * literal `https://` in `remote-server` when TLS is off (`up-infra` without `--tls`).
+ * If `remote-server` omits a port, append the profile-specific published/listen-derived port.
+ *
+ * @param {string} rawRemote
+ * @param {'docker'|'local'} profile
+ * @param {number} listenPort
+ * @param {number} developerIdNum
+ * @param {boolean} infraTlsEnabled
+ * @returns {string}
+ */
+function remotePublicBaseWithoutTraefik(
+  rawRemote,
+  profile,
+  listenPort,
+  developerIdNum,
+  infraTlsEnabled,
+  declarativePortOpts
+) {
+  const raw = String(rawRemote || '').trim().replace(/\/+$/, '');
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : (infraTlsEnabled ? `https://${raw}` : `http://${raw}`);
+  const u = new URL(withScheme);
+  const scheme = infraTlsEnabled ? 'https' : 'http';
+
+  if (u.port !== '') {
+    return `${scheme}://${u.host}`;
+  }
+
+  const hostPort = resolveHostPortForDeclarativePublic({
+    profile,
+    listenPort,
+    developerIdNum,
+    declarativeTargetAppKey: declarativePortOpts && declarativePortOpts.declarativeTargetAppKey,
+    declarativeCurrentAppKey: declarativePortOpts && declarativePortOpts.declarativeCurrentAppKey
+  });
+  const defaultPort = scheme === 'https' ? 443 : 80;
+  if (Number(hostPort) === defaultPort) {
+    return `${scheme}://${u.hostname}`;
+  }
+  return `${scheme}://${u.hostname}:${hostPort}`;
+}
+
+/**
+ * @param {Object} opts - same shape as computePublicUrlBaseString
+ * @returns {string|null}
+ */
+function buildTraefikPublicBaseIfApplicable(opts) {
+  const { traefik, pathActive, hostTemplate, tls, developerIdRaw, remoteServer, infraTlsEnabled } =
+    opts;
+  // Plan 124: Traefik host authority only when pathActive (traefik ∧ frontDoorRouting.enabled)
+  if (!traefik || !pathActive || !hostTemplate || !String(hostTemplate).trim()) {
+    return null;
+  }
+  const expanded = expandFrontDoorHostTemplateForUrls(hostTemplate, {
+    developerIdRaw,
+    remoteServer
+  });
+  if (!expanded) {
+    return null;
+  }
+  const useHttps = Boolean(infraTlsEnabled) || tls !== false;
+  const scheme = useHttps ? 'https' : 'http';
+  return `${scheme}://${expanded}`.replace(/\/+$/, '');
+}
+
+/**
+ * Scheme + authority (no path) for public url://* when Traefik, remote, or localhost.
+ *
+ * @param {Object} opts
+ * @param {boolean} [opts.traefik]
+ * @param {string|null|undefined} opts.hostTemplate
+ * @param {boolean} [opts.tls]
+ * @param {string|number|null|undefined} opts.developerIdRaw
+ * @param {string|null|undefined} opts.remoteServer
+ * @param {'docker'|'local'} opts.profile
+ * @param {number} opts.listenPort
+ * @param {number} opts.developerIdNum
+ * @param {boolean} [opts.infraTlsEnabled] - `tlsEnabled` from ~/.aifabrix/config.yaml (`up-infra --tls`); when true, Traefik front-door public URLs use https even if application.yaml has `frontDoorRouting.tls: false`
+ * @param {boolean} [opts.pathActive] - traefik ∧ frontDoorRouting.enabled; required for Traefik host branch (plan 124)
+ * @returns {string}
+ */
+function computePublicUrlBaseString(opts) {
+  const { remoteServer, profile, listenPort, developerIdNum, infraTlsEnabled } = opts;
+  const declarativePortOpts = {
+    declarativeTargetAppKey: opts.declarativeTargetAppKey,
+    declarativeCurrentAppKey: opts.declarativeCurrentAppKey
+  };
+
+  const traefikBase = buildTraefikPublicBaseIfApplicable({
+    ...opts,
+    pathActive: Boolean(opts.pathActive)
+  });
+  if (traefikBase) {
+    return traefikBase;
+  }
+
+  if (remoteServer && String(remoteServer).trim()) {
+    return remotePublicBaseWithoutTraefik(
+      remoteServer,
+      profile,
+      listenPort,
+      developerIdNum,
+      Boolean(infraTlsEnabled),
+      declarativePortOpts
+    );
+  }
+
+  const hostPort = resolveHostPortForDeclarativePublic({
+    profile,
+    listenPort,
+    developerIdNum,
+    declarativeTargetAppKey: declarativePortOpts.declarativeTargetAppKey,
+    declarativeCurrentAppKey: declarativePortOpts.declarativeCurrentAppKey
+  });
+  const scheme = infraTlsEnabled ? 'https' : 'http';
+  return `${scheme}://localhost:${hostPort}`;
+}
+
+module.exports = {
+  expandFrontDoorHostTemplateForUrls,
+  computePublicUrlBaseString,
+  resolveHostPortForDeclarativePublic
+};