@wtfalch/foundry 0.42.1 → 0.44.0

package/dist/plan/blue-green.js

@@ -0,0 +1,444 @@
+import { createHash } from 'node:crypto';
+import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
+import { serverConnectorScopeKey } from './cloudflared-connector.js';
+import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
+import { appNameFor, appStepKey } from './platform-diff.js';
+import { remoteDatabaseAppliedFor } from './remote-database.js';
+export const COLORS = ['blue', 'green'];
+/** The name of `base`'s copy in `color`: `<base>-blue`. */
+export function colorAppName(base, color) {
+    return `${base}-${color}`;
+}
+export const lbAppName = (base) => `${base}-lb`;
+export const stageAppName = (base) => `${base}-stage`;
+/** The color a name carries, or `null`. */
+export function colorOfName(name) {
+    return COLORS.find((color) => name.endsWith(`-${color}`)) ?? null;
+}
+/** Live blue until a release moves it. */
+export const DEFAULT_WEIGHTS = 'blue:100,green:0';
+/** `blue:95,green:5`. Whole percentages that sum to 100, so a typo cannot send traffic nowhere. */
+export function parseWeights(raw) {
+    const text = raw ?? DEFAULT_WEIGHTS;
+    const match = /^blue:(\d{1,3}),green:(\d{1,3})$/.exec(text);
+    if (!match)
+        return null;
+    const weights = { blue: Number(match[1]), green: Number(match[2]) };
+    return weights.blue + weights.green === 100 ? weights : null;
+}
+export const formatWeights = (w) => `blue:${w.blue},green:${w.green}`;
+/** The scope keys of a blue/green subject (contract C3). `.` separated, no `:`. */
+export const bgKey = {
+    live: (id) => `bg.${id}.live`,
+    digest: (id, color) => `bg.${id}.digest.${color}`,
+    weights: (id) => `bg.${id}.weights`,
+    stage: (id) => `bg.${id}.stage`,
+    window: (id) => `bg.${id}.window`,
+    held: (id, digest) => `bg.${id}.held.${digest}`,
+    /** The weights the load balancer on `server` was last written with. */
+    lb: (id, server) => `bg.${id}.lb.${server}`,
+    /** The hash of the structure (apps, balancer, stage) last applied on `server`. */
+    applied: (id, server) => `bg.${id}.applied.${server}`,
+    /** The Coolify app of one part (`blue`, `green`, `lb`, `stage`) on `server`. */
+    app: (id, server, part) => `bg.${id}.app.${server}.${part}`,
+    /** The cloudflared connector app of the tunnel on a non-primary `server`. */
+    connector: (id, server) => `bg.${id}.connector.${server}`,
+    stageDatabase: (id) => `bg.${id}.stagedb`,
+    /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
+    blueName: (id) => `bg.${id}.bluename`,
+    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    pinKey: (id) => `bg.${id}.pinkey`,
+};
+/** The three env names the reporting health read uses (contract C1). */
+export const REPORTING_ENV = {
+    color: 'REPORTING_COLOR',
+    release: 'REPORTING_RELEASE',
+    healthToken: 'REPORTING_HEALTH_TOKEN',
+};
+/** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
+export const healthTokenName = (id) => `reporting-health-${id}`;
+/** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
+export function reportingEnv(input) {
+    return [
+        { key: REPORTING_ENV.color, value: input.color },
+        ...(input.release ? [{ key: REPORTING_ENV.release, value: input.release }] : []),
+        { key: REPORTING_ENV.healthToken, value: input.healthToken },
+    ];
+}
+/**
+ * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
+ * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
+ */
+export function entrySubject(org, entry, recorded) {
+    if (!entry.blueGreen || entry.repo === null || !org.hosting.enabled)
+        return null;
+    const base = appNameFor(org, entry);
+    const isStatic = entry.buildPack === 'static';
+    return {
+        id: entry.key,
+        base,
+        primaryBlueName: liveAppNameFor(org, entry, recorded),
+        port: isStatic ? 80 : (entry.port ?? 80),
+        repo: entry.repo,
+        folder: entry.folder,
+        branch: entry.branch,
+        buildPack: entry.buildPack,
+        healthPath: entry.healthPath ?? (isStatic ? '/' : '/api/health'),
+        database: entry.database,
+        hostnames: entryHostnames(org, entry),
+        config: entry.blueGreen,
+    };
+}
+/**
+ * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
+ * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as
+ * blue, never renamed); else `<base>-blue` for an entry with no app yet.
+ */
+export function liveAppNameFor(org, entry, recorded = {}) {
+    const base = appNameFor(org, entry);
+    if (!entry.blueGreen)
+        return base;
+    const named = recorded[bgKey.blueName(entry.key)];
+    if (named)
+        return named;
+    return recorded[`coolify:app:${appStepKey(org, entry.key)}`] ? base : colorAppName(base, 'blue');
+}
+/** Whether the balancer on the primary is written and the structure applied: the tunnel may move to it. */
+export function balancerApplied(id, recorded, primaryUuid) {
+    return Boolean(primaryUuid && recorded[bgKey.lb(id, primaryUuid)] && recorded[bgKey.applied(id, primaryUuid)]);
+}
+/** The origin the tunnel routes a subject's names to: its balancer, reached on each server's own network. */
+export function lbOrigin(subject) {
+    return `http://${lbAppName(subject.base)}:${subject.port}`;
+}
+/** Usable and reachable servers in the order Coolify lists them, and the uuids of the rest. */
+export function splitServers(all) {
+    const up = [];
+    const down = [];
+    for (const server of all)
+        (server.usable && server.reachable ? up : down).push(server.uuid);
+    return { up, down };
+}
+/** The scope key of the org's primary server (`COOLIFY_SERVER_SCOPE_KEY` in `executor.ts`). */
+export const PRIMARY_SERVER_SCOPE_KEY = 'coolify_server';
+// ---- the load balancer -----------------------------------------------------
+/** The sticky cookie that keeps a user on one color. */
+export const LB_COOKIE_NAME = 'bg_color';
+/** A request with this header goes to the named color whatever the weights; the release runner checks a color with it. */
+export const LB_COLOR_HEADER = 'X-Foundry-Color';
+/** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
+export const LB_PIN_HEADER = 'X-Foundry-Pin';
+const PIN_KEY = /^[0-9a-f]{64}$/;
+/** Above the default priority of `app` (its rule length), so a pinned request never reaches the weighted service. */
+const LB_PIN_PRIORITY = 10000;
+export const LB_CONFIG_PATH = '/etc/traefik/dynamic/lb.yml';
+/** Where the balancer's config lives inside the container, mounted as one file. */
+const LB_ENTRYPOINT = 'web';
+/**
+ * The balancer's inline Dockerfile: a pinned Traefik with a file provider watching one directory.
+ * Weights are never in here, so a weight change is a config write and never a redeploy.
+ */
+export function lbDockerfile(port) {
+    return [
+        `FROM traefik:${pinnedRef('traefik')}`,
+        `CMD ["--providers.file.directory=/etc/traefik/dynamic", "--providers.file.watch=true", "--entrypoints.${LB_ENTRYPOINT}.address=:${port}", "--entrypoints.traefik.address=:8080", "--ping=true", "--log.level=WARN", "--accesslog=false", "--api=false"]`,
+        'HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 CMD ["traefik", "healthcheck", "--ping"]',
+        '',
+    ].join('\n');
+}
+/** The traefik tag the balancer runs, for a test that keeps the pin and the Dockerfile equal. */
+export const LB_IMAGE_REF = `traefik:${VERSIONS.traefik}`;
+/**
+ * The balancer's dynamic config: two weighted services and a sticky cookie. A color at weight 0 is left out
+ * of the weighted list, because Traefik sends a request that carries a sticky cookie to the named service
+ * whatever its weight, which would keep a rolled-back user on the failed color. The weights are in the first
+ * line, so a reader sees both numbers. `backends` are the URLs of each color's containers, one per server.
+ */
+export function renderLbConfig(input) {
+    const { weights, backends, pinKey } = input;
+    if (!PIN_KEY.test(pinKey))
+        throw new Error('the load balancer pin key is not 64 hex characters');
+    const listed = COLORS.filter((color) => weights[color] > 0);
+    const lines = [
+        `# weights ${formatWeights(weights)}`,
+        'http:',
+        '  routers:',
+        ...COLORS.flatMap((color) => [
+            `    pin-${color}:`,
+            `      rule: Header(\`${LB_COLOR_HEADER}\`, \`${color}\`) && Header(\`${LB_PIN_HEADER}\`, \`${pinKey}\`)`,
+            `      priority: ${LB_PIN_PRIORITY}`,
+            `      entryPoints: [${LB_ENTRYPOINT}]`,
+            `      service: ${color}`,
+        ]),
+        '    app:',
+        '      rule: PathPrefix(`/`)',
+        `      entryPoints: [${LB_ENTRYPOINT}]`,
+        '      service: weighted',
+        '  services:',
+        '    weighted:',
+        '      weighted:',
+        '        sticky:',
+        '          cookie:',
+        `            name: ${LB_COOKIE_NAME}`,
+        '            httpOnly: true',
+        '            secure: true',
+        '            sameSite: lax',
+        '        services:',
+        ...listed.flatMap((color) => [
+            `          - name: ${color}`,
+            `            weight: ${weights[color]}`,
+        ]),
+    ];
+    for (const color of COLORS) {
+        lines.push(`    ${color}:`, '      loadBalancer:', '        servers:', ...backends[color].map((url) => `          - url: ${url}`));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * The URL of one color's container on its own server's network. On the primary, blue is the app that was
+ * already there, under its own name; every other color is `<base>-<color>`.
+ */
+export const colorBackend = (subject, color, onPrimary) => `http://${onPrimary && color === 'blue' ? subject.primaryBlueName : colorAppName(subject.base, color)}:${subject.port}`;
+/** A short hash of what decides the shape of a server's apps, so a change replans the server. */
+export function structureHash(subject, input) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        base: subject.base,
+        port: subject.port,
+        repo: subject.repo,
+        folder: subject.folder,
+        branch: subject.branch,
+        buildPack: subject.buildPack,
+        healthPath: subject.healthPath,
+        database: subject.database,
+        primary: input.primary,
+        lb: VERSIONS.traefik,
+    }))
+        .digest('hex')
+        .slice(0, 16);
+}
+/** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
+export function namesNotBlueGreen(org) {
+    const served = new Set();
+    for (const entry of org.hosting.entries) {
+        if (!entry.blueGreen)
+            continue;
+        for (const name of entryHostnames(org, entry))
+            served.add(name);
+        if (entry.hostnames.includes('*')) {
+            const wildcard = wildcardHostname(org);
+            if (wildcard)
+                served.add(wildcard);
+        }
+    }
+    return tunnelIngressHostnames(org).filter((name) => !served.has(name));
+}
+const MAX_NAME = 63;
+/** Restated from `executor.ts`, the same rule as `diff.ts` does: the app id of the org tunnel's cloudflared connector. */
+const TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
+/**
+ * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the
+ * stage on the primary) when the recorded shape differs, else one balancer-config step when only the weights
+ * differ. A server that is down is skipped and reported in `unmanaged`. Pure: reads nothing but its input.
+ */
+export function planBlueGreen(input) {
+    const { org, recordedIds } = input;
+    const steps = [];
+    const unmanaged = [];
+    for (const entry of org.hosting.entries) {
+        const subject = entrySubject(org, entry, recordedIds);
+        if (!subject)
+            continue;
+        const id = subject.id;
+        const blocked = (why, part = 'blocked') => unmanaged.push({
+            description: `${org.slug}'s ${id} app blue/green is blocked, not planned: ${why}`,
+            key: `bg:${id}:${part}`,
+        });
+        if (entry.buildPack === 'dockercompose')
+            continue;
+        if (colorAppName(subject.base, 'green').length > MAX_NAME) {
+            blocked('its app name is too long for the green copy; shorten the slug or the entry key');
+            continue;
+        }
+        if (!input.servers) {
+            blocked('the host cannot list Coolify servers');
+            continue;
+        }
+        if (!input.canHoldSecrets) {
+            blocked('the host cannot hold the health token (its held keys cannot put)');
+            continue;
+        }
+        const weights = parseWeights(recordedIds[bgKey.weights(id)]);
+        if (!weights) {
+            blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`, 'weights');
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${appStepKey(org, id)}`] && !input.appPlanned(id)) {
+            blocked('its blue copy is not recorded and no app step is planned to make it');
+            continue;
+        }
+        const { up, down } = splitServers(input.servers);
+        const recordedPrimary = recordedIds[PRIMARY_SERVER_SCOPE_KEY];
+        const primary = recordedPrimary ?? up[0];
+        if (!primary || !up.includes(primary)) {
+            blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
+            continue;
+        }
+        for (const uuid of down) {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${uuid}: the server is not usable or not reachable right now`,
+                key: `bg:${id}:down:${uuid}`,
+            });
+        }
+        const others = up.filter((uuid) => uuid !== primary);
+        const unrouted = namesNotBlueGreen(org);
+        const useOthers = others.length > 0 && unrouted.length === 0;
+        if (others.length > 0 && !useOthers) {
+            blocked('a second server needs every name on the tunnel to be blue/green, because its connector answers all of them', 'servers');
+        }
+        const targets = [primary, ...(useOthers ? others : [])];
+        if (useOthers && recordedIds[`cloudflare:tunnel:${org.id}`]) {
+            for (const server of others) {
+                const key = `${org.id}:${server}`;
+                if (!recordedIds[serverConnectorScopeKey(TUNNEL_CONNECTOR_APP_SCOPE_KEY, server)] &&
+                    !steps.some((s) => s.kind === 'bluegreen-connector' && s.key === key)) {
+                    steps.push({
+                        kind: 'bluegreen-connector',
+                        phase: 'after',
+                        key,
+                        description: `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel on Coolify server ${server}`,
+                        desired: { server, primary },
+                    });
+                }
+            }
+        }
+        for (const server of targets) {
+            const isPrimary = server === primary;
+            const key = `${org.id}:${id}:${server}`;
+            const hash = structureHash(subject, { primary: isPrimary });
+            if (!isPrimary && subject.database && !remoteDatabaseAppliedFor(recordedIds, id, server)) {
+                unmanaged.push({
+                    description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${server} yet: its database route to that server is not applied`,
+                    key: `bg:${id}:dbroute:${server}`,
+                });
+                continue;
+            }
+            if (recordedIds[bgKey.applied(id, server)] !== hash) {
+                steps.push({
+                    kind: 'bluegreen',
+                    phase: 'before',
+                    key,
+                    description: `run ${org.slug}'s ${id} app as blue and green behind a load balancer on Coolify server ${server}${isPrimary ? ', with a stage copy' : ''}`,
+                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                });
+            }
+            else if (recordedIds[bgKey.lb(id, server)] !== formatWeights(weights)) {
+                steps.push({
+                    kind: 'bluegreen-lb',
+                    phase: 'before',
+                    key,
+                    description: `set ${org.slug}'s ${id} app traffic to ${formatWeights(weights)} on Coolify server ${server}`,
+                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                });
+            }
+        }
+    }
+    return { steps, unmanaged };
+}
+// ---- platform-archon -------------------------------------------------------
+/** The scope-key id, base name and port platform-archon runs under. */
+export const ARCHON_SUBJECT_ID = 'platform-archon';
+/** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
+export const ARCHON_REPO = 'wtfalch/archon';
+const ARCHON_PORT_NUMBER = 3000;
+/**
+ * platform-archon as a blue/green subject: the same type a hosting entry makes. Its running app keeps its
+ * name and serves as the blue copy, because renaming its container would take its sign-in and tunnel down
+ * mid-apply; green and the balancer are new apps beside it.
+ */
+export function archonSubject(platform, repo) {
+    const { archon } = platform;
+    if (!archon.enabled || !archon.blueGreen)
+        return null;
+    return {
+        id: ARCHON_SUBJECT_ID,
+        base: ARCHON_SUBJECT_ID,
+        primaryBlueName: ARCHON_SUBJECT_ID,
+        port: ARCHON_PORT_NUMBER,
+        repo,
+        folder: null,
+        branch: archon.gitRef,
+        buildPack: 'dockerfile',
+        healthPath: '/api/health',
+        database: true,
+        hostnames: [archon.hostname],
+        config: archon.blueGreen,
+    };
+}
+/**
+ * Where the tunnel sends a subject's names: its balancer once the structure on the primary is applied (the
+ * balancer's config written and every part running), else the app as before. Pointing the tunnel at a balancer
+ * that does not exist or does not answer yet would take the site down.
+ */
+export function tunnelOriginFor(subject, recorded, primaryUuid, fallback) {
+    if (!subject || !balancerApplied(subject.id, recorded, primaryUuid))
+        return fallback;
+    return lbOrigin(subject);
+}
+/** The origin the archon step last wrote to the tunnel through {@link tunnelOriginFor}, recorded by the platform step. */
+export const ARCHON_BG_ORIGIN_SCOPE_KEY = 'archon_bluegreen_origin';
+/** The platform scope keys the archon plan reads (restated from `platform-diff.ts`, which imports this module). */
+const ARCHON_APP_RECORD = 'coolify:app:platform:archon';
+const ARCHON_TUNNEL_RECORD = 'cloudflare_platform_archon_tunnel';
+/**
+ * Plans the one platform step that runs platform-archon on the blue/green path: the structure on the primary
+ * server, the balancer's weights, and the tunnel's move to the balancer. It plans nothing until archon's app and
+ * tunnel are recorded, because the step copies the app's env and moves that tunnel. Archon runs on the primary
+ * only: the platform has no database route to another server.
+ */
+export function planArchonBlueGreen(input) {
+    const subject = archonSubject(input.platform, input.repo);
+    const none = { step: null, unmanaged: [] };
+    if (!subject)
+        return none;
+    const { recorded } = input;
+    if (!recorded[ARCHON_APP_RECORD] || !recorded[ARCHON_TUNNEL_RECORD])
+        return none;
+    const blocked = (why) => ({
+        step: null,
+        unmanaged: [
+            {
+                description: `platform-archon blue/green is blocked, not planned: ${why}`,
+                key: `bg:${subject.id}:blocked`,
+            },
+        ],
+    });
+    if (input.executorBlocked)
+        return blocked(input.executorBlocked);
+    if (!input.servers)
+        return blocked('the host cannot list Coolify servers');
+    const weights = parseWeights(recorded[bgKey.weights(subject.id)]);
+    if (!weights)
+        return blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`);
+    const { up } = splitServers(input.servers);
+    const primary = recorded[PRIMARY_SERVER_SCOPE_KEY] ?? up[0];
+    if (!primary || !up.includes(primary)) {
+        return blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
+    }
+    const done = recorded[bgKey.applied(subject.id, primary)] === structureHash(subject, { primary: true }) &&
+        recorded[bgKey.lb(subject.id, primary)] === formatWeights(weights) &&
+        recorded[ARCHON_BG_ORIGIN_SCOPE_KEY] === lbOrigin(subject);
+    if (done)
+        return none;
+    return {
+        unmanaged: [],
+        step: {
+            kind: 'bluegreen',
+            phase: 'after',
+            key: subject.id,
+            description: `run platform-archon as blue and green behind a load balancer on Coolify server ${primary}, then send its tunnel to the balancer`,
+            desired: { subject: subject.id, primary, weights: formatWeights(weights) },
+        },
+    };
+}

package/dist/plan/boule.d.ts

@@ -79,8 +79,44 @@ export declare const BOULE_PEER_PASSWORD_ENV = "AUTHZ_PEER_PASSWORD_OPERATOR";
 export declare const BOULE_BRIDGE_SECRET_ENV = "ARCHON_BRIDGE_SECRET";
 /** The role Boule creates from {@link BOULE_PEER_PASSWORD_ENV}, with grants on schema `authz` only. */
 export declare const BOULE_PEER_ROLE = "authz_operator_rt";
+/** The org's Archon id and the credential Boule reaches Archon with (C3). The id is the org's own; the credential is a secret. */
+export declare const BOULE_ARCHON_ORG_ID_ENV = "ARCHON_ORG_ID";
+export declare const BOULE_ARCHON_CREDENTIAL_ENV = "ARCHON_CREDENTIAL";
+/** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
+export declare const BOULE_CUSTOMERS_ORG_ENV = "CUSTOMERS_ORGANISATION_ID";
+export declare const BOULE_CUSTOMERS_CREDENTIAL_ENV = "CUSTOMERS_DIRECTORY_CREDENTIAL";
+/**
+ * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
+ * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
+ * push is {@link ARCHON_CREDENTIAL_RENEW_AFTER_MS} old.
+ */
+export declare const BOULE_ARCHON_PUSHED_AT_SCOPE_KEY = "boule_archon_pushed_at";
+export declare const ARCHON_CREDENTIAL_RENEW_AFTER_MS: number;
+/** True when no push is recorded, it is unreadable, or it is at least 335 days old. */
+export declare function archonCredentialRenewDue(recorded: Readonly<Record<string, string>>, nowMs: number): boolean;
+/** The ZITADEL machine user that reads the customers organisation. No secret. */
+export declare const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = "customers_directory_user";
+/** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
+export declare const CUSTOMERS_SIGN_UP_SCOPE_KEY = "zitadel_customers_signup";
+/** Where the held-key store keeps the Archon credential of an org's Boule. */
+export declare const bouleArchonCredentialRef: (orgId: string) => string;
+/** Where the held-key store keeps the directory credential of an org's customers. */
+export declare const customersDirectoryRef: (orgId: string) => string;
+/** The customers organisation id `zitadel:customers` recorded. */
+export declare const customersOrgIdOf: (org: Pick<DeclaredOrg, "id">, recorded: Readonly<Record<string, string>>) => string | undefined;
+/**
+ * What the host can deliver to an org's Boule beyond its sign-in env: the Archon credential
+ * (`mintBouleArchonCredential`) and the customers directory credential (`mintOrgDirectoryReader`).
+ * Each needs a held-key store that can put. The plan decides once and carries the answer in the step.
+ */
+export interface BouleCredentialWants {
+    archonCredential?: boolean;
+    customersDirectory?: boolean;
+    /** The recorded Archon credential is missing or 335 days old: the step mints it again. */
+    archonRenewDue?: boolean;
+}
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "SIGNIN_UPSTREAM"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "SIGNIN_UPSTREAM"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a
@@ -106,7 +142,7 @@ export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER",
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean): {
+export declare function desiredBouleEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, issuer: string | null, archonUrl: string | null, mailWanted?: boolean, wants?: BouleCredentialWants): {
     env: Record<string, string>;
     missing: string[];
 };
@@ -129,3 +165,8 @@ export declare function wantedBouleBrokerEntry(org: DeclaredOrg, recorded: Reado
  * except `SIGNIN_UPSTREAM`: the switch turned off must take it away, so a live one that is not desired is drift.
  */
 export declare function bouleEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+/**
+ * The customers env a live Boule still holds after the company switched customers off. A host that merely
+ * cannot deliver the credential keeps what it has: only an explicit off removes it.
+ */
+export declare function staleCustomersEnv(org: Pick<DeclaredOrg, 'customers'>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/boule.js

@@ -90,6 +90,34 @@ export const BOULE_PEER_PASSWORD_ENV = 'AUTHZ_PEER_PASSWORD_OPERATOR';
 export const BOULE_BRIDGE_SECRET_ENV = 'ARCHON_BRIDGE_SECRET';
 /** The role Boule creates from {@link BOULE_PEER_PASSWORD_ENV}, with grants on schema `authz` only. */
 export const BOULE_PEER_ROLE = 'authz_operator_rt';
+/** The org's Archon id and the credential Boule reaches Archon with (C3). The id is the org's own; the credential is a secret. */
+export const BOULE_ARCHON_ORG_ID_ENV = 'ARCHON_ORG_ID';
+export const BOULE_ARCHON_CREDENTIAL_ENV = 'ARCHON_CREDENTIAL';
+/** The company's customers organisation in the sign-in service, and the read-only credential that lists its people (C3). */
+export const BOULE_CUSTOMERS_ORG_ENV = 'CUSTOMERS_ORGANISATION_ID';
+export const BOULE_CUSTOMERS_CREDENTIAL_ENV = 'CUSTOMERS_DIRECTORY_CREDENTIAL';
+/**
+ * When the Archon credential was last minted and held (ISO date-time). No secret. Archon's mint rotates
+ * on every call and the credential lives 365 days, so foundry mints only when none was pushed or the
+ * push is {@link ARCHON_CREDENTIAL_RENEW_AFTER_MS} old.
+ */
+export const BOULE_ARCHON_PUSHED_AT_SCOPE_KEY = 'boule_archon_pushed_at';
+export const ARCHON_CREDENTIAL_RENEW_AFTER_MS = 335 * 24 * 60 * 60 * 1000;
+/** True when no push is recorded, it is unreadable, or it is at least 335 days old. */
+export function archonCredentialRenewDue(recorded, nowMs) {
+    const at = Date.parse(recorded[BOULE_ARCHON_PUSHED_AT_SCOPE_KEY] ?? '');
+    return Number.isNaN(at) || nowMs - at >= ARCHON_CREDENTIAL_RENEW_AFTER_MS;
+}
+/** The ZITADEL machine user that reads the customers organisation. No secret. */
+export const CUSTOMERS_DIRECTORY_USER_SCOPE_KEY = 'customers_directory_user';
+/** `1` or `0`: the sign-up switch last written to the customers organisation's login policy. */
+export const CUSTOMERS_SIGN_UP_SCOPE_KEY = 'zitadel_customers_signup';
+/** Where the held-key store keeps the Archon credential of an org's Boule. */
+export const bouleArchonCredentialRef = (orgId) => `foundry:boule-archon:${orgId}`;
+/** Where the held-key store keeps the directory credential of an org's customers. */
+export const customersDirectoryRef = (orgId) => `foundry:customers-directory:${orgId}`;
+/** The customers organisation id `zitadel:customers` recorded. */
+export const customersOrgIdOf = (org, recorded) => recorded[`zitadel:customers:${org.id}`] || undefined;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
 export const BOULE_MANAGED_ENV_KEYS = [
     'APP_URL',
@@ -104,6 +132,10 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_MAIL_TOKEN_ENV,
     BOULE_PEER_PASSWORD_ENV,
     BOULE_BRIDGE_SECRET_ENV,
+    BOULE_ARCHON_ORG_ID_ENV,
+    BOULE_ARCHON_CREDENTIAL_ENV,
+    BOULE_CUSTOMERS_ORG_ENV,
+    BOULE_CUSTOMERS_CREDENTIAL_ENV,
     SIGN_IN_UPSTREAM_ENV,
 ];
 /**
@@ -131,7 +163,7 @@ export const BOULE_MANAGED_ENV_KEYS = [
  * (`DATABASE_URL_OWNER`, `DATABASE_URL`, minted once) and `AUTH_COOKIE_SECRET`
  * (generated once, never rotated).
  */
-export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false) {
+export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = false, wants = {}) {
     const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
     const clientId = recorded[BOULE_CLIENT_ID_SCOPE_KEY];
     const missing = [];
@@ -153,6 +185,12 @@ export function desiredBouleEnv(org, recorded, issuer, archonUrl, mailWanted = f
         env.AUTH_CLIENT_ID = clientId;
     if (archonUrl)
         env.ARCHON_URL = archonUrl;
+    if (wants.archonCredential)
+        env[BOULE_ARCHON_ORG_ID_ENV] = org.id;
+    // The id is not missing while unrecorded: the customers step records it, and the plan plans Boule again then.
+    const customersOrgId = wants.customersDirectory ? customersOrgIdOf(org, recorded) : undefined;
+    if (customersOrgId)
+        env[BOULE_CUSTOMERS_ORG_ENV] = customersOrgId;
     const owner = org.owners[0];
     const ownerUserId = owner
         ? recorded[`zitadel:owner:${org.id}:${owner.email.toLowerCase()}`]
@@ -219,3 +257,12 @@ export function bouleEnvDrift(desired, live) {
         drift.push(SIGN_IN_UPSTREAM_ENV);
     return drift;
 }
+/**
+ * The customers env a live Boule still holds after the company switched customers off. A host that merely
+ * cannot deliver the credential keeps what it has: only an explicit off removes it.
+ */
+export function staleCustomersEnv(org, live) {
+    if (org.customers?.enabled)
+        return [];
+    return [BOULE_CUSTOMERS_ORG_ENV, BOULE_CUSTOMERS_CREDENTIAL_ENV].filter((key) => live[key] !== undefined);
+}

package/dist/plan/broker-entries.d.ts

@@ -19,6 +19,28 @@ export declare function brokerEntryName(org: DeclaredOrg, entry: HostingEntry):
 export declare function brokerEntryAppliedScopeKey(entryKey: string): string;
 /** The foreign entries the last write found invalid, as a JSON array of names. */
 export declare function brokerEntryWarningsScopeKey(entryKey: string): string;
+/** The ZITADEL project id that is an MCP entry's token audience, recorded by `zitadel:mcp-project`. */
+export declare const entryMcpProjectScopeKey: (entryKey: string) => string;
+/** The marker for the entry's app having JWT access tokens and the MCP callback (`zitadel:mcp-access`). */
+export declare const entryMcpAccessAppliedScopeKey: (entryKey: string) => string;
+/** The instance access-token lifetime the MCP flow wants, in seconds (auth ADR 0002, 4). */
+export declare const MCP_ACCESS_TOKEN_LIFETIME_SECONDS = 3600;
+/** Records the lifetime foundry last set; the value is {@link MCP_ACCESS_TOKEN_LIFETIME_SECONDS}. */
+export declare const ACCESS_TOKEN_LIFETIME_APPLIED_SCOPE_KEY = "access_token_lifetime_applied";
+/** The broker's callback on the org's login host. It joins the entry app's redirect URIs. */
+export declare const mcpCallbackUri: (org: DeclaredOrg) => string;
+/**
+ * What an entry's MCP resource is, from the one recorded project id. The
+ * broker entry (`wantedBrokerEntry`) and the app's env (`entryAuthEnv`) both
+ * read it here, so the audience the broker checks and the audience the app
+ * compares are the same value. `null` without `mcp`, or until the project
+ * exists.
+ */
+export declare function entryMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    resource: string;
+    projectId: string;
+    loginHost: string;
+} | null;
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
@@ -32,6 +54,12 @@ export interface BrokerEntryWant {
     from: string;
     registration: boolean;
     replaces: string | null;
+    /** Present only for an entry with `uses.auth.mcp`: what the broker needs to be its authorization server. */
+    mcp?: {
+        resource: string;
+        projectId: string;
+        loginHost: string;
+    };
 }
 /**
  * Each value a broker entry needs and the step that records it, so the