@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/plan/executor.js

@@ -3,6 +3,7 @@ import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, agoraHostnameFor, desiredAgoraEnv, } from './agora.js';
 import { MAS_IMAGE, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
+import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
 // ---------------------------------------------------------------------------
 // Errors
@@ -108,10 +109,11 @@ export function healthUrls(org) {
 }
 /**
  * The `OrgMailOrg` argument for `applyOrgMail`/`parkOrgMail`: an org with
- * `mail.usesDomain` off has no domain of its own, so it is level 1 on
- * `MAIL_APEX` and its mode is forced to `'hosted'` — `@wtfalch/email`'s own
- * `resolveDomain` refuses any other mode for a domain-less org, and a
- * level-1 `{slug}.{apex}` domain always has Stalwart's MX (foundry#7 "Mail").
+ * `mail.usesDomain` off has no domain of its own, so it is level 1 on the
+ * platform's own mail apex (`coolifyMail`'s `options.apex`) and its mode is
+ * forced to `'hosted'` — `@wtfalch/email`'s own `resolveDomain` refuses any
+ * other mode for a domain-less org, and a level-1 `{slug}.{apex}` domain
+ * always has Stalwart's MX (foundry#7 "Mail").
  */
 function mailOrgFor(org, usesDomain, mode) {
     return usesDomain && org.domain
@@ -226,17 +228,6 @@ const AGORA_APP_DOCKERFILE = 'apps/agora/Dockerfile';
  * restated rather than shared across the two files.
  */
 const LOG_DIR = '/app/logs';
-/**
- * #177: the fallback Stalwart apex and mail host `coolifyMail` uses when its
- * own step carries none (`diff.ts`'s `planMail` always supplies one once a
- * platform is wired -- `platform-org.ts`'s `DEFAULT_ORG_PLATFORM_READINESS`
- * is this exact pair, so a host that has not wired `FoundryPlanApplyOptions.
- * platform` yet keeps running on the address every org's mail always ran on
- * before the platform existed to ask, the same values `@wtfalch/email`'s own
- * README examples use for `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`).
- */
-const MAIL_APEX = 'wtfalch.dev';
-const MAIL_HOST = 'mail.wtfalch.dev';
 /**
  * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
  * not a `system:kind:key` resource id (that slot already holds the app's
@@ -312,6 +303,29 @@ const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
  * file's own `LOG_DIR` doc comment names for `diff.ts`.
  */
 const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/**
+ * #149 review finding: `MailPort.hasOrgRelay` only confirms Stalwart's route
+ * holds *a* secret, not that it is the one {@link FoundryStepExecutor
+ * .ensureOrgLettermintRelay} itself wrote for the project Lettermint
+ * currently lists under `<slug>-relay` -- a route a stale run wrote for a
+ * project that has since been lost and reprovisioned under the same name
+ * would otherwise read as healthy. Recorded as `<project id>@<mail domain>`
+ * right after a successful `MailPort.applyOrgRelay`, a flat scope id (no
+ * `:`) the same way {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is. The domain half
+ * also catches a domain switch: the healthy branch never calls
+ * `applyOrgRelay` again, so without this the Stalwart route would stay
+ * restricted to the org's previous domain forever.
+ */
+const ORG_MAIL_RELAY_SCOPE_KEY = 'mail_relay';
+/**
+ * #230: the role mailboxes {@link ensureRoleMailboxes} has created, as one
+ * flat scope id holding their full addresses (`local@domain`, lowercased, so a
+ * mail domain change owes the new domain its own set) joined by `,`
+ * (`validateMail` refuses a `,` in a name, so the join is unambiguous). Updated after each
+ * mailbox, so a crash part-way through never recreates the ones already
+ * made. `plan/diff.ts` keeps its own copy of this literal.
+ */
+const MAIL_ROLE_MAILBOXES_SCOPE_KEY = 'mail_role_mailboxes';
 /**
  * #80: the id of an ai key `aiKey` has minted but not yet delivered, a flat
  * scope id (no `:`). `plan/diff.ts` keeps its own copy of this literal.
@@ -328,17 +342,6 @@ const AI_KEY_DELIVERY_ATTEMPTS = 3;
 const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
 /** How many times `jobsRegistration` tries each `deliverSecret` before giving up. */
 const JOBS_DELIVERY_ATTEMPTS = 3;
-/**
- * The one mailbox this executor mints on its own (#162) -- a plain,
- * discoverable local part rather than anything derived from the owner's own
- * (possibly personal) `email`, so it never collides with a name and never
- * repeats a stranger's inbox back at them. #162's own "Decide" section
- * leaves open whether every *other* person in the org also gets a mailbox
- * from foundry, or only from Boule -- unresolved, on purpose, until a human
- * picks one; this constant and {@link ensureOwnerMailbox} only ever cover
- * the owner, which every candidate answer to that question already includes.
- */
-const MAIL_OWNER_LOCAL_PART = 'owner';
 /**
  * `coolifyCalls` provisions four resources from one `coolify:calls` step
  * (#128) — the same one-step, several-resource shape `cmsSite` already solves
@@ -463,6 +466,8 @@ export class FoundryStepExecutor {
                 return this.aiKey(action, org, context);
             case 'coolify:mail':
                 return this.coolifyMail(action, org, context);
+            case 'coolify:mail-copy':
+                return this.mailCopy(org, context);
             case 'coolify:chat':
                 throw new NotBuiltError(`coolify:chat for ${org.slug}`, "chat's per-org Synapse+MAS has no admin API yet; tracked at https://github.com/wtfalch/chat/issues/40");
             case 'cms:site':
@@ -970,9 +975,10 @@ export class FoundryStepExecutor {
      * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
      * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
      * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
-     * reason. AUTH_APP_KEY (waits on an auth broker registration API) and
-     * DATABASE_URL_OWNER (a runtime-role split not built yet, `pushDatabaseUrl`'s
-     * own doc comment) are out of scope here (task brief).
+     * reason. `AUTH_APP_KEY` (#206 -- which broker an org's app registers with
+     * is its own design question, left out of #204's own "How" rather than
+     * guessed) and DATABASE_URL_OWNER (a runtime-role split not built yet,
+     * `pushDatabaseUrl`'s own doc comment) are out of scope here (task brief).
      */
     async pushAppEnv(appId, org, context) {
         const recorded = context.recordedIds();
@@ -1052,7 +1058,10 @@ export class FoundryStepExecutor {
      * be deleted.
      *
      * `MAIL_FROM` is upserted every time: it depends only on the mail domain
-     * `coolify:mail` resolved.
+     * `coolify:mail` resolved and `org.mail.noReplyLocalPart` (#162, decided
+     * 2026-09-29 -- defaults to `'no-reply'`, restated here rather than
+     * imported from `org.ts`'s `DEFAULT_NO_REPLY_LOCAL_PART`, this file's own
+     * `LOG_DIR`-style convention).
      *
      * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
      * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
@@ -1065,7 +1074,6 @@ export class FoundryStepExecutor {
         if (!mailDomain)
             return;
         const appName = `${org.slug}-app`;
-        const relayName = `${org.slug}-relay`;
         const [projects, envs] = await Promise.all([
             this.ports.lettermint.listProjects(),
             this.ports.coolify.listEnvs(appId),
@@ -1086,18 +1094,133 @@ export class FoundryStepExecutor {
             allProjects = [...projects, created.project];
             envUpdates.push({ key: 'LETTERMINT_API_TOKEN', value: created.token });
         }
-        envUpdates.push({ key: 'MAIL_FROM', value: `no-reply@${mailDomain}` });
+        envUpdates.push({
+            key: 'MAIL_FROM',
+            value: `${org.mail.noReplyLocalPart ?? 'no-reply'}@${mailDomain}`,
+        });
         await this.ports.coolify.bulkUpsertEnvs(appId, envUpdates);
         // A running container read its env at start and still holds the old
         // token, so a fresh one only reaches it through a restart -- before the
         // old project is deleted below. A just-created app starts with the new env.
         if (!healthy && running)
             await this.ports.coolify.restart(appId);
+        await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+        for (const project of allProjects) {
+            if (project.name === appName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
+        }
+    }
+    /**
+     * #149: mints this org's own Lettermint relay credential and writes it to
+     * Stalwart via `MailPort.applyOrgRelay`, the same mint rule
+     * {@link ensureAppLettermintMail} already uses for the org's app token --
+     * "healthy" means Stalwart's own route exists ({@link MailPort.hasOrgRelay}),
+     * AND Lettermint lists a project named `<slug>-relay` whose id
+     * {@link ORG_MAIL_RELAY_SCOPE_KEY} records for this
+     * exact mail domain (review finding: a route with a secret and a
+     * same-named project both present is not enough -- the project could be a
+     * lost-and-reprovisioned one this step never wrote a route for, and a mail
+     * domain switch must re-point the route rather than read as healthy
+     * forever because the old route still has a secret in it). A route with no
+     * live project behind it, a project the route's own secret never reached,
+     * or a recorded project id/domain that no longer matches, are all exactly
+     * as unhealthy as neither existing.
+     *
+     * A fresh project is created and its token written to Stalwart first, and
+     * only then is every other `<slug>-relay` project deleted -- a lost route
+     * and a duplicate project both end the same way. The new project's domain
+     * restriction runs before the token is written, so a failure there never
+     * touches the working route. Review finding: if either the
+     * domain-restriction step or `applyOrgRelay` throws after a
+     * fresh project was minted, that project is deleted before the error
+     * propagates -- otherwise every retry sees more than one `<slug>-relay`
+     * project and mints yet another one, growing the orphan count without
+     * bound.
+     *
+     * `coolify:mail` runs before `coolify:app` (`diff.ts`'s own step order), so
+     * this is very often the first of the two to reach the org's Lettermint
+     * domain: {@link ensureLettermintDomainRestriction} registers and restricts
+     * it the same way the app step does, rather than assuming it already
+     * exists -- the domain must never end up unrestricted, whichever step gets
+     * there first.
+     */
+    async ensureOrgLettermintRelay(org, mailOrg, mailDomain, context) {
+        const relayName = `${org.slug}-relay`;
+        const [projects, hasRelay] = await Promise.all([
+            this.ports.lettermint.listProjects(),
+            this.ports.mail.hasOrgRelay(mailOrg),
+        ]);
+        // The recorded project, not "the only one": a leftover duplicate whose
+        // delete keeps failing must not force a fresh mint on every apply.
+        const recordedRelay = context.recordedIds()[ORG_MAIL_RELAY_SCOPE_KEY];
+        const held = projects.find((p) => p.name === relayName && `${p.id}@${mailDomain}` === recordedRelay);
+        const healthy = held !== undefined && hasRelay;
+        let allProjects = projects;
+        let keepProjectId;
+        if (healthy && held) {
+            keepProjectId = held.id;
+            await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+        }
+        else {
+            const created = await this.ports.lettermint.createProject(relayName);
+            keepProjectId = created.project.id;
+            allProjects = [...projects, created.project];
+            try {
+                // Everything that can fail for the new project runs before the token
+                // reaches Stalwart: a failure here leaves the working route alone.
+                // The restriction covers old and new projects, so the old one keeps
+                // sending until the route switches.
+                await this.ensureLettermintDomainRestriction(org, mailDomain, allProjects);
+                await this.ports.mail.applyOrgRelay(mailOrg, created.token);
+            }
+            catch (err) {
+                await this.discardLettermintProject(created.project.id);
+                throw err;
+            }
+            context.recordScopeId(ORG_MAIL_RELAY_SCOPE_KEY, `${keepProjectId}@${mailDomain}`);
+            // Written now: a crash before the end-of-run write would leave the old
+            // project recorded, and the next apply would sweep the one the route uses.
+            await context.persistScopeIds();
+        }
+        for (const project of allProjects) {
+            if (project.name === relayName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
+        }
+    }
+    /**
+     * Deletes a just-minted project from inside a `catch`. A failed delete is
+     * dropped so it never replaces the error being rethrown; the orphan is
+     * swept by the next apply's duplicate delete.
+     */
+    async discardLettermintProject(id) {
+        try {
+            await this.ports.lettermint.deleteProject(id);
+        }
+        catch {
+            // Dropped: the caller rethrows the original error.
+        }
+    }
+    /**
+     * Ensures this org's Lettermint domain exists, is restricted to exactly
+     * the `<slug>-app`/`<slug>-relay` projects live in `allProjects`, has its
+     * DNS published and a verification triggered. Shared by
+     * {@link ensureAppLettermintMail} and {@link ensureOrgLettermintRelay}
+     * (#149) -- whichever of the two steps runs first on a fresh org creates
+     * the domain, and the other then finds it (`findExactLettermintDomain`).
+     *
+     * A crash between the restriction write and the DNS publish/verify below
+     * is safe even for a freshly created domain: DNS is only published, and
+     * verification only triggered, after the restriction -- so an
+     * unrestricted domain cannot verify and cannot send, whichever project
+     * owns it (post-#140 review finding, restated here rather than only at
+     * the one call site it used to have).
+     */
+    async ensureLettermintDomainRestriction(org, mailDomain, allProjects) {
+        const appName = `${org.slug}-app`;
+        const relayName = `${org.slug}-relay`;
         const existing = await this.findExactLettermintDomain(mailDomain);
-        // A crash between here and `restrictDomainToProjects` below is safe even
-        // for a freshly created domain: DNS is only published, and verification
-        // only triggered, after the restriction -- so an unrestricted domain
-        // cannot verify and cannot send, whichever project owns it.
         const domain = existing
             ? await this.ports.lettermint.getDomain(existing.id)
             : await this.ports.lettermint.createDomain(mailDomain);
@@ -1107,15 +1230,10 @@ export class FoundryStepExecutor {
         await this.ports.lettermint.restrictDomainToProjects(domain.id, scopedProjectIds);
         const zone = await this.ports.cloudflare.findZoneByApex(mailDomain);
         if (!zone) {
-            throw new Error(`coolify:app for ${org.slug}: no Cloudflare zone found for ${mailDomain}`);
+            throw new Error(`Lettermint for ${org.slug}: no Cloudflare zone found for ${mailDomain}`);
         }
         await this.publishLettermintDnsRecords(zone.id, domain.dnsRecords);
         await this.ports.lettermint.verifyDomain(domain.id);
-        for (const project of allProjects) {
-            if (project.name === appName && project.id !== keepProjectId) {
-                await this.ports.lettermint.deleteProject(project.id);
-            }
-        }
     }
     /**
      * Review finding (post-#140 rework): {@link LettermintPort.findDomain}'s
@@ -1713,9 +1831,9 @@ export class FoundryStepExecutor {
         if (!masCredentials) {
             throw new Error(`coolify:calls-service for ${org.slug}: the calls Matrix stack's MAS client credentials are not on the MAS app yet -- retry this apply once coolify:calls has minted them`);
         }
-        const sfu = await this.ports.callsSfu.resolveCredentials();
+        const sfu = await this.ports.callsSfu.resolveCredentials(org.slug);
         if (!sfu) {
-            throw new Error(`coolify:calls-service for ${org.slug}: the shared calls SFU has no LiveKit credentials configured yet -- see https://github.com/wtfalch/foundry/issues/122`);
+            throw new Error(`coolify:calls-service for ${org.slug}: the shared calls SFU has no LiveKit credentials for this org yet -- see https://github.com/wtfalch/foundry/issues/152`);
         }
         const projectUuid = await this.ensureCoolifyProject(org, context);
         const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
@@ -2031,20 +2149,21 @@ export class FoundryStepExecutor {
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
      * publishes whatever Stalwart DNS records the call returns, and records the
      * resolved mail domain as a scope id ({@link MAIL_DOMAIN_SCOPE_KEY}).
-     * 2026-09-28 lettermint-org-mail swap: this step no longer calls the mail
-     * relay provider at all -- registering the domain, restricting it and
-     * publishing its own DNS records all moved to the app step
-     * (`ensureAppLettermintMail`, "Core rule"), since the first project can
-     * only exist once the token has a home. Parking mail (mode `'off'`) does
-     * still reach Lettermint, the one exception: {@link parkLettermintMail}
-     * deletes the org's own projects and then its domain, so a domain never
-     * ends up restricted only to dead projects.
+     *
+     * #149: this step also mints the org's own Lettermint *relay* credential
+     * ({@link ensureOrgLettermintRelay}) -- the app's own *sending* credential
+     * stays in the app step (`ensureAppLettermintMail`, "Core rule"), since the
+     * first app project can only exist once the token has a home. Parking mail
+     * (mode `'off'`) reaches Lettermint too: {@link parkLettermintMail} drops
+     * the relay route, then deletes the org's own projects and its domain, so
+     * a domain never ends up restricted only to dead projects and no route
+     * ever points at a project this apply is about to remove.
      *
      * Review finding: a mail domain switch (`org.domain` changes, or
      * `usesDomain` flips) must also delete the *old* Lettermint domain here,
      * before recording the new one -- otherwise it stays registered and
-     * restricted to the org's still-live `<slug>-app` project, which could
-     * then keep sending as it forever. {@link deleteStaleLettermintDomain}
+     * restricted to the org's still-live `<slug>-app`/`<slug>-relay` projects,
+     * which could then keep sending as it forever. {@link deleteStaleLettermintDomain}
      * does this by comparing the previously recorded domain (case-insensitive)
      * against the one this apply just resolved.
      *
@@ -2058,15 +2177,22 @@ export class FoundryStepExecutor {
         // #177: `diff.ts`'s `planMail` carries the platform's own apex/mail host
         // in `desired` once it is wired -- "the executor writes exactly these
         // host values, so what the plan showed is what gets applied" (`planAgora`'s
-        // own rule). `MAIL_APEX`/`MAIL_HOST` remain the fallback for a plan built
-        // without a platform (this file's own doc comment on those constants).
-        const options = {
-            apex: action.desired.apex ?? MAIL_APEX,
-            mailHost: action.desired.mailHost ?? MAIL_HOST,
-        };
+        // own rule) -- and blocks the step (never plans it) while the platform's
+        // mail is off or not yet applied. So a `desired` missing either value
+        // here is not a live gap to fall back on (#205): it is a step planned
+        // before that rule existed, now stale. Fail rather than silently point an
+        // org's mail at a fixed address nothing may still be listening on; the
+        // fix is to plan this org's mail again.
+        const apex = action.desired.apex;
+        const mailHost = action.desired.mailHost;
+        if (!apex || !mailHost) {
+            throw new Error(`coolify:mail for ${org.slug}: this step's plan carries no platform mail ${!apex && !mailHost ? 'apex or host' : !apex ? 'apex' : 'host'}; plan this org's mail again`);
+        }
+        const options = { apex, mailHost };
         if (mode === 'off') {
-            await this.ports.mail.parkOrgMail(mailOrgFor(org, usesDomain, 'hosted'), options);
-            await this.parkLettermintMail(org, context);
+            const parkedMailOrg = mailOrgFor(org, usesDomain, 'hosted');
+            await this.ports.mail.parkOrgMail(parkedMailOrg, options);
+            await this.parkLettermintMail(org, parkedMailOrg, context);
             return undefined;
         }
         const mailOrg = mailOrgFor(org, usesDomain, mode);
@@ -2077,30 +2203,97 @@ export class FoundryStepExecutor {
         // #177: what this step wrote from the platform, so `planMail` can see a later change.
         context.recordScopeId(ORG_MAIL_APPLIED_APEX_SCOPE_KEY, options.apex);
         context.recordScopeId(ORG_MAIL_APPLIED_HOST_SCOPE_KEY, options.mailHost);
-        await this.ensureOwnerMailbox(org, mailOrg, result.domain, context);
+        await this.ensureOwnerMailbox(org, mailOrg, context);
+        await this.ensureOrgLettermintRelay(org, mailOrg, result.domain, context);
+        await this.ensureRoleMailboxes(org, mailOrg, result.domain, context);
         return { resourceId: result.domain };
     }
     /**
-     * #162: gives the org's declared owner a mailbox on its just-resolved mail
-     * domain, the one address this executor mints on its own
-     * ({@link MAIL_OWNER_LOCAL_PART}'s own doc comment). A no-op when the org
-     * has no owner yet, or once {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already
-     * recorded -- checked first so a second apply never calls
-     * `MailPort.createMailbox` again, rather than relying on that port method's
-     * own duplicate refusal.
+     * `plan/diff.ts`'s `planMailCopy` (#113): this apply's share of copying
+     * the org's old mail into Stalwart, via `mail-copy.ts`'s `runMailCopyStep`
+     * -- the only thing this method itself does is read back what the last
+     * apply recorded, hand it to that function, and record what comes back.
+     * An account that failed to copy records the progress made, never
+     * `mail_copy_done`, then throws with the failing account, phase and
+     * redacted stderr tail, so the apply reports it as not done. A missing
+     * `mailCopy` port throws too: a configuration gap a retry cannot fix.
      */
-    async ensureOwnerMailbox(org, mailOrg, domain, context) {
+    async mailCopy(org, context) {
+        if (!this.ports.mailCopy) {
+            throw new NotBuiltError(`coolify:mail-copy for ${org.slug}`, 'construct FoundryStepExecutor with `mailCopy` (#113)');
+        }
+        const alreadyCompleted = new Set(parseMailCopyCompleted(context.recordedIds()[MAIL_COPY_COMPLETED_SCOPE_KEY]));
+        const result = await runMailCopyStep(org, this.ports.mailCopy, alreadyCompleted);
+        context.recordScopeId(MAIL_COPY_COMPLETED_SCOPE_KEY, JSON.stringify(result.completed));
+        if (result.done)
+            context.recordScopeId(MAIL_COPY_DONE_SCOPE_KEY, '1');
+        if (result.failure) {
+            const { account, phase, exitCode, detail } = result.failure;
+            // Written now: the throw below ends the step before the end-of-run write.
+            await context.persistScopeIds();
+            throw new Error(`coolify:mail-copy for ${org.slug}: ${phase} of ${account} ${exitCode === undefined ? 'threw' : `exited ${exitCode}`}${detail ? `: ${detail}` : ''} -- retry this apply to continue (a provider's daily limit looks the same)`);
+        }
+        return undefined;
+    }
+    /**
+     * #162 (decided 2026-09-29): gives the org's declared owner a mailbox at
+     * its declared `mail.ownerMailboxAddress` -- nothing is guessed any more
+     * (the hardcoded `owner@<domain>` PR 163 shipped first is gone). A no-op
+     * when the org has no owner yet, when no address is declared yet
+     * (`plan/diff.ts`'s `planMail` reports that case as blocked, not planned,
+     * so this step's own mode/domain work still runs), or once
+     * {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already recorded -- checked last
+     * so a second apply never calls `MailPort.createMailbox` again, rather
+     * than relying on that port method's own duplicate refusal.
+     */
+    async ensureOwnerMailbox(org, mailOrg, context) {
         if (!org.owner)
             return;
+        const address = org.mail.ownerMailboxAddress ?? null;
+        if (!address)
+            return;
         if (context.recordedIds()[MAIL_OWNER_MAILBOX_SCOPE_KEY])
             return;
-        const address = `${MAIL_OWNER_LOCAL_PART}@${domain}`;
         await this.ports.mail.createMailbox(mailOrg, {
             address,
             name: `${org.owner.givenName} ${org.owner.familyName}`,
         });
         context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
     }
+    /**
+     * #230: creates each of the org's declared `mail.roleMailboxes` on its
+     * just-resolved mail domain, once. A role mailbox has no person behind it,
+     * so its display name is just its local part, and like the owner's it is
+     * created with no password: `MailPort.createMailbox` takes none, so there
+     * is no secret to store or print. A "already has a mailbox" refusal from the port counts as created. The created set is recorded under
+     * {@link MAIL_ROLE_MAILBOXES_SCOPE_KEY} after every mailbox, so a second
+     * apply (or a retry after a crash) skips what exists rather than relying
+     * on the mail server's own duplicate refusal.
+     */
+    async ensureRoleMailboxes(org, mailOrg, domain, context) {
+        const declared = org.mail.roleMailboxes ?? [];
+        if (declared.length === 0)
+            return;
+        const recorded = context.recordedIds()[MAIL_ROLE_MAILBOXES_SCOPE_KEY];
+        const created = new Set(recorded ? recorded.split(',') : []);
+        for (const local of declared) {
+            const address = `${local}@${domain}`;
+            const entry = address.toLowerCase();
+            if (created.has(entry))
+                continue;
+            try {
+                await this.ports.mail.createMailbox(mailOrg, { address, name: local });
+            }
+            catch (error) {
+                // A crash between create and record leaves the mailbox made but
+                // unrecorded; the port exposes no existence check, only the refusal.
+                if (!/already has a mailbox/i.test(error instanceof Error ? error.message : String(error)))
+                    throw error;
+            }
+            created.add(entry);
+            context.recordScopeId(MAIL_ROLE_MAILBOXES_SCOPE_KEY, [...created].join(','));
+        }
+    }
     /**
      * Deletes the org's previous Lettermint domain once the mail domain it was
      * registered under has changed -- otherwise it stays registered and
@@ -2145,17 +2338,22 @@ export class FoundryStepExecutor {
     /**
      * Parking mail (2026-09-28 lettermint-org-mail swap, "Core rule": "Parking
      * mail deletes the org's projects and then the domain itself, so no
-     * restriction points only at dead projects"). Deletes every Lettermint
-     * project named `<slug>-app` or `<slug>-relay`, then the org's own
-     * Lettermint domain, if one was found -- in that order, never the reverse.
+     * restriction points only at dead projects"). #149: first drops the
+     * Stalwart relay route with `MailPort.removeOrgRelay` -- a missing route is
+     * a no-op, per that port method's own contract, so this is safe to call
+     * even for an org whose relay was never minted -- then deletes every
+     * Lettermint project named `<slug>-app` or `<slug>-relay`, then the org's
+     * own Lettermint domain, if one was found -- in that order, never the
+     * reverse, so the route is always gone before the project it pointed at.
      * A no-op until a previous apply recorded {@link MAIL_DOMAIN_SCOPE_KEY}:
      * nothing was ever provisioned for an org whose mail went straight from
      * never-applied to off.
      */
-    async parkLettermintMail(org, context) {
+    async parkLettermintMail(org, mailOrg, context) {
         const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
         if (!mailDomain)
             return;
+        await this.ports.mail.removeOrgRelay(mailOrg);
         const names = new Set([`${org.slug}-app`, `${org.slug}-relay`]);
         const projects = await this.ports.lettermint.listProjects();
         for (const project of projects) {

package/dist/plan/index.d.ts

@@ -14,14 +14,20 @@ export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, Provide
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
-export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './platform-providers.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
+export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export type { AgoraHostPort, AgoraHostValues } from './agora.js';
+export type { MailIdentityApp, MailIdentityAudienceCheck } from './mail-identity.js';
+export { checkMailIdentityAudience } from './mail-identity.js';
+export type { MailAllowlistApp } from './mail-identity-allowlist.js';
+export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, } from './executor.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/index.js

@@ -7,9 +7,12 @@ export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, Confirmatio
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
 // #171: how a host signs files management requests with the delivered key.
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
-export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './platform-providers.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
+export { checkMailIdentityAudience } from './mail-identity.js';
+export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';