@wtfalch/foundry 0.9.0 → 0.10.0

package/dist/plan/executor.js

@@ -2,12 +2,14 @@ import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry } from '../org.js';
-import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, agoraHostnameFor, desiredAgoraEnv, } from './agora.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, agoraHostnameFor, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.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 { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { appHostname, entryHostnames, tunnelDnsHostnames, tunnelIngressHostnames, } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, loginBindingState, loginHostClientIds, pendingRemovalHosts, pendingRemovalState, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
-import { APP_ENV_APPLIED_SCOPE_KEY, CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, DB_ENV_APPLIED_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appStepKey, resolveAppEnv, } from './platform-diff.js';
+import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, } from './platform-diff.js';
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
  * listApps` -- a plain array, with no `loginBaseUri` or completeness signal
@@ -48,25 +50,6 @@ export class NotBuiltError extends Error {
 // ---------------------------------------------------------------------------
 // Hostnames
 // ---------------------------------------------------------------------------
-/**
- * The Coolify name of a hosting entry's app: `<slug>` for the `app` entry, so
- * the move to a list finds the app that runs today, `<slug>-<key>` for any
- * other.
- */
-function appNameFor(org, entry) {
-    return entry.key === APP_ENTRY_KEY ? org.slug : `${org.slug}-${entry.key}`;
-}
-/**
- * `<slug>.oikos.host` (`../slug.ts`), or `DeclaredOrg.domain` once
- * `hosting.usesDomain` is true — the same rule `diff.ts`'s `planApp` and
- * `planSite` document, reused here for the org's own hosted app, its
- * Cloudflare tunnel ingress and its ZITADEL issuer apps' redirect URIs
- * (task brief: "Hostnames: `<slug>.oikos.host` ... or `DeclaredOrg.domain`
- * when `hosting.usesDomain`").
- */
-function hostnameFor(org) {
-    return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
-}
 /**
  * #274 fix round 3 point 4: `zitadelLoginHost`'s own comparison between a
  * live app's ZITADEL-reported login base URI and the one this step itself
@@ -104,36 +87,6 @@ function callsHostnameFor(org) {
         ? `calls.${org.domain}`
         : `${org.slug}-calls.oikos.host`;
 }
-/**
- * The hostnames `cloudflareTunnel` routes to `COOLIFY_PROXY_ORIGIN`
- * (https://github.com/wtfalch/foundry/issues/115). A site-enabled org
- * (`org.ts`'s `SiteConfig.enabled`) has no single app hostname to reuse -- it
- * needs both its public site at `org.domain` and its cms studio (the sign-in
- * and editing surface, `@wtfalch/cms`) at `cms.<domain>`, so both are named
- * here; `org.domain` is non-null in that branch, guaranteed by `org.ts`'s
- * `validateSite` ("site.enabled requires domain"). Every other org --
- * concretely a hosting org, whose one app hostname this served before #115
- * ever existed -- keeps exactly the prior single-hostname behavior
- * ({@link hostnameFor}), unchanged.
- *
- * #145: an own-domain calls service adds `calls.<domain>` on top of whichever
- * of those a site/hosting org already gets, since calls can run alongside
- * either (or neither).
- */
-function tunnelIngressHostnames(org) {
-    const hostnames = org.site.enabled && org.domain ? [org.domain, `cms.${org.domain}`] : [hostnameFor(org)];
-    if (org.calls.enabled && org.calls.usesDomain && org.domain) {
-        hostnames.push(`calls.${org.domain}`);
-    }
-    // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set
-    // -- no toggle to gate this on. A level-1 org (no domain) adds nothing
-    // here: `<slug>-agora.oikos.host` rides the shared `*.oikos.host` wildcard
-    // tunnel (`scripts/shared-ingress.mjs`), not a per-org tunnel.
-    if (org.domain) {
-        hostnames.push(agoraHostnameFor(org));
-    }
-    return hostnames;
-}
 /**
  * The health URLs an outside prober should call for this org (#43): one per
  * app foundry runs for it. A hosting org's app answers at its own hostname,
@@ -143,8 +96,17 @@ function tunnelIngressHostnames(org) {
  * this file's hostname rules.
  */
 export function healthUrls(org) {
-    if (org.hosting.enabled)
-        return [`https://${hostnameFor(org)}/api/health`];
+    // One URL per entry that has a public name; an internal entry has none.
+    if (org.hosting.enabled && appEntry(org.hosting)) {
+        return org.hosting.entries.flatMap((entry) => {
+            const [hostname] = entryHostnames(org, entry);
+            if (!hostname)
+                return [];
+            return [
+                `https://${hostname}${entry.healthPath ?? (entry.buildPack === 'static' ? '/' : '/api/health')}`,
+            ];
+        });
+    }
     if (org.site.enabled && org.domain) {
         return [`https://${org.domain}/api/health`, `https://${cmsHostnameFor(org)}/api/health`];
     }
@@ -166,7 +128,7 @@ function mailOrgFor(org, usesDomain, mode) {
 /**
  * Every app on the Coolify box shares one Traefik reverse proxy, and Coolify
  * itself points that proxy's routing at whatever `domains` an application
- * declares (`coolifyApp`'s `hostnameFor(org)`) -- so a tunnel's ingress only
+ * declares (`coolifyApp`'s `appHostname(org)`) -- so a tunnel's ingress only
  * has to reach the proxy, never a specific app container.
  * `wtfalch/app-template`'s bootstrap (`bootstrap/steps/cf-tunnel.ts`, prior
  * art for the exact org this file's `cloudflareTunnel` implements, cited by
@@ -587,6 +549,8 @@ export class FoundryStepExecutor {
                 return this.zitadelCustomers(org, context);
             case 'coolify:app':
                 return this.coolifyApp(action, org, context);
+            case 'coolify:broker-entry':
+                return this.coolifyBrokerEntry(action, org, context);
             case 'coolify:database':
                 return this.coolifyDatabase(action, org, context);
             case 'coolify:calls':
@@ -637,7 +601,12 @@ export class FoundryStepExecutor {
      * any policy but foundry's, since that policy could let others in.
      */
     async cloudflareAccess(org) {
-        const domain = hostnameFor(org);
+        // Only the `app` entry has a public name (`planAccess`); per-entry
+        // hostnames are issue 309.
+        const entry = appEntry(org.hosting);
+        if (!entry)
+            throw new Error(`cloudflare:access for ${org.slug}: no '${APP_ENTRY_KEY}' hosting entry`);
+        const domain = appHostname(org);
         const name = `foundry:${org.id}`;
         const cf = this.ports.cloudflare;
         const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
@@ -655,7 +624,7 @@ export class FoundryStepExecutor {
             await cf.createAccessPolicy(app.id, {
                 name: ACCESS_POLICY_NAME,
                 decision: 'allow',
-                include: (appEntry(org.hosting)?.accessEmails ?? []).map((email) => ({ email: { email } })),
+                include: entry.accessEmails.map((email) => ({ email: { email } })),
             });
         }
         return { resourceId: app.id };
@@ -842,6 +811,9 @@ export class FoundryStepExecutor {
             ...(recorded[APP_CLIENT_ID_SCOPE_KEY]
                 ? org.hosting.issuerApps.filter((a) => a.kind === 'web').map((a) => a.name)
                 : []),
+            ...Object.keys(recorded)
+                .filter((key) => key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX))
+                .map((key) => key.slice(ENTRY_CLIENT_ID_SCOPE_PREFIX.length)),
             ...(recorded[CMS_CLIENT_ID_SCOPE_KEY] ? ['cms'] : []),
             ...(recorded[AGORA_CLIENT_ID_SCOPE_KEY] ? ['agora'] : []),
         ].map((name) => recorded[`zitadel:app:${name}`]));
@@ -1025,7 +997,7 @@ export class FoundryStepExecutor {
             ? cmsHostnameFor(org)
             : isAgoraClient
                 ? agoraHostnameFor(org)
-                : hostnameFor(org);
+                : appHostname(org);
         // Native apps sign in via device code, with no redirect of their own
         // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
         // file) -- empty arrays rather than a web app's callback/logout URLs.
@@ -1037,11 +1009,23 @@ export class FoundryStepExecutor {
         const redirectUri = isAgoraClient
             ? `https://${hostname}/callback`
             : `https://${hostname}/auth/callback`;
+        // An entry with `uses.auth` signs in at its own exact hostnames, one pair
+        // of addresses each; a `*` adds none (`entryHostnames`).
+        const authEntry = org.hosting.entries.find((e) => e.key === action.key && e.uses?.auth);
+        const hosts = authEntry ? entryHostnames(org, authEntry) : null;
         const created = await this.ports.zitadel.createOidcApp(zitadelOrgId, projectId, {
             name: action.key,
             appType,
-            redirectUris: appType === 'native' ? [] : [redirectUri],
-            postLogoutRedirectUris: appType === 'native' ? [] : [`https://${hostname}/`],
+            redirectUris: appType === 'native'
+                ? []
+                : hosts
+                    ? hosts.map((host) => `https://${host}/auth/callback`)
+                    : [redirectUri],
+            postLogoutRedirectUris: appType === 'native'
+                ? []
+                : hosts
+                    ? hosts.map((host) => `https://${host}/`)
+                    : [`https://${hostname}/`],
         });
         if (appType === 'web') {
             // `coolifyApp`'s own `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` to
@@ -1056,7 +1040,9 @@ export class FoundryStepExecutor {
                 ? CMS_CLIENT_ID_SCOPE_KEY
                 : isAgoraClient
                     ? AGORA_CLIENT_ID_SCOPE_KEY
-                    : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+                    : authEntry
+                        ? entryClientIdScopeKey(action.key)
+                        : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
         }
         return { resourceId: created.appId };
     }
@@ -1111,9 +1097,9 @@ export class FoundryStepExecutor {
             await this.ports.coolify.raw('POST', `/applications/${recordedAppId}/stop`);
             return { resourceId: recordedAppId };
         }
-        const entry = appEntry(org.hosting);
+        const entry = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
         if (!entry)
-            throw new Error(`coolify:app for ${org.slug}: no '${APP_ENTRY_KEY}' hosting entry`);
+            throw new Error(`coolify:app for ${org.slug}: no hosting entry for ${action.key}`);
         // A level-1 org with no bespoke app of its own gets the shared standard
         // app instead (gap P1, `.plans/2026-09-26-level-1-org-map.md`): an entry
         // with no `repo`.
@@ -1139,6 +1125,15 @@ export class FoundryStepExecutor {
                 environmentIds: [environment.id],
             });
         }
+        // An entry with no names is internal: the other entries reach it as
+        // `<slug>-<key>`, and it gets no domain, route or DNS record.
+        const names = entryHostnames(org, entry);
+        const isStatic = entry.buildPack === 'static';
+        const folderField = isStatic ? 'publish_directory' : 'base_directory';
+        const settingsKey = appSettingsAppliedScopeKey(entry.key);
+        const domainsKey = appDomainsAppliedScopeKey(entry.key);
+        let haveNames;
+        let have;
         let appId;
         if (existing) {
             appId = existing.uuid;
@@ -1152,6 +1147,8 @@ export class FoundryStepExecutor {
             if (!isRunningOrStarting(live.status)) {
                 await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
             }
+            have = appliedAppSettings(context.recordedIds(), entry.key);
+            haveNames = appliedAppDomains(org, context.recordedIds(), entry.key);
         }
         else {
             const server = await this.resolveServer();
@@ -1166,13 +1163,49 @@ export class FoundryStepExecutor {
                 git_branch: entry.branch,
                 build_pack: entry.buildPack,
                 name: appNameFor(org, entry),
-                domains: hostnameFor(org),
+                domains: names.length > 0 ? names.join(',') : undefined,
+                autogenerate_domain: names.length > 0 ? undefined : false,
+                // A static site is served by Coolify's own web server on port 80.
+                ports_exposes: isStatic ? '80' : entry.port === null ? undefined : String(entry.port),
+                is_auto_deploy_enabled: entry.autoDeploy,
+                [folderField]: entry.folder === null ? undefined : `/${entry.folder}`,
                 // Only the shared standard app builds from this repo; a bespoke
                 // app's Dockerfile is at its own repo's root.
                 dockerfile_location: entry.repo ? undefined : DEFAULT_APP_DOCKERFILE,
             });
             appId = created.uuid;
-        }
+            // Create sent every setting, so nothing is left to patch.
+            have = appSettingsOf(entry);
+            haveNames = names;
+        }
+        // Patch what differs from what the app has. A crash before the marker is
+        // recorded below leaves the old one, so the retry patches the same
+        // difference again.
+        const want = appSettingsOf(entry);
+        const patch = {};
+        if (want.folder !== have.folder)
+            patch[folderField] = want.folder ? `/${want.folder}` : '/';
+        if (want.port !== have.port && want.port !== null && !isStatic) {
+            patch.ports_exposes = String(want.port);
+        }
+        if (want.autoDeploy !== have.autoDeploy)
+            patch.is_auto_deploy_enabled = want.autoDeploy;
+        // Create names the app after `domains`; a changed name reaches a live app
+        // here (rule 3). The internal name is set after create, as the calls
+        // stack's apps do.
+        if (JSON.stringify(names) !== JSON.stringify(haveNames))
+            patch.domains = names.join(',');
+        if (names.length === 0 && (!existing || patch.domains !== undefined)) {
+            patch.custom_internal_name = appNameFor(org, entry);
+        }
+        if (Object.keys(patch).length > 0)
+            await this.ports.coolify.updateApplication(appId, patch);
+        // The container builds and listens from these only at its next deploy.
+        const settingsNeedDeploy = Boolean(patch.base_directory ||
+            patch.publish_directory ||
+            patch.ports_exposes ||
+            patch.domains !== undefined ||
+            patch.custom_internal_name);
         // The database plans before the app (`diff.ts`'s `computePlanDetail`,
         // hosting-wiring campaign) so that, on the same apply, the database's
         // resource id is already recorded by the time this runs -- but this also
@@ -1188,7 +1221,7 @@ export class FoundryStepExecutor {
         // Restart when the push changed something, or when no earlier run got as
         // far as restarting after one (marker missing): a crash between the push
         // and the restart leaves the env right and the container stale.
-        const dbNeedsRestart = dbPush.pushed && (dbPush.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]);
+        const dbNeedsRestart = dbPush.pushed && (dbPush.changed || !context.recordedIds()[dbEnvAppliedScopeKey(entry.key)]);
         // Every app keeps its own logs across a redeploy (#75). Unconditional,
         // like the env push below: found by mount path before create, so a
         // re-run (or the drift step `diff.ts`'s `planApp` plans for an app that
@@ -1196,27 +1229,42 @@ export class FoundryStepExecutor {
         // `ensureLogVolume` whether this app was already running before this
         // call -- see its own doc comment for why that decides whether to
         // restart it.
-        await this.ensureLogVolume(appId, org, Boolean(existing));
+        await this.ensureLogVolume(appId, org, Boolean(existing), appNameFor(org, entry));
         // The app receives whatever it needs to sign in (gap P2). Unconditional,
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
-        const appEnv = await this.pushAppEnv(appId, org, entry, context);
+        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null);
         // Rule 4 (#239, #243): a container reads its env only at start, so an app
         // that was already there is restarted, once, when its database URLs or its
         // declared appEnv changed.
-        if ((appEnv.changed || dbNeedsRestart) && existing)
+        // A new folder needs a build, which a restart does not do, so a settings
+        // change deploys instead (rule 3), and that carries the env too.
+        if (settingsNeedDeploy)
+            await this.ports.coolify.deploy(appId);
+        else if ((appEnv.changed || dbNeedsRestart) && existing)
             await this.ports.coolify.restart(appId);
-        // Recorded only after the restart succeeded: a failed restart leaves the
-        // old value, so the next plan replans (rule 3). The db marker is not a URL.
-        context.recordScopeId(APP_ENV_APPLIED_SCOPE_KEY, appEnv.applied);
+        // Recorded only after the redeploy succeeded: a failed one leaves the old
+        // value, so the next plan replans (rule 3). The db marker is not a URL.
+        // A port taken back to null was not patched, so the marker keeps the old
+        // one and `planApp` reports it instead of planning it.
+        context.recordScopeId(settingsKey, JSON.stringify({ ...want, port: want.port ?? have.port }));
+        context.recordScopeId(domainsKey, JSON.stringify(names));
+        context.recordScopeId(appEnvAppliedScopeKey(entry.key), appEnv.applied);
+        if (entry.uses?.auth) {
+            context.recordScopeId(entryAuthEnvAppliedScopeKey(entry.key), appEnv.authApplied);
+        }
         if (dbPush.pushed)
-            context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
+            context.recordScopeId(dbEnvAppliedScopeKey(entry.key), '1');
         // #140 rework (2026-09-28 lettermint-org-mail swap): the hosted app's own
         // Lettermint project, domain restriction and `MAIL_FROM` (only the app
         // started by this same step, per the design's "only apps that send mail
         // get it" -- cms and calls do not). A no-op until `coolify:mail` has
         // actually resolved a mail domain for this org.
-        await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
+        // One Lettermint project, `<slug>-app`, belongs to the `app` entry; a
+        // second entry sharing the name would delete the first's live token.
+        if (entry.key === APP_ENTRY_KEY) {
+            await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
+        }
         return { resourceId: appId };
     }
     /**
@@ -1240,13 +1288,13 @@ export class FoundryStepExecutor {
      * `createGithubAppApplication`'s own instant-deploy path, so a restart
      * here would only be a redundant extra one).
      */
-    async ensureLogVolume(appId, org, wasAlreadyRunning) {
+    async ensureLogVolume(appId, org, wasAlreadyRunning, appName = org.slug) {
         const storages = await this.ports.coolify.listStorages(appId);
         const already = (storages.persistent_storages ?? []).some((s) => s.mount_path === LOG_DIR);
         if (already)
             return;
         await this.ports.coolify.createPersistentStorage(appId, {
-            name: `${org.slug}-logs`,
+            name: `${appName}-logs`,
             mount_path: LOG_DIR,
         });
         if (wasAlreadyRunning) {
@@ -1293,14 +1341,16 @@ export class FoundryStepExecutor {
         // Handles the database being provisioned after the app already exists
         // (`coolifyApp`'s own push handles the more common order, database
         // before app on the same apply -- `diff.ts`'s `computePlanDetail`).
-        const appId = context.recordedIds()[`coolify:app:${appStepKey(org)}`];
-        if (appId) {
+        const dbEntry = org.hosting.entries.find((e) => e.database);
+        const appId = dbEntry && context.recordedIds()[`coolify:app:${appStepKey(org, dbEntry.key)}`];
+        if (dbEntry && appId) {
+            const markerKey = dbEnvAppliedScopeKey(dbEntry.key);
             const push = await this.pushDatabaseUrl(appId, dbId, org.slug.replace(/-/g, '_'));
             if (push.pushed) {
-                if (push.changed || !context.recordedIds()[DB_ENV_APPLIED_SCOPE_KEY]) {
+                if (push.changed || !context.recordedIds()[markerKey]) {
                     await this.ports.coolify.restart(appId);
                 }
-                context.recordScopeId(DB_ENV_APPLIED_SCOPE_KEY, '1');
+                context.recordScopeId(markerKey, '1');
             }
         }
         return { resourceId: dbId };
@@ -1390,21 +1440,41 @@ export class FoundryStepExecutor {
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
      */
-    async pushAppEnv(appId, org, entry, context) {
+    async pushAppEnv(appId, org, entry, context, authIssuer) {
         const recorded = context.recordedIds();
         const envs = [
-            { key: 'APP_URL', value: `https://${hostnameFor(org)}` },
+            // Only the `app` entry has a public name; the others are internal.
+            ...(entry.key === APP_ENTRY_KEY
+                ? [{ key: 'APP_URL', value: `https://${appHostname(org)}` }]
+                : []),
             // #75: read back by the package-side pino sink (not this repo's job,
             // #75 "What belongs where") once `ensureLogVolume` has mounted the
             // matching volume.
             { key: 'LOG_DIR', value: LOG_DIR },
         ];
-        const zitadelOrgId = recorded.zitadel_org;
-        if (zitadelOrgId)
-            envs.push({ key: 'AUTH_ORGANIZATION_ID', value: zitadelOrgId });
-        const clientId = recorded[APP_CLIENT_ID_SCOPE_KEY];
-        if (clientId)
-            envs.push({ key: 'AUTH_CLIENT_ID', value: clientId });
+        // An entry with `uses.auth` signs in one organisation, with its own client
+        // and the issuer; any other entry keeps the org's staff organisation and
+        // the one hosted-app client.
+        const authEnv = entryAuthEnv(org, entry, recorded, authIssuer);
+        if (entry.uses?.auth) {
+            // A customers entry never falls back to the staff organisation's id.
+            if (!authEnv.AUTH_ORGANIZATION_ID) {
+                throw new Error(`coolify:app for ${org.slug}: entry '${entry.key}' signs in ${entry.uses.auth.users}, whose organisation id is not recorded yet`);
+            }
+            for (const [key, value] of Object.entries(authEnv))
+                envs.push({ key, value });
+            const appKey = await this.ensureAuthAppKey(appId);
+            if (appKey)
+                envs.push({ key: 'AUTH_APP_KEY', value: appKey });
+        }
+        else {
+            const zitadelOrgId = recorded.zitadel_org;
+            if (zitadelOrgId)
+                envs.push({ key: 'AUTH_ORGANIZATION_ID', value: zitadelOrgId });
+            const clientId = recorded[APP_CLIENT_ID_SCOPE_KEY];
+            if (clientId)
+                envs.push({ key: 'AUTH_CLIENT_ID', value: clientId });
+        }
         // The invited owner's ZITADEL user id (gap P3): the app uses it to make
         // them its own owner in authz on first sign-in. `runSteps` records this
         // under the same `system:kind:key` shape every step's `resourceId` uses
@@ -1433,7 +1503,66 @@ export class FoundryStepExecutor {
         // replans this step when the declared map changes (rule 3). Ids and a
         // domain, never a secret.
         const applied = JSON.stringify(appEnv);
-        return { changed: applied !== (recorded[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}'), applied };
+        // The sign-in values, recorded by `coolifyApp` the same way; the key is
+        // never part of them.
+        const authApplied = JSON.stringify(authEnv);
+        return {
+            changed: applied !== (recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}') ||
+                (Boolean(entry.uses?.auth) &&
+                    authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}')),
+            applied,
+            authApplied,
+        };
+    }
+    /**
+     * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
+     * of at least 32 characters (the broker refuses a shorter one). `null` once
+     * it has one: the app's env is where the key lives, and
+     * `coolifyBrokerEntry` reads it back from there. It goes to this env and
+     * the broker's, nowhere else.
+     */
+    async ensureAuthAppKey(appId) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        const already = envs.some((e) => e.key === 'AUTH_APP_KEY' && !e.is_preview && (e.value ?? '').length >= 32);
+        return already ? null : randomBytes(32).toString('base64url');
+    }
+    /**
+     * `plan/diff.ts`'s `planBrokerEntries` (F5): the entry's `AUTH_APPS` entry,
+     * written by `writeBrokerEntry` with the key `pushAppEnv` put in the app's
+     * env. Records what it wrote (never the key) and any foreign entry the
+     * broker would drop.
+     */
+    async coolifyBrokerEntry(action, org, context) {
+        const broker = this.ports.broker;
+        if (!broker)
+            throw new Error(`coolify:broker-entry for ${org.slug}: the broker port is not wired`);
+        const recorded = context.recordedIds();
+        const entry = org.hosting.entries.find((e) => appStepKey(org, e.key) === action.key);
+        if (!entry?.uses?.auth) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: no uses.auth entry for ${action.key}`);
+        }
+        const wanted = wantedBrokerEntry(org, entry, recorded);
+        if ('missing' in wanted) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: ${wanted.missing.map((m) => m.what).join(', ')} not recorded yet`);
+        }
+        const appId = recorded[`coolify:app:${action.key}`];
+        if (!appId) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: app ${action.key} is not recorded yet`);
+        }
+        const appKey = (await this.ports.coolify.listEnvs(appId)).find((e) => e.key === 'AUTH_APP_KEY' && !e.is_preview)?.value;
+        if (!appKey || appKey.length < 32) {
+            throw new Error(`coolify:broker-entry for ${org.slug}: app ${appId} has no AUTH_APP_KEY yet`);
+        }
+        const previousRaw = recorded[brokerEntryAppliedScopeKey(entry.key)];
+        const result = await writeBrokerEntry(broker, {
+            want: wanted.want,
+            appKey,
+            previous: previousRaw ? JSON.parse(previousRaw) : null,
+        });
+        context.recordScopeId(brokerEntryWarningsScopeKey(entry.key), JSON.stringify(result.invalidForeign));
+        // Last: a run that failed above plans the step again.
+        context.recordScopeId(brokerEntryAppliedScopeKey(entry.key), JSON.stringify(wanted.want));
+        return {};
     }
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
@@ -2554,7 +2683,7 @@ export class FoundryStepExecutor {
         // offline.tf's bootstrap, cited by
         // https://github.com/wtfalch/foundry/issues/71): every app on the
         // Coolify box already gets a Traefik route from the `domains` its
-        // `coolify:app` step declared (`hostnameFor(org)`, this file's
+        // `coolify:app` step declared (`appHostname(org)`, this file's
         // `coolifyApp`), so a cloudflared connector joined to the same Docker
         // network only has to reach Traefik and let it route by Host header --
         // the connector never needs to know the app's own container name or
@@ -2802,7 +2931,7 @@ export class FoundryStepExecutor {
         }
         const dnsTarget = `${tunnelId}.cfargotunnel.com`;
         const previousTargets = new Set([...previousIds].filter((id) => id !== tunnelId).map((id) => `${id}.cfargotunnel.com`));
-        const hostnames = tunnelIngressHostnames(org).filter((hostname) => hostname === domain || hostname.endsWith(`.${domain}`));
+        const hostnames = tunnelDnsHostnames(org, domain);
         const droppedHostnames = previousHostnames.filter((hostname) => !hostnames.includes(hostname));
         const conflicts = [];
         const toCreate = [];

package/dist/plan/hostnames.d.ts

@@ -0,0 +1,24 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+/**
+ * The full names an entry is served at. With `hosting.usesDomain` off, or no
+ * domain, `hostnames` is not read: the `app` entry is at `<slug>.oikos.host`
+ * and every other entry is internal. `'*'` names nothing here; the wildcard is
+ * acted on elsewhere.
+ */
+export declare function entryHostnames(org: DeclaredOrg, entry: HostingEntry): string[];
+/**
+ * The one primary name of the org's app: its first, or the name the app was
+ * served at before entries had hostnames. `APP_URL`, the ZITADEL redirect URI
+ * and the jobs registration read it.
+ */
+export declare function appHostname(org: DeclaredOrg): string;
+/** What `domains` held on an `app` entry's Coolify app before entries had hostnames. */
+export declare function legacyAppHostname(org: DeclaredOrg): string;
+/**
+ * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
+ * #164): a site's two names, every entry's names, an own-domain calls name and
+ * Agora's. An org that does not host keeps the single name it always had.
+ */
+export declare function tunnelIngressHostnames(org: DeclaredOrg): string[];
+/** The ingress names that get a DNS record: those under the org's own domain. */
+export declare function tunnelDnsHostnames(org: DeclaredOrg, domain: string): string[];

package/dist/plan/hostnames.js

@@ -0,0 +1,56 @@
+import { APP_ENTRY_KEY } from '../org.js';
+import { agoraHostnameFor } from './agora.js';
+/**
+ * The full names an entry is served at. With `hosting.usesDomain` off, or no
+ * domain, `hostnames` is not read: the `app` entry is at `<slug>.oikos.host`
+ * and every other entry is internal. `'*'` names nothing here; the wildcard is
+ * acted on elsewhere.
+ */
+export function entryHostnames(org, entry) {
+    const { domain } = org;
+    if (!org.hosting.usesDomain || !domain) {
+        return entry.key === APP_ENTRY_KEY ? [`${org.slug}.oikos.host`] : [];
+    }
+    return entry.hostnames.flatMap((name) => name === '*' ? [] : name === '@' ? [domain] : [`${name}.${domain}`]);
+}
+/**
+ * The one primary name of the org's app: its first, or the name the app was
+ * served at before entries had hostnames. `APP_URL`, the ZITADEL redirect URI
+ * and the jobs registration read it.
+ */
+export function appHostname(org) {
+    const entry = org.hosting.entries.find((e) => e.key === APP_ENTRY_KEY);
+    const first = entry ? entryHostnames(org, entry)[0] : undefined;
+    return first ?? legacyAppHostname(org);
+}
+/** What `domains` held on an `app` entry's Coolify app before entries had hostnames. */
+export function legacyAppHostname(org) {
+    return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
+}
+/**
+ * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
+ * #164): a site's two names, every entry's names, an own-domain calls name and
+ * Agora's. An org that does not host keeps the single name it always had.
+ */
+export function tunnelIngressHostnames(org) {
+    const hostnames = org.site.enabled && org.domain ? [org.domain, `cms.${org.domain}`] : [];
+    if (org.hosting.enabled) {
+        for (const entry of org.hosting.entries)
+            hostnames.push(...entryHostnames(org, entry));
+    }
+    else if (hostnames.length === 0) {
+        hostnames.push(legacyAppHostname(org));
+    }
+    if (org.calls.enabled && org.calls.usesDomain && org.domain) {
+        hostnames.push(`calls.${org.domain}`);
+    }
+    // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set.
+    if (org.domain) {
+        hostnames.push(agoraHostnameFor(org));
+    }
+    return [...new Set(hostnames)];
+}
+/** The ingress names that get a DNS record: those under the org's own domain. */
+export function tunnelDnsHostnames(org, domain) {
+    return tunnelIngressHostnames(org).filter((hostname) => hostname === domain || hostname.endsWith(`.${domain}`));
+}

package/dist/plan/index.d.ts

@@ -24,6 +24,8 @@ export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCop
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, 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';
 export type { LoginHostBinding, LoginHostBindingsPort } from './login-host.js';
 export { loginHostnameFor } from './login-host.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './mail-identity.js';

package/dist/plan/index.js

@@ -12,6 +12,7 @@ export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } 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 { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { PlatformBrokerPort } from './broker-entries.js';
 export { loginHostnameFor } from './login-host.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';

package/dist/plan/locked-hostnames.d.ts

@@ -0,0 +1,8 @@
+import type { DeclaredOrg } from '../org.js';
+/**
+ * The names under the org's domain that foundry owns, so no hosting entry may
+ * take one: Agora, the cms studio when the site is on, calls when it uses the
+ * domain, the sign-in host when the issuer does, and every platform service
+ * hostname that falls under the domain. Empty for an org with no domain.
+ */
+export declare function lockedHostnames(org: DeclaredOrg, platformHostnames: readonly string[]): Set<string>;

package/dist/plan/locked-hostnames.js

@@ -0,0 +1,26 @@
+import { agoraHostnameFor } from './agora.js';
+import { loginHostnameFor } from './login-host.js';
+/**
+ * The names under the org's domain that foundry owns, so no hosting entry may
+ * take one: Agora, the cms studio when the site is on, calls when it uses the
+ * domain, the sign-in host when the issuer does, and every platform service
+ * hostname that falls under the domain. Empty for an org with no domain.
+ */
+export function lockedHostnames(org, platformHostnames) {
+    const { domain } = org;
+    const locked = new Set();
+    if (!domain)
+        return locked;
+    locked.add(agoraHostnameFor(org));
+    if (org.site.enabled)
+        locked.add(`cms.${domain}`);
+    if (org.calls.enabled && org.calls.usesDomain)
+        locked.add(`calls.${domain}`);
+    if (org.issuer.usesDomain)
+        locked.add(loginHostnameFor(org));
+    for (const hostname of platformHostnames) {
+        if (hostname.endsWith(`.${domain}`))
+            locked.add(hostname);
+    }
+    return locked;
+}