@aifabrix/builder 2.61.2 → 2.63.0

package/lib/parameters/physical-database-naming.js

@@ -0,0 +1,136 @@
+/**
+ * Physical database, role and password-secret names for a local installation.
+ *
+ * Local runs every entitled environment on one PostgreSQL server, which is 227.0's shared
+ * model. Without an environment segment two environments declaring the same logical
+ * database name collide on the database, the role and the secret — the defect Miso 227.3
+ * fixed for Azure. The local path had none of it: keys are derived as
+ * `databases-{appKey}-{i}-*` with no environment in them.
+ *
+ * This mirrors Miso's `resolvePhysicalDatabaseNames`
+ * (`services/infra-parameters/physical-database-naming.ts`) deliberately. Matching it makes
+ * a local environment and an Azure environment the same object at a different address,
+ * which is the point of validating a near-Azure stack in Docker. A second scheme would be
+ * two isolation rules to keep in step, and the Azure one already ships.
+ *
+ * Pure: no I/O. The environment comes from the caller, never from `process.env` and never
+ * from a manifest.
+ *
+ * @fileoverview Environment-encoded PostgreSQL naming for shared local infrastructure
+ */
+
+'use strict';
+
+/** Canonical environment keys. Matches the Azure and database vocabulary, not licence slots. */
+const PHYSICAL_NAME_ENVIRONMENTS = Object.freeze(['miso', 'dev', 'tst', 'pro']);
+
+/** PostgreSQL truncates identifiers at 63 bytes, silently, which would reintroduce collisions. */
+const POSTGRES_IDENTIFIER_LIMIT = 63;
+
+class UnknownPhysicalEnvironmentError extends Error {
+  constructor(environment) {
+    super(
+      `Unknown environment '${environment}'. Expected one of: ${PHYSICAL_NAME_ENVIRONMENTS.join(', ')}.`
+    );
+    this.name = 'UnknownPhysicalEnvironmentError';
+    this.environment = environment;
+  }
+}
+
+class PhysicalNameTooLongError extends Error {
+  constructor(resolvedName, limit) {
+    super(
+      `Resolved physical name '${resolvedName}' is ${resolvedName.length} characters, over the ` +
+      `${limit} character limit. Shorten the application key or the logical database name.`
+    );
+    this.name = 'PhysicalNameTooLongError';
+    this.resolvedName = resolvedName;
+    this.limit = limit;
+  }
+}
+
+/**
+ * Normalise a segment to the PostgreSQL identifier character set.
+ *
+ * @param {string} value - Raw segment
+ * @returns {string}
+ */
+function normalizeSegment(value) {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * Reject an unknown environment instead of defaulting to one.
+ *
+ * Defaulting is how a production database ends up on a development server, so this fails
+ * closed.
+ *
+ * @param {string} environment - Environment key
+ * @returns {string} Normalised environment key
+ * @throws {UnknownPhysicalEnvironmentError}
+ */
+function assertPhysicalEnvironment(environment) {
+  const normalized = String(environment ?? '').trim().toLowerCase();
+  if (!PHYSICAL_NAME_ENVIRONMENTS.includes(normalized)) {
+    throw new UnknownPhysicalEnvironmentError(environment);
+  }
+  return normalized;
+}
+
+/**
+ * Resolve the database, role and password-secret names together.
+ *
+ * Resolved as one call so a caller cannot take two of the three and leave the third
+ * verbatim, which is the shape of the original defect.
+ *
+ * @param {Object} params - Inputs
+ * @param {string} params.logicalName - Logical database name from the manifest
+ * @param {string} params.appKey - Application key
+ * @param {string} params.environment - Logical environment
+ * @returns {{ logicalName: string, databaseName: string, roleName: string, passwordSecretKey: string }}
+ * @throws {UnknownPhysicalEnvironmentError|PhysicalNameTooLongError|Error}
+ */
+function resolvePhysicalDatabaseNames(params = {}) {
+  const environment = assertPhysicalEnvironment(params.environment);
+  const logicalName = String(params.logicalName ?? '').trim();
+  const app = normalizeSegment(params.appKey);
+  const logical = normalizeSegment(logicalName);
+
+  if (!app) {
+    throw new Error('appKey is required to resolve a physical database name');
+  }
+  if (!logical) {
+    throw new Error('logicalName is required to resolve a physical database name');
+  }
+
+  const databaseName = `${environment}_${app}_${logical}`;
+  const roleName = `${databaseName}_user`;
+
+  // The role is the longest derived identifier, so checking it covers the database too.
+  if (roleName.length > POSTGRES_IDENTIFIER_LIMIT) {
+    throw new PhysicalNameTooLongError(roleName, POSTGRES_IDENTIFIER_LIMIT);
+  }
+
+  return {
+    logicalName,
+    databaseName,
+    roleName,
+    // Hyphenated because the vault naming contract rejects underscores.
+    passwordSecretKey: `${databaseName.replace(/_/g, '-')}-password`
+  };
+}
+
+module.exports = {
+  PHYSICAL_NAME_ENVIRONMENTS,
+  POSTGRES_IDENTIFIER_LIMIT,
+  UnknownPhysicalEnvironmentError,
+  PhysicalNameTooLongError,
+  normalizeSegment,
+  assertPhysicalEnvironment,
+  resolvePhysicalDatabaseNames
+};

package/lib/parameters/physical-secret-name.js

@@ -0,0 +1,194 @@
+/**
+ * The physical secret name for a catalog key (plan 210.0, mirroring Miso 227.4).
+ *
+ * Builder resolved `tst` and `pro` secrets by prefixing the logical key: `pro-<key>`. That is
+ * right for an environment-scoped parameter and **wrong for the other two cases**, which
+ * Miso's naming rule (`services/parameters/parameter-naming.ts`) states as:
+ *
+ * ```text
+ * system                          <key>            no prefix, deliberately
+ * environment-scoped              dev-<key>
+ * application-scoped              dev-<app>-<key>
+ * ```
+ *
+ * So the database password an installation actually holds is
+ * `pro-dataplane-databases-0-passwordKeyVault`, not `pro-databases-dataplane-0-passwordKeyVault`
+ * — the application segment sits before the key, not after the environment alone. And system
+ * names such as `keycloak-*` and `acr-*` must not move at all, because the Marketplace
+ * template writes them and every installation-level reader expects them where they are.
+ *
+ * Rather than restate that rule, this resolves the name the way Miso's `computeVaultSecretName`
+ * does: from the catalog entry's own `azure.vaultSecretName` or `azure.vaultSecretNamePattern`.
+ * The catalog is the Miso master and Builder mirrors it byte for byte, so the pattern is the
+ * contract. A key with no pattern is installation-wide by declaration, not by omission.
+ *
+ * This is why no caller may build a prefix itself: the three cases are not distinguishable
+ * from the key alone.
+ *
+ * @fileoverview Catalog-driven physical secret names, mirroring Miso's computeVaultSecretName
+ */
+
+'use strict';
+
+/** Database catalog keys carry both the owning application and the index in the key. */
+const DATABASE_KEY_PARTS = /^databases-([a-z0-9-]+)-(\d+)-(?:url|password)KeyVault$/;
+
+/**
+ * @param {string} key - Logical catalog key
+ * @returns {string} The index, or empty when the key is not a database key
+ */
+function extractDatabaseIndex(key) {
+  const match = String(key ?? '').match(DATABASE_KEY_PARTS);
+  return match ? match[2] : '';
+}
+
+/**
+ * The application a database key belongs to.
+ *
+ * Most database entries match the catalog's generic `keyPattern` rather than an exact key, so
+ * they carry no `ownerAppKey` to read — the owner is in the key. Without this the `{appKey}`
+ * placeholder resolves empty and the name collapses to `pro--databases-0-…`, a name nothing
+ * writes and nothing reads.
+ *
+ * @param {string} key - Logical catalog key
+ * @returns {string} The application key, or empty when the key is not a database key
+ */
+function extractDatabaseAppKey(key) {
+  const match = String(key ?? '').match(DATABASE_KEY_PARTS);
+  return match ? match[1] : '';
+}
+
+/**
+ * Substitute the placeholders a vault name pattern may carry.
+ *
+ * @param {string} pattern - From `azure.vaultSecretNamePattern`
+ * @param {string} key - Logical catalog key
+ * @param {{ environment?: string, serviceName?: string, appKey?: string }} context
+ * @returns {string}
+ */
+function applyVaultNamePattern(pattern, key, context = {}) {
+  return String(pattern)
+    .replace(/\{key\}/g, key)
+    .replace(/\{environment\}/g, context.environment ?? '')
+    .replace(/\{serviceName\}/g, context.serviceName ?? '')
+    .replace(/\{appKey\}/g, context.appKey ?? '')
+    .replace(/\{index\}/g, extractDatabaseIndex(key));
+}
+
+/**
+ * The physical name of the secret holding a logical key's value.
+ *
+ * @param {string} key - Logical catalog key
+ * @param {Object} [context] - Resolution context
+ * @param {string} [context.environment] - Environment key
+ * @param {string} [context.serviceName] - Installation service name
+ * @param {Object} [context.catalog] - Catalog override, for tests
+ * @returns {string} Physical secret name, or the key unchanged when the catalog says so
+ */
+function computePhysicalSecretName(key, context = {}) {
+  const logicalKey = String(key ?? '').trim();
+  if (!logicalKey) {
+    return logicalKey;
+  }
+  const entry = findCatalogEntry(logicalKey, context.catalog);
+  const azure = entry && entry.azure ? entry.azure : null;
+  if (!azure) {
+    return logicalKey;
+  }
+  if (azure.vaultSecretName) {
+    return String(azure.vaultSecretName);
+  }
+  if (!azure.vaultSecretNamePattern) {
+    return logicalKey;
+  }
+  // The owning application comes from the entry or from the key, never from the caller: an
+  // application-scoped parameter names its own owner, and a caller passing a different one
+  // would silently address another application's secret.
+  return applyVaultNamePattern(azure.vaultSecretNamePattern, logicalKey, {
+    environment: context.environment,
+    serviceName: context.serviceName,
+    appKey: entry.ownerAppKey || extractDatabaseAppKey(logicalKey)
+  });
+}
+
+/**
+ * @param {string} key - Logical catalog key
+ * @param {Object} [override] - Catalog override, for tests
+ * @returns {Object|null}
+ */
+function findCatalogEntry(key, override) {
+  const catalog = override || loadCatalogQuietly();
+  if (!catalog || typeof catalog.findEntryForKey !== 'function') {
+    return null;
+  }
+  try {
+    return catalog.findEntryForKey(key) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The catalog, or nothing.
+ *
+ * A key resolves to itself when the catalog cannot be read, which is the same answer an
+ * absent entry gives. Failing here instead would turn an unreadable catalog into "no secret
+ * resolves", and the catalog is already validated by its own checks.
+ *
+ * @returns {Object|null}
+ */
+function loadCatalogQuietly() {
+  try {
+    return require('./infra-parameter-catalog').getInfraParameterCatalog();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The name an environment-isolated installation must read.
+ *
+ * `computePhysicalSecretName` answers what the catalog declares. This answers what an
+ * environment may actually use, and the two differ in one place that matters.
+ *
+ * **An application-scoped secret is never shared between environments.** Each environment's
+ * application holds its own credential. Some catalog entries still pin a literal from before
+ * environments existed — `dataplane-client-secretKeyVault` names itself, with no
+ * `{environment}` anywhere — and honouring that in `pro` would hand `pro` the credential
+ * `dev` is using. One leaked client secret would then authenticate as the other environment's
+ * application, which is the whole isolation gone.
+ *
+ * So an app-scoped name that does not carry its environment gets one. System names
+ * (`keycloak-*`, `acr-*`) are left exactly as they are: there is one Keycloak and one
+ * registry per platform, and those secrets are shared on purpose.
+ *
+ * @param {string} key - Logical catalog key
+ * @param {string} environment - Environment key
+ * @returns {string} The secret name this environment must read
+ */
+function resolveStrictSecretName(key, environment) {
+  const logicalKey = String(key ?? '').trim();
+  const env = String(environment ?? '').trim().toLowerCase();
+  if (!logicalKey || !env) {
+    return logicalKey;
+  }
+  const physical = computePhysicalSecretName(logicalKey, { environment: env });
+  if (physical.startsWith(`${env}-`)) {
+    return physical;
+  }
+  const entry = findCatalogEntry(logicalKey);
+  // Unplaced keys are this installation's own and are scoped by environment; `system`,
+  // `infra` and `shared` entries are platform-wide and keep their names.
+  if (!entry || entry.scope === 'app') {
+    return `${env}-${physical}`;
+  }
+  return physical;
+}
+
+module.exports = {
+  extractDatabaseIndex,
+  extractDatabaseAppKey,
+  applyVaultNamePattern,
+  computePhysicalSecretName,
+  resolveStrictSecretName
+};

package/lib/parameters/rsa-secret-values.js

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Generate linked catalog RSA secrets without rotating existing identities.
+ */
+const crypto = require('crypto');
+const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
+
+/** @param {*} value @returns {boolean} Whether a stored value is populated. */
+function populated(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+/**
+ * Read a stored key without exposing crypto errors or key material.
+ * @param {string} value
+ * @param {string} encryptionKey
+ * @param {string} pairId
+ * @returns {import('crypto').KeyObject}
+ */
+function readPrivateKey(value, encryptionKey, pairId) {
+  try {
+    const pem = isEncrypted(value) ? decryptSecret(value, encryptionKey) : value;
+    const key = crypto.createPrivateKey(pem);
+    if (key.asymmetricKeyType !== 'rsa') throw new Error('Not RSA');
+    return key;
+  } catch {
+    throw new Error(`Cannot generate RSA pair "${pairId}": existing private key cannot be read as RSA. Restore a valid private key before retrying.`);
+  }
+}
+
+/**
+ * Pairs whose private half belongs to Mori, not to an installation.
+ *
+ * Builder must never mint these. Licence trust is a two-signature chain, and both links
+ * exist so that substituting a key fails rather than silently succeeding:
+ *
+ * 1. Mori signs the licence. The installation verifies it against the public key held on
+ *    disk, so a licence from anywhere else does not verify.
+ * 2. That on-disk material is itself validated against a key in Key Vault. The Key Vault is
+ *    provisioned by the Marketplace deployment and readable only by Miso's managed
+ *    identity — nobody can change it, including us — so swapping the on-disk public key for
+ *    one whose private half an attacker holds fails at the second check.
+ *
+ * The second link is an **Azure** guarantee. A Docker installation has no Key Vault and no
+ * managed identity, so locally the chain is the pinned public key alone. Closing that is
+ * online validation against Mori, which is a known gap deferred on purpose: the delivery
+ * target is Azure, and Docker exists to validate the shape of that stack.
+ *
+ * It does not soften this rule. The one environment lacking the second check is the last
+ * one that should mint its own keys, and a locally generated pair would make local
+ * behaviour diverge from the Azure stack it exists to mirror.
+ *
+ * Generating the pair locally breaks both links at once: the installation would hold the
+ * private half of the key it verifies against, so it could sign a licence it then accepts,
+ * and the material would no longer correspond to what Key Vault validates. 227.1 pinned
+ * this key "precisely because a key travelling inside the token it verifies proves
+ * nothing"; a self-generated key proves exactly as little.
+ *
+ * The public half reaches an installation through the `moriLicensePublicKey` deployment
+ * parameter, which the installation contract already classifies as registration-supplied.
+ * An installation with neither half stays unpinned and refuses every licence, which is the
+ * documented and correct failure.
+ */
+const ISSUER_SUPPLIED_PAIR_IDS = Object.freeze(['mori-license-signing', 'mori-policy-signing']);
+
+/**
+ * @param {Object} entry - Catalog entry
+ * @returns {boolean} True when the pair is supplied by Mori rather than generated here
+ */
+function isIssuerSuppliedPair(entry) {
+  return ISSUER_SUPPLIED_PAIR_IDS.includes(entry?.generator?.pairId);
+}
+
+/**
+ * Generate missing parts for one catalog pair, preserving existing key material.
+ * @param {Object[]} entries
+ * @param {Object} existing
+ * @param {string} encryptionKey
+ * @returns {Object} Missing values, including the linked counterpart when declared.
+ */
+function generatePair(entries, existing, encryptionKey) {
+  const pairId = entries[0].generator.pairId;
+  const privateEntry = entries.find(e => e.generator.part === 'private');
+  const publicEntries = entries.filter(e => e.generator.part === 'public');
+  if (!privateEntry) throw new Error(`Cannot generate RSA pair "${pairId}": catalog has no private key entry.`);
+  const storedPrivate = existing[privateEntry.key];
+  const hasPublic = publicEntries.some(e => populated(existing[e.key]));
+  if (!populated(storedPrivate) && hasPublic) {
+    throw new Error(`Cannot generate RSA pair "${pairId}": public key exists but private key is missing. Restore the matching private key before retrying.`);
+  }
+  const privateKey = populated(storedPrivate)
+    ? readPrivateKey(storedPrivate, encryptionKey, pairId)
+    : crypto.generateKeyPairSync('rsa', { modulusLength: 2048 }).privateKey;
+  const publicKey = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' });
+  const values = {};
+  if (!populated(storedPrivate)) {
+    values[privateEntry.key] = privateKey.export({ type: 'pkcs8', format: 'pem' });
+  }
+  for (const entry of publicEntries) {
+    if (!populated(existing[entry.key])) values[entry.key] = publicKey;
+  }
+  return values;
+}
+
+/**
+ * Prepare linked RSA values for a single write operation; never cache identities globally.
+ * @param {string[]} keys - Missing keys requested by the caller
+ * @param {Object} [existing] - Existing or explicitly supplied values (plain or encrypted)
+ * @param {string} [encryptionKey] - Local encryption key
+ * @returns {Object} Newly generated values only
+ */
+function generateRsaSecretValues(keys, existing = {}, encryptionKey) {
+  let catalog;
+  try {
+    catalog = require('./infra-parameter-catalog').getInfraParameterCatalog();
+  } catch {
+    return {}; // Ordinary generation retains its existing catalog-unavailable handling.
+  }
+  const values = {};
+  for (const key of keys) {
+    if (populated(existing[key]) || populated(values[key])) continue;
+    const entry = catalog.findEntryForKey(key);
+    if (entry?.generator?.type !== 'rsaKeyPair') continue;
+    // Supplied by Mori at deployment and validated against Key Vault. Generating it here
+    // would hand the installation the private half of the key it verifies licences against.
+    if (isIssuerSuppliedPair(entry)) continue;
+    const entries = catalog.data.parameters.filter(e => e.key &&
+      e.generator?.type === 'rsaKeyPair' && e.generator.pairId === entry.generator.pairId);
+    Object.assign(values, generatePair(entries, { ...existing, ...values }, encryptionKey));
+  }
+  return values;
+}
+
+/**
+ * The rsaKeyPair branch, which is the only one that can refuse.
+ *
+ * Builder never mints a pair whose private half belongs to the issuer: an installation
+ * holding it could sign a licence it would then accept. Miso's catalog has since changed
+ * these three entries to `emptyAllowed`, so this is now a guard against the declaration
+ * coming back rather than a branch the shipped catalog reaches.
+ *
+ * @param {string} key - Secret key
+ * @param {Object} catalogEntry - Catalog entry
+ * @returns {string|undefined}
+ * @throws {Error} When the pair is issuer-supplied
+ */
+function generateRsaValueFromCatalog(key, catalogEntry) {
+  if (isIssuerSuppliedPair(catalogEntry)) {
+    throw new Error(
+      `Secret "${key}" is supplied by Mori and is never generated here. Licence trust is a ` +
+      'two-signature chain: Mori signs the licence, which is verified against the on-disk ' +
+      'public key, and that material is validated against a Key Vault key readable only by ' +
+      'Miso\'s managed identity. The public half reaches an installation through the ' +
+      'moriLicensePublicKey deployment parameter. An installation with neither stays ' +
+      'unpinned and refuses every licence, which is the intended failure.'
+    );
+  }
+  return generateRsaSecretValues([key])[key];
+}
+
+module.exports = {
+  generateRsaSecretValues,
+  generateRsaValueFromCatalog,
+  isIssuerSuppliedPair,
+  ISSUER_SUPPLIED_PAIR_IDS
+};

package/lib/programmatic/run-channel-install-artifacts.js

@@ -45,6 +45,30 @@ function listChannelArtifacts(ctx) {
   return { artifacts };
 }
 
+/**
+ * Locate the rendered setup document.
+ *
+ * `dist/channels/<target>/` is build output and is gitignored, so anything served only from
+ * there disappears on a clean, a rebuild, or in a fresh workspace — which is what made the
+ * portal report "Setup document not available" after an install that had succeeded. The
+ * durable copy lives beside the channel's other committed files under
+ * `integration/<systemKey>/`, so that is preferred and `dist/` is only a fallback for a
+ * package built but not yet persisted.
+ *
+ * @param {import('./workspace-context').WorkspaceContext} ctx - Workspace context
+ * @param {string} root - User root
+ * @param {string} target - Channel target / system key
+ * @returns {string} Absolute path, or '' when no copy exists
+ */
+function resolveInstallGuidePath(ctx, root, target) {
+  const candidates = [];
+  if (typeof ctx.getIntegrationPath === 'function') {
+    candidates.push(path.join(ctx.getIntegrationPath(), 'INSTALL.md'));
+  }
+  candidates.push(path.join(path.dirname(getArtifactOutputPath(root, target)), 'INSTALL.md'));
+  return candidates.find(candidate => fs.existsSync(candidate)) || '';
+}
+
 /**
  * @param {import('./workspace-context').WorkspaceContext} ctx
  * @param {string} artifactId
@@ -68,8 +92,8 @@ function resolveArtifactFile(ctx, artifactId) {
     }
   }
   if (id === 'installMd') {
-    const absPath = path.join(path.dirname(getArtifactOutputPath(root, target)), 'INSTALL.md');
-    if (fs.existsSync(absPath)) {
+    const absPath = resolveInstallGuidePath(ctx, root, target);
+    if (absPath) {
       return { absPath, contentType: 'text/markdown; charset=utf-8', fileName: 'INSTALL.md' };
     }
   }
@@ -131,6 +155,8 @@ async function handleChannelCallback(ctx, provider, query, body, deps = {}) {
 
 module.exports = {
   listChannelArtifacts,
+  resolveArtifactFile,
+  resolveInstallGuidePath,
   getChannelArtifact,
   handleChannelCallback,
   storeChannelCallbackCredential

package/lib/programmatic/run-channel-package.js

@@ -119,7 +119,9 @@ function generatePackageArtifact(ctx, body, channelTarget, branding, dataplaneUr
     projectRoot: ctx.getUserRoot(),
     channelTarget,
     runtimeValues,
-    dryRun: body.dryRun === true
+    dryRun: body.dryRun === true,
+    // Persist the setup document beside the channel's committed files; dist/ is disposable.
+    durableDir: workspaceSystemDir(ctx)
   });
 }
 

package/lib/programmatic/workspace-context.js

@@ -27,6 +27,38 @@ const WORKSPACE_INTEGRATION_FORMAT = 'json';
  * @property {string} bearerToken
  */
 
+/**
+ * The root a given environment's work lives under.
+ *
+ * `tst` and `pro` get a path segment of their own so an environment's work is separable and
+ * can be deleted on its own; `dev` keeps the existing layout, so no in-flight workspace moves
+ * and nothing that already holds a path stops resolving.
+ *
+ * Because `dev` is unprefixed, a user id equal to a promotion-only environment name would
+ * make `<root>/pro` mean two things — that environment, or that user's dev work. `userId`
+ * comes from a token and only has to avoid traversal to pass validation, so the collision is
+ * refused here rather than assumed away.
+ *
+ * @param {string} workspaceRoot - Resolved WORKSPACE_ROOT
+ * @param {string} userId - Validated user id
+ * @param {string} [environment] - Environment key
+ * @returns {string} Root for this environment
+ * @throws {Error} When the user id would collide with an environment segment
+ */
+function resolveEnvironmentWorkspaceRoot(workspaceRoot, userId, environment) {
+  const { isPromotionOnlyEnvironment } = require('../core/environment-mode-policy');
+  if (isPromotionOnlyEnvironment(userId)) {
+    throw new Error(
+      `userId "${userId}" collides with an environment workspace segment; it cannot be an ` +
+      'environment name'
+    );
+  }
+  if (!isPromotionOnlyEnvironment(environment)) {
+    return workspaceRoot;
+  }
+  return path.join(workspaceRoot, String(environment).trim().toLowerCase());
+}
+
 /**
  * @param {string} segment
  * @returns {string}
@@ -63,7 +95,9 @@ function createWorkspaceContext(params) {
   }
 
   const workspaceRoot = resolveWorkspaceRoot(params.workspaceRoot);
-  const userRoot = path.join(workspaceRoot, userId);
+  const environment = params.environment || process.env.DEFAULT_ENVIRONMENT || 'dev';
+  const environmentRoot = resolveEnvironmentWorkspaceRoot(workspaceRoot, userId, environment);
+  const userRoot = path.join(environmentRoot, userId);
   const integrationRoot = path.join(userRoot, 'integration');
   const useExplicitIntegration = Boolean(params.integrationPath);
   const integrationPath = useExplicitIntegration
@@ -82,7 +116,7 @@ function createWorkspaceContext(params) {
     userId,
     workspaceRoot,
     systemKey,
-    environment: params.environment || process.env.DEFAULT_ENVIRONMENT || 'dev',
+    environment,
     controllerUrl:
       params.controllerUrl ||
       process.env.MISO_CONTROLLER_URL ||
@@ -149,5 +183,6 @@ module.exports = {
   runWithWorkspaceContext,
   ensureIntegrationDirectory,
   resolveWorkspaceRoot,
+  resolveEnvironmentWorkspaceRoot,
   assertPathContained
 };