cursedbelt-server 3.0.1 → 4.1.0

package/dist/server/storage/binaryStore.js

@@ -0,0 +1,739 @@
+/**
+ * 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 } from 'node:crypto';
+/*
+ * ── 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();
+/** Bounded: a genuinely runaway app must not turn this into a leak. */
+const MAX_TRACKED_REPEATS = 50;
+function recordRepeat(tenant, key, count, at) {
+    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 = Date.now) {
+    const at = now();
+    const live = [];
+    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() {
+    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) {
+    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;
+/**
+ * 🔴 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) {
+    const trimmed = raw.trim();
+    if (trimmed.includes('-----BEGIN'))
+        return trimmed.replaceAll('\\n', '\n');
+    let decoded;
+    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) => Buffer.from(bytes).toString('base64url');
+/** Keys may contain `/` as a real separator; each SEGMENT is percent-encoded
+ *  because the server decodes the whole path before matching it to the token. */
+const encodeKeyPath = (key) => key.split('/').map(encodeURIComponent).join('/');
+export function createBinaryStore(cfg) {
+    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();
+    const absentUntil = new Map();
+    /** A live negative memo, or `false` (lapsed entries are dropped as they are met). */
+    const knownAbsent = (key) => {
+        const until = absentUntil.get(key);
+        if (until === undefined)
+            return false;
+        if (until > now())
+            return true;
+        absentUntil.delete(key);
+        return false;
+    };
+    const rememberPresent = (key, meta) => {
+        absentUntil.delete(key);
+        present.set(key, meta);
+    };
+    const rememberAbsent = (key) => {
+        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) => {
+        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();
+    const countWireRead = (key) => {
+        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 = null;
+    const privateKey = () => {
+        keyObject ??= createPrivateKey(normalizePrivateKeyPem(cfg.privateKey));
+        return keyObject;
+    };
+    const signToken = async (claims, ttlSeconds, 
+    /** Snap `iat` down to a multiple of this so the whole token is byte-stable
+     *  inside one window — see {@link MediaUrlOptions.stableWindowSeconds}. */
+    windowSeconds) => {
+        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) => `${cfg.appId}/${key}`;
+    const mediaUrl = async (key, opts) => {
+        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, master, opts) => {
+        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, opts) => (await mediaUrl(key, opts)).replace(baseUrl, internalBaseUrl);
+    /** `/meta` authorizes with the same token shape as `/media` — an exact-key claim. */
+    const metaUrl = async (key) => {
+        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 = () => {
+        if (!cfg.internalSecret) {
+            throw new Error('[binary-store] remove requires internalSecret (BINARY_SERVER_INTERNAL_SECRET)');
+        }
+        return { 'x-internal-secret': cfg.internalSecret };
+    };
+    const store = {
+        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,
+            });
+            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]);
+            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());
+            const meta = {
+                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, env = process.env) {
+    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, env = process.env) {
+    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, env = process.env) {
+    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,
+    };
+}