@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/worker-app.js

@@ -1,11 +1,14 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { WORKER_APP_HYPERDRIVE_BINDING, WORKER_APP_KEYS_SECRET, WORKER_APP_KEYS_URL_VAR, workerAppHasBuild, workerAppHostId, } from '../worker-app-config.js';
+import { APPS_DOMAIN } from '../org.js';
+import { WORKER_APP_KEYS_SECRET, WORKER_APP_KEYS_URL_VAR, workerAppHasBuild, workerAppHostId, } from '../worker-app-config.js';
+import { WORKER_APP_DNS_RECORD, pendingWorkerAppMigrations, strayContainerImage, withCallTimeout, workerAppRegistryPrefix, workerAppShape, workerAppUpload, } from '../worker-app-upload.js';
 import { entryAuthEnv } from './broker-entries.js';
 import { workerAppHostname } from './hostnames.js';
+import { workspaceWorkerParent } from './workspace-worker.js';
 import { appStepKey } from './platform-diff.js';
 import { remoteDatabaseKeys } from './remote-database.js';
 import { applyWorkerAppDatabase, deleteWorkerAppDatabaseRoute, deleteWorkerAppHyperdrive, workerAppDbRouteMarkerScopeKey, workerAppHyperdriveScopeKey, workerAppMigrationsScopeKey, } from './worker-app-database.js';
-import { WORKER_COMPATIBILITY_DATE } from './worker.js';
+export { WORKER_APP_DNS_RECORD, withCallTimeout, workerAppRegistryPrefix };
 /**
  * ADR 0002: a hosting entry that declares `workerApp` runs as one Cloudflare
  * Worker with Durable Objects and Containers on the platform account. One step
@@ -60,14 +63,11 @@ export const workerAppTraceScopeKeys = (entryKey) => [
 export const workerAppResourceKey = (stepKey) => `cloudflare:worker-app:${stepKey}`;
 export const WORKER_APP_ORG_HASH_LENGTH = 8;
 /** `${8 hex of the org id's sha256}-${entry key}-app`. */
-export const workerAppName = (org, entry) => `${createHash('sha256').update(org.id).digest('hex').slice(0, WORKER_APP_ORG_HASH_LENGTH)}-${entry.key}-app`;
+export const workerAppName = (org, entry) => workspaceWorkerParent(entry) !== null
+    ? `${org.slug}-${workspaceWorkerParent(entry)}-work`
+    : `${createHash('sha256').update(org.id).digest('hex').slice(0, WORKER_APP_ORG_HASH_LENGTH)}-${entry.key}-app`;
 /** The zone that holds the routes of an org with no domain of its own. */
 export const WORKER_APP_OIKOS_ZONE = 'oikos.host';
-/** The record a Worker route needs on the org's own zone: Cloudflare's documented dummy, proxied. */
-export const WORKER_APP_DNS_RECORD = {
-    type: 'AAAA',
-    content: '100::',
-};
 /** True once the Worker app holds the broker key (`authEnv` delivered it). */
 export const brokerKeyDelivered = (recorded, entryKey) => Boolean(parseJson(recorded[workerAppSecretsScopeKey(entryKey)], {})
     .AUTH_APP_KEY);
@@ -107,7 +107,11 @@ export function custodyRenewalDue(recorded, entryKey, now) {
 }
 const sortedEntries = (record) => Object.entries(record ?? {}).sort(([a], [b]) => a.localeCompare(b));
 /** The zone apex the entry's route lives in. */
-export const workerAppApex = (org) => org.hosting.usesDomain && org.domain ? org.domain : WORKER_APP_OIKOS_ZONE;
+export const workerAppApex = (org, entry) => entry && workspaceWorkerParent(entry) !== null
+    ? APPS_DOMAIN
+    : org.hosting.usesDomain && org.domain
+        ? org.domain
+        : WORKER_APP_OIKOS_ZONE;
 /** True when the want has a secret that must be held (a generated one, the broker key, a custody credential). */
 const holdsGenerated = (want) => want.secrets.length > 0;
 /**
@@ -160,27 +164,19 @@ export function wantedWorkerApp(org, entry, recorded, input) {
     }
     if (missing.length > 0)
         return { missing };
+    const shape = workerAppShape(app);
     return {
         want: {
             name: workerAppName(org, entry),
-            artifactUrl: app.artifactUrl,
-            artifactSha256: app.artifactSha256,
-            compatibilityDate: app.compatibilityDate ?? WORKER_COMPATIBILITY_DATE,
-            compatibilityFlags: [...(app.compatibilityFlags ?? [])].sort(),
+            artifactUrl: shape.artifactUrl,
+            artifactSha256: shape.artifactSha256,
+            compatibilityDate: shape.compatibilityDate,
+            compatibilityFlags: shape.compatibilityFlags,
             host: workerAppHostname(org, entry),
-            apex: workerAppApex(org),
-            classes: Object.entries(app.durableObjects.classes)
-                .map(([binding, className]) => ({ binding, className }))
-                .sort((a, b) => a.binding.localeCompare(b.binding)),
-            migrations: app.durableObjects.migrations,
-            containers: (app.containers ?? [])
-                .map((c) => ({
-                className: c.className,
-                image: `${c.image.repository}@${c.image.digest}`,
-                instanceType: c.instanceType,
-                maxInstances: c.maxInstances,
-            }))
-                .sort((a, b) => a.className.localeCompare(b.className)),
+            apex: workerAppApex(org, entry),
+            classes: shape.classes,
+            migrations: shape.migrations,
+            containers: shape.containers,
             vars: sortedEntries(vars),
             ...(app.database
                 ? {
@@ -223,8 +219,6 @@ export function migrationPrefixError(applied, declared) {
 }
 /** The unapplied migrations after the last tag in `applied`. */
 export const unappliedMigrations = (declared, applied) => declared.slice(applied.length);
-/** The registry prefix a container image of this platform must start with. */
-export const workerAppRegistryPrefix = (accountId) => `registry.cloudflare.com/${accountId}/`;
 /** Every entry key with a deployed or half-deployed Worker app recorded. */
 export function liveWorkerApps(orgId, recordedIds) {
     const mainPrefix = `cloudflare:worker-app:${orgId}:`;
@@ -328,9 +322,7 @@ export function planWorkerApps(org, recordedIds, input) {
             continue;
         }
         const { want } = wanted;
-        const stray = (app.containers ?? []).find((c) => input.registryAccountId === undefined ||
-            !c.image.repository.startsWith(workerAppRegistryPrefix(input.registryAccountId)) ||
-            c.image.repository.split('/').some((part) => /^\.+$/.test(part)));
+        const stray = strayContainerImage(app, input.registryAccountId);
         if (stray) {
             block(input.registryAccountId === undefined
                 ? 'the host supplies no Cloudflare account id for the container registry'
@@ -400,31 +392,6 @@ export function planWorkerApps(org, recordedIds, input) {
 /** An outside call that has not answered in this long fails the step; the next apply repairs it. */
 export const WORKER_APP_CALL_TIMEOUT_MS = 120_000;
 export const WORKER_APP_KEYS_DELIVERY_ATTEMPTS = 3;
-/**
- * Races `task` against a timer. An error names the call and edge's error code, never the cause.
- */
-export function withCallTimeout(ms, label, task) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(`${label}: no answer within ${ms} ms`)), ms);
-        task().then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            // The cause is dropped: a provider error can echo a request body. The
-            // HTTP status stays, because callers tell "already gone" by it. So does
-            // edge's error code (a fixed lower-case enum, never a secret), to say why.
-            const { status, code } = (error ?? {});
-            const known = typeof code === 'string' && /^[a-z_]{1,40}$/.test(code) ? code : undefined;
-            const failure = new Error(known ? `${label} failed (${known})` : `${label} failed`);
-            if (typeof status === 'number')
-                failure.status = status;
-            if (known)
-                failure.code = known;
-            reject(failure);
-        });
-    });
-}
 const isGone = (error) => {
     const status = error?.status;
     return typeof status === 'number' && status === 404;
@@ -481,58 +448,14 @@ export async function applyWorkerApp(deps, org, action, context) {
     const recordedTags = parseJson(recorded0[workerAppTagsScopeKey(entryKey)], []);
     // The live tag is the fact; the record can be behind it after a crash between upload and record.
     const liveTag = await call('read the migration tag', () => workers.liveMigrationTag(want.name));
-    let appliedCount;
-    if (liveTag === undefined)
-        appliedCount = 0;
-    else {
-        const index = declaredTags.indexOf(liveTag);
-        if (index < 0) {
-            throw new Error(`${at}: the live Worker holds migration '${liveTag}', which is not in the declared list; migrations are append-only and foundry will not guess`);
-        }
-        appliedCount = index + 1;
-    }
+    const pending = pendingWorkerAppMigrations(want.migrations, liveTag);
+    if (!pending.ok)
+        throw new Error(`${at}: ${pending.reason}`);
     const recordedError = migrationPrefixError(recordedTags, declaredTags);
     if (recordedError)
         throw new Error(`${at}: ${recordedError}`);
-    const pending = want.migrations.slice(appliedCount);
-    const migrations = pending.length > 0
-        ? {
-            ...(liveTag !== undefined ? { oldTag: liveTag } : {}),
-            newTag: pending[pending.length - 1]?.tag,
-            steps: pending.map((m) => ({
-                ...(m.newSqliteClasses ? { newSqliteClasses: m.newSqliteClasses } : {}),
-                ...(m.deletedClasses ? { deletedClasses: m.deletedClasses } : {}),
-                ...(m.renamedClasses ? { renamedClasses: m.renamedClasses } : {}),
-            })),
-        }
-        : undefined;
-    await call('upload the script', () => workers.uploadWorkerApp({
-        name: want.name,
-        artifactUrl: want.artifactUrl,
-        artifactSha256: want.artifactSha256,
-        compatibilityDate: want.compatibilityDate,
-        compatibilityFlags: want.compatibilityFlags,
-        bindings: [
-            ...want.classes.map((c) => ({
-                type: 'durable_object_namespace',
-                name: c.binding,
-                class_name: c.className,
-            })),
-            ...want.vars.map(([name, text]) => ({
-                type: 'plain_text',
-                name,
-                text,
-            })),
-            ...(hyperdriveId
-                ? [{ type: 'hyperdrive', name: WORKER_APP_HYPERDRIVE_BINDING, id: hyperdriveId }]
-                : []),
-        ],
-        observability: { enabled: true, head_sampling_rate: 1 },
-        ...(migrations ? { migrations } : {}),
-        ...(want.containers.length > 0
-            ? { containers: want.containers.map((c) => c.className) }
-            : {}),
-    }));
+    const migrations = pending.migrations;
+    await call('upload the script', () => workers.uploadWorkerApp(workerAppUpload(want.name, want, want.vars, migrations, hyperdriveId)));
     context.recordScopeId(workerAppTagsScopeKey(entryKey), JSON.stringify(declaredTags));
     await context.persistScopeIds();
     // A Worker that no longer declares a database no longer binds its config: delete it now.

package/dist/plan/worker.d.ts

@@ -1,4 +1,5 @@
 import type { DeclaredOrg, HostingEntry, WorkerConfig } from '../org.js';
+import { WORKER_COMPATIBILITY_DATE } from '../worker-app-upload.js';
 import type { DraftStep } from './diff.js';
 /**
  * F8 (#318): one plain Cloudflare Worker per hosting entry that declares
@@ -91,7 +92,7 @@ export declare const workerName: (org: DeclaredOrg, entry: HostingEntry) => stri
  * like {@link RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS} is a fixed Cloudflare
  * Free plan value rather than something an org declares.
  */
-export declare const WORKER_COMPATIBILITY_DATE = "2026-09-12";
+export { WORKER_COMPATIBILITY_DATE };
 export type WorkerMode = 'apply' | 'retire';
 export interface WorkerWant {
     name: string;
@@ -131,4 +132,3 @@ export declare function planWorkers(org: DeclaredOrg, recordedIds: Readonly<Reco
     steps: DraftStep[];
     blocked: Blocked;
 };
-export {};

package/dist/plan/worker.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { WORKER_COMPATIBILITY_DATE } from '../worker-app-upload.js';
 import { entryHostnames } from './hostnames.js';
 import { lockedHostnames } from './locked-hostnames.js';
 import { appStepKey } from './platform-diff.js';
@@ -123,7 +124,7 @@ export const workerName = (org, entry) =>
  * like {@link RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS} is a fixed Cloudflare
  * Free plan value rather than something an org declares.
  */
-export const WORKER_COMPATIBILITY_DATE = '2026-09-12';
+export { WORKER_COMPATIBILITY_DATE };
 /**
  * With a wildcard route (`*.<domain>/*`) the Worker would also capture every
  * hostname foundry provisions on the domain, so each gets a no-Worker route

package/dist/plan/workspace-client.d.ts

@@ -0,0 +1,25 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+/** The name of an entry's workspace client and of the key its workspace broker entry is held under. */
+export declare const workspaceClientKey: (entryKey: string) => string;
+/** The company's ZITADEL organisation for the customers of its workspaces. The space keeps it apart from every slug. */
+export declare const testCustomersOrgName: (slug: string) => string;
+/** The recorded id of that organisation (the step's `system:kind:key`). */
+export declare const testCustomersOrgKey: (orgId: string) => string;
+/** `'1'` or `'0'`: whether the test customers organisation was last left open to self-registration. */
+export declare const TEST_CUSTOMERS_SIGN_UP_SCOPE_KEY = "test_customers_sign_up";
+/** `'email-code'` once the emailed-code metadata was written to the test customers organisation. */
+export declare const TEST_CUSTOMERS_SIGN_IN_SCOPE_KEY = "test_customers_sign_in";
+/** The server entries whose workspace has its own sign-in: a workspace and `uses.auth`. */
+export declare function workspaceAuthEntries(org: DeclaredOrg): HostingEntry[];
+/** The entry whose workspace client is named `clientKey`, or `undefined`. */
+export declare const workspaceAuthEntryOf: (org: DeclaredOrg, clientKey: string) => HostingEntry | undefined;
+/** The entries whose workspace signs in the test customers organisation. */
+export declare const testCustomersEntries: (org: DeclaredOrg) => HostingEntry[];
+/** The addresses a workspace client signs in at: the workspace host. */
+export declare const workspaceClientHosts: (org: DeclaredOrg, entry: HostingEntry) => string[];
+/**
+ * `org` (planned without its dark entries) plus the sign-in-only shape of the dark entries whose workspace has
+ * sign-in, so the login host's lists of customers clients match what the executor, which reads the org as
+ * declared, writes. The copies have no address and no Worker.
+ */
+export declare function withDarkWorkspaceSignIn(org: DeclaredOrg, declared: DeclaredOrg): DeclaredOrg;

package/dist/plan/workspace-client.js

@@ -0,0 +1,48 @@
+import { workspaceHost } from './hostnames.js';
+/**
+ * What the sign-in of a server workspace is called, shared by the planners that must agree on it. A workspace of
+ * an entry with `uses.auth` signs in with its own ZITADEL client named `<entry key>-work`, and its customers
+ * sign in a separate "<slug> test customers" organisation, never the live customers one.
+ */
+/** The suffix of the client, broker entry and held key that belong to an entry's workspace. */
+const WORKSPACE_CLIENT_SUFFIX = '-work';
+/** The name of an entry's workspace client and of the key its workspace broker entry is held under. */
+export const workspaceClientKey = (entryKey) => `${entryKey}${WORKSPACE_CLIENT_SUFFIX}`;
+/** The company's ZITADEL organisation for the customers of its workspaces. The space keeps it apart from every slug. */
+export const testCustomersOrgName = (slug) => `${slug} test customers`;
+/** The recorded id of that organisation (the step's `system:kind:key`). */
+export const testCustomersOrgKey = (orgId) => `zitadel:customers-test:${orgId}`;
+/** `'1'` or `'0'`: whether the test customers organisation was last left open to self-registration. */
+export const TEST_CUSTOMERS_SIGN_UP_SCOPE_KEY = 'test_customers_sign_up';
+/** `'email-code'` once the emailed-code metadata was written to the test customers organisation. */
+export const TEST_CUSTOMERS_SIGN_IN_SCOPE_KEY = 'test_customers_sign_in';
+/** The server entries whose workspace has its own sign-in: a workspace and `uses.auth`. */
+export function workspaceAuthEntries(org) {
+    if (!org.hosting.enabled)
+        return [];
+    return org.hosting.entries.filter((entry) => entry.workspace !== undefined &&
+        entry.workerApp === undefined &&
+        entry.uses?.auth !== undefined);
+}
+/** The entry whose workspace client is named `clientKey`, or `undefined`. */
+export const workspaceAuthEntryOf = (org, clientKey) => workspaceAuthEntries(org).find((entry) => workspaceClientKey(entry.key) === clientKey);
+/** The entries whose workspace signs in the test customers organisation. */
+export const testCustomersEntries = (org) => workspaceAuthEntries(org).filter((entry) => entry.uses?.auth?.users === 'customers');
+/** The addresses a workspace client signs in at: the workspace host. */
+export const workspaceClientHosts = (org, entry) => [
+    workspaceHost(org.slug, entry.key),
+];
+/**
+ * `org` (planned without its dark entries) plus the sign-in-only shape of the dark entries whose workspace has
+ * sign-in, so the login host's lists of customers clients match what the executor, which reads the org as
+ * declared, writes. The copies have no address and no Worker.
+ */
+export function withDarkWorkspaceSignIn(org, declared) {
+    const present = new Set(org.hosting.entries.map((entry) => entry.key));
+    const dark = workspaceAuthEntries(declared)
+        .filter((entry) => !present.has(entry.key))
+        .map((entry) => ({ ...entry, hostnames: [], gates: [] }));
+    if (dark.length === 0)
+        return org;
+    return { ...org, hosting: { ...org.hosting, entries: [...org.hosting.entries, ...dark] } };
+}

package/dist/plan/workspace-sign-in.d.ts

@@ -0,0 +1,55 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { UnmanagedItem } from '../plan.js';
+import { type BrokerEntryInput, type BrokerEntryWant } from './broker-entries.js';
+import type { DraftStep } from './diff.js';
+import type { LiveResource } from './live.js';
+/** The step `coolify:workspace-broker-entry` and its action key, for the planner and the executor to share. */
+export declare const WORKSPACE_BROKER_ENTRY_KIND = "workspace-broker-entry";
+/**
+ * The MCP resource of a workspace with `uses.auth.mcp`: its own endpoint on the workspace host, its own audience
+ * project in the test customers organisation (recorded by `zitadel:mcp-project` under the client's name), and the
+ * onboarding page on the workspace host. `null` without `mcp` or until the project is recorded.
+ */
+export declare function workspaceMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    resource: string;
+    projectId: string;
+    loginHost: string;
+    onboardingUrl?: string;
+} | null;
+/**
+ * What the app's env says about who signs in at the workspace, as recorded so far, or `null` until the
+ * organisation, client and issuer are all known. Non-secret values only.
+ */
+export declare function workspaceAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string> | null;
+/**
+ * The client ids of the company's live apps: every recorded client id except the workspaces' own. A stage that
+ * holds one of them could sign in as the live app.
+ */
+export declare function liveClientIds(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): string[];
+/** What `ws.<key>.signin` records: the sign-in env above as JSON, or `null` while it is not all known. */
+export declare function workspaceSignInMarker(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): string | null;
+/**
+ * The test customers organisation, planned once an entry's workspace signs in customers. Sign-up and the emailed
+ * code follow what the company declares for its live customers (`customers.signUp`, the entries' `signIn`), so
+ * testers meet the same sign-in the customers will. Idempotent on the recorded id and the two markers.
+ */
+export declare function planTestCustomers(org: DeclaredOrg, live: readonly LiveResource[], claimed: Set<string>, recordedIds: Readonly<Record<string, string>>, metadataWired: boolean): {
+    step: DraftStep | null;
+    blocked: UnmanagedItem[];
+};
+/** One ZITADEL web client `<key>-work` per workspace with sign-in, planned once; its redirect addresses name the workspace host. */
+export declare function planWorkspaceClients(org: DeclaredOrg, byKey: ReadonlyMap<string, LiveResource>, claimed: Set<string>): DraftStep[];
+/** What a workspace broker entry must say, without its keys, or what is still missing. */
+export declare function wantedWorkspaceBrokerEntry(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    want: BrokerEntryWant;
+} | {
+    missing: BrokerEntryInput[];
+};
+/**
+ * One broker `AUTH_APPS` entry per workspace with sign-in, written after the workspace step has put the stage's
+ * `AUTH_APP_KEY` in its env. Idempotent on the recorded marker of what the last write said.
+ */
+export declare function planWorkspaceBrokerEntries(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], brokerWired: boolean, brokerWorkspacesDatabase: boolean, stageReady: (entry: HostingEntry) => boolean): {
+    steps: DraftStep[];
+    blocked: UnmanagedItem[];
+};

package/dist/plan/workspace-sign-in.js

@@ -0,0 +1,273 @@
+import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, entryClientIdScopeKey, } from './agora.js';
+import { BOULE_CLIENT_ID_SCOPE_KEY } from './boule.js';
+import { brokerEntryAppliedScopeKey, entryMcpProjectScopeKey, } from './broker-entries.js';
+import { BROKER_WORKSPACES_DATABASE_ENV, workspacesDatabaseRef, workspacesUrl, } from './entry-workspaces.js';
+import { workspaceHost } from './hostnames.js';
+import { loginHostnameFor } from './login-host.js';
+import { appStepKey } from './platform-diff.js';
+import { TEST_CUSTOMERS_SIGN_IN_SCOPE_KEY, TEST_CUSTOMERS_SIGN_UP_SCOPE_KEY, testCustomersEntries, testCustomersOrgKey, workspaceAuthEntries, workspaceClientKey, } from './workspace-client.js';
+/**
+ * The sign-in of a server workspace (`HostingEntry.workspace` with `uses.auth`), so the team and invited testers
+ * can test the whole app, customer sign-in and customer workspaces included, before it is live. It is built from
+ * the same pieces as the live entry's sign-in and shares none of its secrets:
+ *  - a company with any such entry gets a "<slug> test customers" organisation (`planTestCustomers`), never the
+ *    live customers one;
+ *  - the entry gets its own ZITADEL client `<key>-work` at the workspace host (`planWorkspaceClients`);
+ *  - the stage app gets its own `AUTH_*` values, cookie secret, app key and, with `uses.auth.workspaces`, its own
+ *    workspaces key;
+ *  - the broker gets its own entry `<slug>-<key>-work` (`planWorkspaceBrokerEntries`), whose key and workspaces
+ *    key hash are the stage's, so it has its own product tenant in the broker.
+ */
+const resourceKey = (system, kind, key) => `${system}:${kind}:${key}`;
+/** The step `coolify:workspace-broker-entry` and its action key, for the planner and the executor to share. */
+export const WORKSPACE_BROKER_ENTRY_KIND = 'workspace-broker-entry';
+/**
+ * The MCP resource of a workspace with `uses.auth.mcp`: its own endpoint on the workspace host, its own audience
+ * project in the test customers organisation (recorded by `zitadel:mcp-project` under the client's name), and the
+ * onboarding page on the workspace host. `null` without `mcp` or until the project is recorded.
+ */
+export function workspaceMcp(org, entry, recorded) {
+    const mcp = entry.uses?.auth?.mcp;
+    const projectId = recorded[entryMcpProjectScopeKey(workspaceClientKey(entry.key))];
+    if (!mcp || !projectId)
+        return null;
+    const host = workspaceHost(org.slug, entry.key);
+    return {
+        resource: `https://${host}${mcp.path}`,
+        projectId,
+        loginHost: loginHostnameFor(org),
+        ...(mcp.onboardingPath ? { onboardingUrl: `https://${host}${mcp.onboardingPath}` } : {}),
+    };
+}
+/**
+ * What the app's env says about who signs in at the workspace, as recorded so far, or `null` until the
+ * organisation, client and issuer are all known. Non-secret values only.
+ */
+export function workspaceAuthEnv(org, entry, recorded, issuer) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return null;
+    const organizationId = auth.users === 'customers' ? recorded[testCustomersOrgKey(org.id)] : recorded.zitadel_org;
+    const clientId = recorded[entryClientIdScopeKey(workspaceClientKey(entry.key))];
+    if (!organizationId || !clientId || !issuer)
+        return null;
+    const mcp = workspaceMcp(org, entry, recorded);
+    if (auth.mcp && !mcp)
+        return null;
+    return {
+        AUTH_ORGANIZATION_ID: organizationId,
+        AUTH_CLIENT_ID: clientId,
+        AUTH_ISSUER: issuer,
+        ...(auth.workspaces ? { WORKSPACES_URL: workspacesUrl(org) } : {}),
+        ...(mcp
+            ? {
+                MCP_AUDIENCE: mcp.projectId,
+                MCP_RESOURCE: mcp.resource,
+                MCP_ISSUER: `https://${mcp.loginHost}`,
+            }
+            : {}),
+    };
+}
+const SHARED_CLIENT_KEYS = new Set([
+    APP_CLIENT_ID_SCOPE_KEY,
+    CMS_CLIENT_ID_SCOPE_KEY,
+    AGORA_CLIENT_ID_SCOPE_KEY,
+    BOULE_CLIENT_ID_SCOPE_KEY,
+]);
+/**
+ * The client ids of the company's live apps: every recorded client id except the workspaces' own. A stage that
+ * holds one of them could sign in as the live app.
+ */
+export function liveClientIds(org, recorded) {
+    const own = new Set(workspaceAuthEntries(org).map((e) => entryClientIdScopeKey(workspaceClientKey(e.key))));
+    return Object.entries(recorded)
+        .filter(([key, id]) => Boolean(id) &&
+        (SHARED_CLIENT_KEYS.has(key) ||
+            (key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX) && !own.has(key))))
+        .map(([, id]) => id)
+        .sort();
+}
+/** What `ws.<key>.signin` records: the sign-in env above as JSON, or `null` while it is not all known. */
+export function workspaceSignInMarker(org, entry, recorded, issuer) {
+    const env = workspaceAuthEnv(org, entry, recorded, issuer);
+    return env ? JSON.stringify(env) : null;
+}
+/**
+ * The test customers organisation, planned once an entry's workspace signs in customers. Sign-up and the emailed
+ * code follow what the company declares for its live customers (`customers.signUp`, the entries' `signIn`), so
+ * testers meet the same sign-in the customers will. Idempotent on the recorded id and the two markers.
+ */
+export function planTestCustomers(org, live, claimed, recordedIds, metadataWired) {
+    const entries = testCustomersEntries(org);
+    const wanted = entries.length > 0;
+    const signUp = org.customers?.signUp === true;
+    const wantedSignIn = entries.some((e) => e.uses?.auth?.signIn === 'email-code')
+        ? 'email-code'
+        : '';
+    const blocked = [];
+    const orgId = recordedIds[testCustomersOrgKey(org.id)];
+    const metadataBlocked = () => ({
+        description: `${org.slug}'s test customers organisation sign-in metadata is blocked, not planned: the host's ZITADEL client cannot set or remove organisation metadata`,
+        key: `zitadel:customers-test-signin:${org.id}`,
+    });
+    const draft = (desired, description) => ({
+        step: {
+            action: { system: 'zitadel', kind: 'customers-test', key: org.id, desired },
+            step: { description, destroys: false, migrates: false },
+        },
+        blocked,
+    });
+    if (!orgId) {
+        if (!wanted)
+            return { step: null, blocked };
+        const withSignIn = wantedSignIn === 'email-code' && metadataWired;
+        if (wantedSignIn === 'email-code' && !metadataWired)
+            blocked.push(metadataBlocked());
+        return draft({ signUp, ...(withSignIn ? { signIn: wantedSignIn } : {}) }, `provision a ZITADEL org for ${org.slug}'s test customers, with self-registration ${signUp ? 'on' : 'off'}${withSignIn ? ' and sign-in by emailed code' : ''}`);
+    }
+    for (const r of live) {
+        if (r.system === 'zitadel' && r.kind === 'project_grant' && r.config.grantedOrgId === orgId) {
+            claimed.add(resourceKey(r.system, r.kind, r.key));
+        }
+    }
+    const appliedSignUp = recordedIds[TEST_CUSTOMERS_SIGN_UP_SCOPE_KEY] === '1' ? '1' : '0';
+    const wantedSignUp = wanted && signUp ? '1' : '0';
+    const appliedSignIn = recordedIds[TEST_CUSTOMERS_SIGN_IN_SCOPE_KEY] === 'email-code' ? 'email-code' : '';
+    const signInDiffers = appliedSignIn !== (wanted ? wantedSignIn : '');
+    if (signInDiffers && !metadataWired)
+        blocked.push(metadataBlocked());
+    const writeSignIn = signInDiffers && metadataWired;
+    if (appliedSignUp === wantedSignUp && !writeSignIn)
+        return { step: null, blocked };
+    return draft({
+        signUp: wantedSignUp === '1',
+        ...(writeSignIn ? { signIn: wanted ? wantedSignIn : '' } : {}),
+    }, appliedSignUp === wantedSignUp
+        ? `${wantedSignIn ? 'set' : 'remove'} the emailed-code sign-in metadata of ${org.slug}'s test customers`
+        : `turn self-registration ${wantedSignUp === '1' ? 'on' : 'off'} for ${org.slug}'s test customers`);
+}
+/** One ZITADEL web client `<key>-work` per workspace with sign-in, planned once; its redirect addresses name the workspace host. */
+export function planWorkspaceClients(org, byKey, claimed) {
+    const steps = [];
+    for (const entry of workspaceAuthEntries(org)) {
+        const client = workspaceClientKey(entry.key);
+        const key = resourceKey('zitadel', 'app', client);
+        if (byKey.has(key)) {
+            claimed.add(key);
+            continue;
+        }
+        steps.push({
+            action: { system: 'zitadel', kind: 'app', key: client, desired: { appType: 'web' } },
+            step: {
+                description: `provision the workspace sign-in client '${client}' for ${org.slug}`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return steps;
+}
+/** What a workspace broker entry must say, without its keys, or what is still missing. */
+export function wantedWorkspaceBrokerEntry(org, entry, recorded) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return { missing: [] };
+    const client = workspaceClientKey(entry.key);
+    const organizationId = auth.users === 'customers' ? recorded[testCustomersOrgKey(org.id)] : recorded.zitadel_org;
+    const clientId = recorded[entryClientIdScopeKey(client)];
+    const mailDomain = recorded.mail_domain;
+    const missing = [];
+    if (!organizationId) {
+        missing.push(auth.users === 'customers'
+            ? { what: 'the test customers organisation id', producedBy: ['zitadel', 'customers-test'] }
+            : { what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
+    }
+    if (!clientId)
+        missing.push({ what: 'its workspace sign-in client id', producedBy: ['zitadel', 'app'] });
+    if (!mailDomain)
+        missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
+    const mcp = workspaceMcp(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))
+        return { missing };
+    const host = workspaceHost(org.slug, entry.key);
+    return {
+        want: {
+            name: `${org.slug}-${client}`,
+            organizationId,
+            clientId,
+            origins: [`https://${host}`],
+            from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
+            registration: auth.registration === 'open',
+            replaces: null,
+            ...(mcp ? { mcp } : {}),
+            ...(auth.workspaces
+                ? {
+                    workspaces: {
+                        roles: [...auth.workspaces.roles],
+                        inviteUrl: `https://${host}${auth.workspaces.invitePath}`,
+                    },
+                }
+                : {}),
+            ...(auth.signIn ? { emailLink: auth.signIn === 'email-code' } : {}),
+        },
+    };
+}
+/**
+ * One broker `AUTH_APPS` entry per workspace with sign-in, written after the workspace step has put the stage's
+ * `AUTH_APP_KEY` in its env. Idempotent on the recorded marker of what the last write said.
+ */
+export function planWorkspaceBrokerEntries(org, recordedIds, plannedSteps, brokerWired, brokerWorkspacesDatabase, stageReady) {
+    const steps = [];
+    const blocked = [];
+    for (const entry of workspaceAuthEntries(org)) {
+        const auth = entry.uses?.auth;
+        if (!auth)
+            continue;
+        const at = `${org.slug}'s ${entry.key} workspace broker entry`;
+        const key = `coolify:workspace-broker-entry:${entry.key}`;
+        const block = (why) => blocked.push({ description: `${at} is blocked, not planned: ${why}`, key });
+        if (!brokerWired) {
+            block('the host has not wired the broker port');
+            continue;
+        }
+        if (auth.workspaces && !brokerWorkspacesDatabase) {
+            block(`the broker has no ${BROKER_WORKSPACES_DATABASE_ENV}; hold the connection string of its workspaces database at ${workspacesDatabaseRef(org)}, then apply again`);
+            continue;
+        }
+        if (!stageReady(entry)) {
+            block("the workspace's app has no sign-in key yet");
+            continue;
+        }
+        const wanted = wantedWorkspaceBrokerEntry(org, entry, recordedIds);
+        if ('want' in wanted) {
+            if (recordedIds[brokerEntryAppliedScopeKey(workspaceClientKey(entry.key))] ===
+                JSON.stringify(wanted.want)) {
+                continue;
+            }
+        }
+        else {
+            const unplanned = wanted.missing.filter(({ producedBy: [system, kind] }) => !plannedSteps.some((p) => p.action.system === system && p.action.kind === kind));
+            if (unplanned.length > 0) {
+                block(`${unplanned.map((m) => m.what).join(', ')} not recorded yet`);
+                continue;
+            }
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: WORKSPACE_BROKER_ENTRY_KIND,
+                key: appStepKey(org, entry.key),
+                desired: {},
+            },
+            step: {
+                description: `write ${at} beside the others`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/workspace-worker.d.ts

@@ -0,0 +1,4 @@
+import type { HostingEntry } from '../org.js';
+export declare function registerWorkspaceWorker(copy: HostingEntry, parentKey: string): void;
+/** The key of the entry a workspace Worker copy belongs to, or `null` for a declared entry. */
+export declare function workspaceWorkerParent(entry: HostingEntry): string | null;