@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/broker-entries.d.ts

@@ -1,5 +1,5 @@
 import { type DeclaredOrg, type HostingEntry } from '../org.js';
-import type { DeclaredOrgStore, PlatformStore } from '../store.js';
+import type { DeclaredOrgStore, HeldLease, MutationLease, PlatformStore } from '../store.js';
 import type { CoolifyPort } from './executor.js';
 /**
  * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
@@ -62,6 +62,11 @@ export interface BrokerEntryWant {
         loginHost: string;
         onboardingUrl?: string;
     };
+    /** Present only for an entry with `uses.auth.workspaces`. The key's hash is not part of it: see {@link writeBrokerEntry}. */
+    workspaces?: {
+        roles: string[];
+        inviteUrl: string;
+    };
     /**
      * `true` for `signIn: 'email-code'`, `false` for an entry that declares `signIn: 'password'`.
      * Absent when the entry declares no `signIn`: a hand-set `emailLink` stays as it is.
@@ -95,10 +100,22 @@ export interface BrokerPort {
         is_preview: boolean;
     }>>;
     setAuthApps(raw: string): Promise<void>;
+    /** Sets one env of the broker app. Needed only to give the broker its `WORKSPACES_DATABASE_URL`. */
+    setEnv?(key: string, value: string): Promise<void>;
     deploy(): Promise<void>;
     /** The platform's `PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY` value, if any. */
     recordedDeploy(): Promise<string | undefined>;
-    recordDeploy(value: string): Promise<void>;
+    /** With `fence` (a `platform` lease the caller holds, from {@link withPlatformLease}) the write carries it and takes no lease itself. */
+    recordDeploy(value: string, fence?: MutationLease): Promise<void>;
+    /**
+     * T3b: runs `fn` holding the `platform` mutation lease, so two companies' applies never read, change and
+     * write a shared broker env (`AUTH_REGISTRARS`) at once. `fn` gets the lease (undefined for a port with
+     * no lease store), which its `recordDeploy` carries. Returns {@link HeldLease} while another holder has
+     * it, and `fn` does not run. Optional: a port without it writes unleased.
+     */
+    withPlatformLease?<T>(fn: (fence: MutationLease | undefined) => Promise<T>): Promise<{
+        value: T;
+    } | HeldLease>;
     /**
      * The id of Archon's own sign-in organisation, when the platform has made it.
      * No other entry may sign in that organisation, so an entry that does is
@@ -129,10 +146,14 @@ export declare class PlatformBrokerPort implements BrokerPort {
         is_preview: boolean;
     }[]>;
     setAuthApps(raw: string): Promise<void>;
+    setEnv(key: string, value: string): Promise<void>;
     deploy(): Promise<void>;
     recordedDeploy(): Promise<string | undefined>;
     archonOrganisationId(): Promise<string | undefined>;
-    recordDeploy(value: string): Promise<void>;
+    withPlatformLease<T>(fn: (fence: MutationLease | undefined) => Promise<T>): Promise<{
+        value: T;
+    } | HeldLease>;
+    recordDeploy(value: string, fence?: MutationLease): Promise<void>;
 }
 /**
  * Writes one entry's broker entry beside the others and deploys the broker
@@ -149,6 +170,10 @@ export declare function writeBrokerEntry(broker: BrokerPort, input: {
     want: BrokerEntryWant;
     appKey: string;
     previous: BrokerEntryWant | null;
+    /** sha256 hex of the entry's workspaces key. Required with `want.workspaces`; the key itself never reaches here. */
+    workspacesKeyHash?: string;
+    /** The operator's held connection string for the broker's workspaces database, written to the broker when it differs. */
+    workspacesDatabaseUrl?: string;
 }): Promise<{
     invalidForeign: string[];
     replaced: string | null;

package/dist/plan/broker-entries.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { isFoundryOwnedBrokerEntryName, } from '../org.js';
 import { entryClientIdScopeKey } from './agora.js';
 import { MCP_DATABASE_URL_ENV, MCP_OAUTH_SECRET_ENV } from './broker-mcp.js';
+import { BROKER_WORKSPACES_DATABASE_ENV, wantedWorkspaces, workspacesUrl, } from './entry-workspaces.js';
 import { entryHostnames } from './hostnames.js';
 import { loginHostnameFor } from './login-host.js';
 import { PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
@@ -80,6 +81,8 @@ export function entryAuthEnv(org, entry, recorded, issuer) {
         }
         : {};
     Object.assign(values, mcpValues);
+    if (auth.workspaces)
+        Object.assign(values, { WORKSPACES_URL: workspacesUrl(org) });
     return Object.fromEntries(Object.entries(values).filter(([, value]) => Boolean(value)));
 }
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
@@ -105,8 +108,17 @@ export function wantedBrokerEntry(org, entry, recorded) {
     if (auth.mcp && !mcp) {
         missing.push({ what: 'its MCP audience project id', producedBy: ['zitadel', 'mcp-project'] });
     }
-    if (!organizationId || !clientId || !mailDomain || (auth.mcp && !mcp))
+    const workspaces = wantedWorkspaces(org, entry);
+    if (auth.workspaces && !workspaces) {
+        missing.push({ what: 'its public address', producedBy: ['coolify', 'app'] });
+    }
+    if (!organizationId ||
+        !clientId ||
+        !mailDomain ||
+        (auth.mcp && !mcp) ||
+        (auth.workspaces && !workspaces)) {
         return { missing };
+    }
     return {
         want: {
             name: brokerEntryName(org, entry),
@@ -117,10 +129,13 @@ export function wantedBrokerEntry(org, entry, recorded) {
             registration: auth.registration === 'open',
             replaces: auth.replacesBrokerEntry ?? null,
             ...(mcp ? { mcp } : {}),
+            ...(workspaces ? { workspaces } : {}),
             ...(auth.signIn ? { emailLink: auth.signIn === 'email-code' } : {}),
         },
     };
 }
+/** How long {@link PlatformBrokerPort.withPlatformLease} holds the `platform` lease: an env write, two reads, a deploy call and a record. */
+const PLATFORM_LEASE_TTL_MS = 120_000;
 /** {@link BrokerPort} over the platform's recorded ids and a Coolify client. */
 export class PlatformBrokerPort {
     options;
@@ -141,6 +156,9 @@ export class PlatformBrokerPort {
             { key: 'AUTH_APPS', value: raw },
         ]);
     }
+    async setEnv(key, value) {
+        await this.options.coolify.bulkUpsertEnvs(await this.appId(), [{ key, value }]);
+    }
     async deploy() {
         await this.options.coolify.deploy(await this.appId());
     }
@@ -150,8 +168,27 @@ export class PlatformBrokerPort {
     async archonOrganisationId() {
         return (await this.options.store.getServiceIds())[PLATFORM_ARCHON_ORG_SCOPE_KEY] || undefined;
     }
-    async recordDeploy(value) {
+    async withPlatformLease(fn) {
+        const { leases } = this.options;
+        if (!leases)
+            return { value: await fn(undefined) };
+        const lease = await leases.acquireMutationLease('platform', randomUUID(), PLATFORM_LEASE_TTL_MS);
+        if (!('token' in lease))
+            return lease;
+        try {
+            return { value: await fn(lease) };
+        }
+        finally {
+            await leases.releaseMutationLease(lease).catch(() => undefined);
+        }
+    }
+    async recordDeploy(value, fence) {
         const { leases, store } = this.options;
+        if (fence) {
+            const ids = await store.getServiceIds();
+            await store.putServiceIds({ ...ids, [PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]: value }, fence);
+            return;
+        }
         const lease = await leases?.acquireMutationLease('platform', randomUUID(), 60_000);
         if (lease && !('token' in lease))
             return;
@@ -187,6 +224,24 @@ export async function writeBrokerEntry(broker, input) {
         throw new Error(`${label} would sign in Archon's own organisation, which no other entry may`);
     }
     const brokerEnvs = await broker.listEnvs();
+    // The broker does not start without the database once an entry declares workspaces, and then no one signs in.
+    let pendingDatabase = null;
+    if (want.workspaces) {
+        if (!input.workspacesKeyHash) {
+            throw new Error(`${label}: the workspaces key hash is missing, so nothing was written`);
+        }
+        const liveDatabase = brokerEnvs.find((e) => e.key === BROKER_WORKSPACES_DATABASE_ENV && !e.is_preview)?.value;
+        const wanted = input.workspacesDatabaseUrl ?? liveDatabase;
+        if (!wanted) {
+            throw new Error(`${label}: the broker has no ${BROKER_WORKSPACES_DATABASE_ENV}, so nothing was written`);
+        }
+        if (wanted !== liveDatabase) {
+            if (!broker.setEnv) {
+                throw new Error(`${label}: the broker port cannot set ${BROKER_WORKSPACES_DATABASE_ENV}`);
+            }
+            pendingDatabase = wanted;
+        }
+    }
     const env = brokerEnvs.find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
     // A value that reads back empty is not an empty list: writing over it
     // would drop every hand-written entry.
@@ -235,6 +290,15 @@ export async function writeBrokerEntry(broker, input) {
         entry.mcp = want.mcp;
     else
         entry.mcp = undefined;
+    // The previous write's `workspaces` goes when the entry no longer declares it; the key hash goes with it.
+    if (want.workspaces && input.workspacesKeyHash) {
+        entry.workspaces = want.workspaces;
+        entry.workspacesKey = input.workspacesKeyHash;
+    }
+    else {
+        entry.workspaces = undefined;
+        entry.workspacesKey = undefined;
+    }
     // A hand-set `emailLink` stays unless the entry declares `signIn`, or declared it before and stopped.
     if (want.emailLink !== undefined)
         entry.emailLink = want.emailLink;
@@ -275,6 +339,12 @@ export async function writeBrokerEntry(broker, input) {
         next.push(existing);
     });
     place();
+    // The database first: a failure after it leaves a broker env nothing reads yet, never an entry the broker cannot start with.
+    let databaseWritten = false;
+    if (pendingDatabase !== null) {
+        await broker.setEnv?.(BROKER_WORKSPACES_DATABASE_ENV, pendingDatabase);
+        databaseWritten = true;
+    }
     const nextRaw = JSON.stringify(next);
     const changed = JSON.stringify(current) !== nextRaw;
     if (changed) {
@@ -291,7 +361,8 @@ export async function writeBrokerEntry(broker, input) {
     // so that one does not hold back the deploy.
     const missing = (await missingBrokerInputs({ listEnvs: () => broker.listEnvs() }, brokerAppId)).filter((input) => input !== 'AUTH_APPS');
     const live = changed ? nextRaw : raw;
-    if (brokerDeployNeeded(missing, brokerAppId, live, parseBrokerDeployRecord(await broker.recordedDeploy()))) {
+    if (databaseWritten ||
+        brokerDeployNeeded(missing, brokerAppId, live, parseBrokerDeployRecord(await broker.recordedDeploy()))) {
         await broker.deploy();
         // The platform's record of what the broker last deployed, so its next
         // apply does not read this write as drift and deploy the broker again.

package/dist/plan/broker-registrar.d.ts

@@ -0,0 +1,168 @@
+import type { DeclaredOrg } from '../org.js';
+import type { BrokerEntryInput, BrokerPort } from './broker-entries.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 declare 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 declare const REGISTRAR_MINTED_SCOPE_KEY = "registrar_minted";
+/** The mint id whose key the last successful Boule env write carried. */
+export declare 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 declare 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 declare 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 declare const REGISTRAR_REMOVAL_HELD_SCOPE_KEY = "broker_registrar_removal_held";
+/** The held-key ref of a company's registrar key. */
+export declare const registrarRef: (orgId: string) => string;
+/** 32 random bytes, base64url: 43 characters, over the broker's 32-character floor. */
+export declare const mintRegistrarKey: () => string;
+interface HeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+/**
+ * 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 declare function ensureRegistrarKey(input: {
+    orgId: string;
+    slug: string;
+    heldKeys: HeldKeys | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    secret: (value: string) => void;
+    log?: (line: string) => void;
+}): Promise<{
+    key: string;
+    mint: string;
+}>;
+/** The company's record in `AUTH_REGISTRARS`, without its key. */
+export interface RegistrarRecord {
+    /** The company's own sign-in organisation (its Boule's `AUTH_ORGANIZATION_ID`). */
+    organizationId: string;
+    /** Its customers organisation, then its test customers organisation once that exists. */
+    customers: string[];
+    loginHost: string;
+}
+/**
+ * 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 declare function wantedRegistrar(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    want: RegistrarRecord;
+} | {
+    missing: BrokerEntryInput[];
+};
+/** The applied marker: the record and the mint it carries the key of. */
+export declare const registrarAppliedValue: (record: RegistrarRecord, mint: string) => string;
+/** The organisation id the last broker write named, or null. */
+export declare function appliedRegistrarOrganization(recorded: Readonly<Record<string, string>>): string | null;
+/**
+ * `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 declare function registrarsProblem(list: readonly unknown[], 
+/** How an entry is named; by default its place in `list`. */
+labelOf?: (index: number) => string): string | null;
+/** What {@link writeRegistrar} did: whether the value changed, what the broker waits for, and why a removal wrote nothing. */
+export interface RegistrarWrite {
+    changed: boolean;
+    waits: string[];
+    /**
+     * A removal that wrote nothing because another company's record in the list is one the broker refuses
+     * (it would not start on that list with or without this company's record). The company's record stays,
+     * so its key is kept. Names the entry by its place, never a key.
+     */
+    removalHeld?: string;
+}
+/**
+ * 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 declare function writeRegistrar(broker: BrokerPort, input: {
+    slug: string;
+    record: (RegistrarRecord & {
+        key: string;
+    }) | null;
+    previousOrganizationId: string | null;
+    /** More organisations whose record is this company's (its recorded sign-in organisation), for a removal after a crash before the applied marker. */
+    ownOrganizationIds?: readonly string[];
+    /** The company's held key: a record carrying it is the company's whatever organisation it names. */
+    ownKey?: string | null;
+    /** Told every key it reads or writes (every company's), so the caller can redact them from an error. */
+    secret?: (value: string) => void;
+    /** One plain line per thing worth a log (a replaced hand-written record, an unleased write). Never a key. */
+    log?: (line: string) => void;
+}): Promise<RegistrarWrite>;
+/** A planned step, as `diff.ts` collects them. */
+interface RegistrarDraftStep {
+    action: {
+        system: 'coolify';
+        kind: string;
+        key: string;
+        desired: Record<string, unknown>;
+    };
+    step: {
+        description: string;
+        destroys: boolean;
+        migrates: boolean;
+    };
+}
+/**
+ * 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 declare function planBrokerRegistrar(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, plannedSteps: ReadonlyArray<{
+    action: {
+        system: string;
+        kind: string;
+    };
+}>, host: {
+    brokerWired: boolean;
+    canHoldSecrets: boolean;
+    issuerKnown: boolean;
+}): {
+    deliver: boolean;
+    /** Customers are off but the record cannot be taken away yet: Boule keeps its registrar env, in step with it. */
+    keepBouleEnv: boolean;
+    step: RegistrarDraftStep | null;
+    blocked: string[];
+};
+/**
+ * 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 declare function bouleRegistrarDrift(org: Pick<DeclaredOrg, 'customers' | 'boule'>, recorded: Readonly<Record<string, string>>, liveEnv: Readonly<Record<string, string>>, deliver: boolean, 
+/** {@link planBrokerRegistrar}'s `keepBouleEnv`: the record stays at the broker, so Boule keeps the key. */
+keep?: boolean): string[];