@aifabrix/builder 2.56.0 → 2.57.0

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

@@ -0,0 +1,165 @@
+'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 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`);
+}
+
+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: 'Unused: Azure web apps pull images with their managed identities.' },
+  acrAdminPassword: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Unused: Azure image pull never uses a registry password.' },
+  acrResourceId: { kind: 'acrLookup', field: 'id', description: 'Resolved from acrName; both web app identities receive AcrPull on it and the deployment fails if the grant fails.' },
+  deployRoleAssignments: { kind: 'file', source: 'templateDefault', description: 'Deploy required Azure role assignments.' },
+  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,
+  normalizeLicenseEdition,
+  buildEnvTemplate,
+  assertTemplateCoverage
+};

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

@@ -0,0 +1,161 @@
+'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
+} = require('./infra-catalog');
+
+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 } : {});
+  }
+}
+
+function buildParameters(template, existing = {}) {
+  const parameters = {};
+  for (const name of Object.keys(PARAMETER_CATALOG)) {
+    const fresh = parameterEntry(name, template);
+    const workflowOwned = ['fixed', 'deferred', 'secretEnv'].includes(PARAMETER_CATALOG[name].kind);
+    parameters[name] = existing[name] && !workflowOwned ? { ...fresh, value: existing[name].value } : fresh;
+  }
+  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 }),
+    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,
+  buildInfraDocument,
+  missingRequiredFields
+};

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

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * @fileoverview Projects `environment-infra.json` plus resolved workspace secrets into standard
+ * ARM deploymentParameters, and applies the default-off current-IP access option.
+ * Deferred tenant-activation parameters are never projected.
+ */
+
+const { PARAMETER_CATALOG } = require('./infra-catalog');
+const { sha256 } = require('./workspace-files');
+
+function projectParameter(name, doc, context) {
+  const spec = PARAMETER_CATALOG[name];
+  switch (spec.kind) {
+  case 'deferred':
+    return undefined;
+  case 'secretEnv': {
+    const value = context.env[spec.env];
+    if (spec.required && (typeof value !== 'string' || value === '')) {
+      throw new Error(`Workspace .env is missing required ${spec.env}; rerun after the secret resolves`);
+    }
+    return value;
+  }
+  case 'acrLookup':
+    if (!context.acr || !context.acr[spec.field]) {
+      throw new Error(`ACR ${spec.field} was not resolved from acrName`);
+    }
+    return context.acr[spec.field];
+  case 'fixed':
+    return spec.value;
+  default:
+    return doc.parameters[name].value;
+  }
+}
+
+/**
+ * Builds the owner-only ARM parameters document and the non-secret input hash.
+ * @param {Object} doc - Infra manifest
+ * @param {Object} context - Resolution context
+ * @param {Object.<string,string>} context.env - Resolved workspace .env values
+ * @param {{ id: string, loginServer: string }} context.acr - Resolved registry
+ * @param {string} context.templateHash - SHA-256 of the deployed template
+ * @returns {{ document: Object, inputHash: string }}
+ */
+function buildArmParameters(doc, context) {
+  const parameters = {};
+  const nonSecret = {};
+  for (const name of Object.keys(PARAMETER_CATALOG)) {
+    const value = projectParameter(name, doc, context);
+    if (value === undefined) continue;
+    parameters[name] = { value };
+    // Secrets never enter the hash.
+    if (PARAMETER_CATALOG[name].kind !== 'secretEnv') nonSecret[name] = value;
+  }
+  return {
+    document: {
+      $schema: 'https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#',
+      contentVersion: '1.0.0.0',
+      parameters
+    },
+    inputHash: sha256(JSON.stringify({ templateHash: context.templateHash, parameters: nonSecret }))
+  };
+}
+
+/**
+ * Applies or revokes the generated caller `/32` rule. User-entered rules are preserved.
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {{ enabled: boolean, cidr?: string, resolvedAt?: string, resolver?: string }} access
+ */
+function applyAllowMyIp(doc, access) {
+  const previous = doc.allowMyIp.resolvedCidr;
+  const current = Array.isArray(doc.parameters.allowedIPs.value) ? doc.parameters.allowedIPs.value : [];
+  const userRules = current.filter(rule => rule !== previous);
+  doc.allowMyIp.value = access.enabled;
+  if (access.enabled) {
+    doc.parameters.allowedIPs.value = [...new Set([...userRules, access.cidr])];
+    doc.parameters.enablePostgresPublicAccess.value = true;
+    Object.assign(doc.allowMyIp, { resolvedCidr: access.cidr, resolvedAt: access.resolvedAt, resolver: access.resolver });
+    return;
+  }
+  doc.parameters.allowedIPs.value = userRules;
+  doc.parameters.enablePostgresPublicAccess.value = false;
+  Object.assign(doc.allowMyIp, { resolvedCidr: null, resolvedAt: null, resolver: null });
+}
+
+module.exports = { buildArmParameters, applyAllowMyIp };

package/lib/deployment/installation/public-ip.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * @fileoverview Resolves the caller's single public IPv4 for default-off, invocation-specific
+ * infrastructure test access. Sends no credentials or cookies, follows no redirects and never
+ * retries against another host.
+ */
+
+const net = require('net');
+const { makeApiCall } = require('../../utils/api');
+
+const PUBLIC_IP_RESOLVER = 'https://api.ipify.org?format=json';
+const TIMEOUT_MS = 5000;
+
+const NON_PUBLIC_IPV4 = [
+  ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
+  ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16],
+  ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]
+];
+
+function ipv4ToInt(ip) {
+  return ip.split('.').reduce((acc, octet) => ((acc << 8) + Number(octet)) >>> 0, 0);
+}
+
+/**
+ * True for one strictly formatted, globally routable IPv4 address.
+ * @param {string} ip - Candidate address
+ * @returns {boolean}
+ */
+function isPublicIpv4(ip) {
+  if (typeof ip !== 'string' || net.isIPv4(ip) !== true || !/^(\d{1,3})(\.\d{1,3}){3}$/.test(ip)) return false;
+  if (ip.split('.').some(octet => octet.length > 1 && octet.startsWith('0'))) return false;
+  const value = ipv4ToInt(ip);
+  return !NON_PUBLIC_IPV4.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return ((value & mask) >>> 0) === ((ipv4ToInt(base) & mask) >>> 0);
+  });
+}
+
+/**
+ * Resolves the caller's public IPv4 as a `/32` rule.
+ * @param {Function} [call] - HTTP call (defaults to the shared API utility)
+ * @param {Function} [now] - Clock
+ * @returns {Promise<{ cidr: string, resolvedAt: string, resolver: string }>}
+ */
+async function resolvePublicIpv4(call = makeApiCall, now = () => new Date()) {
+  const response = await call(PUBLIC_IP_RESOLVER, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+    credentials: 'omit',
+    timeoutMs: TIMEOUT_MS
+  });
+  if (!response || !response.success) {
+    throw new Error('Could not resolve the caller public IPv4 for --allow-my-ip (resolver unavailable, redirected or timed out)');
+  }
+  const data = response.data;
+  const ip = data && typeof data === 'object' && !Array.isArray(data) ? data.ip : undefined;
+  if (!isPublicIpv4(ip)) {
+    throw new Error('Public IP resolver did not return exactly one public IPv4 address; --allow-my-ip was not applied');
+  }
+  return { cidr: `${ip}/32`, resolvedAt: now().toISOString(), resolver: PUBLIC_IP_RESOLVER };
+}
+
+module.exports = { PUBLIC_IP_RESOLVER, isPublicIpv4, resolvePublicIpv4 };

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

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * @fileoverview Workspace-mode `env deploy <resource-group> --stage <stage>` input validation:
+ * resource-group key, stage, vendor matrix and stage-scoped option checks. Runs before any
+ * filesystem, network or cloud mutation.
+ */
+
+const path = require('path');
+const { normalizeLicenseEdition } = require('./infra-catalog');
+
+const WORKSPACE_STAGES = Object.freeze(['register', 'infra', 'dev', 'tst', 'pro']);
+const ENVIRONMENT_STAGES = Object.freeze(['dev', 'tst', 'pro']);
+const VENDORS = Object.freeze(['AZURE', 'DOCKER']);
+const DEFAULT_VENDOR = 'AZURE';
+const RESOURCE_GROUP_KEY = /^[a-z][a-z0-9-]{2,39}$/;
+const ENV_VAR_NAME = /^[A-Z_][A-Z0-9_]*$/;
+const LEGACY_MARKETPLACE_FLAGS = Object.freeze([
+  'marketplaceJson', 'parameters', 'subscription', 'resourceGroup', 'installId'
+]);
+const DOCKER_SETUP_GUIDANCE = 'DOCKER installations deploy through "aifabrix setup"; only --stage register is supported for DOCKER.';
+
+/**
+ * True when options select the deprecated explicit Marketplace/journal mode.
+ * @param {Object} options - Commander options
+ * @returns {boolean}
+ */
+function isLegacyMarketplaceMode(options) {
+  if (LEGACY_MARKETPLACE_FLAGS.some(flag => options[flag] !== undefined && options[flag] !== null)) {
+    return true;
+  }
+  return !options.stage && Boolean(options.controllerUrl);
+}
+
+/**
+ * True when options select the resource-group installation workspace mode.
+ * @param {Object} options - Commander options
+ * @returns {boolean}
+ */
+function isWorkspaceMode(options) {
+  return Boolean(options.stage) && !isLegacyMarketplaceMode(options);
+}
+
+/**
+ * Validates the positional resource-group key before it is used as a path segment.
+ * @param {string} value - Positional value
+ * @returns {string} The validated key
+ * @throws {Error} On absolute paths, separators, traversal, normalization changes or bad format
+ */
+function validateResourceGroupKey(value) {
+  const raw = typeof value === 'string' ? value : '';
+  if (!raw || path.isAbsolute(raw) || /[\\/]/.test(raw) || raw.includes('..') ||
+      path.normalize(raw) !== raw || raw.normalize('NFC') !== raw || raw.trim() !== raw) {
+    throw new Error('Resource group must be a plain workspace key without paths, separators or traversal');
+  }
+  if (!RESOURCE_GROUP_KEY.test(raw)) {
+    throw new Error('Resource group must be a lowercase Azure-safe name (3-40 characters: a-z, 0-9, -; starts with a letter)');
+  }
+  return raw;
+}
+
+/**
+ * Normalizes a vendor value case-insensitively.
+ * @param {string|undefined} value - Raw vendor value
+ * @returns {string|undefined} Canonical vendor or undefined when absent
+ */
+function normalizeVendor(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const vendor = String(value).trim().toUpperCase();
+  if (!VENDORS.includes(vendor)) {
+    throw new Error(`Unsupported vendor "${value}". Use one of: ${VENDORS.join(', ')}`);
+  }
+  return vendor;
+}
+
+function validateStage(stage) {
+  const value = String(stage || '').trim().toLowerCase();
+  if (!WORKSPACE_STAGES.includes(value)) {
+    throw new Error(`Unsupported stage "${stage}". Use one of: ${WORKSPACE_STAGES.join(', ')}`);
+  }
+  return value;
+}
+
+function resolveVendor(stage, requested, persisted) {
+  if (requested && persisted && requested !== persisted) {
+    throw new Error(`Workspace vendor is ${persisted}; --vendor ${requested} conflicts with the existing installation`);
+  }
+  if (stage === 'register') {
+    if (requested !== 'DOCKER') {
+      throw new Error('--stage register requires explicit --vendor DOCKER; AZURE installations register with Mori during tenant activation in Miso');
+    }
+    return requested;
+  }
+  const vendor = requested || persisted || DEFAULT_VENDOR;
+  if (vendor === 'DOCKER') {
+    throw new Error(`--stage ${stage} is not supported for DOCKER. ${DOCKER_SETUP_GUIDANCE}`);
+  }
+  return vendor;
+}
+
+function assertInfraOnlyOptions(stage, options) {
+  if (options.allowMyIp && stage !== 'infra') {
+    throw new Error('--allow-my-ip is supported only with --stage infra for AZURE installations');
+  }
+  if (options.licenseEdition === undefined) return;
+  if (stage !== 'infra') {
+    throw new Error('--license-edition is supported only with --stage infra for AZURE installations');
+  }
+  normalizeLicenseEdition(options.licenseEdition);
+}
+
+function assertStageScopedOptions(stage, options) {
+  assertInfraOnlyOptions(stage, options);
+  const envOnly = [['controllerUrl', '--controller-url'], ['misoApiKeyEnv', '--miso-api-key-env']];
+  for (const [key, flag] of envOnly) {
+    if (options[key] !== undefined && !ENVIRONMENT_STAGES.includes(stage)) {
+      throw new Error(`${flag} is supported only with --stage dev, tst or pro`);
+    }
+  }
+  if (options.config !== undefined) {
+    throw new Error('--config is not supported with --stage; environment settings live in the workspace environment files');
+  }
+  if (options.preset !== undefined && stage === 'register') {
+    throw new Error('--preset is not supported with --stage register');
+  }
+  if (options.misoApiKeyEnv !== undefined && !ENV_VAR_NAME.test(String(options.misoApiKeyEnv))) {
+    throw new Error('--miso-api-key-env must be an environment-variable name (for example MISO_API_KEY), never a key value');
+  }
+  if (options.controllerUrl !== undefined && !/^https:\/\/[^/\s]+(\/[^\s]*)?$/.test(String(options.controllerUrl))) {
+    throw new Error('--controller-url must be an https:// URL');
+  }
+}
+
+/**
+ * Resolves validated workspace-mode input.
+ * @param {string} resourceGroupKey - Positional resource-group key
+ * @param {Object} options - Commander options
+ * @param {string|undefined} persistedVendor - Vendor recorded in an existing workspace
+ * @returns {{ resourceGroup: string, stage: string, vendor: string, allowMyIp: boolean, licenseEdition: string|undefined,
+ *   preset: string|undefined, controllerUrl: string|undefined, misoApiKeyEnv: string|undefined }}
+ */
+function resolveStageInput(resourceGroupKey, options, persistedVendor) {
+  const resourceGroup = validateResourceGroupKey(resourceGroupKey);
+  const stage = validateStage(options.stage);
+  assertStageScopedOptions(stage, options);
+  const vendor = resolveVendor(stage, normalizeVendor(options.vendor), normalizeVendor(persistedVendor));
+  return {
+    resourceGroup,
+    stage,
+    vendor,
+    allowMyIp: options.allowMyIp === true,
+    licenseEdition: options.licenseEdition,
+    preset: options.preset,
+    controllerUrl: options.controllerUrl,
+    misoApiKeyEnv: options.misoApiKeyEnv
+  };
+}
+
+module.exports = {
+  WORKSPACE_STAGES,
+  ENVIRONMENT_STAGES,
+  VENDORS,
+  DEFAULT_VENDOR,
+  isLegacyMarketplaceMode,
+  isWorkspaceMode,
+  validateResourceGroupKey,
+  normalizeVendor,
+  resolveStageInput
+};