@wtfalch/foundry 0.61.0 → 0.63.0

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

@@ -10,6 +10,8 @@ import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js'
 import { STAGE_SIGN_IN_NAMES, buildStageEnv } from './stage-env.js';
 import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
 import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
+import { StageServiceError, ensureStageServices } from './stage-services.js';
+import { STAGE_SIGNIN_NONE, StageSignInError, ensureStagePublicClient, ensureStageSignIn, } from './stage-signin.js';
 import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_APP_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_IMAGE_TAG, STAGE_SINK_REPOSITORY, stageMailEnv, stageSinkAppName, } from './stage-sink.js';
 import { readWorkspaceCommit, wsKey } from './workspace.js';
 /** How long one Coolify call of the sink may take. */
@@ -95,7 +97,10 @@ export async function applyBlueGreenServer(deps, subject, server) {
             await deps.persist();
         }
     }
-    deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
+    deps.record(bgKey.applied(id, server.uuid), structureHash(subject, {
+        primary: isPrimary,
+        ...(deps.guardInputs ? { guards: deps.guardInputs } : {}),
+    }));
     await deps.persist();
 }
 /**
@@ -481,30 +486,92 @@ export async function ensureStage(deps, subject, serverUuid) {
     const stageHas = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
     const mailChanged = [...mail, ...signInEnv].some((e) => stageHas.get(e.key) !== e.value);
     stageEnv.push(...mail);
-    const stageSurface = {
+    const stageSurfaceOf = () => ({
         env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
         resources: stageResources(subject),
+    });
+    const prodSurface = {
+        env: [...prodEnv, ...greenEnv]
+            .filter((e) => !e.is_preview && e.value !== undefined)
+            .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+        resources: prodResources(subject),
+        internalHosts: Object.values(prodResources(subject)),
     };
-    const violations = assertStageIsolated({
+    const sinkMail = Object.fromEntries(mail.map((e) => [e.key, e.value]));
+    const signInIsolation = deps.signIn
+        ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
+        : {};
+    const isolationViolations = (surface) => assertStageIsolated({
         kind,
-        prod: {
-            env: [...prodEnv, ...greenEnv]
-                .filter((e) => !e.is_preview && e.value !== undefined)
-                .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
-            resources: prodResources(subject),
-            internalHosts: Object.values(prodResources(subject)),
-        },
-        stage: stageSurface,
-        sinkMail: Object.fromEntries(mail.map((e) => [e.key, e.value])),
-        ...(deps.signIn
-            ? { signIn: { customers: deps.signIn.customers, live: deps.signIn.live } }
-            : {}),
+        prod: prodSurface,
+        stage: surface,
+        sinkMail,
+        ...signInIsolation,
     });
+    // The env written this run, and the env stage already holds (put there by an earlier apply, an older
+    // builder or a hand): a forbidden name or a production value already on the live stage app is refused too.
+    // A name this run writes again is replaced, so only the other live names are checked here.
+    const written = new Set(stageEnv.map((e) => e.key));
+    const liveStage = {
+        env: [...stageHas]
+            .filter(([name, value]) => value !== undefined && !written.has(name))
+            .map(([name, value]) => ({ name, class: envClass(name), value })),
+        resources: {},
+    };
+    let stageSurface = stageSurfaceOf();
+    const violations = [
+        ...new Set([
+            ...isolationViolations(stageSurface),
+            ...assertStageIsolated({
+                kind,
+                prod: prodSurface,
+                stage: liveStage,
+                sinkMail,
+                ...signInIsolation,
+            }),
+        ]),
+    ].sort();
     if (violations.length > 0) {
         // Stage fails closed for itself: nothing is written to it, production's structure goes on.
         await stageFailed(deps, subject, `blocked:${violations.join(',')}`);
         return;
     }
+    // Stage's own files, ai and jobs organisations and keys, for the services production's app uses. They are made
+    // before the probes, which need the keys; nothing is written to the stage app until the probes were rejected.
+    const prodValues = new Map(prodEnv
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    let servicesRecord;
+    try {
+        const made = await ensureStageServices({
+            id: subject.id,
+            kind,
+            prod: prodValues,
+            port: deps.stageGuards?.services,
+            recorded: deps.recorded,
+            record: deps.record,
+            persist: deps.persist,
+            secret: deps.secret,
+            log: (line) => console.info(`${deps.label}: ${line}`),
+        });
+        stageEnv.push(...made.env);
+        servicesRecord = made.record;
+    }
+    catch (error) {
+        // A StageServiceError holds ids and refs only; any other cause can echo a credential.
+        if (error instanceof StageServiceError)
+            console.error(`${deps.label}: ${error.message}`);
+        await stageFailed(deps, subject, 'blocked:services', error);
+        return;
+    }
+    if (servicesRecord !== 'none') {
+        stageSurface = stageSurfaceOf();
+        const withServices = isolationViolations(stageSurface);
+        if (withServices.length > 0) {
+            await stageFailed(deps, subject, `blocked:${withServices.join(',')}`);
+            return;
+        }
+    }
     // Stage's credentials are tried against production before they are written; one that production accepts
     // blocks stage (nothing is written to it), and what was tried is recorded by name so the copy slice sees it.
     const stageValues = new Map((await coolify.listEnvs(appId))
@@ -512,7 +579,7 @@ export async function ensureStage(deps, subject, serverUuid) {
         .map((e) => [e.key, e.value]));
     for (const e of stageEnv)
         stageValues.set(e.key, e.value);
-    const isolationHash = stageIsolationHash(stageSurface);
+    let isolationHash = stageIsolationHash(stageSurface);
     let probeResult;
     try {
         probeResult = await runStageProbes(buildStageProbes({
@@ -524,9 +591,12 @@ export async function ensureStage(deps, subject, serverUuid) {
                 ? { liveCustomersOrgId: deps.signIn.live.customersOrgId }
                 : {}),
             ...(deps.signIn ? { signInRedirectUri: deps.signIn.redirectUri } : {}),
-            prod: new Map(prodEnv
-                .filter((e) => !e.is_preview && e.value !== undefined)
-                .map((e) => [e.key, e.value])),
+            prod: new Map([
+                ...prodValues,
+                ...(deps.stageGuards?.services?.prodJobsProjectId
+                    ? [['JOBS_PROJECT_ID', deps.stageGuards.services.prodJobsProjectId]]
+                    : []),
+            ]),
         }));
     }
     catch (error) {
@@ -534,7 +604,7 @@ export async function ensureStage(deps, subject, serverUuid) {
         await stageFailed(deps, subject, 'blocked:database', error);
         return;
     }
-    const probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    let probes = stageProbesRecord(probeResult, isolationHash, stageValues);
     if (probeResult.failed.length > 0) {
         deps.record(bgKey.stageProbes(subject.id), probes.value);
         await stageFailed(deps, subject, `blocked:${probeResult.failed.join(',')}`);
@@ -544,9 +614,108 @@ export async function ensureStage(deps, subject, serverUuid) {
         await stageFailed(deps, subject, 'blocked:gate');
         return;
     }
+    // Stage's own sign-in: made only now, after the isolation check, the probes and the gate. Its credentials are
+    // added to the env and the isolation check runs once more over the whole of it.
+    const signIn = deps.stageGuards?.signIn;
+    let signInGuard;
+    if (signIn?.required === true && signIn.public === true) {
+        // A static SPA (Agora): a client and nothing secret. Its config is built from production's with the stage
+        // client id, then the isolation check runs once more over the whole env.
+        try {
+            const made = await ensureStagePublicClient({
+                id: subject.id,
+                port: signIn,
+                recorded: deps.recorded,
+                record: deps.record,
+                persist: deps.persist,
+            });
+            const rebuilt = buildStageEnv({
+                kind,
+                appUrl: stageAppUrl(subject),
+                logDir: deps.logDir,
+                database,
+                prod: prodEnv,
+                existing: [],
+                mint: () => '',
+                stageClientId: made.clientId,
+            });
+            const config = rebuilt.env.find((e) => e.key === 'AGORA_CONFIG');
+            if (config)
+                stageEnv.push(config);
+            signInGuard = made.guard;
+        }
+        catch (error) {
+            if (error instanceof StageSignInError)
+                console.error(`${deps.label}: ${error.message}`);
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, 'blocked:signin', error);
+            return;
+        }
+        for (const e of stageEnv)
+            stageValues.set(e.key, e.value);
+        stageSurface = stageSurfaceOf();
+        const again = isolationViolations(stageSurface);
+        if (again.length > 0) {
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, `blocked:${again.join(',')}`);
+            return;
+        }
+        isolationHash = stageIsolationHash(stageSurface);
+        probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    }
+    else if (signIn?.required === true) {
+        try {
+            const made = await ensureStageSignIn({
+                id: subject.id,
+                port: signIn,
+                recorded: deps.recorded,
+                record: deps.record,
+                persist: deps.persist,
+                secret: deps.secret,
+                generate: () => randomBytes(32).toString('base64url'),
+                sleep: deps.sleep,
+            });
+            stageEnv.push(...made.env);
+            signInGuard = made.guard;
+        }
+        catch (error) {
+            // A StageSignInError holds ids and refs only; any other cause can echo a credential.
+            if (error instanceof StageSignInError)
+                console.error(`${deps.label}: ${error.message}`);
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, 'blocked:signin', error);
+            return;
+        }
+        if (!stageEnv.some((e) => e.key === 'AUTH_COOKIE_SECRET')) {
+            // A cookie secret of stage's own, kept across applies; never a copy of production's.
+            const have = stageHas.get('AUTH_COOKIE_SECRET') || randomBytes(32).toString('base64url');
+            deps.secret(have);
+            stageEnv.push({ key: 'AUTH_COOKIE_SECRET', value: have });
+        }
+        for (const e of stageEnv)
+            stageValues.set(e.key, e.value);
+        stageSurface = stageSurfaceOf();
+        const again = isolationViolations(stageSurface);
+        if (again.length > 0) {
+            deps.record(bgKey.stageSignIn(subject.id), '');
+            await stageFailed(deps, subject, `blocked:${again.join(',')}`);
+            return;
+        }
+        isolationHash = stageIsolationHash(stageSurface);
+        probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    }
+    else if (signIn?.required === false) {
+        signInGuard = STAGE_SIGNIN_NONE;
+    }
+    else {
+        console.info(`${deps.label}: stage sign-in was not set up: the host gave no sign-in for this subject, so ${bgKey.stageSignIn(subject.id)} stays unrecorded`);
+    }
     await upsertEnv(deps, appId, stageEnv);
+    if (signInGuard)
+        deps.record(bgKey.stageSignIn(subject.id), signInGuard);
     if (mail.length > 0)
         deps.record(bgKey.stageSink(subject.id), 'applied');
+    deps.record(bgKey.stageServices(subject.id), servicesRecord);
     deps.record(bgKey.stageIsolation(subject.id), isolationHash);
     deps.record(bgKey.stageProbes(subject.id), probes.value);
     await deps.persist();
@@ -589,8 +758,11 @@ async function ensureStageGate(deps, subject) {
     if (!gate || deps.recorded()[bgKey.stageGate(subject.id)])
         return true;
     let id;
+    let membersHash;
     try {
-        id = (await gate.create()).id;
+        const created = await gate.create();
+        id = created.id;
+        membersHash = created.membersHash;
     }
     catch (error) {
         // An Access error can echo the request, which names the people allowed in: only its name is logged.
@@ -598,6 +770,8 @@ async function ensureStageGate(deps, subject) {
         return false;
     }
     deps.record(bgKey.stageGate(subject.id), id);
+    if (membersHash)
+        deps.record(bgKey.stageGateMembers(subject.id), membersHash);
     await deps.persist();
     return true;
 }
@@ -607,7 +781,8 @@ async function stageAppId(deps, subject, name, serverUuid) {
         name,
         server: serverUuid,
         branch: subject.branch,
-        autoDeploy: true,
+        // Stage deploys only when a person promotes a commit to it (`deploy_stage`); a merge never reaches it.
+        autoDeploy: false,
     });
 }
 function isNotFound(error) {

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

@@ -1,4 +1,4 @@
-import type { BlueGreenConfig, DeclaredOrg, HostingEntry } from '../org.js';
+import { type BlueGreenConfig, type DeclaredOrg, type HostingEntry } from '../org.js';
 import { type StageKind } from './stage-isolation.js';
 /**
  * Blue/green releases (docs/adr/0001-blue-green-releases.md). A color is a property any app can have
@@ -29,6 +29,8 @@ export declare const bgKey: {
     digest: (id: string, color: Color) => string;
     weights: (id: string) => string;
     stage: (id: string) => string;
+    /** The last `deploy_stage`: `<ISO time>|ok|<commit>` or `<ISO time>|failed|<step>`. */
+    stageDeploy: (id: string) => string;
     window: (id: string) => string;
     held: (id: string, digest: string) => string;
     /** The weights the load balancer on `server` was last written with. */
@@ -55,8 +57,29 @@ export declare const bgKey: {
     stageIsolation: (id: string) => string;
     /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
     stageGate: (id: string) => string;
+    /** The hash of the sorted email list last written to the stage gate (owners plus the people holding `releases:preview`). */
+    stageGateMembers: (id: string) => string;
     /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
     stageProbes: (id: string) => string;
+    /** Stage's own sign-in client: its ZITADEL app id, and its client id (public, not a secret). */
+    stageClient: (id: string) => string;
+    stageClientId: (id: string) => string;
+    /** The held ref of stage's app key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    stageSignInKey: (id: string) => string;
+    /** `{name, organizationId}` of stage's broker entry, so org destroy can remove it. No key. */
+    stageBroker: (id: string) => string;
+    /** `ok:<hash of the client, app and broker entry ids>` or `none`; the copy waits for it. */
+    stageSignIn: (id: string) => string;
+    /** `none` (production's app uses no files, ai or jobs) or `ok:<hash>` once every service it uses is held by stage or listed absent. */
+    stageServices: (id: string) => string;
+    /** `ok:<hash of the ids>` or `absent:<service>:<reason>` for one service (`files`, `ai` or `jobs`). */
+    stageService: (id: string, service: string) => string;
+    /** The id of stage's own organisation (files, ai) or project (jobs). An id, not a secret. */
+    stageServiceOrg: (id: string, service: string) => string;
+    /** The name stage's project or organisation was made under, when the service is deleted by name (jobs). */
+    stageServiceName: (id: string, service: string) => string;
+    /** `{ids, refs}` of stage's keys in that service: key ids and held refs, never a value. */
+    stageServiceKeys: (id: string, service: string) => string;
     /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
     stageSink: (id: string) => string;
     /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
@@ -164,11 +187,14 @@ export interface BlueGreenSubject {
      * (address check, crash loop) and moves up by time.
      */
     reporting: boolean;
-    /** Set for Boule and Agora, which are not hosting entries. */
+    /** Set for Boule, Agora and kosmos, which are not hosting entries. */
     builtin?: BuiltinApp;
 }
-/** The apps foundry runs for every company, which can declare blue/green (`org.boule`, `org.agora`). */
-export type BuiltinApp = 'boule' | 'agora';
+/**
+ * The apps foundry runs for a company that can declare blue/green: Boule and Agora, every company's own, plus
+ * kosmos once the company turns it on (`org.boule`, `org.agora`, `org.kosmos`; docs/adr/0001, rule 1).
+ */
+export type BuiltinApp = 'boule' | 'agora' | 'kosmos';
 export declare const BUILTIN_APPS: readonly BuiltinApp[];
 /** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
 export declare const BUILTIN_APP: {
@@ -188,6 +214,14 @@ export declare const BUILTIN_APP: {
         readonly database: false;
         readonly reporting: false;
     };
+    readonly kosmos: {
+        readonly repo: "wtfalch/kosmos";
+        readonly dockerfile: "/Dockerfile";
+        readonly port: 3000;
+        readonly healthPath: "/api/health";
+        readonly database: true;
+        readonly reporting: true;
+    };
 };
 /**
  * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
@@ -195,11 +229,12 @@ export declare const BUILTIN_APP: {
  */
 export declare function entrySubject(org: DeclaredOrg, entry: HostingEntry, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
 /**
- * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
- * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ * The company's Boule, Agora or kosmos as a subject; `null` when it does not declare blue/green (see
+ * {@link builtinDeclaresBlueGreen}). The running app keeps its name `<slug>-<app>` and is blue, like
+ * platform-archon. All three run on the primary server only.
  */
 export declare function builtinSubject(org: DeclaredOrg, app: BuiltinApp, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
-/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule, Agora and kosmos. */
 export declare function blueGreenSubjects(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): BlueGreenSubject[];
 /** Whether the org declares blue/green for any of its apps. */
 export declare const declaresBlueGreen: (org: DeclaredOrg) => boolean;
@@ -281,9 +316,38 @@ export interface BlueGreenPlanStep {
 /** A short hash of what decides the shape of a server's apps, so a change replans the server. */
 export declare function structureHash(subject: BlueGreenSubject, input: {
     primary: boolean;
+    guards?: readonly string[];
 }): string;
-/** The kind of stage app a subject has: platform-archon, else a customer app. */
-export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id">) => StageKind;
+/**
+ * The kind of stage app a subject has: Boule and Agora by `builtin` (a hosting entry that happens to be keyed
+ * `boule` is still a customer app), platform-archon by its id, else a customer app (kosmos included: it has no lists of its own).
+ */
+export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id" | "builtin">) => StageKind;
+/** What decides which stage guards can be made. Each is a fact the planner and the executor both hold. */
+export interface StageGuardFacts {
+    /** The host supplied the probe port. */
+    probesPort: boolean;
+    /** The host has an Access port. */
+    accessPort: boolean;
+    /** The platform's recorded Access provider. */
+    providerId?: string | null | undefined;
+    /** The domain the stage host is under. */
+    domain?: string | null | undefined;
+    /** The company's sign-in organisation, the claim the gate requires. */
+    claimValue?: string | null | undefined;
+    /** How many owner emails the gate admits. */
+    emails: number;
+    /** A `hosting.access` rule already names the stage host: no gate is made over it. */
+    hostRuled: boolean;
+}
+/**
+ * The stage guards that can be made now, by name. The names go into the applied structure hash, so a guard
+ * that becomes possible after the first apply changes the hash and plans the structure step once more.
+ */
+export declare function stageGuardInputs(facts: StageGuardFacts): string[];
+/** The guard names as the plan's `desired.guards` carries them, and back. */
+export declare const formatGuards: (guards: readonly string[]) => string;
+export declare const parseGuards: (value: unknown) => string[];
 /** The names stage can collide on. */
 export declare function stageResources(subject: BlueGreenSubject): Record<string, string>;
 /** The names of the subject's live parts: stage must equal none of them. */
@@ -310,6 +374,11 @@ export interface PlanBlueGreenInput {
     accessProviderId?: string | null;
     /** The company's stage mail sink is recorded and its live app is stopped or gone (read from Coolify at plan time). */
     stageSinkDown?: boolean;
+    /** Which stage-guard ports the host has. Absent: neither, so no guard input is counted. */
+    stageGuardPorts?: {
+        probes: boolean;
+        access: boolean;
+    };
 }
 /**
  * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the
@@ -359,6 +428,8 @@ export declare function planArchonBlueGreen(input: {
     servers: readonly BlueGreenServer[] | undefined;
     /** Why the executor cannot run it (no way to hold the health token), or absent. */
     executorBlocked?: string | undefined;
+    /** The stage guards that can be made now ({@link stageGuardInputs}); they go into the applied hash. */
+    guards?: readonly string[];
 }): {
     step: BlueGreenPlanStep | null;
     unmanaged: UnmanagedLine[];