cursedbelt-server 1.0.0

package/src/server/private-media/mountPrivateRoutes.ts

@@ -0,0 +1,265 @@
+import type { Context, Hono } from 'hono';
+import { decodeRange, serveRange } from '../storage/streamRange';
+import { type MediaStore, privateHlsFileKey, privateSourceKey } from '../storage/types';
+import { cryptBlobRangeStream, cryptBlobStream, openMeta, unwrapContentKey } from './crypto';
+import type { PrivateIndex } from './index-store';
+import { toPublic } from './index-store';
+import type { UnlockPasswordPolicy, UnlockService } from './unlock';
+
+// Mounts the private-media routes. The unlock / index / reveal endpoints are session-guarded (a
+// fetch CAN send the app's Bearer). The byte routes under /u/<token>/ are UN-guarded (hls.js
+// can't send a Bearer) and authorized by the path-embedded unlock token instead — the same token
+// carries the sealed set key, so the content-key route can unwrap the item's AES-128 key. The
+// encrypted segments themselves are edge-cacheable ciphertext; only the tiny key is gated + no-store.
+
+/** Access-Control-Allow-Origin resolver for split-origin private streaming (media on another
+ * origin than the SPA). Same shape as the storage layer's. */
+export type CorsResolver =
+  | string
+  | string[]
+  | ((requestOrigin: string | undefined) => string | null | undefined);
+
+function resolveAcao(cors: CorsResolver | undefined, reqOrigin: string | undefined): string | null {
+  if (!cors) return null;
+  if (typeof cors === 'string') return cors;
+  if (Array.isArray(cors)) return reqOrigin && cors.includes(reqOrigin) ? reqOrigin : null;
+  return cors(reqOrigin) ?? null;
+}
+
+export type MountPrivateOptions = {
+  store: MediaStore;
+  index: PrivateIndex;
+  unlock: UnlockService;
+  /** Path prefix (default '/_private'). */
+  basePath?: string;
+  /** App session auth → the caller's id + their per-user salt (created lazily, stable). Return
+   * null to reject. Gates unlock/index/reveal (the byte routes use the path token instead). */
+  authorize: (c: Context) => Promise<{ userId: string; userSalt: string } | null>;
+  /** What a supplied password means (default: derive — deniable sets). `gate` verifies it
+   * against the app's accounts and mints the recoverable server-key grant instead. */
+  passwordPolicy?: UnlockPasswordPolicy;
+  /** Cross-origin access for split-origin deploys. */
+  cors?: CorsResolver;
+};
+
+export function mountPrivateRoutes(app: Hono, opts: MountPrivateOptions): void {
+  const base = opts.basePath ?? '/_private';
+  const { store, index, unlock } = opts;
+  const cors = (c: Context, res: Response): Response => {
+    const acao = resolveAcao(opts.cors, c.req.header('origin'));
+    if (acao) {
+      res.headers.set('Access-Control-Allow-Origin', acao);
+      res.headers.set(
+        'Access-Control-Expose-Headers',
+        'Content-Range, Content-Length, Accept-Ranges',
+      );
+      res.headers.append('Vary', 'Origin');
+    }
+    return res;
+  };
+
+  const policy = opts.passwordPolicy ?? { mode: 'derive' as const };
+
+  /** Resolve what the supplied password contributes under the active policy:
+   * derive ⇒ it feeds key derivation (may be undefined ⇒ standard set);
+   * gate ⇒ it must be present AND verify against the app's accounts, then the
+   * set key is the recoverable server one (password never feeds derivation).
+   * Returns an error Response to short-circuit with, or the derivation input. */
+  const resolvePassword = async (
+    c: Context,
+    who: { userId: string; userSalt: string },
+    password: string | undefined,
+  ): Promise<{ derivePassword?: string } | { error: Response }> => {
+    if (policy.mode === 'derive') return { derivePassword: password };
+    if (!password) return { error: c.json({ error: 'password required' }, 401) };
+    if (!(await policy.verifyPassword(who, password))) {
+      return { error: c.json({ error: 'invalid password' }, 401) };
+    }
+    return {}; // verified — standard (server-key) set
+  };
+
+  // POST /unlock { password? } → a token sealing the set key (deniable w/ password, else
+  // standard; under the gate policy the password is verified and the set is always standard).
+  app.post(`${base}/unlock`, async (c) => {
+    const who = await opts.authorize(c);
+    if (!who) return c.json({ error: 'unauthorized' }, 401);
+    const body = (await c.req.json().catch(() => ({}))) as { password?: string };
+    const resolved = await resolvePassword(c, who, body.password || undefined);
+    if ('error' in resolved) return resolved.error;
+    const { token, mode } = await unlock.unlock({
+      userId: who.userId,
+      userSalt: who.userSalt,
+      password: resolved.derivePassword,
+    });
+    return c.json({ token, mode });
+  });
+
+  // GET /index → clear, non-sensitive rows only (size + createdAt + status). Never title/thumb/mode.
+  app.get(`${base}/index`, async (c) => {
+    const who = await opts.authorize(c);
+    if (!who) return c.json({ error: 'unauthorized' }, 401);
+    return c.json({ items: (await index.list(who.userId)).map(toPublic) });
+  });
+
+  // Decrypt every descriptor a set key opens, silently skipping the rest (decrypt-success IS the
+  // membership test — deniability). Shared by the password and token reveal routes.
+  const revealWithKey = async (userId: string, setKey: Buffer) => {
+    const revealed: Array<{ id: string; meta: unknown }> = [];
+    for (const item of await index.list(userId)) {
+      const meta = openMeta(setKey, item.sealedMeta);
+      if (meta !== null) revealed.push({ id: item.id, meta });
+    }
+    return revealed;
+  };
+
+  // POST /reveal { password } → which items that password unlocks (GCM decrypt-success), with
+  // their now-decrypted metadata. Others stay opaque. This is the "try a password" cleanup UX.
+  // Under the gate policy the password must verify first and the standard set is revealed.
+  app.post(`${base}/reveal`, async (c) => {
+    const who = await opts.authorize(c);
+    if (!who) return c.json({ error: 'unauthorized' }, 401);
+    const body = (await c.req.json().catch(() => ({}))) as { password?: string };
+    const resolved = await resolvePassword(c, who, body.password || undefined);
+    if ('error' in resolved) return resolved.error;
+    const setKey = unlock.deriveSetKey({
+      userId: who.userId,
+      userSalt: who.userSalt,
+      password: resolved.derivePassword,
+    });
+    return c.json({ items: await revealWithKey(who.userId, setKey) });
+  });
+
+  // POST /reveal-unlocked { token } → the same reveal, keyed by an UNLOCK TOKEN instead of the
+  // password (the token seals the set key — same mechanism the content-key route uses). Lets an
+  // already-unlocked session list its items without re-typing the password. The token must belong
+  // to the session caller.
+  app.post(`${base}/reveal-unlocked`, async (c) => {
+    const who = await opts.authorize(c);
+    if (!who) return c.json({ error: 'unauthorized' }, 401);
+    const body = (await c.req.json().catch(() => ({}))) as { token?: string };
+    if (!body.token) return c.json({ error: 'token required' }, 400);
+    const grant = await unlock.verify(body.token);
+    if (!grant || grant.userId !== who.userId) return c.json({ error: 'invalid token' }, 401);
+    return c.json({ items: await revealWithKey(who.userId, grant.setKey) });
+  });
+
+  // GET /u/:token/hls/:source/:video/* → the encrypted HLS tree. The `enc.key` sub-path returns
+  // the unwrapped AES-128 content key (gated, no-store); every other path serves the encrypted
+  // segment/playlist (edge-cacheable — hls.js decrypts with the key).
+  app.get(`${base}/u/:token/hls/:source/:video/*`, async (c) => {
+    const raw = c.req.param('token');
+    if (!raw) return c.body(null, 401);
+    const grant = await unlock.verify(raw);
+    if (!grant) return c.body(null, 401);
+    const video = c.req.param('video');
+    const prefix = `${base}/u/${raw}/hls/${c.req.param('source')}/${video}/`;
+    const rel = c.req.path.slice(prefix.length);
+    if (!rel || rel.includes('..')) return c.body(null, 400);
+
+    if (rel.endsWith('enc.key')) {
+      const item = await index.get(grant.userId, video);
+      if (!item) return c.body(null, 404);
+      const content = unwrapContentKey(grant.setKey, item.wrappedContentKey);
+      // null ⇒ this token's set key doesn't own the item (wrong password / wrong mode).
+      if (!content) return c.body(null, 403);
+      // A fresh, tightly-sized ArrayBuffer copy of the 16-byte key — an unambiguous BodyInit
+      // (wrapping the Node Buffer directly can mis-size the response).
+      const keyBytes = Uint8Array.from(content.key);
+      return cors(
+        c,
+        new Response(keyBytes.buffer, {
+          status: 200,
+          headers: { 'Content-Type': 'application/octet-stream', 'Cache-Control': 'no-store' },
+        }),
+      );
+    }
+
+    const mime = rel.endsWith('.m3u8') ? 'application/vnd.apple.mpegurl' : 'video/mp2t';
+    return cors(
+      c,
+      await serveRange(
+        store,
+        privateHlsFileKey(grant.userId, video, rel),
+        mime,
+        c.req.header('range'),
+      ),
+    );
+  });
+
+  // GET /u/:token/file/:id → a private file stored as one AES-128-CTR ciphertext blob at
+  // privateSourceKey. Decrypted server-side per request under the token's set key; the mime
+  // comes from the sealed descriptor, so a token whose set key can't open the item (wrong
+  // password / wrong mode) gets a 403 and never any bytes.
+  //
+  // RANGE SUPPORT (genapp-100): CTR is positionally keyed, so a byte range decrypts from the
+  // block-aligned ciphertext offset with the IV counter advanced (`cryptBlobRangeStream`). This
+  // is what makes a big private VIDEO scrub on a remote-store host, where no local ffmpeg means
+  // no HLS derivatives and the blob route is the only byte path. Plaintext is never stored.
+  app.get(`${base}/u/:token/file/:id`, async (c) => {
+    const raw = c.req.param('token');
+    if (!raw) return c.body(null, 401);
+    const grant = await unlock.verify(raw);
+    if (!grant) return c.body(null, 401);
+    const id = c.req.param('id');
+    const item = await index.get(grant.userId, id);
+    if (!item) return c.body(null, 404);
+    const content = unwrapContentKey(grant.setKey, item.wrappedContentKey);
+    if (!content) return c.body(null, 403);
+    const meta = openMeta<{ mime?: string }>(grant.setKey, item.sealedMeta);
+    const baseHeaders: Record<string, string> = {
+      'Content-Type': meta?.mime || 'application/octet-stream',
+      'Cache-Control': 'no-store',
+      'Accept-Ranges': 'bytes',
+    };
+
+    const key = privateSourceKey(grant.userId, id);
+    const range = item.sizeBytes > 0 ? decodeRange(c.req.header('range'), item.sizeBytes) : { kind: 'full' as const };
+    if (range.kind === 'unsatisfiable') {
+      return cors(
+        c,
+        new Response(null, { status: 416, headers: { 'Content-Range': `bytes */${item.sizeBytes}` } }),
+      );
+    }
+    if (range.kind === 'partial') {
+      // Fetch ciphertext from the BLOCK-ALIGNED start (CTR block = 16 bytes); the range
+      // stream drops the intra-block lead-in so the client sees exactly [start, end].
+      const alignedStart = range.start - (range.start % 16);
+      const stored = await store.getRange(key, { start: alignedStart, end: range.end });
+      if (!stored) return c.body(null, 404);
+      return cors(
+        c,
+        new Response(cryptBlobRangeStream(content, stored.stream, range.start), {
+          status: 206,
+          headers: {
+            ...baseHeaders,
+            'Content-Range': `bytes ${range.start}-${range.end}/${item.sizeBytes}`,
+            'Content-Length': String(range.end - range.start + 1),
+          },
+        }),
+      );
+    }
+
+    const stored = await store.getRange(key);
+    if (!stored) return c.body(null, 404);
+    const headers = { ...baseHeaders };
+    if (item.sizeBytes > 0) headers['Content-Length'] = String(item.sizeBytes);
+    return cors(c, new Response(cryptBlobStream(content, stored.stream), { status: 200, headers }));
+  });
+
+  // Preflight for the cross-origin byte routes.
+  if (opts.cors) {
+    app.options(`${base}/u/*`, (c) => {
+      const acao = resolveAcao(opts.cors, c.req.header('origin'));
+      const headers: Record<string, string> = {
+        'Access-Control-Allow-Methods': 'GET, OPTIONS',
+        'Access-Control-Allow-Headers': 'Range',
+        'Access-Control-Max-Age': '86400',
+      };
+      if (acao) {
+        headers['Access-Control-Allow-Origin'] = acao;
+        headers.Vary = 'Origin';
+      }
+      return c.body(null, 204, headers);
+    });
+  }
+}

package/src/server/private-media/pipeline.spec.ts

@@ -0,0 +1,111 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { createDecipheriv } from 'node:crypto';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { isFfmpegAvailable } from '../media-bun';
+import { createDiskStore } from '../storage/diskStore';
+import { privateHlsFileKey, privateHlsMasterKey } from '../storage/types';
+import { deriveServerSetKey, unwrapContentKey } from './crypto';
+import { processPrivateVideo } from './pipeline';
+
+// Integration test — needs ffmpeg on PATH. When absent (CI image without it) the tests no-op so
+// the suite still passes; the pipeline itself returns 'failed' when ffmpeg is missing (private
+// media can't degrade to plaintext), which is the intended behavior.
+describe('processPrivateVideo (encrypted HLS)', () => {
+  let root: string;
+  let work: string;
+  let clip: string;
+  let hasFfmpeg = false;
+
+  beforeAll(async () => {
+    hasFfmpeg = await isFfmpegAvailable();
+    root = await mkdtemp(path.join(tmpdir(), 'pm-store-'));
+    work = await mkdtemp(path.join(tmpdir(), 'pm-work-'));
+    if (!hasFfmpeg) return;
+    clip = path.join(work, 'src.mp4');
+    const proc = Bun.spawn(
+      [
+        'ffmpeg',
+        '-y',
+        '-f',
+        'lavfi',
+        '-i',
+        'testsrc=size=854x480:rate=15:duration=3',
+        '-pix_fmt',
+        'yuv420p',
+        '-c:v',
+        'libx264',
+        '-preset',
+        'ultrafast',
+        '-t',
+        '3',
+        clip,
+      ],
+      { stdout: 'ignore', stderr: 'ignore' },
+    );
+    await proc.exited;
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+    await rm(work, { recursive: true, force: true });
+  });
+
+  test('encrypts HLS segments; the wrapped key unwraps and decrypts a segment to valid MPEG-TS', async () => {
+    if (!hasFfmpeg) {
+      console.warn('[pipeline.spec] ffmpeg absent — skipping encrypted-HLS integration test');
+      return;
+    }
+    const store = createDiskStore(root);
+    const setKey = deriveServerSetKey('server-secret', 'user-1');
+
+    const res = await processPrivateVideo({
+      store,
+      workDir: work,
+      owner: 't1',
+      id: 'v1',
+      sourcePath: clip,
+      setKey,
+    });
+
+    expect(res.status).toBe('ready');
+    expect(res.hasHls).toBe(true);
+    expect(res.wrappedContentKey).not.toBeNull();
+
+    // The master + a 480p variant playlist exist, and the playlist declares AES-128 encryption.
+    expect(await store.stat(privateHlsMasterKey('t1', 'v1'))).not.toBeNull();
+    const playlistBytes = await store.get(privateHlsFileKey('t1', 'v1', '480/playlist.m3u8'));
+    expect(playlistBytes).not.toBeNull();
+    const playlist = new TextDecoder().decode(playlistBytes as Uint8Array);
+    expect(playlist).toContain('#EXT-X-KEY:METHOD=AES-128');
+    expect(playlist).toContain('URI="enc.key"');
+
+    // The raw content key never leaves wrapped — but unwrapping with the set key recovers it,
+    // and it correctly AES-128-CBC-decrypts a real segment back to an MPEG-TS stream (0x47 sync).
+    const content = unwrapContentKey(setKey, res.wrappedContentKey as string);
+    expect(content).not.toBeNull();
+    expect(content?.key.length).toBe(16);
+
+    const seg = await store.get(privateHlsFileKey('t1', 'v1', '480/seg_00000.ts'));
+    expect(seg).not.toBeNull();
+    const d = createDecipheriv('aes-128-cbc', content?.key as Buffer, content?.iv as Buffer);
+    const plain = Buffer.concat([d.update(Buffer.from(seg as Uint8Array)), d.final()]);
+    expect(plain[0]).toBe(0x47); // MPEG-TS sync byte ⇒ decryption + key are correct
+  }, 30_000);
+
+  test('returns failed when ffmpeg is unavailable (private media cannot go plaintext)', async () => {
+    // Documents the contract; only meaningfully exercised on a machine without ffmpeg.
+    if (hasFfmpeg) return;
+    const store = createDiskStore(root);
+    const res = await processPrivateVideo({
+      store,
+      workDir: work,
+      owner: 't',
+      id: 'v',
+      sourcePath: '/nonexistent',
+      setKey: deriveServerSetKey('s', 'u'),
+    });
+    expect(res.status).toBe('failed');
+    expect(res.wrappedContentKey).toBeNull();
+  });
+});

package/src/server/private-media/pipeline.ts

@@ -0,0 +1,170 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import {
+  hlsLadderArgs,
+  isFfmpegAvailable,
+  LIBRARY_CRF,
+  probeVideoStream,
+  resolveLadder,
+  runFfmpegProgress,
+} from '../media-bun';
+import {
+  type MediaStore,
+  privateHlsFileKey,
+  privateHlsMasterKey,
+  privateSourceKey,
+} from '../storage/types';
+import { cryptBlobStream, generateContentKey, wrapContentKey } from './crypto';
+
+// ── Encrypted-HLS pipeline (private media) ──────────────────────────────────────
+// Transcodes a private upload into an AES-128-encrypted HLS ladder: ffmpeg encrypts every
+// segment with a per-item content key (via a key-info file), so the segments are ciphertext at
+// rest (Spotlight-safe, opaque names) AND safe to edge-cache — the player fetches the content
+// key from the gated key route and decrypts client-side (fast). The plaintext source is staged
+// only in the work dir and never persisted; only the encrypted segments + playlists are stored.
+// The content key is returned WRAPPED under the caller's set key (server-held or password-derived).
+
+const KEY_URI = 'enc.key'; // relative in the playlist → the gated key route serves it per-video
+
+export type PrivateProcessResult = {
+  status: ProcessingStatus;
+  durationSeconds: number;
+  hasHls: boolean;
+  /** The AES-128 content key + IV, wrapped under the caller's set key. Null if processing failed. */
+  wrappedContentKey: string | null;
+};
+
+export type PrivateProcessOptions = {
+  store: MediaStore;
+  /** Scratch dir for ffmpeg I/O + the transient key file (cleaned up afterwards). */
+  workDir: string;
+  owner: string;
+  id: string;
+  /** Local PLAINTEXT source, staged by the caller; never persisted (deleted with the job dir). */
+  sourcePath: string;
+  /** The mode key (server-held or password-derived) the content key is wrapped under. */
+  setKey: Buffer;
+  ladderHeights?: number[];
+  onProgress?: (status: ProcessingStatus, pct: number) => void;
+};
+
+async function uploadTree(store: MediaStore, dir: string, owner: string, id: string) {
+  const walk = async (rel: string): Promise<void> => {
+    const entries = await readdir(path.join(dir, rel), { withFileTypes: true });
+    for (const e of entries) {
+      const childRel = rel ? path.join(rel, e.name) : e.name;
+      if (e.isDirectory()) {
+        await walk(childRel);
+      } else {
+        const mime = e.name.endsWith('.m3u8') ? 'application/vnd.apple.mpegurl' : 'video/mp2t';
+        const file = Bun.file(path.join(dir, childRel));
+        await store.putStream(privateHlsFileKey(owner, id, childRel), file.stream(), mime, {
+          contentLength: file.size,
+        });
+      }
+    }
+  };
+  await walk('');
+}
+
+export async function processPrivateVideo(
+  opts: PrivateProcessOptions,
+): Promise<PrivateProcessResult> {
+  const { store, workDir, owner, id, sourcePath, setKey, onProgress } = opts;
+  const report = (s: ProcessingStatus, p: number) => onProgress?.(s, p);
+  const failed: PrivateProcessResult = {
+    status: 'failed',
+    durationSeconds: 0,
+    hasHls: false,
+    wrappedContentKey: null,
+  };
+
+  // Private media MUST be encrypted — unlike public it can't degrade to a plaintext fallback.
+  if (!(await isFfmpegAvailable())) return failed;
+
+  const jobDir = path.join(workDir, owner, id);
+  await mkdir(jobDir, { recursive: true });
+
+  try {
+    report('processing', 1);
+    const probe = await probeVideoStream(sourcePath);
+
+    // Mint the AES-128 content key + write the ffmpeg key-info file (key URI / key file / IV).
+    const content = generateContentKey();
+    const keyFile = path.join(jobDir, 'enc.key.bin');
+    await writeFile(keyFile, content.key);
+    const keyInfoFile = path.join(jobDir, 'enc.keyinfo');
+    await writeFile(keyInfoFile, `${KEY_URI}\n${keyFile}\n${content.iv.toString('hex')}\n`);
+
+    const heights = resolveLadder(opts.ladderHeights ?? [480, 720, 1080], probe.height);
+    const hlsDir = path.join(jobDir, 'hls');
+    await mkdir(hlsDir, { recursive: true });
+
+    const ok = await runFfmpegProgress(
+      hlsLadderArgs(sourcePath, hlsDir, {
+        heights,
+        crf: Number(LIBRARY_CRF),
+        hasAudio: probe.hasAudio,
+        keyInfoFile,
+      }),
+      probe.duration,
+      (pct) => report('processing', Math.max(1, Math.min(98, pct))),
+    );
+    if (!ok) return failed;
+
+    // Upload ONLY the encrypted segments + playlists — never the key file (served via the route).
+    await uploadTree(store, hlsDir, owner, id);
+
+    report('ready', 100);
+    return {
+      status: 'ready',
+      durationSeconds: probe.duration,
+      hasHls: (await store.stat(privateHlsMasterKey(owner, id))) !== null,
+      wrappedContentKey: wrapContentKey(setKey, content),
+    };
+  } catch {
+    report('failed', 0);
+    return failed;
+  } finally {
+    // Wipe the job dir — the plaintext source, the raw key file, and the outputs all vanish.
+    await rm(jobDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+// ── Encrypted-blob pipeline (private NON-video files: photos, docs, audio) ────────
+// A non-video private upload has no HLS ladder to build — it becomes ONE AES-128-CTR ciphertext
+// blob at privateSourceKey, under the same per-item content-key material the HLS path wraps.
+// Serving is the gated blob route in mountPrivateRoutes (decrypts server-side per request); the
+// plaintext staging file is the caller's to wipe, mirroring processPrivateVideo.
+
+export type PrivateBlobResult = {
+  status: ProcessingStatus;
+  sizeBytes: number;
+  /** The content key + IV, wrapped under the caller's set key. Null if processing failed. */
+  wrappedContentKey: string | null;
+};
+
+export async function processPrivateBlob(opts: {
+  store: MediaStore;
+  owner: string;
+  id: string;
+  /** Local PLAINTEXT source, staged by the caller; never persisted (caller deletes it). */
+  sourcePath: string;
+  setKey: Buffer;
+}): Promise<PrivateBlobResult> {
+  try {
+    const file = Bun.file(opts.sourcePath);
+    const sizeBytes = file.size; // CTR is length-preserving, so plaintext size == stored size
+    const content = generateContentKey();
+    await opts.store.putStream(
+      privateSourceKey(opts.owner, opts.id),
+      cryptBlobStream(content, file.stream()),
+      'application/octet-stream',
+      { contentLength: sizeBytes },
+    );
+    return { status: 'ready', sizeBytes, wrappedContentKey: wrapContentKey(opts.setKey, content) };
+  } catch {
+    return { status: 'failed', sizeBytes: 0, wrappedContentKey: null };
+  }
+}