@wtfalch/foundry 0.47.0 → 0.48.0

package/dist/plan/stage-env.js

@@ -0,0 +1,52 @@
+import { STAGE_ALLOWLIST, isAllowed, isDenied, isSharedWithProd, } from './stage-isolation.js';
+/** Prod names whose stage value waits for the stage's own organisation or project: absent until then. */
+const WAITS_FOR_STAGE_SERVICE = new Set([
+    'FILES_URL',
+    'AI_URL',
+    'JOBS_SCHEDULER_URL',
+    'ANALYTICS_URL',
+]);
+/** Secrets stage mints for itself, when the app uses them. A copy of prod's value would be a prod credential. */
+const MINTED = ['AUTH_COOKIE_SECRET', 'KEYSTORE_KEK'];
+/**
+ * The env of a stage app, built from the kind's allowlist and never from a copy of the live app's env. Every
+ * name is allowed and none is denied, or this throws a fixed text with the name.
+ */
+export function buildStageEnv(input) {
+    const { kind } = input;
+    const live = (list) => new Map(list
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    const prod = live(input.prod);
+    const existing = live(input.existing);
+    const env = new Map();
+    const set = (key, value) => {
+        if (isDenied(kind, key) || !isAllowed(kind, key)) {
+            throw new Error(`stage env: ${key} is not allowed for a ${kind} stage`);
+        }
+        env.set(key, value);
+    };
+    set('LOG_DIR', input.logDir);
+    if (isAllowed(kind, 'APP_URL'))
+        set('APP_URL', input.appUrl);
+    if (isAllowed(kind, 'APP_ENVIRONMENT'))
+        set('APP_ENVIRONMENT', 'stage');
+    for (const { key, value } of input.database)
+        set(key, value);
+    for (const [key, value] of prod) {
+        if (!env.has(key) &&
+            isSharedWithProd(key) &&
+            isAllowed(kind, key) &&
+            !WAITS_FOR_STAGE_SERVICE.has(key)) {
+            set(key, value);
+        }
+    }
+    for (const key of MINTED) {
+        if (prod.has(key) && isAllowed(kind, key))
+            set(key, existing.get(key) ?? input.mint());
+    }
+    const absent = STAGE_ALLOWLIST[kind]
+        .filter((name) => !name.endsWith('*') && prod.has(name) && !env.has(name))
+        .sort();
+    return { env: [...env].map(([key, value]) => ({ key, value })), absent };
+}

package/dist/plan/stage-guards.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
+ * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
+ * this file returns, logs or throws a value: errors and results carry fixed text and names.
+ */
+/** Milliseconds one probe may take. A probe that does not answer in time is not a rejection. */
+export declare const STAGE_PROBE_TIMEOUT_MS = 10000;
+/**
+ * The calls the host makes to prove a stage credential does not work against production. Every method answers
+ * `true` when production REFUSED the credential, `false` when it accepted it. A method the host does not
+ * implement leaves that probe "not run". No method ever returns a value.
+ */
+export interface StageProbePort {
+    /** Logs in to the production database host with the stage role and password. */
+    databaseRejects?(input: {
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+    }): Promise<boolean>;
+    /** Uses the stage files key on production's organisation. */
+    filesRejects?(input: {
+        url: string;
+        apiKey: string;
+        organisationId: string;
+    }): Promise<boolean>;
+    /** Uses the stage ai key on production's organisation. */
+    aiRejects?(input: {
+        url: string;
+        apiKey: string;
+        organisationId: string;
+    }): Promise<boolean>;
+    /** Uses the stage jobs key on production's project. */
+    jobsRejects?(input: {
+        url: string;
+        syncKey: string;
+        projectId: string;
+    }): Promise<boolean>;
+}
+/** One probe. `run` is `null` when the host has no port for it: the probe is then reported as not run. */
+export interface StageProbe {
+    what: string;
+    /** `true`: production rejected the stage credential. */
+    run: (() => Promise<boolean>) | null;
+}
+export interface StageProbeInput {
+    port: StageProbePort | undefined;
+    /** The env stage will hold. */
+    stage: ReadonlyMap<string, string>;
+    /** The env of the live app. */
+    prod: ReadonlyMap<string, string>;
+    /** Whether stage has a database: if no database probe can be built, one is kept as not run. */
+    database?: boolean;
+}
+/**
+ * The probes for what stage holds: its database role against production's database host, and its files, ai and
+ * jobs keys against production's organisation or project, each only where stage has the key and production
+ * names the target. A probe whose port method is missing is kept with `run: null`.
+ */
+export declare function buildStageProbes(input: StageProbeInput): StageProbe[];
+export interface StageProbeResult {
+    /** Names of the probes production rejected. */
+    rejected: string[];
+    /** Names of the probes that were accepted, threw or timed out: the apply fails on these. */
+    failed: string[];
+    /** Names of the probes with no port: reported as not run, never as passed. */
+    notRun: string[];
+}
+/** Runs every probe once, each under a timeout. A throw and a timeout count as failed, never as rejected. */
+export declare function runStageProbes(probes: readonly StageProbe[], options?: {
+    timeoutMs?: number;
+}): Promise<StageProbeResult>;
+/**
+ * What `bg.<id>.stageprobes` holds: `ok:<hash>` when every probe ran and was rejected (the hash covers the
+ * stage env names, the sha256 of each stage secret and URL value, and the probe names, so a changed stage
+ * credential invalidates it), `notrun:<names>` when a probe had no port, `failed:<names>` when one was accepted.
+ */
+export declare function stageProbesRecord(result: StageProbeResult, isolationHash: string, stage: ReadonlyMap<string, string>): {
+    value: string;
+    ok: boolean;
+};
+/** The Access gate stage's host sits behind: made once, staff only, recorded as `bg.<id>.stagegate`. */
+export interface StageGate {
+    /** The stage host the gate covers. */
+    hostname: string;
+    /** Makes the gate (no bypass and no service-token rule) and returns its id. */
+    create: () => Promise<{
+        id: string;
+    }>;
+}
+export interface StageGuardDeps {
+    probes?: StageProbePort;
+    gate?: StageGate;
+}
+/** The key of the stage gate in the company (a DNS label, like a declared gate's). */
+export declare const stageGateKey: (id: string) => string;
+/** The hostname stage is served at: under the company's domain, never a name production uses. */
+export declare const stageHostname: (domain: string, id: string) => string;
+/** Why stage guards are not ready, or `[]`. Names only; the copy slice calls this before it reads production. */
+export declare function stageGuardsReady(recorded: Readonly<Record<string, string>>, id: string): {
+    ready: boolean;
+    missing: string[];
+};

package/dist/plan/stage-guards.js

@@ -0,0 +1,149 @@
+import { createHash } from 'node:crypto';
+import { bgKey } from './blue-green.js';
+import { envClass } from './stage-isolation.js';
+/**
+ * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
+ * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
+ * this file returns, logs or throws a value: errors and results carry fixed text and names.
+ */
+/** Milliseconds one probe may take. A probe that does not answer in time is not a rejection. */
+export const STAGE_PROBE_TIMEOUT_MS = 10_000;
+const DB_URL = /^[a-z][a-z0-9+.-]*:\/\/([^:@/]*):([^@/]*)@([^/:?#]+)(?::(\d+))?\/([^?#]*)/i;
+function parseDatabaseUrl(name, value) {
+    const match = DB_URL.exec(value);
+    if (!match)
+        throw new Error(`stage probes: ${name} is not a connection URL`);
+    return {
+        user: decodeURIComponent(match[1]),
+        password: decodeURIComponent(match[2]),
+        host: match[3],
+        port: match[4] ? Number(match[4]) : 5432,
+        database: match[5],
+    };
+}
+/**
+ * The probes for what stage holds: its database role against production's database host, and its files, ai and
+ * jobs keys against production's organisation or project, each only where stage has the key and production
+ * names the target. A probe whose port method is missing is kept with `run: null`.
+ */
+export function buildStageProbes(input) {
+    const { port, stage, prod, database } = input;
+    const probes = [];
+    const stageUrl = stage.get('DATABASE_URL');
+    const prodUrl = prod.get('DATABASE_URL_OWNER') ?? prod.get('DATABASE_URL');
+    if (stageUrl && prodUrl) {
+        const from = parseDatabaseUrl('DATABASE_URL', stageUrl);
+        const to = parseDatabaseUrl('the live database URL', prodUrl);
+        const call = port?.databaseRejects?.bind(port);
+        probes.push({
+            what: 'database:stage-role-on-prod-host',
+            run: call
+                ? () => call({
+                    host: to.host,
+                    port: to.port,
+                    database: to.database,
+                    user: from.user,
+                    password: from.password,
+                })
+                : null,
+        });
+    }
+    if (database && !(stageUrl && prodUrl)) {
+        // Stage has a database but a URL could not be read: the guard is not run, never passed.
+        probes.push({ what: 'database', run: null });
+    }
+    for (const [what, urlName, keyName, orgName, method] of [
+        ['files:stage-key-on-prod-org', 'FILES_URL', 'FILES_API_KEY', 'FILES_ORGANISATION_ID', 'files'],
+        ['ai:stage-key-on-prod-org', 'AI_URL', 'AI_API_KEY', 'AI_ORGANISATION_ID', 'ai'],
+    ]) {
+        const url = stage.get(urlName);
+        const apiKey = stage.get(keyName);
+        const organisationId = prod.get(orgName);
+        if (!url || !apiKey || !organisationId)
+            continue;
+        const call = (method === 'files' ? port?.filesRejects : port?.aiRejects)?.bind(port);
+        probes.push({
+            what,
+            run: call ? () => call({ url, apiKey, organisationId }) : null,
+        });
+    }
+    const jobsUrl = stage.get('JOBS_SCHEDULER_URL');
+    const syncKey = stage.get('JOBS_SYNC_KEY');
+    const projectId = prod.get('JOBS_PROJECT_ID');
+    if (jobsUrl && syncKey && projectId) {
+        const call = port?.jobsRejects?.bind(port);
+        probes.push({
+            what: 'jobs:stage-key-on-prod-project',
+            run: call ? () => call({ url: jobsUrl, syncKey, projectId }) : null,
+        });
+    }
+    return probes;
+}
+/** Runs every probe once, each under a timeout. A throw and a timeout count as failed, never as rejected. */
+export async function runStageProbes(probes, options = {}) {
+    const timeoutMs = options.timeoutMs ?? STAGE_PROBE_TIMEOUT_MS;
+    const out = { rejected: [], failed: [], notRun: [] };
+    for (const probe of probes) {
+        if (!probe.run) {
+            out.notRun.push(probe.what);
+            continue;
+        }
+        let timer;
+        try {
+            const rejected = await Promise.race([
+                probe.run(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+                }),
+            ]);
+            (rejected === true ? out.rejected : out.failed).push(probe.what);
+        }
+        catch {
+            // The cause can echo the credential; the name is all the report needs.
+            out.failed.push(probe.what);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    return out;
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * What `bg.<id>.stageprobes` holds: `ok:<hash>` when every probe ran and was rejected (the hash covers the
+ * stage env names, the sha256 of each stage secret and URL value, and the probe names, so a changed stage
+ * credential invalidates it), `notrun:<names>` when a probe had no port, `failed:<names>` when one was accepted.
+ */
+export function stageProbesRecord(result, isolationHash, stage) {
+    if (result.failed.length > 0)
+        return { value: `failed:${result.failed.join(',')}`, ok: false };
+    if (result.notRun.length > 0)
+        return { value: `notrun:${result.notRun.join(',')}`, ok: false };
+    const credentials = [...stage]
+        .filter(([name]) => envClass(name) === 'secret' || envClass(name) === 'url')
+        .map(([name, value]) => `${name}=${sha256(value)}`)
+        .sort();
+    return {
+        value: `ok:${sha256(`${isolationHash}:${result.rejected.join(',')}:${credentials.join(',')}`)}`,
+        ok: true,
+    };
+}
+/** The key of the stage gate in the company (a DNS label, like a declared gate's). */
+export const stageGateKey = (id) => `stage-${id}`;
+/** The hostname stage is served at: under the company's domain, never a name production uses. */
+export const stageHostname = (domain, id) => `stage-${id}.${domain}`;
+/** Why stage guards are not ready, or `[]`. Names only; the copy slice calls this before it reads production. */
+export function stageGuardsReady(recorded, id) {
+    const missing = [];
+    if (!recorded[bgKey.stageIsolation(id)])
+        missing.push('stageisolation');
+    if (!recorded[bgKey.stageGate(id)])
+        missing.push('stagegate');
+    if (!recorded[bgKey.stageProbes(id)]?.startsWith('ok:'))
+        missing.push('stageprobes');
+    // An older ok: record outlives a later block; the stage state says what the last apply found.
+    if (recorded[bgKey.stageState(id)] !== 'ok')
+        missing.push('stagestate');
+    return { ready: missing.length === 0, missing };
+}

package/dist/plan/stage-isolation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The stage-isolation check (campaign T3 section 4). Stage must hold no credential that reaches production,
+ * so this runs before stage gets any env and again when the plan is made. It returns violation names only:
+ * a violation names an env var or a resource kind, never a value.
+ */
+export type StageKind = 'boule' | 'agora' | 'archon' | 'customer';
+export type EnvClass = 'secret' | 'url' | 'id' | 'literal';
+export interface SurfaceEnv {
+    name: string;
+    class: EnvClass;
+    /** The value, where the caller holds it. */
+    value?: string;
+    /** A reference to the value, where the caller holds only that (plan time). */
+    ref?: string;
+}
+/** What one side (production or stage) holds. */
+export interface Surface {
+    env: SurfaceEnv[];
+    /** Every name the side can collide on: app, database and role names, hostnames, container names. */
+    resources: Record<string, string>;
+    /** Internal hosts a stage URL must not name (prod database container, sidecar, balancer, platform apps). */
+    internalHosts?: readonly string[];
+}
+/** The class of an env name, from its spelling. */
+export declare function envClass(name: string): EnvClass;
+/** Env names (or `PREFIX_*`) each kind of stage app may hold. A name not here is refused. */
+export declare const STAGE_ALLOWLIST: Record<StageKind, readonly string[]>;
+/** Whether `name` is on the deny list of `kind`. */
+export declare function isDenied(kind: StageKind, name: string): boolean;
+/** Whether `name` is on the allowlist of `kind`. Mail names are checked by A5 only. */
+export declare function isAllowed(kind: StageKind, name: string): boolean;
+/**
+ * Env that stage holds with the same value as production, on purpose. Each entry says why that cannot write
+ * to production. A name not here must differ from every production value.
+ */
+export declare const SHARED_WITH_PROD: Readonly<Record<string, string>>;
+/** Whether `name` may equal production's value. */
+export declare const isSharedWithProd: (name: string) => boolean;
+export interface StageIsolationInput {
+    kind: StageKind;
+    prod: Surface;
+    stage: Surface;
+    /** The mail env stage is allowed to hold: the sink's wiring. Empty: stage holds no mail env. */
+    sinkMail?: Readonly<Record<string, string>>;
+}
+/**
+ * The violations of stage isolation, as `<code>:<name>`; empty when stage is isolated. Names only: an env
+ * name or a resource kind, never a value.
+ *  - A1 allowlist: `env_not_allowed`. A2 deny list: `env_denied`.
+ *  - A3 values: `value_shared` (a secret, url or id equals a production value), `shared_differs` (a name on
+ *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
+ *  - A4 names: `resource_shared`, `host_is_prod_internal`.
+ *  - A5 mail: `mail_not_sink`, `mail_token`.
+ */
+export declare function assertStageIsolated(input: StageIsolationInput): string[];
+/** The sha256 of the stage env name set plus the resource set: what `bg.<id>.stageisolation` records. */
+export declare function stageIsolationHash(stage: Surface): string;

package/dist/plan/stage-isolation.js

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+const SECRET_NAME = /(KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|KEK|DATABASE_URL)/;
+const URL_NAME = /(_URL|_URI|_UPSTREAM|_ISSUER)$/;
+const ID_NAME = /(_ID|_ORGANI[SZ]ATION_ID)$/;
+/** The class of an env name, from its spelling. */
+export function envClass(name) {
+    if (SECRET_NAME.test(name))
+        return 'secret';
+    if (URL_NAME.test(name))
+        return 'url';
+    if (ID_NAME.test(name))
+        return 'id';
+    return 'literal';
+}
+/** `AB_*` matches by prefix; anything else matches exactly. */
+function globMatches(pattern, name) {
+    return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : pattern === name;
+}
+const matchesAny = (patterns, name) => patterns.some((p) => globMatches(p, name));
+const MAIL_NAME = /^(MAIL_|LETTERMINT_|SMTP_)/;
+/** Env names (or `PREFIX_*`) each kind of stage app may hold. A name not here is refused. */
+export const STAGE_ALLOWLIST = {
+    boule: [
+        'APP_URL',
+        'BOULE_ORG_NAME',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+        'REPORTING_*',
+        'AUTHZ_BOOTSTRAP_OPERATOR*',
+        'AUTHZ_FIRST_OWNER*',
+        'CUSTOMERS_ORGANISATION_ID',
+        'ARCHON_URL',
+        'ARCHON_ORG_ID',
+        'ARCHON_CREDENTIAL',
+        'ARCHON_BRIDGE_SECRET',
+        'AUTHZ_PEER_PASSWORD_OPERATOR',
+        'OWNER_SEED_SECRET',
+    ],
+    agora: ['AGORA_CONFIG', 'SIGNIN_UPSTREAM', 'LOG_DIR'],
+    archon: [
+        'APP_URL',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'CI_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'AUTHZ_DATABASE_URL',
+        'BOULE_URL',
+        'ARCHON_BRIDGE_SECRET',
+        'REPORTING_SITE',
+        'KEYSTORE_KEK',
+        'LOG_LEVEL',
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+    ],
+    customer: [
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+        'APP_URL',
+        'APP_ENVIRONMENT',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'FILES_URL',
+        'FILES_ORGANISATION_ID',
+        'FILES_API_KEY',
+        'AI_URL',
+        'AI_ORGANISATION_ID',
+        'AI_API_KEY',
+        'AI_WEBHOOK_SECRET',
+        'JOBS_SCHEDULER_URL',
+        'JOBS_SIGNING_SECRET',
+        'JOBS_SYNC_KEY',
+        'ANALYTICS_URL',
+        'ANALYTICS_SITE_KEY',
+    ],
+};
+/** Names no stage holds, whatever the app. */
+const DENY_COMMON = [
+    'LETTERMINT_API_TOKEN',
+    'MAIL_ADMIN_*',
+    'MAIL_SMTP_*',
+    'OFFBOARDING_SERVICES',
+    'CHAT_ADMIN_INSTANCES',
+    'COOLIFY_*',
+    'CF_*',
+    'CLOUDFLARE_*',
+    'ZITADEL_*',
+    'TUNNEL_TOKEN',
+    'CUSTOMERS_DIRECTORY_CREDENTIAL',
+    'FOUNDRY_*',
+    'INTEGRATIONS_*',
+    'KEYSTORE_KEK_PREVIOUS',
+    'UPTIME_*',
+    'JOBS_ADMIN_TOKEN',
+    'CUSTOMER_GRANTS',
+    'DEPLOYMENT_CAPABILITIES',
+    'CHARGE_TOKEN',
+    'USAGE_TOKEN',
+    'RELEASE_TICK_TOKEN',
+    'ARCHON_SETUP_CODE',
+    'ARCHON_FIRST_OWNER_LINK',
+    'MAINTENANCE_BYPASS_TOKEN',
+];
+const DENY_BY_KIND = {
+    boule: ['JOBS_*', 'EDGE_*'],
+    agora: [
+        'AGORA_*_UPSTREAM',
+        'AGORA_MAIL_UPSTREAM',
+        'AGORA_FILES_UPSTREAM',
+        'AGORA_CHAT_UPSTREAM',
+        'AGORA_MATRIX_UPSTREAM',
+        'AGORA_MAS_UPSTREAM',
+        'AGORA_CALLS_UPSTREAM',
+        'MESSAGING_*',
+        'MAIL_PROJECT_ID',
+        'FILES_PROJECT_ID',
+        'AGORA_UPDATE_FEED_URL',
+    ],
+    archon: ['FILES_*', 'AI_*', 'JOBS_*', 'KEYS_*', 'EDGE_*'],
+    customer: ['EDGE_*', 'KEYS_*'],
+};
+/** Whether `name` is on the deny list of `kind`. */
+export function isDenied(kind, name) {
+    return matchesAny(DENY_COMMON, name) || matchesAny(DENY_BY_KIND[kind], name);
+}
+/** Whether `name` is on the allowlist of `kind`. Mail names are checked by A5 only. */
+export function isAllowed(kind, name) {
+    return matchesAny(STAGE_ALLOWLIST[kind], name);
+}
+/**
+ * Env that stage holds with the same value as production, on purpose. Each entry says why that cannot write
+ * to production. A name not here must differ from every production value.
+ */
+export const SHARED_WITH_PROD = {
+    AUTH_ISSUER: 'stage signs in through the same issuer by decision; it holds no ZITADEL management token, and an OIDC client cannot write users',
+    AUTH_ORGANIZATION_ID: 'same issuer organisation as AUTH_ISSUER; an id, not a credential',
+    CI_ORGANIZATION_ID: 'an id of the same issuer organisation; not a credential',
+    CUSTOMERS_ORGANISATION_ID: 'an id of the customers organisation in the same issuer; not a credential',
+    BOULE_ORG_NAME: 'a display name',
+    ARCHON_ORG_ID: 'the exact copy of the database holds the same organisation rows',
+    'AUTHZ_BOOTSTRAP_OPERATOR*': 'who may operate stage; an address, not a credential',
+    'AUTHZ_FIRST_OWNER*': 'who owns stage; an address, not a credential',
+    FILES_URL: 'the files service is shared; stage reaches it only with its own organisation and key',
+    AI_URL: 'the ai service is shared; stage reaches it only with its own organisation and key',
+    JOBS_SCHEDULER_URL: 'the jobs service is shared; stage reaches it only with its own project and signing secret',
+    ANALYTICS_URL: 'the analytics collector is shared; stage reports under its own site key',
+};
+/** Whether `name` may equal production's value. */
+export const isSharedWithProd = (name) => Object.keys(SHARED_WITH_PROD).some((p) => globMatches(p, name));
+const LIVE_MODE_KEY = /(^|[^a-z0-9])(sk|rk)_live_|^live_/;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const URL_HOST = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/?#]*@)?([^/?#:]+)/i;
+const hostOf = (value) => URL_HOST.exec(value)?.[1]?.toLowerCase() ?? null;
+/**
+ * The violations of stage isolation, as `<code>:<name>`; empty when stage is isolated. Names only: an env
+ * name or a resource kind, never a value.
+ *  - A1 allowlist: `env_not_allowed`. A2 deny list: `env_denied`.
+ *  - A3 values: `value_shared` (a secret, url or id equals a production value), `shared_differs` (a name on
+ *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
+ *  - A4 names: `resource_shared`, `host_is_prod_internal`.
+ *  - A5 mail: `mail_not_sink`, `mail_token`.
+ */
+export function assertStageIsolated(input) {
+    const { kind, prod, stage } = input;
+    const sink = input.sinkMail ?? {};
+    const out = new Set();
+    const prodByName = new Map();
+    for (const item of prod.env)
+        prodByName.set(item.name, item);
+    const prodHashes = new Set();
+    const prodRefs = new Set();
+    const prodHosts = new Set((prod.internalHosts ?? []).map((h) => h.toLowerCase()));
+    for (const item of prod.env) {
+        if (item.class === 'literal')
+            continue;
+        if (item.value) {
+            prodHashes.add(sha256(item.value));
+            const host = hostOf(item.value);
+            if (host)
+                prodHosts.add(host);
+        }
+        if (item.ref)
+            prodRefs.add(item.ref);
+    }
+    for (const item of stage.env) {
+        const { name } = item;
+        const isMail = MAIL_NAME.test(name);
+        if (isMail) {
+            if (item.value !== sink[name]) {
+                out.add(`${name === 'LETTERMINT_API_TOKEN' ? 'mail_token' : 'mail_not_sink'}:${name}`);
+            }
+        }
+        if (isDenied(kind, name))
+            out.add(`env_denied:${name}`);
+        else if (!isMail && !isAllowed(kind, name))
+            out.add(`env_not_allowed:${name}`);
+        if (item.value !== undefined && LIVE_MODE_KEY.test(item.value))
+            out.add(`live_mode_key:${name}`);
+        if (item.class === 'literal')
+            continue;
+        const shared = isSharedWithProd(name);
+        const counterpart = prodByName.get(name);
+        if (shared) {
+            const same = item.value !== undefined && counterpart?.value !== undefined
+                ? item.value === counterpart.value
+                : item.ref === counterpart?.ref;
+            if (counterpart && !same)
+                out.add(`shared_differs:${name}`);
+            continue;
+        }
+        if (item.value && prodHashes.has(sha256(item.value)))
+            out.add(`value_shared:${name}`);
+        if (item.ref && prodRefs.has(item.ref))
+            out.add(`value_shared:${name}`);
+        const host = item.value ? hostOf(item.value) : null;
+        if (host && prodHosts.has(host))
+            out.add(`host_is_prod_internal:${name}`);
+    }
+    const prodResources = new Set(Object.values(prod.resources));
+    for (const [resourceKind, value] of Object.entries(stage.resources)) {
+        if (prodResources.has(value))
+            out.add(`resource_shared:${resourceKind}`);
+    }
+    return [...out].sort();
+}
+/** The sha256 of the stage env name set plus the resource set: what `bg.<id>.stageisolation` records. */
+export function stageIsolationHash(stage) {
+    const names = stage.env.map((e) => e.name).sort();
+    const resources = Object.entries(stage.resources)
+        .map(([k, v]) => `${k}=${v}`)
+        .sort();
+    return sha256(JSON.stringify({ names, resources }));
+}

package/dist/refuse-org.d.ts

@@ -1,7 +1,7 @@
 import { type DeclaredOrg, type OrgRefusal } from './org.js';
 /**
  * The first refusal of the whole-company validation a store write runs for
- * hosting (every entry, its sign-in included) and customers, or `null`. Locked
+ * hosting (every entry, its sign-in included), customers and the blue/green of Boule and Agora, or `null`. Locked
  * names are the org's own; the platform's service names are not known here.
  */
 export declare function refuseOrg(org: DeclaredOrg): OrgRefusal | null;

package/dist/refuse-org.js

@@ -1,10 +1,12 @@
-import { refuseCustomers, refuseHosting } from './org.js';
+import { refuseBuiltinBlueGreen, refuseCustomers, refuseHosting, } from './org.js';
 import { hostingNames } from './plan/locked-hostnames.js';
 /**
  * The first refusal of the whole-company validation a store write runs for
- * hosting (every entry, its sign-in included) and customers, or `null`. Locked
+ * hosting (every entry, its sign-in included), customers and the blue/green of Boule and Agora, or `null`. Locked
  * names are the org's own; the platform's service names are not known here.
  */
 export function refuseOrg(org) {
-    return refuseHosting(org.hosting, hostingNames(org, [])) ?? refuseCustomers(org);
+    return (refuseHosting(org.hosting, hostingNames(org, [])) ??
+        refuseCustomers(org) ??
+        refuseBuiltinBlueGreen(org));
 }

package/dist/release/decide.d.ts

@@ -92,4 +92,9 @@ export declare function decide(input: {
     stepHoldMinutes?: number | undefined;
     now: Date;
     observation: Observation;
+    /**
+     * The app has no reporting health read (a static app). Only hard fails count: it never reports a relative
+     * fail, steps up by time, and the window closes after its minimum time.
+     */
+    hardOnly?: boolean;
 }): Decision;