@wtfalch/foundry 0.14.0 → 0.16.0

package/dist/plan/entry-ai-key.js

@@ -0,0 +1,209 @@
+import { AI_ENTRY_PERMISSIONS } from '../org.js';
+import { entryHostnames } from './hostnames.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * F6a: one ai key per entry with `uses.ai`, minted below the org's own ai key
+ * (`ai:key:<orgId>`), delivered into that entry's env and nowhere else.
+ */
+/** How long an entry's key lives. ai refuses more than 365 and anything past its minter's own expiry. */
+export const AI_ENTRY_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export const AI_ENTRY_RENEW_WINDOW_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Flat scope ids (no `:`) per entry. Entry keys hold neither `:` nor `.`. */
+export const entryAiUndeliveredScopeKey = (entryKey) => `ai_key_undelivered_${entryKey}`;
+/** The ISO time the entry's live key expires. */
+export const entryAiExpiresScopeKey = (entryKey) => `ai_key_expires_${entryKey}`;
+/** What the last apply wrote: permissions, offerings, webhook address, ai address. Never a secret. */
+export const entryAiAppliedScopeKey = (entryKey) => `ai_key_applied_${entryKey}`;
+/** Set before the webhook is registered and cleared once its secret is in the env. */
+export const entryAiWebhookPendingScopeKey = (entryKey) => `ai_webhook_pending_${entryKey}`;
+/** The id of the key whose env write finished, before the app restart that completes the step. */
+export const entryAiWrittenScopeKey = (entryKey) => `ai_key_env_written_${entryKey}`;
+/** The expiry ai returned for the key above. */
+export const entryAiPendingExpiresScopeKey = (entryKey) => `ai_key_pending_expires_${entryKey}`;
+/** `{ expiresAt, minter }` of a key ai clamped under the renewal window; renewing it again under the same minter only repeats. */
+export const entryAiClampedScopeKey = (entryKey) => `ai_key_clamped_${entryKey}`;
+/** The id of a key that was live when its entry stopped declaring `uses.ai`, once handled. */
+export const entryAiRetiredScopeKey = (entryKey) => `ai_key_retired_${entryKey}`;
+/**
+ * REVOKE SEAM (ai#157, A1b, not built): the ids of keys left live because
+ * `AiOrganisationPort.revokeKey` is absent or failed, as a JSON array. They
+ * expire on their own; the plan lists each.
+ */
+export const entryAiUnrevokedScopeKey = (entryKey) => `ai_key_unrevoked_${entryKey}`;
+export const ENTRY_AI_UNREVOKED_PREFIX = 'ai_key_unrevoked_';
+export function parseIdList(raw) {
+    try {
+        const parsed = raw ? JSON.parse(raw) : [];
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+export const entryAiKeyName = (org, entry) => `${org.slug}-${entry.key}`;
+export function wantedEntryAi(org, entry, aiUrl) {
+    const ai = entry.uses?.ai;
+    const host = entryHostnames(org, entry)[0];
+    return {
+        permissions: [...(ai?.permissions ?? AI_ENTRY_PERMISSIONS)],
+        offerings: [...(ai?.offerings ?? [])],
+        webhook: ai?.webhookPath !== undefined && host ? `https://${host}${ai.webhookPath}` : null,
+        aiUrl,
+    };
+}
+/**
+ * One step per entry whose key is missing, near expiry or whose declared
+ * settings changed. Blocked, not planned (rule 2), while the org's key, the
+ * entry's app or the ai address is not recorded, or after a mint whose
+ * delivery failed: a second mint would leave two live keys.
+ */
+export function planEntryAiKeys(org, recordedIds, plannedSteps, readiness, now) {
+    const steps = [];
+    const blocked = [];
+    // Keys listed as left live, whichever entry they came from.
+    for (const [name, raw] of Object.entries(recordedIds)) {
+        if (!name.startsWith(ENTRY_AI_UNREVOKED_PREFIX))
+            continue;
+        const entryKey = name.slice(ENTRY_AI_UNREVOKED_PREFIX.length);
+        for (const id of parseIdList(raw)) {
+            blocked.push({
+                description: `warning: ${org.slug}'s ${entryKey} ai key ${id} stays live until it expires; ai has no revoke route yet (https://github.com/wtfalch/ai/issues/157)`,
+                key: `ai:key:${org.id}:${entryKey}:unrevoked:${id}`,
+            });
+        }
+    }
+    const declared = new Set(org.hosting.entries.filter((e) => e.uses?.ai).map((e) => e.key));
+    const keyPrefix = `ai:key:${org.id}:`;
+    // A key whose entry is gone, or no longer declares `uses.ai`, is revoked.
+    if (readiness.aiReady) {
+        for (const [name, id] of Object.entries(recordedIds)) {
+            if (!name.startsWith(keyPrefix) || !id)
+                continue;
+            const entryKey = name.slice(keyPrefix.length);
+            if (declared.has(entryKey) || recordedIds[entryAiRetiredScopeKey(entryKey)] === id)
+                continue;
+            steps.push({
+                action: {
+                    system: 'ai',
+                    kind: 'key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire' },
+                },
+                step: {
+                    description: `revoke ${org.slug}'s ${entryKey} ai key ${id}: the entry no longer declares uses.ai`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    for (const entry of org.hosting.entries) {
+        if (!entry.uses?.ai)
+            continue;
+        const at = `${org.slug}'s ${entry.key} ai key`;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `ai:key:${stepKey}`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        if (!readiness.aiReady)
+            continue; // `ai:organisation` already reports it.
+        // A key retired earlier is dead even though its id is still recorded.
+        const liveKeyId = recordedIds[key] && recordedIds[entryAiRetiredScopeKey(entry.key)] !== recordedIds[key]
+            ? recordedIds[key]
+            : undefined;
+        const undelivered = recordedIds[entryAiUndeliveredScopeKey(entry.key)];
+        const finishing = Boolean(undelivered && recordedIds[entryAiWrittenScopeKey(entry.key)] === undelivered);
+        if (undelivered && !finishing) {
+            block(`key ${undelivered} was minted but not delivered, and no new key is minted until it is revoked in ai`);
+            continue;
+        }
+        if (recordedIds[entryAiWebhookPendingScopeKey(entry.key)]) {
+            block('its webhook was registered but the secret was not delivered; rotate it in ai');
+            continue;
+        }
+        if (!readiness.aiUrl) {
+            block("the platform has not recorded ai's address yet");
+            continue;
+        }
+        const planned = (system, kind, k) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === k);
+        if (!recordedIds[`ai:key:${org.id}`] && !planned('ai', 'key', org.id)) {
+            block("the org's own ai key is not recorded yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        const want = wantedEntryAi(org, entry, readiness.aiUrl);
+        const applied = recordedIds[entryAiAppliedScopeKey(entry.key)];
+        const wantJson = JSON.stringify(want);
+        let mode = null;
+        if (finishing) {
+            // The env holds the new key; only the restart and the records are left.
+            mode = 'finish';
+        }
+        else if (!liveKeyId) {
+            mode = 'mint';
+        }
+        else {
+            const expiresRaw = recordedIds[entryAiExpiresScopeKey(entry.key)];
+            const expires = Date.parse(expiresRaw ?? '');
+            let appliedWant = {};
+            try {
+                appliedWant = applied ? JSON.parse(applied) : {};
+            }
+            catch {
+                // An unreadable marker plans the settings step again.
+            }
+            if (!(expires - now >= AI_ENTRY_RENEW_WINDOW_DAYS * DAY_MS)) {
+                // ai clamps an entry key to the org key's expiry. A key already
+                // clamped under this window by this same minter would only be
+                // replaced by another as short: the org key must be renewed first.
+                let clamped = {};
+                try {
+                    clamped = JSON.parse(recordedIds[entryAiClampedScopeKey(entry.key)] || '{}');
+                }
+                catch {
+                    // Unreadable: treated as not clamped.
+                }
+                if (clamped.expiresAt === expiresRaw &&
+                    clamped.minter === recordedIds[`ai:key:${org.id}`]) {
+                    block(`the key expires ${expiresRaw} because the org's own ai key expires then; renew the org's own ai key, then this one is renewed`);
+                    continue;
+                }
+                mode = 'renew';
+            }
+            else if (JSON.stringify(appliedWant.permissions) !== JSON.stringify(want.permissions)) {
+                mode = 'renew';
+            }
+            else if (applied !== wantJson)
+                mode = 'settings';
+        }
+        if (!mode)
+            continue;
+        steps.push({
+            action: {
+                system: 'ai',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode,
+                    name: entryAiKeyName(org, entry),
+                    expiresDays: AI_ENTRY_KEY_DAYS,
+                    ...want,
+                },
+            },
+            step: {
+                description: mode === 'settings'
+                    ? `update ${at}'s AI_* env and webhook`
+                    : mode === 'finish'
+                        ? `finish ${at}: restart the app that already holds the new key`
+                        : `${mode === 'mint' ? 'mint' : 'renew'} ${at} below the org's own key, write AI_* env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/entry-files-key.d.ts

@@ -0,0 +1,82 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import type { PlannedStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * F6b: the org's own files key, minted below the files organisation's
+ * first owner and renewed before it expires, and one files key per entry with `uses.files`, minted below
+ * it. A secret goes to `deliverSecret` (the org key) or into the entry's env
+ * (an entry key) and nowhere else.
+ */
+/** How long a key lives. files refuses more than 365 and anything past its minter's own expiry. */
+export declare const FILES_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export declare const FILES_KEY_RENEW_WINDOW_DAYS = 30;
+/** What the org's own key holds: it mints and revokes, and holds what its entries may hold. */
+export declare const FILES_ROOT_PERMISSIONS: readonly ["credentials:create", "credentials:revoke", "files.collections:read", "files.files:read", "files.files:download", "files.files:upload", "files.files:replace", "files.files:delete"];
+/**
+ * Flat scope ids (no `:`). The org's own key: the id minted last (it blocks
+ * only while it differs from the recorded key, which means it was never
+ * delivered) and when the recorded key expires.
+ */
+export declare const FILES_ROOT_UNDELIVERED_SCOPE_KEY = "files_key_undelivered";
+export declare const FILES_ROOT_EXPIRES_SCOPE_KEY = "files_key_expires";
+/** Ids of org keys replaced by a renewal, as a JSON array, revoked once every entry holds a key below the new one. */
+export declare const FILES_ROOT_PREVIOUS_SCOPE_KEY = "files_key_previous";
+/** Ids of replaced org keys whose revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export declare const FILES_ROOT_UNREVOKED_SCOPE_KEY = "files_key_unrevoked";
+/** The sign-in user id files made the organisation's owner when foundry provisioned it with one; the org key is minted below it. */
+export declare const FILES_ORG_OWNER_SCOPE_KEY = "files_org_owner";
+/** Agora's files key, which files returns once when it onboards Agora at provisioning: its id once delivered, and an id minted but not yet delivered. */
+export declare const FILES_AGORA_KEY_SCOPE_KEY = "files_agora_key";
+export declare const FILES_AGORA_UNDELIVERED_SCOPE_KEY = "files_agora_key_undelivered";
+/** Per entry. Entry keys hold neither `:` nor `.`. */
+export declare const entryFilesUndeliveredScopeKey: (entryKey: string) => string;
+/** The id of the org key the entry's live key was minted below. */
+export declare const entryFilesMinterScopeKey: (entryKey: string) => string;
+/** The ISO time the entry's live key expires. */
+export declare const entryFilesExpiresScopeKey: (entryKey: string) => string;
+/** What the last apply wrote: permissions, collection names, files address. Never a secret. */
+export declare const entryFilesAppliedScopeKey: (entryKey: string) => string;
+/** The id of the key whose env write finished, before the app restart that completes the step. */
+export declare const entryFilesWrittenScopeKey: (entryKey: string) => string;
+/** The expiry files returned for the key above. */
+export declare const entryFilesPendingExpiresScopeKey: (entryKey: string) => string;
+/** The id of a key that was live when its entry stopped declaring `uses.files`, once handled. */
+export declare const entryFilesRetiredScopeKey: (entryKey: string) => string;
+/** The ids of keys left live because a revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export declare const entryFilesUnrevokedScopeKey: (entryKey: string) => string;
+export declare const ENTRY_FILES_UNREVOKED_PREFIX = "files_entry_unrevoked_";
+export declare const ENTRY_FILES_UNDELIVERED_PREFIX = "files_entry_undelivered_";
+export declare function parseIdList(raw: string | undefined): string[];
+export declare const filesRootKeyName: (org: DeclaredOrg) => string;
+export declare const entryFilesKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/** The recorded ZITADEL user id of the org's first owner, the files organisation's first member. */
+export declare function filesOwnerUserId(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): string | undefined;
+export interface EntryFilesWant {
+    permissions: string[];
+    collections: string[];
+    filesUrl: string;
+}
+export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string): EntryFilesWant;
+export type EntryFilesMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * The org key's steps, then one step per entry whose key is missing, near
+ * expiry, minted below a replaced org key or whose declared settings changed.
+ * Blocked, not planned (rule 2), while the owner, the org key, the entry's
+ * app or the files address is not recorded, or after a mint whose delivery
+ * failed: a second mint would leave two live keys.
+ *
+ * Renewing the org key: under 30 days left (or an expiry nobody recorded),
+ * `renew` mints a new one and delivers it. Each entry is then re-minted below
+ * it by its own `renew` step, and only then does `revoke-previous` revoke the
+ * old org key, which revokes everything still below it.
+ */
+export declare function planFilesKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: PlannedStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/entry-files-key.js

@@ -0,0 +1,327 @@
+import { FILES_ENTRY_PERMISSIONS } from '../org.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * F6b: the org's own files key, minted below the files organisation's
+ * first owner and renewed before it expires, and one files key per entry with `uses.files`, minted below
+ * it. A secret goes to `deliverSecret` (the org key) or into the entry's env
+ * (an entry key) and nowhere else.
+ */
+/** How long a key lives. files refuses more than 365 and anything past its minter's own expiry. */
+export const FILES_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export const FILES_KEY_RENEW_WINDOW_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** What the org's own key holds: it mints and revokes, and holds what its entries may hold. */
+export const FILES_ROOT_PERMISSIONS = [
+    'credentials:create',
+    'credentials:revoke',
+    ...FILES_ENTRY_PERMISSIONS,
+];
+/**
+ * Flat scope ids (no `:`). The org's own key: the id minted last (it blocks
+ * only while it differs from the recorded key, which means it was never
+ * delivered) and when the recorded key expires.
+ */
+export const FILES_ROOT_UNDELIVERED_SCOPE_KEY = 'files_key_undelivered';
+export const FILES_ROOT_EXPIRES_SCOPE_KEY = 'files_key_expires';
+/** Ids of org keys replaced by a renewal, as a JSON array, revoked once every entry holds a key below the new one. */
+export const FILES_ROOT_PREVIOUS_SCOPE_KEY = 'files_key_previous';
+/** Ids of replaced org keys whose revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export const FILES_ROOT_UNREVOKED_SCOPE_KEY = 'files_key_unrevoked';
+/** The sign-in user id files made the organisation's owner when foundry provisioned it with one; the org key is minted below it. */
+export const FILES_ORG_OWNER_SCOPE_KEY = 'files_org_owner';
+/** Agora's files key, which files returns once when it onboards Agora at provisioning: its id once delivered, and an id minted but not yet delivered. */
+export const FILES_AGORA_KEY_SCOPE_KEY = 'files_agora_key';
+export const FILES_AGORA_UNDELIVERED_SCOPE_KEY = 'files_agora_key_undelivered';
+/** Per entry. Entry keys hold neither `:` nor `.`. */
+export const entryFilesUndeliveredScopeKey = (entryKey) => `files_entry_undelivered_${entryKey}`;
+/** The id of the org key the entry's live key was minted below. */
+export const entryFilesMinterScopeKey = (entryKey) => `files_entry_minter_${entryKey}`;
+/** The ISO time the entry's live key expires. */
+export const entryFilesExpiresScopeKey = (entryKey) => `files_entry_expires_${entryKey}`;
+/** What the last apply wrote: permissions, collection names, files address. Never a secret. */
+export const entryFilesAppliedScopeKey = (entryKey) => `files_entry_applied_${entryKey}`;
+/** The id of the key whose env write finished, before the app restart that completes the step. */
+export const entryFilesWrittenScopeKey = (entryKey) => `files_entry_written_${entryKey}`;
+/** The expiry files returned for the key above. */
+export const entryFilesPendingExpiresScopeKey = (entryKey) => `files_entry_pending_expires_${entryKey}`;
+/** The id of a key that was live when its entry stopped declaring `uses.files`, once handled. */
+export const entryFilesRetiredScopeKey = (entryKey) => `files_entry_retired_${entryKey}`;
+/** The ids of keys left live because a revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export const entryFilesUnrevokedScopeKey = (entryKey) => `files_entry_unrevoked_${entryKey}`;
+export const ENTRY_FILES_UNREVOKED_PREFIX = 'files_entry_unrevoked_';
+export const ENTRY_FILES_UNDELIVERED_PREFIX = 'files_entry_undelivered_';
+export function parseIdList(raw) {
+    try {
+        const parsed = raw ? JSON.parse(raw) : [];
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+export const filesRootKeyName = (org) => `${org.slug}-files`;
+export const entryFilesKeyName = (org, entry) => `${org.slug}-${entry.key}-files`;
+/** The recorded ZITADEL user id of the org's first owner, the files organisation's first member. */
+export function filesOwnerUserId(org, recordedIds) {
+    const first = org.owners[0];
+    return first ? recordedIds[`zitadel:owner:${org.id}:${first.email.toLowerCase()}`] : undefined;
+}
+export function wantedEntryFiles(entry, filesUrl) {
+    const files = entry.uses?.files;
+    return {
+        permissions: [...(files?.permissions ?? FILES_ENTRY_PERMISSIONS)],
+        collections: [...(files?.collections ?? [])],
+        filesUrl,
+    };
+}
+/**
+ * The org key's steps, then one step per entry whose key is missing, near
+ * expiry, minted below a replaced org key or whose declared settings changed.
+ * Blocked, not planned (rule 2), while the owner, the org key, the entry's
+ * app or the files address is not recorded, or after a mint whose delivery
+ * failed: a second mint would leave two live keys.
+ *
+ * Renewing the org key: under 30 days left (or an expiry nobody recorded),
+ * `renew` mints a new one and delivers it. Each entry is then re-minted below
+ * it by its own `renew` step, and only then does `revoke-previous` revoke the
+ * old org key, which revokes everything still below it.
+ */
+export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
+    const steps = [];
+    const blocked = [];
+    const planned = (system, kind, k) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === k);
+    // Keys listed as left live, whichever entry they came from.
+    for (const [name, raw] of Object.entries(recordedIds)) {
+        if (!name.startsWith(ENTRY_FILES_UNREVOKED_PREFIX))
+            continue;
+        const entryKey = name.slice(ENTRY_FILES_UNREVOKED_PREFIX.length);
+        for (const id of parseIdList(raw)) {
+            blocked.push({
+                description: `warning: ${org.slug}'s ${entryKey} files key ${id} stays live until it expires; its revoke failed`,
+                key: `files:key:${org.id}:${entryKey}:unrevoked:${id}`,
+            });
+        }
+    }
+    for (const id of parseIdList(recordedIds[FILES_ROOT_UNREVOKED_SCOPE_KEY])) {
+        blocked.push({
+            description: `warning: ${org.slug}'s replaced own files key ${id} stays live until it expires; its revoke failed`,
+            key: `files:key:${org.id}:unrevoked:${id}`,
+        });
+    }
+    // Agora's key came back once and was not delivered.
+    const agoraUndelivered = recordedIds[FILES_AGORA_UNDELIVERED_SCOPE_KEY];
+    if (agoraUndelivered && agoraUndelivered !== recordedIds[FILES_AGORA_KEY_SCOPE_KEY]) {
+        blocked.push({
+            description: `warning: ${org.slug}'s Agora files key ${agoraUndelivered} was created but not delivered; revoke it in files`,
+            key: `files:agora-key:${org.id}`,
+        });
+    }
+    const entries = org.hosting.entries.filter((e) => e.uses?.files);
+    const declared = new Set(entries.map((e) => e.key));
+    const rootKeyId = recordedIds[`files:key:${org.id}`];
+    // A key whose entry is gone, or no longer declares `uses.files`, is revoked:
+    // the recorded one and any minted but not delivered or not yet restarted.
+    if (readiness.filesReady) {
+        const prefix = `files:key:${org.id}:`;
+        const gone = new Set();
+        for (const name of Object.keys(recordedIds)) {
+            if (name.startsWith(prefix) && recordedIds[name])
+                gone.add(name.slice(prefix.length));
+            if (name.startsWith(ENTRY_FILES_UNDELIVERED_PREFIX) && recordedIds[name]) {
+                gone.add(name.slice(ENTRY_FILES_UNDELIVERED_PREFIX.length));
+            }
+        }
+        for (const entryKey of gone) {
+            if (declared.has(entryKey))
+                continue;
+            const liveId = recordedIds[`${prefix}${entryKey}`];
+            const stale = liveId && recordedIds[entryFilesRetiredScopeKey(entryKey)] !== liveId;
+            const loose = recordedIds[entryFilesUndeliveredScopeKey(entryKey)];
+            if (!stale && !loose)
+                continue;
+            steps.push({
+                action: {
+                    system: 'files',
+                    kind: 'key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire' },
+                },
+                step: {
+                    description: `revoke ${org.slug}'s ${entryKey} files key ${[stale ? liveId : '', loose ?? ''].filter(Boolean).join(' and ')}: the entry no longer declares uses.files`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    if (entries.length === 0 || !readiness.filesReady)
+        return { steps, blocked };
+    for (const entry of entries) {
+        if (entry.uses?.files?.shareHost) {
+            blocked.push({
+                description: `${org.slug}'s ${entry.key} share host is blocked: the platform's files host has no route for share.<domain> yet, so FILES_SHARE_ORIGIN is not delivered`,
+                key: `files:share:${org.id}:${entry.key}`,
+            });
+        }
+    }
+    // The org's own key: minted, or renewed when it is short or its expiry is unknown.
+    const rootBlock = (why) => blocked.push({
+        description: `${org.slug}'s own files key is blocked: ${why}`,
+        key: `files:key:${org.id}`,
+    });
+    const rootExpiresRaw = recordedIds[FILES_ROOT_EXPIRES_SCOPE_KEY];
+    const rootExpires = Date.parse(rootExpiresRaw ?? '');
+    const rootShort = Boolean(rootKeyId) &&
+        (Number.isNaN(rootExpires) || rootExpires - now < FILES_KEY_RENEW_WINDOW_DAYS * DAY_MS);
+    const rootUndelivered = recordedIds[FILES_ROOT_UNDELIVERED_SCOPE_KEY];
+    let rootMode = null;
+    if (!rootKeyId || rootShort) {
+        const ownerKey = org.owners[0] ? `${org.id}:${org.owners[0].email.toLowerCase()}` : '';
+        const orgPlanned = planned('files', 'organisation', org.id);
+        if (rootUndelivered && rootUndelivered !== rootKeyId) {
+            rootBlock(`key ${rootUndelivered} was minted but not delivered, and no new key is minted until it is revoked in files`);
+        }
+        else if (!org.owners[0]) {
+            rootBlock('the org names no owner; the key is minted below the files organisation owner');
+        }
+        else if (!recordedIds[FILES_ORG_OWNER_SCOPE_KEY] && !orgPlanned) {
+            rootBlock("the files organisation exists without an owner, and files can mint its key only below one; make the org's first owner an owner member of it in files, then record that person's sign-in user id as the scope id files_org_owner");
+        }
+        else if (!recordedIds[FILES_ORG_OWNER_SCOPE_KEY] &&
+            !filesOwnerUserId(org, recordedIds) &&
+            !planned('zitadel', 'owner', ownerKey)) {
+            rootBlock("the first owner's sign-in user id is not recorded yet");
+        }
+        else {
+            rootMode = rootKeyId ? 'renew' : 'mint';
+            steps.push({
+                action: {
+                    system: 'files',
+                    kind: 'key',
+                    key: org.id,
+                    desired: {
+                        mode: rootMode,
+                        name: filesRootKeyName(org),
+                        expiresDays: FILES_KEY_DAYS,
+                        permissions: [...FILES_ROOT_PERMISSIONS],
+                    },
+                },
+                step: {
+                    description: rootMode === 'renew'
+                        ? `renew ${org.slug}'s own files key and re-mint its entry keys below it`
+                        : `mint ${org.slug}'s own files key below its owner`,
+                    destroys: false,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    const entryStepKeys = [];
+    for (const entry of entries) {
+        const at = `${org.slug}'s ${entry.key} files key`;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `files:key:${stepKey}`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        const liveKeyId = recordedIds[key] && recordedIds[entryFilesRetiredScopeKey(entry.key)] !== recordedIds[key]
+            ? recordedIds[key]
+            : undefined;
+        const undelivered = recordedIds[entryFilesUndeliveredScopeKey(entry.key)];
+        const finishing = Boolean(undelivered && recordedIds[entryFilesWrittenScopeKey(entry.key)] === undelivered);
+        if (undelivered && !finishing) {
+            block(`key ${undelivered} was minted but not delivered, and no new key is minted until it is revoked in files`);
+            continue;
+        }
+        if (!readiness.filesUrl) {
+            block("the platform has not recorded files' address yet");
+            continue;
+        }
+        if (!rootKeyId && !rootMode) {
+            block("the org's own files key is not recorded yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        const want = wantedEntryFiles(entry, readiness.filesUrl);
+        const applied = recordedIds[entryFilesAppliedScopeKey(entry.key)];
+        const wantJson = JSON.stringify(want);
+        let mode = null;
+        if (finishing) {
+            mode = 'finish';
+        }
+        else {
+            let appliedWant = {};
+            try {
+                appliedWant = applied ? JSON.parse(applied) : {};
+            }
+            catch {
+                // An unreadable marker plans the settings step again.
+            }
+            if (!liveKeyId) {
+                mode = 'mint';
+            }
+            else if (
+            // Below an org key that is being, or was, replaced.
+            rootMode === 'renew' ||
+                (rootKeyId && recordedIds[entryFilesMinterScopeKey(entry.key)] !== rootKeyId) ||
+                !(Date.parse(recordedIds[entryFilesExpiresScopeKey(entry.key)] ?? '') - now >=
+                    FILES_KEY_RENEW_WINDOW_DAYS * DAY_MS) ||
+                JSON.stringify(appliedWant.permissions) !== JSON.stringify(want.permissions)) {
+                mode = 'renew';
+            }
+            else if (applied !== wantJson) {
+                mode = 'settings';
+            }
+            if ((mode === 'mint' || mode === 'renew') && !rootMode && rootShort) {
+                block(`the org's own files key expires ${rootExpiresRaw || 'at an unknown time'}, and its renewal is blocked (see the org key's item); renew it first`);
+                continue;
+            }
+        }
+        if (!mode)
+            continue;
+        entryStepKeys.push(stepKey);
+        steps.push({
+            action: {
+                system: 'files',
+                kind: 'key',
+                key: stepKey,
+                desired: { mode, name: entryFilesKeyName(org, entry), ...want },
+            },
+            step: {
+                description: mode === 'settings'
+                    ? `update ${at}'s FILES_* env`
+                    : mode === 'finish'
+                        ? `finish ${at}: restart the app that already holds the new key`
+                        : `${mode === 'mint' ? 'mint' : 'renew'} ${at} below the org's own key, write FILES_* env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    // The replaced org key goes last, once every entry holds a key below the new one.
+    const previous = parseIdList(recordedIds[FILES_ROOT_PREVIOUS_SCOPE_KEY]);
+    const consistent = entries.every((e) => {
+        const stepKey = appStepKey(org, e.key);
+        return (recordedIds[`files:key:${stepKey}`] &&
+            recordedIds[entryFilesMinterScopeKey(e.key)] === rootKeyId &&
+            !recordedIds[entryFilesUndeliveredScopeKey(e.key)]);
+    });
+    if (rootMode === 'renew' || (previous.length > 0 && consistent)) {
+        steps.push({
+            action: {
+                system: 'files',
+                kind: 'key',
+                key: org.id,
+                desired: { mode: 'revoke-previous' },
+            },
+            step: {
+                description: `revoke ${org.slug}'s replaced own files key once every entry key is below the new one`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}