cursedbelt-server 4.18.0 → 4.19.0

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

@@ -0,0 +1,173 @@
+import { type ConfigBlocker } from "cwip/env";
+import { type EnvLike } from "./door.js";
+export * from "./door.js";
+export type { ConfigBlocker } from "cwip/env";
+export { formatConfigBlockers, isConfigRefusal, sessionSecretBlocker } from "cwip/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 declare function stateRoot(options?: {
+    env?: EnvLike;
+    stateRoot?: string;
+}): string;
+/** The scratch tree tests may write under — the one carve-out {@link assertTestSafeDbPath} allows. */
+export declare function testScratchRoot(options?: {
+    env?: EnvLike;
+    stateRoot?: string;
+}): string;
+/** A deployed app's data directory: `<state root>/apps/<app>`. */
+export declare function deployedDataDirFor(app: string, options?: {
+    env?: EnvLike;
+    stateRoot?: string;
+}): string;
+/** Why a test was refused a real data directory. */
+export declare function realDataDirRefusal(app: string): string;
+export interface ResolveAppDataDirOptions {
+    /** The app key — `vault`, `roms`, … Names the directory. */
+    app: string;
+    env?: EnvLike;
+    /**
+     * The dev shell's directory name, when it should differ from `app`. Defaults to `app`:
+     * RENAMING a dev directory makes that shell boot EMPTY, which reads exactly like data loss.
+     * Opt in per app with a reason (`vault` passes `vault-dev`).
+     */
+    devDirName?: string;
+    /** Tests of this module: the state root to resolve under. */
+    stateRoot?: string;
+}
+/**
+ * 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 declare function resolveAppDataDir(options: ResolveAppDataDirOptions): string;
+/**
+ * `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 declare function ensureDbDirectory(dbPath: string): void;
+/** Why a test was refused a database inside the state root. */
+export declare function realDbRefusal(dbPath: string): string;
+/**
+ * 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 declare function assertTestSafeDbPath(dbPath: string, options?: {
+    env?: EnvLike;
+    stateRoot?: string;
+}): void;
+export interface SatelliteConfigSpec {
+    /** App key — `roms`. Prefixes errors, names the data dir and the `<PREFIX>_` vars. */
+    app: string;
+    /** `PORT`'s fallback. */
+    defaultPort: number;
+    /** Session lifetime fallback, seconds. */
+    sessionTtlSeconds: number;
+    /**
+     * The ONE person an owner-only app opens for, unless `<PREFIX>_OWNER_EMAIL` says otherwise.
+     * Required: this library is published and does not know the owner.
+     */
+    ownerEmail: string;
+    /** Env-var prefix. Defaults to the app key upper-cased. */
+    envPrefix?: string;
+    /** The sqlite file inside the data dir. Defaults to `<app>.sqlite`. */
+    dbFile?: string;
+    /** This app's production origin. Defaults to `https://<app>.cursedalchemy.com`. */
+    publicUrl?: string;
+    /** This app's dev origin — the vite port, which is NOT `defaultPort`. */
+    devPublicUrl?: string;
+    /**
+     * Compute the origin fallback yourself when the prod/dev pair is not the whole story
+     * (`vault`: a loopback release is `deployed` and its origin is `127.0.0.1`, not the prod
+     * hostname). `<PREFIX>_PUBLIC_URL` still wins.
+     */
+    publicUrlFallback?: (ctx: {
+        port: number;
+        deployed: boolean;
+        live: boolean;
+    }) => string;
+    /** The dev shell's data-dir name — see {@link ResolveAppDataDirOptions.devDirName}. */
+    devDirName?: string;
+    /** Take this data dir instead of resolving one — the escape hatch, not the road. */
+    dataDir?: string;
+    /** Whether the app signs in through the accounts app. Default `true`; `patterns` has its own password. */
+    sso?: boolean;
+    /**
+     * Whether `<PREFIX>_EXTRA_ALLOWED_EMAILS` is read at all. Default `true`. An app that must only
+     * ever open for its owner (`vault`) passes `false`, and the list is always `[]`.
+     */
+    extraEmails?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Tests: the state root to resolve under. */
+    stateRoot?: string;
+}
+/** The fields every satellite's config carried, under the names they all used. */
+export interface SatelliteConfig {
+    app: string;
+    port: number;
+    /** A release — see `isRelease`. */
+    deployed: boolean;
+    /** A release OR a production build — what origin defaults and the refusal key on. */
+    live: boolean;
+    dataDir: string;
+    dbPath: string;
+    /** Sessions get their own file, so the credential surface is not a table in the app database. */
+    sessionsDbPath: string;
+    /** A remembered per-dev-tree secret in dev; production REQUIRES a stable one (a blocker). */
+    sessionSecret: string;
+    sessionTtlSeconds: number;
+    /** THIS app's absolute origin — where SSO grants may be redirected. */
+    publicUrl: string;
+    /** The accounts app's origin; `""` when `sso: false`. */
+    authUrl: string;
+    /** Static SSO verification key (SPKI PEM); `""` when unset or `sso: false`. */
+    ssoPublicKeyPem: string;
+    env: NodeJS.ProcessEnv;
+    /** `<PREFIX>` — so an app names its extra vars without repeating it. */
+    envPrefix: string;
+    ownerEmail: string;
+    /** Admitted in addition to the owner — only where `extraEmailsApply` says so. */
+    extraAllowedEmails: string[];
+}
+/**
+ * Read the fields every satellite needs. An app spreads the result into its own config and adds
+ * what is genuinely its own.
+ */
+export declare function readSatelliteConfig(spec: SatelliteConfigSpec): SatelliteConfig;
+/** The file the dev session secret is remembered in, inside the app's data dir. */
+export declare 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 declare function devSessionSecret(dataDir: string, live: boolean): string;
+/** The blockers every satellite shares — today exactly one, the session secret. */
+export declare function satelliteBlockers(config: Pick<SatelliteConfig, "env" | "envPrefix">): ConfigBlocker[];
+/**
+ * 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 declare function fileTokenBlocker(config: Pick<SatelliteConfig, "env">, what: string, name?: string): ConfigBlocker | null;
+/** Every reason, one line each — what a `/healthz` or a `--check` prints. */
+export declare function satelliteBlockerLines(config: Pick<SatelliteConfig, "env" | "envPrefix">, extra?: readonly (ConfigBlocker | null)[]): string[];
+/**
+ * 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 declare function assertSatelliteUsable(config: Pick<SatelliteConfig, "app" | "env" | "envPrefix" | "live">, stakes: string, extra?: readonly (ConfigBlocker | null)[]): void;

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[];