cursedbelt-server 4.18.1 → 4.19.0

package/dist/server/maps-budget/mapsBudget.d.ts

@@ -0,0 +1,194 @@
+/**
+ * A HARD, persisted call ceiling for Google Maps Platform — monthly AND daily.
+ *
+ * ── Why this is a package and not a helper in one app ───────────────────────
+ * Two apps had their own copy of it — `apps/orch` (leave-by times) and
+ * `apps/family` (the atlas) — and two consumers is exactly the threshold the
+ * placement law names. The reason to promote rather than to leave them is
+ * sharper than tidiness: **the guarantee is that the ceiling and the network
+ * call cannot be separated**, and a rule living in two files that can drift is a
+ * guarantee with two chances to stop being one. A THIRD copy was the real risk.
+ *
+ * ── 🔴 `cursedbelt-server/maps-budget`, since 4.19.0 (task 345) ──────────────
+ * It was copied again in THIS generation, under two file names —
+ * `apps/family/src/kit/mapsBudget.ts` and `apps/station/src/kit/mapsPlatform.ts`,
+ * 13,408 identical bytes that no basename census could see. It lives here now,
+ * with its suite, as a leaf that imports nothing: an app injects its own
+ * {@link MapsBudgetStore}, so neither app can reach the other's ledger, and the
+ * generic `Api` parameter lets each name its own API set without a shared enum.
+ * It is in the SERVER tier rather than `cursedbelt-core` because a spend ceiling
+ * only means anything where the key is — never in a browser bundle.
+ *
+ * ── The owner's constraint, verbatim (2026-08-08) ───────────────────────────
+ * *"Note I don't want to allow spending with the apis so we have to enforce the
+ * limits for the free tiers if applicable."*
+ *
+ * Maps Platform is unlike the free Google APIs in three ways that together make
+ * a client-side ceiling the only real protection:
+ *
+ *   1. It REQUIRES a billing account. A runaway loop on Gmail or Calendar costs
+ *      nothing; here it bills.
+ *   2. The free allowance is 10,000 events/month per Essentials API. Past that,
+ *      calls cost money rather than failing.
+ *   3. 🔴 **A Cloud BUDGET DOES NOT CAP USAGE — it only alerts.** The only
+ *      server-side hard stop is a per-API QUOTA in Cloud Console, and that step
+ *      is the owner's. This is ours.
+ *
+ * ── 🔴 TWO periods, because a month is not a shape a runaway respects ───────
+ * A monthly cap can be burned inside a single day. A loop that starts on the
+ * 2nd spends the whole allowance by the 3rd and leaves the API dead for the
+ * other 29 — which is the outcome the ceiling exists to PREVENT, arriving by
+ * way of the ceiling itself. So every call is measured against both:
+ *
+ *   · the **month**, which protects the free tier and therefore the bill;
+ *   · the **day**, `dailyCeiling()` of the month's, which catches the loop in
+ *     hours rather than in a billing period.
+ *
+ * The daily number is DERIVED from the monthly one and never written down
+ * twice. Two tables drift, and this module exists because two copies of this
+ * rule already did.
+ *
+ * Both have to pass, and a refusal by either counts nothing. Expected real
+ * volume across ALL APIs is a few dozen calls a day — about 1% of the free
+ * allowance — so a tenth of the month still leaves roughly 10× headroom on the
+ * busiest single API. A ceiling being hit still means something is broken.
+ *
+ * ── Two properties that are not negotiable ─────────────────────────────────
+ * **PERSISTED, never in memory** — BOTH counters. An in-memory counter resets
+ * on every restart, and a crash-loop restarting hourly would reset it hourly —
+ * turning the one safeguard into a formality precisely when something is wrong.
+ * A daily counter is the one a restart-loop would defeat most cheaply, so it is
+ * persisted the same way. Each key embeds its own period, so a new month or a
+ * new day starts at zero with no scheduled reset to fail and no "the machine was
+ * off on the 1st" hole.
+ *
+ * **A corrupted counter fails SAFE**, treated as exhausted rather than as zero —
+ * the daily one exactly as the monthly one, deliberately. The wrong direction
+ * here spends the owner's money, and two fail-safes with different opinions in
+ * one module would be worse than either choice.
+ *
+ * ── What is deliberately NOT here ──────────────────────────────────────────
+ * The typed API callers. `apps/family` talks to eight Maps APIs plus Street
+ * View; `apps/orch` talks to Routes and Weather. They share no call site, only
+ * this rule — and hoisting nine wrappers into a package to give two apps one
+ * counter would be the shared-code version of the same mistake this package
+ * exists to fix. Each app keeps its own ONE DOOR (`maps.ts` in family, pinned by
+ * a test that scans for Google hosts outside it) and both doors consume this.
+ */
+/** Where the counter lives. A tiny KV, so an app can back it with whatever
+ *  durable store it already has — `apps/orch` uses its own settings store,
+ *  `apps/family` uses the `meta` table of the database it already opens. */
+export interface MapsBudgetStore {
+    read: (key: string) => string | null;
+    write: (key: string, value: string) => void;
+}
+/** The two periods a call is measured against. They answer different questions:
+ *  a month says whether the free tier is safe, a day says whether something is
+ *  looping right now — and they come back at different times, which is the
+ *  reason an app is told WHICH one refused. */
+export type BudgetPeriod = "month" | "day";
+export type BudgetVerdict = 
+/** Counted against BOTH periods. The caller may make exactly the request it
+ *  asked for. `used`/`ceiling` are the MONTH's — the figure a health surface
+ *  has always shown; `usage()` reports the day beside it. */
+{
+    allowed: true;
+    used: number;
+    ceiling: number;
+}
+/**
+ * 🔴 Refused. The caller must DEGRADE LOUDLY — never skip silently, and never
+ * make the call anyway. `reason` is viewer-facing; `fix` is for whoever has to
+ * do something about it, and is empty when the app has nothing to add.
+ *
+ * `used`, `ceiling`, `scope` and `period` all describe the ONE period that
+ * refused, so a caller can say when the API comes back without re-deriving it.
+ */
+ | {
+    allowed: false;
+    used: number;
+    ceiling: number;
+    scope: BudgetPeriod;
+    period: string;
+    reason: string;
+    fix: string;
+};
+/** What an app is told when it must explain a refusal. */
+export interface RefusalContext<Api extends string> {
+    api: Api;
+    /** Calls already spent in the period that refused, or that period's ceiling
+     *  when the counter is unreadable — never `Infinity`, so it is always
+     *  printable. */
+    used: number;
+    /** The ceiling of the period that refused — the MONTH's ceiling for a monthly
+     *  refusal, a tenth of it for a daily one. */
+    ceiling: number;
+    /** Which ceiling refused. 🔴 An app that words both cases the same is telling
+     *  a viewer the map is off for a month when it is off until midnight. */
+    scope: BudgetPeriod;
+    /** The period that refused: `YYYY-MM` for a month, `YYYY-MM-DD` for a day. */
+    period: string;
+    /** True when the counter could not be read and was failed safe. The wording
+     *  for that case is genuinely different: nothing was necessarily spent. */
+    corrupted: boolean;
+}
+export interface MapsBudget<Api extends string> {
+    /**
+     * Check AND count in one step, immediately before the request.
+     *
+     * 🔴 The order is the whole point: counting after the call would count
+     * correctly and protect nothing. `calls` is for a BATCH endpoint (family's
+     * elevation lookup sends 100 points in one request) and a batch that would
+     * cross EITHER line is refused whole rather than truncated — half an answer
+     * drawn as a complete one is worse than a labeled absence.
+     */
+    consume(api: Api, calls?: number): BudgetVerdict;
+    /** Read-only, for a health surface. Both periods, because the one that will
+     *  actually refuse the next call is usually the day, and a surface showing
+     *  only "12 of 3000" would read as healthy while the API is off until
+     *  midnight. */
+    usage(api: Api): {
+        api: Api;
+        used: number;
+        ceiling: number;
+        period: string;
+        day: {
+            used: number;
+            ceiling: number;
+            period: string;
+        };
+    };
+}
+/** `YYYY-MM` in local time — the period a monthly allowance is measured over. */
+export declare const monthKey: (at: number) => string;
+/** `YYYY-MM-DD` in local time — the period the daily sub-ceiling is measured
+ *  over. Local, like `monthKey`, so "today" means the owner's today. */
+export declare const dayKey: (at: number) => string;
+/** How much of a month's allowance one day may take. A tenth: expected use is a
+ *  few dozen calls a day against ceilings sized ~100× that, so a tenth still
+ *  leaves roughly 10× headroom on the busiest API while stopping a runaway in
+ *  hours instead of in a billing period. */
+export declare const DAILY_SHARE_OF_MONTH = 10;
+/**
+ * The daily sub-ceiling, DERIVED — never a second table.
+ *
+ * Rounded UP, so a ceiling of 1 stays reachable (a tenth of it rounded down
+ * would be zero, i.e. an API switched off by arithmetic) and every API keeps at
+ * least one call a day.
+ */
+export declare const dailyCeiling: (monthlyCeiling: number) => number;
+export interface MapsBudgetOptions<Api extends string> {
+    store: MapsBudgetStore;
+    /** The ceiling per API. Every API the app may call must appear, so adding one
+     *  is a deliberate act — a new line in the owner's bill and a new row here. */
+    ceilings: Record<Api, number>;
+    /** How this app words a refusal. Supplied by the app rather than templated
+     *  here because the audience differs: family's reaches a relative looking at a
+     *  map, orch's reaches the owner's notification bell. */
+    refusal: (context: RefusalContext<Api>) => {
+        reason: string;
+        fix?: string;
+    };
+    now?: () => number;
+}
+export declare function createMapsBudget<Api extends string>(options: MapsBudgetOptions<Api>): MapsBudget<Api>;

package/dist/server/maps-budget/mapsBudget.js

@@ -0,0 +1,193 @@
+/**
+ * A HARD, persisted call ceiling for Google Maps Platform — monthly AND daily.
+ *
+ * ── Why this is a package and not a helper in one app ───────────────────────
+ * Two apps had their own copy of it — `apps/orch` (leave-by times) and
+ * `apps/family` (the atlas) — and two consumers is exactly the threshold the
+ * placement law names. The reason to promote rather than to leave them is
+ * sharper than tidiness: **the guarantee is that the ceiling and the network
+ * call cannot be separated**, and a rule living in two files that can drift is a
+ * guarantee with two chances to stop being one. A THIRD copy was the real risk.
+ *
+ * ── 🔴 `cursedbelt-server/maps-budget`, since 4.19.0 (task 345) ──────────────
+ * It was copied again in THIS generation, under two file names —
+ * `apps/family/src/kit/mapsBudget.ts` and `apps/station/src/kit/mapsPlatform.ts`,
+ * 13,408 identical bytes that no basename census could see. It lives here now,
+ * with its suite, as a leaf that imports nothing: an app injects its own
+ * {@link MapsBudgetStore}, so neither app can reach the other's ledger, and the
+ * generic `Api` parameter lets each name its own API set without a shared enum.
+ * It is in the SERVER tier rather than `cursedbelt-core` because a spend ceiling
+ * only means anything where the key is — never in a browser bundle.
+ *
+ * ── The owner's constraint, verbatim (2026-08-08) ───────────────────────────
+ * *"Note I don't want to allow spending with the apis so we have to enforce the
+ * limits for the free tiers if applicable."*
+ *
+ * Maps Platform is unlike the free Google APIs in three ways that together make
+ * a client-side ceiling the only real protection:
+ *
+ *   1. It REQUIRES a billing account. A runaway loop on Gmail or Calendar costs
+ *      nothing; here it bills.
+ *   2. The free allowance is 10,000 events/month per Essentials API. Past that,
+ *      calls cost money rather than failing.
+ *   3. 🔴 **A Cloud BUDGET DOES NOT CAP USAGE — it only alerts.** The only
+ *      server-side hard stop is a per-API QUOTA in Cloud Console, and that step
+ *      is the owner's. This is ours.
+ *
+ * ── 🔴 TWO periods, because a month is not a shape a runaway respects ───────
+ * A monthly cap can be burned inside a single day. A loop that starts on the
+ * 2nd spends the whole allowance by the 3rd and leaves the API dead for the
+ * other 29 — which is the outcome the ceiling exists to PREVENT, arriving by
+ * way of the ceiling itself. So every call is measured against both:
+ *
+ *   · the **month**, which protects the free tier and therefore the bill;
+ *   · the **day**, `dailyCeiling()` of the month's, which catches the loop in
+ *     hours rather than in a billing period.
+ *
+ * The daily number is DERIVED from the monthly one and never written down
+ * twice. Two tables drift, and this module exists because two copies of this
+ * rule already did.
+ *
+ * Both have to pass, and a refusal by either counts nothing. Expected real
+ * volume across ALL APIs is a few dozen calls a day — about 1% of the free
+ * allowance — so a tenth of the month still leaves roughly 10× headroom on the
+ * busiest single API. A ceiling being hit still means something is broken.
+ *
+ * ── Two properties that are not negotiable ─────────────────────────────────
+ * **PERSISTED, never in memory** — BOTH counters. An in-memory counter resets
+ * on every restart, and a crash-loop restarting hourly would reset it hourly —
+ * turning the one safeguard into a formality precisely when something is wrong.
+ * A daily counter is the one a restart-loop would defeat most cheaply, so it is
+ * persisted the same way. Each key embeds its own period, so a new month or a
+ * new day starts at zero with no scheduled reset to fail and no "the machine was
+ * off on the 1st" hole.
+ *
+ * **A corrupted counter fails SAFE**, treated as exhausted rather than as zero —
+ * the daily one exactly as the monthly one, deliberately. The wrong direction
+ * here spends the owner's money, and two fail-safes with different opinions in
+ * one module would be worse than either choice.
+ *
+ * ── What is deliberately NOT here ──────────────────────────────────────────
+ * The typed API callers. `apps/family` talks to eight Maps APIs plus Street
+ * View; `apps/orch` talks to Routes and Weather. They share no call site, only
+ * this rule — and hoisting nine wrappers into a package to give two apps one
+ * counter would be the shared-code version of the same mistake this package
+ * exists to fix. Each app keeps its own ONE DOOR (`maps.ts` in family, pinned by
+ * a test that scans for Google hosts outside it) and both doors consume this.
+ */
+/** `YYYY-MM` in local time — the period a monthly allowance is measured over. */
+export const monthKey = (at) => {
+    const d = new Date(at);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+};
+/** `YYYY-MM-DD` in local time — the period the daily sub-ceiling is measured
+ *  over. Local, like `monthKey`, so "today" means the owner's today. */
+export const dayKey = (at) => {
+    const d = new Date(at);
+    return `${monthKey(at)}-${String(d.getDate()).padStart(2, "0")}`;
+};
+/** How much of a month's allowance one day may take. A tenth: expected use is a
+ *  few dozen calls a day against ceilings sized ~100× that, so a tenth still
+ *  leaves roughly 10× headroom on the busiest API while stopping a runaway in
+ *  hours instead of in a billing period. */
+export const DAILY_SHARE_OF_MONTH = 10;
+/**
+ * The daily sub-ceiling, DERIVED — never a second table.
+ *
+ * Rounded UP, so a ceiling of 1 stays reachable (a tenth of it rounded down
+ * would be zero, i.e. an API switched off by arithmetic) and every API keeps at
+ * least one call a day.
+ */
+export const dailyCeiling = (monthlyCeiling) => Math.ceil(monthlyCeiling / DAILY_SHARE_OF_MONTH);
+export function createMapsBudget(options) {
+    const now = options.now ?? Date.now;
+    /**
+     * 🔴 The monthly key is UNCHANGED (`maps-budget.<api>.2026-09`) — live stores
+     * hold counts under it. The daily one is the same shape with the day on the
+     * end (`…2026-09-11`), so the two can never collide and no migration is
+     * needed: the first call of a new day simply starts a new counter at zero.
+     *
+     * The store is read/write only — deliberately, so an app can back it with any
+     * KV it already has — which means nothing prunes yesterday's keys. That is
+     * a few hundred bytes per API per year, and cheaper than an interface that
+     * can delete rows in the owner's database.
+     */
+    const key = (api, period) => `maps-budget.${api}.${period}`;
+    const readCount = (api, period) => {
+        const raw = Number(options.store.read(key(api, period)) ?? 0);
+        // 🔴 Fails SAFE — see the header. Exhausted, never zero. The daily counter
+        // takes the same reading for the same reason; two fail-safes with different
+        // opinions would be worse than either.
+        return Number.isFinite(raw) && raw >= 0 ? raw : Number.POSITIVE_INFINITY;
+    };
+    /** Both lines for `api` at this instant — the month, then the day. */
+    const linesFor = (api, at) => {
+        const monthly = options.ceilings[api];
+        return [
+            { scope: "month", period: monthKey(at), ceiling: monthly },
+            { scope: "day", period: dayKey(at), ceiling: dailyCeiling(monthly) },
+        ];
+    };
+    return {
+        consume(api, calls = 1) {
+            const at = now();
+            const [month, day] = linesFor(api, at);
+            const monthUsed = readCount(api, month.period);
+            const dayUsed = readCount(api, day.period);
+            /**
+             * 🔴 The MONTH is tested first, and the order is not cosmetic: it decides
+             * what a viewer is told when both are spent, and only one answer is true
+             * then. "Off until midnight" is a promise the budget cannot keep once the
+             * month is gone; "off until the month ends" is right in both cases.
+             */
+            const refused = monthUsed + calls > month.ceiling
+                ? { line: month, used: monthUsed }
+                : dayUsed + calls > day.ceiling
+                    ? { line: day, used: dayUsed }
+                    : null;
+            if (refused) {
+                const corrupted = !Number.isFinite(refused.used);
+                const used = corrupted ? refused.line.ceiling : refused.used;
+                const spoken = options.refusal({
+                    api,
+                    used,
+                    ceiling: refused.line.ceiling,
+                    scope: refused.line.scope,
+                    period: refused.line.period,
+                    corrupted,
+                });
+                return {
+                    allowed: false,
+                    used,
+                    ceiling: refused.line.ceiling,
+                    scope: refused.line.scope,
+                    period: refused.line.period,
+                    reason: spoken.reason,
+                    fix: spoken.fix ?? "",
+                };
+            }
+            // Both fit, so both are counted. A refusal above wrote nothing at all —
+            // a call that did not happen must not be charged to either period.
+            options.store.write(key(api, month.period), String(monthUsed + calls));
+            options.store.write(key(api, day.period), String(dayUsed + calls));
+            return { allowed: true, used: monthUsed + calls, ceiling: month.ceiling };
+        },
+        usage(api) {
+            const [month, day] = linesFor(api, now());
+            // A corrupted counter reports its ceiling rather than `Infinity`, so a
+            // health surface prints a number and reads as exhausted — which is how
+            // `consume` is about to treat it.
+            const spent = (line) => {
+                const used = readCount(api, line.period);
+                return Number.isFinite(used) ? used : line.ceiling;
+            };
+            return {
+                api,
+                used: spent(month),
+                ceiling: month.ceiling,
+                period: month.period,
+                day: { used: spent(day), ceiling: day.ceiling, period: day.period },
+            };
+        },
+    };
+}

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;