@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/plan/platform-diff.js

@@ -47,6 +47,17 @@ export const PLATFORM_ARCHON_KEY = 'platform:archon';
  */
 export const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = 'archon_applied_hostname';
 export const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = 'archon_applied_git_ref';
+/**
+ * #211 round 4: the broker app id Archon last registered its entry with.
+ * `provisionPlatformArchon` reads the broker to register with from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} alone, so a broker recreated under a
+ * new app id (the old one deleted by hand, or `platform:auth` minting a fresh
+ * one) leaves Archon "applied" against a broker that no longer holds its
+ * entry. `planArchon` plans the step again whenever this differs from the
+ * currently recorded {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}, the same way a
+ * changed hostname or `gitRef` does.
+ */
+export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_app';
 /**
  * #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.
@@ -56,6 +67,132 @@ export const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = 'archon_applied_git_ref
 export const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = 'archon_gate_closed';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
+/**
+ * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
+ * for the login app and the broker, mirroring
+ * {@link PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY}/
+ * {@link PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} in shape -- a recorded
+ * id once delivered, an undelivered id recorded first, the moment the user
+ * is minted.
+ *
+ * Unlike the admin pair, an undelivered login-client key never blocks
+ * {@link planAuth} from planning the step again -- #216 round 2: `planAuth`
+ * below does read it, but only to surface a non-blocking note (alongside a
+ * planned step, the way #211 round 3's broker-deploy block already is)
+ * rather than to hold the step back. Revoking a stale login-client PAT
+ * destroys nothing -- unlike the admin user's, whose loss the admin pair's
+ * own "delete that user by hand" message exists for because nothing else
+ * here re-derives the ZITADEL masterkey a lost admin PAT might have been the
+ * only record of -- so `mintLoginClientMachineUser` (`zitadel-machine-user.ts`)
+ * always lists and deletes every PAT the user already holds before minting a
+ * fresh one. That is what lets `provisionPlatformAuth` simply re-mint on the
+ * next run, with no manual step, which is #216's whole fix for the bug PR
+ * #215 shipped with: PR #215 mirrored the admin pair's forever-blocking
+ * behaviour for this key too, which meant one failed Coolify call lost the
+ * login-client token for good.
+ *
+ * #216 round 4: the value recorded here is JSON ({@link
+ * PlatformAuthLoginClientRecord}, parsed back by
+ * {@link parseLoginClientRecord}), not the bare user id round 2-3 wrote --
+ * the user id alone can never tell a healthy delivery from one a concurrent
+ * apply has since clobbered, because `mintLoginClientMachineUser` reuses the
+ * same user on every mint. The PAT id travels alongside it so {@link
+ * planAuth} can ask ZITADEL, on every plan, whether that exact PAT is still
+ * the sole live one.
+ *
+ * #216 round 5: that alone is still not enough -- a recorded PAT can be the
+ * sole live one in ZITADEL while Coolify holds a *different*, already-dead
+ * token, when two concurrent applies interleave their own writes and
+ * records in the right (wrong) order (see `authLoginClientDrifted`'s own
+ * doc comment in `platform-providers.ts` for the exact ordering). So the
+ * record also carries `tokenHash`, a sha256 of the exact token that was
+ * delivered -- never the token itself -- which `authLoginClientDrifted`
+ * compares against what is actually live in both apps' Coolify envs.
+ */
+export const PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY = 'zitadel_platform_login_client_user_id';
+export const PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_login_client_user_undelivered';
+/**
+ * Parses a {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} scope id back
+ * into a {@link PlatformAuthLoginClientRecord}. `null` for anything that is
+ * not one -- absent, the pre-round-4 plain user-id string, the round 2-4
+ * `{userId, patId}` shape with no `tokenHash`, or corrupt JSON -- the same
+ * "malformed reads as unapplied, never throws" rule
+ * {@link parseBrokerDeployRecord} follows and for the same reason: this is a
+ * planning read, not a validation boundary. A pre-round-5 record reading as
+ * unapplied is the intended migration: the next apply's fresh mint recomputes
+ * it in the new shape, the same way a pre-round-4 plain-string record already
+ * did.
+ */
+export function parseLoginClientRecord(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.userId !== 'string' || !candidate.userId)
+        return null;
+    if (typeof candidate.patId !== 'string' || !candidate.patId)
+        return null;
+    if (typeof candidate.tokenHash !== 'string' || !candidate.tokenHash)
+        return null;
+    return { userId: candidate.userId, patId: candidate.patId, tokenHash: candidate.tokenHash };
+}
+/**
+ * #204/#211: the sign-in broker app `provisionPlatformAuth` creates alongside
+ * ZITADEL and the login app. Defined here, not in `platform-providers.ts`
+ * (which imports it), because `planAuth` below needs it too -- a recorded
+ * `coolify:app:platform:auth` key with no recorded broker id is a platform
+ * provisioned before #204 shipped, and must still plan the step again so the
+ * broker gets created rather than being read as fully applied.
+ */
+export const PLATFORM_AUTH_BROKER_SCOPE_KEY = 'coolify_platform_auth_broker_app';
+/**
+ * #211: recorded once the broker has actually been deployed -- distinct from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} (the app exists) precisely because
+ * the app can exist for a while before it is ever deployed (see
+ * `missingBrokerInputs` in `platform-providers.ts`). Defined here, not there,
+ * for the same reason as {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}: `planAuth`
+ * below needs it too, so a broker that is created but not yet deployed still
+ * plans the step again instead of reading as fully applied for good.
+ */
+export const PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY = 'coolify_platform_auth_broker_deployed';
+/**
+ * Parses a {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} scope id back into
+ * a {@link BrokerDeployRecord}. `null` for anything that is not one --
+ * absent, the pre-round-5 plain broker-id string, or corrupt JSON -- because
+ * this is a planning read, not a validation boundary: a malformed record
+ * must read as "not deployed" so the step plans (and overwrites it) again,
+ * never throw and take the rest of the plan down with it. Exported here
+ * rather than defined in `platform-providers.ts` for the same reason
+ * {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} itself was moved here in
+ * round 2 -- {@link planAuth} below needs it too, without a circular import.
+ */
+export function parseBrokerDeployRecord(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.brokerAppId !== 'string' || !candidate.brokerAppId)
+        return null;
+    if (typeof candidate.authAppsHash !== 'string' || !candidate.authAppsHash)
+        return null;
+    return { brokerAppId: candidate.brokerAppId, authAppsHash: candidate.authAppsHash };
+}
 /**
  * #197: the `cloudflared` connector app `provisionPlatformAuth` runs for its
  * own tunnel. Consulted by `planAuth` below so that a tunnel recorded with no
@@ -68,6 +205,21 @@ export const PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_auth_conn
 export const PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_mail_connector_app';
 /** #197: the same connector scope id for the Archon step's own tunnel, read by `planArchon`. */
 export const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_archon_connector_app';
+/**
+ * #213: the three held-key refs, under tenant `platform`, Archon's own
+ * onboarding reads before it can start (archon#101 round 3, archon#104).
+ * `planArchon`'s step puts each one, once, before Archon's app deploys; an
+ * entry already held is left alone, never overwritten
+ * (`putArchonMasterKeys` in `platform-providers.ts`). The Coolify URL and
+ * token are values this package already deploys with; the Cloudflare
+ * parent token ("API Tokens Write", so Archon can mint its own scoped
+ * child tokens from it) is a human-created credential the host supplies --
+ * neither Coolify nor Cloudflare lets either be minted over an API (#213
+ * "Human steps").
+ */
+export const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = 'platform:master:coolify-url';
+export const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = 'platform:master:coolify-token';
+export const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = 'platform:master:cloudflare-token';
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -144,6 +296,27 @@ export const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = 'ai_platform_internal_url';
  */
 export const PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY = 'ai_platform_management_key_id';
 export const PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY = 'ai_platform_management_key_undelivered';
+/**
+ * #201: set when ai's `POST /v1/platform/keys` reports its `archon` key
+ * already exists but returns no secret -- a mint this record never learned
+ * about (most likely the crash window {@link PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY}'s
+ * own comment describes: the secret returned once and was never recorded).
+ * ai shows a credential's secret only at mint time, so it cannot be
+ * recovered; the planner reports this instead of minting under another
+ * name. A person revokes the live `archon` key in ai and removes this
+ * recorded key to let the step mint a fresh one.
+ */
+export const PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY = 'ai_platform_management_key_conflict';
+/**
+ * #201: the same two-key discipline as {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}
+ * and {@link PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY}, for the Ed25519 pair
+ * foundry mints to sign its calls to ai's `POST /v1/platform/keys`. The
+ * undelivered key is recorded the moment the pair is minted; the set key,
+ * only once the private half was delivered and the public half pinned on
+ * the runner as `MANAGEMENT_PUBLIC_KEYS`.
+ */
+export const PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY = 'ai_platform_signing_key_undelivered';
+export const PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY = 'ai_platform_signing_key_set';
 /**
  * #172: ai's platform (operator) tenant id, which the management key belongs
  * to -- what ai's own README calls `AI_ORGANISATION_ID`. Not a secret.
@@ -169,14 +342,6 @@ export const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = 'ai_platform_migrate_blocke
  * that throws) is repaired by the next one.
  */
 export const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = 'ai_platform_deploy_pending';
-/**
- * #172: what the planner says while no AI management key minter is supplied.
- * A fixed text: it is part of the stale-plan comparison. ai issues its first
- * platform credential only through its `keys:issue-archon` script, run
- * against its database with its keys worker credential; it has no HTTP route
- * for that, so foundry cannot build a minter over ai's admin API yet.
- */
-export const PLATFORM_AI_MINTER_BLOCKED = "the platform's AI host is blocked, not planned: no AI management key minter was supplied. ai mints its first platform key only through its keys:issue-archon script against its database, so the host must supply PlatformAiDeps.managementKeyMinter";
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -261,7 +426,7 @@ export function planPlatform(platform, live, options = {}) {
     const sfu = platform.sfu.enabled && sfuBlocked ? null : planSfu(platform);
     if (sfu)
         plannedSteps.push(sfu);
-    const auth = planAuth(platform, recordedIds, blocked.auth);
+    const auth = planAuth(platform, recordedIds, blocked.auth, blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? []);
     if (auth.step)
         plannedSteps.push(auth.step);
     // #174: the integrations host. Planned after auth; neither step reads the
@@ -476,14 +641,123 @@ function planSfu(platform) {
  * -- `provisionPlatformAuth` re-runs idempotently against everything it
  * already built and only adds the connector, so this never mints or
  * redeploys what a prior run already finished.
+ *
+ * #211: the same holds for the broker ({@link PLATFORM_AUTH_BROKER_SCOPE_KEY}).
+ * A platform applied before #204 shipped the broker recorded the app and the
+ * connector and never the broker, so without this check it would read as
+ * fully applied and Archon would never find a broker to register with.
+ *
+ * #211 round 2: a recorded broker id is not the same as a *deployed* broker
+ * ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY}) -- `provisionPlatformAuth`
+ * creates and records the app before it has `ZITADEL_SERVICE_USER_TOKEN`/
+ * `RESEND_API_TOKEN` to deploy it with (#209, #210). So this still plans the
+ * step again while the broker sits undeployed: `executorBlocked` (from
+ * `authBrokerBlockedReason`) reports it blocked, by name, for as long as the
+ * inputs stay missing, and the moment they arrive the same replanned step
+ * deploys it -- no apply is left blocked for good once its inputs exist.
+ *
+ * #211 round 5: "deployed" ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY})
+ * is read back through {@link parseBrokerDeployRecord}, not `Boolean(...)`,
+ * and only counts while the record's `brokerAppId` matches the currently
+ * recorded {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} -- a broker recreated under
+ * a new app id (the old one deleted by hand, or a fresh mint) leaves the old
+ * record pointing at an app that no longer exists, and a plain `Boolean`
+ * check (round 2-4) could never see that. This function has no live Coolify
+ * access, so it cannot also compare the record's `authAppsHash` against a
+ * live `AUTH_APPS` -- that half of the same rule (`brokerDeployNeeded` in
+ * `platform-providers.ts`) only runs inside the two `provision*` functions,
+ * which do have one. A malformed record parses to `null` and is treated the
+ * same as none recorded -- see {@link parseBrokerDeployRecord}'s own doc
+ * comment.
+ *
+ * #211 round 3: `executorBlocked` must not hold back the step itself once
+ * the broker exists (`brokerApplied`). `authBrokerBlockedReason` only ever
+ * returns non-null once a broker app id is recorded, so `executorBlocked &&
+ * brokerApplied` can only mean "broker created, not yet deployed" -- never
+ * "no executor". Blocking the whole step on that would deadlock: #209 mints
+ * the broker's own token as part of running this step, and a step that is
+ * never planned never runs. So this still plans the step -- surfacing
+ * `executorBlocked` in `blocked` for visibility, not to stop planning.
+ *
+ * #211 round 6: round 3's `!brokerApplied` guard assumed "no executor" and
+ * "broker not yet created" always coincide. They don't: a broker recorded on
+ * an earlier apply, then run again against a host built without its auth
+ * dependencies (`this.auth` undefined in `PlatformProvidersExecutor`), has
+ * `brokerApplied === true` and `executorBlocked` set to the no-deps message,
+ * so round 3's check let the step through and apply threw on the missing
+ * executor. `executorMissing` is that case's own signal
+ * ({@link PlanPlatformOptions.blocked}'s `authExecutorMissing`) and holds the
+ * step back unconditionally -- there is no executor to run it with, whatever
+ * `recordedIds` says.
+ *
+ * #216: a platform with every one of the above applied but no recorded
+ * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} is not fully applied
+ * either -- the same "provisioned before this shipped" case
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} already covers, here for a platform
+ * applied before #216's login-client mint existed at all.
+ * `provisionPlatformAuth` re-runs idempotently against everything it already
+ * built and only mints and delivers the login-client token, so this never
+ * redoes what a prior run already finished. Unlike the admin key, an
+ * undelivered login-client key never blocks this check -- see
+ * {@link PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY}'s own doc comment
+ * for why -- though it is still read, below, for a non-blocking note.
+ *
+ * #216 round 4: a *recorded* login-client key is also not enough on its own
+ * -- `authDrifted` (the host's own `driftedSteps`, reading ZITADEL's live
+ * PATs for the recorded user) means the PAT this platform's two apps were
+ * handed is no longer the sole live one: a concurrent apply's own mint
+ * revoked or replaced it, or minted an extra one alongside it. Round 2 and
+ * round 3 both tried to catch that from inside the same run that delivered
+ * the token (checking once after every write, then checking again before
+ * every write) and both left a window a slow concurrent write could still
+ * land in. This closes it from the other end instead: every plan re-checks
+ * the live state no matter which run last touched it, so whichever run's
+ * write actually won is caught on the very next plan, not raced against
+ * from inside the run that might lose.
+ *
+ * #216 round 5: `otherInputsMissing` keeps the note below honest when a
+ * re-mint is needed (undelivered or drifted) but cannot actually happen yet
+ * -- `provisionPlatformAuth` only mints and delivers once the broker's
+ * inputs *other than* `ZITADEL_SERVICE_USER_TOKEN` are all present
+ * (deferred, not blocked -- see that function's own doc comment), so a note
+ * 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) {
+function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = []) {
     if (!platform.auth.enabled)
         return { step: null, blocked: null };
     const key = resourceKey('coolify', 'app', PLATFORM_AUTH_KEY);
     const connectorApplied = Boolean(recordedIds[PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY]);
-    if (recordedIds[key] && connectorApplied)
+    // #211: a recorded app and connector with no recorded broker id is a
+    // platform provisioned before #204 shipped the broker, or a run that threw
+    // before the broker's own id was recorded -- still not fully applied, the
+    // same rule `connectorApplied` already follows for #197's connector.
+    const brokerApplied = Boolean(recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY]);
+    // #211 round 2: also require the broker to be deployed, not merely created.
+    // #211 round 5: and only while the deploy record still names the broker
+    // that is currently recorded -- see this function's own doc comment.
+    const brokerDeployRecord = parseBrokerDeployRecord(recordedIds[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]);
+    const brokerDeployed = brokerDeployRecord !== null &&
+        brokerDeployRecord.brokerAppId === recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+    // #216 round 4: parsed back, not just `Boolean(...)` -- see this
+    // function's own doc comment and {@link parseLoginClientRecord}.
+    const loginClientRecord = parseLoginClientRecord(recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY]);
+    // #216 round 4: a recorded record whose PAT has since drifted (revoked,
+    // replaced, or joined by an extra live PAT) reads as unapplied, same as
+    // none recorded at all -- see this function's own doc comment.
+    const loginClientApplied = loginClientRecord !== null && !authDrifted;
+    // #216 round 2: read for a non-blocking note only -- see
+    // {@link PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY}'s own doc
+    // comment for why this never holds the step back the way the admin key's
+    // own `undelivered` check below does.
+    const loginClientUndelivered = recordedIds[PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY];
+    if (recordedIds[key] &&
+        connectorApplied &&
+        brokerApplied &&
+        brokerDeployed &&
+        loginClientApplied) {
         return { step: null, blocked: null };
+    }
     // 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
     // would leave foundry without its admin key. Report it, plan nothing.
@@ -494,7 +768,16 @@ function planAuth(platform, recordedIds, executorBlocked) {
             blocked: `the platform's sign-in is blocked, not planned: the admin key of ZITADEL machine user ${undelivered} was minted but never delivered and cannot be shown again; delete that user in ZITADEL and remove the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`,
         };
     }
-    if (executorBlocked)
+    // #211 round 6: the executor itself is unusable on this host -- nothing to
+    // plan, whatever the broker's recorded state says.
+    if (executorMissing)
+        return { step: null, blocked: executorBlocked ?? null };
+    // #211 round 3: a blocked reason with no broker yet created also means the
+    // executor is unusable (no auth dependencies) -- nothing to plan.
+    // A blocked reason with the broker already created means only its deploy
+    // is held back; plan the step anyway so it can keep retrying and, once
+    // #209/#210 land, deploy on the very next apply.
+    if (executorBlocked && !brokerApplied)
         return { step: null, blocked: executorBlocked };
     return {
         step: {
@@ -505,14 +788,48 @@ function planAuth(platform, recordedIds, executorBlocked) {
                 desired: { hostname: platform.auth.hostname, gitRef: platform.auth.gitRef },
             },
             step: {
-                description: `provision the platform's own sign-in (ZITADEL) at ${platform.auth.hostname}`,
+                description: `provision the platform's own sign-in (ZITADEL, the login app and the sign-in broker) at ${platform.auth.hostname}`,
                 destroys: false,
                 migrates: false,
             },
         },
-        blocked: null,
+        // #211 round 3: still surface a broker-deploy block for visibility even
+        // though the step above is planned -- see the doc comment above. #216
+        // round 2: when nothing executor-side is blocked, surface an in-flight
+        // (or abandoned) login-client mint the same way -- informational only,
+        // never a reason to skip planning. #216 round 4: same treatment for a
+        // drifted (already-delivered, now stale) login-client token. #216 round
+        // 5: and only claim "this apply re-mints" when `otherInputsMissing` is
+        // actually empty -- see this function's own doc comment.
+        blocked: executorBlocked ??
+            loginClientNeedsMintNote(loginClientUndelivered, loginClientApplied, authDrifted, loginClientRecord, otherInputsMissing),
     };
 }
+/**
+ * #216 round 5: the note {@link planAuth} surfaces when the login-client key
+ * needs a re-mint it cannot yet perform, split out of `planAuth`'s own return
+ * statement so the "needs minting" question and the "can it actually mint
+ * right now" question are each answered in one place.
+ */
+function loginClientNeedsMintNote(loginClientUndelivered, loginClientApplied, authDrifted, loginClientRecord, otherInputsMissing) {
+    const undeliveredNeedsMint = Boolean(loginClientUndelivered) && !loginClientApplied;
+    let subject = null;
+    if (undeliveredNeedsMint) {
+        subject = `the login-client key of ZITADEL machine user ${loginClientUndelivered} was minted but not yet confirmed delivered`;
+    }
+    else if (authDrifted && loginClientRecord) {
+        subject = `the login-client token delivered for ZITADEL machine user ${loginClientRecord.userId} is no longer the sole live token on that user, likely revoked or replaced by a concurrent apply`;
+    }
+    if (subject === null)
+        return null;
+    if (otherInputsMissing.length > 0) {
+        return `${subject}; this apply cannot re-mint and redeliver it yet -- the platform's sign-in broker still needs ${otherInputsMissing.join(' and ')} first`;
+    }
+    const action = undeliveredNeedsMint
+        ? 'this apply re-mints (revoking it) and retries'
+        : 'this apply re-mints and redelivers';
+    return `${subject}; ${action} -- no manual step needed`;
+}
 /**
  * #169: the platform's own mail server (Stalwart), built fresh -- Stalwart on
  * Coolify with its own storage, reached at `platform.mail.hostname` for
@@ -763,6 +1080,18 @@ function planAi(platform, recordedIds, executorBlocked) {
         recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY] !== platform.ai.gitRef;
     if (applied && !drifted)
         return { step: null, blocked: null };
+    // #201: the signing pair foundry mints to authenticate its own calls to
+    // ai's platform/keys route. Minted but not confirmed delivered and pinned:
+    // the private half cannot be recovered, so report it rather than mint
+    // another (the same reason the management key check below never mints
+    // twice).
+    const signingUndelivered = recordedIds[PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY];
+    if (signingUndelivered && !recordedIds[PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: its signing key ${signingUndelivered} was minted but not confirmed delivered and pinned, and the private half cannot be recovered; check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
+        };
+    }
     // Minted but never delivered: ai shows a key's secret once, so it is lost.
     // Minting another would hide that; report it and plan nothing.
     const undelivered = recordedIds[PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY];
@@ -772,6 +1101,16 @@ function planAi(platform, recordedIds, executorBlocked) {
             blocked: `the platform's AI host is blocked, not planned: AI management key ${undelivered} was minted but never delivered and cannot be shown again; revoke it in ai (keys:revoke --id ${undelivered}) and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY} to mint a new one`,
         };
     }
+    // #201: ai reported its 'archon' key already exists with no secret to
+    // show -- a mint this record never learned about. Never minted under
+    // another name; a person must revoke the live key first.
+    const conflict = recordedIds[PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY];
+    if (conflict) {
+        return {
+            step: null,
+            blocked: `the platform's AI host is blocked, not planned: ai already holds a management key named 'archon' (${conflict}) that was never recorded delivered, so its secret cannot be shown again; revoke it in ai and remove the recorded key ${PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY} to mint a new one`,
+        };
+    }
     const migrateBlocked = recordedIds[PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY];
     if (migrateBlocked) {
         return {
@@ -819,6 +1158,11 @@ function planAi(platform, recordedIds, executorBlocked) {
  * planned in this same plan: Archon's sign-in client is created inside it, so
  * the step could only throw.
  *
+ * #213: also puts {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF},
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF} and
+ * {@link PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF} as held keys, before
+ * the app deploys -- `putArchonMasterKeys` in `platform-providers.ts`.
+ *
  * #197: a recorded app with no recorded `cloudflared` connector
  * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
  * {@link planAuth} does.
@@ -831,6 +1175,13 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted)
         Boolean(recordedIds[PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY]) &&
         recordedIds[PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY] === platform.archon.hostname &&
         recordedIds[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY] === platform.archon.gitRef &&
+        // #211 round 4: a broker recreated under a new app id (the old one
+        // deleted by hand, or `platform:auth` minting a fresh one) leaves
+        // Archon's last registration on a broker that no longer exists, and
+        // nothing else here would ever plan the step again to redo it.
+        Boolean(recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY] ===
+            recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY] &&
         !recordedIds[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY];
     if (applied && !drifted)
         return { step: null, blocked: null };
@@ -857,7 +1208,9 @@ function planArchon(platform, recordedIds, executorBlocked, authReady, drifted)
                 desired: { hostname: platform.archon.hostname, gitRef: platform.archon.gitRef },
             },
             step: {
-                description: `provision Archon at ${platform.archon.hostname}`,
+                description: `provision Archon at ${platform.archon.hostname}, putting its master keys ` +
+                    `(${PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}, ${PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}, ` +
+                    `${PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF}) as held keys if they are not held yet`,
                 destroys: false,
                 migrates: false,
             },

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

@@ -4,8 +4,9 @@ import type { AgoraHostValues } from './agora.js';
  * https://github.com/wtfalch/foundry/issues/177: what an org step needs to
  * know about the platform it runs on -- whether each shared service it
  * depends on is enabled *and* applied (not just declared), and the one
- * address `coolify:mail`'s own step used to read as a literal
- * (`executor.ts`'s old `MAIL_APEX`/`MAIL_HOST` constants). Built by
+ * address `coolify:mail`'s own step used to read off two fixed, hand-built
+ * constants in `executor.ts` (removed for #205; `mailHost` below is what
+ * replaced them). Built by
  * {@link orgPlatformReadinessFrom} from the very `DeclaredPlatform` + applied
  * service ids `planPlatform` (`platform-diff.ts`) already reasons over -- the
  * same "declared vs applied" distinction every platform step already makes