@wtfalch/foundry 0.71.0 → 0.72.1

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'>;

package/dist/plan/zitadel-machine-user.js

@@ -86,6 +86,14 @@ export class ZitadelLoginClientRoleConflictError extends Error {
 }
 /** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
 export 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 const ORG_DIRECTORY_USER_MANAGER_ROLE = 'ORG_USER_MANAGER';
+const ORG_DIRECTORY_ROLES = [ORG_DIRECTORY_READER_ROLE, ORG_DIRECTORY_USER_MANAGER_ROLE];
 /**
  * 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
@@ -95,12 +103,20 @@ export class ZitadelDirectoryRoleConflictError extends Error {
     userId;
     roles;
     constructor(userId, roles) {
-        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_READER_ROLE}] -- refusing to reuse it as a directory reader`);
+        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_ROLES.join(', ')}] -- refusing to reuse it as a directory reader`);
         this.userId = userId;
         this.roles = roles;
         this.name = 'ZitadelDirectoryRoleConflictError';
     }
 }
+/** Each call to ZITADEL gives up after this long. */
+const CALL_TIMEOUT_MS = 30_000;
+/**
+ * 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 const REGISTRAR_ROLE = 'ORG_PROJECT_CREATOR';
 export function createZitadelAdminMinter(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     async function call(method, path, body, orgId) {
@@ -119,6 +135,7 @@ export function createZitadelAdminMinter(options) {
                 ...(orgId ? { 'x-zitadel-orgid': orgId } : {}),
             },
             body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
         });
         const text = await response.text();
         let data = {};
@@ -306,21 +323,12 @@ export function createZitadelAdminMinter(options) {
         if (!userId)
             throw new Error('ZITADEL did not return the machine user id');
         if (existing) {
-            const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
-            const roles = (members.result ?? [])
-                .filter((m) => m.userId === userId)
-                .flatMap((m) => m.roles ?? []);
-            if (roles.some((role) => role !== ORG_DIRECTORY_READER_ROLE)) {
+            const roles = await memberRoles(orgId, userId);
+            if (roles.some((role) => !ORG_DIRECTORY_ROLES.includes(role))) {
                 throw new ZitadelDirectoryRoleConflictError(userId, roles);
             }
         }
-        try {
-            await call('POST', '/management/v1/orgs/me/members', { userId, roles: [ORG_DIRECTORY_READER_ROLE] }, orgId);
-        }
-        catch (e) {
-            if (!(e instanceof ZitadelHttpError && e.status === 409))
-                throw e;
-        }
+        await ensureOrgDirectoryRoles(orgId, userId);
         await revokeAllPats(orgId, userId);
         const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
         const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
@@ -329,6 +337,78 @@ export function createZitadelAdminMinter(options) {
         }
         return { userId, token: pat.token, patId };
     }
+    /**
+     * The broker's registrar user: a machine user of its own in `orgIds[0]` (found by `userName`, else made)
+     * holding {@link REGISTRAR_ROLE} in every org of `orgIds`, each grant added only when the org does not
+     * have it yet (a 409 is the same). Mints no token, so it is safe to repeat whenever an org joins the
+     * list. Calls follow ZITADEL's published v1 management API and have not been run against a live
+     * instance.
+     */
+    async function ensureRegistrarUser(orgIds, input) {
+        const home = orgIds[0];
+        if (!home)
+            throw new Error('the registrar user needs at least one organisation');
+        const found = await call('POST', '/management/v1/users/_search', {
+            queries: [
+                { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
+            ],
+        }, home);
+        let userId = found.result?.[0]?.id;
+        if (!userId) {
+            const created = await call('POST', '/management/v1/users/machine', {
+                userName: input.userName,
+                name: input.name,
+                accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+            }, home);
+            userId = typeof created.userId === 'string' ? created.userId : undefined;
+        }
+        if (!userId)
+            throw new Error('ZITADEL did not return the machine user id');
+        for (const orgId of new Set(orgIds)) {
+            try {
+                await call('POST', '/management/v1/orgs/me/members', { userId, roles: [REGISTRAR_ROLE] }, orgId);
+            }
+            catch (e) {
+                if (!(e instanceof ZitadelHttpError && e.status === 409))
+                    throw e;
+            }
+        }
+        return { userId };
+    }
+    /** A fresh token for the registrar user; every token it holds is revoked first, so one stays live. */
+    async function mintRegistrarToken(homeOrgId, userId) {
+        await revokeAllPats(homeOrgId, userId);
+        const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, homeOrgId);
+        const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
+        if (typeof pat.token !== 'string' || pat.token === '' || !patId) {
+            throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+        }
+        return { token: pat.token, patId };
+    }
+    /**
+     * The directory user's roles in one organisation: {@link ORG_DIRECTORY_ROLES}, set whether it is a member
+     * yet or not (a 409 on the add means it is, and the roles are then replaced with a `PUT`). Calls follow
+     * ZITADEL's published v1 management API and have not been run against a live instance.
+     */
+    async function ensureOrgDirectoryRoles(orgId, userId) {
+        try {
+            await call('POST', '/management/v1/orgs/me/members', { userId, roles: ORG_DIRECTORY_ROLES }, orgId);
+        }
+        catch (e) {
+            if (!(e instanceof ZitadelHttpError && e.status === 409))
+                throw e;
+            // The PUT replaces every role, so the roles a person added stay: ours join the existing set.
+            const existing = await memberRoles(orgId, userId);
+            await call('PUT', `/management/v1/orgs/me/members/${userId}`, { roles: [...existing, ...ORG_DIRECTORY_ROLES.filter((r) => !existing.includes(r))] }, orgId);
+        }
+    }
+    /** The organisation roles one user holds in an organisation. */
+    async function memberRoles(orgId, userId) {
+        const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
+        return (members.result ?? [])
+            .filter((m) => m.userId === userId)
+            .flatMap((m) => m.roles ?? []);
+    }
     /** Deletes every PAT of a user; a PAT already gone (404) is the outcome wanted. */
     async function revokeAllPats(orgId, userId) {
         for (const patId of await listPats(orgId, userId)) {
@@ -342,7 +422,10 @@ export function createZitadelAdminMinter(options) {
         }
     }
     return {
+        ensureRegistrarUser,
+        mintRegistrarToken,
         mintOrgDirectoryReader,
+        ensureOrgDirectoryRoles,
         revokeOrgDirectoryReader: revokeAllPats,
         mintAdminMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_OWNER').then(({ userId, token }) => ({ userId, token })),
         mintLoginClientMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_LOGIN_CLIENT'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.71.0",
+  "version": "0.72.1",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -54,7 +54,7 @@
     "status": "node scripts/status.mjs"
   },
   "peerDependencies": {
-    "@wtfalch/providers": ">=0.12.0",
+    "@wtfalch/providers": ">=0.16.0",
     "drizzle-orm": ">=0.45.2"
   },
   "dependencies": {
@@ -63,7 +63,7 @@
     "@wtfalch/auth": "^0.26.0",
     "@wtfalch/edge": "0.23.0",
     "@wtfalch/email": "^0.20.0",
-    "@wtfalch/providers": "0.12.0",
+    "@wtfalch/providers": "0.16.0",
     "bcryptjs": "3.0.3",
     "ssh2": "1.17.0",
     "zod": "4.6.5"