@wtfalch/foundry 0.32.0 → 0.34.0

package/dist/plan/plan-apply.js

@@ -1,20 +1,25 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
-import { validateHosting } from '../org.js';
+import { sfuSlotPorts } from '../calls-sfu.js';
+import { 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 { unconfirmedUpgrades } from './confirm-upgrade.js';
-import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
+import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, isPlatformOwnOrg, toPlan, } from './diff.js';
 import { entryAiUndeliveredScopeKey } from './entry-ai-key.js';
 import { BOULE_EDGE_ENTRY_KEY, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
 import { FILES_ROOT_UNDELIVERED_SCOPE_KEY, entryFilesUndeliveredScopeKey, } from './entry-files-key.js';
 import { readLivePlatformResources, readLiveResources, } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
+import { agoraIssuerHostFor, loginHostServesAgora, readLoginHostDiscovery, } from './login-host.js';
+import { OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, } from './mail-relay.js';
+import { findNameClashes, nameClashMessage } from './org-names.js';
+import { OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, orgTarget } from './own-services.js';
 import { PLATFORM_ARCHON_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_KEY, appStepKey, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
-import { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, dnsBlockedReason, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
+import { DEFAULT_ORG_PLATFORM_READINESS, NO_DOMAIN_MAIL_APEX, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, dnsBlockedReason, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, serviceGitRefsOf, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { liveWorkers, workerTraceScopeKeys } from './worker.js';
 /** #441: the lease scope that serializes every mutation of one company, and the one for the shared platform. */
@@ -126,6 +131,10 @@ const HOSTNAME_STEPS = new Set([
  * destructive or migrating step without the org's name typed, or one the
  * actor is not authorized to run.
  */
+/** `unmanaged` key of the fixed line for an own org on a host with no `ownServices` port. */
+const OWN_SERVICES_PORT_ABSENT_KEY = 'own-services:port';
+/** `unmanaged` key of the fixed line for an own org whose scoped ports have no files-organisation port. */
+const OWN_FILES_ORGANISATION_PORT_ABSENT_KEY = 'own-services:files-port';
 export class FoundryPlanApply {
     store;
     readers;
@@ -137,12 +146,17 @@ export class FoundryPlanApply {
     agora;
     jobsScheduler;
     loginHostBindings;
+    loginHostDiscovery;
     zitadelIdTokenUserinfo;
     broker;
     edgeWorkers;
+    ownerInviteMail;
     hostFiles;
     hostAi;
     hostEdge;
+    hostOwnServices;
+    sfuPortsOpen;
+    onlySteps;
     now;
     leaseTtlMs;
     appliedVersions;
@@ -159,12 +173,17 @@ export class FoundryPlanApply {
         this.agora = options.agora;
         this.jobsScheduler = options.jobsScheduler ?? false;
         this.loginHostBindings = options.loginHostBindings ?? false;
+        this.loginHostDiscovery = options.loginHostDiscovery;
         this.zitadelIdTokenUserinfo = options.zitadelIdTokenUserinfo ?? false;
         this.broker = options.broker ?? false;
         this.edgeWorkers = options.edgeWorkers ?? false;
+        this.ownerInviteMail = options.ownerInviteMail ?? false;
         this.hostFiles = options.filesOrganisation ?? false;
         this.hostAi = options.aiOrganisation ?? false;
         this.hostEdge = options.edge ?? false;
+        this.hostOwnServices = options.ownServices ?? false;
+        this.sfuPortsOpen = options.sfuPortsOpen;
+        this.onlySteps = options.onlySteps;
         this.now = options.now ?? (() => new Date());
         this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.appliedVersions = options.appliedVersions;
@@ -893,29 +912,94 @@ export class FoundryPlanApply {
         });
         return applied;
     }
+    /** An own org with calls on: the host's answer about its slot's ports. A failure or a slow answer is "not open". */
+    async readSfuPortsOpen(org) {
+        const slot = org.services?.sfuSlot;
+        if (!this.sfuPortsOpen || !ownsServices(org) || !org.calls.enabled || !slot)
+            return false;
+        let ports;
+        try {
+            ports = sfuSlotPorts(slot);
+        }
+        catch {
+            return false;
+        }
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(false), 5_000));
+        return Promise.race([this.sfuPortsOpen(ports).catch(() => false), timeout]);
+    }
     async computeFreshPlan(id) {
         const org = await this.store.get(id);
         if (!org)
             throw new DeclaredOrgNotFoundError(id);
-        const [live, applied, platformReadiness, agoraHost, archonUrl] = await Promise.all([
-            readLiveResources(id, this.readers),
-            this.store.getAppliedState(id),
-            this.orgPlatformReadiness(),
-            this.orgAgoraHost(id),
+        const applied = await this.store.getAppliedState(id);
+        const [live, platformReadiness, agoraHost, archonUrl] = await Promise.all([
+            readLiveResources(id, this.readers, org, applied?.serviceIds ?? {}),
+            this.orgPlatformReadiness(org, applied?.serviceIds ?? {}),
+            this.orgAgoraHost(org, applied?.serviceIds ?? {}),
             this.orgArchonUrl(),
         ]);
         const otherSlugs = (await this.store.list()).filter((o) => o.id !== id).map((o) => o.slug);
         const platformHostnames = await this.platformServiceHostnames();
+        const recorded = applied?.serviceIds ?? {};
+        // Read only for an org Agora may switch and whose login host is applied.
+        const issuerHost = agoraIssuerHostFor(org, isPlatformOwnOrg(org, platformReadiness.platformOwnerOrgId)).host;
+        const loginHostServesDiscovery = issuerHost !== null && loginHostServesAgora(issuerHost, org, recorded)
+            ? await readLoginHostDiscovery(this.loginHostDiscovery, issuerHost)
+            : false;
+        const sfuPortsOpen = await this.readSfuPortsOpen(org);
+        const resumable = await this.ownResumableRefs(org);
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
             loginHostBindings: this.loginHostBindings,
+            loginHostServesDiscovery,
             zitadelIdTokenUserinfo: this.zitadelIdTokenUserinfo,
             broker: this.broker,
             edgeWorkers: this.edgeWorkers,
+            ownerInviteMail: this.ownerInviteMail,
             otherSlugs,
             now: () => this.now().getTime(),
             archonUrl,
             platformHostnames,
+            ownServices: this.hostOwnServices,
+            ownMailKeyHeld: await this.ownMailKeyHeld(org),
+            ownMailKeyMintable: this.executor.ownMailKeyMintable?.() ?? false,
+            ownJobsTokenHeld: resumable.jobs,
+            ownSfuKeysHeld: resumable.sfu,
+            ...(ownsServices(org) ? { mailRelayApplied: await this.mailRelayApplied() } : {}),
+            sfuPortsOpen,
+            ownFilesDeps: this.executor.ownFilesDeps?.(),
+            ...(ownsServices(org) && this.executor.ownFilesR2Ports
+                ? { ownFilesR2Ports: await this.executor.ownFilesR2Ports(org, recorded) }
+                : {}),
         });
+        if (ownsServices(org) && !this.hostOwnServices) {
+            detail.unmanaged.push({
+                description: `${org.slug} runs its own services, and this host has no ownServices port`,
+                key: OWN_SERVICES_PORT_ABSENT_KEY,
+            });
+        }
+        if (ownsServices(org) &&
+            this.hostOwnServices &&
+            detail.plannedSteps.some(({ action }) => action.system === 'files' && action.kind === 'organisation') &&
+            (await this.executor.ownFilesOrganisationPort?.(org, recorded)) === false) {
+            detail.plannedSteps = detail.plannedSteps.filter(({ action }) => !(action.system === 'files' && action.kind === 'organisation'));
+            detail.unmanaged.push({
+                description: `${org.slug}'s Files organisation is blocked, not planned: the host gave the company no files-organisation port`,
+                key: OWN_FILES_ORGANISATION_PORT_ABSENT_KEY,
+            });
+        }
+        const clashes = findNameClashes(org, await this.store.list());
+        for (const source of ['own', 'hosting']) {
+            const clash = clashes.find((c) => c.source === source);
+            if (!clash)
+                continue;
+            detail.plannedSteps = detail.plannedSteps.filter(({ action }) => source === 'own'
+                ? !(action.system === 'coolify' && action.kind.startsWith('own-'))
+                : !(action.system === 'coolify' && (action.kind === 'app' || action.kind === 'database')));
+            detail.unmanaged.push({
+                description: `${org.slug}'s ${source === 'own' ? 'own services are' : 'hosting is'} blocked, not planned: ${nameClashMessage(org.slug, clash)}`,
+                key: `names:clash:${source}`,
+            });
+        }
         const invalid = await this.invalidHosting(org);
         if (invalid) {
             // Rule 2: reported in `unmanaged`, not thrown. Steps that read the
@@ -926,6 +1010,11 @@ export class FoundryPlanApply {
                 key: 'hosting:invalid',
             });
         }
+        if (this.onlySteps) {
+            const { step, blocked } = this.onlySteps;
+            detail.plannedSteps = detail.plannedSteps.filter(({ action }) => step(action));
+            detail.unmanaged = detail.unmanaged.filter((item) => item.key === undefined || blocked(item.key));
+        }
         return { org, plan: toPlan(detail), detail };
     }
     /**
@@ -950,7 +1039,40 @@ export class FoundryPlanApply {
      * DEFAULT_ORG_PLATFORM_READINESS} reports every service not ready, so every
      * org step that needs one is blocked.
      */
-    async orgPlatformReadiness() {
+    async orgPlatformReadiness(org, orgRecordedIds) {
+        const base = await this.sharedPlatformReadiness();
+        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 ? { ...readiness, serviceGitRefs: serviceGitRefsOf(platform) } : readiness;
+    }
+    /** An own org's Lettermint key is held. A resolver that throws counts as not held. */
+    async ownMailKeyHeld(org) {
+        const held = this.platformDeps?.heldKeys;
+        if (!ownsServices(org) || !held)
+            return false;
+        return (await heldOwnKeyRefs(held, org)).has(orgTarget(org).refs.brokerMailKey);
+    }
+    /** Which of an own org's undelivered-secret refs hold a value now, so a rerun resumes instead of blocking. */
+    async ownResumableRefs(org) {
+        const held = this.platformDeps?.heldKeys;
+        if (!ownsServices(org) || !held)
+            return { jobs: false, sfu: false };
+        const refs = orgTarget(org).refs;
+        const heldRefs = await heldOwnKeyRefs(held, org);
+        return { jobs: heldRefs.has(refs.jobsAdminToken), sfu: heldRefs.has(refs.livekitKeys) };
+    }
+    /** The relay is declared and has recorded the routes it last applied: port 25 reaches the mail servers. */
+    async mailRelayApplied() {
+        const platform = await this.platformDeps?.store.get();
+        if (!platform?.mail.relay)
+            return false;
+        const recorded = await this.platformDeps?.store.getServiceIds();
+        return Boolean(recorded?.[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY]);
+    }
+    async sharedPlatformReadiness() {
         if (!this.platformDeps)
             return DEFAULT_ORG_PLATFORM_READINESS;
         const platform = await this.platformDeps.store.get();
@@ -988,11 +1110,14 @@ export class FoundryPlanApply {
      * `platformDeps` {@link orgPlatformReadiness} reads -- but only when the
      * host supplies no `agora` port of its own. An explicit `agora` (#164)
      * always wins, unchanged, so a host that already has its own values
-     * (perhaps not yet wired to this platform) keeps them.
+     * (perhaps not yet wired to this platform) keeps them. An org that owns its
+     * services never takes the host's values: they belong to the shared services.
      */
-    async orgAgoraHost(id) {
+    async orgAgoraHost(org, orgRecordedIds) {
+        if (ownsServices(org))
+            return agoraHostValuesForOwn(org, orgRecordedIds);
         if (this.agora)
-            return readAgoraHost(this.agora, id);
+            return readAgoraHost(this.agora, org.id);
         if (!this.platformDeps)
             return NO_AGORA_HOST_VALUES;
         const platform = await this.platformDeps.store.get();
@@ -1041,16 +1166,73 @@ export class FoundryPlanApply {
         const callsOrgSlugs = (await this.store.list())
             .filter((org) => org.calls.enabled)
             .map((org) => org.slug);
+        const mailRelay = platform.mail.relay === true ? await this.mailRelayInputs(platform) : null;
         const detail = computePlatformPlanDetail(platform, live, {
             jobsObservable: readers.coolify !== undefined,
             sfuBlocked,
             callsOrgSlugs,
+            ...(mailRelay ?? {}),
             recordedIds: serviceIds,
             blocked: (await executor.blockedSteps?.(platform, serviceIds)) ?? {},
             drifted: (await executor.driftedSteps?.(platform, serviceIds)) ?? {},
         });
         return { platform, plan: toPlatformPlan(detail, platform.ownerOrgId), detail };
     }
+    /**
+     * What the shared mail relay needs from the orgs. A route exists for an org
+     * that owns its services, serves mail on its own domain and has recorded its
+     * mail server's SMTP address (`mail_smtp_internal`, written by the company
+     * mail step). Every other org with mail on its own domain, the platform
+     * apex and the shared no-domain apex are platform domains: the platform's Stalwart receives them. An org
+     * that owns its services but has no mail server yet appears in neither list,
+     * so the relay refuses its mail until the server exists.
+     */
+    async mailRelayInputs(platform) {
+        const candidates = [];
+        const mailPlatformDomains = [platform.apex];
+        for (const org of await this.store.list()) {
+            if (org.mail.mode === 'off')
+                continue;
+            // Mail without the org's own domain is served on the shared no-domain apex.
+            if (!org.domain || !org.mail.usesDomain) {
+                if (!mailPlatformDomains.includes(NO_DOMAIN_MAIL_APEX)) {
+                    mailPlatformDomains.push(NO_DOMAIN_MAIL_APEX);
+                }
+                continue;
+            }
+            if (!ownsServices(org)) {
+                mailPlatformDomains.push(org.domain);
+                continue;
+            }
+            const recorded = (await this.store.getAppliedState(org.id))?.serviceIds ?? {};
+            const target = recorded[OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY];
+            if (recorded.coolify_platform_mail_app && target) {
+                candidates.push({ slug: org.slug, route: { domain: org.domain, target } });
+            }
+        }
+        // A domain the platform serves, or two companies claim, gets no route; the other routes stay.
+        const platformSet = new Set(mailPlatformDomains.map((d) => d.toLowerCase()));
+        const claims = new Map();
+        for (const { route } of candidates) {
+            const domain = route.domain.toLowerCase();
+            claims.set(domain, (claims.get(domain) ?? 0) + 1);
+        }
+        const mailRoutes = [];
+        const mailRoutesBlocked = [];
+        for (const { slug, route } of candidates) {
+            const domain = route.domain.toLowerCase();
+            if (platformSet.has(domain)) {
+                mailRoutesBlocked.push(`${slug}'s mail route for ${route.domain} is blocked, not planned: ${route.domain} is a platform mail domain`);
+            }
+            else if ((claims.get(domain) ?? 0) > 1) {
+                mailRoutesBlocked.push(`${slug}'s mail route for ${route.domain} is blocked, not planned: another company claims ${route.domain}`);
+            }
+            else {
+                mailRoutes.push(route);
+            }
+        }
+        return { mailRoutes, mailPlatformDomains, mailRoutesBlocked };
+    }
     async sfuBlockedReason(platform) {
         if (!platform.sfu.enabled)
             return null;
@@ -1192,6 +1374,8 @@ function destroyTargets(serviceIds, orgId) {
         'cloudflare:worker:',
         'coolify:database:',
         'coolify:app:',
+        // An own files host's storage key: the token id is the step's recorded resource id.
+        'coolify:own-files-r2:',
         'zitadel:customers:',
         // F6a: an entry's ai key, `<orgId>:<entry>`; the org's own key has no `:` and is left alone.
         'ai:key:',
@@ -1271,6 +1455,16 @@ function destroyTargets(serviceIds, orgId) {
             continue;
         targets.push({ system: 'edge', kind: 'key', key: entryKey, id });
     }
+    // A storage key minted but never delivered has no main id; its token is deleted too.
+    const r2Undelivered = serviceIds[OWN_FILES_R2_UNDELIVERED_SCOPE_KEY];
+    if (r2Undelivered) {
+        targets.push({
+            system: 'coolify',
+            kind: 'own-files-r2',
+            key: 'undelivered',
+            id: r2Undelivered,
+        });
+    }
     for (const [resourceKey, id] of Object.entries(serviceIds)) {
         if (!resourceKey.startsWith('zitadel:app:') || !id)
             continue;
@@ -1327,6 +1521,9 @@ function destroyStepDescriptions(targets) {
 function destroyServiceIdKey(target) {
     if (target.kind === 'project' || target.kind === 'org')
         return target.key;
+    if (target.kind === 'own-files-r2' && target.key === 'undelivered') {
+        return OWN_FILES_R2_UNDELIVERED_SCOPE_KEY;
+    }
     return `${target.system}:${target.kind}:${target.key}`;
 }
 /**
@@ -1342,6 +1539,12 @@ const STEP_FIELDS = {
     'coolify:broker-entry': 'hosting.entries.uses.auth',
     'coolify:mail': 'mail',
     'coolify:chat': 'chat.usesDomain',
+    'coolify:own-auth': 'services.own',
+    'coolify:own-files': 'services.own',
+    'coolify:own-files-r2': 'services.own',
+    'coolify:own-jobs': 'services.own',
+    'coolify:own-mail': 'services.own',
+    'coolify:own-sfu': 'services.own',
     'coolify:calls': 'calls.enabled',
     'coolify:calls-service': 'calls.enabled',
     'coolify:calls-chat': 'calls.enabled',
@@ -1489,6 +1692,7 @@ function canonical(plan) {
         // version-change line must still be caught as stale, the same as any
         // other field here.
         versionChanges: [...(plan.versionChanges ?? [])].sort((x, y) => x.description.localeCompare(y.description)),
+        notes: [...(plan.notes ?? [])].sort((x, y) => x.key.localeCompare(y.key)),
     };
 }
 /**

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

@@ -1,8 +1,9 @@
 import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
-import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
+import { type Plan, type PlanNote, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
 import type { LiveResource } from './live.js';
+import { type MailRoute, PLATFORM_MAIL_RELAY_KEY } from './mail-relay.js';
 /**
  * The platform's own diff result, the {@link DeclaredPlatform} counterpart to
  * `diff.ts`'s `PlanDetail` -- everything the same, minus the `orgId` an org's
@@ -16,6 +17,8 @@ export interface PlatformPlanDetail {
     unmanaged: UnmanagedItem[];
     /** #251: see {@link VersionChangeItem}. Never folded into `plannedSteps`. */
     versionChanges: VersionChangeItem[];
+    /** Advisory lines that block no step; see {@link PlanNote}. */
+    notes: PlanNote[];
 }
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
@@ -161,12 +164,11 @@ export declare const PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY = "archon_deployment";
  */
 export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_broker_app";
 /**
- * The `AUTHZ_BOOTSTRAP_OPERATOR` the last Archon apply set (`none` when it set
- * none). `planArchon` plans the step again when the owner's id recorded by
- * `platform:auth` differs from it, so Archon picks the owner up once auth
- * has recorded it.
+ * The sign-in org id the last Archon apply set as `AUTH_ORGANIZATION_ID` and
+ * registered its broker entry under. `planArchon` plans the step again when
+ * {@link archonAuthOrganizationId} differs from it.
  */
-export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applied_bootstrap_operator";
+export declare const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = "archon_applied_auth_org";
 /**
  * #475: whether the last successful Archon apply patched the app with
  * `custom_network_aliases` and `is_consistent_container_name_enabled: false`
@@ -183,11 +185,11 @@ export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applie
  */
 export declare const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = "archon_applied_rolling_update";
 /**
- * The owner's ZITADEL user id Archon takes as its first operator, from
- * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
- * recorded or the recorded value is `none` (no owner declared).
+ * The sign-in org Archon accepts: the platform owner company's own
+ * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
+ * a platform with no owner company declared. Undefined when neither is recorded.
  */
-export declare function archonBootstrapOperator(recorded: Readonly<Record<string, string>>): string | undefined;
+export declare function archonAuthOrganizationId(recorded: Readonly<Record<string, string>>): string | undefined;
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -207,6 +209,26 @@ export declare const PLATFORM_AUTH_SMTP_SCOPE_KEY = "zitadel_platform_smtp_provi
  * requested, so the invite goes out once. `none` when no owner is declared.
  */
 export declare const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_owner_invite_user_id";
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
+/**
+ * The id of the platform owner company's own sign-in organisation, made by
+ * `platform:auth` with the same name and primary domain a company apply uses,
+ * so that apply finds this org and makes no second one. `none` when the owner
+ * company is not declared. Archon signs people in from this org; the
+ * `foundry` org ({@link PLATFORM_ZITADEL_ORG_SCOPE_KEY}) holds no people.
+ */
+export declare const PLATFORM_OWNER_ORG_SCOPE_KEY = "zitadel_platform_owner_org";
+/** The primary domain `platform:auth` registered on the owner company's sign-in org. */
+export declare const PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY = "zitadel_platform_owner_org_domain";
+/** The owner org's sign-in domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export declare const PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY = "zitadel_platform_owner_org_domain_blocked";
+/**
+ * The sign-in org the recorded owner invite ({@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY})
+ * was made in. An invite recorded against another org (the `foundry` org, on a
+ * platform applied before the owner moved) plans the auth step again.
+ */
+export declare const PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY = "zitadel_platform_owner_invite_org";
 /**
  * #394: the id of the role-less ZITADEL machine user that reserves the
  * username `admin` in the platform's own org, so nobody can sign up under a
@@ -216,8 +238,6 @@ export declare const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_ow
 export declare const PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY = "zitadel_platform_reserved_admin_username";
 /** #394: recorded once the platform's own ZITADEL org has self-registration forced off. */
 export declare const PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY = "zitadel_platform_registration_closed";
-/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
-export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
 export declare const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = "zitadel_platform_admin_user_id";
 export declare const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = "zitadel_platform_admin_user_undelivered";
 /** #283: the created instance's id, recorded once its owner token is delivered. */
@@ -413,6 +433,18 @@ export declare const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = "mail_applied_git
  * no key and creates nothing in the sign-in server.
  */
 export declare const PLATFORM_MAIL_ROUTE_SCOPE_KEY = "mail_route_applied";
+/**
+ * The host ports the platform Stalwart publishes, as the mapping string the
+ * last apply set on its app. Without the shared relay it binds SMTP port 25
+ * itself; with `mail.relay` it keeps only submission, because the relay owns
+ * port 25. A missing record means the mapping it was created with, `25:25,...`.
+ */
+export declare const PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY = "mail_host_ports_applied";
+export declare const PLATFORM_MAIL_HOST_PORTS_DIRECT = "25:25,465:465,587:587";
+export declare const PLATFORM_MAIL_HOST_PORTS_RELAY = "465:465,587:587";
+export declare function platformMailHostPorts(platform: DeclaredPlatform): string;
+export { PLATFORM_MAIL_RELAY_KEY };
+export { PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, type MailRoute, } from './mail-relay.js';
 export declare const PLATFORM_MAIL_ROUTE_WANTED = "local-first";
 /**
  * #177: where the mail server answers on the Coolify network
@@ -952,6 +984,19 @@ export interface PlanPlatformOptions {
      * only when the recorded fingerprint differs; absent, it always plans it.
      */
     callsOrgSlugs?: readonly string[];
+    /**
+     * Which company domain goes to which company mail server. Used only when
+     * `platform.mail.relay` is true (default `[]`).
+     */
+    mailRoutes?: readonly MailRoute[];
+    /**
+     * The domains the platform's own Stalwart serves; the relay hands them to
+     * it and refuses any domain in neither list. Used only when
+     * `platform.mail.relay` is true (default `[]`).
+     */
+    mailPlatformDomains?: readonly string[];
+    /** One line per company route left out of `mailRoutes`; each is reported blocked and the relay still plans without it. */
+    mailRoutesBlocked?: readonly string[];
     /** The platform's recorded resource/scope ids (default `{}`). */
     recordedIds?: Readonly<Record<string, string>>;
     /** Per-step block reasons the executor reports (default `{}`). */
@@ -974,11 +1019,15 @@ export interface PlanPlatformOptions {
          * these. Default `[]`.
          */
         authOtherInputsMissing?: string[];
+        /** C3: why the owner's invite cannot be made (no work address, no mail port). The rest of the step still plans. */
+        authOwnerInvite?: string;
         files?: string;
         integrations?: string;
         ai?: string;
         archon?: string;
         mail?: string;
+        /** Why the shared mail relay cannot run: the executor lacks the mail dependencies or the base image tag floats. */
+        relay?: string;
         /** #478: why the edge host is blocked, or absent when it is not. */
         edge?: string;
         /** #604: why the Access sign-in provider cannot be made yet (no dependencies, or edge cannot confirm Access is ready), or absent. */