@wtfalch/foundry 0.46.0 → 0.47.0

package/dist/org.js

@@ -10,6 +10,9 @@ export const ACCESS_RULE_KINDS = new Set(['bypass', 'service-token']);
 export const DEFAULT_GATE_LIMIT = 3;
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export const APP_ENTRY_KEY = 'app';
+function refusal(code, path, message) {
+    return { code, path, message };
+}
 /** The most volumes one entry may declare. */
 export const MAX_ENTRY_VOLUMES = 8;
 /** `uses.auth.mcp.onboardingPath`: absolute, no query, no fragment, no dot segments. */
@@ -44,9 +47,14 @@ export const FILES_ENTRY_ENV_NAMES = [
 export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export const EDGE_ENTRY_ENV_NAMES = ['EDGE_URL', 'EDGE_API_KEY'];
-/** The org's `app` entry: today's one app. */
-export function appEntry(hosting) {
-    return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
+/** True for the entry marked `main`, and for an entry keyed {@link APP_ENTRY_KEY} that leaves `main` unset. */
+export function isMainEntry(entry) {
+    return entry.main ?? entry.key === APP_ENTRY_KEY;
+}
+/** The org's main app: the entry marked `main`, else the entry keyed {@link APP_ENTRY_KEY}. */
+export function mainEntry(hosting) {
+    return (hosting.entries.find((entry) => entry.main === true) ??
+        hosting.entries.find((entry) => entry.main === undefined && entry.key === APP_ENTRY_KEY));
 }
 /**
  * `sharedSecret` ({@link EnvSharedSecret}) and `heldSecret` ({@link EnvHeldSecret}) are the secret sources. The
@@ -107,26 +115,30 @@ const HOSTING_BUILD_PACKS = new Set([
  * - `tunnel` requires `enabled` -- it means nothing without the apps running.
  * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
- * - `enabled` requires an entry keyed {@link APP_ENTRY_KEY}.
+ * - `enabled` requires at least one entry, and at most one entry is the main app ({@link isMainEntry}).
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
  */
 export function validateHosting(hosting, names) {
+    return refuseHosting(hosting, names)?.message ?? null;
+}
+/** {@link validateHosting} with the code and path of the first refusal. */
+export function refuseHosting(hosting, names) {
     if (hosting.tunnel && !hosting.enabled) {
-        return 'hosting.tunnel requires hosting.enabled';
+        return refusal('hosting_tunnel_needs_hosting', 'hosting.tunnel', 'hosting.tunnel requires hosting.enabled');
     }
     const seenNames = new Set();
     for (const app of hosting.issuerApps) {
         if (!app.name) {
-            return 'every issuerApps entry needs a non-empty name';
+            return refusal('issuer_app_name_missing', 'hosting.issuerApps', 'every issuerApps entry needs a non-empty name');
         }
         if (seenNames.has(app.name)) {
-            return `issuerApps name '${app.name}' is not unique`;
+            return refusal('issuer_app_name_not_unique', `hosting.issuerApps.${app.name}.name`, `issuerApps name '${app.name}' is not unique`);
         }
         seenNames.add(app.name);
         if (!ISSUER_APP_KINDS.has(app.kind)) {
-            return `issuerApps '${app.name}' has an unknown kind '${app.kind}'`;
+            return refusal('issuer_app_kind_unknown', `hosting.issuerApps.${app.name}.kind`, `issuerApps '${app.name}' has an unknown kind '${app.kind}'`);
         }
         // The fixed 'agora' ZITADEL client (#164, `plan/diff.ts`'s
         // `planAgoraClient`) already owns the `zitadel:app:agora` key, for
@@ -134,20 +146,20 @@ export function validateHosting(hosting, names) {
         // reservation (`validateSite` below), which only applies once
         // `site.enabled` is true.
         if (app.name === 'agora') {
-            return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
+            return refusal('issuer_app_name_reserved_agora', `hosting.issuerApps.${app.name}.name`, `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`);
         }
         // #161: the same for the always-on Boule client.
         if (app.name === 'boule') {
-            return `issuerApps '${app.name}' is reserved for the always-on Boule client every org gets`;
+            return refusal('issuer_app_name_reserved_boule', `hosting.issuerApps.${app.name}.name`, `issuerApps '${app.name}' is reserved for the always-on Boule client every org gets`);
         }
     }
-    if (hosting.enabled && !appEntry(hosting)) {
-        return `hosting.enabled requires an entry keyed '${APP_ENTRY_KEY}'`;
+    if (hosting.enabled && hosting.entries.length === 0) {
+        return refusal('hosting_needs_entry', 'hosting.entries', 'hosting.enabled requires at least one entry');
     }
     const seenKeys = new Set();
     for (const entry of hosting.entries) {
         if (seenKeys.has(entry.key)) {
-            return `hosting.entries key '${entry.key}' is not unique`;
+            return refusal('entry_key_not_unique', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is not unique`);
         }
         seenKeys.add(entry.key);
         const invalid = validateHostingEntry(entry, hosting.enabled);
@@ -166,14 +178,19 @@ export function validateHosting(hosting, names) {
         if (invalidWorker)
             return invalidWorker;
         const invalidWorkerApp = validateEntryWorkerApp(entry, hosting, names);
-        if (invalidWorkerApp)
-            return invalidWorkerApp;
+        if (invalidWorkerApp) {
+            return refusal('worker_app_invalid', `hosting.entries.${entry.key}.workerApp`, invalidWorkerApp);
+        }
         const invalidEdgeUse = validateEntryEdge(entry, hosting, names?.domain);
         if (invalidEdgeUse)
             return invalidEdgeUse;
     }
+    const mains = hosting.entries.filter(isMainEntry);
+    if (mains.length > 1) {
+        return refusal('hosting_main_count', 'hosting.entries', `at most one hosting entry may be the main app: ${mains.map((entry) => `'${entry.key}'`).join(' and ')} are`);
+    }
     if (hosting.entries.filter((entry) => entry.uses?.ai?.webhookPath !== undefined).length > 1) {
-        return 'at most one hosting entry may set uses.ai webhookPath: ai keeps one webhook per organisation';
+        return refusal('ai_webhook_path_not_unique', 'hosting.entries', 'at most one hosting entry may set uses.ai webhookPath: ai keeps one webhook per organisation');
     }
     // #318 re-review: two entries declaring the same worker route both throw at
     // apply (`cloudflareWorker` refuses a route already bound to a Worker
@@ -185,7 +202,7 @@ export function validateHosting(hosting, names) {
         if (!entry.worker)
             continue;
         if (seenWorkerRoutes.has(entry.worker.route)) {
-            return `hosting.entries '${entry.key}' worker route '${entry.worker.route}' is already declared by another entry`;
+            return refusal('worker_route_not_unique', `hosting.entries.${entry.key}.worker.route`, `hosting.entries '${entry.key}' worker route '${entry.worker.route}' is already declared by another entry`);
         }
         seenWorkerRoutes.add(entry.worker.route);
     }
@@ -193,7 +210,7 @@ export function validateHosting(hosting, names) {
     if (invalidNames)
         return invalidNames;
     if (hosting.entries.filter(entryHasDatabase).length > 1) {
-        return 'at most one hosting entry may set database: the one runtime database role cannot serve two apps';
+        return refusal('database_not_unique', 'hosting.entries', 'at most one hosting entry may set database: the one runtime database role cannot serve two apps');
     }
     const invalidGates = validateGates(hosting, names?.domain, names?.locked);
     if (invalidGates)
@@ -204,7 +221,7 @@ export function validateHosting(hosting, names) {
         if (invalidRule)
             return invalidRule;
         if (seenAccessHostnames.has(rule.hostname)) {
-            return `hosting.access hostname '${rule.hostname}' is listed twice`;
+            return refusal('access_hostname_not_unique', 'hosting.access', `hosting.access hostname '${rule.hostname}' is listed twice`);
         }
         seenAccessHostnames.add(rule.hostname);
     }
@@ -220,20 +237,20 @@ const ACCESS_RULE_HOSTNAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-
 function validateAccessRule(rule, hosting, names) {
     const at = `hosting.access '${rule.hostname}'`;
     if (!rule.hostname || !ACCESS_RULE_HOSTNAME.test(rule.hostname)) {
-        return `hosting.access entries need a full hostname ('${rule.hostname}' is not one)`;
+        return refusal('access_hostname_invalid', 'hosting.access', `hosting.access entries need a full hostname ('${rule.hostname}' is not one)`);
     }
     if (!hosting.enabled) {
-        return `${at} requires hosting.enabled`;
+        return refusal('access_needs_hosting', 'hosting.access', `${at} requires hosting.enabled`);
     }
     if (!ACCESS_RULE_KINDS.has(rule.kind)) {
-        return `${at} has an unknown kind '${rule.kind}'`;
+        return refusal('access_kind_unknown', 'hosting.access', `${at} has an unknown kind '${rule.kind}'`);
     }
     if (rule.kind === 'service-token' && !rule.serviceTokenName) {
-        return `${at} kind 'service-token' needs a non-empty serviceTokenName`;
+        return refusal('access_service_token_name_missing', 'hosting.access', `${at} kind 'service-token' needs a non-empty serviceTokenName`);
     }
     if (names) {
         if (names.locked.has(rule.hostname)) {
-            return `${at} is a name foundry owns`;
+            return refusal('access_hostname_locked', 'hosting.access', `${at} is a name foundry owns`);
         }
         const { domain } = names;
         // Any name under the domain: `share.<domain>` and `storage.<domain>` are
@@ -242,7 +259,7 @@ function validateAccessRule(rule, hosting, names) {
             domain !== null &&
             (rule.hostname === domain || rule.hostname.endsWith(`.${domain}`));
         if (!served) {
-            return `${at} is not a name the org serves under its own domain`;
+            return refusal('access_hostname_not_served', 'hosting.access', `${at} is not a name the org serves under its own domain`);
         }
     }
     return null;
@@ -256,7 +273,7 @@ function validateAccessRule(rule, hosting, names) {
  */
 function validateGates(hosting, domain, locked) {
     if (!Number.isInteger(hosting.gateLimit) || hosting.gateLimit < 1) {
-        return 'hosting.gateLimit must be a positive whole number';
+        return refusal('gate_limit_invalid', 'hosting.gateLimit', 'hosting.gateLimit must be a positive whole number');
     }
     const seenKeys = new Set();
     for (const entry of hosting.entries) {
@@ -264,33 +281,33 @@ function validateGates(hosting, domain, locked) {
         for (const gate of entry.gates) {
             const at = `hosting.entries '${entry.key}' gate '${gate.key}'`;
             if (!hosting.enabled || !hosting.usesDomain || domain === null) {
-                return `${at} needs hosting.enabled, hosting.usesDomain and an org domain`;
+                return refusal('gate_needs_domain', `hosting.entries.${entry.key}.gates.${gate.key}`, `${at} needs hosting.enabled, hosting.usesDomain and an org domain`);
             }
             if (!ENTRY_KEY.test(gate.key)) {
-                return `${at} key must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`;
+                return refusal('gate_key_invalid', `hosting.entries.${entry.key}.gates.${gate.key}.key`, `${at} key must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`);
             }
             if (seenKeys.has(gate.key))
-                return `${at} key is used by two gates`;
+                return refusal('gate_key_not_unique', `hosting.entries.${entry.key}.gates.${gate.key}.key`, `${at} key is used by two gates`);
             seenKeys.add(gate.key);
             if (gate.hostnames.length === 0)
-                return `${at} needs at least one hostname`;
+                return refusal('gate_needs_hostname', `hosting.entries.${entry.key}.gates.${gate.key}.hostnames`, `${at} needs at least one hostname`);
             for (const name of gate.hostnames) {
                 if (!entry.hostnames.includes(name)) {
-                    return `${at} hostname '${name}' is not one of the entry's hostnames`;
+                    return refusal('gate_hostname_not_entry_hostname', `hosting.entries.${entry.key}.gates.${gate.key}.hostnames`, `${at} hostname '${name}' is not one of the entry's hostnames`);
                 }
                 if (taken.has(name))
-                    return `${at} hostname '${name}' is held by two gates or listed twice`;
+                    return refusal('gate_hostname_held_twice', `hosting.entries.${entry.key}.gates.${gate.key}.hostnames`, `${at} hostname '${name}' is held by two gates or listed twice`);
                 taken.add(name);
                 if (domain && name !== '*') {
                     const full = name === '@' ? domain : `${name}.${domain}`;
                     if (locked?.has(full))
-                        return `${at} hostname '${name}' is a name foundry owns: ${full}`;
+                        return refusal('gate_hostname_locked', `hosting.entries.${entry.key}.gates.${gate.key}.hostnames`, `${at} hostname '${name}' is a name foundry owns: ${full}`);
                 }
             }
         }
     }
     if (seenKeys.size > hosting.gateLimit) {
-        return `hosting declares ${seenKeys.size} gates, over its limit of ${hosting.gateLimit}`;
+        return refusal('gate_limit_exceeded', 'hosting.gateLimit', `hosting declares ${seenKeys.size} gates, over its limit of ${hosting.gateLimit}`);
     }
     return null;
 }
@@ -307,34 +324,34 @@ function validateEntryHostnames(hosting, names) {
         const at = `hosting.entries '${entry.key}'`;
         if (entry.hostnames.includes('*')) {
             if (!hosting.usesDomain || (names && !names.domain)) {
-                return `${at} hostname '*' needs hosting.usesDomain and an org domain: it serves any name under the domain`;
+                return refusal('wildcard_needs_domain', `hosting.entries.${entry.key}.hostnames`, `${at} hostname '*' needs hosting.usesDomain and an org domain: it serves any name under the domain`);
             }
             if (hosting.entries.filter((e) => e.hostnames.includes('*')).length > 1) {
-                return `hostname '*' is held by two entries: an org has one wildcard`;
+                return refusal('wildcard_held_twice', `hosting.entries.${entry.key}.hostnames`, `hostname '*' is held by two entries: an org has one wildcard`);
             }
         }
-        if (!hosting.usesDomain && entry.key !== APP_ENTRY_KEY && entry.hostnames.length > 0) {
-            return `${at} hostnames need hosting.usesDomain: without it only the '${APP_ENTRY_KEY}' entry is served, at its own address`;
+        if (!hosting.usesDomain && !isMainEntry(entry) && entry.hostnames.length > 0) {
+            return refusal('hostnames_need_domain', `hosting.entries.${entry.key}.hostnames`, `${at} hostnames need hosting.usesDomain: without it only the main app is served, at its own address`);
         }
         const reads = hosting.usesDomain && names?.domain;
         if (reads &&
-            entry.key === APP_ENTRY_KEY &&
+            isMainEntry(entry) &&
             !entry.workerApp &&
             !entry.hostnames.some((n) => n !== '*')) {
-            return `${at} needs a hostname ('@' or a label) while hosting.usesDomain is on: '*' alone names nothing, and the app would fall back to the bare domain`;
+            return refusal('hostname_needed', `hosting.entries.${entry.key}.hostnames`, `${at} needs a hostname ('@' or a label) while hosting.usesDomain is on: '*' alone names nothing, and the app would fall back to the bare domain`);
         }
         for (const name of entry.hostnames) {
             if (name !== '@' && name !== '*' && !ENTRY_KEY.test(name)) {
-                return `${at} hostname '${name}' must be '@', '*' or a DNS label`;
+                return refusal('hostname_invalid', `hosting.entries.${entry.key}.hostnames`, `${at} hostname '${name}' must be '@', '*' or a DNS label`);
             }
             if (taken.has(name))
-                return `hostname '${name}' is held by two entries or listed twice`;
+                return refusal('hostname_not_unique', `hosting.entries.${entry.key}.hostnames`, `hostname '${name}' is held by two entries or listed twice`);
             taken.add(name);
             if (names?.domain &&
                 name !== '@' &&
                 name !== '*' &&
                 names.locked.has(`${name}.${names.domain}`)) {
-                return `${at} hostname '${name}' is a name foundry owns: ${name}.${names.domain}`;
+                return refusal('hostname_locked', `hosting.entries.${entry.key}.hostnames`, `${at} hostname '${name}' is a name foundry owns: ${name}.${names.domain}`);
             }
         }
     }
@@ -371,105 +388,109 @@ const HELD_SECRETS = "declare it as { from: 'heldSecret' }, not a plain value";
 function validateHostingEntry(entry, enabled) {
     const at = `hosting.entries '${entry.key}'`;
     if (!ENTRY_KEY.test(entry.key)) {
-        return `hosting.entries key '${entry.key}' must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`;
+        return refusal('entry_key_invalid', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`);
     }
     if (entry.repo !== null && !REPO.test(entry.repo)) {
-        return `${at} repo must be a repo under wtfalch, or null`;
+        return refusal('entry_repo_invalid', `hosting.entries.${entry.key}.repo`, `${at} repo must be a repo under wtfalch, or null`);
     }
     if (entry.folder !== null && (entry.folder.startsWith('/') || entry.folder.includes('..'))) {
-        return `${at} folder must be a relative path inside the repo`;
+        return refusal('entry_folder_invalid', `hosting.entries.${entry.key}.folder`, `${at} folder must be a relative path inside the repo`);
     }
     if (!entry.branch) {
-        return `${at} branch must be non-empty`;
+        return refusal('entry_branch_empty', `hosting.entries.${entry.key}.branch`, `${at} branch must be non-empty`);
     }
     if (!HOSTING_BUILD_PACKS.has(entry.buildPack)) {
-        return `${at} buildPack has an unknown value '${entry.buildPack}'`;
+        return refusal('entry_build_pack_unknown', `hosting.entries.${entry.key}.buildPack`, `${at} buildPack has an unknown value '${entry.buildPack}'`);
     }
     if (entry.buildPack === 'dockercompose') {
-        return `${at} buildPack dockercompose is not available for an entry`;
+        return refusal('entry_build_pack_unavailable', `hosting.entries.${entry.key}.buildPack`, `${at} buildPack dockercompose is not available for an entry`);
     }
     if (entry.port !== null &&
         !(Number.isInteger(entry.port) && entry.port >= 1 && entry.port <= 65535)) {
-        return `${at} port must be a whole number from 1 to 65535, or null`;
+        return refusal('entry_port_invalid', `hosting.entries.${entry.key}.port`, `${at} port must be a whole number from 1 to 65535, or null`);
     }
     if (entry.healthPath !== null && !entry.healthPath.startsWith('/')) {
-        return `${at} healthPath must start with '/', or be null`;
+        return refusal('entry_health_path_invalid', `hosting.entries.${entry.key}.healthPath`, `${at} healthPath must start with '/', or be null`);
     }
     if (entry.capabilities !== undefined &&
         entry.capabilities !== 'restricted' &&
         entry.capabilities !== 'standard') {
-        return `${at} capabilities must be 'restricted' or 'standard'`;
+        return refusal('entry_capabilities_invalid', `hosting.entries.${entry.key}.capabilities`, `${at} capabilities must be 'restricted' or 'standard'`);
     }
     if (entry.database && !enabled) {
-        return `${at} database requires hosting.enabled`;
+        return refusal('entry_database_needs_hosting', `hosting.entries.${entry.key}.database`, `${at} database requires hosting.enabled`);
     }
     const invalidVolumes = validateEntryVolumes(entry, at);
     if (invalidVolumes)
         return invalidVolumes;
-    const invalidBlueGreen = validateBlueGreen(entry.blueGreen, at);
+    const invalidBlueGreen = refuseBlueGreen(entry.blueGreen, at, `hosting.entries.${entry.key}.blueGreen`);
     if (invalidBlueGreen)
         return invalidBlueGreen;
     if (entry.blueGreen !== undefined &&
-        entry.key !== APP_ENTRY_KEY &&
+        !isMainEntry(entry) &&
         !entry.hostnames.some((name) => name !== '*')) {
-        return `${at} blueGreen needs a public hostname: the release check reaches each color through it`;
+        return refusal('blue_green_needs_hostname', `hosting.entries.${entry.key}.blueGreen`, `${at} blueGreen needs a public hostname: the release check reaches each color through it`);
     }
     for (const [name, value] of Object.entries(entry.env)) {
         if (!name) {
-            return `${at} env needs a non-empty env var name`;
+            return refusal('env_name_empty', `hosting.entries.${entry.key}.env`, `${at} env needs a non-empty env var name`);
         }
         if (FOUNDRY_ENV_NAME.test(name) || (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
-            return `${at} env '${name}' is set by foundry and cannot be declared`;
+            return refusal('env_name_reserved', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' is set by foundry and cannot be declared`);
         }
         if (typeof value !== 'string') {
             if (value?.from === 'platformMailKey') {
-                return `${at} env '${name}' has an unknown source 'platformMailKey': each company uses its own mail key`;
+                return refusal('env_source_platform_mail_key', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' has an unknown source 'platformMailKey': each company uses its own mail key`);
             }
             if (!APP_ENV_SOURCES.has(value?.from)) {
-                return `${at} env '${name}' has an unknown source '${value?.from}'`;
+                return refusal('env_source_unknown', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' has an unknown source '${value?.from}'`);
             }
             if (value.from === 'sharedSecret' && !ENTRY_KEY.test(value.name ?? '')) {
-                return `${at} env '${name}' sharedSecret needs a name (lowercase letters, digits and hyphens)`;
+                return refusal('env_shared_secret_name_invalid', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' sharedSecret needs a name (lowercase letters, digits and hyphens)`);
             }
             if (value.from === 'heldSecret') {
                 if (value.name !== name) {
-                    return `${at} env '${name}' heldSecret name must be '${name}', the env name it is declared under`;
+                    return refusal('env_held_secret_name_mismatch', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' heldSecret name must be '${name}', the env name it is declared under`);
                 }
                 if (!HELD_ENV_NAME.test(name)) {
-                    return `${at} env '${name}' heldSecret needs an env name of letters, digits and underscores`;
+                    return refusal('env_held_secret_name_invalid', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' heldSecret needs an env name of letters, digits and underscores`);
                 }
             }
         }
         else if (SECRET_ENV_NAME.test(name) || (name.endsWith('_URL') && urlHasPassword(value))) {
-            return `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`;
+            return refusal('env_looks_like_secret', `hosting.entries.${entry.key}.env.${name}`, `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`);
         }
     }
     return null;
 }
 /** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
 export function validateBlueGreen(value, at) {
+    return refuseBlueGreen(value, at, at)?.message ?? null;
+}
+/** {@link validateBlueGreen} with the code; `path` is the dotted path of the `blueGreen` value. */
+function refuseBlueGreen(value, at, path) {
     if (value === undefined)
         return null;
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        return `${at} blueGreen must be an object`;
+        return refusal('blue_green_not_object', path, `${at} blueGreen must be an object`);
     }
     const { steps, stepHoldMinutes } = value;
     if (steps !== undefined) {
         if (!Array.isArray(steps) || steps.length === 0 || steps.length > 20) {
-            return `${at} blueGreen steps must be a list of 1 to 20 percentages`;
+            return refusal('blue_green_steps_length', `${path}.steps`, `${at} blueGreen steps must be a list of 1 to 20 percentages`);
         }
         if (!steps.every((n) => Number.isInteger(n) && n >= 1 && n <= 100)) {
-            return `${at} blueGreen steps must be whole numbers from 1 to 100`;
+            return refusal('blue_green_steps_range', `${path}.steps`, `${at} blueGreen steps must be whole numbers from 1 to 100`);
         }
         if (!steps.every((n, i) => i === 0 || n > steps[i - 1])) {
-            return `${at} blueGreen steps must be ascending`;
+            return refusal('blue_green_steps_order', `${path}.steps`, `${at} blueGreen steps must be ascending`);
         }
         if (steps[steps.length - 1] !== 100)
-            return `${at} blueGreen steps must end at 100`;
+            return refusal('blue_green_steps_end', `${path}.steps`, `${at} blueGreen steps must end at 100`);
     }
     if (stepHoldMinutes !== undefined &&
         !(Number.isInteger(stepHoldMinutes) && stepHoldMinutes >= 1 && stepHoldMinutes <= 1440)) {
-        return `${at} blueGreen stepHoldMinutes must be a whole number from 1 to 1440`;
+        return refusal('blue_green_hold_invalid', `${path}.stepHoldMinutes`, `${at} blueGreen stepHoldMinutes must be a whole number from 1 to 1440`);
     }
     return null;
 }
@@ -480,38 +501,38 @@ function validateEntryVolumes(entry, at) {
     if (volumes === undefined)
         return null;
     if (!Array.isArray(volumes))
-        return `${at} volumes must be a list`;
+        return refusal('volumes_not_list', `hosting.entries.${entry.key}.volumes`, `${at} volumes must be a list`);
     if (volumes.length > MAX_ENTRY_VOLUMES) {
-        return `${at} volumes holds at most ${MAX_ENTRY_VOLUMES} volumes`;
+        return refusal('volumes_too_many', `hosting.entries.${entry.key}.volumes`, `${at} volumes holds at most ${MAX_ENTRY_VOLUMES} volumes`);
     }
     const names = new Set();
     const paths = new Set();
     for (const volume of volumes) {
         const { name, mountPath } = volume ?? {};
         if (typeof name !== 'string' || !ENTRY_KEY.test(name)) {
-            return `${at} volumes needs a name that is a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`;
+            return refusal('volume_name_invalid', `hosting.entries.${entry.key}.volumes`, `${at} volumes needs a name that is a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`);
         }
         if (name === 'logs') {
-            return `${at} volumes name 'logs' is the log volume's, which every app already has`;
+            return refusal('volume_name_logs', `hosting.entries.${entry.key}.volumes`, `${at} volumes name 'logs' is the log volume's, which every app already has`);
         }
         if (names.has(name))
-            return `${at} volumes name '${name}' is not unique`;
+            return refusal('volume_name_not_unique', `hosting.entries.${entry.key}.volumes`, `${at} volumes name '${name}' is not unique`);
         names.add(name);
         if (typeof mountPath !== 'string' || !VOLUME_MOUNT_PATH.test(mountPath)) {
-            return `${at} volumes '${name}' mountPath must be an absolute path of letters, digits, '.', '_', '-' and '/', with no '..', no empty part and no trailing '/'`;
+            return refusal('volume_mount_path_invalid', `hosting.entries.${entry.key}.volumes`, `${at} volumes '${name}' mountPath must be an absolute path of letters, digits, '.', '_', '-' and '/', with no '..', no empty part and no trailing '/'`);
         }
         if (mountPath.length > VOLUME_MOUNT_PATH_MAX) {
-            return `${at} volumes '${name}' mountPath holds at most ${VOLUME_MOUNT_PATH_MAX} characters`;
+            return refusal('volume_mount_path_too_long', `hosting.entries.${entry.key}.volumes`, `${at} volumes '${name}' mountPath holds at most ${VOLUME_MOUNT_PATH_MAX} characters`);
         }
         if (mountPath === LOG_DIR_PATH || mountPath.startsWith(`${LOG_DIR_PATH}/`)) {
-            return `${at} volumes '${name}' mountPath ${LOG_DIR_PATH} is the log volume's, which every app already has`;
+            return refusal('volume_mount_path_log_dir', `hosting.entries.${entry.key}.volumes`, `${at} volumes '${name}' mountPath ${LOG_DIR_PATH} is the log volume's, which every app already has`);
         }
         if (mountPath === '/app' ||
             VOLUME_FORBIDDEN_ROOTS.some((root) => mountPath === root || mountPath.startsWith(`${root}/`))) {
-            return `${at} volumes '${name}' mountPath must not be /app or a system path (${VOLUME_FORBIDDEN_ROOTS.join(', ')})`;
+            return refusal('volume_mount_path_forbidden', `hosting.entries.${entry.key}.volumes`, `${at} volumes '${name}' mountPath must not be /app or a system path (${VOLUME_FORBIDDEN_ROOTS.join(', ')})`);
         }
         if (paths.has(mountPath))
-            return `${at} volumes mountPath '${mountPath}' is not unique`;
+            return refusal('volume_mount_path_not_unique', `hosting.entries.${entry.key}.volumes`, `${at} volumes mountPath '${mountPath}' is not unique`);
         paths.add(mountPath);
     }
     return null;
@@ -528,36 +549,36 @@ function validateEntryAuth(entry, hosting, domain) {
         return null;
     const at = `hosting.entries '${entry.key}' uses.auth`;
     if (!hosting.enabled)
-        return `${at} requires hosting.enabled`;
+        return refusal('auth_needs_hosting', `hosting.entries.${entry.key}.uses.auth`, `${at} requires hosting.enabled`);
     if (auth.users !== 'staff' && auth.users !== 'customers') {
-        return `${at} users must be 'staff' or 'customers'`;
+        return refusal('auth_users_invalid', `hosting.entries.${entry.key}.uses.auth.users`, `${at} users must be 'staff' or 'customers'`);
     }
     if (auth.registration !== 'open' && auth.registration !== 'closed') {
-        return `${at} registration must be 'open' or 'closed'`;
+        return refusal('auth_registration_invalid', `hosting.entries.${entry.key}.uses.auth.registration`, `${at} registration must be 'open' or 'closed'`);
     }
     // The staff organisation holds the org's own people and its project.
     if (auth.users === 'staff' && auth.registration === 'open') {
-        return `${at} registration 'open' needs users 'customers': nobody signs themselves up as staff`;
+        return refusal('registration_open_needs_customers', `hosting.entries.${entry.key}.uses.auth.registration`, `${at} registration 'open' needs users 'customers': nobody signs themselves up as staff`);
     }
     if (auth.replacesBrokerEntry !== undefined &&
         (typeof auth.replacesBrokerEntry !== 'string' || auth.replacesBrokerEntry === '')) {
-        return `${at} replacesBrokerEntry must be the non-empty name of a broker entry`;
+        return refusal('auth_replaces_broker_entry_invalid', `hosting.entries.${entry.key}.uses.auth.replacesBrokerEntry`, `${at} replacesBrokerEntry must be the non-empty name of a broker entry`);
     }
     if (typeof auth.replacesBrokerEntry === 'string' &&
         isFoundryOwnedBrokerEntryName(auth.replacesBrokerEntry)) {
-        return `${at} replacesBrokerEntry '${auth.replacesBrokerEntry}' is a broker entry foundry writes itself`;
+        return refusal('auth_replaces_broker_entry_owned', `hosting.entries.${entry.key}.uses.auth.replacesBrokerEntry`, `${at} replacesBrokerEntry '${auth.replacesBrokerEntry}' is a broker entry foundry writes itself`);
     }
     if (!hasExactHostname(entry, hosting, domain)) {
-        return `${at} needs an exact hostname to sign in at`;
+        return refusal('auth_needs_exact_hostname', `hosting.entries.${entry.key}.hostnames`, `${at} needs an exact hostname to sign in at`);
     }
     if (auth.mcp !== undefined) {
         if (auth.users !== 'customers' || auth.registration !== 'open') {
-            return `${at} mcp needs users 'customers' and registration 'open': an MCP client signs the customer in, and only customers register themselves`;
+            return refusal('mcp_needs_open_customers', `hosting.entries.${entry.key}.uses.auth.mcp`, `${at} mcp needs users 'customers' and registration 'open': an MCP client signs the customer in, and only customers register themselves`);
         }
         if (typeof auth.mcp?.path !== 'string' ||
             !MCP_PATH.test(auth.mcp.path) ||
             auth.mcp.path.length > 200) {
-            return `${at} mcp.path must be an absolute path of letters, digits, '_', '~' and '-' segments, such as '/mcp'`;
+            return refusal('mcp_path_invalid', `hosting.entries.${entry.key}.uses.auth.mcp.path`, `${at} mcp.path must be an absolute path of letters, digits, '_', '~' and '-' segments, such as '/mcp'`);
         }
         const onboarding = auth.mcp.onboardingPath;
         if (onboarding !== undefined &&
@@ -570,21 +591,21 @@ function validateEntryAuth(entry, hosting, domain) {
                 onboarding.includes('\\') ||
                 /[\s\p{Cc}]/u.test(onboarding) ||
                 onboarding.length > ONBOARDING_PATH_MAX_LENGTH)) {
-            return `${at} mcp.onboardingPath must be an absolute path that starts with '/', such as '/onboarding', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`;
+            return refusal('mcp_onboarding_path_invalid', `hosting.entries.${entry.key}.uses.auth.mcp.onboardingPath`, `${at} mcp.onboardingPath must be an absolute path that starts with '/', such as '/onboarding', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`);
         }
     }
     const signIn = auth.signIn;
     if (signIn !== undefined && signIn !== 'password' && signIn !== 'email-code') {
-        return `${at} signIn must be 'password' or 'email-code'`;
+        return refusal('auth_sign_in_invalid', `hosting.entries.${entry.key}.uses.auth.signIn`, `${at} signIn must be 'password' or 'email-code'`);
     }
     if (signIn === 'email-code' && auth.users !== 'customers') {
-        return `${at} signIn 'email-code' needs users 'customers': only customers sign in with an emailed code`;
+        return refusal('email_code_needs_customers', `hosting.entries.${entry.key}.uses.auth.signIn`, `${at} signIn 'email-code' needs users 'customers': only customers sign in with an emailed code`);
     }
     if (entry.key === 'agora' ||
         entry.key === 'boule' ||
         entry.key === 'cms' ||
         hosting.issuerApps.some((app) => app.name === entry.key)) {
-        return `${at} client name '${entry.key}' is already held by another ZITADEL client`;
+        return refusal('client_name_taken', `hosting.entries.${entry.key}.key`, `${at} client name '${entry.key}' is already held by another ZITADEL client`);
     }
     return null;
 }
@@ -594,7 +615,7 @@ function hasExactHostname(entry, hosting, domain) {
         return true; // Its host is workerApp.host, or <slug>[-<key>].oikos.host.
     return hosting.usesDomain && domain !== null
         ? entry.hostnames.some((name) => name !== '*')
-        : entry.key === APP_ENTRY_KEY;
+        : isMainEntry(entry);
 }
 /**
  * `uses.ai`: at least one offering, permissions from the known set, a
@@ -607,32 +628,32 @@ function validateEntryAi(entry, hosting, domain) {
         return null;
     const at = `hosting.entries '${entry.key}' uses.ai`;
     if (!hosting.enabled)
-        return `${at} requires hosting.enabled`;
+        return refusal('ai_needs_hosting', `hosting.entries.${entry.key}.uses.ai`, `${at} requires hosting.enabled`);
     const isNames = (value) => Array.isArray(value) &&
         value.length > 0 &&
         value.every((v) => typeof v === 'string' && v !== '') &&
         new Set(value).size === value.length;
     if (!isNames(ai.offerings))
-        return `${at} offerings must be a list of distinct, non-empty names`;
+        return refusal('ai_offerings_invalid', `hosting.entries.${entry.key}.uses.ai.offerings`, `${at} offerings must be a list of distinct, non-empty names`);
     if (ai.permissions !== undefined) {
         const known = AI_ENTRY_PERMISSIONS;
         if (!isNames(ai.permissions) || !ai.permissions.every((p) => known.includes(p))) {
-            return `${at} permissions must be distinct values of: ${known.join(', ')}`;
+            return refusal('ai_permissions_invalid', `hosting.entries.${entry.key}.uses.ai.permissions`, `${at} permissions must be distinct values of: ${known.join(', ')}`);
         }
     }
     if (ai.webhookPath !== undefined) {
         if (typeof ai.webhookPath !== 'string' ||
             !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,199}$/.test(ai.webhookPath) ||
             ai.webhookPath.startsWith('//')) {
-            return `${at} webhookPath must be a path that starts with one '/', with no query or fragment`;
+            return refusal('ai_webhook_path_invalid', `hosting.entries.${entry.key}.uses.ai.webhookPath`, `${at} webhookPath must be a path that starts with one '/', with no query or fragment`);
         }
         if (!hasExactHostname(entry, hosting, domain)) {
-            return `${at} webhookPath needs an exact hostname to receive the webhook at`;
+            return refusal('ai_webhook_needs_exact_hostname', `hosting.entries.${entry.key}.uses.ai.webhookPath`, `${at} webhookPath needs an exact hostname to receive the webhook at`);
         }
     }
     const named = Object.keys(entry.env ?? {}).find((name) => AI_ENTRY_ENV_NAMES.includes(name));
     if (named)
-        return `${at} writes ${named}; remove it from env`;
+        return refusal('ai_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
     return null;
 }
 /**
@@ -646,31 +667,31 @@ function validateEntryFiles(entry, hosting, domain) {
         return null;
     const at = `hosting.entries '${entry.key}' uses.files`;
     if (!hosting.enabled)
-        return `${at} requires hosting.enabled`;
+        return refusal('files_needs_hosting', `hosting.entries.${entry.key}.uses.files`, `${at} requires hosting.enabled`);
     const names = (value) => Array.isArray(value) &&
         value.every((v) => typeof v === 'string' && v !== '') &&
         new Set(value).size === value.length;
     if (!names(files.collections) || !files.collections.every((n) => /^[A-Z][A-Z0-9_]*$/.test(n))) {
-        return `${at} collections must be distinct names of uppercase letters, digits and '_', starting with a letter`;
+        return refusal('files_collections_invalid', `hosting.entries.${entry.key}.uses.files.collections`, `${at} collections must be distinct names of uppercase letters, digits and '_', starting with a letter`);
     }
     if (files.permissions !== undefined) {
         const known = FILES_ENTRY_PERMISSIONS;
         if (!names(files.permissions) ||
             files.permissions.length === 0 ||
             !files.permissions.every((p) => known.includes(p))) {
-            return `${at} permissions must be distinct values of: ${known.join(', ')}`;
+            return refusal('files_permissions_invalid', `hosting.entries.${entry.key}.uses.files.permissions`, `${at} permissions must be distinct values of: ${known.join(', ')}`);
         }
     }
     if (files.shareHost !== undefined && typeof files.shareHost !== 'boolean') {
-        return `${at} shareHost must be true or false`;
+        return refusal('files_share_host_invalid', `hosting.entries.${entry.key}.uses.files.shareHost`, `${at} shareHost must be true or false`);
     }
     if (files.shareHost && !(hosting.usesDomain && domain)) {
-        return `${at} shareHost needs hosting.usesDomain and a domain: it is served at share.<domain>`;
+        return refusal('files_share_host_needs_domain', `hosting.entries.${entry.key}.uses.files.shareHost`, `${at} shareHost needs hosting.usesDomain and a domain: it is served at share.<domain>`);
     }
     const written = [...FILES_ENTRY_ENV_NAMES, ...files.collections.map(filesCollectionEnvName)];
     const named = Object.keys(entry.env ?? {}).find((name) => written.includes(name));
     if (named)
-        return `${at} writes ${named}; remove it from env`;
+        return refusal('files_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
     return null;
 }
 /** A route pattern's zone apex: the host part before the first `/`, with one leading `*.` label stripped. */
@@ -708,35 +729,36 @@ function validateEntryWorker(entry, hosting, domain) {
         return null;
     const at = `hosting.entries '${entry.key}' worker`;
     if (!hosting.enabled)
-        return `${at} requires hosting.enabled`;
+        return refusal('worker_needs_hosting', `hosting.entries.${entry.key}.worker`, `${at} requires hosting.enabled`);
     if (entry.repo === null) {
-        return `${at} needs its own repo (repo: null is not a Worker source)`;
+        return refusal('worker_needs_repo', `hosting.entries.${entry.key}.repo`, `${at} needs its own repo (repo: null is not a Worker source)`);
     }
     if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
-        return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "-edge") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`;
+        return refusal('worker_key_too_long', `hosting.entries.${entry.key}.key`, `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "-edge") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`);
     }
     const invalidArtifact = validateArtifact(at, worker.artifactUrl, worker.artifactSha256, entry.repo);
-    if (invalidArtifact)
-        return invalidArtifact;
+    if (invalidArtifact) {
+        return refusal('worker_artifact_invalid', `hosting.entries.${entry.key}.worker`, invalidArtifact);
+    }
     if (!WORKER_ROUTE.test(worker.route)) {
-        return `${at} route must be a hostname (an optional leading '*.' label, then at least two more labels) and a path, joined by '/'`;
+        return refusal('worker_route_invalid', `hosting.entries.${entry.key}.worker.route`, `${at} route must be a hostname (an optional leading '*.' label, then at least two more labels) and a path, joined by '/'`);
     }
     const zone = workerRouteZone(worker.route);
     if (!domain || zone !== domain) {
-        return `${at} route '${worker.route}' must be on the org's own domain${domain ? ` (${domain})` : ''}: worker is only for our own projects`;
+        return refusal('worker_route_off_domain', `hosting.entries.${entry.key}.worker.route`, `${at} route '${worker.route}' must be on the org's own domain${domain ? ` (${domain})` : ''}: worker is only for our own projects`);
     }
     // A wildcard route (`*.<domain>/*`) is allowed beside hostnames foundry owns:
     // `planWorkers` plans a no-Worker route for each of them, so they stay out of it.
     for (const limit of worker.bindings?.rateLimits ?? []) {
         if (!limit.name.trim())
-            return `${at} bindings.rateLimits needs a non-empty name`;
+            return refusal('worker_rate_limit_name_missing', `hosting.entries.${entry.key}.worker.bindings.rateLimits`, `${at} bindings.rateLimits needs a non-empty name`);
         if (!limit.namespaceId.trim())
-            return `${at} bindings.rateLimits needs a non-empty namespaceId`;
+            return refusal('worker_rate_limit_namespace_missing', `hosting.entries.${entry.key}.worker.bindings.rateLimits`, `${at} bindings.rateLimits needs a non-empty namespaceId`);
         if (!(Number.isInteger(limit.limit) && limit.limit > 0)) {
-            return `${at} bindings.rateLimits limit must be a positive whole number`;
+            return refusal('worker_rate_limit_invalid', `hosting.entries.${entry.key}.worker.bindings.rateLimits`, `${at} bindings.rateLimits limit must be a positive whole number`);
         }
         if (limit.period !== 10 && limit.period !== 60) {
-            return `${at} bindings.rateLimits period must be 10 or 60 (Cloudflare allows no other value)`;
+            return refusal('worker_rate_limit_period_invalid', `hosting.entries.${entry.key}.worker.bindings.rateLimits`, `${at} bindings.rateLimits period must be 10 or 60 (Cloudflare allows no other value)`);
         }
     }
     return null;
@@ -752,15 +774,15 @@ function validateEntryEdge(entry, hosting, domain) {
         return null;
     const at = `hosting.entries '${entry.key}' uses.edge`;
     if (edge !== true)
-        return `${at} must be true`;
+        return refusal('edge_not_true', `hosting.entries.${entry.key}.uses.edge`, `${at} must be true`);
     if (!hosting.enabled)
-        return `${at} requires hosting.enabled`;
+        return refusal('edge_needs_hosting', `hosting.entries.${entry.key}.uses.edge`, `${at} requires hosting.enabled`);
     if (!hosting.usesDomain || !domain) {
-        return `${at} needs hosting.usesDomain and an org domain: edge serves only the org's own domain`;
+        return refusal('edge_needs_domain', `hosting.entries.${entry.key}.uses.edge`, `${at} needs hosting.usesDomain and an org domain: edge serves only the org's own domain`);
     }
     const named = Object.keys(entry.env ?? {}).find((name) => EDGE_ENTRY_ENV_NAMES.includes(name));
     if (named)
-        return `${at} writes ${named}; remove it from env`;
+        return refusal('edge_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
     return null;
 }
 function urlHasPassword(value) {
@@ -984,6 +1006,10 @@ export function validateSignIn(org) {
  * the customers organisation.
  */
 export function validateCustomers(org) {
+    return refuseCustomers(org)?.message ?? null;
+}
+/** {@link validateCustomers} with the code and path of the refusal. */
+export function refuseCustomers(org) {
     const customers = org.customers;
     if (customers !== undefined) {
         const value = customers;
@@ -993,14 +1019,15 @@ export function validateCustomers(org) {
             typeof value?.enabled !== 'boolean' ||
             typeof value?.signUp !== 'boolean' ||
             Object.keys(customers).some((key) => key !== 'enabled' && key !== 'signUp')) {
-            return 'customers must be { enabled: boolean, signUp: boolean }';
+            return refusal('customers_invalid', 'customers', 'customers must be { enabled: boolean, signUp: boolean }');
+        }
+        if (value.signUp && !value.enabled) {
+            return refusal('customers_sign_up_needs_enabled', 'customers.signUp', 'customers.signUp needs customers.enabled');
         }
-        if (value.signUp && !value.enabled)
-            return 'customers.signUp needs customers.enabled';
     }
     const open = org.hosting.entries.find((entry) => entry.uses?.auth?.registration === 'open');
     if (open && !(org.customers?.enabled && org.customers.signUp)) {
-        return `hosting.entries '${open.key}' uses.auth registration 'open' needs customers.enabled and customers.signUp`;
+        return refusal('registration_open_needs_sign_up', `hosting.entries.${open.key}.uses.auth.registration`, `hosting.entries '${open.key}' uses.auth registration 'open' needs customers.enabled and customers.signUp`);
     }
     return null;
 }