@aifabrix/builder 2.62.0 → 2.63.1

package/lib/commands/up-dataplane-bootstrap.js

@@ -19,6 +19,11 @@ const {
   extractAppConfiguration
 } = require('../utils/app-register-config');
 const { buildRegistrationData, saveLocalCredentials, applyLocalhostPortAdjustment } = require('../app/register');
+const {
+  loadDataplanePipelineCredentialsFromSecretsFile,
+  credentialsAcceptToken,
+  waitForDataplaneCredentials
+} = require('./up-dataplane-credentials');
 const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const { getToken } = require('../api/auth.api');
 const { updateApplicationSelfStatus } = require('../api/applications.api');
@@ -31,6 +36,111 @@ const ENCRYPTION_VAULT_KEYS = [
   'secrets-encryptionKeyVault'
 ];
 
+const BOOTSTRAP_CREDENTIAL_ERROR_CODE = 'DATAPLANE_BOOTSTRAP_CREDENTIALS_UNAVAILABLE';
+
+/**
+ * Create a stable, secret-safe bootstrap credential error.
+ * @param {string} message
+ * @returns {Error}
+ */
+function createBootstrapCredentialError(message) {
+  const error = new Error(message);
+  error.code = BOOTSTRAP_CREDENTIAL_ERROR_CODE;
+  return error;
+}
+
+/**
+ * @param {Object|null|undefined} credentials
+ * @returns {boolean}
+ */
+function hasUsablePipelineCredentials(credentials) {
+  return Boolean(
+    credentials &&
+    typeof credentials.clientId === 'string' && credentials.clientId.trim() &&
+    typeof credentials.clientSecret === 'string' && credentials.clientSecret.trim()
+  );
+}
+
+/**
+ * Persist newly issued credentials and prove they can be loaded before deployment.
+ * @async
+ * @param {Object} responseData
+ * @param {string} controllerUrl
+ * @param {string} environmentKey
+ * @param {number} containerPort
+ * @returns {Promise<{status: string, credentialsAvailable: true}>}
+ */
+async function persistBootstrapCredentials(responseData, controllerUrl, environmentKey, containerPort) {
+  try {
+    await saveLocalCredentials(responseData, controllerUrl, { required: true });
+  } catch {
+    throw createBootstrapCredentialError(
+      'Dataplane bootstrap credentials could not be persisted locally; deployment was not started.'
+    );
+  }
+  const localCredentials = await loadDataplanePipelineCredentialsFromSecretsFile();
+  if (!hasUsablePipelineCredentials(localCredentials)) {
+    throw createBootstrapCredentialError(
+      'Dataplane bootstrap credentials are not available from the supported local secret store; ' +
+        'deployment was not started.'
+    );
+  }
+  await syncDataplaneApplicationUrls(
+    controllerUrl,
+    environmentKey,
+    responseData.credentials,
+    containerPort
+  );
+  if (!(await waitForDataplaneCredentials(controllerUrl))) {
+    throw createBootstrapCredentialError(
+      'Dataplane bootstrap credentials were issued but the controller did not accept them in time. ' +
+        'Deployment was not started; retry the command after checking the controller token endpoint.'
+    );
+  }
+  logger.log(formatSuccessLine('Dataplane bootstrap credentials saved locally'));
+  return { status: 'provisioned', credentialsAvailable: true };
+}
+
+/**
+ * Require existing supported local credentials for an idempotent response.
+ * @async
+ * @returns {Promise<{status: string, credentialsAvailable: true}>}
+ */
+async function acceptAlreadyProvisionedDataplane(controllerUrl) {
+  const localCredentials = await loadDataplanePipelineCredentialsFromSecretsFile();
+  const accepted = hasUsablePipelineCredentials(localCredentials) &&
+    await credentialsAcceptToken(controllerUrl);
+  if (!accepted) {
+    throw createBootstrapCredentialError(
+      'Dataplane is registered on the controller but pipeline credentials are missing locally. ' +
+        'Use an authorized session to run: aifabrix app rotate-secret dataplane, then retry setup.'
+    );
+  }
+  logger.log(formatSuccessLine('Dataplane already provisioned (bootstrap idempotent)'));
+  return { status: 'already_provisioned', credentialsAvailable: true };
+}
+
+/**
+ * @async
+ * @param {Object} responseData
+ * @param {string} controllerUrl
+ * @param {string} environmentKey
+ * @param {number} containerPort
+ * @returns {Promise<{status: string, credentialsAvailable: true}>}
+ */
+async function handleBootstrapResponse(responseData, controllerUrl, environmentKey, containerPort) {
+  if (hasUsablePipelineCredentials(responseData.credentials)) {
+    return persistBootstrapCredentials(responseData, controllerUrl, environmentKey, containerPort);
+  }
+  if (responseData.status === 'already_provisioned') {
+    return acceptAlreadyProvisionedDataplane(controllerUrl);
+  }
+  throw createBootstrapCredentialError(
+    'Dataplane bootstrap returned no usable credentials or supported already-provisioned status; ' +
+      'deployment was not started.'
+  );
+}
+
 /**
  * @param {Record<string, unknown>} secrets
  * @returns {string|null}
@@ -118,41 +228,6 @@ async function syncDataplaneApplicationUrls(controllerUrl, environmentKey, crede
   }
 }
 
-async function handleBootstrapResponse(responseData, controllerUrl, environmentKey, containerPort) {
-  if (responseData.credentials && responseData.credentials.clientSecret) {
-    await saveLocalCredentials(responseData, controllerUrl);
-    await syncDataplaneApplicationUrls(
-      controllerUrl,
-      environmentKey,
-      responseData.credentials,
-      containerPort
-    );
-    logger.log(formatSuccessLine('Dataplane bootstrap credentials saved locally'));
-    const { waitForDataplaneCredentials } = require('./up-dataplane-credentials');
-    if (!(await waitForDataplaneCredentials(controllerUrl))) {
-      throw new Error(
-        'Dataplane bootstrap credentials were issued but the controller did not accept them in time. ' +
-        'The deploy that follows gets one attempt, so it would fail with a less specific error. ' +
-        'Retry the command; if it persists, check the controller is serving /api/v1/auth/token.'
-      );
-    }
-    return;
-  }
-  if (responseData.status === 'already_provisioned') {
-    logger.log(formatSuccessLine('Dataplane already provisioned (bootstrap idempotent)'));
-    const { credentialsAcceptToken } = require('./up-dataplane-credentials');
-    if (await credentialsAcceptToken(controllerUrl)) return;
-    throw new Error(
-      'Dataplane is registered on the controller but local pipeline credentials are missing or ' +
-        'not accepted by it. Run: aifabrix login && aifabrix app rotate-secret dataplane'
-    );
-  }
-  throw new Error(
-    'Dataplane bootstrap returned no credentials and no "already_provisioned" status ' +
-      `(status: ${responseData.status || 'none'}). The controller may be a version this CLI does not support.`
-  );
-}
-
 /**
  * Register dataplane via bootstrap endpoint (idempotent).
  * @async
@@ -160,7 +235,7 @@ async function handleBootstrapResponse(responseData, controllerUrl, environmentK
  * @param {string} controllerUrl
  * @param {string} environmentKey
  * @param {Function} buildDataplaneImageRefFn
- * @returns {Promise<void>}
+ * @returns {Promise<{status: string, credentialsAvailable: true}>}
  */
 async function bootstrapDataplaneApplication(options, controllerUrl, environmentKey, buildDataplaneImageRefFn) {
   const encryptionKey = await resolveBootstrapEncryptionKey();
@@ -193,7 +268,7 @@ async function bootstrapDataplaneApplication(options, controllerUrl, environment
     registrationData
   );
 
-  await handleBootstrapResponse(responseData, controllerUrl, environmentKey, containerPort);
+  return handleBootstrapResponse(responseData, controllerUrl, environmentKey, containerPort);
 }
 
 module.exports = {
@@ -201,5 +276,7 @@ module.exports = {
   resolveBootstrapEncryptionKey,
   bootstrapDataplaneApplication,
   syncDataplaneApplicationUrls,
-  pickBootstrapEncryptionKeyFromSecrets
+  pickBootstrapEncryptionKeyFromSecrets,
+  hasUsablePipelineCredentials,
+  BOOTSTRAP_CREDENTIAL_ERROR_CODE
 };

package/lib/commands/up-dataplane.js

@@ -344,34 +344,8 @@ async function provisionAndDeployDataplane(options, environmentKey, controllerUr
   logger.log('');
 }
 
-/**
- * Handle up-dataplane command: ensure logged in, environment dev, ensure dataplane,
- * register or rotate (if already registered), deploy (send manifest to controller),
- * then run dataplane app locally (always local deployment).
- *
- * @async
- * @function handleUpDataplane
- * @param {Object} options - Commander options
- * @param {string} [options.registry] - Override registry for dataplane
- * @param {string} [options.registryMode] - Override registry mode (acr|external)
- * @param {string} [options.image] - Override image reference for dataplane
- * @param {boolean} [options.skipInfraCheck] - When true, skip Postgres/Redis gate (caller already verified, e.g. guided up-dataplane).
- * @returns {Promise<void>}
- * @throws {Error} If infra not up, controller unavailable, not logged in, environment not dev, or any step fails
- */
-/**
- * Run options for the local dataplane container.
- *
- * A guided platform install already shows one spinner for the whole dataplane step, so it
- * either forwards its own progress callback or asks for silence; a standalone run prints
- * normally.
- *
- * @param {Object} options - Command options
- * @param {string} runEnvKey - Resolved run environment
- * @param {number|undefined} portOverride - Resolved port override
- * @returns {Object} Options for app.runApp
- */
-function buildDataplaneRunOptions(options, runEnvKey, portOverride) {
+async function runDataplaneLocally(options) {
+  const { runEnvKey, portOverride } = await computeDataplaneRunOverrides(options);
   const runAppOpts = {
     skipEnvOutputPath: true,
     env: runEnvKey,
@@ -387,7 +361,7 @@ function buildDataplaneRunOptions(options, runEnvKey, portOverride) {
       runAppOpts.silentPoll = true;
     }
   }
-  return runAppOpts;
+  await app.runApp('dataplane', runAppOpts);
 }
 
 async function handleUpDataplane(options = {}) {
@@ -420,8 +394,7 @@ async function handleUpDataplane(options = {}) {
     controllerUrl
   );
 
-  const { runEnvKey, portOverride } = await computeDataplaneRunOverrides(options);
-  await app.runApp('dataplane', buildDataplaneRunOptions(options, runEnvKey, portOverride));
+  await runDataplaneLocally(options);
 
   if (options.platformInstall !== true) {
     logger.log(formatSuccessParagraph('up-dataplane complete. Dataplane is registered, deployed in dev, and running locally.'));

package/lib/core/local-env-overrides.js

@@ -12,6 +12,8 @@
 
 'use strict';
 
+const { buildDevUsernameForFrontDoorHost } = require('../utils/compose-traefik-ingress-base');
+
 /** Applications the CLI registers itself through `.../applications/bootstrap`. */
 const CLI_BOOTSTRAPPED_APP_KEYS = Object.freeze(['dataplane']);
 
@@ -43,12 +45,30 @@ const ONBOARDING_APPS_CONFIG_KEY = 'onboardingApps';
  * to everybody, which is what happened the last time it carried a value.
  */
 const MISO_CONTROLLER_LOCAL_ONLY_ENV = Object.freeze({
-  INFRASTRUCTURE_NAME: '${DEV_USERNAME}.${DEV_ROOT_DOMAIN}',
   KEYCLOAK_PUBLIC_KEY: '',
   OTEL_SERVICE_VERSION: '',
   ACR_LOGIN_SERVER: ''
 });
 
+/**
+ * Miso's infrastructure name on a local install: `local-devNN`, the installation name the licence
+ * binds to (Miso plan 266.0). Miso names the customer's Entra SSO and SCIM applications from it
+ * (`AIF-local-dev03-SSO`) and also looks them up by that name.
+ *
+ * A concrete value, not a placeholder. These overrides are merged after the template is
+ * resolved, so the previous `${DEV_USERNAME}.${DEV_ROOT_DOMAIN}` was never interpolated by
+ * Builder; Docker substituted the unset variables with empty strings and Miso received `.`,
+ * creating `AIF-.-SSO` / `AIF-.-SCIM` in the customer's directory (2026-10-06). Developer id 0
+ * has no `devNN`, so nothing is injected there rather than an invalid `local-`.
+ *
+ * @param {Object} [cfg] - Parsed `~/.aifabrix/config.yaml`
+ * @returns {Object.<string, string>} `{ INFRASTRUCTURE_NAME }` or empty
+ */
+function localInfrastructureNameEnv(cfg) {
+  const devUsername = buildDevUsernameForFrontDoorHost(cfg ? cfg['developer-id'] : undefined);
+  return devUsername ? { INFRASTRUCTURE_NAME: `local-${devUsername}` } : {};
+}
+
 function normalizeAppKeyList(value) {
   const raw = Array.isArray(value) ? value : String(value ?? '').split(',');
   const seen = new Set();
@@ -91,7 +111,8 @@ function localEnvOverridesForApp(appName, cfg) {
   if (key === 'miso-controller') {
     return {
       ONBOARDING_APPS: resolveLocalOnboardingApps(cfg).join(','),
-      ...MISO_CONTROLLER_LOCAL_ONLY_ENV
+      ...MISO_CONTROLLER_LOCAL_ONLY_ENV,
+      ...localInfrastructureNameEnv(cfg)
     };
   }
   if (key === 'builder-api' || key === 'integration-server') {

package/lib/deployment/installation/index.js

@@ -29,7 +29,10 @@ async function deployInstallationStage(resourceGroupKey, options, deps = {}) {
   // install registers with Mori exactly as any other does.
   if (isLocalInstallationKey(resourceGroup) && ENVIRONMENT_STAGES.includes(validateStage(options.stage))) {
     const { runLocalEnvironmentStage } = require('./local-environment-stage');
-    return runLocalEnvironmentStage(resourceGroup, validateStage(options.stage), deps);
+    return runLocalEnvironmentStage(resourceGroup, validateStage(options.stage), {
+      ...deps,
+      preset: options.preset
+    });
   }
   const workspace = openWorkspace(resourceGroup, { root: deps.root });
   const input = resolveStageInput(resourceGroup, options, workspace.infra?.vendor?.value);

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

@@ -102,8 +102,6 @@ const PARAMETER_CATALOG = Object.freeze({
   moriLicensePublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori licence issuer public key (SPKI PEM); empty leaves the installation unpinned and it then refuses every licence.' },
   moriPolicyPublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori policy signing anchor (SPKI PEM), a different pair from the licence key; empty leaves the policy bundle checkable only against the key it carries, which proves nothing.' },
   moriLicenseIssuer: { kind: 'file', source: 'registration', required: false, description: 'Expected iss claim on a Mori licence.' },
-  entraIdClientId: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
-  entraIdClientSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdTenantId: { kind: 'deferred', description: 'Customer Entra provider tenant; distinct from the Azure subscription directory tenant and configured later.' },
   licenseEdition: { kind: 'license', source: 'cliOrFile', description: 'License requested from Mori during tenant activation: COMMUNITY, STANDARD or ENTERPRISE, or an Azure Marketplace subscription ID. Standard/Enterprise by name is a 30-day evaluation.' },
   installationResourceModel: { kind: 'file', source: 'templateDefault', description: 'Initial installation topology: shared for Community and Standard, dedicated for Enterprise DEV. Defaults to shared and is protected by Azure application configuration. It records the topology the installation starts in and grants no later licence entitlement, so it is not a licence input.' },

package/lib/deployment/installation/local-environment-authorize.js

@@ -0,0 +1,221 @@
+/**
+ * Ask Miso whether a local environment may exist, with honest failure labels.
+ *
+ * Local create uses the same request shape as Azure: key, environment, and
+ * configuration.preset / serviceName / location. Docker values are real
+ * placement for that system (location local, serviceName local-devNN), not a
+ * stripped body. Schema rejection is not a licence decline.
+ *
+ * @fileoverview Local env deploy — Miso authorize with contract vs licence split
+ */
+
+'use strict';
+
+const { resolveLocalInstallationName } = require('./local-installation');
+const { normalizePreset } = require('../environment-config');
+
+/** Placement location stored for Docker / local / database installs. */
+const LOCAL_LOCATION = 'local';
+
+/**
+ * @param {Object|Error|null|undefined} errorOrResponse
+ * @returns {number}
+ */
+function statusOf(errorOrResponse) {
+  if (!errorOrResponse || typeof errorOrResponse !== 'object') {
+    return 0;
+  }
+  const raw =
+    errorOrResponse.status ??
+    errorOrResponse.statusCode ??
+    (errorOrResponse.errorData && errorOrResponse.errorData.statusCode);
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * @param {Object|Error|null|undefined} errorOrResponse
+ * @returns {string}
+ */
+function detailOf(errorOrResponse) {
+  if (!errorOrResponse) {
+    return 'request failed';
+  }
+  if (typeof errorOrResponse === 'string') {
+    return errorOrResponse;
+  }
+  return (
+    errorOrResponse.formattedError ||
+    errorOrResponse.detail ||
+    (typeof errorOrResponse.error === 'string' ? errorOrResponse.error : null) ||
+    errorOrResponse.message ||
+    'request failed'
+  );
+}
+
+/**
+ * True when the controller refused the body as invalid, before any licence decision.
+ *
+ * @param {Object|Error|null|undefined} errorOrResponse
+ * @returns {boolean}
+ */
+function isContractValidationFailure(errorOrResponse) {
+  const status = statusOf(errorOrResponse);
+  if (status === 400 || status === 422) {
+    return true;
+  }
+  const text = [
+    detailOf(errorOrResponse),
+    errorOrResponse && errorOrResponse.title,
+    errorOrResponse && errorOrResponse.type,
+    JSON.stringify((errorOrResponse && errorOrResponse.errorData) || {})
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+  return /configuration\.|["']?preset["']?|servicename|service.?name|["']?location["']?/.test(
+    text
+  );
+}
+
+/**
+ * @param {string} envKey
+ * @param {Object|Error} errorOrResponse
+ * @returns {Error}
+ */
+function formatAuthorizeFailure(envKey, errorOrResponse) {
+  const detail = detailOf(errorOrResponse);
+  if (isContractValidationFailure(errorOrResponse)) {
+    return new Error(
+      `Cannot create environment ${envKey}: the controller rejected the request as invalid ` +
+        `(not a licence decision).\n${detail}\n` +
+        'Local create uses the same configuration fields as Azure (preset, serviceName, ' +
+        'location). Nothing was created locally.'
+    );
+  }
+  return new Error(
+    `Miso declined environment ${envKey}: ${detail}\n` +
+      'Editions are licensed in Miso. Nothing was created locally.'
+  );
+}
+
+/**
+ * Same create body shape as Azure environment create.
+ *
+ * Docker still sends a licensed size preset (default `s`). `location` is `local`
+ * and `serviceName` is the installation name. Optional `--preset` overrides size.
+ *
+ * @param {string} envKey
+ * @param {{ serviceName: string, preset?: string, location?: string }} placement
+ * @returns {{ key: string, environment: string, configuration: Object }}
+ */
+function buildLocalEnvironmentCreateBody(envKey, placement) {
+  const key = String(envKey || '').trim();
+  return {
+    key,
+    environment: key,
+    configuration: {
+      preset: normalizePreset(placement.preset),
+      serviceName: String(placement.serviceName || '').trim(),
+      location: String(placement.location || LOCAL_LOCATION).trim() || LOCAL_LOCATION
+    }
+  };
+}
+
+/**
+ * @async
+ * @param {Object} deps
+ * @param {string} installationKey
+ * @returns {Promise<string>}
+ */
+async function resolveAuthorizeServiceName(deps, installationKey) {
+  if (deps.serviceName) {
+    return String(deps.serviceName).trim();
+  }
+  const config = deps.config || require('../../core/config');
+  const developerId = await config.getDeveloperId();
+  return resolveLocalInstallationName(installationKey || 'local', developerId);
+}
+
+/**
+ * @async
+ * @param {string} envKey
+ * @param {Object} deps
+ * @returns {Promise<{ controllerUrl: string, authConfig: Object }>}
+ */
+async function resolveAuthorizeSession(envKey, deps) {
+  const resolveControllerUrl =
+    deps.resolveControllerUrl || require('../../utils/controller-url').resolveControllerUrl;
+  const getOrRefreshDeviceToken =
+    deps.getOrRefreshDeviceToken ||
+    require('../../utils/token-manager').getOrRefreshDeviceToken;
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error(
+      `Cannot create ${envKey}: no controller is configured, so whether your licence ` +
+        'permits this environment cannot be checked. Run "aifabrix login" first.'
+    );
+  }
+  const deviceToken = await getOrRefreshDeviceToken(controllerUrl);
+  if (!deviceToken || !deviceToken.token) {
+    throw new Error(
+      `Cannot create ${envKey}: not signed in, so whether your licence permits this ` +
+        'environment cannot be checked. Run "aifabrix login" first.'
+    );
+  }
+  return {
+    controllerUrl,
+    authConfig: {
+      type: 'device',
+      token: deviceToken.token,
+      controller: deviceToken.controller || controllerUrl
+    }
+  };
+}
+
+/**
+ * @async
+ * @param {string} envKey
+ * @param {Object} [deps]
+ * @returns {Promise<void>}
+ */
+async function authorizeEnvironmentWithController(envKey, deps = {}) {
+  if (typeof deps.authorizeEnvironment === 'function') {
+    await deps.authorizeEnvironment(envKey);
+    return;
+  }
+  const createEnvironment =
+    deps.createEnvironment || require('../../api/environments.api').createEnvironment;
+  const { controllerUrl, authConfig } = await resolveAuthorizeSession(envKey, deps);
+  const serviceName = await resolveAuthorizeServiceName(deps, deps.installationKey);
+  if (!serviceName) {
+    throw new Error(
+      `Cannot create ${envKey}: local serviceName is empty. Name the installation ` +
+        '(for example local-dev03) or set a developer id with "aifabrix setup".'
+    );
+  }
+  const body = buildLocalEnvironmentCreateBody(envKey, {
+    serviceName,
+    preset: deps.preset,
+    location: deps.location
+  });
+  let response;
+  try {
+    response = await createEnvironment(controllerUrl, authConfig, body);
+  } catch (error) {
+    throw formatAuthorizeFailure(envKey, error);
+  }
+  if (response && response.success === false) {
+    throw formatAuthorizeFailure(envKey, response);
+  }
+}
+
+module.exports = {
+  LOCAL_LOCATION,
+  statusOf,
+  detailOf,
+  isContractValidationFailure,
+  formatAuthorizeFailure,
+  buildLocalEnvironmentCreateBody,
+  authorizeEnvironmentWithController
+};

package/lib/deployment/installation/local-environment-snapshot.js

@@ -0,0 +1,124 @@
+/**
+ * Load an environment's bootstrap snapshot after its dataplane credential exists.
+ *
+ * Each environment holds its own application credential. `pro` must never authenticate
+ * with `dev`'s client secret. The snapshot is the settings source; this module does not
+ * write a parallel env file.
+ *
+ * @fileoverview Local env deploy — per-environment bootstrap snapshot
+ */
+
+'use strict';
+
+const { resolveStrictSecretName } = require('../../parameters/physical-secret-name');
+
+const DATAPLANE_CLIENT_ID_KEY = 'dataplane-client-idKeyVault';
+const DATAPLANE_CLIENT_SECRET_KEY = 'dataplane-client-secretKeyVault';
+
+/**
+ * @param {Object} secrets
+ * @param {string} key
+ * @returns {string|null}
+ */
+function nonEmptySecret(secrets, key) {
+  if (!secrets || typeof secrets !== 'object') {
+    return null;
+  }
+  const value = secrets[key];
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+/**
+ * Resolve this environment's dataplane client credentials.
+ *
+ * Uses `resolveStrictSecretName` so an application-scoped secret is never shared between
+ * environments, even when the catalog still pins an unprefixed literal.
+ *
+ * @param {string} envKey
+ * @param {Object} secrets
+ * @returns {{ clientId: string, clientSecret: string, clientIdKey: string, clientSecretKey: string }}
+ * @throws {Error} When either credential is missing for this environment
+ */
+function resolveEnvironmentDataplaneCredentials(envKey, secrets) {
+  const env = String(envKey || '').trim().toLowerCase();
+  const clientIdKey = resolveStrictSecretName(DATAPLANE_CLIENT_ID_KEY, env);
+  const clientSecretKey = resolveStrictSecretName(DATAPLANE_CLIENT_SECRET_KEY, env);
+  let clientId = nonEmptySecret(secrets, clientIdKey);
+  let clientSecret = nonEmptySecret(secrets, clientSecretKey);
+  let resolvedIdKey = clientIdKey;
+  let resolvedSecretKey = clientSecretKey;
+  // Same adoption rule as databases: a pre-environment install's unprefixed credential
+  // belongs to `dev`. tst and pro never adopt — that would share isolation away.
+  if (env === 'dev' && (!clientId || !clientSecret)) {
+    const adoptedId = nonEmptySecret(secrets, DATAPLANE_CLIENT_ID_KEY);
+    const adoptedSecret = nonEmptySecret(secrets, DATAPLANE_CLIENT_SECRET_KEY);
+    if (adoptedId && adoptedSecret) {
+      clientId = adoptedId;
+      clientSecret = adoptedSecret;
+      resolvedIdKey = DATAPLANE_CLIENT_ID_KEY;
+      resolvedSecretKey = DATAPLANE_CLIENT_SECRET_KEY;
+    }
+  }
+  if (!clientId || !clientSecret) {
+    const missing = [
+      !clientId ? clientIdKey : null,
+      !clientSecret ? clientSecretKey : null
+    ].filter(Boolean);
+    throw new Error(
+      `Cannot load a configuration snapshot for ${env}: missing ${missing.join(' and ')}. ` +
+        'Each environment uses its own dataplane credential. Add ' +
+        `aifabrix secret set ${missing[0]} <value>` +
+        (missing[1] ? ` (and ${missing[1]})` : '') +
+        '.'
+    );
+  }
+  return {
+    clientId,
+    clientSecret,
+    clientIdKey: resolvedIdKey,
+    clientSecretKey: resolvedSecretKey
+  };
+}
+
+/**
+ * Fetch the registered dataplane's bootstrap snapshot for this environment.
+ *
+ * @async
+ * @param {string} envKey
+ * @param {Object} [deps]
+ * @returns {Promise<{ configuration: Object, context: Object, issuedAt?: string }>}
+ */
+async function loadEnvironmentBootstrapSnapshot(envKey, deps = {}) {
+  const resolveControllerUrl =
+    deps.resolveControllerUrl || require('../../utils/controller-url').resolveControllerUrl;
+  const loadSecrets = deps.loadSecrets || require('../../core/secrets').loadSecrets;
+  const fetchBootstrapSnapshot =
+    deps.fetchBootstrapSnapshot ||
+    require('../../api/bootstrap-snapshot.api').fetchBootstrapSnapshot;
+
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error(
+      `Cannot load a configuration snapshot for ${envKey}: no controller is configured. ` +
+        'Run "aifabrix login" first.'
+    );
+  }
+  const secrets = deps.secrets || (await loadSecrets(undefined));
+  const credentials = resolveEnvironmentDataplaneCredentials(envKey, secrets);
+  return fetchBootstrapSnapshot(
+    controllerUrl,
+    { clientId: credentials.clientId, clientSecret: credentials.clientSecret },
+    deps
+  );
+}
+
+module.exports = {
+  DATAPLANE_CLIENT_ID_KEY,
+  DATAPLANE_CLIENT_SECRET_KEY,
+  resolveEnvironmentDataplaneCredentials,
+  loadEnvironmentBootstrapSnapshot
+};