@aifabrix/builder 2.61.2 → 2.62.0

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

package/lib/schema/infra.parameter.yaml

@@ -593,31 +593,31 @@ parameters:
     azure:
       notes: Not a typical Key Vault name; local optional pypi token.
 
-  # Default client id for controller app in local multi-service layout; override after register if needed.
+  # Miso Controller ↔ controller OAuth. The Controller issues both values at registration;
+  # local infrastructure must leave them empty until application resolution retrieves them.
   - key: miso-controller-client-idKeyVault
     ownerAppKey: miso-controller
     scope: app
     sensitive: false
     generator:
-      type: literal
-      value: 'miso-controller-miso-miso-controller'
-    ensureOn: [upInfra, resolveApp]
+      type: emptyString
+    ensureOn: [resolveApp]
     azure:
       legacyVaultSecretNames:
         - '{serviceName}-miso-clientIdKeyVault'
       notes: >-
-        Per-app OAuth client id from controller registration; literal default matches local Keycloak client naming.
+        Per-app OAuth client id issued when miso-controller is registered with Miso.
 
   - key: miso-controller-client-secretKeyVault
     ownerAppKey: miso-controller
     scope: app
     generator:
-      type: randomBytes32
-    ensureOn: [upInfra, resolveApp]
+      type: emptyString
+    ensureOn: [resolveApp]
     azure:
       notes: >-
-        Per-app OAuth client secret used by miso-controller for service-to-service auth (MISO_CLIENTSECRET).
-        Generated on first ensure for local bootstrap.
+        Per-app OAuth client secret issued when miso-controller is registered with Miso and used
+        for service-to-service auth (MISO_CLIENTSECRET). Never generated by local infrastructure.
 
   # Builder API ↔ controller OAuth. These are explicit declarations rather than catch-all
   # matches so the backup catalog records the owner and canonical names unambiguously.
@@ -644,28 +644,41 @@ parameters:
       notes: Per-app OAuth client secret issued when builder-api is registered with Miso.
 
   # Dataplane ↔ controller OAuth (builder/dataplane env.template MISO_CLIENTID / MISO_CLIENTSECRET).
+  # Plan 265.0: issued by the Controller at registration, so the catalog must not produce a
+  # value for it. The previous `literal` on the `upInfra` hook meant Builder generated an id
+  # the Controller owns — and the literal was `miso-controller-dev-dataplane`, with `dev`
+  # baked into an entry that is not dev-specific. `emptyString` on `resolveApp` is the shape
+  # `builder-api-client-idKeyVault` already uses for the same relationship.
   - key: dataplane-client-idKeyVault
     ownerAppKey: dataplane
     scope: app
     sensitive: false
     generator:
-      type: literal
-      value: 'miso-controller-dev-dataplane'
-    ensureOn: [upInfra, resolveApp]
+      type: emptyString
+    ensureOn: [resolveApp]
     azure:
       notes: >-
-        Per-app OAuth client id from controller registration; literal default matches local Keycloak client naming
-        (override for environments such as miso-controller-dev-dataplane).
-
+        Per-app OAuth client id issued when dataplane is registered with Miso. Not generated
+        locally: the Controller owns it, and a locally invented id is one the Controller has
+        never seen.
+
+  # Plan 265.0: the Controller issues this secret, so a `randomBytes32` generator on the
+  # `upInfra` hook had Builder inventing an OAuth secret the Controller owns. That invented
+  # value is what defeated the "credentials missing locally" guard and surfaced as a
+  # misleading auth error rather than a clear one. Matches
+  # `builder-api-client-secretKeyVault`.
   - key: dataplane-client-secretKeyVault
     ownerAppKey: dataplane
     scope: app
     generator:
-      type: randomBytes32
-    ensureOn: [upInfra, resolveApp]
+      type: emptyString
+    ensureOn: [resolveApp]
     azure:
       vaultSecretName: dataplane-client-secretKeyVault
-      notes: Per-app OAuth client secret for dataplane; generated on first ensure.
+      notes: >-
+        Per-app OAuth client secret issued when dataplane is registered with Miso. Never
+        generated locally; it is fetched from the Controller, which is the only party that
+        can issue one it will accept.
 
   # Mori / telemetry is optional for an unlicensed Community installation.
   - key: mori-controller-api-keyKeyVault
@@ -706,10 +719,17 @@ parameters:
     #
     # Rotating an installation that already holds a value here means clearing BOTH halves
     # together — the generator is get-or-create, so replacing one alone leaves a mismatched pair.
+    # Supplied, never generated. Mori owns this pair and keeps the private half; an installation
+    # that minted it would hold the private half of the key it verifies against and could sign a
+    # licence it would then accept. Builder refuses these pairs (aifabrix-builder 211.0 /
+    # 5bfeb06d); `rsaKeyPair` here made Miso mint them anyway, because catalog-resolver runs the
+    # generator unconditionally and never consults valueSource. `emptyAllowed` is what stops it:
+    # the materializer skips isEmptyByDesign rows, so Miso no longer writes this secret at all.
+    # It arrives instead as a deploy parameter -- packages.json -> main.bicep ->
+    # 08_keyvault-secrets.bicep -> the installation vault -- which is also the only writer that
+    # can hold Mori's real key rather than a locally invented one.
     generator:
-      type: rsaKeyPair
-      pairId: mori-license-signing
-      part: public
+      type: emptyAllowed
     ensureOn: [upInfra, resolveApp]
     azure:
       vaultSecretName: mori-license-public-keyKeyVault
@@ -817,10 +837,17 @@ parameters:
     ownerAppKey: mori-controller
     scope: app
     sensitive: true
+    # Supplied, never generated. Mori owns this pair and keeps the private half; an installation
+    # that minted it would hold the private half of the key it verifies against and could sign a
+    # licence it would then accept. Builder refuses these pairs (aifabrix-builder 211.0 /
+    # 5bfeb06d); `rsaKeyPair` here made Miso mint them anyway, because catalog-resolver runs the
+    # generator unconditionally and never consults valueSource. `emptyAllowed` is what stops it:
+    # the materializer skips isEmptyByDesign rows, so Miso no longer writes this secret at all.
+    # It arrives instead as a deploy parameter -- packages.json -> main.bicep ->
+    # 08_keyvault-secrets.bicep -> the installation vault -- which is also the only writer that
+    # can hold Mori's real key rather than a locally invented one.
     generator:
-      type: rsaKeyPair
-      pairId: mori-policy-signing
-      part: private
+      type: emptyAllowed
     ensureOn: [resolveApp]
     azure:
       vaultSecretName: secrets-policyPrivateKeyVault
@@ -857,10 +884,17 @@ parameters:
     # Mori and the dataplane must not share a signing identity. Sharing one means the dataplane
     # holds a key that mints licences, and the two services have completely different blast
     # radii. Mori is the licence server; the dataplane runs customer workloads.
+    # Supplied, never generated. Mori owns this pair and keeps the private half; an installation
+    # that minted it would hold the private half of the key it verifies against and could sign a
+    # licence it would then accept. Builder refuses these pairs (aifabrix-builder 211.0 /
+    # 5bfeb06d); `rsaKeyPair` here made Miso mint them anyway, because catalog-resolver runs the
+    # generator unconditionally and never consults valueSource. `emptyAllowed` is what stops it:
+    # the materializer skips isEmptyByDesign rows, so Miso no longer writes this secret at all.
+    # It arrives instead as a deploy parameter -- packages.json -> main.bicep ->
+    # 08_keyvault-secrets.bicep -> the installation vault -- which is also the only writer that
+    # can hold Mori's real key rather than a locally invented one.
     generator:
-      type: rsaKeyPair
-      pairId: mori-license-signing
-      part: private
+      type: emptyAllowed
     ensureOn: [resolveApp]
     azure:
       vaultSecretName: secrets-licensePrivateKeyVault