@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/plan/edge-access.d.ts

@@ -86,6 +86,12 @@ export interface AccessPort {
         id: string;
     }>;
     replaceGateHostnames(gateId: string, hostnames: string[]): Promise<void>;
+    /**
+     * Replaces the whole list of people who pass a gate; nothing else about the gate changes. Edge's platform
+     * client has no such call yet, so {@link createEdgeAccess} does not implement it: a host that wants a
+     * workspace's testers to change supplies a port that does (edge's company `gates.setPeople`).
+     */
+    setGatePeople?(gateId: string, emails: string[]): Promise<void>;
     /** Deletes the gate with its application, policy and list; a gate already gone is done. */
     deleteGate(gateId: string): Promise<void>;
     /** The Cloudflare Access team address (`<team>.cloudflareaccess.com`); rejects with `not_configured` while the Cloudflare token lacks an Access right. */

package/dist/plan/edge-dns.d.ts

@@ -15,6 +15,12 @@ export interface DnsRecordInput {
     ttl?: number;
     /** Required for an `MX` record. */
     priority?: number;
+    /**
+     * The company the record is written for, sent on create and on the adopt that
+     * precedes an update. Edge ties a path gate on a platform-zone host to the
+     * organisation its record was written for. Omitted: the record is the platform's.
+     */
+    organisationId?: string;
 }
 /**
  * Foundry's DNS calls. Every record call in foundry goes through this; the one

package/dist/plan/edge-dns.js

@@ -129,9 +129,10 @@ export function createEdgeDns(client, options = {}) {
         }
         unadopted.set(zone, pending);
     };
-    const adopt = async (zone, record) => {
+    const adopt = async (zone, record, organisationId) => {
         const result = await writeSlot(() => dns.adopt({
             zone,
+            ...(organisationId === undefined ? {} : { organisationId }),
             records: [
                 {
                     name: record.name,
@@ -150,14 +151,14 @@ export function createEdgeDns(client, options = {}) {
         unadopted.get(zone)?.delete(record.id);
     };
     /** Adopts `recordId` when it was seen without an edge row. */
-    const ensureAdopted = async (zone, recordId) => {
+    const ensureAdopted = async (zone, recordId, organisationId) => {
         const record = unadopted.get(zone)?.get(recordId);
         if (record)
-            await adopt(zone, record);
+            await adopt(zone, record, organisationId);
     };
     /** Runs a write; on `not_found` adopts the live record once and retries. */
-    const writeExisting = async (zone, recordId, write) => {
-        await ensureAdopted(zone, recordId);
+    const writeExisting = async (zone, recordId, write, organisationId) => {
+        await ensureAdopted(zone, recordId, organisationId);
         // `forbidden` also answers a revoked or under-scoped platform key, so the
         // record is listed again and the company message is used only when its
         // owner really is an organisation; anything else is the original error.
@@ -192,7 +193,7 @@ export function createEdgeDns(client, options = {}) {
             const record = live.find((r) => r.id === recordId);
             if (!record || record.owner !== null)
                 throw error;
-            await adopt(zone, record);
+            await adopt(zone, record, organisationId);
             try {
                 return await writeSlot(write);
             }
@@ -225,11 +226,12 @@ export function createEdgeDns(client, options = {}) {
                 name: rec.name,
                 type: rec.type,
                 ...body(rec),
+                ...(rec.organisationId === undefined ? {} : { organisationId: rec.organisationId }),
             }));
             return { id: created.id, name: created.name, content: summary(created).content };
         },
         async updateDnsRecord(zone, recordId, rec) {
-            const updated = await writeExisting(zone, recordId, () => dns.update(zone, recordId, body(rec)));
+            const updated = await writeExisting(zone, recordId, () => dns.update(zone, recordId, body(rec)), rec.organisationId);
             return { id: updated.id, name: updated.name, content: summary(updated).content };
         },
         async deleteDnsRecord(zone, recordId) {

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

@@ -37,7 +37,7 @@ export declare const entryAiKeyName: (org: DeclaredOrg, entry: HostingEntry) =>
 export interface EntryAiWant {
     permissions: string[];
     offerings: string[];
-    /** `https://<first hostname><webhookPath>`, or null without `webhookPath`. */
+    /** `https://<serving host><webhookPath>` (the live host, else the workspace host), or null without `webhookPath` or a host. */
     webhook: string | null;
     aiUrl: string;
 }

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

@@ -1,5 +1,5 @@
 import { AI_ENTRY_PERMISSIONS } from '../org.js';
-import { entryHostnames } from './hostnames.js';
+import { entryServingHost } from './hostnames.js';
 import { appStepKey } from './platform-diff.js';
 /**
  * F6a: one ai key per entry with `uses.ai`, minted below the org's own ai key
@@ -45,7 +45,7 @@ export function parseIdList(raw) {
 export const entryAiKeyName = (org, entry) => `${org.slug}-${entry.key}`;
 export function wantedEntryAi(org, entry, aiUrl) {
     const ai = entry.uses?.ai;
-    const host = entryHostnames(org, entry)[0];
+    const host = entryServingHost(org, entry);
     return {
         permissions: [...(ai?.permissions ?? AI_ENTRY_PERMISSIONS)],
         offerings: [...(ai?.offerings ?? [])],

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

@@ -0,0 +1,58 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { OrgPlatformReadiness } from './platform-org.js';
+/**
+ * `uses.audit` (foundry#929, audit#56): one `audit:ledger` step per entry, keyed `<orgId>:<entry>`:
+ *
+ * 1. makes the platform's checkpoint signer if none exists (one Ed25519 key for every ledger, its seed held at
+ *    `foundry:audit-signer:seed`, never in an app, an env, a plan or a log) and records its public key at
+ *    {@link AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY} (not a secret: it goes in the trusted-keys file a verifier is given);
+ * 2. registers the entry's ledger for sealing by recording `audit_ledger.<entry>` = the ledger name, last.
+ *
+ * Only registered ledgers are sealed (`audit/registry.ts`), and the registry is read from the records, so the
+ * sealing tick (`audit/seal.ts`, run by the host every `AUDIT_SEAL_EVERY_MINUTES`) never touches a database whose
+ * Worker app and migrations have not applied.
+ *
+ * Planned after the entry's Worker app applied or is planned in the same run: the app's database holds the audit
+ * tables from then on. Blocked, not failing (a plan line each): the held keys cannot put the signer's seed, the
+ * Worker app is not applied yet. Dropping `uses.audit` plans nothing: the record stays, the registry stops
+ * listing the ledger, and the ledger itself is never touched (append-only, nothing pruned).
+ */
+/** The platform signer's public key, 64 hex characters. */
+export declare const AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY = "audit_signer_public_key";
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+export declare function planEntryAudit(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: Pick<OrgPlatformReadiness, 'canHoldSecrets'>): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export interface EntryAuditDeps {
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    org: {
+        id: string;
+        slug: string;
+    };
+    entryKey: string;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    /** Registers a value so no log, error or result ever carries it. */
+    secret: (value: string) => void;
+    mint?: () => string;
+}
+/**
+ * Runs the step. The seed is registered as a secret the moment it is made, so a failure after that never
+ * prints it. Safe to repeat: a held seed is reused, and the records are written last. When a public key is
+ * already recorded and the held seed reads empty, nothing is made and nothing is put (see `ensurePlatformSigner`).
+ */
+export declare function applyEntryAudit(deps: EntryAuditDeps): Promise<{
+    resourceId: string;
+}>;
+/** The entry keys with a registration record, for status pages. */
+export declare function recordedAuditEntries(recordedIds: Readonly<Record<string, string>>): string[];
+export {};

package/dist/plan/entry-audit.js

@@ -0,0 +1,122 @@
+import { AUDIT_LEDGER_PREFIX, appLedgerName, auditLedgerScopeKey } from '../audit/registry.js';
+import { auditSealerScopeKey, auditSealerUndeliveredScopeKey } from '../audit/sealer-role.js';
+import { AUDIT_SIGNER_REF, ensurePlatformSigner, mintSignerSeed } from '../audit/signer.js';
+import { workerAppAppliedScopeKey } from './worker-app.js';
+/**
+ * `uses.audit` (foundry#929, audit#56): one `audit:ledger` step per entry, keyed `<orgId>:<entry>`:
+ *
+ * 1. makes the platform's checkpoint signer if none exists (one Ed25519 key for every ledger, its seed held at
+ *    `foundry:audit-signer:seed`, never in an app, an env, a plan or a log) and records its public key at
+ *    {@link AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY} (not a secret: it goes in the trusted-keys file a verifier is given);
+ * 2. registers the entry's ledger for sealing by recording `audit_ledger.<entry>` = the ledger name, last.
+ *
+ * Only registered ledgers are sealed (`audit/registry.ts`), and the registry is read from the records, so the
+ * sealing tick (`audit/seal.ts`, run by the host every `AUDIT_SEAL_EVERY_MINUTES`) never touches a database whose
+ * Worker app and migrations have not applied.
+ *
+ * Planned after the entry's Worker app applied or is planned in the same run: the app's database holds the audit
+ * tables from then on. Blocked, not failing (a plan line each): the held keys cannot put the signer's seed, the
+ * Worker app is not applied yet. Dropping `uses.audit` plans nothing: the record stays, the registry stops
+ * listing the ledger, and the ledger itself is never touched (append-only, nothing pruned).
+ */
+/** The platform signer's public key, 64 hex characters. */
+export const AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY = 'audit_signer_public_key';
+export function planEntryAudit(org, recordedIds, plannedSteps, readiness) {
+    const steps = [];
+    const blocked = [];
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    for (const entry of org.hosting.entries) {
+        if (entry.uses?.audit !== true)
+            continue;
+        const key = `${org.id}:${entry.key}`;
+        const ledger = appLedgerName(org, entry.key);
+        if (recordedIds[auditLedgerScopeKey(entry.key)] === ledger &&
+            recordedIds[AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY]) {
+            continue;
+        }
+        const block = (why) => blocked.push({ description: `${org.slug}'s ${entry.key} audit log is blocked: ${why}`, key });
+        if (readiness.canHoldSecrets !== true) {
+            block("the host's held keys cannot hold the platform signer's key");
+            continue;
+        }
+        const undelivered = recordedIds[auditSealerUndeliveredScopeKey(entry.key)];
+        if (undelivered) {
+            block(`the sealing password for role ${undelivered} was minted and never held; clear the recorded ${auditSealerUndeliveredScopeKey(entry.key)} to mint it again`);
+            continue;
+        }
+        const appPlanned = plannedSteps.some((p) => p.action.system === 'cloudflare' &&
+            p.action.kind === 'worker-app' &&
+            p.action.key === key &&
+            p.action.desired.mode === 'apply');
+        const appApplied = Boolean(recordedIds[workerAppAppliedScopeKey(entry.key)]);
+        if (appApplied && !appPlanned && !recordedIds[auditSealerScopeKey(entry.key)]) {
+            block("the sealing role has not been made: the host's database port cannot make it, or the Worker app has not applied since uses.audit was turned on");
+            continue;
+        }
+        if (!appApplied && !appPlanned) {
+            block("the entry's Worker app, which carries the database, is not applied yet");
+            continue;
+        }
+        steps.push({
+            action: { system: 'audit', kind: 'ledger', key, desired: { ledger } },
+            step: {
+                description: `register ${org.slug}'s ${entry.key} audit log as ${ledger} for platform sealing, making the platform signer first if none exists`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
+/**
+ * Runs the step. The seed is registered as a secret the moment it is made, so a failure after that never
+ * prints it. Safe to repeat: a held seed is reused, and the records are written last. When a public key is
+ * already recorded and the held seed reads empty, nothing is made and nothing is put (see `ensurePlatformSigner`).
+ */
+export async function applyEntryAudit(deps) {
+    const at = `audit:ledger for ${deps.org.slug} entry '${deps.entryKey}'`;
+    const mint = deps.mint ?? mintSignerSeed;
+    const { signer } = await ensurePlatformSigner({
+        resolveSeed: async () => {
+            const seed = (await deps.heldKeys.resolve(AUDIT_SIGNER_REF)) || null;
+            if (seed)
+                deps.secret(seed);
+            return seed;
+        },
+        // Create-if-absent: a held value is never overwritten, however it came to be read as empty before.
+        deliverSeed: async (seed) => {
+            deps.secret(seed);
+            const held = (await deps.heldKeys.resolve(AUDIT_SIGNER_REF)) || null;
+            if (held) {
+                deps.secret(held);
+                throw new Error(`${AUDIT_SIGNER_REF} already holds a key; it was not overwritten, nothing was changed, apply again`);
+            }
+            await deps.heldKeys.put(AUDIT_SIGNER_REF, seed);
+        },
+    }, mint, deps.recorded()[AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY] || undefined).catch((error) => {
+        // Our own messages name the ref, never the value; anything else is dropped in case it echoes the seed.
+        const own = error instanceof Error && error.message.includes(AUDIT_SIGNER_REF);
+        throw new Error(own
+            ? `${at}: ${error.message}`
+            : `${at}: the platform signer's key could not be held or read`);
+    });
+    if (!deps.recorded()[auditSealerScopeKey(deps.entryKey)]) {
+        throw new Error(`${at}: the sealing role is not recorded; the entry's Worker app makes it, and the host's database port must be able to`);
+    }
+    const existing = deps.recorded()[AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY];
+    if (existing && existing !== signer.publicKey) {
+        throw new Error(`${at}: the held signer key is not the one recorded as the platform signer; checkpoints already sealed would no longer verify against it. Restore the held key at ${AUDIT_SIGNER_REF} or clear ${AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY} on purpose`);
+    }
+    deps.record(AUDIT_SIGNER_PUBLIC_KEY_SCOPE_KEY, signer.publicKey);
+    await deps.persist();
+    const ledger = appLedgerName(deps.org, deps.entryKey);
+    deps.record(auditLedgerScopeKey(deps.entryKey), ledger);
+    return { resourceId: ledger };
+}
+/** The entry keys with a registration record, for status pages. */
+export function recordedAuditEntries(recordedIds) {
+    return Object.keys(recordedIds)
+        .filter((k) => k.startsWith(AUDIT_LEDGER_PREFIX))
+        .map((k) => k.slice(AUDIT_LEDGER_PREFIX.length));
+}

package/dist/plan/entry-customer-grants.d.ts

@@ -0,0 +1,75 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+/**
+ * `uses.customerGrants`: the app implements Boule's customer-grants routes. Foundry makes one credential per
+ * entry (`<base64url>.<base64url>`), holds it, and gives it to two places: the app's env
+ * (`CUSTOMER_GRANTS_CREDENTIAL`) and the company's Boule, inside its `CUSTOMER_GRANTS` JSON. The plan never
+ * holds the value; it compares the JSON's shape (tenant key, organisation, app names and urls) and the
+ * presence of every credential.
+ */
+export declare const CUSTOMER_GRANTS_CREDENTIAL_ENV = "CUSTOMER_GRANTS_CREDENTIAL";
+/** The env Boule reads the grants from (`src/lib/customer-grants/config.ts`). */
+export declare const CUSTOMER_GRANTS_ENV = "CUSTOMER_GRANTS";
+/** Recorded (no secret) once an entry's credential was held: its ref. Cleared when the flag goes. */
+export declare const customerGrantsMintedScopeKey: (entryKey: string) => string;
+export declare const CUSTOMER_GRANTS_MINTED_PREFIX = "customer_grants_minted.";
+/** Recorded once foundry has written Boule's `CUSTOMER_GRANTS`: the JSON's shape hash input, no secret. Cleared when foundry takes it away. */
+export declare const CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY = "boule_customer_grants_written";
+/** The held-key ref of an entry's credential. */
+export declare const customerGrantsRef: (orgId: string, entryKey: string) => string;
+/** `<id>.<secret>`, both base64url, 32 random bytes each. */
+export declare const mintCustomerGrantsCredential: () => string;
+interface HeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+/**
+ * The entry's credential: read from the held keys, else made and held first, and the ref recorded and
+ * persisted before the value goes anywhere, so a crash after the `put` hands the same value out on the next
+ * apply. A ref that is recorded but no longer held stops here and mints nothing: a second value would leave
+ * the app and Boule disagreeing. Errors name the ref, never the value. `secret` registers it for redaction.
+ * Both the app step and the Boule step call this, so either may run first.
+ */
+export declare function ensureCustomerGrantsCredential(input: {
+    orgId: string;
+    slug: string;
+    entryKey: string;
+    heldKeys: HeldKeys | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    secret: (value: string) => void;
+}): Promise<string>;
+/** The entries that declare `uses.customerGrants`, in declared order. */
+export declare const customerGrantsEntries: (org: Pick<DeclaredOrg, "hosting">) => HostingEntry[];
+/** Entry keys that were given a credential and no longer declare the flag (or are gone). */
+export declare function customerGrantsToDrop(org: Pick<DeclaredOrg, 'hosting'>, recorded: Readonly<Record<string, string>>): string[];
+/** What the JSON says without any secret. */
+export interface CustomerGrantsShape {
+    /** The key in Boule's `CUSTOMER_GRANTS`: the company's issuer organisation id (`AUTH_ORGANIZATION_ID` of its Boule). */
+    tenantKey: string;
+    customersOrganisationId: string;
+    apps: Record<string, {
+        name: string;
+        url: string;
+    }>;
+}
+/**
+ * What Boule's `CUSTOMER_GRANTS` should say, or `null` with the plan lines for each reason it says nothing
+ * yet. The key is the issuer organisation id because a company's Boule has one deploy per organisation and
+ * the Boule tenant row is made at its first start, after which foundry could not know its id.
+ */
+export declare function wantedCustomerGrants(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, boule: {
+    live: boolean;
+}): {
+    shape: CustomerGrantsShape | null;
+    notes: string[];
+};
+/** Boule's `CUSTOMER_GRANTS` value: stable key order, so an unchanged value is byte-identical. */
+export declare function customerGrantsJson(shape: CustomerGrantsShape, directoryCredential: string, credentials: Readonly<Record<string, string>>): string;
+/**
+ * Whether the live value already says what `shape` says: the same single tenant key, organisation and apps
+ * (names, urls), with a credential present for each and for the directory. Credentials are compared by presence
+ * only, in memory.
+ */
+export declare function customerGrantsShapeMatches(live: string | undefined, shape: CustomerGrantsShape): boolean;
+export {};

package/dist/plan/entry-customer-grants.js

@@ -0,0 +1,154 @@
+import { randomBytes } from 'node:crypto';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+import { customersOrgIdOf } from './boule.js';
+import { entryServingHost } from './hostnames.js';
+/**
+ * `uses.customerGrants`: the app implements Boule's customer-grants routes. Foundry makes one credential per
+ * entry (`<base64url>.<base64url>`), holds it, and gives it to two places: the app's env
+ * (`CUSTOMER_GRANTS_CREDENTIAL`) and the company's Boule, inside its `CUSTOMER_GRANTS` JSON. The plan never
+ * holds the value; it compares the JSON's shape (tenant key, organisation, app names and urls) and the
+ * presence of every credential.
+ */
+export const CUSTOMER_GRANTS_CREDENTIAL_ENV = 'CUSTOMER_GRANTS_CREDENTIAL';
+/** The env Boule reads the grants from (`src/lib/customer-grants/config.ts`). */
+export const CUSTOMER_GRANTS_ENV = 'CUSTOMER_GRANTS';
+/** Recorded (no secret) once an entry's credential was held: its ref. Cleared when the flag goes. */
+export const customerGrantsMintedScopeKey = (entryKey) => `customer_grants_minted.${entryKey}`;
+export const CUSTOMER_GRANTS_MINTED_PREFIX = 'customer_grants_minted.';
+/** Recorded once foundry has written Boule's `CUSTOMER_GRANTS`: the JSON's shape hash input, no secret. Cleared when foundry takes it away. */
+export const CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY = 'boule_customer_grants_written';
+/** The held-key ref of an entry's credential. */
+export const customerGrantsRef = (orgId, entryKey) => `foundry:customer-grants:${orgId}:${entryKey}`;
+/** `<id>.<secret>`, both base64url, 32 random bytes each. */
+export const mintCustomerGrantsCredential = () => `${randomBytes(32).toString('base64url')}.${randomBytes(32).toString('base64url')}`;
+/**
+ * The entry's credential: read from the held keys, else made and held first, and the ref recorded and
+ * persisted before the value goes anywhere, so a crash after the `put` hands the same value out on the next
+ * apply. A ref that is recorded but no longer held stops here and mints nothing: a second value would leave
+ * the app and Boule disagreeing. Errors name the ref, never the value. `secret` registers it for redaction.
+ * Both the app step and the Boule step call this, so either may run first.
+ */
+export async function ensureCustomerGrantsCredential(input) {
+    const ref = customerGrantsRef(input.orgId, input.entryKey);
+    const at = `customer grants for ${input.slug}`;
+    const held = await input.heldKeys?.resolve(ref);
+    if (held) {
+        input.secret(held);
+        return held;
+    }
+    if (input.recorded()[customerGrantsMintedScopeKey(input.entryKey)]) {
+        throw new Error(`${at}: the credential of entry '${input.entryKey}' was made but is no longer held (ref ${ref}); restore the held value`);
+    }
+    if (typeof input.heldKeys?.put !== 'function') {
+        throw new Error(`${at}: the held keys cannot put the credential of entry '${input.entryKey}'`);
+    }
+    const credential = mintCustomerGrantsCredential();
+    input.secret(credential);
+    await input.heldKeys.put(ref, credential);
+    input.record(customerGrantsMintedScopeKey(input.entryKey), ref);
+    await input.persist();
+    return credential;
+}
+/** The entries that declare `uses.customerGrants`, in declared order. */
+export const customerGrantsEntries = (org) => org.hosting.enabled ? org.hosting.entries.filter((e) => e.uses?.customerGrants) : [];
+/** Entry keys that were given a credential and no longer declare the flag (or are gone). */
+export function customerGrantsToDrop(org, recorded) {
+    const wanted = new Set(customerGrantsEntries(org).map((e) => e.key));
+    return Object.keys(recorded)
+        .filter((k) => k.startsWith(CUSTOMER_GRANTS_MINTED_PREFIX) && recorded[k])
+        .map((k) => k.slice(CUSTOMER_GRANTS_MINTED_PREFIX.length))
+        .filter((key) => !wanted.has(key));
+}
+/**
+ * What Boule's `CUSTOMER_GRANTS` should say, or `null` with the plan lines for each reason it says nothing
+ * yet. The key is the issuer organisation id because a company's Boule has one deploy per organisation and
+ * the Boule tenant row is made at its first start, after which foundry could not know its id.
+ */
+export function wantedCustomerGrants(org, recorded, boule) {
+    const entries = customerGrantsEntries(org);
+    const notes = [];
+    if (entries.length === 0)
+        return { shape: null, notes };
+    const at = `${org.slug}'s customer grants`;
+    const tenantKey = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const customersOrganisationId = customersOrgIdOf(org, recorded);
+    if (!org.customers?.enabled) {
+        notes.push(`${at} are not planned: ${entries.map((e) => `'${e.key}'`).join(', ')} declare customerGrants but the company has customers off, so there is no customers organisation to list`);
+    }
+    else if (!customersOrganisationId) {
+        notes.push(`${at} wait: the customers organisation is not made yet; Boule gets its entry on the apply after it is`);
+    }
+    if (!tenantKey) {
+        notes.push(`${at} wait: the company's sign-in organisation is not recorded yet`);
+    }
+    if (!boule.live) {
+        notes.push(`${at} wait: ${org.slug} has no Boule yet; it gets its entry once Boule is running`);
+    }
+    const apps = {};
+    for (const entry of entries) {
+        const host = entryServingHost(org, entry);
+        if (!host) {
+            notes.push(`${at}: entry '${entry.key}' has no address Boule can call yet, so it is left out of Boule's entry`);
+            continue;
+        }
+        apps[entry.key] = { name: entry.key, url: `https://${host}/api` };
+    }
+    if (!org.customers?.enabled ||
+        !tenantKey ||
+        !customersOrganisationId ||
+        Object.keys(apps).length === 0) {
+        return { shape: null, notes };
+    }
+    return { shape: { tenantKey, customersOrganisationId, apps }, notes };
+}
+/** Boule's `CUSTOMER_GRANTS` value: stable key order, so an unchanged value is byte-identical. */
+export function customerGrantsJson(shape, directoryCredential, credentials) {
+    const apps = {};
+    for (const key of Object.keys(shape.apps).sort()) {
+        const app = shape.apps[key];
+        apps[key] = { name: app.name, url: app.url, credential: credentials[key] };
+    }
+    return JSON.stringify({
+        [shape.tenantKey]: {
+            customersOrganisationId: shape.customersOrganisationId,
+            directoryCredential,
+            apps,
+        },
+    });
+}
+/**
+ * Whether the live value already says what `shape` says: the same single tenant key, organisation and apps
+ * (names, urls), with a credential present for each and for the directory. Credentials are compared by presence
+ * only, in memory.
+ */
+export function customerGrantsShapeMatches(live, shape) {
+    if (!live)
+        return false;
+    try {
+        const all = JSON.parse(live);
+        const keys = Object.keys(all);
+        if (keys.length !== 1 || keys[0] !== shape.tenantKey)
+            return false;
+        const entry = all[shape.tenantKey];
+        if (entry.customersOrganisationId !== shape.customersOrganisationId)
+            return false;
+        if (typeof entry.directoryCredential !== 'string' || !entry.directoryCredential)
+            return false;
+        const apps = entry.apps ?? {};
+        const liveKeys = Object.keys(apps).sort();
+        const wantedKeys = Object.keys(shape.apps).sort();
+        if (liveKeys.join('\n') !== wantedKeys.join('\n'))
+            return false;
+        return wantedKeys.every((key) => {
+            const have = apps[key];
+            const want = shape.apps[key];
+            return (have?.name === want?.name &&
+                have?.url === want?.url &&
+                typeof have?.credential === 'string' &&
+                have.credential !== '');
+        });
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, HostingEntry } from '../org.js';
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
 import type { DraftStep } from './diff.js';
 import type { OrgPlatformReadiness } from './platform-org.js';
 /**
@@ -43,6 +43,21 @@ export declare const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = "edge_reserved_lab
  * so it never collides with a declared entry.
  */
 export declare const BOULE_EDGE_ENTRY_KEY = "_boule";
+/**
+ * F3 (#924): Boule's edge key is wanted when the org has its own domain (DNS records) or its Boule runs apps
+ * (`org.boule.apps`: it deploys the company's own Workers through edge, `workers:deploy`). Edge gives every
+ * company key every customer permission in its own organisation, `workers:deploy` and `workers:read` among them
+ * (`apps/host/src/lib/edge-host.ts` `buildAccess`), and scopes a deploy to the script names
+ * `<organisationId>--<app>` and `<organisationId>--<app>-work` from the key's own organisation, so the key
+ * carries no scope of its own and a key minted before the permission existed gains it without a re-mint.
+ */
+export declare const bouleEdgeKeyWanted: (org: DeclaredOrg) => boolean;
+/**
+ * The domain edge binds a company's key to (`mintKey` needs a lowercase hostname and refuses one another
+ * organisation's key overlaps). A company without its own domain is on `<slug>.oikos.host`, the address
+ * `plan/diff.ts` already gives its apps.
+ */
+export declare const edgeKeyDomain: (org: Pick<DeclaredOrg, "domain" | "slug">) => string;
 /** The recorded-id key of the Coolify app an edge key's env is written to. */
 export declare function edgeKeyAppRecordKey(org: DeclaredOrg, entryKey: string): string;
 export declare const entryEdgeKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
@@ -59,6 +74,16 @@ export declare const entryEdgeKeyName: (org: DeclaredOrg, entry: HostingEntry) =
  * domain), so it reserves `www` only.
  */
 export declare function edgeReservedLabels(org: DeclaredOrg, platformHostnames?: readonly string[]): string[];
+/** The slug last recorded in edge for the org, so a changed slug is sent again and an unchanged one is not. */
+export declare const EDGE_SLUG_APPLIED_SCOPE_KEY = "edge_slug_applied";
+/**
+ * F3: edge accepts a company's platform hostnames (`<slug>-<app>.<platform domain>`,
+ * `work-<slug>-<app>.<workspace domain>`) when the company is on its own domain only once it knows the
+ * company's slug (`PUT /v1/platform/organisations/:orgId/slug`). Planned for a company with Apps on, once
+ * the platform has an edge service, whenever the slug edge holds is not the declared one. A platform
+ * without an edge service is quiet, like Boule's key: nothing is declared that could not be done.
+ */
+export declare function planEdgeSlug(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, readiness: OrgPlatformReadiness): DraftStep | null;
 type Blocked = Array<{
     description: string;
     key: string;

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

@@ -1,3 +1,4 @@
+import { appsOn } from '../org.js';
 import { tunnelIngressHostnames } from './hostnames.js';
 import { lockedHostnames } from './locked-hostnames.js';
 import { appStepKey } from './platform-diff.js';
@@ -44,6 +45,21 @@ export const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = 'edge_reserved_labels_appl
  * so it never collides with a declared entry.
  */
 export const BOULE_EDGE_ENTRY_KEY = '_boule';
+/**
+ * F3 (#924): Boule's edge key is wanted when the org has its own domain (DNS records) or its Boule runs apps
+ * (`org.boule.apps`: it deploys the company's own Workers through edge, `workers:deploy`). Edge gives every
+ * company key every customer permission in its own organisation, `workers:deploy` and `workers:read` among them
+ * (`apps/host/src/lib/edge-host.ts` `buildAccess`), and scopes a deploy to the script names
+ * `<organisationId>--<app>` and `<organisationId>--<app>-work` from the key's own organisation, so the key
+ * carries no scope of its own and a key minted before the permission existed gains it without a re-mint.
+ */
+export const bouleEdgeKeyWanted = (org) => Boolean(org.domain) || appsOn(org);
+/**
+ * The domain edge binds a company's key to (`mintKey` needs a lowercase hostname and refuses one another
+ * organisation's key overlaps). A company without its own domain is on `<slug>.oikos.host`, the address
+ * `plan/diff.ts` already gives its apps.
+ */
+export const edgeKeyDomain = (org) => org.domain ?? `${org.slug}.oikos.host`;
 /** The recorded-id key of the Coolify app an edge key's env is written to. */
 export function edgeKeyAppRecordKey(org, entryKey) {
     return entryKey === BOULE_EDGE_ENTRY_KEY
@@ -89,6 +105,29 @@ export function edgeReservedLabels(org, platformHostnames = []) {
     }
     return [...labels].sort();
 }
+/** The slug last recorded in edge for the org, so a changed slug is sent again and an unchanged one is not. */
+export const EDGE_SLUG_APPLIED_SCOPE_KEY = 'edge_slug_applied';
+/**
+ * F3: edge accepts a company's platform hostnames (`<slug>-<app>.<platform domain>`,
+ * `work-<slug>-<app>.<workspace domain>`) when the company is on its own domain only once it knows the
+ * company's slug (`PUT /v1/platform/organisations/:orgId/slug`). Planned for a company with Apps on, once
+ * the platform has an edge service, whenever the slug edge holds is not the declared one. A platform
+ * without an edge service is quiet, like Boule's key: nothing is declared that could not be done.
+ */
+export function planEdgeSlug(org, recordedIds, readiness) {
+    if (!appsOn(org) || !readiness.edgeReady)
+        return null;
+    if (recordedIds[EDGE_SLUG_APPLIED_SCOPE_KEY] === org.slug)
+        return null;
+    return {
+        action: { system: 'edge', kind: 'slug', key: org.id, desired: { slug: org.slug } },
+        step: {
+            description: `record ${org.slug}'s slug in edge, so edge accepts its platform hostnames`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 /**
  * One step per entry whose edge key is missing, plus one retire step per
  * entry whose `uses.edge` was removed but still has a recorded key.
@@ -111,12 +150,12 @@ export function planEntryEdgeKeys(org, recordedIds, plannedSteps, readiness, now
     // throws before `runSteps` sees a `resourceId`), so scanning the main
     // prefix alone would never find it to revoke once its entry is gone
     // (#317 review).
-    // Boule's key is wanted whenever the org has its own domain (with-domain
-    // mode): edge refuses a company on oikos.host, so none is minted there.
+    // Boule's key is wanted whenever the org has its own domain, or its Boule runs apps
+    // (`bouleEdgeKeyWanted`): a company on oikos.host without apps gets none.
     const holders = org.hosting.entries
         .filter((e) => e.uses?.edge)
         .map((e) => ({ entryKey: e.key, name: entryEdgeKeyName(org, e) }));
-    if (org.domain) {
+    if (bouleEdgeKeyWanted(org)) {
         holders.push({ entryKey: BOULE_EDGE_ENTRY_KEY, name: `${org.slug}-boule-edge` });
     }
     const declared = new Set(holders.map((h) => h.entryKey));