@wtfalch/foundry 0.60.0 → 0.61.0

package/dist/plan/blue-green-apply.js

@@ -7,10 +7,11 @@ import { waitForNewDeployment } from './deploy-health.js';
 import { commandHealthCheckSettings, wgetProbe } from './health-check-settings.js';
 import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
 import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
-import { buildStageEnv } from './stage-env.js';
+import { STAGE_SIGN_IN_NAMES, buildStageEnv } from './stage-env.js';
 import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
 import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
 import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_APP_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_IMAGE_TAG, STAGE_SINK_REPOSITORY, stageMailEnv, stageSinkAppName, } from './stage-sink.js';
+import { readWorkspaceCommit, wsKey } from './workspace.js';
 /** How long one Coolify call of the sink may take. */
 const SINK_CALL_TIMEOUT_MS = 30_000;
 /** Env names whose value is a credential: registered before they are copied. */
@@ -97,6 +98,30 @@ export async function applyBlueGreenServer(deps, subject, server) {
     deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
     await deps.persist();
 }
+/**
+ * Applies a server workspace on the primary: the stage mail sink, then the stage app with its own empty
+ * database, the stage guards and the gate, exactly as a blue/green stage, and no colors. The commit the stage
+ * deployed is recorded as `ws.<id>.commit` for the live app to pin to. A failure halfway leaves the sink, app
+ * and database already made, recorded by id; the next run finds them and does the rest. Stage fails closed for
+ * itself: a refused guard records `bg.<id>.stagestate` and writes nothing to the stage app.
+ */
+export async function applyWorkspaceServer(deps, subject, serverUuid) {
+    const sinkReady = await ensureStageSink(deps, subject, serverUuid);
+    await ensureStage(deps, subject, serverUuid);
+    if (!sinkReady) {
+        deps.record(bgKey.stageState(subject.id), 'blocked:sink');
+        await deps.persist();
+    }
+    const stageId = deps.recorded()[bgKey.app(subject.id, serverUuid, 'stage')];
+    if (stageId && deps.recorded()[bgKey.stageState(subject.id)] === 'ok') {
+        const commit = (await readWorkspaceCommit(deps.coolify, stageId)) ??
+            deps.recorded()[bgKey.stage(subject.id)];
+        if (commit) {
+            deps.record(wsKey.commit(subject.id), commit);
+            await deps.persist();
+        }
+    }
+}
 /** Writes the balancer's config with the recorded weights and records them for this server. */
 export async function applyBlueGreenWeights(deps, subject, server) {
     const weights = parseWeights(deps.recorded()[bgKey.weights(subject.id)]);
@@ -109,15 +134,14 @@ export async function applyBlueGreenWeights(deps, subject, server) {
 }
 async function writeLbConfig(deps, subject, server, lbId, weights) {
     const onPrimary = server.isPrimary;
-    let pinKey = deps.recorded()[bgKey.pinKey(subject.id)];
-    if (!pinKey) {
-        pinKey = randomBytes(32).toString('hex');
-        deps.record(bgKey.pinKey(subject.id), pinKey);
-        await deps.persist();
-    }
+    const pinKey = await deps.pinKey();
+    // The idle slot is the one `bg.<id>.live` does not name; the preview router follows it on every weight write.
+    const idle = deps.recorded()[bgKey.live(subject.id)] === 'green' ? 'blue' : 'green';
     const content = renderLbConfig({
         weights,
         pinKey,
+        idle,
+        reporting: subject.reporting,
         backends: {
             blue: [colorBackend(subject, 'blue', onPrimary)],
             green: [colorBackend(subject, 'green', onPrimary)],
@@ -211,14 +235,16 @@ async function ensureGitApp(deps, subject, input) {
         await deps.persist();
         return found.uuid;
     }
-    const githubApp = await coolify.requireGithubApp();
+    const githubAppUuid = deps.githubAppUuid
+        ? await deps.githubAppUuid(subject.repo)
+        : (await coolify.requireGithubApp()).uuid;
     const created = await coolify.createGithubAppApplication({
         is_preview_deployments_enabled: false,
         project_uuid: deps.projectUuid,
         server_uuid: input.server,
         environment_name: deps.environment.name,
         environment_uuid: deps.environment.uuid,
-        github_app_uuid: githubApp.uuid,
+        github_app_uuid: githubAppUuid,
         git_repository: subject.repo,
         git_branch: input.branch,
         build_pack: subject.buildPack,
@@ -319,7 +345,7 @@ async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
  * the sink deploys; a failure clears it, logs fixed text and the error name, and returns false. Production's
  * structure goes on (stage then holds no mail env and the copy stays refused).
  */
-async function ensureStageSink(deps, subject, serverUuid) {
+export async function ensureStageSink(deps, subject, serverUuid) {
     const org = deps.stageSink;
     if (!org)
         return true;
@@ -377,7 +403,7 @@ async function ensureStageSink(deps, subject, serverUuid) {
     return true;
 }
 /** The stage app and its own empty database, on the primary. Its env comes from the allowlist, never from a copy of the live app's. */
-async function ensureStage(deps, subject, serverUuid) {
+export async function ensureStage(deps, subject, serverUuid) {
     const { coolify } = deps;
     const name = stageAppName(subject.base);
     const appId = await stageAppId(deps, subject, name, serverUuid);
@@ -419,12 +445,12 @@ async function ensureStage(deps, subject, serverUuid) {
         }
     }
     const kind = stageKindOf(subject);
-    const prodEnv = await coolify.listEnvs(deps.primaryBlueAppId);
+    const prodEnv = deps.primaryBlueAppId ? await coolify.listEnvs(deps.primaryBlueAppId) : [];
     const greenId = deps.recorded()[bgKey.app(subject.id, serverUuid, 'green')];
     const greenEnv = greenId ? await coolify.listEnvs(greenId) : [];
     const { env } = buildStageEnv({
         kind,
-        appUrl: stageAppUrl(subject),
+        appUrl: deps.stageAppUrl ?? stageAppUrl(subject),
         logDir: deps.logDir,
         database,
         prod: prodEnv,
@@ -434,8 +460,14 @@ async function ensureStage(deps, subject, serverUuid) {
             deps.secret(value);
             return value;
         },
+        ...(deps.signIn ? { signIn: deps.signIn } : {}),
     });
     const stageEnv = [...env];
+    const signInEnv = deps.signIn ? env.filter((e) => STAGE_SIGN_IN_NAMES.includes(e.key)) : [];
+    // A secret kept from an earlier apply was not minted by this run, so it is registered here.
+    for (const e of signInEnv)
+        if (envClass(e.key) === 'secret')
+            deps.secret(e.value);
     if (subject.reporting && deps.actionsKey) {
         // Stage never shares a production secret: its key is its own, minted once and kept.
         const have = (await coolify.listEnvs(appId)).find((e) => e.key === ACTIONS_KEY_ENV && !e.is_preview);
@@ -447,7 +479,7 @@ async function ensureStage(deps, subject, serverUuid) {
     const sinkApplied = deps.stageSink && deps.recorded()[STAGE_SINK_APPLIED_SCOPE_KEY];
     const mail = deps.stageSink && sinkApplied ? stageMailEnv(deps.stageSink) : [];
     const stageHas = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
-    const mailChanged = mail.some((e) => stageHas.get(e.key) !== e.value);
+    const mailChanged = [...mail, ...signInEnv].some((e) => stageHas.get(e.key) !== e.value);
     stageEnv.push(...mail);
     const stageSurface = {
         env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
@@ -464,6 +496,9 @@ async function ensureStage(deps, subject, serverUuid) {
         },
         stage: stageSurface,
         sinkMail: Object.fromEntries(mail.map((e) => [e.key, e.value])),
+        ...(deps.signIn
+            ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
+            : {}),
     });
     if (violations.length > 0) {
         // Stage fails closed for itself: nothing is written to it, production's structure goes on.
@@ -483,7 +518,12 @@ async function ensureStage(deps, subject, serverUuid) {
         probeResult = await runStageProbes(buildStageProbes({
             port: deps.stageGuards?.probes,
             stage: stageValues,
-            database: subject.database,
+            // With no live app there is no production database to try the stage role against.
+            database: subject.database && deps.primaryBlueAppId !== null,
+            ...(deps.signIn?.live.customersOrgId
+                ? { liveCustomersOrgId: deps.signIn.live.customersOrgId }
+                : {}),
+            ...(deps.signIn ? { signInRedirectUri: deps.signIn.redirectUri } : {}),
             prod: new Map(prodEnv
                 .filter((e) => !e.is_preview && e.value !== undefined)
                 .map((e) => [e.key, e.value])),

package/dist/plan/blue-green.d.ts

@@ -46,7 +46,10 @@ export declare const bgKey: {
     stageState: (id: string) => string;
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id: string) => string;
-    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    /**
+     * The held ref of the balancer's pin key (a credential: it lets a caller pick a color). A value that is 64 hex
+     * characters is the older recorded key, moved to the held ref on the next read and then overwritten by the ref.
+     */
     pinKey: (id: string) => string;
     /** The hash of the stage env name set and resource set that passed the isolation check. */
     stageIsolation: (id: string) => string;
@@ -91,6 +94,34 @@ export declare function mintActionsKey(input: {
     /** Registers the value for redaction before it is written anywhere. */
     secret: (value: string) => void;
 }): Promise<string>;
+/** The held-key name of a subject's balancer pin key: one mint per subject. */
+export declare const pinKeyName: (id: string) => string;
+/** The held store the pin key lives in; `put` is absent on a host that cannot mint. */
+export interface PinHeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+interface PinKeyInput {
+    id: string;
+    ref: string;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    heldKeys: PinHeldKeys;
+    /** Registers the value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+}
+/**
+ * The balancer's pin key, held (CLAUDE.md, Platform steps, rules 1 and 6). Order: the held key; else the older
+ * recorded key (64 hex), put in the held store and replaced by the ref; else one mint, put first, then the ref is
+ * recorded and persisted. A crash between the put and the record reuses the held key. A recorded ref whose key is
+ * no longer held stops: it never mints again. Errors name the ref only.
+ */
+export declare function mintPinKey(input: PinKeyInput & {
+    generate: () => string;
+}): Promise<string>;
+/** Reads the pin key without minting: the held key, else the older recorded key, else null. */
+export declare function readPinKey(input: Omit<PinKeyInput, 'record' | 'persist'>): Promise<string | null>;
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export declare const healthTokenName: (id: string) => string;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -200,6 +231,10 @@ export declare const LB_COOKIE_NAME = "bg_color";
 export declare const LB_COLOR_HEADER = "X-Foundry-Color";
 /** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
 export declare const LB_PIN_HEADER = "X-Foundry-Pin";
+/** The cookie that sends a signed-in person with `releases:preview` to the idle slot. */
+export declare const LB_PREVIEW_COOKIE = "bg_preview";
+/** The path the balancer asks the live slot whether a request may see the idle slot. */
+export declare const LB_PREVIEW_CHECK_PATH = "/api/foundry/preview-check";
 export declare const LB_CONFIG_PATH = "/etc/traefik/dynamic/lb.yml";
 /**
  * The balancer's inline Dockerfile: a pinned Traefik with a file provider watching one directory.
@@ -218,6 +253,10 @@ export declare function renderLbConfig(input: {
     weights: Weights;
     backends: Record<Color, string[]>;
     pinKey: string;
+    /** The slot that is not live: the `preview` router sends a cookie holder here. */
+    idle: Color;
+    /** True when the subject has a server that can answer the permission check; a static subject gets no router. */
+    reporting: boolean;
 }): string;
 /**
  * The URL of one color's container on its own server's network. On the primary, blue is the app that was
@@ -324,3 +363,4 @@ export declare function planArchonBlueGreen(input: {
     step: BlueGreenPlanStep | null;
     unmanaged: UnmanagedLine[];
 };
+export {};

package/dist/plan/blue-green.js

@@ -55,7 +55,10 @@ export const bgKey = {
     stageState: (id) => `bg.${id}.stagestate`,
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id) => `bg.${id}.bluename`,
-    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    /**
+     * The held ref of the balancer's pin key (a credential: it lets a caller pick a color). A value that is 64 hex
+     * characters is the older recorded key, moved to the held ref on the next read and then overwritten by the ref.
+     */
     pinKey: (id) => `bg.${id}.pinkey`,
     /** The hash of the stage env name set and resource set that passed the isolation check. */
     stageIsolation: (id) => `bg.${id}.stageisolation`,
@@ -102,6 +105,56 @@ export async function mintActionsKey(input) {
     await input.persist();
     return key;
 }
+/** The held-key name of a subject's balancer pin key: one mint per subject. */
+export const pinKeyName = (id) => `bg-pin-${id}`;
+/**
+ * The balancer's pin key, held (CLAUDE.md, Platform steps, rules 1 and 6). Order: the held key; else the older
+ * recorded key (64 hex), put in the held store and replaced by the ref; else one mint, put first, then the ref is
+ * recorded and persisted. A crash between the put and the record reuses the held key. A recorded ref whose key is
+ * no longer held stops: it never mints again. Errors name the ref only.
+ */
+export async function mintPinKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    const recordedValue = input.recorded()[bgKey.pinKey(input.id)];
+    if (held) {
+        input.secret(held);
+        if (recordedValue !== input.ref) {
+            input.record(bgKey.pinKey(input.id), input.ref);
+            await input.persist();
+        }
+        return held;
+    }
+    const put = input.heldKeys.put?.bind(input.heldKeys);
+    if (!put)
+        throw new Error(`pin key ${input.ref} cannot be held: the host has no held store to write`);
+    if (recordedValue && PIN_KEY.test(recordedValue)) {
+        input.secret(recordedValue);
+        await put(input.ref, recordedValue);
+        input.record(bgKey.pinKey(input.id), input.ref);
+        await input.persist();
+        return recordedValue;
+    }
+    if (recordedValue) {
+        throw new Error(`pin key ${input.ref} was minted but is no longer held; restore the held value`);
+    }
+    const key = input.generate();
+    input.secret(key);
+    await put(input.ref, key);
+    input.record(bgKey.pinKey(input.id), input.ref);
+    await input.persist();
+    return key;
+}
+/** Reads the pin key without minting: the held key, else the older recorded key, else null. */
+export async function readPinKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    const value = held ||
+        (PIN_KEY.test(input.recorded()[bgKey.pinKey(input.id)] ?? '')
+            ? input.recorded()[bgKey.pinKey(input.id)]
+            : null);
+    if (value)
+        input.secret(value);
+    return value ?? null;
+}
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export const healthTokenName = (id) => `reporting-health-${id}`;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -246,6 +299,11 @@ export const LB_COLOR_HEADER = 'X-Foundry-Color';
 /** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
 export const LB_PIN_HEADER = 'X-Foundry-Pin';
 const PIN_KEY = /^[0-9a-f]{64}$/;
+/** The cookie that sends a signed-in person with `releases:preview` to the idle slot. */
+export const LB_PREVIEW_COOKIE = 'bg_preview';
+/** The path the balancer asks the live slot whether a request may see the idle slot. */
+export const LB_PREVIEW_CHECK_PATH = '/api/foundry/preview-check';
+const LB_PREVIEW_PRIORITY = 9000;
 /** Above the default priority of `app` (its rule length), so a pinned request never reaches the weighted service. */
 const LB_PIN_PRIORITY = 10000;
 export const LB_CONFIG_PATH = '/etc/traefik/dynamic/lb.yml';
@@ -272,7 +330,8 @@ export const LB_IMAGE_REF = `traefik:${VERSIONS.traefik}`;
  * line, so a reader sees both numbers. `backends` are the URLs of each color's containers, one per server.
  */
 export function renderLbConfig(input) {
-    const { weights, backends, pinKey } = input;
+    const { weights, backends, pinKey, idle } = input;
+    const live = COLORS.find((color) => color !== idle);
     if (!PIN_KEY.test(pinKey))
         throw new Error('the load balancer pin key is not 64 hex characters');
     const listed = COLORS.filter((color) => weights[color] > 0);
@@ -287,10 +346,29 @@ export function renderLbConfig(input) {
             `      entryPoints: [${LB_ENTRYPOINT}]`,
             `      service: ${color}`,
         ]),
+        ...(input.reporting
+            ? [
+                '    preview:',
+                `      rule: HeaderRegexp(\`Cookie\`, \`(^|;\\s*)${LB_PREVIEW_COOKIE}=1\`)`,
+                `      priority: ${LB_PREVIEW_PRIORITY}`,
+                `      entryPoints: [${LB_ENTRYPOINT}]`,
+                `      service: ${idle}`,
+                '      middlewares: [preview-check]',
+            ]
+            : []),
         '    app:',
         '      rule: PathPrefix(`/`)',
         `      entryPoints: [${LB_ENTRYPOINT}]`,
         '      service: weighted',
+        ...(input.reporting
+            ? [
+                '  middlewares:',
+                '    preview-check:',
+                '      forwardAuth:',
+                `        address: ${backends[live][0]}${LB_PREVIEW_CHECK_PATH}`,
+                '        trustForwardHeader: false',
+            ]
+            : []),
         '  services:',
         '    weighted:',
         '      weighted:',

package/dist/plan/boule.d.ts

@@ -91,6 +91,12 @@ export declare const BOULE_ARCHON_CREDENTIAL_ENV = "ARCHON_CREDENTIAL";
 /** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
 export declare const BOULE_CUSTOMERS_ORG_ENV = "CUSTOMERS_ORGANISATION_ID";
 export declare const BOULE_CUSTOMERS_CREDENTIAL_ENV = "CUSTOMERS_DIRECTORY_CREDENTIAL";
+/**
+ * F5 (Q44): the company's test customers organisation, beside {@link BOULE_CUSTOMERS_ORG_ENV}, so a workspace copy
+ * of an app registers its sign-in against it. Written once the organisation is recorded (a server workspace with
+ * customers makes it); the plan plans Boule again then, as it does for the customers organisation.
+ */
+export declare const BOULE_TEST_CUSTOMERS_ORG_ENV = "TEST_CUSTOMERS_ORGANISATION_ID";
 /**
  * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
  * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
@@ -130,9 +136,25 @@ export interface BouleCredentialWants {
     customersDirectory?: boolean;
     /** The recorded Archon credential is missing or 335 days old: the step mints it again. */
     archonRenewDue?: boolean;
+    /** F13: Boule is given `CUSTOMER_GRANTS` (an entry declares `uses.customerGrants`; needs `customersDirectory`). */
+    customerGrants?: boolean;
+    /** T3: Boule is given its company's registrar key at the sign-in broker (`plan/broker-registrar.ts`). */
+    registrar?: boolean;
+    /** T3b: customers are off but the broker still holds the record, so Boule keeps its registrar env (plan only). */
+    registrarKept?: boolean;
 }
+/** T3: the broker's base and the company's registrar key, in Boule's env (`plan/broker-registrar.ts`). */
+export declare const AUTH_REGISTRAR_URL_ENV = "AUTH_REGISTRAR_URL";
+export declare const AUTH_REGISTRAR_KEY_ENV = "AUTH_REGISTRAR_KEY";
+/**
+ * A company gets a registrar while it has customers (the people its own apps sign in) or its Boule runs apps
+ * (F5: any company that installs an app with sign-in, `org.boule.apps`).
+ */
+export declare const registrarWanted: (org: Pick<DeclaredOrg, "customers" | "boule">) => boolean;
+/** The broker's base as Boule calls it: `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`. */
+export declare const registrarUrl: (issuer: string) => string;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "SIGNIN_UPSTREAM"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "TEST_CUSTOMERS_ORGANISATION_ID", "CUSTOMER_GRANTS", "SIGNIN_UPSTREAM", "AUTH_REGISTRAR_URL", "AUTH_REGISTRAR_KEY"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a

package/dist/plan/boule.js

@@ -1,6 +1,7 @@
-import { DEFAULT_NO_REPLY_LOCAL_PART, ownerMailboxes, } from '../org.js';
+import { DEFAULT_NO_REPLY_LOCAL_PART, appsOn, ownerMailboxes, } from '../org.js';
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
 import { SIGN_IN_UPSTREAM_ENV, inAppHostApplied, signInUpstream, staleSignInUpstream, } from './sign-in.js';
+import { testCustomersOrgKey } from './workspace-client.js';
 /**
  * #161 (Boule part): what both the planner (`diff.ts`) and the executor
  * (`executor.ts`) need to agree on for an org's Boule -- the hostname, the
@@ -102,6 +103,12 @@ export const BOULE_ARCHON_CREDENTIAL_ENV = 'ARCHON_CREDENTIAL';
 /** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
 export const BOULE_CUSTOMERS_ORG_ENV = 'CUSTOMERS_ORGANISATION_ID';
 export const BOULE_CUSTOMERS_CREDENTIAL_ENV = 'CUSTOMERS_DIRECTORY_CREDENTIAL';
+/**
+ * F5 (Q44): the company's test customers organisation, beside {@link BOULE_CUSTOMERS_ORG_ENV}, so a workspace copy
+ * of an app registers its sign-in against it. Written once the organisation is recorded (a server workspace with
+ * customers makes it); the plan plans Boule again then, as it does for the customers organisation.
+ */
+export const BOULE_TEST_CUSTOMERS_ORG_ENV = 'TEST_CUSTOMERS_ORGANISATION_ID';
 /**
  * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
  * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
@@ -144,6 +151,16 @@ export const bouleArchonCredentialRef = (orgId) => `foundry:boule-archon:${orgId
 export const customersDirectoryRef = (orgId) => `foundry:customers-directory:${orgId}`;
 /** The customers organisation id `zitadel:customers` recorded. */
 export const customersOrgIdOf = (org, recorded) => recorded[`zitadel:customers:${org.id}`] || undefined;
+/** T3: the broker's base and the company's registrar key, in Boule's env (`plan/broker-registrar.ts`). */
+export const AUTH_REGISTRAR_URL_ENV = 'AUTH_REGISTRAR_URL';
+export const AUTH_REGISTRAR_KEY_ENV = 'AUTH_REGISTRAR_KEY';
+/**
+ * A company gets a registrar while it has customers (the people its own apps sign in) or its Boule runs apps
+ * (F5: any company that installs an app with sign-in, `org.boule.apps`).
+ */
+export const registrarWanted = (org) => org.customers?.enabled === true || appsOn(org);
+/** The broker's base as Boule calls it: `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`. */
+export const registrarUrl = (issuer) => `${issuer.replace(/\/+$/, '')}/api`;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -163,7 +180,11 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_ARCHON_CREDENTIAL_ENV,
     BOULE_CUSTOMERS_ORG_ENV,
     BOULE_CUSTOMERS_CREDENTIAL_ENV,
+    BOULE_TEST_CUSTOMERS_ORG_ENV,
+    'CUSTOMER_GRANTS',
     SIGN_IN_UPSTREAM_ENV,
+    AUTH_REGISTRAR_URL_ENV,
+    AUTH_REGISTRAR_KEY_ENV,
 ];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
@@ -218,6 +239,14 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = f
     const customersOrgId = wants.customersDirectory ? customersOrgIdOf(org, recorded) : undefined;
     if (customersOrgId)
         env[BOULE_CUSTOMERS_ORG_ENV] = customersOrgId;
+    const testCustomersOrgId = wants.customersDirectory
+        ? recorded[testCustomersOrgKey(org.id)]
+        : undefined;
+    if (testCustomersOrgId)
+        env[BOULE_TEST_CUSTOMERS_ORG_ENV] = testCustomersOrgId;
+    // The key itself is a secret the executor writes; the plan compares it by presence (`bouleRegistrarDrift`).
+    if (wants.registrar && issuer)
+        env[AUTH_REGISTRAR_URL_ENV] = registrarUrl(issuer);
     const owner = org.owners[0];
     const ownerUserId = owner
         ? recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`]
@@ -355,5 +384,9 @@ export function planBouleOwners(org, recorded, liveBouleEnv) {
 export function staleCustomersEnv(org, live) {
     if (org.customers?.enabled)
         return [];
-    return [BOULE_CUSTOMERS_ORG_ENV, BOULE_CUSTOMERS_CREDENTIAL_ENV].filter((key) => live[key] !== undefined);
+    return [
+        BOULE_CUSTOMERS_ORG_ENV,
+        BOULE_TEST_CUSTOMERS_ORG_ENV,
+        BOULE_CUSTOMERS_CREDENTIAL_ENV,
+    ].filter((key) => live[key] !== undefined);
 }

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;