@aifabrix/builder 2.55.2 → 2.57.0

package/lib/deployment/deploy-poll-ui.js

@@ -23,7 +23,10 @@ function shouldUseDeployPollSpinner() {
  * @returns {{ onPollProgress: Function, finish: () => void }}
  */
 function createDeployPollHandlers(maxAttempts, options = {}) {
+  void maxAttempts;
   const silent = options && options.silent === true;
+  const startedAt = Date.now();
+  const elapsedMs = () => Date.now() - startedAt;
   const noop = () => {};
   if (silent) {
     return {
@@ -49,11 +52,11 @@ function createDeployPollHandlers(maxAttempts, options = {}) {
       setText(text) {
         ensureSpinner(text);
       },
-      onPollProgress: (deploymentData, attempt, maxA) => {
-        ensureSpinner(buildDeployPollSpinnerText(deploymentData, attempt, maxA));
+      onPollProgress: (deploymentData) => {
+        ensureSpinner(buildDeployPollSpinnerText(deploymentData, elapsedMs()));
       },
-      onPollWait: (attempt, maxA) => {
-        ensureSpinner(buildDeployPollWaitText(attempt, maxA));
+      onPollWait: () => {
+        ensureSpinner(buildDeployPollWaitText(elapsedMs()));
       },
       finish: () => {
         if (spinner) {
@@ -64,13 +67,14 @@ function createDeployPollHandlers(maxAttempts, options = {}) {
   }
   return {
     setText: noop,
-    onPollProgress: (deploymentData, attempt, maxA) => {
+    onPollProgress: (deploymentData) => {
       const status = deploymentData?.status ?? 'pending';
       const progress =
         deploymentData && Number.isFinite(Number(deploymentData.progress))
           ? Number(deploymentData.progress)
           : 0;
-      logger.log(chalk.gray(`Status: ${status} (${progress}%) (attempt ${attempt + 1}/${maxA})`));
+      const elapsedSeconds = Math.max(0, Math.floor(elapsedMs() / 1000));
+      logger.log(chalk.gray(`Status: ${status} (${progress}%) — ${elapsedSeconds}s elapsed`));
     },
     onPollWait: noop,
     finish: noop
@@ -79,12 +83,12 @@ function createDeployPollHandlers(maxAttempts, options = {}) {
 
 /**
  * Plain progress while awaiting the next status poll (HTTP in flight).
- * @param {number} attempt
- * @param {number} maxAttempts
+ * @param {number} elapsedMs
  * @returns {string}
  */
-function buildDeployPollWaitText(attempt, maxAttempts) {
-  return `Deploying application... Checking status (attempt ${attempt + 1}/${maxAttempts})`;
+function buildDeployPollWaitText(elapsedMs) {
+  const elapsedSeconds = Math.max(0, Math.floor(Number(elapsedMs || 0) / 1000));
+  return `Deploying application — ${elapsedSeconds}s elapsed`;
 }
 
 /**

package/lib/deployment/deployer-status.js

@@ -89,14 +89,14 @@ function logDeploymentProgress(deploymentData, attempt, maxAttempts) {
 /**
  * Single-line ora text for deploy polling (updates in place; same style as guided infra spinners).
  * @param {Object|null|undefined} deploymentData - Latest deployment payload (optional before first response)
- * @param {number} attempt - Zero-based attempt index
- * @param {number} maxAttempts - Max polling attempts
+ * @param {number} elapsedMs - Time elapsed since deployment polling began
  * @returns {string}
  */
-function buildDeployPollSpinnerText(deploymentData, attempt, maxAttempts) {
+function buildDeployPollSpinnerText(deploymentData, elapsedMs) {
   const status = deploymentData?.status ?? 'pending';
   const progress = deploymentData && Number.isFinite(Number(deploymentData.progress)) ? Number(deploymentData.progress) : 0;
-  return `Deploying application... Status: ${status} (${progress}%) (attempt ${attempt + 1}/${maxAttempts})`;
+  const elapsedSeconds = Math.max(0, Math.floor(Number(elapsedMs || 0) / 1000));
+  return `Deploying application — ${elapsedSeconds}s elapsed · ${status} (${progress}%)`;
 }
 
 /**

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

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * @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.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+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 { materializeWorkspace, saveInfra } = require('./workspace');
+const { missingRequiredFields } = require('./infra-manifest');
+const { buildArmParameters, applyAllowMyIp } = require('./infra-projection');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+const { mergeWorkspaceEnv } = require('./workspace-env');
+const { resolvePublicIpv4 } = require('./public-ip');
+const preflight = require('./azure-preflight');
+const readiness = require('./azure-readiness');
+
+const INFRA_SECRETS = Object.freeze(['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY']);
+
+function missingInputError(file, fields) {
+  const error = new Error(
+    `Installation workspace needs input before infra can run. Set these fields in ${file}, then rerun:\n  - ${fields.join('\n  - ')}`
+  );
+  error.code = 'WORKSPACE_INPUT_REQUIRED';
+  return error;
+}
+
+function applyLicenseOptions(doc, input) {
+  const license = doc.parameters.licenseEdition;
+  if (input.licenseEdition !== undefined) {
+    doc.parameters.licenseEdition = { ...license, value: normalizeLicenseEdition(input.licenseEdition), source: 'cli' };
+  } else {
+    doc.parameters.licenseEdition = { ...license, value: normalizeLicenseEdition(license.value) };
+  }
+  if (!ONBOARDING_MODES.includes(doc.parameters.onboardingMode.value)) {
+    throw new Error(`parameters.onboardingMode.value must be one of ${ONBOARDING_MODES.join(', ')}`);
+  }
+}
+
+async function applyAccessOptions(doc, input, deps) {
+  if (input.preset !== undefined) {
+    doc.preset = { ...doc.preset, value: normalizePreset(input.preset), source: 'cli' };
+  }
+  applyLicenseOptions(doc, input);
+  const enabled = input.allowMyIp || doc.allowMyIp.value === true;
+  if (!enabled) {
+    applyAllowMyIp(doc, { enabled: false });
+    return;
+  }
+  const access = await (deps.resolvePublicIpv4 || resolvePublicIpv4)();
+  applyAllowMyIp(doc, { enabled: true, ...access });
+}
+
+function withTemporaryParameters(document, action) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'aifabrix-arm-'));
+  const file = path.join(dir, 'parameters.json');
+  try {
+    fs.chmodSync(dir, 0o700);
+    fs.writeFileSync(file, JSON.stringify(document), { mode: 0o600 });
+    return action(file);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function recordDeployment(doc, record, now) {
+  doc.deployment = {
+    ...doc.deployment,
+    status: { ...doc.deployment.status, value: 'succeeded' },
+    name: record.deploymentName,
+    id: record.deploymentId,
+    correlationId: record.correlationId || null,
+    inputHash: record.inputHash,
+    completedAt: record.recordedAt || now().toISOString()
+  };
+  for (const name of Object.keys(doc.outputs)) {
+    doc.outputs[name].value = record.outputs[name] ?? null;
+  }
+}
+
+function deployTemplate(workspace, doc, context) {
+  const { document, inputHash } = buildArmParameters(doc, context);
+  return withTemporaryParameters(document, parametersFile => marketplace.deployInfra({
+    installId: doc.installId.value,
+    envKey: null,
+    subscription: doc.subscriptionId.value,
+    resourceGroup: doc.resourceGroup.value,
+    location: doc.parameters.location.value,
+    template: workspace.paths.template,
+    parameters: parametersFile,
+    templateHash: context.templateHash,
+    inputHash
+  }, context.az));
+}
+
+async function verifyAndRecordReadiness(workspace, doc, deps) {
+  readiness.verifyRuntimeImagePull(doc, deps.az);
+  await readiness.waitForApplications(doc, deps.probe || marketplace.probeHttps);
+  const controllerUrl = `${String(doc.outputs.webAppUrl.value).replace(/\/+$/, '')}/miso`;
+  doc.controllerUrl = { ...doc.controllerUrl, value: controllerUrl };
+  doc.tenantActivation.url = { ...doc.tenantActivation.url, value: controllerUrl };
+  saveInfra(workspace, doc);
+  mergeWorkspaceEnv(workspace.paths.env, { CONTROLLER_URL: controllerUrl }, { root: workspace.root, replaceable: ['CONTROLLER_URL'] });
+  return controllerUrl;
+}
+
+async function prepareInfra(workspace, input, deps, az) {
+  const { doc, templateHash } = materializeWorkspace(workspace, input, deps);
+  const missing = missingRequiredFields(doc);
+  if (missing.length > 0) throw missingInputError(workspace.paths.infra, missing);
+  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;
+  await applyAccessOptions(doc, input, deps);
+  saveInfra(workspace, doc);
+  return { doc, templateHash, acr };
+}
+
+function deployWithStatus(workspace, doc, context) {
+  doc.deployment.status = { ...doc.deployment.status, value: 'running' };
+  saveInfra(workspace, doc);
+  try {
+    return deployTemplate(workspace, doc, context);
+  } catch (error) {
+    doc.deployment.status = { ...doc.deployment.status, value: 'failed' };
+    saveInfra(workspace, doc);
+    throw error;
+  }
+}
+
+/**
+ * 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)
+ * @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 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 });
+  recordDeployment(doc, record, context.now);
+  saveInfra(workspace, doc);
+  const controllerUrl = await verifyAndRecordReadiness(workspace, doc, context);
+  return { doc, controllerUrl, activationUrl: doc.tenantActivation.url.value };
+}
+
+module.exports = { runAzureInfraStage, INFRA_SECRETS };

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

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * @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.
+ */
+
+const ROLE_ASSIGNMENT_WRITE = 'Microsoft.Authorization/roleAssignments/write';
+const DEPLOYMENT_WRITE = 'Microsoft.Resources/deployments/write';
+const PERMISSIONS_API = '2022-04-01';
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    throw new Error(`Azure CLI returned an unreadable ${label} response`);
+  }
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @param {Function} az - Azure CLI runner
+ * @throws {Error} When the active account differs from the workspace target
+ */
+function assertActiveAccount(doc, az) {
+  const account = parseJson(az(['account', 'show', '--output', 'json']), 'account');
+  const expectedSub = String(doc.subscriptionId.value).toLowerCase();
+  const expectedTenant = String(doc.tenantId.value).toLowerCase();
+  if (String(account.id).toLowerCase() !== expectedSub || String(account.tenantId).toLowerCase() !== expectedTenant) {
+    throw new Error(
+      `Active Azure account (subscription ${account.id}, tenant ${account.tenantId}) does not match the workspace ` +
+      `(subscription ${doc.subscriptionId.value}, tenant ${doc.tenantId.value}). ` +
+      `Run "az login --tenant ${doc.tenantId.value}" and "az account set --subscription ${doc.subscriptionId.value}".`
+    );
+  }
+}
+
+/**
+ * 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 }}
+ */
+function resolveAcr(doc, az) {
+  const subscription = String(doc.subscriptionId.value);
+  const acr = parseJson(az([
+    'acr', 'show', '--name', doc.acrName.value, '--subscription', subscription, '--output', 'json'
+  ]), 'registry');
+  if (typeof acr.id !== 'string' || typeof acr.loginServer !== 'string' || !acr.loginServer) {
+    throw new Error(`Registry ${doc.acrName.value} did not return a resource ID and login server`);
+  }
+  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 };
+}
+
+function actionMatches(pattern, action) {
+  const expression = new RegExp(`^${String(pattern).split('*').map(part => part.replace(/[.+?^${}()|[\]\\/]/g, '\\$&')).join('.*')}$`, 'i');
+  return expression.test(action);
+}
+
+/**
+ * True when Azure RBAC grants `action` at `scope` to the signed-in caller.
+ * @param {Function} az - Azure CLI runner
+ * @param {string} scope - Resource scope ID
+ * @param {string} action - Control-plane action
+ * @returns {boolean}
+ */
+function hasPermission(az, scope, action) {
+  const result = parseJson(az([
+    'rest', '--method', 'get',
+    '--url', `https://management.azure.com${scope}/providers/Microsoft.Authorization/permissions?api-version=${PERMISSIONS_API}`,
+    '--output', 'json'
+  ]), 'permissions');
+  return (result.value || []).some(permission =>
+    (permission.actions || []).some(pattern => actionMatches(pattern, action)) &&
+    !(permission.notActions || []).some(pattern => actionMatches(pattern, 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
+ */
+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 (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`);
+  }
+  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`);
+  }
+}
+
+module.exports = { assertActiveAccount, resolveAcr, hasPermission, actionMatches, assertDeploymentAuthority };

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

@@ -0,0 +1,71 @@
+'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.
+ */
+
+const APP_OUTPUTS = Object.freeze([
+  { name: 'webAppName', label: 'Miso' },
+  { name: 'keycloakWebAppName', label: 'Keycloak' }
+]);
+
+function scoped(args, doc) {
+  return [...args, '--subscription', doc.subscriptionId.value];
+}
+
+function verifyAppImagePull(doc, app, acrId, az) {
+  const group = doc.resourceGroup.value;
+  const principalId = az(scoped([
+    'webapp', 'identity', 'show', '--resource-group', group, '--name', app.value,
+    '--query', 'principalId', '--output', 'tsv'
+  ], doc));
+  if (!principalId) throw new Error(`${app.label} web app has no system-assigned identity`);
+  const assignments = az(scoped([
+    'role', 'assignment', 'list', '--scope', acrId, '--role', 'AcrPull',
+    '--query', `length([?principalId=='${principalId}'])`, '--output', 'tsv'
+  ], doc));
+  if (!(Number(assignments) > 0)) {
+    throw new Error(`${app.label} web app identity has no AcrPull assignment on the workspace registry`);
+  }
+  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 does not pull images with its managed identity`);
+  }
+}
+
+/**
+ * Verifies persistent managed-identity image-pull authorization for both web apps.
+ * @param {Object} doc - Infra manifest with outputs
+ * @param {Function} az - Azure CLI runner
+ */
+function verifyRuntimeImagePull(doc, az) {
+  const acrId = doc.parameters.acrResourceId.value;
+  for (const { name, label } of APP_OUTPUTS) {
+    const value = doc.outputs[name].value;
+    if (!value) throw new Error(`ARM output ${name} is missing; cannot verify ${label} image pull`);
+    verifyAppImagePull(doc, { value, label }, acrId, az);
+  }
+}
+
+/**
+ * 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)
+ * @returns {Promise<void>}
+ */
+async function waitForApplications(doc, probe) {
+  await probe(doc.outputs.webAppUrl.value, '/api/v1/health/readiness', 'Miso');
+  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');
+  }
+  const parsed = new URL(realmUrl);
+  await probe(parsed.origin, parsed.pathname, 'Keycloak');
+}
+
+module.exports = { verifyRuntimeImagePull, waitForApplications };

package/lib/deployment/installation/docker-register.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * @fileoverview DOCKER `--stage register`: one idempotent Mori bootstrap request. The one-time
+ * Service API Key is written only to the local user secrets file (never the shared store or a
+ * remote secrets API) and then materialized into the ignored workspace `.env`.
+ */
+
+const { materializeWorkspace, saveInfra } = require('./workspace');
+const { missingRequiredFields } = require('./infra-manifest');
+const { MORI_SERVICE_KEY } = require('./infra-catalog');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+const { assertIgnoredSecretFile } = require('./workspace-files');
+
+const LOST_KEY_GUIDANCE =
+  `The one-time Mori installation key is not in local secrets (${MORI_SERVICE_KEY}). ` +
+  'Mori issues it only once, so Builder will not request another. Restore it with ' +
+  `"aifabrix secret set ${MORI_SERVICE_KEY} <value>" or ask the Mori administrator to rotate the installation key.`;
+
+function defaultDeps() {
+  const { bootstrapMarketplaceInstallation } = require('../../api/marketplace-bootstrap.api');
+  const { saveLocalSecret } = require('../../utils/local-secrets');
+  const { loadSecrets } = require('../../core/secrets');
+  return { bootstrap: bootstrapMarketplaceInstallation, saveLocalSecret, loadSecrets };
+}
+
+function setStatus(doc, value, evidence) {
+  doc.registration.status = { ...doc.registration.status, value };
+  if (evidence !== undefined) doc.registration.evidence = evidence;
+}
+
+async function hasLocalKey(deps) {
+  const secrets = (await deps.loadSecrets()) || {};
+  const value = secrets[MORI_SERVICE_KEY];
+  return typeof value === 'string' && value.trim() !== '' && !value.startsWith('kv://');
+}
+
+function bootstrapBody(doc) {
+  return {
+    subscriptionId: doc.subscriptionId.value,
+    tenantId: doc.tenantId.value,
+    resourceGroupName: doc.resourceGroup.value,
+    cloudVendor: 'DOCKER',
+    marketplaceSubscriptionId: doc.marketplaceSubscriptionId.value || ''
+  };
+}
+
+function evidenceFrom(data) {
+  return {
+    apiKeyId: data.apiKeyId || null,
+    keyPrefix: data.keyPrefix || null,
+    createdAt: data.createdAt || null,
+    installation: data.installation || null,
+    entitlement: data.entitlement || null
+  };
+}
+
+async function requestRegistration(workspace, doc, deps) {
+  setStatus(doc, 'requested');
+  saveInfra(workspace, doc);
+  const response = await deps.bootstrap(doc.moriBaseUrl.value.replace(/\/+$/, ''), bootstrapBody(doc));
+  if (!response || !response.success) {
+    const status = response?.status;
+    setStatus(doc, status === 409 ? 'conflict' : 'not-registered');
+    saveInfra(workspace, doc);
+    if (status === 409) throw new Error(`Mori reports this installation is already registered. ${LOST_KEY_GUIDANCE}`);
+    throw new Error(`Mori registration failed${status ? ` (HTTP ${status})` : ' (network error)'}; no key was issued. Rerun when Mori is reachable.`);
+  }
+  const data = response.data?.data || response.data || {};
+  if (typeof data.apiKey !== 'string' || data.apiKey === '') {
+    setStatus(doc, 'failed');
+    saveInfra(workspace, doc);
+    throw new Error('Mori registration returned no installation key; contact the Mori administrator before retrying');
+  }
+  await deps.saveLocalSecret(MORI_SERVICE_KEY, data.apiKey);
+  setStatus(doc, 'registered', evidenceFrom(data));
+  saveInfra(workspace, doc);
+}
+
+/**
+ * Runs DOCKER registration.
+ * @param {Object} workspace - Opened workspace
+ * @param {Object} input - Validated stage input
+ * @param {Object} [overrides] - Injected dependencies (bootstrap, saveLocalSecret, loadSecrets, secretsApi, templatePath)
+ * @returns {Promise<{ doc: Object, alreadyRegistered: boolean }>}
+ */
+async function runDockerRegisterStage(workspace, input, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  const { doc } = materializeWorkspace(workspace, input, overrides);
+  const missing = missingRequiredFields(doc);
+  if (missing.length > 0) {
+    throw new Error(`Set these fields in ${workspace.paths.infra}, then rerun:\n  - ${missing.join('\n  - ')}`);
+  }
+  assertIgnoredSecretFile(workspace.paths.env, workspace.root);
+  const status = doc.registration.status.value;
+  const alreadyRegistered = status === 'registered';
+  if (['registered', 'requested', 'conflict'].includes(status)) {
+    if (!(await hasLocalKey(deps))) throw new Error(LOST_KEY_GUIDANCE);
+    if (!alreadyRegistered) {
+      setStatus(doc, 'registered');
+      saveInfra(workspace, doc);
+    }
+  } else {
+    await requestRegistration(workspace, doc, deps);
+  }
+  await materializeWorkspaceSecrets({
+    vendor: 'DOCKER', envPath: workspace.paths.env, root: workspace.root, secretsApi: overrides.secretsApi
+  });
+  return { doc, alreadyRegistered };
+}
+
+module.exports = { runDockerRegisterStage, LOST_KEY_GUIDANCE };

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

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * @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.
+ */
+
+const { validateControllerUrl } = require('../../utils/deployment-validation');
+const { readWorkspaceEnv } = require('./workspace-env');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+
+/**
+ * Resolves the Controller URL for an environment stage and persists an explicit override.
+ * @param {Object} params - Inputs
+ * @param {Object} params.envDoc - Environment document (mutated on override)
+ * @param {Object} params.infra - Infra manifest
+ * @param {Object.<string,string>} params.env - Workspace .env values
+ * @param {string} [params.override] - Validated --controller-url
+ * @returns {string} Controller URL
+ */
+function resolveControllerUrl({ envDoc, infra, env, override }) {
+  if (override) {
+    envDoc.controllerUrl = { ...envDoc.controllerUrl, value: override, source: 'cli' };
+  }
+  const candidate = envDoc.controllerUrl.value || env.CONTROLLER_URL || infra.controllerUrl?.value;
+  if (!candidate) {
+    throw new Error('No Controller URL is recorded for this installation. Run --stage infra first or pass --controller-url https://<host>/miso.');
+  }
+  return validateControllerUrl(candidate).replace(/\/+$/, '');
+}
+
+async function workspaceApiKey(workspace, secretsApi) {
+  const existing = readWorkspaceEnv(workspace.paths.env).MISO_API_KEY;
+  if (existing) return existing;
+  const resolved = await materializeWorkspaceSecrets({
+    vendor: 'AZURE', envPath: workspace.paths.env, root: workspace.root, names: ['MISO_API_KEY'], secretsApi
+  });
+  return resolved.MISO_API_KEY;
+}
+
+/**
+ * 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 }>}
+ */
+async function resolveEnvironmentAuth({ 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' };
+  }
+  if (processEnv.MISO_API_KEY) {
+    return { 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' };
+  }
+  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' };
+  }
+  throw new Error(
+    `No Controller authentication for ${controllerUrl}. Run "aifabrix login -c ${controllerUrl}", ` +
+    'or set MISO_API_KEY (or --miso-api-key-env <NAME>) to a temporary installation key.'
+  );
+}
+
+module.exports = { resolveControllerUrl, resolveEnvironmentAuth };