@wtfalch/foundry 0.28.0 → 0.30.0

package/dist/plan/executor.js

@@ -2,11 +2,11 @@ import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { resolveCallsSfuUrls } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, sharedSecretRef, } from '../org.js';
-import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatIntrospectionAppName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
-import { CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, chatInternalNames, chatMasConfigYaml, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
+import { CHAT_MAS_PORT, CHAT_REPO, CHAT_SERVICE_DOCKERFILE, CHAT_SERVICE_PORT, CHAT_SYNAPSE_DOCKERFILE, CHAT_SYNAPSE_PORT, assertChatServerName, chatInternalNames, chatMasConfigYaml, chatRekeyedInternalNames, chatServerName, chatServiceEnvs, chatSynapseHomeserverYaml, chatUpstreams, } from './chat-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { CORE_FILES_COLLECTION_NAME, FILES_CORE_COLLECTION_SCOPE_KEY, ZITADEL_FILES_PROJECT_SCOPE_KEY, } from './core-files.js';
 import { waitForNewDeployment, } from './deploy-health.js';
@@ -607,6 +607,39 @@ const CHAT_SERVICE_SCOPE_KEY = 'coolify_chat_service';
 const CHAT_SYNAPSE_DB_SCOPE_KEY = 'coolify_chat_synapse_database';
 const CHAT_MAS_DB_SCOPE_KEY = 'coolify_chat_mas_database';
 const CHAT_SERVICE_DB_SCOPE_KEY = 'coolify_chat_service_database';
+/**
+ * #463: `coolifyChatRekey`'s own scope ids for the new, domain-named
+ * Synapse+MAS pair the re-key provisions beside the original. The chat
+ * service and its own database keep their original scope keys above --
+ * only the two Matrix apps and their databases are new resources; the
+ * service is repointed in place, never re-created.
+ */
+const CHAT_REKEY_SYNAPSE_SCOPE_KEY = 'coolify_chat_rekey_synapse';
+const CHAT_REKEY_MAS_SCOPE_KEY = 'coolify_chat_rekey_mas';
+const CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY = 'coolify_chat_rekey_synapse_database';
+const CHAT_REKEY_MAS_DB_SCOPE_KEY = 'coolify_chat_rekey_mas_database';
+/**
+ * Set once {@link ChatRekeyPort.copyHomeserver} returns, so a retried or
+ * repeated apply never copies the same history twice -- the copy itself is
+ * also idempotent by server name (that port's own doc comment), so this is
+ * belt and suspenders, not the only guard.
+ */
+const CHAT_REKEY_COPIED_SCOPE_KEY = 'coolify_chat_rekey_copied';
+/**
+ * A copy of the level-1 MAS app's id, taken the first time
+ * `coolifyChatRekey` runs for an org, before anything else happens. The
+ * generic `coolify:chat:<orgId>` scope id this step returns as its own
+ * `resourceId` is overwritten with the *new* MAS app's id once the re-key
+ * finishes, so a second run reading that generic id to decide what to park
+ * would stop the live, just-rekeyed MAS instead of the original one --
+ * this dedicated copy is what every run parks from, immune to that
+ * overwrite.
+ */
+const CHAT_REKEY_ORIGINAL_MAS_SCOPE_KEY = 'coolify_chat_rekey_original_mas';
+/** Set once the chat service runs healthy on the new pair; the original is parked only after it. */
+const CHAT_REKEY_REPOINTED_SCOPE_KEY = 'coolify_chat_rekey_repointed';
+/** The copy is bounded; an interrupted one is safe to run again because the port is idempotent. */
+const CHAT_REKEY_COPY_TIMEOUT_MS = 60 * 60 * 1000;
 /** {@link CALLS_SECRET_ENV_KEYS}' counterpart on chat's own MAS app. */
 const CHAT_SECRET_ENV_KEYS = {
     masSynapseSharedSecret: 'CHAT_MATRIX_MAS_SYNAPSE_SHARED_SECRET',
@@ -784,6 +817,8 @@ export class FoundryStepExecutor {
                 return this.coolifyCalls(action, org, context);
             case 'coolify:calls-service':
                 return this.coolifyCallsService(action, org, context);
+            case 'coolify:calls-chat':
+                return this.coolifyCallsChat(action, org, context);
             case 'cloudflare:tunnel':
                 return this.cloudflareTunnel(action, org, context);
             case 'cloudflare:zone':
@@ -1293,13 +1328,14 @@ export class FoundryStepExecutor {
         // ZITADEL's default invite link (`/ui/v2/login/verify`) 404s; the platform's login app, which
         // every org's users sign in through on this instance, serves `/verify` at the root.
         const authIssuer = action.desired.authIssuer;
+        if (!authIssuer) {
+            throw new Error(`zitadel:owner for ${org.slug}: no invite template issuer -- refusing to send ZITADEL's default invite link, which 404s on this platform`);
+        }
         const { userId } = await this.ports.zitadel.inviteOrgOwner(zitadelOrgId, {
             givenName: action.desired.givenName,
             familyName: action.desired.familyName,
             email: action.desired.email,
-        }, authIssuer
-            ? `${authIssuer}/verify?userId={{.UserID}}&code={{.Code}}&organization={{.OrgID}}&invite=true`
-            : undefined);
+        }, `${authIssuer}/verify?userId={{.UserID}}&code={{.Code}}&organization={{.OrgID}}&invite=true`);
         // An owner invited after chat was built never reaches `coolifyChat`
         // again, so the role is granted here once the messaging project exists.
         const messagingProjectId = context.recordedIds()[ZITADEL_MESSAGING_PROJECT_SCOPE_KEY];
@@ -2493,6 +2529,10 @@ export class FoundryStepExecutor {
      * domain restricted to them before any old project is deleted, so the
      * restriction list never becomes empty.
      *
+     * #654: the non-platform-apex part now lives in {@link ensureOrgAppMailToken},
+     * shared with Boule, which holds the same token; the rule below is its rule
+     * with the consumers read from the hosted app and Boule.
+     *
      * Mint rule ("Credential model"): the project is healthy when the app env
      * holds `LETTERMINT_API_TOKEN` and Lettermint lists exactly one project
      * named `<slug>-app` -- unlike the earlier provider's key, a Lettermint project's name
@@ -2545,7 +2585,6 @@ export class FoundryStepExecutor {
         if (!hasPlatformApexField) {
             throw new Error(`coolify:app for ${org.slug}: this step's plan carries no platformApex; plan this org's app again`);
         }
-        const appName = `${org.slug}-app`;
         // #491: an org whose mail domain is the platform's own apex (Company
         // Included on companyincluded.com, today) shares the platform's existing
         // Lettermint project rather than minting a `<slug>-app` one of its own --
@@ -2588,44 +2627,129 @@ export class FoundryStepExecutor {
                 await this.ports.coolify.restart(appId);
             return;
         }
-        const [projects, envs] = await Promise.all([
+        await this.ensureOrgAppMailToken({
+            org,
+            context,
+            mailDomain,
+            self: { role: 'app', id: appId, restart: running },
+            mailFrom: `${org.mail.noReplyLocalPart ?? 'no-reply'}@${mailDomain}`,
+            platformApex,
+            platformLettermintProjectId,
+        });
+    }
+    /**
+     * The one mint rule for the org's `<slug>-app` Lettermint token, shared by
+     * the hosted app (`ensureAppLettermintMail`) and Boule
+     * (`ensureBouleMail`), which hold the same token. Lettermint shows a
+     * token once, so the token lives only in those apps' envs: the rule reads
+     * every consumer that is recorded (the hosted app first, Boule second).
+     * The project is healthy when Lettermint lists exactly one `<slug>-app`
+     * project and some consumer holds a token. A healthy rule gives `self` that
+     * token (the app's wins) when it lacks it or holds another; a peer gets it
+     * in its own step. An
+     * unhealthy one mints a fresh project and writes its token to every
+     * consumer, restarting those that run, before any other `<slug>-app`
+     * project is deleted. Either role may run first: an app added after Boule
+     * adopts Boule's token instead of deleting its project.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, recorded, logged or interpolated into an error. Returns
+     * whether `self`'s own token changed and whether it was restarted here.
+     *
+     * A peer recorded but gone from Coolify (404) is no consumer. A healthy
+     * company's step writes only its own env; a re-mint writes every live
+     * consumer, restarts the running ones, restricts the domain, then deletes
+     * the old projects.
+     */
+    async ensureOrgAppMailToken(args) {
+        const { org, context, mailDomain, self, mailFrom } = args;
+        const appName = `${org.slug}-app`;
+        const recorded = context.recordedIds();
+        const appId = self.role === 'app' ? self.id : recorded[`coolify:app:${appStepKey(org)}`];
+        const bouleId = self.role === 'boule' ? self.id : recorded[`coolify:boule:${org.id}`];
+        const peerListEnvs = (id) => !id || id === self.id
+            ? Promise.resolve(null)
+            : // A recorded peer that Coolify no longer has is not a consumer: not
+                // read, written or restarted (same 404 rule as the retire step).
+                this.ports.coolify
+                    .listEnvs(id)
+                    .catch((error) => {
+                    if (!isNotFoundError(error))
+                        throw error;
+                    return null;
+                });
+        const [projects, selfEnvs, appEnvs, bouleEnvs] = await Promise.all([
             this.ports.lettermint.listProjects(),
-            this.ports.coolify.listEnvs(appId),
+            this.ports.coolify.listEnvs(self.id),
+            self.role === 'app' ? Promise.resolve(null) : peerListEnvs(appId),
+            self.role === 'boule' ? Promise.resolve(null) : peerListEnvs(bouleId),
         ]);
-        const envValue = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const tokenOf = (envs) => envs.find((e) => e.key === 'LETTERMINT_API_TOKEN' && !e.is_preview)?.value || undefined;
+        // The hosted app first, Boule second: the app's token wins a disagreement.
+        const consumers = [];
+        const appSlot = self.role === 'app' ? selfEnvs : appEnvs;
+        const bouleSlot = self.role === 'boule' ? selfEnvs : bouleEnvs;
+        if (appSlot && appId)
+            consumers.push({ id: appId, token: tokenOf(appSlot) });
+        if (bouleSlot && bouleId)
+            consumers.push({ id: bouleId, token: tokenOf(bouleSlot) });
+        const existingToken = consumers.find((c) => c.token)?.token;
         const ours = projects.filter((p) => p.name === appName);
         const held = ours.length === 1 ? ours[0] : undefined;
-        const healthy = held !== undefined && Boolean(envValue('LETTERMINT_API_TOKEN'));
+        const healthy = held !== undefined && existingToken !== undefined;
         let allProjects = projects;
         let keepProjectId;
-        const envUpdates = [];
-        if (healthy && held) {
+        let token;
+        if (healthy && held && existingToken) {
             keepProjectId = held.id;
+            token = existingToken;
         }
         else {
             const created = await this.ports.lettermint.createProject(appName);
             keepProjectId = created.project.id;
             allProjects = [...projects, created.project];
-            envUpdates.push({ key: 'LETTERMINT_API_TOKEN', value: created.token });
+            token = created.token;
+        }
+        // A healthy company: this step writes only its own env; a peer that lacks
+        // the token gets it in its own step. A re-mint kills the old token, so it
+        // reaches every live consumer here.
+        const targets = consumers.filter((c) => c.token !== token && (!healthy || c.id === self.id));
+        const selfChanged = targets.some((c) => c.id === self.id);
+        for (const consumer of consumers) {
+            const updates = [];
+            if (targets.includes(consumer))
+                updates.push({ key: 'LETTERMINT_API_TOKEN', value: token });
+            if (consumer.id === self.id && mailFrom)
+                updates.push({ key: 'MAIL_FROM', value: mailFrom });
+            if (updates.length > 0)
+                await this.ports.coolify.bulkUpsertEnvs(consumer.id, updates);
         }
-        envUpdates.push({
-            key: 'MAIL_FROM',
-            value: `${org.mail.noReplyLocalPart ?? 'no-reply'}@${mailDomain}`,
-        });
-        await this.ports.coolify.bulkUpsertEnvs(appId, envUpdates);
         // A running container read its env at start and still holds the old
-        // token, so a fresh one only reaches it through a restart -- before the
-        // old project is deleted below. A just-created app is deployed first (#566).
-        if (!healthy && running)
-            await this.ports.coolify.restart(appId);
-        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects, platformApex, platformLettermintProjectId);
+        // token, so a fresh one only reaches it through a restart -- after every
+        // write and before the old project is deleted below, so a failure in
+        // between leaves the old project for the next apply to re-mint. A just-created
+        // app is deployed first (#566).
+        let selfRestarted = false;
+        for (const consumer of targets) {
+            const isSelf = consumer.id === self.id;
+            const running = isSelf
+                ? self.restart
+                : isRunningOrStarting((await this.ports.coolify.getApplication(consumer.id)).status);
+            if (!running)
+                continue;
+            await this.ports.coolify.restart(consumer.id);
+            if (isSelf)
+                selfRestarted = true;
+        }
+        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects, args.platformApex, args.platformLettermintProjectId);
         for (const project of allProjects) {
             if (project.name === appName &&
                 project.id !== keepProjectId &&
-                project.id !== platformLettermintProjectId) {
+                project.id !== args.platformLettermintProjectId) {
                 await this.ports.lettermint.deleteProject(project.id);
             }
         }
+        return { selfChanged, selfRestarted };
     }
     /**
      * #149: mints this org's own Lettermint relay credential and writes it to
@@ -3605,7 +3729,7 @@ export class FoundryStepExecutor {
             if (action.desired.usesDomain === false) {
                 throw new NotBuiltError(`coolify:chat reverse re-key for ${org.slug}`, 'moving its chat back onto the original server_name is not built (#7 amendment 3)');
             }
-            throw new NotBuiltError(`coolify:chat re-key for ${org.slug}`, 'moving its chat onto the company domain is not built; chat stays on its level-1 server_name');
+            return this.coolifyChatRekey(org, context, recorded);
         }
         const issuer = action.desired.issuer;
         if (typeof issuer !== 'string' || issuer === '') {
@@ -3790,6 +3914,224 @@ export class FoundryStepExecutor {
         context.recordScopeId(CHAT_SERVICE_URL_SCOPE_KEY, chatUpstreams(org.slug).chat);
         return { resourceId: mas.appId };
     }
+    /**
+     * `coolifyChat`'s forward re-key (#463, design note
+     * `docs/chat-rekey-design.md` Option 1): a live chat recorded, and
+     * `org.chat.usesDomain` flipped on. Provisions a second Synapse+MAS pair
+     * named for the org's own domain (`chatRekeyedInternalNames`), copies
+     * every room, member and message across through
+     * {@link FoundryStepExecutorPorts.chatRekey}, repoints the existing chat
+     * service at the new pair, and parks -- never deletes, so a stalled
+     * migration can be rolled back by simply restarting them -- the original
+     * Synapse and MAS apps. The chat service and its own database are never
+     * re-created; only the Matrix half of the stack moves.
+     *
+     * Idempotent on recorded ids: new resources are found by name before they
+     * are created, the new MAS's secrets are read back from its own envs, and
+     * the copy, the repoint and the park each run once
+     * ({@link CHAT_REKEY_COPIED_SCOPE_KEY}, {@link CHAT_REKEY_REPOINTED_SCOPE_KEY}).
+     * The original pair keeps serving until the chat service is healthy on the
+     * new one; a failure before that leaves it running.
+     */
+    async coolifyChatRekey(org, context, recorded) {
+        if (!this.ports.chatRekey) {
+            throw new NotBuiltError(`coolify:chat re-key for ${org.slug}`, 'construct FoundryStepExecutor with `chatRekey` -- the copy mechanism must be proven against a real Synapse and MAS pair first (#463 Human step)');
+        }
+        if (!org.domain) {
+            throw new Error(`coolify:chat re-key for ${org.slug}: the org has no domain to re-key onto`);
+        }
+        try {
+            assertChatServerName(org.domain);
+        }
+        catch {
+            throw new Error(`coolify:chat re-key for ${org.slug}: the org's domain is not a valid server_name`);
+        }
+        const runtime = this.ports.runtime ?? {};
+        const sleep = runtime.sleep ?? defaultSleep;
+        const oldSynapseAppId = recorded[CHAT_SYNAPSE_SCOPE_KEY];
+        const oldServiceAppId = recorded[CHAT_SERVICE_SCOPE_KEY];
+        if (!oldSynapseAppId || !oldServiceAppId) {
+            throw new Error(`coolify:chat re-key for ${org.slug}: its level-1 Synapse or chat service is not recorded yet`);
+        }
+        // See {@link CHAT_REKEY_ORIGINAL_MAS_SCOPE_KEY}'s own doc comment: taken
+        // once, from the generic resourceId this step returns, before that id is
+        // ever repointed at the new MAS.
+        const oldMasAppId = recorded[CHAT_REKEY_ORIGINAL_MAS_SCOPE_KEY] ?? recorded[`coolify:chat:${org.id}`];
+        if (!oldMasAppId) {
+            throw new Error(`coolify:chat re-key for ${org.slug}: its level-1 MAS is not recorded yet`);
+        }
+        context.recordScopeId(CHAT_REKEY_ORIGINAL_MAS_SCOPE_KEY, oldMasAppId);
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const server = await this.resolveServer(org, context);
+        const names = chatRekeyedInternalNames(org.slug);
+        const synapseDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.synapseDb, 'synapse', CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
+        context.recordScopeId(CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY, synapseDbId);
+        const masDbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, names.masDb, 'mas', CHAT_REKEY_MAS_DB_SCOPE_KEY);
+        context.recordScopeId(CHAT_REKEY_MAS_DB_SCOPE_KEY, masDbId);
+        const [synapseDbRow, masDbRow] = await Promise.all([
+            getDatabaseStarted(this.ports.coolify, synapseDbId),
+            getDatabaseStarted(this.ports.coolify, masDbId),
+        ]);
+        const synapseDb = synapseDbRow.internal_db_url
+            ? parseCallsDbUrl(synapseDbRow.internal_db_url)
+            : null;
+        const masDb = masDbRow.internal_db_url ? parseCallsDbUrl(masDbRow.internal_db_url) : null;
+        if (!synapseDb || !masDb) {
+            throw new Error(`coolify:chat re-key for ${org.slug}: its new database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const synapse = await this.findOrCreateCallsApp(names.synapse, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: CHAT_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name: names.synapse,
+            dockerfile_location: CHAT_SYNAPSE_DOCKERFILE,
+            ports_exposes: CHAT_SYNAPSE_PORT,
+            autogenerate_domain: false,
+        }), { startIfStopped: false });
+        const mas = await this.findOrCreateCallsApp(names.mas, environment.id, () => this.ports.coolify.createDockerfileApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: CALLS_MAS_DOCKERFILE,
+            name: names.mas,
+            description: `matrix-authentication-service for ${org.slug}'s re-keyed chat (#463)`,
+            instant_deploy: false,
+        }), { startIfStopped: false });
+        await this.ports.coolify.updateApplication(synapse.appId, {
+            custom_internal_name: names.synapse,
+            ...(synapse.existed ? {} : { health_check_enabled: false }),
+        });
+        await this.ports.coolify.updateApplication(mas.appId, {
+            custom_internal_name: names.mas,
+            ...(mas.existed ? {} : { health_check_enabled: false }),
+        });
+        context.recordScopeId(CHAT_REKEY_SYNAPSE_SCOPE_KEY, synapse.appId);
+        context.recordScopeId(CHAT_REKEY_MAS_SCOPE_KEY, mas.appId);
+        // The new MAS holds the minted secrets, so its id is on record before they exist.
+        await context.persistScopeIds();
+        const synapseStorages = await this.ports.coolify.listStorages(synapse.appId);
+        if (!(synapseStorages.persistent_storages ?? []).some((s) => s.mount_path === '/data')) {
+            await this.ports.coolify.createPersistentStorage(synapse.appId, {
+                name: `${names.synapse}-data`,
+                mount_path: '/data',
+            });
+        }
+        const secrets = await this.ensureCallsMatrixSecrets(mas.appId, CHAT_SECRET_ENV_KEYS);
+        const agoraHost = agoraHostnameFor(org);
+        await this.ensureCallsFileStorage(synapse.appId, '/data/homeserver.yaml', chatSynapseHomeserverYaml({
+            orgSlug: org.slug,
+            db: synapseDb,
+            masHost: names.mas,
+            masSharedSecret: secrets.value.masSynapseSharedSecret,
+            serverName: org.domain,
+        }));
+        await this.ports.coolify.bulkUpsertEnvs(synapse.appId, [
+            { key: 'SYNAPSE_CONFIG_PATH', value: '/data/homeserver.yaml' },
+            { key: 'UID', value: '0' },
+            { key: 'GID', value: '0' },
+        ]);
+        await this.ensureCallsFileStorage(mas.appId, '/config/config.yaml', chatMasConfigYaml({
+            orgSlug: org.slug,
+            publicHost: agoraHost,
+            db: masDb,
+            synapseHost: names.synapse,
+            sharedSecret: secrets.value.masSynapseSharedSecret,
+            clientId: secrets.value.masClientId,
+            clientSecret: secrets.value.masClientSecret,
+            encryptionKey: secrets.value.masEncryptionKey,
+            rsaKeyPem: secrets.value.masRsaKeyPem,
+            ecKeyPem: secrets.value.masEcKeyPem,
+            serverName: org.domain,
+        }));
+        // MAS first: Synapse asks it for token introspection. Both are healthy
+        // before the copy reads or writes either of them.
+        for (const app of [mas, synapse]) {
+            if (!app.existed ||
+                secrets.changed ||
+                !isRunningOrStarting((await this.ports.coolify.getApplication(app.appId)).status)) {
+                await waitForNewDeployment(this.ports.coolify, app.appId, { kind: 'deployment-only' }, runtime, sleep, 'coolify:chat', `${org.slug}'s original chat pair stays live; the new ${app === mas ? 'MAS' : 'Synapse'} is not up`);
+            }
+        }
+        if (!recorded[CHAT_REKEY_COPIED_SCOPE_KEY]) {
+            const oldNames = chatInternalNames(org.slug);
+            const abort = new AbortController();
+            let timer;
+            try {
+                await Promise.race([
+                    this.ports.chatRekey.copyHomeserver({
+                        orgSlug: org.slug,
+                        fromServerName: chatServerName(org.slug),
+                        fromInternalHost: `http://${oldNames.synapse}:${CHAT_SYNAPSE_PORT}`,
+                        toServerName: org.domain,
+                        toInternalHost: `http://${names.synapse}:${CHAT_SYNAPSE_PORT}`,
+                        signal: abort.signal,
+                    }),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            abort.abort();
+                            reject(new Error('timed out'));
+                        }, CHAT_REKEY_COPY_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            catch {
+                throw new Error(`coolify:chat re-key for ${org.slug}: the copy did not finish; the original chat pair stays live. Apply again`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            context.recordScopeId(CHAT_REKEY_COPIED_SCOPE_KEY, '1');
+            await context.persistScopeIds();
+        }
+        // The marker is set only after the service is healthy on the new pair; an
+        // env write whose deploy failed must not let the original be parked.
+        if (!recorded[CHAT_REKEY_REPOINTED_SCOPE_KEY]) {
+            const envs = [
+                { key: 'CHAT_SERVER_NAME', value: org.domain },
+                {
+                    key: 'CHAT_INTERNAL_HOMESERVER_URL',
+                    value: `http://${names.synapse}:${CHAT_SYNAPSE_PORT}`,
+                },
+                { key: 'MAS_URL', value: `http://${names.mas}:${CHAT_MAS_PORT}` },
+                { key: 'MAS_CLIENT_ID', value: secrets.value.masClientId },
+                { key: 'MAS_CLIENT_SECRET', value: secrets.value.masClientSecret },
+            ];
+            let written = false;
+            for (let attempt = 1; attempt <= JOBS_DELIVERY_ATTEMPTS && !written; attempt++) {
+                try {
+                    await this.ports.coolify.bulkUpsertEnvs(oldServiceAppId, envs);
+                    written = true;
+                }
+                catch {
+                    // Retried; the error is dropped in case it echoes the client secret.
+                }
+            }
+            if (!written) {
+                throw new Error(`coolify:chat re-key for ${org.slug}: the new MAS client could not be written to the chat service (${oldServiceAppId}) after ${JOBS_DELIVERY_ATTEMPTS} attempts; the original chat pair stays live`);
+            }
+            await waitForNewDeployment(this.ports.coolify, oldServiceAppId, publicHealthCheck(org, context.recordedIds(), agoraHostnameFor(org), CHAT_SERVICE_HEALTH_CHECK_PATH, { viaAgora: true }), runtime, sleep, 'coolify:chat', `${org.slug}'s original chat pair stays live`);
+            context.recordScopeId(CHAT_REKEY_REPOINTED_SCOPE_KEY, '1');
+            await context.persistScopeIds();
+        }
+        // Park, never delete (#7 corrections 1's park-not-delete rule), the
+        // original Synapse and MAS: cheap to roll back onto before members are
+        // told to use the new id, the design note's own rollback story. Skipped
+        // once already stopped, so a third run touches nothing here either.
+        for (const appId of [oldSynapseAppId, oldMasAppId]) {
+            if (isRunningOrStarting((await this.ports.coolify.getApplication(appId)).status)) {
+                await this.ports.coolify.raw('POST', `/applications/${appId}/stop`);
+            }
+        }
+        return { resourceId: mas.appId };
+    }
     // ---- calls service (#145, part 2 of #128) -------------------------------
     /**
      * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
@@ -3899,9 +4241,9 @@ export class FoundryStepExecutor {
             envs.push({ key: 'CALLS_BINDING_SECRET', value: bindingSecret });
         // The seven ZITADEL token vars, all or none (the service refuses to boot
         // on a partial set). Deliberately absent: `CALLS_CHAT_URL` and
-        // `CALLS_CHAT_TOKEN`. Foundry does not deploy chat
-        // (https://github.com/wtfalch/chat/issues/40), so with both unset the
-        // calls service admits only `event:` rooms.
+        // `CALLS_CHAT_TOKEN`. `coolifyCallsChat` sets and removes the pair, after
+        // this step and chat, so a chat-less org keeps event-only calls and this
+        // write never leaves one of the two behind.
         const tokenHost = action.desired.host;
         const tokenMarker = callsTokenEnvMarker(tokenHost ?? null, context.recordedIds());
         const token = tokenHost && tokenMarker
@@ -3960,6 +4302,88 @@ export class FoundryStepExecutor {
             context.recordScopeId(dbMarkerKey, '1');
         return { resourceId: app.appId };
     }
+    /**
+     * `plan/diff.ts`'s `planCallsChat`: the one internal token that lets the
+     * calls service ask chat who is in a room, and the chat address. The token
+     * is `CHAT_INTERNAL_TOKEN` on chat-service and `CALLS_CHAT_TOKEN` on the
+     * calls service, which gets `CALLS_CHAT_URL` in the same write: it refuses
+     * to boot on one without the other. Chat-service's env is the only memory
+     * of the token across a run, the way {@link ensureCallsMatrixSecrets} keeps
+     * the MAS secrets on the MAS app, so it is generated only when that env has
+     * none. Its id is recorded and persisted before either app holds it, and the
+     * guard after both do (platform rule 1). Both apps are redeployed last; the
+     * applied marker is recorded after that, so a run that fails in between is
+     * planned and finished again. `remove` (chat is off) deletes both vars from
+     * the calls service and restarts it.
+     */
+    async coolifyCallsChat(action, org, context) {
+        const at = `coolify:calls-chat for ${org.slug}`;
+        const recorded = context.recordedIds();
+        const callsAppId = recorded[`coolify:calls-service:${action.key}`];
+        const chatAppId = recorded[CHAT_SERVICE_SCOPE_KEY];
+        const envOf = async (appId, key) => (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === key && !e.is_preview);
+        if (!callsAppId)
+            throw new Error(`${at}: the calls service has not been provisioned yet`);
+        if (action.desired.remove === true) {
+            for (const key of ['CALLS_CHAT_URL', 'CALLS_CHAT_TOKEN']) {
+                const env = await envOf(callsAppId, key);
+                if (env?.uuid)
+                    await this.ports.coolify.deleteEnv(callsAppId, env.uuid);
+            }
+            if (isRunningOrStarting((await this.ports.coolify.getApplication(callsAppId)).status)) {
+                await this.ports.coolify.restart(callsAppId);
+            }
+            context.recordScopeId(CHAT_CALLS_APPLIED_SCOPE_KEY, '');
+            return {};
+        }
+        const chatUrl = chatUpstreams(org.slug).chat;
+        if (!chatAppId || !chatHasUpstreams(org, recorded)) {
+            throw new Error(`${at}: chat has not been provisioned yet`);
+        }
+        let tokenId = recorded[CHAT_CALLS_TOKEN_SCOPE_KEY];
+        const undelivered = recorded[CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY];
+        if (undelivered && !tokenId) {
+            throw new Error(`${at}: token ${undelivered} was minted but never written to both apps; remove the recorded key ${CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY} to write it again`);
+        }
+        // Chat refuses a token under 32 characters; the calls service needs the same bytes.
+        const held = (await envOf(chatAppId, 'CHAT_INTERNAL_TOKEN'))?.value;
+        const usable = held !== undefined && /^\S{32,}$/.test(held) ? held : undefined;
+        if (tokenId && !usable) {
+            throw new Error(`${at}: token ${tokenId} is recorded but chat-service no longer holds a usable one; remove the recorded keys ${CHAT_CALLS_TOKEN_SCOPE_KEY} and ${CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        const token = usable ?? randomBytes(32).toString('hex');
+        if (!tokenId) {
+            tokenId = randomBytes(8).toString('hex');
+            context.recordScopeId(CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, tokenId);
+            await context.persistScopeIds();
+        }
+        const id = tokenId;
+        const write = async (appId, app, envs) => {
+            for (let attempt = 1; attempt <= JOBS_DELIVERY_ATTEMPTS; attempt++) {
+                try {
+                    await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+                    return;
+                }
+                catch {
+                    // Retried; the error is dropped in case it echoes the token.
+                }
+            }
+            throw new Error(`${at}: token ${id} could not be written to ${app} after ${JOBS_DELIVERY_ATTEMPTS} attempts`);
+        };
+        await write(chatAppId, 'chat-service', [{ key: 'CHAT_INTERNAL_TOKEN', value: token }]);
+        await write(callsAppId, 'the calls service', [
+            { key: 'CALLS_CHAT_URL', value: chatUrl },
+            { key: 'CALLS_CHAT_TOKEN', value: token },
+        ]);
+        context.recordScopeId(CHAT_CALLS_TOKEN_SCOPE_KEY, id);
+        // Chat first: the calls service's first question must find the route.
+        const runtime = this.ports.runtime ?? {};
+        const sleep = runtime.sleep ?? defaultSleep;
+        await waitForNewDeployment(this.ports.coolify, chatAppId, publicHealthCheck(org, context.recordedIds(), agoraHostnameFor(org), CHAT_SERVICE_HEALTH_CHECK_PATH, { viaAgora: true }), runtime, sleep, 'coolify:calls-chat', `${org.slug}'s chat service stays at its previous deploy`);
+        await waitForNewDeployment(this.ports.coolify, callsAppId, publicHealthCheck(org, context.recordedIds(), callsHostnameFor(org), CALLS_HEALTH_CHECK_PATH), runtime, sleep, 'coolify:calls-chat', `${org.slug}'s calls service stays at its previous deploy`);
+        context.recordScopeId(CHAT_CALLS_APPLIED_SCOPE_KEY, chatCallsApplied(id, chatUrl));
+        return {};
+    }
     /**
      * The seven ZITADEL token env vars the calls service needs to accept
      * Agora's sign-in token (`calls/docs/member-auth.md`). Only called with all
@@ -4237,7 +4661,14 @@ export class FoundryStepExecutor {
         // written is the env the plan showed.
         const issuer = action.desired.issuer ?? null;
         const archonUrl = action.desired.archonUrl ?? null;
-        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer, archonUrl);
+        // The plan decides blocked mail (`mailBlocked`); a plan with no
+        // `platformApex` key predates this field and is refused before any mail
+        // env is written.
+        const mailWanted = bouleMailWanted(org, context.recordedIds()) && action.desired.mailBlocked !== true;
+        if (mailWanted && !('platformApex' in action.desired)) {
+            throw new Error(`coolify:boule for ${org.slug}: this step's plan carries no platformApex; plan this org's Boule again`);
+        }
+        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer, archonUrl, mailWanted);
         if (missing.length > 0) {
             throw new Error(`Boule for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
         }
@@ -4288,6 +4719,12 @@ export class FoundryStepExecutor {
         if (!dbPush.pushed) {
             throw new Error(`Boule for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
         }
+        // The org's Lettermint token, the same one its hosted app holds. A no-op
+        // for an org with mail off or no mail domain recorded: Boule then shows
+        // the invite link.
+        const mail = mailWanted
+            ? await this.ensureBouleMail(app.appId, org, context, action, app.existed && Boolean(context.recordedIds()[BOULE_DEPLOYED_SCOPE_KEY]))
+            : { changed: false, restarted: false };
         // #504: see `coolifyAgora`'s own comment just above -- `createGithubAppApplication`
         // never sets `instant_deploy`, so a brand new app (or one found by name
         // that a previous apply created but crashed before deploying) sat built
@@ -4300,11 +4737,53 @@ export class FoundryStepExecutor {
             context.recordScopeId(BOULE_DEPLOYED_SCOPE_KEY, '1');
         }
         else if (app.existed &&
-            (envChanged || cookieSecret !== null || appKey !== null || dbPush.changed)) {
+            !mail.restarted &&
+            (envChanged || cookieSecret !== null || appKey !== null || dbPush.changed || mail.changed)) {
+            // A restart inside the mail rule already came after every env write above.
             await this.ports.coolify.restart(app.appId);
         }
         return { resourceId: app.appId };
     }
+    /**
+     * Gives Boule `LETTERMINT_API_TOKEN`: the platform's held key for an org on
+     * the platform's own apex, else the org's `<slug>-app` token through the
+     * shared mint rule ({@link ensureOrgAppMailToken}), which mints that project
+     * when no hosted app made it yet. `MAIL_FROM` is written with the rest of
+     * Boule's env. Returns whether Boule's token changed, so the caller
+     * restarts a running Boule, unless `restarted`: the shared rule then already
+     * restarted it (`running`), before it deleted the old project.
+     */
+    async ensureBouleMail(appId, org, context, action, running) {
+        const none = { changed: false, restarted: false };
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return none;
+        const platformApex = action.desired.platformApex ?? null;
+        const platformLettermintProjectId = action.desired.platformLettermintProjectId ?? null;
+        if (platformApex && mailDomain.toLowerCase() === platformApex.toLowerCase()) {
+            const heldToken = (await this.ports.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) ?? null;
+            if (!heldToken) {
+                throw new Error(`coolify:boule for ${org.slug}: the platform's own Lettermint token is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`);
+            }
+            const current = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'LETTERMINT_API_TOKEN' && !e.is_preview)?.value;
+            if (current === heldToken)
+                return none;
+            await this.ports.coolify.bulkUpsertEnvs(appId, [
+                { key: 'LETTERMINT_API_TOKEN', value: heldToken },
+            ]);
+            return { changed: true, restarted: false };
+        }
+        const { selfChanged, selfRestarted } = await this.ensureOrgAppMailToken({
+            org,
+            context,
+            mailDomain,
+            self: { role: 'boule', id: appId, restart: running },
+            mailFrom: null,
+            platformApex,
+            platformLettermintProjectId,
+        });
+        return { changed: selfChanged, restarted: selfRestarted };
+    }
     // ---- jobs (#173) ---------------------------------------------------------
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with