cursedbelt-server 3.0.1 → 4.1.0

package/dist/server/master-lock/lockPage.d.ts

@@ -22,6 +22,15 @@ export interface LockPageOptions {
 export declare function lockPageHtml(options: LockPageOptions): string;
 /** The stylesheet. Follows the viewer's theme and commits to nothing else. */
 export declare const LOCK_STYLE = ":root{color-scheme:light dark;\n  --ml-bg:#f4f5f7;--ml-card:#ffffff;--ml-text:#14171c;--ml-muted:#69707c;--ml-border:#d9dde3;\n  --ml-accent:#1f6feb;--ml-accent-text:#ffffff;--ml-danger:#b42318;\n  --ml-shadow:0 18px 48px rgba(16,18,22,.14)}\n@media (prefers-color-scheme:dark){:root{\n  --ml-bg:#0d0f13;--ml-card:#171a20;--ml-text:#e7eaef;--ml-muted:#8b93a1;--ml-border:#2b3039;\n  --ml-accent:#4f8cf7;--ml-accent-text:#0b0d11;--ml-danger:#f97066;\n  --ml-shadow:0 18px 48px rgba(0,0,0,.55)}}\n*{box-sizing:border-box}\nbody{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;\n  background:var(--ml-bg);color:var(--ml-text);\n  font:15px/1.55 ui-sans-serif,system-ui,-apple-system,\"Segoe UI\",sans-serif}\n.card{width:100%;max-width:23rem;background:var(--ml-card);border:1px solid var(--ml-border);\n  border-radius:16px;padding:28px 26px 24px;box-shadow:var(--ml-shadow);text-align:center}\n.glyph{font-size:30px;line-height:1;margin-bottom:10px}\nh1{margin:0 0 6px;font-size:18px;font-weight:650;letter-spacing:-.01em}\n.note{margin:0 0 20px;font-size:13px;color:var(--ml-muted)}\n.field{display:block;text-align:left;margin-bottom:14px}\n.field span{display:block;font-size:12px;font-weight:600;color:var(--ml-muted);margin-bottom:6px}\ninput{width:100%;height:40px;padding:0 12px;border:1px solid var(--ml-border);border-radius:9px;\n  background:var(--ml-bg);color:inherit;font:inherit}\ninput:focus{outline:2px solid var(--ml-accent);outline-offset:1px;border-color:transparent}\nbutton{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-accent);\n  color:var(--ml-accent-text);font:inherit;font-weight:600;cursor:pointer}\nbutton[disabled]{opacity:.6;cursor:progress}\n.status{margin:14px 0 0;min-height:1.2em;font-size:12.5px;color:var(--ml-muted)}\n.status[data-tone=\"error\"]{color:var(--ml-danger)}\n.field span em{font-style:normal;font-weight:500;text-transform:none;opacity:.7}\nbutton.quiet{margin-top:10px;height:32px;background:none;color:var(--ml-muted);font-weight:500;\n  font-size:12.5px;text-decoration:underline;text-underline-offset:3px}\nbutton.quiet:hover{color:var(--ml-text)}\nbutton.quiet[disabled]{opacity:.5}\n.hints{margin:10px 0 0;padding:12px 14px;text-align:left;border:1px solid var(--ml-border);\n  border-radius:10px;background:var(--ml-bg);font-size:12.5px}\n.hints dt{font-weight:650;color:var(--ml-text)}\n.hints dd{margin:2px 0 10px;color:var(--ml-muted);overflow-wrap:anywhere}\n.hints dd:last-child{margin-bottom:0}\n";
+/**
+ * 🔴 The ONE browser copy of `deriveMasterLockVerifier`, shared by every page this feature
+ * serves. Pinned by `lockPage.spec.ts`, which evaluates it and compares against the
+ * TypeScript one. Do not "tidy" it apart, and do not write a second copy — interpolate this.
+ *
+ * It ends by publishing the function on `globalThis`, which is the seam the spec pulls it
+ * out through and the seam the accounts page's script calls it back through.
+ */
+export declare const MASTER_LOCK_DERIVE_SOURCE = "function unb64u(text) {\n  const padded = text.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const binary = atob(padded + \"=\".repeat((4 - (padded.length % 4)) % 4));\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);\n  return out;\n}\nfunction b64u(bytes) {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\nasync function pbkdf2(material, salt, iterations) {\n  const key = await crypto.subtle.importKey(\"raw\", material, \"PBKDF2\", false, [\"deriveBits\"]);\n  const bits = await crypto.subtle.deriveBits(\n    { name: \"PBKDF2\", salt: salt, iterations: iterations, hash: \"SHA-256\" }, key, 256);\n  return new Uint8Array(bits);\n}\nasync function deriveVerifier(password, kdf) {\n  const salt = unb64u(kdf.salt);\n  const bytes = new TextEncoder().encode(password);\n  const kek = await pbkdf2(bytes, salt, kdf.iter);\n  const joined = new Uint8Array(kek.length + bytes.length);\n  joined.set(kek, 0);\n  joined.set(bytes, kek.length);\n  return b64u(await pbkdf2(joined, salt, 1));\n}\nglobalThis.__masterLockDerive = deriveVerifier;";
 /**
  * The page's script.
  *

package/dist/server/master-lock/lockPage.js

@@ -12,13 +12,18 @@
  * keep a wall that strict. Two same-origin files cost one round trip each and let the page
  * ship under `script-src 'self'` with no nonce plumbing.
  *
- * ── 🔴 The derivation in `LOCK_SCRIPT` is a HAND COPY of `deriveMasterLockVerifier` ──────
+ * ── 🔴 The derivation in `MASTER_LOCK_DERIVE_SOURCE` is a HAND COPY of
+ *      `deriveMasterLockVerifier` ────────────────────────────────────────────
  * It cannot import it: this file is served to a browser as plain text, outside every build.
  * A copy that drifts derives a verifier that can never match, and the symptom would be "my
  * correct password is refused" — the same shape of bug that cost `apps/collections` a day.
- * So `lockPage.spec.ts` EVALUATES the script's function out of this source and asserts it
- * agrees with the TypeScript one on a fixed vector. Change one, the spec fails until you
- * change the other.
+ * So `lockPage.spec.ts` EVALUATES the function out of this source and asserts it agrees with
+ * the TypeScript one on a fixed vector. Change one, the spec fails until you change the other.
+ *
+ * 🔴 It is its OWN exported constant, and there is exactly ONE of it. `accountsPage.ts` serves
+ * a second browser script that has to derive the same way — a second hand copy would be a
+ * second thing to keep in step, and the pinning spec would only be watching one of them. Both
+ * scripts interpolate this string, and the spec asserts that they do.
  */
 import { MASTER_LOCK_PATHS } from "cursedbelt-core/master-lock";
 const escapeHtml = (value) => value.replace(/[&<>"']/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch] ?? ch);
@@ -125,35 +130,14 @@ button.quiet[disabled]{opacity:.5}
 .hints dd:last-child{margin-bottom:0}
 `;
 /**
- * The page's script.
+ * 🔴 The ONE browser copy of `deriveMasterLockVerifier`, shared by every page this feature
+ * serves. Pinned by `lockPage.spec.ts`, which evaluates it and compares against the
+ * TypeScript one. Do not "tidy" it apart, and do not write a second copy — interpolate this.
  *
- * Derives in the browser and sends only the verifier — the password itself never crosses
- * the network, which is what makes "saved nowhere" true rather than aspirational.
- *
- * 600,000 PBKDF2 rounds take a beat on a phone, so the button says so; a page that looks
- * frozen gets clicked again, and every extra click is another 600k rounds.
+ * It ends by publishing the function on `globalThis`, which is the seam the spec pulls it
+ * out through and the seam the accounts page's script calls it back through.
  */
-export const LOCK_SCRIPT = `const paths = ${JSON.stringify(MASTER_LOCK_PATHS)};
-
-const form = document.getElementById("ml-form");
-const input = document.getElementById("ml-input");
-const confirmInput = document.getElementById("ml-confirm");
-const hintInput = document.getElementById("ml-hint");
-const submit = document.getElementById("ml-submit");
-const status = document.getElementById("ml-status");
-const forgot = document.getElementById("ml-forgot");
-const hints = document.getElementById("ml-hints");
-
-function say(message, tone) {
-  status.textContent = message;
-  if (tone) status.setAttribute("data-tone", tone);
-  else status.removeAttribute("data-tone");
-}
-
-// ── derivation ───────────────────────────────────────────────────────────────
-// 🔴 Byte-identical to deriveMasterLockVerifier in cursedbelt-core/master-lock. Pinned by
-// lockPage.spec.ts, which evaluates THIS function and compares. Do not "tidy" it apart.
-function unb64u(text) {
+export const MASTER_LOCK_DERIVE_SOURCE = `function unb64u(text) {
   const padded = text.replace(/-/g, "+").replace(/_/g, "/");
   const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
   const out = new Uint8Array(binary.length);
@@ -180,13 +164,37 @@ async function deriveVerifier(password, kdf) {
   joined.set(bytes, kek.length);
   return b64u(await pbkdf2(joined, salt, 1));
 }
-globalThis.__masterLockDerive = deriveVerifier;
+globalThis.__masterLockDerive = deriveVerifier;`;
+/**
+ * The page's script.
+ *
+ * Derives in the browser and sends only the verifier — the password itself never crosses
+ * the network, which is what makes "saved nowhere" true rather than aspirational.
+ *
+ * 600,000 PBKDF2 rounds take a beat on a phone, so the button says so; a page that looks
+ * frozen gets clicked again, and every extra click is another 600k rounds.
+ */
+export const LOCK_SCRIPT = `const paths = ${JSON.stringify(MASTER_LOCK_PATHS)};
+
+// ── derivation ───────────────────────────────────────────────────────────────
+${MASTER_LOCK_DERIVE_SOURCE}
+
+const form = document.getElementById("ml-form");
+const input = document.getElementById("ml-input");
+const confirmInput = document.getElementById("ml-confirm");
+const hintInput = document.getElementById("ml-hint");
+const submit = document.getElementById("ml-submit");
+const status = document.getElementById("ml-status");
+const forgot = document.getElementById("ml-forgot");
+const hints = document.getElementById("ml-hints");
+
+function say(message, tone) {
+  status.textContent = message;
+  if (tone) status.setAttribute("data-tone", tone);
+  else status.removeAttribute("data-tone");
+}
 
 // ── the page ─────────────────────────────────────────────────────────────────
-// 🔴 Everything below this line touches \`document\` beyond \`getElementById\`, and
-// lockPage.spec.ts cuts the source at the marker above to evaluate the derivation with a
-// stub. Keep page state here, not in the prelude, or that test throws instead of running.
-//
 // Rendered by the server from THIS principal's own record. The server re-decides it on
 // every POST, so this only chooses which form to submit — it cannot grant anything.
 const enrolling = document.body.dataset.mode === "enroll";

package/dist/server/media-bun/streaming.d.ts

@@ -53,7 +53,6 @@ export declare const hlsLadderArgs: (inPath: string, outDir: string, opts: {
     heights: number[];
     crf: number;
     hasAudio: boolean;
-    keyInfoFile?: string;
 }) => string[];
 /** Poster: a frame `atSeconds` in (default ~1s, to skip black intros), scaled to the library
  *  width, as JPEG. Pass a smaller seek (or 0) for very short clips — seeking past EOF yields no

package/dist/server/media-bun/streaming.js

@@ -142,7 +142,7 @@ export const hlsLadderArgs = (inPath, outDir, opts) => {
     const varMap = hs
         .map((h, i) => (opts.hasAudio ? `v:${i},a:${i},name:${h}` : `v:${i},name:${h}`))
         .join(' ');
-    args.push('-f', 'hls', '-hls_time', '4', '-hls_playlist_type', 'vod', '-hls_segment_type', 'mpegts', ...(opts.keyInfoFile ? ['-hls_key_info_file', opts.keyInfoFile] : []), '-master_pl_name', 'master.m3u8', '-hls_segment_filename', path.join(outDir, '%v', 'seg_%05d.ts'), '-var_stream_map', varMap, path.join(outDir, '%v', 'playlist.m3u8'));
+    args.push('-f', 'hls', '-hls_time', '4', '-hls_playlist_type', 'vod', '-hls_segment_type', 'mpegts', '-master_pl_name', 'master.m3u8', '-hls_segment_filename', path.join(outDir, '%v', 'seg_%05d.ts'), '-var_stream_map', varMap, path.join(outDir, '%v', 'playlist.m3u8'));
     return args;
 };
 /** Poster: a frame `atSeconds` in (default ~1s, to skip black intros), scaled to the library

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

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