@wtfalch/foundry 0.55.0 → 0.56.0

package/dist/plan/diff.d.ts

@@ -101,6 +101,8 @@ export interface PlanOrgOptions {
     workerAppDbBackupConfigured?: boolean;
     /** The executor can store the sign-in database's CA and certificate (`FoundryStepExecutor.ownSigninDbKeysPuttable`). Absent: true. */
     ownSigninDbKeysPuttable?: boolean;
+    /** The executor's company ZITADEL port can write the sign-in mail (`FoundryStepExecutor.ownSigninMailWritable`). Absent: true. */
+    ownSigninMailWritable?: boolean;
     /** The host supplies the backup bucket the sign-in database dumps into (`FoundryStepExecutor.ownSigninDbBackupConfigured`). Absent: true. */
     ownSigninDbBackupConfigured?: boolean;
     /** The own jobs admin token's held-key ref holds a value. */

package/dist/plan/diff.js

@@ -214,6 +214,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         now: (options.now ?? Date.now)(),
         signinDbKeysPuttable: options.ownSigninDbKeysPuttable ?? true,
         signinDbBackupConfigured: options.ownSigninDbBackupConfigured ?? true,
+        signinMailWritable: options.ownSigninMailWritable ?? true,
     });
     if (ownAuth.step)
         plannedSteps.push(ownAuth.step);

package/dist/plan/executor.d.ts

@@ -2021,6 +2021,11 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     bouleArchonCredentialAvailable(): boolean;
     /** Whether the held keys can store a new company's sign-in database CA and certificate (#746). */
     ownSigninDbKeysPuttable(): boolean;
+    /**
+     * Whether the host says its company ZITADEL port has `ensureEmailOtpMessageText` and `ensureLabelPolicy`
+     * (`provision.auth.signinMailWritable`). The port is a lazy proxy that answers any name, so it cannot be probed.
+     */
+    ownSigninMailWritable(): boolean;
     /** Whether the held keys can store a Worker app database's CA and certificate. */
     workerAppDbKeysPuttable(): boolean;
     /** Whether the host supplies the backup bucket a Worker app database dumps into (the files host's bucket and key ports). */

package/dist/plan/executor.js

@@ -1013,6 +1013,13 @@ export class FoundryStepExecutor {
     ownSigninDbKeysPuttable() {
         return Boolean(this.ports.ownServices?.provision.auth.heldKeys?.put);
     }
+    /**
+     * Whether the host says its company ZITADEL port has `ensureEmailOtpMessageText` and `ensureLabelPolicy`
+     * (`provision.auth.signinMailWritable`). The port is a lazy proxy that answers any name, so it cannot be probed.
+     */
+    ownSigninMailWritable() {
+        return this.ports.ownServices?.provision.auth.signinMailWritable === true;
+    }
     /** Whether the held keys can store a Worker app database's CA and certificate. */
     workerAppDbKeysPuttable() {
         return typeof this.ports.heldKeys?.put === 'function';
@@ -7342,6 +7349,7 @@ export class FoundryStepExecutor {
             // empty; the login-host step writes it once the apps' clients exist.
             ...(inAppSignIn(org) ? { signInLogin: { bindings: null } } : {}),
             mcp: orgDeclaresMcp(org),
+            mailBranding: { companyName: org.displayName },
         });
         if (refChanged) {
             const now = scope.recordedIds();

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

@@ -51,6 +51,8 @@ export interface PlanOwnAuthOptions {
     signinDbKeysPuttable?: boolean;
     /** The host supplies the backup bucket the sign-in database dumps into. Default true. */
     signinDbBackupConfigured?: boolean;
+    /** The host's ZITADEL port can write the sign-in mail text and look. Default true. False: the marker is not required. */
+    signinMailWritable?: boolean;
 }
 /**
  * An own org (`services.own`) runs its own sign-in: ZITADEL, the login app

package/dist/plan/own-diff.js

@@ -17,6 +17,7 @@ import { SIGN_IN_LOGIN_APP_SCOPE_KEY, inAppSignIn } from './sign-in.js';
 import { signinDbBackupMissing } from './signin-db-backup.js';
 import { SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY, signinDbCertDue } from './signin-db-tls.js';
 import { SIGNIN_DB_TLS_SCOPE_KEY } from './signin-db.js';
+import { PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY, signinMailMarker } from './signin-mail.js';
 /** `unmanaged` key of the one line `planOwnJobs` reports. */
 export const OWN_JOBS_BLOCKED_KEY = 'own-jobs';
 /**
@@ -163,6 +164,9 @@ export function planOwnAuth(options) {
         recordedIds[PLATFORM_AUTH_SMTP_SCOPE_KEY] &&
         recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
         recordedIds[PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY] === AUTH_TUNNEL_ROUTES_VERSION &&
+        // The code mail carries the company's name and design; an older apply, or a renamed company, writes it again.
+        (options.signinMailWritable === false ||
+            recordedIds[PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY] === signinMailMarker(org.displayName)) &&
         // An entry with `mcp` needs the broker's database and secret (auth ADR 0002).
         (!orgDeclaresMcp(org) || recordedIds[PLATFORM_AUTH_MCP_SCOPE_KEY] === '1') &&
         (Boolean(recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY]) || !brokerHoldsAnEntry) &&
@@ -175,7 +179,15 @@ export function planOwnAuth(options) {
         !signinDbBackupMissing(recordedIds) &&
         // ZITADEL was started on the TLS database and never seen healthy there: the step starts it again.
         !recordedIds[SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY]) {
-        return { step: null, blocked: null };
+        // Applied and otherwise done: say why the mail stays ZITADEL's stock text, once.
+        const mailMissing = options.signinMailWritable === false &&
+            recordedIds[PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY] !== signinMailMarker(org.displayName);
+        return {
+            step: null,
+            blocked: mailMissing
+                ? `${org.slug}'s sign-in mail keeps ZITADEL's default text: the host cannot write message texts`
+                : null,
+        };
     }
     return {
         blocked: null,

package/dist/plan/plan-apply.d.ts

@@ -234,6 +234,8 @@ export interface StepExecutor {
     ownSigninDbKeysPuttable?(): boolean;
     /** Whether the host supplies the backup bucket the sign-in database dumps into (#746). Absent: true. */
     ownSigninDbBackupConfigured?(): boolean;
+    /** Whether the host's company ZITADEL port can write the sign-in mail text and look. Absent: true. */
+    ownSigninMailWritable?(): boolean;
     /**
      * Whether the host's scoped ports for this own org include a files-organisation
      * port. The planner plans no `files:organisation` step for an own org while

package/dist/plan/plan-apply.js

@@ -1363,6 +1363,7 @@ export class FoundryPlanApply {
             workerAppDbBackupConfigured: this.executor.workerAppDbBackupConfigured?.() ?? true,
             ownSigninDbKeysPuttable: this.executor.ownSigninDbKeysPuttable?.() ?? true,
             ownSigninDbBackupConfigured: this.executor.ownSigninDbBackupConfigured?.() ?? true,
+            ownSigninMailWritable: this.executor.ownSigninMailWritable?.() ?? true,
             ...(this.backupGate
                 ? {
                     backupStorageUuid: (await this.platformDeps?.store.getServiceIds())?.[PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY] || null,

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

@@ -20,6 +20,7 @@ import type { PlatformDriftedSteps, PlatformStepExecutionContext, PlatformStepEx
 import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platform-diff.js';
 import type { PlatformOwnerInput } from './platform-org.js';
 import type { SigninDbBackupPort } from './signin-db-backup.js';
+import { type PlatformZitadelMailBranding } from './signin-mail.js';
 export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { type PlatformGithubReleaseHookDeps } from './github-release-hook.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
@@ -134,6 +135,12 @@ export interface PlatformAuthSmtp {
     password?: () => Promise<string>;
 }
 export interface PlatformAuthDeps {
+    /**
+     * The host's ZITADEL port can write the sign-in mail text and look (`PlatformZitadelMailBranding`,
+     * `@wtfalch/providers` 0.13.0). Only `true` writes it; otherwise a company keeps ZITADEL's stock text
+     * and the planner reports it. The port may be a proxy that answers any method name, so the host says it.
+     */
+    signinMailWritable?: boolean;
     /** Overrides the Lettermint SMTP relay ZITADEL is given. Absent, Lettermint exactly as before. */
     smtp?: PlatformAuthSmtp;
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'> & 
@@ -150,7 +157,7 @@ export interface PlatformAuthDeps {
     requestHeaders?: PlatformRequestHeadersFactory;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
-    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'enforceSecondFactor' | 'inviteOrgOwner' | 'ensureDomainPolicy' | 'addOrgDomain' | 'removeOrgDomain' | 'setPrimaryOrgDomain' | 'setUserMetadata' | 'getUserMetadata'> & PlatformZitadelSmtp;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'enforceSecondFactor' | 'inviteOrgOwner' | 'ensureDomainPolicy' | 'addOrgDomain' | 'removeOrgDomain' | 'setPrimaryOrgDomain' | 'setUserMetadata' | 'getUserMetadata'> & PlatformZitadelSmtp & Partial<PlatformZitadelMailBranding>;
     /**
      * Mails the owner's first-sign-in link to their personal address (the same
      * port as `FoundryStepExecutorPorts.ownerInviteMail`). The link carries the
@@ -564,6 +571,10 @@ export interface AuthStackInput {
      * database on the sign-in Postgres and `MCP_OAUTH_SECRET` before that entry reaches it. Absent: neither.
      */
     mcp?: boolean;
+    /** A company's own sign-in: the code mail names this company (sender, text) and uses the platform's design. Absent: ZITADEL's stock mail. */
+    mailBranding?: {
+        companyName: string;
+    };
 }
 /**
  * #168: makes `coolify:app` keyed {@link PLATFORM_AUTH_KEY} true -- a Coolify

package/dist/plan/platform-providers.js

@@ -36,6 +36,7 @@ import { ensureSignInOrg, inviteOwnerWithLink, signInOrgDomain } from './sign-in
 import { SIGN_IN_BASE_PATH, SIGN_IN_BUILD_ARG_ENV, SIGN_IN_LOGIN_APP_SCOPE_KEY, SIGN_IN_UPSTREAM_ENV, inAppOnSharedLogin, signInLoginNames, signInUpstream, } from './sign-in.js';
 import { SIGNIN_DB_ZITADEL_PENDING_SCOPE_KEY } from './signin-db-tls.js';
 import { SIGNIN_DB_APP_SCOPE_KEY, SIGNIN_DB_TLS_SCOPE_KEY, dockerfileAppCreator, ensureSigninDbCaFile, provisionSigninDb, signinDbDsn, waitHealthy, withCallTimeout, } from './signin-db.js';
+import { PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY, applySigninMail, signinMailMarker, signinMailName, } from './signin-mail.js';
 export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { githubReleaseHookPlanInputs, provisionGithubReleaseHook, } from './github-release-hook.js';
 import { applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
@@ -2531,7 +2532,9 @@ export async function provisionAuthStack(scope, deps, target, input) {
                 user: smtpTarget.user,
                 password: smtpPassword,
                 senderAddress: input.smtpSender,
-                senderName: PLATFORM_AUTH_MAIL_SENDER_NAME,
+                senderName: input.mailBranding
+                    ? signinMailName(input.mailBranding.companyName)
+                    : PLATFORM_AUTH_MAIL_SENDER_NAME,
                 tls: smtpTarget.tls,
                 description: target.kind === 'platform'
                     ? PLATFORM_AUTH_SMTP_DESCRIPTION
@@ -2547,6 +2550,27 @@ export async function provisionAuthStack(scope, deps, target, input) {
             ]);
             throw new Error(`${label}: could not configure ZITADEL's SMTP provider for ${hostname}: ${cause}`);
         }
+        // A company's own sign-in: its name and design in the code mail. Idempotent; the marker is
+        // recorded after both writes, so a failure halfway is repeated.
+        if (input.mailBranding &&
+            (deps.signinMailWritable !== true ||
+                typeof mailZitadel.ensureEmailOtpMessageText !== 'function' ||
+                typeof mailZitadel.ensureLabelPolicy !== 'function')) {
+            console.info(`${label}: the host cannot write message texts, so the sign-in mail keeps ZITADEL's default text`);
+        }
+        else if (input.mailBranding) {
+            try {
+                await applySigninMail(mailZitadel, input.mailBranding.companyName);
+            }
+            catch (error) {
+                const cause = redactSecrets(error instanceof Error ? error.message : String(error), [
+                    mailToken,
+                    ...(smtpPassword ? [smtpPassword] : []),
+                ]);
+                throw new Error(`${label}: could not set the sign-in mail text and look for ${hostname}: ${cause}`);
+            }
+            await record(PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY, signinMailMarker(input.mailBranding.companyName));
+        }
         const inviteRecorded = scope.recordedIds()[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY];
         const inviteOrgRecorded = scope.recordedIds()[PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY];
         // An invite recorded for another org (the `foundry` org, before the owner moved) is made again.

package/dist/plan/signin-mail.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The sign-in code mail of a company that runs its own sign-in: the company's name in the sender and
+ * the text, the platform's design tokens for the look. ZITADEL's email-code message is built from the
+ * instance's custom text and label policy; both are written through `PlatformZitadelMailBranding`
+ * (`@wtfalch/providers` 0.13.0), each only when it differs.
+ *
+ * The look: no company declares a design foundry can read (an `OrgTheme` lives in cms and reaches
+ * Agora, Boule and the site as data), so every company gets the login's house colours
+ * (`SIGNIN_MAIL_LABEL_POLICY`). No logo: ZITADEL takes it as a multipart upload the client does not make.
+ */
+/** Raise it when the text or the look changes, so an applied company plans its sign-in step again. */
+export declare const AUTH_SIGNIN_MAIL_VERSION = "1";
+/** `signinMailMarker` of the company name and version last written, recorded after both writes. */
+export declare const PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY = "auth_signin_mail_applied";
+/** The two ZITADEL calls the sign-in mail needs. `@wtfalch/providers` 0.13.0's `ZitadelClient` has both. */
+export interface PlatformZitadelMailBranding {
+    ensureEmailOtpMessageText(language: string, text: {
+        title: string;
+        preHeader: string;
+        subject: string;
+        greeting: string;
+        text: string;
+        buttonText: string;
+        footerText: string;
+    }): Promise<{
+        changed: boolean;
+    }>;
+    ensureLabelPolicy(policy: {
+        primaryColor: string;
+        backgroundColor: string;
+        fontColor: string;
+        warnColor: string;
+        primaryColorDark: string;
+        backgroundColorDark: string;
+        fontColorDark: string;
+        warnColorDark: string;
+        disableWatermark: boolean;
+    }): Promise<{
+        changed: boolean;
+    }>;
+}
+/** What the marker holds: the version and the company name, so a rename writes the mail again. */
+export declare function signinMailMarker(companyName: string): string;
+/**
+ * The name as it goes into the sender and the text: one line, and no `{{`, which ZITADEL would run
+ * as a template action.
+ */
+export declare function signinMailName(companyName: string): string;
+export declare const SIGNIN_MAIL_LANGUAGE = "en";
+/**
+ * English text. `{{.OTP}}` is the code variable of this message (ZITADEL's `otp.go` sets it; the link
+ * behind the button carries the code as `{{.Code}}` from the login's `urlTemplate`). No greeting by
+ * name: the login fills names from the email address, so it would read "Wtfalch Wtfalch".
+ */
+export declare function signinMailText(companyName: string): {
+    title: string;
+    preHeader: string;
+    subject: string;
+    greeting: string;
+    text: string;
+    buttonText: string;
+    footerText: string;
+};
+/**
+ * The login's house colours as ZITADEL's label policy. The login reads the instance label policy for
+ * its own page colours and falls back to these when a value is empty (`login/src/helpers/colors.ts`
+ * in wtfalch/auth), so writing them keeps the sign-in window as it is and makes the mail match it.
+ */
+export declare const SIGNIN_MAIL_LABEL_POLICY: {
+    readonly primaryColor: "#B23A0C";
+    readonly backgroundColor: "#F6F3EC";
+    readonly fontColor: "#1D1B16";
+    readonly warnColor: "#B3261E";
+    readonly primaryColorDark: "#FF8A4A";
+    readonly backgroundColorDark: "#17130E";
+    readonly fontColorDark: "#EDE8DD";
+    readonly warnColorDark: "#FF9C8C";
+    readonly disableWatermark: true;
+};
+/** Writes the text and the look, each only when it differs. Throws the client's fixed-text error. */
+export declare function applySigninMail(zitadel: PlatformZitadelMailBranding, companyName: string): Promise<{
+    changed: boolean;
+}>;

package/dist/plan/signin-mail.js

@@ -0,0 +1,69 @@
+/**
+ * The sign-in code mail of a company that runs its own sign-in: the company's name in the sender and
+ * the text, the platform's design tokens for the look. ZITADEL's email-code message is built from the
+ * instance's custom text and label policy; both are written through `PlatformZitadelMailBranding`
+ * (`@wtfalch/providers` 0.13.0), each only when it differs.
+ *
+ * The look: no company declares a design foundry can read (an `OrgTheme` lives in cms and reaches
+ * Agora, Boule and the site as data), so every company gets the login's house colours
+ * (`SIGNIN_MAIL_LABEL_POLICY`). No logo: ZITADEL takes it as a multipart upload the client does not make.
+ */
+/** Raise it when the text or the look changes, so an applied company plans its sign-in step again. */
+export const AUTH_SIGNIN_MAIL_VERSION = '1';
+/** `signinMailMarker` of the company name and version last written, recorded after both writes. */
+export const PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY = 'auth_signin_mail_applied';
+/** What the marker holds: the version and the company name, so a rename writes the mail again. */
+export function signinMailMarker(companyName) {
+    return `${AUTH_SIGNIN_MAIL_VERSION}:${signinMailName(companyName)}`;
+}
+/**
+ * The name as it goes into the sender and the text: one line, and no `{{`, which ZITADEL would run
+ * as a template action.
+ */
+export function signinMailName(companyName) {
+    return companyName
+        .replace(/[\p{Cc}\s]+/gu, ' ')
+        .replaceAll('{{', '{ {')
+        .replaceAll('}}', '} }')
+        .trim();
+}
+export const SIGNIN_MAIL_LANGUAGE = 'en';
+/**
+ * English text. `{{.OTP}}` is the code variable of this message (ZITADEL's `otp.go` sets it; the link
+ * behind the button carries the code as `{{.Code}}` from the login's `urlTemplate`). No greeting by
+ * name: the login fills names from the email address, so it would read "Wtfalch Wtfalch".
+ */
+export function signinMailText(companyName) {
+    const name = signinMailName(companyName);
+    return {
+        title: 'Your sign-in code',
+        preHeader: `Your ${name} sign-in code`,
+        subject: `Your ${name} sign-in code`,
+        greeting: 'Hello,',
+        text: 'Your code is {{.OTP}}. It works for five minutes. Or use the button to sign in on this device.',
+        buttonText: 'Sign in',
+        footerText: name,
+    };
+}
+/**
+ * The login's house colours as ZITADEL's label policy. The login reads the instance label policy for
+ * its own page colours and falls back to these when a value is empty (`login/src/helpers/colors.ts`
+ * in wtfalch/auth), so writing them keeps the sign-in window as it is and makes the mail match it.
+ */
+export const SIGNIN_MAIL_LABEL_POLICY = {
+    primaryColor: '#B23A0C',
+    backgroundColor: '#F6F3EC',
+    fontColor: '#1D1B16',
+    warnColor: '#B3261E',
+    primaryColorDark: '#FF8A4A',
+    backgroundColorDark: '#17130E',
+    fontColorDark: '#EDE8DD',
+    warnColorDark: '#FF9C8C',
+    disableWatermark: true,
+};
+/** Writes the text and the look, each only when it differs. Throws the client's fixed-text error. */
+export async function applySigninMail(zitadel, companyName) {
+    const text = await zitadel.ensureEmailOtpMessageText(SIGNIN_MAIL_LANGUAGE, signinMailText(companyName));
+    const look = await zitadel.ensureLabelPolicy({ ...SIGNIN_MAIL_LABEL_POLICY });
+    return { changed: text.changed || look.changed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",