@wtfalch/foundry 0.45.1 → 0.46.0

package/dist/plan/org-postgres.js

@@ -0,0 +1,293 @@
+import { randomBytes } from 'node:crypto';
+import { ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, orgServiceDatabase, } from '../org.js';
+import { JobFailure, waitForJob } from './job-app.js';
+import { ORG_POSTGRES_JOB_ADMIN_ENV, jobCreatesRuntimeRole, orgPostgresPasswordEnv, orgPostgresProvisionDockerfile, orgPostgresRuntimePasswordEnv, } from './org-postgres-job.js';
+import { boundedCall, withCallTimeout } from './signin-db.js';
+/** Recorded once a live company's data for `home` is copied to the org's server (#444). */
+export const orgPostgresMigratedScopeKey = (home) => `org_postgres_migrated.${home}`;
+/** Whether `home` still has a legacy Coolify database that has not been moved to the server. */
+export function legacyUnmigrated(org, home, recordedIds) {
+    const legacy = home.legacyKey(org);
+    return (legacy !== null &&
+        Boolean(recordedIds[legacy]) &&
+        !recordedIds[orgPostgresMigratedScopeKey(home.schema)]);
+}
+/**
+ * Pure. Where a consumer finds its database, from recorded ids alone: on the
+ * server once the home is recorded and either it never had a legacy database
+ * or its migration is recorded. A live company stays on its Coolify database
+ * until then.
+ */
+export function serviceOnServer(org, home, recordedIds) {
+    return Boolean(recordedIds[home.scopeKey]) && !legacyUnmigrated(org, home, recordedIds);
+}
+/** Pure. The home's endpoint on the server whose Coolify `internal_db_url` is given; null when that URL has no host. */
+export function serviceEndpoint(org, home, serverInternalUrl) {
+    if (!URL.canParse(serverInternalUrl))
+        return null;
+    const url = new URL(serverInternalUrl);
+    if (!url.hostname)
+        return null;
+    const names = orgServiceDatabase(org, home);
+    return {
+        host: url.hostname,
+        port: url.port || '5432',
+        database: names.database,
+        ownerUser: names.ownerRole,
+        runtimeUser: names.runtimeRole,
+    };
+}
+/** Pure. The owner URL, and the runtime URL when a runtime password is given. */
+export function serviceUrls(endpoint, ownerPassword, runtimePassword) {
+    const build = (user, password) => `postgres://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${endpoint.host}:${endpoint.port}/${endpoint.database}`;
+    return {
+        owner: build(endpoint.ownerUser, ownerPassword),
+        runtime: runtimePassword === null ? null : build(endpoint.runtimeUser, runtimePassword),
+    };
+}
+// Restore path: roles are not in a Coolify dump. Re-run the provisioning job (idempotent; it is
+// given a password only for a home not recorded), then `pg_restore` each dump with
+// `--no-owner --no-acl --role=<owner>`. Template apps create `<db>_rt` again on first boot.
+/** The server's name in Coolify. */
+export const orgPostgresServerName = (org) => `${org.slug}-postgres`;
+/** The job app's name in Coolify. */
+export const orgPostgresJobName = (org) => `${org.slug}-postgres-job`;
+/** The job app's id while it exists. */
+export const ORG_POSTGRES_JOB_APP_SCOPE_KEY = 'org_postgres_job_app';
+/** An opaque id, set between a password's mint and its delivery. Never the password. */
+export const orgPostgresUndeliveredScopeKey = (home) => `org_postgres_undelivered.${home}`;
+/** Where the host holds a home's password, once delivered. */
+export const orgPostgresSecretRef = (org, home, role) => `org-postgres:${org.slug}:${home}:${role}`;
+/** How many times each password is handed to `deliverSecret`. */
+export const ORG_POSTGRES_DELIVERY_ATTEMPTS = 3;
+/**
+ * The two steps that make the company's Postgres server and its databases true, from recorded ids
+ * alone: the server while it is not recorded, the databases of every enabled home that is not. The
+ * databases step needs no precondition beyond the server step before it in the same plan.
+ */
+export function planOrgPostgresSteps(org, plan) {
+    const steps = [];
+    if (plan.serverMissing) {
+        steps.push({
+            action: { system: 'coolify', kind: 'org-postgres', key: org.id, desired: {} },
+            step: {
+                description: `create ${org.slug}'s one Postgres server (${orgPostgresServerName(org)})`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    if (plan.missingSchemas.length > 0) {
+        const homes = plan.missingSchemas.map((home) => home.schema);
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'org-postgres-databases',
+                key: org.id,
+                desired: { homes },
+            },
+            step: {
+                description: `create ${org.slug}'s databases and roles on its Postgres server: ${homes.join(', ')}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return steps;
+}
+const mint = () => randomBytes(24).toString('base64url');
+const mintOpaque = () => randomBytes(12).toString('hex');
+/** Creates the company's Postgres server once and starts it. Returns the Coolify uuid. */
+export async function provisionOrgPostgresServer(scope, deps, org) {
+    const coolify = withCallTimeout(deps.coolify);
+    let id = scope.recordedIds()[ORG_POSTGRES_SERVER_SCOPE_KEY];
+    if (!id) {
+        const projectUuid = await deps.ensureProject();
+        const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = orgPostgresServerName(org);
+        const found = (await coolify.listDatabases()).find((db) => db.name === name && db.environment_id === environment.id);
+        if (found) {
+            id = found.uuid;
+        }
+        else {
+            const created = await coolify.createPostgresDatabase({
+                project_uuid: projectUuid,
+                server_uuid: await deps.serverUuid(),
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                name,
+                postgres_db: 'postgres',
+                postgres_user: 'postgres',
+            });
+            id = created.uuid;
+        }
+        // Recorded before it is started: a crash after the create must not make a second container.
+        scope.recordScopeId(ORG_POSTGRES_SERVER_SCOPE_KEY, id);
+        await scope.persist();
+    }
+    await boundedCall(deps.startDatabase(id), 'Coolify startDatabase');
+    return { resourceId: id };
+}
+/**
+ * Creates the databases and roles of the homes in `homeKeys` that are not recorded, with one job app
+ * for all of them, then hands each owner password to the host and records the home.
+ *
+ * One mint (CLAUDE.md platform rule 1): each home's password is minted once per attempt, an opaque id
+ * is recorded under `org_postgres_undelivered.<home>` and persisted before the job runs, and the home
+ * is recorded only after the password is delivered. A run that dies between the two finds the id,
+ * and mints again: no consumer has read the old password, and the job sets the new one.
+ */
+export async function provisionOrgPostgresDatabases(scope, deps, org, homeKeys) {
+    const label = `${org.slug}'s Postgres databases`;
+    const coolify = withCallTimeout(deps.coolify);
+    const recorded = scope.recordedIds();
+    const serverId = recorded[ORG_POSTGRES_SERVER_SCOPE_KEY];
+    if (!serverId)
+        throw new Error(`${label}: the Postgres server is not recorded yet`);
+    const homes = ORG_SERVICE_SCHEMAS.filter((home) => homeKeys.includes(home.schema) && !recorded[home.scopeKey]);
+    if (homes.length === 0)
+        return;
+    const databases = homes.map((home) => orgServiceDatabase(org, home));
+    const onSecret = (value) => deps.onSecret?.(value);
+    const server = await boundedCall(deps.startDatabase(serverId), 'Coolify startDatabase');
+    if (!server.internal_db_url)
+        throw new Error(`${label}: the Postgres server has no internal URL`);
+    const adminUrl = server.internal_db_url;
+    onSecret(adminUrl);
+    if (URL.canParse(adminUrl)) {
+        const password = decodeURIComponent(new URL(adminUrl).password);
+        if (password)
+            onSecret(password);
+    }
+    const mintPassword = deps.mintPassword ?? mint;
+    const passwords = new Map();
+    for (const home of databases) {
+        const owner = mintPassword();
+        const runtime = jobCreatesRuntimeRole(home) ? mintPassword() : null;
+        onSecret(owner);
+        if (runtime)
+            onSecret(runtime);
+        passwords.set(home.schema, { owner, runtime });
+        scope.recordScopeId(orgPostgresUndeliveredScopeKey(home.schema), (deps.mintId ?? mintOpaque)());
+    }
+    await scope.persist();
+    await runJob(scope, deps, org, label, coolify, databases, adminUrl, passwords);
+    const failed = [];
+    for (const home of databases) {
+        const held = passwords.get(home.schema);
+        if (!held)
+            continue;
+        try {
+            await deliver(deps, orgPostgresSecretRef(org, home.schema, 'owner'), held.owner);
+            if (held.runtime) {
+                await deliver(deps, orgPostgresSecretRef(org, home.schema, 'runtime'), held.runtime);
+            }
+        }
+        catch {
+            failed.push(home.schema);
+            continue;
+        }
+        scope.recordScopeId(`org_postgres_schema.${home.schema}`, home.database);
+        scope.recordScopeId(orgPostgresUndeliveredScopeKey(home.schema), '');
+        await scope.persist();
+    }
+    if (failed.length > 0) {
+        throw new Error(`${label}: the passwords for ${failed.join(', ')} were set but could not be delivered after ${ORG_POSTGRES_DELIVERY_ATTEMPTS} attempts; the next apply sets and delivers new ones`);
+    }
+}
+async function deliver(deps, ref, secret) {
+    for (let attempt = 1; attempt <= ORG_POSTGRES_DELIVERY_ATTEMPTS; attempt += 1) {
+        try {
+            await boundedCall(deps.deliverSecret(ref, secret), 'deliverSecret');
+            return;
+        }
+        catch {
+            // The cause may carry the secret; nothing of it is kept.
+        }
+    }
+    throw new Error('delivery failed');
+}
+async function runJob(scope, deps, org, label, coolify, databases, adminUrl, passwords) {
+    const jobName = orgPostgresJobName(org);
+    let jobAppId;
+    try {
+        const projectUuid = await deps.ensureProject();
+        const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+        // A job left by an earlier run holds an old script and old passwords: it is replaced, never reused.
+        const leftover = await coolify.findApplicationByName(jobName, {
+            environmentIds: [environment.id],
+        });
+        if (leftover)
+            await coolify.raw('DELETE', `/applications/${leftover.uuid}`);
+        const created = await coolify.createDockerfileApplication({
+            project_uuid: projectUuid,
+            server_uuid: await deps.serverUuid(),
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: orgPostgresProvisionDockerfile(databases),
+            name: jobName,
+            description: `${org.slug}'s Postgres databases job`,
+            instant_deploy: false,
+            autogenerate_domain: false,
+        });
+        jobAppId = created.uuid;
+        scope.recordScopeId(ORG_POSTGRES_JOB_APP_SCOPE_KEY, jobAppId);
+        await scope.persist();
+        await coolify.updateApplication(jobAppId, { health_check_enabled: false });
+        await coolify.bulkUpsertEnvs(jobAppId, [
+            { key: ORG_POSTGRES_JOB_ADMIN_ENV, value: adminUrl },
+            ...databases.flatMap((home) => {
+                const held = passwords.get(home.schema);
+                if (!held)
+                    return [];
+                return [
+                    { key: orgPostgresPasswordEnv(home.schema), value: held.owner },
+                    ...(held.runtime
+                        ? [{ key: orgPostgresRuntimePasswordEnv(home.schema), value: held.runtime }]
+                        : []),
+                ];
+            }),
+        ]);
+        await coolify.deploy(jobAppId, true);
+        await waitForJob(coolify, jobAppId, deps.runtime ?? {}, {
+            job: 'the Postgres job',
+            stopped: 'the Postgres job stopped before it finished',
+        });
+    }
+    catch (error) {
+        const why = error instanceof JobFailure ? error.message : 'a Coolify call failed or timed out';
+        // The failed job app must not keep running with the admin URL and passwords in its env.
+        let cleaned = '';
+        if (jobAppId) {
+            const id = jobAppId;
+            const blank = [
+                ORG_POSTGRES_JOB_ADMIN_ENV,
+                ...databases.flatMap((home) => [
+                    orgPostgresPasswordEnv(home.schema),
+                    orgPostgresRuntimePasswordEnv(home.schema),
+                ]),
+            ].map((key) => ({ key, value: '' }));
+            try {
+                await boundedCall(coolify.raw('POST', `/applications/${id}/stop`), 'stop the job');
+            }
+            catch {
+                cleaned += '; the job app could not be stopped, stop it in Coolify';
+            }
+            try {
+                await boundedCall(coolify.bulkUpsertEnvs(id, blank), 'clear the job env');
+            }
+            catch {
+                cleaned +=
+                    '; its env could not be cleared, delete the app in Coolify (it holds the admin URL)';
+            }
+        }
+        throw new Error(`${label}: ${why}${jobAppId ? `; the job app ${jobAppId} is left stopped without secrets for inspection and the next apply replaces it${cleaned}` : ''}; apply again`);
+    }
+    try {
+        await coolify.raw('DELETE', `/applications/${jobAppId}`);
+    }
+    catch {
+        throw new Error(`${label}: the job ran, but its app ${jobAppId} could not be deleted; delete it in Coolify (it holds the admin URL), then apply again`);
+    }
+    scope.recordScopeId(ORG_POSTGRES_JOB_APP_SCOPE_KEY, '');
+}

package/dist/plan/plan-apply.d.ts

@@ -14,6 +14,7 @@ import { type UnconfirmedUpgrade } from './confirm-upgrade.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
 import { type LoginHostDiscoveryPort } from './login-host.js';
+import { type OrgPostgresMigrationConfirmation } from './org-postgres-migrate.js';
 import { type EdgePortName, type HeldKeyResolver, type PlatformOwnerInput } from './platform-org.js';
 import type { CallsSfuConnectionPort } from './platform-sfu.js';
 import { type ReleaseContext, type ReleaseHost } from './release-host.js';
@@ -62,9 +63,9 @@ export interface AuditLog {
     recordAdoption(entry: {
         actor: AuditActor;
         orgId: OrgId;
-        action: 'adopt' | 'release';
+        action: 'adopt' | 'release' | 'confirm-org-postgres-migration';
         entryKey: string;
-        outcome: 'adopted' | 'released' | 'refused';
+        outcome: 'adopted' | 'released' | 'refused' | 'recorded';
         reason?: string;
         at: Date;
     }): Promise<void>;
@@ -281,6 +282,8 @@ export interface PlatformStepExecutionContext {
 export interface PlatformDriftedSteps {
     archon?: boolean;
     auth?: boolean;
+    /** #643: a recorded sign-in app (ZITADEL, login or broker) is gone from Coolify or not running. */
+    authApps?: boolean;
     /** The host sets it. */
     edge?: boolean;
     /** #380 */
@@ -466,6 +469,12 @@ export interface FoundryPlanApplyOptions {
      * before zitadel-login's binding can be written.
      */
     loginHostBindings?: boolean;
+    /**
+     * True when the host's `loginHostBindings` port writes the `clientOrganizations` map
+     * (`upsertClientOrganizations` and `deleteClientOrganizations`). Absent or false: the plan says in one
+     * fixed line that the shared login does not check customers clients' organisation.
+     */
+    loginHostClientOrganizations?: boolean;
     /**
      * Reads `GET https://<login host>/.well-known/openid-configuration` for a
      * company's login host (5 s limit). Optional, and without it every company's
@@ -481,6 +490,15 @@ export interface FoundryPlanApplyOptions {
      * token of its existing sign-in apps.
      */
     zitadelIdTokenUserinfo?: boolean;
+    /** True when the host's ZITADEL client has `updateOidcAppPostLogoutRedirectUris`; without it no org plans the post-logout address update. */
+    zitadelPostLogoutUris?: boolean;
+    /**
+     * True when the host's ZITADEL client has `getOidcAppRedirectUris` and
+     * `updateOidcAppRedirectUris` (`@wtfalch/providers` 0.12.0). Optional, and
+     * false without them: no org plans the step that registers the desktop
+     * sign-in callback on its existing sign-in apps.
+     */
+    zitadelRedirectUris?: boolean;
     /**
      * Auth ADR 0002: true when the host's ZITADEL client has `ensureOidcAppMcpAccess`
      * and `ensureAccessTokenLifetime` (`@wtfalch/providers` 0.11.0). Without it every
@@ -644,8 +662,11 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly agora;
     private readonly jobsScheduler;
     private readonly loginHostBindings;
+    private readonly loginHostClientOrganizations;
     private readonly loginHostDiscovery;
     private readonly zitadelIdTokenUserinfo;
+    private readonly zitadelPostLogoutUris;
+    private readonly zitadelRedirectUris;
     private readonly zitadelMcp;
     private readonly zitadelOrgMetadata;
     private readonly broker;
@@ -706,6 +727,13 @@ export declare class FoundryPlanApply implements PlanApply {
      * {@link apply}. Every path writes an audit row.
      */
     release(id: OrgId, entryKey: string): Promise<AppliedState>;
+    /**
+     * Records that the staging copy of a live company's data was checked, which is the only thing that lets
+     * the org Postgres migration step run (#444). It is its own call, never part of an apply. Needs the
+     * platform permission. It stores the staging copy id, who confirmed and when, and writes an audit row.
+     * Throws {@link InvalidMigrationConfirmationError} for a confirmation that is not valid.
+     */
+    confirmOrgPostgresMigration(orgId: OrgId, confirmation: OrgPostgresMigrationConfirmation): Promise<void>;
     private computeAdopt;
     apply(plan: Plan, confirmedOrgName: string, options?: FoundryApplyOptions): Promise<AppliedState>;
     /**

package/dist/plan/plan-apply.js

@@ -1,15 +1,16 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { sfuSlotPorts } from '../calls-sfu.js';
-import { heldEnvRef, ownsServices, validateHosting } from '../org.js';
+import { ORG_SERVICE_SCHEMAS, heldEnvRef, ownsServices, validateHosting } from '../org.js';
 import { PLATFORM_SERVICE_KEYS } from '../platform.js';
 import { AlreadyRunningError, StepFailedError } from '../runner/errors.js';
 import { StaleLeaseError, } from '../store.js';
 import { AdoptRefusedError, adoptCandidates, adoptedKeysUnreadable, adoptedScopeKey, parseAdoptSnapshot, planAdoptFrom, } from './adopt.js';
 import { NO_AGORA_HOST_VALUES, readAgoraHost, } from './agora.js';
-import { NetworkMoveBackupMissingError, SigninDbMoveBackupMissingError, UpgradeBackupMissingError, platformDatabasesForService, requireFreshBackupForSigninMove, requireFreshBackupsForMove, requireFreshBackupsForUpgrades, } from './backup-gate.js';
+import { NetworkMoveBackupMissingError, OrgPostgresMigrationBackupMissingError, SigninDbMoveBackupMissingError, UpgradeBackupMissingError, platformDatabasesForService, requireFreshBackupForOrgPostgresMigration, requireFreshBackupForSigninMove, requireFreshBackupsForMove, requireFreshBackupsForUpgrades, } from './backup-gate.js';
 import { ARCHON_REPO, PRIMARY_SERVER_SCOPE_KEY, archonSubject, entrySubject, } from './blue-green.js';
 import { readLiveBuilds } from './build-record.js';
+import { LEGACY_BACKUP_NAMES } from './company-backups.js';
 import { unconfirmedUpgrades } from './confirm-upgrade.js';
 import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
 import { entryAiUndeliveredScopeKey } from './entry-ai-key.js';
@@ -20,6 +21,7 @@ import { hostingNames } from './locked-hostnames.js';
 import { agoraIssuerHostFor, loginHostServesAgora, readLoginHostDiscovery, } from './login-host.js';
 import { OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY, OWN_MAIL_SMTP_PORT_BASE, OWN_MAIL_SMTP_PORT_MAX, OWN_MAIL_SMTP_PORT_SCOPE_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, isOwnMailSmtpPort, mailRelayFingerprint, } from './mail-relay.js';
 import { findNameClashes, nameClashMessage } from './org-names.js';
+import { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationNotConfirmedError, invalidMigrationConfirmation, migrateHomeOf, parseMigrationConfirmation, } from './org-postgres-migrate.js';
 import { ownHostnames } from './own-hostnames.js';
 import { OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, orgTarget } from './own-services.js';
 import { PLATFORM_ARCHON_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_KEY, appStepKey, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
@@ -159,8 +161,11 @@ export class FoundryPlanApply {
     agora;
     jobsScheduler;
     loginHostBindings;
+    loginHostClientOrganizations;
     loginHostDiscovery;
     zitadelIdTokenUserinfo;
+    zitadelPostLogoutUris;
+    zitadelRedirectUris;
     zitadelMcp;
     zitadelOrgMetadata;
     broker;
@@ -194,8 +199,11 @@ export class FoundryPlanApply {
         this.agora = options.agora;
         this.jobsScheduler = options.jobsScheduler ?? false;
         this.loginHostBindings = options.loginHostBindings ?? false;
+        this.loginHostClientOrganizations = options.loginHostClientOrganizations ?? false;
         this.loginHostDiscovery = options.loginHostDiscovery;
         this.zitadelIdTokenUserinfo = options.zitadelIdTokenUserinfo ?? false;
+        this.zitadelPostLogoutUris = options.zitadelPostLogoutUris ?? false;
+        this.zitadelRedirectUris = options.zitadelRedirectUris ?? false;
         this.zitadelMcp = options.zitadelMcp ?? false;
         this.zitadelOrgMetadata = options.zitadelOrgMetadata ?? false;
         this.broker = options.broker ?? false;
@@ -379,6 +387,55 @@ export class FoundryPlanApply {
             return released;
         }));
     }
+    /**
+     * Records that the staging copy of a live company's data was checked, which is the only thing that lets
+     * the org Postgres migration step run (#444). It is its own call, never part of an apply. Needs the
+     * platform permission. It stores the staging copy id, who confirmed and when, and writes an audit row.
+     * Throws {@link InvalidMigrationConfirmationError} for a confirmation that is not valid.
+     */
+    async confirmOrgPostgresMigration(orgId, confirmation) {
+        const record = (outcome, reason) => this.audit.recordAdoption({
+            actor: this.actor,
+            orgId,
+            action: 'confirm-org-postgres-migration',
+            entryKey: 'org_postgres_migration',
+            outcome,
+            ...(reason === undefined ? {} : { reason }),
+            at: this.now(),
+        });
+        if ((await this.authz.canApplyPlatform?.(this.actor)) !== true) {
+            await record('refused', 'not authorized');
+            throw new NotAuthorizedError(this.actor, orgId);
+        }
+        const invalid = invalidMigrationConfirmation(confirmation);
+        if (invalid) {
+            await record('refused', invalid);
+            throw new InvalidMigrationConfirmationError(invalid);
+        }
+        const value = {
+            stagingCopy: confirmation.stagingCopy,
+            confirmedBy: confirmation.confirmedBy,
+            confirmedAt: confirmation.confirmedAt,
+        };
+        await this.withMutationLease(companyScope(orgId), (reason) => record('refused', reason), (fence) => this.withRunnerSerialization(orgId, (reason) => record('refused', reason), async () => {
+            if (!(await this.store.get(orgId))) {
+                await record('refused', `no declared org ${orgId}`);
+                throw new DeclaredOrgNotFoundError(orgId);
+            }
+            const previous = await this.store.getAppliedState(orgId);
+            await this.store.putAppliedState({
+                orgId,
+                serviceIds: {
+                    ...(previous?.serviceIds ?? {}),
+                    [ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY]: JSON.stringify(value),
+                },
+                checkpoints: previous?.checkpoints ?? [],
+                failedFields: previous?.failedFields ?? [],
+                lastApplied: previous?.lastApplied ?? null,
+            }, fence);
+            await record('recorded');
+        }));
+    }
     async computeAdopt(id, input) {
         const org = await this.store.get(id);
         if (!org)
@@ -485,6 +542,40 @@ export class FoundryPlanApply {
                     throw e;
                 }
             }
+            // A migration to the company's Postgres server needs the recorded staging confirmation and a fresh dump
+            // of the old database. Both are checked before the first port call.
+            const migrations = detail.plannedSteps.filter((s) => s.action.system === 'coolify' && s.action.kind === 'org-postgres-migrate');
+            if (migrations.length > 0) {
+                const ids = (await this.store.getAppliedState(orgId))?.serviceIds ?? {};
+                if (!parseMigrationConfirmation(ids[ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY])) {
+                    await this.refuse(plan, 'org postgres migration without a recorded staging confirmation');
+                    throw new OrgPostgresMigrationNotConfirmedError();
+                }
+                try {
+                    for (const migration of migrations) {
+                        const home = ORG_SERVICE_SCHEMAS.find((h) => h.schema === migrateHomeOf(migration.action));
+                        const legacyKey = home?.legacyKey(org);
+                        const backupName = home ? LEGACY_BACKUP_NAMES[home.schema] : undefined;
+                        if (!this.backupGate)
+                            throw new OrgPostgresMigrationBackupMissingError('no-gate');
+                        if (!legacyKey || !backupName) {
+                            throw new OrgPostgresMigrationBackupMissingError('no-backup');
+                        }
+                        await requireFreshBackupForOrgPostgresMigration({
+                            coolify: this.backupGate.coolify,
+                            orgId,
+                            recordedIds: ids,
+                            now: () => this.now().getTime(),
+                        }, legacyKey, backupName);
+                    }
+                }
+                catch (e) {
+                    if (e instanceof OrgPostgresMigrationBackupMissingError) {
+                        await this.refuse(plan, 'org postgres migration without a fresh backup');
+                    }
+                    throw e;
+                }
+            }
             if (planNeedsConfirmation(plan.steps) &&
                 confirmedOrgName.trim() !== org.displayName.trim()) {
                 await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
@@ -1219,8 +1310,11 @@ export class FoundryPlanApply {
             : undefined;
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
             loginHostBindings: this.loginHostBindings,
+            loginHostClientOrganizations: this.loginHostClientOrganizations,
             loginHostServesDiscovery,
             zitadelIdTokenUserinfo: this.zitadelIdTokenUserinfo,
+            zitadelPostLogoutUris: this.zitadelPostLogoutUris,
+            zitadelRedirectUris: this.zitadelRedirectUris,
             zitadelMcp: this.zitadelMcp,
             zitadelOrgMetadata: this.zitadelOrgMetadata,
             broker: ownsServices(org) && this.hostOwnServices && this.executor.ownBrokerPort
@@ -1356,14 +1450,16 @@ export class FoundryPlanApply {
             ...(await this.sharedPlatformReadiness()),
             heldEnv: await this.heldEnvReadiness(org),
         };
-        if (!ownsServices(org))
-            return base;
-        const held = this.platformDeps?.heldKeys;
         const platform = await this.platformDeps?.store.get();
-        const readiness = orgPlatformReadinessFor(org, base, orgRecordedIds, held ? await heldOwnKeyRefs(held, org) : new Set());
-        return platform
+        // The auth release gates the shared-host organisation check and the cookie domain of every company.
+        const withRefs = (readiness) => platform
             ? { ...readiness, serviceGitRefs: serviceGitRefsOf(platform, org.versionPin) }
             : readiness;
+        if (!ownsServices(org))
+            return withRefs(base);
+        const held = this.platformDeps?.heldKeys;
+        const readiness = orgPlatformReadinessFor(org, base, orgRecordedIds, held ? await heldOwnKeyRefs(held, org) : new Set());
+        return withRefs(readiness);
     }
     /**
      * The org's `heldSecret` envs: the refs that hold a value now, which of those differ from the live
@@ -2022,6 +2118,7 @@ const STEP_FIELDS = {
     'zitadel:owner': 'owners',
     'zitadel:customers': 'hosting.entries.uses.auth',
     'zitadel:id-token-userinfo': 'hosting.entries.uses.auth',
+    'zitadel:desktop-callback': 'hosting.entries.uses.auth',
     'zitadel:mcp-project': 'hosting.entries.uses.auth.mcp',
     'zitadel:mcp-access': 'hosting.entries.uses.auth.mcp',
     'zitadel:access-token-lifetime': 'hosting.entries.uses.auth.mcp',

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

@@ -60,6 +60,12 @@ export declare const PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY = "auth_z
 export declare const AUTH_ZITADEL_RUN_OPTIONS = "--entrypoint \"/app/zitadel start-from-init --masterkeyFromEnv --tlsMode external\"";
 /** The run options last applied to the ZITADEL app (value: the options string), so a changed value forces one redeploy. */
 export declare const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = "zitadel_platform_auth_run_options_applied";
+/**
+ * The `gitRef` the platform's login, in-app login and broker apps were last built from (value: the ref). A
+ * different declared ref plans the auth step again: it patches `git_branch` on those three apps and
+ * redeploys them, so a release tag named in the declaration reaches the running login.
+ */
+export declare const PLATFORM_AUTH_APPLIED_GIT_REF_SCOPE_KEY = "platform_auth_applied_git_ref";
 /**
  * #251: the Synapse/MAS image tags an org's calls Matrix stack last
  * successful apply actually set live. `coolifyCalls` (`executor.ts`)
@@ -611,6 +617,31 @@ export declare const PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY = "zitadel_platform_a
  * repair while this differs from the recorded client app id.
  */
 export declare const PLATFORM_ARCHON_ID_TOKEN_USERINFO_APPLIED_SCOPE_KEY = "archon_id_token_userinfo_applied";
+/**
+ * The marker for Archon's sign-in client once its post-logout addresses were
+ * set: the client's ZITADEL app id and the set it holds
+ * (`postLogoutAppliedValue`). `planArchonPostLogoutUris` plans the update
+ * while this differs from what the declared hostname wants.
+ */
+export declare const PLATFORM_ARCHON_POST_LOGOUT_APPLIED_SCOPE_KEY = "archon_post_logout_applied";
+/**
+ * #394 (decision D2, release one): the role key on the platform's `mail`
+ * ZITADEL project that every mailbox user holds once the project's role check
+ * is on. This release only makes the role and grants it; the check stays off.
+ */
+export declare const PLATFORM_MAIL_USER_ROLE = "mail:use";
+/** The mail project id once {@link PLATFORM_MAIL_USER_ROLE} exists on it. */
+export declare const PLATFORM_MAIL_ROLE_ENSURED_SCOPE_KEY = "zitadel_platform_mail_role";
+/** `<mail project id>|<owner user id, or none>` once the owner holds the role. */
+export declare const PLATFORM_MAIL_ROLE_GRANTED_SCOPE_KEY = "zitadel_platform_mail_role_granted";
+/** The mail project id once its role check and has-project check are on (release two, behind an option). */
+export declare const PLATFORM_MAIL_ROLE_CHECK_SCOPE_KEY = "zitadel_platform_mail_role_check";
+/**
+ * The ZITADEL app id of Archon's sign-in client once `/auth/desktop/callback`
+ * was registered on it (#339). `planArchonDesktopCallback` plans the step
+ * while this differs from the recorded client app id.
+ */
+export declare const PLATFORM_ARCHON_DESKTOP_CALLBACK_APPLIED_SCOPE_KEY = "archon_desktop_callback_applied";
 /**
  * The settings `coolifyApp` owns on an entry's app (`folder`, `port`,
  * `autoDeploy`) as the JSON the marker below holds. `coolifyApp` records it
@@ -1225,6 +1256,18 @@ export interface PlanPlatformOptions {
          * repair step is not planned.
          */
         archonIdTokenUserinfo?: boolean;
+        /** The owner company's ZITADEL client has `updateOidcAppPostLogoutRedirectUris`. */
+        archonPostLogoutUris?: boolean;
+        /**
+         * The Archon sign-in client's ZITADEL client has `getOidcAppRedirectUris`
+         * and `updateOidcAppRedirectUris`. Not a block: without them the desktop
+         * callback step is not planned.
+         */
+        archonDesktopCallback?: boolean;
+        /** The mail step's ZITADEL client can make a project role and grant it. Not a block: without it no mail role step is planned. */
+        mailRole?: boolean;
+        /** The host asked for the mail project's role check (release two) and its client has `setProjectRoleChecks`. */
+        mailRoleCheck?: boolean;
         /**
          * The executor has the platform's sign-in dependencies and a ZITADEL
          * client for its instance. Not a block: without it the sign-in policy
@@ -1265,6 +1308,8 @@ export interface PlanPlatformOptions {
     drifted?: {
         archon?: boolean;
         auth?: boolean;
+        /** #643: a recorded sign-in app is missing or not running; plans the step again, minting nothing. */
+        authApps?: boolean;
         edge?: boolean;
         files?: boolean;
         backupStorage?: boolean;