@wtfalch/foundry 0.14.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/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.14.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"