@wtfalch/foundry 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, EnvValue, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } 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';

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

@@ -196,9 +196,6 @@ export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercom
  * 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.
- *
- * Until the planner reads more than one entry, only the entry keyed
- * {@link APP_ENTRY_KEY} is planned.
  */
 export interface HostingConfig {
     /** The org's apps run on Coolify. */
@@ -234,6 +231,15 @@ export interface HostingEntry {
     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`. */
@@ -251,6 +257,23 @@ export interface HostingEntry {
      * this map.
      */
     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;
 }
 /**
  * A plain string is pushed as it is, so `validateHosting` refuses one that
@@ -282,7 +305,10 @@ export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
  *   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

@@ -32,7 +32,7 @@ const HOSTING_BUILD_PACKS = new Set([
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
  */
-export function validateHosting(hosting) {
+export function validateHosting(hosting, names) {
     if (hosting.tunnel && !hosting.enabled) {
         return 'hosting.tunnel requires hosting.enabled';
     }
@@ -69,12 +69,53 @@ export function validateHosting(hosting) {
         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.
@@ -141,6 +182,46 @@ function validateHostingEntry(entry, enabled) {
     }
     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 !== '';

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

package/dist/plan/broker-entries.d.ts

@@ -0,0 +1,104 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { PlatformStore } from '../store.js';
+import type { CoolifyPort } from './executor.js';
+/**
+ * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
+ * `uses.auth` gets one entry in the broker's `AUTH_APPS`. The org executor has
+ * no way to reach the broker, so it takes a {@link BrokerPort}; the host wires
+ * one (Archon, row AR2).
+ *
+ * Foundry tells its own entry from a hand-written one by `name`
+ * (`<slug>-<entry key>`) and the `organizationId` the entry signs in, plus the
+ * names it recorded when it last wrote. Every other entry is copied back as it
+ * was. No marker field is written: the broker's parser drops unknown fields,
+ * and the name match plus the recorded names is enough.
+ */
+/** The `AUTH_APPS` name of an entry's broker entry. */
+export declare function brokerEntryName(org: DeclaredOrg, entry: HostingEntry): string;
+/** What the last successful broker write for an entry wrote (JSON of {@link BrokerEntryWant}). Ids, names and origins; never the key. */
+export declare function brokerEntryAppliedScopeKey(entryKey: string): string;
+/** The foreign entries the last write found invalid, as a JSON array of names. */
+export declare function brokerEntryWarningsScopeKey(entryKey: string): string;
+/** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
+export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
+/** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
+export declare function entryAuthEnvAppliedScopeKey(entryKey: string): string;
+/** What a broker entry must say, without its key. */
+export interface BrokerEntryWant {
+    name: string;
+    organizationId: string;
+    clientId: string;
+    origins: string[];
+    from: string;
+    registration: boolean;
+    replaces: string | null;
+}
+/**
+ * Each value a broker entry needs and the step that records it, so the
+ * planner can tell "not yet" (a step in this plan records it) from "blocked".
+ */
+export type BrokerEntryInput = {
+    what: string;
+    producedBy: [system: string, kind: string];
+};
+export declare function wantedBrokerEntry(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    want: BrokerEntryWant;
+} | {
+    missing: BrokerEntryInput[];
+};
+/**
+ * The broker app, as the org executor sees it: Coolify env read, env write
+ * and deploy on the broker's app, and the platform's record of the last broker
+ * deploy. Foundry defines the port; Archon wires it (AR2).
+ */
+export interface BrokerPort {
+    /** The broker app's Coolify id; throws when the platform has none recorded. */
+    appId(): Promise<string>;
+    listEnvs(): Promise<Array<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }>>;
+    setAuthApps(raw: string): Promise<void>;
+    deploy(): Promise<void>;
+    /** The platform's `PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY` value, if any. */
+    recordedDeploy(): Promise<string | undefined>;
+    recordDeploy(value: string): Promise<void>;
+}
+/** {@link BrokerPort} over the platform's recorded ids and a Coolify client. */
+export declare class PlatformBrokerPort implements BrokerPort {
+    private readonly options;
+    constructor(options: {
+        store: Pick<PlatformStore, 'getServiceIds' | 'putServiceIds'>;
+        coolify: Pick<CoolifyPort, 'listEnvs' | 'bulkUpsertEnvs' | 'deploy'>;
+    });
+    appId(): Promise<string>;
+    listEnvs(): Promise<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }[]>;
+    setAuthApps(raw: string): Promise<void>;
+    deploy(): Promise<void>;
+    recordedDeploy(): Promise<string | undefined>;
+    recordDeploy(value: string): Promise<void>;
+}
+/**
+ * Writes one entry's broker entry beside the others and deploys the broker
+ * when its `AUTH_APPS` changed. Foundry's own entry is updated in place, a
+ * hand-written entry the entry declares it replaces is removed, and every
+ * other entry is copied back as it was, an invalid one included: the broker
+ * drops it, and one bad hand-written entry must not block sign-in. Errors
+ * name the entry, never a key.
+ *
+ * Returns the names of foreign entries the broker would drop, and the JSON
+ * of a replaced entry (what the F4a snapshot is handed).
+ */
+export declare function writeBrokerEntry(broker: BrokerPort, input: {
+    want: BrokerEntryWant;
+    appKey: string;
+    previous: BrokerEntryWant | null;
+}): Promise<{
+    invalidForeign: string[];
+    replaced: string | null;
+}>;

package/dist/plan/broker-entries.js

@@ -0,0 +1,214 @@
+import { entryClientIdScopeKey } from './agora.js';
+import { entryHostnames } from './hostnames.js';
+import { PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
+import { brokerDeployNeeded, brokerDeployRecordValue, missingBrokerInputs, validateBrokerAppEntry, } from './platform-providers.js';
+/**
+ * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
+ * `uses.auth` gets one entry in the broker's `AUTH_APPS`. The org executor has
+ * no way to reach the broker, so it takes a {@link BrokerPort}; the host wires
+ * one (Archon, row AR2).
+ *
+ * Foundry tells its own entry from a hand-written one by `name`
+ * (`<slug>-<entry key>`) and the `organizationId` the entry signs in, plus the
+ * names it recorded when it last wrote. Every other entry is copied back as it
+ * was. No marker field is written: the broker's parser drops unknown fields,
+ * and the name match plus the recorded names is enough.
+ */
+/** The `AUTH_APPS` name of an entry's broker entry. */
+export function brokerEntryName(org, entry) {
+    return `${org.slug}-${entry.key}`;
+}
+/** What the last successful broker write for an entry wrote (JSON of {@link BrokerEntryWant}). Ids, names and origins; never the key. */
+export function brokerEntryAppliedScopeKey(entryKey) {
+    return `broker_entry_applied.${entryKey}`;
+}
+/** The foreign entries the last write found invalid, as a JSON array of names. */
+export function brokerEntryWarningsScopeKey(entryKey) {
+    return `broker_entry_warnings.${entryKey}`;
+}
+/** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
+export function entryAuthEnv(org, entry, recorded, issuer) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return {};
+    const organizationId = auth.users === 'customers' ? recorded[`zitadel:customers:${org.id}`] : recorded.zitadel_org;
+    const values = {
+        AUTH_ORGANIZATION_ID: organizationId,
+        AUTH_CLIENT_ID: recorded[entryClientIdScopeKey(entry.key)],
+        AUTH_ISSUER: issuer ?? undefined,
+    };
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => Boolean(value)));
+}
+/** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
+export function entryAuthEnvAppliedScopeKey(entryKey) {
+    return `auth_env_applied.${entryKey}`;
+}
+export function wantedBrokerEntry(org, entry, recorded) {
+    const auth = entry.uses?.auth;
+    const organizationId = auth.users === 'customers' ? recorded[`zitadel:customers:${org.id}`] : recorded.zitadel_org;
+    const clientId = recorded[entryClientIdScopeKey(entry.key)];
+    const mailDomain = recorded.mail_domain;
+    const missing = [];
+    if (!organizationId) {
+        missing.push(auth.users === 'customers'
+            ? { what: 'the customers organisation id', producedBy: ['zitadel', 'customers'] }
+            : { what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
+    }
+    if (!clientId)
+        missing.push({ what: 'its sign-in client id', producedBy: ['zitadel', 'app'] });
+    if (!mailDomain)
+        missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
+    if (!organizationId || !clientId || !mailDomain)
+        return { missing };
+    return {
+        want: {
+            name: brokerEntryName(org, entry),
+            organizationId,
+            clientId,
+            origins: entryHostnames(org, entry).map((host) => `https://${host}`),
+            from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
+            registration: auth.registration === 'open',
+            replaces: auth.replacesBrokerEntry ?? null,
+        },
+    };
+}
+/** {@link BrokerPort} over the platform's recorded ids and a Coolify client. */
+export class PlatformBrokerPort {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async appId() {
+        const id = (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+        if (!id)
+            throw new Error('the platform has not recorded its broker app yet');
+        return id;
+    }
+    async listEnvs() {
+        return this.options.coolify.listEnvs(await this.appId());
+    }
+    async setAuthApps(raw) {
+        await this.options.coolify.bulkUpsertEnvs(await this.appId(), [
+            { key: 'AUTH_APPS', value: raw },
+        ]);
+    }
+    async deploy() {
+        await this.options.coolify.deploy(await this.appId());
+    }
+    async recordedDeploy() {
+        return (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY];
+    }
+    async recordDeploy(value) {
+        const ids = await this.options.store.getServiceIds();
+        await this.options.store.putServiceIds({
+            ...ids,
+            [PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]: value,
+        });
+    }
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Writes one entry's broker entry beside the others and deploys the broker
+ * when its `AUTH_APPS` changed. Foundry's own entry is updated in place, a
+ * hand-written entry the entry declares it replaces is removed, and every
+ * other entry is copied back as it was, an invalid one included: the broker
+ * drops it, and one bad hand-written entry must not block sign-in. Errors
+ * name the entry, never a key.
+ *
+ * Returns the names of foreign entries the broker would drop, and the JSON
+ * of a replaced entry (what the F4a snapshot is handed).
+ */
+export async function writeBrokerEntry(broker, input) {
+    const { want, appKey, previous } = input;
+    const label = `broker entry '${want.name}'`;
+    const brokerAppId = await broker.appId();
+    const env = (await broker.listEnvs()).find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
+    // A value that reads back empty is not an empty list: writing over it
+    // would drop every hand-written entry.
+    if (env && !env.value) {
+        throw new Error(`${label}: the broker's AUTH_APPS read back empty, so nothing was written`);
+    }
+    const raw = env?.value;
+    let parsed = [];
+    if (raw) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${label}: the broker's AUTH_APPS is not JSON, so nothing was written`);
+        }
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${label}: the broker's AUTH_APPS is not a JSON array, so nothing was written`);
+    }
+    const current = parsed;
+    const isOwn = (entry) => isObject(entry) &&
+        entry.name === want.name &&
+        (entry.organizationId === want.organizationId ||
+            (previous !== null && entry.organizationId === previous.organizationId));
+    const isReplaced = (entry) => want.replaces !== null && isObject(entry) && entry.name === want.replaces && !isOwn(entry);
+    const entry = {
+        ...(current.find(isOwn) ?? {}),
+        organizationId: want.organizationId,
+        key: appKey,
+        name: want.name,
+        clientIds: [want.clientId],
+        origins: want.origins,
+        from: want.from,
+        registration: want.registration,
+    };
+    try {
+        validateBrokerAppEntry(entry, brokerAppId, 0);
+    }
+    catch (error) {
+        // The validator's message names the broker app and the entry's place in
+        // the list, never a value; keep only what is wrong with it.
+        const why = error.message.replace(/^.*AUTH_APPS\[\d+\] /, '');
+        throw new Error(`${label} would be dropped by the broker: it ${why}`);
+    }
+    const invalidForeign = [];
+    const replaced = [];
+    const next = [];
+    let placed = false;
+    const place = () => {
+        if (!placed)
+            next.push(entry);
+        placed = true;
+    };
+    current.forEach((existing, index) => {
+        if (isOwn(existing))
+            return place();
+        if (isReplaced(existing)) {
+            replaced.push(existing);
+            return place();
+        }
+        try {
+            validateBrokerAppEntry(existing, brokerAppId, index);
+        }
+        catch {
+            const name = isObject(existing) && typeof existing.name === 'string' ? existing.name : null;
+            invalidForeign.push(name === null ? `AUTH_APPS[${index}]` : name.slice(0, 100));
+        }
+        next.push(existing);
+    });
+    place();
+    const nextRaw = JSON.stringify(next);
+    const changed = JSON.stringify(current) !== nextRaw;
+    if (changed)
+        await broker.setAuthApps(nextRaw);
+    // The platform's own check of the broker's inputs also refuses a broker
+    // whose AUTH_APPS holds an invalid entry; the broker itself only drops it,
+    // so that one does not hold back the deploy.
+    const missing = (await missingBrokerInputs({ listEnvs: () => broker.listEnvs() }, brokerAppId)).filter((input) => input !== 'AUTH_APPS');
+    const live = changed ? nextRaw : raw;
+    if (brokerDeployNeeded(missing, brokerAppId, live, parseBrokerDeployRecord(await broker.recordedDeploy()))) {
+        await broker.deploy();
+        // The platform's record of what the broker last deployed, so its next
+        // apply does not read this write as drift and deploy the broker again.
+        await broker.recordDeploy(brokerDeployRecordValue(brokerAppId, live));
+    }
+    return {
+        invalidForeign,
+        replaced: replaced.length > 0 ? JSON.stringify(replaced) : null,
+    };
+}

package/dist/plan/diff.d.ts

@@ -34,6 +34,8 @@ export interface PlannedStep {
 export interface PlanOrgOptions {
     /** #267: the executor was built with a `loginHostBindings` port. */
     loginHostBindings?: boolean;
+    /** F5: the executor was built with a `broker` port. */
+    broker?: boolean;
 }
 export interface PlanDetail {
     orgId: OrgId;