@wtfalch/foundry 0.60.0 → 0.61.0

package/dist/plan/apps-db-route.d.ts

@@ -0,0 +1,90 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { StepExecutionContext } from './plan-apply.js';
+import { type WorkerAppDatabaseDeps } from './worker-app-database.js';
+/**
+ * F4 (#925): the Hyperdrive route to the company's own Postgres server (`<slug>-postgres`, the one the
+ * apps admin role lives on). Boule creates a database per app copy on that server (`app_<app>_<copy>`) and
+ * the edge it calls makes one Hyperdrive config per database. Hyperdrive reaches a database inside Coolify's
+ * Docker network only through the company's Cloudflare tunnel behind an Access service token, so this step
+ * makes the route once for the server, not once per database:
+ *
+ *   Access app on `<8 hex of org id>-apps-db-hd.<zone>` (a service-token policy) -> tunnel rule
+ *   `tcp://<server host>:5432` -> proxied CNAME to the tunnel,
+ *
+ * the same three parts `worker-app-database.ts` makes for a Worker app's own database (`ensureDatabaseRoute`
+ * is shared), under the scope-id family `bgdb.apps-db.*`, so org destroy and the existing teardown find them.
+ * The zone is the company's domain, or `oikos.host` for a company without one. The service token is minted
+ * once (platform-step rule 1) and held; its id and secret are given to Boule's env, and nowhere else.
+ *
+ * Boule's env gets: {@link APPS_DATABASE_HOST_ENV} (the tunnel hostname Hyperdrive connects to),
+ * {@link APPS_DATABASE_ACCESS_CLIENT_ID_ENV} and {@link APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV} (the Access
+ * service token), {@link APPS_DATABASE_PORT_ENV}. The company's Postgres server speaks no TLS of its own, so
+ * there is no CA to give: the encrypted leg is Hyperdrive to Cloudflare's edge and the tunnel.
+ */
+export declare const APPS_DB_ENTRY_KEY = "apps-db";
+export declare const APPS_DATABASE_HOST_ENV = "APPS_DATABASE_HOST";
+export declare const APPS_DATABASE_PORT_ENV = "APPS_DATABASE_PORT";
+export declare const APPS_DATABASE_ACCESS_CLIENT_ID_ENV = "APPS_DATABASE_ACCESS_CLIENT_ID";
+export declare const APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV = "APPS_DATABASE_ACCESS_CLIENT_SECRET";
+export declare const APPS_DATABASE_ADMIN_URL_ENV = "APPS_DATABASE_ADMIN_URL";
+export declare const APPS_DATABASE_ROUTE_ENVS: readonly ["APPS_DATABASE_HOST", "APPS_DATABASE_PORT", "APPS_DATABASE_ACCESS_CLIENT_ID", "APPS_DATABASE_ACCESS_CLIENT_SECRET"];
+/** The tunnel hostname last written to Boule, recorded last so a failed run is repeated. */
+export declare const APPS_DB_ROUTE_APPLIED_SCOPE_KEY = "apps_db_route_applied";
+/** The tunnel hostname of the company's apps database route. */
+export declare const appsDbHostname: (org: DeclaredOrg) => string;
+export interface PlanAppsDbRouteOptions {
+    /** Access, tunnel, DNS and zone ports are available (edge). */
+    accessReady: boolean;
+    canHoldSecrets: boolean;
+    /** The tunnel is recorded or planned in this plan. */
+    tunnelReady: boolean;
+}
+/**
+ * Pure. `apply` once the company's apps are on and everything the route needs is recorded or planned;
+ * `retire` when they went off and the route is still recorded. Anything missing is blocked, not planned
+ * (platform-step rule 2); a service token minted and never held is blocked and never minted again (rule 1).
+ */
+export declare function planAppsDbRoute(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], options: PlanAppsDbRouteOptions): {
+    steps: DraftStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+/** The Boule app and its env, as the executor wires them. */
+export interface AppsDbRouteBoule {
+    upsertEnvs(rows: Array<{
+        key: string;
+        value: string;
+        literal: true;
+    }>): Promise<void>;
+    deleteEnvs(names: readonly string[]): Promise<void>;
+    restart(): Promise<void>;
+}
+export interface AppsDbRouteDeps {
+    database: Pick<WorkerAppDatabaseDeps, 'tunnels' | 'access' | 'dns' | 'zones'>;
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+    /** Registers a value for redaction before it is written anywhere. */
+    secret(value: string): void;
+    /** The Postgres server's host inside the Docker network (its internal URL's host). */
+    upstreamHost(serverId: string): Promise<string>;
+    boule: AppsDbRouteBoule;
+    /** Test hook: the timeout of a call, in ms. */
+    timeoutMs?: number;
+}
+/** Makes the route true, then gives Boule its env and restarts it. The applied marker is recorded last. */
+export declare function applyAppsDbRoute(deps: AppsDbRouteDeps, org: DeclaredOrg, context: StepExecutionContext): Promise<void>;
+/**
+ * Apps went off: Boule's env rows, then the DNS record, tunnel rule, Access app and service token (and the
+ * held token), then the applied marker. The databases and the role on the server are not touched. A run that
+ * fails halfway is repeated by the next apply (the ids are cleared last).
+ */
+export declare function retireAppsDbRoute(deps: AppsDbRouteDeps, org: DeclaredOrg, context: StepExecutionContext): Promise<void>;
+/** The held secret ref of the route's Access token (for tests and the executor). */
+export declare const appsDbAccessRef: (org: Pick<DeclaredOrg, "id">) => string;
+/** True when the apps admin role is recorded: the route is worth making only with it (used by the planner's caller). */
+export declare const appsAdminRecorded: (recorded: Readonly<Record<string, string>>) => boolean;

package/dist/plan/apps-db-route.js

@@ -0,0 +1,168 @@
+import { ORG_POSTGRES_SERVER_SCOPE_KEY, appsOn } from '../org.js';
+import { withCallTimeout } from '../worker-app-upload.js';
+import { ORG_APPS_ADMIN_SCOPE_KEY } from './org-apps-admin.js';
+import { REMOTE_DATABASE_PORT, remoteDatabaseKeys } from './remote-database.js';
+import { deleteWorkerAppDatabaseRoute, ensureDatabaseRoute, ensureServiceToken, hyperdriveHostname, } from './worker-app-database.js';
+import { WORKER_APP_CALL_TIMEOUT_MS, workerAppApex, workerAppSecretRef } from './worker-app.js';
+/**
+ * F4 (#925): the Hyperdrive route to the company's own Postgres server (`<slug>-postgres`, the one the
+ * apps admin role lives on). Boule creates a database per app copy on that server (`app_<app>_<copy>`) and
+ * the edge it calls makes one Hyperdrive config per database. Hyperdrive reaches a database inside Coolify's
+ * Docker network only through the company's Cloudflare tunnel behind an Access service token, so this step
+ * makes the route once for the server, not once per database:
+ *
+ *   Access app on `<8 hex of org id>-apps-db-hd.<zone>` (a service-token policy) -> tunnel rule
+ *   `tcp://<server host>:5432` -> proxied CNAME to the tunnel,
+ *
+ * the same three parts `worker-app-database.ts` makes for a Worker app's own database (`ensureDatabaseRoute`
+ * is shared), under the scope-id family `bgdb.apps-db.*`, so org destroy and the existing teardown find them.
+ * The zone is the company's domain, or `oikos.host` for a company without one. The service token is minted
+ * once (platform-step rule 1) and held; its id and secret are given to Boule's env, and nowhere else.
+ *
+ * Boule's env gets: {@link APPS_DATABASE_HOST_ENV} (the tunnel hostname Hyperdrive connects to),
+ * {@link APPS_DATABASE_ACCESS_CLIENT_ID_ENV} and {@link APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV} (the Access
+ * service token), {@link APPS_DATABASE_PORT_ENV}. The company's Postgres server speaks no TLS of its own, so
+ * there is no CA to give: the encrypted leg is Hyperdrive to Cloudflare's edge and the tunnel.
+ */
+export const APPS_DB_ENTRY_KEY = 'apps-db';
+export const APPS_DATABASE_HOST_ENV = 'APPS_DATABASE_HOST';
+export const APPS_DATABASE_PORT_ENV = 'APPS_DATABASE_PORT';
+export const APPS_DATABASE_ACCESS_CLIENT_ID_ENV = 'APPS_DATABASE_ACCESS_CLIENT_ID';
+export const APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV = 'APPS_DATABASE_ACCESS_CLIENT_SECRET';
+export const APPS_DATABASE_ADMIN_URL_ENV = 'APPS_DATABASE_ADMIN_URL';
+export const APPS_DATABASE_ROUTE_ENVS = [
+    APPS_DATABASE_HOST_ENV,
+    APPS_DATABASE_PORT_ENV,
+    APPS_DATABASE_ACCESS_CLIENT_ID_ENV,
+    APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV,
+];
+/** The tunnel hostname last written to Boule, recorded last so a failed run is repeated. */
+export const APPS_DB_ROUTE_APPLIED_SCOPE_KEY = 'apps_db_route_applied';
+/** The tunnel hostname of the company's apps database route. */
+export const appsDbHostname = (org) => hyperdriveHostname(org, APPS_DB_ENTRY_KEY, workerAppApex(org));
+const routeKeys = remoteDatabaseKeys(APPS_DB_ENTRY_KEY);
+/**
+ * Pure. `apply` once the company's apps are on and everything the route needs is recorded or planned;
+ * `retire` when they went off and the route is still recorded. Anything missing is blocked, not planned
+ * (platform-step rule 2); a service token minted and never held is blocked and never minted again (rule 1).
+ */
+export function planAppsDbRoute(org, recordedIds, plannedSteps, options) {
+    const key = `cloudflare:apps-db-route:${org.id}`;
+    const at = `${org.slug}'s apps database route`;
+    const blocked = [];
+    const block = (why) => {
+        blocked.push({ description: `${at} is blocked, not planned: ${why}`, key });
+        return { steps: [], blocked };
+    };
+    const draft = (desired, description) => ({
+        action: { system: 'cloudflare', kind: 'apps-db-route', key: org.id, desired },
+        step: { description, destroys: desired.mode === 'retire', migrates: false },
+    });
+    const recordedRoute = Boolean(recordedIds[routeKeys.route] ||
+        recordedIds[routeKeys.access] ||
+        recordedIds[routeKeys.token] ||
+        recordedIds[routeKeys.undelivered] ||
+        recordedIds[APPS_DB_ROUTE_APPLIED_SCOPE_KEY]);
+    if (!appsOn(org)) {
+        if (!recordedRoute)
+            return { steps: [], blocked };
+        if (!options.accessReady)
+            return block('the host supplies no Access, tunnel, DNS or zone port');
+        return {
+            steps: [
+                draft({ mode: 'retire' }, `remove ${org.slug}'s apps database route (the company's Boule runs no apps); the databases stay`),
+            ],
+            blocked,
+        };
+    }
+    const planned = (system, kind) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === org.id);
+    const hostname = appsDbHostname(org);
+    if (recordedIds[APPS_DB_ROUTE_APPLIED_SCOPE_KEY] === hostname)
+        return { steps: [], blocked };
+    if (!options.accessReady)
+        return block('the host supplies no Access, tunnel, DNS or zone port');
+    if (!options.canHoldSecrets)
+        return block('the host cannot hold secrets');
+    const lost = recordedIds[routeKeys.undelivered];
+    if (lost) {
+        return block(`service token ${lost} was created but its secret was never saved, so it cannot be used. To start over, turn apps off and apply (that removes the route and clears this note), delete the token ${lost} in Cloudflare Zero Trust if it is still listed, then turn apps on again`);
+    }
+    if (!recordedIds[ORG_POSTGRES_SERVER_SCOPE_KEY] && !planned('coolify', 'org-postgres')) {
+        return block('its Postgres server is not provisioned yet');
+    }
+    if (!options.tunnelReady)
+        return block("the company's Cloudflare tunnel is not applied yet");
+    if (!recordedIds[`coolify:boule:${org.id}`] && !planned('coolify', 'boule')) {
+        return block('Boule is not recorded yet');
+    }
+    return {
+        steps: [
+            draft({ mode: 'apply', hostname }, `make ${org.slug}'s apps database route (${hostname}) and give Boule the host and its Access token`),
+        ],
+        blocked,
+    };
+}
+/** Makes the route true, then gives Boule its env and restarts it. The applied marker is recorded last. */
+export async function applyAppsDbRoute(deps, org, context) {
+    const at = `cloudflare:apps-db-route for ${org.slug}`;
+    const ms = deps.timeoutMs ?? WORKER_APP_CALL_TIMEOUT_MS;
+    const call = (label, task, over) => withCallTimeout(over ?? ms, `${at}: ${label}`, task);
+    if (!deps.heldKeys.put)
+        throw new Error(`${at}: needs a held-key store that can put`);
+    const put = deps.heldKeys.put;
+    const recorded = context.recordedIds();
+    if (!appsOn(org))
+        throw new Error(`${at}: the company's Boule runs no apps (org.boule.apps)`);
+    const serverId = recorded[ORG_POSTGRES_SERVER_SCOPE_KEY];
+    if (!serverId)
+        throw new Error(`${at}: ${org.slug}'s Postgres server is not recorded yet`);
+    const tunnelId = recorded[`cloudflare:tunnel:${org.id}`];
+    if (!tunnelId)
+        throw new Error(`${at}: ${org.slug}'s Cloudflare tunnel is not applied yet`);
+    if (!recorded[`coolify:boule:${org.id}`])
+        throw new Error(`${at}: Boule is not recorded yet`);
+    const upstreamHost = await call('read the database host', () => deps.upstreamHost(serverId));
+    if (!upstreamHost)
+        throw new Error(`${at}: the Postgres server reports no host`);
+    const hostname = appsDbHostname(org);
+    const access = await ensureServiceToken({ access: deps.database.access, heldKeys: deps.heldKeys, secret: deps.secret }, org, { key: APPS_DB_ENTRY_KEY }, `${org.slug}-apps`, at, call, context, put);
+    await ensureDatabaseRoute(deps.database, call, context, {
+        entryKey: APPS_DB_ENTRY_KEY,
+        accessName: `${org.slug}-apps-db-access`,
+        hostname,
+        upstreamHost,
+        markerDatabase: serverId,
+        tunnelId,
+        zoneApex: workerAppApex(org),
+        tokenId: access.id,
+        at,
+    });
+    deps.secret(access.clientSecret);
+    await call('write Boule env', () => deps.boule.upsertEnvs([
+        { key: APPS_DATABASE_HOST_ENV, value: hostname, literal: true },
+        { key: APPS_DATABASE_PORT_ENV, value: String(REMOTE_DATABASE_PORT), literal: true },
+        { key: APPS_DATABASE_ACCESS_CLIENT_ID_ENV, value: access.clientId, literal: true },
+        { key: APPS_DATABASE_ACCESS_CLIENT_SECRET_ENV, value: access.clientSecret, literal: true },
+    ]));
+    await call('restart Boule', () => deps.boule.restart());
+    context.recordScopeId(APPS_DB_ROUTE_APPLIED_SCOPE_KEY, hostname);
+    await context.persistScopeIds();
+}
+/**
+ * Apps went off: Boule's env rows, then the DNS record, tunnel rule, Access app and service token (and the
+ * held token), then the applied marker. The databases and the role on the server are not touched. A run that
+ * fails halfway is repeated by the next apply (the ids are cleared last).
+ */
+export async function retireAppsDbRoute(deps, org, context) {
+    const at = `cloudflare:apps-db-route for ${org.slug}`;
+    const ms = deps.timeoutMs ?? WORKER_APP_CALL_TIMEOUT_MS;
+    const call = (label, task, over) => withCallTimeout(over ?? ms, `${at}: ${label}`, task);
+    await call('take the env rows out of Boule', () => deps.boule.deleteEnvs([...APPS_DATABASE_ROUTE_ENVS]));
+    await deleteWorkerAppDatabaseRoute(deps.database, deps.heldKeys.put ? { put: deps.heldKeys.put } : undefined, org.id, APPS_DB_ENTRY_KEY, context.recordedIds(), context, call);
+    context.recordScopeId(APPS_DB_ROUTE_APPLIED_SCOPE_KEY, '');
+    await context.persistScopeIds();
+}
+/** The held secret ref of the route's Access token (for tests and the executor). */
+export const appsDbAccessRef = (org) => workerAppSecretRef(org.id, APPS_DB_ENTRY_KEY, 'HYPERDRIVE_ACCESS');
+/** True when the apps admin role is recorded: the route is worth making only with it (used by the planner's caller). */
+export const appsAdminRecorded = (recorded) => Boolean(recorded[ORG_APPS_ADMIN_SCOPE_KEY]);

package/dist/plan/apps-zones.d.ts

@@ -0,0 +1,56 @@
+import { type DeclaredOrg } from '../org.js';
+import type { AppsDbRouteBoule } from './apps-db-route.js';
+import type { DraftStep } from './diff.js';
+import type { ZonePort } from './edge-zones.js';
+import type { StepExecutionContext } from './plan-apply.js';
+/**
+ * FZ: the address facts Boule's managed backend needs next to F3/F4's keys (`EDGE_URL`,
+ * `APPS_DATABASE_*`). With the company's Apps switch on, its Boule env gets:
+ *
+ *   APPS_COMPANY_SLUG          `org.slug`
+ *   APPS_PLATFORM_DOMAIN       the zone the live host `<slug>-<app>.<domain>` sits in: the company's own
+ *                              domain when the company hosts on it, `oikos.host` otherwise
+ *   APPS_ZONE_ID               the Cloudflare zone id of that zone (looked up through the zone port)
+ *   APPS_WORKSPACE_DOMAIN      the workspace domain, a platform constant (`APPS_DOMAIN`)
+ *   APPS_WORKSPACE_ZONE_ID     the zone id of the workspace domain (looked up the same way)
+ *
+ * Boule is restarted after the write. The marker below holds `<slug>|<live domain>` and is recorded last,
+ * so a changed slug or domain is delivered again and a failed run is repeated. Apps off: the five rows
+ * come out and the marker is cleared.
+ */
+export declare const APPS_COMPANY_SLUG_ENV = "APPS_COMPANY_SLUG";
+export declare const APPS_PLATFORM_DOMAIN_ENV = "APPS_PLATFORM_DOMAIN";
+export declare const APPS_ZONE_ID_ENV = "APPS_ZONE_ID";
+export declare const APPS_WORKSPACE_DOMAIN_ENV = "APPS_WORKSPACE_DOMAIN";
+export declare const APPS_WORKSPACE_ZONE_ID_ENV = "APPS_WORKSPACE_ZONE_ID";
+export declare const APPS_ZONES_ENVS: readonly ["APPS_COMPANY_SLUG", "APPS_PLATFORM_DOMAIN", "APPS_ZONE_ID", "APPS_WORKSPACE_DOMAIN", "APPS_WORKSPACE_ZONE_ID"];
+/** What was last written to Boule, recorded last. */
+export declare const APPS_ZONES_APPLIED_SCOPE_KEY = "apps_zones_applied";
+/** The value the marker holds for an org as declared now. */
+export declare const appsZonesMarker: (org: DeclaredOrg) => string;
+export interface PlanAppsZonesOptions {
+    /** The zone port is available (edge). */
+    zonesReady: boolean;
+}
+/**
+ * Pure. `apply` with Apps on once the zone port exists and Boule is recorded or planned, whenever what
+ * Boule holds is not the declared slug and domains; `retire` when Apps went off and a marker is recorded.
+ * Anything missing is blocked in plain words, not planned.
+ */
+export declare function planAppsZones(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], options: PlanAppsZonesOptions): {
+    steps: DraftStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+export interface AppsZonesDeps {
+    zones: Pick<ZonePort, 'findZoneByApex'>;
+    boule: AppsDbRouteBoule;
+    /** Test hook: the timeout of a call, in ms. */
+    timeoutMs?: number;
+}
+/** Looks both zones up, writes the five rows, restarts Boule, then records the marker. */
+export declare function applyAppsZones(deps: AppsZonesDeps, org: DeclaredOrg, context: StepExecutionContext): Promise<void>;
+/** Apps went off: the rows out of Boule, Boule restarted, then the marker cleared. */
+export declare function retireAppsZones(deps: Pick<AppsZonesDeps, 'boule' | 'timeoutMs'>, org: DeclaredOrg, context: StepExecutionContext): Promise<void>;

package/dist/plan/apps-zones.js

@@ -0,0 +1,118 @@
+import { APPS_DOMAIN, appsOn } from '../org.js';
+import { withCallTimeout } from '../worker-app-upload.js';
+import { WORKER_APP_CALL_TIMEOUT_MS, workerAppApex } from './worker-app.js';
+/**
+ * FZ: the address facts Boule's managed backend needs next to F3/F4's keys (`EDGE_URL`,
+ * `APPS_DATABASE_*`). With the company's Apps switch on, its Boule env gets:
+ *
+ *   APPS_COMPANY_SLUG          `org.slug`
+ *   APPS_PLATFORM_DOMAIN       the zone the live host `<slug>-<app>.<domain>` sits in: the company's own
+ *                              domain when the company hosts on it, `oikos.host` otherwise
+ *   APPS_ZONE_ID               the Cloudflare zone id of that zone (looked up through the zone port)
+ *   APPS_WORKSPACE_DOMAIN      the workspace domain, a platform constant (`APPS_DOMAIN`)
+ *   APPS_WORKSPACE_ZONE_ID     the zone id of the workspace domain (looked up the same way)
+ *
+ * Boule is restarted after the write. The marker below holds `<slug>|<live domain>` and is recorded last,
+ * so a changed slug or domain is delivered again and a failed run is repeated. Apps off: the five rows
+ * come out and the marker is cleared.
+ */
+export const APPS_COMPANY_SLUG_ENV = 'APPS_COMPANY_SLUG';
+export const APPS_PLATFORM_DOMAIN_ENV = 'APPS_PLATFORM_DOMAIN';
+export const APPS_ZONE_ID_ENV = 'APPS_ZONE_ID';
+export const APPS_WORKSPACE_DOMAIN_ENV = 'APPS_WORKSPACE_DOMAIN';
+export const APPS_WORKSPACE_ZONE_ID_ENV = 'APPS_WORKSPACE_ZONE_ID';
+export const APPS_ZONES_ENVS = [
+    APPS_COMPANY_SLUG_ENV,
+    APPS_PLATFORM_DOMAIN_ENV,
+    APPS_ZONE_ID_ENV,
+    APPS_WORKSPACE_DOMAIN_ENV,
+    APPS_WORKSPACE_ZONE_ID_ENV,
+];
+/** What was last written to Boule, recorded last. */
+export const APPS_ZONES_APPLIED_SCOPE_KEY = 'apps_zones_applied';
+/** The value the marker holds for an org as declared now. */
+export const appsZonesMarker = (org) => `${org.slug}|${workerAppApex(org)}|${APPS_DOMAIN}`;
+/**
+ * Pure. `apply` with Apps on once the zone port exists and Boule is recorded or planned, whenever what
+ * Boule holds is not the declared slug and domains; `retire` when Apps went off and a marker is recorded.
+ * Anything missing is blocked in plain words, not planned.
+ */
+export function planAppsZones(org, recordedIds, plannedSteps, options) {
+    const key = `cloudflare:apps-zones:${org.id}`;
+    const blocked = [];
+    const draft = (desired, description) => ({
+        action: { system: 'cloudflare', kind: 'apps-zones', key: org.id, desired },
+        step: { description, destroys: desired.mode === 'retire', migrates: false },
+    });
+    const applied = recordedIds[APPS_ZONES_APPLIED_SCOPE_KEY];
+    if (!appsOn(org)) {
+        if (!applied)
+            return { steps: [], blocked };
+        return {
+            steps: [
+                draft({ mode: 'retire' }, `take ${org.slug}'s slug and zone ids out of Boule's env (the company's Boule runs no apps)`),
+            ],
+            blocked,
+        };
+    }
+    if (applied === appsZonesMarker(org))
+        return { steps: [], blocked };
+    const block = (why) => {
+        blocked.push({
+            description: `${org.slug}'s slug and zone ids for Boule are blocked, not planned: ${why}`,
+            key,
+        });
+        return { steps: [], blocked };
+    };
+    if (!options.zonesReady)
+        return block('the host supplies no zone port');
+    const boulePlanned = plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'boule' && p.action.key === org.id);
+    if (!recordedIds[`coolify:boule:${org.id}`] && !boulePlanned) {
+        return block('Boule is not recorded yet');
+    }
+    return {
+        steps: [
+            draft({ mode: 'apply', slug: org.slug, domain: workerAppApex(org), workspaceDomain: APPS_DOMAIN }, `give ${org.slug}'s Boule its slug and the zone ids of ${workerAppApex(org)} and ${APPS_DOMAIN}`),
+        ],
+        blocked,
+    };
+}
+/** Looks both zones up, writes the five rows, restarts Boule, then records the marker. */
+export async function applyAppsZones(deps, org, context) {
+    const at = `cloudflare:apps-zones for ${org.slug}`;
+    const ms = deps.timeoutMs ?? WORKER_APP_CALL_TIMEOUT_MS;
+    const call = (label, task) => withCallTimeout(ms, `${at}: ${label}`, task);
+    if (!appsOn(org))
+        throw new Error(`${at}: the company's Boule runs no apps (org.boule.apps)`);
+    if (!context.recordedIds()[`coolify:boule:${org.id}`]) {
+        throw new Error(`${at}: Boule is not recorded yet`);
+    }
+    const domain = workerAppApex(org);
+    const live = await call(`find the zone of ${domain}`, () => deps.zones.findZoneByApex(domain));
+    if (!live?.id) {
+        throw new Error(`${at} is blocked: no Cloudflare zone for ${domain} was found, so Boule cannot be told its zone id; make the zone, then apply again`);
+    }
+    const workspace = await call(`find the zone of ${APPS_DOMAIN}`, () => deps.zones.findZoneByApex(APPS_DOMAIN));
+    if (!workspace?.id) {
+        throw new Error(`${at} is blocked: no Cloudflare zone for the workspace domain ${APPS_DOMAIN} was found, so Boule cannot be told its zone id; the platform needs that zone before workspace copies can be served`);
+    }
+    await call('write Boule env', () => deps.boule.upsertEnvs([
+        { key: APPS_COMPANY_SLUG_ENV, value: org.slug, literal: true },
+        { key: APPS_PLATFORM_DOMAIN_ENV, value: domain, literal: true },
+        { key: APPS_ZONE_ID_ENV, value: live.id, literal: true },
+        { key: APPS_WORKSPACE_DOMAIN_ENV, value: APPS_DOMAIN, literal: true },
+        { key: APPS_WORKSPACE_ZONE_ID_ENV, value: workspace.id, literal: true },
+    ]));
+    await call('restart Boule', () => deps.boule.restart());
+    context.recordScopeId(APPS_ZONES_APPLIED_SCOPE_KEY, appsZonesMarker(org));
+    await context.persistScopeIds();
+}
+/** Apps went off: the rows out of Boule, Boule restarted, then the marker cleared. */
+export async function retireAppsZones(deps, org, context) {
+    const at = `cloudflare:apps-zones for ${org.slug}`;
+    const ms = deps.timeoutMs ?? WORKER_APP_CALL_TIMEOUT_MS;
+    await withCallTimeout(ms, `${at}: take the env rows out of Boule`, () => deps.boule.deleteEnvs([...APPS_ZONES_ENVS]));
+    await withCallTimeout(ms, `${at}: restart Boule`, () => deps.boule.restart());
+    context.recordScopeId(APPS_ZONES_APPLIED_SCOPE_KEY, '');
+    await context.persistScopeIds();
+}

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

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { sharedSecretRef } from '../org.js';
 import { applyBlueGreenServer } from './blue-green-apply.js';
-import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, actionsKeyName, bgKey, healthTokenName, lbOrigin, mintActionsKey, splitServers, } from './blue-green.js';
+import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, actionsKeyName, bgKey, healthTokenName, lbOrigin, mintActionsKey, mintPinKey, pinKeyName, splitServers, } from './blue-green.js';
 /**
  * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is
  * blue; green, the balancer and stage are new apps beside it on the primary server. The tunnel moves to the
@@ -60,6 +60,16 @@ export async function applyArchonBlueGreen(run) {
         isRunning: run.isRunning,
         adoptRunningBlue: true,
         stageSink: { slug: 'platform' },
+        pinKey: () => mintPinKey({
+            id,
+            ref: sharedSecretRef(run.ownerOrgId, pinKeyName(id)),
+            recorded: run.recorded,
+            record: run.record,
+            persist: run.persist,
+            heldKeys: run.heldKeys,
+            generate: () => randomBytes(32).toString('hex'),
+            secret: run.secret,
+        }),
         actionsKey: async () => {
             const key = await mintActionsKey({
                 id,

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

@@ -3,9 +3,10 @@ import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
 import type { TunnelPort } from './edge-tunnels.js';
 import type { CoolifyPort } from './executor.js';
+import { type StageSignIn } from './stage-env.js';
 import { type StageGuardDeps } from './stage-guards.js';
 /** The Coolify calls this module makes. */
-type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
+type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
     listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
     /** Needed by the stage mail sink; a host without it gets no sink, so no stage mail env. */
     createDockerImageApplication?: CoolifyPort['createDockerImageApplication'];
@@ -24,8 +25,12 @@ export interface BlueGreenApplyDeps {
     };
     /** The entry's one health token: held once, handed to the env writes below and nowhere else. */
     healthToken: () => Promise<string>;
+    /** The balancer's pin key: held, minted once (`mintPinKey`). It goes into the balancer's config file and nowhere else. */
+    pinKey: () => Promise<string>;
     /** Registers a value for redaction before it is written anywhere. */
     secret: (value: string) => void;
+    /** The Coolify GitHub source uuid a new app of `repo` is created through. Absent: the platform's (`requireGithubApp`). */
+    githubAppUuid?: (repo: string) => Promise<string>;
     runtime: DeployHealthRuntime;
     sleep: (ms: number) => Promise<void>;
     /** The step's name, for errors. */
@@ -57,8 +62,22 @@ export interface BlueGreenApplyDeps {
         slug: string;
     };
 }
+/**
+ * What the stage code (the git app, the env, the deploy, the sink, `ensureStage`) needs. A blue/green apply and a
+ * workspace apply both have it. `primaryBlueAppId` is the live app whose env stage's names are checked against;
+ * `null` for a workspace with no live app yet, which has no production to be isolated from.
+ */
+export type StageDeps = Pick<BlueGreenApplyDeps, 'coolify' | 'recorded' | 'record' | 'persist' | 'projectUuid' | 'environment' | 'secret' | 'githubAppUuid' | 'runtime' | 'sleep' | 'label' | 'logDir' | 'isRunning' | 'stageGuards' | 'stageSink' | 'actionsKey'> & {
+    primaryBlueAppId: string | null;
+    /** The stage's own sign-in (a workspace of an entry with `uses.auth`). Absent: stage holds no sign-in env of its own. */
+    signIn?: StageSignIn;
+    /** Where the stage app says it is served (`APP_URL`). Absent: its address on the company network. */
+    stageAppUrl?: string;
+};
 /** What writing a balancer's config needs; {@link BlueGreenApplyDeps} and the release runner both have it. */
 export interface LbConfigDeps {
+    /** The balancer's pin key: held, minted once, never recorded as a value (`mintPinKey`). */
+    pinKey: () => Promise<string>;
     coolify: Pick<Coolify, 'listStorages' | 'createFileStorage' | 'updateFileStorage'>;
     recorded: () => Readonly<Record<string, string>>;
     record: (key: string, value: string) => void;
@@ -80,6 +99,14 @@ export declare function applyBlueGreenServer(deps: BlueGreenApplyDeps, subject:
     uuid: string;
     primaryUuid: string;
 }): Promise<void>;
+/**
+ * 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 declare function applyWorkspaceServer(deps: StageDeps, subject: BlueGreenSubject, serverUuid: string): Promise<void>;
 /** Writes the balancer's config with the recorded weights and records them for this server. */
 export declare function applyBlueGreenWeights(deps: LbConfigDeps, subject: BlueGreenSubject, server: {
     uuid: string;
@@ -104,6 +131,15 @@ export declare function copiedEnv(deps: {
     key: string;
     value: string;
 }>;
+/**
+ * One Mailpit app per company beside stage, shared by every stage of the company. It is checked against the live
+ * app on every run: one that is stopped or gone is deployed again. `stage_sink_applied` is recorded only after
+ * 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).
+ */
+export declare function ensureStageSink(deps: StageDeps, subject: BlueGreenSubject, serverUuid: string): Promise<boolean>;
+/** 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. */
+export declare function ensureStage(deps: StageDeps, subject: BlueGreenSubject, serverUuid: string): Promise<void>;
 /** A connector for the org's tunnel on each given server; the primary's is the existing one. */
 export declare function applyBlueGreenConnectors(input: {
     coolify: Parameters<typeof ensureConnectorsOnServers>[0]['coolify'];