@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/kosmos.d.ts

@@ -0,0 +1,56 @@
+import type { DeclaredOrg } from '../org.js';
+/**
+ * foundry#949: what both the planner (`diff.ts`) and the executor
+ * (`executor.ts`) need to agree on for an org's kosmos -- the hostname, the
+ * recorded ids and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write. The same split
+ * `boule.ts` and `agora.ts` already follow, trimmed to what kosmos needs for
+ * its first release: a ZITADEL client, a database and sign-in env. Kosmos has
+ * no mail, no owner seeding and no Archon credential -- it is not Boule.
+ */
+/**
+ * The fixed `kosmos` ZITADEL web client's `clientId`, recorded by
+ * `executor.ts`'s `zitadelApp` and read by `coolifyKosmos` for
+ * `AUTH_CLIENT_ID`. Public, not a secret, so a flat scope id like
+ * `boule_client_id`.
+ */
+export declare const KOSMOS_CLIENT_ID_SCOPE_KEY = "kosmos_client_id";
+/**
+ * The kosmos database's Coolify uuid. It has no `system:kind:key` slot of its
+ * own (the step's one auto-recorded `resourceId` is the app), so it is a flat
+ * scope id, like the Boule and cms databases.
+ */
+export declare const KOSMOS_DATABASE_SCOPE_KEY = "coolify_kosmos_database";
+/**
+ * Recorded once `coolifyKosmos` has actually called `deploy` on this org's
+ * kosmos app -- the same marker {@link BOULE_DEPLOYED_SCOPE_KEY} (`boule.ts`)
+ * and {@link AGORA_DEPLOYED_SCOPE_KEY} (`agora.ts`) are, and for the same
+ * reason: Coolify defaults `instant_deploy` to false, so a freshly created
+ * app sat built but never started.
+ */
+export declare const KOSMOS_DEPLOYED_SCOPE_KEY = "coolify_kosmos_deployed";
+/**
+ * `kosmos.<domain>` when the org has a domain, `<slug>-kosmos.oikos.host`
+ * otherwise -- the same tier rule `bouleHostnameFor`/`agoraHostnameFor`
+ * follow; `../slug.ts`'s `KOSMOS_SUFFIX` reserves the collision.
+ */
+export declare function kosmosHostnameFor(org: DeclaredOrg): string;
+/** The env names `desiredKosmosEnv` can write, so the live reader knows which to read back. */
+export declare const KOSMOS_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID"];
+/**
+ * The env vars an org's kosmos app should carry, and every input still missing
+ * to build them. Callers that write must refuse on a non-empty `missing`: an
+ * kosmos with a blank client id fails every sign-in. `issuer` is the host's
+ * issuer address (`AgoraHostValues.issuer`), the same one Agora and Boule sign
+ * in at.
+ *
+ * Not here, and written by the executor instead: the database URLs
+ * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
+ * (generated once, never rotated) -- the same split `desiredBouleEnv` keeps.
+ */
+export declare function desiredKosmosEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null): {
+    env: Record<string, string>;
+    missing: string[];
+};
+/** The desired env keys the live app lacks or holds a different value for. */
+export declare function kosmosEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/kosmos.js

@@ -0,0 +1,84 @@
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+/**
+ * foundry#949: what both the planner (`diff.ts`) and the executor
+ * (`executor.ts`) need to agree on for an org's kosmos -- the hostname, the
+ * recorded ids and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write. The same split
+ * `boule.ts` and `agora.ts` already follow, trimmed to what kosmos needs for
+ * its first release: a ZITADEL client, a database and sign-in env. Kosmos has
+ * no mail, no owner seeding and no Archon credential -- it is not Boule.
+ */
+/**
+ * The fixed `kosmos` ZITADEL web client's `clientId`, recorded by
+ * `executor.ts`'s `zitadelApp` and read by `coolifyKosmos` for
+ * `AUTH_CLIENT_ID`. Public, not a secret, so a flat scope id like
+ * `boule_client_id`.
+ */
+export const KOSMOS_CLIENT_ID_SCOPE_KEY = 'kosmos_client_id';
+/**
+ * The kosmos database's Coolify uuid. It has no `system:kind:key` slot of its
+ * own (the step's one auto-recorded `resourceId` is the app), so it is a flat
+ * scope id, like the Boule and cms databases.
+ */
+export const KOSMOS_DATABASE_SCOPE_KEY = 'coolify_kosmos_database';
+/**
+ * Recorded once `coolifyKosmos` has actually called `deploy` on this org's
+ * kosmos app -- the same marker {@link BOULE_DEPLOYED_SCOPE_KEY} (`boule.ts`)
+ * and {@link AGORA_DEPLOYED_SCOPE_KEY} (`agora.ts`) are, and for the same
+ * reason: Coolify defaults `instant_deploy` to false, so a freshly created
+ * app sat built but never started.
+ */
+export const KOSMOS_DEPLOYED_SCOPE_KEY = 'coolify_kosmos_deployed';
+/**
+ * `kosmos.<domain>` when the org has a domain, `<slug>-kosmos.oikos.host`
+ * otherwise -- the same tier rule `bouleHostnameFor`/`agoraHostnameFor`
+ * follow; `../slug.ts`'s `KOSMOS_SUFFIX` reserves the collision.
+ */
+export function kosmosHostnameFor(org) {
+    return org.domain ? `kosmos.${org.domain}` : `${org.slug}-kosmos.oikos.host`;
+}
+/** The env names `desiredKosmosEnv` can write, so the live reader knows which to read back. */
+export const KOSMOS_MANAGED_ENV_KEYS = [
+    'APP_URL',
+    'AUTH_ISSUER',
+    'AUTH_ORGANIZATION_ID',
+    'AUTH_CLIENT_ID',
+];
+/**
+ * The env vars an org's kosmos app should carry, and every input still missing
+ * to build them. Callers that write must refuse on a non-empty `missing`: an
+ * kosmos with a blank client id fails every sign-in. `issuer` is the host's
+ * issuer address (`AgoraHostValues.issuer`), the same one Agora and Boule sign
+ * in at.
+ *
+ * Not here, and written by the executor instead: the database URLs
+ * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
+ * (generated once, never rotated) -- the same split `desiredBouleEnv` keeps.
+ */
+export function desiredKosmosEnv(org, recorded, issuer) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const clientId = recorded[KOSMOS_CLIENT_ID_SCOPE_KEY];
+    const missing = [];
+    if (!issuer)
+        missing.push('issuer');
+    if (!zitadelOrgId)
+        missing.push('zitadelOrgId');
+    if (!clientId)
+        missing.push('clientId');
+    const env = {
+        APP_URL: `https://${kosmosHostnameFor(org)}`,
+    };
+    if (issuer)
+        env.AUTH_ISSUER = issuer;
+    if (zitadelOrgId)
+        env.AUTH_ORGANIZATION_ID = zitadelOrgId;
+    if (clientId)
+        env.AUTH_CLIENT_ID = clientId;
+    return { env, missing };
+}
+/** The desired env keys the live app lacks or holds a different value for. */
+export function kosmosEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => live[key] !== value)
+        .map(([key]) => key);
+}

package/dist/plan/live.d.ts

@@ -42,7 +42,7 @@ export interface LiveResource {
      * see that function's own doc comment for why "always planned" broke
      * `bootstrapPlatform`.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github' | 'audit';
     kind: string;
     key: string;
     config: Record<string, unknown>;

package/dist/plan/locked-hostnames.d.ts

@@ -1,6 +1,6 @@
 import { type DeclaredOrg } from '../org.js';
-/** The labels an own org's services answer on, so no hosting entry may take them. */
-export declare const OWN_SERVICE_LABELS: readonly ["auth", "mail", "files", "sfu"];
+import { OWN_SERVICE_LABELS } from '../service-labels.js';
+export { OWN_SERVICE_LABELS };
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
  * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the

package/dist/plan/locked-hostnames.js

@@ -1,11 +1,12 @@
-import { ownsServices } from '../org.js';
+import { kosmosOn, ownsServices } from '../org.js';
+import { OWN_SERVICE_LABELS } from '../service-labels.js';
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { cmsStudioHostnameFor, siteHostnameFor } from './hostnames.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { loginHostnameFor } from './login-host.js';
 import { ownHostnames } from './own-hostnames.js';
-/** The labels an own org's services answer on, so no hosting entry may take them. */
-export const OWN_SERVICE_LABELS = ['auth', 'mail', 'files', 'sfu'];
+export { OWN_SERVICE_LABELS };
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
  * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the
@@ -31,6 +32,8 @@ export function lockedHostnames(org, platformHostnames) {
     }
     locked.add(agoraHostnameFor(org));
     locked.add(bouleHostnameFor(org));
+    if (kosmosOn(org))
+        locked.add(kosmosHostnameFor(org));
     if (org.site.enabled)
         locked.add(cmsStudioHostnameFor(org));
     if (org.calls.enabled && org.calls.usesDomain)
@@ -58,6 +61,6 @@ export function hostingNames(org, platformHostnames) {
         locked: lockedHostnames(org, platformHostnames),
         slug: org.slug,
         siteOwnsApex: org.site.enabled && org.site.usesDomain && org.domain !== null,
-        builtinBlueGreen: org.boule?.blueGreen !== undefined || org.agora?.blueGreen !== undefined,
+        builtinBlueGreen: org.boule?.blueGreen !== undefined || org.agora?.blueGreen !== undefined || kosmosOn(org),
     };
 }

package/dist/plan/login-host.js

@@ -2,6 +2,7 @@ import { ownsServices } from '../org.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, agoraHostnameFor, } from './agora.js';
 import { BOULE_CLIENT_ID_SCOPE_KEY, bouleHostnameFor } from './boule.js';
 import { SIGN_IN_IN_APP_SCOPE_KEY, inAppSignIn, inAppStatePairs, } from './sign-in.js';
+import { testCustomersEntries, testCustomersOrgKey, workspaceClientKey, } from './workspace-client.js';
 /**
  * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's own company login host -- the hostname and
@@ -168,7 +169,11 @@ export const LOGIN_BINDING_SCOPE_KEY = 'login_host_binding';
  * is no longer declared is not here, so it stays bound as before.
  */
 export function customersEntryKeys(org) {
-    return new Set(org.hosting.entries.filter((e) => e.uses?.auth?.users === 'customers').map((e) => e.key));
+    return new Set([
+        ...org.hosting.entries.filter((e) => e.uses?.auth?.users === 'customers').map((e) => e.key),
+        // A workspace's customers client signs in the test customers organisation, on the shared host as well.
+        ...testCustomersEntries(org).map((e) => workspaceClientKey(e.key)),
+    ]);
 }
 /**
  * The org's recorded app client ids (hosted app, each entry's own bar a customers entry, cms, agora, boule),
@@ -201,13 +206,14 @@ export const LOGIN_CLIENT_ORGS_SCOPE_KEY = 'login_client_orgs';
  */
 export function customersClientOrganizations(org, recorded) {
     const customersOrgId = recorded[`zitadel:customers:${org.id}`];
-    if (!customersOrgId)
-        return {};
+    const testOrgId = recorded[testCustomersOrgKey(org.id)];
     const map = {};
+    const workspaceKeys = new Set(testCustomersEntries(org).map((e) => workspaceClientKey(e.key)));
     for (const key of customersEntryKeys(org)) {
         const clientId = recorded[ENTRY_CLIENT_ID_SCOPE_PREFIX + key];
-        if (clientId)
-            map[clientId] = customersOrgId;
+        const orgId = workspaceKeys.has(key) ? testOrgId : customersOrgId;
+        if (clientId && orgId)
+            map[clientId] = orgId;
     }
     return map;
 }

package/dist/plan/machine-paths.d.ts

@@ -0,0 +1,36 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F11: the paths of a gated entry that a machine calls, not a person: the ai service posts to
+ * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`. A gate (`gates.ts`) stops a machine, so each of
+ * these paths on each gated host gets its own path-scoped Access application (`<host><path>`) with a bypass
+ * policy, the opposite of a private page's path gate. Cloudflare applies the most specific application, so
+ * the bypass wins over the host's whole-host gate. The app itself checks the machine's credential.
+ */
+/** The path Boule's customer-grants routes live under (`uses.customerGrants`, F13). */
+export declare const CUSTOMER_GRANTS_PATH = "/api/customer-grants";
+/** The paths of `entry` that machines call, in a fixed order, without repeats. */
+export declare function entryMachinePaths(entry: Pick<HostingEntry, 'uses'>): string[];
+/** The step key stem of one machine bypass: a hash of host and path, so it fits a key and needs no escaping. */
+export declare function machineBypassKey(host: string, path: string): string;
+/** The recorded `host/path` a machine bypass was made for, by its step key stem, read for the delete's wording. */
+export declare const machineBypassScopeKey: (stem: string) => string;
+export interface MachineBypass {
+    entry: string;
+    host: string;
+    path: string;
+}
+/** Every machine bypass wanted, by step key stem, and a line for each case where an entry's machine path gets none. */
+export declare function declaredMachineBypasses(org: DeclaredOrg, declared?: DeclaredOrg): {
+    bypasses: Map<string, MachineBypass>;
+    notes: string[];
+};
+/**
+ * One step per wanted machine bypass with no recorded Access application, and one deleting step per recorded
+ * bypass no longer wanted (a removed path, a removed gate, a removed entry). A delete is not `destroys`: it
+ * loses no data and only closes a path again, so it needs no typed confirmation.
+ */
+export declare function planMachineBypasses(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, declared?: DeclaredOrg): {
+    steps: DraftStep[];
+    notes: string[];
+};

package/dist/plan/machine-paths.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { isLiveEntry } from '../org.js';
+import { resolveGateHostnames } from './gates.js';
+import { entryHostnames, workspaceHost } from './hostnames.js';
+import { appStepKey } from './platform-diff.js';
+import { workspaceEntries } from './workspace.js';
+/**
+ * F11: the paths of a gated entry that a machine calls, not a person: the ai service posts to
+ * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`. A gate (`gates.ts`) stops a machine, so each of
+ * these paths on each gated host gets its own path-scoped Access application (`<host><path>`) with a bypass
+ * policy, the opposite of a private page's path gate. Cloudflare applies the most specific application, so
+ * the bypass wins over the host's whole-host gate. The app itself checks the machine's credential.
+ */
+/** The path Boule's customer-grants routes live under (`uses.customerGrants`, F13). */
+export const CUSTOMER_GRANTS_PATH = '/api/customer-grants';
+/** The paths of `entry` that machines call, in a fixed order, without repeats. */
+export function entryMachinePaths(entry) {
+    const paths = [];
+    const webhook = entry.uses?.ai?.webhookPath;
+    if (webhook !== undefined)
+        paths.push(webhook);
+    if (entry.uses?.customerGrants)
+        paths.push(CUSTOMER_GRANTS_PATH);
+    return [...new Set(paths)];
+}
+/** The step key stem of one machine bypass: a hash of host and path, so it fits a key and needs no escaping. */
+export function machineBypassKey(host, path) {
+    return `mp-${createHash('sha256').update(`${host}\0${path}`).digest('hex').slice(0, 16)}`;
+}
+/** What edge accepts as the path of a destination: segments of `a-z 0-9 . _ ~ -`, none empty, `.` or `..`, at most 200 characters. */
+const EDGE_PATH = /^(\/[a-z0-9._~-]+)+$/;
+const edgeAccepts = (path) => path.length <= 200 &&
+    EDGE_PATH.test(path) &&
+    !path.split('/').some((s) => s === '.' || s === '..');
+/** The recorded `host/path` a machine bypass was made for, by its step key stem, read for the delete's wording. */
+export const machineBypassScopeKey = (stem) => `machine_bypass_${stem}`;
+/**
+ * The gated hosts an entry is served on: the exact names of its own gates, the entry's live names under a
+ * gated wildcard (`*.<domain>` cannot carry a path), and the entry's workspace host when `declared` gives it one.
+ */
+function gatedHosts(org, declared, entry) {
+    const hosts = new Set();
+    const live = org.hosting.entries.find((e) => e.key === entry.key);
+    if (live && org.hosting.enabled && org.domain) {
+        const names = resolveGateHostnames(org.domain, live.gates.flatMap((gate) => gate.hostnames));
+        for (const name of names) {
+            if (!name.startsWith('*.'))
+                hosts.add(name);
+        }
+        const wildcards = names.filter((name) => name.startsWith('*.')).map((name) => name.slice(1));
+        for (const host of entryHostnames(org, live)) {
+            if (wildcards.some((suffix) => host.endsWith(suffix)))
+                hosts.add(host);
+        }
+    }
+    if (workspaceEntries(declared).some((e) => e.key === entry.key)) {
+        hosts.add(workspaceHost(declared.slug, entry.key));
+    }
+    return [...hosts].sort();
+}
+/** Every machine bypass wanted, by step key stem, and a line for each case where an entry's machine path gets none. */
+export function declaredMachineBypasses(org, declared = org) {
+    const bypasses = new Map();
+    const notes = [];
+    if (!declared.hosting.enabled)
+        return { bypasses, notes };
+    for (const entry of declared.hosting.entries) {
+        const paths = entryMachinePaths(entry);
+        if (paths.length === 0)
+            continue;
+        const hosts = gatedHosts(org, declared, entry);
+        if (hosts.length === 0) {
+            notes.push(`${org.slug}'s ${entry.key} has machine paths (${paths.join(', ')}) but no gated host${isLiveEntry(entry) ? '' : ' and no workspace'}, so no Access bypass is planned for them`);
+            continue;
+        }
+        for (const path of paths) {
+            if (!edgeAccepts(path)) {
+                notes.push(`${org.slug}'s ${entry.key} machine path ${path} gets no Access bypass: edge accepts only lower-case a-z, 0-9, '.', '_', '~' and '-' in path segments`);
+                continue;
+            }
+            for (const host of hosts) {
+                bypasses.set(machineBypassKey(host, path), { entry: entry.key, host, path });
+            }
+        }
+    }
+    return { bypasses, notes };
+}
+const accessRecordKey = (org, stem) => `cloudflare:access:${org.id}:${stem}`;
+/**
+ * One step per wanted machine bypass with no recorded Access application, and one deleting step per recorded
+ * bypass no longer wanted (a removed path, a removed gate, a removed entry). A delete is not `destroys`: it
+ * loses no data and only closes a path again, so it needs no typed confirmation.
+ */
+export function planMachineBypasses(org, recordedIds, declared = org) {
+    const { bypasses, notes } = declaredMachineBypasses(org, declared);
+    const steps = [];
+    const prefix = accessRecordKey(org, 'mp-');
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id || !name.startsWith(prefix))
+            continue;
+        const stem = name.slice(accessRecordKey(org, '').length);
+        if (bypasses.has(stem))
+            continue;
+        const was = recordedIds[machineBypassScopeKey(stem)];
+        steps.push({
+            action: {
+                system: 'cloudflare',
+                kind: 'access',
+                key: appStepKey(org, stem),
+                desired: { machineBypass: 'delete' },
+            },
+            step: {
+                description: `remove the Access bypass ${was ? `on ${was} ` : ''}(${org.slug}'s ${stem}): the machine path is no longer declared`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    for (const [stem, { entry, host, path }] of [...bypasses].sort(([a], [b]) => a.localeCompare(b))) {
+        if (recordedIds[accessRecordKey(org, stem)])
+            continue;
+        steps.push({
+            action: {
+                system: 'cloudflare',
+                kind: 'access',
+                key: appStepKey(org, stem),
+                desired: { machineBypass: 'apply', entry, domain: `${host}${path}` },
+            },
+            step: {
+                description: `let machine callers through Cloudflare Access on ${host}${path} (${org.slug}'s ${entry}): a bypass for the path only`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, notes };
+}

package/dist/plan/mcp.d.ts

@@ -30,7 +30,7 @@ type Blocked = Array<{
 export declare const MCP_CALL_TIMEOUT_MS = 60000;
 /** The want of the access step, recorded when it is done. */
 export declare const mcpAccessWant: (org: DeclaredOrg) => string;
-export declare function planMcp(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], zitadelMcp: boolean): {
+export declare function planMcp(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], zitadelMcp: boolean, declaredOrg?: DeclaredOrg): {
     steps: DraftStep[];
     blocked: Blocked;
 };

package/dist/plan/mcp.js

@@ -1,23 +1,44 @@
 import { ACCESS_TOKEN_LIFETIME_APPLIED_SCOPE_KEY, MCP_ACCESS_TOKEN_LIFETIME_SECONDS, entryMcpAccessAppliedScopeKey, entryMcpProjectScopeKey, mcpCallbackUri, } from './broker-entries.js';
 import { withCallTimeout } from './worker-app.js';
+import { testCustomersOrgKey, workspaceAuthEntries, workspaceAuthEntryOf, workspaceClientKey, } from './workspace-client.js';
 /** A ZITADEL call of the MCP steps that has not answered in this long fails the step; the next apply repeats it. */
 export const MCP_CALL_TIMEOUT_MS = 60_000;
 /** The want of the access step, recorded when it is done. */
 export const mcpAccessWant = (org) => JSON.stringify({ accessTokenType: 'jwt', redirectUri: mcpCallbackUri(org) });
-export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
+export function planMcp(org, recorded, plannedSteps, zitadelMcp, declaredOrg = org) {
     const steps = [];
     const blocked = [];
-    const entries = org.hosting.enabled
+    const live = org.hosting.enabled
         ? org.hosting.entries.filter((e) => Boolean(e.uses?.auth?.mcp))
         : [];
-    if (entries.length === 0)
+    const workspaces = workspaceAuthEntries(declaredOrg).filter((e) => e.uses?.auth?.mcp);
+    if (live.length === 0 && workspaces.length === 0)
         return { steps, blocked };
     const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system &&
         p.action.kind === kind &&
         (key === undefined || p.action.key === key));
-    for (const entry of entries) {
-        const at = `${org.slug}'s ${entry.key} MCP`;
-        const stepKey = `${org.id}:${entry.key}`;
+    const targets = [
+        ...live.map((entry) => ({
+            clientKey: entry.key,
+            at: `${org.slug}'s ${entry.key} MCP`,
+            customersOrg: {
+                recorded: `zitadel:customers:${org.id}`,
+                kind: 'customers',
+                what: 'customers',
+            },
+        })),
+        ...workspaces.map((entry) => ({
+            clientKey: workspaceClientKey(entry.key),
+            at: `${org.slug}'s ${entry.key} workspace MCP`,
+            customersOrg: {
+                recorded: testCustomersOrgKey(org.id),
+                kind: 'customers-test',
+                what: 'test customers',
+            },
+        })),
+    ];
+    for (const { clientKey, at, customersOrg } of targets) {
+        const stepKey = `${org.id}:${clientKey}`;
         if (!zitadelMcp) {
             blocked.push({
                 description: `${at} is blocked, not planned: the host's ZITADEL client cannot set JWT access tokens or the access-token lifetime`,
@@ -25,10 +46,10 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
             });
             continue;
         }
-        if (!recorded[entryMcpProjectScopeKey(entry.key)]) {
-            if (!recorded[`zitadel:customers:${org.id}`] && !planned('zitadel', 'customers')) {
+        if (!recorded[entryMcpProjectScopeKey(clientKey)]) {
+            if (!recorded[customersOrg.recorded] && !planned('zitadel', customersOrg.kind)) {
                 blocked.push({
-                    description: `${at} project is blocked, not planned: the customers organisation id is not recorded yet`,
+                    description: `${at} project is blocked, not planned: the ${customersOrg.what} organisation id is not recorded yet`,
                     key: `zitadel:mcp-project:${stepKey}`,
                 });
             }
@@ -36,15 +57,15 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
                 steps.push({
                     action: { system: 'zitadel', kind: 'mcp-project', key: stepKey, desired: {} },
                     step: {
-                        description: `make the empty project that is ${org.slug}'s ${entry.key} MCP token audience`,
+                        description: `make the empty project that is ${org.slug}'s ${clientKey} MCP token audience`,
                         destroys: false,
                         migrates: false,
                     },
                 });
             }
         }
-        if (recorded[entryMcpAccessAppliedScopeKey(entry.key)] !== mcpAccessWant(org)) {
-            if (!recorded[`zitadel:app:${entry.key}`] && !planned('zitadel', 'app', entry.key)) {
+        if (recorded[entryMcpAccessAppliedScopeKey(clientKey)] !== mcpAccessWant(org)) {
+            if (!recorded[`zitadel:app:${clientKey}`] && !planned('zitadel', 'app', clientKey)) {
                 blocked.push({
                     description: `${at} access is blocked, not planned: the sign-in client is not recorded yet`,
                     key: `zitadel:mcp-access:${stepKey}`,
@@ -54,7 +75,7 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
                 steps.push({
                     action: { system: 'zitadel', kind: 'mcp-access', key: stepKey, desired: {} },
                     step: {
-                        description: `${org.slug}'s ${entry.key} sign-in client issues JWT access tokens and accepts ${mcpCallbackUri(org)}`,
+                        description: `${org.slug}'s ${clientKey} sign-in client issues JWT access tokens and accepts ${mcpCallbackUri(org)}`,
                         destroys: false,
                         migrates: false,
                     },
@@ -75,6 +96,17 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
     }
     return { steps, blocked };
 }
+/**
+ * The entry a step key names: a live entry by its key, or a workspace by its client name `<key>-work`. A
+ * workspace's client name cannot be another entry's key (`client_name_taken`), so the two never meet.
+ */
+function mcpTarget(org, clientKey) {
+    const live = org.hosting.entries.find((e) => e.key === clientKey && e.uses?.auth?.mcp);
+    if (live)
+        return { workspace: false, entry: live };
+    const entry = workspaceAuthEntryOf(org, clientKey);
+    return entry?.uses?.auth?.mcp ? { workspace: true, entry } : undefined;
+}
 // ---- the apply -------------------------------------------------------------
 /**
  * The empty project in the customers organisation that is an entry's MCP token
@@ -85,10 +117,10 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
 export async function applyMcpProject(zitadel, org, action, context) {
     const entryKey = action.key.slice(org.id.length + 1);
     const at = `zitadel:mcp-project for ${org.slug} entry '${entryKey}'`;
-    if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.auth?.mcp)) {
+    const target = mcpTarget(org, entryKey);
+    if (!target)
         throw new Error(`${at}: the entry no longer declares uses.auth.mcp`);
-    }
-    const customersOrgId = context.recordedIds()[`zitadel:customers:${org.id}`];
+    const customersOrgId = context.recordedIds()[target.workspace ? testCustomersOrgKey(org.id) : `zitadel:customers:${org.id}`];
     if (!customersOrgId)
         throw new Error(`${at}: the customers organisation is not recorded yet`);
     const { project } = await withCallTimeout(MCP_CALL_TIMEOUT_MS, `${at}: find or create the project`, () => zitadel.findOrCreateProject(customersOrgId, `${org.slug}-${entryKey}-mcp`));
@@ -105,7 +137,7 @@ export async function applyMcpAccess(zitadel, org, action, context) {
     const ensure = zitadel.ensureOidcAppMcpAccess?.bind(zitadel);
     if (!ensure)
         throw new Error(`${at}: the ZITADEL client cannot set JWT access tokens`);
-    if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.auth?.mcp)) {
+    if (!mcpTarget(org, entryKey)) {
         throw new Error(`${at}: the entry no longer declares uses.auth.mcp`);
     }
     const recorded = context.recordedIds();