@wtfalch/foundry 0.60.0 → 0.61.0

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;

package/dist/plan/workspace-worker.js

@@ -0,0 +1,13 @@
+/**
+ * A Worker-app workspace is planned as a second Worker app: a copy of the entry under the key `<key>-work`.
+ * The copy is never declared; `withWorkspaceWorkers` (`plan/workspace.ts`) makes it and registers it here, so
+ * the name, host and zone helpers can tell it from a declared entry. A leaf module: `hostnames.ts` reads it.
+ */
+const PARENT_OF = new WeakMap();
+export function registerWorkspaceWorker(copy, parentKey) {
+    PARENT_OF.set(copy, parentKey);
+}
+/** The key of the entry a workspace Worker copy belongs to, or `null` for a declared entry. */
+export function workspaceWorkerParent(entry) {
+    return PARENT_OF.get(entry) ?? null;
+}

package/dist/plan/workspace.d.ts

@@ -0,0 +1,101 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import { type BlueGreenServer, type BlueGreenSubject } from './blue-green.js';
+import type { DraftStep } from './diff.js';
+/** The scope keys of a workspace, beside the stage's `bg.<key>.…` ones. `.` separated, no `:`. */
+export declare const wsKey: {
+    /** The hash of the workspace's shape last applied. Also the sign that its route may be written. */
+    applied: (key: string) => string;
+    /** The 40 character commit the workspace runs; the live app is made from it. */
+    commit: (key: string) => string;
+    /** The commit the live app was last made from or moved to by a promote (`HostingEntry.liveCommit`). */
+    liveCommit: (key: string) => string;
+    /** The non-secret sign-in env the workspace was last applied with (JSON); never a key. */
+    signIn: (key: string) => string;
+};
+/** The key of a workspace's Access gate in the company. */
+export declare const workspaceGateKey: (entryKey: string) => string;
+/** The key of the gate over the test inbox. Entry keys cannot start with a hyphen, so it never clashes with `ws-<key>`. */
+export declare const INBOX_GATE_KEY = "ws--inbox";
+/** True when the org has a server workspace, and so a stage mail sink to show. */
+export declare const hasInbox: (org: DeclaredOrg) => boolean;
+/** The people-list hash a gate was last made or changed with. */
+export declare const gatePeopleScopeKey: (gateKey: string) => string;
+/** The entries of an org that declare a workspace. */
+export declare function workspaceEntries(org: DeclaredOrg): HostingEntry[];
+/** True for a workspace that runs as a server (Coolify), false for a Worker app's. */
+export declare const isServerWorkspace: (entry: HostingEntry) => boolean;
+/**
+ * The company's people who may open company apps: the owners, by sign-in address and work address. This is the
+ * list the stage gate used (owners only); the owners are the only company people the gate inputs hold.
+ */
+export declare function companyPeople(org: Pick<DeclaredOrg, 'owners'>): string[];
+/** Who passes a workspace's gate: the company's people and the entry's testers, lowercased, distinct, sorted. */
+export declare function workspacePeople(org: Pick<DeclaredOrg, 'owners'>, entry: HostingEntry): string[];
+/** The hash recorded when a gate's people were set. A change of testers changes it. */
+export declare const peopleHash: (emails: readonly string[]) => string;
+/** The org without the entries that are not live: nothing that makes an app or its address sees them. */
+export declare function withoutDarkEntries(org: DeclaredOrg): DeclaredOrg;
+/**
+ * The org with a second Worker app per Worker-app workspace, keyed `<key>-work`, so the Worker app planner and
+ * executor deploy it like any other. The copy has no database and no sign-in env (the workspace gate is its
+ * sign-in; a database would be the live one) and is served at the workspace host. `declared` names the org the
+ * workspaces are read from when `org` has had dark entries removed.
+ */
+export declare function withWorkspaceWorkers(org: DeclaredOrg, declared?: DeclaredOrg): DeclaredOrg;
+/** A server workspace as the blue/green stage code sees its subject: no colors, no hostnames, no reporting. */
+export declare function workspaceSubject(org: DeclaredOrg, entry: HostingEntry): BlueGreenSubject;
+/** The origin the tunnel sends a server workspace's host to: the stage app on the company network. */
+export declare const workspaceOrigin: (subject: Pick<BlueGreenSubject, "base" | "port">) => string;
+/**
+ * The tunnel routes of the server workspaces: the workspace host to the stage app. A route is written only once
+ * the workspace was applied and its stage guards hold (isolated, probed, gated, healthy), never before.
+ */
+export declare function workspaceRoutes(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): Array<{
+    hostname: string;
+    service: string;
+}>;
+/** Whether `name` is the workspace host of one of the org's server workspaces. */
+export declare function ownsWorkspaceName(org: DeclaredOrg, name: string): boolean;
+/** A short hash of what decides the shape of a server workspace, so a change replans it. */
+export declare function workspaceStructureHash(org: DeclaredOrg, entry: HostingEntry): string;
+export interface PlanWorkspacesInput {
+    /** The org as declared, dark entries included. */
+    org: DeclaredOrg;
+    recordedIds: Readonly<Record<string, string>>;
+    /** Every Coolify server the host reports. `undefined`: the host cannot list them. */
+    servers: readonly BlueGreenServer[] | undefined;
+    /** The workspace's Access gate is recorded or planned in this run. */
+    gateReady: (gateKey: string) => boolean;
+    /** The company's stage mail sink is recorded and its live app is stopped or gone. */
+    stageSinkDown?: boolean;
+    /**
+     * The sign-in env a workspace with `uses.auth` should run with, as `workspaceSignInMarker` writes it, or
+     * `null` while it is not all recorded (the workspace is then blocked). Absent: sign-in is not planned.
+     */
+    signInWanted?: (entry: HostingEntry) => string | null;
+    /** The issuer the workspace's app signs in at; goes to the step for the executor. */
+    authIssuer?: string | null;
+}
+/**
+ * One `coolify:workspace` step per server workspace whose shape is not applied yet or whose stage needs another
+ * try; the Worker-app workspaces are planned by `planWorkerApps` through {@link withWorkspaceWorkers}. Pure.
+ * Blocked, not planned, while the host cannot list servers, the primary is unusable, the stage would not be
+ * isolated from the company's other apps, or the gate is not there: a workspace nobody can sign in to is not made.
+ */
+export declare function planWorkspaces(input: PlanWorkspacesInput): {
+    steps: DraftStep[];
+    unmanaged: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+/**
+ * The commit of the newest finished deployment of the workspace's stage app, or `null` when the port cannot
+ * list deployments, the read fails or there is none. The live app of a workspace entry is made from it.
+ */
+export declare function readWorkspaceCommit(coolify: {
+    listApplicationDeployments?(uuid: string, take?: number): Promise<Array<{
+        commit?: string;
+        status: string;
+    }>>;
+}, stageAppId: string): Promise<string | null>;