@wtfalch/foundry 0.16.15 → 0.17.0

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

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, HostingEntry, OrgId } from '../org.js';
+import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
 import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
@@ -107,6 +107,17 @@ export declare const PLATFORM_ARCHON_KEY = "platform:archon";
  */
 export declare const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = "archon_applied_hostname";
 export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied_git_ref";
+/**
+ * #398: the integrations management key id Archon runs with, recorded by
+ * `provisionPlatformArchon` only after its deployment finished and its health
+ * check passed with that id in its env. `provisionPlatformIntegrations`'s
+ * rotation step reads this before dropping a previous key id from the
+ * runner's `MANAGEMENT_PUBLIC_KEYS`: the old key stays pinned until this
+ * matches the new id, so a request signed by an Archon container still
+ * running the old key is never refused. If Archon's deploy fails this stays
+ * unrecorded and the old key stays pinned.
+ */
+export declare const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = "archon_integrations_key_synced";
 /**
  * #211 round 4: the broker app id Archon last registered its entry with.
  * `provisionPlatformArchon` reads the broker to register with from
@@ -118,6 +129,19 @@ export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied
  * changed hostname or `gitRef` does.
  */
 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.
+ */
+export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applied_bootstrap_operator";
+/**
+ * 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).
+ */
+export declare function archonBootstrapOperator(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.
@@ -285,6 +309,20 @@ export declare const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = "coolify_platform
 export declare const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = "platform:master:coolify-url";
 export declare const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = "platform:master:coolify-token";
 export declare const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = "platform:master:cloudflare-token";
+/**
+ * #436: a Coolify API token scoped to `read` only, for Archon's own
+ * `/backups` page (`COOLIFY_URL`/`COOLIFY_READ_TOKEN`, Archon's
+ * `src/lib/backups/coolify.ts`) -- deliberately not
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}'s root token, which a
+ * read-only status page must never hold. Coolify's token UI has no API
+ * counterpart to create one (`@wtfalch/providers`'s `CoolifyClient` doc:
+ * "Keys & Tokens -> API tokens" only), so a human creates it in Coolify's
+ * console and holds it under this ref; `provisionPlatformArchon` only reads
+ * it back, and pushes nothing until it is held. `COOLIFY_URL` needs no ref
+ * of its own: it is not secret, and {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}
+ * already holds the same panel's address.
+ */
+export declare const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = "platform:archon:coolify-read-token";
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -400,14 +438,31 @@ export declare function appDomainsAppliedScopeKey(entryKey: string): string;
  * entry), so an app that runs today plans no change.
  */
 export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, entryKey: string): string[];
+/** Whether the secret sources can be filled right now: the mail key is held, and a new shared secret can be held. */
+export interface AppSecretAvailability {
+    platformMailKey: boolean;
+    sharedSecret: boolean;
+}
 /**
  * The entry's `env` values that have a value, in env-name order, and the env
  * names whose source has none yet. Shared by `planApp` and the executor's
  * `pushAppEnv` so both read the same recorded ids.
+ *
+ * A secret source is never a value here. `secrets` names each one that can be
+ * filled (`available`), `unresolvedSecrets` each that cannot, and `marker`
+ * is `values` plus a `secret:<source>` label per available secret: the JSON
+ * `coolifyApp` records as applied, so a declared change replans and no secret
+ * is written into it.
  */
-export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, available?: AppSecretAvailability): {
     values: Record<string, string>;
     unresolved: Array<[string, string]>;
+    secrets: Array<{
+        name: string;
+        source: 'platformMailKey' | EnvSharedSecret;
+    }>;
+    unresolvedSecrets: Array<[string, string]>;
+    marker: Record<string, string>;
 };
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
@@ -478,13 +533,6 @@ export declare const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = "ai_platform_migrat
  * that throws) is repaired by the next one.
  */
 export declare const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = "ai_platform_deploy_pending";
-/**
- * The Coolify deployment queued for the host (its `deployment_uuid`, or
- * `untracked` when the deploy answered none), set when that deploy is queued
- * and cleared once it finished. The mint waits for it, so a retry after a
- * failed wait still waits instead of minting against the old container.
- */
-export declare const PLATFORM_AI_RUNNER_DEPLOYMENT_SCOPE_KEY = "ai_platform_runner_deployment";
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -684,3 +732,49 @@ export declare const PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY = "integrations_man
 /** The hostname and gitRef the last successful apply put live; a difference from the declared ones plans the step again. */
 export declare const PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY = "integrations_applied_hostname";
 export declare const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = "integrations_applied_gitref";
+/**
+ * #398: the key id currently pinned on the runner as the active entry of
+ * `MANAGEMENT_PUBLIC_KEYS` -- `foundry-1` on the first mint, and whatever a
+ * rotation minted next after that. `collectArchonServiceInputs` reads this
+ * (falling back to the fixed `INTEGRATIONS_MANAGEMENT_KEY_ID` constant for a
+ * platform applied before this key existed) for Archon's own
+ * `INTEGRATIONS_MANAGEMENT_KEY_ID` env, so a rotated id reaches it without
+ * Archon's step needing to know anything happened on the integrations side.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY = "integrations_management_key_id";
+/**
+ * #398: the key id the runner was last deployed with in its
+ * `MANAGEMENT_PUBLIC_KEYS`, recorded by `provisionPlatformIntegrations` only
+ * after the runner's deployment finished. Archon is not moved to a new key id
+ * until this equals the active id, so Archon never signs with a key the
+ * running runner does not yet hold.
+ */
+export declare const PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY = "integrations_runner_keyring_deployed";
+/**
+ * #398: the same two-key discipline as
+ * {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}, for a rotation's
+ * new pair: recorded the moment it is minted, before delivery, and cleared
+ * by nothing -- {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} moving past it
+ * is what later runs read as "delivered and pinned", the same way the
+ * once-only mint's guard is a second key rather than removing the first.
+ * An id here that {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} has not
+ * caught up to means the pair may be lost or half-applied; the step reports
+ * it and mints no further pair.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY = "integrations_management_key_rotation_undelivered";
+/**
+ * #398: the previous key id, still pinned in `MANAGEMENT_PUBLIC_KEYS` beside
+ * the new one, pending removal -- set the moment the new pair is pinned
+ * beside it, and cleared (to `''`, the {@link PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY}
+ * convention for "was set, now isn't") once the previous id is actually
+ * removed from the keyring. Its presence is the overlap window: both keys
+ * verify a request while it holds.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = "integrations_management_key_rotation_previous";
+/**
+ * #398: how a rotation is requested. A person records any non-empty value
+ * under this scope key; `planIntegrations` then plans the step again and
+ * `provisionPlatformIntegrations` mints the new pair, clearing the key (to
+ * `''`) as soon as the mint is recorded, so one request is one rotation.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = "integrations_management_key_rotation_requested";

package/dist/plan/platform-diff.js

@@ -2,6 +2,7 @@ import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
 import { legacyAppHostname } from './hostnames.js';
+import { withStepSystem } from './step-system.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -127,6 +128,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';
+/**
+ * #398: the integrations management key id Archon runs with, recorded by
+ * `provisionPlatformArchon` only after its deployment finished and its health
+ * check passed with that id in its env. `provisionPlatformIntegrations`'s
+ * rotation step reads this before dropping a previous key id from the
+ * runner's `MANAGEMENT_PUBLIC_KEYS`: the old key stays pinned until this
+ * matches the new id, so a request signed by an Archon container still
+ * running the old key is never refused. If Archon's deploy fails this stays
+ * unrecorded and the old key stays pinned.
+ */
+export const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = 'archon_integrations_key_synced';
 /**
  * #211 round 4: the broker app id Archon last registered its entry with.
  * `provisionPlatformArchon` reads the broker to register with from
@@ -138,6 +150,22 @@ export const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = 'archon_applied_git_ref
  * changed hostname or `gitRef` does.
  */
 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.
+ */
+export const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = 'archon_applied_bootstrap_operator';
+/**
+ * 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).
+ */
+export function archonBootstrapOperator(recorded) {
+    const id = recorded[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY];
+    return id && id !== 'none' ? id : 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.
@@ -316,6 +344,20 @@ export const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = 'coolify_platform_archon_
 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';
+/**
+ * #436: a Coolify API token scoped to `read` only, for Archon's own
+ * `/backups` page (`COOLIFY_URL`/`COOLIFY_READ_TOKEN`, Archon's
+ * `src/lib/backups/coolify.ts`) -- deliberately not
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF}'s root token, which a
+ * read-only status page must never hold. Coolify's token UI has no API
+ * counterpart to create one (`@wtfalch/providers`'s `CoolifyClient` doc:
+ * "Keys & Tokens -> API tokens" only), so a human creates it in Coolify's
+ * console and holds it under this ref; `provisionPlatformArchon` only reads
+ * it back, and pushes nothing until it is held. `COOLIFY_URL` needs no ref
+ * of its own: it is not secret, and {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF}
+ * already holds the same panel's address.
+ */
+export const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = 'platform:archon:coolify-read-token';
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -448,8 +490,14 @@ export function appliedAppDomains(org, recorded, entryKey) {
  * The entry's `env` values that have a value, in env-name order, and the env
  * names whose source has none yet. Shared by `planApp` and the executor's
  * `pushAppEnv` so both read the same recorded ids.
+ *
+ * A secret source is never a value here. `secrets` names each one that can be
+ * filled (`available`), `unresolvedSecrets` each that cannot, and `marker`
+ * is `values` plus a `secret:<source>` label per available secret: the JSON
+ * `coolifyApp` records as applied, so a declared change replans and no secret
+ * is written into it.
  */
-export function resolveAppEnv(org, entry, recorded) {
+export function resolveAppEnv(org, entry, recorded, available = { platformMailKey: false, sharedSecret: false }) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -457,14 +505,38 @@ export function resolveAppEnv(org, entry, recorded) {
     };
     const values = {};
     const unresolved = [];
+    const secrets = [];
+    const unresolvedSecrets = [];
+    const marker = {};
     for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        if (typeof declared !== 'string' && declared.from === 'platformMailKey') {
+            if (available.platformMailKey) {
+                secrets.push({ name, source: 'platformMailKey' });
+                marker[name] = 'secret:platformMailKey';
+            }
+            else
+                unresolvedSecrets.push([name, 'platformMailKey']);
+            continue;
+        }
+        if (typeof declared !== 'string' && declared.from === 'sharedSecret') {
+            const label = `sharedSecret ${declared.name}`;
+            if (available.sharedSecret) {
+                secrets.push({ name, source: declared });
+                marker[name] = `secret:sharedSecret:${declared.name}`;
+            }
+            else
+                unresolvedSecrets.push([name, label]);
+            continue;
+        }
         const value = typeof declared === 'string' ? declared : sources[declared.from];
-        if (value)
+        if (value) {
             values[name] = value;
+            marker[name] = value;
+        }
         else if (typeof declared !== 'string')
             unresolved.push([name, declared.from]);
     }
-    return { values, unresolved };
+    return { values, unresolved, secrets, unresolvedSecrets, marker };
 }
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
@@ -535,13 +607,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';
-/**
- * The Coolify deployment queued for the host (its `deployment_uuid`, or
- * `untracked` when the deploy answered none), set when that deploy is queued
- * and cleared once it finished. The mint waits for it, so a retry after a
- * failed wait still waits instead of minting against the old container.
- */
-export const PLATFORM_AI_RUNNER_DEPLOYMENT_SCOPE_KEY = 'ai_platform_runner_deployment';
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -715,8 +780,19 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
+    // #398: the old integrations key stays pinned until Archon holds the new
+    // id; name that when Archon is what is stopping it.
+    if (archon.blocked &&
+        recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY] &&
+        recordedIds[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY] !==
+            recordedIds[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY]) {
+        unmanaged.push({
+            description: `the previous integrations management key ${recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY]} stays pinned on the runner until Archon is redeployed with the new key, and Archon is blocked (see above)`,
+            key: 'integrations',
+        });
+    }
     unmanaged.push(...backups.blocked);
-    return { plannedSteps, unmanaged, versionChanges };
+    return { plannedSteps: plannedSteps.map(withStepSystem), unmanaged, versionChanges };
 }
 /**
  * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
@@ -1344,6 +1420,52 @@ export const PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY = 'integrations_management_
 /** The hostname and gitRef the last successful apply put live; a difference from the declared ones plans the step again. */
 export const PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY = 'integrations_applied_hostname';
 export const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = 'integrations_applied_gitref';
+/**
+ * #398: the key id currently pinned on the runner as the active entry of
+ * `MANAGEMENT_PUBLIC_KEYS` -- `foundry-1` on the first mint, and whatever a
+ * rotation minted next after that. `collectArchonServiceInputs` reads this
+ * (falling back to the fixed `INTEGRATIONS_MANAGEMENT_KEY_ID` constant for a
+ * platform applied before this key existed) for Archon's own
+ * `INTEGRATIONS_MANAGEMENT_KEY_ID` env, so a rotated id reaches it without
+ * Archon's step needing to know anything happened on the integrations side.
+ */
+export const PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY = 'integrations_management_key_id';
+/**
+ * #398: the key id the runner was last deployed with in its
+ * `MANAGEMENT_PUBLIC_KEYS`, recorded by `provisionPlatformIntegrations` only
+ * after the runner's deployment finished. Archon is not moved to a new key id
+ * until this equals the active id, so Archon never signs with a key the
+ * running runner does not yet hold.
+ */
+export const PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY = 'integrations_runner_keyring_deployed';
+/**
+ * #398: the same two-key discipline as
+ * {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}, for a rotation's
+ * new pair: recorded the moment it is minted, before delivery, and cleared
+ * by nothing -- {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} moving past it
+ * is what later runs read as "delivered and pinned", the same way the
+ * once-only mint's guard is a second key rather than removing the first.
+ * An id here that {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} has not
+ * caught up to means the pair may be lost or half-applied; the step reports
+ * it and mints no further pair.
+ */
+export const PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY = 'integrations_management_key_rotation_undelivered';
+/**
+ * #398: the previous key id, still pinned in `MANAGEMENT_PUBLIC_KEYS` beside
+ * the new one, pending removal -- set the moment the new pair is pinned
+ * beside it, and cleared (to `''`, the {@link PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY}
+ * convention for "was set, now isn't") once the previous id is actually
+ * removed from the keyring. Its presence is the overlap window: both keys
+ * verify a request while it holds.
+ */
+export const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = 'integrations_management_key_rotation_previous';
+/**
+ * #398: how a rotation is requested. A person records any non-empty value
+ * under this scope key; `planIntegrations` then plans the step again and
+ * `provisionPlatformIntegrations` mints the new pair, clearing the key (to
+ * `''`) as soon as the mint is recorded, so one request is one rotation.
+ */
+export const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = 'integrations_management_key_rotation_requested';
 /**
  * #174: the integrations host (https://github.com/wtfalch/integrations) -- its
  * migrate job, web app and queue worker, their shared database, and its
@@ -1360,6 +1482,13 @@ export const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = 'integrations_appl
  * Blocked, not planned: an undelivered key, and an executor that cannot run
  * the step (no integrations dependencies, or no `@wtfalch/keys` values for
  * the host).
+ *
+ * #398: a rotation (see {@link PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY})
+ * or one still pending removal of the previous key
+ * ({@link PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY}) plans the
+ * step again even when `applied`. A rotation whose new pair is minted but
+ * not confirmed delivered is blocked, never planned: the step would throw
+ * on every apply.
  */
 function planIntegrations(platform, recordedIds, executorBlocked) {
     if (!platform.integrations.enabled)
@@ -1368,7 +1497,41 @@ function planIntegrations(platform, recordedIds, executorBlocked) {
     const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_INTEGRATIONS_KEY)]) &&
         recordedIds[PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY] === hostname &&
         recordedIds[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY] === gitRef;
-    if (applied)
+    const keyId = recordedIds[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY];
+    const previous = recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY];
+    const keySet = Boolean(recordedIds[PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY]);
+    // #398: a rotation key minted but not confirmed delivered and pinned blocks
+    // the step whatever else is recorded: the executor throws on it, and
+    // Archon's env refuses to pair the held key with an older id.
+    const rotationUndelivered = recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY];
+    if (rotationUndelivered && rotationUndelivered !== keyId) {
+        return {
+            step: null,
+            blocked: `the integrations host is blocked, not planned: rotation key ${rotationUndelivered} was minted but not confirmed delivered and pinned; check the held key and the runner's MANAGEMENT_PUBLIC_KEYS, then remove the recorded key ${PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY} and set ${PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY} again to mint a new one`,
+        };
+    }
+    // A request counts only once the first key is minted and no earlier
+    // rotation is waiting to drop its previous key.
+    const requested = Boolean(recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY]) &&
+        keySet &&
+        !previous;
+    const requestIgnored = Boolean(recordedIds[PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY]) && !requested;
+    // The previous key is dropped once Archon holds the new id, or at once when
+    // Archon is not enabled (nothing else holds the old key). While Archon has
+    // not synced there is nothing for this step to do.
+    // Mirrors the executor's drop guards: the previous id is not the active
+    // one, and the last delivered mint is the active one.
+    const dropReady = Boolean(previous) &&
+        previous !== keyId &&
+        rotationUndelivered === keyId &&
+        (!platform.archon.enabled ||
+            recordedIds[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY] === keyId);
+    // The runner has not been deployed with the active key id yet (a deploy
+    // failed after the key was pinned): plan the step to deploy it.
+    const runnerStale = Boolean(keyId) &&
+        recordedIds[PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY] !== keyId;
+    const rotating = requested || dropReady || runnerStale;
+    if (applied && !rotating)
         return { step: null, blocked: null };
     const undelivered = recordedIds[PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY];
     if (undelivered && !recordedIds[PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY]) {
@@ -1388,7 +1551,9 @@ function planIntegrations(platform, recordedIds, executorBlocked) {
                 desired: { hostname, gitRef },
             },
             step: {
-                description: `provision the integrations host at ${hostname}`,
+                description: `provision the integrations host at ${hostname}${requestIgnored
+                    ? `; the recorded rotation request ${PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY} is ignored and cleared (no key minted yet, or the previous key ${previous ?? ''} is still pending removal); set it again afterwards`
+                    : ''}`,
                 destroys: false,
                 migrates: false,
             },
@@ -1613,7 +1778,20 @@ 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_GATE_CLOSED_SCOPE_KEY];
+        (recordedIds[PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY] ?? 'none') ===
+            (archonBootstrapOperator(recordedIds) ?? 'none') &&
+        !recordedIds[PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY] &&
+        // #398: a rotated integrations key id Archon's env was not yet written
+        // with (see PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY). Absent
+        // before the first rotation on a platform applied before #398.
+        // Only while integrations is enabled, and only once the runner is deployed
+        // with that id (PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY).
+        (!platform.integrations.enabled ||
+            !recordedIds[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY] ||
+            recordedIds[PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY] !==
+                recordedIds[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY] ||
+            recordedIds[PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY] ===
+                recordedIds[PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY]);
     if (applied && !drifted)
         return { step: null, blocked: null };
     if (!platform.auth.enabled) {

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

@@ -1,5 +1,21 @@
 import type { DeclaredPlatform } from '../platform.js';
 import type { AgoraHostValues } from './agora.js';
+/**
+ * #443: the no-domain company mail apex -- `<slug>.oikos.host`, the same
+ * fixed suffix `agora.ts`'s `agoraHostnameFor`, `boule.ts`'s
+ * `bouleHostnameFor` and `hostnames.ts`'s own `<slug>.oikos.host` already
+ * use for a level-1 org's hostnames. `OrgPlatformReadiness.mailHost.apex`
+ * used to be `platform.apex` (the platform's own brand apex, e.g.
+ * `companyincluded.com`), which gave a domainless org `slug@companyincluded.com`
+ * instead of the settled `slug@oikos.host` contract
+ * (`@wtfalch/email`'s `org-mail.ts`'s `resolveDomain` is the only reader of
+ * this `apex`, for a level-1 org alone -- a with-domain org returns
+ * `org.domain` and never looks at it). `mailHost` itself (the MX server's own
+ * hostname, `platformMailMxHost(platform.apex)`) is unaffected: the shared
+ * mail server stays the platform's own, whichever apex a mailbox's address
+ * uses.
+ */
+export declare const NO_DOMAIN_MAIL_APEX = "oikos.host";
 /**
  * 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
@@ -68,6 +84,13 @@ export interface OrgPlatformReadiness {
         ai: string | null;
         jobs: string | null;
     };
+    /**
+     * The platform's Lettermint key (`PLATFORM_AUTH_BROKER_MAIL_KEY_REF`) is held,
+     * so an entry env from `platformMailKey` can be filled. Absent reads as not held.
+     */
+    mailKeyHeld?: boolean;
+    /** The host's held keys can `put`, so an entry env from `sharedSecret` can be filled. Absent reads as false. */
+    canHoldSecrets?: boolean;
     /**
      * True when the host wired no held-keys reader, so no key could be checked.
      * A missing key is then reported as "no reader given" instead of "not held".
@@ -91,6 +114,8 @@ export declare const ORG_PLATFORM_KEY_REFS: {
 /** The one method of Archon's held keys this package reads. A value is returned to the caller and never logged, recorded or put in a plan. */
 export interface HeldKeyResolver {
     resolve(ref: string): Promise<string | null | undefined>;
+    /** Holds a value under `ref`; only the org steps' shared secrets need it. */
+    put?(ref: string, value: string): Promise<void>;
 }
 /**
  * Which of {@link ORG_PLATFORM_KEY_REFS} `heldKeys` can resolve right now. A

package/dist/plan/platform-org.js

@@ -1,5 +1,21 @@
 import { JOBS_SCHEDULER_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, platformMailMxHost, } from './platform-diff.js';
 import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+/**
+ * #443: the no-domain company mail apex -- `<slug>.oikos.host`, the same
+ * fixed suffix `agora.ts`'s `agoraHostnameFor`, `boule.ts`'s
+ * `bouleHostnameFor` and `hostnames.ts`'s own `<slug>.oikos.host` already
+ * use for a level-1 org's hostnames. `OrgPlatformReadiness.mailHost.apex`
+ * used to be `platform.apex` (the platform's own brand apex, e.g.
+ * `companyincluded.com`), which gave a domainless org `slug@companyincluded.com`
+ * instead of the settled `slug@oikos.host` contract
+ * (`@wtfalch/email`'s `org-mail.ts`'s `resolveDomain` is the only reader of
+ * this `apex`, for a level-1 org alone -- a with-domain org returns
+ * `org.domain` and never looks at it). `mailHost` itself (the MX server's own
+ * hostname, `platformMailMxHost(platform.apex)`) is unaffected: the shared
+ * mail server stays the platform's own, whichever apex a mailbox's address
+ * uses.
+ */
+export const NO_DOMAIN_MAIL_APEX = 'oikos.host';
 /**
  * What an org's plan reads when no platform is declared: nothing is ready, so
  * every org step that depends on a platform service is blocked (#177). A host
@@ -73,7 +89,7 @@ noKeyReader = false) {
     };
     return {
         mailHost: mailApplied
-            ? { apex: platform.apex, mailHost: platformMailMxHost(platform.apex) }
+            ? { apex: NO_DOMAIN_MAIL_APEX, mailHost: platformMailMxHost(platform.apex) }
             : null,
         filesReady: filesApplied && missingKeys.files === null,
         filesUrl: filesApplied

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

@@ -1,4 +1,5 @@
 import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
+import type { DeclaredOrg } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { DeclaredOrgStore, PlatformStore } from '../store.js';
 import type { StepAction } from './diff.js';
@@ -243,6 +244,13 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         backupStorage?: boolean;
         backupStorageBlocked?: string;
     }>;
+    /**
+     * Gives the files runner a changed share-domain set and nothing else: its
+     * Coolify `domains`, `FILES_PUBLIC_HOSTS` and one redeploy of the runner.
+     * Returns the scope ids to record, or `null` when nothing changed
+     * (or the runner was never applied).
+     */
+    refreshFilesShare(_platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<Record<string, string> | null>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
@@ -357,7 +365,7 @@ export declare function defaultStalwartForInstance(input: {
  * own shape.
  */
 export interface PlatformMailDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'raw' | 'listStorages' | 'createPersistentStorage' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'raw' | 'listStorages' | 'createPersistentStorage' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait'>;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
     /**
      * Must target the platform's own ZITADEL instance, or `zitadelForInstance`
@@ -401,7 +409,7 @@ export interface PlatformMailRuntime {
  * {@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' | 'updateApplication' | 'deploy'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait'>;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord' | 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
     /** Must target the platform's own ZITADEL instance, or `zitadelForInstance` must be set. */
     zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createOidcApp' | 'listApps' | 'deleteApp'>;
@@ -447,6 +455,17 @@ export interface PlatformArchonDeps {
         coolifyToken: string;
         cloudflareParentToken: string;
     };
+    /** Clock, sleep and fetch for the post-deploy health wait (#252); real ones by default. */
+    runtime?: PlatformArchonRuntime;
+}
+export interface PlatformArchonRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for `/api/health` to answer the new deploy (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
 }
 /**
  * The name of foundry's own Cloudflare Access app in front of Archon. Same
@@ -562,7 +581,7 @@ export declare class AiManagementKeyUntrustedError extends Error {
 }
 /** #172: everything {@link provisionPlatformAi} needs beyond {@link PlatformStepExecutionContext}. */
 export interface PlatformAiDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
     /**
      * Reads back a secret this step delivered on an earlier apply -- needed
@@ -690,7 +709,7 @@ export declare function brokerDeployRecordValue(brokerAppId: string, authAppsRaw
  * {@link PlatformAuthDeps}.
  */
 export interface PlatformFilesDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
     /**
      * Must target the platform's own sign-in (the instance `platform:auth`
      * built), or {@link zitadelForInstance} must be set.
@@ -799,7 +818,7 @@ export declare const FILES_INTROSPECTION_SECRET_REF = "zitadel:platform:files:in
  * {@link FoundryPlatformStepExecutor} keeps compiling with it omitted.
  */
 export interface PlatformIntegrationsDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'updateApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'raw'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'updateApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'raw'>;
     /** Hands the management private key to the host, once (`FoundryStepExecutorPorts.deliverSecret`'s contract). */
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
     /**
@@ -898,4 +917,18 @@ export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyRe
     constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
+/** Scope id (no `:`): the share domains the runner's Coolify `domains` was last set to, comma-joined. */
+export declare const PLATFORM_FILES_SHARE_DOMAINS_SCOPE_KEY = "platform_files_share_domains";
+/**
+ * The runner's `FILES_PUBLIC_HOSTS`: the host-supplied `publicHosts` first, in
+ * their given order, then the share domains sorted, with no host twice.
+ * Empty when there is neither.
+ */
+export declare function filesPublicHostsValue(publicHosts: string | undefined, shareDomains: readonly string[] | undefined): string;
+/**
+ * The share domain of every org that has a domain and an entry declaring
+ * `uses.files.shareHost`: `share.<domain>`. The platform files step derives it
+ * from the declared orgs, for its apply and its drift check alike.
+ */
+export declare function filesShareDomains(orgs: readonly DeclaredOrg[]): string[];
 export {};