cursedbelt-server 4.0.0 → 4.1.0

package/src/server/storage/binaryStore.ts

@@ -0,0 +1,1049 @@
+/**
+ * binary-server client — the ONE way an app talks to the machine's binary store
+ * (`apps/binary-server`, :3099 behind binary-server.cursedalchemy.com).
+ *
+ * The owner's standing decision: binary-server is THE binary/media storage spot for
+ * every app — local disks must not accumulate image/blob payloads. Any app that loads
+ * or generates images stores them through this client, behind its own app-local seam
+ * (an `AttachmentStore`, a box-art cache, art artifacts).
+ *
+ * Protocol (see binary-server/src/server.ts + src/tokens.ts):
+ *   - `PUT /upload/<app>/<key>?token=` uploads whole bytes (201).
+ *   - `GET /media/<app>/<key>?token=` downloads (Range-capable; 404 when absent).
+ *   - `DELETE /media/<app>/<key>?token=` is gated by BOTH `x-internal-secret` AND a
+ *     per-op delete token (`op:"delete"`, tenant-scoped like read/write). Owner ruling #10.
+ *   - Tokens are RS256 JWTs signed with the app's PRIVATE key (bs holds only the
+ *     public half); `iss` must exactly match the registered issuer and `k` must be
+ *     the app-prefixed path (`<app>/<key>`). Paths are decoded whole on the server,
+ *     so keys are encoded PER SEGMENT with `/` kept literal.
+ *
+ * ── 🔴 Why this sits beside `createBinaryServerStore` rather than replacing it ──────
+ * `./binaryServerStore.ts` is 102 lines: a {@link MediaStore} adapter whose RS256 signer
+ * is INJECTED, deliberately, so that module carries no key material. This one is the
+ * other half of the same wire — it MINTS the token from a PKCS8 private PEM and owns the
+ * whole client surface: auto-chunking, the absence memo, Range reads, the repeat-key
+ * counter and tenant resolution. They are not the same module and neither is a worse
+ * version of the other; they share one contract, {@link FileTokenClaims}, so a token
+ * minted here can never drift out of shape from one minted there against the same
+ * binary-server.
+ *
+ * 🔴 It is published as the LEAF subpath `cursedbelt-server/binary-store`, never through
+ * the `./storage` barrel — that barrel drags the file-catalogue and transcode graph, and
+ * this module's whole promise is that an app pays nothing but `node:crypto` for it.
+ * `src/leafSubpathsImportNothing.spec.ts` is what holds that promise.
+ *
+ * ── Where it came from (2026-09-17) ────────────────────────────────────────────────
+ * Five apps carried a byte-for-byte copy of this file and three of them had drifted.
+ * Nothing could see it: a repo's gate proves that repo, so five green gates is what
+ * three forks of the fleet's binary-storage client looked like from the outside. The
+ * divergence was measured before the move and was entirely in prose and in one stale
+ * 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, type KeyObject } from 'node:crypto';
+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;
+}
+
+/*
+ * ── The process-wide repeat register (§ the repeat-key counter) ───────────────
+ *
+ * An app makes one store per tenant and a few make two, so the counter has to
+ * aggregate somewhere above an individual client for the answer to mean "what is
+ * THIS DEPLOYMENT doing". It is a module-level map for the same reason an install
+ * metrics recorder is module-level: the thing being measured is the process, and
+ * threading a collector through every `createBinaryStore` call site would make
+ * instrumenting an app an act of remembering.
+ *
+ * An app reports it on `/healthz`, which the fleet probe already fetches for every
+ * live deployment — so this reaches the incident sweep, and the owner's text channel,
+ * without anybody making a new request for it.
+ */
+const repeats = new Map<string, RepeatedBinaryKey & { at: number }>();
+/** Bounded: a genuinely runaway app must not turn this into a leak. */
+const MAX_TRACKED_REPEATS = 50;
+
+function recordRepeat(tenant: string, key: string, count: number, at: number): void {
+  const id = `${tenant}/${key}`;
+  if (!repeats.has(id) && repeats.size >= MAX_TRACKED_REPEATS) return;
+  repeats.set(id, {
+    tenant,
+    key,
+    reads: count,
+    windowMs: BINARY_REPEAT_WINDOW_MS,
+    at,
+  });
+}
+
+/**
+ * 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 function repeatedBinaryKeys(now: () => number = Date.now): RepeatedBinaryKey[] {
+  const at = now();
+  const live: RepeatedBinaryKey[] = [];
+  for (const [id, row] of repeats) {
+    if (at - row.at >= BINARY_REPEAT_WINDOW_MS) {
+      repeats.delete(id);
+      continue;
+    }
+    live.push({ tenant: row.tenant, key: row.key, reads: row.reads, windowMs: row.windowMs });
+  }
+  return live.sort((a, b) => b.reads - a.reads);
+}
+
+/** Test seam — the register is process-wide, so a spec must be able to clear it. */
+export function resetRepeatedBinaryKeys(): void {
+  repeats.clear();
+}
+
+/**
+ * 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 function wantsFresh(req: { headers: Headers } | Headers): boolean {
+  const headers = req instanceof Headers ? req : req.headers;
+  const cacheControl = headers.get('cache-control')?.toLowerCase() ?? '';
+  if (cacheControl.includes('no-cache')) return true;
+  return (headers.get('pragma')?.toLowerCase() ?? '').includes('no-cache');
+}
+
+/**
+ * 🔴 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 const AUTO_CHUNK_THRESHOLD_BYTES = 64 * 1024 * 1024;
+
+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 const BINARY_ABSENCE_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * 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 const BINARY_REPEAT_WINDOW_MS = 5 * 60 * 1000;
+export const BINARY_REPEAT_THRESHOLD = 50;
+
+export const DOWNLOAD_TOKEN_TTL_SECONDS = 60;
+export 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 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 function normalizePrivateKeyPem(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.includes('-----BEGIN')) return trimmed.replaceAll('\\n', '\n');
+  let decoded: string;
+  try {
+    decoded = Buffer.from(trimmed, 'base64').toString('utf8');
+  } catch {
+    throw new Error('[binary-store] private key is neither PEM nor base64');
+  }
+  if (!decoded.includes('-----BEGIN')) {
+    throw new Error('[binary-store] private key decodes to something that is not a PEM');
+  }
+  return decoded;
+}
+
+const base64url = (bytes: Uint8Array | string): string =>
+  Buffer.from(bytes as Uint8Array).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. */
+const encodeKeyPath = (key: string): string => key.split('/').map(encodeURIComponent).join('/');
+
+export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
+  const baseUrl = cfg.baseUrl.replace(/\/+$/, '');
+  /*
+   * 🔴 Where THIS PROCESS fetches bytes from, which is not where a browser fetches
+   * them from (2026-09-08).
+   *
+   * `baseUrl` is binary-server's public name, and it has to be: a phone has no other
+   * way to reach it. But an app's own SERVER calling `get`/`meta` went out to that
+   * public name too — through Cloudflare's Worker and back — to read bytes from a
+   * daemon on the same Mac. Two consequences, and the fleet met both on one day:
+   *
+   *  1. Every server-side read spent a request out of the Workers FREE plan's
+   *     100,000/day. family alone made 15,689 of them that day.
+   *  2. When that ceiling was reached Cloudflare answered 429 to everything, and
+   *     family's people page drew no faces at all — because the app could not reach a
+   *     store sitting 20cm away. The owner: "we can't let them block our images
+   *     without a fallback."
+   *
+   * No extra copy is needed for that fallback. The bytes are already local, and an
+   * R2-backed object is reachable by binary-server directly — R2 is not gated by the
+   * Workers limit. So a deployment sharing a machine with binary-server names its
+   * loopback origin here and stops leaving the box to read its own files.
+   *
+   * `mediaUrl` is deliberately NOT affected: it mints a signed URL to hand to a
+   * BROWSER, and a browser cannot resolve 127.0.0.1 to this Mac. Redirected media —
+   * videos, large downloads — therefore still goes through the edge, which is correct,
+   * and is named as the remaining gap.
+   */
+  const internalBaseUrl = (cfg.internalBaseUrl ?? cfg.baseUrl).replace(/\/+$/, '');
+  const autoChunkBytes = cfg.autoChunkBytes ?? AUTO_CHUNK_THRESHOLD_BYTES;
+  const now = cfg.now ?? Date.now;
+  const absenceTtlMs = cfg.absenceTtlMs ?? BINARY_ABSENCE_TTL_MS;
+
+  /*
+   * ── 🔴 The shared picture cache (2026-09-09) ───────────────────────────────
+   *
+   * Three apps had written three copies of this, each after its own outage, and a
+   * fourth (family) had none at all and was measured at 2,449 reads per key per day.
+   * It belongs here because this is the one seam every app's media passes through —
+   * the rule from music (remember a YES for ever) and the rule from roms (remember a
+   * NO for an hour) in the place that makes them true for everybody.
+   *
+   * The positive memo is a `BlobMeta`, not a bare flag, because the read it exists to
+   * remove is `meta()` — one index read at binary-server, but a whole Cloudflare Worker
+   * invocation from the outside, which is the currency the fleet actually ran out of.
+   *
+   * 🔴 What makes "for ever" safe is the KEY SHAPE, not optimism. A key here is a
+   * content digest (music, collections) or a timestamped upload (family portraits:
+   * `<space>/portrait/<id>-<base36 time>`), so a re-upload is a NEW key and nothing can
+   * change under an old one. The one shape that does NOT have that property is roms'
+   * box art, whose key hashes the game NAME — which is why `put` refreshes the memo
+   * rather than leaving it, and why a `get` that comes back empty DEMOTES a positive
+   * memo instead of trusting it. Between them, a key whose bytes were replaced or
+   * released out from under us self-heals on the next read that actually wanted bytes.
+   */
+  const present = new Map<string, BlobMeta>();
+  const absentUntil = new Map<string, number>();
+
+  /** A live negative memo, or `false` (lapsed entries are dropped as they are met). */
+  const knownAbsent = (key: string): boolean => {
+    const until = absentUntil.get(key);
+    if (until === undefined) return false;
+    if (until > now()) return true;
+    absentUntil.delete(key);
+    return false;
+  };
+  const rememberPresent = (key: string, meta: BlobMeta): void => {
+    absentUntil.delete(key);
+    present.set(key, meta);
+  };
+  const rememberAbsent = (key: string): void => {
+    present.delete(key);
+    absentUntil.set(key, now() + absenceTtlMs);
+  };
+  /** Neither memo is trustworthy for this key any more — a write, or a delete. */
+  const forget = (key: string): void => {
+    present.delete(key);
+    absentUntil.delete(key);
+  };
+
+  /*
+   * The repeat-key counter (see BINARY_REPEAT_THRESHOLD). Counts WIRE reads only:
+   * a memo hit is the cure, so a key the memo answers has to fall silent, or the
+   * alarm would fire loudest on the apps that fixed themselves.
+   */
+  const reads = new Map<string, { count: number; since: number }>();
+  const countWireRead = (key: string): void => {
+    const at = now();
+    const seen = reads.get(key);
+    if (!seen || at - seen.since >= BINARY_REPEAT_WINDOW_MS) {
+      reads.set(key, { count: 1, since: at });
+      return;
+    }
+    seen.count++;
+    // Below the line this is ordinary traffic, and the register must stay empty on a
+    // healthy deployment — an alarm that lists every key is one nobody reads.
+    if (seen.count < BINARY_REPEAT_THRESHOLD) return;
+    if (seen.count === BINARY_REPEAT_THRESHOLD) {
+      // Once per key per window, at the moment it crosses — a line per read would
+      // be the same storm in the log file.
+      console.warn(
+        `[binary-store] ${cfg.appId}/${key} has been read ${seen.count} times in ` +
+          `${Math.round((at - seen.since) / 1000)}s. Every one of those is a request out ` +
+          "of the fleet's daily Cloudflare allowance for bytes that cannot have changed — " +
+          'this caller should be holding the answer. See BINARY_REPEAT_THRESHOLD.',
+      );
+    }
+    recordRepeat(cfg.appId, key, seen.count, at);
+  };
+  let keyObject: KeyObject | null = null;
+  const privateKey = (): KeyObject => {
+    keyObject ??= createPrivateKey(normalizePrivateKeyPem(cfg.privateKey));
+    return keyObject;
+  };
+
+  const signToken = async (
+    claims: FileTokenClaims,
+    ttlSeconds: number,
+    /** Snap `iat` down to a multiple of this so the whole token is byte-stable
+     *  inside one window — see {@link MediaUrlOptions.stableWindowSeconds}. */
+    windowSeconds?: number,
+  ): Promise<string> => {
+    const clock = Math.floor(Date.now() / 1000);
+    const issuedAt =
+      windowSeconds && windowSeconds > 0
+        ? Math.floor(clock / windowSeconds) * windowSeconds
+        : clock;
+    const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const payload = base64url(
+      JSON.stringify({ iss: cfg.issuer, iat: issuedAt, exp: issuedAt + ttlSeconds, ...claims }),
+    );
+    const signature = cryptoSign('sha256', Buffer.from(`${header}.${payload}`), privateKey());
+    return `${header}.${payload}.${base64url(signature)}`;
+  };
+
+  const appKey = (key: string): string => `${cfg.appId}/${key}`;
+  const mediaUrl = async (key: string, opts?: MediaUrlOptions): Promise<string> => {
+    const window = opts?.stableWindowSeconds;
+    // Two windows, so a URL minted in the last second of one is still valid for a
+    // download that starts in the next.
+    const ttl =
+      window && window > 0 ? window * 2 : (opts?.ttlSeconds ?? DOWNLOAD_TOKEN_TTL_SECONDS);
+    const token = await signToken(
+      { k: appKey(key), fn: opts?.filename, dl: opts?.disposition },
+      ttl,
+      window,
+    );
+    return `${baseUrl}/media/${encodeKeyPath(appKey(key))}?token=${encodeURIComponent(token)}`;
+  };
+
+  /**
+   * A signed URL for the MASTER of a multi-object tree, authorized by PREFIX.
+   *
+   * ── 🔴 Why an exact-key token cannot work here ──────────────────────────────────────
+   * An HLS ladder is a tree — a master naming rung playlists naming segments — and a
+   * player resolves those names RELATIVE to the master's URL. A relative URI resolves
+   * against the base URL's PATH and discards its query string (RFC 3986, and every player
+   * behaves this way), so `720/index.m3u8` arrives at binary-server with no `?token=` and
+   * is correctly refused.
+   *
+   * binary-server solves the second half: it rewrites a playlist as it serves it, appending
+   * the SAME token to every URI the playlist names (`src/media/hlsPlaylist.ts`). That
+   * rewrite only fires for a PREFIX token, and deliberately so — copying an exact-key token
+   * onto a child URI produces a URL that 403s, which is the same broken video with an extra
+   * query parameter. So the first half has to be minted here, and this is it.
+   *
+   * 🔴 It grants nothing the bearer did not already have: the prefix is the tree, and every
+   * URI inside the tree resolves under it. But it IS broader than an exact key by
+   * construction, so it is deliberately a separate method with its own name rather than a
+   * flag on `mediaUrl` — a caller reaching for prefix authority should have to say so.
+   */
+  const mediaPrefixUrl = async (
+    prefix: string,
+    master: string,
+    opts?: MediaUrlOptions,
+  ): Promise<string> => {
+    const window = opts?.stableWindowSeconds;
+    const ttl =
+      window && window > 0 ? window * 2 : (opts?.ttlSeconds ?? DOWNLOAD_TOKEN_TTL_SECONDS);
+    // The claim is the PREFIX; the URL points at the master inside it.
+    const token = await signToken({ p: appKey(prefix) }, ttl, window);
+    return `${baseUrl}/media/${encodeKeyPath(appKey(master))}?token=${encodeURIComponent(token)}`;
+  };
+
+  /** The same signed URL, aimed at the origin THIS PROCESS should use. Never handed to
+   *  a browser — see the note on `internalBaseUrl`. */
+  const internalMediaUrl = async (key: string, opts?: MediaUrlOptions): Promise<string> =>
+    (await mediaUrl(key, opts)).replace(baseUrl, internalBaseUrl);
+
+  /** `/meta` authorizes with the same token shape as `/media` — an exact-key claim. */
+  const metaUrl = async (key: string): Promise<string> => {
+    const token = await signToken({ k: appKey(key) }, DOWNLOAD_TOKEN_TTL_SECONDS);
+    // `/meta` is only ever asked by a server, so it always uses the internal origin.
+    return `${internalBaseUrl}/meta/${encodeKeyPath(appKey(key))}?token=${encodeURIComponent(token)}`;
+  };
+
+  const internalHeaders = (): Record<string, string> => {
+    if (!cfg.internalSecret) {
+      throw new Error(
+        '[binary-store] remove requires internalSecret (BINARY_SERVER_INTERNAL_SECRET)',
+      );
+    }
+    return { 'x-internal-secret': cfg.internalSecret };
+  };
+
+  const store: BinaryStore = {
+    appId: cfg.appId,
+    signToken,
+    mediaUrl,
+    mediaPrefixUrl,
+
+    async put(key, bytes, mime, opts) {
+      // 🔴 The chunked fallback, applied HERE rather than at every call site —
+      // the limit is the Cloudflare Tunnel's, so it is a property of this
+      // client's destination and not of anyone's payload. See
+      // AUTO_CHUNK_THRESHOLD_BYTES.
+      if (bytes.byteLength > autoChunkBytes) {
+        return await store.putLarge(key, bytes, mime, opts);
+      }
+      const token = await signToken({ k: appKey(key) }, UPLOAD_TOKEN_TTL_SECONDS);
+      const title = opts?.title?.trim();
+      const titleQs = title ? `&title=${encodeURIComponent(title)}` : '';
+      const immutableQs = opts?.immutable ? '&immutable=1' : '';
+      const res = await fetch(
+        `${baseUrl}/upload/${encodeKeyPath(appKey(key))}?token=${encodeURIComponent(token)}${titleQs}${immutableQs}`,
+        {
+          method: 'PUT',
+          headers: mime ? { 'content-type': mime } : undefined,
+          body: bytes as unknown as BodyInit,
+        },
+      );
+      if (!res.ok) {
+        // A 413 that reaches here despite the threshold above means the edge's
+        // real cap is lower than we think, or the caller disabled the
+        // fallback. Say what it is and what to do — the bare status is what
+        // made eight rejected DS cartridges read as eight unrelated mysteries
+        // on 2026-08-08.
+        if (res.status === 413) {
+          throw new Error(
+            `[binary-store] put ${key}: 413 — ${bytes.byteLength} bytes was refused before it ` +
+              'reached binary-server (the Cloudflare Tunnel in front of it caps a request body ' +
+              `at roughly 100 MB). Use putLarge(), or lower autoChunkBytes (currently ${autoChunkBytes}).`,
+          );
+        }
+        throw new Error(`[binary-store] put ${key}: ${res.status}`);
+      }
+      // 🔴 It exists now, and its BYTES may be new ones. Dropping both memos rather
+      // than asserting a presence is what keeps a name-addressed key (roms' box art
+      // hashes the game name, not the bytes) honest: the next reader re-asks once
+      // and re-learns, instead of trusting a size and mime from the previous file.
+      forget(key);
+    },
+
+    /*
+     * 🔴 Every chunk is READ INTO MEMORY before it is sent, and that is not a
+     * simplification — it is the fix for a hang that stopped the collections dropzone
+     * dead for a day (measured 2026-08-13, Bun 1.3.14).
+     *
+     * `Bun.file(path).slice(a, b)` is a lazy PARTIAL view of a file, and handing one to
+     * `fetch` as a body never sends: the request stalls until binary-server's 60s
+     * `idleTimeout` closes the socket, and the caller sees `EPIPE` / "socket connection
+     * was closed unexpectedly". Measured on one 20 MB file against the live server:
+     *
+     *   Bun.file, 16 MiB chunks (2 parts)  → FAIL after 56,164 ms
+     *   Bun.file,  8 MiB chunks (3 parts)  → FAIL after 60,000 ms
+     *   Bun.file, one WHOLE-range slice    → OK in 62 ms
+     *   the same bytes already in memory   → OK in 43 ms
+     *
+     * A whole-range slice works because it is not really a partial view, which is why
+     * every small file went through fine and only the ones that had to be split failed —
+     * i.e. exactly the videos this path exists for. 42 files / 35 GB failed 42/42 on
+     * every scheduled sweep for a day with nothing in binary-server's log, because from
+     * its side the request simply never arrived.
+     *
+     * The cost is one chunk resident at a time — 16 MiB — which is the bound `putLarge`
+     * always promised. It is NOT the bound the old code delivered: the lazy slice was
+     * never read at all.
+     */
+    async putLarge(key, source, mime, opts) {
+      const chunkBytes = Math.max(1, opts?.chunkBytes ?? 16 * 1024 * 1024);
+      const blob = source instanceof Blob ? source : new Blob([source as BlobPart]);
+      const total = Math.max(1, Math.ceil(blob.size / chunkBytes));
+      // One session id for the whole upload: bs keys the chunk scratch by it and
+      // assembles as soon as it has counted `tc` arrivals.
+      const sid = `${Date.now().toString(36)}-${Math.trunc(Math.random() * 1e9).toString(36)}`;
+      const title = opts?.title?.trim();
+      const titleQs = title ? `&title=${encodeURIComponent(title)}` : '';
+      const immutableQs = opts?.immutable ? '&immutable=1' : '';
+      for (let ci = 0; ci < total; ci++) {
+        const token = await signToken(
+          { k: appKey(key), sid, ci, tc: total },
+          UPLOAD_TOKEN_TTL_SECONDS,
+        );
+        const slice = new Uint8Array(
+          await blob
+            .slice(ci * chunkBytes, Math.min((ci + 1) * chunkBytes, blob.size))
+            .arrayBuffer(),
+        );
+        const res = await fetch(
+          `${baseUrl}/upload-chunk/${encodeKeyPath(appKey(key))}?token=${encodeURIComponent(token)}${titleQs}${immutableQs}`,
+          {
+            method: 'PUT',
+            headers: mime ? { 'content-type': mime } : undefined,
+            body: slice,
+          },
+        );
+        if (!res.ok) {
+          throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
+        }
+      }
+      forget(key); // see `put`
+    },
+
+    async get(key, opts) {
+      // 🔴 The negative memo short-circuits the BYTES too, and that is where most of
+      // the saving is: family drew a face by asking for bytes it had already been
+      // told were not there, hundreds of times a page. The positive memo cannot
+      // short-circuit here — we want the bytes, and only the store has them.
+      if (!opts?.fresh && knownAbsent(key)) return null;
+      countWireRead(key);
+      const res = await fetch(await internalMediaUrl(key));
+      if (res.status === 404) {
+        rememberAbsent(key);
+        return null;
+      }
+      if (!res.ok) {
+        // 🔴 NOT an absence. "The store could not be asked" and "the store does not
+        // have it" are different facts, and conflating them is the bug family met
+        // twice in one day — a 429 from a spent Cloudflare allowance rendering as a
+        // photograph that does not exist. Caching that would blank a page of faces
+        // for an hour, which is the one outcome this memo must never cause.
+        throw new Error(`[binary-store] get ${key}: ${res.status}`);
+      }
+      // A key we believed present that answers 404 is demoted above; one that
+      // answers bytes stays believed. See the memo header on why `put` is the
+      // other half of keeping a name-addressed key honest.
+      return new Uint8Array(await res.arrayBuffer());
+    },
+
+    async has(key, opts) {
+      return (await store.meta(key, opts)) !== null;
+    },
+
+    known(key) {
+      // Order matters: a lapsed absence is DROPPED by `knownAbsent`, so asking it
+      // first keeps this accessor from reporting an expiry the next real read would
+      // not honour. A positive memo has no expiry, so it needs no such care.
+      if (knownAbsent(key)) return 'absent';
+      return present.has(key) ? 'present' : 'unknown';
+    },
+
+    forgetMisses(prefix) {
+      if (prefix === undefined) {
+        const dropped = absentUntil.size;
+        absentUntil.clear();
+        return dropped;
+      }
+      let dropped = 0;
+      for (const key of [...absentUntil.keys()]) {
+        if (key.startsWith(prefix)) {
+          absentUntil.delete(key);
+          dropped++;
+        }
+      }
+      return dropped;
+    },
+
+    cacheStats() {
+      // Lapsed entries are dropped as they are met, so count only live ones —
+      // a stat that includes expired rows reads as a memo that never releases.
+      const at = now();
+      let absent = 0;
+      for (const until of absentUntil.values()) if (until > at) absent++;
+      return { present: present.size, absent };
+    },
+
+    async fetchMedia(key, init) {
+      // A one-hour stable window, matching what apps hand to browsers: the token is part
+      // of the URL, so a fresh one per request would defeat every cache between here and
+      // the object — see MediaUrlOptions.stableWindowSeconds.
+      const url = await internalMediaUrl(key, { stableWindowSeconds: 60 * 60 });
+      return await fetch(url, {
+        method: init?.method ?? 'GET',
+        // 🔴 Only when the caller HAS one. `Range: undefined` is fine, but a literal
+        // empty string is a malformed header that some origins answer 416 to.
+        ...(init?.range ? { headers: { range: init.range } } : {}),
+        ...(init?.signal ? { signal: init.signal } : {}),
+      });
+    },
+
+    async meta(key, opts) {
+      if (!opts?.fresh) {
+        const memo = present.get(key);
+        if (memo) return memo;
+        if (knownAbsent(key)) return null;
+      }
+      countWireRead(key);
+      const res = await fetch(await metaUrl(key));
+      if (res.status === 404) {
+        rememberAbsent(key);
+        return null;
+      }
+      // A throw leaves both memos untouched, deliberately — see `get`.
+      if (!res.ok) throw new Error(`[binary-store] meta ${key}: ${res.status}`);
+      const body = (await res.json()) as Partial<BlobMeta> & { size?: number };
+      const meta: BlobMeta = {
+        size: Number(body.size ?? 0),
+        mime: body.mime ?? null,
+        title: body.title ?? null,
+        checksum: body.checksum ?? null,
+        createdAt: body.createdAt,
+        updatedAt: body.updatedAt,
+      };
+      rememberPresent(key, meta);
+      return meta;
+    },
+
+    async stat(key, opts) {
+      // Prefer /meta: one index read on the server — no disk touch, no access-time
+      // bump, no body. It is the cheap answer and it is the one bs added for this.
+      //
+      // The fallback is NOT dead code, and it cannot be skipped on a null: a
+      // binary-server predating /meta answers 404 to /meta for an object it HAS, which
+      // by status alone is indistinguishable from "no such object". So a null is
+      // confirmed with the old Range probe, which every version supports. The extra
+      // round trip is paid only when the answer is "absent" or the server is old.
+      // 🔴 The MEMO is consulted for the whole of `stat`, not just for its `meta`
+      // half. Otherwise a key confirmed absent still paid the Range probe on every
+      // single call — which is most of what an absent key costs, and the reason
+      // this memo exists at all.
+      if (!opts?.fresh && knownAbsent(key)) return null;
+      try {
+        const m = await store.meta(key, opts);
+        if (m) return { size: m.size };
+      } catch {
+        // A transport/5xx failure — the probe below is the second opinion.
+      }
+      countWireRead(key);
+      const res = await fetch(await internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } });
+      if (res.status === 404) {
+        rememberAbsent(key);
+        return null;
+      }
+      if (!res.ok) throw new Error(`[binary-store] stat ${key}: ${res.status}`);
+      // 🔴 The object IS here and `/meta` said 404 — an old binary-server, which is
+      // the case this fallback exists for. `meta` recorded an absence on that 404 and
+      // it is WRONG, so it is dropped rather than left to blank the key for an hour.
+      // Not promoted to a positive memo either: a Range probe yields a size and
+      // nothing else, and a fabricated `mime: null` would be `meta()` inventing an
+      // answer it never received.
+      forget(key);
+      const contentRange = res.headers.get('content-range');
+      const totalBytes = contentRange
+        ? Number(contentRange.split('/')[1])
+        : Number(res.headers.get('content-length'));
+      return Number.isFinite(totalBytes) ? { size: totalBytes } : null;
+    },
+
+    async remove(key) {
+      // Sign a per-op, path-scoped delete token: bs requires it AND the internal secret
+      // (owner ruling #10). `internalHeaders()` throws first if no secret is configured.
+      const headers = internalHeaders();
+      const token = await signToken({ k: appKey(key), op: 'delete' }, DELETE_TOKEN_TTL_SECONDS);
+      const res = await fetch(
+        `${baseUrl}/media/${encodeKeyPath(appKey(key))}?token=${encodeURIComponent(token)}`,
+        { method: 'DELETE', headers },
+      );
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`[binary-store] remove ${key}: ${res.status}`);
+      }
+      // Gone, and we know it — a positive memo that survived a delete would hand out
+      // a URL to a 404 for the life of the process.
+      rememberAbsent(key);
+    },
+
+    async removePrefix(prefix) {
+      // The token's exact-key claim is the container's own path; bs derives the tree from it
+      // and the `?container=1` flag. Same two-barrier gate as remove().
+      const headers = internalHeaders();
+      const token = await signToken({ k: appKey(prefix), op: 'delete' }, DELETE_TOKEN_TTL_SECONDS);
+      const res = await fetch(
+        `${baseUrl}/media/${encodeKeyPath(appKey(prefix))}?container=1&token=${encodeURIComponent(token)}`,
+        { method: 'DELETE', headers },
+      );
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`[binary-store] removePrefix ${prefix}: ${res.status}`);
+      }
+      // A whole tree went; every memo under it is void. NOT recorded as absences —
+      // the keys are not enumerable from here, and a container is routinely refilled.
+      for (const key of [...present.keys()]) if (key.startsWith(prefix)) forget(key);
+      for (const key of [...absentUntil.keys()]) if (key.startsWith(prefix)) forget(key);
+    },
+  };
+
+  return store;
+}
+
+/**
+ * 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 function binaryStoreTenant(
+  appId: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const tenant = env.BINARY_STORE_TENANT?.trim() || appId?.trim();
+  if (!tenant || tenant === 'undefined' || tenant === 'null') {
+    throw new Error(
+      "[binary-store] no tenant id — pass the app's key as the first argument " +
+        '(`readBinaryStoreEnv("family")` / `createBinaryStore({ appId: "family" })`), ' +
+        'or set BINARY_STORE_TENANT. Without one every upload signs for ' +
+        `"${tenant ?? ''}/<key>" and binary-server answers 403 forbidden, which reads ` +
+        'as a bad credential rather than as a missing argument.',
+    );
+  }
+  return tenant;
+}
+
+/**
+ * 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 function resolvedMediaTenant(
+  appId: string,
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  return readBinaryStoreEnv(appId, env)?.appId ?? 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 function readBinaryStoreEnv(
+  appId: string,
+  env: Record<string, string | undefined> = process.env,
+): BinaryStoreConfig | null {
+  const baseUrl = env.BINARY_SERVER_URL?.trim();
+  const issuer = env.FILE_TOKEN_ISSUER?.trim();
+  const privateKey = env.FILE_TOKEN_PRIVATE_KEY?.trim();
+  if (!baseUrl || !issuer || !privateKey) return null;
+  return {
+    baseUrl,
+    appId: binaryStoreTenant(appId, env),
+    issuer,
+    privateKey,
+    internalSecret: env.BINARY_SERVER_INTERNAL_SECRET?.trim() || undefined,
+    internalBaseUrl: env.BINARY_SERVER_INTERNAL_URL?.trim() || undefined,
+  };
+}