@wtfalch/foundry 0.16.12 → 0.16.14

package/dist/bootstrap/bootstrap.js

@@ -108,7 +108,7 @@ export function guardStepDeps(executor, redactor, deliverSecret, heldKeys) {
         // #201: ai's own default minter needs heldKeys too, to re-sign a mint
         // request against its signing key when an earlier run pinned it but
         // crashed before the management key itself was minted and delivered.
-        if (key === 'archon' || key === 'ai' || 'heldKeys' in copy)
+        if (key === 'archon' || key === 'ai' || key === 'auth' || 'heldKeys' in copy)
             copy.heldKeys = heldKeys;
         out[key] = copy;
     }

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

@@ -125,6 +125,18 @@ export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_
  * between is repaired by the next one.
  */
 export declare const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = "archon_gate_closed";
+/**
+ * The ZITADEL SMTP provider (Lettermint) `provisionPlatformAuth` configured on
+ * the platform's instance, recorded as the provider id. Without it ZITADEL
+ * cannot send the owner's invite, so a platform applied before it existed
+ * plans the auth step again.
+ */
+export declare const PLATFORM_AUTH_SMTP_SCOPE_KEY = "zitadel_platform_smtp_provider_id";
+/**
+ * The platform owner's ZITADEL user id, recorded once the invite email was
+ * 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";
 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. */

package/dist/plan/platform-diff.js

@@ -145,6 +145,18 @@ export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_a
  * between is repaired by the next one.
  */
 export const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = 'archon_gate_closed';
+/**
+ * The ZITADEL SMTP provider (Lettermint) `provisionPlatformAuth` configured on
+ * the platform's instance, recorded as the provider id. Without it ZITADEL
+ * cannot send the owner's invite, so a platform applied before it existed
+ * plans the auth step again.
+ */
+export const PLATFORM_AUTH_SMTP_SCOPE_KEY = 'zitadel_platform_smtp_provider_id';
+/**
+ * The platform owner's ZITADEL user id, recorded once the invite email was
+ * requested, so the invite goes out once. `none` when no owner is declared.
+ */
+export const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_owner_invite_user_id';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export 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. */
@@ -1021,7 +1033,7 @@ function planSfu(platform) {
  * #211 round 2: a recorded broker id is not the same as a *deployed* broker
  * ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY}) -- `provisionPlatformAuth`
  * creates and records the app before it has `ZITADEL_SERVICE_USER_TOKEN`/
- * `RESEND_API_TOKEN` to deploy it with (#209, #210). So this still plans the
+ * `LETTERMINT_API_TOKEN` to deploy it with (#209, #210). So this still plans the
  * step again while the broker sits undeployed: `executorBlocked` (from
  * `authBrokerBlockedReason`) reports it blocked, by name, for as long as the
  * inputs stay missing, and the moment they arrive the same replanned step
@@ -1131,6 +1143,10 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         brokerApplied &&
         brokerDeployed &&
         loginClientApplied &&
+        // Mail and the owner's invite: a platform applied before they existed
+        // plans the step again, which only adds them.
+        Boolean(recordedIds[PLATFORM_AUTH_SMTP_SCOPE_KEY]) &&
+        Boolean(recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) &&
         // The ZITADEL run options reach the container only through the auth
         // step's redeploy, so a platform recorded before them still plans it.
         recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {

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

@@ -13,13 +13,32 @@ import { type CallsSfuPlatformDeps } from './platform-sfu.js';
  * positions, so every #167-era caller of {@link FoundryPlatformStepExecutor}
  * (zone only) keeps compiling with this third argument simply omitted.
  */
+/**
+ * The SMTP call `provisionPlatformAuth` makes on the instance's ZITADEL.
+ * `@wtfalch/providers` gains it in 0.7.2; stated here so foundry compiles
+ * against 0.7.1 and tests use fakes.
+ */
+export interface PlatformZitadelSmtp {
+    ensureSmtpProvider(config: {
+        host: string;
+        user: string;
+        password: string;
+        senderAddress: string;
+        senderName: string;
+        tls: boolean;
+        description: string;
+    }): Promise<{
+        id: string;
+        changed: boolean;
+    }>;
+}
 export interface PlatformAuthDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'
     /** #197: fetches the tunnel's connector token for {@link ensureCloudflaredConnector}. */
      | 'getTunnelToken'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
-    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'inviteOrgOwner'> & PlatformZitadelSmtp;
     /**
      * Builds the ZITADEL port for the new instance from its issuer URL
      * (`https://<auth.hostname>`). When set it is used instead of
@@ -28,6 +47,19 @@ export interface PlatformAuthDeps {
      */
     zitadelForInstance?: (issuerUrl: string) => PlatformAuthDeps['zitadel'];
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /**
+     * #210: reads back the broker's Lettermint mail key, held under
+     * {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF}. Never minted here -- unlike
+     * the login-client token above, foundry has no Lettermint account of its
+     * own to mint one from, so this only ever reads back a value a human (or
+     * Archon's own onboarding) put there directly once Lettermint issued it.
+     * Absent, or with nothing held under that ref yet, `LETTERMINT_API_TOKEN`
+     * stays a gap `missingBrokerInputs` reports by name, the same "blocked,
+     * not failing" every other unmet broker input already follows.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
     /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
     runtime?: PlatformAuthRuntime;
 }
@@ -185,7 +217,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly ai?;
     private readonly archon?;
     private readonly backup?;
-    constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list'>, options?: FoundryPlatformStepExecutorOptions);
+    constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list' | 'get'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
         authExecutorMissing?: boolean;
@@ -234,6 +266,15 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
  * key delivered under `zitadel:platform:admin`.
  */
 export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:instanceBearer";
+/**
+ * #210: the ref the broker's Lettermint mail key is held under. Unlike every
+ * other `_REF` in this file, nothing here ever delivers a value under it --
+ * {@link PlatformAuthDeps.heldKeys} only reads it back, once a human (or
+ * Archon's own onboarding) puts it there directly with the key Lettermint
+ * issued, on one allowed to send from every app's domain
+ * (`wtfalch/auth/docs/deploy.md`).
+ */
+export declare const PLATFORM_AUTH_BROKER_MAIL_KEY_REF = "lettermint:platform:apiToken";
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,
@@ -591,13 +632,14 @@ export declare function createAiManagementKeyMinter(options: {
 }): AiManagementKeyMinter;
 /**
  * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
- * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
- * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
- * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
- * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
- * recorded scope id: whichever of #209/#210 lands first (or a human, setting
- * either directly on the app) is enough to clear that one input, in either
- * order, with no coupling to this step's own execution.
+ * `broker/server.ts`) refuses to start without -- `ZITADEL_SERVICE_USER_TOKEN`/
+ * `_FILE` (#209 mints and pushes this once it lands) and `LETTERMINT_API_TOKEN`
+ * (#210: `wtfalch/auth#138` moved the broker's account mail onto
+ * `@wtfalch/mailer`'s Lettermint transport, so this is the env name the
+ * broker actually reads now, not `RESEND_API_TOKEN`). Read from the broker's
+ * own live env, not a recorded scope id: whichever of #209/#210 lands first
+ * (or a human, setting either directly on the app) is enough to clear that
+ * one input, in either order, with no coupling to this step's own execution.
  *
  * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
  * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array

package/dist/plan/platform-providers.js

@@ -6,7 +6,7 @@ import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { ACCESS_POLICY_NAME, getDatabaseStarted, isNotFoundError, isRunningOrStarting, } from './executor.js';
 import { coolifyDomains } from './hostnames.js';
-import { AUTH_ZITADEL_RUN_OPTIONS, JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_RUNNER_DEPLOYMENT_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { AUTH_ZITADEL_RUN_OPTIONS, JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_RUNNER_DEPLOYMENT_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
@@ -302,7 +302,8 @@ export class FoundryPlatformStepExecutor {
             if (!this.auth) {
                 throw new Error('platform:auth needs FoundryPlatformStepExecutor to be constructed with its auth dependencies (#168)');
             }
-            return provisionPlatformAuth(context, this.auth);
+            const company = await this.declaredOrgStore.get(context.platform.ownerOrgId);
+            return provisionPlatformAuth(context, this.auth, company?.owners ?? []);
         }
         if (action.system === 'coolify' && action.kind === 'app' && action.key === PLATFORM_FILES_KEY) {
             if (!this.files) {
@@ -577,6 +578,15 @@ const PLATFORM_AUTH_ORG_NAME = 'foundry';
  */
 export const PLATFORM_AUTH_INSTANCE_BEARER_REF = 'zitadel:platform:instanceBearer';
 const PLATFORM_AUTH_BEARER_USER_NAME = 'foundry-instance-owner';
+/**
+ * #210: the ref the broker's Lettermint mail key is held under. Unlike every
+ * other `_REF` in this file, nothing here ever delivers a value under it --
+ * {@link PlatformAuthDeps.heldKeys} only reads it back, once a human (or
+ * Archon's own onboarding) puts it there directly with the key Lettermint
+ * issued, on one allowed to send from every app's domain
+ * (`wtfalch/auth/docs/deploy.md`).
+ */
+export const PLATFORM_AUTH_BROKER_MAIL_KEY_REF = 'lettermint:platform:apiToken';
 /**
  * Retries `action` up to `attempts` times, sleeping increasingly between
  * tries -- the same shape the admin machine user's own delivery retry (just
@@ -811,10 +821,15 @@ async function liveLoginClientTokenHash(coolify, appId) {
  *   `IAM_LOGIN_CLIENT` machine user (never the admin one, which is
  *   `IAM_OWNER`) and delivers its token to both apps, once the broker's
  *   other required inputs are already met.
- * - The broker never receives `RESEND_API_TOKEN` either, so it will not start
- *   on `AUTH_APPS` alone. `wtfalch/auth#138` moves the broker's account mail
- *   onto held keys and `@wtfalch/mailer`; until that lands there is no held
- *   key to read here, so this stays a plain gap rather than a wired value.
+ * - ~~The broker never receives `RESEND_API_TOKEN` either, so it will not
+ *   start on `AUTH_APPS` alone.~~ Closed by #210, once `wtfalch/auth#138`
+ *   moved the broker's account mail onto `@wtfalch/mailer`'s Lettermint
+ *   transport: this function now reads the key back from
+ *   {@link PlatformAuthDeps.heldKeys} under
+ *   {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} and pushes it as
+ *   `LETTERMINT_API_TOKEN`, once a human (or Archon's own onboarding) has
+ *   put one there. Still a gap until then, the same "blocked, not failing"
+ *   way an unset `AUTH_APPS` already is.
  * - `AUTH_APPS` starts unset: the broker has nothing to serve until a
  *   platform app registers with it ({@link provisionPlatformArchon} is the
  *   first), so it will not start (`parseApps` throws on an empty list) until
@@ -842,7 +857,7 @@ async function liveLoginClientTokenHash(coolify, appId) {
  * #197: a `cloudflared` connector for this tunnel is run
  * ({@link ensureCloudflaredConnector}), so `hostname` answers.
  */
-async function provisionPlatformAuth(context, deps) {
+async function provisionPlatformAuth(context, deps, owners = []) {
     const { platform } = context;
     const hostname = platform.auth.hostname;
     const gitRef = platform.auth.gitRef;
@@ -1043,14 +1058,24 @@ async function provisionPlatformAuth(context, deps) {
         { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
         { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
     ];
-    // `AUTH_APPS`, `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN`
-    // are not pushed here -- this function's own doc comment, "Known gaps".
+    // #210: read back now, not inside the deploy-decision block below -- this
+    // push has to land before `missingBrokerInputs` is read a few lines down,
+    // the same way `envsDiffer`/`bulkUpsertEnvs` below already do for every
+    // other broker env, so a single apply that finds the key already held can
+    // also see `LETTERMINT_API_TOKEN` as met and deploy in that same run.
+    const heldMailKey = await deps.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF);
+    // `AUTH_APPS` and `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` are not pushed here
+    // -- this function's own doc comment, "Known gaps". `LETTERMINT_API_TOKEN`
+    // is, once held (#210): pushing it costs nothing even while the broker
+    // still cannot start on the other two, and the deploy decision below stays
+    // gated on `missingBrokerInputs` regardless.
     const brokerEnvs = [
         {
             key: 'ZITADEL_API_URL',
             value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
         },
         { key: 'ZITADEL_DOMAIN', value: hostname },
+        ...(heldMailKey ? [{ key: 'LETTERMINT_API_TOKEN', value: heldMailKey }] : []),
     ];
     // Compared before the write: an env change only reaches a running
     // container on its next deploy (`diff.ts`'s `coolifyCalls` follows the
@@ -1074,11 +1099,11 @@ async function provisionPlatformAuth(context, deps) {
         await deps.coolify.deploy(loginAppId);
     }
     // #211: the broker's own `server.ts` refuses to start without
-    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN` -- deploying
-    // it without them only produces a container that crash-loops behind
-    // `/api`. The app is still created and recorded above either way, so #209
-    // and #210 (or a human, directly) have something to push the env onto;
-    // only the deploy waits.
+    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `LETTERMINT_API_TOKEN` --
+    // deploying it without them only produces a container that crash-loops
+    // behind `/api`. The app is still created and recorded above either way,
+    // so #209 and #210 (or a human, directly) have something to push the env
+    // onto; only the deploy waits.
     // #211 round 5: `brokerDeployNeeded` is its own reason to deploy (not only
     // alongside justCreated/running/envsChanged, none of which this function's
     // own `brokerEnvs` write above ever touches `AUTH_APPS`): it is what
@@ -1262,7 +1287,7 @@ async function provisionPlatformAuth(context, deps) {
     // envs, then redeploys both.
     //
     // Deferred, not blocked, while the broker's other required inputs
-    // (`RESEND_API_TOKEN`, `AUTH_APPS`) are still missing (composing with
+    // (`LETTERMINT_API_TOKEN`, `AUTH_APPS`) are still missing (composing with
     // #211's own gating): minting and delivering here would only redeploy a
     // broker that still refuses to start on the other missing input, spending
     // a mint and two deploys on nothing this apply can fix. `blockedSteps`'s
@@ -1379,8 +1404,62 @@ async function provisionPlatformAuth(context, deps) {
         // own doc comment, and `authLoginClientDrifted`'s, for why.
         await record(PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, loginClientRecordValue(loginClientUserId, loginClientPatId, loginClientToken));
     }
+    // ---- ZITADEL mail and the owner's invite ----------------------------------
+    // The token is the held key, else the broker's live env. Absent, nothing
+    // here can run; `authBrokerBlockedReason` already reports it by name.
+    const mailToken = heldMailKey || (await currentEnvValue(deps.coolify, brokerAppId, 'LETTERMINT_API_TOKEN'));
+    if (mailToken) {
+        const mailZitadel = deps.zitadelForInstance?.(`https://${hostname}`) ?? deps.zitadel;
+        try {
+            // Runs every time the step does (idempotent), so a rotated token lands.
+            const smtp = await mailZitadel.ensureSmtpProvider({
+                host: PLATFORM_AUTH_SMTP_HOST,
+                user: PLATFORM_AUTH_SMTP_USER,
+                password: mailToken,
+                senderAddress: `noreply@${platform.apex}`,
+                senderName: PLATFORM_AUTH_MAIL_SENDER_NAME,
+                tls: true,
+                description: PLATFORM_AUTH_SMTP_DESCRIPTION,
+            });
+            await record(PLATFORM_AUTH_SMTP_SCOPE_KEY, smtp.id);
+        }
+        catch {
+            throw new Error(`platform:auth: could not configure ZITADEL's SMTP provider for ${hostname}; the cause is left out because it can carry the Lettermint key`);
+        }
+        if (!context.recordedIds()[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) {
+            const owner = owners[0];
+            if (!owner) {
+                // No owner declared: nothing to invite. Recorded so the step is not replanned for it.
+                await record(PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, 'none');
+            }
+            else {
+                const ownerOrgId = context.recordedIds()[PLATFORM_ZITADEL_ORG_SCOPE_KEY] ??
+                    (await mailZitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME)).org.id;
+                await record(PLATFORM_ZITADEL_ORG_SCOPE_KEY, ownerOrgId);
+                let invitedUserId;
+                try {
+                    ({ userId: invitedUserId } = await mailZitadel.inviteOrgOwner(ownerOrgId, {
+                        givenName: owner.givenName,
+                        familyName: owner.familyName,
+                        email: owner.email,
+                    }));
+                }
+                catch {
+                    throw new Error(`platform:auth: could not invite the platform owner into ZITADEL org ${ownerOrgId}; the cause is left out because it can carry the owner's email`);
+                }
+                await record(PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, invitedUserId);
+            }
+        }
+    }
     return { resourceId: zitadelAppId };
 }
+/** Lettermint's SMTP relay, as ZITADEL's SMTP provider wants it: `host:port`, STARTTLS. */
+const PLATFORM_AUTH_SMTP_HOST = 'smtp.lettermint.co:587';
+const PLATFORM_AUTH_SMTP_USER = 'lettermint';
+/** Marks the provider as foundry's, so `ensureSmtpProvider` finds it again. */
+const PLATFORM_AUTH_SMTP_DESCRIPTION = 'foundry:platform:lettermint';
+/** The same name the broker's `from` uses (`Company Included <noreply@apex>`). */
+const PLATFORM_AUTH_MAIL_SENDER_NAME = 'Company Included';
 // ---------------------------------------------------------------------------
 // #169: the platform's own mail server (Stalwart)
 // ---------------------------------------------------------------------------
@@ -1967,12 +2046,12 @@ async function mailBlockedReason(platform, mail, recordedIds) {
 }
 /**
  * #211: the broker cannot start without `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`,
- * `RESEND_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already skips
- * deploying the broker while any is missing ({@link missingBrokerInputs});
- * this is the same check surfaced through `blockedSteps`, so a plan says
- * why, by name, rather than the broker simply sitting undeployed with no
- * explanation. `null` while there is no broker app id recorded yet (nothing
- * to check) or every input is present.
+ * `LETTERMINT_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already
+ * skips deploying the broker while any is missing
+ * ({@link missingBrokerInputs}); this is the same check surfaced through
+ * `blockedSteps`, so a plan says why, by name, rather than the broker simply
+ * sitting undeployed with no explanation. `null` while there is no broker
+ * app id recorded yet (nothing to check) or every input is present.
  *
  * #211 round 3: wraps the live read the way {@link mailBlockedReason} wraps
  * its own Coolify call -- a transient `listEnvs` failure must report a
@@ -1986,6 +2065,21 @@ async function mailBlockedReason(platform, mail, recordedIds) {
  * go fix an entry, not merely wait for one of #209/#210/Archon's own
  * registration to supply one), and reporting it identically hid which one
  * was true.
+ *
+ * #210: `LETTERMINT_API_TOKEN` joins `ZITADEL_SERVICE_USER_TOKEN` in being
+ * excluded from `otherInputsMissing` -- but only while `auth.heldKeys`
+ * actually resolves {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} right now.
+ * `planAuth`'s own "loop fix" stops planning this step the moment every
+ * `otherInputsMissing` entry looks like something only another run can
+ * supply; excluding `LETTERMINT_API_TOKEN` unconditionally (the way
+ * `ZITADEL_SERVICE_USER_TOKEN` is, since foundry can always eventually mint
+ * that one) would keep the step planned, and `provisionPlatformAuth`
+ * running its full body, forever on a host that never wires `heldKeys` or
+ * whose operator has not put a Lettermint key there yet -- exactly the
+ * wasteful-replan bug #211 round 5 fixed for the broker deploy itself. Once
+ * the key *is* held, excluding it lets this run's `provisionPlatformAuth`
+ * push it (see that function's own `heldMailKey` read) and clears the gap
+ * for good.
  */
 async function authBrokerBlockedReason(auth, recordedIds) {
     const brokerAppId = recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
@@ -1993,9 +2087,11 @@ async function authBrokerBlockedReason(auth, recordedIds) {
         return { reason: null, otherInputsMissing: [] };
     let missing;
     let authAppsRaw;
+    let heldMailKey;
     try {
         missing = await missingBrokerInputs(auth.coolify, brokerAppId);
         authAppsRaw = await currentEnvValue(auth.coolify, brokerAppId, 'AUTH_APPS');
+        heldMailKey = (await auth.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) ?? null;
     }
     catch {
         return {
@@ -2007,13 +2103,19 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     }
     // #216 round 5: what `provisionPlatformAuth`'s own `loginClientOtherInputsMissing`
     // gate is -- see `planAuth`'s own doc comment for why it needs this too.
-    const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN');
+    // #210: and `LETTERMINT_API_TOKEN`, once held -- see this function's own
+    // doc comment.
+    const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN' && !(m === 'LETTERMINT_API_TOKEN' && heldMailKey));
     if (missing.length === 0)
         return { reason: null, otherInputsMissing };
+    // #210: say where the operator seals the Lettermint key, not only its env name.
+    const named = (names) => names.map((m) => m === 'LETTERMINT_API_TOKEN'
+        ? `LETTERMINT_API_TOKEN (seal it under the held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`
+        : m);
     if (authAppsProblem(authAppsRaw, brokerAppId) === 'malformed') {
         const otherMissing = missing.filter((m) => m !== 'AUTH_APPS');
         const otherSuffix = otherMissing.length > 0
-            ? `, and it has no ${otherMissing.join(' and no ')} yet (#209, #210)`
+            ? `, and it has no ${named(otherMissing).join(' and no ')} yet (#209, #210)`
             : '';
         return {
             reason: `the platform's sign-in broker ${brokerAppId} is blocked, not deployed: its AUTH_APPS is malformed${otherSuffix}`,
@@ -2024,7 +2126,7 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     // those issues when one of them is actually among what's missing.
     const suffix = missing.some((m) => m !== 'AUTH_APPS') ? ' (#209, #210)' : '';
     return {
-        reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${missing.join(' and no ')} yet${suffix}`,
+        reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${named(missing).join(' and no ')} yet${suffix}`,
         otherInputsMissing,
     };
 }
@@ -2197,8 +2299,8 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  * `provisionPlatformAuth` guarantees by the time this step is reachable (its
  * own resourceId records only once the broker app exists too). The broker
  * will not actually be able to serve a request with this key until
- * `provisionPlatformAuth`'s own "Known gaps" (`ZITADEL_SERVICE_USER_TOKEN`,
- * `RESEND_API_TOKEN`) are closed; wiring the key here is still correct and
+ * `provisionPlatformAuth`'s own `ZITADEL_SERVICE_USER_TOKEN` is minted and
+ * `LETTERMINT_API_TOKEN` is held; wiring the key here is still correct and
  * needed so the two apps agree the moment the broker can run.
  *
  * Known gaps, left for review:
@@ -2486,8 +2588,8 @@ async function provisionPlatformArchon(context, deps) {
         await deps.coolify.bulkUpsertEnvs(brokerAppId, desiredAuthApps);
     }
     // #211 round 2: deploying the broker before its own `server.ts` can start
-    // (missing `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` or `RESEND_API_TOKEN`, #209,
-    // #210) only produces a container that crash-loops behind `/api` -- the
+    // (missing `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` or `LETTERMINT_API_TOKEN`,
+    // #209, #210) only produces a container that crash-loops behind `/api` -- the
     // same rule `provisionPlatformAuth` follows for its own deploy of this
     // app. The env is still written either way, so the broker serves the new
     // registration the moment it is next deployed, by either step.
@@ -3987,13 +4089,14 @@ async function findOrCreatePlatformApp(coolify, name, environment, create) {
 }
 /**
  * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
- * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
- * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
- * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
- * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
- * recorded scope id: whichever of #209/#210 lands first (or a human, setting
- * either directly on the app) is enough to clear that one input, in either
- * order, with no coupling to this step's own execution.
+ * `broker/server.ts`) refuses to start without -- `ZITADEL_SERVICE_USER_TOKEN`/
+ * `_FILE` (#209 mints and pushes this once it lands) and `LETTERMINT_API_TOKEN`
+ * (#210: `wtfalch/auth#138` moved the broker's account mail onto
+ * `@wtfalch/mailer`'s Lettermint transport, so this is the env name the
+ * broker actually reads now, not `RESEND_API_TOKEN`). Read from the broker's
+ * own live env, not a recorded scope id: whichever of #209/#210 lands first
+ * (or a human, setting either directly on the app) is enough to clear that
+ * one input, in either order, with no coupling to this step's own execution.
  *
  * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
  * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array
@@ -4011,8 +4114,8 @@ export async function missingBrokerInputs(coolify, brokerAppId) {
     if (!has('ZITADEL_SERVICE_USER_TOKEN') && !has('ZITADEL_SERVICE_USER_TOKEN_FILE')) {
         missing.push('ZITADEL_SERVICE_USER_TOKEN');
     }
-    if (!has('RESEND_API_TOKEN'))
-        missing.push('RESEND_API_TOKEN');
+    if (!has('LETTERMINT_API_TOKEN'))
+        missing.push('LETTERMINT_API_TOKEN');
     if (authAppsProblem(value('AUTH_APPS'), brokerAppId) !== null)
         missing.push('AUTH_APPS');
     return missing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.16.12",
+  "version": "0.16.14",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
     "@wtfalch/audit": "0.6.0",
     "@wtfalch/auth": "0.16.0",
     "@wtfalch/email": "^0.17.0",
-    "@wtfalch/providers": "0.6.0",
+    "@wtfalch/providers": "0.7.2",
     "ssh2": "1.17.0",
     "zod": "4.6.5"
   },