cursedbelt-server 4.0.0 → 4.1.0

package/src/server/storage/binaryStore.spec.ts

@@ -0,0 +1,908 @@
+/**
+ * The suite `createBinaryStore` never had.
+ *
+ * ── 🔴 Why this file is new rather than ported ──────────────────────────────────────
+ * The task that moved this module here said "with the ported suite in the count".
+ * There was no suite to port. Measured 2026-09-17 across all five apps that carried a
+ * copy — `roms`, `family`, `music`, `vault`, `collections` — **no test anywhere
+ * constructed a real `createBinaryStore` and exercised it**. All 38 consumer sites
+ * import the TYPES (`import type { BinaryStore }`) and substitute the fake; the 1,036
+ * lines that mint the token, chunk the upload, memoise the absence and count the
+ * repeats were run only in production.
+ *
+ * That is worse than it sounds, because this module's own comments cite tests that do
+ * not exist — {@link BINARY_ABSENCE_TTL_MS} says both of its bypasses are *"proven by
+ * `forgetMisses`' tests"*, and nothing proved either. Publishing an untested 1,036-line
+ * module and then telling five apps to depend on it would have converted five private
+ * copies into one shared, still-unproven dependency, which is a worse arrangement than
+ * the fork it replaces: the same risk, now with one blast radius instead of five.
+ *
+ * So the deliverable is the module AND its first real coverage. Everything below is an
+ * assertion about a behaviour the file's own prose claims — the memo demotions, the
+ * 429-is-not-a-404 rule, the chunk fallback, the stable window, the two-barrier delete
+ * — each one a documented incident that nothing could have caught a regression of.
+ *
+ * `fetch` is stubbed at the global, so nothing here touches the network or a key
+ * server; the RSA keypair is generated in-process and the signature is verified with
+ * `node:crypto`, which is what makes the token assertions real rather than shape-deep.
+ */
+import { afterAll, afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { generateKeyPairSync, verify as cryptoVerify } from 'node:crypto';
+import {
+  AUTO_CHUNK_THRESHOLD_BYTES,
+  BINARY_ABSENCE_TTL_MS,
+  BINARY_REPEAT_THRESHOLD,
+  BINARY_REPEAT_WINDOW_MS,
+  type BinaryStoreConfig,
+  binaryStoreTenant,
+  createBinaryStore,
+  normalizePrivateKeyPem,
+  readBinaryStoreEnv,
+  repeatedBinaryKeys,
+  resetRepeatedBinaryKeys,
+  resolvedMediaTenant,
+  wantsFresh,
+} from './binaryStore';
+import { binaryStoreFakeDefaults } from './binaryStoreFake';
+
+// One 2048-bit keypair for the whole file — generation is the slow part, and every
+// assertion below only needs *a* valid PKCS8 PEM and its public half.
+const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+const PEM = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+
+const BASE = 'https://binary-server.test';
+const INTERNAL = 'http://127.0.0.1:3099';
+
+// ── the fetch stub ────────────────────────────────────────────────────────────────
+type Call = { url: string; init: RequestInit | undefined };
+let calls: Call[] = [];
+let reply: (url: string, init: RequestInit | undefined) => Response;
+const realFetch = globalThis.fetch;
+const realWarn = console.warn;
+let warnings: string[] = [];
+
+beforeEach(() => {
+  calls = [];
+  warnings = [];
+  reply = () => new Response(null, { status: 404 });
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : String(input);
+    calls.push({ url, init });
+    return Promise.resolve(reply(url, init));
+  }) as unknown as typeof fetch;
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(' '));
+  };
+  // The repeat register is module-level by design (it measures the PROCESS), so a
+  // spec that did not clear it would inherit the previous one's counts.
+  resetRepeatedBinaryKeys();
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  console.warn = realWarn;
+});
+
+afterAll(() => {
+  globalThis.fetch = realFetch;
+  console.warn = realWarn;
+});
+
+/** A store on a controllable clock. `now` drives the memos; token times use the real one. */
+let clock = 1_700_000_000_000;
+const makeStore = (over: Partial<BinaryStoreConfig> = {}) => {
+  clock = 1_700_000_000_000;
+  return createBinaryStore({
+    baseUrl: BASE,
+    appId: 'roms',
+    issuer: 'roms-issuer',
+    privateKey: PEM,
+    now: () => clock,
+    ...over,
+  });
+};
+
+/**
+ * The `?token=` of a URL, decoded.
+ *
+ * Read with a regex rather than `new URL().searchParams`: happy-dom registers its own
+ * `URL` global from this repo's test preload, and it throws `Invalid URL` on these.
+ */
+const tokenOf = (url: string): { header: any; payload: any; signed: string; sig: string } => {
+  const raw = decodeURIComponent(/[?&]token=([^&]*)/.exec(url)?.[1] ?? '');
+  const [h, p, s] = raw.split('.');
+  return {
+    header: JSON.parse(Buffer.from(h ?? '', 'base64url').toString('utf8')),
+    payload: JSON.parse(Buffer.from(p ?? '', 'base64url').toString('utf8')),
+    signed: `${h}.${p}`,
+    sig: s ?? '',
+  };
+};
+
+const lastUrl = () => calls[calls.length - 1]?.url ?? '';
+const ok = (body: BodyInit | null = null, init: ResponseInit = {}) => new Response(body, init);
+const json = (value: unknown) =>
+  new Response(JSON.stringify(value), { headers: { 'content-type': 'application/json' } });
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+describe('the token it mints', () => {
+  it('is an RS256 JWT that verifies against the tenant public key', async () => {
+    const store = makeStore();
+    const { header, payload, signed, sig } = tokenOf(await store.mediaUrl('art/zelda.png'));
+
+    expect(header).toEqual({ alg: 'RS256', typ: 'JWT' });
+    expect(payload.iss).toBe('roms-issuer');
+    // 🔴 The assertion that makes this a real test and not a shape check: binary-server
+    // holds only the PUBLIC half, so a token it cannot verify is a 403 in production.
+    expect(
+      cryptoVerify('sha256', Buffer.from(signed), publicKey, Buffer.from(sig, 'base64url')),
+      'binary-server would refuse this token',
+    ).toBe(true);
+  });
+
+  it('app-prefixes the key into the `k` claim and expires it', async () => {
+    const store = makeStore();
+    const { payload } = tokenOf(await store.mediaUrl('art/zelda.png'));
+    expect(payload.k).toBe('roms/art/zelda.png');
+    expect(payload.exp - payload.iat).toBe(60); // DOWNLOAD_TOKEN_TTL_SECONDS
+  });
+
+  it('carries filename and disposition as `fn`/`dl`', async () => {
+    const store = makeStore();
+    const { payload } = tokenOf(
+      await store.mediaUrl('rom/x', { filename: 'Zelda.nds', disposition: 'attachment' }),
+    );
+    expect(payload.fn).toBe('Zelda.nds');
+    expect(payload.dl).toBe('attachment');
+  });
+
+  it('percent-encodes each key SEGMENT and keeps `/` literal', async () => {
+    // binary-server decodes the whole path before matching it to the token, so a key
+    // whose segment contains a space or a `#` must survive as one segment.
+    const store = makeStore();
+    const url = await store.mediaUrl('box art/Zelda #1.png');
+    expect(url).toContain('/media/roms/box%20art/Zelda%20%231.png?');
+    expect(tokenOf(url).payload.k).toBe('roms/box art/Zelda #1.png');
+  });
+});
+
+describe('normalizePrivateKeyPem', () => {
+  it('accepts a raw PEM unchanged', () => {
+    expect(normalizePrivateKeyPem(`  ${PEM}  `)).toBe(PEM.trim());
+  });
+
+  it('accepts a PEM whose newlines arrived as literal backslash-n', () => {
+    // How a private key survives a round trip through an .env file. A literal `\n` is
+    // not whitespace, so the trim leaves it and the replace restores the real newline.
+    expect(normalizePrivateKeyPem(PEM.replaceAll('\n', '\\n'))).toBe(PEM);
+  });
+
+  it('accepts the base64-wrapped form `register-app` prints', () => {
+    expect(normalizePrivateKeyPem(Buffer.from(PEM).toString('base64'))).toBe(PEM);
+  });
+
+  it('refuses something that is neither, naming what it is not', () => {
+    // Buffer.from(…, 'base64') never throws — it yields garbage — so THIS is the
+    // branch that actually fires for a malformed key.
+    expect(() => normalizePrivateKeyPem('not-a-key')).toThrow(/not a PEM/);
+  });
+});
+
+describe('put', () => {
+  it('uploads whole bytes with the mime and the upload TTL', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 201 });
+    await store.put('rom/abc', new Uint8Array([1, 2, 3]), 'application/octet-stream');
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0]!;
+    expect(call.url).toContain(`${BASE}/upload/roms/rom/abc?`);
+    expect(call.init?.method).toBe('PUT');
+    expect(call.init?.headers).toEqual({ 'content-type': 'application/octet-stream' });
+    expect(new Uint8Array(call.init?.body as Uint8Array)).toEqual(new Uint8Array([1, 2, 3]));
+    expect(tokenOf(call.url).payload.exp - tokenOf(call.url).payload.iat).toBe(600);
+  });
+
+  it('sends title and immutable as query parameters only when asked', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 201 });
+    await store.put('rom/a', new Uint8Array([1]), undefined, { title: '  My ROM  ', immutable: true });
+    expect(lastUrl()).toContain('&title=My%20ROM');
+    expect(lastUrl()).toContain('&immutable=1');
+
+    calls = [];
+    await store.put('rom/b', new Uint8Array([1]));
+    expect(lastUrl()).not.toContain('title=');
+    expect(lastUrl()).not.toContain('immutable=');
+    expect(calls[0]?.init?.headers).toBeUndefined();
+  });
+
+  it('explains a 413 instead of re-raising the bare status', async () => {
+    // The 2026-08-08 incident: eight DS cartridges read as eight unrelated mysteries.
+    const store = makeStore({ autoChunkBytes: 1024 });
+    reply = () => ok(null, { status: 413 });
+    await expect(store.put('rom/big', new Uint8Array(10))).rejects.toThrow(
+      /413 — 10 bytes was refused before it reached binary-server.*lower autoChunkBytes \(currently 1024\)/s,
+    );
+  });
+
+  it('re-raises any other failure with its status', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 500 });
+    await expect(store.put('rom/a', new Uint8Array([1]))).rejects.toThrow(
+      '[binary-store] put rom/a: 500',
+    );
+  });
+
+  it('🔴 takes the CHUNKED path by itself above the threshold', async () => {
+    // The whole point of AUTO_CHUNK_THRESHOLD_BYTES: the Cloudflare Tunnel's limit is a
+    // property of this client's destination, so no call site should have to know it.
+    const store = makeStore({ autoChunkBytes: 8 });
+    reply = () => ok(null, { status: 201 });
+    await store.put('rom/big', new Uint8Array(20), 'application/octet-stream');
+
+    // Every request went to /upload-chunk, and none to /upload — the caller said `put`.
+    expect(calls.every((c) => c.url.includes('/upload-chunk/'))).toBe(true);
+    expect(tokenOf(calls[0]!.url).payload.sid).toBeString();
+
+    // …and `Infinity` restores the pre-2026-08-08 behaviour for a caller that has a
+    // measured reason to want one request.
+    calls = [];
+    const direct = makeStore({ autoChunkBytes: Number.POSITIVE_INFINITY });
+    await direct.put('rom/big', new Uint8Array(20));
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toContain('/upload/roms/rom/big?');
+  });
+
+  it('forgets both memos after a write, so a name-addressed key self-heals', async () => {
+    // roms' box art hashes the game NAME, so bytes CAN change under a key. Asserting a
+    // presence here would hand out a stale size and mime for the life of the process.
+    const store = makeStore();
+    reply = () => json({ size: 10, mime: 'image/png' });
+    await store.meta('art/zelda');
+    expect(store.known('art/zelda')).toBe('present');
+
+    reply = () => ok(null, { status: 201 });
+    await store.put('art/zelda', new Uint8Array([1]));
+    expect(store.known('art/zelda')).toBe('unknown');
+  });
+});
+
+describe('putLarge', () => {
+  it('sends ceil(size/chunk) chunks, one session id, ascending ci, constant tc', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 201 });
+    await store.putLarge('video/x', new Uint8Array(10), 'video/mp4', { chunkBytes: 4 });
+
+    expect(calls).toHaveLength(3); // ceil(10/4)
+    const claims = calls.map((c) => tokenOf(c.url).payload);
+    expect(claims.map((p) => p.ci)).toEqual([0, 1, 2]);
+    expect(claims.every((p) => p.tc === 3)).toBe(true);
+    expect(new Set(claims.map((p) => p.sid)).size).toBe(1);
+    expect(claims.every((p) => p.k === 'roms/video/x')).toBe(true);
+  });
+
+  it('🔴 sends the real BYTES of each slice, not a lazy view', async () => {
+    // The 2026-08-13 hang: a Bun.file partial view handed to fetch never sends, and
+    // 42 files / 35 GB failed 42/42 for a day with nothing in binary-server's log.
+    const store = makeStore();
+    reply = () => ok(null, { status: 201 });
+    const source = new Uint8Array([0, 1, 2, 3, 4, 5, 6]);
+    await store.putLarge('video/x', source, undefined, { chunkBytes: 3 });
+
+    const sent = calls.map((c) => [...new Uint8Array(c.init?.body as Uint8Array)]);
+    expect(sent).toEqual([[0, 1, 2], [3, 4, 5], [6]]);
+  });
+
+  it('accepts a Blob source and names the failing chunk', async () => {
+    const store = makeStore();
+    reply = (url) => ok(null, { status: url.includes('token') && calls.length === 2 ? 500 : 201 });
+    await expect(
+      store.putLarge('video/x', new Blob([new Uint8Array(6)]), undefined, { chunkBytes: 3 }),
+    ).rejects.toThrow('[binary-store] putLarge video/x chunk 2/2: 500');
+  });
+
+  it('never divides by a zero chunk size', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 201 });
+    await store.putLarge('video/x', new Uint8Array(3), undefined, { chunkBytes: 0 });
+    expect(calls).toHaveLength(3); // clamped to 1 byte per chunk, not Infinity chunks
+  });
+});
+
+describe('the negative memo', () => {
+  it('answers a second read from memory instead of the wire', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    expect(await store.get('art/missing')).toBeNull();
+    expect(calls).toHaveLength(1);
+
+    expect(await store.get('art/missing')).toBeNull();
+    expect(calls, 'the memo did not short-circuit the second read').toHaveLength(1);
+    expect(store.known('art/missing')).toBe('absent');
+  });
+
+  it('🔴 does NOT record an absence for a transport failure', async () => {
+    // family met this twice in one day: a 429 from a spent Cloudflare allowance
+    // rendering as a photograph that does not exist, cached for an hour.
+    const store = makeStore();
+    reply = () => ok(null, { status: 429 });
+    await expect(store.get('art/there')).rejects.toThrow('[binary-store] get art/there: 429');
+    expect(store.known('art/there')).toBe('unknown');
+    expect(store.cacheStats()).toEqual({ present: 0, absent: 0 });
+  });
+
+  it('lapses after the TTL and asks again', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.get('art/missing');
+    expect(calls).toHaveLength(1);
+
+    clock += BINARY_ABSENCE_TTL_MS + 1;
+    await store.get('art/missing');
+    expect(calls, 'a lapsed absence must re-ask').toHaveLength(2);
+  });
+
+  it('honours a shorter TTL when an app has a measured reason', async () => {
+    const store = makeStore({ absenceTtlMs: 1_000 });
+    reply = () => ok(null, { status: 404 });
+    await store.get('art/missing');
+    clock += 1_001;
+    await store.get('art/missing');
+    expect(calls).toHaveLength(2);
+  });
+
+  it('is bypassed by `{ fresh: true }` — the per-request escape hatch', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.get('art/missing');
+    await store.get('art/missing', { fresh: true });
+    expect(calls).toHaveLength(2);
+  });
+});
+
+describe('the positive memo', () => {
+  it('remembers a meta for ever and stops asking', async () => {
+    const store = makeStore();
+    reply = () => json({ size: 42, mime: 'image/png', title: 'Zelda', checksum: 'abc' });
+    const first = await store.meta('art/zelda');
+    expect(first).toEqual({
+      size: 42,
+      mime: 'image/png',
+      title: 'Zelda',
+      checksum: 'abc',
+      createdAt: undefined,
+      updatedAt: undefined,
+    });
+
+    clock += BINARY_ABSENCE_TTL_MS * 10;
+    expect(await store.meta('art/zelda')).toEqual(first!);
+    expect(calls, 'a present key must never expire — the key shape makes it safe').toHaveLength(1);
+  });
+
+  it('fills the missing fields with null rather than undefined', async () => {
+    const store = makeStore();
+    reply = () => json({ size: '7' });
+    expect(await store.meta('art/x')).toMatchObject({ size: 7, mime: null, title: null, checksum: null });
+  });
+
+  it('is demoted when the object turns out to be gone', async () => {
+    const store = makeStore();
+    reply = () => json({ size: 1 });
+    await store.meta('art/zelda');
+    expect(store.known('art/zelda')).toBe('present');
+
+    reply = () => ok(null, { status: 404 });
+    expect(await store.get('art/zelda')).toBeNull();
+    expect(store.known('art/zelda'), 'a 404 must demote a believed-present key').toBe('absent');
+  });
+
+  it('leaves both memos untouched when meta cannot be asked', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 503 });
+    await expect(store.meta('art/x')).rejects.toThrow('[binary-store] meta art/x: 503');
+    expect(store.known('art/x')).toBe('unknown');
+  });
+});
+
+describe('has / known / cacheStats / forgetMisses', () => {
+  it('has() is meta() as a boolean', async () => {
+    const store = makeStore();
+    reply = () => json({ size: 1 });
+    expect(await store.has('a')).toBe(true);
+    reply = () => ok(null, { status: 404 });
+    expect(await store.has('b')).toBe(false);
+  });
+
+  it('🔴 known() reports "unknown" for a key nobody has asked about', () => {
+    // Collapsing this into "absent" turns a cold process into one that draws nothing.
+    expect(makeStore().known('never-asked')).toBe('unknown');
+  });
+
+  it('known() reports a lapsed absence as unknown, not absent', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.get('a');
+    expect(store.known('a')).toBe('absent');
+    clock += BINARY_ABSENCE_TTL_MS + 1;
+    expect(store.known('a')).toBe('unknown');
+  });
+
+  it('cacheStats counts only LIVE absences', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.get('a');
+    reply = () => json({ size: 1 });
+    await store.meta('b');
+    expect(store.cacheStats()).toEqual({ present: 1, absent: 1 });
+
+    clock += BINARY_ABSENCE_TTL_MS + 1;
+    expect(store.cacheStats(), 'an expired row reads as a memo that never releases').toEqual({
+      present: 1,
+      absent: 0,
+    });
+  });
+
+  it('forgetMisses() drops every absence and reports how many', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.get('a');
+    await store.get('b');
+    expect(store.forgetMisses()).toBe(2);
+    expect(store.cacheStats().absent).toBe(0);
+  });
+
+  it('🔴 forgetMisses(prefix) is a REPAIR, not a cache flush', async () => {
+    // The positives survive, so proving a fix costs only the keys that were missing.
+    const store = makeStore();
+    reply = () => json({ size: 1 });
+    await store.meta('keep/me');
+    reply = () => ok(null, { status: 404 });
+    await store.get('art/one');
+    await store.get('art/two');
+    await store.get('other/three');
+
+    expect(store.forgetMisses('art/')).toBe(2);
+    expect(store.known('other/three')).toBe('absent');
+    expect(store.known('keep/me'), 'a positive memo must survive a repair').toBe('present');
+  });
+});
+
+describe('stat', () => {
+  it('prefers /meta and pays no Range probe when it answers', async () => {
+    const store = makeStore();
+    reply = () => json({ size: 99 });
+    expect(await store.stat('a')).toEqual({ size: 99 });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toContain('/meta/');
+  });
+
+  it('🔴 falls back to the Range probe, and UNDOES the wrong absence', async () => {
+    // A binary-server predating /meta answers 404 for an object it HAS — indistinguishable
+    // by status from "no such object", so the null has to be confirmed.
+    const store = makeStore();
+    reply = (url) =>
+      url.includes('/meta/')
+        ? ok(null, { status: 404 })
+        : ok(null, { status: 206, headers: { 'content-range': 'bytes 0-0/4096' } });
+
+    expect(await store.stat('a')).toEqual({ size: 4096 });
+    expect(
+      store.known('a'),
+      'meta recorded an absence that was WRONG; leaving it blanks the key for an hour',
+    ).toBe('unknown');
+  });
+
+  it('records the absence when both agree the key is gone', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    expect(await store.stat('a')).toBeNull();
+    expect(store.known('a')).toBe('absent');
+  });
+
+  it('🔴 short-circuits the WHOLE of stat on a live absence', async () => {
+    // Not just its meta half — otherwise a key confirmed absent still paid the Range
+    // probe on every call, which is most of what an absent key costs.
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    await store.stat('a');
+    const after = calls.length;
+    expect(await store.stat('a')).toBeNull();
+    expect(calls.length, 'stat must consult the memo before probing').toBe(after);
+  });
+
+  it('falls back to content-length when there is no content-range', async () => {
+    const store = makeStore();
+    reply = (url) =>
+      url.includes('/meta/')
+        ? ok(null, { status: 404 })
+        : ok(null, { status: 200, headers: { 'content-length': '7' } });
+    expect(await store.stat('a')).toEqual({ size: 7 });
+  });
+});
+
+describe('the repeat-key counter', () => {
+  it('stays silent on ordinary traffic', async () => {
+    const store = makeStore();
+    reply = () => ok(new Uint8Array([1]));
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD - 1; i++) await store.get('art/a');
+    expect(repeatedBinaryKeys(() => clock)).toEqual([]);
+    expect(warnings).toEqual([]);
+  });
+
+  it('🔴 reports a key at the threshold, and warns exactly once', async () => {
+    // Every quota incident this fleet has had was this shape: one key, over and over,
+    // visible in Cloudflare's top-talker list and in nobody's code.
+    const store = makeStore();
+    reply = () => ok(new Uint8Array([1]));
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD + 5; i++) await store.get('art/a');
+
+    const hot = repeatedBinaryKeys(() => clock);
+    expect(hot).toHaveLength(1);
+    expect(hot[0]).toMatchObject({ tenant: 'roms', key: 'art/a', windowMs: BINARY_REPEAT_WINDOW_MS });
+    expect(hot[0]!.reads).toBeGreaterThanOrEqual(BINARY_REPEAT_THRESHOLD);
+    expect(warnings, 'a line per read would be the same storm in the log file').toHaveLength(1);
+    expect(warnings[0]).toContain('has been read 50 times');
+  });
+
+  it('🔴 does not count memo hits — the memo working is the cure', async () => {
+    const store = makeStore();
+    reply = () => ok(null, { status: 404 });
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD + 5; i++) await store.get('art/missing');
+    expect(calls, 'only the first read reached the wire').toHaveLength(1);
+    expect(
+      repeatedBinaryKeys(() => clock),
+      'the alarm would otherwise fire loudest on the apps that fixed themselves',
+    ).toEqual([]);
+  });
+
+  it('drops a burst that stopped, instead of accusing for ever', async () => {
+    const store = makeStore();
+    reply = () => ok(new Uint8Array([1]));
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD; i++) await store.get('art/a');
+    expect(repeatedBinaryKeys(() => clock)).toHaveLength(1);
+    expect(repeatedBinaryKeys(() => clock + BINARY_REPEAT_WINDOW_MS)).toEqual([]);
+  });
+
+  it('reports the worst offender first', async () => {
+    const store = makeStore();
+    reply = () => ok(new Uint8Array([1]));
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD; i++) await store.get('quiet');
+    for (let i = 0; i < BINARY_REPEAT_THRESHOLD + 10; i++) await store.get('loud');
+    expect(repeatedBinaryKeys(() => clock).map((r) => r.key)).toEqual(['loud', 'quiet']);
+  });
+});
+
+describe('mediaUrl and the stable window', () => {
+  it('🔴 mints a byte-identical URL inside one window', async () => {
+    // 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 re-downloads bytes it already has.
+    const store = makeStore();
+    const a = await store.mediaUrl('art/z', { stableWindowSeconds: 3600 });
+    const b = await store.mediaUrl('art/z', { stableWindowSeconds: 3600 });
+    expect(b).toBe(a);
+
+    const { payload } = tokenOf(a);
+    expect(payload.iat % 3600, 'iat must be snapped to the window, not to the clock').toBe(0);
+    expect(payload.exp - payload.iat, 'valid for TWO windows').toBe(7200);
+  });
+
+  it('mints a fresh token per call when no window is asked for', async () => {
+    const store = makeStore();
+    const a = tokenOf(await store.mediaUrl('art/z'));
+    expect(a.payload.iat % 3600 === 0 && a.payload.exp - a.payload.iat === 7200).toBe(false);
+  });
+
+  it('honours an explicit ttlSeconds', async () => {
+    const store = makeStore();
+    const { payload } = tokenOf(await store.mediaUrl('art/z', { ttlSeconds: 15 }));
+    expect(payload.exp - payload.iat).toBe(15);
+  });
+
+  it('🔴 always uses the PUBLIC origin — a browser cannot resolve loopback', async () => {
+    const store = makeStore({ internalBaseUrl: INTERNAL });
+    expect(await store.mediaUrl('art/z')).toStartWith(`${BASE}/media/`);
+  });
+
+  it('strips a trailing slash from the configured base', async () => {
+    const store = makeStore({ baseUrl: `${BASE}///` });
+    expect(await store.mediaUrl('a')).toStartWith(`${BASE}/media/`);
+  });
+});
+
+describe('mediaPrefixUrl', () => {
+  it('🔴 signs the PREFIX but points at the master', async () => {
+    // An HLS player resolves rung playlists RELATIVE to the master's URL and discards
+    // the query string, so only a prefix token can authorize the tree.
+    const store = makeStore();
+    const url = await store.mediaPrefixUrl('video/x/hls', 'video/x/hls/master.m3u8');
+    expect(url).toContain('/media/roms/video/x/hls/master.m3u8?');
+
+    const { payload } = tokenOf(url);
+    expect(payload.p).toBe('roms/video/x/hls');
+    expect(payload.k, 'an exact-key token 403s every segment').toBeUndefined();
+  });
+
+  it('takes a stable window too', async () => {
+    const store = makeStore();
+    const a = await store.mediaPrefixUrl('t', 't/m.m3u8', { stableWindowSeconds: 3600 });
+    expect(await store.mediaPrefixUrl('t', 't/m.m3u8', { stableWindowSeconds: 3600 })).toBe(a);
+  });
+});
+
+describe('internalBaseUrl — reading bytes without leaving the box', () => {
+  it('🔴 sends get/meta/stat to the loopback origin', async () => {
+    // 2026-09-08: family made 15,689 server-side reads that went out to the public name
+    // and back to read bytes from a daemon on the same Mac, then met a 429 wall.
+    const store = makeStore({ internalBaseUrl: INTERNAL });
+    reply = () => json({ size: 1 });
+    await store.meta('a');
+    expect(lastUrl()).toStartWith(`${INTERNAL}/meta/`);
+
+    reply = () => ok(new Uint8Array([1]));
+    await store.get('b');
+    expect(lastUrl()).toStartWith(`${INTERNAL}/media/`);
+  });
+
+  it('defaults to the public base when the deployment does not share the Mac', async () => {
+    const store = makeStore();
+    reply = () => ok(new Uint8Array([1]));
+    await store.get('b');
+    expect(lastUrl()).toStartWith(`${BASE}/media/`);
+  });
+});
+
+describe('fetchMedia', () => {
+  it('forwards a Range header untouched — Range IS seeking', async () => {
+    const store = makeStore({ internalBaseUrl: INTERNAL });
+    reply = () => ok(null, { status: 206 });
+    const res = await store.fetchMedia('song/a', { range: 'bytes=100-200' });
+
+    expect(res.status).toBe(206);
+    expect(calls[0]?.init?.headers).toEqual({ range: 'bytes=100-200' });
+    expect(calls[0]?.url).toStartWith(`${INTERNAL}/media/`);
+  });
+
+  it('🔴 sends NO header at all when the caller has no range', async () => {
+    // A literal empty string is a malformed header some origins answer 416 to.
+    const store = makeStore();
+    reply = () => ok(null);
+    await store.fetchMedia('song/a', { range: '' });
+    expect(calls[0]?.init?.headers).toBeUndefined();
+
+    calls = [];
+    await store.fetchMedia('song/a', { range: null });
+    expect(calls[0]?.init?.headers).toBeUndefined();
+  });
+
+  it('honours HEAD and forwards an abort signal', async () => {
+    const store = makeStore();
+    reply = () => ok(null);
+    const controller = new AbortController();
+    await store.fetchMedia('song/a', { method: 'HEAD', signal: controller.signal });
+    expect(calls[0]?.init?.method).toBe('HEAD');
+    expect(calls[0]?.init?.signal).toBe(controller.signal);
+  });
+
+  it('uses a one-hour stable window so caches between here and the object can work', async () => {
+    const store = makeStore();
+    reply = () => ok(null);
+    await store.fetchMedia('song/a');
+    await store.fetchMedia('song/a');
+    expect(calls[0]?.url).toBe(calls[1]?.url ?? '');
+    expect(tokenOf(calls[0]!.url).payload.iat % 3600).toBe(0);
+  });
+});
+
+describe('remove and removePrefix — the two-barrier gate', () => {
+  it('🔴 refuses without the internal secret rather than sending a bare token', async () => {
+    await expect(makeStore().remove('a')).rejects.toThrow(/requires internalSecret/);
+    expect(calls, 'nothing may go on the wire').toHaveLength(0);
+  });
+
+  it('sends BOTH the secret header and an op:delete token', async () => {
+    const store = makeStore({ internalSecret: 's3cret' });
+    reply = () => ok(null, { status: 204 });
+    await store.remove('rom/a');
+
+    expect(calls[0]?.init?.method).toBe('DELETE');
+    expect(calls[0]?.init?.headers).toEqual({ 'x-internal-secret': 's3cret' });
+    const { payload } = tokenOf(calls[0]!.url);
+    expect(payload.op).toBe('delete');
+    expect(payload.k).toBe('roms/rom/a');
+    expect(payload.exp - payload.iat).toBe(120);
+  });
+
+  it('tolerates a 404 and still records the absence', async () => {
+    const store = makeStore({ internalSecret: 's' });
+    reply = () => ok(null, { status: 404 });
+    await store.remove('rom/a');
+    expect(store.known('rom/a'), 'a surviving positive memo would link to a 404').toBe('absent');
+  });
+
+  it('re-raises a real delete failure', async () => {
+    const store = makeStore({ internalSecret: 's' });
+    reply = () => ok(null, { status: 500 });
+    await expect(store.remove('rom/a')).rejects.toThrow('[binary-store] remove rom/a: 500');
+  });
+
+  it('removePrefix flags the container and voids every memo under it', async () => {
+    const store = makeStore({ internalSecret: 's' });
+    reply = () => json({ size: 1 });
+    await store.meta('tree/a');
+    reply = () => ok(null, { status: 404 });
+    await store.get('tree/b');
+    await store.get('elsewhere/c');
+
+    reply = () => ok(null, { status: 204 });
+    await store.removePrefix('tree/');
+
+    expect(lastUrl()).toContain('?container=1&token=');
+    expect(tokenOf(lastUrl()).payload.op).toBe('delete');
+    expect(store.known('tree/a')).toBe('unknown');
+    // 🔴 NOT recorded as absences: the keys are not enumerable from here and a
+    // container is routinely refilled.
+    expect(store.known('tree/b')).toBe('unknown');
+    expect(store.known('elsewhere/c'), 'a sibling tree is untouched').toBe('absent');
+  });
+});
+
+describe('wantsFresh — the owner`s hard refresh', () => {
+  it('reads a browser hard refresh off either header', () => {
+    expect(wantsFresh(new Headers({ 'cache-control': 'no-cache' }))).toBe(true);
+    expect(wantsFresh(new Headers({ 'cache-control': 'NO-CACHE, max-age=0' }))).toBe(true);
+    expect(wantsFresh(new Headers({ pragma: 'no-cache' }))).toBe(true);
+  });
+
+  it('is false for an ordinary request', () => {
+    expect(wantsFresh(new Headers())).toBe(false);
+    expect(wantsFresh(new Headers({ 'cache-control': 'max-age=0' }))).toBe(false);
+  });
+
+  it('accepts a Request-shaped object as well as bare Headers', () => {
+    expect(wantsFresh({ headers: new Headers({ pragma: 'no-cache' }) })).toBe(true);
+  });
+});
+
+describe('tenant resolution', () => {
+  it('prefers BINARY_STORE_TENANT over the app key, so a stage gets its own', () => {
+    // 2026-08-21: a literal tenant made an ephemeral stage structurally unable to store
+    // a byte — it signed as `collections-stage` while addressing `collections/…`.
+    expect(binaryStoreTenant('collections', { BINARY_STORE_TENANT: 'collections-stage' })).toBe(
+      'collections-stage',
+    );
+    expect(binaryStoreTenant('collections', {})).toBe('collections');
+  });
+
+  it('🔴 throws on a blank tenant rather than signing for "undefined/<key>"', () => {
+    // binary-server answers a bare {"error":"forbidden"}, which reads as a broken
+    // credential — and was filed as one. The check has to live on this side of the wire.
+    for (const bad of ['', '   ', 'undefined', 'null']) {
+      expect(() => binaryStoreTenant(bad, {}), `"${bad}" must not pass`).toThrow(/no tenant id/);
+    }
+    expect(() => binaryStoreTenant(undefined as unknown as string, {})).toThrow(/no tenant id/);
+  });
+
+  it('resolvedMediaTenant answers null for a store-less shell instead of throwing', () => {
+    // The same question as binaryStoreTenant, asked where a throw would 500 /healthz.
+    expect(resolvedMediaTenant('roms', {})).toBeNull();
+    expect(
+      resolvedMediaTenant('roms', {
+        BINARY_SERVER_URL: BASE,
+        FILE_TOKEN_ISSUER: 'i',
+        FILE_TOKEN_PRIVATE_KEY: 'k',
+        BINARY_STORE_TENANT: 'roms-stage',
+      }),
+    ).toBe('roms-stage');
+  });
+});
+
+describe('readBinaryStoreEnv', () => {
+  const full = {
+    BINARY_SERVER_URL: BASE,
+    FILE_TOKEN_ISSUER: 'roms-issuer',
+    FILE_TOKEN_PRIVATE_KEY: PEM,
+  };
+
+  it('returns null unless all three required vars are present', () => {
+    expect(readBinaryStoreEnv('roms', {})).toBeNull();
+    for (const key of Object.keys(full)) {
+      const partial = { ...full, [key]: '  ' };
+      expect(readBinaryStoreEnv('roms', partial), `${key} blank must disable the store`).toBeNull();
+    }
+  });
+
+  it('maps the standard secrets-file surface onto the config', () => {
+    expect(
+      readBinaryStoreEnv('roms', {
+        ...full,
+        BINARY_SERVER_INTERNAL_SECRET: 's3cret',
+        BINARY_SERVER_INTERNAL_URL: INTERNAL,
+      }),
+    ).toEqual({
+      baseUrl: BASE,
+      appId: 'roms',
+      issuer: 'roms-issuer',
+      // Trimmed on the way out of the env — a trailing newline in a secrets file is
+      // invisible and must not reach `createPrivateKey`.
+      privateKey: PEM.trim(),
+      internalSecret: 's3cret',
+      internalBaseUrl: INTERNAL,
+    });
+  });
+
+  it('leaves the optional fields undefined rather than empty', () => {
+    const cfg = readBinaryStoreEnv('roms', { ...full, BINARY_SERVER_INTERNAL_SECRET: '   ' });
+    expect(cfg?.internalSecret).toBeUndefined();
+    expect(cfg?.internalBaseUrl).toBeUndefined();
+  });
+
+  it('produces a config that actually signs', async () => {
+    const store = createBinaryStore(readBinaryStoreEnv('roms', full)!);
+    const { signed, sig } = tokenOf(await store.mediaUrl('a'));
+    expect(cryptoVerify('sha256', Buffer.from(signed), publicKey, Buffer.from(sig, 'base64url'))).toBe(true);
+  });
+});
+
+describe('the threshold constant', () => {
+  it('is 64 MiB — early is free, late is a 413', () => {
+    expect(AUTO_CHUNK_THRESHOLD_BYTES).toBe(64 * 1024 * 1024);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════════
+
+describe('binaryStoreFakeDefaults', () => {
+  it('satisfies every member of the interface', () => {
+    // 🔴 The assertion the fake exists for: when a method is added to `BinaryStore`,
+    // THIS is what fails to compile, in the package that owns the interface — instead
+    // of twenty-two suites in apps whose commits nobody is looking at.
+    const fake = binaryStoreFakeDefaults('collections');
+    const real = makeStore();
+    expect(Object.keys(fake).sort()).toEqual(Object.keys(real).sort());
+  });
+
+  it('answers "not here" without inventing a result', async () => {
+    const fake = binaryStoreFakeDefaults('collections');
+    expect(fake.appId).toBe('collections');
+    expect(await fake.get('a')).toBeNull();
+    expect(await fake.meta('a')).toBeNull();
+    expect(await fake.stat('a')).toBeNull();
+    expect(await fake.has('a')).toBe(false);
+    expect((await fake.fetchMedia('a')).status).toBe(404);
+    expect(fake.cacheStats()).toEqual({ present: 0, absent: 0 });
+  });
+
+  it('🔴 knows nothing, rather than claiming a key is absent', () => {
+    // "absent" would make a listing route's memo-only branch look exercised when
+    // nothing was ever memoized — the one thing a test of that branch is for.
+    expect(binaryStoreFakeDefaults('c').known('anything')).toBe('unknown');
+  });
+
+  it('🔴 never lies about work done', () => {
+    // An app's repair route reports this number to the owner; a fabricated one makes a
+    // broken repair read as a working one.
+    expect(binaryStoreFakeDefaults('c').forgetMisses()).toBe(0);
+    expect(binaryStoreFakeDefaults('c').forgetMisses('art/')).toBe(0);
+  });
+
+  it('carries the key in mediaUrl, and BOTH names in mediaPrefixUrl', async () => {
+    const fake = binaryStoreFakeDefaults('collections');
+    expect(await fake.mediaUrl('art/z')).toContain('/collections/art/z');
+    const prefixed = await fake.mediaPrefixUrl('tree', 'tree/master.m3u8');
+    // Signing the wrong one 403s every segment while the master itself loads fine.
+    expect(prefixed).toContain('/collections/tree/master.m3u8');
+    expect(prefixed).toContain('p=tree');
+  });
+
+  it('is inert on every mutator', async () => {
+    const fake = binaryStoreFakeDefaults('c');
+    await fake.put('a', new Uint8Array([1]));
+    await fake.putLarge('a', new Uint8Array([1]));
+    await fake.remove('a');
+    await fake.removePrefix('a');
+    expect(calls, 'a fake must never reach the network').toHaveLength(0);
+    expect(await fake.signToken({ k: 'c/a' }, 60)).toBe('fake-token');
+  });
+});