@wtfalch/foundry 0.31.0 → 0.33.1

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

@@ -1,5 +1,5 @@
 import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
-import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
+import { type Plan, type PlanNote, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
 import type { LiveResource } from './live.js';
@@ -16,6 +16,8 @@ export interface PlatformPlanDetail {
     unmanaged: UnmanagedItem[];
     /** #251: see {@link VersionChangeItem}. Never folded into `plannedSteps`. */
     versionChanges: VersionChangeItem[];
+    /** Advisory lines that block no step; see {@link PlanNote}. */
+    notes: PlanNote[];
 }
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
@@ -161,12 +163,11 @@ export declare const PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY = "archon_deployment";
  */
 export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_broker_app";
 /**
- * The `AUTHZ_BOOTSTRAP_OPERATOR` the last Archon apply set (`none` when it set
- * none). `planArchon` plans the step again when the owner's id recorded by
- * `platform:auth` differs from it, so Archon picks the owner up once auth
- * has recorded it.
+ * The sign-in org id the last Archon apply set as `AUTH_ORGANIZATION_ID` and
+ * registered its broker entry under. `planArchon` plans the step again when
+ * {@link archonAuthOrganizationId} differs from it.
  */
-export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applied_bootstrap_operator";
+export declare const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = "archon_applied_auth_org";
 /**
  * #475: whether the last successful Archon apply patched the app with
  * `custom_network_aliases` and `is_consistent_container_name_enabled: false`
@@ -183,11 +184,11 @@ export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applie
  */
 export declare const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = "archon_applied_rolling_update";
 /**
- * The owner's ZITADEL user id Archon takes as its first operator, from
- * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
- * recorded or the recorded value is `none` (no owner declared).
+ * The sign-in org Archon accepts: the platform owner company's own
+ * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
+ * a platform with no owner company declared. Undefined when neither is recorded.
  */
-export declare function archonBootstrapOperator(recorded: Readonly<Record<string, string>>): string | undefined;
+export declare function archonAuthOrganizationId(recorded: Readonly<Record<string, string>>): string | undefined;
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -207,6 +208,26 @@ export declare const PLATFORM_AUTH_SMTP_SCOPE_KEY = "zitadel_platform_smtp_provi
  * requested, so the invite goes out once. `none` when no owner is declared.
  */
 export declare const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_owner_invite_user_id";
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
+/**
+ * The id of the platform owner company's own sign-in organisation, made by
+ * `platform:auth` with the same name and primary domain a company apply uses,
+ * so that apply finds this org and makes no second one. `none` when the owner
+ * company is not declared. Archon signs people in from this org; the
+ * `foundry` org ({@link PLATFORM_ZITADEL_ORG_SCOPE_KEY}) holds no people.
+ */
+export declare const PLATFORM_OWNER_ORG_SCOPE_KEY = "zitadel_platform_owner_org";
+/** The primary domain `platform:auth` registered on the owner company's sign-in org. */
+export declare const PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY = "zitadel_platform_owner_org_domain";
+/** The owner org's sign-in domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export declare const PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY = "zitadel_platform_owner_org_domain_blocked";
+/**
+ * The sign-in org the recorded owner invite ({@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY})
+ * was made in. An invite recorded against another org (the `foundry` org, on a
+ * platform applied before the owner moved) plans the auth step again.
+ */
+export declare const PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY = "zitadel_platform_owner_invite_org";
 /**
  * #394: the id of the role-less ZITADEL machine user that reserves the
  * username `admin` in the platform's own org, so nobody can sign up under a
@@ -972,6 +993,8 @@ export interface PlanPlatformOptions {
          * these. Default `[]`.
          */
         authOtherInputsMissing?: string[];
+        /** C3: why the owner's invite cannot be made (no work address, no mail port). The rest of the step still plans. */
+        authOwnerInvite?: string;
         files?: string;
         integrations?: string;
         ai?: string;
@@ -1038,6 +1061,12 @@ export interface PlanPlatformOptions {
          * repair step is not planned.
          */
         archonIdTokenUserinfo?: boolean;
+        /**
+         * The executor has the platform's sign-in dependencies and a ZITADEL
+         * client for its instance. Not a block: without it the sign-in policy
+         * step is not planned.
+         */
+        authSignInPolicy?: boolean;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded

package/dist/plan/platform-diff.js

@@ -2,9 +2,11 @@ import { createHash } from 'node:crypto';
 import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
+import { versionChangeNeedsConfirmation } from './confirm-upgrade.js';
 import { ACCESS_PROVIDER_RECORD_KEY } from './gates.js';
 import { legacyAppHostname } from './hostnames.js';
 import { callsSfuAppliedFingerprint } from './platform-sfu.js';
+import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, signInDomainBlockedText } from './sign-in-org.js';
 import { withStepSystem } from './step-system.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
@@ -21,6 +23,7 @@ export function toPlatformPlan(detail, ownerOrgId) {
         steps: detail.plannedSteps.map((p) => p.step),
         unmanaged: detail.unmanaged,
         versionChanges: detail.versionChanges,
+        notes: detail.notes,
     };
 }
 function resourceKey(system, kind, key) {
@@ -78,6 +81,9 @@ export function versionChangeLine(service, from, to, note) {
         kind: VERSION_CHANGE_KIND,
         service,
         description: `${service}: ${from} -> ${to} (${note})`,
+        from,
+        to,
+        needsConfirmation: versionChangeNeedsConfirmation(service, from, to),
     };
 }
 /**
@@ -99,6 +105,8 @@ export function versionNotAppliedLine(service, appLive, applied, pinned) {
             kind: VERSION_CHANGE_KIND,
             service,
             description: `${service}: pinned ${pinned}, running tag unknown`,
+            to: pinned,
+            needsConfirmation: false,
         };
     }
     if (applied === pinned)
@@ -107,6 +115,10 @@ export function versionNotAppliedLine(service, appLive, applied, pinned) {
         kind: VERSION_CHANGE_KIND,
         service,
         description: `${service}: pinned ${pinned}, running ${applied} (not applied by foundry)`,
+        from: applied,
+        to: pinned,
+        // #254: no apply acts on this line, so there is no upgrade to confirm.
+        needsConfirmation: false,
     };
 }
 /**
@@ -185,12 +197,11 @@ export const PLATFORM_ARCHON_DEPLOYMENT_SCOPE_KEY = 'archon_deployment';
  */
 export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_app';
 /**
- * The `AUTHZ_BOOTSTRAP_OPERATOR` the last Archon apply set (`none` when it set
- * none). `planArchon` plans the step again when the owner's id recorded by
- * `platform:auth` differs from it, so Archon picks the owner up once auth
- * has recorded it.
+ * The sign-in org id the last Archon apply set as `AUTH_ORGANIZATION_ID` and
+ * registered its broker entry under. `planArchon` plans the step again when
+ * {@link archonAuthOrganizationId} differs from it.
  */
-export const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = 'archon_applied_bootstrap_operator';
+export const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = 'archon_applied_auth_org';
 /**
  * #475: whether the last successful Archon apply patched the app with
  * `custom_network_aliases` and `is_consistent_container_name_enabled: false`
@@ -207,13 +218,15 @@ export const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = 'archon_applied_bootst
  */
 export const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = 'archon_applied_rolling_update';
 /**
- * The owner's ZITADEL user id Archon takes as its first operator, from
- * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
- * recorded or the recorded value is `none` (no owner declared).
+ * The sign-in org Archon accepts: the platform owner company's own
+ * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
+ * a platform with no owner company declared. Undefined when neither is recorded.
  */
-export function archonBootstrapOperator(recorded) {
-    const id = recorded[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY];
-    return id && id !== 'none' ? id : undefined;
+export function archonAuthOrganizationId(recorded) {
+    const owner = recorded[PLATFORM_OWNER_ORG_SCOPE_KEY];
+    if (owner && owner !== 'none')
+        return owner;
+    return recorded[PLATFORM_ZITADEL_ORG_SCOPE_KEY] || undefined;
 }
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
@@ -234,6 +247,26 @@ export const PLATFORM_AUTH_SMTP_SCOPE_KEY = 'zitadel_platform_smtp_provider_id';
  * requested, so the invite goes out once. `none` when no owner is declared.
  */
 export const PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY = 'zitadel_platform_owner_invite_user_id';
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export const PLATFORM_ZITADEL_ORG_SCOPE_KEY = 'zitadel_platform_org';
+/**
+ * The id of the platform owner company's own sign-in organisation, made by
+ * `platform:auth` with the same name and primary domain a company apply uses,
+ * so that apply finds this org and makes no second one. `none` when the owner
+ * company is not declared. Archon signs people in from this org; the
+ * `foundry` org ({@link PLATFORM_ZITADEL_ORG_SCOPE_KEY}) holds no people.
+ */
+export const PLATFORM_OWNER_ORG_SCOPE_KEY = 'zitadel_platform_owner_org';
+/** The primary domain `platform:auth` registered on the owner company's sign-in org. */
+export const PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY = 'zitadel_platform_owner_org_domain';
+/** The owner org's sign-in domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export const PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY = 'zitadel_platform_owner_org_domain_blocked';
+/**
+ * The sign-in org the recorded owner invite ({@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY})
+ * was made in. An invite recorded against another org (the `foundry` org, on a
+ * platform applied before the owner moved) plans the auth step again.
+ */
+export const PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY = 'zitadel_platform_owner_invite_org';
 /**
  * #394: the id of the role-less ZITADEL machine user that reserves the
  * username `admin` in the platform's own org, so nobody can sign up under a
@@ -1126,7 +1159,7 @@ export function planPlatform(platform, live, options = {}) {
     // reconcile below can be planned in the *same* round hc first comes up,
     // the same way files/mail/archon are planned in auth's own first round.
     const hcReady = hc.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_HC_KEY)]);
-    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? []);
+    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? [], blocked.authOwnerInvite);
     if (auth.step)
         plannedSteps.push(auth.step);
     // #174: the integrations host. Planned after auth; neither step reads the
@@ -1183,6 +1216,10 @@ export function planPlatform(platform, live, options = {}) {
     const idTokenUserinfo = planArchonIdTokenUserinfo(platform, recordedIds, blocked.archonIdTokenUserinfo ?? false);
     if (idTokenUserinfo)
         plannedSteps.push(idTokenUserinfo);
+    // #669: after the ID token repair too, which is proven; a policy call that fails every time holds up nothing.
+    const signInPolicy = planAuthSignInPolicy(platform, recordedIds, blocked.authSignInPolicy ?? false);
+    if (signInPolicy)
+        plannedSteps.push(signInPolicy);
     // #251: one line per service whose recorded applied ref no longer matches
     // what the next apply would use (or, for zitadel, what is actually live).
     // Never pushed into `plannedSteps` -- see `VersionChangeItem`'s own doc
@@ -1227,6 +1264,12 @@ export function planPlatform(platform, live, options = {}) {
     // A blocked jobs scheduler is reported here, not planned: a step that
     // throws every apply, or that can never be seen live and so re-plans
     // forever, is worse than none.
+    if (!platform.ownerOrgId) {
+        unmanaged.push({
+            description: "platform.ownerOrgId is not declared, so no org is the platform's own: no peer password or bridge secret is minted for any Boule and Archon reads no people",
+            key: 'owner-org',
+        });
+    }
     if (jobs.blocked)
         unmanaged.push({ description: jobs.blocked, key: 'jobs' });
     if (platform.sfu.enabled && sfuBlocked) {
@@ -1268,7 +1311,12 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: heartbeats.blocked, key: 'heartbeats' });
     for (const description of uptime.blocked)
         unmanaged.push({ description, key: 'uptime' });
-    return { plannedSteps: plannedSteps.map(withStepSystem), unmanaged, versionChanges };
+    return {
+        plannedSteps: plannedSteps.map(withStepSystem),
+        unmanaged,
+        versionChanges,
+        notes: uptime.notes,
+    };
 }
 /**
  * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
@@ -1687,9 +1735,12 @@ function planSfu(platform, callsOrgSlugs, recordedIds) {
  * promising "this apply re-mints" while one of those is still missing would
  * be wrong the moment it is read.
  */
-function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = []) {
+function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = [], ownerInviteBlocked) {
     if (!platform.auth.enabled)
         return { step: null, blocked: null };
+    // C3/S2: standing notes. The invite and the domain wait on a person; they hold nothing else back.
+    const standing = [ownerInviteBlocked, ownerDomainBlockedText(recordedIds)].filter((t) => Boolean(t));
+    const standingNote = standing.length > 0 ? standing.join('; ') : null;
     const key = resourceKey('coolify', 'app', PLATFORM_AUTH_KEY);
     const connectorApplied = Boolean(recordedIds[PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY]);
     // #211: a recorded app and connector with no recorded broker id is a
@@ -1723,14 +1774,18 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         // Mail and the owner's invite: a platform applied before they existed
         // plans the step again, which only adds them.
         Boolean(recordedIds[PLATFORM_AUTH_SMTP_SCOPE_KEY]) &&
-        Boolean(recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) &&
+        (Boolean(recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY]) || Boolean(ownerInviteBlocked)) &&
+        // The owner company's own sign-in org, and an invite made in it: a
+        // platform whose owner was invited into the `foundry` org plans the step again.
+        Boolean(recordedIds[PLATFORM_OWNER_ORG_SCOPE_KEY]) &&
+        (Boolean(ownerInviteBlocked) ||
+            recordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY] === 'none' ||
+            recordedIds[PLATFORM_AUTH_OWNER_INVITE_ORG_SCOPE_KEY] ===
+                recordedIds[PLATFORM_OWNER_ORG_SCOPE_KEY]) &&
         // The ZITADEL run options reach the container only through the auth
         // step's redeploy, so a platform recorded before them still plans it.
-        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
-        // #394: a platform applied before these existed plans the step again.
-        Boolean(recordedIds[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY]) &&
-        Boolean(recordedIds[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY])) {
-        return { step: null, blocked: null };
+        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {
+        return { step: null, blocked: standingNote };
     }
     // The admin key was minted but never reached the host. ZITADEL shows a
     // token once, so it is lost: minting another would hide that, and skipping
@@ -1801,6 +1856,7 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         // 5: and only claim "this apply re-mints" when `otherInputsMissing` is
         // actually empty -- see this function's own doc comment.
         blocked: executorBlocked ??
+            standingNote ??
             loginClientNeedsMintNote(loginClientUndelivered, loginClientApplied, authDrifted, loginClientRecord, otherInputsMissing),
     };
 }
@@ -2249,6 +2305,31 @@ function planArchonIdTokenUserinfo(platform, recordedIds, wired) {
         },
     };
 }
+/**
+ * #394, #669: the platform's sign-in org reserves the username `admin` and
+ * switches self-registration off. One `zitadel:sign-in-policy` step keyed
+ * {@link PLATFORM_AUTH_KEY}, planned while either recorded key is missing and
+ * the sign-in's ZITADEL org is recorded. Not planned before that, and not
+ * blocked: nothing is owed until the sign-in exists.
+ */
+function planAuthSignInPolicy(platform, recordedIds, wired) {
+    if (!wired || !platform.auth.enabled)
+        return null;
+    if (!recordedIds[PLATFORM_ZITADEL_ORG_SCOPE_KEY])
+        return null;
+    if (recordedIds[PLATFORM_AUTH_RESERVED_ADMIN_USERNAME_SCOPE_KEY] &&
+        recordedIds[PLATFORM_AUTH_REGISTRATION_CLOSED_SCOPE_KEY]) {
+        return null;
+    }
+    return {
+        action: { system: 'zitadel', kind: 'sign-in-policy', key: PLATFORM_AUTH_KEY, desired: {} },
+        step: {
+            description: "reserve the username 'admin' and switch self-registration off on the platform's sign-in org",
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 /**
  * #604: the platform's ZITADEL as a sign-in provider in Cloudflare Access: a
  * ZITADEL client for Cloudflare, then edge's `ensureProvider`. One
@@ -2449,9 +2530,9 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
  * destructive step removes whatever of it is recorded (edge removes its KV
  * namespace with the script).
  *
- * The returned `blocked` lines are reported in `unmanaged`; some accompany a
- * planned step (a secret whose source does not exist yet), because the step
- * still delivers everything that exists.
+ * The returned `blocked` lines are reported in `unmanaged`. A secret whose
+ * source does not exist yet blocks nothing: the step still delivers
+ * everything that exists, so it comes back in `notes`.
  */
 function planUptime(platform, recordedIds, executorBlocked, heldOptional, archonApplied, uptimeHeld = {
     token: true,
@@ -2469,9 +2550,9 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
     });
     if (!uptime.enabled) {
         if (!uptimeRecorded(recordedIds))
-            return { step: null, blocked: [] };
+            return { step: null, blocked: [], notes: [] };
         if (executorBlocked)
-            return { step: null, blocked: [executorBlocked] };
+            return { step: null, blocked: [executorBlocked], notes: [] };
         return {
             step: {
                 action: action({ remove: true }),
@@ -2482,6 +2563,7 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
                 },
             },
             blocked: [],
+            notes: [],
         };
     }
     if (!uptime.tag || !uptime.sha256) {
@@ -2490,6 +2572,7 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
             blocked: [
                 'the uptime Worker is blocked, not planned: no artifact is pinned; declare uptime.tag (an Archon release tag) and uptime.sha256 (the digest of archon-uptime-worker.js at that tag)',
             ],
+            notes: [],
         };
     }
     if (!archonApplied) {
@@ -2498,16 +2581,25 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
             blocked: [
                 'the uptime Worker is blocked, not planned: platform:archon has not been applied yet',
             ],
+            notes: [],
         };
     }
     if (executorBlocked)
-        return { step: null, blocked: [executorBlocked] };
-    const missing = [];
+        return { step: null, blocked: [executorBlocked], notes: [] };
+    const notes = [];
     if (!heldOptional.includes('CHAT_ACCESS_TOKEN')) {
-        missing.push(`the uptime Worker has no chat credential (CHAT_ACCESS_TOKEN): hold one under ${PLATFORM_UPTIME_CHAT_TOKEN_REF} and it is set on the next apply; until then it sends no chat alerts`);
+        notes.push({
+            key: 'uptime:CHAT_ACCESS_TOKEN',
+            service: 'uptime',
+            description: `the uptime Worker has no chat credential (CHAT_ACCESS_TOKEN): hold one under ${PLATFORM_UPTIME_CHAT_TOKEN_REF} and it is set on the next apply; until then it sends no chat alerts`,
+        });
     }
     if (!heldOptional.includes('MAIL_API_KEY')) {
-        missing.push(`the uptime Worker has no mail API key (MAIL_API_KEY): hold one under ${PLATFORM_UPTIME_MAIL_KEY_REF} and it is set on the next apply; until then it sends no alert email`);
+        notes.push({
+            key: 'uptime:MAIL_API_KEY',
+            service: 'uptime',
+            description: `the uptime Worker has no mail API key (MAIL_API_KEY): hold one under ${PLATFORM_UPTIME_MAIL_KEY_REF} and it is set on the next apply; until then it sends no alert email`,
+        });
     }
     const hostname = platform.archon.hostname;
     // Applied only once a run got to its end and recorded these: a Worker that
@@ -2523,7 +2615,7 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
         (recordedIds[PLATFORM_UPTIME_APPLIED_VARS_SCOPE_KEY] ?? '') === uptimeHeld.vars &&
         recordedIds[PLATFORM_UPTIME_APPLIED_SECRETS_SCOPE_KEY] === uptimeSecretNames(heldOptional);
     if (applied)
-        return { step: null, blocked: missing };
+        return { step: null, blocked: [], notes };
     return {
         step: {
             action: action({ hostname, gitRef: uptime.tag, sha256: uptime.sha256 }),
@@ -2533,7 +2625,8 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
                 migrates: false,
             },
         },
-        blocked: missing,
+        blocked: [],
+        notes,
     };
 }
 /**
@@ -2671,8 +2764,8 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
         Boolean(recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY]) &&
         recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] ===
             recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
-        (recordedIds[PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY] ?? 'none') ===
-            (archonBootstrapOperator(recordedIds) ?? 'none') &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY] ===
+            archonAuthOrganizationId(recordedIds) &&
         // #475: a platform applied before the rolling-update fix keeps planning
         // this step until a confirmed redeploy has cleared it. #480: this marker
         // alone does not catch the live app's settings changing back afterward
@@ -2737,3 +2830,12 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted,
         blocked: null,
     };
 }
+/** The blocked text for a refused owner-org sign-in domain, while it is recorded and not yet primary. */
+function ownerDomainBlockedText(recordedIds) {
+    const blockedDomain = recordedIds[PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY];
+    if (!blockedDomain)
+        return null;
+    if (recordedIds[PLATFORM_OWNER_ORG_DOMAIN_SCOPE_KEY] === blockedDomain)
+        return null;
+    return signInDomainBlockedText('the platform owner', blockedDomain).replace(ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, PLATFORM_OWNER_ORG_DOMAIN_BLOCKED_SCOPE_KEY);
+}

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

@@ -61,6 +61,8 @@ export interface OrgPlatformReadiness {
      * while `MAIL_DOMAIN_SCOPE_KEY` was still recorded as the apex.
      */
     platformApex: string | null;
+    /** `DeclaredPlatform.ownerOrgId`, or `null` when no platform is declared or it is empty. The one fact "this is the platform's own org" rests on. */
+    platformOwnerOrgId: string | null;
     /** `DeclaredPlatform.mail.lettermintProjectId`, `null` when undeclared or when no platform is declared. See {@link platformApex}'s own doc comment for why this is unconditional too. */
     platformLettermintProjectId: string | null;
     /** The files host (#171). Files is always on for every org (#80), so `false` always blocks rather than only mattering when a flag is set. */

package/dist/plan/platform-org.js

@@ -27,6 +27,7 @@ export const NO_DOMAIN_MAIL_APEX = 'oikos.host';
 export const DEFAULT_ORG_PLATFORM_READINESS = {
     mailHost: null,
     platformApex: null,
+    platformOwnerOrgId: null,
     platformLettermintProjectId: null,
     filesReady: false,
     aiReady: false,
@@ -124,6 +125,7 @@ edgePortPresent = false) {
         // mail.lettermintProjectId are facts regardless of whether mail itself is
         // enabled or applied.
         platformApex: platform.apex,
+        platformOwnerOrgId: platform.ownerOrgId || null,
         platformLettermintProjectId: platform.mail.lettermintProjectId ?? null,
         filesReady: filesApplied && missingKeys.files === null,
         filesUrl: filesApplied

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

@@ -1,5 +1,5 @@
 import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
-import type { DeclaredOrg } from '../org.js';
+import { type DeclaredOrg } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { DeclaredOrgStore, PlatformStore } from '../store.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
@@ -10,7 +10,8 @@ import type { TunnelPort } from './edge-tunnels.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import type { PlatformDriftedSteps, PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
-import { type BrokerDeployRecord } from './platform-diff.js';
+import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platform-diff.js';
+export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 import { type PlatformUptimeDeps } from './uptime-worker.js';
 /**
@@ -90,7 +91,14 @@ export interface PlatformAuthDeps {
     tunnels: PlatformTunnelsFactory;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
-    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'inviteOrgOwner'> & PlatformZitadelSmtp;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'inviteOrgOwner' | 'addOrgDomain' | 'setPrimaryOrgDomain' | 'setUserMetadata' | 'getUserMetadata'> & PlatformZitadelSmtp;
+    /**
+     * Mails the owner's first-sign-in link to their personal address (the same
+     * port as `FoundryStepExecutorPorts.ownerInviteMail`). The link carries the
+     * invite code, so `send` must not log it or put it in an error. Without it
+     * the owner invite cannot run and the step stops there with a fixed message.
+     */
+    ownerInviteMail?: FoundryStepExecutorPorts['ownerInviteMail'];
     /**
      * Builds the ZITADEL port for the new instance from its issuer URL
      * (`https://<auth.hostname>`). When set it is used instead of
@@ -315,6 +323,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         auth?: string;
         authExecutorMissing?: boolean;
         authOtherInputsMissing?: string[];
+        authOwnerInvite?: string;
         files?: string;
         integrations?: string;
         ai?: string;
@@ -336,6 +345,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         archonRunsInsideApp?: boolean;
         archonDeployRunning?: string;
         archonIdTokenUserinfo?: boolean;
+        authSignInPolicy?: boolean;
     }>;
     /**
      * foundry#542: why the uptime Worker cannot run yet, which optional secrets
@@ -519,12 +529,51 @@ export interface PlatformMailRuntime {
     /** Tries at handing the admin key to the host (default 3). */
     deliverAttempts?: number;
 }
+/**
+ * #211: the broker cannot start without `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`,
+ * `LETTERMINT_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already
+ * skips deploying the broker while any is missing
+ * ({@link missingBrokerInputs}); this is the same check surfaced through
+ * `blockedSteps`, so a plan says why, by name, rather than the broker simply
+ * sitting undeployed with no explanation. `null` while there is no broker
+ * app id recorded yet (nothing to check) or every input is present.
+ *
+ * #211 round 3: wraps the live read the way {@link mailBlockedReason} wraps
+ * its own Coolify call -- a transient `listEnvs` failure must report a
+ * blocked reason naming the broker app id, never throw out of
+ * `blockedSteps` and take the rest of the plan down with it.
+ *
+ * #211 round 5 addendum: when `AUTH_APPS` is the reason, names which problem
+ * it actually is ({@link authAppsProblem}) instead of always saying "it has
+ * no ... AUTH_APPS yet" -- that wording is only true when nothing has been
+ * set; a present-but-invalid value is a different failure (a person needs to
+ * go fix an entry, not merely wait for one of #209/#210/Archon's own
+ * registration to supply one), and reporting it identically hid which one
+ * was true.
+ *
+ * #210: `LETTERMINT_API_TOKEN` joins `ZITADEL_SERVICE_USER_TOKEN` in being
+ * excluded from `otherInputsMissing` -- but only while `auth.heldKeys`
+ * actually resolves {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} right now.
+ * `planAuth`'s own "loop fix" stops planning this step the moment every
+ * `otherInputsMissing` entry looks like something only another run can
+ * supply; excluding `LETTERMINT_API_TOKEN` unconditionally (the way
+ * `ZITADEL_SERVICE_USER_TOKEN` is, since foundry can always eventually mint
+ * that one) would keep the step planned, and `provisionPlatformAuth`
+ * running its full body, forever on a host that never wires `heldKeys` or
+ * whose operator has not put a Lettermint key there yet -- exactly the
+ * wasteful-replan bug #211 round 5 fixed for the broker deploy itself. Once
+ * the key *is* held, excluding it lets this run's `provisionPlatformAuth`
+ * push it (see that function's own `heldMailKey` read) and clears the gap
+ * for good.
+ */
+/** Why the platform owner cannot be invited yet, or `null`. Fixed text: names no address. */
+export declare function ownerInviteBlockedReason(ownerCompany: DeclaredOrg | null, hasInviteMail: boolean): string | null;
 /**
  * #175: everything {@link provisionPlatformArchon} needs beyond
  * {@link PlatformStepExecutionContext}, bundled like {@link PlatformAuthDeps}.
  */
 export interface PlatformArchonDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'getDeployment'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'listEnvironments' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'getDeployment'>;
     /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
     dns: PlatformDnsFactory;
     /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
@@ -603,8 +652,6 @@ export interface PlatformArchonRuntime {
  * org (`foundry:<orgId>`), with the platform's step key in the org id's place.
  */
 export declare const PLATFORM_ARCHON_ACCESS_APP_NAME = "foundry:platform:archon";
-/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
-export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */
 export declare const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = "zitadel_platform_archon_client_id";
 /**
@@ -1246,4 +1293,3 @@ export declare function filesPublicHostsValue(publicHosts: string | undefined, s
  * from the declared orgs, for its apply and its drift check alike.
  */
 export declare function filesShareDomains(orgs: readonly DeclaredOrg[]): string[];
-export {};