@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/bootstrap/bootstrap.d.ts

@@ -7,7 +7,16 @@ export interface BootstrapPlatformInput {
     company: BootstrapCompany;
     owner: BootstrapOwner;
 }
-/** The master keys, read from the host's held keys by the caller. */
+/**
+ * The master keys, read from the host's held keys by the caller.
+ *
+ * #213: `coolifyUrl`, `coolifyToken` and `cloudflareApiToken` are also what
+ * `bootstrapPlatform` puts as Archon's own held keys
+ * (`platform:master:coolify-url`, `-coolify-token`, `-cloudflare-token`)
+ * before Archon's app deploys, so its onboarding can read them back.
+ * `cloudflareApiToken` needs "API Tokens Write" for that: Archon mints its
+ * own scoped child tokens from it.
+ */
 export interface RootCredentials {
     coolifyUrl: string;
     coolifyToken: string;
@@ -32,8 +41,14 @@ export interface BootstrapPlatformDeps {
     migrateSql: MigrateSql;
     rootCredentials: () => Promise<RootCredentials>;
     deliverSecret: (ref: string, secret: string) => Promise<void>;
+    /**
+     * `put` (#213) is optional, like `PlatformArchonDeps.heldKeys`'s own: a
+     * host without one still compiles, and Archon's master keys are reported
+     * blocked, not skipped, while it is missing.
+     */
     heldKeys: {
         resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
     };
     /** Per-step dependencies (auth, mail, files, ai, integrations, archon, sfu). A step without its own is reported blocked. */
     executor?: BootstrapExecutorDeps;

package/dist/bootstrap/bootstrap.js

@@ -106,12 +106,39 @@ export function guardStepDeps(executor, redactor, deliverSecret, heldKeys) {
         const copy = { ...deps };
         if ('deliverSecret' in copy)
             copy.deliverSecret = deliverSecret;
-        if (key === 'archon' || 'heldKeys' in copy)
+        // #201: ai's own default minter needs heldKeys too, to re-sign a mint
+        // request against its signing key when an earlier run pinned it but
+        // crashed before the management key itself was minted and delivered.
+        if (key === 'archon' || key === 'ai' || 'heldKeys' in copy)
             copy.heldKeys = heldKeys;
         out[key] = copy;
     }
     return out;
 }
+/**
+ * #213: stamps `PlatformArchonDeps.masterKeys` from the root credentials
+ * `bootstrapPlatform` already resolved, onto whatever the host gave the
+ * archon step through `deps.executor.archon` -- the values are
+ * `credentials`' own, not something the host names separately, so this is
+ * not one more thing for `guardStepDeps`'s caller to wire by hand. A run
+ * with no `archon` deps at all (the step then reported blocked, as before)
+ * is passed through unchanged.
+ */
+function archonMasterKeys(guarded, credentials) {
+    if (!guarded.archon)
+        return guarded;
+    return {
+        ...guarded,
+        archon: {
+            ...guarded.archon,
+            masterKeys: {
+                coolifyUrl: credentials.coolifyUrl,
+                coolifyToken: credentials.coolifyToken,
+                cloudflareParentToken: credentials.cloudflareApiToken,
+            },
+        },
+    };
+}
 /**
  * The platform's first apply, run from Archon's onboarding flow: migrates
  * foundry's tables, declares Company Included and the platform (never
@@ -148,6 +175,17 @@ export async function bootstrapPlatform(input, deps) {
                 redactor.add(value);
                 return value;
             },
+            // #213: only present when the host's own heldKeys can put, so a host
+            // without one leaves Archon's master keys reported blocked rather
+            // than silently no-op'd.
+            ...(deps.heldKeys.put
+                ? {
+                    async put(ref, value) {
+                        redactor.add(value);
+                        await deps.heldKeys.put?.(ref, value);
+                    },
+                }
+                : {}),
         };
         const migrated = await migrate(deps.migrateSql);
         emit({
@@ -193,7 +231,7 @@ export async function bootstrapPlatform(input, deps) {
                 executor: new FoundryPlatformStepExecutor(cloudflare, orgStore, {
                     coolify,
                     deliverSecret,
-                    ...guardStepDeps(deps.executor, redactor, deliverSecret, heldKeys),
+                    ...archonMasterKeys(guardStepDeps(deps.executor, redactor, deliverSecret, heldKeys), credentials),
                 }),
             };
         }

package/dist/bootstrap/declare.js

@@ -49,7 +49,12 @@ export function declaredCompanyOrg(company, owner) {
         slug: company.slug,
         displayName: company.name,
         domain: null,
-        mail: { mode: 'off', usesDomain: false },
+        mail: {
+            mode: 'off',
+            usesDomain: false,
+            ownerMailboxAddress: null,
+            noReplyLocalPart: 'no-reply',
+        },
         chat: { usesDomain: false },
         calls: { enabled: false, usesDomain: false },
         issuer: { usesDomain: false },

package/dist/calls-sfu-deploy-support.d.ts

@@ -38,6 +38,14 @@ export declare function verifyHostKey(rawKey: Buffer, expectedFingerprint: strin
  * this script writes holds no secret. Returns the SFTP file mode to write
  * with, or `undefined` for anything else (the SFTP server's own default).
  * PR #125's review, finding 2; extended for #127's second secret file.
+ *
+ * A trailing `.tmp` is stripped before comparing: `calls-sfu.ts`'s
+ * `applyCallsSfu` writes `livekit.yaml` to a `.tmp` path first and renames
+ * it into place (#152 round 2 review, finding 3 -- a temp file plus an
+ * atomic rename, rather than overwriting the live config two concurrent
+ * applies could otherwise tear). The temp file holds the same secret the
+ * final path does, so it gets the same 0600 mode; `mv` preserves it across
+ * the rename.
  */
 export declare function fileWriteMode(path: string): number | undefined;
 /**

package/dist/calls-sfu-deploy-support.js

@@ -53,9 +53,18 @@ export function verifyHostKey(rawKey, expectedFingerprint) {
  * this script writes holds no secret. Returns the SFTP file mode to write
  * with, or `undefined` for anything else (the SFTP server's own default).
  * PR #125's review, finding 2; extended for #127's second secret file.
+ *
+ * A trailing `.tmp` is stripped before comparing: `calls-sfu.ts`'s
+ * `applyCallsSfu` writes `livekit.yaml` to a `.tmp` path first and renames
+ * it into place (#152 round 2 review, finding 3 -- a temp file plus an
+ * atomic rename, rather than overwriting the live config two concurrent
+ * applies could otherwise tear). The temp file holds the same secret the
+ * final path does, so it gets the same 0600 mode; `mv` preserves it across
+ * the rename.
  */
 export function fileWriteMode(path) {
-    return path === LIVEKIT_CONFIG_PATH || path === CLOUDFLARED_ENV_PATH ? 0o600 : undefined;
+    const target = path.endsWith('.tmp') ? path.slice(0, -'.tmp'.length) : path;
+    return target === LIVEKIT_CONFIG_PATH || target === CLOUDFLARED_ENV_PATH ? 0o600 : undefined;
 }
 // ---------------------------------------------------------------------------
 // 3. Preflight

package/dist/calls-sfu.d.ts

@@ -21,13 +21,21 @@
  * platform's own `sfu:livekit` step, `plan/platform-sfu.ts`), never imported
  * here, and every test in `calls-sfu.test.ts` runs against a fake.
  *
- * The address, the LiveKit API key and its secret are never hardcoded here
+ * The address and every LiveKit API key/secret pair are never hardcoded here
  * ({@link CallsSfuConfig}): PR 344's review on app-template's
  * `calls-instance` step found its first cut created three Coolify apps
  * before it ever checked the address was known.
  * {@link requireCallsSfuAddress} is that check, run first, before either
  * file is written.
  *
+ * #152: one shared instance, kept apart by *per-company* keys rather than
+ * one shared pair -- {@link CallsSfuConfig.livekitKeys} carries every org's
+ * own key/secret pair, and {@link livekitConfigYaml} writes all of them into
+ * `keys:`. Minting and delivering each org's pair is the platform `sfu`
+ * step's job (`plan/platform-sfu.ts`'s `applyCallsSfuPlatformStep`), not
+ * this module's -- the same "this package never invents a credential" rule
+ * the single-pair design already followed.
+ *
  * #127 adds a second compose service, `cloudflared`, so the SFU has a public
  * `wss://` address through its own named tunnel -- browsers on an https page
  * cannot open a plain `ws://` connection, and 7880 was open to the whole
@@ -64,16 +72,24 @@ export declare class MissingCloudflaredTunnelTokenError extends Error {
 export declare function requireCloudflaredTunnelToken(token: string | undefined | null): string;
 /**
  * Everything {@link applyCallsSfu} needs and this package never invents on
- * its own: the SFU's own address (calls#15), the LiveKit API key/secret pair
- * every client and the service sign tokens with, and the token for the
- * named tunnel `scripts/calls-sfu-ingress.mjs` creates. All four come from
- * the secrets store, at the caller's own script -- #122's and #127's "Human
- * steps".
+ * its own: the SFU's own address (calls#15), one LiveKit API key/secret pair
+ * per org with calls enabled (#152 -- a shared instance, kept apart by
+ * per-company keys, not a port range or a deployment each), and the token
+ * for the named tunnel `scripts/calls-sfu-ingress.mjs` creates. All of it
+ * comes from the secrets store, at the caller's own script -- #122's and
+ * #127's "Human steps" -- except the per-org pairs, which the platform `sfu`
+ * step mints itself (`plan/platform-sfu.ts`).
  */
 export interface CallsSfuConfig {
     address: string;
-    livekitApiKey: string;
-    livekitApiSecret: string;
+    /**
+     * API key id -> secret, one entry per org currently enabled for calls.
+     * {@link livekitConfigYaml} writes every entry under `keys:`, sorted by key
+     * id so the same set of orgs always serializes to the same bytes -- what
+     * `calls-sfu-ssh-adapter.ts`'s `applyCallsSfuOverSession` compares, byte
+     * for byte, to decide whether LiveKit needs a restart.
+     */
+    livekitKeys: Record<string, string>;
     cloudflaredTunnelToken: string;
 }
 /**
@@ -163,6 +179,13 @@ export declare function cloudflaredEnvFile(token: string): string;
  * has one public address of its own, bridged directly rather than sitting
  * behind NAT (calls#15's decision comment), so there is a known-good answer
  * and no reason to make LiveKit discover it via STUN.
+ *
+ * `keys:` carries one line per entry in {@link CallsSfuConfig.livekitKeys}
+ * (#152), sorted by key id -- never object insertion order, which
+ * JavaScript does not even guarantee is the order the platform step built
+ * the map in. An org dropped from the map (calls turned off) simply has no
+ * line here on the next apply; nothing here deletes a key, it only ever
+ * writes the set it was given.
  */
 export declare function livekitConfigYaml(config: CallsSfuConfig): string;
 /**

package/dist/calls-sfu.js

@@ -21,13 +21,21 @@
  * platform's own `sfu:livekit` step, `plan/platform-sfu.ts`), never imported
  * here, and every test in `calls-sfu.test.ts` runs against a fake.
  *
- * The address, the LiveKit API key and its secret are never hardcoded here
+ * The address and every LiveKit API key/secret pair are never hardcoded here
  * ({@link CallsSfuConfig}): PR 344's review on app-template's
  * `calls-instance` step found its first cut created three Coolify apps
  * before it ever checked the address was known.
  * {@link requireCallsSfuAddress} is that check, run first, before either
  * file is written.
  *
+ * #152: one shared instance, kept apart by *per-company* keys rather than
+ * one shared pair -- {@link CallsSfuConfig.livekitKeys} carries every org's
+ * own key/secret pair, and {@link livekitConfigYaml} writes all of them into
+ * `keys:`. Minting and delivering each org's pair is the platform `sfu`
+ * step's job (`plan/platform-sfu.ts`'s `applyCallsSfuPlatformStep`), not
+ * this module's -- the same "this package never invents a credential" rule
+ * the single-pair design already followed.
+ *
  * #127 adds a second compose service, `cloudflared`, so the SFU has a public
  * `wss://` address through its own named tunnel -- browsers on an https page
  * cannot open a plain `ws://` connection, and 7880 was open to the whole
@@ -191,9 +199,20 @@ export function cloudflaredEnvFile(token) {
  * has one public address of its own, bridged directly rather than sitting
  * behind NAT (calls#15's decision comment), so there is a known-good answer
  * and no reason to make LiveKit discover it via STUN.
+ *
+ * `keys:` carries one line per entry in {@link CallsSfuConfig.livekitKeys}
+ * (#152), sorted by key id -- never object insertion order, which
+ * JavaScript does not even guarantee is the order the platform step built
+ * the map in. An org dropped from the map (calls turned off) simply has no
+ * line here on the next apply; nothing here deletes a key, it only ever
+ * writes the set it was given.
  */
 export function livekitConfigYaml(config) {
     const address = requireCallsSfuAddress(config.address);
+    const keys = Object.entries(config.livekitKeys).sort(([a], [b]) => a.localeCompare(b));
+    const keysYaml = keys.length === 0
+        ? 'keys: {}\n'
+        : `keys:\n${keys.map(([apiKey, apiSecret]) => `  ${apiKey}: ${apiSecret}`).join('\n')}\n`;
     return `port: ${LIVEKIT_SIGNALLING_PORT}
 rtc:
   tcp_port: ${LIVEKIT_MEDIA_TCP_PORT}
@@ -201,9 +220,7 @@ rtc:
   port_range_end: 60000
   use_external_ip: false
   node_ip: ${address}
-keys:
-  ${config.livekitApiKey}: ${config.livekitApiSecret}
-`;
+${keysYaml}`;
 }
 async function run(host, command) {
     const result = await host.exec(command);
@@ -211,6 +228,20 @@ async function run(host, command) {
         throw new Error(`"${command}" exited ${result.exitCode}: ${result.stderr || result.stdout}`);
     }
 }
+/**
+ * Writes `contents` to `${path}.tmp` and renames it onto `path` with `mv`,
+ * rather than writing `path` directly -- `mv` within the same directory is a
+ * single rename syscall, so a reader of `path` (this function's own
+ * `cat`-and-compare in `calls-sfu-ssh-adapter.ts`, or LiveKit's own read at
+ * container start) only ever sees the old complete file or the new complete
+ * one, never a partial write from one apply interleaved with another's
+ * (#152 round 2 review, finding 3).
+ */
+async function writeFileAtomically(host, path, contents) {
+    const tmpPath = `${path}.tmp`;
+    await host.writeFile(tmpPath, contents);
+    await run(host, `mv -f ${tmpPath} ${path}`);
+}
 /**
  * Writes all three files, brings LiveKit and `cloudflared` up, then narrows
  * the VM firewall to exactly what #122's and #127's "Decided" sections name
@@ -240,7 +271,7 @@ export async function applyCallsSfu(host, config) {
     requireCallsSfuAddress(config.address);
     requireCloudflaredTunnelToken(config.cloudflaredTunnelToken);
     await host.writeFile(LIVEKIT_COMPOSE_PATH, dockerComposeYaml());
-    await host.writeFile(LIVEKIT_CONFIG_PATH, livekitConfigYaml(config));
+    await writeFileAtomically(host, LIVEKIT_CONFIG_PATH, livekitConfigYaml(config));
     await host.writeFile(CLOUDFLARED_ENV_PATH, cloudflaredEnvFile(config.cloudflaredTunnelToken));
     await run(host, `docker compose -f ${LIVEKIT_COMPOSE_PATH} up -d`);
     await run(host, 'ufw allow 22/tcp');

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
-export { validateBuyerIdentity, validateHosting, validateOwner, validateSite } from './org.js';
+export { DEFAULT_MAIL_APPS, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export type { RequestableField, CallsChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
@@ -23,11 +23,15 @@ export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export type { MailIdentityApp, MailIdentityAudienceCheck } from './plan/index.js';
+export { checkMailIdentityAudience } from './plan/index.js';
+export type { MailAllowlistApp } from './plan/index.js';
+export { checkMailAppsAllowlist } from './plan/index.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './plan/index.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './plan/index.js';
-export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './plan/index.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './plan/index.js';
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './plan/index.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './plan/index.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
@@ -37,6 +41,8 @@ export type { CallsSfuSshConnectOptions } from './calls-sfu-ssh-client.js';
 export { UnknownCallsSfuHostKeyError, toCallsSfuHostPort, applyCallsSfuOverSession, } from './calls-sfu-ssh-adapter.js';
 export type { LivekitCredentials } from './calls-sfu-keys.js';
 export { mintLivekitCredentials } from './calls-sfu-keys.js';
+export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './plan/index.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './plan/index.js';
 export type { MigrateSql, MigrationResult } from './migrate.js';
 export { MIGRATIONS_DIR, migrate } from './migrate.js';
 export type { BootstrapCompany, BootstrapExecutorDeps, BootstrapOwner, BootstrapPlatformDeps, BootstrapPlatformInput, BootstrapProgress, BootstrapResult, RootCredentials, } from './bootstrap/index.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { validateBuyerIdentity, validateHosting, validateOwner, validateSite } from './org.js';
+export { DEFAULT_MAIL_APPS, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
@@ -10,13 +10,16 @@ export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesF
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
 export { HttpJobsSchedulerClient } from './plan/index.js';
+export { checkMailIdentityAudience } from './plan/index.js';
+export { checkMailAppsAllowlist } from './plan/index.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './plan/index.js';
-export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './plan/index.js';
+export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './plan/index.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
 export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';
 export { UnknownCallsSfuHostKeyError, toCallsSfuHostPort, applyCallsSfuOverSession, } from './calls-sfu-ssh-adapter.js';
 export { mintLivekitCredentials } from './calls-sfu-keys.js';
+export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './plan/index.js';
 export { MIGRATIONS_DIR, migrate } from './migrate.js';
 export { bootstrapPlatform } from './bootstrap/index.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';

package/dist/migrations/0019_mail_owner_mailbox.sql

@@ -0,0 +1,15 @@
+-- @wtfalch/foundry: #162 (decided 2026-09-29) -- the owner's mailbox
+-- address is now declared, not guessed (replacing the hardcoded
+-- `owner@<domain>` PR 163 shipped first), and the org's send-only no-reply
+-- address gets its own configurable local part. Mirrors
+-- `src/store/schema.ts`'s `declaredOrgs` table additions.
+--
+-- owner_mailbox_address is nullable: an org can have mail on with no
+-- address declared yet, and `plan/diff.ts`'s `planMail` reports the
+-- mailbox alone as blocked in that case rather than this column refusing
+-- the row. no_reply_local_part defaults to 'no-reply' so every existing
+-- row keeps today's behaviour unchanged.
+
+alter table foundry_declared_orgs
+  add column if not exists owner_mailbox_address text,
+  add column if not exists no_reply_local_part text not null default 'no-reply';

package/dist/migrations/0020_mail_apps.sql

@@ -0,0 +1,7 @@
+-- @wtfalch/foundry: which ZITADEL apps in the org's audience project may
+-- read a person's mail (#34). Mirrors `src/store/schema.ts`'s `mailApps`.
+-- Defaults to 'agora' and 'webmail' so every existing org keeps its current
+-- behaviour.
+
+alter table foundry_declared_orgs
+  add column if not exists mail_apps jsonb not null default '["agora","webmail"]'::jsonb;

package/dist/migrations/0021_mail_role_mailboxes.sql

@@ -0,0 +1,6 @@
+-- @wtfalch/foundry: the role mailboxes an org wants pre-created on its mail
+-- domain (#230). Mirrors `src/store/schema.ts`'s `roleMailboxes`. Defaults to
+-- an empty list so every existing org keeps its current behaviour.
+
+alter table foundry_declared_orgs
+  add column if not exists role_mailboxes jsonb not null default '[]'::jsonb;

package/dist/org.d.ts

@@ -32,11 +32,61 @@ export type MailMode = 'off' | 'received' | 'hosted';
  * Decided in #7 amendment 1: setting `domain` alone never starts a mail
  * change. `usesDomain` is mail's own field for that, independent of
  * `mode` — a domain can be recorded before mail is ever pointed at it.
+ *
+ * `mailApps`: which ZITADEL apps in the org's audience project may read a
+ * person's mail. Decided by William (2026-09-30, #34): only listed apps
+ * may read a person's mail, and the org's own declared config holds the
+ * list -- ZITADEL puts a project's own id into the default audience of
+ * every app signed in to that project, so a matching `requireAudience`
+ * value alone says nothing about *who* carries it (`manage` had exactly
+ * this hole until it moved to its own project, wtfalch/agora#100;
+ * `operator` has it today, wtfalch/operator#11). `undefined` means the org
+ * declares none of its own and {@link DEFAULT_MAIL_APPS} applies --
+ * optional so every existing declared org, and every test fixture that
+ * builds a `MailConfig` literal, keeps working unchanged; a caller that
+ * cares reads `mail.mailApps ?? DEFAULT_MAIL_APPS`, the same fallback
+ * `plan/mail-identity-allowlist.ts`'s own doc comment names.
  */
 export interface MailConfig {
     mode: MailMode;
     usesDomain: boolean;
+    mailApps?: string[];
+    /**
+     * The owner's mailbox address on this org's mail domain. Decided
+     * 2026-09-29 on #162: nothing is guessed any more, replacing the
+     * hardcoded `owner@<domain>` PR 163 shipped first. `null` (the default)
+     * until an operator names one -- `plan/diff.ts`'s `planMail` then reports
+     * the owner's mailbox alone as blocked, naming this field, while every
+     * other part of the org's mail still applies. Optional so a caller that
+     * builds a `MailConfig` for anything other than the owner's mailbox (most
+     * existing call sites, before this field existed) is unaffected; absent
+     * is treated the same as `null` everywhere this is read.
+     */
+    ownerMailboxAddress?: string | null;
+    /**
+     * The local part of the org's send-only no-reply address (no inbox),
+     * read by `plan/executor.ts`'s `ensureAppLettermintMail` for `MAIL_FROM`.
+     * Defaults to `'no-reply'` when absent -- #162: a localised default via
+     * `@wtfalch/i18n` (a Norwegian company's own word for it, say) is
+     * deferred, since that package has none yet. An operator's own value
+     * always wins once set.
+     */
+    noReplyLocalPart?: string;
+    /**
+     * Local parts of the role mailboxes this org wants pre-created on its mail
+     * domain (#230) -- `postmaster`, `abuse`, `security` and the like. Role
+     * mailboxes have no person behind them, so unlike {@link ownerMailboxAddress}
+     * they are not tied to `owner` and are never invited through the broker.
+     * Foundry holds no default set: every org declares its own. `undefined` or
+     * empty means none. Each name is a local part, not an address, so the
+     * address is always on the org's own resolved mail domain.
+     */
+    roleMailboxes?: string[];
 }
+/** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
+export declare const DEFAULT_MAIL_APPS: readonly string[];
+/** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
+export declare const DEFAULT_NO_REPLY_LOCAL_PART = "no-reply";
 /**
  * Chat's per-service opt-in into the org's `domain` fact.
  *
@@ -329,6 +379,37 @@ export interface OwnerIdentity {
  * null` (no owner named yet) is always valid.
  */
 export declare function validateOwner(owner: OwnerIdentity | null): string | null;
+/**
+ * `null` when `mail` is valid; otherwise the reason it is not (#162,
+ * decided 2026-09-29).
+ *
+ * `ownerMailboxAddress`, when set, must be a valid email address; when
+ * `usesDomain` is also true and `domain` is set, it must be on that exact
+ * domain ("validate it is on the org's own domain", #162's "How"). A
+ * level-1 org's mail domain is `<slug>.<platform apex>` -- the platform's
+ * own fact, not this file's -- so that case is left for `plan/diff.ts`'s
+ * `planMail` to resolve and block on, the same way it already resolves
+ * `mailHost` itself.
+ *
+ * Deliberately NOT required just because `mode` is not `'off'`: an org can
+ * have mail on with no address declared yet, same as it can have an owner
+ * named with no ZITADEL invite sent yet -- `planMail` reports the mailbox
+ * alone as blocked in that case rather than this function refusing to let
+ * the org be saved at all (#162 "Done when": "mail on with no owner address
+ * plans a blocked item and still applies the other steps").
+ *
+ * `noReplyLocalPart`, when set, must be non-empty and contain neither `@`
+ * nor whitespace.
+ *
+ * `roleMailboxes`, when set (#230), has only plain local parts (no `@`, `,` or
+ * whitespace) and no duplicate, ignoring case.
+ *
+ * `mailApps`, when set (#34), has no empty entry and no duplicate -- same
+ * two rules `validateHosting` already applies to `issuerApps`' names, for
+ * the same reason: a duplicate or blank entry can never mean anything
+ * different from leaving it out.
+ */
+export declare function validateMail(org: Pick<DeclaredOrg, 'mail' | 'domain'>): string | null;
 /**
  * The form an app foundry does not own takes. Decided in #7's `#15`
  * refinement comment:

package/dist/org.js

@@ -1,3 +1,7 @@
+/** {@link MailConfig.mailApps} when the org declares none of its own (#34, decided 2026-09-30). */
+export const DEFAULT_MAIL_APPS = ['agora', 'webmail'];
+/** {@link MailConfig.noReplyLocalPart}'s own default, restated wherever it is read rather than imported (this file's `LOG_DIR`-style convention, named in `plan/executor.ts`'s own doc comments). */
+export const DEFAULT_NO_REPLY_LOCAL_PART = 'no-reply';
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -185,3 +189,87 @@ export function validateOwner(owner) {
         return 'owner.familyName must not be empty';
     return null;
 }
+/** A local part has no `@` and no whitespace -- loose on purpose, the same restraint {@link OWNER_EMAIL_PATTERN}'s own doc comment states. */
+const LOCAL_PART_PATTERN = /^[^\s@]+$/;
+/**
+ * `null` when `mail` is valid; otherwise the reason it is not (#162,
+ * decided 2026-09-29).
+ *
+ * `ownerMailboxAddress`, when set, must be a valid email address; when
+ * `usesDomain` is also true and `domain` is set, it must be on that exact
+ * domain ("validate it is on the org's own domain", #162's "How"). A
+ * level-1 org's mail domain is `<slug>.<platform apex>` -- the platform's
+ * own fact, not this file's -- so that case is left for `plan/diff.ts`'s
+ * `planMail` to resolve and block on, the same way it already resolves
+ * `mailHost` itself.
+ *
+ * Deliberately NOT required just because `mode` is not `'off'`: an org can
+ * have mail on with no address declared yet, same as it can have an owner
+ * named with no ZITADEL invite sent yet -- `planMail` reports the mailbox
+ * alone as blocked in that case rather than this function refusing to let
+ * the org be saved at all (#162 "Done when": "mail on with no owner address
+ * plans a blocked item and still applies the other steps").
+ *
+ * `noReplyLocalPart`, when set, must be non-empty and contain neither `@`
+ * nor whitespace.
+ *
+ * `roleMailboxes`, when set (#230), has only plain local parts (no `@`, `,` or
+ * whitespace) and no duplicate, ignoring case.
+ *
+ * `mailApps`, when set (#34), has no empty entry and no duplicate -- same
+ * two rules `validateHosting` already applies to `issuerApps`' names, for
+ * the same reason: a duplicate or blank entry can never mean anything
+ * different from leaving it out.
+ */
+export function validateMail(org) {
+    const { mail } = org;
+    const address = mail.ownerMailboxAddress ?? null;
+    if (address !== null) {
+        if (!OWNER_EMAIL_PATTERN.test(address)) {
+            return `mail.ownerMailboxAddress '${address}' is not a valid email address`;
+        }
+        if (mail.usesDomain && org.domain) {
+            const addressDomain = address.slice(address.indexOf('@') + 1).toLowerCase();
+            if (addressDomain !== org.domain.toLowerCase()) {
+                return `mail.ownerMailboxAddress '${address}' must be on ${org.domain}`;
+            }
+        }
+    }
+    if (mail.noReplyLocalPart !== undefined && !LOCAL_PART_PATTERN.test(mail.noReplyLocalPart)) {
+        return `mail.noReplyLocalPart '${mail.noReplyLocalPart}' must not be empty or contain '@' or whitespace`;
+    }
+    if (mail.roleMailboxes) {
+        const seen = new Set();
+        const reserved = new Map([
+            [(mail.noReplyLocalPart ?? DEFAULT_NO_REPLY_LOCAL_PART).toLowerCase(), 'no-reply'],
+        ]);
+        if (address !== null)
+            reserved.set(address.slice(0, address.indexOf('@')).toLowerCase(), 'owner');
+        for (const name of mail.roleMailboxes) {
+            if (!LOCAL_PART_PATTERN.test(name) || name.includes(',')) {
+                return `mail.roleMailboxes entry '${name}' must be a non-empty local part without '@', ',' or whitespace`;
+            }
+            if (seen.has(name.toLowerCase())) {
+                return `mail.roleMailboxes name '${name}' is not unique`;
+            }
+            const clash = reserved.get(name.toLowerCase());
+            if (clash) {
+                return `mail.roleMailboxes name '${name}' clashes with the ${clash} mailbox`;
+            }
+            seen.add(name.toLowerCase());
+        }
+    }
+    if (mail.mailApps) {
+        const seen = new Set();
+        for (const name of mail.mailApps) {
+            if (!name) {
+                return 'mail.mailApps entry needs a non-empty name';
+            }
+            if (seen.has(name)) {
+                return `mail.mailApps name '${name}' is not unique`;
+            }
+            seen.add(name);
+        }
+    }
+    return null;
+}