@wtfalch/foundry 0.8.0 → 0.10.0

package/dist/bootstrap/declare.js

@@ -63,15 +63,11 @@ export function declaredCompanyOrg(company, owner) {
         issuer: { usesDomain: false },
         site: { enabled: false, usesDomain: false },
         hosting: {
-            appEnv: {},
             enabled: false,
             usesDomain: false,
-            database: false,
             tunnel: false,
-            gitBranch: DEFAULT_GIT_REF,
-            buildPack: 'nixpacks',
-            accessEmails: [],
             issuerApps: [],
+            entries: [],
         },
         sso: { enabled: false },
         guests: { enabled: false },

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 { DEFAULT_MAIL_APPS, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, HostingEntryUses, EntryAuth, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, 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';
@@ -30,7 +30,7 @@ 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 { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_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';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { DEFAULT_MAIL_APPS, validateBuyerIdentity, validateHosting, validateMail, validateOwner, validateSite, } from './org.js';
+export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, 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';
@@ -13,7 +13,7 @@ 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 { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_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';

package/dist/migrations/0029_hosting_entries.sql

@@ -0,0 +1,109 @@
+-- @wtfalch/foundry: an org's hosting as a list of entries, and today's one app
+-- moved onto it as the entry keyed 'app' (org.ts's `HostingConfig.entries`).
+-- Mirrors `src/store/schema.ts`'s `hostingEntries`.
+--
+-- Copies and never drops: hosting_database, hosting_git_branch,
+-- hosting_build_pack, hosting_access_emails, hosting_app_env and
+-- bespoke_app_repo stay for an older reader. Safe to run twice: an org that
+-- already has entries is skipped, and a renamed id key is no longer there to
+-- rename. An org with hosting off but an app id recorded (a parked app) gets
+-- its entry too, so re-enabling it finds its settings.
+--
+-- A row the new validation (org.ts's `validateHostingEntry`) would refuse
+-- makes the migration fail, naming every such org id and column at once, before
+-- anything changes: a row that cannot be saved is worse found weeks later
+-- than as a failed deploy. An empty branch becomes 'main', its default.
+
+do $$
+declare
+  bad text;
+begin
+  select string_agg(format('%s: %s', o.id, c.problem), '; ' order by o.id)
+    into bad
+      from foundry_declared_orgs o
+      cross join lateral (values
+        ('bespoke_app_repo ' || quote_literal(o.bespoke_app_repo) || ' is not a repo under wtfalch',
+         o.bespoke_app_repo is not null and o.bespoke_app_repo !~ '^wtfalch/[A-Za-z0-9._-]+$'),
+        ('hosting_build_pack ' || quote_literal(o.hosting_build_pack) || ' is not available for an entry',
+         o.hosting_build_pack not in ('dockerfile', 'nixpacks', 'static')),
+        ('hosting_database or hosting_access_emails is set while hosting_enabled is off',
+         not o.hosting_enabled and (o.hosting_database or o.hosting_access_emails <> '[]'::jsonb)),
+        ('hosting_access_emails holds an invalid email',
+         exists (select 1 from jsonb_array_elements_text(o.hosting_access_emails) e
+                  where e !~ '^[^@[:space:]]+@[^@[:space:]]+$')),
+        ('hosting_app_env names a variable foundry sets itself, or an unknown source',
+         exists (select 1 from jsonb_each_text(o.hosting_app_env) e
+                  where e.key = ''
+                     or e.key ~ '^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$'
+                     or e.value not in ('filesOrganisationId', 'aiOrganisationId', 'mailDomain')))
+      ) as c(problem, refused)
+     where c.refused
+       -- to_jsonb, because the column does not exist yet on a first run.
+       and coalesce(to_jsonb(o) -> 'hosting_entries', '[]'::jsonb) = '[]'::jsonb
+       and (o.hosting_enabled or exists (
+              select 1 from foundry_applied_state a
+               where (a.service_ids -> ('coolify:app:' || a.org_id)) is not null
+                 and a.org_id = o.id));
+  if bad is not null then
+    raise exception 'migration 0029: cannot move hosting onto an entry, org %', bad;
+  end if;
+end $$;
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_entries jsonb not null default '[]'::jsonb;
+
+update foundry_declared_orgs
+   set hosting_entries = jsonb_build_array(jsonb_build_object(
+         'key', 'app',
+         'repo', bespoke_app_repo,
+         'folder', null,
+         'branch', coalesce(nullif(hosting_git_branch, ''), 'main'),
+         'buildPack', hosting_build_pack,
+         'port', null,
+         'healthPath', null,
+         'database', hosting_database,
+         'autoDeploy', true,
+         'accessEmails', hosting_access_emails,
+         'env', coalesce(
+           (select jsonb_object_agg(e.key, jsonb_build_object('from', e.value))
+              from jsonb_each_text(hosting_app_env) as e),
+           '{}'::jsonb)
+       ))
+ where hosting_entries = '[]'::jsonb
+   and (hosting_enabled or exists (
+          select 1 from foundry_applied_state a
+           where a.org_id = foundry_declared_orgs.id
+             and (a.service_ids -> ('coolify:app:' || a.org_id)) is not null));
+
+-- The recorded ids and applied-env markers are one key per org today; the
+-- entry key joins them so a second app cannot collide with the first. A key
+-- is renamed only when its new form is absent; if both exist the new one
+-- stays and the old one is left as it is. Without
+-- the rename the planner would not find the app it already made and would
+-- plan it again, restarting it. last_applied_at and
+-- last_applied_declared_org_version are not touched.
+update foundry_applied_state
+   set service_ids = service_ids
+         - ('coolify:app:' || org_id)
+         || jsonb_build_object('coolify:app:' || org_id || ':app', service_ids -> ('coolify:app:' || org_id))
+ where (service_ids -> ('coolify:app:' || org_id)) is not null
+   and (service_ids -> ('coolify:app:' || org_id || ':app')) is null;
+
+update foundry_applied_state
+   set service_ids = service_ids
+         - ('cloudflare:access:' || org_id)
+         || jsonb_build_object('cloudflare:access:' || org_id || ':app', service_ids -> ('cloudflare:access:' || org_id))
+ where (service_ids -> ('cloudflare:access:' || org_id)) is not null
+   and (service_ids -> ('cloudflare:access:' || org_id || ':app')) is null;
+
+update foundry_applied_state
+   set service_ids = service_ids - 'app_env_applied'
+         || jsonb_build_object('app_env_applied.app', service_ids -> 'app_env_applied')
+ where (service_ids -> 'app_env_applied') is not null
+   and (service_ids -> 'app_env_applied.app') is null;
+
+update foundry_applied_state
+   set service_ids = service_ids - 'db_env_applied'
+         || jsonb_build_object('db_env_applied.app', service_ids -> 'db_env_applied')
+ where (service_ids -> 'db_env_applied') is not null
+   and (service_ids -> 'db_env_applied.app') is null;

package/dist/migrations/0030_hosting_entry_hostnames.sql

@@ -0,0 +1,24 @@
+-- @wtfalch/foundry: each hosting entry names where it is served (org.ts's
+-- `HostingEntry.hostnames`). Mirrors `src/store/schema.ts`'s `hostingEntries`.
+--
+-- The `app` entry of an org with hosting.usesDomain on is served at the org's
+-- domain, so it gets ['@']; every other entry, and the `app` entry of an org
+-- with usesDomain off (served at <slug>.oikos.host), gets []. An org planned
+-- before this migration therefore plans the same names after it.
+--
+-- Copies and never drops: no column changes, only entries without a
+-- `hostnames` field gain one. Safe to run twice: an entry that has the field
+-- is left as it is.
+
+update foundry_declared_orgs o
+   set hosting_entries = (
+     select coalesce(jsonb_agg(
+              case when e ? 'hostnames' then e
+                   else e || jsonb_build_object(
+                     'hostnames',
+                     case when e ->> 'key' = 'app' and o.hosting_uses_domain
+                          then '["@"]'::jsonb else '[]'::jsonb end)
+              end order by t.ord), '[]'::jsonb)
+       from jsonb_array_elements(o.hosting_entries) with ordinality as t(e, ord))
+ where exists (
+   select 1 from jsonb_array_elements(o.hosting_entries) e where not (e ? 'hostnames'));

package/dist/org.d.ts

@@ -184,54 +184,108 @@ export interface IssuerApp {
  */
 export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercompose';
 /**
- * The org's own hosted app and what runs beside it (#71, part of #14's
+ * The org's hosted apps and what runs beside them (#71, part of #14's
  * adopted/standard/bespoke map) -- distinct from the cms site (`SiteConfig`
  * above), which is `@wtfalch/cms` content, not the org's own application
  * code. `usesDomain` follows the same opt-in-per-service rule as mail, chat,
  * calls, the issuer and the site (#7 amendment 1): setting `DeclaredOrg.domain`
  * alone never moves the app onto it or starts managing its Cloudflare zone.
  *
- * `database` and `tunnel` are each meaningless without the app itself
- * running, so `validateHosting` below requires `enabled` before either can
+ * `enabled`, `usesDomain`, `tunnel` and `issuerApps` are the org's own: one
+ * park switch, one hostname rule, one tunnel and one ZITADEL project for all
+ * its apps. Each app is one of `entries`. `tunnel` is meaningless without the
+ * apps running, so `validateHosting` below requires `enabled` before it can
  * be true.
- *
- * `gitBranch` and `buildPack` were fixed values `executor.ts` hardcoded
- * (`'main'`/`'nixpacks'`) until this campaign's hosting-wiring work made them
- * declarable; those two strings are their defaults now, kept here so an org
- * that never mentions them still gets exactly what shipped before.
  */
 export interface HostingConfig {
-    /** The org's own app runs on Coolify. */
+    /** The org's apps run on Coolify. */
     enabled: boolean;
     /** Served on `DeclaredOrg.domain` (and its Cloudflare zone managed) instead of `<slug>.oikos.host` (`../slug.ts`). */
     usesDomain: boolean;
-    /** A Postgres database beside the app. Requires `enabled`. */
-    database: boolean;
-    /** The app is reached through a Cloudflare tunnel. Requires `enabled`. */
+    /** The apps are reached through a Cloudflare tunnel. Requires `enabled`. */
     tunnel: boolean;
+    /** The org's declared ZITADEL OIDC applications (#71). */
+    issuerApps: IssuerApp[];
+    /** One entry per app the org runs. */
+    entries: HostingEntry[];
+}
+/** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
+export declare const APP_ENTRY_KEY = "app";
+/**
+ * One app the org runs. `database` and `accessEmails` are meaningless
+ * without `HostingConfig.enabled`, so `validateHosting` requires it before
+ * either is set.
+ */
+export interface HostingEntry {
+    /** A DNS label, unique per org. It goes into step ids and scope keys, so it never holds `:` or `.`. */
+    key: string;
+    /** The repo under `wtfalch` the app builds from. `null` is the shared standard app (`executor.ts`'s `DEFAULT_APP_REPO`). */
+    repo: string | null;
+    /** The app's folder in `repo`. `null` is the repo root. */
+    folder: string | null;
     /** The branch `coolify:app` builds and deploys from. Default: `'main'`. */
-    gitBranch: string;
+    branch: string;
     /** The Coolify build strategy `coolify:app` provisions with. Default: `'nixpacks'`. */
     buildPack: HostingBuildPack;
-    /** The org's declared ZITADEL OIDC applications (#71). */
-    issuerApps: IssuerApp[];
+    /** The port the app listens on. `null` is Coolify's default. */
+    port: number | null;
+    /** The path that answers 200 when the app is healthy. `null` is none. */
+    healthPath: string | null;
+    /**
+     * The names the entry is served at: `'@'` (the org's domain), a label under
+     * the domain, or `'*'` (reserved: a later change acts on it). Empty means an
+     * internal app, reached as `<slug>-<key>` on the Coolify network. Read only
+     * when `HostingConfig.usesDomain` is on and the org has a domain; otherwise
+     * the `app` entry is served at `<slug>.oikos.host` and no other entry may
+     * set any.
+     */
+    hostnames: string[];
+    /** A Postgres database beside the app. At most one entry per org. */
+    database: boolean;
+    /** Deploy on every push to `branch`. Default: `true`. */
+    autoDeploy: boolean;
     /**
      * Emails Cloudflare Access lets through to the app's hostname (#84). Empty
-     * means no Access gate. Requires `enabled`.
+     * means no Access gate. Only the entry keyed {@link APP_ENTRY_KEY} may set it.
      */
     accessEmails: string[];
     /**
-     * Maps the app's own env var name to one of `AppEnvSource`'s values --
-     * each a value the plan already mints for this org (Files, AI, mail) but
-     * never used to push an app's own env (#243). Each bespoke app names these
-     * differently (lokessmie uses `STORAGE_*`/`AI_*`); this is how an org
-     * declares its own app's names for them. `{}` means the app names none of
-     * them, so `pushAppEnv` pushes nothing from this map.
+     * The app's own env var names and what they hold (#243). Each bespoke app
+     * names the values the plan mints (Files, AI, mail) differently (lokessmie
+     * uses `STORAGE_*`/`AI_*`); `{ from }` declares its own name for one. `{}`
+     * means the app names none of them, so `pushAppEnv` pushes nothing from
+     * this map.
      */
-    appEnv: Record<string, AppEnvSource>;
+    env: Record<string, EnvValue>;
+    /** What the entry signs in through. Absent means it uses nothing. */
+    uses?: HostingEntryUses;
+}
+/**
+ * Sign-in for one entry: one ZITADEL client and one broker entry, signing in
+ * ONE organisation. `staff` is the org's own ZITADEL org, `customers` the
+ * `<slug> customers` org. `registration` is the broker entry's sign-up switch.
+ * `replacesBrokerEntry` is the `name` of the hand-written broker `AUTH_APPS`
+ * entry this entry's own entry replaces; the first write removes it.
+ */
+export interface EntryAuth {
+    users: 'staff' | 'customers';
+    registration: 'open' | 'closed';
+    replacesBrokerEntry?: string;
+}
+export interface HostingEntryUses {
+    auth?: EntryAuth;
 }
 /**
- * The closed set of values the plan already mints that `HostingConfig.appEnv`
+ * A plain string is pushed as it is, so `validateHosting` refuses one that
+ * looks like a secret. `{ from }` names a value the plan already mints.
+ */
+export type EnvValue = string | {
+    from: AppEnvSource;
+};
+/** The org's `app` entry: today's one app. */
+export declare function appEntry(hosting: HostingConfig): HostingEntry | undefined;
+/**
+ * The closed set of values the plan already mints that `HostingEntry.env`
  * may map an app's env var name to (#243): the org's own Files organisation
  * id, its AI organisation id, and the mail domain its Lettermint project
  * sends from. Each is read from `StepExecutionContext.recordedIds()` in
@@ -243,14 +297,18 @@ export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.
  *
- * - `database` and `tunnel` each require `enabled` -- neither means anything
- *   without the app itself running.
- * - `gitBranch` is non-empty and `buildPack` is one of `HostingBuildPack`'s
- *   four values.
+ * - `tunnel` requires `enabled` -- it means nothing without the apps running.
  * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
+ * - `enabled` requires an entry keyed {@link APP_ENTRY_KEY}.
+ * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
+ *   unique, and at most one entry has a `database`, because the one
+ *   `<slug>_rt` runtime role cannot serve two apps.
  */
-export declare function validateHosting(hosting: HostingConfig): string | null;
+export declare function validateHosting(hosting: HostingConfig, names?: {
+    domain: string | null;
+    locked: ReadonlySet<string>;
+}): string | null;
 export declare function validateDomain(domain: string): string | null;
 /**
  * `null` when `site` is valid; otherwise the reason it is not (#101).

package/dist/org.js

@@ -2,6 +2,12 @@
 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';
+/** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
+export const APP_ENTRY_KEY = 'app';
+/** The org's `app` entry: today's one app. */
+export function appEntry(hosting) {
+    return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
+}
 export const APP_ENV_SOURCES = new Set([
     'filesOrganisationId',
     'aiOrganisationId',
@@ -18,34 +24,18 @@ const HOSTING_BUILD_PACKS = new Set([
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.
  *
- * - `database` and `tunnel` each require `enabled` -- neither means anything
- *   without the app itself running.
- * - `gitBranch` is non-empty and `buildPack` is one of `HostingBuildPack`'s
- *   four values.
+ * - `tunnel` requires `enabled` -- it means nothing without the apps running.
  * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
+ * - `enabled` requires an entry keyed {@link APP_ENTRY_KEY}.
+ * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
+ *   unique, and at most one entry has a `database`, because the one
+ *   `<slug>_rt` runtime role cannot serve two apps.
  */
-export function validateHosting(hosting) {
-    if (hosting.database && !hosting.enabled) {
-        return 'hosting.database requires hosting.enabled';
-    }
+export function validateHosting(hosting, names) {
     if (hosting.tunnel && !hosting.enabled) {
         return 'hosting.tunnel requires hosting.enabled';
     }
-    if (!hosting.gitBranch) {
-        return 'hosting.gitBranch must be non-empty';
-    }
-    if (!HOSTING_BUILD_PACKS.has(hosting.buildPack)) {
-        return `hosting.buildPack has an unknown value '${hosting.buildPack}'`;
-    }
-    if (hosting.accessEmails.length > 0 && !hosting.enabled) {
-        return 'hosting.accessEmails requires hosting.enabled';
-    }
-    for (const email of hosting.accessEmails) {
-        if (!/^[^@\s]+@[^@\s]+$/.test(email)) {
-            return `hosting.accessEmails has an invalid email '${email}'`;
-        }
-    }
     const seenNames = new Set();
     for (const app of hosting.issuerApps) {
         if (!app.name) {
@@ -67,16 +57,179 @@ export function validateHosting(hosting) {
             return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
         }
     }
-    for (const [envName, source] of Object.entries(hosting.appEnv)) {
-        if (!envName) {
-            return 'every appEnv key needs a non-empty env var name';
+    if (hosting.enabled && !appEntry(hosting)) {
+        return `hosting.enabled requires an entry keyed '${APP_ENTRY_KEY}'`;
+    }
+    const seenKeys = new Set();
+    for (const entry of hosting.entries) {
+        if (seenKeys.has(entry.key)) {
+            return `hosting.entries key '${entry.key}' is not unique`;
+        }
+        seenKeys.add(entry.key);
+        const invalid = validateHostingEntry(entry, hosting.enabled);
+        if (invalid)
+            return invalid;
+        const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
+        if (invalidAuth)
+            return invalidAuth;
+    }
+    const invalidNames = validateEntryHostnames(hosting, names);
+    if (invalidNames)
+        return invalidNames;
+    if (hosting.entries.filter((entry) => entry.database).length > 1) {
+        return 'at most one hosting entry may set database: the one runtime database role cannot serve two apps';
+    }
+    return null;
+}
+/**
+ * The rules for the names of every entry: each is `@`, `*` or a DNS label, no
+ * name twice, none on a name foundry owns (`plan/locked-hostnames.ts`), and
+ * none at all on a non-`app` entry while `usesDomain` is off. `names` is what
+ * the caller knows of the org; without it only the checks that need no domain
+ * run.
+ */
+function validateEntryHostnames(hosting, names) {
+    const taken = new Set();
+    for (const entry of hosting.entries) {
+        const at = `hosting.entries '${entry.key}'`;
+        if (!hosting.usesDomain && entry.key !== APP_ENTRY_KEY && entry.hostnames.length > 0) {
+            return `${at} hostnames need hosting.usesDomain: without it only the '${APP_ENTRY_KEY}' entry is served, at its own address`;
+        }
+        const reads = hosting.usesDomain && names?.domain;
+        if (reads && entry.key === APP_ENTRY_KEY && !entry.hostnames.some((n) => n !== '*')) {
+            return `${at} needs a hostname ('@' or a label) while hosting.usesDomain is on: '*' alone names nothing, and the app would fall back to the bare domain`;
+        }
+        for (const name of entry.hostnames) {
+            if (name !== '@' && name !== '*' && !ENTRY_KEY.test(name)) {
+                return `${at} hostname '${name}' must be '@', '*' or a DNS label`;
+            }
+            if (taken.has(name))
+                return `hostname '${name}' is held by two entries or listed twice`;
+            taken.add(name);
+            if (names?.domain &&
+                name !== '@' &&
+                name !== '*' &&
+                names.locked.has(`${name}.${names.domain}`)) {
+                return `${at} hostname '${name}' is a name foundry owns: ${name}.${names.domain}`;
+            }
+        }
+    }
+    return null;
+}
+const ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
+// The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
+const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
+const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
+const HELD_SECRETS = 'held secrets are not available yet';
+/** The rules for one {@link HostingEntry}; `null` when it is valid. */
+function validateHostingEntry(entry, enabled) {
+    const at = `hosting.entries '${entry.key}'`;
+    if (!ENTRY_KEY.test(entry.key)) {
+        return `hosting.entries key '${entry.key}' must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`;
+    }
+    if (entry.repo !== null && !REPO.test(entry.repo)) {
+        return `${at} repo must be a repo under wtfalch, or null`;
+    }
+    if (entry.folder !== null && (entry.folder.startsWith('/') || entry.folder.includes('..'))) {
+        return `${at} folder must be a relative path inside the repo`;
+    }
+    if (!entry.branch) {
+        return `${at} branch must be non-empty`;
+    }
+    if (!HOSTING_BUILD_PACKS.has(entry.buildPack)) {
+        return `${at} buildPack has an unknown value '${entry.buildPack}'`;
+    }
+    if (entry.buildPack === 'dockercompose') {
+        return `${at} buildPack dockercompose is not available for an entry`;
+    }
+    if (entry.port !== null &&
+        !(Number.isInteger(entry.port) && entry.port >= 1 && entry.port <= 65535)) {
+        return `${at} port must be a whole number from 1 to 65535, or null`;
+    }
+    if (entry.healthPath !== null && !entry.healthPath.startsWith('/')) {
+        return `${at} healthPath must start with '/', or be null`;
+    }
+    if (entry.database && !enabled) {
+        return `${at} database requires hosting.enabled`;
+    }
+    if (entry.accessEmails.length > 0 && !enabled) {
+        return `${at} accessEmails requires hosting.enabled`;
+    }
+    if (entry.accessEmails.length > 0 && entry.key !== APP_ENTRY_KEY) {
+        return `${at} accessEmails is only available on the '${APP_ENTRY_KEY}' entry for now`;
+    }
+    for (const email of entry.accessEmails) {
+        if (!/^[^@\s]+@[^@\s]+$/.test(email)) {
+            return `${at} accessEmails has an invalid email '${email}'`;
+        }
+    }
+    for (const [name, value] of Object.entries(entry.env)) {
+        if (!name) {
+            return `${at} env needs a non-empty env var name`;
+        }
+        if (FOUNDRY_ENV_NAME.test(name)) {
+            return `${at} env '${name}' is set by foundry and cannot be declared`;
+        }
+        if (typeof value !== 'string') {
+            if (!APP_ENV_SOURCES.has(value?.from)) {
+                return `${at} env '${name}' has an unknown source '${value?.from}'`;
+            }
         }
-        if (!APP_ENV_SOURCES.has(source)) {
-            return `appEnv '${envName}' has an unknown source '${source}'`;
+        else if (SECRET_ENV_NAME.test(name) || (name.endsWith('_URL') && urlHasPassword(value))) {
+            return `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`;
         }
     }
     return null;
 }
+/**
+ * `uses.auth`: its two switches are known values, sign-up is never open
+ * into the staff organisation, the entry has an exact
+ * hostname to sign in at (a `*` or an internal entry has none), and the
+ * client's name, which is the entry key, is not one another client holds.
+ */
+function validateEntryAuth(entry, hosting, domain) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return null;
+    const at = `hosting.entries '${entry.key}' uses.auth`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    if (auth.users !== 'staff' && auth.users !== 'customers') {
+        return `${at} users must be 'staff' or 'customers'`;
+    }
+    if (auth.registration !== 'open' && auth.registration !== 'closed') {
+        return `${at} registration must be 'open' or 'closed'`;
+    }
+    // The staff organisation holds the org's own people and its project.
+    if (auth.users === 'staff' && auth.registration === 'open') {
+        return `${at} registration 'open' needs users 'customers': nobody signs themselves up as staff`;
+    }
+    if (auth.replacesBrokerEntry !== undefined &&
+        (typeof auth.replacesBrokerEntry !== 'string' || auth.replacesBrokerEntry === '')) {
+        return `${at} replacesBrokerEntry must be the non-empty name of a broker entry`;
+    }
+    // With no domain the hostnames are not read (`entryHostnames`).
+    const hasName = hosting.usesDomain && domain !== null
+        ? entry.hostnames.some((name) => name !== '*')
+        : entry.key === APP_ENTRY_KEY;
+    if (!hasName)
+        return `${at} needs an exact hostname to sign in at`;
+    if (entry.key === 'agora' ||
+        entry.key === 'cms' ||
+        hosting.issuerApps.some((app) => app.name === entry.key)) {
+        return `${at} client name '${entry.key}' is already held by another ZITADEL client`;
+    }
+    return null;
+}
+function urlHasPassword(value) {
+    try {
+        return new URL(value).password !== '';
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * A DNS-label-per-segment format check for `DeclaredOrg.domain` (#131): every
  * dot-separated segment follows the exact rule `../slug.ts`'s `DNS_LABEL`

package/dist/plan/agora.d.ts

@@ -24,6 +24,13 @@ export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
  * report).
  */
 export declare const APP_CLIENT_ID_SCOPE_KEY = "zitadel_app_client_id";
+/**
+ * An entry with `uses.auth` has its own client, recorded under
+ * `zitadel_app_client_id.<entry key>` (a scope key holds no `:`). Not a
+ * secret. The entry key is also the client's name in the org's project.
+ */
+export declare const ENTRY_CLIENT_ID_SCOPE_PREFIX = "zitadel_app_client_id.";
+export declare function entryClientIdScopeKey(entryKey: string): string;
 /**
  * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
  * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the

package/dist/plan/agora.js

@@ -23,6 +23,15 @@ export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
  * report).
  */
 export const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
+/**
+ * An entry with `uses.auth` has its own client, recorded under
+ * `zitadel_app_client_id.<entry key>` (a scope key holds no `:`). Not a
+ * secret. The entry key is also the client's name in the org's project.
+ */
+export const ENTRY_CLIENT_ID_SCOPE_PREFIX = `${APP_CLIENT_ID_SCOPE_KEY}.`;
+export function entryClientIdScopeKey(entryKey) {
+    return `${ENTRY_CLIENT_ID_SCOPE_PREFIX}${entryKey}`;
+}
 /**
  * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
  * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the