@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/platform-providers.js

@@ -0,0 +1,3029 @@
+import { generateKeyPairSync, randomBytes } from 'node:crypto';
+import { isIPv4 } from 'node:net';
+import { redactSecrets } from '../calls-sfu-deploy-support.js';
+import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { ACCESS_POLICY_NAME, isNotFoundError, isRunningOrStarting } from './executor.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_MINTER_BLOCKED, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, platformMailMxHost, } from './platform-diff.js';
+import { applyCallsSfuPlatformStep } from './platform-sfu.js';
+/** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
+function apexZoneKey(apex) {
+    return `cloudflare:zone:${apex}`;
+}
+/** The key `runPlatformSteps` records the jobs scheduler app's id under (`system:kind:key`, #173). */
+const JOBS_APP_KEY = `coolify:jobs:${JOBS_SCHEDULER_KEY}`;
+/**
+ * #173: the jobs scheduler's own Coolify project and database, flat scope
+ * ids recorded via `PlatformStepExecutionContext.recordScopeId` -- not
+ * `system:kind:key` (that form is reserved for the one resource
+ * `runPlatformSteps` auto-records from a step's own `resourceId`, the app
+ * itself), the same distinction `executor.ts`'s `coolify_project`/
+ * `CALLS_SERVICE_DB_SCOPE_KEY` draw for an org's own steps.
+ */
+const JOBS_PROJECT_SCOPE_KEY = 'platform_coolify_project';
+const JOBS_DATABASE_SCOPE_KEY = 'coolify_jobs_database';
+/**
+ * Set (to the app's uuid) once the scheduler's `SCHEDULER_ADMIN_TOKEN` has
+ * been delivered to the host and written to the app. The token is only
+ * generated while this is unset, so a rerun of a step that failed earlier
+ * never rotates a token the host already holds.
+ */
+const JOBS_ADMIN_TOKEN_SCOPE_KEY = 'jobs_admin_token_set';
+/** How many times `coolifyJobs` tries `deliverSecret` before giving up. */
+const JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS = 3;
+/** The ref the scheduler's admin token is delivered under: the host's real `JobsSchedulerPort` adapter reads it back. */
+export const JOBS_ADMIN_TOKEN_REF = 'jobs:scheduler:adminToken';
+/** The name of the Coolify project every platform-level service (starting with jobs, #173) lives in. */
+const PLATFORM_COOLIFY_PROJECT_NAME = 'platform';
+/** https://github.com/wtfalch/jobs -- the scheduler's own repo, Dockerfile at its root (its own `Dockerfile`'s doc comment). */
+const JOBS_SCHEDULER_REPO = 'wtfalch/jobs';
+/**
+ * The real {@link PlatformStepExecutor} for the two steps built so far:
+ * `cloudflare:zone` for the platform's apex (#167) and `coolify:jobs` for the
+ * jobs scheduler (#173). `coolify` is optional so every #167-era caller --
+ * anything that only ever plans the apex zone -- keeps constructing this with
+ * two arguments; a `coolify:jobs` step reaching this executor with no
+ * `coolify` port configured throws, naming what is missing, rather than
+ * silently doing nothing.
+ *
+ * `cloudflareZone` mirrors `executor.ts`'s `cloudflareZone`: find the zone by
+ * apex and adopt it, create it only when absent. companyincluded.com already
+ * exists on Cloudflare, empty, so the first apply adopts it. The owner org
+ * (Company Included, whose own domain is the apex) may record the same zone
+ * under its own applied state, so that owner is allowed. Any other org that
+ * recorded it makes this refuse to adopt. There is no delete here and
+ * `PlatformStepExecutor` has none: neither path ever removes the zone.
+ *
+ * `coolifyJobs` mirrors `executor.ts`'s `coolifyApp`/`coolifyDatabase`,
+ * simplified for one platform-level singleton rather than one per org: find
+ * or create a dedicated `platform` Coolify project, find or create the
+ * scheduler's own database, find or create the scheduler app itself (from
+ * https://github.com/wtfalch/jobs, one Dockerfile at its repo root, on the
+ * declared `gitRef`), then push the database's `internal_db_url` in as
+ * `DATABASE_URL`. There is no park branch yet, matching `planJobs`'s own
+ * scope note -- `platform.jobs.enabled` going from true to false plans
+ * nothing, so this method is never asked to stop or delete anything.
+ *
+ * #170 adds `sfu:livekit`, the platform's shared calls SFU. `sfu` is
+ * optional: an existing host that constructs this executor for the zone step
+ * alone keeps compiling, and a plan that includes an `sfu:livekit` step
+ * without it configured refuses clearly rather than silently doing nothing.
+ *
+ * #168 adds `coolify:app` keyed {@link PLATFORM_AUTH_KEY}, the platform's own
+ * sign-in ({@link provisionPlatformAuth}), once a host passes
+ * {@link PlatformAuthDeps}.
+ *
+ * #169 adds `coolify:app` keyed {@link PLATFORM_MAIL_KEY}, the platform's own
+ * mail server ({@link provisionPlatformMail}), once a host passes
+ * {@link PlatformMailDeps}.
+ *
+ * #174 adds `coolify:app` keyed {@link PLATFORM_INTEGRATIONS_KEY},
+ * the integrations host ({@link provisionPlatformIntegrations}), once a host
+ * passes {@link PlatformIntegrationsDeps}.
+ *
+ * #171 adds `coolify:app` keyed {@link PLATFORM_FILES_KEY}, the files host
+ * ({@link provisionPlatformFiles}), once a host passes {@link PlatformFilesDeps}.
+ *
+ * #172 adds `coolify:app` keyed {@link PLATFORM_AI_KEY}, the platform's AI
+ * host ({@link provisionPlatformAi}), once a host passes {@link PlatformAiDeps}.
+ *
+ * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
+ * ({@link provisionPlatformArchon}), once a host passes
+ * {@link PlatformArchonDeps}.
+ */
+export class FoundryPlatformStepExecutor {
+    cloudflare;
+    declaredOrgStore;
+    coolify;
+    deliverSecret;
+    sfu;
+    auth;
+    mail;
+    integrations;
+    files;
+    ai;
+    archon;
+    constructor(cloudflare, declaredOrgStore, options = {}) {
+        this.cloudflare = cloudflare;
+        this.declaredOrgStore = declaredOrgStore;
+        this.coolify = options.coolify;
+        this.deliverSecret = options.deliverSecret;
+        this.sfu = options.sfu;
+        this.auth = options.auth;
+        this.mail = options.mail;
+        this.integrations = options.integrations;
+        this.files = options.files;
+        this.ai = options.ai;
+        this.archon = options.archon;
+    }
+    async blockedSteps(platform, recordedIds = {}) {
+        const blocked = {};
+        if (platform.auth.enabled && !this.auth) {
+            blocked.auth =
+                "the platform's sign-in is blocked, not planned: the host built the platform executor without its auth dependencies";
+        }
+        if (platform.mail.enabled) {
+            const mailBlocked = await mailBlockedReason(platform, this.mail, recordedIds);
+            if (mailBlocked)
+                blocked.mail = mailBlocked;
+        }
+        if (platform.integrations.enabled && !this.integrations) {
+            blocked.integrations =
+                'the integrations host is blocked, not planned: the host built the platform executor without its integrations dependencies';
+        }
+        else if (platform.integrations.enabled && this.integrations) {
+            const missing = INTEGRATIONS_KEYS_ENV_NAMES.filter((n) => !this.integrations?.keysEnv?.[n]);
+            if (missing.length > 0) {
+                blocked.integrations = `the integrations host is blocked, not planned: the host supplies no value for ${missing.join(', ')}, the host's own @wtfalch/keys settings`;
+            }
+        }
+        if (platform.files.enabled && !this.files) {
+            blocked.files =
+                'the files host is blocked, not planned: the host built the platform executor without its files dependencies';
+        }
+        else if (platform.files.enabled && !filesKeys(this.files)) {
+            blocked.files =
+                'the files host is blocked, not planned: the host supplies no keys worker URL and credential (KEYS_WORKER_URL, KEYS_CREDENTIAL), so files-migrate would never become healthy';
+        }
+        if (platform.ai.enabled && !this.ai) {
+            blocked.ai =
+                "the platform's AI host is blocked, not planned: the host built the platform executor without its ai dependencies";
+        }
+        else if (platform.ai.enabled &&
+            !this.ai?.managementKeyMinter &&
+            !recordedIds[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY]) {
+            blocked.ai = PLATFORM_AI_MINTER_BLOCKED;
+        }
+        if (platform.archon.enabled) {
+            if (!this.archon) {
+                blocked.archon =
+                    'Archon is blocked, not planned: the host built the platform executor without its archon dependencies';
+            }
+            else if (this.archon.accessEmails.length === 0) {
+                blocked.archon =
+                    'Archon is blocked, not planned: the host names no email the Cloudflare Access app in front of it may let through';
+            }
+            else {
+                const inputs = await collectArchonServiceInputs(platform, this.archon, recordedIds);
+                if ('blocked' in inputs)
+                    blocked.archon = inputs.blocked;
+            }
+        }
+        return blocked;
+    }
+    /** Whether Archon's live Access policy lets through anyone but the declared emails. */
+    async driftedSteps(platform, recordedIds = {}) {
+        if (!platform.archon.enabled || !this.archon)
+            return {};
+        if (!recordedIds[`coolify:app:${PLATFORM_ARCHON_KEY}`])
+            return {};
+        const drifted = await archonAccessDrifted(this.archon.cloudflare, platform.archon.hostname, this.archon.accessEmails);
+        return drifted ? { archon: true } : {};
+    }
+    async execute(action, context) {
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_AUTH_KEY) {
+            if (!this.auth) {
+                throw new Error('platform:auth needs FoundryPlatformStepExecutor to be constructed with its auth dependencies (#168)');
+            }
+            return provisionPlatformAuth(context, this.auth);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_FILES_KEY) {
+            if (!this.files) {
+                throw new Error('platform:files needs FoundryPlatformStepExecutor to be constructed with its files dependencies (#171)');
+            }
+            return provisionPlatformFiles(context, this.files);
+        }
+        if (action.system === 'coolify' &&
+            action.kind === 'app' &&
+            action.key === PLATFORM_INTEGRATIONS_KEY) {
+            if (!this.integrations) {
+                throw new Error('platform:integrations needs FoundryPlatformStepExecutor to be constructed with its integrations dependencies (#174)');
+            }
+            return provisionPlatformIntegrations(action, context, this.integrations);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_AI_KEY) {
+            if (!this.ai) {
+                throw new Error('platform:ai needs FoundryPlatformStepExecutor to be constructed with its ai dependencies (#172)');
+            }
+            return provisionPlatformAi(context, this.ai);
+        }
+        if (action.system === 'coolify' &&
+            action.kind === 'app' &&
+            action.key === PLATFORM_ARCHON_KEY) {
+            if (!this.archon) {
+                throw new Error('platform:archon needs FoundryPlatformStepExecutor to be constructed with its archon dependencies (#175)');
+            }
+            return provisionPlatformArchon(context, this.archon);
+        }
+        if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_MAIL_KEY) {
+            if (!this.mail) {
+                throw new Error('platform:mail needs FoundryPlatformStepExecutor to be constructed with its mail dependencies (#169)');
+            }
+            return provisionPlatformMail(context, this.mail);
+        }
+        if (action.system === 'cloudflare' && action.kind === 'zone') {
+            return this.cloudflareZone(action, context);
+        }
+        if (action.system === 'coolify' && action.kind === 'jobs') {
+            return this.coolifyJobs(action, context);
+        }
+        if (action.system === 'sfu' && action.kind === 'livekit') {
+            return this.executeSfu();
+        }
+        throw new Error(`platform step ${action.system}:${action.kind} is not built yet`);
+    }
+    async cloudflareZone(action, context) {
+        const domain = action.key;
+        const existing = await exactZone(this.cloudflare, domain);
+        if (existing) {
+            const owner = await this.declaredOrgStore.findOrgIdForZone(existing.id);
+            if (owner !== null && owner !== context.platform.ownerOrgId) {
+                throw new Error(`cloudflare:zone for the platform: zone ${existing.id} (${domain}) is already recorded under org ${owner}; foundry does not adopt it`);
+            }
+            return { resourceId: existing.id };
+        }
+        const created = await this.cloudflare.createZone(domain);
+        return { resourceId: created.id };
+    }
+    async executeSfu() {
+        if (!this.sfu) {
+            throw new Error('platform step sfu:livekit is not built yet (#170: pass `sfu` to FoundryPlatformStepExecutor)');
+        }
+        await applyCallsSfuPlatformStep(this.sfu);
+        return undefined;
+    }
+    async coolifyJobs(action, context) {
+        const coolify = this.coolify;
+        if (!coolify) {
+            throw new Error('platform step coolify:jobs needs a Coolify port -- construct FoundryPlatformStepExecutor with one (#173)');
+        }
+        const deliverSecret = this.deliverSecret;
+        if (!deliverSecret) {
+            throw new Error('platform step coolify:jobs needs a deliverSecret -- construct FoundryPlatformStepExecutor with one, to hand the scheduler admin token to the host (#173)');
+        }
+        const hostname = action.desired.hostname;
+        const gitRef = action.desired.gitRef;
+        const recorded = context.recordedIds();
+        let projectUuid = recorded[JOBS_PROJECT_SCOPE_KEY];
+        if (!projectUuid) {
+            const found = await coolify.findProjectByName(PLATFORM_COOLIFY_PROJECT_NAME);
+            projectUuid = found
+                ? found.uuid
+                : (await coolify.createProject(PLATFORM_COOLIFY_PROJECT_NAME)).uuid;
+            context.recordScopeId(JOBS_PROJECT_SCOPE_KEY, projectUuid);
+        }
+        const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+        let dbId = recorded[JOBS_DATABASE_SCOPE_KEY];
+        if (!dbId) {
+            const dbName = `${JOBS_SCHEDULER_KEY}-scheduler-db`;
+            const found = (await coolify.listDatabases()).find((db) => db.name === dbName && db.environment_id === environment.id);
+            if (found) {
+                dbId = found.uuid;
+            }
+            else {
+                const server = await resolvePlatformServer(coolify);
+                const created = await coolify.createPostgresDatabase({
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    name: dbName,
+                    postgres_db: 'jobs',
+                    postgres_user: 'jobs',
+                });
+                dbId = created.uuid;
+            }
+            context.recordScopeId(JOBS_DATABASE_SCOPE_KEY, dbId);
+        }
+        const existingApp = await coolify.findApplicationByName(JOBS_SCHEDULER_KEY, {
+            environmentIds: [environment.id],
+        });
+        let appId;
+        if (existingApp) {
+            appId = existingApp.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const githubApp = await coolify.requireGithubApp();
+            const created = await coolify.createGithubAppApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                github_app_uuid: githubApp.uuid,
+                git_repository: JOBS_SCHEDULER_REPO,
+                git_branch: gitRef,
+                build_pack: 'dockerfile',
+                name: JOBS_SCHEDULER_KEY,
+                domains: hostname,
+            });
+            appId = created.uuid;
+        }
+        const db = await coolify.getDatabase(dbId);
+        if (!db.internal_db_url) {
+            throw new Error(`platform step coolify:jobs: database ${dbId} has no internal_db_url yet; not deploying the scheduler without a database`);
+        }
+        const envs = [{ key: 'DATABASE_URL', value: db.internal_db_url }];
+        // SCHEDULER_ADMIN_TOKEN gates the admin API the org registrations use
+        // (jobs README, "The admin API"); unset, every admin route answers 401.
+        // Delivered to the host before it is written to the app, so a failed
+        // delivery leaves nothing set and the rerun simply generates a new one.
+        let tokenJustSet = false;
+        if (!context.recordedIds()[JOBS_ADMIN_TOKEN_SCOPE_KEY]) {
+            const token = randomBytes(32).toString('hex');
+            let delivered = false;
+            for (let attempt = 1; attempt <= JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS && !delivered; attempt++) {
+                try {
+                    await deliverSecret(JOBS_ADMIN_TOKEN_REF, token);
+                    delivered = true;
+                }
+                catch {
+                    // Retried; the error is dropped in case it echoes the token.
+                }
+            }
+            if (!delivered) {
+                throw new Error(`platform step coolify:jobs: the scheduler admin token could not be delivered after ${JOBS_ADMIN_TOKEN_DELIVERY_ATTEMPTS} attempts`);
+            }
+            envs.push({ key: 'SCHEDULER_ADMIN_TOKEN', value: token });
+            await coolify.bulkUpsertEnvs(appId, envs);
+            context.recordScopeId(JOBS_ADMIN_TOKEN_SCOPE_KEY, appId);
+            tokenJustSet = true;
+        }
+        else {
+            await coolify.bulkUpsertEnvs(appId, envs);
+        }
+        // The app is created with `instant_deploy: false` and an env change needs
+        // a redeploy, so deploy after a create or a new token. Also when it is not
+        // running, so a deploy that failed on an earlier run is retried.
+        const running = (await coolify.getApplication(appId)).status?.startsWith('running') ?? false;
+        if (!existingApp || tokenJustSet || !running)
+            await coolify.deploy(appId);
+        return { resourceId: appId };
+    }
+}
+// ---------------------------------------------------------------------------
+// #168: the platform's own sign-in (ZITADEL)
+// ---------------------------------------------------------------------------
+const PLATFORM_AUTH_PROJECT = 'platform';
+const PLATFORM_AUTH_DB_NAME = 'platform-auth-db';
+const PLATFORM_AUTH_ZITADEL_APP_NAME = 'platform-auth-zitadel';
+const PLATFORM_AUTH_LOGIN_APP_NAME = 'platform-auth-login';
+/**
+ * Fixed `custom_internal_name`s (`diff.ts`'s `coolifyCalls` sets the same
+ * kind of name on Synapse/MAS) so the Cloudflare tunnel below can address
+ * each app directly, by container name, on the shared Coolify Docker network
+ * -- bypassing Coolify's own Traefik, which dispatches purely by `Host`
+ * header and so cannot give two different apps the same public hostname.
+ */
+const PLATFORM_AUTH_ZITADEL_INTERNAL_NAME = 'platform-auth-zitadel';
+const PLATFORM_AUTH_LOGIN_INTERNAL_NAME = 'platform-auth-login';
+const PLATFORM_AUTH_TUNNEL_NAME = 'platform-auth-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_AUTH_TUNNEL_NAME}. */
+const PLATFORM_AUTH_CLOUDFLARED_APP_NAME = 'platform-auth-cloudflared';
+/** `wtfalch/auth`'s `docker-compose.yml`: `image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION:-v4.17.3}`. */
+const AUTH_ZITADEL_IMAGE = 'ghcr.io/zitadel/zitadel';
+const AUTH_ZITADEL_IMAGE_TAG = 'v4.17.3';
+/** `wtfalch/auth`'s own `login/Dockerfile` -- `docs/deploy.md`'s "One compose service, four containers... Two images are built from this repository: the proxy... and the login". */
+const AUTH_REPO = 'wtfalch/auth';
+const AUTH_LOGIN_DOCKERFILE = 'login/Dockerfile';
+/**
+ * `wtfalch/auth`'s login app answers on 3000 (its `Dockerfile`'s Next.js
+ * default); ZITADEL answers on 8080 -- both fixed by `docker-compose.yml`'s
+ * own `ZITADEL_PORT: 8080` and the login image's own `EXPOSE`.
+ */
+const AUTH_ZITADEL_PORT = '8080';
+const AUTH_LOGIN_PORT = '3000';
+/**
+ * Every ZITADEL OIDC/management/console/asset path -- `deploy/proxy/Caddyfile`'s
+ * own explicit list, restated here as one regex since the tunnel routes by a
+ * single `path` per ingress rule rather than a set. Anything not matching
+ * falls through to the login app's own ingress rule below (login v2 answers
+ * everything else, including the root).
+ */
+const AUTH_ZITADEL_PATH_PATTERN = '^/(oidc|oauth|saml|management|admin|system|auth|assets|ui/console|\\.well-known)(/|$)';
+const PLATFORM_AUTH_PROJECT_SCOPE_KEY = 'coolify_project_platform_auth';
+const PLATFORM_AUTH_DB_SCOPE_KEY = 'coolify_platform_auth_database';
+const PLATFORM_AUTH_ZITADEL_SCOPE_KEY = 'coolify_platform_auth_zitadel_app';
+const PLATFORM_AUTH_LOGIN_SCOPE_KEY = 'coolify_platform_auth_login_app';
+const PLATFORM_AUTH_TUNNEL_SCOPE_KEY = 'cloudflare_platform_auth_tunnel';
+/** Recorded once the ZITADEL app has been deployed, so ZITADEL may have written to its database. */
+const PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY = 'zitadel_platform_auth_deployed';
+const PLATFORM_AUTH_ADMIN_USER_NAME = 'foundry-admin';
+const PLATFORM_AUTH_ORG_NAME = 'foundry';
+/**
+ * #168: makes `coolify:app` keyed {@link PLATFORM_AUTH_KEY} true -- a Coolify
+ * Postgres, the ZITADEL app itself and the zitadel-login app, reached through
+ * one Cloudflare tunnel and DNS record at `platform.auth.hostname`, then (only
+ * the first time) foundry's own admin machine user, handed to
+ * {@link PlatformAuthDeps.deliverSecret}. Env values and instance settings
+ * are `wtfalch/auth`'s own `docker-compose.yml` (checked 2026-09-29), with
+ * `ZITADEL_DOMAIN`/`wtfalch.dev` replaced by this platform's own
+ * `apex`/`auth.hostname` wherever the compose named one -- every other
+ * setting it leaves open (login v2 required, external port 443, TLS
+ * terminated at Cloudflare, `PASSWORDCHANGEREQUIRED` false) is kept exactly
+ * as that compose has it (#168's "Decide").
+ *
+ * Every part is safe to run again after a throw partway: each id is recorded
+ * (and persisted) as soon as its resource exists, each app is named and
+ * deployed on every run that needs it, and the admin key is delivered before
+ * the guard that skips the mint is recorded.
+ *
+ * Two apps, one public hostname, no third `proxy` app: `wtfalch/auth` splits
+ * ZITADEL's API from its login UI with a built Caddy proxy container inside
+ * one docker-compose stack; foundry instead gives each app a fixed
+ * `custom_internal_name` and lets the Cloudflare tunnel itself path-route
+ * between them (`AUTH_ZITADEL_PATH_PATTERN`), skipping Coolify's own Traefik
+ * (which can only dispatch by `Host`, not by path) rather than provisioning a
+ * fourth Coolify resource to do the same job. Neither app is created with a
+ * Coolify `domains` binding for the same reason -- the tunnel reaches each
+ * one directly by its `custom_internal_name`, never through Traefik.
+ *
+ * Known gaps, left for review (#168's own "the PR stays open for William's
+ * review"):
+ * - The login app never receives `ZITADEL_SERVICE_USER_TOKEN`. `wtfalch/auth`
+ *   reads it from a bootstrap file two containers share inside one compose
+ *   stack; two Coolify apps share none. The minted admin token must not go
+ *   there (it is `IAM_OWNER`); a dedicated `IAM_LOGIN_CLIENT` machine user
+ *   would need its own mint, delivery and redeploy. Sign-in through the login
+ *   app is not proven working until that is wired.
+ * - Whoever supplies `deps.zitadel` (or `zitadelForInstance`) must hold a
+ *   bearer token for the new instance, which foundry cannot read from it.
+ *
+ * #197: a `cloudflared` connector for this tunnel is run
+ * ({@link ensureCloudflaredConnector}), so `hostname` answers.
+ */
+async function provisionPlatformAuth(context, deps) {
+    const { platform } = context;
+    const hostname = platform.auth.hostname;
+    const gitRef = platform.auth.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    // Records an id and writes it out now, so a crash before the step ends
+    // cannot lose a resource a provider already created.
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_AUTH_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_AUTH_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_AUTH_PROJECT)).uuid;
+        await record(PLATFORM_AUTH_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_AUTH_DB_SCOPE_KEY];
+    // A database ZITADEL has already run against may hold data encrypted with a
+    // masterkey this run cannot see (see `ensureMasterkey`). A database that
+    // exists but was never deployed against (a throw between its create and the
+    // first deploy) is still empty, so a retry may generate the key.
+    const databaseInUse = Boolean(dbId && recorded[PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY]);
+    if (!dbId) {
+        const server = await resolvePlatformServer(deps.coolify);
+        const created = await deps.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name: PLATFORM_AUTH_DB_NAME,
+            postgres_db: 'zitadel',
+            postgres_user: 'zitadel',
+        });
+        dbId = created.uuid;
+        await record(PLATFORM_AUTH_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        // Static config check before either app is touched (`diff.ts`'s
+        // `coolifyCalls` follows the same rule for its own databases): Coolify
+        // can take a moment to report a freshly created database's
+        // `internal_db_url`, so the next apply retries from a clean state.
+        throw new Error('coolify:app for the platform (auth): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the ZITADEL app itself ---------------------------------------------
+    const zitadelApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_ZITADEL_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        return deps.coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: AUTH_ZITADEL_IMAGE,
+            docker_registry_image_tag: AUTH_ZITADEL_IMAGE_TAG,
+            ports_exposes: AUTH_ZITADEL_PORT,
+            name: PLATFORM_AUTH_ZITADEL_APP_NAME,
+            description: `ZITADEL for the platform's own sign-in (#168, ${AUTH_ZITADEL_IMAGE}:${AUTH_ZITADEL_IMAGE_TAG})`,
+            instant_deploy: false,
+        });
+    });
+    const zitadelAppId = zitadelApp.appId;
+    await record(PLATFORM_AUTH_ZITADEL_SCOPE_KEY, zitadelAppId);
+    // Set on every run, not only after a create: a throw right after the
+    // create must not leave the app unnamed for good, and the tunnel addresses
+    // the app by this name. (The port cannot read the current name back, and
+    // setting the same value again is harmless.)
+    await deps.coolify.updateApplication(zitadelAppId, {
+        custom_internal_name: PLATFORM_AUTH_ZITADEL_INTERNAL_NAME,
+    });
+    // ---- the zitadel-login app -----------------------------------------------
+    const loginApp = await findOrCreatePlatformApp(deps.coolify, PLATFORM_AUTH_LOGIN_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: AUTH_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: PLATFORM_AUTH_LOGIN_APP_NAME,
+            dockerfile_location: AUTH_LOGIN_DOCKERFILE,
+        });
+    });
+    const loginAppId = loginApp.appId;
+    await record(PLATFORM_AUTH_LOGIN_SCOPE_KEY, loginAppId);
+    await deps.coolify.updateApplication(loginAppId, {
+        custom_internal_name: PLATFORM_AUTH_LOGIN_INTERNAL_NAME,
+    });
+    // ---- env -----------------------------------------------------------------
+    // Generated once, handed straight to `bulkUpsertEnvs` and nowhere else --
+    // never returned, recorded, logged or interpolated into a thrown error, the
+    // same rule `executor.ts`'s `ensureAuthCookieSecret` follows for a value
+    // this package mints itself rather than receiving from a provider.
+    const masterkey = await ensureMasterkey(deps.coolify, zitadelAppId, databaseInUse);
+    const adminPassword = await ensureGeneratedEnv(deps.coolify, zitadelAppId, 'ZITADEL_ADMIN_PASSWORD', generateAdminPassword);
+    const zitadelEnvs = [
+        { key: 'ZITADEL_PORT', value: AUTH_ZITADEL_PORT },
+        { key: 'ZITADEL_EXTERNALDOMAIN', value: hostname },
+        { key: 'ZITADEL_EXTERNALPORT', value: '443' },
+        { key: 'ZITADEL_EXTERNALSECURE', value: 'true' },
+        { key: 'ZITADEL_TLS_ENABLED', value: 'false' },
+        { key: 'ZITADEL_DATABASE_POSTGRES_DSN', value: db.internal_db_url },
+        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME', value: 'zitadel-admin' },
+        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED', value: 'false' },
+        { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED', value: 'true' },
+        { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI', value: `https://${hostname}/` },
+        { key: 'ZITADEL_OIDC_DEFAULTLOGINURLV2', value: `https://${hostname}/login?authRequest=` },
+        {
+            key: 'ZITADEL_OIDC_DEFAULTLOGOUTURLV2',
+            value: `https://${hostname}/logout?post_logout_redirect=`,
+        },
+        { key: 'ZITADEL_SAML_DEFAULTLOGINURLV2', value: `https://${hostname}/login?samlRequest=` },
+        { key: 'ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED', value: 'true' },
+    ];
+    if (masterkey)
+        zitadelEnvs.push({ key: 'ZITADEL_MASTERKEY', value: masterkey });
+    if (adminPassword)
+        zitadelEnvs.push({ key: 'ZITADEL_ADMIN_PASSWORD', value: adminPassword });
+    const loginEnvs = [
+        {
+            key: 'ZITADEL_API_URL',
+            value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
+        },
+        { key: 'CUSTOM_REQUEST_HEADERS', value: `Host:${hostname},X-Forwarded-Proto:https` },
+        { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
+        { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
+    ];
+    // Compared before the write: an env change only reaches a running
+    // container on its next deploy (`diff.ts`'s `coolifyCalls` follows the
+    // identical rule).
+    const zitadelEnvsChanged = await envsDiffer(deps.coolify, zitadelAppId, zitadelEnvs);
+    const loginEnvsChanged = await envsDiffer(deps.coolify, loginAppId, loginEnvs);
+    await deps.coolify.bulkUpsertEnvs(zitadelAppId, zitadelEnvs);
+    await deps.coolify.bulkUpsertEnvs(loginAppId, loginEnvs);
+    // Deploy an app that was just created, is not running (a throw after the
+    // create left it never deployed, or it stopped), or whose envs changed.
+    if (zitadelApp.justCreated || !zitadelApp.running || zitadelEnvsChanged) {
+        await deps.coolify.deploy(zitadelAppId);
+        await record(PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY, zitadelAppId);
+    }
+    if (loginApp.justCreated || !loginApp.running || loginEnvsChanged) {
+        await deps.coolify.deploy(loginAppId);
+    }
+    // ---- tunnel and DNS ------------------------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_AUTH_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_AUTH_TUNNEL_NAME));
+    await record(PLATFORM_AUTH_TUNNEL_SCOPE_KEY, tunnel.id);
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            {
+                hostname,
+                path: AUTH_ZITADEL_PATH_PATTERN,
+                service: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
+            },
+            { hostname, service: `http://${PLATFORM_AUTH_LOGIN_INTERNAL_NAME}:${AUTH_LOGIN_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    // ---- cloudflared connector for the tunnel above (#197) --------------------
+    // Without this, `hostname` resolves to a tunnel nothing is dialed into and
+    // answers with a Cloudflare error -- the known gap #197 closes for this
+    // step's own tunnel only (see this function's doc comment).
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_AUTH_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        resolveServer: () => resolvePlatformServer(deps.coolify),
+        recordedConnectorAppId: recorded[PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    // The apex zone step records the zone id before this step runs, but it
+    // creates no record for the hostname, so it is created here.
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:auth: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // ---- foundry's own admin machine user, once ------------------------------
+    if (!recorded[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        const lost = recorded[PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            // The planner reports this and plans nothing; this is the same rule for
+            // a caller that reaches the step anyway.
+            throw new Error(`platform:auth: the admin key of ZITADEL machine user ${lost} was minted but never delivered; delete that user and the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        // Minting needs a running instance behind the tunnel: the first apply
+        // gets here right after the deploy.
+        await waitForInstance(`https://${hostname}/.well-known/openid-configuration`, runtime, sleep);
+        const zitadel = deps.zitadelForInstance?.(`https://${hostname}`) ?? deps.zitadel;
+        const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+        const { userId, token } = await zitadel.mintAdminMachineUser(org.id, {
+            userName: PLATFORM_AUTH_ADMIN_USER_NAME,
+            name: 'Foundry (platform admin)',
+        });
+        // Recorded and persisted before the token leaves this function: if
+        // delivery fails for good, the next plan reports the lost key rather than
+        // skipping or minting again. Only a delivered key records the guard.
+        await record(PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, userId);
+        // Handed off once, right here, before returning -- never in the return
+        // value, `serviceIds`, the store, a log or a thrown error (see
+        // `FoundryStepExecutorPorts.deliverSecret`'s own doc comment). The error
+        // below names the user id only, never the token or the cause.
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret('zitadel:platform:admin', token);
+                break;
+            }
+            catch {
+                if (attempt >= attempts) {
+                    throw new Error(`platform:auth: the admin key of ZITADEL machine user ${userId} was minted but could not be delivered after ${attempts} tries`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await record(PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, userId);
+    }
+    return { resourceId: zitadelAppId };
+}
+// ---------------------------------------------------------------------------
+// #169: the platform's own mail server (Stalwart)
+// ---------------------------------------------------------------------------
+const PLATFORM_MAIL_PROJECT = 'platform';
+const PLATFORM_MAIL_APP_NAME = 'platform-mail-stalwart';
+const PLATFORM_MAIL_INTERNAL_NAME = 'platform-mail-stalwart';
+const PLATFORM_MAIL_TUNNEL_NAME = 'platform-mail-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_MAIL_TUNNEL_NAME}. */
+const PLATFORM_MAIL_CLOUDFLARED_APP_NAME = 'platform-mail-cloudflared';
+/**
+ * `stalw.art/docs/install/docker`: the official image. `platform.mail.gitRef`
+ * carries its tag -- `platform.ts`'s `PlatformService.gitRef` doc comment
+ * ("the release it runs") holds for an image tag too, and Stalwart has no
+ * repo of its own to build from the way the login app does.
+ */
+const STALWART_IMAGE = 'stalwartlabs/stalwart';
+const STALWART_HTTP_PORT = '8080';
+/**
+ * SMTP (25), submission (587) and submissions (465) -- the three ports
+ * #169's own "Human steps" names. IMAP/POP3/ManageSieve are left off:
+ * nothing in this estate speaks them to Stalwart directly yet, and every
+ * port opened here is one Coolify's host firewall must also open.
+ */
+const STALWART_SMTP_PORTS = ['25', '465', '587'];
+const STALWART_PORTS_EXPOSES = [STALWART_HTTP_PORT, ...STALWART_SMTP_PORTS].join(',');
+/**
+ * `host:container`, comma separated (`CoolifyPort.createDockerImageApplication`'s
+ * own doc comment: "a mail server cannot do without" this). The HTTP port is
+ * not here -- it stays behind the tunnel, exactly like `platform:auth`'s
+ * ZITADEL/login apps.
+ */
+const STALWART_PORTS_MAPPINGS = STALWART_SMTP_PORTS.map((p) => `${p}:${p}`).join(',');
+const STALWART_DATA_MOUNT = '/opt/stalwart';
+/** `STALWART_RECOVERY_ADMIN=<user>:<password>` -- the fixed recovery account name; only the password half is generated. */
+const STALWART_RECOVERY_USER = 'admin';
+/**
+ * Stalwart's unauthenticated readiness endpoint (200 once its data store is
+ * up; `crates/http/src/request.rs`'s `healthz` route in v0.16.24). Not
+ * `/.well-known/jmap`, which answers 401 to a client with no credentials.
+ */
+const STALWART_READY_PATH = '/healthz/ready';
+/** Where the server the app was created on is recorded, so the MX record follows the app, not a later pick. */
+const PLATFORM_MAIL_SERVER_SCOPE_KEY = 'coolify_platform_mail_server';
+const PLATFORM_MAIL_PROJECT_SCOPE_KEY = 'coolify_project_platform_mail';
+const PLATFORM_MAIL_APP_SCOPE_KEY = 'coolify_platform_mail_app';
+const PLATFORM_MAIL_TUNNEL_SCOPE_KEY = 'cloudflare_platform_mail_tunnel';
+/**
+ * Recorded once the app has been deployed at least once -- same role as
+ * `PLATFORM_AUTH_ZITADEL_DEPLOYED_SCOPE_KEY`, kept for parity though nothing
+ * here reads it back the way `ensureMasterkey` does: losing
+ * `STALWART_RECOVERY_ADMIN` is not destructive the same way losing ZITADEL's
+ * masterkey is.
+ */
+const PLATFORM_MAIL_DEPLOYED_SCOPE_KEY = 'stalwart_platform_mail_deployed';
+/**
+ * The hostname and image tag the last successful deploy used, recorded right
+ * after that deploy. `provisionPlatformMail` reads these (not the applied keys
+ * the planner reads, which stay last) to decide on a redeploy, so a retry after
+ * a later failure does not stop the running server again.
+ */
+const PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY = 'mail_deployed_hostname';
+const PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY = 'mail_deployed_git_ref';
+/**
+ * The fixed description Stalwart's admin API key is minted under
+ * (`StalwartClient.createApiKey`'s own signature returns only the secret,
+ * never an id) -- what a human revokes it by in Stalwart's own admin UI if
+ * it is ever lost between mint and delivery, and what
+ * {@link PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} records in that case.
+ */
+export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
+/**
+ * #169: makes `coolify:app` keyed {@link PLATFORM_MAIL_KEY} true -- Stalwart
+ * on Coolify with its own persistent storage, reached at
+ * `platform.mail.hostname` through a Cloudflare tunnel for web, JMAP and its
+ * management API (mirroring #168's ZITADEL/login apps: TLS terminated at
+ * Cloudflare, plain HTTP behind the tunnel) and at `mx.<apex>` over a direct,
+ * unproxied `A` record to the Coolify server's own address for SMTP -- raw
+ * SMTP cannot ride Cloudflare's HTTP-only tunnel the way a web app does,
+ * which is exactly why #169's own "Human steps" asks a person to open ports
+ * 25, 465 and 587 on that server's host firewall. Then, once the instance
+ * answers, the OIDC directory against the platform's own sign-in and
+ * foundry's admin API key, minted once and handed to
+ * {@link PlatformMailDeps.deliverSecret}.
+ *
+ * Every part is safe to run again after a throw partway, the same rules
+ * {@link provisionPlatformAuth} follows: each id is recorded (and persisted)
+ * as soon as its resource exists, the app is deployed on every run that
+ * needs it, and the admin key is delivered before the guard that skips the
+ * mint is recorded. Unlike ZITADEL's `ZITADEL_ADMIN_PASSWORD`, the recovery
+ * credential this step generates (`STALWART_RECOVERY_ADMIN`) is read back
+ * from Coolify's own env store on every run rather than held only in memory
+ * -- `CoolifyPort.listEnvs`'s own doc comment says these values come back
+ * live -- so a retry after a delivery failure re-authenticates with the same
+ * credential instead of losing it.
+ *
+ * **Why not `@wtfalch/email/postmaster`'s `mailObjects`/`applyObjects`**, the
+ * instance-bootstrap helper `wtfalch-manage` already uses for the hand-built
+ * `mail.wtfalch.dev`: that plan also wires an `AcmeProvider` and `DnsServer`
+ * for Stalwart's own DNS-01 ACME challenge, and an `MtaRoute` that relays
+ * every outbound message through Resend -- the estate moved transactional
+ * mail off Resend onto Lettermint before this issue (`@wtfalch/mailer` ADR
+ * 0006), and this step provisions no Cloudflare DNS token for Stalwart's own
+ * ACME either. Calling it as-is would mint an outbound relay this platform
+ * does not want and a credential requirement this issue does not cover, so
+ * {@link PlatformMailAdminPort.applySettings} is a narrower, hand-built
+ * settings write instead: the default hostname and the OIDC directory only.
+ *
+ * Known gaps, left for review (like #168's own "the PR stays open for
+ * William's review"):
+ * - **No ACME/TLS for the SMTP listener.** `mx.<apex>` answers with
+ *   Stalwart's own self-signed certificate until a follow-up wires a real
+ *   one (`mailObjects`'s `AcmeProvider`/`DnsServer` shape, minus the Resend
+ *   relay it also carries).
+ * - **`oidcAudience` is supplied, not resolved.** #168 mints foundry's own
+ *   ZITADEL admin machine user but registers no resource API for Stalwart's
+ *   access-token `aud` check; whoever supplies
+ *   {@link PlatformMailDeps.oidcAudience} must have registered one by hand
+ *   until that is built.
+ * - **The org step `coolify:mail`'s `MAIL_APEX`/`MAIL_HOST` constants
+ *   (`executor.ts`) still point at the hand-built `wtfalch.dev` instance,
+ *   not this one**, and the Lettermint team token it reads still comes from
+ *   wherever the host already reads it, not held keys. Both need
+ *   `StepExecutionContext` to carry the platform, which `plan-apply.ts`'s
+ *   own doc comment already scoped out of #167 as more than a small change
+ *   -- a follow-up issue, not this one.
+ */
+async function provisionPlatformMail(context, deps) {
+    const { platform } = context;
+    const hostname = platform.mail.hostname;
+    const mailHost = platformMailMxHost(platform.apex);
+    const imageTag = platform.mail.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_MAIL_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_MAIL_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_MAIL_PROJECT)).uuid;
+        await record(PLATFORM_MAIL_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- the Stalwart app itself ---------------------------------------------
+    const imageTagBlocked = mailImageTagBlocked(imageTag);
+    if (imageTagBlocked)
+        throw new Error(imageTagBlocked);
+    // One server for both the app and the MX record: recorded the first time,
+    // read back after, so a later run never points `mx.<apex>` somewhere the
+    // app is not.
+    const server = await resolveMailServer(deps.coolify, recorded[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
+    await record(PLATFORM_MAIL_SERVER_SCOPE_KEY, server.uuid);
+    const serverIpBlocked = mailServerIpBlocked(server.ip);
+    if (serverIpBlocked)
+        throw new Error(serverIpBlocked);
+    const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_MAIL_APP_NAME, environment, async () => {
+        return deps.coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: STALWART_IMAGE,
+            docker_registry_image_tag: imageTag,
+            ports_exposes: STALWART_PORTS_EXPOSES,
+            ports_mappings: STALWART_PORTS_MAPPINGS,
+            name: PLATFORM_MAIL_APP_NAME,
+            description: `Stalwart for the platform's own mail (#169, ${STALWART_IMAGE}:${imageTag})`,
+            instant_deploy: false,
+        });
+    });
+    const appId = app.appId;
+    await record(PLATFORM_MAIL_APP_SCOPE_KEY, appId);
+    // Set on every run, not only after a create -- same rule `provisionPlatformAuth` follows for its own apps.
+    // The image tag too: a declared release change reaches the app here.
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: PLATFORM_MAIL_INTERNAL_NAME,
+        docker_registry_image_tag: imageTag,
+    });
+    // #177: org steps (an org's own `coolify:mail`/`coolify:agora`) read this
+    // back instead of a literal, the same way files/ai's own internal
+    // addresses are recorded.
+    await record(PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}`);
+    // ---- storage ---------------------------------------------------------------
+    const storages = await deps.coolify.listStorages(appId);
+    const hasDataVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === STALWART_DATA_MOUNT);
+    if (!hasDataVolume) {
+        await deps.coolify.createPersistentStorage(appId, {
+            name: `${PLATFORM_MAIL_APP_NAME}-data`,
+            mount_path: STALWART_DATA_MOUNT,
+        });
+    }
+    // ---- env ---------------------------------------------------------------------
+    // Generated once; unlike ZITADEL's masterkey this is never re-derived from
+    // "is the database already in use", because losing it is not destructive
+    // the same way -- worst case a later apply cannot read it back and the
+    // admin-key mint below throws, naming exactly that.
+    const recoveryGenerated = await ensureGeneratedEnv(deps.coolify, appId, 'STALWART_RECOVERY_ADMIN', () => `${STALWART_RECOVERY_USER}:${randomBytes(18).toString('base64')}`);
+    const envs = [
+        { key: 'STALWART_PUBLIC_URL', value: `https://${hostname}` },
+    ];
+    if (recoveryGenerated)
+        envs.push({ key: 'STALWART_RECOVERY_ADMIN', value: recoveryGenerated });
+    const envsChanged = await envsDiffer(deps.coolify, appId, envs);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    const declaredChanged = recorded[PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY] !== imageTag;
+    if (app.justCreated || !app.running || envsChanged || declaredChanged) {
+        // A container still up from before would answer the readiness probe with
+        // the old deployment's health. Stop it and see it stopped first, so the
+        // wait below only ever reads the new deployment.
+        if (!app.justCreated && app.running) {
+            await deps.coolify.raw('POST', `/applications/${appId}/stop`);
+            await waitForMailStopped(deps.coolify, appId, runtime, sleep);
+        }
+        await deps.coolify.deploy(appId);
+        await record(PLATFORM_MAIL_DEPLOYED_SCOPE_KEY, appId);
+        // Right after the deploy, so a later failure (tunnel, DNS, readiness,
+        // settings, mint) does not make the next run stop and redeploy the app.
+        await record(PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY, hostname);
+        await record(PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY, imageTag);
+    }
+    // ---- tunnel and DNS: web/JMAP/management ------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_MAIL_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_MAIL_TUNNEL_NAME));
+    await record(PLATFORM_MAIL_TUNNEL_SCOPE_KEY, tunnel.id);
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            { hostname, service: `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    // #197: without a connector, `hostname` answers with a Cloudflare error.
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_MAIL_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        // The Stalwart app's own server, so the connector shares its Docker network.
+        resolveServer: async () => server,
+        recordedConnectorAppId: recorded[PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:mail: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // ---- the MX hostname: a direct, unproxied A record --------------------------
+    const serverIp = server.ip; // checked by mailServerIpBlocked above
+    const [mxRecord] = await deps.cloudflare.findDnsRecord(zoneId, mailHost, 'A');
+    if (!mxRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'A',
+            name: mailHost,
+            content: serverIp,
+            proxied: false,
+        });
+    }
+    else if (mxRecord.content !== serverIp) {
+        await deps.cloudflare.updateDnsRecord(zoneId, mxRecord.id, {
+            type: 'A',
+            name: mailHost,
+            content: serverIp,
+            proxied: false,
+        });
+    }
+    // ---- OIDC directory and foundry's own admin API key, once --------------------
+    if (!recorded[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]) {
+        const lost = recorded[PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            throw new Error(`platform:mail: an admin API key ("${lost}") was minted but never delivered; revoke it in Stalwart and remove the recorded key ${PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        await waitForMailInstance(`https://${hostname}${STALWART_READY_PATH}`, runtime, sleep);
+        const recoveryEnv = (await deps.coolify.listEnvs(appId)).find((e) => e.key === 'STALWART_RECOVERY_ADMIN' && !e.is_preview);
+        if (!recoveryEnv) {
+            throw new Error('platform:mail: STALWART_RECOVERY_ADMIN is not set on the app; cannot authenticate to mint the admin key');
+        }
+        const password = recoveryEnv.value.slice(`${STALWART_RECOVERY_USER}:`.length);
+        try {
+            const admin = deps.stalwartForInstance({
+                url: `https://${hostname}`,
+                user: STALWART_RECOVERY_USER,
+                password,
+            });
+            await admin.applySettings({
+                mailHost,
+                oidc: { issuerUrl: `https://${platform.auth.hostname}`, audience: deps.oidcAudience },
+            });
+            // Recorded and persisted before the secret leaves this function: if
+            // delivery fails for good, the next plan reports the lost key rather
+            // than skipping or minting again.
+            await record(PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION);
+            const secret = await admin.createApiKey(PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, 'inherit');
+            const attempts = runtime.deliverAttempts ?? 3;
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    await deps.deliverSecret('stalwart:platform:admin', secret);
+                    break;
+                }
+                catch {
+                    if (attempt >= attempts) {
+                        throw new Error(`platform:mail: the admin API key ("${PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION}") was minted but could not be delivered after ${attempts} tries`);
+                    }
+                    await sleep(1000 * attempt);
+                }
+            }
+            await record(PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, appId);
+        }
+        catch (error) {
+            throw redactedMailError(error, [password]);
+        }
+    }
+    // Last, after every write the applied values depend on, so a run that
+    // failed halfway plans again.
+    await record(PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, imageTag);
+    return { resourceId: appId };
+}
+/** Why the Stalwart image tag cannot be used, or `null`. A floating tag cannot be re-pulled by comparing tags. */
+function mailImageTagBlocked(tag) {
+    if (tag.trim() === '' || tag.trim().toLowerCase() === 'latest') {
+        return `the platform's mail server is blocked, not planned: the Stalwart image tag "${tag}" floats; declare a pinned release (for example v0.16.24) as the mail gitRef`;
+    }
+    return null;
+}
+/** Why the server's address cannot be the MX A record's content, or `null`. */
+function mailServerIpBlocked(ip) {
+    if (!ip) {
+        return "the platform's mail server is blocked, not planned: the Coolify server reports no ip, so mx.<apex> has no address to point at; set the server's IP in Coolify";
+    }
+    if (!isIPv4(ip)) {
+        return `the platform's mail server is blocked, not planned: the Coolify server's ip "${ip}" is not an IPv4 address, so it cannot be the mx.<apex> A record; set the server's public IPv4 in Coolify`;
+    }
+    return null;
+}
+/** The recorded server when one is recorded and still listed, else the platform's usual pick. */
+async function resolveMailServer(coolify, recordedUuid) {
+    if (!recordedUuid)
+        return resolvePlatformServer(coolify);
+    const server = (await coolify.listServers()).find((s) => s.uuid === recordedUuid);
+    if (!server) {
+        throw new Error(`platform:mail: the Coolify server ${recordedUuid} the mail app was created on is no longer listed`);
+    }
+    return server;
+}
+/**
+ * The mail step's own reasons it cannot run yet, as fixed text: missing
+ * dependencies or audience, a floating image tag, a server with no usable
+ * address. Skipped once the step is applied at the declared values, so a
+ * live app is not blocked by a later Coolify change to the server's address.
+ */
+async function mailBlockedReason(platform, mail, recordedIds) {
+    if (!mail) {
+        return "the platform's mail server is blocked, not planned: the host built the platform executor without its mail dependencies";
+    }
+    if (recordedIds[`coolify:app:${PLATFORM_MAIL_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]) {
+        return null;
+    }
+    if (!mail.oidcAudience || mail.oidcAudience.trim() === '') {
+        return "the platform's mail server is blocked, not planned: the host supplies no oidcAudience, the ZITADEL resource id Stalwart's OIDC directory checks access tokens against";
+    }
+    const tagBlocked = mailImageTagBlocked(platform.mail.gitRef);
+    if (tagBlocked)
+        return tagBlocked;
+    try {
+        const server = await resolveMailServer(mail.coolify, recordedIds[PLATFORM_MAIL_SERVER_SCOPE_KEY]);
+        return mailServerIpBlocked(server.ip);
+    }
+    catch {
+        return "the platform's mail server is blocked, not planned: no usable Coolify server could be resolved for it";
+    }
+}
+/** Polls until Coolify reports the mail app stopped, so a healthy answer read afterwards is the new deployment's. */
+async function waitForMailStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (!status || !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:mail: the Stalwart app ${appId} did not stop within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/** Polls `url` until it answers 2xx, or throws once `readyTimeoutMs` has passed. */
+async function waitForMailInstance(url, runtime, sleep) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            const response = await fetchImpl(url);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Not up yet: DNS, the tunnel or the container.
+        }
+        if (now() >= deadline) {
+            throw new Error(`platform:mail: the new Stalwart instance did not answer at ${url} within ${Math.round(timeout / 1000)}s; retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+function redactedMailError(error, secrets) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    const message = redactSecrets(original.message, secrets);
+    const stack = redactSecrets(original.stack ?? message, secrets);
+    if (message === original.message && stack === original.stack)
+        return original;
+    const clean = new Error(message);
+    clean.name = original.name;
+    clean.stack = stack;
+    return clean;
+}
+const PLATFORM_ARCHON_PROJECT = 'platform';
+const PLATFORM_ARCHON_APP_NAME = 'platform-archon';
+const PLATFORM_ARCHON_DB_NAME = 'platform-archon-db';
+/**
+ * The database Coolify creates for Archon. Archon's own
+ * `drizzle/0001_runtime_role.sql` names its runtime role
+ * `current_database() || '_rt'`, so {@link ARCHON_RUNTIME_ROLE} follows.
+ */
+const ARCHON_POSTGRES_DB = 'archon';
+const ARCHON_RUNTIME_ROLE = `${ARCHON_POSTGRES_DB}_rt`;
+/** Fixed so the tunnel addresses the container directly (see `provisionPlatformAuth`). */
+const PLATFORM_ARCHON_INTERNAL_NAME = 'platform-archon';
+const PLATFORM_ARCHON_TUNNEL_NAME = 'platform-archon-tunnel';
+/** #197: the one Coolify app that runs `cloudflared` for {@link PLATFORM_ARCHON_TUNNEL_NAME}. */
+const PLATFORM_ARCHON_CLOUDFLARED_APP_NAME = 'platform-archon-cloudflared';
+/** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
+const ARCHON_REPO = 'wtfalch/archon';
+const ARCHON_PORT = '3000';
+/**
+ * The name of foundry's own Cloudflare Access app in front of Archon. Same
+ * `foundry:<key>` convention `executor.ts`'s `cloudflareAccess` uses for an
+ * org (`foundry:<orgId>`), with the platform's step key in the org id's place.
+ */
+export const PLATFORM_ARCHON_ACCESS_APP_NAME = `foundry:${PLATFORM_ARCHON_KEY}`;
+/** The ZITADEL project and OIDC app Archon's sign-in client lives in. */
+const PLATFORM_ARCHON_ZITADEL_PROJECT = 'archon';
+const PLATFORM_ARCHON_ZITADEL_APP = 'archon';
+const PLATFORM_ARCHON_PROJECT_SCOPE_KEY = 'coolify_project_platform_archon';
+const PLATFORM_ARCHON_DB_SCOPE_KEY = 'coolify_platform_archon_database';
+const PLATFORM_ARCHON_TUNNEL_SCOPE_KEY = 'cloudflare_platform_archon_tunnel';
+const PLATFORM_ARCHON_ACCESS_SCOPE_KEY = 'cloudflare_platform_archon_access_app';
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export const PLATFORM_ZITADEL_ORG_SCOPE_KEY = 'zitadel_platform_org';
+const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_archon_project';
+const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = 'zitadel_platform_archon_app';
+/** The hostname the sign-in client's redirect URIs were made for; a change makes a new client. */
+const PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY = 'zitadel_platform_archon_client_hostname';
+/** Archon's OIDC client id: public, not a secret, so a plain scope id. */
+export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_client_id';
+/**
+ * #175: makes `coolify:app` keyed {@link PLATFORM_ARCHON_KEY} true: Archon
+ * from https://github.com/wtfalch/archon on `platform.archon.gitRef`, its own
+ * Postgres, a sign-in client in the platform's own ZITADEL, a Cloudflare
+ * Access app that lets only {@link PlatformArchonDeps.accessEmails} through,
+ * and a tunnel plus DNS record at `platform.archon.hostname`.
+ *
+ * One Coolify app, no separate migrate job: Archon's `Dockerfile` has no
+ * migration stage (its closing note says the old one was removed), and its
+ * `runner` starts with `scripts/migrate-and-start.sh`, which applies
+ * `drizzle/*.sql` as `DATABASE_URL_OWNER`, creates the `<database>_rt` runtime
+ * role, sets its password from `DATABASE_URL`, unsets the owner URL and only
+ * then starts the server.
+ *
+ * Order matters in two places. The Access app is created before the DNS
+ * record, so the hostname never resolves without the gate in front of it
+ * (Archon's `docs/operator-deployment.md`: "Install the Access gate before
+ * publishing DNS"). The sign-in client is created before the env push, so
+ * `AUTH_CLIENT_ID` is in the first deploy.
+ *
+ * Env written from the applied platform and held keys, never pasted:
+ * - `APP_URL`, `AUTH_ISSUER` (`https://<auth.hostname>`),
+ *   `AUTH_ORGANIZATION_ID` and `AUTH_CLIENT_ID` (both from ZITADEL, this run),
+ *   `AUTH_COOKIE_SECRET` (generated once, never rotated).
+ * - `DATABASE_URL_OWNER` (Coolify's `internal_db_url`) and `DATABASE_URL`
+ *   (the `archon_rt` runtime role, its password minted once, never rotated,
+ *   the same rule `executor.ts`'s `ensureCmsRuntimeUrl` follows). A URL that
+ *   does not parse fails the step without printing it.
+ * - For each of files, ai, integrations and jobs that the platform declares
+ *   enabled: its `https://<hostname>` URL, and its management key when
+ *   {@link PlatformArchonDeps.heldKeys} holds one.
+ *
+ * The OIDC client is ZITADEL's public web client (authorization code with
+ * PKCE, no client secret: `createOidcApp` never returns one, see
+ * `executor.ts`'s `zitadelApp`), which is what Archon's `@wtfalch/auth`
+ * sign-in reads -- it takes `AUTH_CLIENT_ID` and no client secret. So there
+ * is no one-time secret to hand to `deliverSecret` here. The two values this
+ * step does generate (cookie secret, runtime-role password) go straight into
+ * the app's env and nowhere else: never returned, recorded, logged or put in
+ * an error.
+ *
+ * Known gaps, left for review:
+ * - `AUTH_APP_KEY`: the `auth.wtfalch.dev` broker's per-organisation
+ *   registry key. The platform's new sign-in has no broker registration API,
+ *   the same gap `executor.ts`'s `pushAppEnv` names for an org's app.
+ * - `AUTHZ_BOOTSTRAP_OPERATOR`: the first operator's ZITADEL subject id. A
+ *   person has to exist in the new instance first; not something foundry
+ *   mints.
+ * - Foundry's own database URL. Archon runs foundry in its panel, but foundry
+ *   does not know its own connection string at plan/apply time: that is host
+ *   config, not something `DeclaredPlatform` or held keys carry.
+ * - The refs and scope ids Archon reads from the files, ai and integrations
+ *   steps are exported by those steps' own modules. A
+ *   missing one blocks the plan (`blockedSteps`); it is never skipped. The
+ *   env names `AI_*`, `INTEGRATIONS_*`, `JOBS_URL` and `JOBS_ADMIN_TOKEN` are
+ *   this step's proposal; Archon reads only `FILES_URL` and
+ *   `FILES_MANAGEMENT_KEY` of these today. Files' signed-assertion identity
+ *   (`FILES_MANAGEMENT_ISSUER`, `_KEY_ID`, `_PRIVATE_KEY`, `_SCOPE`) and
+ *   `FILES_ORGANISATION_ID` are not wired.
+ * - The step plans again when the hostname, `gitRef` or the Access policy's
+ *   include list changes. Env for a service enabled later is not pushed until
+ *   one of those changes.
+ * - No API updates an app's Access policy, so a changed include list closes
+ *   the tunnel hostname, deletes the Access app and builds it again.
+ * - #197: a `cloudflared` connector runs for this tunnel, as in `provisionPlatformAuth`.
+ * - Retiring `operator.wtfalch.dev` stays a human step.
+ */
+async function provisionPlatformArchon(context, deps) {
+    const { platform } = context;
+    const hostname = platform.archon.hostname;
+    const gitRef = platform.archon.gitRef;
+    const recorded = context.recordedIds();
+    const issuer = `https://${platform.auth.hostname}`;
+    const appliedGitRef = recorded[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY];
+    if (deps.accessEmails.length === 0) {
+        throw new Error('platform:archon: no Access emails given; refusing to put Archon behind an Access app nobody can pass');
+    }
+    // The sign-in client below is created inside the platform's own ZITADEL,
+    // which `platform:auth` builds. The planner orders that step first and
+    // blocks this one while auth is off; this is the same rule for a caller
+    // that reaches the step anyway.
+    if (!platform.auth.enabled || !recorded[`coolify:app:${PLATFORM_AUTH_KEY}`]) {
+        throw new Error("platform:archon: the platform's own sign-in (platform:auth) has not been applied yet; Archon's sign-in client lives in it");
+    }
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    // Every service the platform declares must have delivered what Archon reads.
+    // The planner blocks first; this is the same rule for a caller that reaches
+    // the step anyway, and it is where the values are read for the env below.
+    const inputs = await collectArchonServiceInputs(platform, deps, recorded);
+    if ('blocked' in inputs)
+        throw new Error(`platform:archon: ${inputs.blocked}`);
+    // ---- Coolify project and database -----------------------------------------
+    let projectUuid = recorded[PLATFORM_ARCHON_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_ARCHON_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_ARCHON_PROJECT)).uuid;
+        await record(PLATFORM_ARCHON_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    let dbId = recorded[PLATFORM_ARCHON_DB_SCOPE_KEY];
+    if (!dbId) {
+        const server = await resolvePlatformServer(deps.coolify);
+        const created = await deps.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name: PLATFORM_ARCHON_DB_NAME,
+            postgres_db: ARCHON_POSTGRES_DB,
+            postgres_user: ARCHON_POSTGRES_DB,
+        });
+        dbId = created.uuid;
+        await record(PLATFORM_ARCHON_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (archon): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the app ----------------------------------------------------------------
+    const app = await findOrCreatePlatformApp(deps.coolify, PLATFORM_ARCHON_APP_NAME, environment, async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: ARCHON_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name: PLATFORM_ARCHON_APP_NAME,
+        });
+    });
+    const appId = app.appId;
+    // Set on every run: the tunnel addresses the app by this name, and a throw
+    // right after the create must not leave it unnamed for good.
+    // `git_branch` is patched too, so a changed `gitRef` reaches the app; the
+    // deploy below is decided from the last applied `gitRef`.
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: PLATFORM_ARCHON_INTERNAL_NAME,
+        git_branch: gitRef,
+    });
+    // ---- sign-in client in the platform's own ZITADEL -------------------------
+    const zitadel = deps.zitadelForInstance?.(issuer) ?? deps.zitadel;
+    const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+    if (recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] !== org.id) {
+        await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, org.id);
+    }
+    const { project } = await zitadel.findOrCreateProject(org.id, PLATFORM_ARCHON_ZITADEL_PROJECT);
+    if (recorded[PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY] !== project.id) {
+        await record(PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    }
+    // The client's redirect URIs name the hostname, and no call updates them, so
+    // a client made for another hostname is deleted and made again. Its id is
+    // public and there is no secret to lose.
+    let clientId = recorded[PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY] === hostname
+        ? recorded[PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY]
+        : undefined;
+    if (!clientId) {
+        // An app under this name with no usable client id is one whose create
+        // response was lost, or one made for another hostname: its client id
+        // cannot be read back (`listApps` does not carry it), so it is deleted and
+        // made again, as `zitadelApp` does.
+        const orphan = (await zitadel.listApps(org.id, project.id)).find((a) => a.name === PLATFORM_ARCHON_ZITADEL_APP &&
+            a.appType === 'web' &&
+            a.state !== 'APP_STATE_REMOVED');
+        if (orphan) {
+            try {
+                await zitadel.deleteApp(org.id, project.id, orphan.id);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        const created = await zitadel.createOidcApp(org.id, project.id, {
+            name: PLATFORM_ARCHON_ZITADEL_APP,
+            appType: 'web',
+            // `@wtfalch/auth`'s default callback path (Archon's own
+            // `docs/operator-deployment.md`, step 4).
+            redirectUris: [`https://${hostname}/auth/callback`],
+            postLogoutRedirectUris: [`https://${hostname}/`],
+        });
+        context.recordScopeId(PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY, created.appId);
+        context.recordScopeId(PLATFORM_ARCHON_CLIENT_HOSTNAME_SCOPE_KEY, hostname);
+        await record(PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY, created.clientId);
+        clientId = created.clientId;
+    }
+    // ---- env ------------------------------------------------------------------
+    const envs = [
+        { key: 'APP_URL', value: `https://${hostname}` },
+        { key: 'AUTH_ISSUER', value: issuer },
+        { key: 'AUTH_ORGANIZATION_ID', value: org.id },
+        { key: 'AUTH_CLIENT_ID', value: clientId },
+        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        { key: 'REPORTING_SITE', value: 'archon' },
+    ];
+    const cookieSecret = await ensureGeneratedEnv(deps.coolify, appId, 'AUTH_COOKIE_SECRET', () => randomBytes(32).toString('base64'));
+    if (cookieSecret)
+        envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+    const runtimeUrl = await ensureArchonRuntimeUrl(deps.coolify, appId, db.internal_db_url);
+    if (runtimeUrl)
+        envs.push({ key: 'DATABASE_URL', value: runtimeUrl });
+    envs.push(...inputs.envs);
+    const changed = await envsDiffer(deps.coolify, appId, envs);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    // ---- Cloudflare Access, before the hostname resolves ----------------------
+    let gateClosed = Boolean(recorded[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY]);
+    const accessAppId = await ensureArchonAccess(deps.cloudflare, hostname, deps.accessEmails, async () => {
+        // The Access app is about to be rebuilt: answer 404 for every hostname
+        // meanwhile, so it is never served without the gate. The marker is
+        // persisted first: a failure before the real ingress is written back
+        // leaves it set, and the next plan repairs the step.
+        gateClosed = true;
+        await record(PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, '1');
+        const tunnel = await deps.cloudflare.findTunnelByName(PLATFORM_ARCHON_TUNNEL_NAME);
+        if (tunnel)
+            await deps.cloudflare.putTunnelConfig(tunnel.id, {
+                ingress: [{ service: 'http_status:404' }],
+            });
+    });
+    if (recorded[PLATFORM_ARCHON_ACCESS_SCOPE_KEY] !== accessAppId) {
+        await record(PLATFORM_ARCHON_ACCESS_SCOPE_KEY, accessAppId);
+    }
+    // ---- deploy ---------------------------------------------------------------
+    if (app.justCreated ||
+        !app.running ||
+        changed ||
+        appliedGitRef !== gitRef ||
+        recorded[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname) {
+        await deps.coolify.deploy(appId);
+    }
+    // ---- tunnel and DNS ---------------------------------------------------------
+    const existingTunnel = await deps.cloudflare.findTunnelByName(PLATFORM_ARCHON_TUNNEL_NAME);
+    const tunnel = existingTunnel ?? (await deps.cloudflare.createTunnel(PLATFORM_ARCHON_TUNNEL_NAME));
+    if (recorded[PLATFORM_ARCHON_TUNNEL_SCOPE_KEY] !== tunnel.id) {
+        await record(PLATFORM_ARCHON_TUNNEL_SCOPE_KEY, tunnel.id);
+    }
+    await deps.cloudflare.putTunnelConfig(tunnel.id, {
+        ingress: [
+            { hostname, service: `http://${PLATFORM_ARCHON_INTERNAL_NAME}:${ARCHON_PORT}` },
+            { service: 'http_status:404' },
+        ],
+    });
+    if (gateClosed) {
+        await record(PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, '');
+    }
+    // #197: without a connector, `hostname` answers with a Cloudflare error.
+    await ensureCloudflaredConnector({
+        coolify: deps.coolify,
+        cloudflare: deps.cloudflare,
+        tunnelId: tunnel.id,
+        appName: PLATFORM_ARCHON_CLOUDFLARED_APP_NAME,
+        projectUuid,
+        environment,
+        resolveServer: () => resolvePlatformServer(deps.coolify),
+        recordedConnectorAppId: recorded[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: (appId) => record(PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, appId),
+    });
+    const zoneId = recorded[apexZoneKey(platform.apex)] ?? (await exactZone(deps.cloudflare, platform.apex))?.id;
+    if (!zoneId) {
+        throw new Error(`platform:archon: no Cloudflare zone for ${platform.apex} to put ${hostname} in`);
+    }
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [dnsRecord] = await deps.cloudflare.findDnsRecord(zoneId, hostname, 'CNAME');
+    if (!dnsRecord) {
+        await deps.cloudflare.createDnsRecord(zoneId, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    else if (dnsRecord.content !== dnsTarget) {
+        await deps.cloudflare.updateDnsRecord(zoneId, dnsRecord.id, {
+            type: 'CNAME',
+            name: hostname,
+            content: dnsTarget,
+            proxied: true,
+        });
+    }
+    // Last, after every write the applied values depend on, so a run that failed
+    // halfway plans again.
+    await record(PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
+    return { resourceId: appId };
+}
+/**
+ * `executor.ts`'s `cloudflareAccess`, for the platform's Archon: reuses only
+ * an Access app named {@link PLATFORM_ARCHON_ACCESS_APP_NAME}, refuses to
+ * adopt any other Access app already holding the hostname, and refuses when
+ * its own app carries a policy foundry did not create, since that policy
+ * could let others in.
+ */
+async function ensureArchonAccess(cf, domain, emails, closeGate) {
+    const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
+    const foreign = onDomain.find((a) => a.name !== PLATFORM_ARCHON_ACCESS_APP_NAME);
+    if (foreign) {
+        throw new Error(`platform:archon: Access app '${foreign.name}' already holds ${domain}; foundry does not adopt it`);
+    }
+    const create = async () => {
+        const created = await cf.createAccessApp({
+            name: PLATFORM_ARCHON_ACCESS_APP_NAME,
+            domain,
+            type: 'self_hosted',
+        });
+        await cf.createAccessPolicy(created.id, archonAccessPolicy(emails));
+        return created;
+    };
+    const existing = onDomain[0];
+    if (!existing)
+        return (await create()).id;
+    const policies = await cf.listAccessPolicies(existing.id);
+    const other = policies.find((p) => p.name !== ACCESS_POLICY_NAME);
+    if (other) {
+        throw new Error(`platform:archon: Access app ${existing.id} has policy '${other.name}' that foundry did not create`);
+    }
+    if (policies.length === 0) {
+        await cf.createAccessPolicy(existing.id, archonAccessPolicy(emails));
+        return existing.id;
+    }
+    if (policies.every((p) => sameEmails(p.include, emails)))
+        return existing.id;
+    // No call updates an app's policy: rebuild the app, hostname closed meanwhile.
+    await closeGate();
+    await cf.deleteAccessApp(existing.id);
+    return (await create()).id;
+}
+function archonAccessPolicy(emails) {
+    return {
+        name: ACCESS_POLICY_NAME,
+        decision: 'allow',
+        include: emails.map((email) => ({ email: { email } })),
+    };
+}
+/** Whether an Access policy's include list is exactly `emails` (case-insensitive) and nothing else. */
+function sameEmails(include, emails) {
+    if (!Array.isArray(include))
+        return false;
+    const live = new Set();
+    for (const entry of include) {
+        const email = entry?.email?.email;
+        if (typeof email !== 'string' || Object.keys(entry).length !== 1)
+            return false;
+        live.add(email.toLowerCase());
+    }
+    const declared = new Set(emails.map((e) => e.toLowerCase()));
+    return live.size === declared.size && [...declared].every((e) => live.has(e));
+}
+/**
+ * Whether Archon's Access app or policy is gone or no longer lets through
+ * exactly the declared emails. A failed read is not drift: the next plan reads
+ * again.
+ */
+async function archonAccessDrifted(cf, domain, emails) {
+    try {
+        const app = (await cf.listAccessApps()).find((a) => a.domain === domain && a.name === PLATFORM_ARCHON_ACCESS_APP_NAME);
+        if (!app)
+            return true;
+        const policies = await cf.listAccessPolicies(app.id);
+        return !(policies.length > 0 && policies.every((p) => sameEmails(p.include, emails)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What Archon reads from each enabled service, gathered before anything is
+ * built. Either everything is there and the env values come back, or the first
+ * missing piece comes back as one fixed sentence naming a step, scope id or
+ * held-key ref, never a value. Also read at plan time, so the text must not
+ * vary between calls.
+ */
+async function collectArchonServiceInputs(platform, deps, recorded) {
+    const block = (why) => ({ blocked: `Archon is blocked, not planned: ${why}` });
+    const envs = [];
+    const heldByRef = new Map();
+    const services = ['files', 'ai', 'integrations', 'jobs'].filter((s) => platform[s].enabled);
+    if (services.length > 0 && !deps.heldKeys) {
+        return block(`the host built the platform executor without a held-key reader, and ${services.join(', ')} ${services.length === 1 ? 'is' : 'are'} enabled`);
+    }
+    for (const service of services) {
+        const needs = service === 'jobs'
+            ? { stepKey: null, scopeKeys: [], refs: [JOBS_ADMIN_TOKEN_REF] }
+            : ARCHON_SERVICE_INPUTS[service];
+        if (needs.stepKey && !recorded[`coolify:app:${needs.stepKey}`]) {
+            return block(`the ${service} step (${needs.stepKey}) is not applied yet`);
+        }
+        for (const scopeKey of needs.scopeKeys) {
+            if (!recorded[scopeKey]) {
+                return block(`the ${service} step has not recorded the scope id ${scopeKey}`);
+            }
+        }
+        for (const ref of needs.refs) {
+            let held;
+            try {
+                held = (await deps.heldKeys?.resolve(ref)) ?? null;
+            }
+            catch {
+                // The cause is dropped in case it echoes a secret.
+                return block(`the held key ${ref} could not be read`);
+            }
+            if (!held)
+                return block(`the held key ${ref} is not held yet`);
+            heldByRef.set(ref, held);
+        }
+    }
+    const held = (ref) => heldByRef.get(ref);
+    for (const service of services) {
+        if (service === 'files') {
+            envs.push({ key: 'FILES_URL', value: recorded[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY] }, { key: 'FILES_MANAGEMENT_KEY', value: held(ARCHON_SERVICE_INPUTS.files.refs[0]) });
+        }
+        else if (service === 'ai') {
+            envs.push({ key: 'AI_URL', value: recorded[PLATFORM_AI_INTERNAL_URL_SCOPE_KEY] }, { key: 'AI_MANAGEMENT_KEY', value: held(ARCHON_SERVICE_INPUTS.ai.refs[0]) }, {
+                key: 'AI_ORGANISATION_ID',
+                value: recorded[PLATFORM_AI_ORGANISATION_SCOPE_KEY],
+            });
+        }
+        else if (service === 'integrations') {
+            const url = `https://${platform.integrations.hostname}`;
+            envs.push({ key: 'INTEGRATIONS_URL', value: url }, {
+                key: 'INTEGRATIONS_MANAGEMENT_PRIVATE_KEY',
+                value: held(INTEGRATIONS_MANAGEMENT_KEY_REF),
+            }, { key: 'INTEGRATIONS_MANAGEMENT_ISSUER', value: INTEGRATIONS_MANAGEMENT_ISSUER }, { key: 'INTEGRATIONS_MANAGEMENT_KEY_ID', value: INTEGRATIONS_MANAGEMENT_KEY_ID }, { key: 'INTEGRATIONS_MANAGEMENT_AUDIENCE', value: url });
+        }
+        else {
+            envs.push({ key: 'JOBS_URL', value: `https://${platform.jobs.hostname}` }, { key: 'JOBS_ADMIN_TOKEN', value: held(JOBS_ADMIN_TOKEN_REF) });
+        }
+    }
+    return { envs };
+}
+/**
+ * `null` once the app already has a `DATABASE_URL`, never rotated: Archon's
+ * `db-runtime-role.sh` sets the `archon_rt` password from this URL on every
+ * boot while the previous container's pool is still open, so it must stay
+ * the same across deploys. `executor.ts`'s `ensureCmsRuntimeUrl`, with
+ * Archon's role name; see that method for why a parse failure is swallowed
+ * (Node's `ERR_INVALID_URL` carries the whole input, credential included).
+ * `base64url` fits `db-runtime-role.sh`'s password alphabet
+ * (`A-Za-z0-9_.~-`).
+ */
+async function ensureArchonRuntimeUrl(coolify, appId, dbInternalUrl) {
+    const envs = await coolify.listEnvs(appId);
+    if (envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview))
+        return null;
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(dbInternalUrl));
+    }
+    catch {
+        // Node's `ERR_INVALID_URL` carries the whole input, credential included, so
+        // neither it nor the URL goes into this message.
+        throw new Error('platform:archon: the database internal_db_url could not be parsed; not generating DATABASE_URL. Check the database in Coolify and apply again');
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${ARCHON_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
+export const PLATFORM_AI_MANAGEMENT_KEY_REF = 'ai:platform:managementKey';
+/**
+ * What foundry's management key may do: exactly the grants `ai`'s README
+ * ("Archon's first key", by-hand form) gives archon's key, which are the
+ * ones `ai:organisation`, `ai:budget`, `ai:key` and the org destroy call.
+ */
+export const PLATFORM_AI_MANAGEMENT_PERMISSIONS = [
+    'ai.organisations:provision',
+    'ai.organisations:offer',
+    'ai.organisations:delete',
+    'ai.keys:issue',
+    'ai.budgets:update',
+];
+/** The message {@link provisionPlatformAi} throws when no {@link AiManagementKeyMinter} was supplied. */
+export const PLATFORM_AI_MINTER_MISSING = "platform:ai: the AI host is deployed but foundry's AI management key cannot be minted: no AiManagementKeyMinter was supplied (PlatformAiDeps.managementKeyMinter). ai mints its first platform credential only through its keys:issue-archon script run against the database (apps/host/scripts/authz/bootstrap-archon.ts); it has no HTTP route for that, and CoolifyPort cannot run a command inside a container (#172)";
+const PLATFORM_AI_PROJECT = 'platform';
+const PLATFORM_AI_REPO = 'wtfalch/ai';
+const PLATFORM_AI_DB_NAME = 'ai-db';
+const PLATFORM_AI_POSTGRES_DB = 'ai';
+/**
+ * One app per build target of `wtfalch/ai`'s root Dockerfile (its
+ * `apps/host/README.md`, "Images and validation"). `target` is set as
+ * Coolify's `dockerfile_target_build`; `internalName` as the app's fixed
+ * `custom_internal_name`, the way `platform:auth` names its two apps.
+ */
+const PLATFORM_AI_MIGRATE = {
+    name: 'ai-migrate',
+    target: 'migration',
+    internalName: 'platform-ai-migrate',
+};
+const PLATFORM_AI_RUNNER = { name: 'ai', target: 'runner', internalName: 'platform-ai' };
+const PLATFORM_AI_WORKER = {
+    name: 'ai-worker',
+    target: 'worker',
+    internalName: 'platform-ai-worker',
+};
+/** The runner target's `EXPOSE 3000` / `PORT=3000`. */
+const PLATFORM_AI_PORT = '3000';
+const PLATFORM_AI_PROJECT_SCOPE_KEY = 'coolify_project_platform_ai';
+const PLATFORM_AI_DB_SCOPE_KEY = 'coolify_platform_ai_database';
+const PLATFORM_AI_MIGRATE_SCOPE_KEY = 'coolify_platform_ai_migrate_app';
+const PLATFORM_AI_RUNNER_SCOPE_KEY = 'coolify_platform_ai_app';
+const PLATFORM_AI_WORKER_SCOPE_KEY = 'coolify_platform_ai_worker_app';
+/**
+ * Written only when absent, never overwritten: an operator's own model list
+ * or worker bounds survive every apply. Values are `.env.example`'s, and
+ * `AI_MODELS=[]` is the README's "honest configuration for a host with no
+ * approved text model".
+ */
+const PLATFORM_AI_RUNNER_DEFAULTS = [
+    { key: 'AI_MODELS', value: '[]' },
+    { key: 'AI_FORGE_BINDINGS', value: '[]' },
+];
+const PLATFORM_AI_WORKER_DEFAULTS = [
+    ...PLATFORM_AI_RUNNER_DEFAULTS,
+    { key: 'AI_WORKER_BATCH', value: '10' },
+    { key: 'AI_WORKER_TIMEOUT_MS', value: '60000' },
+];
+/**
+ * #172: makes `coolify:app` keyed {@link PLATFORM_AI_KEY} true -- the ai host
+ * (https://github.com/wtfalch/ai) on the platform's Coolify, then foundry's
+ * own AI management key.
+ *
+ * The issue says to run the three parts "as `scripts/redeploy-dark.sh` in
+ * that repo runs them". No such script exists anywhere in that repo's
+ * history, so the shape here comes from what the repo does document: its
+ * root Dockerfile's `migration`, `runner` and `worker` targets and
+ * `apps/host/README.md`. One Coolify Postgres and three apps from the same
+ * repo and `gitRef`, one per target:
+ *
+ * - `ai-migrate` (`migration`) gets `DATABASE_URL_OWNER` (the database's
+ *   own superuser URL, the only app that ever sees it) and `DATABASE_URL`,
+ *   from which `db-runtime-role.sh` sets the `<database>_rt` role's password.
+ *   Its container stays up after migrating ("Coolify reads an exited
+ *   container as a failed deploy") and turns healthy once the marker file is
+ *   written, so this waits for `running:healthy` and then stops it.
+ * - `ai` (`runner`, port 3000) and `ai-worker` (`worker`, the continuously
+ *   polling `scripts/work.ts`) get only `DATABASE_URL`, the restricted
+ *   runtime role, plus the defaults in {@link PLATFORM_AI_WORKER_DEFAULTS}.
+ *
+ * Order: migrate first, wait, stop it, then the runner and worker, so neither
+ * ever starts against an unmigrated schema. A migrate job that does not turn
+ * healthy in time records {@link PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY}; the
+ * planner then reports the step blocked instead of timing out on every apply.
+ * A changed hostname or gitRef plans the step again (the applied values are
+ * recorded last): `git_branch` is patched on every run, `APP_URL` follows the
+ * hostname, and everything redeploys. The migration re-runs whenever
+ * either of the other two is (re)deployed; it is idempotent and additive.
+ * Coolify's auto-deploy on push is switched off on all three, because a push
+ * would otherwise redeploy runner and worker without the migration first.
+ *
+ * `DATABASE_URL` is minted once (a base64url password, the alphabet
+ * `db-runtime-role.sh` allows) and reused from whichever app already has it,
+ * never rotated: the role's password is set from it at every migration.
+ *
+ * The runner's internal address, `http://platform-ai:3000`, is recorded under
+ * {@link PLATFORM_AI_INTERNAL_URL_SCOPE_KEY}. Nothing public is wired: no
+ * Coolify `domains`, tunnel, DNS record or Access app. Whether ai gets
+ * `ai.<apex>` or stays internal like files is open (#172 "Decide"), and both
+ * answers only add to this. `APP_URL` is set from `platform.ai.hostname` as
+ * declared, since the host reads its own origin from it either way.
+ *
+ * The management key follows `platform:auth`'s admin-key discipline: the
+ * credential id is recorded as undelivered before the secret leaves this
+ * function, delivery is retried, and only a delivered key records the guard
+ * that skips the mint. The secret is never returned, recorded, logged or
+ * put in an error. The step's resource id is returned only after that, so
+ * the planner keeps planning the step until the key is delivered.
+ *
+ * Known gaps, left for review (#172 stays open for review):
+ * - No minter ships, so the step is blocked in the planner (nothing is
+ *   deployed) until a host supplies an {@link AiManagementKeyMinter}. It
+ *   cannot be built over ai's admin API: ai issues its first platform-tenant
+ *   credential only from `apps/host/scripts/authz/bootstrap-archon.ts`
+ *   (`keys:issue-archon`), a script that writes to the database directly and
+ *   needs `AUTHZ_BOOTSTRAP_OPERATOR` and the `KEYS_*` settings. Its HTTP
+ *   routes cannot bootstrap one: `POST /v1/organisations/{id}/keys` needs an
+ *   existing `ai.keys:issue` key and refuses the platform tenant, and a
+ *   signed management proof needs a human who already holds authority there.
+ *   `CoolifyPort` has no call that runs a command in a container.
+ * - Crash window: the credential id is recorded only after the minter
+ *   returns, so a crash between the mint and that record loses a key nobody
+ *   knows the id of. ai has no name or idempotency key on that path to find
+ *   it again by; {@link AiManagementKeyMinter} therefore requires a minter to
+ *   look up an existing key named `foundry` and return it before issuing one.
+ * - Coolify's `dockerfile_target_build` and `is_auto_deploy_enabled` are set
+ *   through the generic application PATCH; neither has been checked against
+ *   a live instance from this package.
+ * - The key is minted for 90 days (the README's own examples); nothing
+ *   rotates it yet, so the platform loses its AI management key after 90 days.
+ * - Deploys are decided from the recorded "pending" mark and the app's own
+ *   status, not from a deployment's age: the port cannot read one.
+ * - Provider keys (`KEYS_WORKER_URL`, `KEYS_CREDENTIAL`, `KEYS_VERIFY_KEYS`)
+ *   and sign-in (`AUTH_*`) are not set: until an operator supplies them the
+ *   host answers `503 not_configured` for provider work, as its README says.
+ */
+async function provisionPlatformAi(context, deps) {
+    const { platform } = context;
+    const hostname = platform.ai.hostname;
+    const gitRef = platform.ai.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const { coolify } = deps;
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_AI_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await coolify.findProjectByName(PLATFORM_AI_PROJECT);
+        projectUuid = found ? found.uuid : (await coolify.createProject(PLATFORM_AI_PROJECT)).uuid;
+        await record(PLATFORM_AI_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_AI_DB_SCOPE_KEY];
+    if (!dbId) {
+        const found = (await coolify.listDatabases()).find((d) => d.name === PLATFORM_AI_DB_NAME && d.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const created = await coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_AI_DB_NAME,
+                postgres_db: PLATFORM_AI_POSTGRES_DB,
+                postgres_user: PLATFORM_AI_POSTGRES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(PLATFORM_AI_DB_SCOPE_KEY, dbId);
+    }
+    const db = await coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (ai): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    const ownerUrl = db.internal_db_url;
+    // ---- the three apps ------------------------------------------------------
+    const ensureApp = async (spec, scopeKey) => {
+        const app = await findOrCreatePlatformApp(coolify, spec.name, environment, async () => {
+            const server = await resolvePlatformServer(coolify);
+            const githubApp = await coolify.requireGithubApp();
+            return coolify.createGithubAppApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                github_app_uuid: githubApp.uuid,
+                git_repository: PLATFORM_AI_REPO,
+                git_branch: gitRef,
+                build_pack: 'dockerfile',
+                name: spec.name,
+            });
+        });
+        await record(scopeKey, app.appId);
+        // Set on every run, so a throw right after the create never leaves an app
+        // building the wrong target or deploying itself on a push.
+        const patch = {
+            custom_internal_name: spec.internalName,
+            dockerfile_target_build: spec.target,
+            is_auto_deploy_enabled: false,
+            // Every run, so a changed gitRef reaches an app that already exists.
+            git_branch: gitRef,
+        };
+        if (spec === PLATFORM_AI_RUNNER)
+            patch.ports_exposes = PLATFORM_AI_PORT;
+        await coolify.updateApplication(app.appId, patch);
+        return app;
+    };
+    const migrate = await ensureApp(PLATFORM_AI_MIGRATE, PLATFORM_AI_MIGRATE_SCOPE_KEY);
+    const runner = await ensureApp(PLATFORM_AI_RUNNER, PLATFORM_AI_RUNNER_SCOPE_KEY);
+    const worker = await ensureApp(PLATFORM_AI_WORKER, PLATFORM_AI_WORKER_SCOPE_KEY);
+    // ---- env -----------------------------------------------------------------
+    // Both database URLs are live credentials: handed to `bulkUpsertEnvs` and
+    // nowhere else, never returned, recorded, logged or put in an error.
+    const runtimeUrl = await ensureAiRuntimeUrl(coolify, [runner.appId, worker.appId, migrate.appId], ownerUrl);
+    const migrateEnvs = [
+        { key: 'DATABASE_URL_OWNER', value: ownerUrl },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+    ];
+    const runnerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        { key: 'APP_URL', value: `https://${hostname}` },
+        ...(await missingEnvs(coolify, runner.appId, PLATFORM_AI_RUNNER_DEFAULTS)),
+    ];
+    const workerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...(await missingEnvs(coolify, worker.appId, PLATFORM_AI_WORKER_DEFAULTS)),
+    ];
+    // Whether anything the containers run on differs from what they last
+    // deployed with. Marked and persisted before the first write, and cleared
+    // only after the deploys below, so a run that fails halfway (the migrate
+    // wait throwing, for one) leaves the mark and the next run deploys again.
+    const migrateChanged = await envsDiffer(coolify, migrate.appId, migrateEnvs);
+    const runnerChanged = await envsDiffer(coolify, runner.appId, runnerEnvs);
+    const workerChanged = await envsDiffer(coolify, worker.appId, workerEnvs);
+    const declaredChanged = recorded[PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== gitRef;
+    const pending = Boolean(recorded[PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY]) ||
+        migrateChanged ||
+        runnerChanged ||
+        workerChanged ||
+        declaredChanged;
+    if (pending)
+        await record(PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, '1');
+    await coolify.bulkUpsertEnvs(migrate.appId, migrateEnvs);
+    await coolify.bulkUpsertEnvs(runner.appId, runnerEnvs);
+    await coolify.bulkUpsertEnvs(worker.appId, workerEnvs);
+    const deployRunner = runner.justCreated || !runner.running || pending;
+    const deployWorker = worker.justCreated || !worker.running || pending;
+    const runMigration = migrate.justCreated || deployRunner || deployWorker;
+    // ---- migrate, wait, stop, then runner and worker ------------------------
+    if (runMigration) {
+        // A migrate container still up from an earlier run (one that threw before
+        // stopping it) would already read healthy. Stop it and wait until it
+        // reads stopped, so the wait below only ever sees the new deployment.
+        if (!migrate.justCreated && migrate.running) {
+            await coolify.raw('POST', `/applications/${migrate.appId}/stop`);
+            await waitForStopped(coolify, migrate.appId, runtime, sleep);
+        }
+        await coolify.deploy(migrate.appId);
+        try {
+            await waitForAiMigration(coolify, migrate.appId, runtime, sleep);
+        }
+        catch (error) {
+            if (error instanceof MigrationNotHealthyError) {
+                // Blocked from now on: the planner reports it and plans nothing until
+                // a person fixes the job and removes this key, instead of waiting out
+                // the timeout on every apply.
+                await record(PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, error.lastStatus);
+            }
+            throw error;
+        }
+        await coolify.raw('POST', `/applications/${migrate.appId}/stop`);
+    }
+    if (deployRunner)
+        await coolify.deploy(runner.appId);
+    if (deployWorker)
+        await coolify.deploy(worker.appId);
+    await record(PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, '');
+    // The deploys are done, so record what they deployed now. A later failure
+    // at the mint or delivery must not make the next apply see a changed
+    // hostname or gitRef and redeploy the live host again. The planner still
+    // plans the step until the resource id is recorded, once the key is delivered.
+    await record(PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, gitRef);
+    const internalUrl = `http://${PLATFORM_AI_RUNNER.internalName}:${PLATFORM_AI_PORT}`;
+    await record(PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, internalUrl);
+    // ---- foundry's AI management key, once -----------------------------------
+    const now = context.recordedIds();
+    if (!now[PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY]) {
+        const lost = now[PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY];
+        if (lost) {
+            throw new Error(`platform:ai: AI management key ${lost} was minted but never delivered; revoke it and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        const minter = deps.managementKeyMinter;
+        // The planner blocks the step while there is no minter; this is for a
+        // caller that reaches the step anyway.
+        if (!minter)
+            throw new Error(PLATFORM_AI_MINTER_MISSING);
+        let minted;
+        try {
+            minted = await minter.mintManagementKey({
+                internalUrl,
+                name: 'foundry',
+                expiresDays: 90,
+                permissions: PLATFORM_AI_MANAGEMENT_PERMISSIONS,
+            });
+        }
+        catch {
+            // The cause is dropped in case it echoes a credential.
+            throw new Error('platform:ai: the AI management key could not be minted (the minter failed; its error is not shown). Nothing was recorded; apply again');
+        }
+        const { credentialId, organisationId, secret } = minted;
+        await record(PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, credentialId);
+        await record(PLATFORM_AI_ORGANISATION_SCOPE_KEY, organisationId);
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret(PLATFORM_AI_MANAGEMENT_KEY_REF, secret);
+                break;
+            }
+            catch {
+                // The cause is dropped in case it echoes the secret.
+                if (attempt >= attempts) {
+                    throw new Error(`platform:ai: AI management key ${credentialId} was minted but could not be delivered after ${attempts} tries`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await record(PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, credentialId);
+    }
+    return { resourceId: runner.appId };
+}
+/** The migrate job did not turn healthy in time; carries its last status, which holds no secret. */
+class MigrationNotHealthyError extends Error {
+    lastStatus;
+    constructor(lastStatus, message) {
+        super(message);
+        this.lastStatus = lastStatus;
+    }
+}
+/**
+ * Polls the app until Coolify reports it stopped (`exited`/`stopped`), so a
+ * healthy status read afterwards belongs to a deployment queued after this.
+ */
+async function waitForStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 600_000;
+    const interval = runtime.migrateIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (status && !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:ai: the migrate job ${appId} did not stop within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` -- the
+ * migration target's healthcheck passes only once `migrate.mjs` has finished
+ * -- or throws {@link MigrationNotHealthyError} once `migrateTimeoutMs` has
+ * passed. The caller stopped the app and saw it stopped before deploying, so
+ * a healthy status here is the new deployment's. Any other status (queued,
+ * building, exited, starting unhealthy) keeps waiting. On a timeout the job
+ * is left as it is: stopping it mid-migration is worse.
+ */
+async function waitForAiMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 600_000;
+    const interval = runtime.migrateIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        await sleep(interval);
+        const { status } = await coolify.getApplication(appId);
+        if (status?.startsWith('running:healthy'))
+            return;
+        if (now() >= deadline) {
+            throw new MigrationNotHealthyError(status ?? 'unknown', `platform:ai: the migrate job ${appId} did not report healthy within ${Math.round(timeout / 1000)}s (last status ${status ?? 'unknown'}); the host and worker were not deployed. Check its logs; the step is blocked until the recorded key ${PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY} is removed`);
+        }
+    }
+}
+/**
+ * The runtime role's `DATABASE_URL`, reused from the first of `appIds` that
+ * already has one, else minted: `<database>_rt` (the name ai's
+ * `0001_runtime_role.sql` derives) with a fresh base64url password, on the
+ * owner URL's host, database and query string. The owner URL is parsed
+ * inside a try: Node's parse error carries the whole input, credential
+ * included, so it is replaced with a fixed message.
+ */
+async function ensureAiRuntimeUrl(coolify, appIds, ownerUrl) {
+    for (const appId of appIds) {
+        const existing = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+        if (existing)
+            return existing.value;
+    }
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(ownerUrl));
+    }
+    catch {
+        throw new Error("platform:ai: the database's internal_db_url could not be parsed");
+    }
+    const database = pathname.replace(/^\//, '');
+    if (!/^[A-Za-z0-9_]+$/.test(database)) {
+        throw new Error("platform:ai: the database's name cannot form a runtime role name (letters, digits and _ only)");
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${database}_rt:${password}@${host}${pathname}${search}`;
+}
+/** The entries of `defaults` whose key the app does not have yet. */
+async function missingEnvs(coolify, appId, defaults) {
+    const present = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => e.key));
+    return defaults.filter((d) => !present.has(d.key));
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Polls `url` until it answers 2xx, or throws once `readyTimeoutMs` has passed. */
+async function waitForInstance(url, runtime, sleep) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            const response = await fetchImpl(url);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Not up yet: DNS, the tunnel or the container.
+        }
+        if (now() >= deadline) {
+            throw new Error(`platform:auth: the new ZITADEL instance did not answer at ${url} within ${Math.round(timeout / 1000)}s; retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+async function resolvePlatformServer(coolify) {
+    const servers = await coolify.listServers();
+    const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
+    if (!server)
+        throw new Error('no usable Coolify server is registered on this instance');
+    return server;
+}
+/**
+ * `executor.ts`'s `coolifyCalls`/`findOrCreateCallsApp`, restated here rather
+ * than imported: that method is private to `FoundryStepExecutor`, and this
+ * file holds no instance of that class to call it on. `running` says whether
+ * the app was already running or starting; the caller deploys it when not.
+ */
+async function findOrCreatePlatformApp(coolify, name, environment, create) {
+    const existing = await coolify.findApplicationByName(name, { environmentIds: [environment.id] });
+    if (existing) {
+        const live = await coolify.getApplication(existing.uuid);
+        return {
+            appId: existing.uuid,
+            justCreated: false,
+            running: isRunningOrStarting(live.status),
+        };
+    }
+    const created = await create();
+    return { appId: created.uuid, justCreated: true, running: false };
+}
+/** Whether any desired env is missing from the app, or set to another value. */
+async function envsDiffer(coolify, appId, desired) {
+    const live = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    return desired.some((e) => live.get(e.key) !== e.value);
+}
+/**
+ * `null` once the app already has this key set -- generated only the first
+ * time, never regenerated or overwritten, mirroring `executor.ts`'s
+ * `ensureAuthCookieSecret` exactly.
+ */
+async function ensureGeneratedEnv(coolify, appId, key, generate) {
+    const envs = await coolify.listEnvs(appId);
+    const already = envs.some((e) => e.key === key && !e.is_preview);
+    if (already)
+        return null;
+    return generate();
+}
+/**
+ * {@link ensureGeneratedEnv} for `ZITADEL_MASTERKEY`, which encrypts what
+ * ZITADEL keeps in its database. A new key over a database ZITADEL has run
+ * against (one that existed before this run and had its app deployed) makes
+ * that data unreadable, so such a database never gets a generated one. The
+ * env is always written before the first deploy, so a missing key on a
+ * deployed app means someone removed it. This throws, and a person sets the key that database was
+ * initialised with (or deletes an unused database) and applies again.
+ */
+async function ensureMasterkey(coolify, appId, databaseInUse) {
+    const envs = await coolify.listEnvs(appId);
+    if (envs.some((e) => e.key === 'ZITADEL_MASTERKEY' && !e.is_preview))
+        return null;
+    if (databaseInUse) {
+        throw new Error(`platform:auth: app ${appId} has no ZITADEL_MASTERKEY but its database is already in use; not generating a new one. Set ZITADEL_MASTERKEY on that app to the key the database was initialised with, or delete the database if ZITADEL never ran on it, then apply again`);
+    }
+    return randomBytes(24).toString('base64');
+}
+/** `docs/deploy.md`: "ZITADEL_ADMIN_PASSWORD: 8+, upper, lower, digit, symbol". */
+function generateAdminPassword() {
+    return `${randomBytes(18).toString('base64')}Aa1!`;
+}
+/**
+ * #171: how the host signs a files management request with the key this step
+ * delivers under {@link FILES_MANAGEMENT_KEY_REF} (files'
+ * `signManagementRequest`'s `SigningIdentity`): `issuer` is
+ * {@link FILES_MANAGEMENT_ISSUER}, `keyId` is {@link FILES_MANAGEMENT_KEY_ID},
+ * `audience` is `https://<platform.files.hostname>` (the files host's
+ * `APP_URL`, which this step sets), and `privateKey` is the delivered PKCS#8
+ * PEM. Neither constant is a secret. The files host pins the public half
+ * through `MANAGEMENT_ISSUER`/`MANAGEMENT_PUBLIC_KEYS`, which this step sets.
+ */
+export const FILES_MANAGEMENT_ISSUER = 'foundry';
+export const FILES_MANAGEMENT_KEY_ID = 'foundry-1';
+/** The ref the management private key (PKCS#8 PEM) is delivered under. */
+export const FILES_MANAGEMENT_KEY_REF = 'files:platform:managementKey';
+/** The ref the files host's introspection client secret is delivered under. */
+export const FILES_INTROSPECTION_SECRET_REF = 'zitadel:platform:files:introspection';
+/** https://github.com/wtfalch/files -- root Dockerfile with `migration` and `runner` targets. */
+const FILES_REPO = 'wtfalch/files';
+const PLATFORM_FILES_PROJECT = 'platform';
+const PLATFORM_FILES_DB_NAME = 'platform-files-db';
+/** The two Coolify apps files' `apps/host/README.md` ("Deploying on Coolify") names. */
+const FILES_MIGRATE_APP_NAME = 'files-migrate';
+const FILES_RUNNER_APP_NAME = 'files';
+/**
+ * The runner's fixed `custom_internal_name`: the name another container on
+ * the Coolify network reaches it by, and so the host part of
+ * {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY}'s recorded address.
+ */
+const FILES_RUNNER_INTERNAL_NAME = 'platform-files';
+/** The runner's port (`Dockerfile`'s `runner` stage: `PORT=3000`, `EXPOSE 3000`). */
+const FILES_PORT = '3000';
+/** The Postgres database name; files' runtime role is `<database>_rt`. */
+const FILES_DB = 'files';
+const FILES_RUNTIME_ROLE = `${FILES_DB}_rt`;
+const FILES_ZITADEL_PROJECT_NAME = 'files';
+const FILES_INTROSPECTION_APP_NAME = 'files-introspection';
+const PLATFORM_FILES_PROJECT_SCOPE_KEY = 'coolify_project_platform_files';
+const PLATFORM_FILES_DB_SCOPE_KEY = 'coolify_platform_files_database';
+const PLATFORM_FILES_MIGRATE_SCOPE_KEY = 'coolify_platform_files_migrate_app';
+const PLATFORM_FILES_RUNNER_SCOPE_KEY = 'coolify_platform_files_runner_app';
+/**
+ * #171: makes `coolify:app` keyed {@link PLATFORM_FILES_KEY} true -- the files
+ * host from https://github.com/wtfalch/files, on Coolify's internal network
+ * only, following its `apps/host/README.md` ("Deploying on Coolify"):
+ *
+ * 1. A Coolify Postgres (`files`), and two apps from the repo's root
+ *    Dockerfile: `files-migrate` (the `migration` target) and `files` (the
+ *    `runner` target, no domain, a fixed `custom_internal_name`).
+ * 2. In the platform's own sign-in: the `files` ZITADEL project (its id is the
+ *    person-token audience, `AUTH_PERSON_TOKEN_AUDIENCE`) and an API app, the
+ *    host's introspection client (`AUTH_PERSON_TOKEN_INTROSPECTION_*`).
+ * 3. Foundry's management key: an Ed25519 keypair minted here. The public
+ *    half is pinned on the runner (`MANAGEMENT_ISSUER`,
+ *    `MANAGEMENT_PUBLIC_KEYS`); the private half goes to the host as a held
+ *    key, which is what the org steps' `FilesOrganisationPort` signs with.
+ * 4. Deploy `files-migrate`, wait for it to report healthy, stop it, then
+ *    deploy `files`.
+ * 5. Record the runner's internal address and the ZITADEL project id.
+ *
+ * Both secrets are handed to {@link PlatformFilesDeps.deliverSecret} and
+ * written to the runner's env, and nowhere else: never returned, recorded,
+ * logged or put in a thrown error. Each is made only while its guard is
+ * unrecorded, and follows `platform:auth`'s admin-token pattern: an
+ * "undelivered" id is recorded and persisted the moment the secret is made,
+ * and the guard only after delivery AND the env write. A run that fails in
+ * between leaves an undelivered id with no guard; the planner reports that
+ * and never mints again, and a person clears the recorded key (and the
+ * ZITADEL client) to allow a new one.
+ *
+ * A re-run after a changed hostname or `gitRef` (recorded as applied scope
+ * ids) updates `git_branch` and the runner env and redeploys, and mints
+ * nothing.
+ *
+ * Known gaps, left for review:
+ * - The README says to wait for `files-migrate: done` in the migrate app's
+ *   logs. `CoolifyPort` cannot read logs, so this waits for Coolify to report
+ *   the app `running:healthy` instead. The `migration` stage's HEALTHCHECK
+ *   (`test -f /tmp/files-migrated`) passes on the file touched right before
+ *   that line is logged, so the two mean the same thing. The migrate app is stopped
+ *   before its deploy, so the poll cannot pass on a container left up by a
+ *   failed run. Whether Coolify's status still shows the old container for a
+ *   moment right after the deploy is not checked against a live Coolify.
+ * - The Dockerfile target is chosen by setting `dockerfile_target_build`
+ *   through `updateApplication`, since `createGithubAppApplication` has no
+ *   field for it. Not yet checked against a live Coolify.
+ * - The runner is created without `domains`, like `platform:auth`'s apps.
+ *   Whether Coolify adds a generated domain anyway is not yet checked.
+ * - Foundry sets only the env it owns: the two database URLs, `APP_URL`,
+ *   `AUTH_ISSUER`, `AUTH_PERSON_TOKEN_*`, `MANAGEMENT_*` and the two `KEYS_*`
+ *   values the host supplies through {@link PlatformFilesDeps.keys}, which
+ *   files-migrate needs to become healthy. The rest of files' `.env.example`
+ *   (`R2_*`, `KEYS_VERIFY_KEYS`, `JOBS_*`, `AUTHZ_BOOTSTRAP_OPERATOR`, ...)
+ *   is set by a person on the runner.
+ * - The files project lives in the platform's `foundry` ZITADEL org. An
+ *   org's Agora requests it as an audience scope from its own ZITADEL org;
+ *   whether that needs a project grant per org is not decided here.
+ * - The recorded address is reachable only from a container on the same
+ *   Coolify network, so the host must run there to use it for management
+ *   calls.
+ */
+async function provisionPlatformFiles(context, deps) {
+    const { platform } = context;
+    const gitRef = platform.files.gitRef;
+    const recorded = context.recordedIds();
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const attempts = runtime.deliverAttempts ?? 3;
+    const keys = filesKeys(deps);
+    if (!keys) {
+        throw new Error('platform:files needs the keys worker URL and credential in its files dependencies (KEYS_WORKER_URL, KEYS_CREDENTIAL); files-migrate never becomes healthy without them');
+    }
+    // Never plan-and-throw: the planner reports a lost secret and plans
+    // nothing; this is the same rule for a caller that reaches the step anyway.
+    for (const [undeliveredKey, guardKey] of [
+        [PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY],
+        [PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY],
+    ]) {
+        const lost = recorded[undeliveredKey];
+        if (lost && !recorded[guardKey]) {
+            throw new Error(`platform:files: a secret (${lost}) was minted but never delivered; remove the recorded key ${undeliveredKey} to mint a new one`);
+        }
+    }
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    let projectUuid = recorded[PLATFORM_FILES_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await deps.coolify.findProjectByName(PLATFORM_FILES_PROJECT);
+        projectUuid = found
+            ? found.uuid
+            : (await deps.coolify.createProject(PLATFORM_FILES_PROJECT)).uuid;
+        await record(PLATFORM_FILES_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await deps.coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database ----------------------------------------------------------
+    let dbId = recorded[PLATFORM_FILES_DB_SCOPE_KEY];
+    if (!dbId) {
+        // Found by name first, so a crash between create and record never makes
+        // a second one (`coolifyJobs` does the same).
+        const found = (await deps.coolify.listDatabases()).find((db) => db.name === PLATFORM_FILES_DB_NAME && db.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(deps.coolify);
+            const created = await deps.coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: PLATFORM_FILES_DB_NAME,
+                postgres_db: FILES_DB,
+                postgres_user: FILES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(PLATFORM_FILES_DB_SCOPE_KEY, dbId);
+    }
+    const db = await deps.coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error('coolify:app for the platform (files): the database has no internal_db_url yet -- retry this apply once Coolify reports one');
+    }
+    // ---- the two apps --------------------------------------------------------
+    const createFilesApp = (name) => async () => {
+        const server = await resolvePlatformServer(deps.coolify);
+        const githubApp = await deps.coolify.requireGithubApp();
+        return deps.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: FILES_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name,
+        });
+    };
+    const migrateApp = await findOrCreatePlatformApp(deps.coolify, FILES_MIGRATE_APP_NAME, environment, createFilesApp(FILES_MIGRATE_APP_NAME));
+    await record(PLATFORM_FILES_MIGRATE_SCOPE_KEY, migrateApp.appId);
+    // Set on every run, like `platform:auth`'s `custom_internal_name`: a throw
+    // right after a create must not leave the app on the wrong target.
+    // `git_branch` too, so a changed `gitRef` reaches an app made earlier.
+    await deps.coolify.updateApplication(migrateApp.appId, {
+        dockerfile_target_build: 'migration',
+        git_branch: gitRef,
+    });
+    const runnerApp = await findOrCreatePlatformApp(deps.coolify, FILES_RUNNER_APP_NAME, environment, createFilesApp(FILES_RUNNER_APP_NAME));
+    await record(PLATFORM_FILES_RUNNER_SCOPE_KEY, runnerApp.appId);
+    await deps.coolify.updateApplication(runnerApp.appId, {
+        dockerfile_target_build: 'runner',
+        custom_internal_name: FILES_RUNNER_INTERNAL_NAME,
+        git_branch: gitRef,
+    });
+    // ---- database env ----------------------------------------------------------
+    // The migrate app sets `files_rt`'s password from DATABASE_URL on every
+    // boot (files' `scripts/db-runtime-role.sh`), and the runner connects with
+    // the same URL, so both apps carry one value, minted once and never
+    // rotated: an existing value on either app is reused.
+    const runtimeUrl = await ensureFilesRuntimeUrl(deps.coolify, [migrateApp.appId, runnerApp.appId], db.internal_db_url);
+    // The keys worker the migrate app needs to become healthy (files' README:
+    // `DATABASE_URL_OWNER`, `DATABASE_URL`, `KEYS_WORKER_URL`, `KEYS_CREDENTIAL`).
+    const keysEnvs = [
+        { key: 'KEYS_WORKER_URL', value: keys.workerUrl },
+        { key: 'KEYS_CREDENTIAL', value: keys.credential },
+    ];
+    await deps.coolify.bulkUpsertEnvs(migrateApp.appId, [
+        { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...keysEnvs,
+    ]);
+    // ---- the files ZITADEL project, in the platform's sign-in ----------------
+    const issuer = `https://${platform.auth.hostname}`;
+    const zitadel = deps.zitadelForInstance?.(issuer) ?? deps.zitadel;
+    const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+    const { project } = await zitadel.findOrCreateProject(org.id, FILES_ZITADEL_PROJECT_NAME);
+    await record(PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    const runnerEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        // The management verifier's audience, which must be an HTTPS origin. The
+        // host has no public address, so this is a name, not a route.
+        { key: 'APP_URL', value: `https://${platform.files.hostname}` },
+        { key: 'AUTH_ISSUER', value: issuer },
+        { key: 'AUTH_PERSON_TOKEN_AUDIENCE', value: project.id },
+        ...keysEnvs,
+    ];
+    // Base env first, so a secret's own write below cannot be the only one
+    // that lands, and a re-run with a changed hostname updates `APP_URL`.
+    await deps.coolify.bulkUpsertEnvs(runnerApp.appId, runnerEnvs);
+    // ---- the introspection client, once --------------------------------------
+    if (!recorded[PLATFORM_FILES_INTROSPECTION_SCOPE_KEY]) {
+        // An app by this name here has no recorded secret (no undelivered id, or
+        // the throw above would have fired): a crash between the create and the
+        // record. Nothing was delivered, so it is deleted and made again.
+        const stale = (await zitadel.listApps(org.id, project.id)).filter((app) => app.name === FILES_INTROSPECTION_APP_NAME && app.state !== 'APP_STATE_REMOVED');
+        for (const app of stale) {
+            try {
+                await zitadel.deleteApp(org.id, project.id, app.id);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        const client = await zitadel.createApiApp(org.id, project.id, {
+            name: FILES_INTROSPECTION_APP_NAME,
+        });
+        // Recorded and persisted before the secret leaves this function: a failed
+        // delivery or env write is then reported by the planner, not remade.
+        await record(PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, client.appId);
+        await deliverWithRetry(deps.deliverSecret, FILES_INTROSPECTION_SECRET_REF, client.clientSecret, attempts, sleep, `the introspection client secret (ZITADEL app ${client.appId})`);
+        await deps.coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_ID', value: client.clientId },
+            { key: 'AUTH_PERSON_TOKEN_INTROSPECTION_CLIENT_SECRET', value: client.clientSecret },
+        ]);
+        await record(PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, client.appId);
+    }
+    // ---- foundry's management key, once --------------------------------------
+    if (!recorded[PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY]) {
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+            publicKeyEncoding: { type: 'spki', format: 'pem' },
+            privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        });
+        await record(PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, FILES_MANAGEMENT_KEY_ID);
+        await deliverWithRetry(deps.deliverSecret, FILES_MANAGEMENT_KEY_REF, privateKey, attempts, sleep, 'the files management key');
+        await deps.coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'MANAGEMENT_ISSUER', value: FILES_MANAGEMENT_ISSUER },
+            {
+                key: 'MANAGEMENT_PUBLIC_KEYS',
+                value: JSON.stringify({ [FILES_MANAGEMENT_KEY_ID]: publicKey }),
+            },
+        ]);
+        await record(PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, FILES_MANAGEMENT_KEY_ID);
+    }
+    // ---- deploy: stop migrate, deploy it, wait, stop it, then the runner -----
+    // A failed run can leave `files-migrate` up and healthy from the last
+    // deploy. Stopped first, so the wait below cannot pass on the old
+    // container before the new migration has run.
+    await stopIfRunning(deps.coolify, migrateApp.appId);
+    await deps.coolify.deploy(migrateApp.appId);
+    await waitForMigration(deps.coolify, migrateApp.appId, runtime, sleep);
+    await deps.coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+    await deps.coolify.deploy(runnerApp.appId);
+    await record(PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, `http://${FILES_RUNNER_INTERNAL_NAME}:${FILES_PORT}`);
+    // Last: a run that failed anywhere above is planned again.
+    context.recordScopeId(PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, platform.files.hostname);
+    await record(PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, gitRef);
+    return { resourceId: runnerApp.appId };
+}
+function filesKeys(deps) {
+    const keys = deps?.keys;
+    return keys?.workerUrl && keys.credential ? keys : null;
+}
+/** Stops the app when Coolify reports it running; a stop on an app that is not running can fail. */
+async function stopIfRunning(coolify, appId) {
+    const { status } = await coolify.getApplication(appId);
+    if (status?.startsWith('running'))
+        await coolify.raw('POST', `/applications/${appId}/stop`);
+}
+/**
+ * Hands `secret` to the host, retrying. The thrown error names `what` only,
+ * never the secret or the cause, which could echo it.
+ */
+async function deliverWithRetry(deliverSecret, ref, secret, attempts, sleep, what) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await deliverSecret(ref, secret);
+            return;
+        }
+        catch {
+            if (attempt >= attempts) {
+                throw new Error(`platform:files: ${what} could not be delivered after ${attempts} tries; the next plan reports it as lost and mints no new one`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+}
+/**
+ * The runtime `DATABASE_URL` both files apps share: the first one already set
+ * on either app, else a new `files_rt` credential on the database's host,
+ * built the way `executor.ts`'s `ensureCmsRuntimeUrl` builds `cms_rt`'s. A
+ * parse failure throws a message with no part of the URL in it, since the
+ * URL carries the superuser's password.
+ */
+async function ensureFilesRuntimeUrl(coolify, appIds, dbInternalUrl) {
+    for (const appId of appIds) {
+        const existing = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+        if (existing)
+            return existing.value;
+    }
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(dbInternalUrl));
+    }
+    catch {
+        throw new Error("coolify:app for the platform (files): the database's internal_db_url could not be parsed to build the runtime DATABASE_URL");
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${FILES_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` after
+ * first reporting anything else -- a healthy status before that is the old
+ * container, since the stop and deploy calls can return before Coolify's
+ * status catches up. The
+ * `migration` stage's HEALTHCHECK passes only once the migration has
+ * succeeded (see {@link provisionPlatformFiles}'s known gaps for why this
+ * stands in for the log line). Throws once `migrateTimeoutMs` has passed; the
+ * runner is then never deployed against an unmigrated database.
+ */
+async function waitForMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 900_000;
+    const interval = runtime.migrateIntervalMs ?? 10_000;
+    const deadline = now() + timeout;
+    let left = false;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (status === 'running:healthy' && left)
+            return;
+        if (status !== 'running:healthy')
+            left = true;
+        if (now() >= deadline) {
+            throw new Error(`platform:files: files-migrate (${appId}) did not report healthy within ${Math.round(timeout / 1000)}s (last status: ${status ?? 'unknown'}); the files app was not deployed. Check its logs for "files-migrate: done" and retry this apply`);
+        }
+        await sleep(interval);
+    }
+}
+export const INTEGRATIONS_KEYS_ENV_NAMES = [
+    'KEYS_WORKER_URL',
+    'KEYS_CREDENTIAL',
+    'KEYS_VERIFY_KEYS',
+    'KEYS_AUDIT_TOKEN',
+];
+/** https://github.com/wtfalch/integrations -- one root Dockerfile, three targets. */
+const INTEGRATIONS_REPO = 'wtfalch/integrations';
+/**
+ * The three Coolify apps `apps/host/README.md`'s "Deploy: migrate, web,
+ * worker" names, each with the root Dockerfile target it builds.
+ */
+const INTEGRATIONS_MIGRATE_APP = { name: 'integrations-migrate', target: 'migration' };
+const INTEGRATIONS_RUNNER_APP = { name: 'integrations', target: 'runner' };
+const INTEGRATIONS_WORKER_APP = { name: 'integrations-worker', target: 'worker' };
+/** The runner's `EXPOSE 3000`; readiness is its own `HEALTHCHECK` on `/api/health`. */
+const INTEGRATIONS_RUNNER_PORT = '3000';
+const INTEGRATIONS_DB_NAME = 'integrations-db';
+/**
+ * The Postgres database and owner name. The host's runtime role is derived
+ * from the database, never configured: `drizzle/0001_runtime_role.sql`
+ * creates `current_database() || '_rt'`, so the runtime URL below must name
+ * exactly {@link INTEGRATIONS_RUNTIME_ROLE}.
+ */
+const INTEGRATIONS_POSTGRES_DB = 'integrations';
+const INTEGRATIONS_RUNTIME_ROLE = `${INTEGRATIONS_POSTGRES_DB}_rt`;
+/**
+ * `.env.example`'s own default. Only ever set when absent: every stored
+ * registration client secret is bound to this id, so foundry never
+ * overwrites a value a person changed.
+ */
+const INTEGRATIONS_OPERATOR_TENANT_ID = 'operator';
+/** `.env.example`'s own default for one worker pass; only ever set when absent. */
+const INTEGRATIONS_WORKER_BATCH = '50';
+const INTEGRATIONS_DATABASE_SCOPE_KEY = 'coolify_integrations_database';
+const INTEGRATIONS_MIGRATE_APP_SCOPE_KEY = 'coolify_integrations_migrate_app';
+const INTEGRATIONS_RUNNER_APP_SCOPE_KEY = 'coolify_integrations_app';
+const INTEGRATIONS_WORKER_APP_SCOPE_KEY = 'coolify_integrations_worker_app';
+/** Set (to the gitRef it migrated) once that ref's migration succeeded and the app was stopped. */
+const INTEGRATIONS_MIGRATED_SCOPE_KEY = 'integrations_migrated';
+/** The ref the management private key (PKCS#8 PEM) is delivered under. */
+export const INTEGRATIONS_MANAGEMENT_KEY_REF = 'integrations:management:privateKey';
+/** `MANAGEMENT_ISSUER` on the integrations host: whoever signs with the delivered key signs as this issuer. */
+export const INTEGRATIONS_MANAGEMENT_ISSUER = 'foundry';
+/**
+ * The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS`
+ * (the host's keyring allows `^[A-Za-z0-9_-]{1,100}$`). A signer names it in
+ * its signed request; fixed, since there is one key until rotation is built.
+ */
+export const INTEGRATIONS_MANAGEMENT_KEY_ID = 'foundry-1';
+/**
+ * #174: makes `coolify:app` keyed {@link PLATFORM_INTEGRATIONS_KEY} true --
+ * the integrations host (https://github.com/wtfalch/integrations) as its own
+ * `apps/host/README.md` ("Deploy: migrate, web, worker") describes it, in the
+ * shared `platform` Coolify project `coolify:jobs` uses:
+ *
+ * 1. A Postgres database (`integrations-db`), whose superuser URL is
+ *    `DATABASE_URL_OWNER` and whose `integrations_rt` runtime role gets a
+ *    password minted here once, as `DATABASE_URL` -- the same owner/runtime
+ *    split `executor.ts`'s `ensureCmsRuntimeUrl` builds for the cms app.
+ * 2. Three apps from the one repo, each on its own Dockerfile target (set by
+ *    `updateApplication`, since Coolify's create endpoint refuses
+ *    `dockerfile_target_build`): `integrations-migrate` (`migration`),
+ *    `integrations` (`runner`, at `hostname`) and `integrations-worker`
+ *    (`worker`). The host's own `@wtfalch/keys` settings
+ *    ({@link PlatformIntegrationsDeps.keysEnv}) are written to them.
+ * 3. The migrate app first, once per `gitRef`: stop it if running, deploy it,
+ *    wait until it reports healthy, stop it, and record the ref it migrated.
+ *    Only then are the runner and worker deployed.
+ * 4. The management key, once: an Ed25519 pair minted here, its id recorded
+ *    before delivery, its private half handed to
+ *    {@link PlatformIntegrationsDeps.deliverSecret} and its public half pinned
+ *    on the runner as `MANAGEMENT_PUBLIC_KEYS`, with `MANAGEMENT_ISSUER`. The
+ *    guard is recorded after both.
+ * 5. The applied `hostname` and `gitRef` are recorded last. A later change
+ *    plans the step again (`planIntegrations`), which patches `git_branch`
+ *    and the runner's `domains`, reruns the migration for a new ref, and
+ *    redeploys. It never mints the key again.
+ *
+ * Every part is safe to run again after a throw partway: each id is recorded
+ * and persisted as soon as its resource exists, and what to deploy is read
+ * from the live apps. Secrets -- the database URLs, the `KEYS_*` values and
+ * the private key -- go to `bulkUpsertEnvs`/`deliverSecret` and nowhere else:
+ * never returned, recorded, logged or put in an error.
+ *
+ * Known gaps, left for review:
+ * - "Wait for `integrations-migrate: done` in its logs" is approximated by
+ *   polling the app's Coolify `status` for `running:healthy`: `CoolifyPort`
+ *   has no way to read container logs. The `migration` target's own
+ *   `HEALTHCHECK` passes only once the file it touches right before printing
+ *   that line exists, so healthy means the same thing. `exited` never counts
+ *   as done.
+ * - The worker is created and deployed when created or changed, but nothing
+ *   schedules it. Its image runs one queue pass and exits, so Coolify's
+ *   scheduled tasks (which run a command in a *running* container) have no
+ *   container to run in, and `wtfalch/jobs` delivers a schedule as an HTTP
+ *   POST to a receiver route the integrations host does not have. Choosing
+ *   between such a route and a long-running worker image is a decision for
+ *   the integrations repo. Until then queued messages wait for a manual pass.
+ * - Changing `gitRef` to a ref that has new commits under the same name is
+ *   not seen: only a different ref name re-plans the step.
+ * - Like `coolify:jobs`, the runner is reached through its Coolify `domains`
+ *   binding; no Cloudflare tunnel or DNS record is created for `hostname`.
+ */
+async function provisionPlatformIntegrations(action, context, deps) {
+    const { coolify } = deps;
+    const hostname = action.desired.hostname;
+    const gitRef = action.desired.gitRef;
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? defaultSleep;
+    const recorded = context.recordedIds();
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    // ---- project and environment: the one shared `platform` project ---------
+    let projectUuid = recorded[JOBS_PROJECT_SCOPE_KEY];
+    if (!projectUuid) {
+        const found = await coolify.findProjectByName(PLATFORM_COOLIFY_PROJECT_NAME);
+        projectUuid = found
+            ? found.uuid
+            : (await coolify.createProject(PLATFORM_COOLIFY_PROJECT_NAME)).uuid;
+        await record(JOBS_PROJECT_SCOPE_KEY, projectUuid);
+    }
+    const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+    // ---- database -------------------------------------------------------------
+    let dbId = recorded[INTEGRATIONS_DATABASE_SCOPE_KEY];
+    if (!dbId) {
+        const found = (await coolify.listDatabases()).find((db) => db.name === INTEGRATIONS_DB_NAME && db.environment_id === environment.id);
+        if (found) {
+            dbId = found.uuid;
+        }
+        else {
+            const server = await resolvePlatformServer(coolify);
+            const created = await coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name: INTEGRATIONS_DB_NAME,
+                postgres_db: INTEGRATIONS_POSTGRES_DB,
+                postgres_user: INTEGRATIONS_POSTGRES_DB,
+            });
+            dbId = created.uuid;
+        }
+        await record(INTEGRATIONS_DATABASE_SCOPE_KEY, dbId);
+    }
+    const db = await coolify.getDatabase(dbId);
+    if (!db.internal_db_url) {
+        throw new Error(`platform:integrations: database ${dbId} has no internal_db_url yet; not deploying the integrations host without a database`);
+    }
+    const ownerUrl = db.internal_db_url;
+    // ---- the three apps --------------------------------------------------------
+    const createApp = (name, domains) => async () => {
+        const server = await resolvePlatformServer(coolify);
+        const githubApp = await coolify.requireGithubApp();
+        return coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: INTEGRATIONS_REPO,
+            git_branch: gitRef,
+            build_pack: 'dockerfile',
+            name,
+            ...(domains ? { domains } : {}),
+        });
+    };
+    const migrateApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_MIGRATE_APP.name, environment, createApp(INTEGRATIONS_MIGRATE_APP.name));
+    await record(INTEGRATIONS_MIGRATE_APP_SCOPE_KEY, migrateApp.appId);
+    const runnerApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_RUNNER_APP.name, environment, createApp(INTEGRATIONS_RUNNER_APP.name, hostname));
+    await record(INTEGRATIONS_RUNNER_APP_SCOPE_KEY, runnerApp.appId);
+    const workerApp = await findOrCreatePlatformApp(coolify, INTEGRATIONS_WORKER_APP.name, environment, createApp(INTEGRATIONS_WORKER_APP.name));
+    await record(INTEGRATIONS_WORKER_APP_SCOPE_KEY, workerApp.appId);
+    // Set on every run, not only after a create: a throw right after a create
+    // must not leave an app building the Dockerfile's last stage for good. The
+    // branch and the runner's domain are set here too, so a changed `gitRef` or
+    // `hostname` reaches an app that already exists.
+    const configChanged = recorded[PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY] !== hostname ||
+        recorded[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY] !== gitRef;
+    await coolify.updateApplication(migrateApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_MIGRATE_APP.target,
+        git_branch: gitRef,
+    });
+    await coolify.updateApplication(runnerApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_RUNNER_APP.target,
+        ports_exposes: INTEGRATIONS_RUNNER_PORT,
+        git_branch: gitRef,
+        domains: hostname,
+    });
+    await coolify.updateApplication(workerApp.appId, {
+        dockerfile_target_build: INTEGRATIONS_WORKER_APP.target,
+        git_branch: gitRef,
+    });
+    // ---- env ---------------------------------------------------------------------
+    // One runtime URL for all three apps: the migrate job sets the role's
+    // password from it, and the runner and worker connect with it.
+    const runtimeUrl = await ensureIntegrationsRuntimeUrl(coolify, migrateApp.appId, ownerUrl);
+    const keys = INTEGRATIONS_KEYS_ENV_NAMES.map((key) => ({
+        key,
+        value: deps.keysEnv[key] ?? '',
+    }));
+    if (keys.some((k) => !k.value)) {
+        throw new Error('platform:integrations: the host supplies no value for the @wtfalch/keys settings; not deploying the integrations host');
+    }
+    const sharedEnvs = [
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        { key: 'APP_URL', value: `https://${hostname}` },
+        ...keys,
+    ];
+    const runnerEnvs = [
+        ...sharedEnvs,
+        ...(await envsIfAbsent(coolify, runnerApp.appId, [
+            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+        ])),
+    ];
+    const workerEnvs = [
+        ...sharedEnvs,
+        ...(await envsIfAbsent(coolify, workerApp.appId, [
+            { key: 'INTEGRATIONS_OPERATOR_TENANT_ID', value: INTEGRATIONS_OPERATOR_TENANT_ID },
+            { key: 'INTEGRATIONS_WORKER_BATCH', value: INTEGRATIONS_WORKER_BATCH },
+        ])),
+    ];
+    const migrateEnvs = [
+        { key: 'DATABASE_URL_OWNER', value: ownerUrl },
+        { key: 'DATABASE_URL', value: runtimeUrl },
+        ...keys.filter((k) => k.key === 'KEYS_WORKER_URL' || k.key === 'KEYS_CREDENTIAL'),
+    ];
+    const runnerEnvsChanged = await envsDiffer(coolify, runnerApp.appId, runnerEnvs);
+    const workerEnvsChanged = await envsDiffer(coolify, workerApp.appId, workerEnvs);
+    await coolify.bulkUpsertEnvs(migrateApp.appId, migrateEnvs);
+    await coolify.bulkUpsertEnvs(runnerApp.appId, runnerEnvs);
+    await coolify.bulkUpsertEnvs(workerApp.appId, workerEnvs);
+    // ---- migrate first, once per gitRef ---------------------------------------------
+    if (context.recordedIds()[INTEGRATIONS_MIGRATED_SCOPE_KEY] !== gitRef) {
+        // A running migrate app is stopped before the deploy is queued, so the old
+        // container's healthy status is never read as the new deployment's.
+        if (migrateApp.running)
+            await coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+        await coolify.deploy(migrateApp.appId);
+        await waitForIntegrationsMigration(coolify, migrateApp.appId, runtime, sleep);
+        // It idles after migrating rather than exiting (the Dockerfile's own
+        // comment), so it is stopped here; a person starts it again for
+        // maintenance commands.
+        await coolify.raw('POST', `/applications/${migrateApp.appId}/stop`);
+        await record(INTEGRATIONS_MIGRATED_SCOPE_KEY, gitRef);
+    }
+    // ---- the management key, once --------------------------------------------------
+    // The pair's id is recorded and persisted before the private half is
+    // delivered. The guard is recorded only after delivery and the write of the
+    // public half. A run that dies in between leaves the id without the guard:
+    // the planner then reports the key and mints nothing, so a second pair can
+    // never replace one the host may already hold.
+    let keyJustSet = false;
+    if (!context.recordedIds()[PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY]) {
+        if (context.recordedIds()[PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY]) {
+            throw new Error(`platform:integrations: management key ${INTEGRATIONS_MANAGEMENT_KEY_ID} was minted but not confirmed delivered and pinned; not minting another. Check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+            publicKeyEncoding: { type: 'spki', format: 'pem' },
+            privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        });
+        await record(PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, INTEGRATIONS_MANAGEMENT_KEY_ID);
+        const attempts = runtime.deliverAttempts ?? 3;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await deps.deliverSecret(INTEGRATIONS_MANAGEMENT_KEY_REF, privateKey);
+                break;
+            }
+            catch {
+                // Retried; the error is dropped in case it echoes the key.
+                if (attempt >= attempts) {
+                    throw new Error(`platform:integrations: management key ${INTEGRATIONS_MANAGEMENT_KEY_ID} was minted but could not be delivered after ${attempts} attempts`);
+                }
+                await sleep(1000 * attempt);
+            }
+        }
+        await coolify.bulkUpsertEnvs(runnerApp.appId, [
+            { key: 'MANAGEMENT_ISSUER', value: INTEGRATIONS_MANAGEMENT_ISSUER },
+            {
+                key: 'MANAGEMENT_PUBLIC_KEYS',
+                value: JSON.stringify({ [INTEGRATIONS_MANAGEMENT_KEY_ID]: publicKey }),
+            },
+        ]);
+        await record(PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, runnerApp.appId);
+        keyJustSet = true;
+    }
+    // ---- then the runner and the worker ------------------------------------------------
+    // Decided from the live state: an env change only reaches a container on its
+    // next deploy, and a stopped runner is deployed so an earlier failed deploy
+    // is retried. The worker exits after one pass by design, so "not running"
+    // says nothing about it and it is deployed only when created or changed.
+    if (runnerApp.justCreated ||
+        !runnerApp.running ||
+        runnerEnvsChanged ||
+        keyJustSet ||
+        configChanged) {
+        await coolify.deploy(runnerApp.appId);
+    }
+    if (workerApp.justCreated || workerEnvsChanged || configChanged) {
+        await coolify.deploy(workerApp.appId);
+    }
+    await record(PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, hostname);
+    await record(PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, gitRef);
+    return { resourceId: runnerApp.appId };
+}
+/**
+ * The runtime `DATABASE_URL` already on the migrate app, or a new one:
+ * {@link INTEGRATIONS_RUNTIME_ROLE} with a password minted once from a
+ * URL-safe alphabet (the host's `db-runtime-role.sh` refuses anything but
+ * `A-Za-z0-9_.~-`), on the owner URL's host, database and query string --
+ * `executor.ts`'s `ensureCmsRuntimeUrl`, with the same rule: never rotated,
+ * because the migrate job set the live role's password from the first one.
+ * A parse failure throws a fixed message, never the URL (Node's own
+ * `ERR_INVALID_URL` carries the whole input, password included).
+ */
+async function ensureIntegrationsRuntimeUrl(coolify, migrateAppId, ownerUrl) {
+    const existing = (await coolify.listEnvs(migrateAppId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview && e.value);
+    if (existing)
+        return existing.value;
+    let host;
+    let pathname;
+    let search;
+    try {
+        ({ host, pathname, search } = new URL(ownerUrl));
+    }
+    catch {
+        throw new Error('platform:integrations: the database internal_db_url could not be parsed; not deploying the integrations host');
+    }
+    const password = randomBytes(24).toString('base64url');
+    return `postgres://${INTEGRATIONS_RUNTIME_ROLE}:${password}@${host}${pathname}${search}`;
+}
+/** The entries of `desired` whose key the app does not have yet -- never overwriting a value a person set. */
+async function envsIfAbsent(coolify, appId, desired) {
+    const live = new Set((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => e.key));
+    return desired.filter((e) => !live.has(e.key));
+}
+/**
+ * Polls the migrate app until Coolify reports it `running:healthy` after
+ * first reporting anything else -- a healthy status before that is the old
+ * container, since the stop and deploy calls can return before Coolify's
+ * status catches up. Its `HEALTHCHECK` passes only after
+ * `integrations-migrate: done` (see
+ * {@link provisionPlatformIntegrations}'s known gaps). Throws once
+ * `migrateTimeoutMs` has passed. The runner and worker are never deployed
+ * after a timeout.
+ */
+async function waitForIntegrationsMigration(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.migrateTimeoutMs ?? 20 * 60_000;
+    const interval = runtime.migratePollMs ?? 10_000;
+    const deadline = now() + timeout;
+    let left = false;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        const healthy = status?.startsWith('running:healthy') === true;
+        if (healthy && left)
+            return;
+        if (!healthy)
+            left = true;
+        if (now() >= deadline) {
+            throw new Error(`platform:integrations: integrations-migrate (${appId}) did not report healthy within ${Math.round(timeout / 1000)}s (last status: ${status ?? 'unknown'}); check its logs, then apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * The real {@link PlatformCloudflareReader}: the platform's apex zone as
+ * `planApexZone` expects to see it, and nothing else. The zone's DNS records
+ * and tunnels belong to no declared platform step yet, so listing them would
+ * only report them unmanaged.
+ *
+ * The zone is fetched by the id the last apply recorded when there is one,
+ * because Cloudflare's zone list can lag a create; with no recorded id it is
+ * found by apex.
+ */
+export class ProvidersPlatformCloudflareReader {
+    client;
+    platformStore;
+    constructor(client, platformStore) {
+        this.client = client;
+        this.platformStore = platformStore;
+    }
+    async listResources() {
+        const platform = await this.platformStore.get();
+        if (!platform)
+            return [];
+        const recordedId = (await this.platformStore.getServiceIds())[apexZoneKey(platform.apex)];
+        const zone = (recordedId && (await recordedZone(this.client, recordedId, platform.apex))) ||
+            (await exactZone(this.client, platform.apex));
+        if (!zone)
+            return [];
+        return [
+            {
+                system: 'cloudflare',
+                kind: 'zone',
+                key: platform.apex,
+                config: { id: zone.id, status: zone.status, name_servers: zone.name_servers },
+            },
+        ];
+    }
+}
+/**
+ * #173: the real {@link PlatformCoolifyReader} for the jobs scheduler app --
+ * the recorded-id half of `ProvidersPlatformCloudflareReader`'s own strategy
+ * above, with no list-by-name fallback: unlike a Cloudflare zone (which
+ * exists before foundry ever touches it), the scheduler app has no identity
+ * to adopt until this package creates it, so "nothing recorded yet" and
+ * "nothing live yet" are the same state here. A recorded id Coolify no
+ * longer has (deleted, or moved) reads as not-live, the same "stale id never
+ * blocks planning for good" rule {@link recordedZone} follows.
+ */
+export class ProvidersPlatformCoolifyReader {
+    client;
+    platformStore;
+    constructor(client, platformStore) {
+        this.client = client;
+        this.platformStore = platformStore;
+    }
+    async listResources() {
+        const recordedId = (await this.platformStore.getServiceIds())[JOBS_APP_KEY];
+        if (!recordedId)
+            return [];
+        try {
+            const app = await this.client.getApplication(recordedId);
+            return [
+                {
+                    system: 'coolify',
+                    kind: 'jobs',
+                    key: JOBS_SCHEDULER_KEY,
+                    config: { uuid: app.uuid, status: app.status },
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/**
+ * `findZoneByApex` returns the longest suffix match, so for a subdomain it
+ * answers with the parent zone. The platform's zone is its apex exactly;
+ * any other zone is never adopted or reported as the platform's.
+ */
+async function exactZone(client, apex) {
+    const zone = await client.findZoneByApex(apex);
+    return zone && zone.name === apex ? zone : undefined;
+}
+/**
+ * The zone the last apply recorded, or `undefined` when Cloudflare no longer
+ * has it under that id (deleted, or moved to another account) or it is no
+ * longer the apex. The caller then falls back to finding it by apex, so a
+ * stale recorded id never blocks planning for good.
+ */
+async function recordedZone(client, id, apex) {
+    try {
+        const zone = await client.getZone(id);
+        return zone.name === apex ? zone : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What Archon needs from each service before its step may run: the service's
+ * own applied step (`coolify:app:<stepKey>`), scope ids its step recorded, and
+ * held keys its step delivered. A missing one blocks Archon's plan. Archon
+ * only reads these; it never mints them.
+ */
+const ARCHON_SERVICE_INPUTS = {
+    files: {
+        stepKey: PLATFORM_FILES_KEY,
+        scopeKeys: [PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY],
+        refs: [FILES_MANAGEMENT_KEY_REF, FILES_INTROSPECTION_SECRET_REF],
+    },
+    ai: {
+        stepKey: PLATFORM_AI_KEY,
+        scopeKeys: [
+            PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY,
+            PLATFORM_AI_ORGANISATION_SCOPE_KEY,
+            PLATFORM_AI_INTERNAL_URL_SCOPE_KEY,
+        ],
+        refs: [PLATFORM_AI_MANAGEMENT_KEY_REF],
+    },
+    integrations: {
+        stepKey: PLATFORM_INTEGRATIONS_KEY,
+        scopeKeys: [],
+        refs: [INTEGRATIONS_MANAGEMENT_KEY_REF],
+    },
+};