@aifabrix/builder 2.57.0 → 2.59.0

package/lib/datasource/datasource-validate-summary.js

@@ -74,17 +74,20 @@ function summarizeSyncLine(sync) {
   if (!sync || typeof sync !== 'object') {
     return 'Not configured';
   }
-  const parts = [];
+  const disabled = sync.enabled === false;
+  const parts = [disabled ? 'disabled' : sync.enabled === true ? 'enabled' : 'enabled (legacy default)'];
+  if (sync.schedule) {
+    parts.push(`${disabled ? 'retained schedule' : 'scheduled'} ${JSON.stringify(sync.schedule)}`);
+  } else {
+    parts.push('manual-only');
+  }
   if (sync.mode) {
     parts.push(String(sync.mode));
   }
   if (sync.batchSize !== undefined && sync.batchSize !== null) {
     parts.push(`batch size ${sync.batchSize}`);
   }
-  if (sync.schedule) {
-    parts.push(`schedule ${JSON.stringify(sync.schedule)}`);
-  }
-  return parts.length ? parts.join(', ') : 'Present';
+  return parts.join(', ');
 }
 
 /**

package/lib/datasource/sync-defaults.js

@@ -0,0 +1,53 @@
+/**
+ * Datasource synchronization defaults for newly authored sync blocks.
+ * @fileoverview Keeps default creation separate from preservation decisions.
+ */
+
+'use strict';
+
+const DEFAULT_DATASOURCE_SYNC = Object.freeze({
+  enabled: true,
+  mode: 'pull',
+  schedule: '@monthly',
+  batchSize: 500
+});
+
+const DATASOURCE_SYNC_MODES = new Set(['pull', 'push', 'bidirectional']);
+
+/**
+ * @param {Record<string, unknown>} [overrides]
+ * @returns {Record<string, unknown>}
+ */
+function createDefaultDatasourceSync(overrides = {}) {
+  return { ...DEFAULT_DATASOURCE_SYNC, ...overrides };
+}
+
+/**
+ * Resolve sync for a newly materialized BID datasource.
+ * An explicit datasource block is preserved exactly, including no schedule.
+ * @param {Record<string, unknown>} datasource
+ * @param {Record<string, unknown>} bidSync
+ * @returns {unknown}
+ */
+function resolveAuthoredDatasourceSync(datasource, bidSync) {
+  if (Object.prototype.hasOwnProperty.call(datasource, 'sync')) {
+    const explicit = datasource.sync;
+    return explicit && typeof explicit === 'object' ? { ...explicit } : explicit;
+  }
+  const overrides = {};
+  for (const key of ['enabled', 'schedule', 'batchSize']) {
+    if (Object.prototype.hasOwnProperty.call(bidSync, key)) {
+      overrides[key] = bidSync[key];
+    }
+  }
+  if (DATASOURCE_SYNC_MODES.has(String(bidSync.mode))) {
+    overrides.mode = bidSync.mode;
+  }
+  return createDefaultDatasourceSync(overrides);
+}
+
+module.exports = {
+  DEFAULT_DATASOURCE_SYNC,
+  createDefaultDatasourceSync,
+  resolveAuthoredDatasourceSync
+};

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']);
 
@@ -48,6 +50,16 @@ async function applyAccessOptions(doc, input, deps) {
   if (input.preset !== undefined) {
     doc.preset = { ...doc.preset, value: normalizePreset(input.preset), source: 'cli' };
   }
+  // The template sizes compute and PostgreSQL from capacityProfile, and the workspace already
+  // records a preset with the same values. Deriving one from the other keeps a single source:
+  // an installation cannot end up recording preset 'm' while deploying 's'.
+  if (doc.parameters.capacityProfile) {
+    doc.parameters.capacityProfile = {
+      ...doc.parameters.capacityProfile,
+      value: normalizePreset(doc.preset.value),
+      source: 'workspacePreset'
+    };
+  }
   applyLicenseOptions(doc, input);
   const enabled = input.allowMyIp || doc.allowMyIp.value === true;
   if (!enabled) {
@@ -111,18 +123,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 +176,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,39 @@ 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}`);
   }
+  // Checked separately, because they are different permissions on different resources.
+  //
+  // Credential mode used to return here and skip both. That was wrong for the first one: the
+  // installation still needs Contributor granted in the resource group it is creating, and
+  // skipping the check hid the fact that the grant was being skipped too. The controller then
+  // could not create anything, and the failure surfaced three layers away as "Environment 'dev'
+  // has no recorded placement".
   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`);
   }
+  // The AcrPull grant reaches into the registry's own resource group, which a customer
+  // installation cannot touch at all. Credential mode does not request it, so do not require
+  // permission for it.
+  if (isAdminAcrAuth(doc)) return;
+  if (doc.parameters.deployRegistryRoleAssignment?.value === false) return;
   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
  */
@@ -52,14 +82,36 @@ function verifyRuntimeImagePull(doc, az) {
   }
 }
 
+/**
+ * Attempts allowed for Miso readiness, at 10-second intervals.
+ *
+ * Miso runs first-time onboarding inside startup, and on Azure that onboarding is normally
+ * interrupted once — the template applies post-Key-Vault app settings and restarts the site — so
+ * the retry runs too. A clean installation was measured taking 720 seconds to pass its warm-up
+ * probe, and ce-10 was failed at 300 by the old default of 30 attempts.
+ *
+ * Reporting `readiness did not pass` for a healthy installation is worse than waiting: it leaves
+ * `controllerUrl` unrecorded, and `--stage dev` then refuses with "Shared infrastructure is not
+ * deployed for this workspace" on infrastructure that is deployed and serving.
+ *
+ * 180 attempts is 30 minutes, matching WEBSITES_CONTAINER_START_TIME_LIMIT. Keycloak keeps the
+ * shorter default: it does not run onboarding, and it is already up by the time Miso answers.
+ */
+const MISO_READINESS_ATTEMPTS = 180;
+
 /**
  * Waits for Miso and Keycloak to start after pulling their images.
  * @param {Object} doc - Infra manifest with outputs
- * @param {Function} probe - probeHttps(baseUrl, path, label)
+ * @param {Function} probe - probeHttps(baseUrl, path, label, attempts)
  * @returns {Promise<void>}
  */
 async function waitForApplications(doc, probe) {
-  await probe(doc.outputs.webAppUrl.value, '/api/v1/health/readiness', 'Miso');
+  await probe(
+    doc.outputs.webAppUrl.value,
+    '/api/v1/health/readiness',
+    'Miso',
+    MISO_READINESS_ATTEMPTS
+  );
   const realmUrl = doc.outputs.keycloakRealmUrl.value;
   if (typeof realmUrl !== 'string' || !realmUrl.startsWith('https://')) {
     throw new Error('ARM output keycloakRealmUrl is not a valid HTTPS URL');

package/lib/deployment/installation/environment-auth.js

@@ -2,8 +2,8 @@
 
 /**
  * @fileoverview Controller URL and Bearer authentication for dev/tst/pro workspace stages.
- * Order: explicit `--miso-api-key-env` selector, `MISO_API_KEY` from the process, the workspace
- * `.env`/secret system, then an existing Controller login. Key values never appear in output.
+ * Order: exclusive explicit selector, otherwise Controller login, process key, then
+ * workspace `.env`/secret system. Key values never appear in output.
  */
 
 const { validateControllerUrl } = require('../../utils/deployment-validation');
@@ -40,37 +40,77 @@ async function workspaceApiKey(workspace, secretsApi) {
 }
 
 /**
- * Resolves Bearer authentication for Miso environment calls.
- * @param {Object} params - Inputs
- * @param {Object} params.workspace - Opened workspace
- * @param {string} params.controllerUrl - Controller URL
- * @param {string} [params.keyEnvName] - Explicit environment-variable selector
- * @param {Object} [params.deps] - Injected getDeviceToken/secretsApi/env
- * @returns {Promise<{ authConfig: Object, source: string }>}
+ * Lazily yield credentials without resolving lower-priority secrets unnecessarily.
+ * @param {Object} params - Workspace, controller URL, selector and dependencies
+ * @yields {Object} Authentication candidate
  */
-async function resolveEnvironmentAuth({ workspace, controllerUrl, keyEnvName, deps = {} }) {
+async function* environmentAuthCandidates({ workspace, controllerUrl, keyEnvName, deps = {} }) {
   const processEnv = deps.env || process.env;
   if (keyEnvName) {
     const value = processEnv[keyEnvName];
     if (!value) throw new Error(`Environment variable ${keyEnvName} selected by --miso-api-key-env is not set`);
-    return { authConfig: { type: 'bearer', token: value }, source: 'selector' };
+    yield { authConfig: { type: 'bearer', token: value }, source: 'selector' };
+    return;
+  }
+  const getDeviceToken = deps.getDeviceToken || require('../../utils/token-manager').getOrRefreshDeviceToken;
+  const device = await getDeviceToken(controllerUrl);
+  if (device?.token) {
+    yield { authConfig: { type: 'bearer', token: device.token, controller: controllerUrl }, source: 'login' };
   }
   if (processEnv.MISO_API_KEY) {
-    return { authConfig: { type: 'bearer', token: processEnv.MISO_API_KEY }, source: 'process' };
+    yield { authConfig: { type: 'bearer', token: processEnv.MISO_API_KEY }, source: 'process' };
   }
   const fromWorkspace = await workspaceApiKey(workspace, deps.secretsApi);
-  if (fromWorkspace) {
-    return { authConfig: { type: 'bearer', token: fromWorkspace }, source: 'workspace' };
+  if (fromWorkspace) yield { authConfig: { type: 'bearer', token: fromWorkspace }, source: 'workspace' };
+}
+
+/**
+ * Normalize preflight failures without exposing server-echoed credentials.
+ * @param {Function} validateAuth - Initial read-only request
+ * @param {Object} auth - Candidate auth config
+ * @returns {Promise<Object>} API response (only 401 permits fallback)
+ */
+async function validateCandidate(validateAuth, auth) {
+  let response;
+  try {
+    response = await validateAuth(auth);
+  } catch (error) {
+    const status = error?.status ?? error?.statusCode;
+    response = { success: false, status: Number.isInteger(status) ? status : undefined };
   }
-  const getDeviceToken = deps.getDeviceToken || require('../../utils/token-manager').getOrRefreshDeviceToken;
-  const device = await getDeviceToken(controllerUrl);
-  if (device && device.token) {
-    return { authConfig: { type: 'bearer', token: device.token, controller: controllerUrl }, source: 'login' };
+  if (response?.success === true || response?.status === 401) return response;
+  const status = Number.isInteger(response?.status) ? response.status : undefined;
+  const error = new Error(`Miso tenant status failed${status ? ` (HTTP ${status})` : ''}. Check Controller connectivity and permissions.`);
+  error.status = status;
+  throw error;
+}
+
+/**
+ * Resolve auth, optionally selecting it through the initial read-only preflight.
+ * @param {Object} params - Workspace, controllerUrl, keyEnvName and injected deps
+ * @param {Function} [params.validateAuth] - Read-only request returning an API response
+ * @returns {Promise<Object>} Selected auth/source and optional validationResponse
+ */
+async function resolveEnvironmentAuth(params) {
+  const seen = new Set();
+  for await (const candidate of environmentAuthCandidates(params)) {
+    if (seen.has(candidate.authConfig.token)) continue;
+    seen.add(candidate.authConfig.token);
+    if (!params.validateAuth) return candidate;
+    const response = await validateCandidate(params.validateAuth, candidate.authConfig);
+    if (response.success === true) return { ...candidate, validationResponse: response };
+    if (candidate.source === 'selector') {
+      const error = new Error('Explicit Controller key rejected (HTTP 401). Check --miso-api-key-env; no other credential was tried.');
+      error.status = 401;
+      throw error;
+    }
   }
-  throw new Error(
-    `No Controller authentication for ${controllerUrl}. Run "aifabrix login -c ${controllerUrl}", ` +
+  const error = new Error(
+    `No Controller authentication for ${params.controllerUrl}. Run "aifabrix login -c ${params.controllerUrl}", ` +
     'or set MISO_API_KEY (or --miso-api-key-env <NAME>) to a temporary installation key.'
   );
+  error.status = 401;
+  throw error;
 }
 
 module.exports = { resolveControllerUrl, resolveEnvironmentAuth };

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

@@ -14,6 +14,9 @@ const { buildEnvironmentDocument, buildMisoRequests, refreshVariableCatalog } =
 const { readWorkspaceEnv, removeWorkspaceEnvKey } = require('./workspace-env');
 const { resolveControllerUrl, resolveEnvironmentAuth } = require('./environment-auth');
 
+const logger = require('../../utils/logger');
+const { metadata } = require('../../utils/cli-test-layout-chalk');
+
 const FAILED_STATES = Object.freeze(['failed', 'error', 'cancelled']);
 
 function defaultApi() {
@@ -34,8 +37,7 @@ function apiFailure(step, response) {
   return error;
 }
 
-async function assertTenantActive(ctx) {
-  const response = await ctx.api.getTenantStatus(ctx.controllerUrl, ctx.auth);
+async function assertTenantActive(ctx, response) {
   if (!response.success) throw apiFailure('tenant status', response);
   const status = String(payload(response)?.status || 'UNKNOWN').toUpperCase();
   const recorded = ['PENDING', 'ACTIVE', 'INACTIVE'].includes(status) ? status.toLowerCase() : 'unknown';
@@ -169,11 +171,13 @@ async function runEnvironmentStage(workspace, input, deps = {}) {
   const { envDoc, requests } = prepareEnvironmentDocument(ctx, input, env);
   ctx.controllerUrl = resolveControllerUrl({ envDoc, infra: ctx.infra, env, override: input.controllerUrl });
   saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
-  const { authConfig, source } = await resolveEnvironmentAuth({
-    workspace, controllerUrl: ctx.controllerUrl, keyEnvName: input.misoApiKeyEnv, deps: { ...deps, env: ctx.processEnv }
+  const { authConfig, source, validationResponse } = await resolveEnvironmentAuth({
+    workspace, controllerUrl: ctx.controllerUrl, keyEnvName: input.misoApiKeyEnv, deps: { ...deps, env: ctx.processEnv },
+    validateAuth: auth => ctx.api.getTenantStatus(ctx.controllerUrl, auth)
   });
   ctx.auth = authConfig;
-  await assertTenantActive(ctx);
+  await assertTenantActive(ctx, validationResponse);
+  logger.log(metadata(`Controller authentication source: ${source}`));
   const change = await createOrUpdate(ctx, requests);
   await validateRequest(ctx, requests.deploy);
   const { deploymentId, resumed } = await submitDeployment(ctx, requests.deploy);