@wtfalch/foundry 0.8.0 → 0.10.0

package/dist/plan/platform-diff.js

@@ -1,5 +1,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';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -136,6 +138,10 @@ export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_a
 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';
+/** #283: the created instance's id, recorded once its owner token is delivered. */
+export const PLATFORM_AUTH_INSTANCE_SCOPE_KEY = 'zitadel_platform_instance_id';
+/** #283: an instance that may exist without a delivered owner token; blocks creating another. */
+export const PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_instance_undelivered';
 /**
  * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
  * for the login app and the broker, mirroring
@@ -343,24 +349,78 @@ export function platformMailMxHost(apex) {
 export const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = 'mail_applied_apex';
 export const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = 'mail_applied_host';
 /**
- * #243: the org's `hosting.appEnv` values the last `coolify:app` apply pushed,
+ * The key of a hosting entry in a `coolify:app` or `cloudflare:access` step
+ * and in the ids recorded for it: `<orgId>:<entry key>`, so a second entry
+ * cannot collide with the first.
+ */
+export function appStepKey(org, entryKey = APP_ENTRY_KEY) {
+    return `${org.id}:${entryKey}`;
+}
+/**
+ * The Coolify name of a hosting entry's app: `<slug>` for the `app` entry, so
+ * the move to a list finds the app that runs today, `<slug>-<key>` for any
+ * other.
+ */
+export function appNameFor(org, entry) {
+    return entry.key === APP_ENTRY_KEY ? org.slug : `${org.slug}-${entry.key}`;
+}
+/**
+ * #243: the entry's `env` values the last `coolify:app` apply pushed,
  * recorded as one JSON object (env name to value; ids and a domain, never a
  * secret). `planApp` plans the step again when {@link resolveAppEnv} differs
- * from it, so a changed map reaches an app that is already live.
+ * from it, so a changed map reaches an app that is already live. The `.<key>`
+ * suffix is the entry key; a scope key holds no `:`, so `storeRecordedIds`
+ * still filters it out.
  */
-export const APP_ENV_APPLIED_SCOPE_KEY = 'app_env_applied';
+export function appEnvAppliedScopeKey(entryKey) {
+    return `app_env_applied.${entryKey}`;
+}
 /**
  * #239: set to '1' once an app has been restarted after its database URLs
  * were pushed. Not a URL. Without it a crash between the push and the restart
  * would leave a stale container that no plan notices.
  */
-export const DB_ENV_APPLIED_SCOPE_KEY = 'db_env_applied';
+export function dbEnvAppliedScopeKey(entryKey) {
+    return `db_env_applied.${entryKey}`;
+}
+export function appSettingsOf(entry) {
+    return { folder: entry.folder, port: entry.port, autoDeploy: entry.autoDeploy };
+}
+/** What an app that predates the marker has: Coolify's own defaults, so it plans no change. */
+export const DEFAULT_APP_SETTINGS = { folder: null, port: null, autoDeploy: true };
+export function appSettingsAppliedScopeKey(entryKey) {
+    return `app_settings_applied.${entryKey}`;
+}
+/** The settings the app has: the marker, or the defaults when there is none. */
+export function appliedAppSettings(recorded, entryKey) {
+    const marker = recorded[appSettingsAppliedScopeKey(entryKey)];
+    return marker ? JSON.parse(marker) : DEFAULT_APP_SETTINGS;
+}
+/**
+ * The names `coolifyApp` last put in the entry's Coolify `domains`, as a JSON
+ * array (`[]` for an internal entry). `planApp` plans the step again, with a
+ * redeploy, when {@link entryHostnames} differs from it.
+ */
+export function appDomainsAppliedScopeKey(entryKey) {
+    return `app_domains_applied.${entryKey}`;
+}
+/**
+ * The names the app has: the marker, or for an app that predates it the one
+ * name it was created with (the `app` entry's address, nothing for any other
+ * entry), so an app that runs today plans no change.
+ */
+export function appliedAppDomains(org, recorded, entryKey) {
+    const marker = recorded[appDomainsAppliedScopeKey(entryKey)];
+    if (marker)
+        return JSON.parse(marker);
+    return entryKey === APP_ENTRY_KEY ? [legacyAppHostname(org)] : [];
+}
 /**
- * The `hosting.appEnv` entries whose source has a recorded 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.
+ * 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.
  */
-export function resolveAppEnv(org, recorded) {
+export function resolveAppEnv(org, entry, recorded) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -368,12 +428,12 @@ export function resolveAppEnv(org, recorded) {
     };
     const values = {};
     const unresolved = [];
-    for (const [name, source] of Object.entries(org.hosting.appEnv).sort(([a], [b]) => a < b ? -1 : 1)) {
-        const value = sources[source];
+    for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const value = typeof declared === 'string' ? declared : sources[declared.from];
         if (value)
             values[name] = value;
-        else
-            unresolved.push([name, source]);
+        else if (typeof declared !== 'string')
+            unresolved.push([name, declared.from]);
     }
     return { values, unresolved };
 }
@@ -561,7 +621,7 @@ export function planPlatform(platform, live, options = {}) {
         plannedSteps.push(archon.step);
     // #257: after every service above, so a database any of them just
     // recorded is already visible to `recordedIds` on this same plan.
-    const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false);
+    const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false, drifted.backupStorage ?? false, drifted.backupStorageBlocked);
     plannedSteps.push(...backups.steps);
     // #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).
@@ -763,15 +823,36 @@ export const PLATFORM_BACKUP_SERVICE_KEYS = [
  * Once a step's own `coolify:backup:<service>` resource is live, it is
  * claimed and never re-planned: like every other provision-only step here,
  * there is no park branch for a backup already scheduled.
+ *
+ * #257 fix round 2: that "claimed, never re-planned" rule is exactly why a
+ * rotated R2 credential would otherwise never reach Coolify again once every
+ * service's own backup is live -- nothing left in this loop ever calls
+ * `ensurePlatformBackupStorage` (`platform-providers.ts`) again. `storageDrifted`
+ * (the host's own `driftedSteps`, read fresh each plan) is the signal that
+ * self-heal is needed; when it is true, this plans exactly one extra
+ * `coolify:backup-storage:platform` step, independent of every per-service
+ * step's own claimed status, so the self-heal runs again whether or not any
+ * service step is also being (re)planned this round. It is never itself
+ * "claimed" against a live resource -- there is nothing to read live for a
+ * storage push, only to react to -- so it simply stops being planned the
+ * moment `storageDrifted` goes false again.
+ *
+ * #257 fix round 4, point 4: `storageBlocked`, when set, means the host's own
+ * `driftedSteps` could not even tell whether the storage is drifted (a
+ * Coolify read failed) -- reported in `blocked` instead of planning the
+ * self-heal step, so a persistent failure is visible in the plan rather than
+ * only logged and retried silently forever.
  */
-function planBackups(byKey, claimed, recordedIds, executorMissing) {
+function planBackups(byKey, claimed, recordedIds, executorMissing, storageDrifted, storageBlocked) {
     const steps = [];
     const blocked = [];
+    let anyDatabase = false;
     for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
         const key = resourceKey('coolify', 'backup', service);
         const live = byKey.get(key);
         if (live) {
             claimed.add(key);
+            anyDatabase = true;
             continue;
         }
         // No database yet is not reported: unlike a Coolify reader or a backup
@@ -783,6 +864,7 @@ function planBackups(byKey, claimed, recordedIds, executorMissing) {
         const databaseId = recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]];
         if (!databaseId)
             continue;
+        anyDatabase = true;
         if (executorMissing) {
             blocked.push({
                 description: `platform:backup:${service} is blocked, not planned: the host built the platform executor without its backup dependencies`,
@@ -804,6 +886,33 @@ function planBackups(byKey, claimed, recordedIds, executorMissing) {
             },
         });
     }
+    // #257 fix round 4, point 4: a blocked liveness check is reported instead
+    // of planning the self-heal step -- there is nothing to push until the
+    // read itself works again.
+    if (!executorMissing && storageBlocked && anyDatabase) {
+        blocked.push({ description: storageBlocked, key: 'backup-storage' });
+    }
+    else if (
+    // #257 fix round 2: same "nothing to report yet" gate every other branch
+    // above follows -- a platform with no database yet has no storage to
+    // self-heal either, whatever a stale `storageDrifted` reading says.
+    !executorMissing &&
+        storageDrifted &&
+        anyDatabase) {
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup-storage',
+                key: 'platform',
+                desired: {},
+            },
+            step: {
+                description: "self-heal the platform's R2 backup storage registered with Coolify (a rotated credential or a changed bucket/endpoint)",
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
     return { steps, blocked };
 }
 /**
@@ -999,6 +1108,16 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
             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`,
         };
     }
+    // #283: an instance may exist whose owner token never reached the host.
+    const instanceLost = recordedIds[PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY];
+    if (instanceLost &&
+        !recordedIds[PLATFORM_AUTH_INSTANCE_SCOPE_KEY] &&
+        !recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's sign-in is blocked, not planned: a ZITADEL instance (${instanceLost}) may exist without a delivered owner token; delete it with the system API (DELETE /system/v1/instances/{id}) or redeploy the ZITADEL database, then remove the recorded key ${PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY}`,
+        };
+    }
     // #211 round 6: the executor itself is unusable on this host -- nothing to
     // plan, whatever the broker's recorded state says.
     if (executorMissing)

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

@@ -5,6 +5,7 @@ import type { StepAction } from './diff.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import type { PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
+import { type BrokerDeployRecord } from './platform-diff.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 /**
  * #168: everything {@link provisionPlatformAuth} needs beyond
@@ -206,6 +207,8 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
         auth?: boolean;
+        backupStorage?: boolean;
+        backupStorageBlocked?: string;
     }>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
@@ -223,6 +226,13 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private executeSfu;
     private coolifyJobs;
 }
+/**
+ * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
+ * delivered under, once. A host reads it back to build `zitadelForInstance`
+ * (see {@link provisionPlatformAuth}'s doc comment). Distinct from the admin
+ * key delivered under `zitadel:platform:admin`.
+ */
+export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:instanceBearer";
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,
@@ -361,6 +371,40 @@ export declare const PLATFORM_ARCHON_ACCESS_APP_NAME = "foundry:platform:archon"
 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";
+/**
+ * One `AUTH_APPS` entry, read back. Only the fields this step itself reads or
+ * writes are named; every other field `wtfalch/auth/broker/src/apps.ts`'s
+ * `App` knows about (`from`, `productName`, `locale`, `registration`,
+ * `emailLink`) rides along unnamed through the index signature, so merging an
+ * entry (see `provisionPlatformArchon`) never has to know the broker's full
+ * shape to avoid dropping a field it does not itself set.
+ */
+type BrokerAppEntry = Record<string, unknown> & {
+    organizationId: string;
+    key: string;
+    name: string;
+    clientIds: string[];
+    origins: string[];
+};
+/**
+ * One `AUTH_APPS[index]` entry, checked the way
+ * `wtfalch/auth/broker/src/apps.ts`'s own `parseApps`/`parseAppFields`
+ * (https://github.com/wtfalch/auth/blob/main/broker/src/apps.ts) check it at
+ * boot, in the same order: a `key` of at least 32 characters and a non-empty
+ * `organizationId`; a `name` that passes the broker's own `isSafeText` rule
+ * (#218); a `productName`, when present, that is a string and also passes it
+ * (#218); a `from` that passes {@link isValidSenderFrom}; a `locale` of
+ * `'en'` or `'nb'` when present; non-blank `clientIds`; and `origins` each in
+ * {@link isCanonicalOrigin} form. #211 round 2: on a bad
+ * entry this throws naming the broker app id and the entry's index, never
+ * the value -- `key` may hold another organisation's secret, and even
+ * `organizationId`/`name` are not this step's to print in an error only an
+ * operator reads. `entry` may be anything at all (`null`, a string, an
+ * array): every check below is a `typeof`/`Array.isArray` guard first, so a
+ * malformed entry never reaches a property read on a non-object and throws a
+ * `TypeError` instead of this named error.
+ */
+export declare function validateBrokerAppEntry(entry: unknown, brokerAppId: string, index: number): BrokerAppEntry;
 /**
  * #172/#201: mints Archon's own AI management key -- the plain bearer key
  * (`wtfk_...`) `AiOrganisationPort` (`executor.ts`) authenticates with,
@@ -493,6 +537,51 @@ export declare function createAiManagementKeyMinter(options: {
     fetchImpl?: typeof fetch;
     now?: () => number;
 }): AiManagementKeyMinter;
+/**
+ * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
+ * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
+ * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
+ * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
+ * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
+ * recorded scope id: whichever of #209/#210 lands first (or a human, setting
+ * either directly on the app) is enough to clear that one input, in either
+ * order, with no coupling to this step's own execution.
+ *
+ * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
+ * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array
+ * (`wtfalch/auth/broker/src/apps.ts`), and this check used to name only the
+ * other two, so a deploy could go ahead with a broker that still would not
+ * come up. Also treat `null`/`undefined` as missing, not only `''`: the
+ * `CoolifyPort.listEnvs` doc comment already warns a live value does not
+ * always match its declared `string` type.
+ */
+export declare function missingBrokerInputs(coolify: Pick<CoolifyPort, 'listEnvs'>, brokerAppId: string): Promise<string[]>;
+/**
+ * #211 round 5: the one rule `provisionPlatformAuth` and
+ * `provisionPlatformArchon` both call to decide whether the broker needs a
+ * (re)deploy -- replacing the two ad hoc "was it ever ostensibly deployed"
+ * booleans each function used to keep, which is what let a recreated broker,
+ * and a crash between writing `AUTH_APPS` and deploying, both go unnoticed
+ * (the round 5 issue text's own diagnosis: "they share one cause"). `false`
+ * while any required input is still missing -- deploying a broker that
+ * cannot start is pointless regardless of what changed. Otherwise `true`
+ * when nothing has ever been recorded, when the broker that was deployed is
+ * a different app (recreated under a new id), or when the `AUTH_APPS` that
+ * was deployed is not the `AUTH_APPS` that is live/about-to-be-live now.
+ * `authAppsRaw` is that exact string -- read live by `provisionPlatformAuth`,
+ * which never writes `AUTH_APPS` itself, or supplied by
+ * `provisionPlatformArchon` as the string it already knows it just wrote (or
+ * left unchanged), so neither caller needs a second read to agree with
+ * itself about what is now true of the app.
+ */
+export declare function brokerDeployNeeded(missingInputs: readonly string[], brokerAppId: string, authAppsRaw: string | undefined, recordedDeploy: BrokerDeployRecord | null): boolean;
+/**
+ * #211 round 5: the {@link BrokerDeployRecord} JSON a successful deploy
+ * writes under {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} (via each
+ * caller's own `record()`), replacing the plain broker-id string round 2-4
+ * wrote there. Paired with {@link brokerDeployNeeded}, which reads it back.
+ */
+export declare function brokerDeployRecordValue(brokerAppId: string, authAppsRaw: string | undefined): string;
 /**
  * #171: everything {@link provisionPlatformFiles} needs beyond
  * {@link PlatformStepExecutionContext}, bundled for the same reason as
@@ -600,10 +689,21 @@ export declare const INTEGRATIONS_MANAGEMENT_KEY_ID = "foundry-1";
  * platform database's dump lands in. A person creates or confirms the
  * bucket and these credentials by hand (the issue's own "Human steps"); this
  * package only ever registers the bucket with Coolify and schedules the
- * dump, never creates or reads the bucket itself.
+ * dump, never creates or reads the bucket itself. `raw` carries the S3
+ * storage update call, `PATCH /s3-storages/{uuid}` -- checked against the
+ * same live Coolify 4.3.8 instance `@wtfalch/providers`' own CLAUDE.md
+ * records as the last version this estate verified its `{uuid}` routes
+ * against (that package's own "Known traps": the bundled `openapi.yaml`
+ * omits every one of them, so `routes/api.php`-level comments are what to
+ * trust). `raw` also carries the schedule-repoint call (#257 fix round 3),
+ * `PATCH /databases/{uuid}/backups/{backup_uuid}`, documented in Coolify's
+ * public API reference ("Update database backup") as taking an
+ * `s3_storage_uuid` field. `CoolifyPort` has not wrapped either route with a
+ * typed method, so both go through the same `raw` escape hatch `coolifyApp`'s
+ * own stop/start calls use for a REST route the port has not wrapped yet.
  */
 export interface PlatformBackupDeps {
-    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup'>;
+    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup' | 'raw'>;
     r2: {
         endpoint: string;
         bucket: string;