@wtfalch/foundry 0.44.1 → 0.45.0

package/dist/org.d.ts

@@ -458,8 +458,19 @@ export interface EntryAuth {
      */
     mcp?: {
         path: string;
+        onboardingPath?: string;
     };
+    /**
+     * How the customer proves who they are. `password` is the default.
+     * `email-code` has the sign-in page mail a one-time code instead of asking
+     * for a password: the broker entry gets `emailLink: true` and the customers
+     * organisation gets the metadata `wtfalch.signIn = email-code`. Needs
+     * `users: 'customers'`.
+     */
+    signIn?: 'password' | 'email-code';
 }
+/** `uses.auth.mcp.onboardingPath`: absolute, no query, no fragment, no dot segments. */
+export declare const ONBOARDING_PATH_MAX_LENGTH = 200;
 /** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
 export declare const MCP_PATH: RegExp;
 /**

package/dist/org.js

@@ -11,6 +11,8 @@ export const DEFAULT_GATE_LIMIT = 3;
 export const APP_ENTRY_KEY = 'app';
 /** The most volumes one entry may declare. */
 export const MAX_ENTRY_VOLUMES = 8;
+/** `uses.auth.mcp.onboardingPath`: absolute, no query, no fragment, no dot segments. */
+export const ONBOARDING_PATH_MAX_LENGTH = 200;
 /** The MCP endpoint path: absolute, plain characters, no dot segments, no query. */
 export const MCP_PATH = /^\/[A-Za-z0-9_~-]+(\/[A-Za-z0-9_~-]+)*$|^\/$/;
 /** What an entry's ai key may hold: the most the org's own key holds. */
@@ -556,6 +558,26 @@ function validateEntryAuth(entry, hosting, domain) {
             auth.mcp.path.length > 200) {
             return `${at} mcp.path must be an absolute path of letters, digits, '_', '~' and '-' segments, such as '/mcp'`;
         }
+        const onboarding = auth.mcp.onboardingPath;
+        if (onboarding !== undefined &&
+            (typeof onboarding !== 'string' ||
+                !onboarding.startsWith('/') ||
+                onboarding.startsWith('//') ||
+                onboarding.includes('..') ||
+                onboarding.includes('?') ||
+                onboarding.includes('#') ||
+                onboarding.includes('\\') ||
+                /[\s\p{Cc}]/u.test(onboarding) ||
+                onboarding.length > ONBOARDING_PATH_MAX_LENGTH)) {
+            return `${at} mcp.onboardingPath must be an absolute path that starts with '/', such as '/onboarding', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`;
+        }
+    }
+    const signIn = auth.signIn;
+    if (signIn !== undefined && signIn !== 'password' && signIn !== 'email-code') {
+        return `${at} signIn must be 'password' or 'email-code'`;
+    }
+    if (signIn === 'email-code' && auth.users !== 'customers') {
+        return `${at} signIn 'email-code' needs users 'customers': only customers sign in with an emailed code`;
     }
     if (entry.key === 'agora' ||
         entry.key === 'boule' ||

package/dist/plan/boule.d.ts

@@ -96,6 +96,10 @@ export declare const ARCHON_CREDENTIAL_RENEW_AFTER_MS: number;
 export declare function archonCredentialRenewDue(recorded: Readonly<Record<string, string>>, nowMs: number): boolean;
 /** The ZITADEL machine user that reads the customers organisation. No secret. */
 export declare const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = "customers_directory_user";
+/** The ZITADEL org metadata key that tells the sign-in page how the customers organisation signs in. */
+export declare const CUSTOMERS_SIGN_IN_METADATA_KEY = "wtfalch.signIn";
+/** `email-code` or `password`: the sign-in metadata last written to the customers organisation. Absent: never written. */
+export declare const CUSTOMERS_SIGN_IN_SCOPE_KEY = "zitadel_customers_signin";
 /** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
 export declare const CUSTOMERS_SIGN_UP_SCOPE_KEY = "zitadel_customers_signup";
 /** Where the held-key store keeps the Archon credential of an org's Boule. */

package/dist/plan/boule.js

@@ -110,6 +110,10 @@ export function archonCredentialRenewDue(recorded, nowMs) {
 }
 /** The ZITADEL machine user that reads the customers organisation. No secret. */
 export const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = 'customers_directory_user';
+/** The ZITADEL org metadata key that tells the sign-in page how the customers organisation signs in. */
+export const CUSTOMERS_SIGN_IN_METADATA_KEY = 'wtfalch.signIn';
+/** `email-code` or `password`: the sign-in metadata last written to the customers organisation. Absent: never written. */
+export const CUSTOMERS_SIGN_IN_SCOPE_KEY = 'zitadel_customers_signin';
 /** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
 export const CUSTOMERS_SIGN_UP_SCOPE_KEY = 'zitadel_customers_signup';
 /** Where the held-key store keeps the Archon credential of an org's Boule. */

package/dist/plan/broker-entries.d.ts

@@ -40,6 +40,7 @@ export declare function entryMcp(org: DeclaredOrg, entry: HostingEntry, recorded
     resource: string;
     projectId: string;
     loginHost: string;
+    onboardingUrl?: string;
 } | null;
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
@@ -59,7 +60,13 @@ export interface BrokerEntryWant {
         resource: string;
         projectId: string;
         loginHost: string;
+        onboardingUrl?: string;
     };
+    /**
+     * `true` for `signIn: 'email-code'`, `false` for an entry that declares `signIn: 'password'`.
+     * Absent when the entry declares no `signIn`: a hand-set `emailLink` stays as it is.
+     */
+    emailLink?: boolean;
 }
 /**
  * Each value a broker entry needs and the step that records it, so the

package/dist/plan/broker-entries.js

@@ -52,7 +52,12 @@ export function entryMcp(org, entry, recorded) {
     const host = entryHostnames(org, entry)[0];
     if (!mcp || !projectId || !host)
         return null;
-    return { resource: `https://${host}${mcp.path}`, projectId, loginHost: loginHostnameFor(org) };
+    return {
+        resource: `https://${host}${mcp.path}`,
+        projectId,
+        loginHost: loginHostnameFor(org),
+        ...(mcp.onboardingPath ? { onboardingUrl: `https://${host}${mcp.onboardingPath}` } : {}),
+    };
 }
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export function entryAuthEnv(org, entry, recorded, issuer) {
@@ -111,6 +116,7 @@ export function wantedBrokerEntry(org, entry, recorded) {
             registration: auth.registration === 'open',
             replaces: auth.replacesBrokerEntry ?? null,
             ...(mcp ? { mcp } : {}),
+            ...(auth.signIn ? { emailLink: auth.signIn === 'email-code' } : {}),
         },
     };
 }
@@ -227,6 +233,11 @@ export async function writeBrokerEntry(broker, input) {
         entry.mcp = want.mcp;
     else
         entry.mcp = undefined;
+    // A hand-set `emailLink` stays unless the entry declares `signIn`, or declared it before and stopped.
+    if (want.emailLink !== undefined)
+        entry.emailLink = want.emailLink;
+    else if (previous?.emailLink === true)
+        entry.emailLink = false;
     try {
         validateBrokerAppEntry(entry, brokerAppId, 0);
     }

package/dist/plan/diff.d.ts

@@ -55,6 +55,8 @@ export interface PlanOrgOptions {
     zitadelIdTokenUserinfo?: boolean;
     /** The executor's ZITADEL client has `ensureOidcAppMcpAccess` and `ensureAccessTokenLifetime`; without them `planMcp` is blocked. */
     zitadelMcp?: boolean;
+    /** The executor's ZITADEL client has `setOrgMetadata` and `removeOrgMetadata`; without them the customers organisation's sign-in metadata is reported blocked. */
+    zitadelOrgMetadata?: boolean;
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
     /** #161: the slugs of the other declared orgs, so a Boule whose hostname another org's slug would take is blocked. */

package/dist/plan/diff.js

@@ -3,7 +3,7 @@ import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, held
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { planBlueGreen } from './blue-green.js';
-import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_MAIL_TOKEN_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, customersOrgIdOf, desiredBouleEnv, staleCustomersEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_MAIL_TOKEN_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, CUSTOMERS_SIGN_IN_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, customersOrgIdOf, desiredBouleEnv, staleCustomersEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { chatInternalNames, chatUpstreams } from './chat-matrix.js';
 import { planCompanyBackups } from './company-backups.js';
@@ -400,9 +400,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // this array order, one at a time.
     // Customers before the entries that sign them in: `pushAppEnv` and the
     // broker entry read the customers organisation's id.
-    const customers = planCustomers(org, live, claimed, recordedIds);
-    if (customers)
-        plannedSteps.push(customers);
+    const customers = planCustomers(org, live, claimed, recordedIds, options.zitadelOrgMetadata ?? false);
+    if (customers.step)
+        plannedSteps.push(customers.step);
     for (const step of [
         ...planIssuerApps(org, byKey, claimed),
         ...planEntryClients(org, byKey, claimed),
@@ -707,6 +707,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     unmanaged.push(...edgeWorkers.blocked);
     unmanaged.push(...workerApps.blocked);
     unmanaged.push(...mcp.blocked);
+    unmanaged.push(...customers.blocked);
     unmanaged.push(...entryEdgeKeys.blocked);
     unmanaged.push(...edgeReservedLabels.blocked);
     if (ownAuth.blocked)
@@ -3879,21 +3880,38 @@ function planBouleBrokerEntry(org, recordedIds, plannedSteps, brokerWired) {
  * recorded, the live project grant to that org is claimed so it is not
  * listed as unmanaged.
  */
-function planCustomers(org, live, claimed, recordedIds) {
+function planCustomers(org, live, claimed, recordedIds, metadataWired) {
     const signUp = org.customers?.signUp === true;
     const wanted = org.customers?.enabled === true ||
         org.hosting.entries.some((entry) => entry.uses?.auth?.users === 'customers');
+    // The sign-in page reads this from the customers organisation: any entry with an emailed code turns it on.
+    const wantedSignIn = wanted && org.hosting.entries.some((entry) => entry.uses?.auth?.signIn === 'email-code')
+        ? 'email-code'
+        : '';
+    const blocked = [];
     const customersOrgId = recordedIds[resourceKey('zitadel', 'customers', org.id)];
     if (!customersOrgId) {
         if (!wanted)
-            return null;
+            return { step: null, blocked };
+        const signIn = wantedSignIn === 'email-code' && metadataWired ? { signIn: wantedSignIn } : {};
+        if (wantedSignIn === 'email-code' && !metadataWired) {
+            blocked.push(signInMetadataBlocked(org));
+        }
         return {
-            action: { system: 'zitadel', kind: 'customers', key: org.id, desired: { signUp } },
             step: {
-                description: `provision a ZITADEL org for ${org.slug}'s customers, with self-registration ${signUp ? 'on' : 'off'}`,
-                destroys: false,
-                migrates: false,
+                action: {
+                    system: 'zitadel',
+                    kind: 'customers',
+                    key: org.id,
+                    desired: { signUp, ...signIn },
+                },
+                step: {
+                    description: `provision a ZITADEL org for ${org.slug}'s customers, with self-registration ${signUp ? 'on' : 'off'}${signIn.signIn ? ' and sign-in by emailed code' : ''}`,
+                    destroys: false,
+                    migrates: false,
+                },
             },
+            blocked,
         };
     }
     for (const r of live) {
@@ -3907,22 +3925,39 @@ function planCustomers(org, live, claimed, recordedIds) {
     // marker is on. Switching customers off closes it: the declaration says no one signs themselves up.
     const applied = recordedIds[CUSTOMERS_SIGN_UP_SCOPE_KEY] || '1';
     const wantedSignUp = wanted && signUp ? '1' : '0';
-    if (applied === wantedSignUp)
-        return null;
+    const appliedSignIn = recordedIds[CUSTOMERS_SIGN_IN_SCOPE_KEY] === 'email-code' ? 'email-code' : '';
+    const signInDiffers = appliedSignIn !== wantedSignIn;
+    if (signInDiffers && !metadataWired)
+        blocked.push(signInMetadataBlocked(org));
+    const writeSignIn = signInDiffers && metadataWired;
+    if (applied === wantedSignUp && !writeSignIn)
+        return { step: null, blocked };
     return {
-        action: {
-            system: 'zitadel',
-            kind: 'customers',
-            key: org.id,
-            desired: { signUp: wantedSignUp === '1' },
-        },
         step: {
-            description: `turn self-registration ${wantedSignUp === '1' ? 'on' : 'off'} for ${org.slug}'s customers`,
-            destroys: false,
-            migrates: false,
+            action: {
+                system: 'zitadel',
+                kind: 'customers',
+                key: org.id,
+                desired: {
+                    signUp: wantedSignUp === '1',
+                    ...(writeSignIn ? { signIn: wantedSignIn } : {}),
+                },
+            },
+            step: {
+                description: applied === wantedSignUp
+                    ? `${wantedSignIn ? 'set' : 'remove'} the emailed-code sign-in metadata of ${org.slug}'s customers`
+                    : `turn self-registration ${wantedSignUp === '1' ? 'on' : 'off'} for ${org.slug}'s customers`,
+                destroys: false,
+                migrates: false,
+            },
         },
+        blocked,
     };
 }
+const signInMetadataBlocked = (org) => ({
+    description: `${org.slug}'s customers organisation sign-in metadata is blocked, not planned: the host's ZITADEL client cannot set or remove organisation metadata`,
+    key: `zitadel:customers-signin:${org.id}`,
+});
 /**
  * #246: one step per `hosting.access` rule -- a `bypass` or `service-token`
  * Access policy on a hostname the org serves (`share.<domain>`,

package/dist/plan/executor.d.ts

@@ -1215,6 +1215,17 @@ export interface ZitadelPort {
     ensureAccessTokenLifetime?(seconds: number): Promise<{
         changed: boolean;
     }>;
+    /**
+     * Sets one metadata key on an org (`wtfalch.signIn = email-code` on the
+     * customers organisation). An upsert, so a repeat is no change. Optional, with
+     * {@link ZitadelPort.removeOrgMetadata}: a host whose client lacks either gets
+     * the customers organisation's sign-in metadata reported blocked
+     * (`FoundryPlanApplyOptions.zitadelOrgMetadata`). `zitadel-org-metadata.ts`
+     * is the real implementation.
+     */
+    setOrgMetadata?(orgId: string, key: string, value: string): Promise<void>;
+    /** Removes one metadata key from an org. A key that is not there is done, not an error. */
+    removeOrgMetadata?(orgId: string, key: string): Promise<void>;
 }
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
@@ -2183,6 +2194,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * a re-run after a crash finishes the job.
      */
     private zitadelCustomers;
+    /**
+     * `wtfalch.signIn = email-code` on the customers organisation while an entry
+     * declares it, removed when none does. The planner puts `signIn` in the step
+     * only when the recorded marker differs, so a step for another change touches
+     * nothing here. Returns the marker value to record, or null for no change.
+     */
+    private writeCustomersSignInMetadata;
     private zitadelApp;
     /**
      * The app an earlier attempt's recreate already made under the same

package/dist/plan/executor.js

@@ -9,7 +9,7 @@ import { adoptedKeysUnreadable, parseAdoptSnapshot } from './adopt.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { applyBlueGreenConnectors, applyBlueGreenServer, applyBlueGreenWeights, } from './blue-green-apply.js';
 import { bgKey, colorAppName, entrySubject, healthTokenName, liveAppNameFor, splitServers, } from './blue-green.js';
-import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_ARCHON_PUSHED_AT_SCOPE_KEY, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_CUSTOMERS_ORG_ENV, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, CUSTOMERS_DIRECTORY_USER_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleArchonCredentialRef, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, customersDirectoryRef, customersOrgIdOf, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
+import { BOULE_ARCHON_CREDENTIAL_ENV, BOULE_ARCHON_PUSHED_AT_SCOPE_KEY, BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_CUSTOMERS_CREDENTIAL_ENV, BOULE_CUSTOMERS_ORG_ENV, BOULE_DATABASE_SCOPE_KEY, BOULE_DEPLOYED_SCOPE_KEY, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, CUSTOMERS_DIRECTORY_USER_SCOPE_KEY, CUSTOMERS_SIGN_IN_METADATA_KEY, CUSTOMERS_SIGN_IN_SCOPE_KEY, CUSTOMERS_SIGN_UP_SCOPE_KEY, archonCredentialRenewDue, bouleArchonCredentialRef, bouleEnvDrift, bouleHostnameFor, bouleMailWanted, customersDirectoryRef, customersOrgIdOf, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, mcpCallbackUri, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { recordBuiltCommit } from './build-record.js';
 import { MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, masDockerfile, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
@@ -2235,9 +2235,42 @@ export class FoundryStepExecutor {
         else
             await this.ports.zitadel.closeSelfRegistration(customers.id);
         await this.ports.zitadel.findOrCreateProjectGrant(zitadelOrgId, projectId, customers.id);
+        // The sign-in metadata comes before either marker: a failed write leaves both markers behind, so the next plan repeats the step.
+        const signIn = await this.writeCustomersSignInMetadata(org, customers.id, action, context);
         context.recordScopeId(CUSTOMERS_SIGN_UP_SCOPE_KEY, signUp ? '1' : '0');
+        if (signIn)
+            context.recordScopeId(CUSTOMERS_SIGN_IN_SCOPE_KEY, signIn);
         return { resourceId: customers.id };
     }
+    /**
+     * `wtfalch.signIn = email-code` on the customers organisation while an entry
+     * declares it, removed when none does. The planner puts `signIn` in the step
+     * only when the recorded marker differs, so a step for another change touches
+     * nothing here. Returns the marker value to record, or null for no change.
+     */
+    async writeCustomersSignInMetadata(org, customersOrgId, action, context) {
+        const want = action.desired.signIn;
+        if (want === undefined)
+            return null;
+        const { setOrgMetadata, removeOrgMetadata } = this.ports.zitadel;
+        if (!setOrgMetadata || !removeOrgMetadata) {
+            throw new Error(`zitadel:customers for ${org.slug}: the ZITADEL client cannot set organisation metadata`);
+        }
+        try {
+            if (want === 'email-code') {
+                await setOrgMetadata.call(this.ports.zitadel, customersOrgId, CUSTOMERS_SIGN_IN_METADATA_KEY, 'email-code');
+                return 'email-code';
+            }
+            // Nothing to remove when it was never written.
+            if (context.recordedIds()[CUSTOMERS_SIGN_IN_SCOPE_KEY] !== 'email-code')
+                return null;
+            await removeOrgMetadata.call(this.ports.zitadel, customersOrgId, CUSTOMERS_SIGN_IN_METADATA_KEY);
+            return 'password';
+        }
+        catch {
+            throw new Error(`zitadel:customers for ${org.slug}: writing the sign-in metadata of organisation ${customersOrgId} failed`);
+        }
+    }
     async zitadelApp(action, org, context) {
         const appType = action.desired.appType;
         const recorded = context.recordedIds();

package/dist/plan/index.d.ts

@@ -34,6 +34,7 @@ export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManag
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { createZitadelLoginPolicy } from './zitadel-login-policy.js';
+export { createZitadelOrgMetadata } from './zitadel-org-metadata.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';

package/dist/plan/index.js

@@ -18,6 +18,7 @@ export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEME
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { createZitadelLoginPolicy } from './zitadel-login-policy.js';
+export { createZitadelOrgMetadata } from './zitadel-org-metadata.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';

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

@@ -487,6 +487,12 @@ export interface FoundryPlanApplyOptions {
      * `uses.auth.mcp` is reported blocked.
      */
     zitadelMcp?: boolean;
+    /**
+     * True when the host's ZITADEL client has `setOrgMetadata` and `removeOrgMetadata`.
+     * Without it an entry's `signIn: 'email-code'` is reported blocked: the customers
+     * organisation cannot be told.
+     */
+    zitadelOrgMetadata?: boolean;
     /**
      * F5: true when the host's executor was built with a `broker` port.
      * Optional, and false without it: each entry's broker entry is then
@@ -641,6 +647,7 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly loginHostDiscovery;
     private readonly zitadelIdTokenUserinfo;
     private readonly zitadelMcp;
+    private readonly zitadelOrgMetadata;
     private readonly broker;
     private readonly edgeWorkers;
     private readonly workerApps;

package/dist/plan/plan-apply.js

@@ -162,6 +162,7 @@ export class FoundryPlanApply {
     loginHostDiscovery;
     zitadelIdTokenUserinfo;
     zitadelMcp;
+    zitadelOrgMetadata;
     broker;
     edgeWorkers;
     workerApps;
@@ -196,6 +197,7 @@ export class FoundryPlanApply {
         this.loginHostDiscovery = options.loginHostDiscovery;
         this.zitadelIdTokenUserinfo = options.zitadelIdTokenUserinfo ?? false;
         this.zitadelMcp = options.zitadelMcp ?? false;
+        this.zitadelOrgMetadata = options.zitadelOrgMetadata ?? false;
         this.broker = options.broker ?? false;
         this.edgeWorkers = options.edgeWorkers ?? false;
         this.workerApps = options.workerApps ?? false;
@@ -1220,6 +1222,7 @@ export class FoundryPlanApply {
             loginHostServesDiscovery,
             zitadelIdTokenUserinfo: this.zitadelIdTokenUserinfo,
             zitadelMcp: this.zitadelMcp,
+            zitadelOrgMetadata: this.zitadelOrgMetadata,
             broker: ownsServices(org) && this.hostOwnServices && this.executor.ownBrokerPort
                 ? await this.executor.ownBrokerPort(org, recorded)
                 : this.broker,

package/dist/plan/zitadel-org-metadata.d.ts

@@ -0,0 +1,18 @@
+import type { ZitadelPort } from './executor.js';
+export interface ZitadelOrgMetadataOptions {
+    /** The ZITADEL instance's base URL. */
+    url: string;
+    /** Bearer token allowed to write an org's metadata. */
+    token: string;
+    fetchImpl?: typeof fetch;
+    instanceHost?: string;
+    timeoutMs?: number;
+}
+/**
+ * The real {@link ZitadelPort.setOrgMetadata} and {@link ZitadelPort.removeOrgMetadata}:
+ * ZITADEL's v1 management API, `POST` and `DELETE /management/v1/metadata/<key>`,
+ * org-scoped by `x-zitadel-orgid`. A set is one upsert with the value in base64,
+ * so a repeat is no change. A remove of a key that is not there (404) is done.
+ * An error names the status, never the body.
+ */
+export declare function createZitadelOrgMetadata(options: ZitadelOrgMetadataOptions): Pick<ZitadelPort, 'setOrgMetadata' | 'removeOrgMetadata'>;

package/dist/plan/zitadel-org-metadata.js

@@ -0,0 +1,51 @@
+import { ZitadelHttpError } from './zitadel-machine-user.js';
+const CALL_TIMEOUT_MS = 30_000;
+/**
+ * The real {@link ZitadelPort.setOrgMetadata} and {@link ZitadelPort.removeOrgMetadata}:
+ * ZITADEL's v1 management API, `POST` and `DELETE /management/v1/metadata/<key>`,
+ * org-scoped by `x-zitadel-orgid`. A set is one upsert with the value in base64,
+ * so a repeat is no change. A remove of a key that is not there (404) is done.
+ * An error names the status, never the body.
+ */
+export function createZitadelOrgMetadata(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    async function call(method, orgId, key, body) {
+        if (!orgId)
+            throw new Error('org metadata: orgId is required');
+        const response = await fetchImpl(`${options.url}/management/v1/metadata/${encodeURIComponent(key)}`, {
+            method,
+            signal: AbortSignal.timeout(options.timeoutMs ?? CALL_TIMEOUT_MS),
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                'content-type': 'application/json',
+                'x-zitadel-orgid': orgId,
+                ...(options.instanceHost
+                    ? {
+                        'x-zitadel-instance-host': options.instanceHost,
+                        'x-forwarded-host': options.instanceHost,
+                        'x-forwarded-proto': 'https',
+                    }
+                    : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new ZitadelHttpError(response.status, `${method} org metadata '${key}' failed`);
+        }
+    }
+    return {
+        async setOrgMetadata(orgId, key, value) {
+            await call('POST', orgId, key, { value: Buffer.from(value, 'utf8').toString('base64') });
+        },
+        async removeOrgMetadata(orgId, key) {
+            try {
+                await call('DELETE', orgId, key);
+            }
+            catch (error) {
+                if (error instanceof ZitadelHttpError && error.status === 404)
+                    return;
+                throw error;
+            }
+        },
+    };
+}

package/package.json

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