@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/plan/broker-registrar.js

@@ -0,0 +1,440 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+import { AUTH_REGISTRAR_KEY_ENV, AUTH_REGISTRAR_URL_ENV, customersOrgIdOf, registrarWanted, } from './boule.js';
+import { loginHostnameFor } from './login-host.js';
+import { brokerDeployRecordValue, missingBrokerInputs } from './platform-providers.js';
+import { testCustomersOrgKey } from './workspace-client.js';
+/**
+ * T3 (campaign 2026-10-20, apps-modules): a company with customers gets one registrar key at the sign-in
+ * broker, so its Boule can register the company's own apps there (`PUT /apps/:organizationId/:name`, auth ADR
+ * 0001 and 0003) without Archon. Foundry makes the key, holds it at {@link registrarRef}, writes the
+ * company's record into the broker's `AUTH_REGISTRARS` (`broker/src/apps.ts`'s `parseRegistrars`: the key
+ * itself, the company's sign-in organisation, its customers organisations, its login host) and gives Boule
+ * `AUTH_REGISTRAR_URL` (the broker's base, `<issuer>/api`, the address `@wtfalch/auth` already calls) and
+ * `AUTH_REGISTRAR_KEY`.
+ *
+ * Two steps deliver it, and either may run first: the Boule step (`coolify:boule`) puts the key in Boule's
+ * env, the registrar step (`coolify:broker-registrar`) puts the record in the broker's. Each mint gets an id
+ * (never the key) recorded at {@link REGISTRAR_MINTED_SCOPE_KEY}; each step records which mint it delivered,
+ * so a key made again reaches both places. The plan never holds the key.
+ */
+export const AUTH_REGISTRARS_ENV = 'AUTH_REGISTRARS';
+export { AUTH_REGISTRAR_KEY_ENV, AUTH_REGISTRAR_URL_ENV, registrarUrl, registrarWanted, } from './boule.js';
+/** The id of the held key's mint (a random id, not the key), set once it is held. Cleared when the key is forgotten. */
+export const REGISTRAR_MINTED_SCOPE_KEY = 'registrar_minted';
+/** The mint id whose key the last successful Boule env write carried. */
+export const REGISTRAR_DELIVERED_SCOPE_KEY = 'registrar_delivered';
+/** What the last successful broker write said (JSON of {@link RegistrarRecord} plus the mint id). Never the key. */
+export const REGISTRAR_APPLIED_SCOPE_KEY = 'broker_registrar_applied';
+/** The broker inputs that were missing when the record was written, so the broker was not deployed with it. */
+export const REGISTRAR_DEPLOY_WAITS_SCOPE_KEY = 'broker_registrar_deploy_waits';
+/** Why the last removal wrote nothing (another company's record the broker refuses), so the key was kept. Never a key. */
+export const REGISTRAR_REMOVAL_HELD_SCOPE_KEY = 'broker_registrar_removal_held';
+/** The held-key ref of a company's registrar key. */
+export const registrarRef = (orgId) => `foundry:registrar:${orgId}`;
+/** 32 random bytes, base64url: 43 characters, over the broker's 32-character floor. */
+export const mintRegistrarKey = () => randomBytes(32).toString('base64url');
+/**
+ * The company's registrar key: read from the held keys, else made and held first, and its mint id recorded
+ * and persisted before the key goes anywhere, so a crash after the `put` hands the same key out next time. A
+ * mint recorded but no longer held (F5, Q36: the held value was lost) is made again by this step, never by a
+ * person removing a record: the new mint id is recorded and persisted BEFORE the new key is held, so a crash
+ * between the two leaves a mint nobody was given and the next run makes another, and a crash after the `put`
+ * hands the held key out. The mint id differs from the lost one, so the Boule step and the broker step (each
+ * records which mint it delivered) both deliver the new key; the broker's write replaces the company's old
+ * record by its organisation. Errors name the ref, never the key. `secret` registers it for redaction; `log`
+ * gets one plain line when a lost key is made again.
+ */
+export async function ensureRegistrarKey(input) {
+    const ref = registrarRef(input.orgId);
+    const at = `the registrar key of ${input.slug}`;
+    const held = await input.heldKeys?.resolve(ref);
+    const recordedMint = input.recorded()[REGISTRAR_MINTED_SCOPE_KEY];
+    if (held) {
+        input.secret(held);
+        if (recordedMint)
+            return { key: held, mint: recordedMint };
+        // Held by a run that stopped before it recorded the mint: record one now, the key stays.
+        const mint = randomUUID();
+        input.record(REGISTRAR_MINTED_SCOPE_KEY, mint);
+        await input.persist();
+        return { key: held, mint };
+    }
+    if (typeof input.heldKeys?.put !== 'function') {
+        throw new Error(`${at}: the held keys cannot put it (ref ${ref})`);
+    }
+    const key = mintRegistrarKey();
+    input.secret(key);
+    const mint = randomUUID();
+    if (recordedMint) {
+        input.log?.(`${at} was made but is no longer held (ref ${ref}); making a new one, which Boule and the broker are given again`);
+        input.record(REGISTRAR_MINTED_SCOPE_KEY, mint);
+        await input.persist();
+        await input.heldKeys.put(ref, key);
+        return { key, mint };
+    }
+    await input.heldKeys.put(ref, key);
+    input.record(REGISTRAR_MINTED_SCOPE_KEY, mint);
+    await input.persist();
+    return { key, mint };
+}
+/**
+ * What the company's record says, or each input still missing and the step that records it. The customers
+ * organisation is an input only while `customers.enabled`: a company whose Boule runs apps (F5) without
+ * customers has a record with no customers, and the broker registers its apps against the sign-in organisation.
+ */
+export function wantedRegistrar(org, recorded) {
+    const organizationId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const hasCustomers = org.customers?.enabled === true;
+    const customersOrgId = hasCustomers ? customersOrgIdOf(org, recorded) : undefined;
+    const missing = [];
+    if (!organizationId) {
+        missing.push({
+            what: "the company's sign-in organisation id",
+            producedBy: ['zitadel', 'issuer'],
+        });
+    }
+    if (hasCustomers && !customersOrgId) {
+        missing.push({ what: 'the customers organisation id', producedBy: ['zitadel', 'customers'] });
+    }
+    if (!organizationId || (hasCustomers && !customersOrgId))
+        return { missing };
+    const testCustomersOrgId = hasCustomers ? recorded[testCustomersOrgKey(org.id)] : undefined;
+    return {
+        want: {
+            organizationId,
+            customers: [customersOrgId, testCustomersOrgId].filter((id) => Boolean(id)),
+            loginHost: loginHostnameFor(org),
+        },
+    };
+}
+/** The applied marker: the record and the mint it carries the key of. */
+export const registrarAppliedValue = (record, mint) => JSON.stringify({ ...record, mint });
+/** The organisation id the last broker write named, or null. */
+export function appliedRegistrarOrganization(recorded) {
+    const raw = recorded[REGISTRAR_APPLIED_SCOPE_KEY];
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return typeof value.organizationId === 'string' && value.organizationId
+            ? value.organizationId
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const HOSTNAME_RE = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::\d{1,5})?$/;
+const LONE_SURROGATE = /\p{Surrogate}/u;
+/**
+ * `null` when the broker's `parseRegistrars` takes `list`, else why not, naming the entry by its place and
+ * organisation, never its key. The broker stops at boot on a list it refuses, and then nobody signs in, so
+ * nothing is written that it would refuse.
+ */
+export function registrarsProblem(list, 
+/** How an entry is named; by default its place in `list`. */
+labelOf = (index) => `AUTH_REGISTRARS[${index}]`) {
+    const seenOrganizations = new Set();
+    const seenKeys = new Set();
+    for (const [index, entry] of list.entries()) {
+        const label = labelOf(index);
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            return `${label} is not an object`;
+        }
+        const r = entry;
+        if (typeof r.organizationId !== 'string' || !r.organizationId) {
+            return `${label} has no organizationId`;
+        }
+        const named = `${label} (organisation ${r.organizationId.slice(0, 64)})`;
+        if (typeof r.key !== 'string' || r.key.length < 32 || LONE_SURROGATE.test(r.key)) {
+            return `${named} has no usable key`;
+        }
+        if (r.customers !== undefined &&
+            (!Array.isArray(r.customers) || r.customers.some((id) => typeof id !== 'string' || !id))) {
+            return `${named} has customers that are not a list of organisation ids`;
+        }
+        if (r.loginHost !== undefined &&
+            (typeof r.loginHost !== 'string' || !HOSTNAME_RE.test(r.loginHost))) {
+            return `${named} has a loginHost that is not a bare host`;
+        }
+        const covered = [r.organizationId, ...(r.customers ?? [])];
+        if (new Set(covered).size !== covered.length)
+            return `${named} repeats an organisation`;
+        const clash = covered.find((id) => seenOrganizations.has(id));
+        if (clash)
+            return `${named} covers organisation ${clash}, which an earlier entry covers`;
+        if (seenKeys.has(r.key))
+            return `${named} repeats a key another entry uses`;
+        for (const id of covered)
+            seenOrganizations.add(id);
+        seenKeys.add(r.key);
+    }
+    return null;
+}
+/**
+ * Puts the company's record (or, with `record` null, takes it away) in the broker's `AUTH_REGISTRARS`,
+ * beside every other company's record, which is copied back as it was. The company's own record is the one
+ * naming its organisation, the organisation the last write named, any of `ownOrganizationIds`, or the one
+ * carrying `ownKey`. The read, change, write and deploy run under the `platform` lease (`BrokerPort`'s
+ * `withPlatformLease`), and the value is read again after the write: a record not as written fails the
+ * step. Deploys the broker when the value changed and the broker has its other inputs; otherwise returns
+ * the inputs it waits for, and the broker reads the record on its next deploy. Errors name the company and
+ * the reason, never a key.
+ */
+export async function writeRegistrar(broker, input) {
+    const label = `${input.slug}'s registrar at the broker`;
+    if (!broker.setEnv) {
+        throw new Error(`${label}: the broker port cannot set ${AUTH_REGISTRARS_ENV}`);
+    }
+    if (!broker.withPlatformLease) {
+        input.log?.(`${label}: the broker port takes no platform lease, so ${AUTH_REGISTRARS_ENV} is written unleased and only checked after`);
+        return writeRegistrarHeld(broker, input, label, undefined);
+    }
+    const ran = await broker.withPlatformLease((fence) => writeRegistrarHeld(broker, input, label, fence));
+    if ('heldUntil' in ran) {
+        throw new Error(`${label}: another platform change holds the broker's env until ${ran.heldUntil.toISOString()}, so nothing was written; apply again`);
+    }
+    return ran.value;
+}
+/** The registrar list as read: the array, or why it is not one. */
+function parseRegistrars(raw, label) {
+    let current = [];
+    if (raw) {
+        try {
+            current = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${label}: the broker's ${AUTH_REGISTRARS_ENV} is not JSON, so nothing was written`);
+        }
+    }
+    if (!Array.isArray(current)) {
+        throw new Error(`${label}: the broker's ${AUTH_REGISTRARS_ENV} is not a JSON array, so nothing was written`);
+    }
+    return current;
+}
+const sameStrings = (a, b) => Array.isArray(a) && a.length === b.length && a.every((id, i) => id === b[i]);
+async function writeRegistrarHeld(broker, input, label, fence) {
+    // Checked by the caller; bound to the port, which may be a class.
+    const setEnv = (key, value) => broker.setEnv.call(broker, key, value);
+    const brokerAppId = await broker.appId();
+    const envs = await broker.listEnvs();
+    const raw = envs.find((e) => e.key === AUTH_REGISTRARS_ENV && !e.is_preview)?.value;
+    const current = parseRegistrars(raw, label);
+    for (const existing of current) {
+        const key = existing?.key;
+        if (typeof key === 'string' && key)
+            input.secret?.(key);
+    }
+    if (input.record)
+        input.secret?.(input.record.key);
+    if (input.ownKey)
+        input.secret?.(input.ownKey);
+    const own = new Set([
+        input.record?.organizationId,
+        input.previousOrganizationId,
+        ...(input.ownOrganizationIds ?? []),
+    ].filter((id) => Boolean(id)));
+    const ownKeys = new Set([input.record?.key, input.ownKey].filter((key) => Boolean(key)));
+    const isOwn = (entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return false;
+        const { organizationId, key } = entry;
+        return ((typeof organizationId === 'string' && own.has(organizationId)) ||
+            (typeof key === 'string' && ownKeys.has(key)));
+    };
+    const entry = input.record
+        ? {
+            organizationId: input.record.organizationId,
+            key: input.record.key,
+            customers: [...input.record.customers],
+            loginHost: input.record.loginHost,
+        }
+        : null;
+    const next = [];
+    /** Each kept entry's place in the live list; null for the company's own new record. */
+    const places = [];
+    let placed = false;
+    for (const [index, existing] of current.entries()) {
+        if (!isOwn(existing)) {
+            next.push(existing);
+            places.push(index);
+            continue;
+        }
+        const existingKey = existing.key;
+        if (typeof existingKey !== 'string' || !ownKeys.has(existingKey)) {
+            const organizationId = String(existing.organizationId).slice(0, 64);
+            input.log?.(`${label}: ${entry ? 'replaced' : 'took away'} ${AUTH_REGISTRARS_ENV}[${index}] (organisation ${organizationId}), a record whose key is not the company's held key`);
+        }
+        if (entry && !placed) {
+            next.push(entry);
+            places.push(null);
+        }
+        placed = true;
+    }
+    if (entry && !placed) {
+        next.push(entry);
+        places.push(null);
+    }
+    const labelOf = (index) => {
+        const place = places[index];
+        return place === null || place === undefined
+            ? `${input.slug}'s own record`
+            : `${AUTH_REGISTRARS_ENV}[${place}]`;
+    };
+    const problem = registrarsProblem(next, labelOf);
+    if (problem !== null) {
+        // A removal leaves only other companies' records, so the problem is theirs: the broker refuses that list
+        // with or without this record. Nothing is written (a removal must not be what makes it worse), and the
+        // caller keeps the key, since the broker list still holds the record.
+        if (!entry) {
+            return {
+                changed: false,
+                waits: [],
+                removalHeld: `the broker's ${AUTH_REGISTRARS_ENV} holds a record it refuses, so nothing was written: ${problem}`,
+            };
+        }
+        throw new Error(`${label} is not written: the broker would refuse its ${AUTH_REGISTRARS_ENV} and not start (${problem})`);
+    }
+    const nextRaw = next.length === 0 ? '[]' : JSON.stringify(next);
+    const changed = nextRaw !== (raw || '[]');
+    if (!changed)
+        return { changed, waits: [] };
+    try {
+        await setEnv(AUTH_REGISTRARS_ENV, nextRaw);
+    }
+    catch {
+        // Fixed text: a Coolify error can echo the value, which holds every company's key.
+        throw new Error(`${label}: the broker's ${AUTH_REGISTRARS_ENV} could not be written; apply again`);
+    }
+    // Defence in depth beside the lease: a writer that holds no lease (a person, an older foundry) may have
+    // written over this one. The company's own record must read back as written.
+    const after = await broker.listEnvs();
+    const written = after.find((e) => e.key === AUTH_REGISTRARS_ENV && !e.is_preview)?.value;
+    let readBack = null;
+    try {
+        readBack = parseRegistrars(written, label);
+    }
+    catch {
+        readBack = null;
+    }
+    const mine = readBack?.filter(isOwn) ?? null;
+    const asWritten = mine !== null &&
+        (entry === null
+            ? mine.length === 0
+            : mine.length === 1 &&
+                mine[0].organizationId === entry.organizationId &&
+                mine[0].key === entry.key &&
+                mine[0].loginHost === entry.loginHost &&
+                sameStrings(mine[0].customers, entry.customers));
+    if (!asWritten) {
+        throw new Error(`${label}: the broker's ${AUTH_REGISTRARS_ENV} did not read back with the company's record ${entry ? 'as written' : 'taken away'} (something else wrote it at the same time), so the broker was not deployed; apply again`);
+    }
+    // The broker reads AUTH_REGISTRARS at start only. It cannot start without its other inputs; then the
+    // platform's own deploy, once they land, reads the record.
+    const waits = (await missingBrokerInputs({ listEnvs: async () => after }, brokerAppId)).filter((missing) => missing !== 'AUTH_APPS');
+    if (waits.length > 0)
+        return { changed, waits };
+    await broker.deploy();
+    const authApps = after.find((e) => e.key === 'AUTH_APPS' && !e.is_preview)?.value;
+    // This deploy carried the live AUTH_APPS too: record it, as an AUTH_APPS write does, so the platform's
+    // next apply does not read it as drift and deploy the broker again. Under the lease held here.
+    await broker.recordDeploy(brokerDeployRecordValue(brokerAppId, authApps), fence);
+    return { changed, waits };
+}
+/**
+ * The registrar for an org: whether the Boule step delivers the key (`deliver`), the broker step, and every
+ * reason either is held back as a plan line. Nothing at all for a company that never had customers, so
+ * its plan is unchanged.
+ */
+export function planBrokerRegistrar(org, recorded, plannedSteps, host) {
+    const at = `${org.slug}'s registrar key at the sign-in broker`;
+    const blocked = [];
+    const draft = (desired, description) => ({
+        action: { system: 'coolify', kind: 'broker-registrar', key: org.id, desired },
+        step: { description, destroys: false, migrates: false },
+    });
+    const waits = recorded[REGISTRAR_DEPLOY_WAITS_SCOPE_KEY];
+    if (waits) {
+        blocked.push(`${at} is in the broker's ${AUTH_REGISTRARS_ENV}, but the broker was not deployed with it: it has no ${waits} yet; it reads the record on its next deploy`);
+    }
+    if (!registrarWanted(org)) {
+        const left = Boolean(recorded[REGISTRAR_APPLIED_SCOPE_KEY]) ||
+            Boolean(recorded[REGISTRAR_MINTED_SCOPE_KEY]);
+        if (!left)
+            return { deliver: false, keepBouleEnv: false, step: null, blocked };
+        if (!host.brokerWired) {
+            blocked.push(`${at} is not removed: the company has no customers and its Boule runs no apps, but the host has not wired the broker port; Boule keeps its registrar env until it is`);
+            return { deliver: false, keepBouleEnv: true, step: null, blocked };
+        }
+        const held = recorded[REGISTRAR_REMOVAL_HELD_SCOPE_KEY];
+        if (held) {
+            blocked.push(`${at} is not removed and its key is kept: ${held}; fix or remove that record, and the next apply takes this one away`);
+        }
+        return {
+            deliver: false,
+            // Boule keeps the key while the broker still holds the record the removal could not take away.
+            keepBouleEnv: Boolean(held),
+            step: draft({ remove: true }, `remove ${org.slug}'s registrar from the sign-in broker and forget its key (no customers and no apps)`),
+            blocked,
+        };
+    }
+    if (!host.canHoldSecrets) {
+        blocked.push(`${at} is blocked, not planned: it needs a held-key store that can put, and the host has none`);
+        return { deliver: false, keepBouleEnv: false, step: null, blocked };
+    }
+    if (!host.brokerWired) {
+        blocked.push(`${at} is blocked, not planned: the host has not wired the broker port`);
+        return { deliver: false, keepBouleEnv: false, step: null, blocked };
+    }
+    // Boule is given the key only with the broker's address (`AUTH_REGISTRAR_URL`, from the issuer).
+    const deliver = host.issuerKnown;
+    if (!deliver) {
+        blocked.push(`${at} is not given to Boule yet: the issuer is not known, so ${AUTH_REGISTRAR_URL_ENV} cannot be given with it`);
+    }
+    const wanted = wantedRegistrar(org, recorded);
+    if ('missing' in wanted) {
+        const unplanned = wanted.missing.filter(({ producedBy: [system, kind] }) => !plannedSteps.some((p) => p.action.system === system && p.action.kind === kind));
+        if (unplanned.length > 0) {
+            blocked.push(`${at} is blocked, not planned: ${unplanned.map((m) => m.what).join(', ')} not recorded yet`);
+            return { deliver, keepBouleEnv: false, step: null, blocked };
+        }
+    }
+    else {
+        const mint = recorded[REGISTRAR_MINTED_SCOPE_KEY];
+        if (mint &&
+            recorded[REGISTRAR_APPLIED_SCOPE_KEY] === registrarAppliedValue(wanted.want, mint)) {
+            return { deliver, keepBouleEnv: false, step: null, blocked };
+        }
+    }
+    return {
+        deliver,
+        keepBouleEnv: false,
+        step: draft({}, `write ${org.slug}'s registrar into the sign-in broker's ${AUTH_REGISTRARS_ENV}`),
+        blocked,
+    };
+}
+/**
+ * The Boule env drift the registrar adds: the key missing, or not the mint the held key is (made again since
+ * Boule got it). And, once customers are off, the rows foundry wrote, which the Boule step takes away.
+ */
+export function bouleRegistrarDrift(org, recorded, liveEnv, deliver, 
+/** {@link planBrokerRegistrar}'s `keepBouleEnv`: the record stays at the broker, so Boule keeps the key. */
+keep = false) {
+    if (deliver) {
+        const mint = recorded[REGISTRAR_MINTED_SCOPE_KEY];
+        if (!liveEnv[AUTH_REGISTRAR_KEY_ENV] ||
+            !mint ||
+            recorded[REGISTRAR_DELIVERED_SCOPE_KEY] !== mint) {
+            return [AUTH_REGISTRAR_KEY_ENV];
+        }
+        return [];
+    }
+    if (!registrarWanted(org) &&
+        !keep &&
+        recorded[REGISTRAR_DELIVERED_SCOPE_KEY] &&
+        (liveEnv[AUTH_REGISTRAR_KEY_ENV] !== undefined || liveEnv[AUTH_REGISTRAR_URL_ENV] !== undefined)) {
+        return [AUTH_REGISTRAR_KEY_ENV];
+    }
+    return [];
+}

package/dist/plan/broker-workspaces-database.d.ts

@@ -0,0 +1,48 @@
+import type { CoolifyPort } from './executor.js';
+import type { ServiceTarget } from './own-services.js';
+/**
+ * The database of the auth broker's customer workspaces (`WORKSPACES_DATABASE_URL`), made by foundry on the
+ * Coolify server of the broker's own stack. It is a Coolify Postgres database `<owner>-workspaces-db` in the
+ * broker's project; its URL is held at `ServiceTarget.refs.brokerWorkspacesDatabase`, where an operator-held
+ * URL always was, and the broker-entry step writes it to the broker from there. A URL that is already held is
+ * adopted: nothing is made.
+ */
+/** One Coolify call of this step: the client has no timeout of its own. */
+export declare const WORKSPACES_DATABASE_CALL_TIMEOUT_MS = 60000;
+/** The wait for a new database to start (`getDatabaseStarted` polls up to two minutes, then a grace). */
+export declare const WORKSPACES_DATABASE_START_TIMEOUT_MS = 300000;
+/** The org-scope id that records the database's Coolify id (the id only; never the URL). */
+export declare const BROKER_WORKSPACES_DATABASE_SCOPE_KEY = "broker_workspaces_database";
+/** The Postgres database and role names inside it. */
+export declare const WORKSPACES_DATABASE_NAME = "workspaces";
+export type WorkspacesDatabaseCoolify = Pick<CoolifyPort, 'findOrCreateEnvironment' | 'listServers' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & 
+/** Absent on a company's own Coolify slice: the recorded id is then the only way back to a database made before. */
+Partial<Pick<CoolifyPort, 'listDatabases'>>;
+export interface WorkspacesDatabaseHeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+/** Whether the host can hold a URL: only then does foundry make the database, otherwise the operator holds one. */
+export declare const canHoldWorkspacesDatabase: (heldKeys: WorkspacesDatabaseHeldKeys | undefined) => heldKeys is WorkspacesDatabaseHeldKeys & Required<Pick<WorkspacesDatabaseHeldKeys, "put">>;
+/**
+ * Makes the database when no URL is held at the ref, and holds its URL there. Idempotent: a held URL is left
+ * alone (adopted), a database already made under the name is found, not made again, and a crash between the
+ * create and the hold leaves an empty database the next run finds and holds. Errors name the ref and the
+ * database's id, never the URL. `secret` registers the URL and its password for redaction before either leaves
+ * this function.
+ */
+export declare function ensureBrokerWorkspacesDatabase(input: {
+    target: ServiceTarget;
+    coolify: WorkspacesDatabaseCoolify;
+    /** The broker's Coolify project, or `null` when there is none (the stack is not there yet). */
+    projectUuid: () => Promise<string | null>;
+    heldKeys: WorkspacesDatabaseHeldKeys | undefined;
+    /** The database's Coolify id as recorded by an earlier run, if any. */
+    knownUuid?: string;
+    /** Records the id of a database just made, and persists it, before anything else is done with it. */
+    recordUuid: (uuid: string) => Promise<void>;
+    secret: (value: string) => void;
+    startTimeoutMs?: number;
+}): Promise<{
+    adopted: boolean;
+}>;

package/dist/plan/broker-workspaces-database.js

@@ -0,0 +1,87 @@
+import { withTimeout } from './call-timeout.js';
+import { heldWorkspacesDatabase } from './entry-workspaces.js';
+import { getDatabaseStarted } from './executor.js';
+import { resolvePlatformServer } from './platform-providers.js';
+/**
+ * The database of the auth broker's customer workspaces (`WORKSPACES_DATABASE_URL`), made by foundry on the
+ * Coolify server of the broker's own stack. It is a Coolify Postgres database `<owner>-workspaces-db` in the
+ * broker's project; its URL is held at `ServiceTarget.refs.brokerWorkspacesDatabase`, where an operator-held
+ * URL always was, and the broker-entry step writes it to the broker from there. A URL that is already held is
+ * adopted: nothing is made.
+ */
+/** One Coolify call of this step: the client has no timeout of its own. */
+export const WORKSPACES_DATABASE_CALL_TIMEOUT_MS = 60_000;
+/** The wait for a new database to start (`getDatabaseStarted` polls up to two minutes, then a grace). */
+export const WORKSPACES_DATABASE_START_TIMEOUT_MS = 300_000;
+/** The org-scope id that records the database's Coolify id (the id only; never the URL). */
+export const BROKER_WORKSPACES_DATABASE_SCOPE_KEY = 'broker_workspaces_database';
+/** The Postgres database and role names inside it. */
+export const WORKSPACES_DATABASE_NAME = 'workspaces';
+/** Whether the host can hold a URL: only then does foundry make the database, otherwise the operator holds one. */
+export const canHoldWorkspacesDatabase = (heldKeys) => typeof heldKeys?.put === 'function';
+/**
+ * Makes the database when no URL is held at the ref, and holds its URL there. Idempotent: a held URL is left
+ * alone (adopted), a database already made under the name is found, not made again, and a crash between the
+ * create and the hold leaves an empty database the next run finds and holds. Errors name the ref and the
+ * database's id, never the URL. `secret` registers the URL and its password for redaction before either leaves
+ * this function.
+ */
+export async function ensureBrokerWorkspacesDatabase(input) {
+    const { target, coolify, heldKeys } = input;
+    const ref = target.refs.brokerWorkspacesDatabase;
+    const at = `coolify:workspaces-database for ${target.id}`;
+    if (!canHoldWorkspacesDatabase(heldKeys)) {
+        throw new Error(`${at}: the held keys cannot put the database URL at ${ref}`);
+    }
+    const held = await withTimeout(`${at}: read ${ref}`, WORKSPACES_DATABASE_CALL_TIMEOUT_MS, () => heldWorkspacesDatabase(heldKeys, ref));
+    if (held) {
+        input.secret(held);
+        return { adopted: true };
+    }
+    const call = (what, work) => withTimeout(`${at}: ${what}`, WORKSPACES_DATABASE_CALL_TIMEOUT_MS, work);
+    const projectUuid = await call('find the project', input.projectUuid);
+    if (!projectUuid)
+        throw new Error(`${at}: the broker's Coolify project does not exist yet`);
+    const { environment } = await call('find the environment', () => coolify.findOrCreateEnvironment(projectUuid, 'production'));
+    const name = target.names.workspacesDb;
+    let uuid = input.knownUuid;
+    if (!uuid && coolify.listDatabases) {
+        const list = coolify.listDatabases.bind(coolify);
+        uuid = (await call('list the databases', () => list())).find((d) => d.name === name && d.environment_id === environment.id)?.uuid;
+    }
+    if (!uuid) {
+        const server = await call('list the servers', () => resolvePlatformServer(coolify));
+        uuid = (await call('create the database', () => coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name,
+            postgres_db: WORKSPACES_DATABASE_NAME,
+            postgres_user: WORKSPACES_DATABASE_NAME,
+        }))).uuid;
+    }
+    if (uuid !== input.knownUuid)
+        await input.recordUuid(uuid);
+    const db = await withTimeout(`${at}: start database ${uuid}`, input.startTimeoutMs ?? WORKSPACES_DATABASE_START_TIMEOUT_MS, () => getDatabaseStarted(coolify, uuid));
+    const url = db.internal_db_url;
+    if (!url) {
+        throw new Error(`${at}: database ${uuid} has no internal_db_url yet; apply again once Coolify reports one`);
+    }
+    input.secret(url);
+    let protocol = '';
+    try {
+        const parsed = new URL(url);
+        protocol = parsed.protocol;
+        if (parsed.password)
+            input.secret(decodeURIComponent(parsed.password));
+    }
+    catch {
+        protocol = '';
+    }
+    if (protocol !== 'postgres:' && protocol !== 'postgresql:') {
+        throw new Error(`${at}: database ${uuid} reports no postgres:// URL`);
+    }
+    await call(`hold the URL at ${ref}`, () => heldKeys.put(ref, url));
+    return { adopted: false };
+}

package/dist/plan/desktop-callback.js

@@ -1,6 +1,7 @@
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { appHostname, cmsStudioHostnameFor, entryHostnames } from './hostnames.js';
+import { workspaceAuthEntryOf, workspaceClientHosts } from './workspace-client.js';
 /**
  * #339: the desktop app signs in through the company's web app, so every
  * `@wtfalch/auth` web client foundry makes registers this path beside
@@ -24,15 +25,19 @@ export function signInRedirectUris(org, appKey) {
     if (appKey === 'agora')
         return [`https://${agoraHostnameFor(org)}/callback`];
     const authEntry = org.hosting.entries.find((e) => e.key === appKey && e.uses?.auth);
+    // A workspace's own client `<key>-work` signs in at the workspace host.
+    const workspaceEntry = authEntry ? undefined : workspaceAuthEntryOf(org, appKey);
     const hosts = authEntry
         ? entryHostnames(org, authEntry)
-        : [
-            appKey === 'cms' && org.site.enabled
-                ? cmsStudioHostnameFor(org)
-                : appKey === 'boule'
-                    ? bouleHostnameFor(org)
-                    : appHostname(org),
-        ];
+        : workspaceEntry
+            ? workspaceClientHosts(org, workspaceEntry)
+            : [
+                appKey === 'cms' && org.site.enabled
+                    ? cmsStudioHostnameFor(org)
+                    : appKey === 'boule'
+                        ? bouleHostnameFor(org)
+                        : appHostname(org),
+            ];
     return [
         ...hosts.map((host) => `https://${host}/auth/callback`),
         ...hosts.map(desktopCallbackUri),

package/dist/plan/diff.d.ts

@@ -65,6 +65,10 @@ export interface PlanOrgOptions {
     zitadelOrgMetadata?: boolean;
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
+    /** The broker the org's entries are written to has `WORKSPACES_DATABASE_URL`, or a URL is held to give it. Absent reads as false. */
+    brokerWorkspacesDatabase?: boolean;
+    /** F5b: the broker has none, and the host can make the database and hold its URL (`canProvisionWorkspacesDatabase`). Absent reads as false. */
+    provisionWorkspacesDatabase?: boolean;
     /** #161: the slugs of the other declared orgs, so a Boule whose hostname another org's slug would take is blocked. */
     otherSlugs?: readonly string[];
     /** F6a, F6b: the clock `planEntryAiKeys` and `planFilesKeys` read for the renewal window. Default `Date.now`. */
@@ -77,6 +81,8 @@ export interface PlanOrgOptions {
     workerApps?: boolean;
     /** ADR 0002: the keys service address, when the executor has a keys port. */
     workerAppKeysUrl?: string;
+    /** F7: the keys service's registrar address, when the executor has a `KeysRegistrarPort`. */
+    keysRegistrarUrl?: string;
     /** C2: true when the executor was built with a `WorkerAppDatabasePort`; a `workerApp.database` is blocked without it. */
     workerAppDatabase?: boolean;
     /** ADR 0002: the platform's Cloudflare account id; a container image must live in its registry. */
@@ -212,7 +218,7 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness, options?: PlanOrgOptions): PlanDetail;
+export declare function computePlanDetail(declaredOrg: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness, options?: PlanOrgOptions): PlanDetail;
 /** True when `org` is the platform's owner company. */
 export declare function isPlatformOwnOrg(org: Pick<DeclaredOrg, 'id'>, platformOwnerOrgId: string | null): boolean;
 /**
@@ -280,7 +286,7 @@ export declare const DEFAULT_AI_LIMIT_MICROS = "112250000";
  * record blocks it (rule 2). A foreign broker entry the last write found
  * invalid is listed as a warning: the broker drops it, foundry keeps it.
  */
-export declare function planBrokerEntries(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], brokerWired: boolean): {
+export declare function planBrokerEntries(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], brokerWired: boolean, brokerWorkspacesDatabase: boolean): {
     steps: DraftStep[];
     blocked: UnmanagedItem[];
 };