@wtfalch/foundry 0.9.0 → 0.10.0

package/dist/plan/diff.js

@@ -1,9 +1,11 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { appEntry } from '../org.js';
+import { APP_ENTRY_KEY } from '../org.js';
 import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, desiredAgoraEnv, } from './agora.js';
+import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
+import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } 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, versionNotAppliedLine, } 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, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
@@ -164,12 +166,16 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // `AUTH_CLIENT_ID`, which only exists once that app's own `zitadel:app`
     // step has run -- `plan-apply.ts`'s `runSteps` executes `plannedSteps` in
     // this array order, one at a time.
+    // Customers before the entries that sign them in: `pushAppEnv` and the
+    // broker entry read the customers organisation's id.
+    const customers = planCustomers(org, live, claimed, recordedIds);
+    if (customers)
+        plannedSteps.push(customers);
     plannedSteps.push(...planIssuerApps(org, byKey, claimed));
+    plannedSteps.push(...planEntryClients(org, byKey, claimed));
     // The Access gate before the database, app, tunnel and zone (#84): on a
     // first apply the hostname is gated before anything answers on it.
-    const access = planAccess(org, recordedIds);
-    if (access)
-        plannedSteps.push(access);
+    plannedSteps.push(...planAccess(org, recordedIds));
     // Database before app (hosting-wiring campaign): `plan-apply.ts`'s
     // `runSteps` executes `plannedSteps` in this array order, and the app's own
     // step (`executor.ts`'s `coolifyApp`) pushes the database's connection
@@ -179,9 +185,12 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const database = planDatabase(org, byKey, claimed);
     if (database)
         plannedSteps.push(database);
-    const app = planApp(org, byKey, claimed, recordedIds, plannedSteps);
-    if (app.step)
-        plannedSteps.push(app.step);
+    const authIssuer = 'error' in agoraHost ? null : agoraHost.issuer;
+    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+    plannedSteps.push(...app.steps);
+    // After the apps: the broker entry's key is minted into each app's env.
+    const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
+    plannedSteps.push(...brokerEntries.steps);
     const tunnel = planTunnel(org, byKey, claimed, recordedIds);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -209,11 +218,6 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     else if (rateLimit) {
         plannedSteps.push(rateLimit);
     }
-    // After the apps: the customers org is granted the project the first app
-    // step creates.
-    const customers = planCustomers(org, live, claimed, recordedIds);
-    if (customers)
-        plannedSteps.push(customers);
     // #164: every org's own Agora -- always on, no toggle. Last, so nothing
     // else in the org waits on it: `runSteps` stops at the first failing step.
     // Its fixed ZITADEL client before the Coolify app it signs into:
@@ -288,6 +292,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...zoneBlocked);
     // #243: an appEnv source nothing will record is reported, not silently skipped.
     unmanaged.push(...app.blocked);
+    unmanaged.push(...brokerEntries.blocked);
     return { orgId: org.id, plannedSteps, unmanaged, versionChanges };
 }
 /**
@@ -524,6 +529,7 @@ const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
 const CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
 /** #236: restated from `executor.ts`, the same rule: the domain the org tunnel's DNS was last published under. */
 const CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY = 'cloudflare_tunnel_dns_domain';
+const CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY = 'cloudflare_tunnel_dns_hostnames';
 /** Restated from `executor.ts`, the same rule: the mail domain the last apply resolved. */
 const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
 /** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
@@ -1387,7 +1393,7 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * resource's `enabled` field -- a live resource nothing has actually
  * checked yet is assumed fine rather than replanned every time.
  */
-function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
+function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
     // #243: an `appEnv` source with no recorded value and no step planned to
     // record one this run has nothing to push, now or after this apply.
     const sourceStep = {
@@ -1395,21 +1401,27 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
         aiOrganisationId: ['ai', 'organisation'],
         mailDomain: ['coolify', 'mail'],
     };
-    const entry = org.hosting.enabled ? appEntry(org.hosting) : undefined;
+    const entry = org.hosting.enabled
+        ? org.hosting.entries.find((e) => e.key === entryKey)
+        : undefined;
+    // Descriptions and unmanaged keys of the `app` entry stay as they were; any
+    // other entry is named in them.
+    const label = entryKey === APP_ENTRY_KEY ? 'app' : `${entryKey} app`;
+    const blockedKey = (rest) => entryKey === APP_ENTRY_KEY ? `coolify:app:${rest}` : `coolify:app:${entryKey}:${rest}`;
     const { values: wantedEnv, unresolved } = entry
         ? resolveAppEnv(org, entry, recordedIds)
         : { values: {}, unresolved: [] };
-    const stepKey = appStepKey(org);
+    const stepKey = appStepKey(org, entryKey);
     const blocked = entry
         ? unresolved
             .filter(([, source]) => !plannedSteps.some((p) => p.action.system === sourceStep[source][0] &&
             p.action.kind === sourceStep[source][1]))
             .map(([name, source]) => ({
-            description: `${org.slug}'s app env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
-            key: `coolify:app:env:${name}`,
+            description: `${org.slug}'s ${label} env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
+            key: blockedKey(`env:${name}`),
         }))
         : [];
-    const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     if (toggled)
         return { step: toggled, blocked };
     if (!entry)
@@ -1428,7 +1440,7 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
             step: {
                 action,
                 step: {
-                    description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
+                    description: `add a durable log directory to ${org.slug}'s ${label} (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
                     destroys: false,
                     migrates: false,
                 },
@@ -1447,8 +1459,8 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
         // Rule 2: the push cannot succeed yet, so report it rather than replan
         // forever.
         blocked.push({
-            description: `${org.slug}'s app database URLs are blocked, not planned: the database reports no internal connection URL yet`,
-            key: 'coolify:app:database-url',
+            description: `${org.slug}'s ${label} database URLs are blocked, not planned: the database reports no internal connection URL yet`,
+            key: blockedKey('database-url'),
         });
     }
     else if (dbReady &&
@@ -1458,12 +1470,12 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
         ((Array.isArray(envNames) && !envNames.includes('DATABASE_URL_OWNER')) ||
             // A crash between the push and the restart leaves the env right and no
             // marker: replan once more to restart and set it.
-            !recordedIds[DB_ENV_APPLIED_SCOPE_KEY])) {
+            !recordedIds[dbEnvAppliedScopeKey(entryKey)])) {
         return {
             step: {
                 action,
                 step: {
-                    description: `give ${org.slug}'s app its owner and runtime database URLs and restart it (#239)`,
+                    description: `give ${org.slug}'s ${label} its owner and runtime database URLs and restart it (#239)`,
                     destroys: false,
                     migrates: false,
                 },
@@ -1474,12 +1486,71 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
     // #243 (rule 3): a changed entry `env` reaches an app that is already
     // live. `pushAppEnv` records what it pushed, so this plans the same step
     // again, with a redeploy, only once the resolved map differs from that.
-    if (JSON.stringify(wantedEnv) !== (recordedIds[APP_ENV_APPLIED_SCOPE_KEY] ?? '{}')) {
+    if (JSON.stringify(wantedEnv) !== (recordedIds[appEnvAppliedScopeKey(entryKey)] ?? '{}')) {
         return {
             step: {
                 action,
                 step: {
-                    description: `push ${org.slug}'s changed app env (appEnv) and redeploy the app`,
+                    description: `push ${org.slug}'s changed ${label} env (appEnv) and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // F5 (rule 3): who signs in, which client and which issuer reach an app
+    // that is already live. `pushAppEnv` records what it pushed.
+    if (entry.uses?.auth &&
+        JSON.stringify(entryAuthEnv(org, entry, recordedIds, authIssuer)) !==
+            (recordedIds[entryAuthEnvAppliedScopeKey(entryKey)] ?? '{}')) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `push ${org.slug}'s ${label} sign-in env (organisation, client, issuer) and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // A changed hostname reaches an app that is already live: its domains are
+    // patched and it is redeployed.
+    if (JSON.stringify(entryHostnames(org, entry)) !==
+        JSON.stringify(appliedAppDomains(org, recordedIds, entryKey))) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `apply ${org.slug}'s ${label} hostnames and redeploy the app`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked,
+        };
+    }
+    // A changed `folder`, `port` or `autoDeploy` reaches an app that is already live.
+    const want = appSettingsOf(entry);
+    const have = appliedAppSettings(recordedIds, entryKey);
+    // Coolify has no value that resets a port to its default, so a port taken
+    // back to null cannot be applied (rule 2): reported, not planned.
+    if (want.port === null && have.port !== null) {
+        blocked.push({
+            description: `${org.slug}'s ${label} port is blocked, not planned: Coolify cannot reset it to its default, so set a port`,
+            key: blockedKey('port'),
+        });
+    }
+    if (want.folder !== have.folder ||
+        want.autoDeploy !== have.autoDeploy ||
+        (want.port !== null && want.port !== have.port)) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `apply ${org.slug}'s ${label} folder, port and auto-deploy settings`,
                     destroys: false,
                     migrates: false,
                 },
@@ -1489,6 +1560,44 @@ function planApp(org, byKey, claimed, recordedIds, plannedSteps) {
     }
     return { step: null, blocked };
 }
+/**
+ * {@link planApp} once per hosting entry. A key with no declared entry still
+ * runs for `app`, so an org that turns hosting off parks the app it has live.
+ */
+function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+    const steps = [];
+    const blocked = [];
+    // An entry removed from the list while its app is recorded is parked like a
+    // removed `app`: `planApp` finds no entry for its key.
+    const recordedKeys = Object.keys(recordedIds)
+        .filter((id) => id.startsWith(`coolify:app:${org.id}:`))
+        .map((id) => id.slice(`coolify:app:${org.id}:`.length));
+    const declared = new Set([APP_ENTRY_KEY, ...org.hosting.entries.map((e) => e.key)]);
+    const keys = new Set([...declared, ...recordedKeys]);
+    for (const key of keys) {
+        if (!declared.has(key)) {
+            // The reader gives a parked app no `enabled` field, so only a running
+            // app is parked; a stopped one plans nothing and is still claimed.
+            const resource = byKey.get(resourceKey('coolify', 'app', appStepKey(org, key)));
+            const status = resource?.config.status;
+            if (resource)
+                claimed.add(resourceKey('coolify', 'app', appStepKey(org, key)));
+            if (!resource || (typeof status === 'string' && /^(exited|stopped)/.test(status)))
+                continue;
+        }
+        const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+        // The executor pushes the issuer the plan read, the way Agora gets its host values.
+        if (app.step && app.step.action.desired.enabled !== false) {
+            const signsIn = org.hosting.entries.some((e) => e.key === key && e.uses?.auth);
+            if (signsIn)
+                app.step.action.desired = { ...app.step.action.desired, authIssuer };
+        }
+        if (app.step)
+            steps.push(app.step);
+        blocked.push(...app.blocked);
+    }
+    return { steps, blocked };
+}
 /**
  * #173: register the org's own app with the platform's jobs scheduler
  * (https://github.com/wtfalch/jobs's admin API, jobs#62), so the scheduler
@@ -1537,7 +1646,7 @@ function planJobsRegistration(org, recordedIds, jobsAvailable, missingKeyRef = n
                     : `the platform's jobs admin token ${missingKeyRef} is not held yet`}`,
         };
     }
-    const hostname = org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
+    const hostname = appHostname(org);
     return {
         blocked: null,
         step: {
@@ -1562,7 +1671,10 @@ function planJobsRegistration(org, recordedIds, jobsAvailable, missingKeyRef = n
  * {@link planApp}.
  */
 function planDatabase(org, byKey, claimed) {
-    return planHostingToggle('coolify', 'database', appEntry(org.hosting)?.database ?? false, org, byKey, claimed, () => `provision a database for ${org.slug}'s app`, () => `park ${org.slug}'s database (data is retained, not deleted -- #7 corrections 1)`);
+    return planHostingToggle('coolify', 'database', org.hosting.entries.some((entry) => entry.database), org, byKey, claimed, () => `provision a database for ${org.slug}'s app`, () => `park ${org.slug}'s database (data is retained, not deleted -- #7 corrections 1)`);
+}
+function sortedNames(names) {
+    return names.filter(Boolean).sort().join(',');
 }
 /**
  * A Cloudflare tunnel reaching the org's app (`org.ts`'s
@@ -1618,7 +1730,14 @@ function planTunnel(org, byKey, claimed, recordedIds) {
     if (!live)
         return null;
     const connectorMissing = !recordedIds[CLOUDFLARE_TUNNEL_CONNECTOR_APP_SCOPE_KEY];
-    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain;
+    // A hostname added or dropped on an entry: the names published last time
+    // differ from the names now declared. An org that never recorded a list
+    // has nothing to compare, so only the domain check above applies to it.
+    const published = recordedIds[CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY];
+    const namesChanged = published !== undefined &&
+        org.domain !== null &&
+        sortedNames(published.split(',')) !== sortedNames(tunnelDnsHostnames(org, org.domain));
+    const dnsStale = recordedIds[CLOUDFLARE_TUNNEL_DNS_DOMAIN_SCOPE_KEY] !== org.domain || namesChanged;
     if (!connectorMissing && !dnsStale)
         return null;
     return {
@@ -1762,16 +1881,108 @@ function planIssuerApps(org, byKey, claimed) {
     }
     return steps;
 }
+/**
+ * One ZITADEL web client per entry with `uses.auth`, named by the entry key,
+ * in the org's project. Planned once; its redirect addresses name the entry's
+ * exact hostnames when it is created (`executor.ts`'s `zitadelApp`).
+ */
+function planEntryClients(org, byKey, claimed) {
+    const steps = [];
+    for (const entry of org.hosting.entries) {
+        if (!entry.uses?.auth)
+            continue;
+        const key = resourceKey('zitadel', 'app', entry.key);
+        if (byKey.has(key)) {
+            claimed.add(key);
+            continue;
+        }
+        steps.push({
+            action: { system: 'zitadel', kind: 'app', key: entry.key, desired: { appType: 'web' } },
+            step: {
+                description: `provision the sign-in client '${entry.key}' for ${org.slug}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return steps;
+}
+/**
+ * F5: one broker `AUTH_APPS` entry per entry with `uses.auth`. Idempotent on
+ * the recorded marker of what the last write said (ids, names, origins; never
+ * the key), so a rerun plans nothing. The values it needs come from steps
+ * that run earlier; one that nothing records and no step in this plan will
+ * record blocks it (rule 2). A foreign broker entry the last write found
+ * invalid is listed as a warning: the broker drops it, foundry keeps it.
+ */
+function planBrokerEntries(org, recordedIds, plannedSteps, brokerWired) {
+    const steps = [];
+    const blocked = [];
+    for (const entry of org.hosting.entries) {
+        const auth = entry.uses?.auth;
+        if (!auth)
+            continue;
+        const at = `${org.slug}'s ${entry.key} broker entry`;
+        const key = `coolify:broker-entry:${entry.key}`;
+        const warnings = recordedIds[brokerEntryWarningsScopeKey(entry.key)];
+        for (const name of warnings ? JSON.parse(warnings) : []) {
+            blocked.push({
+                description: `warning: the broker's AUTH_APPS entry '${name}' is invalid and the broker drops it; foundry leaves it as it is`,
+                key: `${key}:invalid:${name}`,
+            });
+        }
+        if (!brokerWired) {
+            blocked.push({
+                description: `${at} is blocked, not planned: the host has not wired the broker port`,
+                key,
+            });
+            continue;
+        }
+        const wanted = wantedBrokerEntry(org, entry, recordedIds);
+        if ('want' in wanted) {
+            if (recordedIds[brokerEntryAppliedScopeKey(entry.key)] === JSON.stringify(wanted.want)) {
+                continue;
+            }
+        }
+        else {
+            const unplanned = wanted.missing.filter(({ producedBy: [system, kind] }) => !plannedSteps.some((p) => p.action.system === system && p.action.kind === kind));
+            if (unplanned.length > 0) {
+                blocked.push({
+                    description: `${at} is blocked, not planned: ${unplanned.map((m) => m.what).join(', ')} not recorded yet`,
+                    key,
+                });
+                continue;
+            }
+        }
+        const replaces = auth.replacesBrokerEntry
+            ? ` and replace the hand-written entry '${auth.replacesBrokerEntry}'`
+            : '';
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'broker-entry',
+                key: appStepKey(org, entry.key),
+                desired: {},
+            },
+            step: {
+                description: `write ${at} beside the others${replaces}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
 /**
  * Plan gap A9: an org's customers sign in through a second ZITADEL org with
- * self-registration on, granted the org's app project. Planned once the org
- * declares an issuer app, since customers need an app to sign in to.
+ * self-registration on, granted the org's app project. Planned once an entry
+ * signs in its customers (`uses.auth.users: 'customers'`).
  * Idempotent on the recorded customers org id, like `planOwner`. Once
  * recorded, the live project grant to that org is claimed so it is not
  * listed as unmanaged.
  */
 function planCustomers(org, live, claimed, recordedIds) {
-    if (org.hosting.issuerApps.length === 0)
+    if (!org.hosting.entries.some((entry) => entry.uses?.auth?.users === 'customers'))
         return null;
     const customersOrgId = recordedIds[resourceKey('zitadel', 'customers', org.id)];
     if (customersOrgId) {
@@ -1795,24 +2006,31 @@ function planCustomers(org, live, claimed, recordedIds) {
 }
 /**
  * #84: a Cloudflare Access gate on the org's app hostname, letting only
- * the `app` entry's `accessEmails` through. Idempotent on the recorded Access app id,
+ * each entry's `accessEmails` through. Idempotent on the recorded Access app id,
  * like `planOwner`: Cloudflare's live listing has no Access apps. A later
  * change to the email list is not reconciled yet.
  */
 function planAccess(org, recordedIds) {
-    const entry = org.hosting.enabled ? appEntry(org.hosting) : undefined;
-    if (!entry || entry.accessEmails.length === 0)
-        return null;
-    if (recordedIds[resourceKey('cloudflare', 'access', appStepKey(org))])
-        return null;
-    return {
-        action: { system: 'cloudflare', kind: 'access', key: appStepKey(org), desired: {} },
+    if (!org.hosting.enabled)
+        return [];
+    // Only the `app` entry has a public name, and so only it can sit behind
+    // Access; per-entry hostnames are issue 309.
+    return org.hosting.entries
+        .filter((entry) => entry.key === APP_ENTRY_KEY && entry.accessEmails.length > 0)
+        .filter((entry) => !recordedIds[resourceKey('cloudflare', 'access', appStepKey(org, entry.key))])
+        .map((entry) => ({
+        action: {
+            system: 'cloudflare',
+            kind: 'access',
+            key: appStepKey(org, entry.key),
+            desired: {},
+        },
         step: {
-            description: `put ${org.slug}'s app behind Cloudflare Access`,
+            description: `put ${org.slug}'s ${entry.key === APP_ENTRY_KEY ? 'app' : `${entry.key} app`} behind Cloudflare Access`,
             destroys: false,
             migrates: false,
         },
-    };
+    }));
 }
 /**
  * https://github.com/wtfalch/foundry/issues/43: one Cloudflare rate-limiting

package/dist/plan/executor.d.ts

@@ -1,6 +1,7 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
+import { type BrokerPort } from './broker-entries.js';
 import type { StepAction } from './diff.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
@@ -97,6 +98,19 @@ export interface CoolifyPort {
         domains?: string;
         /** Selects which of two Dockerfiles in one repo to build (`cmsSite`'s own site/cms apps). */
         dockerfile_location?: string;
+        /** The port the app listens on (`HostingEntry.port`). */
+        ports_exposes?: string;
+        /** `false` for an internal entry: Coolify makes no domain for it. */
+        autogenerate_domain?: boolean;
+        /** The folder a `static` entry serves (`HostingEntry.folder`). */
+        publish_directory?: string;
+        /** Whether a push to `git_branch` deploys (`HostingEntry.autoDeploy`). */
+        is_auto_deploy_enabled?: boolean;
+        /**
+         * The app's folder in the repo (`HostingEntry.folder`). Coolify's create
+         * endpoint takes it; `@wtfalch/providers` forwards the body as it is.
+         */
+        base_directory?: string;
     }): Promise<{
         uuid: string;
     }>;
@@ -316,12 +330,20 @@ export interface CoolifyPort {
      * `CoolifyClient.listDatabaseBackups` method-for-method.
      * `provisionPlatformBackup` reads this to decide whether a database
      * already has an enabled, `save_s3` schedule before creating a second one.
+     * `s3_storage_uuid` (#257 fix round 3) is the field a replaced storage's
+     * repoint compares against -- Coolify's "Update database backup" operation
+     * (https://coolify.io/docs/api-reference/api/operations/update-database-backup)
+     * documents it as a field of the same scheduled-backup resource this list
+     * returns, but the list endpoint's own response has not been checked
+     * against a live instance, so it is optional here rather than assumed
+     * present.
      */
     listDatabaseBackups(databaseUuid: string): Promise<Array<{
         uuid: string;
         frequency: string;
         enabled: boolean;
         save_s3: boolean;
+        s3_storage_uuid?: string;
     }>>;
     /**
      * #257: schedules dumps of a database to the registered S3 storage --
@@ -1134,6 +1156,13 @@ export interface FoundryStepExecutorPorts {
      * or repointed without the binding.
      */
     loginHostBindings?: LoginHostBindingsPort;
+    /**
+     * F5: the broker's `AUTH_APPS`, where an entry with `uses.auth` gets its own
+     * entry. Optional the same way `loginHostBindings` is: without it the plan
+     * reports each broker entry blocked (the host also sets
+     * `FoundryPlanApplyOptions.broker`).
+     */
+    broker?: BrokerPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1401,6 +1430,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /**
+     * 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.
+     */
+    private ensureAuthAppKey;
+    /**
+     * `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.
+     */
+    private coolifyBrokerEntry;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a