@wtfalch/foundry 0.16.13 → 0.16.14

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. */
@@ -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
@@ -198,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;

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) {
@@ -856,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;
@@ -1403,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)
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.16.13",
+  "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"
   },