@aifabrix/builder 2.56.0 → 2.58.0

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

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE `--stage dev|tst|pro`: server-reported activation check, then Miso
+ * create-or-update, validate, deploy (resuming an active deployment on 409) and poll to a terminal
+ * state. Makes no Mori, license, token-issuance or Azure calls.
+ */
+
+const { maskSensitiveData } = require('../../utils/log-redaction');
+const { normalizePreset } = require('../environment-config');
+const { readJsonIfExists, environmentFileName } = require('./workspace-files');
+const { saveInfra, saveEnvironment } = require('./workspace');
+const { buildEnvironmentDocument, buildMisoRequests, refreshVariableCatalog } = require('./environment-manifest');
+const { readWorkspaceEnv, removeWorkspaceEnvKey } = require('./workspace-env');
+const { resolveControllerUrl, resolveEnvironmentAuth } = require('./environment-auth');
+
+const FAILED_STATES = Object.freeze(['failed', 'error', 'cancelled']);
+
+function defaultApi() {
+  const environments = require('../../api/environments.api');
+  const deployments = require('../../api/deployments.api');
+  return { ...environments, deployEnvironment: deployments.deployEnvironment, getDeployment: deployments.getDeployment };
+}
+
+function payload(response) {
+  const body = response?.data;
+  return body && typeof body === 'object' && body.data !== undefined ? body.data : body;
+}
+
+function apiFailure(step, response) {
+  const detail = maskSensitiveData(String(response?.formattedError || response?.error || 'request failed'));
+  const error = new Error(`Miso ${step} failed${response?.status ? ` (HTTP ${response.status})` : ''}: ${detail}`);
+  error.status = response?.status;
+  return error;
+}
+
+async function assertTenantActive(ctx) {
+  const response = await ctx.api.getTenantStatus(ctx.controllerUrl, ctx.auth);
+  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';
+  ctx.infra.tenantActivation.status = { ...ctx.infra.tenantActivation.status, value: recorded, checkedAt: ctx.now().toISOString() };
+  saveInfra(ctx.workspace, ctx.infra);
+  if (status !== 'ACTIVE') {
+    const url = ctx.infra.tenantActivation.url?.value || ctx.controllerUrl;
+    throw new Error(`Tenant activation is ${status}. Open ${url}, sign in and complete activation, then rerun this stage.`);
+  }
+}
+
+function needsUpdate(current, update) {
+  const existing = current?.configuration || {};
+  return Object.entries(update.configuration).some(([key, value]) => JSON.stringify(existing[key]) !== JSON.stringify(value)) ||
+    (update.name && current?.name !== update.name);
+}
+
+async function updateExisting(ctx, current, requests) {
+  if (current?.environment && current.environment !== ctx.envKey) {
+    throw new Error(`Controller environment ${ctx.envKey} has environment type "${current.environment}"; refusing to change it`);
+  }
+  if (!needsUpdate(current, requests.update)) return 'unchanged';
+  const patched = await ctx.api.updateEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth, requests.update);
+  if (!patched.success) throw apiFailure('environment update', patched);
+  return 'updated';
+}
+
+async function createOrUpdate(ctx, requests) {
+  const found = await ctx.api.getEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth);
+  if (found.success) return updateExisting(ctx, payload(found), requests);
+  if (found.status !== 404) throw apiFailure('environment read', found);
+  const created = await ctx.api.createEnvironment(ctx.controllerUrl, ctx.auth, requests.create);
+  if (created.success) return 'created';
+  if (created.status !== 409) throw apiFailure('environment create', created);
+  const reread = await ctx.api.getEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth);
+  if (!reread.success) throw apiFailure('environment read', reread);
+  return updateExisting(ctx, payload(reread), requests);
+}
+
+async function validateRequest(ctx, request) {
+  const response = await ctx.api.validateEnvironmentDeployment(ctx.controllerUrl, ctx.envKey, ctx.auth, request);
+  if (!response.success) throw apiFailure('environment validation', response);
+  const result = payload(response) || {};
+  if (result.valid !== true) {
+    const errors = (result.errors || []).map(item => maskSensitiveData(typeof item === 'string' ? item : JSON.stringify(item)));
+    throw new Error(`Miso rejected the environment configuration:\n  - ${errors.join('\n  - ') || 'no details returned'}`);
+  }
+}
+
+async function submitDeployment(ctx, request) {
+  const response = await ctx.api.deployEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth, { ...request, dryRun: false });
+  if (response.success) {
+    const data = payload(response) || {};
+    return { deploymentId: data.deploymentId || data.id, resumed: false };
+  }
+  const activeId = response.errorData?.deploymentId || response.errorData?.extensions?.deploymentId;
+  if (response.status === 409 && activeId) return { deploymentId: activeId, resumed: true };
+  throw apiFailure('environment deploy', response);
+}
+
+async function pollDeployment(ctx, deploymentId) {
+  for (let attempt = 1; attempt <= ctx.maxAttempts; attempt++) {
+    const response = await ctx.api.getDeployment(ctx.controllerUrl, ctx.envKey, deploymentId, ctx.auth);
+    if (!response.success && response.status !== 404) throw apiFailure('deployment status', response);
+    const status = String(payload(response)?.status || 'pending').toLowerCase();
+    if (status === 'completed') return { status };
+    if (FAILED_STATES.includes(status)) {
+      return { status, error: maskSensitiveData(String(payload(response)?.message || payload(response)?.error || status)) };
+    }
+    await ctx.sleep(ctx.pollInterval);
+  }
+  return { status: 'timeout', error: `No terminal state after ${ctx.maxAttempts} checks` };
+}
+
+function recordDeployment(ctx, envDoc, state) {
+  envDoc.deployment = {
+    ...envDoc.deployment,
+    status: { ...envDoc.deployment.status, value: state.status },
+    id: { ...envDoc.deployment.id, value: state.deploymentId ?? envDoc.deployment.id.value },
+    updatedAt: ctx.now().toISOString(),
+    error: state.error || null
+  };
+  saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
+}
+
+function prepareEnvironmentDocument(ctx, input, env) {
+  const envDoc = buildEnvironmentDocument({ envKey: ctx.envKey, existing: readJsonIfExists(ctx.envFile) });
+  if (input.preset !== undefined) envDoc.preset = { ...envDoc.preset, value: normalizePreset(input.preset), source: 'cli' };
+  const problems = refreshVariableCatalog(envDoc, { ...env, ...ctx.processEnv }, ctx.templatesDir);
+  const requests = buildMisoRequests(envDoc, ctx.infra);
+  envDoc.request = { ...envDoc.request, value: requests.deploy };
+  saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
+  if (problems.length > 0) throw new Error(`Environment ${ctx.envKey} is missing required variables:\n  - ${problems.join('\n  - ')}`);
+  return { envDoc, requests };
+}
+
+function assertInfraReady(workspace, envKey) {
+  const infra = workspace.infra;
+  if (!infra || infra.vendor?.value !== 'AZURE' || infra.deployment?.status?.value !== 'succeeded' || !infra.controllerUrl?.value) {
+    throw new Error(`Shared infrastructure is not deployed for this workspace. Run "af env deploy ${workspace.infra?.resourceGroup?.value || '<resource-group>'} --stage infra" before --stage ${envKey}.`);
+  }
+  return infra;
+}
+
+function buildContext(workspace, input, deps) {
+  const envKey = input.stage;
+  return {
+    workspace, envKey,
+    infra: assertInfraReady(workspace, envKey),
+    envFile: workspace.paths.environment(envKey),
+    api: deps.api || defaultApi(),
+    now: deps.now || (() => new Date()),
+    sleep: deps.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms))),
+    pollInterval: deps.pollInterval ?? 5000,
+    maxAttempts: deps.maxAttempts ?? 360,
+    processEnv: deps.env || process.env,
+    templatesDir: deps.templatesDir
+  };
+}
+
+/**
+ * Runs a dev, tst or pro environment stage.
+ * @param {Object} workspace - Opened workspace
+ * @param {Object} input - Validated stage input
+ * @param {Object} [deps] - Injected api, getDeviceToken, secretsApi, env, now, sleep, pollInterval, maxAttempts, templatesDir
+ * @returns {Promise<{ envKey: string, deploymentId: string, status: string, change: string, resumed: boolean }>}
+ */
+async function runEnvironmentStage(workspace, input, deps = {}) {
+  const ctx = buildContext(workspace, input, deps);
+  const env = readWorkspaceEnv(workspace.paths.env);
+  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 }
+  });
+  ctx.auth = authConfig;
+  await assertTenantActive(ctx);
+  const change = await createOrUpdate(ctx, requests);
+  await validateRequest(ctx, requests.deploy);
+  const { deploymentId, resumed } = await submitDeployment(ctx, requests.deploy);
+  if (!deploymentId) throw new Error('Miso accepted the deployment without a deploymentId');
+  recordDeployment(ctx, envDoc, { status: 'running', deploymentId });
+  const final = await pollDeployment(ctx, deploymentId);
+  recordDeployment(ctx, envDoc, { ...final, deploymentId });
+  if (final.status !== 'completed') {
+    throw new Error(`Environment ${ctx.envKey} deployment ${deploymentId} ended as ${final.status}: ${final.error}. Rerun the stage to resume.`);
+  }
+  if (source === 'workspace') removeWorkspaceEnvKey(workspace.paths.env, 'MISO_API_KEY');
+  return { envKey: ctx.envKey, deploymentId, status: final.status, change, resumed, fileName: environmentFileName(ctx.envKey) };
+}
+
+module.exports = { runEnvironmentStage };

package/lib/deployment/installation/index.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * @fileoverview Resource-group installation workspace dispatcher for
+ * `env deploy <resource-group> --stage register|infra|dev|tst|pro`.
+ * All input validation happens before any filesystem, network or cloud mutation.
+ */
+
+const { resolveStageInput, validateResourceGroupKey, ENVIRONMENT_STAGES } = require('./stage-input');
+const { openWorkspace } = require('./workspace');
+
+/**
+ * Runs one installation workspace stage.
+ * @param {string} resourceGroupKey - Positional resource-group key
+ * @param {Object} options - Commander options
+ * @param {Object} [deps] - Injected dependencies for stage runners
+ * @returns {Promise<Object>} Stage result with `stage`, `vendor` and `workspaceDir`
+ */
+async function deployInstallationStage(resourceGroupKey, options, deps = {}) {
+  const resourceGroup = validateResourceGroupKey(resourceGroupKey);
+  const workspace = openWorkspace(resourceGroup, { root: deps.root });
+  const input = resolveStageInput(resourceGroup, options, workspace.infra?.vendor?.value);
+  const base = { stage: input.stage, vendor: input.vendor, workspaceDir: workspace.dir };
+  if (input.stage === 'register') {
+    const { runDockerRegisterStage } = require('./docker-register');
+    return { ...base, ...(await runDockerRegisterStage(workspace, input, deps)) };
+  }
+  if (input.stage === 'infra') {
+    const { runAzureInfraStage } = require('./azure-infra-stage');
+    return { ...base, ...(await runAzureInfraStage(workspace, input, deps)) };
+  }
+  if (ENVIRONMENT_STAGES.includes(input.stage)) {
+    const { runEnvironmentStage } = require('./environment-stage');
+    return { ...base, ...(await runEnvironmentStage(workspace, input, deps)) };
+  }
+  throw new Error(`Unsupported stage ${input.stage}`);
+}
+
+module.exports = { deployInstallationStage };

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

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * @fileoverview Classification of every shipped Marketplace ARM parameter and output for the
+ * installation workspace, plus the canonical `env.template` secret contract. The catalog must
+ * cover the vendor template exactly; drift fails closed.
+ *
+ * Parameter kinds:
+ * - file: value lives in environment-infra.json (seeded from the template default when present)
+ * - secretEnv: resolved from the workspace .env at deploy time (`valueFromEnv`)
+ * - acrLookup: derived from `acrName` through the authenticated Azure account
+ * - fixed: value forced by the installation workflow
+ * - allowMyIp: computed from the default-off current-IP access option
+ * - license: installer-chosen license (edition name or Marketplace subscription ID)
+ * - onboarding: Miso onboarding mode, file-owned with a Builder default
+ * - deferred: tenant-activation/provider setting; never resolved or sent by infra
+ */
+
+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;
+
+/**
+ * Normalizes a license choice: an edition name (case-insensitive) or a Marketplace subscription ID.
+ * @param {string} value - Raw value
+ * @returns {string} Canonical edition name or lower-case UUID
+ * @throws {Error} When the value is neither
+ */
+function normalizeLicenseEdition(value) {
+  const raw = String(value ?? '').trim();
+  if (UUID.test(raw)) return raw.toLowerCase();
+  const edition = raw.toUpperCase();
+  if (LICENSE_EDITIONS.includes(edition)) return edition;
+  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.' },
+  tags: { kind: 'file', source: 'generated', description: 'Tags applied to shared Azure resources.' },
+  enableAppInsights: { kind: 'file', source: 'templateDefault', description: 'Deploy Application Insights resources.' },
+  enableAzureOpenAI: { kind: 'file', source: 'templateDefault', description: 'Deploy Azure OpenAI resources.' },
+  enablePartnerCenterAttribution: { kind: 'file', source: 'templateDefault', description: 'Enable Marketplace partner attribution.' },
+  enablePostgresPublicAccess: { kind: 'allowMyIp', source: 'allowMyIp', description: 'Default off; enabled only while allowMyIp grants the validated caller IPv4 /32 for testing.' },
+  allowedIPs: { kind: 'allowMyIp', source: 'allowMyIpOrUser', description: 'Explicit CIDRs for PostgreSQL, Key Vault, and Storage; allowMyIp merges the resolved caller IPv4 /32.' },
+  adminPassword: { kind: 'secretEnv', env: 'ADMIN_PASSWORD', required: true, description: 'Installation administrator password.' },
+  deploymentEnvironment: { kind: 'file', source: 'templateDefault', description: 'Vendor deployment profile.' },
+  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: '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.' },
+  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.' },
+  onboardingMode: { kind: 'onboarding', source: 'workspacePolicy', description: 'Miso onboarding mode (ONBOARDING_MODE); Builder installations use saasDirect, Marketplace customer installations use customerOwned.' },
+  misoImageTag: { kind: 'file', source: 'templateDefault', description: 'Miso container image tag.' },
+  keycloakImageTag: { kind: 'file', source: 'templateDefault', description: 'Keycloak container image tag.' }
+});
+
+const OUTPUT_CATALOG = Object.freeze({
+  resourceGroupName: 'Deployed Azure resource group.',
+  vnetId: 'Shared virtual-network resource ID.',
+  keyVaultName: 'Installation Key Vault name.',
+  scriptStorageAccountName: 'Deployment-script storage account.',
+  flowiseFileShareName: 'Flowise file share.',
+  managedIdentityName: 'Shared managed identity name.',
+  appServicePlanName: 'App Service plan name.',
+  webAppName: 'Miso web application name.',
+  webAppUrl: 'Miso web application URL.',
+  postgresServerName: 'PostgreSQL server name.',
+  postgresServerFqdn: 'PostgreSQL server FQDN.',
+  postgresMisoDatabaseName: 'Miso database name.',
+  postgresLogsDatabaseName: 'Logs database name.',
+  postgresKeycloakDatabaseName: 'Keycloak database name.',
+  keycloakWebAppName: 'Keycloak web application name.',
+  keycloakWebAppUrl: 'Keycloak web application URL.',
+  keycloakRealmUrl: 'Keycloak realm URL.',
+  keycloakAdminUser: 'Keycloak administrator user name.',
+  portalUrl: 'Azure portal link for the installation resource group.'
+});
+
+/** Mori service key name written by DOCKER registration. */
+const MORI_SERVICE_KEY = 'mori-controller-api-keyKeyVault';
+
+/**
+ * Canonical secret contract. `generate` keys may be created by the Builder secret system;
+ * `required` keys must resolve to a non-empty value before use.
+ */
+const SECRET_BINDINGS = Object.freeze({
+  ADMIN_PASSWORD: { kv: 'miso-controller-admin-passwordKeyVault', required: true, generate: false, comment: 'Required installation administrator password; same canonical secret used by Miso onboarding.' },
+  ENCRYPTION_KEY: { kv: 'miso-controller-secrets-encryptionKeyVault', required: true, generate: true, comment: 'Application/data encryption key.' },
+  MORI_CALLBACK_API_KEY: { kv: 'mori-callback-api-keyKeyVault', required: true, generate: true, comment: 'Mori callback credential.' },
+  MISO_API_KEY: { kv: 'miso-controller-secrets-apiKeyVault', required: false, generate: false, comment: 'Temporary Miso deployment key; an existing login may be used instead.' },
+  MORI_API_KEY: { kv: MORI_SERVICE_KEY, required: true, generate: false, comment: 'Mori installation service key stored by DOCKER registration.' }
+});
+
+const ENV_TEMPLATE_KEYS = Object.freeze({
+  AZURE: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY', 'MISO_API_KEY'],
+  DOCKER: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY', 'MORI_API_KEY']
+});
+
+/**
+ * Committed env.template content for a vendor.
+ * @param {string} vendor - AZURE or DOCKER
+ * @returns {string}
+ */
+function buildEnvTemplate(vendor) {
+  const lines = ['# Installation workspace secret contract. Values resolve from the Builder secret system into the ignored .env.'];
+  for (const name of ENV_TEMPLATE_KEYS[vendor]) {
+    lines.push(`# ${SECRET_BINDINGS[name].comment}`, `${name}=kv://${SECRET_BINDINGS[name].kv}`);
+  }
+  if (vendor === 'AZURE') {
+    lines.push('# Controller URL written by successful infra deployment.', 'CONTROLLER_URL=');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function sameKeys(actual, expected) {
+  const missing = expected.filter(key => !actual.includes(key));
+  const unclassified = actual.filter(key => !expected.includes(key));
+  return { missing, unclassified };
+}
+
+/**
+ * Fails closed when the vendor template has parameters or outputs the catalog does not classify.
+ * @param {Object} template - Parsed ARM template
+ * @throws {Error} On drift
+ */
+function assertTemplateCoverage(template) {
+  const params = sameKeys(Object.keys(template.parameters || {}), Object.keys(PARAMETER_CATALOG));
+  const outputs = sameKeys(Object.keys(template.outputs || {}), Object.keys(OUTPUT_CATALOG));
+  const problems = [
+    ...params.unclassified.map(key => `unclassified parameter ${key}`),
+    ...params.missing.map(key => `missing parameter ${key}`),
+    ...outputs.unclassified.map(key => `unclassified output ${key}`),
+    ...outputs.missing.map(key => `missing output ${key}`)
+  ];
+  if (problems.length > 0) {
+    throw new Error(`Marketplace template does not match the supported installation contract: ${problems.join(', ')}. Update Builder before deploying this template.`);
+  }
+}
+
+module.exports = {
+  PARAMETER_CATALOG,
+  OUTPUT_CATALOG,
+  SECRET_BINDINGS,
+  ENV_TEMPLATE_KEYS,
+  MORI_SERVICE_KEY,
+  LICENSE_EDITIONS,
+  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

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * @fileoverview Generation, normalization and projection of the committed, non-secret
+ * `environment-infra.json` installation manifest. Every operational value is explicit in the
+ * file with its source and description; secrets appear only as `valueFromEnv` references.
+ */
+
+const crypto = require('crypto');
+const {
+  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;
+
+function entry(value, source, description, extra = {}) {
+  return { value, source, description, ...extra };
+}
+
+function templateDefault(template, name) {
+  const value = template.parameters[name].defaultValue;
+  if (typeof value === 'string' && value.startsWith('[')) return '';
+  return value === undefined ? '' : value;
+}
+
+function parameterEntry(name, template) {
+  const spec = PARAMETER_CATALOG[name];
+  switch (spec.kind) {
+  case 'secretEnv':
+    return { valueFromEnv: spec.env, source: 'secretEnv', required: spec.required, description: spec.description };
+  case 'acrLookup':
+    return entry(null, 'azureAcrLookup', spec.description);
+  case 'fixed':
+    return entry(spec.value, spec.source, spec.description);
+  case 'deferred':
+    return entry(null, 'deferred', spec.description, { requiredAt: 'tenantActivation' });
+  case 'allowMyIp':
+    return entry(name === 'allowedIPs' ? [] : false, spec.source, spec.description);
+  case 'license':
+    return entry(DEFAULT_LICENSE_EDITION, spec.source, spec.description);
+  case 'onboarding':
+    return entry(DEFAULT_ONBOARDING_MODE, spec.source, spec.description);
+  default:
+    return entry(templateDefault(template, name), spec.source, spec.description, spec.required ? { required: true } : {});
+  }
+}
+
+/** 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, ...preservedState(existing[name]) } : fresh;
+  }
+  return parameters;
+}
+
+function buildOutputs(existing = {}) {
+  return Object.fromEntries(Object.entries(OUTPUT_CATALOG).map(([name, description]) =>
+    [name, { value: existing[name]?.value ?? null, description }]));
+}
+
+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),
+    outputs: buildOutputs(existing.outputs),
+    controllerUrl: existing.controllerUrl || entry(null, 'infraOutput', 'Activated Miso Controller URL derived from the Miso web application output.'),
+    tenantActivation: existing.tenantActivation || {
+      status: entry('pending', 'controller', 'Server-reported tenant activation state; Builder never marks activation complete.'),
+      url: entry(null, 'infraOutput', 'URL the user opens to sign in and complete tenant activation.')
+    },
+    deployment: existing.deployment || {
+      status: entry('not-deployed', 'azureDeployment', 'Latest shared infrastructure deployment status.'),
+      name: null, id: null, inputHash: null, completedAt: null
+    }
+  };
+}
+
+function dockerSections(template, existing) {
+  const moriDefault = templateDefault(template, 'moriBaseUrl');
+  return {
+    moriBaseUrl: existing.moriBaseUrl || entry(moriDefault, 'templateDefault', 'Mori service base URL used for registration.', { required: true }),
+    marketplaceSubscriptionId: existing.marketplaceSubscriptionId || entry('', 'workspace', 'Marketplace subscription ID; empty selects Mori Community.'),
+    registration: existing.registration || {
+      status: entry('not-registered', 'mori', 'Mori registration status; the one-time key is stored only in local user secrets.'),
+      evidence: null
+    }
+  };
+}
+
+function identitySections(vendor, resourceGroup, existing) {
+  const docker = vendor === 'DOCKER';
+  const idEntry = (description) => docker
+    ? entry(crypto.randomUUID(), 'generated', description)
+    : entry('', 'user', description, { required: true });
+  return {
+    schemaVersion: INFRA_SCHEMA_VERSION,
+    vendor: existing.vendor || entry(vendor, 'cli', 'Installation vendor; immutable once recorded.'),
+    resourceGroup: existing.resourceGroup || entry(resourceGroup, 'command', 'Workspace and Azure resource-group key.'),
+    installId: existing.installId || entry(resourceGroup, 'command', 'Installation identifier and deployment journal key.'),
+    subscriptionId: existing.subscriptionId || idEntry(docker
+      ? 'Stable Docker installation UUID sent to Mori.'
+      : 'Approved installation subscription recorded by this workspace; active Azure account must match.'),
+    tenantId: existing.tenantId || idEntry(docker
+      ? 'Stable Docker owner UUID sent to Mori.'
+      : 'Approved installation directory tenant recorded by this workspace; not an Entra provider setting.')
+  };
+}
+
+/**
+ * Creates or normalizes the infra manifest for a vendor, preserving user-owned values.
+ * @param {Object} params - Inputs
+ * @param {string} params.vendor - AZURE or DOCKER
+ * @param {string} params.resourceGroup - Resource-group key
+ * @param {Object} params.template - Parsed shipped Marketplace template
+ * @param {Object|null} params.existing - Existing manifest
+ * @returns {Object} Manifest document
+ */
+function buildInfraDocument({ vendor, resourceGroup, template, existing }) {
+  const current = existing || {};
+  if (existing && existing.schemaVersion !== INFRA_SCHEMA_VERSION) {
+    throw new Error(`environment-infra.json schemaVersion ${existing.schemaVersion} is not supported; expected ${INFRA_SCHEMA_VERSION}`);
+  }
+  const sections = vendor === 'DOCKER' ? dockerSections(template, current) : azureSections(template, current);
+  return {
+    ...identitySections(vendor, resourceGroup, current),
+    ...sections,
+    variables: current.variables || {},
+    generated: current.generated || {}
+  };
+}
+
+/**
+ * Lists user-owned required fields that are still empty or invalid.
+ * @param {Object} doc - Manifest
+ * @returns {string[]} JSON paths inside environment-infra.json
+ */
+function missingRequiredFields(doc) {
+  const missing = [];
+  for (const key of ['subscriptionId', 'tenantId']) {
+    if (!UUID.test(String(doc[key].value || ''))) missing.push(`${key}.value (UUID)`);
+  }
+  if (doc.vendor.value === 'DOCKER') {
+    if (!/^https:\/\//.test(String(doc.moriBaseUrl.value || ''))) missing.push('moriBaseUrl.value (https URL)');
+    return missing;
+  }
+  if (!/^[a-zA-Z0-9]{5,50}$/.test(String(doc.acrName.value || ''))) missing.push('acrName.value');
+  if (!/^[a-z0-9]+$/.test(String(doc.parameters.location.value || ''))) missing.push('parameters.location.value');
+  if (!/^https:\/\//.test(String(doc.parameters.moriBaseUrl.value || ''))) missing.push('parameters.moriBaseUrl.value (https URL)');
+  return missing;
+}
+
+module.exports = {
+  INFRA_SCHEMA_VERSION,
+  ACR_AUTH_DESCRIPTION,
+  buildInfraDocument,
+  missingRequiredFields
+};