@wtfalch/foundry 0.71.0 → 0.72.0

package/dist/plan/platform-providers.js

@@ -15,7 +15,7 @@ import { desktopCallbackUri, unionRedirectUris } from './desktop-callback.js';
 import { placedOnPlatform } from './destinations.js';
 import { ACCESS_POLICY_NAME, LOG_DIR, coolifyProjectMark, getDatabaseStarted, isNotFoundError, isRunningOrStarting, setOidcAppLoginBaseUri, } from './executor.js';
 import { ACCESS_PROVIDER_RECORD_KEY, GATE_CLAIM_NAME } from './gates.js';
-import { IMAGE_HEALTHCHECK_SETTINGS, commandHealthCheckSettings, healthCheckSettings, tcpProbe, } from './health-check-settings.js';
+import { IMAGE_HEALTHCHECK_SETTINGS, commandHealthCheckSettings, healthCheckSettings, rollingUpdateSettings, tcpProbe, } from './health-check-settings.js';
 import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
 import { LIMITS, limited } from './own-limits.js';
 import { postLogoutAppliedValue, postLogoutUrisFor } from './post-logout-uris.js';
@@ -24,6 +24,7 @@ import { buildStageCopyHostPorts } from './stage-copy-host.js';
 import { stageGateKey, stageHostname, syncStageGateMembers, } from './stage-guards.js';
 export { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
 import { BROKER_DB_NAME, BROKER_DB_USER, ensureBrokerMcpEnv } from './broker-mcp.js';
+import { REGISTRAR_TOKEN_SCOPE_KEY, REGISTRAR_TOKEN_UNDELIVERED_SCOPE_KEY, RegistrarTokenError, ensureBrokerRegistrarToken, } from './broker-registrar-token.js';
 import { withTimeout } from './call-timeout.js';
 import { SIGN_IN_BIND_KEY_ENV, SIGN_IN_BIND_KEY_MIN_LENGTH, SIGN_IN_BIND_KEY_SCOPE_KEY, } from './cookie-domain.js';
 import { coolifyDomains, coolifyTunnelDomains, filesShareHostname } from './hostnames.js';
@@ -436,6 +437,9 @@ export class FoundryPlatformStepExecutor {
             const inviteBlocked = ownerInviteBlockedReason(ownerCompany, Boolean(this.auth.ownerInviteMail));
             if (inviteBlocked)
                 blocked.authOwnerInvite = inviteBlocked;
+            const registrarBlocked = await registrarTokenBlockedReason(this.auth, recordedIds);
+            if (registrarBlocked)
+                blocked.authRegistrar = registrarBlocked;
         }
         if (platform.mail.enabled) {
             const mailBlocked = await mailBlockedReason(platform, this.mail, recordedIds);
@@ -911,13 +915,22 @@ export class FoundryPlatformStepExecutor {
             const loginClientDrifted = await authLoginClientDrifted(platform, this.auth, recordedIds);
             // The broker lacks the MCP database and secret a shared org's entry needs (auth ADR 0002).
             const mcpDrifted = recordedIds[PLATFORM_AUTH_MCP_SCOPE_KEY] !== '1' && (await this.mcpWanted());
+            // The broker has no registrar token yet (`ZITADEL_REGISTRAR_TOKEN`).
+            // A token minted and never held is blocked (`blockedSteps`), not drift: no apply could change it.
+            const registrarDrifted = this.auth.registrarTokenWritable === true &&
+                !recordedIds[REGISTRAR_TOKEN_SCOPE_KEY] &&
+                !(await registrarTokenBlockedReason(this.auth, recordedIds));
             if (loginClientDrifted ||
                 mcpDrifted ||
+                registrarDrifted ||
                 (await this.signInLoginDrifted(this.auth, recordedIds))) {
                 result.auth = true;
             }
             if (await authAppsNotRunning(this.auth.coolify, recordedIds))
                 result.authApps = true;
+            // An app made before the rolling update still has its fixed container name: the step clears it.
+            if (await authAppsKeepInternalName(this.auth.coolify, recordedIds))
+                result.auth = true;
         }
         // #380: once the runner app is recorded, re-check its live env against
         // every setting `ensureStarted()` requires -- the gap that left the
@@ -1561,7 +1574,25 @@ const PLATFORM_AUTH_ADMIN_USER_NAME = 'foundry-admin';
 const PLATFORM_AUTH_RESERVED_USERNAME = 'admin';
 /** #216 (building on #209/#215): the narrower `IAM_LOGIN_CLIENT` machine user for the login app and the broker. */
 const PLATFORM_AUTH_LOGIN_CLIENT_USER_NAME = 'foundry-login-client';
-const PLATFORM_AUTH_ORG_NAME = 'foundry';
+export const PLATFORM_AUTH_ORG_NAME = 'foundry';
+/**
+ * The instance's first organisation (the default one, whose name the login shows as its wordmark).
+ * A company's own instance passes the recorded id (the platform passes none and keeps the name `foundry`);
+ * found by that id when there is one, because a company's own instance has it renamed to the
+ * company's name (`applySigninMail`), and a lookup by name would then make a second `foundry` org. The
+ * name is the way in only before the id is recorded. A recorded id ZITADEL no longer has is a failure,
+ * never a reason to make another org.
+ */
+async function platformAuthFirstOrg(zitadel, recordedId) {
+    if (recordedId) {
+        // The name is no way back in once the id is recorded: the org was renamed, and a lookup by name would make another.
+        if (typeof zitadel.getOrg !== 'function') {
+            throw new Error("the instance's first organisation is recorded, but the host's ZITADEL port cannot read it by id; it is not looked up by name");
+        }
+        return await zitadel.getOrg(recordedId);
+    }
+    return (await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME)).org;
+}
 /**
  * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
  * delivered under, once. A host reads it back to build `zitadelForInstance`
@@ -1628,6 +1659,27 @@ function loginClientRecordValue(userId, patId, token) {
     };
     return JSON.stringify(record);
 }
+/**
+ * The broker's registrar token was minted and never held: nothing can deliver it and a second mint is refused
+ * (platform-step rule 1), so the plan reports it and plans nothing for it. Undefined when not in that state.
+ */
+async function registrarTokenBlockedReason(auth, recordedIds) {
+    const userId = recordedIds[REGISTRAR_TOKEN_UNDELIVERED_SCOPE_KEY];
+    if (auth.registrarTokenWritable !== true || !userId || recordedIds[REGISTRAR_TOKEN_SCOPE_KEY]) {
+        return undefined;
+    }
+    let held;
+    try {
+        held = await auth.heldKeys?.resolve(platformTarget().refs.registrarToken);
+    }
+    catch {
+        // Not read: nothing is claimed, and the step itself reports the state.
+        return undefined;
+    }
+    if (held)
+        return undefined;
+    return `the broker's registrar token of ZITADEL machine user ${userId} was minted but never confirmed held; remove the recorded key ${REGISTRAR_TOKEN_UNDELIVERED_SCOPE_KEY} to make a new one`;
+}
 /**
  * #216 round 4: whether the login-client PAT recorded for this platform
  * (under {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY}) is still, right
@@ -2037,7 +2089,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
     const gitBranchPatchFor = (app) => authRefChanged && !app.justCreated ? { git_branch: gitRef } : {};
     // The Dockerfile's own HEALTHCHECK is the live check (`IMAGE_HEALTHCHECK_SETTINGS`).
     await deps.coolify.updateApplication(loginAppId, {
-        custom_internal_name: target.internal.authLogin,
+        ...rollingUpdateSettings(target.internal.authLogin),
         ...IMAGE_HEALTHCHECK_SETTINGS,
         ...gitBranchPatchFor(loginApp),
     });
@@ -2071,7 +2123,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
         : null;
     if (signInApp && signInNames) {
         await deps.coolify.updateApplication(signInApp.appId, {
-            custom_internal_name: signInNames.internal,
+            ...rollingUpdateSettings(signInNames.internal),
             ...IMAGE_HEALTHCHECK_SETTINGS,
             ...gitBranchPatchFor(signInApp),
         });
@@ -2097,7 +2149,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
     const brokerAppId = brokerApp.appId;
     await record(PLATFORM_AUTH_BROKER_SCOPE_KEY, brokerAppId);
     await deps.coolify.updateApplication(brokerAppId, {
-        custom_internal_name: target.internal.authBroker,
+        ...rollingUpdateSettings(target.internal.authBroker),
         ...IMAGE_HEALTHCHECK_SETTINGS,
         ...gitBranchPatchFor(brokerApp),
     });
@@ -2201,6 +2253,8 @@ export async function provisionAuthStack(scope, deps, target, input) {
         loginEnvs.push({ key: 'LETTERMINT_API_TOKEN', value: heldMailKey });
     if (input.smtpSender)
         loginEnvs.push({ key: 'LOGIN_MAIL_FROM', value: input.smtpSender });
+    if (input.passkeyRpId)
+        loginEnvs.push({ key: LOGIN_PASSKEY_RP_ID_ENV, value: input.passkeyRpId });
     // `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
@@ -2242,6 +2296,12 @@ export async function provisionAuthStack(scope, deps, target, input) {
     await deps.coolify.bulkUpsertEnvs(zitadelAppId, zitadelEnvs);
     await deps.coolify.bulkUpsertEnvs(loginAppId, loginEnvs);
     await deps.coolify.bulkUpsertEnvs(brokerAppId, brokerEnvs);
+    // A domain removed (or `usesDomain` off) leaves no RP ID to set: a value from an earlier apply is removed,
+    // and the apps deploy again, so a passkey is never bound to a domain the company no longer has.
+    const staleRpIdLogin = input.passkeyRpId
+        ? false
+        : await removeLoginEnv(deps.coolify, loginAppId, LOGIN_PASSKEY_RP_ID_ENV);
+    let staleRpIdSignIn = false;
     // The in-app login: the login's env, the base path as a build argument, and the host table.
     let signInEnvsChanged = false;
     // The session bind key is minted once, on the in-app login app only: a key already live (32 characters or
@@ -2265,6 +2325,9 @@ export async function provisionAuthStack(scope, deps, target, input) {
         ];
         signInEnvsChanged = await envsDiffer(deps.coolify, signInApp.appId, signInEnvs);
         await deps.coolify.bulkUpsertEnvs(signInApp.appId, signInEnvs);
+        staleRpIdSignIn = input.passkeyRpId
+            ? false
+            : await removeLoginEnv(deps.coolify, signInApp.appId, LOGIN_PASSKEY_RP_ID_ENV);
     }
     // Deploy an app that was just created, is not running (a throw after the
     // create left it never deployed, or it stopped), or whose envs changed.
@@ -2290,10 +2353,12 @@ export async function provisionAuthStack(scope, deps, target, input) {
     // died between the write and the deploy leaves the marker unset, and the next run sees no env diff.
     const loginEnvUnconfirmed = Boolean(heldMailKey &&
         input.smtpSender &&
-        recorded[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] !== authLoginEnvMarker(input.smtpSender));
+        recorded[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] !==
+            authLoginEnvMarker(input.smtpSender, input.passkeyRpId));
     if (loginApp.justCreated ||
         !loginApp.running ||
         loginEnvsChanged ||
+        staleRpIdLogin ||
         loginEnvUnconfirmed ||
         authRefChanged) {
         await deps.coolify.deploy(loginAppId);
@@ -2305,6 +2370,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
         (signInApp.justCreated ||
             !signInApp.running ||
             signInEnvsChanged ||
+            staleRpIdSignIn ||
             bindKeyWritten ||
             bindKeyUnconfirmed ||
             loginEnvUnconfirmed ||
@@ -2316,7 +2382,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
     // The mail env is live on the login apps: written above and deployed with them. Without the held
     // key the marker stays unset, so the step is planned again once the key is held.
     if (heldMailKey && input.smtpSender) {
-        await record(PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY, authLoginEnvMarker(input.smtpSender));
+        await record(PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY, authLoginEnvMarker(input.smtpSender, input.passkeyRpId));
     }
     // #211: the broker's own `server.ts` refuses to start without
     // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `LETTERMINT_API_TOKEN` --
@@ -2501,7 +2567,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
         // gets here right after the deploy.
         await waitForInstance(`https://${hostname}/.well-known/openid-configuration`, runtime, sleep, label);
         const zitadel = instanceZitadel();
-        const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+        const org = await platformAuthFirstOrg(zitadel, target.kind === 'org' ? recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] : undefined);
         // #216 round 5: recorded here too (mirroring `provisionPlatformArchon`),
         // so `authLoginClientDrifted` (below) never needs its own ZITADEL call
         // to resolve the org -- see that function's own doc comment.
@@ -2642,7 +2708,7 @@ export async function provisionAuthStack(scope, deps, target, input) {
             throw new Error(`${label}: the login-client token of ZITADEL machine user ${loginClientLost} was minted but never confirmed delivered; remove the recorded key ${PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY} to mint a new one`);
         }
         const loginClientZitadel = instanceZitadel();
-        const { org: loginClientOrg } = await loginClientZitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+        const loginClientOrg = await platformAuthFirstOrg(loginClientZitadel, target.kind === 'org' ? freshRecordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY] : undefined);
         // #216 round 5: backfills the org id for a platform whose admin block
         // (above) ran before this recording existed and has not run since --
         // see `authLoginClientDrifted`'s own doc comment.
@@ -2788,12 +2854,17 @@ export async function provisionAuthStack(scope, deps, target, input) {
             (deps.signinMailWritable !== true ||
                 typeof mailZitadel.ensureEmailOtpMessageText !== 'function' ||
                 typeof mailZitadel.ensureLabelPolicy !== 'function' ||
+                typeof mailZitadel.ensureOrgName !== 'function' ||
                 typeof mailZitadel.ensureEmailOtpGenerator !== 'function')) {
             console.info(`${label}: the host cannot write message texts, so the sign-in mail keeps ZITADEL's default text`);
         }
         else if (input.mailBranding) {
+            const firstOrgId = scope.recordedIds()[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
+            if (!firstOrgId) {
+                throw new Error(`${label}: the instance's first organisation is not recorded`);
+            }
             try {
-                await applySigninMail(mailZitadel, input.mailBranding.companyName);
+                await applySigninMail(mailZitadel, input.mailBranding.companyName, firstOrgId);
             }
             catch (error) {
                 const cause = redactSecrets(error instanceof Error ? error.message : String(error), [
@@ -2854,6 +2925,41 @@ export async function provisionAuthStack(scope, deps, target, input) {
             }
         }
     }
+    // The broker's registrar token: made once, held, written to the broker's env, adopted when set by hand.
+    // Last, so a stop here never holds up the login env, the mail or the invite above. It is reported, not
+    // thrown: the plan names the step again while the token is due, or blocked while it was minted and not held.
+    if (input.registrarOrgIds) {
+        try {
+            const firstOrgId = scope.recordedIds()[PLATFORM_ZITADEL_ORG_SCOPE_KEY];
+            if (!firstOrgId) {
+                throw new RegistrarTokenError(`${label}: the instance's first organisation is not recorded`);
+            }
+            await ensureBrokerRegistrarToken({
+                label,
+                zitadel: instanceZitadel(),
+                coolify: deps.coolify,
+                brokerAppId,
+                homeOrgId: firstOrgId,
+                orgIds: input.registrarOrgIds,
+                heldKeys: deps.heldKeys,
+                ref: target.refs.registrarToken,
+                recorded: () => scope.recordedIds(),
+                record,
+                persist: async () => {
+                    await scope.persist();
+                },
+                secret: (value) => runtime.onSecret?.(value),
+                sleep,
+                log: (line) => console.info(line),
+            });
+        }
+        catch (error) {
+            // Only our own text, which names ids; any other cause can carry a token.
+            console.warn(error instanceof RegistrarTokenError
+                ? error.message
+                : `${label}: the broker's registrar token is not in place yet; the next apply tries again`);
+        }
+    }
     return { resourceId: zitadelAppId };
 }
 /** The platform's sign-in project: the shared `platform` project, its id recorded under the sign-in's own scope key. */
@@ -2886,6 +2992,8 @@ async function provisionPlatformAuth(context, deps, options = {}) {
         // In-app sign-in: the second login app copies the login's host table (the host's port writes that).
         ...(signInLogin ? { signInLogin: { bindings: null } } : {}),
         mcp,
+        // The shared companies' organisations are granted by each company's registrar step.
+        ...(deps.registrarTokenWritable === true ? { registrarOrgIds: [] } : {}),
     });
 }
 /**
@@ -6161,6 +6269,30 @@ async function authAppsNotRunning(coolify, recordedIds) {
     }
     return false;
 }
+/**
+ * Whether the login app, the in-app login app or the broker still has a fixed container name
+ * (`custom_internal_name`), which stops Coolify's rolling update. `rollingUpdateSettings` clears it on every
+ * run of the step, so this plans the step again for an app made before. A Coolify read error counts as not drifted.
+ */
+async function authAppsKeepInternalName(coolify, recordedIds) {
+    for (const scopeKey of [
+        PLATFORM_AUTH_LOGIN_SCOPE_KEY,
+        SIGN_IN_LOGIN_APP_SCOPE_KEY,
+        PLATFORM_AUTH_BROKER_SCOPE_KEY,
+    ]) {
+        const appId = recordedIds[scopeKey];
+        if (!appId)
+            continue;
+        try {
+            if ((await coolify.getApplication(appId)).custom_internal_name)
+                return true;
+        }
+        catch {
+            // Nothing logged: the error can carry Coolify's response.
+        }
+    }
+    return false;
+}
 /**
  * Archon's live release webhook secret is missing, or is not the one its last deploy recorded
  * (`PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY`): the release hook step wrote it after Archon's
@@ -7516,6 +7648,17 @@ export function brokerDeployRecordValue(brokerAppId, authAppsRaw) {
     };
     return JSON.stringify(record);
 }
+const LOGIN_PASSKEY_RP_ID_ENV = 'LOGIN_PASSKEY_RP_ID';
+/** Removes one env from an app when it is live. True when it was removed; false with nothing live or no delete on the port. */
+async function removeLoginEnv(coolify, appId, key) {
+    if (typeof coolify.deleteEnv !== 'function')
+        return false;
+    const row = (await coolify.listEnvs(appId)).find((e) => e.key === key && !e.is_preview);
+    if (!row?.uuid)
+        return false;
+    await coolify.deleteEnv(appId, row.uuid);
+    return true;
+}
 /** Whether any desired env is missing from the app, or set to another value. */
 export async function envsDiffer(coolify, appId, desired) {
     const live = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
@@ -8069,7 +8212,7 @@ const EDGE_REPO = 'wtfalch/edge';
 const PLATFORM_EDGE_PROJECT = 'platform';
 const PLATFORM_EDGE_DB_NAME = 'platform-edge-db';
 const EDGE_APP_NAME = 'edge';
-/** The app's fixed `custom_internal_name`, the way `platform:files`' runner names itself. */
+/** The app's network alias (#1054: not a `custom_internal_name`, which turns off rolling updates). */
 const EDGE_RUNNER_INTERNAL_NAME = 'platform-edge';
 /** The runner's port (its Dockerfile: `PORT=3000`, `EXPOSE 3000`). */
 const EDGE_PORT = '3000';
@@ -8274,7 +8417,7 @@ async function provisionPlatformEdge(context, deps) {
     // port the `waitForNewDeployment` call below already probes internally.
     await deps.coolify.updateApplication(appId, {
         dockerfile_target_build: 'runner',
-        custom_internal_name: EDGE_RUNNER_INTERNAL_NAME,
+        ...rollingUpdateSettings(EDGE_RUNNER_INTERNAL_NAME),
         git_branch: gitRef,
         ...healthCheckSettings('/api/health', Number(EDGE_PORT)),
     });

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

@@ -2,7 +2,7 @@
  * 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.14.0), each only when it differs. The code itself (six digits, five minutes)
+ * (`@wtfalch/providers`), each only when it differs. The code itself (six digits, five minutes)
  * is the instance's email-OTP generator.
  *
  * The look: no company declares a design foundry can read (an `OrgTheme` lives in cms and reaches
@@ -10,7 +10,7 @@
  * (`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 = "2";
+export declare const AUTH_SIGNIN_MAIL_VERSION = "3";
 /** `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 code the mail carries: six digits, valid five minutes (`123-456` in the mail, see `signinMailText`). */
@@ -18,8 +18,16 @@ export declare const SIGNIN_MAIL_CODE: {
     readonly length: 6;
     readonly expirySeconds: 300;
 };
-/** The three ZITADEL calls the sign-in mail needs. `@wtfalch/providers` 0.14.0's `ZitadelClient` has all. */
+/** The four ZITADEL calls the sign-in mail needs. */
 export interface PlatformZitadelMailBranding {
+    /**
+     * Renames an organisation, only when its name differs (`PUT /management/v1/orgs/me` as that
+     * organisation). The login shows the instance's default organisation's name as its wordmark when the
+     * host is bound to no company, so a company's own instance names it after the company.
+     */
+    ensureOrgName(orgId: string, name: string): Promise<{
+        changed: boolean;
+    }>;
     ensureEmailOtpMessageText(language: string, text: {
         title: string;
         preHeader: string;
@@ -65,6 +73,11 @@ export declare const SIGNIN_MAIL_LANGUAGE = "en";
  * holds the code, split in the middle with Go's `slice` (`123-456`), because ZITADEL renders the
  * greeting as the large heading, so the code is the first thing the reader sees. No greeting by
  * name: the login fills names from the email address, so it would read "Wtfalch Wtfalch".
+ *
+ * Paragraphs: ZITADEL v4.17.3 puts `{{.Text}}` in one `<div>` of its built-in mail, where a line
+ * break collapses to a space. It escapes the field (`html/template`), then un-escapes the whole mail
+ * before sending it over SMTP (`internal/notification/types/user_email.go:43`,
+ * `html.UnescapeString`), so `<p>` tags in the text arrive as tags. There is no mail template API.
  */
 export declare function signinMailText(companyName: string): {
     title: string;
@@ -91,7 +104,7 @@ export declare const SIGNIN_MAIL_LABEL_POLICY: {
     readonly warnColorDark: "#FF9C8C";
     readonly disableWatermark: true;
 };
-/** Writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
-export declare function applySigninMail(zitadel: PlatformZitadelMailBranding, companyName: string): Promise<{
+/** Names the default organisation after the company, then writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
+export declare function applySigninMail(zitadel: PlatformZitadelMailBranding, companyName: string, defaultOrgId: string): Promise<{
     changed: boolean;
 }>;

package/dist/plan/signin-mail.js

@@ -2,7 +2,7 @@
  * 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.14.0), each only when it differs. The code itself (six digits, five minutes)
+ * (`@wtfalch/providers`), each only when it differs. The code itself (six digits, five minutes)
  * is the instance's email-OTP generator.
  *
  * The look: no company declares a design foundry can read (an `OrgTheme` lives in cms and reaches
@@ -10,7 +10,7 @@
  * (`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 = '2';
+export const AUTH_SIGNIN_MAIL_VERSION = '3';
 /** `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';
 /** The code the mail carries: six digits, valid five minutes (`123-456` in the mail, see `signinMailText`). */
@@ -37,6 +37,11 @@ export const SIGNIN_MAIL_LANGUAGE = 'en';
  * holds the code, split in the middle with Go's `slice` (`123-456`), because ZITADEL renders the
  * greeting as the large heading, so the code is the first thing the reader sees. No greeting by
  * name: the login fills names from the email address, so it would read "Wtfalch Wtfalch".
+ *
+ * Paragraphs: ZITADEL v4.17.3 puts `{{.Text}}` in one `<div>` of its built-in mail, where a line
+ * break collapses to a space. It escapes the field (`html/template`), then un-escapes the whole mail
+ * before sending it over SMTP (`internal/notification/types/user_email.go:43`,
+ * `html.UnescapeString`), so `<p>` tags in the text arrive as tags. There is no mail template API.
  */
 export function signinMailText(companyName) {
     const name = signinMailName(companyName);
@@ -45,7 +50,7 @@ export function signinMailText(companyName) {
         preHeader: `Your ${name} sign-in code`,
         subject: `Your ${name} sign-in code`,
         greeting: '{{slice .OTP 0 3}}-{{slice .OTP 3}}',
-        text: 'Enter this code to sign in. It works for five minutes. Or use the button to sign in on this device.',
+        text: `<p style="margin:0 0 12px 0">Enter this code to sign in. It works for five minutes.</p><p style="margin:0">Or use the button to sign in on this device.</p>`,
         buttonText: 'Sign in',
         footerText: name,
     };
@@ -66,10 +71,13 @@ export const SIGNIN_MAIL_LABEL_POLICY = {
     warnColorDark: '#FF9C8C',
     disableWatermark: true,
 };
-/** Writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
-export async function applySigninMail(zitadel, companyName) {
+/** Names the default organisation after the company, then writes the text, the look and the code, each only when it differs. Throws the client's fixed-text error. */
+export async function applySigninMail(zitadel, companyName, defaultOrgId) {
+    const name = await zitadel.ensureOrgName(defaultOrgId, signinMailName(companyName));
     const text = await zitadel.ensureEmailOtpMessageText(SIGNIN_MAIL_LANGUAGE, signinMailText(companyName));
     const look = await zitadel.ensureLabelPolicy({ ...SIGNIN_MAIL_LABEL_POLICY });
     const code = await zitadel.ensureEmailOtpGenerator({ ...SIGNIN_MAIL_CODE });
-    return { changed: text.changed || look.changed || code.changed };
+    return {
+        changed: name.changed || text.changed || look.changed || code.changed,
+    };
 }

package/dist/plan/zitadel-login-policy.d.ts

@@ -20,4 +20,4 @@ export interface ZitadelLoginPolicyOptions {
  * policy (POST), so a later change to the default cannot turn registration
  * back on. A custom policy keeps its own factors and IdPs (PUT).
  */
-export declare function createZitadelLoginPolicy(options: ZitadelLoginPolicyOptions): Pick<ZitadelPort, 'closeSelfRegistration' | 'enforceSecondFactor'>;
+export declare function createZitadelLoginPolicy(options: ZitadelLoginPolicyOptions): Required<Pick<ZitadelPort, 'closeSelfRegistration' | 'enforceSecondFactor' | 'setCustomersLoginPolicy'>>;

package/dist/plan/zitadel-login-policy.js

@@ -29,7 +29,22 @@ const SECOND_FACTOR_SETTINGS = {
     passwordlessType: 'PASSWORDLESS_TYPE_ALLOWED',
     mfaInitSkipLifetime: '0s',
 };
+/**
+ * What {@link ZitadelPort.setCustomersLoginPolicy} sets: a superset of what any customer app needs, so one
+ * policy serves every app of the customers org. `allowRegister` is not here: `customers.signUp` owns it.
+ */
+const CUSTOMERS_POLICY_SETTINGS = {
+    forceMfa: false,
+    allowExternalIdp: false,
+    allowUsernamePassword: true,
+    passwordlessType: 'PASSWORDLESS_TYPE_ALLOWED',
+};
 const SECOND_FACTORS = ['SECOND_FACTOR_TYPE_OTP', 'SECOND_FACTOR_TYPE_U2F'];
+/**
+ * The customers policy also keeps the emailed code as a second factor, and never removes it: the email-code
+ * session check may need it. The login app narrows the factors it offers an app.
+ */
+const CUSTOMERS_SECOND_FACTORS = [...SECOND_FACTORS, 'SECOND_FACTOR_TYPE_OTP_EMAIL'];
 const MULTI_FACTORS = ['MULTI_FACTOR_TYPE_U2F_WITH_VERIFICATION'];
 /** ZITADEL leaves false booleans and zero durations out of a read. */
 const isZeroDuration = (value) => value === undefined || (typeof value === 'string' && /^0+(\.0+)?s$/.test(value));
@@ -90,56 +105,67 @@ export function createZitadelLoginPolicy(options) {
         }
         return settings;
     };
+    /**
+     * Makes the org's login policy hold `want` and exactly these factor lists, writing nothing when it already
+     * does. Any setting not in `want` is copied back as it is. An org on the instance default gets its own
+     * policy (POST); a custom one is changed by PUT, then by adding the missing factors before removing the
+     * extra ones, so the org is never left with no second factor it needs.
+     */
+    async function conform(orgId, want, wantSecond, wantMulti) {
+        const data = await call('GET', orgId, undefined);
+        const policy = data.policy ?? {};
+        const isDefault = data.isDefault === true || policy.isDefault === true;
+        const secondFactors = stringList(policy.secondFactors);
+        const multiFactors = stringList(policy.multiFactors);
+        const settingsDiffer = Object.entries(want).some(([key, value]) => typeof value === 'boolean'
+            ? (policy[key] === true) !== value
+            : value === '0s'
+                ? !isZeroDuration(policy[key])
+                : policy[key] !== value);
+        const factorsDiffer = !sameSet(secondFactors, wantSecond) || !sameSet(multiFactors, wantMulti);
+        if (!isDefault && !settingsDiffer && !factorsDiffer)
+            return { changed: false };
+        const settings = { ...settingsOf(policy), ...want };
+        if (isDefault) {
+            // The org's own policy, written whole: the factor lists go in the same body.
+            await call('POST', orgId, {
+                ...settings,
+                secondFactors: wantSecond,
+                multiFactors: wantMulti,
+                idps: (policy.idps ?? []).map((idp) => ({
+                    idpId: idp.idpId,
+                    ownerType: 'IDP_OWNER_TYPE_SYSTEM',
+                })),
+            });
+            return { changed: true };
+        }
+        if (settingsDiffer)
+            await call('PUT', orgId, settings);
+        const factorPath = '/management/v1/policies/login';
+        for (const type of wantSecond.filter((t) => !secondFactors.includes(t))) {
+            await call('POST', orgId, { type }, `${factorPath}/second_factors`);
+        }
+        for (const type of wantMulti.filter((t) => !multiFactors.includes(t))) {
+            await call('POST', orgId, { type }, `${factorPath}/multi_factors`);
+        }
+        for (const type of secondFactors.filter((t) => !wantSecond.includes(t))) {
+            await call('DELETE', orgId, undefined, `${factorPath}/second_factors/${encodeURIComponent(type)}`);
+        }
+        for (const type of multiFactors.filter((t) => !wantMulti.includes(t))) {
+            await call('DELETE', orgId, undefined, `${factorPath}/multi_factors/${encodeURIComponent(type)}`);
+        }
+        return { changed: true };
+    }
     return {
         async enforceSecondFactor(orgId) {
             if (!orgId)
                 throw new Error('enforceSecondFactor: orgId is required');
-            const data = await call('GET', orgId, undefined);
-            const policy = data.policy ?? {};
-            const isDefault = data.isDefault === true || policy.isDefault === true;
-            const secondFactors = stringList(policy.secondFactors);
-            const multiFactors = stringList(policy.multiFactors);
-            const want = SECOND_FACTOR_SETTINGS;
-            const settingsDiffer = (policy.forceMfa === true) !== want.forceMfa ||
-                (policy.allowRegister === true) !== want.allowRegister ||
-                (policy.allowExternalIdp === true) !== want.allowExternalIdp ||
-                (policy.allowUsernamePassword === true) !== want.allowUsernamePassword ||
-                policy.passwordlessType !== want.passwordlessType ||
-                !isZeroDuration(policy.mfaInitSkipLifetime);
-            const factorsDiffer = !sameSet(secondFactors, SECOND_FACTORS) || !sameSet(multiFactors, MULTI_FACTORS);
-            if (!isDefault && !settingsDiffer && !factorsDiffer)
-                return { changed: false };
-            const settings = { ...settingsOf(policy), ...want };
-            if (isDefault) {
-                // The org's own policy, written whole: the factor lists go in the same body.
-                await call('POST', orgId, {
-                    ...settings,
-                    secondFactors: SECOND_FACTORS,
-                    multiFactors: MULTI_FACTORS,
-                    idps: (policy.idps ?? []).map((idp) => ({
-                        idpId: idp.idpId,
-                        ownerType: 'IDP_OWNER_TYPE_SYSTEM',
-                    })),
-                });
-                return { changed: true };
-            }
-            if (settingsDiffer)
-                await call('PUT', orgId, settings);
-            // Add before remove, so the org is never left with no second factor.
-            const factorPath = '/management/v1/policies/login';
-            for (const type of SECOND_FACTORS.filter((t) => !secondFactors.includes(t))) {
-                await call('POST', orgId, { type }, `${factorPath}/second_factors`);
-            }
-            for (const type of MULTI_FACTORS.filter((t) => !multiFactors.includes(t))) {
-                await call('POST', orgId, { type }, `${factorPath}/multi_factors`);
-            }
-            for (const type of secondFactors.filter((t) => !SECOND_FACTORS.includes(t))) {
-                await call('DELETE', orgId, undefined, `${factorPath}/second_factors/${encodeURIComponent(type)}`);
-            }
-            for (const type of multiFactors.filter((t) => !MULTI_FACTORS.includes(t))) {
-                await call('DELETE', orgId, undefined, `${factorPath}/multi_factors/${encodeURIComponent(type)}`);
-            }
-            return { changed: true };
+            return conform(orgId, SECOND_FACTOR_SETTINGS, SECOND_FACTORS, MULTI_FACTORS);
+        },
+        async setCustomersLoginPolicy(orgId) {
+            if (!orgId)
+                throw new Error('setCustomersLoginPolicy: orgId is required');
+            return conform(orgId, CUSTOMERS_POLICY_SETTINGS, CUSTOMERS_SECOND_FACTORS, MULTI_FACTORS);
         },
         async closeSelfRegistration(orgId) {
             if (!orgId)

package/dist/plan/zitadel-machine-user.d.ts

@@ -78,6 +78,13 @@ export declare class ZitadelLoginClientRoleConflictError extends Error {
 }
 /** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
 export declare const ORG_DIRECTORY_READER_ROLE = "ORG_OWNER_VIEWER";
+/**
+ * Boule removes a customer with this credential (boule#495). ZITADEL's narrowest built-in organisation role
+ * that holds `user.delete` is `ORG_USER_MANAGER`; it cannot be cut down to delete alone (it also lets the
+ * holder change users in that organisation). It is granted in the customers organisation only, never in the
+ * company's.
+ */
+export declare const ORG_DIRECTORY_USER_MANAGER_ROLE = "ORG_USER_MANAGER";
 /**
  * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
  * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
@@ -88,6 +95,12 @@ export declare class ZitadelDirectoryRoleConflictError extends Error {
     readonly roles: readonly string[];
     constructor(userId: string, roles: readonly string[]);
 }
+/**
+ * The organisation role of the broker's registrar user in each organisation it serves: it may make
+ * projects there, and a project it makes it owns. No member, user or login-policy rights, which
+ * `ORG_OWNER` would add.
+ */
+export declare const REGISTRAR_ROLE = "ORG_PROJECT_CREATOR";
 export interface ZitadelMinterOptions {
     /** The new instance's base URL, e.g. `https://auth.companyincluded.com`. */
     url: string;
@@ -96,4 +109,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader' | 'ensureOrgDirectoryRoles' | 'ensureRegistrarUser' | 'mintRegistrarToken'>;