@wtfalch/foundry 0.16.8 → 0.16.10

package/dist/plan/diff.js

@@ -1,6 +1,6 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ownerMailboxRecorded, ownerMailboxes } from '../org.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, withRecordedMessagingProject, } from './agora.js';
+import { CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, bouleEnvDrift, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
@@ -1003,6 +1003,15 @@ function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
  * #177: blocked, not planned, while `filesReady` is false -- the platform's
  * own files host (#171) is off or not yet applied, so there is nothing here
  * for `FilesOrganisationPort.provisionOrganisation` to reach.
+ *
+ * #273: `desired.agoraOrigin` is every org's own Agora origin (#164's
+ * `agoraHostnameFor`, always on, never blocked on anything this step
+ * doesn't already wait for) -- `executor.ts`'s `filesOrganisation` adds it
+ * to the files host's CORS allowlist alongside provisioning. Known gap: a
+ * later domain change that moves Agora's hostname is not replanned here,
+ * since this step (like `planIssuer`) has nothing to diff once the org's
+ * Files organisation already exists -- the old origin is left allowed
+ * rather than silently dropped.
  */
 function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, noKeyReader = false) {
     const key = resourceKey('files', 'organisation', org.id);
@@ -1023,7 +1032,12 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
                 system: 'files',
                 kind: 'organisation',
                 key: org.id,
-                desired: { provision: true, ceilingBytes: null, ceilingMicros: null },
+                desired: {
+                    provision: true,
+                    ceilingBytes: null,
+                    ceilingMicros: null,
+                    agoraOrigin: `https://${agoraHostnameFor(org)}`,
+                },
             },
             step: {
                 description: `provision ${org.slug}'s own organisation on Files`,

package/dist/plan/executor.d.ts

@@ -1114,6 +1114,20 @@ export interface FilesOrganisationPort {
         name: string;
         created: boolean;
     }>;
+    /**
+     * #273: adds `origin` to the files host's `FILES_ALLOWED_ORIGINS`
+     * allowlist (`wtfalch/files#109`) -- additively, never removing another
+     * organisation's entry already there. That list is a Coolify env var on
+     * the files runner app, not a database row the files management API
+     * reports back (files#109's own reasoning: a database round trip on the
+     * unauthenticated CORS preflight is both a hot-path cost and a new way to
+     * fail closed), so there is nothing here to diff against a live value --
+     * the host decides how `origin` actually reaches that env var, the same
+     * way every other method on this port decides how to speak the service's
+     * protocol. Safely repeatable: calling it again with an origin already on
+     * the list is a no-op.
+     */
+    ensureAllowedOrigin(organisationId: string, origin: string): Promise<void>;
 }
 /**
  * Provisions one org's organisation on AI and switches its AI use on (#80),
@@ -2345,6 +2359,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
      * this is called every time regardless of whether it already ran --
      * idempotent by find-or-create, not by checking `recordedIds` first.
+     *
+     * #273: also ensures the org's Agora origin is on the files host's CORS
+     * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
+     * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org
+     * gets an Agora (#164), so `diff.ts`'s `planFilesOrganisation` always sets
+     * `desired.agoraOrigin`.
      */
     private filesOrganisation;
     /**

package/dist/plan/executor.js

@@ -3970,6 +3970,12 @@ export class FoundryStepExecutor {
      * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
      * this is called every time regardless of whether it already ran --
      * idempotent by find-or-create, not by checking `recordedIds` first.
+     *
+     * #273: also ensures the org's Agora origin is on the files host's CORS
+     * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
+     * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org
+     * gets an Agora (#164), so `diff.ts`'s `planFilesOrganisation` always sets
+     * `desired.agoraOrigin`.
      */
     async filesOrganisation(action, org, context) {
         const files = await this.filesPort();
@@ -3985,6 +3991,9 @@ export class FoundryStepExecutor {
             ceilingMicros: action.desired.ceilingMicros ?? null,
             ...(owner ? { name: org.displayName, owner } : {}),
         });
+        const agoraOrigin = action.desired.agoraOrigin;
+        if (agoraOrigin)
+            await files.ensureAllowedOrigin(org.id, agoraOrigin);
         // Recorded now, so the org key is minted below the member files made.
         if (owner && provisioned.created)
             context.recordScopeId(FILES_ORG_OWNER_SCOPE_KEY, owner);

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

@@ -250,7 +250,8 @@ export declare const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = "foundry:platform:adm
  * ({@link PlatformMailDeps.stalwartForInstance}), the same way
  * `zitadelForInstance` is built from a freshly issued instance's issuer URL.
  * {@link defaultStalwartForInstance} is the real implementation, wrapping
- * `@wtfalch/email/postmaster`'s `openInstance`, `applyObjects` with
+ * `@wtfalch/email/postmaster`'s `openInstance`, `Bootstrap/set` while the
+ * server is still in bootstrap mode, `applyObjects` with
  * `platformMailSettingsObjects` (see `provisionPlatformMail`'s own doc
  * comment for why not `mailObjects`) and `StalwartClient.createApiKey`.
  */
@@ -258,7 +259,10 @@ export interface PlatformMailAdminPort {
     /**
      * Sets the instance's default hostname and its OIDC directory
      * (`x:SystemSettings`/`x:Directory`/`x:Domain`/`x:Authentication`) --
-     * idempotent, safe to call on every apply once the instance is up.
+     * idempotent, safe to call on every apply once the instance is up. A fresh
+     * instance is first given its `Bootstrap` config; Stalwart 0.16 loads that
+     * only on its next start, so the call then returns `'restart'` having
+     * written nothing else. The caller restarts the app and calls again.
      */
     applySettings(input: {
         mailHost: string;
@@ -268,8 +272,12 @@ export interface PlatformMailAdminPort {
             issuerUrl: string;
             audience: string;
         };
-    }): Promise<void>;
-    /** `StalwartClient.createApiKey`'s own signature. */
+    }): Promise<'restart' | undefined>;
+    /**
+     * `StalwartClient.createApiKey`'s own signature. The key belongs to a real
+     * admin account, not to the recovery admin (see
+     * {@link defaultStalwartForInstance}).
+     */
     createApiKey(description: string, permissions: readonly string[] | 'inherit'): Promise<string>;
 }
 /**
@@ -291,6 +299,8 @@ export declare function defaultStalwartForInstance(input: {
     url: string;
     user: string;
     password: string;
+    /** The platform's apex: the domain of the admin account the API key is minted as. */
+    apex: string;
 }): PlatformMailAdminPort;
 /**
  * #169: everything {@link provisionPlatformMail} needs beyond
@@ -320,6 +330,7 @@ export interface PlatformMailDeps {
         url: string;
         user: string;
         password: string;
+        apex: string;
     }): PlatformMailAdminPort;
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
     /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */

package/dist/plan/platform-providers.js

@@ -1413,7 +1413,20 @@ const STALWART_PORTS_EXPOSES = [STALWART_HTTP_PORT, ...STALWART_SMTP_PORTS].join
  * ZITADEL/login apps.
  */
 const STALWART_PORTS_MAPPINGS = STALWART_SMTP_PORTS.map((p) => `${p}:${p}`).join(',');
-const STALWART_DATA_MOUNT = '/opt/stalwart';
+/**
+ * The v0.16 image's two VOLUMEs (its Dockerfile): the data store, and the
+ * `config.json` Stalwart writes when bootstrap completes. The pre-0.16 image
+ * used `/opt/stalwart`, which v0.16 does not use. Each is a Coolify
+ * persistent storage (a Docker named volume, not a host path), so Docker
+ * seeds it from the image on first use and keeps the image's UID 2000
+ * ownership, which the container needs to write it.
+ */
+// Suffixes differ from the pre-0.16 storage's `-data` (still attached at
+// /opt/stalwart on apps created before), so a new storage never shares its name.
+const STALWART_STORAGES = [
+    { suffix: 'var-lib', mount_path: '/var/lib/stalwart' },
+    { suffix: 'etc', mount_path: '/etc/stalwart' },
+];
 /** `STALWART_RECOVERY_ADMIN=<user>:<password>` -- the fixed recovery account name; only the password half is generated. */
 const STALWART_RECOVERY_USER = 'admin';
 /**
@@ -1474,11 +1487,58 @@ export function defaultStalwartForInstance(input) {
     });
     return {
         async applySettings({ mailHost, apex, oidc }) {
+            // A fresh Stalwart (0.16) is in bootstrap mode and refuses every write
+            // but the `Bootstrap` object, and loads that object only on its next
+            // start, so write it and hand the restart to the caller. A server
+            // already past it skips this. `update` drops the response, which
+            // carries the generated `admin@<apex>` secret: this step signs in with
+            // the recovery admin and never needs it.
+            if ((await instance.client.probe()) === 'bootstrap') {
+                await instance.client.update('Bootstrap', 'singleton', {
+                    serverHostname: mailHost,
+                    defaultDomain: apex,
+                    // The server sits behind a tunnel; no ACME challenge can reach it.
+                    requestTlsCertificate: false,
+                });
+                return 'restart';
+            }
             await applyObjects(instance.client, platformMailSettingsObjects({ apex, mailHost, oidc }), () => { });
         },
-        createApiKey: (description, permissions) => instance.client.createApiKey(description, permissions),
+        async createApiKey(description, permissions) {
+            // The recovery admin is not a directory account (Stalwart's
+            // `account_set` in `jmap/src/registry/mapping/account.rs` finds no
+            // Account for its id and answers notFound), so it cannot own a key. Give an internal admin account (no credential, so
+            // nothing to sign in with, and the OIDC directory is never asked) and
+            // act as it: the recovery admin may impersonate any account as
+            // `<account>%<recovery user>`.
+            const domains = await instance.client.list('Domain');
+            const domain = domains.find((d) => d.name === input.apex);
+            if (!domain) {
+                throw new Error(`platform:mail: Stalwart has no domain ${input.apex} to hold the admin account`);
+            }
+            await instance.client.upsert('Account', (a) => a.name === PLATFORM_MAIL_ADMIN_ACCOUNT && a.domainId === domain.id, {
+                '@type': 'User',
+                name: PLATFORM_MAIL_ADMIN_ACCOUNT,
+                domainId: domain.id,
+                description: 'foundry platform admin (API key owner)',
+                roles: { '@type': 'Admin' },
+                permissions: { '@type': 'Inherit' },
+                encryptionAtRest: { '@type': 'Disabled' },
+                quotas: {},
+                aliases: {},
+                memberGroupIds: {},
+            }, {});
+            const asAdmin = openInstance({
+                url: input.url,
+                secret: input.password,
+                user: `${PLATFORM_MAIL_ADMIN_ACCOUNT}@${input.apex}%${input.user}`,
+            });
+            return asAdmin.client.createApiKey(description, permissions);
+        },
     };
 }
+/** The internal account the admin API key belongs to, in the platform's apex domain. */
+const PLATFORM_MAIL_ADMIN_ACCOUNT = 'foundry-admin';
 /** 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';
 /**
@@ -1608,12 +1668,19 @@ async function provisionPlatformMail(context, deps) {
     await record(PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, `http://${PLATFORM_MAIL_INTERNAL_NAME}:${STALWART_HTTP_PORT}`);
     // ---- storage ---------------------------------------------------------------
     const storages = await deps.coolify.listStorages(appId);
-    const hasDataVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === STALWART_DATA_MOUNT);
-    if (!hasDataVolume) {
+    // An app made before this release only has the old `/opt/stalwart` volume.
+    // That one is left in place (empty and unused; detaching it needs a call this
+    // step has no port for) and the two real ones are added.
+    let storagesAdded = false;
+    for (const wanted of STALWART_STORAGES) {
+        if ((storages.persistent_storages ?? []).some((st) => st.mount_path === wanted.mount_path)) {
+            continue;
+        }
         await deps.coolify.createPersistentStorage(appId, {
-            name: `${PLATFORM_MAIL_APP_NAME}-data`,
-            mount_path: STALWART_DATA_MOUNT,
+            name: `${PLATFORM_MAIL_APP_NAME}-${wanted.suffix}`,
+            mount_path: wanted.mount_path,
         });
+        storagesAdded = true;
     }
     // ---- env ---------------------------------------------------------------------
     // Generated once; unlike ZITADEL's masterkey this is never re-derived from
@@ -1630,7 +1697,8 @@ async function provisionPlatformMail(context, deps) {
     await deps.coolify.bulkUpsertEnvs(appId, envs);
     const declaredChanged = recorded[PLATFORM_MAIL_DEPLOYED_HOSTNAME_SCOPE_KEY] !== hostname ||
         recorded[PLATFORM_MAIL_DEPLOYED_GIT_REF_SCOPE_KEY] !== imageTag;
-    if (app.justCreated || !app.running || envsChanged || declaredChanged) {
+    // A new storage binds into the container only at its next start.
+    if (app.justCreated || !app.running || envsChanged || declaredChanged || storagesAdded) {
         // A container still up from before would answer the readiness probe with
         // the old deployment's health. Stop it and see it stopped first, so the
         // wait below only ever reads the new deployment.
@@ -1748,11 +1816,19 @@ async function provisionPlatformMail(context, deps) {
                 url: `https://${hostname}`,
                 user: STALWART_RECOVERY_USER,
                 password,
-            });
-            await admin.applySettings({
-                mailHost,
                 apex: platform.apex,
-                oidc: { issuerUrl: issuer, audience: project.id },
+            });
+            await applyMailSettings(admin, {
+                coolify: deps.coolify,
+                appId,
+                runtime,
+                sleep,
+                hostname,
+                settings: {
+                    mailHost,
+                    apex: platform.apex,
+                    oidc: { issuerUrl: issuer, audience: project.id },
+                },
             });
             await record(PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, project.id);
         }
@@ -1780,11 +1856,19 @@ async function provisionPlatformMail(context, deps) {
                 url: `https://${hostname}`,
                 user: STALWART_RECOVERY_USER,
                 password,
-            });
-            await admin.applySettings({
-                mailHost,
                 apex: platform.apex,
-                oidc: { issuerUrl: issuer, audience: project.id },
+            });
+            await applyMailSettings(admin, {
+                coolify: deps.coolify,
+                appId,
+                runtime,
+                sleep,
+                hostname,
+                settings: {
+                    mailHost,
+                    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
@@ -1982,6 +2066,37 @@ async function waitForMailInstance(url, runtime, sleep) {
         await sleep(interval);
     }
 }
+/**
+ * Applies the settings; when the instance was fresh, restarts the app (the
+ * `Bootstrap` config loads only on Stalwart's next start) and applies again
+ * once it answers ready. Rejects if it is still in bootstrap after the wait.
+ */
+async function applyMailSettings(admin, input) {
+    const { runtime, sleep } = input;
+    if ((await admin.applySettings(input.settings)) !== 'restart')
+        return;
+    await input.coolify.raw('POST', `/applications/${input.appId}/restart`);
+    const now = runtime.now ?? Date.now;
+    const deadline = now() + (runtime.readyTimeoutMs ?? 300_000);
+    for (;;) {
+        await sleep(runtime.readyIntervalMs ?? 5_000);
+        await waitForMailInstance(`https://${input.hostname}${STALWART_READY_PATH}`, runtime, sleep);
+        // The old container may still answer, or drop the connection, for a
+        // moment after the restart call.
+        try {
+            if ((await admin.applySettings(input.settings)) !== 'restart')
+                return;
+        }
+        catch (error) {
+            if (now() >= deadline)
+                throw error;
+            continue;
+        }
+        if (now() >= deadline) {
+            throw new Error(`platform:mail: Stalwart at https://${input.hostname} is still in bootstrap mode after a restart; apply again`);
+        }
+    }
+}
 function redactedMailError(error, secrets) {
     const original = error instanceof Error ? error : new Error(String(error));
     const message = redactSecrets(original.message, secrets);

package/package.json

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