@aifabrix/builder 2.57.0 → 2.58.0

package/lib/core/config-attach-extensions.js

@@ -1,5 +1,5 @@
 /**
- * Attach token, path, format, and scoped-resources helpers to config exports.
+ * Attach token, path, format, scoped-resources, and registry helpers to config exports.
  *
  * @fileoverview Keeps lib/core/config.js under max-lines
  * @author AI Fabrix Team
@@ -42,6 +42,9 @@ function attachConfigExtensions(exportsObj, deps) {
   const { createScopedResourcesPreferenceFunctions } = require('../utils/config-scoped-resources-preference');
   Object.assign(exportsObj, createScopedResourcesPreferenceFunctions(getConfig, saveConfig));
 
+  const { createRegistryPreferenceFunctions } = require('../utils/config-registry-preference');
+  Object.assign(exportsObj, createRegistryPreferenceFunctions(getConfig, saveConfig));
+
   const { createSecretsPathFunctions } = require('../utils/config-secrets-path');
   Object.assign(exportsObj, createSecretsPathFunctions(getConfig, saveConfig));
 }

package/lib/deployment/installation/azure-infra-stage.js

@@ -2,8 +2,9 @@
 
 /**
  * @fileoverview AZURE `--stage infra`: validates the workspace, resolves ACR and secrets, deploys
- * the workspace Marketplace template snapshot, verifies managed-identity image pull and that both
- * applications started, and records outputs. Mori registration and tenant activation stay with Miso.
+ * the workspace Marketplace template snapshot, verifies image pull (managed identity or registry
+ * credentials) and that both applications started, and records outputs. Mori registration and
+ * tenant activation stay with Miso. Registry credentials are never written to the workspace.
  */
 
 // Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
@@ -12,7 +13,7 @@ const os = require('os');
 const path = require('path');
 const marketplace = require('../marketplace-environment');
 const { normalizePreset } = require('../environment-config');
-const { normalizeLicenseEdition, ONBOARDING_MODES } = require('./infra-catalog');
+const { normalizeLicenseEdition, normalizeAzureLocation, ONBOARDING_MODES } = require('./infra-catalog');
 const { materializeWorkspace, saveInfra } = require('./workspace');
 const { missingRequiredFields } = require('./infra-manifest');
 const { buildArmParameters, applyAllowMyIp } = require('./infra-projection');
@@ -21,6 +22,7 @@ const { mergeWorkspaceEnv } = require('./workspace-env');
 const { resolvePublicIpv4 } = require('./public-ip');
 const preflight = require('./azure-preflight');
 const readiness = require('./azure-readiness');
+const registryAuth = require('./registry-auth-mode');
 
 const INFRA_SECRETS = Object.freeze(['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY']);
 
@@ -111,18 +113,41 @@ async function verifyAndRecordReadiness(workspace, doc, deps) {
   return controllerUrl;
 }
 
+function applyLocation(doc, input) {
+  if (input.location === undefined) return;
+  doc.parameters.location = { ...doc.parameters.location, value: normalizeAzureLocation(input.location), source: 'cli' };
+}
+
+async function resolvePullAuth(doc, acr, deps, az) {
+  const loadRegistryCredentials = deps.loadRegistryCredentials ||
+    require('../../utils/registry-credentials').loadRegistryCredentials;
+  const resolved = await registryAuth.resolveRegistryAuth(doc, acr, az, {
+    loadRegistryCredentials,
+    resolveAcrAdminCredentials: preflight.resolveAcrAdminCredentials
+  });
+  registryAuth.applyEffectiveAcrAuth(doc, resolved.mode);
+  return resolved.credentials;
+}
+
 async function prepareInfra(workspace, input, deps, az) {
   const { doc, templateHash } = materializeWorkspace(workspace, input, deps);
+  applyLocation(doc, input);
   const missing = missingRequiredFields(doc);
-  if (missing.length > 0) throw missingInputError(workspace.paths.infra, missing);
+  if (missing.length > 0) {
+    if (input.location !== undefined) saveInfra(workspace, doc);
+    throw missingInputError(workspace.paths.infra, missing);
+  }
+  registryAuth.applyRequestedAcrAuth(doc, input);
   preflight.assertActiveAccount(doc, az);
   const acr = preflight.resolveAcr(doc, az);
-  preflight.assertDeploymentAuthority(doc, acr, az);
   doc.parameters.acrLoginServer.value = acr.loginServer;
   doc.parameters.acrResourceId.value = acr.id;
+  // Local pair first (a partial pair fails closed); Azure admin lookup only for explicit credentials.
+  const registryCredentials = await resolvePullAuth(doc, acr, deps, az);
+  preflight.assertDeploymentAuthority(doc, acr, az);
   await applyAccessOptions(doc, input, deps);
   saveInfra(workspace, doc);
-  return { doc, templateHash, acr };
+  return { doc, templateHash, acr, registryCredentials };
 }
 
 function deployWithStatus(workspace, doc, context) {
@@ -141,17 +166,23 @@ function deployWithStatus(workspace, doc, context) {
  * Runs the AZURE infra stage.
  * @param {Object} workspace - Opened workspace
  * @param {Object} input - Validated stage input
- * @param {Object} [deps] - Injected dependencies (az, probe, resolvePublicIpv4, secretsApi, now, templatePath)
+ * @param {Object} [deps] - Injected dependencies (az, probe, resolvePublicIpv4, secretsApi, now, templatePath,
+ *   loadRegistryCredentials)
  * @returns {Promise<{ doc: Object, controllerUrl: string, activationUrl: string }>}
  */
 async function runAzureInfraStage(workspace, input, deps = {}) {
   const context = { az: deps.az || marketplace.runAz, now: deps.now || (() => new Date()), probe: deps.probe };
-  const { doc, templateHash, acr } = await prepareInfra(workspace, input, deps, context.az);
+  const { doc, templateHash, acr, registryCredentials } = await prepareInfra(workspace, input, deps, context.az);
   const env = await materializeWorkspaceSecrets({
     vendor: 'AZURE', envPath: workspace.paths.env, root: workspace.root, names: INFRA_SECRETS, secretsApi: deps.secretsApi
   });
-  const record = deployWithStatus(workspace, doc, { env, acr, templateHash, az: context.az });
+  const record = deployWithStatus(workspace, doc, {
+    env, acr, templateHash, az: context.az, registryCredentials
+  });
   recordDeployment(doc, record, context.now);
+  // Never persist registry credentials in the workspace manifest.
+  doc.parameters.acrAdminUsername = { ...doc.parameters.acrAdminUsername, value: '', source: 'managedIdentityMode' };
+  doc.parameters.acrAdminPassword = { ...doc.parameters.acrAdminPassword, value: '', source: 'managedIdentityMode' };
   saveInfra(workspace, doc);
   const controllerUrl = await verifyAndRecordReadiness(workspace, doc, context);
   return { doc, controllerUrl, activationUrl: doc.tenantActivation.url.value };

package/lib/deployment/installation/azure-preflight.js

@@ -3,8 +3,8 @@
 /**
  * @fileoverview AZURE infra preflight before any Azure mutation: active account equals the
  * workspace subscription/tenant, `acrName` resolves inside that subscription, and the caller can
- * create deployments, role assignments and the registry AcrPull grant. Uses only the operator's Azure CLI session; no tokens
- * are stored.
+ * create deployments. Managed-identity mode also requires role-assignment and AcrPull authority;
+ * password mode fetches ACR admin credentials instead. Uses only the operator's Azure CLI session.
  */
 
 const ROLE_ASSIGNMENT_WRITE = 'Microsoft.Authorization/roleAssignments/write';
@@ -19,6 +19,14 @@ function parseJson(text, label) {
   }
 }
 
+/**
+ * @param {Object} doc - Infra manifest
+ * @returns {boolean} True when image pull uses registry username/password (effective mode)
+ */
+function isAdminAcrAuth(doc) {
+  return doc.acrAuth?.effective === 'credentials';
+}
+
 /**
  * @param {Object} doc - Infra manifest
  * @param {Function} az - Azure CLI runner
@@ -41,7 +49,7 @@ function assertActiveAccount(doc, az) {
  * Resolves `acrName` to its resource ID and login server within the workspace subscription.
  * @param {Object} doc - Infra manifest
  * @param {Function} az - Azure CLI runner
- * @returns {{ id: string, loginServer: string }}
+ * @returns {{ id: string, loginServer: string, adminUserEnabled: boolean }}
  */
 function resolveAcr(doc, az) {
   const subscription = String(doc.subscriptionId.value);
@@ -54,7 +62,35 @@ function resolveAcr(doc, az) {
   if (!acr.id.toLowerCase().startsWith(`/subscriptions/${subscription.toLowerCase()}/`)) {
     throw new Error(`Registry ${doc.acrName.value} is outside the workspace subscription; use a registry in ${subscription}`);
   }
-  return { id: acr.id, loginServer: acr.loginServer };
+  return { id: acr.id, loginServer: acr.loginServer, adminUserEnabled: acr.adminUserEnabled === true };
+}
+
+/**
+ * Loads ACR admin username/password for password registry auth. Never persists the password.
+ * @param {Object} doc - Infra manifest
+ * @param {{ adminUserEnabled?: boolean }} acr - Resolved registry metadata
+ * @param {Function} az - Azure CLI runner
+ * @returns {{ username: string, password: string }}
+ */
+function resolveAcrAdminCredentials(doc, acr, az) {
+  if (acr.adminUserEnabled !== true) {
+    throw new Error(
+      `Registry ${doc.acrName.value} does not have the admin user enabled; enable admin user on the ACR ` +
+      'or save a local pair with "aifabrix dev set-registry"'
+    );
+  }
+  const creds = parseJson(az([
+    'acr', 'credential', 'show', '--name', doc.acrName.value,
+    '--subscription', String(doc.subscriptionId.value), '--output', 'json'
+  ]), 'registry credentials');
+  const username = typeof creds.username === 'string' ? creds.username : '';
+  const password = Array.isArray(creds.passwords)
+    ? (creds.passwords.find(item => item && item.value)?.value || '')
+    : '';
+  if (!username || !password) {
+    throw new Error(`Registry ${doc.acrName.value} did not return admin credentials; check ACR admin user access`);
+  }
+  return { username, password };
 }
 
 function actionMatches(pattern, action) {
@@ -84,19 +120,28 @@ function hasPermission(az, scope, action) {
  * @param {Object} doc - Infra manifest
  * @param {{ id: string }} acr - Resolved registry
  * @param {Function} az - Azure CLI runner
- * @throws {Error} When deployment, role-assignment or AcrPull grant authority is missing
+ * @throws {Error} When deployment or (mi) role-assignment authority is missing
  */
 function assertDeploymentAuthority(doc, acr, az) {
   const subscriptionScope = `/subscriptions/${doc.subscriptionId.value}`;
   if (!hasPermission(az, subscriptionScope, DEPLOYMENT_WRITE)) {
     throw new Error(`The signed-in Azure account cannot create deployments in subscription ${doc.subscriptionId.value}`);
   }
+  if (isAdminAcrAuth(doc)) return;
   if (doc.parameters.deployRoleAssignments.value !== false && !hasPermission(az, subscriptionScope, ROLE_ASSIGNMENT_WRITE)) {
-    throw new Error(`The signed-in Azure account cannot create role assignments in subscription ${doc.subscriptionId.value}; ask for Owner or User Access Administrator, or set parameters.deployRoleAssignments.value to false when roles already exist`);
+    throw new Error(`The signed-in Azure account cannot create role assignments in subscription ${doc.subscriptionId.value}; ask for Owner or User Access Administrator, or set parameters.deployRoleAssignments.value to false when roles already exist, or use --acr-auth credentials with a pair saved by "aifabrix dev set-registry"`);
   }
   if (!hasPermission(az, acr.id, ROLE_ASSIGNMENT_WRITE)) {
-    throw new Error(`The signed-in Azure account cannot assign AcrPull on registry ${doc.acrName.value}; ask for Owner or User Access Administrator on that registry`);
+    throw new Error(`The signed-in Azure account cannot assign AcrPull on registry ${doc.acrName.value}; ask for Owner or User Access Administrator on that registry, or use --acr-auth credentials with a pair saved by "aifabrix dev set-registry"`);
   }
 }
 
-module.exports = { assertActiveAccount, resolveAcr, hasPermission, actionMatches, assertDeploymentAuthority };
+module.exports = {
+  assertActiveAccount,
+  resolveAcr,
+  resolveAcrAdminCredentials,
+  isAdminAcrAuth,
+  hasPermission,
+  actionMatches,
+  assertDeploymentAuthority
+};

package/lib/deployment/installation/azure-readiness.js

@@ -1,11 +1,15 @@
 'use strict';
 
 /**
- * @fileoverview AZURE infra readiness evidence: both web app identities hold AcrPull on the
- * workspace registry with managed-identity image pull enabled, and Miso and Keycloak answer over
- * HTTPS. Local `az acr login` success is never treated as readiness.
+ * @fileoverview AZURE infra readiness evidence: image pull authorization for both web apps, then
+ * HTTPS probes. Managed-identity mode requires AcrPull + acrUseManagedIdentityCreds; password mode
+ * requires registry credentials on the web app and acrUseManagedIdentityCreds false. Both modes
+ * then require the applications to start (proof that the image was pulled). Local
+ * `az acr login` success is never treated as readiness.
  */
 
+const { isAdminAcrAuth } = require('./azure-preflight');
+
 const APP_OUTPUTS = Object.freeze([
   { name: 'webAppName', label: 'Miso' },
   { name: 'keycloakWebAppName', label: 'Keycloak' }
@@ -15,7 +19,7 @@ function scoped(args, doc) {
   return [...args, '--subscription', doc.subscriptionId.value];
 }
 
-function verifyAppImagePull(doc, app, acrId, az) {
+function verifyManagedIdentityPull(doc, app, acrId, az) {
   const group = doc.resourceGroup.value;
   const principalId = az(scoped([
     'webapp', 'identity', 'show', '--resource-group', group, '--name', app.value,
@@ -38,8 +42,34 @@ function verifyAppImagePull(doc, app, acrId, az) {
   }
 }
 
+function verifyPasswordPull(doc, app, az) {
+  const group = doc.resourceGroup.value;
+  const managedPull = az(scoped([
+    'webapp', 'config', 'show', '--resource-group', group, '--name', app.value,
+    '--query', 'acrUseManagedIdentityCreds', '--output', 'tsv'
+  ], doc));
+  if (String(managedPull).toLowerCase() === 'true') {
+    throw new Error(`${app.label} web app still uses managed-identity image pull; expected registry username/password`);
+  }
+  const username = az(scoped([
+    'webapp', 'config', 'appsettings', 'list', '--resource-group', group, '--name', app.value,
+    '--query', '[?name==\'DOCKER_REGISTRY_SERVER_USERNAME\'].value | [0]', '--output', 'tsv'
+  ], doc));
+  if (!username) {
+    throw new Error(`${app.label} web app is missing DOCKER_REGISTRY_SERVER_USERNAME for password registry auth`);
+  }
+}
+
+function verifyAppImagePull(doc, app, acrId, az) {
+  if (isAdminAcrAuth(doc)) {
+    verifyPasswordPull(doc, app, az);
+    return;
+  }
+  verifyManagedIdentityPull(doc, app, acrId, az);
+}
+
 /**
- * Verifies persistent managed-identity image-pull authorization for both web apps.
+ * Verifies image-pull authorization for both web apps per acrAuth mode.
  * @param {Object} doc - Infra manifest with outputs
  * @param {Function} az - Azure CLI runner
  */

package/lib/deployment/installation/infra-catalog.js

@@ -20,6 +20,9 @@ const LICENSE_EDITIONS = Object.freeze(['COMMUNITY', 'STANDARD', 'ENTERPRISE']);
 const DEFAULT_LICENSE_EDITION = 'COMMUNITY';
 const ONBOARDING_MODES = Object.freeze(['saasDirect', 'customerOwned']);
 const DEFAULT_ONBOARDING_MODE = 'saasDirect';
+const ACR_AUTH_MODES = Object.freeze(['auto', 'mi', 'credentials']);
+const DEFAULT_ACR_AUTH = 'auto';
+const AZURE_LOCATION = /^[a-z0-9]{2,40}$/;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**
@@ -36,6 +39,45 @@ function normalizeLicenseEdition(value) {
   throw new Error(`License edition must be one of ${LICENSE_EDITIONS.join(', ')} or an Azure Marketplace subscription ID`);
 }
 
+/**
+ * Normalizes requested ACR image-pull auth: auto (default), mi, or credentials.
+ * `admin` (and its spellings) is a deprecated alias for `credentials`.
+ * @param {string} value - Raw value
+ * @returns {string} Canonical mode
+ */
+function normalizeAcrAuth(value) {
+  const raw = String(value ?? '').trim();
+  const aliases = {
+    auto: 'auto',
+    mi: 'mi',
+    'managed-identity': 'mi',
+    managedidentity: 'mi',
+    credentials: 'credentials',
+    admin: 'credentials',
+    adminuser: 'credentials',
+    'admin-user': 'credentials',
+    password: 'credentials'
+  };
+  const mode = aliases[raw.toLowerCase()];
+  if (!mode) {
+    throw new Error(`ACR auth must be one of ${ACR_AUTH_MODES.join(', ')} (deprecated alias: admin = credentials)`);
+  }
+  return mode;
+}
+
+/**
+ * Validates an Azure region name (for example swedencentral).
+ * @param {string} value - Raw value
+ * @returns {string} Lower-case region
+ */
+function normalizeAzureLocation(value) {
+  const location = String(value ?? '').trim().toLowerCase();
+  if (!AZURE_LOCATION.test(location)) {
+    throw new Error(`--location must be an Azure region name such as swedencentral (letters and digits only); got "${value}"`);
+  }
+  return location;
+}
+
 const PARAMETER_CATALOG = Object.freeze({
   infrastructureNameOverride: { kind: 'file', source: 'user', description: 'Optional infrastructure-name override; empty uses generated naming.' },
   location: { kind: 'file', source: 'user', required: true, description: 'Azure region for shared infrastructure.' },
@@ -50,10 +92,10 @@ const PARAMETER_CATALOG = Object.freeze({
   keycloakVerifyAudience: { kind: 'file', source: 'templateDefault', description: 'Enable Keycloak audience verification.' },
   encryptionKey: { kind: 'secretEnv', env: 'ENCRYPTION_KEY', required: true, description: 'Application/data encryption key.' },
   acrLoginServer: { kind: 'acrLookup', field: 'loginServer', description: 'Resolved from acrName; not entered separately.' },
-  acrAdminUsername: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Unused: Azure web apps pull images with their managed identities.' },
-  acrAdminPassword: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Unused: Azure image pull never uses a registry password.' },
-  acrResourceId: { kind: 'acrLookup', field: 'id', description: 'Resolved from acrName; both web app identities receive AcrPull on it and the deployment fails if the grant fails.' },
-  deployRoleAssignments: { kind: 'file', source: 'templateDefault', description: 'Deploy required Azure role assignments.' },
+  acrAdminUsername: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Empty in the workspace; credential mode fills it only in the temporary ARM parameters file (never committed).' },
+  acrAdminPassword: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Empty in the workspace; credential mode fills it only in the temporary ARM parameters file (never committed).' },
+  acrResourceId: { kind: 'acrLookup', field: 'id', description: 'Resolved from acrName; mi mode grants AcrPull to both web app identities.' },
+  deployRoleAssignments: { kind: 'file', source: 'templateDefault', description: 'Deploy required Azure role assignments (false while credential image pull is in effect; restored for managed identity).' },
   moriBaseUrl: { kind: 'file', source: 'registration', required: true, description: 'Mori service base URL.' },
   moriCallbackApiKey: { kind: 'secretEnv', env: 'MORI_CALLBACK_API_KEY', required: true, description: 'Mori callback authentication key.' },
   entraCallbackStateSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
@@ -159,7 +201,11 @@ module.exports = {
   DEFAULT_LICENSE_EDITION,
   ONBOARDING_MODES,
   DEFAULT_ONBOARDING_MODE,
+  ACR_AUTH_MODES,
+  DEFAULT_ACR_AUTH,
   normalizeLicenseEdition,
+  normalizeAcrAuth,
+  normalizeAzureLocation,
   buildEnvTemplate,
   assertTemplateCoverage
 };

package/lib/deployment/installation/infra-manifest.js

@@ -8,9 +8,10 @@
 
 const crypto = require('crypto');
 const {
-  PARAMETER_CATALOG, OUTPUT_CATALOG, DEFAULT_LICENSE_EDITION, DEFAULT_ONBOARDING_MODE
+  PARAMETER_CATALOG, OUTPUT_CATALOG, DEFAULT_LICENSE_EDITION, DEFAULT_ONBOARDING_MODE, DEFAULT_ACR_AUTH
 } = require('./infra-catalog');
 
+const ACR_AUTH_DESCRIPTION = 'Image pull auth: auto (default; local dev set-registry pair for the ACR login server, else managed identity), mi (AcrPull), or credentials (local pair, then authorized ACR admin lookup). Credentials are never committed.';
 const INFRA_SCHEMA_VERSION = '2.0.0';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -46,12 +47,24 @@ function parameterEntry(name, template) {
   }
 }
 
+/** Sources written by Builder workflows that must survive regeneration. */
+const STICKY_SOURCES = Object.freeze(['cli', 'acrAuthCredentials', 'acrAuthAdmin']);
+
+function preservedState(previous) {
+  const kept = { value: previous.value };
+  if (STICKY_SOURCES.includes(previous.source)) kept.source = previous.source;
+  for (const key of ['restoreValue', 'restoreSource']) {
+    if (previous[key] !== undefined) kept[key] = previous[key];
+  }
+  return kept;
+}
+
 function buildParameters(template, existing = {}) {
   const parameters = {};
   for (const name of Object.keys(PARAMETER_CATALOG)) {
     const fresh = parameterEntry(name, template);
     const workflowOwned = ['fixed', 'deferred', 'secretEnv'].includes(PARAMETER_CATALOG[name].kind);
-    parameters[name] = existing[name] && !workflowOwned ? { ...fresh, value: existing[name].value } : fresh;
+    parameters[name] = existing[name] && !workflowOwned ? { ...fresh, ...preservedState(existing[name]) } : fresh;
   }
   return parameters;
 }
@@ -64,6 +77,7 @@ function buildOutputs(existing = {}) {
 function azureSections(template, existing) {
   return {
     acrName: existing.acrName || entry('', 'user', 'Required private ACR name. Builder resolves and persists its login server and resource ID using the authenticated Azure account.', { required: true }),
+    acrAuth: existing.acrAuth || entry(DEFAULT_ACR_AUTH, 'cliOrFile', ACR_AUTH_DESCRIPTION),
     allowMyIp: existing.allowMyIp || entry(false, 'cliOrFile', 'Default-off internal test access. When enabled, Builder resolves and audits one public IPv4 /32.', { resolvedCidr: null, resolvedAt: null, resolver: null }),
     preset: existing.preset || entry('s', 'cliOrFile', 'Shared infrastructure sizing preset.'),
     parameters: buildParameters(template, existing.parameters),
@@ -156,6 +170,7 @@ function missingRequiredFields(doc) {
 
 module.exports = {
   INFRA_SCHEMA_VERSION,
+  ACR_AUTH_DESCRIPTION,
   buildInfraDocument,
   missingRequiredFields
 };

package/lib/deployment/installation/infra-projection.js

@@ -3,12 +3,15 @@
 /**
  * @fileoverview Projects `environment-infra.json` plus resolved workspace secrets into standard
  * ARM deploymentParameters, and applies the default-off current-IP access option.
- * Deferred tenant-activation parameters are never projected.
+ * Deferred tenant-activation parameters are never projected. ACR admin credentials (password mode)
+ * are injected only into the temporary parameters file and never enter the input hash.
  */
 
 const { PARAMETER_CATALOG } = require('./infra-catalog');
 const { sha256 } = require('./workspace-files');
 
+const ARM_CREDENTIAL_PARAMS = Object.freeze(new Set(['acrAdminUsername', 'acrAdminPassword']));
+
 function projectParameter(name, doc, context) {
   const spec = PARAMETER_CATALOG[name];
   switch (spec.kind) {
@@ -27,6 +30,12 @@ function projectParameter(name, doc, context) {
     }
     return context.acr[spec.field];
   case 'fixed':
+    if (name === 'acrAdminUsername' && context.registryCredentials) {
+      return context.registryCredentials.username;
+    }
+    if (name === 'acrAdminPassword' && context.registryCredentials) {
+      return context.registryCredentials.password;
+    }
     return spec.value;
   default:
     return doc.parameters[name].value;
@@ -39,6 +48,7 @@ function projectParameter(name, doc, context) {
  * @param {Object} context - Resolution context
  * @param {Object.<string,string>} context.env - Resolved workspace .env values
  * @param {{ id: string, loginServer: string }} context.acr - Resolved registry
+ * @param {{ username: string, password: string }|null|undefined} context.registryCredentials - Credential-mode pull creds (never hashed)
  * @param {string} context.templateHash - SHA-256 of the deployed template
  * @returns {{ document: Object, inputHash: string }}
  */
@@ -49,9 +59,10 @@ function buildArmParameters(doc, context) {
     const value = projectParameter(name, doc, context);
     if (value === undefined) continue;
     parameters[name] = { value };
-    // Secrets never enter the hash.
-    if (PARAMETER_CATALOG[name].kind !== 'secretEnv') nonSecret[name] = value;
+    const catalog = PARAMETER_CATALOG[name];
+    if (catalog.kind !== 'secretEnv' && !ARM_CREDENTIAL_PARAMS.has(name)) nonSecret[name] = value;
   }
+  nonSecret.acrAuth = doc.acrAuth?.effective || doc.acrAuth?.value || 'auto';
   return {
     document: {
       $schema: 'https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#',

package/lib/deployment/installation/registry-auth-mode.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * @fileoverview Image-pull authentication for CLI-managed AZURE infra. The requested mode
+ * (`auto|mi|credentials`, deprecated `admin` = credentials) resolves to an effective `mi` or
+ * `credentials` mode. Credential values come from the primary user's `dev set-registry` pair for the
+ * resolved ACR login server, or (explicit credentials only) from an authorized ACR admin lookup.
+ * They live only in memory and in the temporary ARM parameters file.
+ */
+
+const { normalizeAcrAuth } = require('./infra-catalog');
+const { ACR_AUTH_DESCRIPTION } = require('./infra-manifest');
+
+const FORCED_ROLE_SOURCES = Object.freeze(['acrAuthCredentials', 'acrAuthAdmin']);
+
+/**
+ * Normalizes and records the requested mode (CLI wins over the workspace value).
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {Object} input - Stage input (`acrAuth` from CLI)
+ * @returns {string} Requested mode
+ */
+function applyRequestedAcrAuth(doc, input) {
+  const fromCli = input.acrAuth !== undefined;
+  const mode = normalizeAcrAuth(fromCli ? input.acrAuth : (doc.acrAuth?.value || 'auto'));
+  doc.acrAuth = {
+    ...(doc.acrAuth || {}),
+    value: mode,
+    source: fromCli ? 'cli' : (doc.acrAuth?.source || 'cliOrFile'),
+    description: ACR_AUTH_DESCRIPTION
+  };
+  return mode;
+}
+
+function localSetupHint(host) {
+  return `Run "aifabrix dev set-registry ${host} --username <username> --password-stdin", or use --acr-auth mi`;
+}
+
+async function resolveAzureFallback(doc, acr, az, fetchAdmin) {
+  try {
+    return fetchAdmin(doc, acr, az);
+  } catch (error) {
+    throw new Error(`No registry credentials are available for ${acr.loginServer}: ${error.message}. ${localSetupHint(acr.loginServer)}`);
+  }
+}
+
+/**
+ * Resolves the effective pull mode and ephemeral credentials. A partial local pair always fails.
+ * @param {Object} doc - Infra manifest with a normalized `acrAuth`
+ * @param {{ loginServer: string, adminUserEnabled?: boolean }} acr - Resolved registry
+ * @param {Function} az - Azure CLI runner
+ * @param {Object} deps - `loadRegistryCredentials(host)` and `resolveAcrAdminCredentials(doc, acr, az)`
+ * @returns {Promise<{ mode: 'mi'|'credentials', credentials: ({username: string, password: string}|null), source: string }>}
+ */
+async function resolveRegistryAuth(doc, acr, az, deps) {
+  const requested = normalizeAcrAuth(doc.acrAuth?.value || 'auto');
+  if (requested === 'mi') return { mode: 'mi', credentials: null, source: 'managedIdentity' };
+  const local = await deps.loadRegistryCredentials(acr.loginServer);
+  if (local) return { mode: 'credentials', credentials: local, source: 'localRegistryCredentials' };
+  if (requested === 'auto') return { mode: 'mi', credentials: null, source: 'managedIdentity' };
+  const azure = await resolveAzureFallback(doc, acr, az, deps.resolveAcrAdminCredentials);
+  return { mode: 'credentials', credentials: azure, source: 'acrAdminLookup' };
+}
+
+/**
+ * Records the effective mode and keeps role assignments consistent with it. Credential mode turns
+ * ARM role assignments off; returning to managed identity restores the value it replaced.
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {'mi'|'credentials'} mode - Effective mode
+ */
+function applyEffectiveAcrAuth(doc, mode) {
+  doc.acrAuth = { ...doc.acrAuth, effective: mode };
+  const roles = doc.parameters.deployRoleAssignments;
+  const forced = FORCED_ROLE_SOURCES.includes(roles.source);
+  if (mode === 'credentials') {
+    if (forced) return;
+    doc.parameters.deployRoleAssignments = {
+      ...roles, value: false, source: 'acrAuthCredentials', restoreValue: roles.value, restoreSource: roles.source
+    };
+    return;
+  }
+  if (!forced) return;
+  const { restoreValue, restoreSource, ...rest } = roles;
+  doc.parameters.deployRoleAssignments = {
+    ...rest,
+    value: restoreValue === undefined ? true : restoreValue,
+    source: restoreSource || 'templateDefault'
+  };
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @returns {boolean} True when the last resolved pull mode uses registry credentials
+ */
+function usesRegistryCredentials(doc) {
+  return doc.acrAuth?.effective === 'credentials';
+}
+
+module.exports = { applyRequestedAcrAuth, resolveRegistryAuth, applyEffectiveAcrAuth, usesRegistryCredentials };

package/lib/deployment/installation/stage-input.js

@@ -7,7 +7,7 @@
  */
 
 const path = require('path');
-const { normalizeLicenseEdition } = require('./infra-catalog');
+const { normalizeLicenseEdition, normalizeAcrAuth, normalizeAzureLocation } = require('./infra-catalog');
 
 const WORKSPACE_STAGES = Object.freeze(['register', 'infra', 'dev', 'tst', 'pro']);
 const ENVIRONMENT_STAGES = Object.freeze(['dev', 'tst', 'pro']);
@@ -102,11 +102,24 @@ function assertInfraOnlyOptions(stage, options) {
   if (options.allowMyIp && stage !== 'infra') {
     throw new Error('--allow-my-ip is supported only with --stage infra for AZURE installations');
   }
-  if (options.licenseEdition === undefined) return;
-  if (stage !== 'infra') {
-    throw new Error('--license-edition is supported only with --stage infra for AZURE installations');
+  if (options.licenseEdition !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--license-edition is supported only with --stage infra for AZURE installations');
+    }
+    normalizeLicenseEdition(options.licenseEdition);
+  }
+  if (options.acrAuth !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--acr-auth is supported only with --stage infra for AZURE installations');
+    }
+    normalizeAcrAuth(options.acrAuth);
+  }
+  if (options.location !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--location is supported only with --stage infra (later environments inherit the saved region)');
+    }
+    normalizeAzureLocation(options.location);
   }
-  normalizeLicenseEdition(options.licenseEdition);
 }
 
 function assertStageScopedOptions(stage, options) {
@@ -137,7 +150,7 @@ function assertStageScopedOptions(stage, options) {
  * @param {Object} options - Commander options
  * @param {string|undefined} persistedVendor - Vendor recorded in an existing workspace
  * @returns {{ resourceGroup: string, stage: string, vendor: string, allowMyIp: boolean, licenseEdition: string|undefined,
- *   preset: string|undefined, controllerUrl: string|undefined, misoApiKeyEnv: string|undefined }}
+ *   acrAuth: string|undefined, location: string|undefined, preset: string|undefined, controllerUrl: string|undefined, misoApiKeyEnv: string|undefined }}
  */
 function resolveStageInput(resourceGroupKey, options, persistedVendor) {
   const resourceGroup = validateResourceGroupKey(resourceGroupKey);
@@ -150,6 +163,8 @@ function resolveStageInput(resourceGroupKey, options, persistedVendor) {
     vendor,
     allowMyIp: options.allowMyIp === true,
     licenseEdition: options.licenseEdition,
+    acrAuth: options.acrAuth,
+    location: options.location,
     preset: options.preset,
     controllerUrl: options.controllerUrl,
     misoApiKeyEnv: options.misoApiKeyEnv

package/lib/generator/builders.js

@@ -41,16 +41,15 @@ function filterConfigurationByRegistryMode(configuration, _registryMode) {
   return Array.isArray(configuration) ? configuration : [];
 }
 
+/**
+ * Deployment image reference using the shared registry precedence
+ * (installation `registry` in config.yaml, then manifest `image.registry`).
+ * @param {Object} variables - Application variables
+ * @returns {string}
+ */
 function buildImageReference(variables) {
-  const imageName = variables.image?.name || variables.app?.key || 'app';
-  const registry = variables.image?.registry;
-  const tag = variables.image?.tag || 'latest';
-
-  if (registry) {
-    return `${registry}/${imageName}:${tag}`;
-  }
-
-  return `${imageName}:${tag}`;
+  const { buildManifestImageReference } = require('../utils/resolve-docker-image-ref');
+  return buildManifestImageReference(variables, 'app');
 }
 
 /**