@aifabrix/builder 2.44.5 → 2.45.0

package/lib/utils/secrets-kv-scope.js

@@ -8,6 +8,23 @@
 
 'use strict';
 
+/**
+ * Treat undefined/null and whitespace-only strings as no value so prefixed slots
+ * cannot shadow unprefixed secrets with empty placeholders (plan 117 scoped KV).
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+function isKvSlotEmpty(v) {
+  if (v === undefined || v === null) {
+    return true;
+  }
+  if (typeof v === 'string' && v.trim() === '') {
+    return true;
+  }
+  return false;
+}
+
 /**
  * @param {Function} getValueByPath - From secrets-helpers
  * @returns {{ getValueByPathWithEnvScope: Function, mergeSecretsWithPrefixedCopies: Function }}
@@ -27,7 +44,7 @@ function createScopedKvHelpers(getValueByPath) {
     const prefix = `${String(envKey).toLowerCase()}-`;
     const prefixedPath = prefix + pathStr;
     const fromPrefixed = getValueByPath(secrets, prefixedPath);
-    if (fromPrefixed !== undefined && fromPrefixed !== null) {
+    if (!isKvSlotEmpty(fromPrefixed)) {
       return fromPrefixed;
     }
     return getValueByPath(secrets, pathStr);
@@ -47,7 +64,7 @@ function createScopedKvHelpers(getValueByPath) {
     for (const [k, v] of Object.entries(secrets)) {
       if (typeof k !== 'string' || !k || k.startsWith(prefix)) continue;
       const pk = prefix + k;
-      if (merged[pk] === undefined && v !== undefined && v !== null) {
+      if (isKvSlotEmpty(merged[pk]) && !isKvSlotEmpty(v)) {
         merged[pk] = v;
       }
     }

package/lib/utils/secrets-materialize-local.js

@@ -0,0 +1,134 @@
+/**
+ * Persist resolved kv:// values into the primary user secrets file so regenerate (.env) stays stable.
+ *
+ * @fileoverview After env.template resolves, copy merged secret values into ~/.aifabrix/secrets.local.yaml
+ * when keys are missing or empty locally **and** not already provided by the configured shared store
+ * (`aifabrix-secrets` remote API or shared YAML), so shared-only keys are not duplicated into user secrets.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('./logger');
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
+const localSecretsModule = require('./local-secrets');
+const secretsUtils = require('./secrets-utils');
+const { loadConfiguredSharedSecretsStore } = require('./remote-secrets-loader');
+const { decryptSecretsObject } = require('../core/secrets-load');
+const { collectUniqueKvPathStrings } = require('./secrets-kv-refs');
+const {
+  resolveKvRefValue,
+  mergeSecretsWithPrefixedCopies,
+  isKvKeyAllowedEmptyWhenAbsent
+} = require('./secrets-helpers');
+
+/**
+ * After successful kv resolution, write resolved values to the user secrets file when local slot is empty.
+ * Does not overwrite non-empty local values (user wins).
+ *
+ * @async
+ * @param {string} templateContent - Original env.template text (still contains kv:// refs)
+ * @param {Object} mergedSecrets - Decrypted secrets map passed to resolveKvReferences (same as loadSecrets output)
+ * @param {{ effective?: boolean, envKey?: string }|null} scopedKv - Scoped kv context from generateEnvContent
+ * @param {Object} [options]
+ * @param {boolean} [options.skipMaterializeKvToLocal] - Skip persistence (tests / programmatic)
+ * @returns {Promise<string[]>} Keys materialized (written) to local file
+ */
+function buildScopedMaps(mergedSecrets, scopedKv) {
+  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
+  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(mergedSecrets, scopedKv.envKey) : mergedSecrets;
+  const rawLocal = secretsUtils.loadPrimaryUserSecrets();
+  const localMap = effective ? mergeSecretsWithPrefixedCopies(rawLocal, scopedKv.envKey) : rawLocal;
+  return { effective, secretsMap, localMap };
+}
+
+function shouldSkipPersist(pathStr, resolvedVal, localVal) {
+  if (resolvedVal === undefined || resolvedVal === null) return true;
+  if (
+    typeof resolvedVal === 'string' &&
+    resolvedVal.trim() === '' &&
+    isKvKeyAllowedEmptyWhenAbsent(pathStr)
+  ) {
+    return true;
+  }
+  if (localVal !== undefined && localVal !== null && String(localVal).trim() !== '') {
+    return true;
+  }
+  return false;
+}
+
+function isNonEmptyResolvedKv(val) {
+  if (val === undefined || val === null) return false;
+  if (typeof val === 'string' && val.trim() === '') return false;
+  return true;
+}
+
+async function resolveSharedScopedMapForMaterialize(scopedKv, effective) {
+  try {
+    const rawShared = await loadConfiguredSharedSecretsStore();
+    const decryptedShared = rawShared ? await decryptSecretsObject(rawShared) : null;
+    if (!decryptedShared) return null;
+    return effective && scopedKv && scopedKv.envKey
+      ? mergeSecretsWithPrefixedCopies(decryptedShared, scopedKv.envKey)
+      : decryptedShared;
+  } catch {
+    return null;
+  }
+}
+
+function plaintextKvForLocalPersist(pathStr, secretsMap, localMap, sharedScoped, scopedKv, effective) {
+  const resolvedVal = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+  const localVal = resolveKvRefValue(localMap, pathStr, scopedKv?.envKey, effective);
+  if (shouldSkipPersist(pathStr, resolvedVal, localVal)) return null;
+  const sharedVal =
+    sharedScoped && typeof sharedScoped === 'object'
+      ? resolveKvRefValue(sharedScoped, pathStr, scopedKv?.envKey, effective)
+      : undefined;
+  if (isNonEmptyResolvedKv(sharedVal)) return null;
+  return typeof resolvedVal === 'string' ? resolvedVal : String(resolvedVal);
+}
+
+async function materializeResolvedKvSecretsToUserLocal(templateContent, mergedSecrets, scopedKv, options = {}) {
+  if (
+    !templateContent ||
+    typeof templateContent !== 'string' ||
+    options.skipMaterializeKvToLocal === true
+  ) {
+    return [];
+  }
+
+  try {
+    const { effective, secretsMap, localMap } = buildScopedMaps(mergedSecrets, scopedKv);
+    const sharedScoped = await resolveSharedScopedMapForMaterialize(scopedKv, effective);
+
+    const paths = collectUniqueKvPathStrings(templateContent);
+    const materialized = [];
+
+    for (const pathStr of paths) {
+      const plain = plaintextKvForLocalPersist(pathStr, secretsMap, localMap, sharedScoped, scopedKv, effective);
+      if (plain === null) continue;
+      await localSecretsModule.saveLocalSecret(pathStr, plain);
+      materialized.push(pathStr);
+    }
+
+    if (materialized.length > 0) {
+      logger.log(
+        formatSuccessLine(
+          `Saved ${materialized.length} resolved kv key(s) to local secrets for stable reinstalls: ${materialized.join(', ')}`
+        )
+      );
+    }
+
+    return materialized;
+  } catch (err) {
+    if (typeof logger.warn === 'function') {
+      logger.warn(`Could not materialize resolved kv secrets to local file: ${err.message}`);
+    }
+    return [];
+  }
+}
+
+module.exports = {
+  materializeResolvedKvSecretsToUserLocal
+};

package/lib/utils/secrets-path.js

@@ -13,6 +13,15 @@ const path = require('path');
 const config = require('../core/config');
 const paths = require('./paths');
 
+/**
+ * @param {string} s
+ * @returns {boolean}
+ */
+function isHttpOrHttpsUrl(s) {
+  const t = String(s || '').trim();
+  return t.startsWith('http://') || t.startsWith('https://');
+}
+
 /**
  * Resolves secrets file path when an explicit path is provided.
  * If not provided, returns default fallback under <home>/secrets.yaml.
@@ -32,9 +41,8 @@ function resolveSecretsPath(secretsPath) {
 }
 
 /**
- * Determines the actual secrets file paths that loadSecrets would use
- * Mirrors the cascading lookup logic from loadSecrets
- * Uses config.yaml for default secrets path as fallback
+ * Determines paths used for default `loadSecrets()` (no explicit path): primary user secrets file
+ * and configured `aifabrix-secrets` (shared YAML file path or remote API URL).
  *
  * @async
  * @function getActualSecretsPath
@@ -42,7 +50,8 @@ function resolveSecretsPath(secretsPath) {
  * @param {string} [_appName] - Application name (optional, for backward compatibility, unused)
  * @returns {Promise<Object>} Object with userPath and buildPath (if configured)
  * @returns {string} returns.userPath - User's secrets file path (~/.aifabrix/secrets.local.yaml)
- * @returns {string|null} returns.buildPath - App's secrets file path (if configured in config.yaml)
+ * @returns {string|null} returns.buildPath - On-disk shared secrets file (if configured; never an http(s) URL)
+ * @returns {string|null} [returns.sharedSecretsApiUrl] - When aifabrix-secrets is an API URL (for error messages; loadSecrets merges this API into the kv:// resolution map)
  */
 async function getActualSecretsPath(secretsPath, _appName) {
   // If explicit path provided, use it (backward compatibility)
@@ -50,30 +59,34 @@ async function getActualSecretsPath(secretsPath, _appName) {
     const resolvedPath = resolveSecretsPath(secretsPath);
     return {
       userPath: resolvedPath,
-      buildPath: null
+      buildPath: null,
+      sharedSecretsApiUrl: null
     };
   }
 
-  // Cascading lookup: user's file first (primary home: AIFABRIX_HOME or ~/.aifabrix)
-  const userSecretsPath = path.join(paths.getConfigDirForPaths(), 'secrets.local.yaml');
+  // Default lookup: primary user file plus aifabrix-secrets (file or https URL)
+  const userSecretsPath = paths.getPrimaryUserSecretsLocalPath();
 
-  // Check config.yaml for canonical secrets path
   let buildSecretsPath = null;
+  let sharedSecretsApiUrl = null;
   try {
     const canonicalSecretsPath = await config.getAifabrixSecretsPath();
     if (canonicalSecretsPath) {
-      buildSecretsPath = path.isAbsolute(canonicalSecretsPath)
-        ? canonicalSecretsPath
-        : path.resolve(process.cwd(), canonicalSecretsPath);
+      const raw = String(canonicalSecretsPath).trim();
+      if (isHttpOrHttpsUrl(raw)) {
+        sharedSecretsApiUrl = raw.replace(/\/+$/, '');
+      } else {
+        buildSecretsPath = path.isAbsolute(raw) ? raw : path.resolve(process.cwd(), raw);
+      }
     }
   } catch (error) {
     // Ignore errors, continue
   }
 
-  // Return both paths (even if files don't exist) for error messages
   return {
     userPath: userSecretsPath,
-    buildPath: buildSecretsPath
+    buildPath: buildSecretsPath,
+    sharedSecretsApiUrl
   };
 }
 

package/lib/utils/secrets-utils.js

@@ -58,18 +58,14 @@ async function loadSecretsFromFile(filePath) {
 }
 
 /**
- * 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.
+ * Loads user secrets from {@link pathsUtil.getPrimaryUserSecretsLocalPath} (beside `config.yaml`).
+ * If that file is missing, reads a legacy file at `getAifabrixHome()/secrets.local.yaml` when paths
+ * differ (older CLI when `aifabrix-home` was POSIX home).
  *
  * @function loadPrimaryUserSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
-function loadPrimaryUserSecrets() {
-  const userSecretsPath = pathsUtil.getPrimaryUserSecretsLocalPath();
-  if (!fs.existsSync(userSecretsPath)) {
-    return {};
-  }
+function readPrimaryUserSecretsAtPath(userSecretsPath) {
   ensureSecureFilePermissions(userSecretsPath);
 
   try {
@@ -84,8 +80,22 @@ function loadPrimaryUserSecrets() {
       throw error;
     }
     logger.warn(`Warning: Could not read secrets file ${userSecretsPath}: ${error.message}`);
-    return {};
+    return null;
+  }
+}
+
+function loadPrimaryUserSecrets() {
+  const primaryPath = pathsUtil.getPrimaryUserSecretsLocalPath();
+  if (fs.existsSync(primaryPath)) {
+    const fromPrimary = readPrimaryUserSecretsAtPath(primaryPath);
+    return fromPrimary !== null ? fromPrimary : {};
+  }
+  const legacyPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
+  if (path.resolve(legacyPath) !== path.resolve(primaryPath) && fs.existsSync(legacyPath)) {
+    const fromLegacy = readPrimaryUserSecretsAtPath(legacyPath);
+    return fromLegacy !== null ? fromLegacy : {};
   }
+  return {};
 }
 
 /**
@@ -128,7 +138,7 @@ 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).
+ * Uses the same directory as {@link loadPrimaryUserSecrets} (beside `config.yaml`).
  *
  * @function ensurePrimaryUserSecretsFileExists
  */

package/lib/utils/system-builder-root.js

@@ -0,0 +1,42 @@
+/**
+ * Picks the parent directory for platform `builder/<app>` materialization when the project has no
+ * `builder/<app>`. Compares the effective config directory (`getAifabrixSystemDir`) to the resolved
+ * AI Fabrix home (`getAifabrixHome`, from `AIFABRIX_HOME` or `aifabrix-home` in config.yaml).
+ *
+ * @fileoverview System builder root parent (config dir vs home override)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * When the effective config directory lies under the resolved AI Fabrix home, keep state (including
+ * `builder/`) beside `config.yaml` (e.g. `$HOME/.aifabrix/builder` when `AIFABRIX_HOME=$HOME`).
+ * When `aifabrix-home` relocates home outside the config tree, materialize under that home instead.
+ *
+ * Uses a resolved-path prefix check (not `path.relative`) so "nested under home" is stable across
+ * platforms (e.g. sibling paths like `/var/aifabrix` vs `/var/aifabrix-config` must not be treated
+ * as nested).
+ *
+ * @param {string} systemDir - Absolute config/state directory (same as `getAifabrixSystemDir()`).
+ * @param {string} homeDir - Absolute AI Fabrix home (`getAifabrixHome()`).
+ * @returns {string} Absolute directory whose `builder/` subdir is used
+ */
+function resolveSystemBuilderParentDir(systemDir, homeDir) {
+  const s = path.resolve(systemDir);
+  const h = path.resolve(homeDir);
+  if (s === h) {
+    return s;
+  }
+  const sep = path.sep;
+  const homePrefix = h.endsWith(sep) ? h : `${h}${sep}`;
+  const configUnderHome = s.startsWith(homePrefix);
+  return configUnderHome ? s : h;
+}
+
+module.exports = {
+  resolveSystemBuilderParentDir
+};

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

@@ -11,6 +11,26 @@
 const { expandFrontDoorHostPlaceholders } = require('./compose-generator');
 const { publishedHostPort, localHostPort } = require('./declarative-url-ports');
 
+/**
+ * Public URL authorities that must use `http://` (browsers hit loopback without TLS in practice).
+ *
+ * @param {string} hostname - Parsed URL hostname
+ * @returns {boolean}
+ */
+function isLocalhostPublicSchemeHostname(hostname) {
+  const h = String(hostname || '').trim().toLowerCase();
+  if (!h) {
+    return false;
+  }
+  if (h === 'localhost') {
+    return true;
+  }
+  if (h === '127.0.0.1') {
+    return true;
+  }
+  return h === '::1';
+}
+
 /**
  * Expand frontDoorRouting.host placeholders for url:// (same rules as Traefik labels in compose-generator).
  *
@@ -31,6 +51,17 @@ function hostPortForProfile(profile, listenPort, developerIdNum) {
     : localHostPort(listenPort, developerIdNum);
 }
 
+/**
+ * Scheme for `declarativePublicUrlsUseLocalhost` bases: always **http** for loopback reachability
+ * (ignore `tlsEnabled` / `remote-server` https — localhost URLs are not served with TLS in dev).
+ * @param {Object} opts - Kept for call-site compatibility (same shape as {@link computePublicUrlBaseString})
+ * @returns {'http'}
+ */
+function schemeForDeclarativeLocalhostPublicBase(opts) {
+  void opts;
+  return 'http';
+}
+
 /**
  * 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`
@@ -62,10 +93,10 @@ function resolveHostPortForDeclarativePublic(opts) {
 }
 
 /**
- * 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.
+ * Public authority from `remote-server` when expansion opts in (Traefik on, or per-app `proxy: true` ⇒
+ * `declarativePublicUrlsUseLocalhost === false`). 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
@@ -85,7 +116,10 @@ function remotePublicBaseWithoutTraefik(
   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';
+  let scheme = infraTlsEnabled ? 'https' : 'http';
+  if (isLocalhostPublicSchemeHostname(u.hostname)) {
+    scheme = 'http';
+  }
 
   if (u.port !== '') {
     return `${scheme}://${u.host}`;
@@ -105,17 +139,31 @@ function remotePublicBaseWithoutTraefik(
   return `${scheme}://${u.hostname}:${hostPort}`;
 }
 
+/**
+ * True when `frontDoorRouting.host` depends on `remote-server` for expansion (`${REMOTE_HOST}`).
+ * Without a remote, expansion yields a bare `devNN` label (no DNS) — public `url://` bases must fall back to localhost.
+ *
+ * @param {string|null|undefined} hostTemplate
+ * @returns {boolean}
+ */
+function templateUsesRemoteHostPlaceholder(hostTemplate) {
+  return /\$\{REMOTE_HOST\}/.test(String(hostTemplate || ''));
+}
+
 /**
  * @param {Object} opts - same shape as computePublicUrlBaseString
  * @returns {string|null}
  */
 function buildTraefikPublicBaseIfApplicable(opts) {
-  const { traefik, pathActive, hostTemplate, tls, developerIdRaw, remoteServer, infraTlsEnabled } =
+  const { traefik, pathActive, hostTemplate, developerIdRaw, remoteServer, infraTlsEnabled } =
     opts;
   // Plan 124: Traefik host authority only when pathActive (traefik ∧ frontDoorRouting.enabled)
   if (!traefik || !pathActive || !hostTemplate || !String(hostTemplate).trim()) {
     return null;
   }
+  if (templateUsesRemoteHostPlaceholder(hostTemplate) && !String(remoteServer || '').trim()) {
+    return null;
+  }
   const expanded = expandFrontDoorHostTemplateForUrls(hostTemplate, {
     developerIdRaw,
     remoteServer
@@ -123,8 +171,12 @@ function buildTraefikPublicBaseIfApplicable(opts) {
   if (!expanded) {
     return null;
   }
-  const useHttps = Boolean(infraTlsEnabled) || tls !== false;
-  const scheme = useHttps ? 'https' : 'http';
+  // Scheme follows global `tlsEnabled` (`up-infra --tls`) only — not `frontDoorRouting.tls` when infra TLS is off.
+  const useHttps = Boolean(infraTlsEnabled);
+  let scheme = useHttps ? 'https' : 'http';
+  if (isLocalhostPublicSchemeHostname(expanded)) {
+    scheme = 'http';
+  }
   return `${scheme}://${expanded}`.replace(/\/+$/, '');
 }
 
@@ -140,8 +192,9 @@ function buildTraefikPublicBaseIfApplicable(opts) {
  * @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.infraTlsEnabled] - `tlsEnabled` from ~/.aifabrix/config.yaml (`up-infra --tls`); Traefik front-door public bases use **`https`** only when this is **true** (even if `frontDoorRouting.tls` is **false**). When **false**, front-door bases use **`http`** regardless of `frontDoorRouting.tls`. Loopback hostnames stay **http** always.
  * @param {boolean} [opts.pathActive] - traefik ∧ frontDoorRouting.enabled; required for Traefik host branch (plan 124)
+ * @param {boolean|undefined} [opts.declarativePublicUrlsUseLocalhost] - **`true`**: force localhost authority (+ port rules below). **`false`**: allow `remote-server` as authority when Traefik is on, or when global `traefik` is not `false` and per-app `proxy` opts in without Traefik. **`undefined`**: default — omit `remote-server` when Traefik is off so published services use `http://localhost:<port>` (e.g. `af setup` / device login URLs). When user config has **`traefik: false`**, expansion forces localhost for public bases regardless of per-app `proxy`.
  * @returns {string}
  */
 function computePublicUrlBaseString(opts) {
@@ -159,7 +212,23 @@ function computePublicUrlBaseString(opts) {
     return traefikBase;
   }
 
-  if (remoteServer && String(remoteServer).trim()) {
+  if (opts.declarativePublicUrlsUseLocalhost) {
+    const hostPort = resolveHostPortForDeclarativePublic({
+      profile,
+      listenPort,
+      developerIdNum,
+      declarativeTargetAppKey: declarativePortOpts.declarativeTargetAppKey,
+      declarativeCurrentAppKey: declarativePortOpts.declarativeCurrentAppKey
+    });
+    const scheme = schemeForDeclarativeLocalhostPublicBase(opts);
+    return `${scheme}://localhost:${hostPort}`;
+  }
+
+  const remoteTrimmed = remoteServer && String(remoteServer).trim();
+  const useRemotePublicAuthority =
+    Boolean(remoteTrimmed) &&
+    (Boolean(opts.traefik) || opts.declarativePublicUrlsUseLocalhost === false);
+  if (useRemotePublicAuthority) {
     return remotePublicBaseWithoutTraefik(
       remoteServer,
       profile,
@@ -177,8 +246,7 @@ function computePublicUrlBaseString(opts) {
     declarativeTargetAppKey: declarativePortOpts.declarativeTargetAppKey,
     declarativeCurrentAppKey: declarativePortOpts.declarativeCurrentAppKey
   });
-  const scheme = infraTlsEnabled ? 'https' : 'http';
-  return `${scheme}://localhost:${hostPort}`;
+  return `http://localhost:${hostPort}`;
 }
 
 module.exports = {