@wtfalch/foundry 0.76.0 → 0.77.0

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

@@ -12,11 +12,17 @@ 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. */
+/**
+ * What the org's own key holds: it mints and revokes, and holds what its entries and Boule's key may hold
+ * (foundry#1121: `files.usage:read`, `files.shares:read` and `files.files:share` for Boule's Files page).
+ */
 export const FILES_ROOT_PERMISSIONS = [
     'credentials:create',
     'credentials:revoke',
     ...FILES_ENTRY_PERMISSIONS,
+    'files.usage:read',
+    'files.shares:read',
+    'files.files:share',
 ];
 /**
  * Flat scope ids (no `:`). The org's own key: the id minted last (it blocks
@@ -25,6 +31,12 @@ export const FILES_ROOT_PERMISSIONS = [
  */
 export const FILES_ROOT_UNDELIVERED_SCOPE_KEY = 'files_key_undelivered';
 export const FILES_ROOT_EXPIRES_SCOPE_KEY = 'files_key_expires';
+/**
+ * foundry#1121: the permissions the recorded org key was minted with, as JSON. A key minted before this was
+ * recorded, or with fewer permissions than {@link FILES_ROOT_PERMISSIONS}, is renewed: a key below it can
+ * hold only what it holds.
+ */
+export const FILES_ROOT_PERMISSIONS_SCOPE_KEY = 'files_key_permissions';
 /** 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. */
@@ -52,6 +64,72 @@ export const entryFilesRetiredScopeKey = (entryKey) => `files_entry_retired_${en
 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_';
+/** foundry#1121 (`files-boule-key.ts`). Boule's key is minted, not held yet: its id, never the key. */
+export const FILES_BOULE_UNDELIVERED_SCOPE_KEY = 'files_boule_key_undelivered';
+/** The id of Boule's key once it is held. */
+export const FILES_BOULE_KEY_SCOPE_KEY = 'files_boule_key';
+/** The id of the org's own files key Boule's key was minted below. */
+export const FILES_BOULE_MINTER_SCOPE_KEY = 'files_boule_key_minter';
+/** Ids of Boule keys a renewal replaced, as a JSON array, revoked once the new one is in Boule's env. */
+export const FILES_BOULE_PREVIOUS_SCOPE_KEY = 'files_boule_key_previous';
+/** Per entry: label to collection name in files, every name the entry ever had. */
+export const entryFilesCollectionsScopeKey = (entryKey) => `files_entry_collections_${entryKey}`;
+/** The name a new collection of an entry gets in files. */
+export const entryCollectionName = (entryKey, label) => `${entryKey}.${label}`;
+function parseNames(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const out = {};
+        for (const [label, name] of Object.entries(parsed)) {
+            if (typeof name === 'string' && name)
+                out[label] = name;
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every collection name the entry has had, label to name: the recorded map, or, before one is recorded, each
+ * label of the entry's last applied files marker under its own name (the name files was given before
+ * collections were named per app).
+ */
+export function knownCollectionNames(entryKey, recordedIds) {
+    const recorded = parseNames(recordedIds[entryFilesCollectionsScopeKey(entryKey)]);
+    if (recorded)
+        return recorded;
+    const legacy = {};
+    try {
+        const applied = JSON.parse(recordedIds[entryFilesAppliedScopeKey(entryKey)] ?? '{}');
+        const named = parseNames(JSON.stringify(applied.collectionNames ?? null));
+        if (named)
+            return named;
+        if (Array.isArray(applied.collections)) {
+            for (const label of applied.collections) {
+                if (typeof label === 'string' && label)
+                    legacy[label] = label;
+            }
+        }
+    }
+    catch {
+        // An unreadable marker has no collections to keep.
+    }
+    return legacy;
+}
+/** The files name of each collection the entry declares now, label to name, in the declared order. */
+export function entryCollectionNames(entry, recordedIds) {
+    const known = knownCollectionNames(entry.key, recordedIds);
+    const out = {};
+    for (const label of entry.uses?.files?.collections ?? []) {
+        out[label] = known[label] ?? entryCollectionName(entry.key, label);
+    }
+    return out;
+}
 export function parseIdList(raw) {
     try {
         const parsed = raw ? JSON.parse(raw) : [];
@@ -68,15 +146,29 @@ 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, shareHostname = null) {
+export function wantedEntryFiles(entry, filesUrl, shareHostname = null, recordedIds = {}) {
     const files = entry.uses?.files;
     return {
         permissions: [...(files?.permissions ?? FILES_ENTRY_PERMISSIONS)],
         collections: [...(files?.collections ?? [])],
         filesUrl,
         ...(files?.shareHost && shareHostname ? { shareOrigin: `https://${shareHostname}` } : {}),
+        collectionNames: entryCollectionNames(entry, recordedIds),
     };
 }
+/**
+ * foundry#1121: Boule's files key, when it has one, is below `rootKeyId` and delivered, so revoking the org
+ * key it replaced revokes nothing Boule still uses.
+ */
+export function bouleKeyBelow(recordedIds, rootKeyId) {
+    // A renewal's old key is still in Boule's env until the new one is written.
+    if (parseIdList(recordedIds[FILES_BOULE_PREVIOUS_SCOPE_KEY]).length > 0)
+        return false;
+    if (!recordedIds[FILES_BOULE_KEY_SCOPE_KEY] && !recordedIds[FILES_BOULE_UNDELIVERED_SCOPE_KEY])
+        return true;
+    return (recordedIds[FILES_BOULE_MINTER_SCOPE_KEY] === rootKeyId &&
+        !recordedIds[FILES_BOULE_UNDELIVERED_SCOPE_KEY]);
+}
 /**
  * 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.
@@ -171,9 +263,12 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
     const rootExpires = Date.parse(rootExpiresRaw ?? '');
     const rootShort = Boolean(rootKeyId) &&
         (Number.isNaN(rootExpires) || rootExpires - now < FILES_KEY_RENEW_WINDOW_DAYS * DAY_MS);
+    // foundry#1121: a key minted with fewer permissions than the org key now holds is renewed.
+    const rootNarrow = Boolean(rootKeyId) &&
+        recordedIds[FILES_ROOT_PERMISSIONS_SCOPE_KEY] !== JSON.stringify(FILES_ROOT_PERMISSIONS);
     const rootUndelivered = recordedIds[FILES_ROOT_UNDELIVERED_SCOPE_KEY];
     let rootMode = null;
-    if (!rootKeyId || rootShort) {
+    if (!rootKeyId || rootShort || rootNarrow) {
         const ownerKey = org.owners[0] ? `${org.id}:${org.owners[0].email.toLowerCase()}` : '';
         const orgPlanned = planned('files', 'organisation', org.id);
         if (rootUndelivered && rootUndelivered !== rootKeyId) {
@@ -206,7 +301,9 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
                 },
                 step: {
                     description: rootMode === 'renew'
-                        ? `renew ${org.slug}'s own files key and re-mint its entry keys below it`
+                        ? rootNarrow && !rootShort
+                            ? `renew ${org.slug}'s own files key with the permissions Boule's files key needs, and re-mint its entry keys below it`
+                            : `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,
@@ -241,7 +338,7 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
             block("the entry's app is not recorded yet");
             continue;
         }
-        const want = wantedEntryFiles(entry, readiness.filesUrl, shareHostname);
+        const want = wantedEntryFiles(entry, readiness.filesUrl, shareHostname, recordedIds);
         const applied = recordedIds[entryFilesAppliedScopeKey(entry.key)];
         const wantJson = JSON.stringify(want);
         let mode = null;
@@ -304,7 +401,7 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
         return (recordedIds[`files:key:${stepKey}`] &&
             recordedIds[entryFilesMinterScopeKey(e.key)] === rootKeyId &&
             !recordedIds[entryFilesUndeliveredScopeKey(e.key)]);
-    });
+    }) && bouleKeyBelow(recordedIds, rootKeyId);
     if (rootMode === 'renew' || (previous.length > 0 && consistent)) {
         steps.push({
             action: {

package/dist/plan/entry-jobs-boule-key-apply.d.ts

@@ -0,0 +1,65 @@
+/** Every call this module makes (scheduler, held keys, Coolify) is cut off after this long. */
+export declare const JOBS_BOULE_KEY_CALL_TIMEOUT_MS = 30000;
+/** How many times Boule's key is tried against the held keys. */
+export declare const JOBS_BOULE_KEY_HOLD_ATTEMPTS = 3;
+/** The scheduler's project-key calls (jobs#79), as `JobsSchedulerPort` offers them. */
+export interface JobsProjectKeysPort {
+    mintProjectKey(project: string, grant: {
+        principal: string;
+        scopes: readonly string[];
+    }): Promise<{
+        id: string;
+        key: string;
+    }>;
+    /** Revokes one key; a key or project the scheduler does not know throws with `status: 404`. */
+    revokeProjectKey(project: string, keyId: string): Promise<void>;
+}
+export interface JobsBouleKeyDeps {
+    scheduler: JobsProjectKeysPort;
+    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;
+    };
+    entryKey: string;
+    /** The scheduler's name for the entry's project, `<slug>-<entry>`. */
+    project: 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;
+    timeoutMs?: number;
+}
+/**
+ * Mints (or reuses the held) key for one entry's project and puts it in Boule's `JOBS_PROJECTS` at `url`.
+ * See `entry-jobs-boule-key.ts` for the order. Errors name the project, the key id and the ref, never the key.
+ */
+export declare function ensureJobsBouleKey(deps: JobsBouleKeyDeps, url: string): Promise<void>;
+/**
+ * Revokes Boule's key for an entry that no longer uses jobs (a held one, or one minted and never held), takes
+ * the entry out of `JOBS_PROJECTS` and restarts Boule, then clears the records. A key the scheduler no longer
+ * knows counts as revoked.
+ */
+export declare function retireJobsBouleKey(deps: JobsBouleKeyDeps): Promise<void>;

package/dist/plan/entry-jobs-boule-key-apply.js

@@ -0,0 +1,192 @@
+import { JOBS_BOULE_KEY_GRANT, JOBS_PROJECTS_ENV, jobsBouleKeyAppliedScopeKey, jobsBouleKeyRef, jobsBouleKeyScopeKey, jobsBouleKeyUndeliveredScopeKey, } from './entry-jobs-boule-key.js';
+/** Every call this module makes (scheduler, held keys, Coolify) is cut off after this long. */
+export const JOBS_BOULE_KEY_CALL_TIMEOUT_MS = 30_000;
+/** How many times Boule's key is tried against the held keys. */
+export const JOBS_BOULE_KEY_HOLD_ATTEMPTS = 3;
+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 isNotFound = (error) => error?.status === 404;
+/** Boule's `JOBS_PROJECTS` as it is now, keeping only well-formed entries; every key in it is registered for redaction. */
+async function readProjects(deps, appId, at, ms) {
+    let rows;
+    try {
+        rows = await timed(() => deps.coolify.listEnvs(appId), ms);
+    }
+    catch {
+        throw new Error(`${at}: Boule's env could not be read`);
+    }
+    const row = rows.find((e) => e.key === JOBS_PROJECTS_ENV && !e.is_preview);
+    const projects = {};
+    if (row?.value) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.value);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            for (const [entry, value] of Object.entries(parsed)) {
+                const v = value;
+                if (v && typeof v.url === 'string' && typeof v.key === 'string') {
+                    deps.secret(v.key);
+                    projects[entry] = { url: v.url, key: v.key };
+                }
+            }
+        }
+    }
+    return { projects, uuid: row?.uuid };
+}
+/** Writes `JOBS_PROJECTS` (or removes the row when it is empty) and restarts Boule. The error is fixed text. */
+async function writeProjects(deps, appId, projects, uuid, at, ms, failure) {
+    try {
+        if (Object.keys(projects).length > 0) {
+            await timed(() => deps.coolify.bulkUpsertEnvs(appId, [
+                { key: JOBS_PROJECTS_ENV, value: JSON.stringify(projects), literal: true },
+            ]), ms);
+        }
+        else if (uuid) {
+            await timed(() => deps.coolify.deleteEnv(appId, uuid), ms);
+        }
+        await timed(() => deps.coolify.restart(appId), ms);
+    }
+    catch {
+        // The error is dropped in case Coolify echoes the request body, which holds keys.
+        throw new Error(`${at}: ${failure}`);
+    }
+}
+/**
+ * Mints (or reuses the held) key for one entry's project and puts it in Boule's `JOBS_PROJECTS` at `url`.
+ * See `entry-jobs-boule-key.ts` for the order. Errors name the project, the key id and the ref, never the key.
+ */
+export async function ensureJobsBouleKey(deps, url) {
+    const ms = deps.timeoutMs ?? JOBS_BOULE_KEY_CALL_TIMEOUT_MS;
+    const at = `jobs:boule-key for ${deps.org.slug} entry '${deps.entryKey}'`;
+    const ref = jobsBouleKeyRef(deps.org.id, deps.entryKey);
+    const undeliveredKey = jobsBouleKeyUndeliveredScopeKey(deps.entryKey);
+    const guardKey = jobsBouleKeyScopeKey(deps.entryKey);
+    if (!deps.bouleAppId)
+        throw new Error(`${at}: Boule is not recorded yet`);
+    const recorded = deps.recorded();
+    const undelivered = recorded[undeliveredKey];
+    let guard = recorded[guardKey];
+    if (undelivered && undelivered !== guard) {
+        throw new Error(`${at}: key ${undelivered} was minted but never held, and the scheduler shows a key once; revoke it (DELETE /admin/projects/${deps.project}/keys/${undelivered}) and remove the recorded key ${undeliveredKey}`);
+    }
+    let key = null;
+    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.scheduler.revokeProjectKey(deps.project, 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(guardKey);
+            deps.forget(undeliveredKey);
+            await deps.persist();
+            guard = undefined;
+        }
+    }
+    if (!key) {
+        let minted;
+        try {
+            minted = await timed(() => deps.scheduler.mintProjectKey(deps.project, {
+                principal: JOBS_BOULE_KEY_GRANT.principal,
+                scopes: [...JOBS_BOULE_KEY_GRANT.scopes],
+            }), ms);
+        }
+        catch (error) {
+            const status = error?.status;
+            throw new Error(`${at}: the scheduler refused or did not answer the key for project ${deps.project}${typeof status === 'number' ? ` (${status})` : ''}`);
+        }
+        if (typeof minted?.key === 'string' && minted.key)
+            deps.secret(minted.key);
+        if (typeof minted?.id !== 'string' || !minted.id) {
+            throw new Error(`${at}: the scheduler answered the key for project ${deps.project} with no id`);
+        }
+        deps.record(undeliveredKey, minted.id);
+        await deps.persist();
+        if (typeof minted.key !== 'string' || !minted.key) {
+            throw new Error(`${at}: key ${minted.id} was minted but the scheduler returned no key, which it shows once; revoke it (DELETE /admin/projects/${deps.project}/keys/${minted.id}) and remove the recorded key ${undeliveredKey}`);
+        }
+        let stored = false;
+        for (let attempt = 1; attempt <= JOBS_BOULE_KEY_HOLD_ATTEMPTS && !stored; attempt++) {
+            try {
+                await timed(() => deps.heldKeys.put(ref, minted.key), 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 ${JOBS_BOULE_KEY_HOLD_ATTEMPTS} attempts; revoke it (DELETE /admin/projects/${deps.project}/keys/${minted.id}) and remove the recorded key ${undeliveredKey}`);
+        }
+        deps.record(guardKey, minted.id);
+        await deps.persist();
+        key = minted.key;
+    }
+    const { projects, uuid } = await readProjects(deps, deps.bouleAppId, at, ms);
+    projects[deps.entryKey] = { url, key };
+    await writeProjects(deps, deps.bouleAppId, projects, uuid, at, ms, `the key is held at ${ref} but could not be written to Boule's env; the next apply writes it again`);
+    deps.forget(undeliveredKey);
+    deps.record(jobsBouleKeyAppliedScopeKey(deps.entryKey), url);
+}
+/**
+ * Revokes Boule's key for an entry that no longer uses jobs (a held one, or one minted and never held), takes
+ * the entry out of `JOBS_PROJECTS` and restarts Boule, then clears the records. A key the scheduler no longer
+ * knows counts as revoked.
+ */
+export async function retireJobsBouleKey(deps) {
+    const ms = deps.timeoutMs ?? JOBS_BOULE_KEY_CALL_TIMEOUT_MS;
+    const at = `jobs:boule-key for ${deps.org.slug} entry '${deps.entryKey}'`;
+    const undeliveredKey = jobsBouleKeyUndeliveredScopeKey(deps.entryKey);
+    const guardKey = jobsBouleKeyScopeKey(deps.entryKey);
+    const recorded = deps.recorded();
+    const ids = [...new Set([recorded[guardKey], recorded[undeliveredKey]].filter(Boolean))];
+    for (const id of ids) {
+        try {
+            await timed(() => deps.scheduler.revokeProjectKey(deps.project, id), ms);
+        }
+        catch (error) {
+            if (!isNotFound(error)) {
+                throw new Error(`${at}: key ${id} of project ${deps.project} could not be revoked; the next apply tries again`);
+            }
+        }
+    }
+    if (deps.bouleAppId) {
+        const { projects, uuid } = await readProjects(deps, deps.bouleAppId, at, ms);
+        if (deps.entryKey in projects) {
+            delete projects[deps.entryKey];
+            await writeProjects(deps, deps.bouleAppId, projects, uuid, at, ms, "the key is revoked but could not be taken out of Boule's env; the next apply tries again");
+        }
+    }
+    deps.forget(guardKey);
+    deps.forget(undeliveredKey);
+    deps.forget(jobsBouleKeyAppliedScopeKey(deps.entryKey));
+}

package/dist/plan/entry-jobs-boule-key.d.ts

@@ -0,0 +1,59 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * foundry#1119: Boule's key for one `uses.jobs` entry's project. Boule's Jobs page (boule#651) reads and
+ * presses one app's jobs through the scheduler's `/project/*` routes (jobs#79) with a key scoped to that
+ * project. One `jobs:boule-key` step per entry, keyed `<orgId>:<entry>`, after the entry's `jobs:project`:
+ *
+ * 1. mints `{ principal: 'boule', scopes: ['jobs:read', 'jobs:control'] }` through
+ *    `POST /admin/projects/<slug>-<entry>/keys`, which shows the key once;
+ * 2. records its id as `jobs_boule_key_undelivered.<entry>` and persists it before anything else;
+ * 3. holds the key at `jobs:project:<orgId>:<entry>:bouleKey` (3 tries), then records the id as
+ *    `jobs_boule_key.<entry>` (the held guard) and persists it;
+ * 4. sets the entry in Boule's `JOBS_PROJECTS` (JSON: entry key to `{ url, key }`, `url` the scheduler's
+ *    public origin) and restarts Boule;
+ * 5. only then clears the undelivered marker and records the address as `jobs_boule_key_applied.<entry>`.
+ *
+ * A marker with the held guard equal to it 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 held guard
+ * whose held value is gone is repaired by the step itself: the old key is revoked first, then a new one is
+ * minted the same way, so at most one key of Boule's is live per project.
+ *
+ * Removing `uses.jobs` (or the entry) plans the retire form: revoke the key (`DELETE …/keys/<id>`), a delivered
+ * one or one minted and never held, take the entry out of `JOBS_PROJECTS`, restart Boule, clear the records.
+ * The held value stays (the held store has no delete); it is never read again without a recorded guard.
+ *
+ * The key reaches the held keys and Boule's env and nothing else: not a plan, a log, an error or a recorded id.
+ */
+/** Boule's key is minted, not held yet: its id, never the key. */
+export declare const jobsBouleKeyUndeliveredScopeKey: (entryKey: string) => string;
+/** The id of Boule's key once it is held. */
+export declare const jobsBouleKeyScopeKey: (entryKey: string) => string;
+/** The scheduler address Boule's env was last written with for the entry; a change writes again. */
+export declare const jobsBouleKeyAppliedScopeKey: (entryKey: string) => string;
+/** The held-key ref of Boule's key for an entry's project. */
+export declare const jobsBouleKeyRef: (orgId: string, entryKey: string) => string;
+/** Boule's env name: JSON, entry key to `{ url, key }`. */
+export declare const JOBS_PROJECTS_ENV = "JOBS_PROJECTS";
+/** What Boule's key is minted as. */
+export declare const JOBS_BOULE_KEY_GRANT: {
+    readonly principal: "boule";
+    readonly scopes: readonly ["jobs:read", "jobs:control"];
+};
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * Mint or deliver one step per `uses.jobs` entry whose key is not in Boule's env at the scheduler's current
+ * address; retire one per entry that no longer declares it and still has a key recorded. Blocked, not planned
+ * (rule 2), while the host's scheduler port has no key calls (`projectKeys`), the held keys cannot hold the
+ * key, the scheduler's public address is not recorded, Boule is not recorded or planned, or the entry's project
+ * is not registered or planned.
+ */
+export declare function planEntryJobsBouleKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, projectKeys: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/entry-jobs-boule-key.js

@@ -0,0 +1,141 @@
+import { entryJobsAppliedScopeKey, entryJobsProjectName } from './entry-jobs.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * foundry#1119: Boule's key for one `uses.jobs` entry's project. Boule's Jobs page (boule#651) reads and
+ * presses one app's jobs through the scheduler's `/project/*` routes (jobs#79) with a key scoped to that
+ * project. One `jobs:boule-key` step per entry, keyed `<orgId>:<entry>`, after the entry's `jobs:project`:
+ *
+ * 1. mints `{ principal: 'boule', scopes: ['jobs:read', 'jobs:control'] }` through
+ *    `POST /admin/projects/<slug>-<entry>/keys`, which shows the key once;
+ * 2. records its id as `jobs_boule_key_undelivered.<entry>` and persists it before anything else;
+ * 3. holds the key at `jobs:project:<orgId>:<entry>:bouleKey` (3 tries), then records the id as
+ *    `jobs_boule_key.<entry>` (the held guard) and persists it;
+ * 4. sets the entry in Boule's `JOBS_PROJECTS` (JSON: entry key to `{ url, key }`, `url` the scheduler's
+ *    public origin) and restarts Boule;
+ * 5. only then clears the undelivered marker and records the address as `jobs_boule_key_applied.<entry>`.
+ *
+ * A marker with the held guard equal to it 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 held guard
+ * whose held value is gone is repaired by the step itself: the old key is revoked first, then a new one is
+ * minted the same way, so at most one key of Boule's is live per project.
+ *
+ * Removing `uses.jobs` (or the entry) plans the retire form: revoke the key (`DELETE …/keys/<id>`), a delivered
+ * one or one minted and never held, take the entry out of `JOBS_PROJECTS`, restart Boule, clear the records.
+ * The held value stays (the held store has no delete); it is never read again without a recorded guard.
+ *
+ * The key reaches the held keys and Boule's env and nothing else: not a plan, a log, an error or a recorded id.
+ */
+/** Boule's key is minted, not held yet: its id, never the key. */
+export const jobsBouleKeyUndeliveredScopeKey = (entryKey) => `jobs_boule_key_undelivered.${entryKey}`;
+/** The id of Boule's key once it is held. */
+export const jobsBouleKeyScopeKey = (entryKey) => `jobs_boule_key.${entryKey}`;
+/** The scheduler address Boule's env was last written with for the entry; a change writes again. */
+export const jobsBouleKeyAppliedScopeKey = (entryKey) => `jobs_boule_key_applied.${entryKey}`;
+/** The held-key ref of Boule's key for an entry's project. */
+export const jobsBouleKeyRef = (orgId, entryKey) => `jobs:project:${orgId}:${entryKey}:bouleKey`;
+/** Boule's env name: JSON, entry key to `{ url, key }`. */
+export const JOBS_PROJECTS_ENV = 'JOBS_PROJECTS';
+/** What Boule's key is minted as. */
+export const JOBS_BOULE_KEY_GRANT = {
+    principal: 'boule',
+    scopes: ['jobs:read', 'jobs:control'],
+};
+const usesJobs = (entry) => entry.uses?.jobs === true;
+/**
+ * Mint or deliver one step per `uses.jobs` entry whose key is not in Boule's env at the scheduler's current
+ * address; retire one per entry that no longer declares it and still has a key recorded. Blocked, not planned
+ * (rule 2), while the host's scheduler port has no key calls (`projectKeys`), the held keys cannot hold the
+ * key, the scheduler's public address is not recorded, Boule is not recorded or planned, or the entry's project
+ * is not registered or planned.
+ */
+export function planEntryJobsBouleKeys(org, recordedIds, plannedSteps, readiness, projectKeys) {
+    const steps = [];
+    const blocked = [];
+    const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === key);
+    const wanted = new Set(org.hosting.enabled ? org.hosting.entries.filter(usesJobs).map((e) => e.key) : []);
+    // Keys of entries that dropped uses.jobs or are gone: a held one, or one minted and never held.
+    const retiring = new Set();
+    for (const prefix of [jobsBouleKeyScopeKey(''), jobsBouleKeyUndeliveredScopeKey('')]) {
+        for (const [name, id] of Object.entries(recordedIds)) {
+            if (!id || !name.startsWith(prefix))
+                continue;
+            const entryKey = name.slice(prefix.length);
+            if (!entryKey || wanted.has(entryKey) || retiring.has(entryKey))
+                continue;
+            retiring.add(entryKey);
+            const key = `jobs:boule-key:${org.id}:${entryKey}`;
+            if (!projectKeys) {
+                blocked.push({
+                    description: `${org.slug}'s ${entryKey} Boule jobs key is not revoked, not planned: the host's jobs scheduler port cannot revoke project keys`,
+                    key,
+                });
+                continue;
+            }
+            steps.push({
+                action: {
+                    system: 'jobs',
+                    kind: 'boule-key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire', name: entryJobsProjectName(org, entryKey) },
+                },
+                step: {
+                    description: `revoke Boule's key for ${org.slug}'s ${entryKey} jobs and take it out of Boule's JOBS_PROJECTS, restart Boule: the entry no longer uses jobs`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    for (const entryKey of wanted) {
+        const stepKey = appStepKey(org, entryKey);
+        const key = `jobs:boule-key:${stepKey}`;
+        const at = `${org.slug}'s ${entryKey} Boule jobs key`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        const name = entryJobsProjectName(org, entryKey);
+        const undelivered = recordedIds[jobsBouleKeyUndeliveredScopeKey(entryKey)];
+        const held = recordedIds[jobsBouleKeyScopeKey(entryKey)];
+        if (undelivered && undelivered !== held) {
+            block(`key ${undelivered} was minted but never held, and the scheduler shows a key once; revoke it (DELETE /admin/projects/${name}/keys/${undelivered}) and remove the recorded key ${jobsBouleKeyUndeliveredScopeKey(entryKey)}`);
+            continue;
+        }
+        const url = readiness.jobsPublicUrl;
+        if (!undelivered && held && url && recordedIds[jobsBouleKeyAppliedScopeKey(entryKey)] === url)
+            continue;
+        if (!projectKeys) {
+            block("the host's jobs scheduler port cannot mint project keys");
+            continue;
+        }
+        if (readiness.canHoldSecrets !== true) {
+            block("the host's held keys cannot hold Boule's key");
+            continue;
+        }
+        if (!url) {
+            block("the jobs scheduler's public address is not recorded yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:boule:${org.id}`] && !planned('coolify', 'boule', org.id)) {
+            block("the company's Boule is not recorded yet");
+            continue;
+        }
+        if (!recordedIds[entryJobsAppliedScopeKey(entryKey)] && !planned('jobs', 'project', stepKey)) {
+            block("the entry's jobs project is not registered yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'jobs',
+                kind: 'boule-key',
+                key: stepKey,
+                desired: { mode: 'ensure', name, url },
+            },
+            step: {
+                description: held
+                    ? `write Boule's key for ${org.slug}'s ${entryKey} jobs to Boule's JOBS_PROJECTS, restart Boule`
+                    : `mint Boule a key for jobs project ${name}, hold it, write it to Boule's JOBS_PROJECTS, restart Boule`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/entry-jobs.d.ts

@@ -17,6 +17,8 @@ import type { OrgPlatformReadiness } from './platform-org.js';
  * error or a recorded id. A workspace (stage) gets no project: its copy of the app is built without
  * `JOBS_*` (`stage-env.ts`), so a stage never schedules or receives a live job.
  *
+ * Boule's own key for the project (its Jobs page) is the next step, `jobs:boule-key` (`entry-jobs-boule-key.ts`).
+ *
  * Nothing removes the project when the entry drops `uses.jobs`: the admin API can deregister, but the
  * scheduler port has no such call yet, so the project and its held credentials stay until a person
  * deregisters it.