cursedbelt-server 1.0.0

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

@@ -0,0 +1,219 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Hono } from 'hono';
+import { createDiskStore } from './diskStore';
+import { mountMediaRoutes } from './mountMediaRoutes';
+import { createMediaUrls } from './sources';
+import { decodeRange, serveRange } from './streamRange';
+import { createStreamTokenService } from './streamToken';
+import type { MediaStore } from './types';
+
+describe('decodeRange', () => {
+  test('no header ⇒ full', () => {
+    expect(decodeRange(undefined, 100)).toEqual({ kind: 'full' });
+  });
+  test('inclusive a-b', () => {
+    expect(decodeRange('bytes=4-9', 16)).toEqual({ kind: 'partial', start: 4, end: 9 });
+  });
+  test('open-ended a-', () => {
+    expect(decodeRange('bytes=8-', 16)).toEqual({ kind: 'partial', start: 8, end: 15 });
+  });
+  test('suffix -n', () => {
+    expect(decodeRange('bytes=-4', 16)).toEqual({ kind: 'partial', start: 12, end: 15 });
+  });
+  test('clamps end past EOF', () => {
+    expect(decodeRange('bytes=10-999', 16)).toEqual({ kind: 'partial', start: 10, end: 15 });
+  });
+  test('out of bounds ⇒ unsatisfiable', () => {
+    expect(decodeRange('bytes=999-1000', 16)).toEqual({ kind: 'unsatisfiable' });
+  });
+  test('malformed ⇒ full', () => {
+    expect(decodeRange('rows=1-2', 16)).toEqual({ kind: 'full' });
+  });
+});
+
+describe('streamTokenService', () => {
+  const svc = createStreamTokenService({ secret: 'test-secret-abc' });
+
+  test('round-trips a grant', async () => {
+    const token = await svc.sign({ owner: 'tenant1', sourceId: 'src', videoId: 'vid' });
+    expect(await svc.verify(token)).toEqual({ owner: 'tenant1', sourceId: 'src', videoId: 'vid' });
+  });
+  test('rejects a tampered token', async () => {
+    const token = await svc.sign({ owner: 't', sourceId: 's', videoId: 'v' });
+    expect(await svc.verify(`${token}x`)).toBeNull();
+  });
+  test('rejects an expired token', async () => {
+    const token = await svc.sign({ owner: 't', sourceId: 's', videoId: 'v' }, -10);
+    expect(await svc.verify(token)).toBeNull();
+  });
+  test('rejects a token signed with a different secret', async () => {
+    const other = createStreamTokenService({ secret: 'other-secret' });
+    const token = await other.sign({ owner: 't', sourceId: 's', videoId: 'v' });
+    expect(await svc.verify(token)).toBeNull();
+  });
+});
+
+describe('diskStore + serveRange', () => {
+  let root: string;
+  let store: MediaStore;
+  const key = 'fs/tenant1/clip.mp4';
+  const payload = new TextEncoder().encode('0123456789ABCDEF'); // 16 bytes
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(tmpdir(), 'cb-storage-'));
+    store = createDiskStore(root);
+    await store.put(key, payload, 'video/mp4');
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('stat returns size', async () => {
+    expect(await store.stat(key)).toEqual({ size: 16 });
+  });
+  test('stat of a missing key is null', async () => {
+    expect(await store.stat('fs/tenant1/nope')).toBeNull();
+  });
+  test('getRange returns the inclusive slice', async () => {
+    const rr = await store.getRange(key, { start: 4, end: 9 });
+    const bytes = new Uint8Array(await new Response(rr?.stream).arrayBuffer());
+    expect(new TextDecoder().decode(bytes)).toBe('456789');
+  });
+  test('serveRange answers 206 with Content-Range', async () => {
+    const res = await serveRange(store, key, 'video/mp4', 'bytes=4-9');
+    expect(res.status).toBe(206);
+    expect(res.headers.get('content-range')).toBe('bytes 4-9/16');
+    expect(res.headers.get('content-length')).toBe('6');
+    expect(await res.text()).toBe('456789');
+  });
+  test('serveRange answers 200 for the whole object', async () => {
+    const res = await serveRange(store, key, 'video/mp4', undefined);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-length')).toBe('16');
+  });
+  test('serveRange answers 416 for an unsatisfiable range', async () => {
+    const res = await serveRange(store, key, 'video/mp4', 'bytes=999-1000');
+    expect(res.status).toBe(416);
+    expect(res.headers.get('content-range')).toBe('bytes */16');
+  });
+  test('serveRange answers 404 for a missing key', async () => {
+    const res = await serveRange(store, 'fs/tenant1/nope', 'video/mp4', undefined);
+    expect(res.status).toBe(404);
+  });
+  test('removePrefix clears a subtree', async () => {
+    await store.put('hls/tenant1/vid/master.m3u8', payload, 'application/vnd.apple.mpegurl');
+    await store.removePrefix('hls/tenant1/vid');
+    expect(await store.stat('hls/tenant1/vid/master.m3u8')).toBeNull();
+  });
+
+  test('putStream writes a web ReadableStream without hanging or truncating', async () => {
+    const bytes = new Uint8Array(64 * 1024).map((_, i) => i % 256); // 64 KiB, multi-chunk
+    const stream = new Response(bytes).body as ReadableStream<Uint8Array>;
+    await store.putStream('fs/tenant1/streamed.bin', stream, 'application/octet-stream');
+    expect(await store.stat('fs/tenant1/streamed.bin')).toEqual({ size: 64 * 1024 });
+    const round = await store.get('fs/tenant1/streamed.bin');
+    expect(round?.length).toBe(64 * 1024);
+    expect(round?.[1000]).toBe(1000 % 256);
+  });
+
+  test('putStream survives a LIVE request-body stream (Bun 1.3.x detach bug)', async () => {
+    // Regression: in Bun 1.3.x a request-body stream's internals detach across an
+    // I/O await (the mkdir inside putStream); releaseLock() then throws "undefined
+    // is not a function" and every upload 500s. Only a REAL served request exhibits
+    // it — a Response-body stream (test above) never detaches.
+    const app = new Hono();
+    app.put('/u', async (c) => {
+      const body = c.req.raw.body;
+      if (!body) return c.json({ error: 'empty' }, 400);
+      await store.putStream('fs/tenant1/live.bin', body, 'application/octet-stream');
+      return c.json({ ok: true });
+    });
+    const server = Bun.serve({ fetch: app.fetch, port: 0 });
+    try {
+      const res = await fetch(`http://localhost:${server.port}/u`, {
+        method: 'PUT',
+        body: 'live request bytes',
+      });
+      expect(res.status).toBe(200);
+      expect(await store.stat('fs/tenant1/live.bin')).toEqual({ size: 18 });
+    } finally {
+      server.stop();
+    }
+  });
+});
+
+// The split-origin case: assets served from one origin (e.g. Cloudflare Pages), media+API from
+// another (e.g. an EC2 subdomain). Media URLs are built server-side with an ABSOLUTE base, and
+// the serve routes answer cross-origin CORS with the range headers a seeking <video> needs.
+describe('split-origin media (absolute URLs + CORS)', () => {
+  let root: string;
+  let store: MediaStore;
+  const token = createStreamTokenService({ secret: 'origin-secret' });
+  const ctx = { userId: 'u1', tenantId: 'tenantA' };
+  const payload = new TextEncoder().encode('SEGMENTBYTES-0123456789');
+  const PAGE_ORIGIN = 'https://app.example.com';
+  const API_BASE = 'https://api.example.com/_media';
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(tmpdir(), 'cb-cors-'));
+    store = createDiskStore(root);
+    // Owner keyspace defaults to tenantId → store under fs/tenantA/…
+    await store.put('fs/tenantA/clip.mp4', payload, 'video/mp4');
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('createMediaUrls emits ABSOLUTE cross-origin URLs (not window-relative)', async () => {
+    const urls = createMediaUrls({ baseUrl: API_BASE, token });
+    const built = await urls.build(ctx, 'disk', 'clip');
+    expect(built.streamUrl.startsWith(`${API_BASE}/s/`)).toBe(true);
+    expect(built.hlsUrl.endsWith('/hls/disk/clip/master.m3u8')).toBe(true);
+    // The stream token is a single path segment, so hls.js relative segment fetches inherit it.
+    expect(built.streamUrl).toContain('/s/');
+  });
+
+  test('a trailing slash on baseUrl is normalized', async () => {
+    const urls = createMediaUrls({ baseUrl: `${API_BASE}/`, token });
+    const built = await urls.build(ctx, 'disk', 'clip');
+    expect(built.streamUrl.includes('//s/')).toBe(false);
+  });
+
+  test('cross-origin GET gets ACAO + exposes range headers', async () => {
+    const app = new Hono();
+    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
+    const t = await token.sign({ owner: 'tenantA', sourceId: 'disk', videoId: 'clip' });
+    const res = await app.request(`/_media/s/${t}/media/disk/clip`, {
+      headers: { Origin: PAGE_ORIGIN, Range: 'bytes=0-3' },
+    });
+    expect(res.status).toBe(206);
+    expect(res.headers.get('access-control-allow-origin')).toBe(PAGE_ORIGIN);
+    expect(res.headers.get('access-control-expose-headers')).toContain('Content-Range');
+    expect(res.headers.get('content-range')).toBe('bytes 0-3/23');
+  });
+
+  test('preflight OPTIONS is answered for an allowed origin', async () => {
+    const app = new Hono();
+    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
+    const res = await app.request('/_media/s/x/media/disk/clip', {
+      method: 'OPTIONS',
+      headers: { Origin: PAGE_ORIGIN },
+    });
+    expect(res.status).toBe(204);
+    expect(res.headers.get('access-control-allow-origin')).toBe(PAGE_ORIGIN);
+    expect(res.headers.get('access-control-allow-methods')).toContain('GET');
+  });
+
+  test('a disallowed origin gets no ACAO', async () => {
+    const app = new Hono();
+    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
+    const t = await token.sign({ owner: 'tenantA', sourceId: 'disk', videoId: 'clip' });
+    const res = await app.request(`/_media/s/${t}/media/disk/clip`, {
+      headers: { Origin: 'https://evil.example.com' },
+    });
+    expect(res.headers.get('access-control-allow-origin')).toBeNull();
+  });
+});

package/src/server/storage/streamRange.ts

@@ -0,0 +1,92 @@
+import type { MediaStore } from './types';
+
+// HTTP Range streaming for large media (video), Hono/Bun-native. Serves bytes straight from
+// the active store as 200 (whole) or 206 Partial Content (a byte range) so the browser's
+// <video> element can seek without downloading the entire file. Ported from ca's streamRange,
+// re-expressed as a web `Response` (no Express shim).
+
+export type RangeDecision =
+  | { kind: 'full' }
+  | { kind: 'partial'; start: number; end: number }
+  | { kind: 'unsatisfiable' };
+
+// Parse a single-range `Range: bytes=start-end` header against a known total size. Only the
+// common single-range forms are supported (`a-b`, `a-`, `-n`); anything malformed falls back
+// to a full response, and an out-of-bounds range is rejected so the caller can answer 416.
+// End is clamped to the last byte; ranges are inclusive.
+export function decodeRange(header: string | undefined | null, total: number): RangeDecision {
+  if (!header) return { kind: 'full' };
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!match) return { kind: 'full' };
+  const [, rawStart, rawEnd] = match;
+  if (rawStart === '' && rawEnd === '') return { kind: 'full' };
+
+  let start: number;
+  let end: number;
+  if (rawStart === '') {
+    // Suffix range: the last N bytes.
+    const suffix = Number.parseInt(rawEnd, 10);
+    if (suffix <= 0) return { kind: 'unsatisfiable' };
+    start = Math.max(0, total - suffix);
+    end = total - 1;
+  } else {
+    start = Number.parseInt(rawStart, 10);
+    end = rawEnd === '' ? total - 1 : Number.parseInt(rawEnd, 10);
+  }
+
+  if (start > end || start >= total || start < 0) return { kind: 'unsatisfiable' };
+  if (end >= total) end = total - 1;
+  return { kind: 'partial', start, end };
+}
+
+export type ServeRangeOpts = {
+  /** Content-Disposition value, e.g. 'inline' or `attachment; filename="clip.mp4"`. */
+  contentDisposition?: string;
+  /** Overrides the default 'private, max-age=86400' (e.g. 'no-store' for private bytes). */
+  cacheControl?: string;
+  extraHeaders?: Record<string, string>;
+};
+
+// Build a Range-aware Response for a stored object. `rangeHeader` is the request's Range header
+// (Hono: `c.req.header('range')`). 404 if the key is gone, 416 for an unsatisfiable range, 206
+// for a partial hit, else 200.
+export async function serveRange(
+  store: MediaStore,
+  key: string,
+  mime: string,
+  rangeHeader: string | undefined | null,
+  opts: ServeRangeOpts = {},
+): Promise<Response> {
+  const meta = await store.stat(key);
+  if (!meta) return new Response(null, { status: 404 });
+  const total = meta.size;
+
+  const headers = new Headers({
+    'Accept-Ranges': 'bytes',
+    'Content-Type': mime,
+    'Cache-Control': opts.cacheControl ?? 'private, max-age=86400',
+  });
+  if (opts.contentDisposition) headers.set('Content-Disposition', opts.contentDisposition);
+  if (opts.extraHeaders) {
+    for (const [k, v] of Object.entries(opts.extraHeaders)) headers.set(k, v);
+  }
+
+  const decision = decodeRange(rangeHeader, total);
+
+  if (decision.kind === 'unsatisfiable') {
+    headers.set('Content-Range', `bytes */${total}`);
+    return new Response(null, { status: 416, headers });
+  }
+
+  const range = decision.kind === 'partial' ? decision : undefined;
+  const result = await store.getRange(key, range);
+  if (!result) return new Response(null, { status: 404 });
+
+  if (range) {
+    headers.set('Content-Range', `bytes ${range.start}-${range.end}/${total}`);
+    headers.set('Content-Length', String(range.end - range.start + 1));
+    return new Response(result.stream, { status: 206, headers });
+  }
+  headers.set('Content-Length', String(total));
+  return new Response(result.stream, { status: 200, headers });
+}

package/src/server/storage/streamToken.ts

@@ -0,0 +1,76 @@
+// 🔴 `../auth/jwt`, NOT `../auth`. The jose half is a REAL dependency — stream tokens are
+// signed and verified here, and jose is a plain `dependencies` entry every consumer already
+// installs. The BARREL was the accident: `../auth/index.ts` also reaches `totp.ts` → `otplib`,
+// an OPTIONAL peer, so every app that touched anything in `cursedbelt-server/storage` was made
+// to install a one-time-password library for code it never calls. Import the leaf module that
+// has what you need; never the index that has everything. `src/leafSubpathsImportNothing.spec.ts`
+// fails if this file (or anything else the storage barrel reaches) undoes it.
+import { signToken, verifyPurposeToken } from '../auth/jwt';
+
+// ── Stream tokens ───────────────────────────────────────────────────────────────
+// Media bytes are loaded by <video>/hls.js/<img>, which cannot send the platform Bearer
+// header an app's auth uses. So byte-serving routes live OUTSIDE the guarded API and
+// authorize each request with a short-lived, PATH-embedded token instead.
+//
+// Why path-embedded, not ?t=: hls.js resolves segment/playlist URIs RELATIVE to the master
+// playlist and does NOT inherit query strings — a `?t=` token would be dropped on segment
+// fetches. A token carried as a leading path segment (…/s/<token>/hls/…) is inherited by every
+// relative child URL, so one token authorizes the whole HLS tree.
+//
+// Reuses cursedbelt's ONE jose integration (`signToken`/`verifyPurposeToken`, HS256) — the
+// same primitive the vault/files/pm unlock tokens use — under a dedicated 'media-stream'
+// purpose so it can never be replayed as an access token (or vice-versa).
+
+const MEDIA_STREAM_PURPOSE = 'media-stream';
+
+/** The scope a stream token authorizes: one video's whole derivative tree, under one owner. */
+export type StreamGrant = {
+  /** owner keyspace segment (the media lives under fs/<owner>/… , hls/<owner>/… , …). */
+  owner: string;
+  sourceId: string;
+  videoId: string;
+};
+
+export interface StreamTokenService {
+  sign(grant: StreamGrant, ttlSeconds?: number): Promise<string>;
+  verify(token: string): Promise<StreamGrant | null>;
+}
+
+export function createStreamTokenService(opts: {
+  secret: string;
+  /** Default 6h — long enough to survive a paused-and-resumed playback without a 401. */
+  defaultTtlSeconds?: number;
+}): StreamTokenService {
+  const ttl = opts.defaultTtlSeconds ?? 6 * 60 * 60;
+  return {
+    async sign(grant, ttlSeconds = ttl) {
+      // userId carries the owner; src/vid are extra claims (JWTPayload allows them). sessionId
+      // is unused for stream tokens (they're not tied to a revocable session row) — a stable
+      // marker keeps the required-field contract without implying a session.
+      return signToken(
+        {
+          userId: grant.owner,
+          sessionId: 'media-stream',
+          roles: [],
+          purpose: MEDIA_STREAM_PURPOSE,
+          src: grant.sourceId,
+          vid: grant.videoId,
+        },
+        opts.secret,
+        ttlSeconds,
+      );
+    },
+    async verify(token) {
+      try {
+        const p = await verifyPurposeToken(token, opts.secret, MEDIA_STREAM_PURPOSE);
+        const src = (p as { src?: unknown }).src;
+        const vid = (p as { vid?: unknown }).vid;
+        if (typeof src !== 'string' || typeof vid !== 'string') return null;
+        return { owner: p.userId, sourceId: src, videoId: vid };
+      } catch {
+        // Bad signature / expiry / purpose mismatch — deny.
+        return null;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,134 @@
+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';
+
+// Integration test for the binary-server's transcode API (POST /api/transcode,
+// GET /api/transcode/:jobId). Skips cleanly when the binary-server checkout is
+// absent. Mirrors the pattern from chunked.integration.spec.ts.
+//
+// Transcode API implemented in #tsk_01KWQNXRP25W6BE086K49M9S3W.
+// Contract: POST /api/transcode → { jobId }, GET /api/transcode/:jobId → { status, progress?, result? }.
+// Auth: x-internal-secret header must match process.env.INTERNAL_SECRET.
+
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+
+// 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.
+describe.skipIf(!BS_PRESENT)('transcode API → real binary-server (integration)', () => {
+  let port: number;
+  let storeDir: string;
+  let server: TestServer | null = null;
+  let tmpData: string;
+  const INTERNAL_SECRET = 'test-transcode-secret';
+
+  beforeAll(async () => {
+    tmpData = await mkdtemp(path.join(tmpdir(), 'bs-transcode-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,
+    });
+  }, 90_000);
+
+  afterAll(async () => {
+    await server?.stop();
+    await rm(tmpData, { recursive: true, force: true }).catch(() => void 0);
+  });
+
+  test('POST /api/transcode rejects missing secret with 401', async () => {
+    const res = await fetch(`http://localhost:${port}/api/transcode`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        strategy: 'faststart',
+        sourceKey: 'demo/fs/u1/node1',
+        binaryKey: 'demo/fs/u1/node1.mp4',
+        settings: {},
+      }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test('POST /api/transcode rejects wrong secret with 401', async () => {
+    const res = await fetch(`http://localhost:${port}/api/transcode`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-internal-secret': 'wrong-secret',
+      },
+      body: JSON.stringify({
+        strategy: 'faststart',
+        sourceKey: 'demo/fs/u1/node1',
+        binaryKey: 'demo/fs/u1/node1.mp4',
+        settings: {},
+      }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test('POST /api/transcode with missing source returns jobId then fails', async () => {
+    const res = await fetch(`http://localhost:${port}/api/transcode`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-internal-secret': INTERNAL_SECRET,
+      },
+      body: JSON.stringify({
+        strategy: 'faststart',
+        sourceKey: 'demo/fs/u1/nonexistent',
+        binaryKey: 'demo/fs/u1/nonexistent.mp4',
+        settings: {},
+      }),
+    });
+    expect(res.status).toBe(202);
+    const { jobId } = (await res.json()) as { jobId?: string };
+    expect(typeof jobId).toBe('string');
+
+    // Poll until failed or timeout.
+    const deadline = Date.now() + 5_000;
+    let status: string | undefined;
+    while (Date.now() < deadline) {
+      const poll = await fetch(
+        `http://localhost:${port}/api/transcode/${encodeURIComponent(jobId!)}`,
+        { headers: { 'x-internal-secret': INTERNAL_SECRET } },
+      );
+      expect(poll.status).toBe(200);
+      const body = (await poll.json()) as { status?: string };
+      status = body.status;
+      if (status === 'failed' || status === 'ready') break;
+      await Bun.sleep(100);
+    }
+    expect(status).toBe('failed');
+  });
+
+  test('GET /api/transcode/:jobId returns 404 for unknown job', async () => {
+    const res = await fetch(`http://localhost:${port}/api/transcode/nonexistent-job-id`, {
+      headers: { 'x-internal-secret': INTERNAL_SECRET },
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test('GET /api/transcode/:jobId rejects missing secret with 401', async () => {
+    const res = await fetch(`http://localhost:${port}/api/transcode/any-id`);
+    expect(res.status).toBe(401);
+  });
+});

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

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'bun:test';
+import { createTranscodeJobClient } from './transcodeJobs';
+
+/**
+ * The transport, driven against a scripted binary-server. The two derivative helpers are what
+ * apps call, so what matters is the REQUEST they send (a wrong strategy or a missing
+ * `posterOnly` is a full transcode nobody asked for) and that a failure is a plain negative
+ * answer rather than a throw — every caller's fallback is "render what you rendered before".
+ */
+
+type Call = { url: string; body?: Record<string, unknown>; headers: Record<string, string> };
+
+function scriptedServer(script: {
+  submitStatus?: number;
+  statuses: { status: string; progress?: number; result?: Record<string, unknown> }[];
+}) {
+  const calls: Call[] = [];
+  let polls = 0;
+  const fetchImpl = (async (url: string | URL | Request, init?: RequestInit) => {
+    const href = String(url);
+    const headers = Object.fromEntries(
+      Object.entries((init?.headers ?? {}) as Record<string, string>),
+    );
+    if (init?.method === 'POST') {
+      calls.push({ url: href, body: JSON.parse(String(init.body)), headers });
+      const status = script.submitStatus ?? 202;
+      return new Response(JSON.stringify({ jobId: 'job-1' }), { status });
+    }
+    calls.push({ url: href, headers });
+    const next = script.statuses[Math.min(polls++, script.statuses.length - 1)];
+    return new Response(JSON.stringify(next), { status: 200 });
+  }) as unknown as typeof fetch;
+  return { calls, fetchImpl, polls: () => polls };
+}
+
+const config = (fetchImpl: typeof fetch) => ({
+  baseUrl: 'https://bs.test',
+  appId: 'notes',
+  internalSecret: 's3cret',
+  fetchImpl,
+  pollMs: 0,
+  sleep: async () => {},
+});
+
+describe('createTranscodeJobClient', () => {
+  test('an image job asks for the image strategy with app-scoped keys and the secret', async () => {
+    const server = scriptedServer({ statuses: [{ status: 'ready', result: { hasThumbnail: true } }] });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+
+    const out = await client.imageThumbnail({
+      sourceKey: 'attachments/abc',
+      thumbKey: 'derived/abc-thumb.jpg',
+    });
+
+    expect(out).toEqual({ hasThumbnail: true, hasDisplay: false });
+    const submit = server.calls[0] as Call;
+    expect(submit.url).toBe('https://bs.test/api/transcode');
+    expect(submit.headers['x-internal-secret']).toBe('s3cret');
+    expect(submit.body).toMatchObject({
+      strategy: 'image',
+      sourceKey: 'notes/attachments/abc',
+      binaryKey: 'notes/attachments/abc',
+      posterKey: 'notes/derived/abc-thumb.jpg',
+    });
+    // No displayKey unless one was asked for — a HEIC display JPEG is a second derivative,
+    // not a default.
+    expect(submit.body).not.toHaveProperty('displayKey');
+  });
+
+  test('a display JPEG is requested only when a displayKey is given', async () => {
+    const server = scriptedServer({
+      statuses: [{ status: 'ready', result: { hasThumbnail: true, hasDisplay: true } }],
+    });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+    const out = await client.imageThumbnail({
+      sourceKey: 'attachments/heic',
+      thumbKey: 'derived/heic-thumb.jpg',
+      displayKey: 'derived/heic-display.jpg',
+    });
+    expect(out).toEqual({ hasThumbnail: true, hasDisplay: true });
+    expect((server.calls[0] as Call).body).toMatchObject({
+      displayKey: 'notes/derived/heic-display.jpg',
+    });
+  });
+
+  test('a video poster job is posterOnly — a grid tile must not trigger a full transcode', async () => {
+    const server = scriptedServer({
+      statuses: [{ status: 'ready', result: { hasPoster: true, durationSeconds: 12.5 } }],
+    });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+
+    const out = await client.videoPoster({
+      sourceKey: 'attachments/vid',
+      posterKey: 'derived/vid-poster.jpg',
+    });
+
+    expect(out).toEqual({ hasPoster: true, durationSeconds: 12.5 });
+    expect((server.calls[0] as Call).body).toMatchObject({
+      strategy: 'library',
+      posterOnly: true,
+      posterKey: 'notes/derived/vid-poster.jpg',
+    });
+    // No ladder, no hlsPrefix, no sprite — the expensive half must not be implied.
+    const body = (server.calls[0] as Call).body as Record<string, unknown>;
+    expect(body).not.toHaveProperty('hlsPrefix');
+    expect(body).not.toHaveProperty('spriteKey');
+  });
+
+  test('it polls until the job settles, not once', async () => {
+    const server = scriptedServer({
+      statuses: [
+        { status: 'processing', progress: 10 },
+        { status: 'processing', progress: 80 },
+        { status: 'ready', result: { hasThumbnail: true } },
+      ],
+    });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+    await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' });
+    expect(server.polls()).toBe(3);
+  });
+
+  test('a FAILED job is a negative answer, not a throw — callers fall back to no thumbnail', async () => {
+    const server = scriptedServer({ statuses: [{ status: 'failed' }] });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+    expect(await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).toEqual({
+      hasThumbnail: false,
+      hasDisplay: false,
+    });
+    expect(await client.videoPoster({ sourceKey: 'a', posterKey: 'b' })).toEqual({
+      hasPoster: false,
+      durationSeconds: 0,
+    });
+  });
+
+  test('a ready job that produced nothing still reports nothing', async () => {
+    // binary-server answers `ready` for a source it could probe but not derive from. Reading
+    // the STATUS alone would claim a thumbnail that does not exist, and the consumer would
+    // then render a broken image instead of the text it had.
+    const server = scriptedServer({ statuses: [{ status: 'ready', result: {} }] });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+    expect(await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).toEqual({
+      hasThumbnail: false,
+      hasDisplay: false,
+    });
+  });
+
+  test('a refused submit throws, so a misconfigured secret is loud', async () => {
+    const server = scriptedServer({ submitStatus: 401, statuses: [] });
+    const client = createTranscodeJobClient(config(server.fetchImpl));
+    await expect(client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).rejects.toThrow(/401/);
+  });
+});