@wtfalch/foundry 0.27.0 → 0.29.0

package/dist/calls-sfu.d.ts

@@ -203,6 +203,12 @@ export declare function cloudflaredEnvFile(token: string): string;
  * writes the set it was given.
  */
 export declare function livekitConfigYaml(config: CallsSfuConfig): string;
+/** The command that brings both compose services up; part of what {@link callsSfuFilesVersion} hashes. */
+export declare const CALLS_SFU_UP_COMMAND = "docker compose -f /opt/livekit/docker-compose.yml up -d";
+/** Run first, so the SSH session this runs over is never refused. */
+export declare const CALLS_SFU_SSH_RULE_COMMAND = "ufw allow 22/tcp";
+/** Run after any unscoped signalling rule is removed, in this order. */
+export declare const CALLS_SFU_FIREWALL_COMMANDS: readonly string[];
 /**
  * Writes all three files, brings LiveKit and `cloudflared` up, then narrows
  * the VM firewall to exactly what #122's and #127's "Decided" sections name

package/dist/calls-sfu.js

@@ -239,6 +239,19 @@ rtc:
   node_ip: ${address}
 ${keysYaml}`;
 }
+/** The command that brings both compose services up; part of what {@link callsSfuFilesVersion} hashes. */
+export const CALLS_SFU_UP_COMMAND = `docker compose -f ${LIVEKIT_COMPOSE_PATH} up -d`;
+/** Run first, so the SSH session this runs over is never refused. */
+export const CALLS_SFU_SSH_RULE_COMMAND = 'ufw allow 22/tcp';
+/** Run after any unscoped signalling rule is removed, in this order. */
+export const CALLS_SFU_FIREWALL_COMMANDS = [
+    `ufw allow from ${CALLS_SFU_PRIVATE_CIDR} to any port ${LIVEKIT_SIGNALLING_PORT} proto tcp`,
+    `ufw allow ${LIVEKIT_MEDIA_TCP_PORT}/tcp`,
+    `ufw allow ${LIVEKIT_MEDIA_UDP_RANGE}/udp`,
+    'ufw default deny incoming',
+    'ufw default allow outgoing',
+    'ufw --force enable',
+];
 async function run(host, command) {
     const result = await host.exec(command);
     if (result.exitCode !== 0) {
@@ -290,16 +303,12 @@ export async function applyCallsSfu(host, config) {
     await host.writeFile(LIVEKIT_COMPOSE_PATH, dockerComposeYaml());
     await writeFileAtomically(host, LIVEKIT_CONFIG_PATH, livekitConfigYaml(config));
     await host.writeFile(CLOUDFLARED_ENV_PATH, cloudflaredEnvFile(config.cloudflaredTunnelToken));
-    await run(host, `docker compose -f ${LIVEKIT_COMPOSE_PATH} up -d`);
-    await run(host, 'ufw allow 22/tcp');
+    await run(host, CALLS_SFU_UP_COMMAND);
+    await run(host, CALLS_SFU_SSH_RULE_COMMAND);
     const status = await host.exec('ufw status');
     if (status.exitCode === 0 && hasUnscopedSignallingRule(status.stdout)) {
         await run(host, `ufw delete allow ${LIVEKIT_SIGNALLING_PORT}/tcp`);
     }
-    await run(host, `ufw allow from ${CALLS_SFU_PRIVATE_CIDR} to any port ${LIVEKIT_SIGNALLING_PORT} proto tcp`);
-    await run(host, `ufw allow ${LIVEKIT_MEDIA_TCP_PORT}/tcp`);
-    await run(host, `ufw allow ${LIVEKIT_MEDIA_UDP_RANGE}/udp`);
-    await run(host, 'ufw default deny incoming');
-    await run(host, 'ufw default allow outgoing');
-    await run(host, 'ufw --force enable');
+    for (const command of CALLS_SFU_FIREWALL_COMMANDS)
+        await run(host, command);
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EntryGate, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, } from './org.js';
 export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, appEntry, ownerMailboxes, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateSite, } from './org.js';
-export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
+export type { DeclaredPlatform, PlatformService, PlatformServiceKey, PlatformSfuService, } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 import { type PinnedVersions } from './bootstrap/versions.js';
 export type { PinnedVersions };
@@ -22,7 +22,7 @@ export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, File
 export { AdoptRefusedError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
 export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, DnsPort, EdgePlatformAccess, EdgePlatformDns, EdgePlatformRateLimits, EdgePlatformWorkers, EdgePlatformZones, EdgeZonesOptions, ZonePort, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, EdgeWorkersOptions, EdgePlatformTunnels, TunnelPort, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';
@@ -47,7 +47,7 @@ export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEME
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './plan/index.js';
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './plan/index.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './plan/index.js';
-export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './plan/index.js';
 export type { CallsSfuUrls } from './calls-sfu.js';
 export type { CallsSfuSshSession } from './calls-sfu-ssh-adapter.js';
 export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { AdoptRefusedError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
@@ -26,7 +26,7 @@ export { checkMailAppsAllowlist } from './plan/index.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, createZitadelProjectRoles, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './plan/index.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 './plan/index.js';
-export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './plan/index.js';
 export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';
 export { UnknownCallsSfuHostKeyError, toCallsSfuHostPort, applyCallsSfuOverSession, } from './calls-sfu-ssh-adapter.js';
 export { mintLivekitCredentials } from './calls-sfu-keys.js';

package/dist/migrations/0050_platform_sfu_connection_revision.sql

@@ -0,0 +1,7 @@
+-- @wtfalch/foundry: the platform's `sfu.connectionRevision`, a value a host
+-- changes when the SFU VM's SSH key, host key or tunnel token changes, so the
+-- platform plan shows the `sfu` step again. Declared; null until set.
+-- Mirrors src/store/schema.ts's `foundryDeclaredPlatform` table addition.
+
+alter table foundry_declared_platform
+  add column if not exists sfu_connection_revision text;

package/dist/plan/boule.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg } from '../org.js';
+import { type DeclaredOrg } from '../org.js';
 import type { BrokerEntryInput, BrokerEntryWant } from './broker-entries.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
@@ -36,8 +36,28 @@ export declare const BOULE_DEPLOYED_SCOPE_KEY = "coolify_boule_deployed";
  * issuer.
  */
 export declare function bouleHostnameFor(org: DeclaredOrg): string;
+/** The env name Boule reads its Lettermint token from (boule#266). */
+export declare const BOULE_MAIL_TOKEN_ENV = "LETTERMINT_API_TOKEN";
+/**
+ * Whether Boule should mail invites: the org's mail is hosted and
+ * `coolify:mail` has recorded its domain. Mail off, received, or no domain
+ * yet: no mail env at all, and Boule shows the invite link on screen.
+ */
+export declare function bouleMailWanted(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): boolean;
+/**
+ * Boule's `MAIL_FROM`: the org's no-reply address on its recorded mail
+ * domain. The local part falls back to `DEFAULT_NO_REPLY_LOCAL_PART`, the
+ * same default the hosted app's `MAIL_FROM` uses and the store column holds.
+ */
+export declare function bouleMailFrom(org: DeclaredOrg, mailDomain: string): string;
+/**
+ * Whether the live Boule's mail token needs writing: it holds none, or the
+ * org's hosted app holds a different one (the app's token wins). Compares
+ * values in memory only; the result names nothing secret.
+ */
+export declare function bouleMailTokenDrift(liveToken: string | undefined, appToken: string | undefined): boolean;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "ARCHON_URL"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a
@@ -55,11 +75,15 @@ export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER",
  * absent: Boule has no platform wired in every test and every org-only
  * caller, same as `issuer` before #177.
  *
+ * `mailWanted` (see {@link bouleMailWanted}) adds `MAIL_FROM`. The Lettermint
+ * token is never here: it is a secret the executor writes and the plan
+ * compares in memory ({@link bouleMailTokenDrift}).
+ *
  * Not here, and written by the executor instead: the database URLs
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null): {
+export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean): {
     env: Record<string, string>;
     missing: string[];
 };

package/dist/plan/boule.js

@@ -1,3 +1,4 @@
+import { DEFAULT_NO_REPLY_LOCAL_PART } from '../org.js';
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
@@ -37,6 +38,34 @@ export const BOULE_DEPLOYED_SCOPE_KEY = 'coolify_boule_deployed';
 export function bouleHostnameFor(org) {
     return org.domain ? `boule.${org.domain}` : `${org.slug}-boule.oikos.host`;
 }
+/** The env name Boule reads its Lettermint token from (boule#266). */
+export const BOULE_MAIL_TOKEN_ENV = 'LETTERMINT_API_TOKEN';
+/** The scope id `coolify:mail` records the org's resolved mail domain under. */
+const MAIL_DOMAIN_RECORDED_KEY = 'mail_domain';
+/**
+ * Whether Boule should mail invites: the org's mail is hosted and
+ * `coolify:mail` has recorded its domain. Mail off, received, or no domain
+ * yet: no mail env at all, and Boule shows the invite link on screen.
+ */
+export function bouleMailWanted(org, recorded) {
+    return org.mail.mode === 'hosted' && Boolean(recorded[MAIL_DOMAIN_RECORDED_KEY]);
+}
+/**
+ * Boule's `MAIL_FROM`: the org's no-reply address on its recorded mail
+ * domain. The local part falls back to `DEFAULT_NO_REPLY_LOCAL_PART`, the
+ * same default the hosted app's `MAIL_FROM` uses and the store column holds.
+ */
+export function bouleMailFrom(org, mailDomain) {
+    return `${org.mail.noReplyLocalPart || DEFAULT_NO_REPLY_LOCAL_PART}@${mailDomain}`;
+}
+/**
+ * Whether the live Boule's mail token needs writing: it holds none, or the
+ * org's hosted app holds a different one (the app's token wins). Compares
+ * values in memory only; the result names nothing secret.
+ */
+export function bouleMailTokenDrift(liveToken, appToken) {
+    return !liveToken || (Boolean(appToken) && appToken !== liveToken);
+}
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -46,6 +75,8 @@ export const BOULE_MANAGED_ENV_KEYS = [
     'BOULE_ORG_NAME',
     'AUTHZ_BOOTSTRAP_OPERATOR',
     'ARCHON_URL',
+    'MAIL_FROM',
+    BOULE_MAIL_TOKEN_ENV,
 ];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
@@ -64,11 +95,15 @@ export const BOULE_MANAGED_ENV_KEYS = [
  * absent: Boule has no platform wired in every test and every org-only
  * caller, same as `issuer` before #177.
  *
+ * `mailWanted` (see {@link bouleMailWanted}) adds `MAIL_FROM`. The Lettermint
+ * token is never here: it is a secret the executor writes and the plan
+ * compares in memory ({@link bouleMailTokenDrift}).
+ *
  * Not here, and written by the executor instead: the database URLs
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export function desiredBouleEnv(org, recorded, issuer, archonUrl) {
+export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false) {
     const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
     const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
     const missing = [];
@@ -96,6 +131,9 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl) {
         : undefined;
     if (ownerUserId)
         env.AUTHZ_BOOTSTRAP_OPERATOR = ownerUserId;
+    const mailDomain = recorded[MAIL_DOMAIN_RECORDED_KEY];
+    if (mailWanted && mailDomain)
+        env.MAIL_FROM = bouleMailFrom(org, mailDomain);
     return { env, missing };
 }
 /** The `AUTH_APPS` name of an org's Boule broker entry, and the scope key suffix it records under. */

package/dist/plan/diff.js

@@ -1,7 +1,7 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
-import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { chatInternalNames } from './chat-matrix.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -398,7 +398,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const bouleGuarded = guardApp(bouleClient);
     if (bouleGuarded)
         plannedSteps.push(bouleGuarded);
-    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null);
+    const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness);
     if (boule.step)
         plannedSteps.push(boule.step);
     // After the apps and Boule -- an edge key needs its app recorded or planned,
@@ -468,6 +468,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         unmanaged.push({ description: agora.blocked, key: 'coolify:agora' });
     if (boule.blocked)
         unmanaged.push({ description: boule.blocked, key: 'coolify:boule' });
+    if (boule.mailBlocked) {
+        unmanaged.push({ description: boule.mailBlocked, key: 'coolify:boule:mail' });
+    }
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -2027,7 +2030,7 @@ function planBouleClient(org, byKey, claimed) {
  * address (the one Agora signs in at); without it the Boule is blocked, not
  * planned, so every other step still applies.
  */
-function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl) {
+function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonUrl, readiness) {
     const key = resourceKey('coolify', 'boule', org.id);
     const live = byKey.get(key);
     if (live)
@@ -2042,26 +2045,59 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
     if (tooLong.length > 0) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
         };
     }
     if (otherSlugs.includes(`${org.slug}-boule`)) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: another declared org has the slug '${org.slug}-boule', which is this Boule's hostname`,
         };
     }
     if (!issuer) {
         return {
             step: null,
+            mailBlocked: null,
             blocked: `${org.slug}'s Boule is blocked, not planned: the host supplies no issuer`,
         };
     }
+    // Mail env, only for a hosted-mail org whose domain is recorded. Blocked,
+    // not failing: while the platform cannot yet supply the token, Boule is
+    // planned without mail and keeps showing the invite link.
+    const mailWanted = bouleMailWanted(org, recordedIds);
+    const mailDomain = recordedIds.mail_domain?.toLowerCase();
+    const isApexOrg = Boolean(mailDomain && readiness.platformApex && mailDomain === readiness.platformApex.toLowerCase());
+    let mailBlockedReason = null;
+    if (mailWanted && isApexOrg) {
+        if (!readiness.platformLettermintProjectId) {
+            mailBlockedReason = 'platform.mail.lettermintProjectId is not declared yet';
+        }
+        else if (readiness.mailKeyHeld !== true) {
+            mailBlockedReason = `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`;
+        }
+    }
+    else if (mailWanted) {
+        mailBlockedReason = edgeNeeded(readiness, ['zones', 'dns']);
+    }
+    const mailBlocked = mailBlockedReason
+        ? `${org.slug}'s Boule mail is blocked, not planned: ${mailBlockedReason}`
+        : null;
+    const mailOn = mailWanted && !mailBlocked;
     const action = {
         system: 'coolify',
         kind: 'boule',
         key: org.id,
-        desired: { issuer, archonUrl },
+        // The platform values go in like the app step's: the executor writes
+        // what the plan showed and refuses a plan that carries no `platformApex`.
+        desired: {
+            issuer,
+            archonUrl,
+            platformApex: readiness.platformApex,
+            platformLettermintProjectId: readiness.platformLettermintProjectId,
+            mailBlocked: mailBlocked !== null,
+        },
     };
     if (!live) {
         return {
@@ -2070,13 +2106,19 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
                 step: { description: `provision ${org.slug}'s Boule`, destroys: false, migrates: false },
             },
             blocked: null,
+            mailBlocked,
         };
     }
     const liveEnv = (live.config.env ?? {});
-    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl);
+    const { env } = desiredBouleEnv(org, recordedIds, issuer, archonUrl, mailOn);
     const drift = bouleEnvDrift(env, liveEnv);
+    // The token is compared, never planned with its value.
+    if (mailOn &&
+        bouleMailTokenDrift(liveEnv[BOULE_MAIL_TOKEN_ENV], live.config.appMailToken)) {
+        drift.push(BOULE_MAIL_TOKEN_ENV);
+    }
     if (drift.length === 0)
-        return { step: null, blocked: null };
+        return { step: null, blocked: null, mailBlocked };
     return {
         step: {
             action,
@@ -2087,6 +2129,7 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
             },
         },
         blocked: null,
+        mailBlocked,
     };
 }
 /**

package/dist/plan/executor.d.ts

@@ -519,7 +519,7 @@ export interface WorkersPort {
 /**
  * One DNS record a Lettermint domain's own response says must be published --
  * `purpose` is Lettermint's own label (`return_path`, `dmarc`, `dkim_legacy`,
- * `dkim_primary`, `dkim_secondary`), replacing Resend's `record` field, from
+ * `dkim_primary`, `dkim_secondary`), replacing the earlier provider's `record` field, from
  * {@link LettermintPort.createDomain}/{@link LettermintPort.getDomain}, the
  * same shape https://lettermint.co/docs/api-reference/team/0.0.1/lettermint-team-openapi.json's
  * `DomainDnsRecordData` documents (`fqdn`/`content` renamed to this port's own
@@ -552,17 +552,17 @@ export interface LettermintProject {
  * has no Lettermint client yet, unlike Coolify/Cloudflare/ZITADEL above, so
  * this port names Lettermint's own REST shapes directly
  * (`.plans/2026-09-28-lettermint-api.md`, its own primary-source citations).
- * Replaces `ResendPort` (#138/#140), trimmed to what `coolifyApp`/`coolifyMail`
+ * Replaces the earlier mail port (#138/#140), trimmed to what `coolifyApp`/`coolifyMail`
  * below actually call.
  *
- * Unlike Resend's per-domain sending key, a Lettermint domain is
+ * Unlike the earlier provider's per-domain sending key, a Lettermint domain is
  * unrestricted by default -- any project in the team could send from it --
  * so a project's own domain access is a separate call
  * ({@link restrictDomainToProjects}), and the credential unit is a *project*,
  * not a per-domain key: Lettermint's API mints, at most, one live token per
  * project and has no call to list or revoke an individual token within one
  * (`.plans/2026-09-28-lettermint-api.md` §4), so `<slug>-app` is a project
- * name, never suffixed with a domain id the way Resend's key name was.
+ * name, never suffixed with a domain id the way the earlier provider's key name was.
  */
 export interface LettermintPort {
     /**
@@ -585,7 +585,7 @@ export interface LettermintPort {
     /**
      * Asks Lettermint to re-check DNS now. Never polled or awaited to
      * completion -- the same "do not block the plan on DNS propagation" rule
-     * `ResendPort.verifyDomain` followed: record the status, and let the next
+     * the earlier mail port followed: record the status, and let the next
      * apply re-check it.
      */
     verifyDomain(id: string): Promise<{
@@ -1957,9 +1957,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * domain restricted to them before any old project is deleted, so the
      * restriction list never becomes empty.
      *
+     * #654: the non-platform-apex part now lives in {@link ensureOrgAppMailToken},
+     * shared with Boule, which holds the same token; the rule below is its rule
+     * with the consumers read from the hosted app and Boule.
+     *
      * Mint rule ("Credential model"): the project is healthy when the app env
      * holds `LETTERMINT_API_TOKEN` and Lettermint lists exactly one project
-     * named `<slug>-app` -- unlike Resend's key, a Lettermint project's name
+     * named `<slug>-app` -- unlike the earlier provider's key, a Lettermint project's name
      * carries no domain id, since a domain switch is handled entirely by
      * {@link LettermintPort.restrictDomainToProjects} below and never needs a
      * fresh project. Otherwise a fresh project is created and its token
@@ -2003,6 +2007,31 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * this field existed (review round 2, finding 3).
      */
     private ensureAppLettermintMail;
+    /**
+     * The one mint rule for the org's `<slug>-app` Lettermint token, shared by
+     * the hosted app (`ensureAppLettermintMail`) and Boule
+     * (`ensureBouleMail`), which hold the same token. Lettermint shows a
+     * token once, so the token lives only in those apps' envs: the rule reads
+     * every consumer that is recorded (the hosted app first, Boule second).
+     * The project is healthy when Lettermint lists exactly one `<slug>-app`
+     * project and some consumer holds a token. A healthy rule gives `self` that
+     * token (the app's wins) when it lacks it or holds another; a peer gets it
+     * in its own step. An
+     * unhealthy one mints a fresh project and writes its token to every
+     * consumer, restarting those that run, before any other `<slug>-app`
+     * project is deleted. Either role may run first: an app added after Boule
+     * adopts Boule's token instead of deleting its project.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, recorded, logged or interpolated into an error. Returns
+     * whether `self`'s own token changed and whether it was restarted here.
+     *
+     * A peer recorded but gone from Coolify (404) is no consumer. A healthy
+     * company's step writes only its own env; a re-mint writes every live
+     * consumer, restarts the running ones, restricts the domain, then deletes
+     * the old projects.
+     */
+    private ensureOrgAppMailToken;
     /**
      * #149: mints this org's own Lettermint relay credential and writes it to
      * Stalwart via `MailPort.applyOrgRelay`, the same mint rule
@@ -2443,6 +2472,16 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * Gives Boule `LETTERMINT_API_TOKEN`: the platform's held key for an org on
+     * the platform's own apex, else the org's `<slug>-app` token through the
+     * shared mint rule ({@link ensureOrgAppMailToken}), which mints that project
+     * when no hosted app made it yet. `MAIL_FROM` is written with the rest of
+     * Boule's env. Returns whether Boule's token changed, so the caller
+     * restarts a running Boule, unless `restarted`: the shared rule then already
+     * restarted it (`running`), before it deleted the old project.
+     */
+    private ensureBouleMail;
     /**
      * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
      * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the
@@ -2754,7 +2793,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * upsert `publishMailDnsRecords` above uses for Stalwart's own records --
      * except an existing `_dmarc` record is never overwritten (a stricter
      * policy an org already set, `p=quarantine`/`p=reject`, should not be
-     * relaxed back to Lettermint's own default). Resend's own domain also
+     * relaxed back to Lettermint's own default). The earlier provider's domain also
      * carried an apex `SPF` TXT record that had to be merged into whatever SPF
      * record already existed there (RFC 7208: two `v=spf1` TXT records on one
      * name is a permerror); Lettermint's own DNS records