@wtfalch/foundry 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, PlanDetail, PlatformPlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export type { PlatformOrgClientFactories } from './plan/index.js';

package/dist/index.js

@@ -5,7 +5,7 @@ export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
-export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';

package/dist/plan/agora.d.ts

@@ -106,6 +106,50 @@ export declare const CALLS_SERVICE_NAME_SCOPE_KEY = "coolify_calls_service_inter
 export declare function callsServiceInternalName(org: DeclaredOrg): string;
 /** Whether the recorded marker says the calls service carries the name the org's current slug gives it. */
 export declare function callsServiceHasName(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): boolean;
+/**
+ * Recorded once the calls service app carries the seven ZITADEL token env
+ * vars (`CALLS_ISSUER` ... `CALLS_INTROSPECTION_CLIENT_SECRET`,
+ * `calls/docs/member-auth.md`). Its value is {@link callsTokenEnvMarker}, so a
+ * changed issuer, audience or organisation plans the step again. The same
+ * marker-and-one-restart mechanism as {@link CALLS_SERVICE_NAME_SCOPE_KEY}.
+ */
+export declare const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = "coolify_calls_service_token_env";
+/**
+ * The introspection API app minted for the calls service (once), and the
+ * undelivered key recorded before its secret leaves the executor
+ * (`foundry/CLAUDE.md`, platform rule 1). No `:` in either, as that rule says.
+ */
+export declare const CALLS_INTROSPECTION_SCOPE_KEY = "zitadel_calls_introspection_app";
+export declare const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = "zitadel_calls_introspection_undelivered";
+/** What the plan hands the calls service step: the two host values the token env needs. */
+export interface CallsTokenHost {
+    issuer: string;
+    messagingProjectId: string;
+}
+/**
+ * The token env's inputs, or null while any is missing: the host's issuer and
+ * messaging project id (`AgoraHostValues`) and the org's recorded ZITADEL org
+ * id. Null means write none of the seven, never a partial set: the calls
+ * service refuses to boot on one.
+ */
+export declare function callsTokenHostFrom(host: AgoraHostValues): CallsTokenHost | null;
+/** The value {@link CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY} holds once the env is in place; null when it cannot be written yet. */
+export declare function callsTokenEnvMarker(host: CallsTokenHost | null, recorded: Readonly<Record<string, string>>): string | null;
+/**
+ * The calls service's introspection API app, in the messaging project. One per
+ * org: the project is shared by every org, so the name carries the slug (a DNS
+ * label, at most 63 characters) and only an exact match is ever deleted.
+ */
+export declare function callsIntrospectionAppName(org: DeclaredOrg): string;
+/**
+ * The block shown, and thrown, when the messaging project or the ZITADEL org
+ * differs from what the token env was written for: the recorded client
+ * belongs to the old project, and foundry does not replace or delete it. Null
+ * when nothing is recorded, or only the issuer differs (the client is kept).
+ */
+export declare function callsTokenEnvMovedMessage(org: DeclaredOrg, host: CallsTokenHost | null, recorded: Readonly<Record<string, string>>): string | null;
+/** True when there is nothing to write yet, or the recorded marker says it was written. */
+export declare function callsServiceHasTokenEnv(host: CallsTokenHost | null, recorded: Readonly<Record<string, string>>): boolean;
 /**
  * The env vars an org's Agora app should carry, and every input still
  * missing to build them. `AGORA_CONFIG` is present only when `missing` is

package/dist/plan/agora.js

@@ -109,6 +109,69 @@ export function callsServiceInternalName(org) {
 export function callsServiceHasName(org, recorded) {
     return recorded[CALLS_SERVICE_NAME_SCOPE_KEY] === callsServiceInternalName(org);
 }
+/**
+ * Recorded once the calls service app carries the seven ZITADEL token env
+ * vars (`CALLS_ISSUER` ... `CALLS_INTROSPECTION_CLIENT_SECRET`,
+ * `calls/docs/member-auth.md`). Its value is {@link callsTokenEnvMarker}, so a
+ * changed issuer, audience or organisation plans the step again. The same
+ * marker-and-one-restart mechanism as {@link CALLS_SERVICE_NAME_SCOPE_KEY}.
+ */
+export const CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY = 'coolify_calls_service_token_env';
+/**
+ * The introspection API app minted for the calls service (once), and the
+ * undelivered key recorded before its secret leaves the executor
+ * (`foundry/CLAUDE.md`, platform rule 1). No `:` in either, as that rule says.
+ */
+export const CALLS_INTROSPECTION_SCOPE_KEY = 'zitadel_calls_introspection_app';
+export const CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY = 'zitadel_calls_introspection_undelivered';
+/**
+ * The token env's inputs, or null while any is missing: the host's issuer and
+ * messaging project id (`AgoraHostValues`) and the org's recorded ZITADEL org
+ * id. Null means write none of the seven, never a partial set: the calls
+ * service refuses to boot on one.
+ */
+export function callsTokenHostFrom(host) {
+    if (!host.issuer || !host.messagingProjectId)
+        return null;
+    return { issuer: host.issuer, messagingProjectId: host.messagingProjectId };
+}
+/** The value {@link CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY} holds once the env is in place; null when it cannot be written yet. */
+export function callsTokenEnvMarker(host, recorded) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    if (!host || !zitadelOrgId)
+        return null;
+    return `${host.issuer} ${host.messagingProjectId} ${zitadelOrgId}`;
+}
+/**
+ * The calls service's introspection API app, in the messaging project. One per
+ * org: the project is shared by every org, so the name carries the slug (a DNS
+ * label, at most 63 characters) and only an exact match is ever deleted.
+ */
+export function callsIntrospectionAppName(org) {
+    return `calls-introspection-${org.slug}`;
+}
+/**
+ * The block shown, and thrown, when the messaging project or the ZITADEL org
+ * differs from what the token env was written for: the recorded client
+ * belongs to the old project, and foundry does not replace or delete it. Null
+ * when nothing is recorded, or only the issuer differs (the client is kept).
+ */
+export function callsTokenEnvMovedMessage(org, host, recorded) {
+    const wanted = callsTokenEnvMarker(host, recorded);
+    const written = recorded[CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY];
+    if (!wanted || !written || !recorded[CALLS_INTROSPECTION_SCOPE_KEY])
+        return null;
+    const [, oldProject, oldOrg] = written.split(' ');
+    const [, newProject, newOrg] = wanted.split(' ');
+    if (oldProject === newProject && oldOrg === newOrg)
+        return null;
+    return `${org.slug}'s calls service is blocked, not changed: the messaging project or ZITADEL org differs from the one its token env was written for (project ${oldProject} -> ${newProject}, org ${oldOrg} -> ${newOrg}); retire the ZITADEL app ${callsIntrospectionAppName(org)} (${recorded[CALLS_INTROSPECTION_SCOPE_KEY]}) in the old project by hand, then remove the recorded keys ${CALLS_INTROSPECTION_SCOPE_KEY} and ${CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY}`;
+}
+/** True when there is nothing to write yet, or the recorded marker says it was written. */
+export function callsServiceHasTokenEnv(host, recorded) {
+    const marker = callsTokenEnvMarker(host, recorded);
+    return marker === null || recorded[CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY] === marker;
+}
 /**
  * The env vars an org's Agora app should carry, and every input still
  * missing to build them. `AGORA_CONFIG` is present only when `missing` is

package/dist/plan/diff.js

@@ -1,6 +1,6 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
-import { NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, callsServiceHasName, desiredAgoraEnv, } from './agora.js';
+import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, } from './agora.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { appHostname, entryHostnames, tunnelDnsHostnames } from './hostnames.js';
 import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHostnameFor, pendingRemovalHosts, } from './login-host.js';
@@ -117,7 +117,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // (`executor.ts`'s `coolifyCallsService`) reads the Synapse/MAS addresses
     // and MAS client credentials `coolifyCalls` just recorded, the same
     // ordering `planOwner` relies on for `zitadel:issuer`.
-    const callsService = planCallsService(org, byKey, claimed, platformReadiness.callsReady, recordedIds, calls.blocked !== null);
+    const callsService = planCallsService(org, byKey, claimed, platformReadiness.callsReady, recordedIds, calls.blocked !== null, 'error' in agoraHost ? null : callsTokenHostFrom(agoraHost));
     if (callsService.step)
         plannedSteps.push(callsService.step);
     // #251: same mechanism as the platform's own version-change lines -- see
@@ -275,6 +275,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     }
     if (calls.blocked)
         unmanaged.push({ description: calls.blocked, key: 'coolify:calls' });
+    if (callsService.blocked) {
+        unmanaged.push({ description: callsService.blocked, key: 'coolify:calls-service' });
+    }
     if (filesOrganisation.blocked) {
         unmanaged.push({ description: filesOrganisation.blocked, key: 'files:organisation' });
     }
@@ -831,25 +834,55 @@ function planCalls(org, byKey, claimed, callsReady) {
  * stack it rides beside is itself blocked on `callsReady` -- {@link planCalls}
  * already reports the platform's shared SFU as missing once.
  */
-function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlocked) {
+function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlocked, tokenHost) {
     const key = resourceKey('coolify', 'calls-service', org.id);
     if (org.calls.enabled && !byKey.get(key) && !callsReady) {
         return { step: null, blocked: null };
     }
+    // The introspection secret is shown once. One minted but never written to
+    // the app is lost, so this reports it and mints no second (platform rule 1).
+    const undelivered = recordedIds[CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY];
+    if (org.calls.enabled &&
+        undelivered &&
+        !recordedIds[CALLS_INTROSPECTION_SCOPE_KEY] &&
+        byKey.has(key)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s calls service is blocked, not planned: its introspection client secret (ZITADEL app ${undelivered}) was minted but never written to the app and cannot be shown again; remove the recorded key ${CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY} (and delete the ZITADEL client) to mint a new one`,
+        };
+    }
+    const moved = org.calls.enabled && byKey.has(key)
+        ? callsTokenEnvMovedMessage(org, tokenHost, recordedIds)
+        : null;
+    if (moved)
+        return { step: null, blocked: moved };
     const toggle = planHostingToggle('coolify', 'calls-service', org.calls.enabled, org, byKey, claimed, () => `provision ${org.slug}'s calls service`, () => `park ${org.slug}'s calls service (stops serving; data is retained, not deleted -- #7 corrections 1)`);
+    // The host values ride in the step, as Agora's do, so the env written is
+    // the env the plan showed. Only while enabled: a park step carries none.
+    const withHost = (step) => tokenHost && org.calls.enabled
+        ? {
+            ...step,
+            action: {
+                ...step.action,
+                desired: { ...step.action.desired, host: tokenHost },
+            },
+        }
+        : step;
     if (toggle)
-        return { step: toggle, blocked: null };
-    // A live, enabled app made before the internal name existed (or under an
-    // old slug) has no step from the toggle, yet Agora's address needs the
-    // name. Run the step again until the executor has recorded the marker, but
-    // only while it can succeed: the SFU ready and the Matrix stack not blocked.
+        return { step: withHost(toggle), blocked: null };
+    // A live, enabled app made before the internal name or the token env
+    // existed has no step from the toggle. Run the step again until the
+    // executor has recorded both markers, but only while it can succeed: the
+    // SFU ready and the Matrix stack not blocked.
+    const missingName = !callsServiceHasName(org, recordedIds);
+    const missingTokenEnv = !callsServiceHasTokenEnv(tokenHost, recordedIds);
     if (org.calls.enabled &&
         callsReady &&
         !callsBlocked &&
         byKey.has(key) &&
-        !callsServiceHasName(org, recordedIds)) {
+        (missingName || missingTokenEnv)) {
         return {
-            step: {
+            step: withHost({
                 action: {
                     system: 'coolify',
                     kind: 'calls-service',
@@ -857,11 +890,13 @@ function planCallsService(org, byKey, claimed, callsReady, recordedIds, callsBlo
                     desired: { enabled: true },
                 },
                 step: {
-                    description: `set the calls service's internal name for ${org.slug}`,
+                    description: missingName
+                        ? `set the calls service's internal name for ${org.slug}`
+                        : `set the calls service's ZITADEL token env for ${org.slug}`,
                     destroys: false,
                     migrates: false,
                 },
-            },
+            }),
             blocked: null,
         };
     }

package/dist/plan/executor.d.ts

@@ -1767,6 +1767,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * 1); its own database is never touched from that branch.
      */
     private coolifyCallsService;
+    /**
+     * The seven ZITADEL token env vars the calls service needs to accept
+     * Agora's sign-in token (`calls/docs/member-auth.md`). Only called with all
+     * inputs present, so the set is whole or absent.
+     *
+     * The introspection client is an API app in the messaging project (the
+     * audience the token carries), minted once the way `platform-providers.ts`
+     * mints the files one: its id is recorded under an undelivered key and
+     * persisted before the secret leaves this method, the secret goes to
+     * `deliverSecret` with retries and to the app's env, never to a log, error
+     * or return value, and the guard is recorded by the caller after the env
+     * write. A re-run reads the client id and secret back from the app's own
+     * env and mints nothing.
+     */
+    private callsTokenEnvs;
     /**
      * Reads back the calls Matrix stack's MAS client id/secret from the MAS
      * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting

package/dist/plan/executor.js

@@ -2,7 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
 import { APP_ENTRY_KEY, appEntry } from '../org.js';
-import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, agoraHostnameFor, callsServiceHasName, callsServiceInternalName, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
 import { MAS_IMAGE, MAS_TAG, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
@@ -2452,21 +2452,118 @@ export class FoundryStepExecutor {
             { key: 'SYNAPSE_URL', value: `http://${synapseHost}:8008` },
             { key: 'CALLS_ORIGIN', value: `https://${agoraHostnameFor(org)}` },
             { key: 'CALLS_HOST_ADAPTER', value: 'production' },
+            // Deliberately kept as it was, not widened: the calls service refuses to
+            // boot with no `CALLS_TRUSTED_IP_HEADER` (`config.mjs` has no default),
+            // so unsetting it would stop the service. It keys the refused-bearer
+            // limiter, which is only as honest as the proxy in front overwriting
+            // this header (https://github.com/wtfalch/calls/issues/82).
             { key: 'CALLS_TRUSTED_IP_HEADER', value: 'cf-connecting-ip' },
             { key: 'PORT', value: CALLS_SERVICE_PORT },
         ];
         if (bindingSecret)
             envs.push({ key: 'CALLS_BINDING_SECRET', value: bindingSecret });
+        // The seven ZITADEL token vars, all or none (the service refuses to boot
+        // on a partial set). Deliberately absent: `CALLS_CHAT_URL` and
+        // `CALLS_CHAT_TOKEN`. Foundry does not deploy chat
+        // (https://github.com/wtfalch/chat/issues/40), so with both unset the
+        // calls service admits only `event:` rooms.
+        const tokenHost = action.desired.host;
+        const tokenMarker = callsTokenEnvMarker(tokenHost ?? null, context.recordedIds());
+        const token = tokenHost && tokenMarker
+            ? await this.callsTokenEnvs(org, app.appId, tokenHost, context)
+            : null;
+        if (token)
+            envs.push(...token.envs);
         await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
+        // Recorded after the write, so a failure before it leaves the app
+        // unguarded and the planner reports the lost secret instead of minting again.
+        if (token)
+            context.recordScopeId(CALLS_INTROSPECTION_SCOPE_KEY, token.appId);
         // A container reads its name and env only at start, so a running app is
-        // restarted once, when this run is the one that gave it its name (the same
-        // rule `coolifyApp` follows when an existing app's env changed).
-        if (app.existed && !callsServiceHasName(org, context.recordedIds())) {
+        // restarted once, when this run is the one that gave it its name or its
+        // token env (the same rule `coolifyApp` follows when an existing app's
+        // env changed).
+        const givesTokenEnv = token !== null && context.recordedIds()[CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY] !== tokenMarker;
+        if (app.existed && (!callsServiceHasName(org, context.recordedIds()) || givesTokenEnv)) {
             await this.ports.coolify.restart(app.appId);
         }
         context.recordScopeId(CALLS_SERVICE_NAME_SCOPE_KEY, name);
+        if (token && tokenMarker)
+            context.recordScopeId(CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, tokenMarker);
         return { resourceId: app.appId };
     }
+    /**
+     * The seven ZITADEL token env vars the calls service needs to accept
+     * Agora's sign-in token (`calls/docs/member-auth.md`). Only called with all
+     * inputs present, so the set is whole or absent.
+     *
+     * The introspection client is an API app in the messaging project (the
+     * audience the token carries), minted once the way `platform-providers.ts`
+     * mints the files one: its id is recorded under an undelivered key and
+     * persisted before the secret leaves this method, the secret goes to
+     * `deliverSecret` with retries and to the app's env, never to a log, error
+     * or return value, and the guard is recorded by the caller after the env
+     * write. A re-run reads the client id and secret back from the app's own
+     * env and mints nothing.
+     */
+    async callsTokenEnvs(org, appId, host, context) {
+        const recorded = context.recordedIds();
+        const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+        const scope = (clientId, clientSecret) => [
+            { key: 'CALLS_ISSUER', value: host.issuer },
+            { key: 'CALLS_AUDIENCE', value: host.messagingProjectId },
+            { key: 'CALLS_ORGANISATION_ID', value: zitadelOrgId },
+            // Chat's own scope (`apps/chat-service`): the audience, and `estate`.
+            { key: 'CALLS_APPLICATION_ID', value: host.messagingProjectId },
+            { key: 'CALLS_PLATFORM_ID', value: 'estate' },
+            { key: 'CALLS_INTROSPECTION_CLIENT_ID', value: clientId },
+            { key: 'CALLS_INTROSPECTION_CLIENT_SECRET', value: clientSecret },
+        ];
+        const done = recorded[CALLS_INTROSPECTION_SCOPE_KEY];
+        const undelivered = recorded[CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY];
+        if (undelivered && !done) {
+            throw new Error(`coolify:calls-service for ${org.slug}: the introspection client secret (ZITADEL app ${undelivered}) was minted but never written; remove the recorded key ${CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        // A changed project or org is never replaced here (see the message); an
+        // issuer-only change keeps the client and rewrites the env below.
+        const moved = callsTokenEnvMovedMessage(org, host, recorded);
+        if (moved)
+            throw new Error(`coolify:calls-service: ${moved}`);
+        if (done) {
+            const envs = await this.ports.coolify.listEnvs(appId);
+            const read = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+            const clientId = read('CALLS_INTROSPECTION_CLIENT_ID');
+            const clientSecret = read('CALLS_INTROSPECTION_CLIENT_SECRET');
+            if (!clientId || !clientSecret) {
+                throw new Error(`coolify:calls-service for ${org.slug}: the introspection client (ZITADEL app ${done}) is recorded but its id or secret is no longer on the app; remove the recorded keys ${CALLS_INTROSPECTION_SCOPE_KEY} and ${CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY}, and delete the ZITADEL client, to mint a new one`);
+            }
+            return { envs: scope(clientId, clientSecret), appId: done };
+        }
+        // An app by this name with no recorded secret is a crash between create
+        // and record: nothing was delivered, so it is deleted and made again.
+        const stale = (await this.ports.zitadel.listApps(zitadelOrgId, host.messagingProjectId)).apps.filter((app) => app.name === callsIntrospectionAppName(org) && app.state !== 'APP_STATE_REMOVED');
+        for (const app of stale) {
+            try {
+                await this.ports.zitadel.deleteApp(zitadelOrgId, host.messagingProjectId, app.id);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        const client = await this.ports.zitadel.createApiApp(zitadelOrgId, host.messagingProjectId, {
+            name: callsIntrospectionAppName(org),
+        });
+        context.recordScopeId(CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, client.appId);
+        await context.persistScopeIds();
+        if (!(await this.deliverWithRetry(`zitadel:calls:${org.slug}:introspection`, client.clientSecret))) {
+            throw new Error(`coolify:calls-service for ${org.slug}: the introspection client secret (ZITADEL app ${client.appId}) could not be delivered after ${JOBS_DELIVERY_ATTEMPTS} attempts`);
+        }
+        return {
+            envs: scope(client.clientId, client.clientSecret),
+            appId: client.appId,
+        };
+    }
     /**
      * Reads back the calls Matrix stack's MAS client id/secret from the MAS
      * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting

package/dist/plan/index.d.ts

@@ -3,7 +3,7 @@ export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export type { PlatformPlanDetail } from './platform-diff.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export type { PlatformOrgClientFactories } from './platform-org-ports.js';

package/dist/plan/index.js

@@ -1,6 +1,6 @@
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';

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

@@ -299,6 +299,14 @@ export declare const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = "mail_applied_git
  * own internal address, never its admin credential.
  */
 export declare const PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY = "mail_internal_url";
+/**
+ * #346: the mail ZITADEL project's id in the platform's own sign-in, the
+ * {@link PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY} pattern for mail --
+ * `provisionPlatformMail` finds or creates it and uses the id as the OIDC
+ * audience Stalwart's directory checks an access token's `aud` claim
+ * against, so no host has to register one by hand.
+ */
+export declare const PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY = "zitadel_platform_mail_project";
 /**
  * #177: the one host the platform's mail server takes SMTP/MX on, and so the
  * `mailHost` every org's own mail step writes. `provisionPlatformMail` (the

package/dist/plan/platform-diff.js

@@ -330,6 +330,14 @@ export const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = 'mail_applied_git_ref';
  * own internal address, never its admin credential.
  */
 export const PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY = 'mail_internal_url';
+/**
+ * #346: the mail ZITADEL project's id in the platform's own sign-in, the
+ * {@link PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY} pattern for mail --
+ * `provisionPlatformMail` finds or creates it and uses the id as the OIDC
+ * audience Stalwart's directory checks an access token's `aud` claim
+ * against, so no host has to register one by hand.
+ */
+export const PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_platform_mail_project';
 /**
  * #177: the one host the platform's mail server takes SMTP/MX on, and so the
  * `mailHost` every org's own mail step writes. `provisionPlatformMail` (the

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

@@ -248,10 +248,10 @@ export declare const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = "foundry:platform:adm
  * instance's own URL and the recovery-admin credential this step generated
  * ({@link PlatformMailDeps.stalwartForInstance}), the same way
  * `zitadelForInstance` is built from a freshly issued instance's issuer URL.
- * The real implementation wraps `@wtfalch/email/postmaster`'s `openInstance`
- * (for the `StalwartClient`), a hand-built settings write (see
- * `provisionPlatformMail`'s own doc comment for why not `mailObjects`) and
- * `StalwartClient.createApiKey`.
+ * {@link defaultStalwartForInstance} is the real implementation, wrapping
+ * `@wtfalch/email/postmaster`'s `openInstance`, `applyObjects` with
+ * `platformMailSettingsObjects` (see `provisionPlatformMail`'s own doc
+ * comment for why not `mailObjects`) and `StalwartClient.createApiKey`.
  */
 export interface PlatformMailAdminPort {
     /**
@@ -261,6 +261,8 @@ export interface PlatformMailAdminPort {
      */
     applySettings(input: {
         mailHost: string;
+        /** The platform's own apex domain, `platformMailSettingsObjects`'s `usernameDomain`. */
+        apex: string;
         oidc: {
             issuerUrl: string;
             audience: string;
@@ -269,6 +271,26 @@ export interface PlatformMailAdminPort {
     /** `StalwartClient.createApiKey`'s own signature. */
     createApiKey(description: string, permissions: readonly string[] | 'inherit'): Promise<string>;
 }
+/**
+ * #346: the real {@link PlatformMailAdminPort}, built from the instance's URL
+ * and the recovery-admin credential `provisionPlatformMail` just read back.
+ * `stalwartForInstance` defaults to this, so a host need not build its own --
+ * the narrower settings write `provisionPlatformMail`'s own doc comment
+ * explains ("Why not `mailObjects`/`applyObjects`" as-is) instead goes
+ * through `platformMailSettingsObjects`, which `applyObjects` resolves and
+ * writes the same way `mailObjects` would.
+ *
+ * Exported only so a unit test can call it directly against a mocked
+ * `@wtfalch/email/postmaster` and check that `url`/`user`/`password` reach
+ * `openInstance` and `apex` reaches `applySettings` -- every other test
+ * reaches this function only indirectly, through an injected
+ * `stalwartForInstance` fake.
+ */
+export declare function defaultStalwartForInstance(input: {
+    url: string;
+    user: string;
+    password: string;
+}): PlatformMailAdminPort;
 /**
  * #169: everything {@link provisionPlatformMail} needs beyond
  * {@link PlatformStepExecutionContext}, mirroring {@link PlatformAuthDeps}'s
@@ -278,18 +300,22 @@ export interface PlatformMailDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'raw' | 'listStorages' | 'createPersistentStorage' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
     /**
-     * The ZITADEL resource id an access token's `aud` claim must carry for
-     * Stalwart's OIDC directory to accept it -- a resource API registered
-     * against the platform's own sign-in (#168), which neither that step nor
-     * this one creates. See `provisionPlatformMail`'s own doc comment, "Known
-     * gaps".
+     * Must target the platform's own ZITADEL instance, or `zitadelForInstance`
+     * must be set. `provisionPlatformMail` finds or creates a `mail` project
+     * in it (the {@link PlatformFilesDeps}/{@link PlatformArchonDeps} pattern)
+     * and uses the project's id as the OIDC audience Stalwart's directory
+     * checks an access token's `aud` claim against -- #346, no host has to
+     * register a resource API for this by hand any more.
      */
-    oidcAudience: string;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject'>;
+    /** {@link PlatformArchonDeps.zitadelForInstance}, for Stalwart's OIDC directory. */
+    zitadelForInstance?: (issuerUrl: string) => PlatformMailDeps['zitadel'];
     /**
      * {@link PlatformMailAdminPort}, built from the instance this step just
-     * deployed and the recovery credential it just read back.
+     * deployed and the recovery credential it just read back. Defaults to
+     * {@link defaultStalwartForInstance}.
      */
-    stalwartForInstance(input: {
+    stalwartForInstance?(input: {
         url: string;
         user: string;
         password: string;

package/dist/plan/platform-providers.js

@@ -1,10 +1,11 @@
 import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign, } from 'node:crypto';
 import { isIPv4 } from 'node:net';
+import { applyObjects, openInstance, platformMailSettingsObjects } from '@wtfalch/email/postmaster';
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { ACCESS_POLICY_NAME, isNotFoundError, isRunningOrStarting } from './executor.js';
-import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
 import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
@@ -1389,6 +1390,32 @@ const PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY = 'mail_deployed_git_ref';
  * {@link PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} records in that case.
  */
 export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
+/**
+ * #346: the real {@link PlatformMailAdminPort}, built from the instance's URL
+ * and the recovery-admin credential `provisionPlatformMail` just read back.
+ * `stalwartForInstance` defaults to this, so a host need not build its own --
+ * the narrower settings write `provisionPlatformMail`'s own doc comment
+ * explains ("Why not `mailObjects`/`applyObjects`" as-is) instead goes
+ * through `platformMailSettingsObjects`, which `applyObjects` resolves and
+ * writes the same way `mailObjects` would.
+ *
+ * Exported only so a unit test can call it directly against a mocked
+ * `@wtfalch/email/postmaster` and check that `url`/`user`/`password` reach
+ * `openInstance` and `apex` reaches `applySettings` -- every other test
+ * reaches this function only indirectly, through an injected
+ * `stalwartForInstance` fake.
+ */
+export function defaultStalwartForInstance(input) {
+    const instance = openInstance({ url: input.url, secret: input.password, user: input.user });
+    return {
+        async applySettings({ mailHost, apex, oidc }) {
+            await applyObjects(instance.client, platformMailSettingsObjects({ apex, mailHost, oidc }), () => { });
+        },
+        createApiKey: (description, permissions) => instance.client.createApiKey(description, permissions),
+    };
+}
+/** The ZITADEL project and resource api Stalwart's own OIDC directory checks access tokens' `aud` claim against (#346). */
+const PLATFORM_MAIL_ZITADEL_PROJECT_NAME = 'mail';
 /**
  * #169: makes `coolify:app` keyed {@link PLATFORM_MAIL_KEY} true -- Stalwart
  * on Coolify with its own persistent storage, reached at
@@ -1423,8 +1450,9 @@ export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
  * 0006), and this step provisions no Cloudflare DNS token for Stalwart's own
  * ACME either. Calling it as-is would mint an outbound relay this platform
  * does not want and a credential requirement this issue does not cover, so
- * {@link PlatformMailAdminPort.applySettings} is a narrower, hand-built
- * settings write instead: the default hostname and the OIDC directory only.
+ * {@link PlatformMailAdminPort.applySettings} is a narrower settings write
+ * instead, through `platformMailSettingsObjects`: the default hostname and
+ * the OIDC directory only.
  *
  * Known gaps, left for review (like #168's own "the PR stays open for
  * William's review"):
@@ -1432,11 +1460,6 @@ export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
  *   Stalwart's own self-signed certificate until a follow-up wires a real
  *   one (`mailObjects`'s `AcmeProvider`/`DnsServer` shape, minus the Resend
  *   relay it also carries).
- * - **`oidcAudience` is supplied, not resolved.** #168 mints foundry's own
- *   ZITADEL admin machine user but registers no resource API for Stalwart's
- *   access-token `aud` check; whoever supplies
- *   {@link PlatformMailDeps.oidcAudience} must have registered one by hand
- *   until that is built.
  * - **The Lettermint team token the org app step reads still comes from
  *   wherever the host already reads it, not held keys.** Needs
  *   `StepExecutionContext` to carry the platform, which `plan-apply.ts`'s
@@ -1446,6 +1469,17 @@ export const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = 'foundry:platform:admin';
  *   instance -- `diff.ts`'s `planMail` already blocks the step until the
  *   platform's own mail is applied, so the fallback only ever served a
  *   plan recorded before that, and now fails loudly instead.)
+ * - **A ZITADEL client's token may not carry the mail project's id in
+ *   `aud` by default.** #346's own "Human steps": confirm this on the first
+ *   live run, and if it does not, the client must request the mail
+ *   project's audience scope.
+ * - **The admin API key is minted with `'inherit'` permissions**, not a
+ *   narrower set scoped to only what `applySettings` needs.
+ * - **The undelivered-key guard records before `createApiKey` mints**, not
+ *   after -- so a crash between the two records an id (`admin.createApiKey`
+ *   has not even run) that no key was ever minted for. Harmless today
+ *   (the guard only ever blocks a retry and names an id to revoke by), but
+ *   worth tightening if `createApiKey` ever starts returning its own id.
  */
 async function provisionPlatformMail(context, deps) {
     const { platform } = context;
@@ -1610,6 +1644,57 @@ async function provisionPlatformMail(context, deps) {
             proxied: false,
         });
     }
+    // ---- the mail ZITADEL project, in the platform's sign-in -------------------
+    // #346: found or created on every run, like the files/Archon steps' own
+    // projects -- its id is the OIDC audience Stalwart's directory checks an
+    // access token's `aud` claim against, so no host has to register a
+    // resource API for this by hand.
+    const issuer = `https://${platform.auth.hostname}`;
+    const zitadel = deps.zitadelForInstance?.(issuer) ?? deps.zitadel;
+    const { org } = await zitadel.findOrCreateOrg(PLATFORM_AUTH_ORG_NAME);
+    const { project } = await zitadel.findOrCreateProject(org.id, PLATFORM_MAIL_ZITADEL_PROJECT_NAME);
+    const recordedProjectId = recorded[PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY];
+    const adminKeyRecorded = Boolean(recorded[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]);
+    if (adminKeyRecorded && recordedProjectId !== project.id) {
+        // #346 round 3: the OIDC-directory write below (next block) runs only
+        // once, while the admin key is unrecorded -- so once it is recorded, a
+        // changed project id (the project was deleted and recreated, ZITADEL was
+        // re-bootstrapped, or `recordedProjectId` is simply missing, from a
+        // platform applied before this change) has no other path back to a
+        // correct audience. Re-apply the settings write with the new id, over
+        // the same recovery-admin credential the first run reads back, and mint
+        // no new key -- that stays gated on the admin key being unrecorded,
+        // below. The record is written only after `applySettings` succeeds, so a
+        // throw here leaves the old (still-required) id in place for the next
+        // run to retry. A project deleted out of band is noticed only here, on
+        // the next plan/apply -- the same way the files/Archon steps' own
+        // projects are.
+        await waitForMailInstance(`https://${hostname}${STALWART_READY_PATH}`, runtime, sleep);
+        const recoveryEnv = (await deps.coolify.listEnvs(appId)).find((e) => e.key === 'STALWART_RECOVERY_ADMIN' && !e.is_preview);
+        if (!recoveryEnv) {
+            throw new Error('platform:mail: STALWART_RECOVERY_ADMIN is not set on the app; cannot authenticate to re-apply the OIDC audience');
+        }
+        const password = recoveryEnv.value.slice(`${STALWART_RECOVERY_USER}:`.length);
+        try {
+            const admin = (deps.stalwartForInstance ?? defaultStalwartForInstance)({
+                url: `https://${hostname}`,
+                user: STALWART_RECOVERY_USER,
+                password,
+            });
+            await admin.applySettings({
+                mailHost,
+                apex: platform.apex,
+                oidc: { issuerUrl: issuer, audience: project.id },
+            });
+            await record(PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+        }
+        catch (error) {
+            throw redactedMailError(error, [password]);
+        }
+    }
+    else if (!recordedProjectId) {
+        await record(PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, project.id);
+    }
     // ---- OIDC directory and foundry's own admin API key, once --------------------
     if (!recorded[PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY]) {
         const lost = recorded[PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY];
@@ -1623,14 +1708,15 @@ async function provisionPlatformMail(context, deps) {
         }
         const password = recoveryEnv.value.slice(`${STALWART_RECOVERY_USER}:`.length);
         try {
-            const admin = deps.stalwartForInstance({
+            const admin = (deps.stalwartForInstance ?? defaultStalwartForInstance)({
                 url: `https://${hostname}`,
                 user: STALWART_RECOVERY_USER,
                 password,
             });
             await admin.applySettings({
                 mailHost,
-                oidc: { issuerUrl: `https://${platform.auth.hostname}`, audience: deps.oidcAudience },
+                apex: platform.apex,
+                oidc: { issuerUrl: issuer, audience: project.id },
             });
             // Recorded and persisted before the secret leaves this function: if
             // delivery fails for good, the next plan reports the lost key rather
@@ -1696,9 +1782,9 @@ async function resolveMailServer(coolify, recordedUuid) {
 }
 /**
  * The mail step's own reasons it cannot run yet, as fixed text: missing
- * dependencies or audience, a floating image tag, a server with no usable
- * address. Skipped once the step is applied at the declared values, so a
- * live app is not blocked by a later Coolify change to the server's address.
+ * dependencies, a floating image tag, a server with no usable address.
+ * Skipped once the step is applied at the declared values, so a live app is
+ * not blocked by a later Coolify change to the server's address.
  */
 async function mailBlockedReason(platform, mail, recordedIds) {
     if (!mail) {
@@ -1710,9 +1796,6 @@ async function mailBlockedReason(platform, mail, recordedIds) {
         recordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY]) {
         return null;
     }
-    if (!mail.oidcAudience || mail.oidcAudience.trim() === '') {
-        return "the platform's mail server is blocked, not planned: the host supplies no oidcAudience, the ZITADEL resource id Stalwart's OIDC directory checks access tokens against";
-    }
     const tagBlocked = mailImageTagBlocked(platform.mail.gitRef);
     if (tagBlocked)
         return tagBlocked;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@wtfalch/audit": "0.6.0",
     "@wtfalch/auth": "0.16.0",
-    "@wtfalch/email": "0.15.0",
+    "@wtfalch/email": "^0.17.0",
     "@wtfalch/providers": "0.6.0",
     "ssh2": "1.17.0",
     "zod": "4.6.5"