@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/org.js

@@ -1,6 +1,9 @@
 import { DEFAULT_RULES, checkName, explain } from '@wtfalch/auth/names';
 import { floatingRefBlocked, floatingTagBlocked } from './bootstrap/versions.js';
+import { AI_ENTRY_PERMISSIONS, AI_WEBHOOK_PATH, FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, ROOM_UNSAFE_TEXT, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, isPagePath, } from './entry-rules.js';
+import { hostedLabelRefusal } from './hosted-label.js';
 import { entryHasDatabase, validateArtifact, validateEntryWorkerApp, } from './worker-app-config.js';
+export { AI_ENTRY_PERMISSIONS, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, } from './entry-rules.js';
 /** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
 export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
 /** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
@@ -13,24 +16,29 @@ export const APP_ENTRY_KEY = 'app';
 function refusal(code, path, message) {
     return { code, path, message };
 }
+export const MAX_PRIVATE_PAGES = 20;
+export const MAX_PRIVATE_PAGE_ROLES = 50;
+export const MAX_PRIVATE_PAGE_PEOPLE = 200;
+export const PRIVATE_PAGE_PATH = /^(\/[A-Za-z0-9._~-]+)+$/;
+/** The keys of the Access gates private pages get: `pp-` (live) or `wp-` (workspace) and 16 hex characters. */
+export const PRIVATE_PAGE_GATE_KEY = /^(pp|wp)-[0-9a-f]{16}$/;
+/** A full git commit: 40 lowercase hex characters. */
+export const FULL_COMMIT_SHA = /^[0-9a-f]{40}$/;
+export const MAX_WORKSPACE_TESTERS = 50;
+/** An entry is live unless it says `live: false`. */
+export const isLiveEntry = (entry) => entry.live !== false;
+/** Trimmed, lowercased and distinct testers, in the order first seen. The planner and hosts read testers through this. */
+export function normalizeTesters(testers) {
+    return [...new Set(testers.map((email) => email.trim().toLowerCase()))];
+}
+/** True while the company's Boule runs apps (`org.boule.apps`). */
+export const appsOn = (org) => org.boule?.apps === true;
+/** True while the company's kosmos is turned on (`org.kosmos.enabled`). */
+export const kosmosOn = (org) => org.kosmos?.enabled === true;
 /** The most volumes one entry may declare. */
 export const MAX_ENTRY_VOLUMES = 8;
-/** Longest value of each `uses.auth.room` text field. */
-export const ROOM_TEXT_MAX = {
-    name: 40,
-    headline: 120,
-    line: 200,
-    title: 60,
-    description: 200,
-};
-export const ROOM_STEPS_MIN = 2;
-export const ROOM_STEPS_MAX = 9;
-/** `uses.auth.mcp.onboardingPath`: absolute, no query, no fragment, no dot segments. */
-export const ONBOARDING_PATH_MAX_LENGTH = 200;
-/** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
-export const MCP_PATH = /^\/[A-Za-z0-9_~-]+(\/[A-Za-z0-9_~-]+)*$|^\/$/;
-/** What an entry's ai key may hold: the most the org's own key holds. */
-export const AI_ENTRY_PERMISSIONS = ['ai.offerings:invoke', 'ai.runs:create'];
+/** The env names `uses.auth.workspaces` writes; `env` may not name them. */
+export const WORKSPACES_ENTRY_ENV_NAMES = ['WORKSPACES_URL', 'WORKSPACES_API_KEY'];
 /** The env names `uses.ai` writes; `env` may not name them. */
 export const AI_ENTRY_ENV_NAMES = [
     'AI_URL',
@@ -39,15 +47,6 @@ export const AI_ENTRY_ENV_NAMES = [
     'AI_WEBHOOK_SECRET',
     'AI_OFFERINGS_JSON',
 ];
-/** What an entry's files key may hold: read and write on its collections, and the most the org's own key holds besides minting. */
-export const FILES_ENTRY_PERMISSIONS = [
-    'files.collections:read',
-    'files.files:read',
-    'files.files:download',
-    'files.files:upload',
-    'files.files:replace',
-    'files.files:delete',
-];
 /** The env names `uses.files` always writes, besides one `FILES_COLLECTION_<NAME>_ID` per collection. */
 export const FILES_ENTRY_ENV_NAMES = [
     'FILES_URL',
@@ -57,6 +56,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 env names `uses.mail` writes; `env` may not name them. */
+export const MAIL_ENTRY_ENV_NAMES = ['LETTERMINT_API_TOKEN', 'MAIL_FROM'];
+/** The env names `uses.jobs` writes; `env` may not name them. */
+export const JOBS_ENTRY_ENV_NAMES = [
+    'JOBS_SCHEDULER_URL',
+    'JOBS_SIGNING_SECRET',
+    'JOBS_SYNC_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;
@@ -161,6 +168,9 @@ export function refuseHosting(hosting, names) {
     const badRepos = refuseHostingRepos(hosting.repos);
     if (badRepos)
         return badRepos;
+    const badGithub = refuseHostingGithub(hosting.github);
+    if (badGithub)
+        return badGithub;
     if (hosting.tunnel && !hosting.enabled) {
         return refusal('hosting_tunnel_needs_hosting', 'hosting.tunnel', 'hosting.tunnel requires hosting.enabled');
     }
@@ -192,16 +202,31 @@ export function refuseHosting(hosting, names) {
     if (hosting.enabled && hosting.entries.length === 0) {
         return refusal('hosting_needs_entry', 'hosting.entries', 'hosting.enabled requires at least one entry');
     }
-    const reserveKeys = names?.builtinBlueGreen === true || hosting.entries.some((e) => e.blueGreen !== undefined);
+    const reserveKeys = names?.builtinBlueGreen === true ||
+        hosting.entries.some((e) => e.blueGreen !== undefined || e.workspace !== undefined);
     const seenKeys = new Set();
+    const seenHostedNames = new Set();
     for (const entry of hosting.entries) {
         if (seenKeys.has(entry.key)) {
             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, reserveKeys);
+        const invalid = validateHostingEntry(entry, hosting.enabled, reserveKeys, hosting.github);
         if (invalid)
             return invalid;
+        if (entry.hostedName !== undefined) {
+            const path = `hosting.entries.${entry.key}.hostedName`;
+            const bad = hostedLabelRefusal(entry.hostedName);
+            if (bad)
+                return refusal('hosted_name_invalid', path, bad.message);
+            if (entry.workerApp) {
+                return refusal('hosted_name_worker_app', path, 'A Worker app is served at the address its own host setting names. An app address on companyincluded.app is for apps that run as servers.');
+            }
+            if (seenHostedNames.has(entry.hostedName)) {
+                return refusal('hosted_name_not_unique', path, 'Two apps in this company cannot use the same app address. Choose a different one for one of them.');
+            }
+            seenHostedNames.add(entry.hostedName);
+        }
         const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
         if (invalidAuth)
             return invalidAuth;
@@ -221,6 +246,18 @@ export function refuseHosting(hosting, names) {
         const invalidEdgeUse = validateEntryEdge(entry, hosting, names?.domain);
         if (invalidEdgeUse)
             return invalidEdgeUse;
+        const invalidMailJobs = validateEntryMailJobs(entry, hosting);
+        if (invalidMailJobs)
+            return invalidMailJobs;
+        const invalidGrants = validateEntryCustomerGrants(entry);
+        if (invalidGrants)
+            return invalidGrants;
+        const invalidRepoUse = validateEntryRepoUse(entry);
+        if (invalidRepoUse)
+            return invalidRepoUse;
+        const invalidAuditUse = validateEntryAudit(entry, hosting);
+        if (invalidAuditUse)
+            return invalidAuditUse;
     }
     const mains = hosting.entries.filter(isMainEntry);
     if (mains.length > 1) {
@@ -317,6 +354,14 @@ function validateGates(hosting, domain, locked) {
         return refusal('gate_limit_invalid', 'hosting.gateLimit', 'hosting.gateLimit must be a positive whole number');
     }
     const seenKeys = new Set();
+    const workspaceGateKeys = new Set();
+    for (const entry of hosting.entries) {
+        if (entry.workspace === undefined)
+            continue;
+        workspaceGateKeys.add(`ws-${entry.key}`);
+        if (entry.workerApp === undefined)
+            workspaceGateKeys.add('ws--inbox');
+    }
     for (const entry of hosting.entries) {
         const taken = new Set();
         for (const gate of entry.gates) {
@@ -327,6 +372,12 @@ function validateGates(hosting, domain, locked) {
             if (!ENTRY_KEY.test(gate.key)) {
                 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 (workspaceGateKeys.has(gate.key)) {
+                return refusal('gate_key_taken_by_workspace', `hosting.entries.${entry.key}.gates.${gate.key}.key`, `${at} key is used for a private workspace's sign-in. Choose a different key.`);
+            }
+            if (PRIVATE_PAGE_GATE_KEY.test(gate.key)) {
+                return refusal('gate_key_taken_by_private_page', `hosting.entries.${entry.key}.gates.${gate.key}.key`, `${at} key is used for a private page's sign-in. Choose a different key.`);
+            }
             if (seenKeys.has(gate.key))
                 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);
@@ -400,7 +451,7 @@ function validateEntryHostnames(hosting, names) {
 }
 const ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 /** Names of the parts blue/green adds to an app (`<app>-stage`, `-blue`, `-green`, `-lb`): an entry of that name would adopt one. */
-const RESERVED_ENTRY_KEY = /^(stage|blue|green|lb)$|-(stage|blue|green|lb)$/;
+const RESERVED_ENTRY_KEY = /^(stage|blue|green|lb|apps-db)$|-(stage|blue|green|lb)$/;
 const VOLUME_MOUNT_PATH = /^(\/(?!\.\.?(\/|$))[A-Za-z0-9._-]+)+$/;
 /** The log volume's mount path; `executor.ts`'s `LOG_DIR` is the same value. */
 const LOG_DIR_PATH = '/app/logs';
@@ -422,6 +473,46 @@ const VOLUME_FORBIDDEN_ROOTS = [
 const VOLUME_MOUNT_PATH_MAX = 255;
 const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
 const HOSTING_REPO = /^wtfalch\/[A-Za-z0-9._-]{1,100}$/;
+const GITHUB_ACCOUNT = /^[A-Za-z0-9-]{1,39}$/;
+const REPO_NAME = /^[A-Za-z0-9._-]+$/;
+/** The account whose repos the platform's own source builds; a company cannot claim it as its own. */
+const PLATFORM_GITHUB_ACCOUNT = 'wtfalch';
+/** The rules for `hosting.github`: a positive integer installation id and a GitHub login (1-39 letters, digits, hyphens) that is not the platform's own. */
+function refuseHostingGithub(github) {
+    const invalid = (message) => refusal('hosting_github_invalid', 'hosting.github', message);
+    if (github === undefined)
+        return null;
+    if (typeof github !== 'object' || github === null)
+        return invalid('hosting.github must be an object');
+    const { installationId, account } = github;
+    if (typeof installationId !== 'number' ||
+        !Number.isSafeInteger(installationId) ||
+        installationId <= 0) {
+        return invalid('hosting.github.installationId must be a positive integer');
+    }
+    if (typeof account !== 'string' || !GITHUB_ACCOUNT.test(account)) {
+        return invalid('hosting.github.account must be a GitHub login: 1-39 letters, digits or hyphens');
+    }
+    if (account.toLowerCase() === PLATFORM_GITHUB_ACCOUNT) {
+        return invalid(`hosting.github.account cannot be ${PLATFORM_GITHUB_ACCOUNT}, the platform's own account`);
+    }
+    return null;
+}
+/** True when `repo` is `<account>/<name>` with the account compared ignoring case. */
+function repoUnderAccount(repo, account) {
+    const slash = repo.indexOf('/');
+    return (slash > 0 &&
+        repo.slice(0, slash).toLowerCase() === account.toLowerCase() &&
+        REPO_NAME.test(repo.slice(slash + 1)));
+}
+/**
+ * The company's GitHub config when `repo` is under its account, else `undefined`: such an entry is built
+ * through the company's own Coolify source, any other through the platform's. Read it only through this.
+ */
+export function companyGithubFor(hosting, repo) {
+    const github = hosting.github;
+    return github && repo !== null && repoUnderAccount(repo, github.account) ? github : undefined;
+}
 // The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
 const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
 // Set only on the colors of a blueGreen entry; any other entry may declare them.
@@ -429,16 +520,126 @@ const BLUE_GREEN_ENV_NAME = /^(REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)|NEXT_SERVE
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
 const HELD_SECRETS = "declare it as { from: 'heldSecret' }, not a plain value";
 /** The rules for one {@link HostingEntry}; `null` when it is valid. */
-function validateHostingEntry(entry, enabled, reserveKeys) {
+/** Why an entry's `workspace` and `live` are refused, or `null`. */
+function validateEntryWorkspace(entry, at, hostingEnabled) {
+    const path = `hosting.entries.${entry.key}`;
+    if (entry.live !== undefined && typeof entry.live !== 'boolean') {
+        return refusal('entry_workspace_invalid', `${path}.live`, `${at} live must be true or false`);
+    }
+    if (entry.liveCommit !== undefined) {
+        const commitAt = `${path}.liveCommit`;
+        if (typeof entry.liveCommit !== 'string' || !FULL_COMMIT_SHA.test(entry.liveCommit)) {
+            return refusal('entry_live_commit_invalid', commitAt, `${at} liveCommit must be a full commit: 40 lowercase letters a-f and digits`);
+        }
+        if (entry.workspace === undefined || entry.workerApp !== undefined) {
+            return refusal('entry_live_commit_invalid', commitAt, `${at} liveCommit needs a workspace and an app that runs as a server`);
+        }
+    }
+    if (entry.workspace === undefined) {
+        return entry.live === false
+            ? refusal('entry_live_needs_workspace', `${path}.live`, `${at} live false needs a workspace: with neither, the app would exist nowhere`)
+            : null;
+    }
+    const unsupported = (message) => refusal('entry_workspace_unsupported', `${path}.workspace`, `${at} ${message}`);
+    if (!hostingEnabled)
+        return unsupported('workspace requires hosting.enabled');
+    if (entry.blueGreen !== undefined) {
+        return unsupported('workspace cannot be combined with blueGreen: the workspace is the stage, and an entry has one');
+    }
+    if (entry.worker !== undefined) {
+        return unsupported('workspace cannot be combined with a plain Worker');
+    }
+    if (entry.workerApp?.database !== undefined) {
+        return unsupported('workspace cannot be combined with a Worker app that has a database: its workspace would have to share the live one');
+    }
+    if (entry.repo === null && entry.workerApp === undefined) {
+        return unsupported('workspace needs a repo or a Worker app to run');
+    }
+    const { testers } = entry.workspace;
+    if (!Array.isArray(testers)) {
+        return refusal('entry_workspace_invalid', `${path}.workspace.testers`, `${at} workspace testers must be a list of email addresses`);
+    }
+    if (testers.length > MAX_WORKSPACE_TESTERS) {
+        return refusal('entry_workspace_invalid', `${path}.workspace.testers`, `${at} workspace can have at most ${MAX_WORKSPACE_TESTERS} testers`);
+    }
+    const seen = new Set();
+    for (const email of testers) {
+        if (typeof email !== 'string' || email.length > 254 || !OWNER_EMAIL_PATTERN.test(email)) {
+            return refusal('entry_workspace_invalid', `${path}.workspace.testers`, `${at} workspace tester '${String(email).slice(0, 80)}' is not a valid email address`);
+        }
+        const key = email.toLowerCase();
+        if (seen.has(key)) {
+            return refusal('entry_workspace_invalid', `${path}.workspace.testers`, `${at} workspace tester '${email}' is listed more than once`);
+        }
+        seen.add(key);
+    }
+    return null;
+}
+/** Why an entry's `privatePages` are refused, or `null`. */
+function validateEntryPrivatePages(entry, at, hostingEnabled) {
+    const pages = entry.privatePages;
+    if (pages === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.privatePages`;
+    if (!Array.isArray(pages)) {
+        return refusal('private_page_invalid', path, `${at} privatePages must be a list`);
+    }
+    if (pages.length === 0)
+        return null;
+    if (!hostingEnabled) {
+        return refusal('private_page_needs_hosting', path, `${at} private pages need hosting.enabled: there is no address to protect`);
+    }
+    if (pages.length > MAX_PRIVATE_PAGES) {
+        return refusal('private_page_limit', path, `${at} can have at most ${MAX_PRIVATE_PAGES} private pages`);
+    }
+    const seen = new Set();
+    for (const [index, page] of pages.entries()) {
+        const pageAt = `${path}.${index}`;
+        if (page === null || typeof page !== 'object') {
+            return refusal('private_page_invalid', pageAt, `${at} private page ${index + 1} must be an object`);
+        }
+        const pagePath = page.path;
+        if (typeof pagePath !== 'string' ||
+            pagePath.length > 200 ||
+            !PRIVATE_PAGE_PATH.test(pagePath) ||
+            pagePath.split('/').some((part) => part === '.' || part === '..')) {
+            return refusal('private_page_path_invalid', `${pageAt}.path`, `${at} private page path '${String(pagePath).slice(0, 80)}' must start with '/', hold only letters, digits and . _ ~ - /, have no query or trailing slash, and be more than '/' (200 characters at most)`);
+        }
+        if (seen.has(pagePath)) {
+            return refusal('private_page_duplicate', `${pageAt}.path`, `${at} private page '${pagePath}' is listed more than once`);
+        }
+        seen.add(pagePath);
+        const { roles } = page;
+        if (!Array.isArray(roles) ||
+            roles.length > MAX_PRIVATE_PAGE_ROLES ||
+            roles.some((role) => typeof role !== 'string' || role === '' || role.length > 100) ||
+            new Set(roles).size !== roles.length) {
+            return refusal('private_page_roles_invalid', `${pageAt}.roles`, `${at} private page '${pagePath}' roles must be a list of at most ${MAX_PRIVATE_PAGE_ROLES} distinct non-empty role ids`);
+        }
+        const { people } = page;
+        if (people !== undefined &&
+            (!Array.isArray(people) ||
+                people.length > MAX_PRIVATE_PAGE_PEOPLE ||
+                people.some((email) => typeof email !== 'string' || email.length > 254 || !OWNER_EMAIL_PATTERN.test(email)))) {
+            return refusal('private_page_people_invalid', `${pageAt}.people`, `${at} private page '${pagePath}' people must be a list of at most ${MAX_PRIVATE_PAGE_PEOPLE} valid email addresses`);
+        }
+    }
+    return null;
+}
+function validateHostingEntry(entry, enabled, reserveKeys, github) {
     const at = `hosting.entries '${entry.key}'`;
     if (!ENTRY_KEY.test(entry.key)) {
         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 (reserveKeys && RESERVED_ENTRY_KEY.test(entry.key)) {
-        return refusal('entry_key_reserved', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is reserved: stage, blue, green and lb, and any key ending in -stage, -blue, -green or -lb, name the parts blue/green adds to an app`);
+        return refusal('entry_key_reserved', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is reserved: apps-db (the company's apps database route), stage, blue, green and lb, and any key ending in -stage, -blue, -green or -lb, name the parts blue/green adds to an app`);
     }
-    if (entry.repo !== null && !REPO.test(entry.repo)) {
-        return refusal('entry_repo_invalid', `hosting.entries.${entry.key}.repo`, `${at} repo must be a repo under wtfalch, or null`);
+    if (entry.repo !== null &&
+        !REPO.test(entry.repo) &&
+        !(github && repoUnderAccount(entry.repo, github.account))) {
+        return refusal('entry_repo_invalid', `hosting.entries.${entry.key}.repo`, github
+            ? `${at} repo must be a repo under wtfalch or under ${github.account}, or null`
+            : `${at} repo must be a repo under wtfalch, or null`);
     }
     if (entry.folder !== null && (entry.folder.startsWith('/') || entry.folder.includes('..'))) {
         return refusal('entry_folder_invalid', `hosting.entries.${entry.key}.folder`, `${at} folder must be a relative path inside the repo`);
@@ -473,6 +674,12 @@ function validateHostingEntry(entry, enabled, reserveKeys) {
     const invalidBlueGreen = refuseBlueGreen(entry.blueGreen, at, `hosting.entries.${entry.key}.blueGreen`);
     if (invalidBlueGreen)
         return invalidBlueGreen;
+    const invalidWorkspace = validateEntryWorkspace(entry, at, enabled);
+    if (invalidWorkspace)
+        return invalidWorkspace;
+    const invalidPrivatePages = validateEntryPrivatePages(entry, at, enabled);
+    if (invalidPrivatePages)
+        return invalidPrivatePages;
     if (entry.blueGreen !== undefined &&
         !isMainEntry(entry) &&
         !entry.hostnames.some((name) => name !== '*')) {
@@ -521,7 +728,7 @@ function refuseBlueGreen(value, at, path) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         return refusal('blue_green_not_object', path, `${at} blueGreen must be an object`);
     }
-    const { steps, stepHoldMinutes } = value;
+    const { steps, stepHoldMinutes, advance, minRequests, errorMargin, staffFirst } = value;
     if (steps !== undefined) {
         if (!Array.isArray(steps) || steps.length === 0 || steps.length > 20) {
             return refusal('blue_green_steps_length', `${path}.steps`, `${at} blueGreen steps must be a list of 1 to 20 percentages`);
@@ -539,11 +746,33 @@ function refuseBlueGreen(value, at, path) {
         !(Number.isInteger(stepHoldMinutes) && stepHoldMinutes >= 1 && stepHoldMinutes <= 1440)) {
         return refusal('blue_green_hold_invalid', `${path}.stepHoldMinutes`, `${at} blueGreen stepHoldMinutes must be a whole number from 1 to 1440`);
     }
+    if (advance !== undefined &&
+        advance !== 'time' &&
+        advance !== 'signal' &&
+        advance !== 'approval') {
+        return refusal('blue_green_advance_invalid', `${path}.advance`, `${at} blueGreen advance must be time, signal or approval`);
+    }
+    if (minRequests !== undefined &&
+        !(Number.isInteger(minRequests) && minRequests >= 1 && minRequests <= 100000)) {
+        return refusal('blue_green_min_requests_invalid', `${path}.minRequests`, `${at} blueGreen minRequests must be a whole number from 1 to 100000`);
+    }
+    if (errorMargin !== undefined &&
+        !(typeof errorMargin === 'number' && errorMargin >= 0 && errorMargin <= 1)) {
+        return refusal('blue_green_error_margin_invalid', `${path}.errorMargin`, `${at} blueGreen errorMargin must be a number from 0 to 1`);
+    }
+    if (staffFirst !== undefined && typeof staffFirst !== 'boolean') {
+        return refusal('blue_green_staff_first_invalid', `${path}.staffFirst`, `${at} blueGreen staffFirst must be true or false`);
+    }
     return null;
 }
-/** {@link refuseBlueGreen} for the `blueGreen` of the company's Boule and Agora; the same codes. */
+/**
+ * {@link refuseBlueGreen} for the `blueGreen` of the company's Boule, Agora and kosmos; the same codes.
+ * Also refuses an `issuerApps` entry named `kosmos` while kosmos is on -- the same reservation
+ * {@link refuseHosting}'s own loop already gives Agora and Boule, but kosmos is opt-in, so it is checked here
+ * instead, the same way {@link validateSite} reserves `cms` only while `site.enabled` is true.
+ */
 export function refuseBuiltinBlueGreen(org) {
-    for (const app of ['boule', 'agora']) {
+    for (const app of ['boule', 'agora', 'kosmos']) {
         const value = org[app];
         if (value === undefined)
             continue;
@@ -553,6 +782,21 @@ export function refuseBuiltinBlueGreen(org) {
         const refused = refuseBlueGreen(value.blueGreen, app, `${app}.blueGreen`);
         if (refused)
             return refused;
+        const apps = value.apps;
+        if (apps !== undefined && (app !== 'boule' || typeof apps !== 'boolean')) {
+            return refusal('builtin_app_invalid', `${app}.apps`, app === 'boule'
+                ? 'boule.apps must be true or false'
+                : `${app} has no apps switch: only the company's Boule runs apps`);
+        }
+        const enabled = value.enabled;
+        if (enabled !== undefined && (app !== 'kosmos' || typeof enabled !== 'boolean')) {
+            return refusal('builtin_app_invalid', `${app}.enabled`, app === 'kosmos'
+                ? 'kosmos.enabled must be true or false'
+                : `${app} has no enabled switch: it is always on`);
+        }
+    }
+    if (kosmosOn(org) && org.hosting.issuerApps.some((app) => app.name === 'kosmos')) {
+        return refusal('issuer_app_name_reserved_kosmos', 'hosting.issuerApps.kosmos.name', "kosmos.enabled reserves the issuerApps name 'kosmos'");
     }
     return null;
 }
@@ -643,19 +887,15 @@ function validateEntryAuth(entry, hosting, domain) {
             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 &&
-            (typeof onboarding !== 'string' ||
-                !onboarding.startsWith('/') ||
-                onboarding.startsWith('//') ||
-                onboarding.includes('..') ||
-                onboarding.includes('?') ||
-                onboarding.includes('#') ||
-                onboarding.includes('\\') ||
-                /[\s\p{Cc}]/u.test(onboarding) ||
-                onboarding.length > ONBOARDING_PATH_MAX_LENGTH)) {
+        if (onboarding !== undefined && !isPagePath(onboarding)) {
             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`);
         }
     }
+    if (auth.workspaces !== undefined) {
+        const refused = validateEntryWorkspaces(entry, auth.workspaces, at);
+        if (refused)
+            return refused;
+    }
     const signIn = auth.signIn;
     if (signIn !== undefined && signIn !== 'password' && signIn !== 'email-code') {
         return refusal('auth_sign_in_invalid', `hosting.entries.${entry.key}.uses.auth.signIn`, `${at} signIn must be 'password' or 'email-code'`);
@@ -675,14 +915,62 @@ function validateEntryAuth(entry, hosting, domain) {
     if (entry.key === 'agora' ||
         entry.key === 'boule' ||
         entry.key === 'cms' ||
+        entry.key === 'kosmos' ||
         hosting.issuerApps.some((app) => app.name === entry.key)) {
         return refusal('client_name_taken', `hosting.entries.${entry.key}.key`, `${at} client name '${entry.key}' is already held by another ZITADEL client`);
     }
+    // A server workspace signs in with its own client `<key>-work`.
+    const workspaceClient = `${entry.key}-work`;
+    if (entry.workspace !== undefined &&
+        entry.workerApp === undefined &&
+        (hosting.entries.some((e) => e.key === workspaceClient) ||
+            hosting.issuerApps.some((app) => app.name === workspaceClient))) {
+        return refusal('client_name_taken', `hosting.entries.${entry.key}.key`, `${at} workspace client name '${workspaceClient}' is already held by another entry or ZITADEL client`);
+    }
+    return null;
+}
+/**
+ * `uses.auth.workspaces`: customers only, a server entry (a Worker app has nowhere to keep the key), roles the
+ * broker accepts (1 to 20 distinct names, no `c_` prefix, `owner` only as the first, never `self_service`),
+ * a plain invite path, and no `env` entry that names a value it writes.
+ */
+function validateEntryWorkspaces(entry, workspaces, at) {
+    const path = `hosting.entries.${entry.key}.uses.auth.workspaces`;
+    if (entry.uses?.auth?.users !== 'customers') {
+        return refusal('workspaces_needs_customers', path, `${at} workspaces needs users 'customers': workspaces belong to an app's own customers`);
+    }
+    if (entry.workerApp !== undefined) {
+        return refusal('workspaces_needs_server', path, `${at} workspaces needs an app that runs as a server: a Worker app has nowhere to keep the workspaces key`);
+    }
+    const config = workspaces;
+    const roles = config?.roles;
+    if (!Array.isArray(roles) || roles.length < 1 || roles.length > WORKSPACE_ROLES_MAX) {
+        return refusal('workspaces_roles_invalid', `${path}.roles`, `${at} workspaces needs between 1 and ${WORKSPACE_ROLES_MAX} roles; the first is the owner role`);
+    }
+    const seen = new Set();
+    for (const [index, role] of roles.entries()) {
+        if (typeof role !== 'string' || !WORKSPACE_ROLE.test(role) || role.startsWith('c_')) {
+            return refusal('workspaces_roles_invalid', `${path}.roles`, `${at} workspaces role ${index + 1} must start with a lowercase letter and hold only lowercase letters, digits, '_' and '-' (at most 64 characters), and may not start with 'c_'`);
+        }
+        if (seen.has(role)) {
+            return refusal('workspaces_roles_invalid', `${path}.roles`, `${at} workspaces names the role '${role}' twice`);
+        }
+        if (role === 'self_service' || (role === 'owner' && index > 0)) {
+            return refusal('workspaces_role_reserved', `${path}.roles`, `${at} workspaces role '${role}' is reserved: only the first role may be called 'owner', and 'self_service' is never allowed`);
+        }
+        seen.add(role);
+    }
+    const invitePath = config?.invitePath;
+    if (!isPagePath(invitePath)) {
+        return refusal('workspaces_invite_path_invalid', `${path}.invitePath`, `${at} workspaces invitePath must be an absolute path that starts with '/', such as '/join', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`);
+    }
+    const named = Object.keys(entry.env ?? {}).find((name) => WORKSPACES_ENTRY_ENV_NAMES.includes(name));
+    if (named) {
+        return refusal('workspaces_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} workspaces writes ${named}; remove it from env`);
+    }
     return null;
 }
 const ROOM_KEYS = [...Object.keys(ROOM_TEXT_MAX), 'steps'];
-// biome-ignore lint/suspicious/noControlCharactersInRegex: the point is to refuse them
-const ROOM_UNSAFE_TEXT = /[\u0000-\u001f\u007f<>]/;
 /** A fixed sentence when `uses.auth.room` is not usable, `null` when it is. The value is never in it. */
 function roomProblem(room) {
     if (typeof room !== 'object' || room === null || Array.isArray(room)) {
@@ -747,7 +1035,7 @@ function validateEntryAi(entry, hosting, domain) {
     }
     if (ai.webhookPath !== undefined) {
         if (typeof ai.webhookPath !== 'string' ||
-            !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,199}$/.test(ai.webhookPath) ||
+            !AI_WEBHOOK_PATH.test(ai.webhookPath) ||
             ai.webhookPath.startsWith('//')) {
             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`);
         }
@@ -775,7 +1063,7 @@ function validateEntryFiles(entry, hosting, domain) {
     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))) {
+    if (!names(files.collections) || !files.collections.every((n) => FILES_COLLECTION_NAME.test(n))) {
         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) {
@@ -837,6 +1125,9 @@ function validateEntryWorker(entry, hosting, domain) {
     if (entry.repo === null) {
         return refusal('worker_needs_repo', `hosting.entries.${entry.key}.repo`, `${at} needs its own repo (repo: null is not a Worker source)`);
     }
+    if (!REPO.test(entry.repo)) {
+        return refusal('worker_needs_own_repo', `hosting.entries.${entry.key}.repo`, `${at} can only be built from a repo under wtfalch: worker is only for our own projects`);
+    }
     if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
         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`);
     }
@@ -889,6 +1180,98 @@ function validateEntryEdge(entry, hosting, domain) {
         return refusal('edge_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
     return null;
 }
+/** The env names `uses.repo` writes; `env` may not name them. */
+export const REPO_ENTRY_ENV_NAMES = ['GIT_REPO_URL', 'GIT_SSH_KEY'];
+/**
+ * `uses.repo` (F12): `{ access: 'read' | 'write' }` and nothing else, on an entry that has its own `repo` (a
+ * Worker app has none to clone and is already refused for any use but `uses.auth`), and no `env` entry that
+ * names a value it writes.
+ */
+function validateEntryRepoUse(entry) {
+    const value = entry.uses?.repo;
+    if (value === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.uses.repo`;
+    const at = `hosting.entries '${entry.key}' uses.repo`;
+    const isObject = typeof value === 'object' && value !== null && !Array.isArray(value);
+    const access = isObject ? value.access : undefined;
+    if (!isObject ||
+        (access !== 'read' && access !== 'write') ||
+        Object.keys(value).some((k) => k !== 'access')) {
+        return refusal('repo_use_invalid', path, `${at} must be { access: 'read' } or { access: 'write' }: read lets the app clone its repo, write lets it push too`);
+    }
+    if (entry.repo === null) {
+        return refusal('repo_use_needs_repo', path, `${at} gives the app access to its own repo, and this entry has none: set repo, or remove uses.repo`);
+    }
+    const named = Object.keys(entry.env ?? {}).find((name) => REPO_ENTRY_ENV_NAMES.includes(name));
+    if (named) {
+        return refusal('repo_use_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
+    }
+    return null;
+}
+/** The env name `uses.customerGrants` writes; `env` may not name it. */
+export const CUSTOMER_GRANTS_ENTRY_ENV_NAMES = ['CUSTOMER_GRANTS_CREDENTIAL'];
+/**
+ * `uses.customerGrants`: `true`, customers signing in (`uses.auth` with `users: 'customers'`, which already
+ * needs hosting on and an exact hostname for the app), and no `env` entry that names the credential. A Worker
+ * app is already refused for any use but `uses.auth` (`validateEntryWorkerApp`).
+ */
+function validateEntryCustomerGrants(entry) {
+    const value = entry.uses?.customerGrants;
+    if (value === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.uses.customerGrants`;
+    const at = `hosting.entries '${entry.key}' uses.customerGrants`;
+    if (value !== true)
+        return refusal('customer_grants_not_true', path, `${at} must be true`);
+    if (entry.uses?.auth?.users !== 'customers') {
+        return refusal('customer_grants_needs_customers', path, `${at} is for an app whose customers sign in: declare uses.auth with users 'customers', or remove it`);
+    }
+    const named = Object.keys(entry.env ?? {}).find((name) => CUSTOMER_GRANTS_ENTRY_ENV_NAMES.includes(name));
+    if (named) {
+        return refusal('customer_grants_env_clash', `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
+    }
+    return null;
+}
+/** `uses.mail` and `uses.jobs`: `true`, `hosting.enabled`, and no `env` entry that names a value they write. */
+function validateEntryMailJobs(entry, hosting) {
+    for (const [use, written, code] of [
+        ['mail', MAIL_ENTRY_ENV_NAMES, 'mail'],
+        ['jobs', JOBS_ENTRY_ENV_NAMES, 'jobs'],
+    ]) {
+        const value = entry.uses?.[use];
+        if (value === undefined)
+            continue;
+        const path = `hosting.entries.${entry.key}.uses.${use}`;
+        const at = `hosting.entries '${entry.key}' uses.${use}`;
+        if (value !== true)
+            return refusal(`${code}_not_true`, path, `${at} must be true`);
+        if (!hosting.enabled) {
+            return refusal(`${code}_needs_hosting`, path, `${at} requires hosting.enabled`);
+        }
+        const named = Object.keys(entry.env ?? {}).find((name) => written.includes(name));
+        if (named) {
+            return refusal(`${code}_env_clash`, `hosting.entries.${entry.key}.env.${named}`, `${at} writes ${named}; remove it from env`);
+        }
+    }
+    return null;
+}
+/** `uses.audit`: `true`, `hosting.enabled`, and a Worker app with a database (the ledger lives in it). */
+function validateEntryAudit(entry, hosting) {
+    const value = entry.uses?.audit;
+    if (value === undefined)
+        return null;
+    const path = `hosting.entries.${entry.key}.uses.audit`;
+    const at = `hosting.entries '${entry.key}' uses.audit`;
+    if (value !== true)
+        return refusal('audit_not_true', path, `${at} must be true`);
+    if (!hosting.enabled)
+        return refusal('audit_needs_hosting', path, `${at} requires hosting.enabled`);
+    if (!entry.workerApp?.database) {
+        return refusal('audit_needs_worker_database', path, `${at} requires a Worker app with a database: the ledger is kept in it`);
+    }
+    return null;
+}
 function urlHasPassword(value) {
     try {
         return new URL(value).password !== '';
@@ -925,6 +1308,8 @@ function urlHasPassword(value) {
  */
 const DOMAIN_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const SHARED_ZONE = 'oikos.host';
+/** The platform zone new app addresses (`<hostedName>.companyincluded.app`) and every workspace live in. */
+export const APPS_DOMAIN = 'companyincluded.app';
 /** The mail relay accepts only a letters-only top-level label (`plan/mail-relay.ts`); one domain it rejects would block the relay step for every company. */
 const RELAY_TLD = /^[a-z]{2,63}$/;
 export function validateDomain(domain) {
@@ -947,6 +1332,10 @@ export function validateDomain(domain) {
     if (domain === SHARED_ZONE || domain.endsWith(`.${SHARED_ZONE}`)) {
         return `domain '${domain}' is on ${SHARED_ZONE}, the shared zone for companies without a domain; a company cannot own it`;
     }
+    // companyincluded.app holds the platform's hosted app addresses and every workspace.
+    if (domain === APPS_DOMAIN || domain.endsWith(`.${APPS_DOMAIN}`)) {
+        return `domain '${domain}' is on ${APPS_DOMAIN}, where the platform serves app addresses and workspaces; a company cannot own it`;
+    }
     return null;
 }
 /**
@@ -1509,6 +1898,8 @@ function orgServiceSchema(service, schema, legacyKey, split = true) {
 export const ORG_SERVICE_SCHEMAS = [
     orgServiceSchema('Boule', 'boule', () => 'coolify_boule_database'),
     orgServiceSchema('CMS', 'cms', () => 'coolify_cms_database'),
+    // kosmos, like CMS, sits behind its own feature switch (`KosmosApp.enabled`); see `orgServiceSchemaEnabled`.
+    orgServiceSchema('kosmos', 'kosmos', () => 'coolify_kosmos_database'),
     orgServiceSchema("chat's Synapse homeserver", 'chat_synapse', () => 'coolify_chat_synapse_database', false),
     orgServiceSchema("chat's matrix-authentication-service", 'chat_mas', () => 'coolify_chat_mas_database', false),
     orgServiceSchema("chat's own service", 'chat_service', () => 'coolify_chat_service_database'),
@@ -1542,6 +1933,10 @@ export function orgServiceDatabase(org, home) {
             database = underscored(`${org.slug}-cms-db`);
             runtimeRole = 'cms_rt';
             break;
+        case 'kosmos':
+            database = underscored(`${org.slug}-kosmos-db`);
+            runtimeRole = 'kosmos_rt';
+            break;
         case 'chat_service':
             database = 'chat';
             break;