@wtfalch/foundry 0.29.0 → 0.31.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 { 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];
@@ -3693,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 === '') {
@@ -3878,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 --
@@ -3987,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
@@ -4048,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

package/dist/plan/index.d.ts

@@ -1,6 +1,6 @@
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
-export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
+export type { StepAction, PlannedStep, PlanDetail, OrgPostgresPlan } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export type { StepSystem } from './step-system.js';
 export { stepSystemOf } from './step-system.js';
@@ -21,13 +21,14 @@ export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEME
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export { createZitadelLoginPolicy } from './zitadel-login-policy.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export type { ScopeResolver, RecordedIds, DnsRecordOwners } from './providers-readers.js';
-export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export type { AgoraHostPort, AgoraHostValues } from './agora.js';
 export type { BrokerPort } from './broker-entries.js';
 export { PlatformBrokerPort } from './broker-entries.js';
@@ -57,3 +58,5 @@ export type { EdgePlatformTunnels, TunnelIngress, TunnelPort, TunnelSummary, } f
 export type { ZitadelListAppsRawApp } from './executor.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';
+export type { OrgAppVersionRef, OrgAppVersionStatus, WtfalchPackageDrift, PlatformVersionStatus, ReadPlatformVersionStatusOptions, StatusCoolifyPort, StatusGithubPort, GhExec as StatusGhExec, } from './version-status.js';
+export { readPlatformVersionStatus, wtfalchVersionsFromPnpmLockfile, providersStatusCoolifyPort, ghCliStatusGithubPort, } from './version-status.js';

package/dist/plan/index.js

@@ -11,10 +11,11 @@ export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, Provide
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export { createZitadelLoginPolicy } from './zitadel-login-policy.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
-export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export { PlatformBrokerPort } from './broker-entries.js';
 export { loginHostnameFor } from './login-host.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
@@ -29,3 +30,4 @@ export { createEdgeZones } from './edge-zones.js';
 export { createEdgeTunnels } from './edge-tunnels.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';
+export { readPlatformVersionStatus, wtfalchVersionsFromPnpmLockfile, providersStatusCoolifyPort, ghCliStatusGithubPort, } from './version-status.js';

package/dist/plan/plan-apply.js

@@ -1314,6 +1314,7 @@ const STEP_FIELDS = {
     'coolify:chat': 'chat.usesDomain',
     'coolify:calls': 'calls.enabled',
     'coolify:calls-service': 'calls.enabled',
+    'coolify:calls-chat': 'calls.enabled',
     'ai:budget': 'ai',
     'ai:key': 'ai',
     'cms:site': 'site',

package/dist/plan/platform-diff.d.ts

@@ -207,6 +207,15 @@ export declare const PLATFORM_AUTH_SMTP_SCOPE_KEY = "zitadel_platform_smtp_provi
  * requested, so the invite goes out once. `none` when no owner is declared.
  */
 export declare const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_owner_invite_user_id";
+/**
+ * #394: the id of the role-less ZITADEL machine user that reserves the
+ * username `admin` in the platform's own org, so nobody can sign up under a
+ * name Stalwart maps onto its Admin account. `foundry-admin` is reserved by
+ * the admin machine user itself.
+ */
+export declare const PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY = "zitadel_platform_reserved_admin_username";
+/** #394: recorded once the platform's own ZITADEL org has self-registration forced off. */
+export declare const PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY = "zitadel_platform_registration_closed";
 export declare const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = "zitadel_platform_admin_user_id";
 export declare const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = "zitadel_platform_admin_user_undelivered";
 /** #283: the created instance's id, recorded once its owner token is delivered. */
@@ -394,6 +403,15 @@ export declare const PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY = "stalwart_platf
  */
 export declare const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = "mail_applied_hostname";
 export declare const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = "mail_applied_git_ref";
+/**
+ * #661: recorded with {@link PLATFORM_MAIL_ROUTE_WANTED} once the mail
+ * server's settings write included the rule that delivers hosted recipients
+ * locally (`@wtfalch/email` 0.20.0). A platform applied before it lacks the id,
+ * so `planMail` plans the step once more; that run redeploys nothing, mints
+ * no key and creates nothing in the sign-in server.
+ */
+export declare const PLATFORM_MAIL_ROUTE_SCOPE_KEY = "mail_route_applied";
+export declare const PLATFORM_MAIL_ROUTE_WANTED = "local-first";
 /**
  * #177: where the mail server answers on the Coolify network
  * (`http://<custom_internal_name>:<port>`), recorded by the step the same way

package/dist/plan/platform-diff.js

@@ -234,6 +234,15 @@ export const PLATFORM_AUTH_SMTP_SCOPE_KEY = 'zitadel_platform_smtp_provider_id';
  * requested, so the invite goes out once. `none` when no owner is declared.
  */
 export const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_owner_invite_user_id';
+/**
+ * #394: the id of the role-less ZITADEL machine user that reserves the
+ * username `admin` in the platform's own org, so nobody can sign up under a
+ * name Stalwart maps onto its Admin account. `foundry-admin` is reserved by
+ * the admin machine user itself.
+ */
+export const PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY = 'zitadel_platform_reserved_admin_username';
+/** #394: recorded once the platform's own ZITADEL org has self-registration forced off. */
+export const PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY = 'zitadel_platform_registration_closed';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
 /** #283: the created instance's id, recorded once its owner token is delivered. */
@@ -432,6 +441,15 @@ export const PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY = 'stalwart_platform_admi
  */
 export const PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY = 'mail_applied_hostname';
 export const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = 'mail_applied_git_ref';
+/**
+ * #661: recorded with {@link PLATFORM_MAIL_ROUTE_WANTED} once the mail
+ * server's settings write included the rule that delivers hosted recipients
+ * locally (`@wtfalch/email` 0.20.0). A platform applied before it lacks the id,
+ * so `planMail` plans the step once more; that run redeploys nothing, mints
+ * no key and creates nothing in the sign-in server.
+ */
+export const PLATFORM_MAIL_ROUTE_SCOPE_KEY = 'mail_route_applied';
+export const PLATFORM_MAIL_ROUTE_WANTED = 'local-first';
 /**
  * #177: where the mail server answers on the Coolify network
  * (`http://<custom_internal_name>:<port>`), recorded by the step the same way
@@ -1708,7 +1726,10 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         Boolean(recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) &&
         // The ZITADEL run options reach the container only through the auth
         // step's redeploy, so a platform recorded before them still plans it.
-        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {
+        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
+        // #394: a platform applied before these existed plans the step again.
+        Boolean(recordedIds[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY]) &&
+        Boolean(recordedIds[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY])) {
         return { step: null, blocked: null };
     }
     // The admin key was minted but never reached the host. ZITADEL shows a
@@ -1844,9 +1865,16 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
         recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
         // #177: a mail step applied before this key existed never recorded it, and
         // org steps read it for Agora's mail upstream. Missing means unapplied.
-        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY]) {
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] &&
+        recordedIds[PLATFORM_MAIL_ROUTE_SCOPE_KEY] === PLATFORM_MAIL_ROUTE_WANTED) {
         return { step: null, blocked: null };
     }
+    // Only the route is missing: say so, the app is not redeployed.
+    const onlyRouteMissing = recordedIds[key] &&
+        recordedIds[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] &&
+        recordedIds[PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY] === platform.mail.hostname &&
+        recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY] === platform.mail.gitRef &&
+        recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY];
     // Stalwart's `x:ApiKey/set` shows a secret once. An id was minted but never
     // reached the host: report it, plan nothing, the same rule {@link planAuth}
     // follows for ZITADEL's own admin key.
@@ -1874,7 +1902,9 @@ function planMail(platform, recordedIds, executorBlocked, authReady) {
                 desired: { hostname: platform.mail.hostname, gitRef: platform.mail.gitRef },
             },
             step: {
-                description: `provision mail (Stalwart) at ${platform.mail.hostname}`,
+                description: onlyRouteMissing
+                    ? `write the mail server's local-delivery route at ${platform.mail.hostname}`
+                    : `provision mail (Stalwart) at ${platform.mail.hostname}`,
                 destroys: false,
                 migrates: false,
             },
@@ -2284,7 +2314,7 @@ function planAccessProvider(platform, recordedIds, executorBlocked) {
  * auth/ZITADEL client: `hc` is an internal operational tool, not something
  * an organisation member signs into. Whether this stays the platform's
  * heartbeat server long-term, instead of or alongside the hand-set-up
- * `hc.wtfalch.dev` instance, and what happens to that instance's own data,
+ * heartbeat instance, and what happens to that instance's own data,
  * are both still open "Decide" items on issue #540's own thread -- not
  * settled by this code.
  *
@@ -2598,7 +2628,7 @@ function planAi(platform, recordedIds, executorBlocked) {
 /**
  * #175: Archon (https://github.com/wtfalch/archon), the one shared console,
  * built fresh at `platform.archon.hostname` (`archon.<apex>`) rather than the
- * hand-deployed `operator.wtfalch.dev` it replaces (#165). One step,
+ * hand-deployed `operator` app it replaces (#165). One step,
  * `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, covers the app, its
  * database, its Cloudflare tunnel, Access app and DNS record, and its sign-in
  * client in the platform's own ZITADEL -- the same bundling {@link planAuth}

package/dist/plan/platform-org.d.ts

@@ -86,6 +86,8 @@ export interface OrgPlatformReadiness {
     callsReady: boolean;
     /** The platform's own sign-in (#168), which every org's own ZITADEL org lives inside. */
     authReady: boolean;
+    /** `https://<platform.auth.hostname>`, the platform's own sign-in issuer; `null` until {@link authReady}. The owner invite reads its issuer here, never from Agora's host config. */
+    authIssuer: string | null;
     /** The Access provider id the platform recorded (`ACCESS_PROVIDER_RECORD_KEY`), which every gate requires. `null` or absent until the platform has recorded it. */
     accessProviderId?: string | null;
     /** The jobs scheduler (#173) is enabled, applied, has recorded its internal address, and its admin token is held. */

package/dist/plan/platform-org.js

@@ -32,6 +32,7 @@ export const DEFAULT_ORG_PLATFORM_READINESS = {
     aiReady: false,
     callsReady: false,
     authReady: false,
+    authIssuer: null,
     jobsReady: false,
     edgeReady: false,
     missingKeys: { files: null, ai: null, jobs: null },
@@ -106,6 +107,7 @@ edgePortPresent = false) {
     const jobsApplied = platform.jobs.enabled && Boolean(platformRecordedIds[`coolify:jobs:${JOBS_SCHEDULER_KEY}`]);
     const jobsUrl = platformRecordedIds[JOBS_INTERNAL_URL_SCOPE_KEY];
     const edgeApplied = platform.edge.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_EDGE_KEY);
+    const authReady = platform.auth.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AUTH_KEY);
     const missing = (applied, ref) => applied && heldRefs !== undefined && !heldRefs.has(ref) ? ref : null;
     const missingKeys = {
         files: missing(filesApplied, ORG_PLATFORM_KEY_REFS.files),
@@ -133,7 +135,8 @@ edgePortPresent = false) {
         ...(platformRecordedIds[ACCESS_PROVIDER_RECORD_KEY]
             ? { accessProviderId: platformRecordedIds[ACCESS_PROVIDER_RECORD_KEY] }
             : {}),
-        authReady: platform.auth.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AUTH_KEY),
+        authReady,
+        authIssuer: authReady ? `https://${platform.auth.hostname}` : null,
         jobsReady: jobsApplied && jobsUrl !== undefined && missingKeys.jobs === null,
         ...(jobsApplied && jobsUrl === undefined ? { jobsUrlMissing: true } : {}),
         edgeReady: edgeApplied && edgePortPresent,