@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,21 +1,52 @@
 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';
+export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState } from './state.js';
 export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
-export type { DeclaredOrgStore } from './store.js';
+export type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from './store.js';
 export type { PlanApply } from './apply.js';
-export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
-export { declaredOrgs, foundryAppliedState, foundryAuditEvents, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, } from './store/schema.js';
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, StepAction, PlannedStep, PlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
-export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.js';
-export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './plan/index.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 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';
+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 { 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';
+export type { CallsSfuSshSession } from './calls-sfu-ssh-adapter.js';
+export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';
+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';
+export { bootstrapPlatform } from './bootstrap/index.js';
 export type { RunnerDb } from './runner/db.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/index.js

@@ -1,10 +1,26 @@
-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';
-export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
-export { declaredOrgs, foundryAppliedState, foundryAuditEvents, } from './store/schema.js';
-export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.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 { 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 } 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 { 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';
 export { createJobRunner } from './runner/runner.js';

package/dist/migrations/0016_platform.sql

@@ -0,0 +1,61 @@
+-- @wtfalch/foundry: the declared platform -- the one shared set of services
+-- (auth, mail, sfu, files, ai, jobs, integrations, archon) decided in #165,
+-- owned by Company Included, with its own plan and apply. Mirrors
+-- src/store/schema.ts's `foundryDeclaredPlatform` table.
+--
+-- Singleton by construction: `id` is a boolean that can only ever be `true`
+-- (the check constraint below refuses `false`), and it is the primary key,
+-- so a second row can never exist. This is the same "one declared platform"
+-- decision `foundry_declared_orgs` enforces per-org uniqueness for (#28,
+-- #131), applied here to the whole table instead of a column.
+
+create table if not exists foundry_declared_platform (
+  id                     boolean not null default true,
+
+  -- Company Included's own OrgId (org.ts). Not a level-1 org itself, but
+  -- the platform's resources are billed and owned by one.
+  owner_org_id           text not null,
+
+  -- The shared apex every service's hostname defaults under, e.g.
+  -- companyincluded.com. Validated by src/platform.ts's `validatePlatform`,
+  -- not here, the same two-file split declared_orgs uses (#10).
+  apex                   text not null,
+
+  auth_enabled           boolean not null default false,
+  auth_hostname          text not null,
+  auth_git_ref           text not null default '',
+
+  mail_enabled           boolean not null default false,
+  mail_hostname          text not null,
+  mail_git_ref           text not null default '',
+
+  sfu_enabled            boolean not null default false,
+  sfu_hostname           text not null,
+  sfu_git_ref            text not null default '',
+
+  files_enabled          boolean not null default false,
+  files_hostname         text not null,
+  files_git_ref          text not null default '',
+
+  ai_enabled             boolean not null default false,
+  ai_hostname            text not null,
+  ai_git_ref             text not null default '',
+
+  jobs_enabled           boolean not null default false,
+  jobs_hostname          text not null,
+  jobs_git_ref           text not null default '',
+
+  integrations_enabled   boolean not null default false,
+  integrations_hostname  text not null,
+  integrations_git_ref   text not null default '',
+
+  archon_enabled         boolean not null default false,
+  archon_hostname        text not null,
+  archon_git_ref         text not null default '',
+
+  created_at             timestamptz not null default now(),
+  updated_at             timestamptz not null default now(),
+
+  constraint foundry_declared_platform_pkey primary key (id),
+  constraint foundry_declared_platform_singleton check (id)
+);

package/dist/migrations/0017_requested_changes.sql

@@ -0,0 +1,42 @@
+-- @wtfalch/foundry: a company's own requested setting changes on its
+-- declared org (#178, map #165: "a company's Boule can request setting
+-- changes on its own declared org, and Archon applies them"). Mirrors
+-- src/store/schema.ts's `foundryRequestedChanges` table.
+--
+-- `field` is the whitelist itself, checked here the same way
+-- `foundry_declared_orgs_mail_mode_check` checks `mail_mode`'s closed set --
+-- src/requested-changes.ts's `REQUESTABLE_FIELDS` is the source of truth for
+-- what the list means, this constraint is the database-level copy of it.
+-- `value` carries whatever that field's own shape needs (`enabled` for
+-- calls, `limitBytes`/`limitMicros` for storageLimit, and so on) -- one
+-- jsonb column rather than a column per possible field, since only one
+-- field is ever set per request.
+--
+-- `state` starts at whatever `src/requested-changes.ts`'s `classifyChange`
+-- decided for this request at create time (`auto` or `needs_approval`) --
+-- foundry only stores and classifies (#178 "Why"); archon's own workflow is
+-- what carries a request on to `approved`/`rejected`/`applied`.
+
+create table if not exists foundry_requested_changes (
+  id            bigserial not null,
+  org_id        text not null,
+
+  field         text not null,
+  value         jsonb not null,
+
+  requested_by  text not null,
+  created_at    timestamptz not null default now(),
+
+  state         text not null default 'needs_approval',
+
+  constraint foundry_requested_changes_pkey primary key (id),
+  constraint foundry_requested_changes_org_fkey
+    foreign key (org_id) references foundry_declared_orgs (id),
+  constraint foundry_requested_changes_field_check
+    check (field in ('calls', 'storageLimit', 'aiLimit', 'domain', 'mailTier')),
+  constraint foundry_requested_changes_state_check
+    check (state in ('auto', 'needs_approval', 'approved', 'rejected', 'applied'))
+);
+
+create index if not exists foundry_requested_changes_org_id_idx
+  on foundry_requested_changes (org_id);

package/dist/migrations/0018_platform_apply.sql

@@ -0,0 +1,19 @@
+-- @wtfalch/foundry: what applying the declared platform (#167) needs to
+-- remember, and how its audit rows are told apart from an org's.
+--
+-- `service_ids` is the platform's own applied state: the provider ids its
+-- apply made or adopted, keyed `system:kind:key` like
+-- `foundry_applied_state.service_ids`. Without it a Cloudflare zone created
+-- by one apply is forgotten if the next plan's read lags behind the create.
+-- It lives on the singleton row because there is one platform, and
+-- `put`'s upsert never writes it, so re-declaring the platform keeps it.
+--
+-- `target` marks an audit row as the platform's. It is null for an org row.
+-- A platform plan is stamped with the owner org's id, so `org_id` alone
+-- cannot say which of the two a row is.
+
+alter table foundry_declared_platform
+  add column if not exists service_ids jsonb not null default '{}'::jsonb;
+
+alter table foundry_audit_events
+  add column if not exists target text check (target in ('platform'));

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',
@@ -49,6 +53,14 @@ export function validateHosting(hosting) {
         if (!ISSUER_APP_KINDS.has(app.kind)) {
             return `issuerApps '${app.name}' has an unknown kind '${app.kind}'`;
         }
+        // The fixed 'agora' ZITADEL client (#164, `plan/diff.ts`'s
+        // `planAgoraClient`) already owns the `zitadel:app:agora` key, for
+        // every org -- Agora is always on, unlike the cms client's own 'cms'
+        // reservation (`validateSite` below), which only applies once
+        // `site.enabled` is true.
+        if (app.name === 'agora') {
+            return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
+        }
     }
     return null;
 }
@@ -177,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;
+}

package/dist/plan/agora.d.ts

@@ -0,0 +1,77 @@
+import type { DeclaredOrg, OrgId } from '../org.js';
+/**
+ * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's Agora -- the hostname, the values the host
+ * supplies, and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write.
+ */
+/**
+ * `AppliedState.serviceIds` scope keys `desiredAgoraEnv` reads:
+ * `zitadel_org` is `executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`
+ * scope id, `agora_client_id` the fixed `agora` ZITADEL client's `clientId`
+ * (recorded by `executor.ts`'s `zitadelApp`).
+ */
+export declare const ZITADEL_ORG_SCOPE_KEY = "zitadel_org";
+export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
+/**
+ * The accent every org's Agora wears until orgs choose their own: the house
+ * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
+ * `design/packages/house/src/themes.ts`, the default theme
+ * `HOUSE_DEFAULT_THEME`). Agora's config parser requires `theme.accent` as a
+ * hex colour (`agora/apps/agora/src/agoras.ts`). Restated here rather than
+ * imported: `packages/foundry` carries no `@wtfalch/house` dependency.
+ */
+export declare const AGORA_THEME_ACCENT = "#B23A0C";
+/**
+ * Provider-side values only the host can supply, like every other provider
+ * value `FoundryStepExecutorPorts` carries. As of #177, `plan-apply.ts`'s
+ * `FoundryPlanApply` derives these itself from the applied platform
+ * (`platform-org.ts`'s `agoraHostValuesFromPlatform`) whenever a host wires
+ * one in and supplies no `AgoraHostPort` of its own -- an explicit `agora`
+ * port still overrides that, unchanged. `null` means the value is not
+ * available yet. The first three are required by Agora's config parser
+ * (`agoras.ts`: `issuer`, `mailProjectId`, `messagingProjectId`);
+ * `mailUpstream`/`filesUpstream` are the mail/files servers' internal
+ * addresses, optional -- unset, `AGORA_MAIL_UPSTREAM`/`AGORA_FILES_UPSTREAM`
+ * are not pushed and Agora answers 502 on those routes rather than serving
+ * anything wrong (`executor.ts`'s `coolifyAgora` doc comment).
+ */
+export interface AgoraHostValues {
+    issuer: string | null;
+    mailProjectId: string | null;
+    messagingProjectId: string | null;
+    mailUpstream: string | null;
+    filesUpstream: string | null;
+}
+export interface AgoraHostPort {
+    valuesFor(orgId: OrgId): Promise<AgoraHostValues>;
+}
+/** No host values at all: what an absent port means. */
+export declare const NO_AGORA_HOST_VALUES: AgoraHostValues;
+/** What the plan reads from the host: its values, or why it could not get them. */
+export type AgoraHostReading = AgoraHostValues | {
+    error: string;
+};
+/** Reads the port once for a plan. An absent port, or one that throws, is a blocked Agora, never a failed plan. */
+export declare function readAgoraHost(port: AgoraHostPort | undefined, orgId: OrgId): Promise<AgoraHostReading>;
+/** The host values Agora cannot be configured without, by name -- the ones `host` lacks. */
+export declare function agoraHostMissing(host: AgoraHostValues): string[];
+/**
+ * `agora.<domain>` when the org has a domain, `<slug>-agora.oikos.host`
+ * otherwise (the 2026-09-24 layout, foundry#14; `../slug.ts`'s
+ * `AGORA_SUFFIX` reserves the collision).
+ */
+export declare function agoraHostnameFor(org: DeclaredOrg): string;
+/**
+ * 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
+ * empty; callers that write must refuse on a non-empty `missing`.
+ * `AGORA_MAIL_UPSTREAM` is present only when mail is on and the host supplies
+ * an address.
+ */
+export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, host: AgoraHostValues): {
+    env: Record<string, string>;
+    missing: string[];
+};
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export declare function agoraEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];