cursedbelt-server 1.0.0

package/src/server/sqlite/viewer.ts

@@ -0,0 +1,72 @@
+import type { Database } from 'bun:sqlite';
+import { Hono } from 'hono';
+import { ApiError, toErrorEnvelope } from '../errors';
+import {
+  listSqliteTables,
+  NotReadOnlyError,
+  readSqliteTable,
+  runReadonlySqlite,
+  UnknownTableError,
+} from './browse';
+
+/**
+ * A read-only SQLite browser as a Hono sub-app — a thin HTTP wrapper over the
+ * Hono-free primitives in `browse.ts` (the same primitives a cursedshell plugin or
+ * a bespoke-transport app consumes directly). Mount it behind the owner-only guard:
+ *
+ * ```ts
+ * app.route('/api/v1/admin/sqlite', ownerOnly(createSqliteViewerMiddleware(db)));
+ * ```
+ *
+ * Three endpoints — list tables + counts, paginate one table, run an ad-hoc
+ * `SELECT` — letting the owner inspect the live DB without shell access. Every path
+ * is read-only (see `browse.ts` for the injection/read-only guards). Authn/authz is
+ * the mounting app's job (this sub-app trusts that it is already owner-gated).
+ */
+export function createSqliteViewerMiddleware(db: Database): Hono {
+  const app = new Hono();
+
+  app.get('/tables', (c) => c.json({ items: listSqliteTables(db) }));
+
+  app.get('/tables/:table', (c) => {
+    try {
+      return c.json(
+        readSqliteTable(db, c.req.param('table'), {
+          limit: c.req.query('limit'),
+          offset: c.req.query('offset'),
+        }),
+      );
+    } catch (err) {
+      if (err instanceof UnknownTableError) {
+        return c.json(toErrorEnvelope(new ApiError(404, 'Unknown table', { code: 'unknown_table' })), 404);
+      }
+      throw err;
+    }
+  });
+
+  app.post('/query', async (c) => {
+    let payload: { sql?: unknown; params?: unknown };
+    try {
+      payload = await c.req.json();
+    } catch {
+      return c.json(toErrorEnvelope(new ApiError(400, 'Invalid JSON body', { code: 'bad_request' })), 400);
+    }
+    const params = Array.isArray(payload.params) ? (payload.params as unknown[]) : [];
+    try {
+      const items = runReadonlySqlite(db, payload.sql as string, params);
+      return c.json({ items });
+    } catch (err) {
+      if (err instanceof NotReadOnlyError) {
+        return c.json(toErrorEnvelope(new ApiError(400, err.message, { code: 'not_read_only' })), 400);
+      }
+      return c.json(
+        toErrorEnvelope(
+          new ApiError(400, err instanceof Error ? err.message : String(err), { code: 'query_failed' }),
+        ),
+        400,
+      );
+    }
+  });
+
+  return app;
+}

package/src/server/storage/binaryServerProcessing.integration.spec.ts

@@ -0,0 +1,222 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pickFreePort, startTestServer, type TestServer } from 'cwip/testing';
+import { createBinaryServerProcessing } from './binaryServerProcessing';
+import { fsHlsMasterKey, fsMp4Key, fsPosterKey } from './types';
+
+// End-to-end proof of the REMOTE processing pipeline: the cb client submits
+// library/image jobs to a REAL binary-server (booted from the local checkout,
+// isolated storage), which runs real ffmpeg/sips and writes derivatives back
+// into its own store. Skips cleanly when the checkout or ffmpeg is absent.
+// Mirrors transcode.integration.spec.ts's harness.
+
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const FFMPEG_PRESENT = Bun.which('ffmpeg') !== null;
+
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+// ffmpeg must be on PATH too: the proof is that the REMOTE side runs real ffmpeg, not that the client posted a job.
+describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
+  'binaryServerProcessing → real binary-server (integration)',
+  () => {
+    let port: number;
+    let storeDir: string;
+    let server: TestServer | null = null;
+    let tmpData: string;
+    const INTERNAL_SECRET = 'test-processing-secret';
+    const APP = 'ptest';
+
+    beforeAll(async () => {
+      tmpData = await mkdtemp(path.join(tmpdir(), 'bs-processing-test-'));
+      storeDir = path.join(tmpData, 'binaries');
+      mkdirSync(storeDir, { recursive: true });
+      port = await pickFreePort();
+      server = await startTestServer({
+        cwd: BS_DIR,
+        cmd: ['bun', path.join(BS_DIR, 'src', 'index.ts')],
+        port,
+        env: {
+          PORT: String(port),
+          HOST: '127.0.0.1',
+          STORAGE_ROOT: storeDir,
+          DB_PATH: path.join(tmpData, 'test.sqlite'),
+          INTERNAL_SECRET,
+          NODE_ENV: 'test',
+        },
+        healthPath: '/healthz',
+        timeoutMs: 90_000,
+      });
+
+      // Register the tenant, the way `register-app` does for a real one. This is
+      // not harness ceremony: since binary-server started INDEXING every transcode
+      // output (bs d7bf791), `file_index.app_id` has a FOREIGN KEY onto `apps`, so
+      // an unregistered tenant cannot have a derivative indexed at all. bs now
+      // refuses such a job up front rather than writing bytes it cannot index — and
+      // a harness that skips registration is testing a configuration no deployment
+      // has, which is exactly why this suite went red for a real product change.
+      const register = Bun.spawn(
+        [
+          'bun',
+          '-e',
+          `const db = await import(${JSON.stringify(path.join(BS_DIR, 'src', 'db.ts'))});
+           db.initDb();
+           db.upsertApp({ appId: process.argv[1], issuer: process.argv[2] });`,
+          APP,
+          `https://${APP}.test`,
+        ],
+        {
+          cwd: BS_DIR,
+          env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite') },
+          stdout: 'inherit',
+          stderr: 'inherit',
+        },
+      );
+      expect(await register.exited).toBe(0);
+    }, 90_000);
+
+    afterAll(async () => {
+      await server?.stop();
+      await rm(tmpData, { recursive: true, force: true }).catch(() => void 0);
+    });
+
+    // Write bytes straight into the isolated store the way an upload would land
+    // them (the store shards by container hash — replicate via the server's own
+    // sharding by using the internal write path: PUT via upload requires tokens,
+    // so instead spawn a tiny helper inside BS_DIR that uses its storage module).
+    const putDirect = async (key: string, localFile: string) => {
+      // `bun -e` argv: [bunPath, ...args] — the passed args start at argv[1].
+      const helper = `
+        const { writeFile } = await import(${JSON.stringify(path.join(BS_DIR, 'src', 'storage.ts'))});
+        const [app, ...rest] = process.argv[1].split('/');
+        await writeFile(app, rest.join('/'), Bun.file(process.argv[2]));
+      `;
+      const proc = Bun.spawn(['bun', '-e', helper, `${APP}/${key}`, localFile], {
+        cwd: BS_DIR,
+        env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite') },
+        stdout: 'inherit',
+        stderr: 'inherit',
+      });
+      expect(await proc.exited).toBe(0);
+    };
+
+    const statKey = (key: string) =>
+      fetch(`http://localhost:${port}/internal/stat?key=${encodeURIComponent(`${APP}/${key}`)}`);
+
+    test(
+      'library job: real video → faststart + HLS + poster on the bs store',
+      async () => {
+        // Synthesize a 2s test clip with ffmpeg (color bars + tone).
+        const src = path.join(tmpData, 'clip.mp4');
+        const gen = Bun.spawn(
+          [
+            'ffmpeg',
+            '-y',
+            '-f',
+            'lavfi',
+            '-i',
+            'testsrc=duration=2:size=320x240:rate=24',
+            '-f',
+            'lavfi',
+            '-i',
+            'sine=frequency=440:duration=2',
+            '-c:v',
+            'libx264',
+            '-pix_fmt',
+            'yuv420p',
+            '-c:a',
+            'aac',
+            src,
+          ],
+          { stdout: 'ignore', stderr: 'ignore' },
+        );
+        expect(await gen.exited).toBe(0);
+        await putDirect('source/u1/vid1', src);
+
+        const { videoProcessor } = createBinaryServerProcessing({
+          baseUrl: `http://localhost:${port}`,
+          appId: APP,
+          internalSecret: INTERNAL_SECRET,
+          ladderHeights: [240],
+          pollMs: 300,
+        });
+        const progress: number[] = [];
+        const result = await videoProcessor({
+          store: {} as never,
+          workDir: tmpData,
+          owner: 'u1',
+          id: 'vid1',
+          sourceKey: 'source/u1/vid1',
+          onProgress: (_s, p) => progress.push(p),
+        });
+        expect(result.status).toBe('ready');
+        expect(result.hasPoster).toBe(true);
+        expect(result.hasHls).toBe(true);
+        expect(result.durationSeconds).toBeGreaterThan(1);
+
+        // The derivatives exist in the bs store tree (sharded layout — assert via glob).
+        const files = await Array.fromAsync(
+          new Bun.Glob('**/*').scan({ cwd: path.join(storeDir, APP), onlyFiles: true }),
+        );
+        expect(files.some((f) => f.endsWith(fsMp4Key('u1', 'vid1').split('/').pop() as string))).toBe(true);
+        expect(files.some((f) => f.endsWith('master.m3u8'))).toBe(true);
+        expect(files.some((f) => f.endsWith('vid1-poster.jpg'))).toBe(true);
+      },
+      { timeout: 120_000 },
+    );
+
+    test(
+      'image job: real JPEG → 512px thumbnail derivative',
+      async () => {
+        const srcImg = path.join(tmpData, 'photo.jpg');
+        const gen = Bun.spawn(
+          [
+            'ffmpeg',
+            '-y',
+            '-f',
+            'lavfi',
+            '-i',
+            'testsrc=duration=1:size=1600x1200:rate=1',
+            '-frames:v',
+            '1',
+            srcImg,
+          ],
+          { stdout: 'ignore', stderr: 'ignore' },
+        );
+        expect(await gen.exited).toBe(0);
+        await putDirect('file/u1/img1', srcImg);
+
+        const { imageDerivatives } = createBinaryServerProcessing({
+          baseUrl: `http://localhost:${port}`,
+          appId: APP,
+          internalSecret: INTERNAL_SECRET,
+          pollMs: 300,
+        });
+        const result = await imageDerivatives({
+          store: {} as never,
+          workDir: tmpData,
+          owner: 'u1',
+          id: 'img1',
+          mime: 'image/jpeg',
+          binaryKey: 'file/u1/img1',
+          posterKey: fsPosterKey('u1', 'img1'),
+          displayKey: 'fs/u1/img1-display.jpg',
+          needsDisplay: false,
+        });
+        expect(result.hasThumbnail).toBe(true);
+        const files = await Array.fromAsync(
+          new Bun.Glob('**/*').scan({ cwd: path.join(storeDir, APP), onlyFiles: true }),
+        );
+        expect(files.some((f) => f.endsWith('img1-poster.jpg'))).toBe(true);
+      },
+      { timeout: 60_000 },
+    );
+
+    void statKey; // (reserved for a future /internal/stat probe)
+    void fsHlsMasterKey;
+  },
+);

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

@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'bun:test';
+import { createBinaryServerProcessing } from './binaryServerProcessing';
+import type { MediaStore } from './types';
+
+// Fake binary-server: records submissions, walks each job pending → processing → ready/failed.
+function fakeBs(opts: {
+  result?: Record<string, unknown>;
+  fail?: boolean;
+  rejectSubmit?: boolean;
+}) {
+  const submissions: Array<Record<string, unknown>> = [];
+  let polls = 0;
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    if (url.endsWith('/api/transcode') && init?.method === 'POST') {
+      if (opts.rejectSubmit) return new Response('nope', { status: 401 });
+      submissions.push(JSON.parse(String(init.body)));
+      return Response.json({ jobId: 'job-1' }, { status: 202 });
+    }
+    polls++;
+    if (polls === 1) return Response.json({ status: 'processing', progress: 42 });
+    if (opts.fail) return Response.json({ status: 'failed', error: 'boom' });
+    return Response.json({ status: 'ready', result: opts.result ?? {} });
+  }) as typeof fetch;
+  return { submissions, fetchImpl, pollCount: () => polls };
+}
+
+const noopStore = {} as MediaStore;
+
+const cfg = (fetchImpl: typeof fetch) => ({
+  baseUrl: 'https://bs.example.com',
+  appId: 'p',
+  internalSecret: 's3cret',
+  fetchImpl,
+  pollMs: 1,
+  sleep: async () => {},
+});
+
+describe('createBinaryServerProcessing — video', () => {
+  test('submits an app-scoped library job and maps the result flags', async () => {
+    const bs = fakeBs({
+      result: { durationSeconds: 12.5, hasHls: true, hasPoster: true, hasSprite: false },
+    });
+    const { videoProcessor } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    const progress: Array<[string, number]> = [];
+    const res = await videoProcessor({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'vid1',
+      sourceKey: 'source/u1/vid1',
+      onProgress: (s, p) => progress.push([s, p]),
+    });
+    expect(res).toEqual({
+      status: 'ready',
+      durationSeconds: 12.5,
+      hasHls: true,
+      hasSprite: false,
+      hasPoster: true,
+    });
+    const job = bs.submissions[0];
+    expect(job?.strategy).toBe('library');
+    expect(job?.sourceKey).toBe('p/source/u1/vid1');
+    expect(job?.sourceKeyOut).toBe('p/fs/u1/vid1.mp4');
+    expect(job?.hlsPrefix).toBe('p/hls/u1/vid1');
+    expect(job?.posterKey).toBe('p/fs/u1/vid1-poster.jpg');
+    expect(job?.posterOnly).toBe(false);
+    expect(progress.some(([s, p]) => s === 'processing' && p === 42)).toBe(true);
+    expect(progress.at(-1)).toEqual(['ready', 100]);
+  });
+
+  test('posterOnly rides through', async () => {
+    const bs = fakeBs({ result: { hasPoster: true, durationSeconds: 3 } });
+    const { videoProcessor } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    await videoProcessor({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'vid2',
+      sourceKey: 'source/u1/vid2',
+      posterOnly: true,
+    });
+    expect(bs.submissions[0]?.posterOnly).toBe(true);
+  });
+
+  test('a failed job maps to status failed (never throws into the catalogue)', async () => {
+    const bs = fakeBs({ fail: true });
+    const { videoProcessor } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    const res = await videoProcessor({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'vid3',
+      sourceKey: 'source/u1/vid3',
+    });
+    expect(res.status).toBe('failed');
+  });
+
+  test('a rejected submit maps to status failed', async () => {
+    const bs = fakeBs({ rejectSubmit: true });
+    const { videoProcessor } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    const res = await videoProcessor({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'vid4',
+      sourceKey: 'source/u1/vid4',
+    });
+    expect(res.status).toBe('failed');
+  });
+});
+
+describe('createBinaryServerProcessing — image', () => {
+  test('submits the image job with display key only when needed', async () => {
+    const bs = fakeBs({ result: { hasThumbnail: true } });
+    const { imageDerivatives } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    const res = await imageDerivatives({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'img1',
+      mime: 'image/heic',
+      binaryKey: 'file/u1/img1',
+      posterKey: 'fs/u1/img1-poster.jpg',
+      displayKey: 'fs/u1/img1-display.jpg',
+      needsDisplay: true,
+    });
+    expect(res).toEqual({ hasThumbnail: true });
+    expect(bs.submissions[0]?.strategy).toBe('image');
+    expect(bs.submissions[0]?.displayKey).toBe('p/fs/u1/img1-display.jpg');
+  });
+
+  test('browser-renderable image omits displayKey and failure maps to hasThumbnail false', async () => {
+    const bs = fakeBs({ fail: true });
+    const { imageDerivatives } = createBinaryServerProcessing(cfg(bs.fetchImpl));
+    const res = await imageDerivatives({
+      store: noopStore,
+      workDir: '/tmp/unused',
+      owner: 'u1',
+      id: 'img2',
+      mime: 'image/jpeg',
+      binaryKey: 'file/u1/img2',
+      posterKey: 'fs/u1/img2-poster.jpg',
+      displayKey: 'fs/u1/img2-display.jpg',
+      needsDisplay: false,
+    });
+    expect(res).toEqual({ hasThumbnail: false });
+    expect(bs.submissions[0]?.displayKey).toBeUndefined();
+  });
+});

package/src/server/storage/binaryServerProcessing.ts

@@ -0,0 +1,127 @@
+import type { ImageDerivatives, VideoProcessor } from './files/catalogue';
+import { createTranscodeJobClient } from './transcodeJobs';
+import { fsHlsPrefix, fsMp4Key, fsPosterKey, fsSpriteKey, fsVttKey } from './types';
+
+// The cursedbelt file CATALOGUE's two derivative seams, bound to binary-server's transcode
+// API. The transport itself — submit, poll, and the two derivative shapes — lives in
+// `./transcodeJobs`, so an app that stores binaries WITHOUT a catalogue (apps/notes keys
+// attachments by sha256 through satellite-kit's binary-store) can reach the same pipeline
+// without adopting the catalogue or writing a second HTTP client. There is one derivative
+// pipeline in the fleet; this file is the catalogue-shaped door onto it.
+//
+// Why remote at all: the bytes already live on the binary-server host, which has real CPU,
+// disk and ffmpeg. Pulling a multi-GB source down to the app host defeats the point, and the
+// shared prod t3.micro cannot do it at all.
+//
+// Strategies used here (binary-server side): `library` = faststart MP4 + HLS ladder + poster +
+// sprite/VTT in one job (posterOnly collapses it to probe + poster); `image` = 512px grid
+// thumbnail + optional full-size browser-safe display JPEG. The classic `faststart`/`hls`
+// strategies predate these and stay untouched for existing consumers.
+
+export type BinaryServerProcessingConfig = {
+  /** e.g. 'https://binary-server.cursedalchemy.com' — same value as the byte store's baseUrl. */
+  baseUrl: string;
+  /** App namespace (path + token scope), e.g. 'p'. Keys sent to the transcode API are
+   * app-scoped (`<appId>/<key>`), matching what the MediaStore adapter writes. */
+  appId: string;
+  /** Shared server-to-server secret (x-internal-secret). */
+  internalSecret: string;
+  /** HLS rung heights (passed through as the job's ladder). */
+  ladderHeights?: number[];
+  /** Poll cadence while a job runs. */
+  pollMs?: number;
+  /** Give up on a job after this long (it keeps running server-side; the row just fails). */
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  /** Injectable clock/sleep for tests. */
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export function createBinaryServerProcessing(cfg: BinaryServerProcessingConfig): {
+  videoProcessor: VideoProcessor;
+  imageDerivatives: ImageDerivatives;
+} {
+  const jobs = createTranscodeJobClient(cfg);
+  const { appKey, submit, poll } = jobs;
+
+  const videoProcessor: VideoProcessor = async (opts) => {
+    const { owner, id, onProgress } = opts;
+    const failed = {
+      status: 'failed' as const,
+      durationSeconds: 0,
+      hasHls: false,
+      hasSprite: false,
+      hasPoster: false,
+    };
+    try {
+      onProgress?.('processing', 1);
+      const jobId = await submit({
+        strategy: 'library',
+        nodeId: id,
+        sourceKey: appKey(opts.sourceKey),
+        binaryKey: appKey(fsMp4Key(owner, id)),
+        sourceKeyOut: appKey(fsMp4Key(owner, id)),
+        hlsPrefix: appKey(fsHlsPrefix(owner, id)),
+        posterKey: appKey(fsPosterKey(owner, id)),
+        spriteKey: appKey(fsSpriteKey(owner, id)),
+        vttKey: appKey(fsVttKey(owner, id)),
+        posterOnly: opts.posterOnly === true,
+        settings: { ladder: opts.ladderHeights ?? [480, 720, 1080] },
+      });
+      const job = await poll(jobId, (pct) => onProgress?.('processing', Math.min(99, pct)));
+      if (job.status !== 'ready') {
+        // The "a failed job maps to status failed" fixture test deliberately drives this
+        // path — tagged `[expected-in-tests]` (grep-filterable) rather than silenced, so a
+        // real binary-server outage still surfaces.
+        console.warn(
+          `[binaryServerProcessing][expected-in-tests] video job failed for ${id}: ${job.error ?? '?'}`,
+        );
+        onProgress?.('failed', 0);
+        return failed;
+      }
+      onProgress?.('ready', 100);
+      return {
+        status: 'ready',
+        durationSeconds: job.result?.durationSeconds ?? 0,
+        hasHls: job.result?.hasHls ?? false,
+        hasSprite: job.result?.hasSprite ?? false,
+        hasPoster: job.result?.hasPoster ?? false,
+      };
+    } catch (err) {
+      // The "a rejected submit maps to status failed" fixture test deliberately drives this
+      // path — tagged `[expected-in-tests]` (grep-filterable) rather than silenced, so a
+      // real binary-server outage still surfaces.
+      console.warn(
+        `[binaryServerProcessing][expected-in-tests] video job errored for ${id}: ${err instanceof Error ? err.message : err}`,
+      );
+      onProgress?.('failed', 0);
+      return failed;
+    }
+  };
+
+  const imageDerivatives: ImageDerivatives = async (args) => {
+    try {
+      const jobId = await submit({
+        strategy: 'image',
+        nodeId: args.id,
+        sourceKey: appKey(args.binaryKey),
+        binaryKey: appKey(args.binaryKey),
+        posterKey: appKey(args.posterKey),
+        ...(args.needsDisplay ? { displayKey: appKey(args.displayKey) } : {}),
+      });
+      const job = await poll(jobId);
+      if (job.status !== 'ready' || !job.result?.hasThumbnail) return { hasThumbnail: false };
+      return { hasThumbnail: true };
+    } catch (err) {
+      // The "browser-renderable image ... failure maps to hasThumbnail false" fixture test
+      // deliberately drives this path — tagged `[expected-in-tests]` (grep-filterable)
+      // rather than silenced, so a real binary-server outage still surfaces.
+      console.warn(
+        `[binaryServerProcessing][expected-in-tests] image job errored for ${args.id}: ${err instanceof Error ? err.message : err}`,
+      );
+      return { hasThumbnail: false };
+    }
+  };
+
+  return { videoProcessor, imageDerivatives };
+}

package/src/server/storage/binaryServerStore.ts

@@ -0,0 +1,102 @@
+import type { BinaryServerConfig, MediaStore } from './types';
+
+// The token shapes moved to `./types` (published as `cursedbelt-server/storage/types`) so an
+// app can import the CLAIM SHAPE without importing this adapter's module graph. Re-exported
+// here so every existing `from './binaryServerStore'` and the `./index` barrel keep resolving.
+export type { BinaryServerConfig, FileTokenClaims, FileTokenSigner } from './types';
+
+// binary-server MediaStore adapter. binary-server (Bun/SQLite, RS256 token-gated, Range-capable)
+// is a production storage path: a home/edge file service the app signs short-lived tokens for.
+// User-facing downloads REDIRECT (303) to the signed edge URL rather than proxying bytes back
+// through the app; server-side reads (transcode source, checks) stream locally via getRange.
+//
+// The RS256 signer is INJECTED — the app holds the private key (binary-server holds only the
+// public key). cursedbelt carries no key material and no asymmetric-crypto specifics; it just
+// calls `signFileToken` with the claims binary-server expects.
+
+export function createBinaryServerStore(cfg: BinaryServerConfig): MediaStore {
+  const appKey = (key: string) => `${cfg.appId}/${key}`;
+  const mediaUrl = async (key: string, extra?: { fn?: string; dl?: 'inline' | 'attachment' }) => {
+    const token = await cfg.signFileToken({ k: appKey(key), ...extra });
+    return `${cfg.baseUrl}/media/${appKey(key)}?token=${encodeURIComponent(token)}`;
+  };
+  const uploadUrl = async (key: string) => {
+    const token = await cfg.signFileToken({ k: appKey(key) });
+    return `${cfg.baseUrl}/upload/${appKey(key)}?token=${encodeURIComponent(token)}`;
+  };
+
+  return {
+    async put(key, bytes, mime) {
+      const res = await fetch(await uploadUrl(key), {
+        method: 'PUT',
+        body: new Blob([bytes as BlobPart], { type: mime }),
+      });
+      if (!res.ok) throw new Error(`binary-server put ${key}: ${res.status}`);
+    },
+    async putStream(key, body, mime, opts) {
+      const headers: Record<string, string> = { 'content-type': mime };
+      if (opts?.contentLength != null) headers['content-length'] = String(opts.contentLength);
+      const res = await fetch(await uploadUrl(key), {
+        method: 'PUT',
+        body,
+        headers,
+        // A web ReadableStream body requires duplex: 'half' per the fetch streaming spec.
+        duplex: 'half',
+      } as RequestInit);
+      if (!res.ok) throw new Error(`binary-server putStream ${key}: ${res.status}`);
+    },
+    async get(key) {
+      const res = await fetch(await mediaUrl(key));
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`binary-server get ${key}: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    async remove(key) {
+      // binary-server gates DELETE on BOTH the internal secret AND a per-op, path-scoped RS256
+      // token carrying op:'delete' (owner ruling #10, defense in depth). Sign+send both.
+      const token = await cfg.signFileToken({ k: appKey(key), op: 'delete' });
+      const res = await fetch(
+        `${cfg.baseUrl}/media/${appKey(key)}?token=${encodeURIComponent(token)}`,
+        {
+          method: 'DELETE',
+          headers: cfg.internalSecret ? { 'x-internal-secret': cfg.internalSecret } : {},
+        },
+      );
+      if (!res.ok && res.status !== 404)
+        throw new Error(`binary-server remove ${key}: ${res.status}`);
+    },
+    async removePrefix(prefix) {
+      // The delete token's exact-key claim is the container path; bs derives the tree from it
+      // plus ?container=1. Same two-barrier gate as remove().
+      const token = await cfg.signFileToken({ k: appKey(prefix), op: 'delete' });
+      const res = await fetch(
+        `${cfg.baseUrl}/media/${appKey(prefix)}?container=1&token=${encodeURIComponent(token)}`,
+        {
+          method: 'DELETE',
+          headers: cfg.internalSecret ? { 'x-internal-secret': cfg.internalSecret } : {},
+        },
+      );
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`binary-server removePrefix ${prefix}: ${res.status}`);
+      }
+    },
+    async stat(key) {
+      // A 0-0 range is the cheapest way to learn total size (Content-Range: …/<total>).
+      const res = await fetch(await mediaUrl(key), { headers: { Range: 'bytes=0-0' } });
+      if (res.status === 404) return null;
+      const cr = res.headers.get('content-range');
+      const total = cr ? Number(cr.split('/')[1]) : Number(res.headers.get('content-length'));
+      return Number.isFinite(total) ? { size: total } : null;
+    },
+    async getRange(key, range) {
+      const headers: Record<string, string> = {};
+      if (range) headers.Range = `bytes=${range.start}-${range.end}`;
+      const res = await fetch(await mediaUrl(key), { headers });
+      if (res.status === 404 || !res.body) return null;
+      return { stream: res.body };
+    },
+    async redirectUrl(key, opts) {
+      return mediaUrl(key, { fn: opts.filename, dl: 'inline' });
+    },
+  };
+}