cursedbelt-server 4.0.0 → 4.2.0

package/dist/server/middleware/bodyLimit.js

@@ -0,0 +1,161 @@
+/**
+ * Reading a request body without first agreeing how big it may be.
+ *
+ * ── Why this is one function rather than one per app (2026-07-27) ────────────
+ * The two apps behind the shared owner-auth were inconsistently hardened, in a
+ * way an adversarial review found and neither test suite could:
+ *
+ * - the companion app (since folded into `apps/orch`) read `c.req.text()`,
+ *   checked the length, and returned 413 BEFORE parsing — correct.
+ * - `apps/roms` called `await c.req.json()` first and checked the size deep
+ *   inside the save-state store — i.e. it buffered and parsed an arbitrary body
+ *   into a process whose unit caps at 300 MB of memory before forming an
+ *   opinion about its size.
+ *
+ * Both went through {@link readBoundedJson} after that. The guard is one
+ * function so the posture cannot diverge again, and it is deliberately the
+ * *last* line of defense: a proxy's `client_max_body_size` refuses an oversized
+ * body at the edge, and this refuses it if the proxy is absent, misconfigured,
+ * or bypassed — which is exactly the case in dev, in `preview:prod`, and for any
+ * request that reaches the loopback port directly.
+ *
+ * ── Where it came from (2026-09-17) ──────────────────────────────────────────
+ * Five apps — `roms`, `family`, `music`, `vault`, `collections` — carried this
+ * file byte-for-byte identical (`b36d0eedee7a`), which is the posture diverging
+ * again, only more slowly and with nothing watching: a repo's gate proves that
+ * repo, so five green gates is what five copies of a security guard look like
+ * from the outside. Confirmed identical with `shasum -a256` before the move, so
+ * there was no fork to reconcile and nothing was dropped.
+ *
+ * 🔴 It is published as the LEAF subpath `cursedbelt-server/body-limit`, never
+ * through the `./middleware` barrel — that barrel drags `hono` and the error
+ * envelope, and this module's whole promise is that it imports NOTHING. The
+ * source is a `{ req: { text() } }` / `{ req: { arrayBuffer() } }` /
+ * `{ req: { header() } }` structural type rather than a Hono context, so a
+ * caller needs no framework to use it and a test needs none to exercise it.
+ * `src/leafSubpathsImportNothing.spec.ts` is what holds that promise.
+ */
+/**
+ * Read a body as TEXT, refusing anything over `maxBytes`.
+ *
+ * The sibling of {@link readBoundedJson}, for a payload that IS the text rather
+ * than a document containing it — `apps/patterns`' chunked sends put their
+ * metadata in the query string and the chunk in the raw body, which spares a
+ * megabyte-scale caller from JSON-escaping every piece and spares this process
+ * from parsing what it is only going to concatenate.
+ *
+ * Same byte-not-character measurement, and for the same reason: it is the number
+ * the proxy in front of this is enforcing.
+ */
+export async function readBoundedText(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let raw;
+    try {
+        raw = await c.req.text();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    const bytes = new TextEncoder().encode(raw).length;
+    if (bytes > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Read a body as RAW BYTES, refusing anything over `maxBytes`.
+ *
+ * The third member of the family, for a payload that is neither JSON nor text:
+ * roms' ROM-upload chunks are cartridge bytes, and routing them through
+ * {@link readBoundedText} would decode arbitrary binary as UTF-8 — which is
+ * lossy (every invalid sequence becomes U+FFFD) and measures a size that is not
+ * the size the proxy in front is enforcing.
+ *
+ * A `Content-Length` claim is deliberately NOT trusted here: it is a header, and
+ * the guard has to hold against a body that disagrees with it. The measurement is
+ * the buffer that actually arrived.
+ */
+export async function readBoundedBytes(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let buffer;
+    try {
+        buffer = await c.req.arrayBuffer();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    if (buffer.byteLength > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${buffer.byteLength} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    return { ok: true, value: new Uint8Array(buffer) };
+}
+/**
+ * Refuse a body by its DECLARED `Content-Length`, without reading it.
+ *
+ * The fourth member of the family, and the only one for a body that cannot be
+ * buffered first: a `multipart/form-data` upload. The other three measure the
+ * bytes that actually arrived, which is strictly better — but they get to,
+ * because they buffer. `c.req.formData()` gives no such opportunity: by the time
+ * it resolves, the whole upload is already in a process whose unit caps at
+ * 300 MB of memory, which is the thing the limit exists to prevent.
+ *
+ * So this trusts the header, and the docblock says so plainly. A liar gets
+ * through to the buffering call — but a liar was always going to, and this still
+ * turns the honest 3 GB folder-drop (the actual failure shape) into a refusal
+ * the app can explain instead of an OOM or an nginx HTML 413 the app never sees.
+ * It is a companion to the proxy's `client_max_body_size`, never a replacement.
+ *
+ * A missing or unparseable header is NOT a refusal: chunked requests omit it
+ * legitimately, and refusing them would break a correct client to catch a
+ * dishonest one.
+ */
+export function refuseOversizedBody(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    const declared = Number(c.req.header('content-length'));
+    if (!Number.isFinite(declared) || declared <= maxBytes)
+        return null;
+    return {
+        status: 413,
+        error: `${label} too large (${declared} bytes; the limit is ${maxBytes})`,
+    };
+}
+/**
+ * Read a JSON body, refusing anything over `maxBytes` before parsing it.
+ *
+ * The size is measured in BYTES, not characters. `String.length` counts UTF-16
+ * code units, so a body of 4-byte emoji measures half its true size that way —
+ * which would let a caller past a byte limit the proxy is enforcing in real
+ * bytes, and produce the mismatch this module exists to close.
+ */
+export async function readBoundedJson(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let raw;
+    try {
+        raw = await c.req.text();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    const bytes = new TextEncoder().encode(raw).length;
+    if (bytes > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} must be JSON` };
+    }
+}

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

@@ -0,0 +1,385 @@
+import type { FileTokenClaims } from './types';
+/**
+ * The claims binary-server verifies, re-exported from `./types` (the fleet's single
+ * source of truth — `cursedbelt-server/storage/types`). See there for the per-field
+ * docs. Kept exported here so the call sites that took it from the app-side copy of
+ * this module read unchanged.
+ */
+export type { FileTokenClaims };
+export interface BinaryStoreConfig {
+    /** e.g. `http://127.0.0.1:3099` or `https://binary-server.cursedalchemy.com`. */
+    baseUrl: string;
+    /** Tenant id — the first path segment and the token scope, e.g. `notes`. */
+    appId: string;
+    /** Must byte-match the issuer registered in binary-server's `apps` table. */
+    issuer: string;
+    /** PKCS8 private PEM (raw, `\n`-escaped, or base64-wrapped — all accepted). */
+    privateKey: string;
+    /** Enables `remove`/`removePrefix` (sent as `x-internal-secret`). */
+    internalSecret?: string;
+    /**
+     * Where THIS PROCESS should reach binary-server, when that is somewhere cheaper than
+     * the public name — `http://127.0.0.1:3099` for a deployment sharing the Mac with it.
+     * Defaults to {@link BinaryStoreConfig.baseUrl}. Used by `get`, `meta` and `stat`;
+     * never by `mediaUrl`, whose output is handed to a browser.
+     */
+    internalBaseUrl?: string;
+    /**
+     * Above this many bytes, {@link BinaryStore.put} takes the CHUNKED path by
+     * itself. Defaults to {@link AUTO_CHUNK_THRESHOLD_BYTES}; pass `Infinity` to
+     * turn the fallback off and get the pre-2026-08-08 behavior.
+     */
+    autoChunkBytes?: number;
+    /**
+     * How long a "this key is not here" is believed. Defaults to
+     * {@link BINARY_ABSENCE_TTL_MS}; the constant carries the owner's reasoning and
+     * an app should have a measured reason to differ from it.
+     */
+    absenceTtlMs?: number;
+    /** Injected so the memo's expiry is testable without a real clock. */
+    now?: () => number;
+}
+/**
+ * Which keys this process has read from the wire far too often, worst first —
+ * empty on every healthy deployment, which is what makes it a usable alarm.
+ *
+ * Entries older than one window are dropped as they are read, so a burst that
+ * stopped stops being reported rather than becoming a permanent accusation.
+ */
+export declare function repeatedBinaryKeys(now?: () => number): RepeatedBinaryKey[];
+/** Test seam — the register is process-wide, so a spec must be able to clear it. */
+export declare function resetRepeatedBinaryKeys(): void;
+/**
+ * Did this request ask for a FRESH answer — i.e. is it a hard refresh?
+ *
+ * 🔴 The owner's first escape hatch, and the reason it is a shared function rather
+ * than an inline header read in each app: *"if the no is remembered an hour then I
+ * could fix it but not be able to tell for an hour."* A browser hard-refresh sends
+ * `Cache-Control: no-cache` (older ones send `Pragma`), so reloading the picture is
+ * the repair — as long as every app spells the check the same way.
+ */
+export declare function wantsFresh(req: {
+    headers: Headers;
+} | Headers): boolean;
+/**
+ * 🔴 The size at which a single-request `put` stops being safe, FLEET-WIDE.
+ *
+ * binary-server is published through a Cloudflare Tunnel, and the edge refuses a
+ * request body over ~100 MB with a **413 before it ever reaches the origin**. So
+ * the ceiling is not bs's and not the caller's — it belongs to a hop neither end
+ * controls, and every app that stores a large blob inherits it.
+ *
+ * `apps/roms` hit it on 2026-08-08: eight genuine DS cartridges (128–512 MB)
+ * came back `[binary-store] put rom/<digest>: 413` and it read as eight
+ * mysterious ingest failures rather than as one limit. roms fixed it locally,
+ * which left the trap in place for every other app's attachments and for any
+ * future video/media path — so the threshold lives HERE now and `put` applies it
+ * itself.
+ *
+ * 64 MiB, not 100: the edge's number is approximate and includes headers and any
+ * transfer encoding, and the chunked path costs one extra request for a blob
+ * that only just crosses the line. Being early is free; being late is a 413.
+ */
+export declare const AUTO_CHUNK_THRESHOLD_BYTES: number;
+export interface PutOptions {
+    /** The user-facing display name ("My Dog Video") — binary-server stores it in its
+     *  db ONLY (never on disk), for its inspector/UIs. Optional everywhere. */
+    title?: string;
+    /**
+     * This key IS the digest of these bytes, so they can never change under it.
+     * binary-server then serves the object `public, max-age=31536000, immutable`
+     * instead of the one-day default — no daily revalidation against the home
+     * uplink for bytes that are the same bytes by construction, and cache-busting
+     * needs no version segment because different bytes are a different key.
+     *
+     * Only pass it for a genuinely content-addressed key. A wrong `true` pins stale
+     * bytes at the edge and in every browser for a year.
+     */
+    immutable?: boolean;
+}
+export interface MediaUrlOptions {
+    filename?: string;
+    disposition?: 'inline' | 'attachment';
+    ttlSeconds?: number;
+    /**
+     * Mint a URL that is BYTE-IDENTICAL for every call inside the same window of
+     * this many seconds (the token's `iat`/`exp` are snapped to the window rather
+     * than to the clock), and valid for two windows so one minted at the very end
+     * of a window is still good.
+     *
+     * The problem it solves: a fresh token per call means a fresh URL per call, and
+     * a browser's HTTP cache keys on the URL — so an `<img src>` re-rendered or a
+     * ROM re-launched re-downloads bytes it already has, however long the
+     * Cache-Control says. (The Cloudflare edge is unaffected either way; its cache
+     * key strips `token`.) The cost is a longer-lived bearer URL, so keep the
+     * window as short as the caching win allows and leave it unset for anything
+     * whose leak matters more than its bytes.
+     */
+    stableWindowSeconds?: number;
+}
+export interface BlobMeta {
+    size: number;
+    mime: string | null;
+    /** The display name the uploader set (`PutOptions.title`), if any. */
+    title: string | null;
+    /** sha256 binary-server computed post-write. Audit-only — keys are app-chosen. */
+    checksum: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface PutLargeOptions extends PutOptions {
+    /** Bytes per chunk. Default 16 MiB — big enough that a 500 MB upload is ~32 requests,
+     *  small enough that neither side ever buffers a whole video. */
+    chunkBytes?: number;
+}
+/** How a read should treat the memos — see {@link BINARY_ABSENCE_TTL_MS}. */
+export interface ReadOptions {
+    /**
+     * Ignore both memos: ask the store, and refresh what we believe from its answer.
+     *
+     * This is the per-request escape hatch, and `wantsFresh(request)` is what turns a
+     * browser's hard refresh into it — so "I fixed the picture and cannot tell for an
+     * hour" is answered by reloading the picture.
+     */
+    fresh?: boolean;
+}
+/** What the memos currently hold — for an owner surface, a smoke, and the tests. */
+export interface BinaryCacheStats {
+    /** Keys known to be present. Never expires; see {@link BINARY_ABSENCE_TTL_MS}. */
+    present: number;
+    /** Keys known to be absent, and not yet lapsed. */
+    absent: number;
+}
+/** One key this process has read from the wire far too often — see
+ *  {@link BINARY_REPEAT_THRESHOLD}. */
+export interface RepeatedBinaryKey {
+    /** binary-server tenant, i.e. which app is doing it. */
+    tenant: string;
+    key: string;
+    /** Wire reads inside the current window. Memo hits are NOT counted: the memo
+     *  working is the fix, so a memoized key must go quiet. */
+    reads: number;
+    windowMs: number;
+}
+export interface BinaryStore {
+    readonly appId: string;
+    /**
+     * Store an object. Above {@link AUTO_CHUNK_THRESHOLD_BYTES} this delegates to
+     * {@link BinaryStore.putLarge} by itself, because the limit that makes a
+     * single request fail belongs to the Cloudflare Tunnel in front of
+     * binary-server rather than to any caller — see that constant.
+     */
+    put(key: string, bytes: Uint8Array, mime?: string, opts?: PutOptions): Promise<void>;
+    /**
+     * Upload in chunks (`PUT /upload-chunk`), for objects too large to buffer whole.
+     *
+     * `put` sends one request whose body binary-server reads entirely into memory before
+     * writing — fine for an attachment, wrong for a 500 MB video on a machine that is also
+     * running everything else. This sends bounded pieces and lets bs assemble them once the
+     * last one lands (it counts arrivals, so out-of-order delivery and retries are both safe).
+     */
+    putLarge(key: string, source: Uint8Array | Blob, mime?: string, opts?: PutLargeOptions): Promise<void>;
+    /** `null` when the key does not exist. */
+    get(key: string, opts?: ReadOptions): Promise<Uint8Array | null>;
+    /**
+     * Everything binary-server knows about a blob (`GET /meta`) — `null` when unknown or
+     * deleted. The honest answer to "what IS this?": size, the stored mime, and the TITLE,
+     * none of which `stat` could report (it inferred a size from a Range probe and nothing
+     * else). Added to bs 2026-07-30 for exactly this.
+     *
+     * MEMOIZED since 2026-09-09 — a `null` for an hour, a hit for ever. See
+     * {@link BINARY_ABSENCE_TTL_MS} for both halves and for the two bypasses.
+     */
+    meta(key: string, opts?: ReadOptions): Promise<BlobMeta | null>;
+    /** `null` when the key does not exist. Delegates to {@link BinaryStore.meta}. */
+    stat(key: string, opts?: ReadOptions): Promise<{
+        size: number;
+    } | null>;
+    /**
+     * Does the store hold this key? The cheap question, memoized — and the one every
+     * app was asking the expensive way.
+     *
+     * Prefer it over `stat`/`meta` when the answer is only ever used as a boolean:
+     * it says what it means, and it cannot tempt a caller into trusting a memoized
+     * `size` for a key whose bytes are replaceable.
+     */
+    has(key: string, opts?: ReadOptions): Promise<boolean>;
+    /**
+     * What the memo ALREADY knows about a key, with no I/O and no promise.
+     *
+     * 🔴 The one question `has()` cannot answer, and the reason an app would otherwise keep
+     * a second copy of this cache. A listing route answers for hundreds of rows inside one
+     * request — roms' `/api/roms` draws 300 games — so it cannot await a round trip per row
+     * even when every one of them would hit the memo: `await` in a loop over 300 keys is 300
+     * microtask turns and a `Promise` each, on the box that also serves everything else.
+     * With this the render answers from what is already known and lets the per-card path
+     * fill in the rest.
+     *
+     * `"unknown"` is a real third answer and must not be collapsed into `"absent"`: it means
+     * *nobody has asked yet*, and a caller that treats it as "no" turns a cold process into
+     * one that permanently draws nothing.
+     */
+    known(key: string): 'present' | 'absent' | 'unknown';
+    /**
+     * Forget every "the store does not have this" — all of them, or those whose key
+     * starts with `prefix`. Returns how many were dropped.
+     *
+     * 🔴 The owner's second escape hatch, and it is deliberately a REPAIR rather than
+     * a cache flush: the positive memos are untouched, so proving a fix costs nothing
+     * but the keys that were actually missing. An app exposes it behind its owner gate
+     * (`POST /api/media/forget-misses`) so "I put the picture back" can be verified in
+     * seconds instead of in an hour.
+     */
+    forgetMisses(prefix?: string): number;
+    /** What the memos hold right now. */
+    cacheStats(): BinaryCacheStats;
+    remove(key: string): Promise<void>;
+    /** Wipes a whole container tree (`?container=1`). */
+    removePrefix(prefix: string): Promise<void>;
+    /** A signed, directly-fetchable download URL (for redirects / <img src>). */
+    mediaUrl(key: string, opts?: MediaUrlOptions): Promise<string>;
+    /**
+     * A signed URL for `master`, authorized by `prefix` — the only shape a multi-object tree
+     * (an HLS ladder) can be played from. See the implementation for why an exact-key token
+     * cannot work and why this is a separate method rather than a flag.
+     */
+    mediaPrefixUrl(prefix: string, master: string, opts?: MediaUrlOptions): Promise<string>;
+    /**
+     * The raw `Response` for an object, from the origin THIS PROCESS should use — so an app
+     * can SERVE bytes itself, streaming, when the public edge will not.
+     *
+     * 🔴 The gap {@link BinaryStoreConfig.internalBaseUrl} left open. That note ends
+     * "redirected media — videos, large downloads — therefore still goes through the edge",
+     * and on 2026-09-08 that was the whole outage: Cloudflare spent its Workers day, every
+     * `/media/*` request answered 429, and apps/music could not play a note even though the
+     * bytes were on the same Mac as the server the browser was talking to.
+     *
+     * Two things make this a fallback rather than a second architecture:
+     *  · It returns the RESPONSE, not the bytes. `get` buffers a whole object into memory,
+     *    which is wrong for a 30 MB track and unthinkable for a video; the caller pipes
+     *    `res.body` straight through and holds one chunk at a time.
+     *  · `range` is forwarded and the origin's `206`/`content-range` come back untouched,
+     *    because Range IS seeking. A proxy that drops it turns a seekable track into a
+     *    download.
+     */
+    fetchMedia(key: string, init?: {
+        range?: string | null;
+        method?: 'GET' | 'HEAD';
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** Escape hatch for protocols this module doesn't wrap (chunked uploads). */
+    signToken(claims: FileTokenClaims, ttlSeconds: number): Promise<string>;
+}
+/**
+ * 🔴 How long "the store does not hold this key" is believed — the NEGATIVE memo.
+ *
+ * The positive one never expires and needs no constant: a key in this fleet names
+ * either a content digest or a timestamped upload, so the bytes under it cannot
+ * change and "it is there" cannot stop being true. An ABSENCE is different — it is
+ * a fact about right now, and art, web copies and derivatives all genuinely arrive
+ * later — so it has to lapse.
+ *
+ * An hour is the default because the owner named the cost of getting it wrong:
+ *
+ *   > *"potentially we need a shorter time for remembering a 'no' in some
+ *   > circumstances or at least a way to bypass it occasionally. For instance
+ *   > collections showed a lot of missing thumbnails and images and if the no is
+ *   > remembered an hour then I could fix it but not be able to tell for an hour."*
+ *
+ * So the hour is never the only answer. TWO bypasses ship with it, both cheap and
+ * both proven by {@link BinaryStore.forgetMisses}' tests:
+ *
+ *  · a read with `{ fresh: true }` ignores both memos and re-asks. `wantsFresh()`
+ *    turns a browser's hard refresh (`Cache-Control: no-cache`) into exactly that,
+ *    so the owner's own reload IS the fix for one picture;
+ *  · `forgetMisses(prefix?)` drops every negative memo, or a subtree of them, so an
+ *    app can expose a one-click repair and prove it in seconds rather than in an
+ *    hour.
+ */
+export declare const BINARY_ABSENCE_TTL_MS: number;
+/**
+ * The window and the count that make a key's re-reads an INCIDENT rather than traffic.
+ *
+ * 🔴 Every quota incident this fleet has had was this exact shape and nothing was
+ * watching for it: roms boxart at ~200 reads per key per day (20,626 failed `/media`
+ * fetches in one day), family portraits at 2,449 per key per day, music cover art
+ * doing a server-side `get` that left the Mac to read a file on the Mac. In all three
+ * the giveaway was one key, over and over, from a `Bun/1.3.x` user agent — visible in
+ * Cloudflare's top-talker list and in nobody's code.
+ *
+ * 50 in five minutes is far above any legitimate server-side pattern (a page render
+ * asks for a key once; a warm pass asks once) and far below the rate that spends a
+ * day's allowance, so it fires early and it does not fire on a normal day.
+ */
+export declare const BINARY_REPEAT_WINDOW_MS: number;
+export declare const BINARY_REPEAT_THRESHOLD = 50;
+export declare const DOWNLOAD_TOKEN_TTL_SECONDS = 60;
+export declare const UPLOAD_TOKEN_TTL_SECONDS = 600;
+/** Deletes are server-to-server and near-instant; a short TTL suffices. The token proves the
+ *  caller holds THIS tenant's private key and is authorized for THIS path — binary-server
+ *  requires it alongside the internal secret (defense in depth, owner ruling #10). */
+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;
+export declare function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore;
+/**
+ * Which binary-server TENANT this process is — the app's own key, unless the environment
+ * names another.
+ *
+ * 🔴 It has to be a variable, and 2026-08-21 is the day that stopped being theoretical.
+ * A tenant is TWO facts that must agree: the key a request is SIGNED with, and the key the
+ * request PATH starts with (`authorize()` in binary-server refuses when
+ * `path.split("/")[0] !== token.app_id`). Apps supplied the second as a literal — `const
+ * TENANT = "collections"` — while `FILE_TOKEN_ISSUER`/`FILE_TOKEN_PRIVATE_KEY` came from
+ * the environment. That is fine on production, where the two happen to match, and it makes
+ * an ephemeral STAGE structurally unable to store a byte: `stage up` mints it a real
+ * `collections-stage` tenant and hands it that keypair, and every upload then signs as
+ * `collections-stage` while addressing `collections/…` and comes back
+ * `[binary-store] put file/<sha>: 403`. The stage looked like a working app with an empty
+ * gallery, which is exactly what an empty stage is supposed to look like.
+ *
+ * Reading it here means an app opts in by CALLING this instead of writing a literal, and
+ * `BINARY_STORE_TENANT` is already inside an app's stage-env shared-store denylist
+ * (`/^BINARY_STORE_(?!.*URL$)/`) — so a stage cannot INHERIT production's tenant, only be
+ * given its own. The fallback is the app's key, so an app that never sets it is unchanged.
+ *
+ * 🔴 **A BLANK tenant now throws, and that is the whole point of the check
+ * (2026-08-23).** `undefined` is a perfectly good JavaScript string once it is
+ * template-interpolated, so a caller that forgot the argument signed a token for
+ * `undefined/<key>` and addressed `PUT /upload/undefined/<key>` — at which point
+ * binary-server's `authorize()` refuses it correctly and answers a bare
+ * `{"error":"forbidden"}`. That reads as a broken CREDENTIAL, and it was filed as one
+ * (*"family.env's FILE_TOKEN_PRIVATE_KEY does not authorize against the family tenant"*).
+ * The keypair was correct the whole time and a Mac-side upload works; what was missing was
+ * the tenant id. bs cannot tell the two apart — it sees a token for a tenant it does not
+ * have — so the check has to live on this side of the wire, where the mistake is legible.
+ */
+export declare function binaryStoreTenant(appId: string, env?: Record<string, string | undefined>): string;
+/**
+ * The tenant this process's binary store resolved, or `null` when it has no store.
+ *
+ * The value an app's `mediaTenant` option wants, and the reason it exists as a named
+ * function rather than each app writing `readBinaryStoreEnv(x)?.appId`:
+ *
+ * 🔴 **`null` and a thrown error are different answers and both are correct.**
+ * {@link binaryStoreTenant} throws when it cannot name a tenant, which is right at an upload
+ * site — signing for `"undefined/<key>"` earns a bare 403 that reads as a bad credential. It is
+ * wrong on `/healthz`, where the same throw would turn "this dev shell has no store" into a
+ * 500 and take the app's health probe down with it. So this asks the same question through the
+ * same resolution and answers `null` for the store-less case, which the health handler then
+ * reports as an explicit "no store" rather than as silence.
+ *
+ * Pass the app's OWN tenant key — the constant its store is built from (`LIFE_BINARY_TENANT`,
+ * `STUDIO_BINARY_TENANT`, …), never the app's display name. They are the same string for most
+ * apps and that is precisely why the difference goes unnoticed when it is not.
+ */
+export declare function resolvedMediaTenant(appId: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * The standard env surface every tenant's secrets file carries
+ * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):
+ * `BINARY_SERVER_URL`, `FILE_TOKEN_ISSUER`, `FILE_TOKEN_PRIVATE_KEY`, and
+ * optionally `BINARY_SERVER_INTERNAL_SECRET`. Returns `null` unless the three
+ * required vars are all present — callers fall back to their local backend.
+ */
+export declare function readBinaryStoreEnv(appId: string, env?: Record<string, string | undefined>): BinaryStoreConfig | null;