@wtfalch/foundry 0.76.1 → 0.77.0

package/dist/plan/files-boule-key-apply.d.ts

@@ -0,0 +1,73 @@
+import { type FilesBouleWant } from './files-boule-key.js';
+/** Every call this module makes (files, held keys, Coolify) is cut off after this long. */
+export declare const FILES_BOULE_CALL_TIMEOUT_MS = 30000;
+/** How many times Boule's key is tried against the held keys. */
+export declare const FILES_BOULE_HOLD_ATTEMPTS = 3;
+/** The two files calls this needs, as `FilesOrganisationPort` offers them. */
+export interface FilesBouleFilesPort {
+    issueKeyBelow(organisationId: string, minterId: string, input: {
+        name: string;
+        kind: 'api_key' | 'agent' | 'service';
+        permissions: string[];
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+        expiresAt: string;
+    }>;
+    revokeOrganisationKey(organisationId: string, keyId: string): Promise<unknown>;
+}
+export interface FilesBouleKeyDeps {
+    files: FilesBouleFilesPort;
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    coolify: {
+        bulkUpsertEnvs(appId: string, envs: Array<{
+            key: string;
+            value: string;
+            literal?: boolean;
+        }>): Promise<unknown>;
+        listEnvs(appId: string): Promise<Array<{
+            uuid?: string;
+            key: string;
+            value: string;
+            is_preview: boolean;
+        }>>;
+        deleteEnv(appId: string, envUuid: string): Promise<unknown>;
+        restart(appId: string): Promise<unknown>;
+    };
+    org: {
+        id: string;
+        slug: string;
+    };
+    /** Boule's Coolify app, when it is recorded. */
+    bouleAppId: string | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    forget: (key: string) => void;
+    persist: () => Promise<void>;
+    /** Registers a value for redaction before anything else can see it. */
+    secret: (value: string) => void;
+    now?: () => number;
+    timeoutMs?: number;
+}
+/** What `ensureFilesBouleKey` is given from the plan. */
+export interface FilesBouleStep extends FilesBouleWant {
+    mode: 'mint' | 'renew' | 'deliver';
+    name: string;
+    expiresDays: number;
+    permissions: string[];
+}
+/**
+ * Mints (or reuses the held) Boule key and writes `FILES_URL` and `FILES_BOULE_KEYS` to Boule's env. See
+ * `files-boule-key.ts` for the order. Errors name the key id and the ref, never the key.
+ */
+export declare function ensureFilesBouleKey(deps: FilesBouleKeyDeps, step: FilesBouleStep): Promise<void>;
+/**
+ * Revokes Boule's key once no entry uses files (a held one, one minted and never held, and any a renewal
+ * left), takes `FILES_URL` and `FILES_BOULE_KEYS` out of Boule's env and restarts Boule, then clears the
+ * records. A key files no longer knows counts as revoked.
+ */
+export declare function retireFilesBouleKey(deps: FilesBouleKeyDeps): Promise<void>;

package/dist/plan/files-boule-key-apply.js

@@ -0,0 +1,223 @@
+import { FILES_KEY_RENEW_WINDOW_DAYS, parseIdList } from './entry-files-key.js';
+import { FILES_BOULE_APPLIED_SCOPE_KEY, FILES_BOULE_EXPIRES_SCOPE_KEY, FILES_BOULE_KEYS_ENV, FILES_BOULE_KEY_SCOPE_KEY, FILES_BOULE_MINTER_SCOPE_KEY, FILES_BOULE_PREVIOUS_SCOPE_KEY, FILES_BOULE_UNDELIVERED_SCOPE_KEY, FILES_BOULE_UNREVOKED_SCOPE_KEY, FILES_BOULE_URL_ENV, filesBouleKeyRef, } from './files-boule-key.js';
+/** Every call this module makes (files, held keys, Coolify) is cut off after this long. */
+export const FILES_BOULE_CALL_TIMEOUT_MS = 30_000;
+/** How many times Boule's key is tried against the held keys. */
+export const FILES_BOULE_HOLD_ATTEMPTS = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+async function timed(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            work(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('timeout')), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const statusOf = (error) => {
+    const status = error?.status;
+    return typeof status === 'number' ? ` (${status})` : '';
+};
+const isNotFound = (error) => error?.status === 404;
+/**
+ * Mints (or reuses the held) Boule key and writes `FILES_URL` and `FILES_BOULE_KEYS` to Boule's env. See
+ * `files-boule-key.ts` for the order. Errors name the key id and the ref, never the key.
+ */
+export async function ensureFilesBouleKey(deps, step) {
+    const ms = deps.timeoutMs ?? FILES_BOULE_CALL_TIMEOUT_MS;
+    const now = deps.now ?? Date.now;
+    const at = `files:boule-key for ${deps.org.slug}`;
+    const ref = filesBouleKeyRef(deps.org.id);
+    if (!deps.bouleAppId)
+        throw new Error(`${at}: Boule is not recorded yet`);
+    const bouleAppId = deps.bouleAppId;
+    const recorded = deps.recorded();
+    const undelivered = recorded[FILES_BOULE_UNDELIVERED_SCOPE_KEY];
+    let guard = recorded[FILES_BOULE_KEY_SCOPE_KEY];
+    if (undelivered && undelivered !== guard) {
+        throw new Error(`${at}: key ${undelivered} was minted but never held, and files shows a key once; revoke it in files and remove the recorded key ${FILES_BOULE_UNDELIVERED_SCOPE_KEY}`);
+    }
+    const rootId = recorded[`files:key:${deps.org.id}`];
+    let key = null;
+    if (guard && step.mode === 'renew') {
+        // The key in Boule's env stays until the new one is written; it is revoked after.
+        const previous = parseIdList(recorded[FILES_BOULE_PREVIOUS_SCOPE_KEY]);
+        if (!previous.includes(guard))
+            previous.push(guard);
+        deps.record(FILES_BOULE_PREVIOUS_SCOPE_KEY, JSON.stringify(previous));
+        deps.forget(FILES_BOULE_KEY_SCOPE_KEY);
+        deps.forget(FILES_BOULE_UNDELIVERED_SCOPE_KEY);
+        await deps.persist();
+        guard = undefined;
+    }
+    else if (guard) {
+        try {
+            key = (await timed(() => deps.heldKeys.resolve(ref), ms)) || null;
+        }
+        catch {
+            throw new Error(`${at}: the held key ${ref} could not be read`);
+        }
+        if (key) {
+            deps.secret(key);
+        }
+        else {
+            // The held value is gone: the key Boule had is revoked before a new one is minted.
+            try {
+                await timed(() => deps.files.revokeOrganisationKey(deps.org.id, guard), ms);
+            }
+            catch (error) {
+                if (!isNotFound(error)) {
+                    throw new Error(`${at}: the held key ${ref} is missing and key ${guard} could not be revoked before a new one is minted; the next apply tries again`);
+                }
+            }
+            deps.forget(FILES_BOULE_KEY_SCOPE_KEY);
+            deps.forget(FILES_BOULE_UNDELIVERED_SCOPE_KEY);
+            await deps.persist();
+            guard = undefined;
+        }
+    }
+    if (!key) {
+        if (!rootId)
+            throw new Error(`${at}: the org's own files key is not recorded yet`);
+        // files refuses a key that outlives its minter. A minute is held back so the call still lands inside it.
+        const rootExpires = Date.parse(recorded.files_key_expires ?? '');
+        if (Number.isNaN(rootExpires)) {
+            throw new Error(`${at}: the org's own files key expiry is not recorded`);
+        }
+        const expiresDays = Math.min(step.expiresDays, Math.floor((rootExpires - now() - 60_000) / DAY_MS));
+        if (expiresDays < FILES_KEY_RENEW_WINDOW_DAYS) {
+            throw new Error(`${at}: the org's own files key leaves under ${FILES_KEY_RENEW_WINDOW_DAYS} days; renew it first`);
+        }
+        let minted;
+        try {
+            minted = await timed(() => deps.files.issueKeyBelow(deps.org.id, rootId, {
+                name: step.name,
+                kind: 'service',
+                permissions: [...step.permissions],
+                expiresDays,
+            }), ms);
+        }
+        catch (error) {
+            throw new Error(`${at}: files refused or did not answer the key${statusOf(error)}`);
+        }
+        if (typeof minted?.secret === 'string' && minted.secret)
+            deps.secret(minted.secret);
+        if (typeof minted?.id !== 'string' || !minted.id) {
+            throw new Error(`${at}: files answered the key with no id`);
+        }
+        deps.record(FILES_BOULE_UNDELIVERED_SCOPE_KEY, minted.id);
+        await deps.persist();
+        if (typeof minted.secret !== 'string' || !minted.secret) {
+            throw new Error(`${at}: key ${minted.id} was minted but files returned no key, which it shows once; revoke it in files and remove the recorded key ${FILES_BOULE_UNDELIVERED_SCOPE_KEY}`);
+        }
+        let stored = false;
+        for (let attempt = 1; attempt <= FILES_BOULE_HOLD_ATTEMPTS && !stored; attempt++) {
+            try {
+                await timed(() => deps.heldKeys.put(ref, minted.secret), ms);
+                stored = true;
+            }
+            catch {
+                // Retried; the error is dropped in case it echoes the key.
+            }
+        }
+        if (!stored) {
+            throw new Error(`${at}: key ${minted.id} was minted but could not be held at ${ref} after ${FILES_BOULE_HOLD_ATTEMPTS} attempts; revoke it in files and remove the recorded key ${FILES_BOULE_UNDELIVERED_SCOPE_KEY}`);
+        }
+        deps.record(FILES_BOULE_KEY_SCOPE_KEY, minted.id);
+        deps.record(FILES_BOULE_MINTER_SCOPE_KEY, rootId);
+        deps.record(FILES_BOULE_EXPIRES_SCOPE_KEY, minted.expiresAt);
+        await deps.persist();
+        key = minted.secret;
+    }
+    const value = {
+        live: { organisationId: step.organisationId, key, apps: step.apps },
+    };
+    try {
+        await timed(() => deps.coolify.bulkUpsertEnvs(bouleAppId, [
+            { key: FILES_BOULE_URL_ENV, value: step.url, literal: true },
+            { key: FILES_BOULE_KEYS_ENV, value: JSON.stringify(value), literal: true },
+        ]), ms);
+        await timed(() => deps.coolify.restart(bouleAppId), ms);
+    }
+    catch {
+        // The error is dropped in case Coolify echoes the request body, which holds the key.
+        throw new Error(`${at}: the key is held at ${ref} but could not be written to Boule's env; the next apply writes it again`);
+    }
+    deps.forget(FILES_BOULE_UNDELIVERED_SCOPE_KEY);
+    deps.record(FILES_BOULE_APPLIED_SCOPE_KEY, JSON.stringify({ url: step.url, organisationId: step.organisationId, apps: step.apps }));
+    // The keys a renewal replaced: Boule no longer holds them. A failed revoke is listed, not retried.
+    const previous = parseIdList(deps.recorded()[FILES_BOULE_PREVIOUS_SCOPE_KEY]);
+    if (previous.length > 0) {
+        const unrevoked = parseIdList(deps.recorded()[FILES_BOULE_UNREVOKED_SCOPE_KEY]);
+        for (const id of previous) {
+            try {
+                await timed(() => deps.files.revokeOrganisationKey(deps.org.id, id), ms);
+            }
+            catch (error) {
+                if (!isNotFound(error) && !unrevoked.includes(id))
+                    unrevoked.push(id);
+            }
+        }
+        deps.record(FILES_BOULE_UNREVOKED_SCOPE_KEY, unrevoked.length ? JSON.stringify(unrevoked) : '');
+        deps.forget(FILES_BOULE_PREVIOUS_SCOPE_KEY);
+    }
+}
+/**
+ * Revokes Boule's key once no entry uses files (a held one, one minted and never held, and any a renewal
+ * left), takes `FILES_URL` and `FILES_BOULE_KEYS` out of Boule's env and restarts Boule, then clears the
+ * records. A key files no longer knows counts as revoked.
+ */
+export async function retireFilesBouleKey(deps) {
+    const ms = deps.timeoutMs ?? FILES_BOULE_CALL_TIMEOUT_MS;
+    const at = `files:boule-key for ${deps.org.slug}`;
+    const recorded = deps.recorded();
+    const ids = [
+        ...new Set([
+            recorded[FILES_BOULE_KEY_SCOPE_KEY],
+            recorded[FILES_BOULE_UNDELIVERED_SCOPE_KEY],
+            ...parseIdList(recorded[FILES_BOULE_PREVIOUS_SCOPE_KEY]),
+        ].filter((id) => Boolean(id))),
+    ];
+    for (const id of ids) {
+        try {
+            await timed(() => deps.files.revokeOrganisationKey(deps.org.id, id), ms);
+        }
+        catch (error) {
+            if (!isNotFound(error)) {
+                throw new Error(`${at}: key ${id} could not be revoked; the next apply tries again`);
+            }
+        }
+    }
+    if (deps.bouleAppId) {
+        const appId = deps.bouleAppId;
+        try {
+            const rows = await timed(() => deps.coolify.listEnvs(appId), ms);
+            const gone = rows.filter((e) => !e.is_preview &&
+                e.uuid &&
+                (e.key === FILES_BOULE_KEYS_ENV || e.key === FILES_BOULE_URL_ENV));
+            for (const row of gone) {
+                await timed(() => deps.coolify.deleteEnv(appId, row.uuid), ms);
+            }
+            if (gone.length > 0)
+                await timed(() => deps.coolify.restart(appId), ms);
+        }
+        catch {
+            throw new Error(`${at}: the key is revoked but could not be taken out of Boule's env; the next apply tries again`);
+        }
+    }
+    for (const name of [
+        FILES_BOULE_KEY_SCOPE_KEY,
+        FILES_BOULE_UNDELIVERED_SCOPE_KEY,
+        FILES_BOULE_MINTER_SCOPE_KEY,
+        FILES_BOULE_EXPIRES_SCOPE_KEY,
+        FILES_BOULE_APPLIED_SCOPE_KEY,
+        FILES_BOULE_PREVIOUS_SCOPE_KEY,
+    ]) {
+        deps.forget(name);
+    }
+}

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

@@ -0,0 +1,92 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+export { entryCollectionName, entryCollectionNames, entryFilesCollectionsScopeKey, FILES_BOULE_KEY_SCOPE_KEY, FILES_BOULE_MINTER_SCOPE_KEY, FILES_BOULE_PREVIOUS_SCOPE_KEY, FILES_BOULE_UNDELIVERED_SCOPE_KEY, knownCollectionNames, } from './entry-files-key.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * foundry#1121: Boule's files key, and each app's collections named apart.
+ *
+ * **Boule's key.** Boule's Files page (boule#651) reads one app's report through files' `/v1/manage/report/*`
+ * routes (files#162) and stops its share links. One `files:boule-key` step, keyed by the org id, planned
+ * after Boule and after the entries' own files keys, while any entry declares `uses.files`:
+ *
+ * 1. mints a key below the org's own files key (`issueKeyBelow`, kind `service`) holding
+ *    {@link FILES_BOULE_PERMISSIONS}; files shows it once;
+ * 2. records its id as `files_boule_key_undelivered` and persists it before anything else;
+ * 3. holds the key at `files:boule-key:<orgId>:live` (3 tries), then records the id as `files_boule_key` (the
+ *    held guard), the org key it is below as `files_boule_key_minter` and its expiry, and persists them;
+ * 4. writes `FILES_URL` and `FILES_BOULE_KEYS` (JSON, see {@link FilesBouleKeys}) to Boule's env and restarts
+ *    Boule;
+ * 5. only then clears the undelivered marker, records what it wrote as `files_boule_key_applied` (no key in
+ *    it) and revokes the key it replaced.
+ *
+ * A marker equal to the guard is a delivery that did not finish: the step is planned again and reuses the held
+ * key. A marker without it (minted, never held) is blocked and never minted again. A guard whose held value is
+ * gone is repaired by the step itself: that key is revoked first, then a new one is minted. A renewal (under 30
+ * days left, or below an org key that was replaced) moves the guard to `files_boule_key_previous` and persists
+ * that before it mints, so the old key stays in Boule's env until the new one is written, and is revoked after.
+ * The org key's own `revoke-previous` waits until Boule's key is below the new org key too.
+ *
+ * Removing the last `uses.files` plans the retire form (`destroys: true`): revoke the key (held, or minted and
+ * never held), take both names out of Boule's env, restart Boule, clear the records. The held value stays (the
+ * held store has no delete); it is never read again without a guard.
+ *
+ * **Collections per app.** files makes a collection by name, so two entries declaring `INVOICES` used to share
+ * one and read each other's files. A collection is now named `<entry key>.<LABEL>` (an entry key holds no
+ * `.`, a label holds none either, so two apps never get one name). A collection an entry already had keeps
+ * its old name, so its files stay where they are: the first apply after this reads the labels the entry's
+ * last applied marker names and keeps each as its own name. The names are recorded per entry as
+ * `files_entry_collections_<entry>` (JSON, label to name, every name the entry ever had, so a label removed
+ * and declared again comes back to its files). The app's env is unchanged (`FILES_COLLECTION_<LABEL>_ID` holds
+ * the collection's id); Boule gets the label-to-name map per app in `FILES_BOULE_KEYS`.
+ *
+ * **Not here: the workspace copy.** files has no notion of a copy, and foundry gives each workspace an
+ * organisation of its own per entry (`<org id>-stage-<entry>`, stage services), holding no collections (stage
+ * keeps none of production's `FILES_COLLECTION_*`). There is no one workspace organisation for Boule's `work`
+ * key to read, so `FILES_BOULE_KEYS` carries `live` only.
+ *
+ * The key reaches the held keys and Boule's env and nothing else: not a plan, a log, an error or a recorded id.
+ */
+/** What Boule's key holds: read the reports (`files.usage:read`, `files.files:read`, `files.shares:read`) and stop a share (`files.files:share`). */
+export declare const FILES_BOULE_PERMISSIONS: readonly ["files.usage:read", "files.files:read", "files.shares:read", "files.files:share"];
+/** Boule's env names. */
+export declare const FILES_BOULE_KEYS_ENV = "FILES_BOULE_KEYS";
+export declare const FILES_BOULE_URL_ENV = "FILES_URL";
+/** The ISO time Boule's key expires. */
+export declare const FILES_BOULE_EXPIRES_SCOPE_KEY = "files_boule_key_expires";
+/** What Boule's env was last written with (`{ url, apps }`); never a key. */
+export declare const FILES_BOULE_APPLIED_SCOPE_KEY = "files_boule_key_applied";
+/** Ids of replaced Boule keys whose revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export declare const FILES_BOULE_UNREVOKED_SCOPE_KEY = "files_boule_key_unrevoked";
+/** The held-key ref of Boule's key for the company's own files organisation. */
+export declare const filesBouleKeyRef: (orgId: string) => string;
+export declare const filesBouleKeyName: (org: DeclaredOrg) => string;
+/**
+ * `FILES_BOULE_KEYS` as Boule reads it: one entry per copy. `apps` is, per entry key, the app's collections,
+ * label to the collection's name in files (pass the names as `collection=`).
+ */
+export interface FilesBouleKeys {
+    live: {
+        organisationId: string;
+        key: string;
+        apps: Record<string, Record<string, string>>;
+    };
+}
+export interface FilesBouleWant {
+    url: string;
+    organisationId: string;
+    apps: Record<string, Record<string, string>>;
+}
+export type FilesBouleMode = 'mint' | 'renew' | 'deliver' | 'retire';
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * Boule's key step, or nothing. Blocked, not planned (rule 2), while the held keys cannot hold the key, files'
+ * address is not recorded, Boule or the org's own files key is not recorded or planned, or after a mint whose
+ * key was never held: a second mint would leave two live keys.
+ */
+export declare function planFilesBouleKey(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};

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

@@ -0,0 +1,175 @@
+import { FILES_BOULE_KEY_SCOPE_KEY, FILES_BOULE_MINTER_SCOPE_KEY, FILES_BOULE_PREVIOUS_SCOPE_KEY, FILES_BOULE_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, entryCollectionNames, parseIdList, } from './entry-files-key.js';
+export { entryCollectionName, entryCollectionNames, entryFilesCollectionsScopeKey, FILES_BOULE_KEY_SCOPE_KEY, FILES_BOULE_MINTER_SCOPE_KEY, FILES_BOULE_PREVIOUS_SCOPE_KEY, FILES_BOULE_UNDELIVERED_SCOPE_KEY, knownCollectionNames, } from './entry-files-key.js';
+/**
+ * foundry#1121: Boule's files key, and each app's collections named apart.
+ *
+ * **Boule's key.** Boule's Files page (boule#651) reads one app's report through files' `/v1/manage/report/*`
+ * routes (files#162) and stops its share links. One `files:boule-key` step, keyed by the org id, planned
+ * after Boule and after the entries' own files keys, while any entry declares `uses.files`:
+ *
+ * 1. mints a key below the org's own files key (`issueKeyBelow`, kind `service`) holding
+ *    {@link FILES_BOULE_PERMISSIONS}; files shows it once;
+ * 2. records its id as `files_boule_key_undelivered` and persists it before anything else;
+ * 3. holds the key at `files:boule-key:<orgId>:live` (3 tries), then records the id as `files_boule_key` (the
+ *    held guard), the org key it is below as `files_boule_key_minter` and its expiry, and persists them;
+ * 4. writes `FILES_URL` and `FILES_BOULE_KEYS` (JSON, see {@link FilesBouleKeys}) to Boule's env and restarts
+ *    Boule;
+ * 5. only then clears the undelivered marker, records what it wrote as `files_boule_key_applied` (no key in
+ *    it) and revokes the key it replaced.
+ *
+ * A marker equal to the guard is a delivery that did not finish: the step is planned again and reuses the held
+ * key. A marker without it (minted, never held) is blocked and never minted again. A guard whose held value is
+ * gone is repaired by the step itself: that key is revoked first, then a new one is minted. A renewal (under 30
+ * days left, or below an org key that was replaced) moves the guard to `files_boule_key_previous` and persists
+ * that before it mints, so the old key stays in Boule's env until the new one is written, and is revoked after.
+ * The org key's own `revoke-previous` waits until Boule's key is below the new org key too.
+ *
+ * Removing the last `uses.files` plans the retire form (`destroys: true`): revoke the key (held, or minted and
+ * never held), take both names out of Boule's env, restart Boule, clear the records. The held value stays (the
+ * held store has no delete); it is never read again without a guard.
+ *
+ * **Collections per app.** files makes a collection by name, so two entries declaring `INVOICES` used to share
+ * one and read each other's files. A collection is now named `<entry key>.<LABEL>` (an entry key holds no
+ * `.`, a label holds none either, so two apps never get one name). A collection an entry already had keeps
+ * its old name, so its files stay where they are: the first apply after this reads the labels the entry's
+ * last applied marker names and keeps each as its own name. The names are recorded per entry as
+ * `files_entry_collections_<entry>` (JSON, label to name, every name the entry ever had, so a label removed
+ * and declared again comes back to its files). The app's env is unchanged (`FILES_COLLECTION_<LABEL>_ID` holds
+ * the collection's id); Boule gets the label-to-name map per app in `FILES_BOULE_KEYS`.
+ *
+ * **Not here: the workspace copy.** files has no notion of a copy, and foundry gives each workspace an
+ * organisation of its own per entry (`<org id>-stage-<entry>`, stage services), holding no collections (stage
+ * keeps none of production's `FILES_COLLECTION_*`). There is no one workspace organisation for Boule's `work`
+ * key to read, so `FILES_BOULE_KEYS` carries `live` only.
+ *
+ * The key reaches the held keys and Boule's env and nothing else: not a plan, a log, an error or a recorded id.
+ */
+/** What Boule's key holds: read the reports (`files.usage:read`, `files.files:read`, `files.shares:read`) and stop a share (`files.files:share`). */
+export const FILES_BOULE_PERMISSIONS = [
+    'files.usage:read',
+    'files.files:read',
+    'files.shares:read',
+    'files.files:share',
+];
+/** Boule's env names. */
+export const FILES_BOULE_KEYS_ENV = 'FILES_BOULE_KEYS';
+export const FILES_BOULE_URL_ENV = 'FILES_URL';
+/** The ISO time Boule's key expires. */
+export const FILES_BOULE_EXPIRES_SCOPE_KEY = 'files_boule_key_expires';
+/** What Boule's env was last written with (`{ url, apps }`); never a key. */
+export const FILES_BOULE_APPLIED_SCOPE_KEY = 'files_boule_key_applied';
+/** Ids of replaced Boule keys whose revoke failed, as a JSON array. They expire on their own; the plan lists each. */
+export const FILES_BOULE_UNREVOKED_SCOPE_KEY = 'files_boule_key_unrevoked';
+/** The held-key ref of Boule's key for the company's own files organisation. */
+export const filesBouleKeyRef = (orgId) => `files:boule-key:${orgId}:live`;
+export const filesBouleKeyName = (org) => `${org.slug}-boule-files`;
+/**
+ * Boule's key step, or nothing. Blocked, not planned (rule 2), while the held keys cannot hold the key, files'
+ * address is not recorded, Boule or the org's own files key is not recorded or planned, or after a mint whose
+ * key was never held: a second mint would leave two live keys.
+ */
+export function planFilesBouleKey(org, recordedIds, plannedSteps, readiness, now) {
+    const steps = [];
+    const blocked = [];
+    const key = `files:boule-key:${org.id}`;
+    const at = `${org.slug}'s Boule files key`;
+    const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+    const planned = (system, kind, k) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === k);
+    for (const id of parseIdList(recordedIds[FILES_BOULE_UNREVOKED_SCOPE_KEY])) {
+        blocked.push({
+            description: `warning: ${org.slug}'s replaced Boule files key ${id} stays live until it expires; its revoke failed`,
+            key: `${key}:unrevoked:${id}`,
+        });
+    }
+    const entries = org.hosting.enabled ? org.hosting.entries.filter((e) => e.uses?.files) : [];
+    const undelivered = recordedIds[FILES_BOULE_UNDELIVERED_SCOPE_KEY];
+    const guard = recordedIds[FILES_BOULE_KEY_SCOPE_KEY];
+    const previous = parseIdList(recordedIds[FILES_BOULE_PREVIOUS_SCOPE_KEY]);
+    if (entries.length === 0) {
+        if (!readiness.filesReady)
+            return { steps, blocked };
+        if (guard || undelivered || previous.length > 0) {
+            steps.push({
+                action: { system: 'files', kind: 'boule-key', key: org.id, desired: { mode: 'retire' } },
+                step: {
+                    description: `revoke Boule's files key for ${org.slug} and take FILES_URL and FILES_BOULE_KEYS out of Boule's env, restart Boule: no entry uses files`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+        return { steps, blocked };
+    }
+    // `files:organisation` and the org key's own item report a files host that is not ready.
+    if (!readiness.filesReady)
+        return { steps, blocked };
+    if (undelivered && undelivered !== guard) {
+        block(`key ${undelivered} was minted but never held, and files shows a key once; revoke it in files and remove the recorded key ${FILES_BOULE_UNDELIVERED_SCOPE_KEY}`);
+        return { steps, blocked };
+    }
+    if (readiness.canHoldSecrets !== true) {
+        block("the host's held keys cannot hold Boule's key");
+        return { steps, blocked };
+    }
+    if (!readiness.filesUrl) {
+        block("the platform has not recorded files' address yet");
+        return { steps, blocked };
+    }
+    if (!recordedIds[`coolify:boule:${org.id}`] && !planned('coolify', 'boule', org.id)) {
+        block("the company's Boule is not recorded yet");
+        return { steps, blocked };
+    }
+    const rootKeyId = recordedIds[`files:key:${org.id}`];
+    const rootPlanned = plannedSteps.find((p) => p.action.system === 'files' && p.action.kind === 'key' && p.action.key === org.id);
+    const rootMode = rootPlanned?.action.desired?.mode;
+    const rootRenewing = rootMode === 'renew';
+    if (!rootKeyId && rootMode !== 'mint') {
+        block("the org's own files key is not recorded yet");
+        return { steps, blocked };
+    }
+    const want = {
+        url: readiness.filesUrl,
+        organisationId: org.id,
+        apps: Object.fromEntries(entries.map((e) => [e.key, entryCollectionNames(e, recordedIds)])),
+    };
+    let mode = null;
+    if (!guard) {
+        mode = 'mint';
+    }
+    else if (rootRenewing ||
+        recordedIds[FILES_BOULE_MINTER_SCOPE_KEY] !== rootKeyId ||
+        !(Date.parse(recordedIds[FILES_BOULE_EXPIRES_SCOPE_KEY] ?? '') - now >=
+            FILES_KEY_RENEW_WINDOW_DAYS * DAY_MS)) {
+        mode = 'renew';
+    }
+    else if (undelivered === guard ||
+        previous.length > 0 ||
+        recordedIds[FILES_BOULE_APPLIED_SCOPE_KEY] !== JSON.stringify(want)) {
+        mode = 'deliver';
+    }
+    if (!mode)
+        return { steps, blocked };
+    steps.push({
+        action: {
+            system: 'files',
+            kind: 'boule-key',
+            key: org.id,
+            desired: {
+                mode,
+                name: filesBouleKeyName(org),
+                expiresDays: FILES_KEY_DAYS,
+                permissions: [...FILES_BOULE_PERMISSIONS],
+                ...want,
+            },
+        },
+        step: {
+            description: mode === 'deliver'
+                ? `write Boule's files key for ${org.slug} and its apps' collections to Boule's FILES_BOULE_KEYS, restart Boule`
+                : `${mode === 'mint' ? 'mint' : 'renew'} Boule's files key for ${org.slug} below the org's own key, hold it, write FILES_URL and FILES_BOULE_KEYS to Boule's env, restart Boule`,
+            destroys: false,
+            migrates: false,
+        },
+    });
+    return { steps, blocked };
+}
+const DAY_MS = 24 * 60 * 60 * 1000;

package/dist/plan/hostnames.js

@@ -4,6 +4,7 @@ import { workerAppHostnameOf } from '../worker-app-config.js';
 import { agoraHostnameFor } from './agora.js';
 import { analyticsHostnameFor, analyticsWanted } from './analytics.js';
 import { bouleHostnameFor } from './boule.js';
+import { reportingHostnameFor, reportingWanted } from './reporting.js';
 import { workspaceWorkerParent } from './workspace-worker.js';
 /**
  * The full names an entry is served at. With `hosting.usesDomain` off, or no
@@ -158,6 +159,9 @@ export function tunnelIngressHostnames(org, loginHost = null) {
         // The analytics backend's route, only while something uses it.
         if (analyticsWanted(org))
             hostnames.push(analyticsHostnameFor(org));
+        // The reporting backend's route, the same way.
+        if (reportingWanted(org))
+            hostnames.push(reportingHostnameFor(org));
     }
     const share = filesShareHostname(org);
     if (share)

package/dist/plan/index.d.ts

@@ -1,6 +1,10 @@
 export type { KeysRegistrarPort } from './keys-registrar.js';
 export type { AnalyticsPort } from './analytics.js';
 export { httpAnalytics } from './analytics.js';
+export type { ReportingPort } from './reporting.js';
+export { httpReporting } from './reporting.js';
+export { httpRegistrarApi } from './registered-app.js';
+export type { RegistrarApiPort } from './registered-app.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail, OrgPostgresPlan } from './diff.js';

package/dist/plan/index.js

@@ -1,4 +1,6 @@
 export { httpAnalytics } from './analytics.js';
+export { httpReporting } from './reporting.js';
+export { httpRegistrarApi } from './registered-app.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export { stepSystemOf } from './step-system.js';

package/dist/plan/jobs-scheduler-http.d.ts

@@ -26,6 +26,19 @@ export declare class HttpJobsSchedulerClient implements JobsSchedulerPort {
         secret?: string;
         syncKey?: string;
     }>;
+    /**
+     * foundry#1119: `POST /admin/projects/<name>/keys` (jobs#79). Answers `201 { id, key, ... }`, the key shown
+     * once. A refusal throws with the status only: no response text reaches the error.
+     */
+    mintProjectKey(project: string, grant: {
+        principal: string;
+        scopes: readonly string[];
+    }): Promise<{
+        id: string;
+        key: string;
+    }>;
+    /** `DELETE /admin/projects/<name>/keys/<id>`. A refusal throws with the status only (404: no such key). */
+    revokeProjectKey(project: string, keyId: string): Promise<void>;
     /** `DELETE /admin/projects/<name>`. A refusal throws with the status only. */
     deleteProject(name: string): Promise<void>;
 }