@aifabrix/builder 2.61.2 → 2.62.0

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

@@ -0,0 +1,285 @@
+/**
+ * `env deploy local --stage dev|tst|pro` — the local environment stage (plan 210.0).
+ *
+ * The Azure path creates an environment in the Miso Controller for an Azure installation.
+ * This is the same sentence spoken locally: create this environment's resources inside the
+ * local installation. Increment 1 covers the databases and roles; the promoted container and
+ * the front-door routing follow.
+ *
+ * Every environment shares one Postgres server here, so the names carry the environment —
+ * `{env}_{appKey}_{logical}` with a `_user` role, mirroring Miso 227.3 exactly rather than
+ * inventing a local scheme. See `lib/parameters/physical-database-naming.js`.
+ *
+ * @fileoverview Local environment provisioning for env deploy
+ */
+
+'use strict';
+
+const logger = require('../../utils/logger');
+const { resolveDatabaseNamesWithAdoption } = require('../../parameters/database-adoption');
+const { parseDatabaseSecretKey } = require('../../parameters/database-secret-values');
+const { resolveLocalInstallationName } = require('./local-installation');
+
+/**
+ * Applications that exist **once per environment**.
+ *
+ * The dataplane and nothing else. Keycloak, the Miso Controller, builder-api and
+ * integration-server are **platform services**: one per platform, living in `miso`, shared by
+ * every environment. There is one ACR and one Keycloak, not one each per environment.
+ *
+ * This is why the list also bounds the databases. Creating `pro_keycloak_keycloak` would
+ * stand up a second Keycloak's database for a Keycloak that does not exist, and nothing
+ * would ever connect to it.
+ */
+const ENVIRONMENT_WORKLOAD_APP_KEYS = Object.freeze(['dataplane']);
+
+/**
+ * The databases this environment needs, with their physical names resolved together.
+ *
+ * Resolved as one list so a caller cannot take the database name and leave the role
+ * verbatim, which is the shape of the defect 227.3 fixed.
+ *
+ * Platform-service databases are **excluded**: they belong to the single shared platform in
+ * `miso`, which `setup` installs, not to a workload environment.
+ *
+ * An existing unprefixed database is **adopted** rather than renamed: renaming on a live
+ * server means dropping and recreating, which means losing the data. Only `dev` may adopt,
+ * because everything a pre-environment install created belongs to it.
+ *
+ * @param {string} envKey - Environment key
+ * @param {{ dbName: string, secretKey: string }[]} slots - Platform database slots
+ * @param {Iterable<string>} [existingDatabaseNames] - Databases the server already has
+ * @returns {{ logicalName: string, appKey: string, databaseName: string, roleName: string, secretKey: string, origin: string }[]}
+ * @throws {Error} When a slot's secret key cannot be parsed for its owning application
+ */
+function resolveEnvironmentDatabasePlan(envKey, slots, existingDatabaseNames) {
+  const forEnvironment = slots.filter((slot) => {
+    const parsed = parseDatabaseSecretKey(slot.secretKey);
+    return parsed && ENVIRONMENT_WORKLOAD_APP_KEYS.includes(parsed.appKey);
+  });
+  return forEnvironment.map((slot) => {
+    const parsed = parseDatabaseSecretKey(slot.secretKey);
+    if (!parsed) {
+      throw new Error(
+        `Cannot determine the owning application for database "${slot.dbName}" from secret ` +
+          `key "${slot.secretKey}".`
+      );
+    }
+    const names = resolveDatabaseNamesWithAdoption({
+      logicalName: slot.dbName,
+      appKey: parsed.appKey,
+      environment: envKey,
+      existingDatabaseNames
+    });
+    return {
+      logicalName: names.logicalName,
+      appKey: parsed.appKey,
+      databaseName: names.databaseName,
+      roleName: names.roleName,
+      origin: names.origin,
+      // The catalog key, which the strict resolver already scopes per environment. Not
+      // `names.passwordSecretKey`: which grammar names this secret is open with Miso, and
+      // the catalog key is the one every existing consumer reads.
+      secretKey: slot.secretKey
+    };
+  });
+}
+
+/**
+ * Create the databases and roles for one environment.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<string[]>} Database names ensured
+ */
+async function ensureEnvironmentDatabases(envKey, deps) {
+  const bootstrap = deps.bootstrap || require('../../utils/postgres-platform-bootstrap');
+  const { container, adminPassword, secrets } = await bootstrap.resolveBootstrapContext();
+  const existing = await bootstrap.listExistingDatabaseNames(container, adminPassword);
+  const plan = resolveEnvironmentDatabasePlan(envKey, bootstrap.PLATFORM_DATABASE_SLOTS, existing);
+  const ensured = [];
+  for (const item of plan) {
+    const password = bootstrap.extractPasswordFromUrlOrValue(secrets[item.secretKey]);
+    if (!password || !password.trim()) {
+      // Name the physical secret, which for an application-scoped key carries the owning
+      // application before the key. Quoting `<env>-<key>` here would send someone to create
+      // a name nothing reads.
+      const { computePhysicalSecretName } = require('../../parameters/physical-secret-name');
+      const physical = computePhysicalSecretName(item.secretKey, { environment: envKey });
+      throw new Error(
+        `Secret ${item.secretKey} is missing or empty for environment ${envKey}. ` +
+          `Add it with: aifabrix secret set ${physical} <value>`
+      );
+    }
+    await bootstrap.ensureRoleAndDatabase(
+      container,
+      item.databaseName,
+      item.roleName,
+      password.trim(),
+      adminPassword
+    );
+    if (item.origin === 'adopted') {
+      logger.log(`Adopted existing database ${item.databaseName} for ${envKey}`);
+    }
+    ensured.push(item.databaseName);
+  }
+  return ensured;
+}
+
+/**
+ * Ask Miso whether this environment may exist, before anything is created.
+ *
+ * **Editions are Miso's, not Builder's.** Whether a licence permits `tst` or `pro` is not a
+ * question this repository answers or caches: it asks, and Miso accepts or declines. Builder
+ * holding its own copy of the entitlement rules would be a second answer to drift from the
+ * licence, and a local one at that — the easiest possible thing to edit.
+ *
+ * This runs **first**. A decline after the databases exist would leave an environment's
+ * objects behind for an environment that is not licensed, and nothing would later remove
+ * them.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<void>}
+ * @throws {Error} When Miso declines, or cannot be reached to ask
+ */
+async function authorizeEnvironmentWithController(envKey, deps) {
+  if (typeof deps.authorizeEnvironment === 'function') {
+    await deps.authorizeEnvironment(envKey);
+    return;
+  }
+  const { resolveControllerUrl } = require('../../utils/controller-url');
+  const { getOrRefreshDeviceToken } = require('../../utils/token-manager');
+  const { createEnvironment } = require('../../api/environments.api');
+
+  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.'
+    );
+  }
+  const authConfig = {
+    type: 'device',
+    token: deviceToken.token,
+    controller: deviceToken.controller || controllerUrl
+  };
+  try {
+    await createEnvironment(controllerUrl, authConfig, { key: envKey, environment: envKey });
+  } catch (error) {
+    // Miso owns the edition rules, so its refusal is reported as given rather than
+    // reinterpreted here. Guessing at the reason would put a second, stale explanation of
+    // the licence in front of the operator.
+    throw new Error(
+      `Miso declined environment ${envKey}: ${error.message}\n` +
+        'Editions are licensed in Miso. Nothing was created locally.'
+    );
+  }
+}
+
+/**
+ * Workloads `env deploy` promotes into a promotion-only environment.
+ *
+ * The same set that owns the environment's databases: an application exists per environment
+ * or it does not, and its containers and its databases cannot disagree about which.
+ */
+const PROMOTED_WORKLOAD_APP_KEYS = ENVIRONMENT_WORKLOAD_APP_KEYS;
+
+/**
+ * Run the promoted image as this environment's container.
+ *
+ * `base: true` is the whole point. Without it the run path prefers a local developer-scoped
+ * tag, which is the image someone happens to have built — the opposite of promotion, where
+ * what runs in `pro` must be the artifact that was promoted out of dev.
+ *
+ * Nothing is built here, and image resolution stays with the run path rather than being
+ * recomputed: a second answer to "which image" is how the promoted artifact and the running
+ * one come apart.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<string[]>} Application keys promoted
+ */
+async function promoteWorkloadsForEnvironment(envKey, deps) {
+  const policy = deps.policy || require('../../core/environment-mode-policy');
+  // dev is a working environment: its containers come from `setup` and the `up-*` commands,
+  // and promoting over them would replace what a developer is working on.
+  if (!policy.isPromotionOnlyEnvironment(envKey)) {
+    return [];
+  }
+  const runApp = deps.runApp || require('../../app').runApp;
+  const promoted = [];
+  for (const appKey of PROMOTED_WORKLOAD_APP_KEYS) {
+    try {
+      await runApp(appKey, { env: envKey, base: true });
+    } catch (error) {
+      throw new Error(
+        `Could not promote ${appKey} into ${envKey}: ${error.message}\n` +
+          `${envKey} runs a promoted image and never builds one. Produce it in dev first ` +
+          `with: aifabrix build ${appKey} --base --from-dev`
+      );
+    }
+    promoted.push(appKey);
+  }
+  return promoted;
+}
+
+/**
+ * Run the local environment stage.
+ *
+ * @async
+ * @param {string} installationKey - Positional installation key (`local` or `local-…`)
+ * @param {string} envKey - Validated stage, one of dev|tst|pro
+ * @param {Object} [deps] - Injected collaborators
+ * @returns {Promise<{ stage: string, vendor: string, installation: string, databases: string[], promoted: string[] }>}
+ */
+async function runLocalEnvironmentStage(installationKey, envKey, deps = {}) {
+  const config = deps.config || require('../../core/config');
+  const policy = deps.policy || require('../../core/environment-mode-policy');
+
+  // Miso first: it owns editions, and it accepts or declines this environment. Everything
+  // below creates something, so the licence answer has to come before any of it.
+  await authorizeEnvironmentWithController(envKey, deps);
+
+  // Then the local precondition. tst and pro are unreachable outside the front-door mode,
+  // so creating their databases would leave resources behind for an environment that cannot
+  // serve a request.
+  await policy.assertEnvironmentAllowedForCurrentMode(envKey);
+
+  const developerId = await config.getDeveloperId();
+  const installation = resolveLocalInstallationName(installationKey, developerId);
+
+  logger.log(`Deploying environment ${envKey} into local installation ${installation}`);
+
+  // Databases before containers: a workload that starts without its database fails on its
+  // first request rather than at startup, which is the harder failure to read.
+  const databases = await ensureEnvironmentDatabases(envKey, deps);
+  logger.log(`Ensured ${databases.length} database(s) for ${envKey}: ${databases.join(', ')}`);
+
+  const promoted = await promoteWorkloadsForEnvironment(envKey, deps);
+  if (promoted.length > 0) {
+    logger.log(`Promoted into ${envKey}: ${promoted.join(', ')}`);
+  }
+
+  return { stage: envKey, vendor: 'DOCKER', installation, databases, promoted };
+}
+
+module.exports = {
+  ENVIRONMENT_WORKLOAD_APP_KEYS,
+  PROMOTED_WORKLOAD_APP_KEYS,
+  authorizeEnvironmentWithController,
+  resolveEnvironmentDatabasePlan,
+  ensureEnvironmentDatabases,
+  promoteWorkloadsForEnvironment,
+  runLocalEnvironmentStage
+};

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

@@ -0,0 +1,76 @@
+/**
+ * The `local` installation key for `env deploy` (plan 210.0).
+ *
+ * `env deploy` is dual-mode, and the installation name is what chooses the mode. Miso
+ * already names a local installation `local-dev{NN}`, so Builder mirrors that rather than
+ * inventing a second convention. The operator types the bare word `local`; the CLI knows its
+ * own developer id and supplies the rest.
+ *
+ * Naming the mode in the argument, rather than inferring it from machine state, means the
+ * positional means the same thing on both paths — an installation — and the command reads
+ * the same whichever installation it names.
+ *
+ * @fileoverview Local installation key detection and name derivation
+ */
+
+'use strict';
+
+/** The bare key an operator types. */
+const LOCAL_INSTALLATION_KEY = 'local';
+
+/** Prefix of a fully qualified local installation name. */
+const LOCAL_INSTALLATION_PREFIX = 'local-';
+
+/**
+ * Whether this installation key names a local installation.
+ *
+ * @param {unknown} key - Positional installation key
+ * @returns {boolean}
+ */
+function isLocalInstallationKey(key) {
+  const value = String(key ?? '').trim().toLowerCase();
+  return value === LOCAL_INSTALLATION_KEY || value.startsWith(LOCAL_INSTALLATION_PREFIX);
+}
+
+/**
+ * The installation name for a local key.
+ *
+ * `local` expands to `local-dev{developerId}`; an already-qualified `local-…` is kept as
+ * given, so an operator can name an installation whose id is not this machine's.
+ *
+ * **The developer id must be the stored string, never a parsed number.** It is persisted
+ * zero-padded (`'03'`), and `config.js` preserves that string deliberately. Surrounding code
+ * carries `parseInt(developerId, 10)` for numeric comparisons such as `idNum === 0`; deriving
+ * the name from that would produce `local-dev3`, which disagrees with Miso's `local-dev03`
+ * and surfaces as a missing installation rather than as a naming bug.
+ *
+ * @param {string} key - Positional installation key
+ * @param {string|number} developerId - Stored developer id
+ * @returns {string} Qualified installation name
+ * @throws {Error} When the key is not a local key, or the id is unusable
+ */
+function resolveLocalInstallationName(key, developerId) {
+  const value = String(key ?? '').trim().toLowerCase();
+  if (!isLocalInstallationKey(value)) {
+    throw new Error(`Installation "${key}" is not a local installation key`);
+  }
+  if (value !== LOCAL_INSTALLATION_KEY) {
+    return value;
+  }
+  const id = String(developerId ?? '').trim();
+  if (!id || !/^\d+$/.test(id)) {
+    throw new Error(
+      'Cannot derive the local installation name: no developer id is configured. ' +
+        'Set one with "aifabrix setup", or name the installation explicitly, for example ' +
+        '"aifabrix env deploy local-dev03".'
+    );
+  }
+  return `${LOCAL_INSTALLATION_PREFIX}dev${id}`;
+}
+
+module.exports = {
+  LOCAL_INSTALLATION_KEY,
+  LOCAL_INSTALLATION_PREFIX,
+  isLocalInstallationKey,
+  resolveLocalInstallationName
+};

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

@@ -18,7 +18,10 @@ 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.';
+const DOCKER_SETUP_GUIDANCE =
+  'Install a DOCKER platform with "aifabrix setup", and deploy its environments with ' +
+  '"aifabrix env deploy local --stage <env>". Only --stage register is supported for a ' +
+  'DOCKER vendor on a non-local installation.';
 
 /**
  * True when options select the deprecated explicit Marketplace/journal mode.
@@ -174,6 +177,7 @@ function resolveStageInput(resourceGroupKey, options, persistedVendor) {
 module.exports = {
   WORKSPACE_STAGES,
   ENVIRONMENT_STAGES,
+  validateStage,
   VENDORS,
   DEFAULT_VENDOR,
   isLegacyMarketplaceMode,

package/lib/generator/builders.js

@@ -343,6 +343,9 @@ function addValidatedConfigSections(deployment, variables) {
  * @param {Object} variables - Variables configuration
  */
 function addSimpleOptionalFields(deployment, variables) {
+  if (variables.webSocketsEnabled !== undefined) {
+    deployment.webSocketsEnabled = variables.webSocketsEnabled;
+  }
   if (variables.startupCommand) {
     deployment.startupCommand = variables.startupCommand;
   }
@@ -419,4 +422,3 @@ module.exports = {
   sanitizeAuthType,
   validateBuildFields
 };
-

package/lib/generator/split-variables.js

@@ -46,7 +46,7 @@ function extractRequirementsSection(deployment) {
 }
 
 function extractOptionalSection(deployment, sectionName, optional) {
-  if (!deployment[sectionName]) return;
+  if (!deployment[sectionName] && !(sectionName === 'webSocketsEnabled' && deployment[sectionName] === false)) return;
   optional[sectionName] = sectionName === 'authentication'
     ? { ...deployment[sectionName] }
     : deployment[sectionName];
@@ -57,7 +57,7 @@ function extractOptionalSections(deployment) {
   const names = [
     'healthCheck', 'authentication', 'build', 'repository', 'deployment',
     'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting',
-    'environmentScopedResources', 'required'
+    'environmentScopedResources', 'required', 'webSocketsEnabled'
   ];
   for (const sectionName of names) {
     extractOptionalSection(deployment, sectionName, optional);

package/lib/parameters/database-adoption.js

@@ -0,0 +1,125 @@
+/**
+ * Adopting the databases an existing installation already has (plan 210.0, Miso 227.3).
+ *
+ * Before environments were encoded in the name, a local install created `keycloak`, `miso`
+ * and `dataplane` flat. Encoding the environment renames every one of them, and a rename on
+ * a live Postgres means dropping and recreating — which means losing the data. 227.3 required
+ * the same thing for Azure and answered it the same way: **adopt the database under the name
+ * it already has** rather than move it.
+ *
+ * Miso keeps old names resolvable (`legacyVaultSecretNames`) and adopts a bare legacy
+ * database in `physical-database-adoption.ts`. This is that rule, locally.
+ *
+ * ## The one thing adoption must never do
+ *
+ * Only the environment the legacy install *was* may adopt its databases. A local install
+ * before this plan was `dev` and nothing else, so `dev` adopting `dataplane` continues what
+ * was already running. **`pro` adopting `dataplane` would point production at the database a
+ * developer has been working in** — the exact collision environment-encoded names exist to
+ * prevent, arriving through the mechanism meant to prevent it. So adoption is refused for
+ * every environment except the legacy one, and a fresh install adopts nothing because there
+ * is nothing to adopt.
+ *
+ * Pure: no I/O. The caller supplies the names the server already has.
+ *
+ * @fileoverview Adopt existing unprefixed databases instead of renaming them
+ */
+
+'use strict';
+
+const { resolvePhysicalDatabaseNames } = require('./physical-database-naming');
+
+/**
+ * The environment a pre-environment installation implicitly was.
+ *
+ * Everything an older local install created belongs to `dev`: there was no other environment
+ * to have created it.
+ */
+const LEGACY_ENVIRONMENT = 'dev';
+
+/** How a name was arrived at. */
+const NAME_ORIGIN = Object.freeze({ CONTRACT: 'contract', ADOPTED: 'adopted' });
+
+/**
+ * The role that owns a database, derived the way the server already derived it.
+ *
+ * An adopted database keeps its existing role, and that role was built from the database name
+ * with hyphens flattened. Re-deriving it the same way is what makes adoption a no-op rather
+ * than a second role on an existing database.
+ *
+ * @param {string} databaseName - Physical database name
+ * @returns {string}
+ */
+function roleNameForDatabase(databaseName) {
+  return `${String(databaseName).replace(/-/g, '_')}_user`;
+}
+
+/**
+ * Whether this environment may adopt a legacy database.
+ *
+ * @param {string} environment - Environment key
+ * @returns {boolean}
+ */
+function canAdoptInEnvironment(environment) {
+  return String(environment ?? '').trim().toLowerCase() === LEGACY_ENVIRONMENT;
+}
+
+/**
+ * Resolve the names to use for one database, adopting an existing one where that applies.
+ *
+ * @param {Object} params - Inputs
+ * @param {string} params.logicalName - Logical database name from the manifest
+ * @param {string} params.appKey - Owning application key
+ * @param {string} params.environment - Environment key
+ * @param {Iterable<string>} [params.existingDatabaseNames] - Databases the server already has
+ * @returns {{ logicalName: string, databaseName: string, roleName: string, origin: string }}
+ */
+function resolveDatabaseNamesWithAdoption(params = {}) {
+  const contract = resolvePhysicalDatabaseNames({
+    logicalName: params.logicalName,
+    appKey: params.appKey,
+    environment: params.environment
+  });
+  const existing = new Set(params.existingDatabaseNames || []);
+
+  // The contract name already being there is the normal case after the first run: adopting it
+  // and resolving it are the same answer, so this is reported as `contract` rather than as an
+  // adoption of something this plan created itself.
+  if (existing.has(contract.databaseName) || !canAdoptInEnvironment(params.environment)) {
+    return { ...stripSecretKey(contract), origin: NAME_ORIGIN.CONTRACT };
+  }
+
+  const legacyName = String(params.logicalName ?? '').trim();
+  if (!legacyName || !existing.has(legacyName)) {
+    return { ...stripSecretKey(contract), origin: NAME_ORIGIN.CONTRACT };
+  }
+  return {
+    logicalName: contract.logicalName,
+    databaseName: legacyName,
+    roleName: roleNameForDatabase(legacyName),
+    origin: NAME_ORIGIN.ADOPTED
+  };
+}
+
+/**
+ * `passwordSecretKey` is deliberately not carried forward: which grammar names that secret is
+ * Miso's, and the catalog key is what every consumer reads.
+ *
+ * @param {Object} names - From resolvePhysicalDatabaseNames
+ * @returns {{ logicalName: string, databaseName: string, roleName: string }}
+ */
+function stripSecretKey(names) {
+  return {
+    logicalName: names.logicalName,
+    databaseName: names.databaseName,
+    roleName: names.roleName
+  };
+}
+
+module.exports = {
+  LEGACY_ENVIRONMENT,
+  NAME_ORIGIN,
+  roleNameForDatabase,
+  canAdoptInEnvironment,
+  resolveDatabaseNamesWithAdoption
+};

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
+};