@aifabrix/builder 2.60.0 → 2.62.0

package/lib/utils/registry-credentials.js

@@ -1,9 +1,19 @@
 /**
  * Host-scoped container registry credentials in the primary user secrets file.
  *
- * Keys are exactly `<registry>-username` and `<registry>-password` in the user's
- * `secrets.local.yaml` (never the shared store). Values are encrypted through the existing
- * local-secret writer and reach Docker only via `docker login --password-stdin`.
+ * Keys are `registry-<slug>-username` and `registry-<slug>-password` in the user's
+ * `secrets.local.yaml` (never the shared store), where the slug is the host with every
+ * character outside `[a-z0-9]` replaced by `-`. The vault naming contract accepts
+ * alphanumerics and dashes only, so the earlier `<host>-username` form — which keeps the
+ * dots of `myreg.azurecr.io` — was local-only by accident rather than by design. The
+ * `registry-` prefix keeps a host that begins with an application key distinguishable from
+ * that application's own secrets in the same flat file.
+ *
+ * Pairs written under the old keys are still read, so an existing `dev set-registry` does
+ * not silently stop working, and removal clears both forms.
+ *
+ * Values are encrypted through the existing local-secret writer and reach Docker only via
+ * `docker login --password-stdin`.
  *
  * @fileoverview Registry credential storage, lookup, removal, and per-command Docker login
  * @author AI Fabrix Team
@@ -25,12 +35,41 @@ const { normalizeRegistryHost } = require('./config-registry-preference');
 const authenticatedHosts = new Set();
 
 /**
+ * Host reduced to the vault naming charset: lowercase alphanumerics and dashes.
+ *
+ * @param {string} host - Normalized registry host
+ * @returns {string} Slug safe for a secret key
+ */
+function registryKeySlug(host) {
+  return String(host)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Secret keys for a registry, including the previous form so an existing pair still loads.
+ *
+ * `hostKey` records which host owns the slug. Two hosts can normalise to one slug
+ * (`a.b-c` and `a-b.c` both give `a-b-c`), and silently reusing another registry's
+ * credentials is worse than refusing, so a write compares against it.
+ *
  * @param {string} registry - Registry host
- * @returns {{ host: string, usernameKey: string, passwordKey: string }}
+ * @returns {{ host: string, slug: string, usernameKey: string, passwordKey: string,
+ *   hostKey: string, legacyUsernameKey: string, legacyPasswordKey: string }}
  */
 function registryCredentialKeys(registry) {
   const host = normalizeRegistryHost(registry);
-  return { host, usernameKey: `${host}-username`, passwordKey: `${host}-password` };
+  const slug = registryKeySlug(host);
+  return {
+    host,
+    slug,
+    usernameKey: `registry-${slug}-username`,
+    passwordKey: `registry-${slug}-password`,
+    hostKey: `registry-${slug}-host`,
+    legacyUsernameKey: `${host}-username`,
+    legacyPasswordKey: `${host}-password`
+  };
 }
 
 function hasValue(value) {
@@ -40,7 +79,18 @@ function hasValue(value) {
 function readRawPair(keys) {
   const file = pathsUtil.getPrimaryUserSecretsLocalPath();
   const raw = loadExistingSecrets(file);
-  return { file, username: raw[keys.usernameKey], password: raw[keys.passwordKey] };
+  const current = { username: raw[keys.usernameKey], password: raw[keys.passwordKey] };
+  if (hasValue(current.username) || hasValue(current.password)) {
+    return { file, ...current, legacy: false, owner: raw[keys.hostKey] };
+  }
+  // Written before the keys were namespaced; read it rather than prompting again.
+  return {
+    file,
+    username: raw[keys.legacyUsernameKey],
+    password: raw[keys.legacyPasswordKey],
+    legacy: true,
+    owner: undefined
+  };
 }
 
 function partialPairError(keys) {
@@ -106,13 +156,36 @@ function removeKeysFromFile(file, keyNames) {
   return true;
 }
 
+/**
+ * Refuse to overwrite a different host's credentials when two hosts share a slug.
+ *
+ * @param {Object} keys - From {@link registryCredentialKeys}
+ * @param {Object} snapshot - From readRawPair
+ * @throws {Error} When the slug already belongs to another host
+ */
+function assertNoSlugCollision(keys, snapshot) {
+  const owner = typeof snapshot.owner === 'string' ? snapshot.owner.trim() : '';
+  if (!owner || owner === keys.host) {
+    return;
+  }
+  throw new Error(
+    `Registry key collision: "${keys.host}" and "${owner}" both reduce to "${keys.slug}", ` +
+    `so storing this pair would overwrite the credentials for ${owner}. ` +
+    `Remove the other registry first with "aifabrix dev set-registry ${owner} --clear-credentials".`
+  );
+}
+
 function restorePair(keys, snapshot) {
+  // Always clear what a save writes, then put back what the snapshot actually held — which
+  // may be under the old keys, since a pair written before namespacing is read from there.
   const restore = {};
-  const remove = [];
-  for (const [key, value] of [[keys.usernameKey, snapshot.username], [keys.passwordKey, snapshot.password]]) {
-    if (value === undefined) remove.push(key);
-    else restore[key] = value;
-  }
+  const [usernameKey, passwordKey] = snapshot.legacy
+    ? [keys.legacyUsernameKey, keys.legacyPasswordKey]
+    : [keys.usernameKey, keys.passwordKey];
+  if (snapshot.username !== undefined) restore[usernameKey] = snapshot.username;
+  if (snapshot.password !== undefined) restore[passwordKey] = snapshot.password;
+  const remove = [keys.usernameKey, keys.passwordKey, keys.hostKey]
+    .filter((key) => !Object.prototype.hasOwnProperty.call(restore, key));
   removeKeysFromFile(snapshot.file, remove);
   mergeSecretsIntoFile(snapshot.file, restore);
 }
@@ -130,14 +203,21 @@ async function saveRegistryCredentials(registry, username, password) {
     throw new Error('Registry username and password must both be non-empty');
   }
   const snapshot = readRawPair(keys);
+  assertNoSlugCollision(keys, snapshot);
   await config.ensureSecretsEncryptionKey();
   try {
     await saveLocalSecret(keys.usernameKey, String(username));
     await saveLocalSecret(keys.passwordKey, String(password));
+    // Plain, not through saveLocalSecret: the host is not a secret, and encrypting it would
+    // make every later read compare a ciphertext against the host and report a collision.
+    mergeSecretsIntoFile(snapshot.file, { [keys.hostKey]: keys.host });
   } catch (error) {
     restorePair(keys, snapshot);
     throw new Error(`Could not save registry credentials for ${keys.host}; previous values were restored (${error.message})`);
   }
+  // The pair now lives under the namespaced keys; leaving the old one behind would keep a
+  // stale password readable and let a later read pick whichever it found first.
+  removeKeysFromFile(snapshot.file, [keys.legacyUsernameKey, keys.legacyPasswordKey]);
   authenticatedHosts.delete(keys.host);
   return { host: keys.host, rollback: () => restorePair(keys, snapshot) };
 }
@@ -150,12 +230,24 @@ async function saveRegistryCredentials(registry, username, password) {
 function removeRegistryCredentials(registry) {
   const keys = registryCredentialKeys(registry);
   authenticatedHosts.delete(keys.host);
-  return removeKeysFromFile(pathsUtil.getPrimaryUserSecretsLocalPath(), [keys.usernameKey, keys.passwordKey]);
+  return removeKeysFromFile(pathsUtil.getPrimaryUserSecretsLocalPath(), [
+    keys.usernameKey,
+    keys.passwordKey,
+    keys.hostKey,
+    keys.legacyUsernameKey,
+    keys.legacyPasswordKey
+  ]);
 }
 
 /**
- * Authenticates Docker to the registry once per process: stored pair first, then the optional
- * fallback (for example Azure CLI for ACR). The password is sent only on stdin.
+ * Authenticates Docker to the registry once per process: stored pair first, then the
+ * optional fallback. The password is sent only on stdin.
+ *
+ * There is deliberately no default fallback. Most pulls are of public images and must stay
+ * anonymous; asking for a credential there would prompt for something the pull does not
+ * need. A caller that genuinely requires a credential passes one — see
+ * {@link ensureRegistryLoginWithSources}.
+ *
  * @param {string} registry - Registry host
  * @param {Object} [options] - Options
  * @param {Function} [options.fallback] - async (host) => void when no pair is stored
@@ -180,6 +272,29 @@ async function ensureRegistryLogin(registry, options = {}) {
   return 'none';
 }
 
+/**
+ * Authenticate a registry that a command cannot proceed without.
+ *
+ * Adds the credential-source chain on top of {@link ensureRegistryLogin}: the stored pair,
+ * then `az acr login` for an `*.azurecr.io` host, then a prompt. A non-interactive run
+ * fails naming the host instead of hanging on a question nobody can answer.
+ *
+ * @param {string} registry - Registry host
+ * @param {Object} [sources] - Overrides for {@link buildRegistryAuthFallback}
+ * @returns {Promise<'cached'|'credentials'|'acr'|'prompt'>}
+ */
+async function ensureRegistryLoginWithSources(registry, sources = {}) {
+  const { buildRegistryAuthFallback } = require('./registry-auth-sources');
+  const fallback = buildRegistryAuthFallback(sources);
+  let outcome = null;
+  const result = await ensureRegistryLogin(registry, {
+    fallback: async(host) => {
+      outcome = await fallback(host);
+    }
+  });
+  return result === 'fallback' ? outcome : result;
+}
+
 /**
  * Registry host of an image reference, or '' for Docker Hub style refs.
  * @param {string} imageRef - Image reference (`host/repo:tag`, `repo:tag`, ...)
@@ -224,12 +339,14 @@ function resetRegistryLoginCache(registry) {
 }
 
 module.exports = {
+  registryKeySlug,
   registryCredentialKeys,
   getRegistryCredentialStatus,
   loadRegistryCredentials,
   saveRegistryCredentials,
   removeRegistryCredentials,
   ensureRegistryLogin,
+  ensureRegistryLoginWithSources,
   ensureLoginForImageRefs,
   registryHostFromImageRef,
   resetRegistryLoginCache

package/lib/utils/secrets-generator.js

@@ -16,6 +16,7 @@ const yaml = require('js-yaml');
 const crypto = require('crypto');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
+const { generateRsaSecretValues } = require('../parameters/rsa-secret-values');
 const { mergeFlatSecretsYamlPreservingComments } = require('./secrets-yaml-preserve');
 const {
   generateDatabasePasswordValueForKey,
@@ -165,32 +166,40 @@ function generateDbUrlValue(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;
+/** Generators whose value comes straight from the catalog entry. */
+const CATALOG_DIRECT_GENERATORS = Object.freeze([
+  'randomBytes32', 'randomAlphanumeric', 'password', 'emptyString', 'emptyAllowed', 'literal'
+]);
+
+/**
+ * The catalog entry for a key, or nothing when the catalog cannot be read.
+ *
+ * @param {string} key - Secret key
+ * @returns {Object|undefined}
+ */
+function catalogEntryForKey(key) {
   try {
-    catalogEntry = infraParameterCatalogModule().getInfraParameterCatalog().findEntryForKey(key);
+    return infraParameterCatalogModule().getInfraParameterCatalog().findEntryForKey(key);
   } catch (err) {
     logger.warn(`infra parameter catalog unavailable (${err.message}); using legacy generators.`);
     return undefined;
   }
+}
+
+function tryGenerateSecretValueFromCatalog(key, placeholderContext) {
+  const catalogEntry = catalogEntryForKey(key);
   if (!catalogEntry || !catalogEntry.generator) return undefined;
   const g = catalogEntry.generator.type;
+  if (g === 'rsaKeyPair') {
+    return require('../parameters/rsa-secret-values').generateRsaValueFromCatalog(key, catalogEntry);
+  }
   if (g === 'databasePassword') {
-    const v = generateDbPasswordValue(key);
-    return v !== null ? v : undefined;
+    return generateDbPasswordValue(key) ?? undefined;
   }
   if (g === 'databaseUrl') {
-    const v = generateDbUrlValue(key);
-    return v !== null ? v : undefined;
-  }
-  if (
-    g === 'randomBytes32' ||
-    g === 'randomAlphanumeric' ||
-    g === 'password' ||
-    g === 'emptyString' ||
-    g === 'emptyAllowed' ||
-    g === 'literal'
-  ) {
+    return generateDbUrlValue(key) ?? undefined;
+  }
+  if (CATALOG_DIRECT_GENERATORS.includes(g)) {
     return infraParameterCatalogModule().generateValueFromCatalogEntry(key, catalogEntry, crypto, placeholderContext);
   }
   return undefined;
@@ -411,15 +420,16 @@ async function generateMissingSecrets(envTemplate, secretsPath) {
     return [];
   }
 
-  const newSecrets = {};
+  const newSecrets = generateRsaSecretValues(missingKeys, existingSecrets);
   for (const key of missingKeys) {
-    newSecrets[key] = generateSecretValue(key);
+    if (!(key in newSecrets)) newSecrets[key] = generateSecretValue(key);
   }
 
   appendSecretsToFile(resolvedPath, newSecrets);
 
-  logger.log(`✔ Generated ${missingKeys.length} missing secret key(s): ${missingKeys.join(', ')}`);
-  return missingKeys;
+  const generatedKeys = Object.keys(newSecrets);
+  logger.log(`✔ Generated ${generatedKeys.length} missing secret key(s): ${generatedKeys.join(', ')}`);
+  return generatedKeys;
 }
 
 /**
@@ -479,4 +489,3 @@ module.exports = {
   generateMissingSecrets,
   createDefaultSecrets
 };
-

package/lib/utils/secrets-helpers.js

@@ -55,7 +55,6 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 const EMPTY_ALLOWED_KV_FALLBACK = new Set([
   'redis-passwordKeyVault',
   'azure-openaiapi-urlKeyVault',
-  'secrets-azureOpenaiApiKeyVault',
   'miso-controller-secrets-apiKeyVault'
 ]);
 
@@ -137,7 +136,7 @@ function getValueByPath(secrets, pathStr) {
   return getValueByNestedPath(secrets, pathStr.split('/'));
 }
 
-const { getValueByPathWithEnvScope, mergeSecretsWithPrefixedCopies } =
+const { getValueByPathWithEnvScope, mergeSecretsWithPrefixedCopies, prepareScopedKv } =
   require('./secrets-kv-scope').createScopedKvHelpers(getValueByPath);
 
 function resolveKvRefValue(secretsMap, pathStr, envKey, effective) {
@@ -156,8 +155,7 @@ function resolveKvRefValue(secretsMap, pathStr, envKey, effective) {
  * @returns {string[]} Array of missing kv://<path> references (unique)
  */
 function collectMissingSecrets(content, secrets, scopedKv = null) {
-  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
-  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(secrets, scopedKv.envKey) : secrets;
+  const { secretsMap, envKey, effective } = prepareScopedKv(secrets, scopedKv);
   const seen = new Set();
   const missing = [];
   for (const line of content.split('\n')) {
@@ -169,7 +167,7 @@ function collectMissingSecrets(content, secrets, scopedKv = null) {
       const pathStr = match[1];
       if (seen.has(pathStr)) continue;
       seen.add(pathStr);
-      const value = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+      const value = resolveKvRefValue(secretsMap, pathStr, envKey, effective);
       if ((value === undefined || value === null) && !isKvKeyAllowedEmptyWhenAbsent(pathStr)) {
         missing.push(`kv://${pathStr}`);
       }
@@ -217,8 +215,7 @@ function formatMissingSecretsFileInfo(secretsFilePaths) {
  * @returns {string} Content with kv:// references replaced
  */
 function replaceKvInContent(content, secrets, envVars, scopedKv = null) {
-  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
-  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(secrets, scopedKv.envKey) : secrets;
+  const { secretsMap, envKey, effective } = prepareScopedKv(secrets, scopedKv);
   const lines = content.split('\n');
   const result = lines.map(line => {
     if (isCommentOrEmptyLine(line)) return line;
@@ -226,7 +223,7 @@ function replaceKvInContent(content, secrets, envVars, scopedKv = null) {
     if (!scanLine.trim()) return line;
     const suffix = line.slice(scanLine.length);
     const replaced = scanLine.replace(KV_REF_PATTERN, (match, pathStr) => {
-      let value = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+      let value = resolveKvRefValue(secretsMap, pathStr, envKey, effective);
       if ((value === undefined || value === null) && isKvKeyAllowedEmptyWhenAbsent(pathStr)) {
         value = '';
       }

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

@@ -1,6 +1,21 @@
 /**
  * Env-scoped kv:// resolution helpers (prefixed keys + in-memory aliases).
  *
+ * Two regimes share this module:
+ *
+ * - `dev` and `miso` are **lenient** (plan 117). A `<env>-<key>` secret wins when present,
+ *   and an absent one falls back to the unprefixed key. Existing installations are written
+ *   that way, so removing the fallback would break every one of them.
+ * - `tst` and `pro` are **strict** (plan 210.0). Only `<env>-<key>` is read. An absent key
+ *   is absent — it never falls back to the unprefixed value and it is never generated.
+ *
+ * The strict rule is the whole point: these environments share one Postgres, one Redis and
+ * one secrets file with `dev`. A fallback there would hand production whatever `dev` happens
+ * to hold, which is worse than failing, because it looks like it worked. Strictness is
+ * therefore deliberately independent of `useEnvironmentScopedResources` and of the
+ * per-application `environmentScopedResources` flag: an installation that forgot to set
+ * either must not silently resolve `pro` against `dev`'s secrets.
+ *
  * @fileoverview Split from secrets-helpers for file size limits
  * @author AI Fabrix Team
  * @version 1.0.0
@@ -8,6 +23,25 @@
 
 'use strict';
 
+/**
+ * Environments where the `<env>-` prefix is mandatory rather than preferred.
+ *
+ * Not the same list as `physical-database-naming.PHYSICAL_NAME_ENVIRONMENTS`: that one is the
+ * Postgres naming vocabulary and includes `miso` and `dev`, which resolve leniently here.
+ */
+const STRICT_SCOPED_ENVIRONMENTS = Object.freeze(['tst', 'pro']);
+
+/**
+ * @param {string} envKey - Run environment key
+ * @returns {boolean} True when the prefix is mandatory for this environment
+ */
+function isStrictScopedEnvironment(envKey) {
+  if (!envKey || typeof envKey !== 'string') {
+    return false;
+  }
+  return STRICT_SCOPED_ENVIRONMENTS.includes(envKey.trim().toLowerCase());
+}
+
 /**
  * Treat undefined/null and whitespace-only strings as no value so prefixed slots
  * cannot shadow unprefixed secrets with empty placeholders (plan 117 scoped KV).
@@ -25,9 +59,80 @@ function isKvSlotEmpty(v) {
   return false;
 }
 
+/**
+ * The secret key a strict environment actually requires.
+ *
+ * **Not simply `<env>-<key>`.** Miso's naming rule has three cases, and only the middle one
+ * is a bare environment prefix:
+ *
+ * ```text
+ * system              <key>            unprefixed, deliberately
+ * environment-scoped  pro-<key>
+ * application-scoped  pro-<app>-<key>
+ * ```
+ *
+ * They are not distinguishable from the key alone, so the name comes from the catalog entry's
+ * own vault-name pattern rather than being built here. A database password is therefore
+ * `pro-dataplane-databases-0-passwordKeyVault` — the application segment before the key — and
+ * `keycloak-*` and `acr-*` keep the names the Marketplace template writes.
+ *
+ * @param {string} envKey - Run environment key
+ * @param {string} pathStr - Unprefixed kv path
+ * @returns {string}
+ */
+function strictScopedKeyName(envKey, pathStr) {
+  const { resolveStrictSecretName } = require('../parameters/physical-secret-name');
+  return resolveStrictSecretName(pathStr, String(envKey).toLowerCase());
+}
+
+/**
+ * Alias every unprefixed key to its `<env>-` name so a lenient lookup finds it.
+ *
+ * Never called for a strict environment: aliasing there would reintroduce the fallback
+ * this module exists to remove.
+ *
+ * @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 (isKvSlotEmpty(merged[pk]) && !isKvSlotEmpty(v)) {
+      merged[pk] = v;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Resolve the scoped-kv regime and the secrets map to read through.
+ *
+ * One helper so every caller applies the same rule; a caller that recomputed `effective`
+ * itself could leave a strict environment resolving leniently.
+ *
+ * @param {Object} secrets - Merged secrets map
+ * @param {{ effective?: boolean, envKey?: string }|null} scopedKv
+ * @returns {{ secretsMap: Object, envKey: string|undefined, effective: boolean, strict: boolean }}
+ */
+function prepareScopedKv(secrets, scopedKv) {
+  const envKey = scopedKv && scopedKv.envKey ? scopedKv.envKey : undefined;
+  const strict = isStrictScopedEnvironment(envKey);
+  const effective = strict || Boolean(scopedKv && scopedKv.effective && envKey);
+  const secretsMap =
+    effective && !strict ? mergeSecretsWithPrefixedCopies(secrets, envKey) : secrets;
+  return { secretsMap, envKey, effective, strict };
+}
+
 /**
  * @param {Function} getValueByPath - From secrets-helpers
- * @returns {{ getValueByPathWithEnvScope: Function, mergeSecretsWithPrefixedCopies: Function }}
+ * @returns {Object} Scoped kv helpers bound to that lookup
  */
 function createScopedKvHelpers(getValueByPath) {
   /**
@@ -38,40 +143,34 @@ function createScopedKvHelpers(getValueByPath) {
    * @returns {*}
    */
   function getValueByPathWithEnvScope(secrets, pathStr, envKey, effective) {
-    if (!effective || !envKey) {
+    const strict = isStrictScopedEnvironment(envKey);
+    if (!strict && (!effective || !envKey)) {
       return getValueByPath(secrets, pathStr);
     }
-    const prefix = `${String(envKey).toLowerCase()}-`;
-    const prefixedPath = prefix + pathStr;
-    const fromPrefixed = getValueByPath(secrets, prefixedPath);
+    const fromPrefixed = getValueByPath(secrets, strictScopedKeyName(envKey, pathStr));
+    if (strict) {
+      // No fallback. Undefined rather than the empty value so the caller's
+      // allowed-empty rule still decides whether absence is an error.
+      return isKvSlotEmpty(fromPrefixed) ? undefined : fromPrefixed;
+    }
     if (!isKvSlotEmpty(fromPrefixed)) {
       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 (isKvSlotEmpty(merged[pk]) && !isKvSlotEmpty(v)) {
-        merged[pk] = v;
-      }
-    }
-    return merged;
-  }
-
-  return { getValueByPathWithEnvScope, mergeSecretsWithPrefixedCopies };
+  return {
+    getValueByPathWithEnvScope,
+    mergeSecretsWithPrefixedCopies,
+    prepareScopedKv
+  };
 }
 
-module.exports = { createScopedKvHelpers };
+module.exports = {
+  STRICT_SCOPED_ENVIRONMENTS,
+  isStrictScopedEnvironment,
+  strictScopedKeyName,
+  mergeSecretsWithPrefixedCopies,
+  prepareScopedKv,
+  createScopedKvHelpers
+};

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

@@ -17,6 +17,7 @@ const secretsUtils = require('./secrets-utils');
 const { loadConfiguredSharedSecretsStore } = require('./remote-secrets-loader');
 const { decryptSecretsObject } = require('../core/secrets-load');
 const { collectUniqueKvPathStrings } = require('./secrets-kv-refs');
+const { isStrictScopedEnvironment } = require('./secrets-kv-scope');
 const {
   resolveKvRefValue,
   mergeSecretsWithPrefixedCopies,
@@ -98,6 +99,14 @@ async function materializeResolvedKvSecretsToUserLocal(templateContent, mergedSe
     return [];
   }
 
+  // This writes back under the UNPREFIXED key. In a strict environment that would mint an
+  // unprefixed copy of a tst or pro secret which dev would then resolve, quietly undoing the
+  // isolation. Nothing is lost by skipping: a strict environment resolves only `<env>-<key>`,
+  // so every value it resolved was already stored under the name it will be read by.
+  if (isStrictScopedEnvironment(scopedKv && scopedKv.envKey)) {
+    return [];
+  }
+
   try {
     const { effective, secretsMap, localMap } = buildScopedMaps(mergedSecrets, scopedKv);
     const sharedScoped = await resolveSharedScopedMapForMaterialize(scopedKv, effective);

package/lib/utils/secrets-missing-error.js

@@ -10,6 +10,7 @@
 
 const { formatMissingSecretsFileInfo } = require('./secrets-helpers');
 const { isCommentOrEmptyLine } = require('./secrets-kv-refs');
+const { isStrictScopedEnvironment, strictScopedKeyName } = require('./secrets-kv-scope');
 
 /**
  * @param {string} kvRef - e.g. kv://hubspot-demo/clientSecret
@@ -117,6 +118,35 @@ function buildKvNamespaceAlternateHints(missing, secrets, appName) {
   return lines;
 }
 
+/**
+ * Name the key a strict environment actually needs.
+ *
+ * The template references `kv://<key>`, but `tst` and `pro` only read `<env>-<key>`, so an
+ * error quoting the template reference alone would send someone to create the one name that
+ * will not be used. Both are printed: the reference so the template line is findable, and
+ * the required key so `aifabrix secret set` gets the right argument.
+ *
+ * @param {string[]} missing - kv:// refs
+ * @param {{ envKey?: string }|null} [scopedKv]
+ * @returns {string[]}
+ */
+function buildStrictScopedKeyHints(missing, scopedKv) {
+  const envKey = scopedKv && scopedKv.envKey ? scopedKv.envKey : null;
+  if (!envKey || !isStrictScopedEnvironment(envKey)) {
+    return [];
+  }
+  const env = String(envKey).toLowerCase();
+  const lines = missing.map(
+    (ref) => `Required-key: ${strictScopedKeyName(env, kvRefToSecretSetKey(ref))}`
+  );
+  lines.push(
+    `Scoped-env-hint: ${env} reads only ${env}-prefixed secrets. The unprefixed key is ` +
+      `not a fallback and is never generated for ${env}, so another environment's value ` +
+      'cannot be used by accident.'
+  );
+  return lines;
+}
+
 /**
  * @param {Object} opts
  * @param {string[]} opts.missing
@@ -125,10 +155,11 @@ function buildKvNamespaceAlternateHints(missing, secrets, appName) {
  * @param {string} [opts.envTemplatePath]
  * @param {string} [opts.envTemplate]
  * @param {Object} [opts.secrets]
+ * @param {{ envKey?: string }|null} [opts.scopedKv]
  * @returns {string}
  */
 function buildMissingSecretsErrorMessage(opts) {
-  const { missing, secretsFilePaths, appName, envTemplatePath, envTemplate, secrets } = opts;
+  const { missing, secretsFilePaths, appName, envTemplatePath, envTemplate, secrets, scopedKv } = opts;
   const fileInfo = formatMissingSecretsFileInfo(secretsFilePaths);
   const lines = [`Missing secrets: ${missing.join(', ')}`];
   if (fileInfo) lines.push(fileInfo.trim());
@@ -138,6 +169,9 @@ function buildMissingSecretsErrorMessage(opts) {
     if (templateLine) lines.push(`Env-template-line: ${ref}|${templateLine}`);
   }
   if (appName) lines.push(`App-name: ${appName}`);
+  for (const hint of buildStrictScopedKeyHints(missing, scopedKv)) {
+    lines.push(hint);
+  }
   if (hasStaleOAuthTemplatePaths(missing) && appName) {
     lines.push(`Stale-template-hint: oauth-leftover | repair ${appName}`);
   }