@wtfalch/foundry 0.76.1 → 0.77.0

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

@@ -0,0 +1,65 @@
+import { type AiBouleMode } from './ai-boule-key.js';
+/** Every call this module makes (ai, held keys, Coolify) is cut off after this long. */
+export declare const AI_BOULE_CALL_TIMEOUT_MS = 30000;
+/** How many times Boule's key is tried against the held keys. */
+export declare const AI_BOULE_HOLD_ATTEMPTS = 3;
+/** The ai calls this needs, as `AiOrganisationPort` offers them. */
+export interface AiBouleAiPort {
+    mintNestedKey(input: {
+        organisationId: string;
+        minterKeyId: string;
+        name: string;
+        expiresDays: number;
+        permissions: string[];
+    }): Promise<{
+        organisationId: string;
+        id: string;
+        secret: string;
+        expiresAt: string;
+    }>;
+    /** Optional until ai#157: without it a replaced key stays live until it expires and is listed. */
+    revokeKey?(organisationId: string, keyId: string): Promise<void>;
+}
+export interface AiBouleKeyDeps {
+    ai: AiBouleAiPort;
+    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>;
+        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 `ensureAiBouleKey` is given from the plan. */
+export interface AiBouleStep {
+    mode: AiBouleMode;
+    name: string;
+    expiresDays: number;
+    permissions: string[];
+    url: string;
+    organisationId: string;
+}
+/**
+ * Mints (or reuses the held) Boule key and writes `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY` to Boule's
+ * env. See `ai-boule-key.ts` for the order. Errors name the key id and the ref, never the key.
+ */
+export declare function ensureAiBouleKey(deps: AiBouleKeyDeps, step: AiBouleStep): Promise<void>;

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

@@ -0,0 +1,169 @@
+import { AI_BOULE_APPLIED_SCOPE_KEY, AI_BOULE_CLAMPED_SCOPE_KEY, AI_BOULE_ENV, AI_BOULE_EXPIRES_SCOPE_KEY, AI_BOULE_KEY_SCOPE_KEY, AI_BOULE_MINTER_SCOPE_KEY, AI_BOULE_PREVIOUS_SCOPE_KEY, AI_BOULE_RENEW_WINDOW_DAYS, AI_BOULE_UNDELIVERED_SCOPE_KEY, AI_BOULE_UNREVOKED_SCOPE_KEY, aiBouleKeyRef, parseIds, } from './ai-boule-key.js';
+/** Every call this module makes (ai, held keys, Coolify) is cut off after this long. */
+export const AI_BOULE_CALL_TIMEOUT_MS = 30_000;
+/** How many times Boule's key is tried against the held keys. */
+export const AI_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;
+/** Revokes one key; `false` when the port has no revoke or the call failed (a 404 counts as revoked). */
+async function revoke(deps, id, ms) {
+    const call = deps.ai.revokeKey?.bind(deps.ai);
+    if (!call)
+        return false;
+    try {
+        await timed(() => call(deps.org.id, id), ms);
+        return true;
+    }
+    catch (error) {
+        return isNotFound(error);
+    }
+}
+function listUnrevoked(deps, ids) {
+    if (ids.length === 0)
+        return;
+    const list = parseIds(deps.recorded()[AI_BOULE_UNREVOKED_SCOPE_KEY]);
+    for (const id of ids)
+        if (!list.includes(id))
+            list.push(id);
+    deps.record(AI_BOULE_UNREVOKED_SCOPE_KEY, JSON.stringify(list));
+}
+/**
+ * Mints (or reuses the held) Boule key and writes `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY` to Boule's
+ * env. See `ai-boule-key.ts` for the order. Errors name the key id and the ref, never the key.
+ */
+export async function ensureAiBouleKey(deps, step) {
+    const ms = deps.timeoutMs ?? AI_BOULE_CALL_TIMEOUT_MS;
+    const now = deps.now ?? Date.now;
+    const at = `ai:boule-key for ${deps.org.slug}`;
+    const ref = aiBouleKeyRef(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[AI_BOULE_UNDELIVERED_SCOPE_KEY];
+    const guard = recorded[AI_BOULE_KEY_SCOPE_KEY];
+    if (undelivered && undelivered !== guard) {
+        throw new Error(`${at}: key ${undelivered} was minted but never held, and ai shows a key once; revoke it in ai and remove the recorded key ${AI_BOULE_UNDELIVERED_SCOPE_KEY}`);
+    }
+    const minterKeyId = recorded[`ai: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 = parseIds(recorded[AI_BOULE_PREVIOUS_SCOPE_KEY]);
+        if (!previous.includes(guard))
+            previous.push(guard);
+        deps.record(AI_BOULE_PREVIOUS_SCOPE_KEY, JSON.stringify(previous));
+        deps.forget(AI_BOULE_KEY_SCOPE_KEY);
+        deps.forget(AI_BOULE_UNDELIVERED_SCOPE_KEY);
+        await deps.persist();
+    }
+    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 (or listed) before a new one is minted.
+            if (!(await revoke(deps, guard, ms)))
+                listUnrevoked(deps, [guard]);
+            deps.forget(AI_BOULE_KEY_SCOPE_KEY);
+            deps.forget(AI_BOULE_UNDELIVERED_SCOPE_KEY);
+            await deps.persist();
+        }
+    }
+    if (!key) {
+        if (!minterKeyId)
+            throw new Error(`${at}: the org's own ai key is not recorded yet`);
+        let minted;
+        try {
+            minted = await timed(() => deps.ai.mintNestedKey({
+                organisationId: deps.org.id,
+                minterKeyId,
+                name: step.name,
+                expiresDays: step.expiresDays,
+                permissions: [...step.permissions],
+            }), ms);
+        }
+        catch (error) {
+            throw new Error(`${at}: ai 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}: ai answered the key with no id`);
+        }
+        deps.record(AI_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 ai returned no key, which it shows once; revoke it in ai and remove the recorded key ${AI_BOULE_UNDELIVERED_SCOPE_KEY}`);
+        }
+        let stored = false;
+        for (let attempt = 1; attempt <= AI_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 ${AI_BOULE_HOLD_ATTEMPTS} attempts; revoke it in ai and remove the recorded key ${AI_BOULE_UNDELIVERED_SCOPE_KEY}`);
+        }
+        deps.record(AI_BOULE_KEY_SCOPE_KEY, minted.id);
+        deps.record(AI_BOULE_MINTER_SCOPE_KEY, minterKeyId);
+        deps.record(AI_BOULE_EXPIRES_SCOPE_KEY, minted.expiresAt);
+        // ai clamps the expiry to the org key's: one already inside the window is not renewed below the same key.
+        const clamped = !(Date.parse(minted.expiresAt) - now() >= AI_BOULE_RENEW_WINDOW_DAYS * DAY_MS);
+        deps.record(AI_BOULE_CLAMPED_SCOPE_KEY, clamped ? minterKeyId : '');
+        await deps.persist();
+        key = minted.secret;
+    }
+    try {
+        await timed(() => deps.coolify.bulkUpsertEnvs(bouleAppId, [
+            { key: AI_BOULE_ENV.url, value: step.url, literal: true },
+            { key: AI_BOULE_ENV.organisation, value: step.organisationId, literal: true },
+            { key: AI_BOULE_ENV.key, value: key, 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(AI_BOULE_UNDELIVERED_SCOPE_KEY);
+    deps.record(AI_BOULE_APPLIED_SCOPE_KEY, JSON.stringify({ url: step.url, organisationId: step.organisationId }));
+    // The keys a renewal replaced: Boule no longer holds them.
+    const previous = parseIds(deps.recorded()[AI_BOULE_PREVIOUS_SCOPE_KEY]);
+    if (previous.length > 0) {
+        const left = [];
+        for (const id of previous)
+            if (!(await revoke(deps, id, ms)))
+                left.push(id);
+        listUnrevoked(deps, left);
+        deps.forget(AI_BOULE_PREVIOUS_SCOPE_KEY);
+    }
+}

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

@@ -0,0 +1,89 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * foundry#1122: Boule's ai key. Boule's AI page (boule#651) reads one app's month, days, tasks, runs and budget
+ * through ai's `/v1/apps/:app/*` routes (ai#190) and sets the app's budget, with a key in the company's own ai
+ * organisation. One `ai:boule-key` step, keyed by the org id, after Boule and after the org's own ai key:
+ *
+ * 1. mints a key below the org's own ai key (`ai:key:<orgId>`) through `POST /v1/keys` on the company's behalf
+ *    (`mintNestedKey`), holding {@link AI_BOULE_PERMISSIONS} over the organisation and bound to no app; ai shows
+ *    it once and clamps its expiry to the org key's;
+ * 2. records its id as `ai_boule_key_undelivered` and persists it before anything else;
+ * 3. holds the key at `ai:boule-key:<orgId>` (3 tries), then records the id as `ai_boule_key` (the held guard),
+ *    the org key it is below as `ai_boule_key_minter` and its expiry, and persists them;
+ * 4. writes `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY` to Boule's env and restarts Boule;
+ * 5. only then clears the undelivered marker and records what it wrote as `ai_boule_key_applied` (no key).
+ *
+ * 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 (`revokeKey`, ai#157; without it, or when it
+ * fails, the id is listed as left live), then a new one is minted. A renewal (under 30 days left, or below an
+ * org key that was replaced) moves the guard to `ai_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. A key ai clamped under
+ * the window by the same org key is not renewed again: the plan says the org key must be renewed first.
+ *
+ * **The company's organisation has to offer the five permissions first**, and the org's own key has to hold
+ * them, because a key below it can hold only what it holds. ai marks all five `offered: false` today (ai#170
+ * offers one). So all of it waits for the host's word (`aiBouleReads`): with it, `ai:organisation` offers
+ * {@link aiOffers} (recorded as `ai_offers_applied`), the org key is minted again with them when the recorded
+ * one holds fewer (`ai_key_permissions`), and Boule's key is minted below it. Without it nothing changes and
+ * the plan says why.
+ *
+ * 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 over the company's organisation. */
+export declare const AI_BOULE_PERMISSIONS: readonly ["ai.usage:read", "ai.runs:read", "ai.budgets:read", "ai.budgets:update", "ai.offerings:read"];
+/** What every organisation is offered, and its own key holds, without Boule's reads. */
+export declare const AI_DEFAULT_OFFERS: readonly ["ai.offerings:invoke", "ai.runs:create"];
+/** The organisation's offers, and the permissions its own key is minted with. */
+export declare function aiOffers(bouleReads: boolean): string[];
+/** The offers `ai:organisation` last set, as JSON. */
+export declare const AI_OFFERS_SCOPE_KEY = "ai_offers_applied";
+/** The permissions the recorded org key was minted with, as JSON. Absent: the default offers it was always minted with. */
+export declare const AI_KEY_PERMISSIONS_SCOPE_KEY = "ai_key_permissions";
+/** Ids of org keys replaced by a wider one, as a JSON array. They stay live until they expire: ai has no revoke route yet. */
+export declare const AI_KEY_PREVIOUS_SCOPE_KEY = "ai_key_previous";
+/** The permissions the recorded org key holds. */
+export declare function aiKeyPermissions(recordedIds: Readonly<Record<string, string>>): string;
+/** Boule's env names. */
+export declare const AI_BOULE_ENV: {
+    readonly url: "AI_URL";
+    readonly organisation: "AI_ORGANISATION_ID";
+    readonly key: "AI_API_KEY";
+};
+export declare const AI_BOULE_UNDELIVERED_SCOPE_KEY = "ai_boule_key_undelivered";
+export declare const AI_BOULE_KEY_SCOPE_KEY = "ai_boule_key";
+export declare const AI_BOULE_MINTER_SCOPE_KEY = "ai_boule_key_minter";
+export declare const AI_BOULE_EXPIRES_SCOPE_KEY = "ai_boule_key_expires";
+/** The minter of a key ai clamped under the renewal window: renewing again below it only repeats. */
+export declare const AI_BOULE_CLAMPED_SCOPE_KEY = "ai_boule_key_clamped";
+/** What Boule's env was last written with (`{ url, organisationId }`); never a key. */
+export declare const AI_BOULE_APPLIED_SCOPE_KEY = "ai_boule_key_applied";
+/** Ids of Boule keys a renewal replaced, as a JSON array, revoked once the new one is in Boule's env. */
+export declare const AI_BOULE_PREVIOUS_SCOPE_KEY = "ai_boule_key_previous";
+/** Ids left live because `revokeKey` is absent or failed, as a JSON array. They expire on their own; the plan lists each. */
+export declare const AI_BOULE_UNREVOKED_SCOPE_KEY = "ai_boule_key_unrevoked";
+export declare const aiBouleKeyRef: (orgId: string) => string;
+export declare const aiBouleKeyName: (org: DeclaredOrg) => string;
+/** How long Boule's key is asked for; ai clamps it to the org key's. */
+export declare const AI_BOULE_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export declare const AI_BOULE_RENEW_WINDOW_DAYS = 30;
+export declare function parseIds(raw: string | undefined): string[];
+export type AiBouleMode = 'mint' | 'renew' | 'deliver';
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+/**
+ * Boule's key step, or nothing; nothing at all until the host says ai offers Boule's reads. Blocked, not
+ * planned (rule 2), while the held keys cannot hold the key, ai's address is not recorded, Boule is not recorded or planned, the
+ * org's own key does not hold the five permissions and is not being minted with them, or after a mint whose key
+ * was never held.
+ */
+export declare function planAiBouleKey(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number, bouleReads: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

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

@@ -0,0 +1,195 @@
+/**
+ * foundry#1122: Boule's ai key. Boule's AI page (boule#651) reads one app's month, days, tasks, runs and budget
+ * through ai's `/v1/apps/:app/*` routes (ai#190) and sets the app's budget, with a key in the company's own ai
+ * organisation. One `ai:boule-key` step, keyed by the org id, after Boule and after the org's own ai key:
+ *
+ * 1. mints a key below the org's own ai key (`ai:key:<orgId>`) through `POST /v1/keys` on the company's behalf
+ *    (`mintNestedKey`), holding {@link AI_BOULE_PERMISSIONS} over the organisation and bound to no app; ai shows
+ *    it once and clamps its expiry to the org key's;
+ * 2. records its id as `ai_boule_key_undelivered` and persists it before anything else;
+ * 3. holds the key at `ai:boule-key:<orgId>` (3 tries), then records the id as `ai_boule_key` (the held guard),
+ *    the org key it is below as `ai_boule_key_minter` and its expiry, and persists them;
+ * 4. writes `AI_URL`, `AI_ORGANISATION_ID` and `AI_API_KEY` to Boule's env and restarts Boule;
+ * 5. only then clears the undelivered marker and records what it wrote as `ai_boule_key_applied` (no key).
+ *
+ * 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 (`revokeKey`, ai#157; without it, or when it
+ * fails, the id is listed as left live), then a new one is minted. A renewal (under 30 days left, or below an
+ * org key that was replaced) moves the guard to `ai_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. A key ai clamped under
+ * the window by the same org key is not renewed again: the plan says the org key must be renewed first.
+ *
+ * **The company's organisation has to offer the five permissions first**, and the org's own key has to hold
+ * them, because a key below it can hold only what it holds. ai marks all five `offered: false` today (ai#170
+ * offers one). So all of it waits for the host's word (`aiBouleReads`): with it, `ai:organisation` offers
+ * {@link aiOffers} (recorded as `ai_offers_applied`), the org key is minted again with them when the recorded
+ * one holds fewer (`ai_key_permissions`), and Boule's key is minted below it. Without it nothing changes and
+ * the plan says why.
+ *
+ * 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 over the company's organisation. */
+export const AI_BOULE_PERMISSIONS = [
+    'ai.usage:read',
+    'ai.runs:read',
+    'ai.budgets:read',
+    'ai.budgets:update',
+    'ai.offerings:read',
+];
+/** What every organisation is offered, and its own key holds, without Boule's reads. */
+export const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
+/** The organisation's offers, and the permissions its own key is minted with. */
+export function aiOffers(bouleReads) {
+    return bouleReads ? [...AI_DEFAULT_OFFERS, ...AI_BOULE_PERMISSIONS] : [...AI_DEFAULT_OFFERS];
+}
+/** The offers `ai:organisation` last set, as JSON. */
+export const AI_OFFERS_SCOPE_KEY = 'ai_offers_applied';
+/** The permissions the recorded org key was minted with, as JSON. Absent: the default offers it was always minted with. */
+export const AI_KEY_PERMISSIONS_SCOPE_KEY = 'ai_key_permissions';
+/** Ids of org keys replaced by a wider one, as a JSON array. They stay live until they expire: ai has no revoke route yet. */
+export const AI_KEY_PREVIOUS_SCOPE_KEY = 'ai_key_previous';
+/** The permissions the recorded org key holds. */
+export function aiKeyPermissions(recordedIds) {
+    return recordedIds[AI_KEY_PERMISSIONS_SCOPE_KEY] || JSON.stringify(AI_DEFAULT_OFFERS);
+}
+/** Boule's env names. */
+export const AI_BOULE_ENV = {
+    url: 'AI_URL',
+    organisation: 'AI_ORGANISATION_ID',
+    key: 'AI_API_KEY',
+};
+export const AI_BOULE_UNDELIVERED_SCOPE_KEY = 'ai_boule_key_undelivered';
+export const AI_BOULE_KEY_SCOPE_KEY = 'ai_boule_key';
+export const AI_BOULE_MINTER_SCOPE_KEY = 'ai_boule_key_minter';
+export const AI_BOULE_EXPIRES_SCOPE_KEY = 'ai_boule_key_expires';
+/** The minter of a key ai clamped under the renewal window: renewing again below it only repeats. */
+export const AI_BOULE_CLAMPED_SCOPE_KEY = 'ai_boule_key_clamped';
+/** What Boule's env was last written with (`{ url, organisationId }`); never a key. */
+export const AI_BOULE_APPLIED_SCOPE_KEY = 'ai_boule_key_applied';
+/** Ids of Boule keys a renewal replaced, as a JSON array, revoked once the new one is in Boule's env. */
+export const AI_BOULE_PREVIOUS_SCOPE_KEY = 'ai_boule_key_previous';
+/** Ids left live because `revokeKey` is absent or failed, as a JSON array. They expire on their own; the plan lists each. */
+export const AI_BOULE_UNREVOKED_SCOPE_KEY = 'ai_boule_key_unrevoked';
+export const aiBouleKeyRef = (orgId) => `ai:boule-key:${orgId}`;
+export const aiBouleKeyName = (org) => `${org.slug}-boule`;
+/** How long Boule's key is asked for; ai clamps it to the org key's. */
+export const AI_BOULE_KEY_DAYS = 365;
+/** A key with fewer days left than this is renewed. */
+export const AI_BOULE_RENEW_WINDOW_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function parseIds(raw) {
+    try {
+        const parsed = raw ? JSON.parse(raw) : [];
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Boule's key step, or nothing; nothing at all until the host says ai offers Boule's reads. Blocked, not
+ * planned (rule 2), while the held keys cannot hold the key, ai's address is not recorded, Boule is not recorded or planned, the
+ * org's own key does not hold the five permissions and is not being minted with them, or after a mint whose key
+ * was never held.
+ */
+export function planAiBouleKey(org, recordedIds, plannedSteps, readiness, now, bouleReads) {
+    const steps = [];
+    const blocked = [];
+    const key = `ai:boule-key:${org.id}`;
+    const at = `${org.slug}'s Boule ai 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 parseIds(recordedIds[AI_BOULE_UNREVOKED_SCOPE_KEY])) {
+        blocked.push({
+            description: `warning: ${org.slug}'s replaced Boule ai key ${id} stays live until it expires; it could not be revoked (https://github.com/wtfalch/ai/issues/157)`,
+            key: `${key}:unrevoked:${id}`,
+        });
+    }
+    for (const id of parseIds(recordedIds[AI_KEY_PREVIOUS_SCOPE_KEY])) {
+        blocked.push({
+            description: `warning: ${org.slug}'s replaced own ai key ${id} stays live until it expires, with the entry keys minted below it; ai has no revoke route yet (https://github.com/wtfalch/ai/issues/157)`,
+            key: `ai:key:${org.id}:previous:${id}`,
+        });
+    }
+    // `ai:organisation` reports an ai host that is not ready.
+    if (!readiness.aiReady)
+        return { steps, blocked };
+    const undelivered = recordedIds[AI_BOULE_UNDELIVERED_SCOPE_KEY];
+    const guard = recordedIds[AI_BOULE_KEY_SCOPE_KEY];
+    // Off until the host says ai offers the five permissions: a feature not turned on, not a blocked step, so
+    // every company's plan does not carry a line about it.
+    if (!bouleReads)
+        return { steps, blocked };
+    if (undelivered && undelivered !== guard) {
+        block(`key ${undelivered} was minted but never held, and ai shows a key once; revoke it in ai and remove the recorded key ${AI_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.aiUrl) {
+        block("the platform has not recorded ai's 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 orgKey = recordedIds[`ai:key:${org.id}`];
+    const orgKeyPlanned = planned('ai', 'key', org.id);
+    const orgKeyHolds = Boolean(orgKey) && aiKeyPermissions(recordedIds) === JSON.stringify(aiOffers(true));
+    if (!orgKeyHolds && !orgKeyPlanned) {
+        block("the org's own ai key does not hold Boule's permissions yet, and is not being minted with them");
+        return { steps, blocked };
+    }
+    const want = { url: readiness.aiUrl, organisationId: org.id };
+    const previous = parseIds(recordedIds[AI_BOULE_PREVIOUS_SCOPE_KEY]);
+    const expiresRaw = recordedIds[AI_BOULE_EXPIRES_SCOPE_KEY];
+    const short = !(Date.parse(expiresRaw ?? '') - now >= AI_BOULE_RENEW_WINDOW_DAYS * DAY_MS);
+    const minter = recordedIds[AI_BOULE_MINTER_SCOPE_KEY];
+    let mode = null;
+    if (!guard) {
+        mode = 'mint';
+    }
+    else if (orgKeyPlanned || minter !== orgKey) {
+        mode = 'renew';
+    }
+    else if (short) {
+        if (recordedIds[AI_BOULE_CLAMPED_SCOPE_KEY] === orgKey) {
+            block(`the key expires ${expiresRaw || 'at an unknown time'} because the org's own ai key expires then; renew the org's own ai key, then this one is renewed`);
+            return { steps, blocked };
+        }
+        mode = 'renew';
+    }
+    else if (undelivered === guard ||
+        previous.length > 0 ||
+        recordedIds[AI_BOULE_APPLIED_SCOPE_KEY] !== JSON.stringify(want)) {
+        mode = 'deliver';
+    }
+    if (!mode)
+        return { steps, blocked };
+    steps.push({
+        action: {
+            system: 'ai',
+            kind: 'boule-key',
+            key: org.id,
+            desired: {
+                mode,
+                name: aiBouleKeyName(org),
+                expiresDays: AI_BOULE_KEY_DAYS,
+                permissions: [...AI_BOULE_PERMISSIONS],
+                ...want,
+            },
+        },
+        step: {
+            description: mode === 'deliver'
+                ? `write Boule's ai key for ${org.slug} to Boule's env, restart Boule`
+                : `${mode === 'mint' ? 'mint' : 'renew'} Boule's ai key for ${org.slug} below the org's own key, hold it, write AI_URL, AI_ORGANISATION_ID and AI_API_KEY to Boule's env, restart Boule`,
+            destroys: false,
+            migrates: false,
+        },
+    });
+    return { steps, blocked };
+}

package/dist/plan/analytics.d.ts

@@ -5,7 +5,7 @@ import { type DeclaredOrg } from '../org.js';
  * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
  *
  * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
- * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` and `ANALYTICS_PERSON_KEY` (each generated once here) and `AUTH_ORGANIZATION_ID` (the company's
  * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
  * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
  * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
@@ -22,6 +22,13 @@ export declare const ANALYTICS_DATABASE_SCOPE_KEY = "coolify_analytics_database"
 export declare const ANALYTICS_DEPLOYED_SCOPE_KEY = "coolify_analytics_deployed";
 /** The env name the backend reads its operator key from; also Boule's name for it (C2). */
 export declare const ANALYTICS_OPERATOR_KEY_ENV = "ANALYTICS_OPERATOR_KEY";
+/**
+ * The env name the backend derives each site's person key from (analytics#109, at least 32 characters). Made
+ * once, in the backend's own env only, and never rotated: a new value would count every signed-in person twice.
+ */
+export declare const ANALYTICS_PERSON_KEY_ENV = "ANALYTICS_PERSON_KEY";
+/** 32 random bytes, written as 64 hex characters. */
+export declare const ANALYTICS_PERSON_KEY_BYTES = 32;
 /** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
 export declare const ANALYTICS_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ORGANIZATION_ID"];
 export declare function desiredAnalyticsEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {

package/dist/plan/analytics.js

@@ -6,7 +6,7 @@ import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
  * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
  *
  * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
- * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` and `ANALYTICS_PERSON_KEY` (each generated once here) and `AUTH_ORGANIZATION_ID` (the company's
  * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
  * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
  * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
@@ -25,6 +25,13 @@ export const ANALYTICS_DATABASE_SCOPE_KEY = 'coolify_analytics_database';
 export const ANALYTICS_DEPLOYED_SCOPE_KEY = 'coolify_analytics_deployed';
 /** The env name the backend reads its operator key from; also Boule's name for it (C2). */
 export const ANALYTICS_OPERATOR_KEY_ENV = 'ANALYTICS_OPERATOR_KEY';
+/**
+ * The env name the backend derives each site's person key from (analytics#109, at least 32 characters). Made
+ * once, in the backend's own env only, and never rotated: a new value would count every signed-in person twice.
+ */
+export const ANALYTICS_PERSON_KEY_ENV = 'ANALYTICS_PERSON_KEY';
+/** 32 random bytes, written as 64 hex characters. */
+export const ANALYTICS_PERSON_KEY_BYTES = 32;
 /** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
 export const ANALYTICS_MANAGED_ENV_KEYS = ['APP_URL', 'AUTH_ORGANIZATION_ID'];
 export function desiredAnalyticsEnv(org, recorded) {

package/dist/plan/app-canary-apply.d.ts

@@ -0,0 +1,49 @@
+import type { DnsPort } from './edge-dns.js';
+import type { ZonePort } from './edge-zones.js';
+import type { WorkersPort } from './executor.js';
+import type { PlatformStepExecutionContext } from './plan-apply.js';
+/**
+ * What the canary step needs, each built at edge's recorded address: the
+ * platform's Workers calls (the host builds them with `createEdgeWorkers` and
+ * a `fetchArtifact` that serves the package's own bytes,
+ * `fetchAppCanaryArtifact`), its zone lookup and its DNS calls. These are the
+ * calls a managed app's deploy makes: a Worker upload and a route on
+ * `<label>.companyincluded.app`, plus the proxied record edge's company route
+ * writes for its host. No Access call: the canary has no gate.
+ */
+export interface PlatformAppCanaryDeps {
+    workers: (edgeUrl: string) => WorkersPort | Promise<WorkersPort>;
+    zones: (edgeUrl: string) => Pick<ZonePort, 'findZoneByApex'> | Promise<Pick<ZonePort, 'findZoneByApex'>>;
+    dns: (edgeUrl: string) => DnsPort | Promise<DnsPort>;
+    /** `GET <url>` and its status. The global `fetch`, with no redirects followed, by default. */
+    probe?: (url: string) => Promise<number>;
+    /** Tries of the probe, {@link APP_CANARY_PROBE_ATTEMPTS} by default. */
+    probeAttempts?: number;
+    /** Waits between probes; a real timer by default. */
+    sleep?: (ms: number) => Promise<void>;
+    /** One outside call's limit in milliseconds; 60 s by default. */
+    callTimeoutMs?: number;
+}
+/**
+ * Why the canary cannot be planned yet, read live (rule 2), or `undefined`.
+ * A script, route or DNS record on the canary's name that foundry did not
+ * make is never taken over: the plan says so and plans nothing, rather than a
+ * step that throws on every apply. A missing apps zone is the same.
+ */
+export declare function appCanaryBlockedReason(deps: PlatformAppCanaryDeps | undefined, platform: {
+    appCanary?: {
+        enabled: boolean;
+        tag: string;
+    };
+}, recordedIds: Readonly<Record<string, string>>): Promise<string | undefined>;
+/**
+ * foundry#1133: deploys the canary on the managed-app layer and records the
+ * hostname Archon's uptime probes, last, once it answers 200. The script is
+ * recorded right after its upload (a later failure leaves a half-made canary
+ * foundry owns, which the next apply repairs); the record and the route are
+ * recorded as each is made. Disabled, it clears the hostname first, so Archon
+ * stops probing, then removes the route, the record and the script.
+ */
+export declare function provisionPlatformAppCanary(context: PlatformStepExecutionContext, deps: PlatformAppCanaryDeps): Promise<{
+    resourceId?: string;
+}>;