@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/secrets-generator.js

@@ -16,6 +16,17 @@ const yaml = require('js-yaml');
 const crypto = require('crypto');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
+const { mergeFlatSecretsYamlPreservingComments } = require('./secrets-yaml-preserve');
+const {
+  generateDatabasePasswordValueForKey,
+  generateDatabaseUrlValueForKey,
+  parseDatabaseSecretKey
+} = require('../parameters/database-secret-values');
+
+/** Lazy require so tests can jest.spyOn getInfraParameterCatalog after module load. */
+function infraParameterCatalogModule() {
+  return require('../parameters/infra-parameter-catalog');
+}
 
 /**
  * Parse key-value pairs from YAML-like lines (last occurrence wins per key).
@@ -44,7 +55,9 @@ function parseYamlKeyValueLines(content) {
 /**
  * Parse YAML content tolerating duplicate keys (last occurrence wins).
  * Use for secrets files that may have been appended to repeatedly.
- * Tries yaml.load first; on "duplicate key" error falls back to line-by-line parse.
+ * Tries yaml.load first; on duplicate-key errors or other parse failures (e.g. `{}` on line 1
+ * then `key: value` lines — invalid multi-document without `---`) falls back to line-by-line
+ * parse for flat key: value secrets files.
  *
  * @param {string} content - Raw YAML content
  * @returns {Object} Parsed object (last value wins for duplicate keys)
@@ -56,13 +69,11 @@ function loadYamlTolerantOfDuplicateKeys(content) {
   try {
     const parsed = yaml.load(content);
     return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch (err) {
-    const msg = err.message || '';
-    if (!msg.includes('duplicate') && !msg.includes('duplicated mapping')) {
-      throw err;
-    }
+  } catch {
+    // Duplicate keys, `{}` + appended YAML (invalid multi-doc), or other bad merges —
+    // flat secrets files recover via line parse (last key wins).
+    return parseYamlKeyValueLines(content);
   }
-  return parseYamlKeyValueLines(content);
 }
 
 /**
@@ -104,18 +115,37 @@ function findMissingSecretKeys(envTemplate, existingSecrets) {
   return missingKeys;
 }
 
+/**
+ * Resolve app directory for database key generation (application.yaml lookup).
+ * @param {string} key - Secret key
+ * @returns {string|null}
+ */
+function resolveAppDirForDatabaseKey(key) {
+  const parsed = parseDatabaseSecretKey(key);
+  if (!parsed) return null;
+  try {
+    const builderPath = pathsUtil.getBuilderPath(parsed.appKey);
+    if (fs.existsSync(builderPath)) return builderPath;
+  } catch {
+    /* ignore */
+  }
+  try {
+    const intPath = pathsUtil.getIntegrationPath(parsed.appKey);
+    if (fs.existsSync(intPath)) return intPath;
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
 /**
  * Generate database password value for a key (databases-*-passwordKeyVault)
  * @param {string} key - Secret key name
  * @returns {string|null} Password string or null if key does not match
  */
 function generateDbPasswordValue(key) {
-  const dbPasswordMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-passwordKeyVault$/i);
-  if (!dbPasswordMatch) return null;
-  const appName = dbPasswordMatch[1];
-  if (appName === 'miso-controller') return 'miso_pass123';
-  const dbName = appName.replace(/-/g, '_');
-  return `${dbName}_pass123`;
+  const appDir = resolveAppDirForDatabaseKey(key);
+  return generateDatabasePasswordValueForKey(key, appDir);
 }
 
 /**
@@ -124,44 +154,98 @@ function generateDbPasswordValue(key) {
  * @returns {string|null} URL string or null if key does not match
  */
 function generateDbUrlValue(key) {
-  const dbUrlMatch = key.match(/^databases-([a-z0-9-_]+)-\d+-urlKeyVault$/i);
-  if (!dbUrlMatch) return null;
-  const appName = dbUrlMatch[1];
-  if (appName === 'miso-controller') {
-    return 'postgresql://miso_user:miso_pass123@${DB_HOST}:${DB_PORT}/miso';
+  const appDir = resolveAppDirForDatabaseKey(key);
+  return generateDatabaseUrlValueForKey(key, appDir);
+}
+
+/**
+ * @param {string} key - Secret key
+ * @param {Record<string, string>|undefined} placeholderContext - Merged infra.parameter.yaml defaults + CLI overrides
+ * @returns {string|undefined} Value if catalog handled key; undefined to use legacy rules
+ */
+function tryGenerateSecretValueFromCatalog(key, placeholderContext) {
+  let catalogEntry;
+  try {
+    catalogEntry = infraParameterCatalogModule().getInfraParameterCatalog().findEntryForKey(key);
+  } catch (err) {
+    logger.warn(`infra parameter catalog unavailable (${err.message}); using legacy generators.`);
+    return undefined;
+  }
+  if (!catalogEntry || !catalogEntry.generator) return undefined;
+  const g = catalogEntry.generator.type;
+  if (g === 'databasePassword') {
+    const v = generateDbPasswordValue(key);
+    return v !== null ? v : undefined;
+  }
+  if (g === 'databaseUrl') {
+    const v = generateDbUrlValue(key);
+    return v !== null ? v : undefined;
   }
-  const dbName = appName.replace(/-/g, '_');
-  return `postgresql://${dbName}_user:${dbName}_pass123@\${DB_HOST}:\${DB_PORT}/${dbName}`;
+  if (
+    g === 'randomBytes32' ||
+    g === 'randomAlphanumeric' ||
+    g === 'password' ||
+    g === 'emptyString' ||
+    g === 'emptyAllowed' ||
+    g === 'literal'
+  ) {
+    return infraParameterCatalogModule().generateValueFromCatalogEntry(key, catalogEntry, crypto, placeholderContext);
+  }
+  return undefined;
 }
 
 /**
- * Generates secret value based on key name
- * @function generateSecretValue
- * @param {string} key - Secret key name
- * @returns {string} Generated secret value
+ * Last-resort generation when infra.parameter.yaml cannot be loaded (e.g. tests, broken install).
+ * @param {string} key
+ * @returns {string}
  */
-function generateSecretValue(key) {
+function legacySecretValueWhenCatalogUnavailable(key) {
   const keyLower = key.toLowerCase();
-
   if (keyLower.includes('password')) {
     const dbPassword = generateDbPasswordValue(key);
     if (dbPassword !== null) return dbPassword;
     return crypto.randomBytes(32).toString('base64');
   }
-
   if (keyLower.includes('url') || keyLower.includes('uri')) {
     const dbUrl = generateDbUrlValue(key);
     if (dbUrl !== null) return dbUrl;
     return '';
   }
-
   if (keyLower.includes('key') || keyLower.includes('secret') || keyLower.includes('token')) {
     return crypto.randomBytes(32).toString('base64');
   }
-
   return '';
 }
 
+/**
+ * @param {string} key - Secret key name
+ * @param {Record<string, string>|undefined} placeholderContext - Optional merged catalog defaults + CLI (e.g. up-infra)
+ * @returns {string} Generated secret value
+ */
+function generateSecretValue(key, placeholderContext) {
+  const fromCatalog = tryGenerateSecretValueFromCatalog(key, placeholderContext);
+  if (fromCatalog !== undefined) return fromCatalog;
+
+  const dbPassword = generateDbPasswordValue(key);
+  if (dbPassword !== null) return dbPassword;
+  const dbUrl = generateDbUrlValue(key);
+  if (dbUrl !== null) return dbUrl;
+
+  try {
+    infraParameterCatalogModule().getInfraParameterCatalog();
+  } catch {
+    logger.warn(
+      `Secret key "${key}": infra parameter catalog unavailable; using legacy name heuristics.`
+    );
+    return legacySecretValueWhenCatalogUnavailable(key);
+  }
+
+  throw new Error(
+    `Cannot generate secret for key "${key}": no matching rule in infra.parameter.yaml. ` +
+      'Add a catalog entry or run `aifabrix parameters validate` after fixing env.template references.'
+  );
+}
+
 /**
  * Loads existing secrets from file
  * @function loadExistingSecrets
@@ -196,9 +280,26 @@ function saveSecretsFile(resolvedPath, secrets) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
 
+  if (fs.existsSync(resolvedPath)) {
+    try {
+      const existing = fs.readFileSync(resolvedPath, 'utf8');
+      const mergedContent = mergeFlatSecretsYamlPreservingComments(existing, secrets, {
+        yaml,
+        dumpOpts: YAML_DUMP_OPTS
+      });
+      if (mergedContent !== null) {
+        fs.writeFileSync(resolvedPath, mergedContent + (mergedContent.endsWith('\n') ? '' : '\n'), { mode: 0o600 });
+        return;
+      }
+    } catch (err) {
+      logger.warn(`Could not preserve comments when writing secrets file: ${err.message}; rewriting YAML.`);
+      // fall through to dump overwrite
+    }
+  }
+
   const yamlContent = yaml.dump(secrets, {
     indent: 2,
-    lineWidth: 120,
+    lineWidth: -1,
     noRefs: true,
     sortKeys: false
   });
@@ -206,7 +307,21 @@ function saveSecretsFile(resolvedPath, secrets) {
   fs.writeFileSync(resolvedPath, yamlContent, { mode: 0o600 });
 }
 
-const YAML_DUMP_OPTS = { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false };
+const YAML_DUMP_OPTS = { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false };
+
+/**
+ * @param {string} resolvedPath
+ * @returns {string}
+ */
+function readSecretsFileUtf8OrWarnEmpty(resolvedPath) {
+  try {
+    const raw = fs.readFileSync(resolvedPath, 'utf8');
+    return typeof raw === 'string' ? raw : '';
+  } catch (err) {
+    logger.warn(`Could not read existing secrets file: ${err.message}; appending new keys only.`);
+    return '';
+  }
+}
 
 /**
  * Merges secret keys into the secrets file (load existing, merge, overwrite file).
@@ -253,12 +368,13 @@ function appendSecretsToFile(resolvedPath, secrets) {
     return;
   }
 
-  let existing = '';
+  const existing = readSecretsFileUtf8OrWarnEmpty(resolvedPath);
   try {
-    const raw = fs.readFileSync(resolvedPath, 'utf8');
-    existing = typeof raw === 'string' ? raw : '';
-  } catch (err) {
-    logger.warn(`Could not read existing secrets file: ${err.message}; appending new keys only.`);
+    yaml.load(existing);
+  } catch {
+    const mergedObj = { ...loadExistingSecrets(resolvedPath), ...secrets };
+    saveSecretsFile(resolvedPath, mergedObj);
+    return;
   }
   const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
   fs.writeFileSync(resolvedPath, existing + separator + appendContent, { mode: 0o600 });
@@ -296,7 +412,7 @@ async function generateMissingSecrets(envTemplate, secretsPath) {
 
   appendSecretsToFile(resolvedPath, newSecrets);
 
-  logger.log(`✓ Generated ${missingKeys.length} missing secret key(s): ${missingKeys.join(', ')}`);
+  logger.log(`✔ Generated ${missingKeys.length} missing secret key(s): ${missingKeys.join(', ')}`);
   return missingKeys;
 }
 
@@ -314,6 +430,15 @@ async function generateMissingSecrets(envTemplate, secretsPath) {
  * await createDefaultSecrets('~/.aifabrix/secrets.yaml');
  * // Default secrets file is created
  */
+/** Minimal seed keys for first-time secrets file; values match infra.parameter.yaml generators. */
+const DEFAULT_SECRETS_SEED_KEYS = [
+  'postgres-passwordKeyVault',
+  'redis-passwordKeyVault',
+  'redis-url',
+  'keycloak-admin-passwordKeyVault',
+  'keycloak-web-server-url'
+];
+
 async function createDefaultSecrets(secretsPath) {
   const resolvedPath = secretsPath.startsWith('~')
     ? path.join(os.homedir(), secretsPath.slice(1))
@@ -324,22 +449,17 @@ async function createDefaultSecrets(secretsPath) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
 
-  const defaultSecrets = `# Local Development Secrets
-# Production uses Azure KeyVault
-
-# Database Secrets
-postgres-passwordKeyVault: "admin123"
-
-# Redis Secrets
-redis-passwordKeyVault: ""
-redis-url: "redis://\${REDIS_HOST}:\${REDIS_PORT}"
+  const seeded = {};
+  for (const k of DEFAULT_SECRETS_SEED_KEYS) {
+    seeded[k] = generateSecretValue(k);
+  }
 
-# Keycloak Secrets
-keycloak-admin-passwordKeyVault: "admin123"
-keycloak-server-url: "http://\${KEYCLOAK_HOST}:\${KEYCLOAK_PORT}"
-`;
+  const header =
+    '# Local development secrets (catalog-aligned seed). Run aifabrix up-infra and aifabrix resolve <app> --force for full keys.\n' +
+    '# Production uses Azure Key Vault.\n\n';
+  const body = yaml.dump(seeded, { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false });
 
-  fs.writeFileSync(resolvedPath, defaultSecrets, { mode: 0o600 });
+  fs.writeFileSync(resolvedPath, header + body, { mode: 0o600 });
 }
 
 module.exports = {

package/lib/utils/secrets-helpers.js

@@ -46,6 +46,41 @@ function isCommentOrEmptyLine(line) {
 /** Regex for kv:// path (allows slashes, e.g. kv://hubspot/clientId) */
 const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
 
+const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
+
+/**
+ * Last-resort when infra.parameter.yaml cannot be read (e.g. Jest suites that mock `fs`;
+ * catalog uses `node:fs`, which is often the same mocked instance). Must stay in sync with
+ * `generator.type: emptyAllowed` keys in lib/schema/infra.parameter.yaml.
+ */
+const EMPTY_ALLOWED_KV_FALLBACK = new Set(['redis-passwordKeyVault']);
+
+/**
+ * Infra catalog keys with generator `emptyAllowed` may be absent from the secrets file;
+ * they resolve like an explicit empty string (e.g. local Redis has no password).
+ * @param {string} pathStr - kv path segment (flat key or path with slashes)
+ * @returns {boolean}
+ */
+function isKvKeyAllowedEmptyWhenAbsent(pathStr) {
+  if (!pathStr || typeof pathStr !== 'string') return false;
+  try {
+    const { getInfraParameterCatalog } = require('../parameters/infra-parameter-catalog');
+    return getInfraParameterCatalog().isKeyAllowedEmpty(pathStr);
+  } catch {
+    try {
+      const {
+        readRelaxedEmptyAllowedKeySet,
+        DEFAULT_CATALOG_PATH
+      } = require('../parameters/infra-parameter-catalog');
+      const set = readRelaxedEmptyAllowedKeySet(DEFAULT_CATALOG_PATH);
+      if (set && set.has(pathStr)) return true;
+    } catch {
+      /* ignore */
+    }
+  }
+  return EMPTY_ALLOWED_KV_FALLBACK.has(pathStr);
+}
+
 /**
  * Find object key that matches part case-insensitively.
  * @param {Object} obj - Object to search
@@ -98,19 +133,30 @@ function getValueByPath(secrets, pathStr) {
   return getValueByNestedPath(secrets, pathStr.split('/'));
 }
 
+const { getValueByPathWithEnvScope, mergeSecretsWithPrefixedCopies } =
+  require('./secrets-kv-scope').createScopedKvHelpers(getValueByPath);
+
+function resolveKvRefValue(secretsMap, pathStr, envKey, effective) {
+  const v = getValueByPathWithEnvScope(secretsMap, pathStr, envKey, effective);
+  if (v !== undefined && v !== null) return v;
+  return resolveBashKvFromProcessEnv(pathStr);
+}
+
 /**
  * Collect missing kv:// secrets referenced in content (skips commented and empty lines).
  * Supports path-style refs (e.g. kv://hubspot/clientId). Returns unique refs.
  * @function collectMissingSecrets
  * @param {string} content - Text content
  * @param {Object} secrets - Available secrets (flat or nested)
+ * @param {{ effective?: boolean, envKey?: string }|null} [scopedKv] - Optional env-scoped kv resolution
  * @returns {string[]} Array of missing kv://<path> references (unique)
  */
-function collectMissingSecrets(content, secrets) {
+function collectMissingSecrets(content, secrets, scopedKv = null) {
+  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
+  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(secrets, scopedKv.envKey) : secrets;
   const seen = new Set();
   const missing = [];
-  const lines = content.split('\n');
-  for (const line of lines) {
+  for (const line of content.split('\n')) {
     if (isCommentOrEmptyLine(line)) continue;
     let match;
     KV_REF_PATTERN.lastIndex = 0;
@@ -118,8 +164,8 @@ function collectMissingSecrets(content, secrets) {
       const pathStr = match[1];
       if (seen.has(pathStr)) continue;
       seen.add(pathStr);
-      const value = getValueByPath(secrets, pathStr);
-      if (value === undefined || value === null) {
+      const value = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+      if ((value === undefined || value === null) && !isKvKeyAllowedEmptyWhenAbsent(pathStr)) {
         missing.push(`kv://${pathStr}`);
       }
     }
@@ -157,14 +203,20 @@ function formatMissingSecretsFileInfo(secretsFilePaths) {
  * @param {string} content - Text content containing kv:// references
  * @param {Object} secrets - Secrets map (flat or nested)
  * @param {Object} envVars - Environment variables map for nested interpolation
+ * @param {{ effective?: boolean, envKey?: string }|null} [scopedKv] - Optional env-scoped kv resolution
  * @returns {string} Content with kv:// references replaced
  */
-function replaceKvInContent(content, secrets, envVars) {
+function replaceKvInContent(content, secrets, envVars, scopedKv = null) {
+  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
+  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(secrets, scopedKv.envKey) : secrets;
   const lines = content.split('\n');
   const result = lines.map(line => {
     if (isCommentOrEmptyLine(line)) return line;
     return line.replace(KV_REF_PATTERN, (match, pathStr) => {
-      let value = getValueByPath(secrets, pathStr);
+      let value = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+      if ((value === undefined || value === null) && isKvKeyAllowedEmptyWhenAbsent(pathStr)) {
+        value = '';
+      }
       if (typeof value === 'string') {
         value = value.replace(/\$\{([A-Z_]+)\}/g, (m, envVar) => {
           return envVars[envVar] || m;
@@ -247,44 +299,23 @@ function getPortFromEnvContent(envContent) {
 }
 
 /**
- * Applies developer-id adjustment to port
- * @function applyDeveloperIdAdjustment
- * @param {number} baseAppPort - Base application port
- * @param {number} devIdNum - Developer ID number
- * @returns {number} Adjusted port
- */
-function applyDeveloperIdAdjustment(baseAppPort, devIdNum) {
-  return devIdNum === 0 ? baseAppPort : (baseAppPort + (devIdNum * 100));
-}
-
-/**
- * Calculate application port following override chain and developer-id adjustment
- * Override chain: env-config.yaml → config.yaml → application.yaml port
+ * Resolve manifest listen port (container port) for the app from override chain.
  * @async
- * @function calculateAppPort
  * @param {string} [variablesPath] - Path to application config
- * @param {Object} localEnv - Local environment config from env-config.yaml and config.yaml
+ * @param {Object} localEnv - Merged local env from defaults + config.yaml
  * @param {string} envContent - Environment content for fallback
- * @param {number} devIdNum - Developer ID number
- * @returns {Promise<number>} Final application port with developer-id adjustment
+ * @returns {Promise<number>} Base listen port (before +10 / +dev*100 local host math)
  */
-async function calculateAppPort(variablesPath, localEnv, envContent, devIdNum) {
-  // Start with env-config value
+async function resolveManifestListenPort(variablesPath, localEnv, envContent) {
   let baseAppPort = getPortFromLocalEnv(localEnv);
-
-  // Override with application config port (strongest)
   const variablesPort = getPortFromVariablesFile(variablesPath);
   if (variablesPort !== null) {
     baseAppPort = variablesPort;
   }
-
-  // Fallback to env content if still no port
   if (baseAppPort === null || baseAppPort === undefined) {
     baseAppPort = getPortFromEnvContent(envContent);
   }
-
-  // Apply developer-id adjustment
-  return applyDeveloperIdAdjustment(baseAppPort, devIdNum);
+  return baseAppPort;
 }
 
 /**
@@ -325,16 +356,6 @@ function getPortVarFromEnvTemplatePath(variablesPath) {
   }
 }
 
-/**
- * Adjust infra-related ports in resolved .env content for local environment.
- * Own case: when we generate .env for envOutputPath (not reload), we use localPort (application.yaml build.localPort or port).
- * Sets PORT and the template port var (e.g. MISO_PORT) to localPort so the generated .env is correct for local use.
- * @async
- * @function adjustLocalEnvPortsInContent
- * @param {string} envContent - Resolved .env content
- * @param {string} [variablesPath] - Path to application config (to read port and template port var)
- * @returns {Promise<string>} Updated content with local ports
- */
 /**
  * Gets developer ID number
  * @async
@@ -418,12 +439,13 @@ async function buildEnvVarsForInterpolation(devIdNum) {
 async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   const devIdNum = await getDeveloperIdNumber();
   const localEnv = await getLocalEnvWithOverrides();
+  const { localHostPort } = require('./declarative-url-ports');
 
-  const baseAppPort = await calculateAppPort(variablesPath, localEnv, envContent, 0);
-  const appPort = await calculateAppPort(variablesPath, localEnv, envContent, devIdNum);
+  const baseListen = await resolveManifestListenPort(variablesPath, localEnv, envContent);
+  const appPort = localHostPort(baseListen, devIdNum);
 
   let updated = updatePortVariable(envContent, appPort);
-  updated = updateLocalhostUrls(updated, baseAppPort, appPort);
+  updated = updateLocalhostUrls(updated, baseListen, appPort);
   updated = await rewriteInfraEndpoints(updated, 'local');
 
   const envVars = await buildEnvVarsForInterpolation(devIdNum);
@@ -437,18 +459,6 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   return updated;
 }
 
-/**
- * Ensure secrets map is non-empty or throw a friendly guidance error
- * @function ensureNonEmptySecrets
- * @param {Object} secrets - Secrets map
- * @throws {Error} If secrets is empty
- */
-function ensureNonEmptySecrets(secrets) {
-  if (Object.keys(secrets || {}).length === 0) {
-    throw new Error('No secrets file found. Please create ~/.aifabrix/secrets.local.yaml or configure aifabrix-secrets in config.yaml');
-  }
-}
-
 /**
  * Validate secrets against the env template (skips commented and empty lines)
  * @function validateSecrets
@@ -465,6 +475,8 @@ module.exports = {
   loadEnvConfig,
   interpolateEnvVars,
   collectMissingSecrets,
+  resolveBashKvFromProcessEnv,
+  mergeSecretsWithPrefixedCopies,
   formatMissingSecretsFileInfo,
   replaceKvInContent,
   resolveServicePortsInEnvContent,
@@ -473,7 +485,6 @@ module.exports = {
   adjustLocalEnvPortsInContent,
   readYamlAtPath,
   applyCanonicalSecretsOverride,
-  ensureNonEmptySecrets,
   validateSecrets,
   rewriteInfraEndpoints,
   getEnvHosts

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

@@ -0,0 +1,60 @@
+/**
+ * Env-scoped kv:// resolution helpers (prefixed keys + in-memory aliases).
+ *
+ * @fileoverview Split from secrets-helpers for file size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Function} getValueByPath - From secrets-helpers
+ * @returns {{ getValueByPathWithEnvScope: Function, mergeSecretsWithPrefixedCopies: Function }}
+ */
+function createScopedKvHelpers(getValueByPath) {
+  /**
+   * @param {Object} secrets
+   * @param {string} pathStr
+   * @param {string|null|undefined} envKey
+   * @param {boolean} effective
+   * @returns {*}
+   */
+  function getValueByPathWithEnvScope(secrets, pathStr, envKey, effective) {
+    if (!effective || !envKey) {
+      return getValueByPath(secrets, pathStr);
+    }
+    const prefix = `${String(envKey).toLowerCase()}-`;
+    const prefixedPath = prefix + pathStr;
+    const fromPrefixed = getValueByPath(secrets, prefixedPath);
+    if (fromPrefixed !== undefined && fromPrefixed !== null) {
+      return fromPrefixed;
+    }
+    return getValueByPath(secrets, pathStr);
+  }
+
+  /**
+   * @param {Object} secrets
+   * @param {string} envKey
+   * @returns {Object}
+   */
+  function mergeSecretsWithPrefixedCopies(secrets, envKey) {
+    if (!secrets || typeof secrets !== 'object' || !envKey) {
+      return secrets;
+    }
+    const prefix = `${String(envKey).toLowerCase()}-`;
+    const merged = { ...secrets };
+    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) {
+        merged[pk] = v;
+      }
+    }
+    return merged;
+  }
+
+  return { getValueByPathWithEnvScope, mergeSecretsWithPrefixedCopies };
+}
+
+module.exports = { createScopedKvHelpers };