cursedbelt-server 4.18.1 → 4.19.0

package/dist/server/satellite/config.js

@@ -0,0 +1,259 @@
+/**
+ * `cursedbelt-server/satellite-config` — the satellite CONFIGURATION contract, once: the fields
+ * every app's config carried, the data-dir convention, the test-runner guards, and the refusal
+ * of a production boot that cannot serve safely. Bun/Node only (`node:fs`); a Worker imports
+ * `cursedbelt-server/satellite-door`, which this re-exports whole.
+ *
+ * ## Why, since 4.19.0 (task 281)
+ *
+ * Measured 2026-09-23: nine `appConfig.ts` copies in five versions, plus `appData.ts`,
+ * `stageIdentity.ts` and `runtimeMode.ts` travelling with them. The file's whole job is
+ * `productionBlockers` + `assertUsable`, and the versions differed in exactly that job:
+ *
+ *  · lineage B (`flix`, `station`, `patterns`) threw a plain `Error` — a misconfigured boot
+ *    presented as a crash — where lineage A threw `cwip/env`'s `ConfigRefusalError` (exit 78);
+ *  · `vault`'s trimmed copy dropped the extra-blockers argument, so it COULD not add one;
+ *  · `vault`, `flix` and `station` lost the stage-identity override (`./satellite-door`);
+ *  · lineage A's `appData.ts` called `forgeState({ HOME })`, which threw the environment away —
+ *    so `$FORGE_STATE` was never read, and the state root was spelled with the generation's
+ *    NAME in it (task 304). Here it comes from `cursedops/roots`, which reads `$FORGE_STATE` and
+ *    otherwise the `forge.env` above this module — correct in a launchd job, in a worktree, and
+ *    in the next generation with no edit — and REFUSES rather than guessing.
+ *
+ * The union of the protections is what is here. What an app still owns is its identity: its own
+ * fields, its `stakes` sentence, and its own blockers, passed as `extra` — never a fork of this.
+ *
+ * ## The one behaviour that is STRICTER than every copy
+ *
+ * The refusal fires when the instance is `live` — a release OR a production build — where lineage
+ * A asked only "is this a production build". Every `scripts/service.ts` sets
+ * `NODE_ENV=production`, so the two agree on every real boot today; `live` is the one that also
+ * refuses a release someone started without it.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertConfigUsable, readIntEnv, readOriginEnv, sessionSecretBlocker, } from "cwip/env";
+import { forgeState } from "cursedops/roots";
+import { DEV_AUTH_URL, isProductionRuntime, isRelease, isTestRuntime, LOCAL_AUTH_URL, parseEmailList, PROD_AUTH_URL, stageIdentityIsLocal, TEST_SCRATCH_DIR_NAME, } from "./door.js";
+export * from "./door.js";
+export { formatConfigBlockers, isConfigRefusal, sessionSecretBlocker } from "cwip/env";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// ── the state root, and the data directory under it ─────────────────────────────────────────
+/** Where the generation keeps state: `options.stateRoot`, else `cursedops/roots`, else `null`. */
+function stateRootOrNull(env, explicit) {
+    if (explicit)
+        return explicit;
+    return forgeState(HERE, env);
+}
+/**
+ * The generation's state root — every app's durable data lives under it.
+ *
+ * 🔴 Throws rather than guessing: a function that invented `$HOME/.<something>` would write into
+ * a stranger's tree, and would be right for exactly one generation.
+ */
+export function stateRoot(options = {}) {
+    const root = stateRootOrNull(options.env ?? process.env, options.stateRoot);
+    if (root)
+        return root;
+    throw new Error("No generation state root: $FORGE_STATE is unset and no forge.env was found above this checkout.\n" +
+        "  Source the generation's forge.env first, run from inside its checkout, or set APP_DATA_DIR.");
+}
+/** The scratch tree tests may write under — the one carve-out {@link assertTestSafeDbPath} allows. */
+export function testScratchRoot(options = {}) {
+    return path.join(stateRoot(options), TEST_SCRATCH_DIR_NAME);
+}
+/** A deployed app's data directory: `<state root>/apps/<app>`. */
+export function deployedDataDirFor(app, options = {}) {
+    return path.join(stateRoot(options), "apps", app);
+}
+/** Why a test was refused a real data directory. */
+export function realDataDirRefusal(app) {
+    return (`[${app}] refusing to resolve a REAL data directory under a test runner.\n` +
+        "A test must never open the owner's live database — it is their credentials, notes and saves, " +
+        "and a test is allowed to delete rows.\n" +
+        'Pass an explicit path instead: ":memory:", a scratch directory, or set APP_DATA_DIR for this process.\n' +
+        "(If you are testing THIS resolution, set SATELLITE_ALLOW_REAL_DATA_DIR_IN_TEST=1.)");
+}
+/**
+ * Where this app's durable data lives. `APP_DATA_DIR` when the deploy assigned one; under a test
+ * runner, a REFUSAL (never the owner's live database); otherwise `<state root>/apps/<devDirName>`.
+ */
+export function resolveAppDataDir(options) {
+    const env = options.env ?? process.env;
+    const assigned = env.APP_DATA_DIR?.trim();
+    if (assigned)
+        return assigned;
+    if (isTestRuntime(env) && env.SATELLITE_ALLOW_REAL_DATA_DIR_IN_TEST !== "1") {
+        throw new Error(realDataDirRefusal(options.app));
+    }
+    return path.join(stateRoot(options), "apps", options.devDirName ?? options.app);
+}
+/**
+ * `bun:sqlite`'s `create: true` creates the file, never the directory above it. Swallowed on
+ * purpose: the open that follows names the real problem.
+ */
+export function ensureDbDirectory(dbPath) {
+    if (!dbPath || dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
+        return;
+    try {
+        mkdirSync(path.dirname(path.resolve(dbPath)), { recursive: true });
+    }
+    catch {
+        // see above
+    }
+}
+/** Why a test was refused a database inside the state root. */
+export function realDbRefusal(dbPath) {
+    return (`Refusing to open "${dbPath}" from a test.\n` +
+        "That path is inside this generation's state root — the owner's REAL data, not a fixture. " +
+        "A test may delete rows; this one would delete theirs.\n" +
+        `Use ":memory:", or a directory under the state root's ${TEST_SCRATCH_DIR_NAME} (allowed on purpose).`);
+}
+/**
+ * Under a test runner, refuse a database path inside the state root — except under its scratch
+ * tree. A no-op outside tests, for `:memory:`, and where no state root can be found (there is then
+ * no owner data at a known place to protect).
+ */
+export function assertTestSafeDbPath(dbPath, options = {}) {
+    const env = options.env ?? process.env;
+    if (!isTestRuntime(env))
+        return;
+    if (env.SATELLITE_ALLOW_REAL_DATA_DIR_IN_TEST === "1")
+        return;
+    if (dbPath === ":memory:" || dbPath === "")
+        return;
+    const root = stateRootOrNull(env, options.stateRoot);
+    if (!root)
+        return;
+    const resolved = path.resolve(dbPath);
+    const scratch = path.join(root, TEST_SCRATCH_DIR_NAME);
+    if (resolved.startsWith(`${scratch}${path.sep}`))
+        return;
+    if (resolved === root || resolved.startsWith(`${root}${path.sep}`))
+        throw new Error(realDbRefusal(dbPath));
+}
+/**
+ * Read the fields every satellite needs. An app spreads the result into its own config and adds
+ * what is genuinely its own.
+ */
+export function readSatelliteConfig(spec) {
+    const env = spec.env ?? process.env;
+    const app = spec.app;
+    const prefix = spec.envPrefix ?? app.toUpperCase();
+    const v = (suffix) => `${prefix}_${suffix}`;
+    const deployed = isRelease(env);
+    const dataDir = spec.dataDir ?? resolveAppDataDir({ app, env, devDirName: spec.devDirName, stateRoot: spec.stateRoot });
+    const port = readIntEnv(env, "PORT", spec.defaultPort, app);
+    // 🔴 Origin defaults key on `live`, NOT on `deployed`: a production build run without a
+    // release stamp (`preview:prod`, a gate's artifact smoke) would otherwise point its JWKS fetch
+    // and grant redirect at a DEV auth server.
+    const live = deployed || isProductionRuntime(env);
+    const originFallback = spec.publicUrlFallback
+        ? spec.publicUrlFallback({ port, deployed, live })
+        : live
+            ? (spec.publicUrl ?? `https://${app}.cursedalchemy.com`)
+            : (spec.devPublicUrl ?? `http://localhost:${spec.defaultPort}`);
+    const sso = spec.sso ?? true;
+    return {
+        app,
+        port,
+        deployed,
+        live,
+        dataDir,
+        dbPath: env[v("DB_PATH")]?.trim() || path.join(dataDir, spec.dbFile ?? `${app}.sqlite`),
+        sessionsDbPath: path.join(dataDir, "sessions.sqlite"),
+        sessionSecret: env[v("SESSION_SECRET")]?.trim() || devSessionSecret(dataDir, live),
+        sessionTtlSeconds: readIntEnv(env, v("SESSION_TTL_SECONDS"), spec.sessionTtlSeconds, app),
+        publicUrl: readOriginEnv(env, v("PUBLIC_URL"), originFallback),
+        // 🔴 A stage's accounts are the LOCAL ones, and this is FORCED rather than defaulted: it
+        // ignores `<PREFIX>_AUTH_URL`, because an app's deploy secrets are what a stage boots with,
+        // and one stray prod line there would silently un-isolate every stage of that app — test
+        // sign-ins appearing in the owner's real registry, invisible from inside the run.
+        authUrl: !sso
+            ? ""
+            : stageIdentityIsLocal(env)
+                ? LOCAL_AUTH_URL
+                : readOriginEnv(env, v("AUTH_URL"), live ? PROD_AUTH_URL : DEV_AUTH_URL),
+        ssoPublicKeyPem: sso ? env[v("SSO_PUBLIC_KEY_PEM")]?.trim() || "" : "",
+        env,
+        envPrefix: prefix,
+        ownerEmail: (env[v("OWNER_EMAIL")]?.trim() || spec.ownerEmail).toLowerCase(),
+        extraAllowedEmails: (spec.extraEmails ?? true) ? parseEmailList(env[v("EXTRA_ALLOWED_EMAILS")]) : [],
+    };
+}
+/** The file the dev session secret is remembered in, inside the app's data dir. */
+export const DEV_SESSION_SECRET_FILE = "dev-session-secret";
+/**
+ * The session-cookie key when no `<PREFIX>_SESSION_SECRET` is set.
+ *
+ * In DEV it is a FILE, not a per-boot UUID: the session rows are durable, so a per-boot key turns
+ * every restart into "sign-in just shows the button again" (owner report 2026-08-25 — seven good
+ * session rows in 22 seconds, not one usable). When `live` it stays a throwaway, because the
+ * refusal below forbids that boot and writing a key to disk would turn the refusal into a silent
+ * success with a credential nobody chose.
+ */
+export function devSessionSecret(dataDir, live) {
+    if (live)
+        return crypto.randomUUID();
+    const file = path.join(dataDir, DEV_SESSION_SECRET_FILE);
+    try {
+        const existing = readFileSync(file, "utf8").trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // none yet
+    }
+    const minted = crypto.randomUUID();
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(file, `${minted}\n`, "utf8");
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // an unwritable dev dir still boots; it just signs people out on restart
+    }
+    return minted;
+}
+/** The blockers every satellite shares — today exactly one, the session secret. */
+export function satelliteBlockers(config) {
+    const name = `${config.envPrefix}_SESSION_SECRET`;
+    return config.env[name]?.trim() ? [] : [sessionSecretBlocker(name)];
+}
+/**
+ * The binary-server signing key — for every app whose files live there.
+ *
+ * 🔴 The failure it refuses hides better than any other: every list renders, `/healthz` is 200,
+ * and only the file bytes 403 — a broken gallery, not a missing variable. `family` and `roms` had
+ * no such refusal (task 281's census), so a release missing the key booted "healthy".
+ *
+ * @param what What the key fetches, for the sentence — "images and video", "audio", "portraits".
+ */
+export function fileTokenBlocker(config, what, name = "FILE_TOKEN_PRIVATE_KEY") {
+    if (config.env[name]?.trim())
+        return null;
+    return {
+        name,
+        detail: `signs the binary-server tokens that fetch ${what}. Without it every page lists and not one file loads — a failure that looks like a broken app rather than like missing configuration.`,
+    };
+}
+/** Every reason, one line each — what a `/healthz` or a `--check` prints. */
+export function satelliteBlockerLines(config, extra = []) {
+    return [...satelliteBlockers(config), ...extra.filter((b) => b !== null)].map((b) => `${b.name} — ${b.detail}`);
+}
+/**
+ * Refuse a `live` boot that cannot serve safely, naming every reason at once — `cwip/env`'s
+ * `ConfigRefusalError`, exit 78, so a misconfiguration never reads as a crash. A no-op in dev.
+ *
+ * @param stakes What is at risk, as one clause. It is what makes the failure legible at 3am.
+ * @param extra  The app's own blockers; `null` entries (an optional blocker that passed) are skipped.
+ */
+export function assertSatelliteUsable(config, stakes, extra = []) {
+    assertConfigUsable({
+        app: config.app,
+        stakes,
+        blockers: [...satelliteBlockers(config), ...extra.filter((b) => b !== null)],
+        isProduction: config.live,
+    });
+}

package/dist/server/satellite/door.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `cursedbelt-server/satellite-door` — the PURE half of the satellite configuration contract:
+ * who an instance is (a release, a stage, a test runner, a production build) and who it opens
+ * for. No `node:*` import, no `process` read unless one exists, no package — so a Cloudflare
+ * Worker's door imports the SAME rules its Mac twin does.
+ *
+ * ## Why this is here, since 4.19.0 (task 281)
+ *
+ * Nine apps held an `appConfig.ts` in five versions (measured 2026-09-23: `roms`, `family`,
+ * `music`, `collections` and `auth` on one 445-line lineage; `vault` a trimmed fork of it;
+ * `flix`, `station` and `patterns` a second lineage). The divergence was not taste — it was
+ * protection lost in one copy and kept in another: `vault`, `flix` and `station` lost the stage
+ * identity override, so a stage of any of them would have signed in against PRODUCTION auth;
+ * `station` admitted its extra e-mails on its deployed release; lineage B could not tell an
+ * `APP_RELEASE=0` scratch boot from a release. The rules below are the union, decided once.
+ *
+ * And the Workers needed them without the Node half: `music`'s Worker imported the whole
+ * `appConfig.ts` to reach two pure functions, dragging `node:fs` and the data-dir chain into
+ * its bundle, while `collections` split a `doorConstants.ts` out by hand to avoid the same.
+ * This leaf is that split, once. `./satellite-config` is the Bun/Node half and re-exports all
+ * of this, so a Mac-side caller needs one import.
+ *
+ * 🔴 **This file imports NOTHING.** `src/leafSubpathsImportNothing.spec.ts` proves it in a
+ * fixture with no packages resolvable; an import that survives transpilation turns that red.
+ *
+ * 🔴 It knows the fleet's ZONE (`cursedalchemy.com`) and its accounts app's ports, as the
+ * binary-store client already does — mechanism of this fleet, not of any app. It does NOT
+ * know the owner: `ownerEmail` is always passed in.
+ */
+/** Anything with the shape of an environment — `process.env`, a Worker's `env`, a test literal. */
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+/** The accounts app (`apps/auth`) in production. */
+export declare const PROD_AUTH_URL = "https://auth.cursedalchemy.com";
+/** The accounts app's dev shell. */
+export declare const DEV_AUTH_URL = "http://localhost:3309";
+/**
+ * The LOCAL accounts door a stage signs in against — loopback, never the public hostname, so a
+ * stage's test sign-ins never write a row into the owner's real accounts registry.
+ */
+export declare const LOCAL_AUTH_URL = "http://127.0.0.1:3309";
+/** `APP_STAGE_IDENTITY=local` — the marker a stage boots with. */
+export declare const STAGE_IDENTITY_ENV = "APP_STAGE_IDENTITY";
+/** The one directory under the state root that is fixtures by construction. */
+export declare const TEST_SCRATCH_DIR_NAME = "test-scratch.noindex";
+/**
+ * Every marker that means "a test runner is in charge". A spec that spawns a REAL server strips
+ * exactly these ({@link withoutTestRuntimeMarkers}), so a fourth marker added here is stripped by
+ * everyone for free.
+ */
+export declare const TEST_RUNTIME_ENV_KEYS: readonly ["NODE_ENV", "BUN_TEST", "SATELLITE_TEST_RUNTIME"];
+/** Is this instance a stage whose identity must stay LOCAL? */
+export declare function stageIdentityIsLocal(env?: EnvLike): boolean;
+/**
+ * Is this origin an ephemeral STAGE — `<app>-stage.cursedalchemy.com`?
+ *
+ * Derived from the hostname, never configured: a `-stage` name in the fleet's own zone cannot be
+ * typed into existence (only `stage up` creates the record, behind one Access application), so a
+ * production release cannot acquire one by a typo in a secrets file.
+ */
+export declare function isStageOrigin(publicUrl: string): boolean;
+/**
+ * Is a test runner in charge? The three markers, and `SATELLITE_TEST_RUNTIME` because the React
+ * preloads force `NODE_ENV=development` and erase Bun's own `test`.
+ */
+export declare function isTestRuntime(env?: EnvLike): boolean;
+/** A copy of `env` with every test-runtime marker removed — what a spec hands a REAL server it spawns. */
+export declare function withoutTestRuntimeMarkers(env: EnvLike): Record<string, string>;
+/**
+ * IS THIS A RELEASE? One question, one variable.
+ *
+ * `APP_RELEASE` is stamped by the deploy and by nothing else; `0`/`false` is an explicit no (a
+ * stage plan and a floor test both rely on that — lineage B ignored it and could not). Without
+ * the stamp it falls back to `APP_DATA_DIR`, minus the test-scratch tree, because a release
+ * shipped before the stamp existed must still answer yes: flipping it to no would open the smoke
+ * extras on the open internet. The fallback retires itself as each app redeploys.
+ */
+export declare function isRelease(env?: EnvLike): boolean;
+/**
+ * Is this a DEV runtime? Vite's `import.meta.env.DEV` when a bundle carries it, else
+ * `NODE_ENV !== "production"` of the env given (or the ambient one).
+ */
+export declare function isDevRuntime(env?: EnvLike): boolean;
+/** The inverse of {@link isDevRuntime} — what `assertSatelliteUsable`'s refusal keys on with `deployed`. */
+export declare function isProductionRuntime(env?: EnvLike): boolean;
+/** `a@x, ,b@x` → `["a@x", "b@x"]`. The one parse for every `*_EXTRA_ALLOWED_EMAILS`. */
+export declare function parseEmailList(raw: string | undefined): string[];
+/** The slice of a config the door rules read. */
+export interface DoorConfig {
+    /** A release — {@link isRelease}. */
+    deployed: boolean;
+    /** This instance's own origin, when known. A stage is recognised by it. */
+    publicUrl?: string;
+}
+/**
+ * May extra accounts widen the door on THIS instance? Only off a release, or on a stage.
+ *
+ * 🔴 Keyed on `deployed`, not on the origin and not on loopback: a gate's artifact smoke runs the
+ * PRODUCTION build on `127.0.0.1`, so `live` is true there and the origin falls back to the prod
+ * hostname — keying on either would leave the extras inert in the one place they exist to work.
+ * Derived rather than configured: a boolean meaning "let someone else in" is one typo from true
+ * in production.
+ */
+export declare function extraEmailsApply(config: DoorConfig): boolean;
+/**
+ * The addresses this instance opens for, owner first — what an owner-only app hands its SSO
+ * consumer's `allowedEmails`. One function, so the server, `/healthz` and the tests cannot
+ * disagree about the answer.
+ */
+export declare function allowedEmailsFor(config: DoorConfig & {
+    ownerEmail: string;
+    extraAllowedEmails: readonly string[];
+}): string[];

package/dist/server/satellite/door.js

@@ -0,0 +1,149 @@
+/**
+ * `cursedbelt-server/satellite-door` — the PURE half of the satellite configuration contract:
+ * who an instance is (a release, a stage, a test runner, a production build) and who it opens
+ * for. No `node:*` import, no `process` read unless one exists, no package — so a Cloudflare
+ * Worker's door imports the SAME rules its Mac twin does.
+ *
+ * ## Why this is here, since 4.19.0 (task 281)
+ *
+ * Nine apps held an `appConfig.ts` in five versions (measured 2026-09-23: `roms`, `family`,
+ * `music`, `collections` and `auth` on one 445-line lineage; `vault` a trimmed fork of it;
+ * `flix`, `station` and `patterns` a second lineage). The divergence was not taste — it was
+ * protection lost in one copy and kept in another: `vault`, `flix` and `station` lost the stage
+ * identity override, so a stage of any of them would have signed in against PRODUCTION auth;
+ * `station` admitted its extra e-mails on its deployed release; lineage B could not tell an
+ * `APP_RELEASE=0` scratch boot from a release. The rules below are the union, decided once.
+ *
+ * And the Workers needed them without the Node half: `music`'s Worker imported the whole
+ * `appConfig.ts` to reach two pure functions, dragging `node:fs` and the data-dir chain into
+ * its bundle, while `collections` split a `doorConstants.ts` out by hand to avoid the same.
+ * This leaf is that split, once. `./satellite-config` is the Bun/Node half and re-exports all
+ * of this, so a Mac-side caller needs one import.
+ *
+ * 🔴 **This file imports NOTHING.** `src/leafSubpathsImportNothing.spec.ts` proves it in a
+ * fixture with no packages resolvable; an import that survives transpilation turns that red.
+ *
+ * 🔴 It knows the fleet's ZONE (`cursedalchemy.com`) and its accounts app's ports, as the
+ * binary-store client already does — mechanism of this fleet, not of any app. It does NOT
+ * know the owner: `ownerEmail` is always passed in.
+ */
+/** The accounts app (`apps/auth`) in production. */
+export const PROD_AUTH_URL = "https://auth.cursedalchemy.com";
+/** The accounts app's dev shell. */
+export const DEV_AUTH_URL = "http://localhost:3309";
+/**
+ * The LOCAL accounts door a stage signs in against — loopback, never the public hostname, so a
+ * stage's test sign-ins never write a row into the owner's real accounts registry.
+ */
+export const LOCAL_AUTH_URL = "http://127.0.0.1:3309";
+/** `APP_STAGE_IDENTITY=local` — the marker a stage boots with. */
+export const STAGE_IDENTITY_ENV = "APP_STAGE_IDENTITY";
+/** The one directory under the state root that is fixtures by construction. */
+export const TEST_SCRATCH_DIR_NAME = "test-scratch.noindex";
+/**
+ * Every marker that means "a test runner is in charge". A spec that spawns a REAL server strips
+ * exactly these ({@link withoutTestRuntimeMarkers}), so a fourth marker added here is stripped by
+ * everyone for free.
+ */
+export const TEST_RUNTIME_ENV_KEYS = ["NODE_ENV", "BUN_TEST", "SATELLITE_TEST_RUNTIME"];
+/** `process.env` where there is one; `{}` in a Worker, which has none. */
+const ambientEnv = () => globalThis.process?.env ?? {};
+/** Is this instance a stage whose identity must stay LOCAL? */
+export function stageIdentityIsLocal(env = ambientEnv()) {
+    return env[STAGE_IDENTITY_ENV]?.trim().toLowerCase() === "local";
+}
+/**
+ * Is this origin an ephemeral STAGE — `<app>-stage.cursedalchemy.com`?
+ *
+ * Derived from the hostname, never configured: a `-stage` name in the fleet's own zone cannot be
+ * typed into existence (only `stage up` creates the record, behind one Access application), so a
+ * production release cannot acquire one by a typo in a secrets file.
+ */
+export function isStageOrigin(publicUrl) {
+    try {
+        return new URL(publicUrl).hostname.endsWith("-stage.cursedalchemy.com");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is a test runner in charge? The three markers, and `SATELLITE_TEST_RUNTIME` because the React
+ * preloads force `NODE_ENV=development` and erase Bun's own `test`.
+ */
+export function isTestRuntime(env = ambientEnv()) {
+    return env.NODE_ENV === "test" || Boolean(env.BUN_TEST) || env.SATELLITE_TEST_RUNTIME === "1";
+}
+/** A copy of `env` with every test-runtime marker removed — what a spec hands a REAL server it spawns. */
+export function withoutTestRuntimeMarkers(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (TEST_RUNTIME_ENV_KEYS.includes(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * IS THIS A RELEASE? One question, one variable.
+ *
+ * `APP_RELEASE` is stamped by the deploy and by nothing else; `0`/`false` is an explicit no (a
+ * stage plan and a floor test both rely on that — lineage B ignored it and could not). Without
+ * the stamp it falls back to `APP_DATA_DIR`, minus the test-scratch tree, because a release
+ * shipped before the stamp existed must still answer yes: flipping it to no would open the smoke
+ * extras on the open internet. The fallback retires itself as each app redeploys.
+ */
+export function isRelease(env = ambientEnv()) {
+    const explicit = env.APP_RELEASE?.trim();
+    if (explicit)
+        return explicit !== "0" && explicit.toLowerCase() !== "false";
+    const appDataDir = env.APP_DATA_DIR?.trim() ?? "";
+    return Boolean(appDataDir) && !appDataDir.includes(TEST_SCRATCH_DIR_NAME);
+}
+/**
+ * Is this a DEV runtime? Vite's `import.meta.env.DEV` when a bundle carries it, else
+ * `NODE_ENV !== "production"` of the env given (or the ambient one).
+ */
+export function isDevRuntime(env) {
+    if (env === undefined) {
+        const viteDev = import.meta.env?.DEV;
+        if (typeof viteDev === "boolean")
+            return viteDev;
+    }
+    return (env ?? ambientEnv()).NODE_ENV !== "production";
+}
+/** The inverse of {@link isDevRuntime} — what `assertSatelliteUsable`'s refusal keys on with `deployed`. */
+export function isProductionRuntime(env) {
+    return !isDevRuntime(env);
+}
+/** `a@x, ,b@x` → `["a@x", "b@x"]`. The one parse for every `*_EXTRA_ALLOWED_EMAILS`. */
+export function parseEmailList(raw) {
+    return (raw ?? "")
+        .split(",")
+        .map((email) => email.trim())
+        .filter((email) => email.length > 0);
+}
+/**
+ * May extra accounts widen the door on THIS instance? Only off a release, or on a stage.
+ *
+ * 🔴 Keyed on `deployed`, not on the origin and not on loopback: a gate's artifact smoke runs the
+ * PRODUCTION build on `127.0.0.1`, so `live` is true there and the origin falls back to the prod
+ * hostname — keying on either would leave the extras inert in the one place they exist to work.
+ * Derived rather than configured: a boolean meaning "let someone else in" is one typo from true
+ * in production.
+ */
+export function extraEmailsApply(config) {
+    if (!config.deployed)
+        return true;
+    return isStageOrigin(config.publicUrl ?? "");
+}
+/**
+ * The addresses this instance opens for, owner first — what an owner-only app hands its SSO
+ * consumer's `allowedEmails`. One function, so the server, `/healthz` and the tests cannot
+ * disagree about the answer.
+ */
+export function allowedEmailsFor(config) {
+    return extraEmailsApply(config) ? [config.ownerEmail, ...config.extraAllowedEmails] : [config.ownerEmail];
+}

package/dist/server/storage/binaryStore.d.ts

@@ -322,6 +322,24 @@ export declare const DELETE_TOKEN_TTL_SECONDS = 120;
 /** register-app prints the key as base64(PKCS8 PEM); env files sometimes carry
  *  raw PEM or PEM with literal `\n` sequences. Accept all three. */
 export declare function normalizePrivateKeyPem(raw: string): string;
+/**
+ * A short, stable, PUBLIC identifier for a tenant's signing key — the first 16 hex of sha256
+ * over the public half's SPKI DER. `""` for an unset key, `"unreadable"` for one that does not
+ * parse; never throws.
+ *
+ * 🔴 Why it exists. A wrong or stale `FILE_TOKEN_PRIVATE_KEY` is the failure that hides best:
+ * every list renders, `/healthz` is 200, and only the file bytes 403 — and the assertion that
+ * would catch it ("a file URL serves bytes") needs a signed-in session a deploy smoke does not
+ * have. So an instance publishes this digest on `/healthz` and the smoke derives the same digest
+ * from the key the deploying machine holds; the two are compared with no session anywhere.
+ *
+ * Safe to publish: a truncated hash of the PUBLIC half, which binary-server's tenant registry
+ * already holds. It was `fileTokenKeyId` in four apps' `src/server/config.ts` (music first, then
+ * family, roms and collections), byte-identical, until 4.19.0 (task 321). Lives here because it
+ * is `node:crypto` over the same key {@link createBinaryStore} signs with — and so it runs in a
+ * Worker under `nodejs_compat` exactly as the store does.
+ */
+export declare function fileTokenKeyId(privateKeyPem: string): string;
 export declare function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore;
 /**
  * Which binary-server TENANT this process is — the app's own key, unless the environment

package/dist/server/storage/binaryStore.js

@@ -40,7 +40,7 @@
  * import specifier (`cursedbelt/server/storage`, the pre-split package name) — no
  * behavioural difference in any of the three, so nothing was dropped to land the union.
  */
-import { createPrivateKey, sign as cryptoSign } from 'node:crypto';
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign } from 'node:crypto';
 /*
  * ── The process-wide repeat register (§ the repeat-key counter) ───────────────
  *
@@ -196,6 +196,37 @@ export function normalizePrivateKeyPem(raw) {
     }
     return decoded;
 }
+/**
+ * A short, stable, PUBLIC identifier for a tenant's signing key — the first 16 hex of sha256
+ * over the public half's SPKI DER. `""` for an unset key, `"unreadable"` for one that does not
+ * parse; never throws.
+ *
+ * 🔴 Why it exists. A wrong or stale `FILE_TOKEN_PRIVATE_KEY` is the failure that hides best:
+ * every list renders, `/healthz` is 200, and only the file bytes 403 — and the assertion that
+ * would catch it ("a file URL serves bytes") needs a signed-in session a deploy smoke does not
+ * have. So an instance publishes this digest on `/healthz` and the smoke derives the same digest
+ * from the key the deploying machine holds; the two are compared with no session anywhere.
+ *
+ * Safe to publish: a truncated hash of the PUBLIC half, which binary-server's tenant registry
+ * already holds. It was `fileTokenKeyId` in four apps' `src/server/config.ts` (music first, then
+ * family, roms and collections), byte-identical, until 4.19.0 (task 321). Lives here because it
+ * is `node:crypto` over the same key {@link createBinaryStore} signs with — and so it runs in a
+ * Worker under `nodejs_compat` exactly as the store does.
+ */
+export function fileTokenKeyId(privateKeyPem) {
+    if (!privateKeyPem.trim())
+        return '';
+    try {
+        const spki = createPublicKey(createPrivateKey(normalizePrivateKeyPem(privateKeyPem))).export({
+            type: 'spki',
+            format: 'der',
+        });
+        return createHash('sha256').update(spki).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'unreadable';
+    }
+}
 const base64url = (bytes) => Buffer.from(bytes).toString('base64url');
 /** Keys may contain `/` as a real separator; each SEGMENT is percent-encoded
  *  because the server decodes the whole path before matching it to the token. */