cursedbelt-server 1.0.0

package/src/server/paths/appDataHome.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a machine keeps an app's data — as CONFIGURATION, never as a convention
+ * baked into the library.
+ *
+ * ## What this replaces, and why it is a defect rather than untidiness
+ *
+ * Until 2026-09-13 three live modules in this package joined the ambient home
+ * directory to a hardcoded dotfolder belonging to the previous generation: the
+ * retention store, the archive, and `resolveAppDataRoot`. This package is
+ * PUBLISHED. Anybody who installed it got a library that went looking for a
+ * directory in their home that has nothing to do with them, and — worse — wrote
+ * into it if it happened to exist.
+ *
+ * A library may not know the name of a directory in somebody's home. It may know
+ * two things: what the caller told it, and what the operating system says the
+ * convention is. That is the whole ladder below.
+ *
+ * ## The ladder
+ *
+ *   1. an explicit `override` — a `--data-root` flag, a host's own resolution;
+ *   2. `$APP_DATA_HOME` — the ONE env var, for a machine that keeps every app's
+ *      data under one root so a fleet-wide tool can see all of it at once;
+ *   3. `$XDG_DATA_HOME` — the user already told the OS where data goes;
+ *   4. the platform default: `~/Library/Application Support` on macOS,
+ *      `~/.local/share` everywhere else.
+ *
+ * `$XDG_DATA_HOME` is honored on macOS too. It is not the platform's own
+ * convention there, but a user who sets it has stated a preference, and a
+ * preference outranks a default on any platform.
+ *
+ * Nothing here touches the filesystem: it is a pure mapping from environment to
+ * path, so a caller can reason about the answer before creating anything, and a
+ * test can assert both platforms on one machine.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The one env var. A machine with a shared data root sets this and nothing else. */
+export const APP_DATA_HOME_ENV = "APP_DATA_HOME";
+
+/** The cross-desktop convention this honors ahead of the platform default. */
+export const XDG_DATA_HOME_ENV = "XDG_DATA_HOME";
+
+export interface ResolveAppDataHomeOptions {
+	/** An explicit answer from the caller. Wins outright — this is the "argument" half. */
+	readonly override?: string;
+	/** Environment to read. Injected by tests; defaults to the process's own. */
+	readonly env?: Record<string, string | undefined>;
+	/**
+	 * Platform to resolve for. Injected by tests so both branches are proved on one
+	 * machine; defaults to the running platform.
+	 */
+	readonly platform?: string;
+}
+
+/** Trimmed, or undefined — an env var set to whitespace is not a configuration. */
+function configured(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+/**
+ * The machine's app-data home. See the module note for the ordering rationale.
+ */
+export function resolveAppDataHome(options: ResolveAppDataHomeOptions = {}): string {
+	const env = options.env ?? process.env;
+	const override = configured(options.override);
+	if (override) return override;
+
+	const appDataHome = configured(env[APP_DATA_HOME_ENV]);
+	if (appDataHome) return appDataHome;
+
+	const xdg = configured(env[XDG_DATA_HOME_ENV]);
+	if (xdg) return xdg;
+
+	// `env.HOME` rather than `homedir()` alone, so a caller passing an env object
+	// gets a resolution it can actually control — every test below depends on it,
+	// and so does any host that boots an app under a different account.
+	const home = configured(env.HOME) ?? homedir();
+	const platform = options.platform ?? process.platform;
+	return platform === "darwin"
+		? join(home, "Library", "Application Support")
+		: join(home, ".local", "share");
+}

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

@@ -0,0 +1,165 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Hono } from 'hono';
+import { createDiskStore } from '../storage/diskStore';
+import type { MediaStore } from '../storage/types';
+import { generateUserSalt, sealMeta } from './crypto';
+import { createMemoryPrivateIndex } from './index-store';
+import { mountPrivateRoutes } from './mountPrivateRoutes';
+import { processPrivateBlob } from './pipeline';
+import { createUnlockService } from './unlock';
+
+// The gated blob route: a private NON-video file (photo/doc) is one AES-128-CTR ciphertext at
+// privateSourceKey; the route decrypts under the unlock token's set key and serves plaintext
+// with the sealed descriptor's mime. A token whose set key doesn't own the item gets 403.
+
+const unlock = createUnlockService({ serverSecret: 'srv', unlockSecret: 'unlock' });
+const salt = generateUserSalt();
+const PLAINTEXT = 'plain photo bytes ✻ not for strangers';
+
+describe('private blob route', () => {
+  let root: string;
+  let store: MediaStore;
+  const index = createMemoryPrivateIndex();
+  const app = new Hono();
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(tmpdir(), 'pm-blob-'));
+    store = createDiskStore(path.join(root, 'store'));
+    mountPrivateRoutes(app, {
+      store,
+      index,
+      unlock,
+      authorize: async () => ({ userId: 'u1', userSalt: salt }),
+    });
+
+    // Encrypt a staged plaintext under the 'alpha' set and index it, mirroring ingestPrivate.
+    const src = path.join(root, 'src.bin');
+    await writeFile(src, PLAINTEXT);
+    const setKey = unlock.deriveSetKey({ userId: 'u1', userSalt: salt, password: 'alpha' });
+    const res = await processPrivateBlob({ store, owner: 'u1', id: 'b1', sourcePath: src, setKey });
+    expect(res.status).toBe('ready');
+    await index.add({
+      id: 'b1',
+      owner: 'u1',
+      sizeBytes: res.sizeBytes,
+      createdAt: 1,
+      status: 'ready',
+      keyMode: 'deniable',
+      wrappedContentKey: res.wrappedContentKey ?? '',
+      sealedMeta: sealMeta(setKey, { name: 'secret.jpg', mime: 'image/jpeg', tags: [] }),
+    });
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const tokenFor = async (password: string) =>
+    (await unlock.unlock({ userId: 'u1', userSalt: salt, password })).token;
+
+  test('serves decrypted plaintext with the sealed mime to the owning set', async () => {
+    const res = await app.request(`/_private/u/${await tokenFor('alpha')}/file/b1`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('image/jpeg');
+    expect(res.headers.get('cache-control')).toBe('no-store');
+    expect(await res.text()).toBe(PLAINTEXT);
+  });
+
+  test("a valid token from the WRONG set can't open it (403, zero bytes)", async () => {
+    const res = await app.request(`/_private/u/${await tokenFor('bravo')}/file/b1`);
+    expect(res.status).toBe(403);
+  });
+
+  test('garbage token → 401; unknown id → 404', async () => {
+    expect((await app.request('/_private/u/not-a-token/file/b1')).status).toBe(401);
+    const res = await app.request(`/_private/u/${await tokenFor('alpha')}/file/nope`);
+    expect(res.status).toBe(404);
+  });
+});
+
+// ── Range/CTR-seek (genapp-100) ──────────────────────────────────────────────
+// A big private VIDEO on a remote-store host has no HLS derivatives — this
+// route is its only byte path, so Range is what makes it scrub. CTR decrypts
+// from the block-aligned offset with the IV counter advanced; these pin the
+// exact-slice contract at aligned, unaligned, suffix, and unsatisfiable ranges.
+describe('private blob route — Range (CTR seek)', () => {
+  let root: string;
+  let store: MediaStore;
+  const index = createMemoryPrivateIndex();
+  const app = new Hono();
+  // >3 CTR blocks with an unaligned tail, so mid-block seeks are meaningful.
+  const BYTES = Buffer.from(Array.from({ length: 1000 }, (_, i) => i % 251));
+
+  beforeAll(async () => {
+    root = await mkdtemp(path.join(tmpdir(), 'pm-blob-range-'));
+    store = createDiskStore(path.join(root, 'store'));
+    mountPrivateRoutes(app, {
+      store,
+      index,
+      unlock,
+      authorize: async () => ({ userId: 'u1', userSalt: salt }),
+    });
+    const src = path.join(root, 'clip.bin');
+    await writeFile(src, BYTES);
+    const setKey = unlock.deriveSetKey({ userId: 'u1', userSalt: salt, password: 'alpha' });
+    const res = await processPrivateBlob({ store, owner: 'u1', id: 'v1', sourcePath: src, setKey });
+    expect(res.status).toBe('ready');
+    await index.add({
+      id: 'v1',
+      owner: 'u1',
+      sizeBytes: res.sizeBytes,
+      createdAt: 1,
+      status: 'ready',
+      keyMode: 'deniable',
+      wrappedContentKey: res.wrappedContentKey ?? '',
+      sealedMeta: sealMeta(setKey, { name: 'clip.mp4', mime: 'video/mp4', tags: [] }),
+    });
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const token = async () => (await unlock.unlock({ userId: 'u1', userSalt: salt, password: 'alpha' })).token;
+  const get = async (range?: string) =>
+    app.request(`/_private/u/${await token()}/file/v1`, range ? { headers: { range } } : undefined);
+
+  test('a full read advertises Accept-Ranges and still decrypts whole', async () => {
+    const res = await get();
+    expect(res.status).toBe(200);
+    expect(res.headers.get('accept-ranges')).toBe('bytes');
+    expect(Buffer.from(await res.arrayBuffer()).equals(BYTES)).toBe(true);
+  });
+
+  test('a block-aligned range decrypts the exact slice as 206', async () => {
+    const res = await get('bytes=160-479');
+    expect(res.status).toBe(206);
+    expect(res.headers.get('content-range')).toBe('bytes 160-479/1000');
+    expect(res.headers.get('content-length')).toBe('320');
+    expect(Buffer.from(await res.arrayBuffer()).equals(BYTES.subarray(160, 480))).toBe(true);
+  });
+
+  test('an UNALIGNED mid-block range decrypts the exact slice (the CTR counter + lead-in drop)', async () => {
+    const res = await get('bytes=7-300');
+    expect(res.status).toBe(206);
+    expect(res.headers.get('content-range')).toBe('bytes 7-300/1000');
+    expect(Buffer.from(await res.arrayBuffer()).equals(BYTES.subarray(7, 301))).toBe(true);
+  });
+
+  test('an open-ended range runs to the last byte; a suffix range serves the tail', async () => {
+    const open = await get('bytes=990-');
+    expect(open.status).toBe(206);
+    expect(Buffer.from(await open.arrayBuffer()).equals(BYTES.subarray(990))).toBe(true);
+    const suffix = await get('bytes=-25');
+    expect(suffix.status).toBe(206);
+    expect(suffix.headers.get('content-range')).toBe('bytes 975-999/1000');
+    expect(Buffer.from(await suffix.arrayBuffer()).equals(BYTES.subarray(975))).toBe(true);
+  });
+
+  test('an out-of-bounds range answers 416 with the total', async () => {
+    const res = await get('bytes=1000-1200');
+    expect(res.status).toBe(416);
+    expect(res.headers.get('content-range')).toBe('bytes */1000');
+  });
+});

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

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  derivePasswordSetKey,
+  deriveServerSetKey,
+  generateContentKey,
+  generateUserSalt,
+  openMeta,
+  sealMeta,
+  unwrapContentKey,
+  wrapContentKey,
+} from './crypto';
+
+describe('private-media crypto core', () => {
+  const salt = generateUserSalt();
+
+  test('same password + salt → same key; different password → different key', () => {
+    const a = derivePasswordSetKey('hunter2', salt);
+    const a2 = derivePasswordSetKey('hunter2', salt);
+    const b = derivePasswordSetKey('other-pass', salt);
+    expect(a.equals(a2)).toBe(true);
+    expect(a.equals(b)).toBe(false);
+    expect(a.length).toBe(32);
+  });
+
+  test('the same password under different user salts yields different keys', () => {
+    const s2 = generateUserSalt();
+    expect(derivePasswordSetKey('pw', salt).equals(derivePasswordSetKey('pw', s2))).toBe(false);
+  });
+
+  test('server key is recoverable and distinct from any password key', () => {
+    const srv = deriveServerSetKey('server-secret', 'user-1');
+    expect(srv.equals(deriveServerSetKey('server-secret', 'user-1'))).toBe(true);
+    expect(srv.equals(deriveServerSetKey('server-secret', 'user-2'))).toBe(false);
+    expect(srv.equals(derivePasswordSetKey('server-secret', salt))).toBe(false);
+  });
+
+  test('sealMeta/openMeta round-trips; a wrong key returns null (the membership test)', () => {
+    const key = derivePasswordSetKey('pw-A', salt);
+    const wrong = derivePasswordSetKey('pw-B', salt);
+    const sealed = sealMeta(key, { title: 'Secret Clip', notes: 'private', tags: ['x'] });
+    expect(openMeta<{ title: string }>(key, sealed)?.title).toBe('Secret Clip');
+    expect(openMeta(wrong, sealed)).toBeNull(); // wrong password ⇒ not a member, no info leak
+  });
+
+  test('content key wrap/unwrap round-trips; wrong key ⇒ null', () => {
+    const key = derivePasswordSetKey('pw', salt);
+    const wrong = deriveServerSetKey('srv', 'u');
+    const content = generateContentKey();
+    expect(content.key.length).toBe(16); // AES-128
+    expect(content.iv.length).toBe(16);
+    const wrapped = wrapContentKey(key, content);
+    const unwrapped = unwrapContentKey(key, wrapped);
+    expect(unwrapped?.key.equals(content.key)).toBe(true);
+    expect(unwrapped?.iv.equals(content.iv)).toBe(true);
+    expect(unwrapContentKey(wrong, wrapped)).toBeNull();
+  });
+
+  test('a tampered envelope decrypts to null, not garbage', () => {
+    const key = derivePasswordSetKey('pw', salt);
+    const sealed = sealMeta(key, { title: 't' });
+    expect(openMeta(key, `${sealed}x`)).toBeNull();
+  });
+});
+
+describe('incrementIv (genapp-100 CTR seek)', () => {
+  test('adds blocks big-endian with byte carry', async () => {
+    const { incrementIv } = await import('./crypto');
+    const iv = Buffer.alloc(16);
+    iv[15] = 0xff;
+    const plus1 = incrementIv(iv, 1);
+    expect(plus1[15]).toBe(0x00);
+    expect(plus1[14]).toBe(0x01);
+    // A large jump carries across multiple bytes: 0x01_0000 blocks.
+    const jump = incrementIv(Buffer.alloc(16), 0x010000);
+    expect(jump[13]).toBe(0x01);
+    expect(jump[14]).toBe(0x00);
+    expect(jump[15]).toBe(0x00);
+    // The input IV is never mutated.
+    expect(iv[15]).toBe(0xff);
+  });
+});

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

@@ -0,0 +1,155 @@
+import { createCipheriv, randomBytes } from 'node:crypto';
+import { decryptSecret, deriveKey, encryptSecret } from 'cwip/node';
+
+// ── private-media crypto core ───────────────────────────────────────────────────
+// The reusable heart of encrypted private media. Pure composition of cwip's `secretBox`
+// (scrypt `deriveKey` + AES-256-GCM `encryptSecret`/`decryptSecret`) — whose own docs describe
+// exactly our two key modes: derive from a SERVER SECRET (recoverable "standard") vs from the
+// USER'S PASSWORD (zero-knowledge "deniable"). We use scrypt (slow, brute-force-resistant) for
+// the password KDF — NOT cursedbelt's vault HKDF, which is fast and password-unsafe.
+//
+// Streaming stays fast because the bytes are AES-128 HLS segments the player decrypts (edge-
+// cacheable); this module only mints/wraps the small 16-byte content key + seals metadata.
+
+export type KeyMode = 'standard' | 'deniable';
+
+/** A random per-user salt (non-secret, stored plaintext, stable once created). Domain-separates
+ * a user's password-derived keys so the same password yields different keys across users. */
+export const generateUserSalt = (): string => randomBytes(16).toString('base64url');
+
+/** Zero-knowledge set key: scrypt(password, per-user salt). The server never stores this (or a
+ * hash of it); it exists only transiently after an unlock. Different passwords → disjoint sets. */
+export const derivePasswordSetKey = (password: string, userSalt: string): Buffer =>
+  deriveKey(password, `pmedia:${userSalt}`);
+
+/** Recoverable set key: scrypt(serverSecret, userId). The server can always derive it, so
+ * `standard`-mode media is decryptable once private is unlocked (session-gated) — protects a
+ * stolen disk / Finder / backups, but a compromised running server can decrypt. */
+export const deriveServerSetKey = (serverSecret: string, userId: string): Buffer =>
+  deriveKey(serverSecret, `pmedia-srv:${userId}`);
+
+// ── Sealed metadata envelope (title / thumbnail key / notes / tags) ──────────────
+// Encrypted under the set key; NEVER stored in the plaintext index. A successful decrypt is
+// also the deniable MEMBERSHIP TEST — trying a password reveals only the items it opens.
+
+export const sealMeta = (setKey: Buffer, meta: unknown): string =>
+  encryptSecret(JSON.stringify(meta), setKey);
+
+/** Open a sealed envelope, or null if this key doesn't own it (wrong password / mode key).
+ * The null return IS the membership signal — no stored set identifier is needed. */
+export function openMeta<T = unknown>(setKey: Buffer, sealed: string): T | null {
+  try {
+    return JSON.parse(decryptSecret(sealed, setKey)) as T;
+  } catch {
+    return null;
+  }
+}
+
+// ── AES-128 HLS content key: minted per item, WRAPPED under the set key ───────────
+// The raw 16-byte key + 16-byte IV drive ffmpeg's `-hls_key_info_file` (AES-128 segments). Only
+// the wrapped form is stored; the key route unwraps it (with the unlock-provided set key) and
+// returns the raw key to hls.js, which decrypts segments client-side.
+
+export type ContentKey = { key: Buffer; iv: Buffer };
+
+export const generateContentKey = (): ContentKey => ({
+  key: randomBytes(16), // AES-128
+  iv: randomBytes(16),
+});
+
+export const wrapContentKey = (setKey: Buffer, content: ContentKey): string =>
+  encryptSecret(`${content.key.toString('base64')}.${content.iv.toString('base64')}`, setKey);
+
+/** Unwrap a content key, or null if the set key can't open it (wrong password / mode key). */
+export function unwrapContentKey(setKey: Buffer, wrapped: string): ContentKey | null {
+  try {
+    const [k, iv] = decryptSecret(wrapped, setKey).split('.');
+    if (!k || !iv) return null;
+    return { key: Buffer.from(k, 'base64'), iv: Buffer.from(iv, 'base64') };
+  } catch {
+    return null;
+  }
+}
+
+// ── Whole-file blob cipher (non-video private files: photos, docs) ────────────────
+// AES-128-CTR under the item's content key — the same key/IV material the HLS path wraps, so
+// wrap/unwrap is shared. CTR is length-preserving and streaming (no padding, no buffering), and
+// encrypt/decrypt are the same operation. Tamper-evidence comes from the GCM-sealed descriptor +
+// the gated serve route (parity with the encrypted-HLS segments, which are CBC-without-MAC too).
+
+/** Pipe a byte stream through the item's AES-128-CTR keystream. Symmetric: pass ciphertext to
+ * decrypt, plaintext to encrypt. */
+/** Big-endian increment of a 16-byte CTR IV by `blocks` — the counter arithmetic that lets a
+ * decryptor start mid-stream (genapp-100: Range/seek on private blobs). */
+export function incrementIv(iv: Buffer, blocks: number): Buffer {
+  const out = Buffer.from(iv);
+  let carry = BigInt(blocks);
+  for (let i = out.length - 1; i >= 0 && carry > 0n; i--) {
+    const sum = BigInt(out[i]) + (carry & 0xffn);
+    out[i] = Number(sum & 0xffn);
+    carry = (carry >> 8n) + (sum >> 8n);
+  }
+  return out;
+}
+
+/**
+ * Decrypt a CTR ciphertext stream that starts at the BLOCK-ALIGNED offset covering plaintext
+ * byte `startOffset`, dropping the intra-block lead-in — the seek half of {@link cryptBlobStream}.
+ * CTR is length-preserving and positionally keyed, so byte N of plaintext only needs ciphertext
+ * from block ⌊N/16⌋ onward with the IV counter advanced by that many blocks (genapp-100: this is
+ * what makes big private videos scrub on a remote-store host with no local derivatives).
+ */
+export function cryptBlobRangeStream(
+  content: ContentKey,
+  stream: ReadableStream<Uint8Array>,
+  startOffset: number,
+): ReadableStream<Uint8Array> {
+  const BLOCK = 16;
+  const blocks = Math.floor(startOffset / BLOCK);
+  let drop = startOffset % BLOCK;
+  const cipher = createCipheriv('aes-128-ctr', content.key, incrementIv(content.iv, blocks));
+  return stream.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        let out = cipher.update(chunk);
+        if (drop > 0) {
+          const skip = Math.min(drop, out.byteLength);
+          out = out.subarray(skip);
+          drop -= skip;
+        }
+        if (out.byteLength > 0) {
+          controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+        }
+      },
+      flush(controller) {
+        const out = cipher.final(); // empty for CTR — kept for cipher-contract completeness
+        if (out.byteLength > 0) {
+          controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+        }
+      },
+    }),
+  );
+}
+
+export function cryptBlobStream(
+  content: ContentKey,
+  stream: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const cipher = createCipheriv('aes-128-ctr', content.key, content.iv);
+  return stream.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        const out = cipher.update(chunk);
+        if (out.byteLength > 0) {
+          controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+        }
+      },
+      flush(controller) {
+        const out = cipher.final(); // empty for CTR — kept for cipher-contract completeness
+        if (out.byteLength > 0) {
+          controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+        }
+      },
+    }),
+  );
+}

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

@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { createDiskStore } from '../storage/diskStore';
+import { generateUserSalt, sealMeta } from './crypto';
+import { createMemoryPrivateIndex } from './index-store';
+import { mountPrivateRoutes } from './mountPrivateRoutes';
+import { createUnlockService } from './unlock';
+
+// The gate password policy: the password is an ACCESS CHECK against the app's own accounts
+// (e.g. the login store), not a key-derivation input. Correct password ⇒ a STANDARD
+// (recoverable, server-key) grant; wrong/absent password ⇒ 401; password changes never
+// orphan content because the set key never depended on the password.
+
+const unlock = createUnlockService({ serverSecret: 'srv', unlockSecret: 'unlock' });
+const salt = generateUserSalt();
+
+function gateApp(verify: (password: string) => boolean) {
+  const app = new Hono();
+  const index = createMemoryPrivateIndex();
+  mountPrivateRoutes(app, {
+    store: createDiskStore('/tmp/unused-pm-gate'),
+    index,
+    unlock,
+    authorize: async () => ({ userId: 'u1', userSalt: salt }),
+    passwordPolicy: {
+      mode: 'gate',
+      verifyPassword: async (_who, password) => verify(password),
+    },
+  });
+  return { app, index };
+}
+
+const post = (app: Hono, path: string, body: unknown) =>
+  app.request(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+describe('unlock gate policy', () => {
+  test('correct password ⇒ standard grant (key never derived from the password)', async () => {
+    const { app } = gateApp((pw) => pw === 'login-pw');
+    const res = await post(app, '/_private/unlock', { password: 'login-pw' });
+    expect(res.status).toBe(200);
+    const { token, mode } = (await res.json()) as { token: string; mode: string };
+    expect(mode).toBe('standard');
+    const grant = await unlock.verify(token);
+    expect(grant?.mode).toBe('standard');
+    // The grant's key equals the server-derived one — NOT a password derivation.
+    expect(grant?.setKey.equals(unlock.deriveSetKey({ userId: 'u1', userSalt: salt }))).toBe(true);
+  });
+
+  test('wrong password ⇒ 401, no token', async () => {
+    const { app } = gateApp((pw) => pw === 'login-pw');
+    const res = await post(app, '/_private/unlock', { password: 'wrong' });
+    expect(res.status).toBe(401);
+  });
+
+  test('missing password ⇒ 401 (no silent session unlock under gate)', async () => {
+    const { app } = gateApp(() => true);
+    const res = await post(app, '/_private/unlock', {});
+    expect(res.status).toBe(401);
+  });
+
+  test('reveal under gate verifies then reveals the STANDARD set', async () => {
+    const { app, index } = gateApp((pw) => pw === 'login-pw');
+    const standardKey = unlock.deriveSetKey({ userId: 'u1', userSalt: salt });
+    await index.add({
+      id: 'item1',
+      owner: 'u1',
+      sealedMeta: sealMeta(standardKey, { name: 'secret.jpg', mime: 'image/jpeg', tags: [] }),
+      wrappedContentKey: 'unused',
+      sizeBytes: 3,
+      createdAt: Date.now(),
+      status: 'ready',
+      keyMode: 'standard',
+    });
+    const bad = await post(app, '/_private/reveal', { password: 'nope' });
+    expect(bad.status).toBe(401);
+    const good = await post(app, '/_private/reveal', { password: 'login-pw' });
+    expect(good.status).toBe(200);
+    const { items } = (await good.json()) as { items: Array<{ id: string }> };
+    expect(items.map((i) => i.id)).toEqual(['item1']);
+  });
+
+  test('derive policy (default) still mints deniable sets from passwords', async () => {
+    const app = new Hono();
+    mountPrivateRoutes(app, {
+      store: createDiskStore('/tmp/unused-pm-gate'),
+      index: createMemoryPrivateIndex(),
+      unlock,
+      authorize: async () => ({ userId: 'u1', userSalt: salt }),
+    });
+    const res = await post(app, '/_private/unlock', { password: 'anything' });
+    expect(res.status).toBe(200);
+    expect(((await res.json()) as { mode: string }).mode).toBe('deniable');
+  });
+});

package/src/server/private-media/index-store.ts

@@ -0,0 +1,83 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import type { KeyMode } from './crypto';
+
+// ── Private index ───────────────────────────────────────────────────────────────
+// Per-user rows for encrypted media. The row holds ONLY non-sensitive facts in the clear
+// (size, created-at, status) so a user can see "N locked files, X GB" and prune ones whose
+// password they've lost. The sensitive parts — title / thumbnail / notes / tags — live in the
+// AES-GCM `sealedMeta` envelope, and the AES-128 content key lives in `wrappedContentKey`; both
+// are opaque without the set key. The public projection (`toPublic`) is what the index endpoint
+// returns — it strips every secret, including the key MODE (so the clear index can't even hint
+// which rows are deniable). An app swaps the in-memory store for a SQLite-backed one (see
+// cursedbelt-server/sqlite) without touching the routes.
+
+export type PrivateItem = {
+  id: string;
+  owner: string;
+  sizeBytes: number;
+  createdAt: number;
+  status: ProcessingStatus;
+  keyMode: KeyMode;
+  /** AES-128 content key + IV, wrapped under the item's set key. */
+  wrappedContentKey: string;
+  /** AES-GCM envelope of { title, notes, tags, durationSeconds, … } under the item's set key. */
+  sealedMeta: string;
+};
+
+/** What the index endpoint exposes — clear, non-sensitive facts only. No title/thumb/notes/tags,
+ * no key mode, no wrapped key. */
+export type PrivateIndexRow = {
+  id: string;
+  sizeBytes: number;
+  createdAt: number;
+  status: ProcessingStatus;
+};
+
+export const toPublic = (item: PrivateItem): PrivateIndexRow => ({
+  id: item.id,
+  sizeBytes: item.sizeBytes,
+  createdAt: item.createdAt,
+  status: item.status,
+});
+
+export interface PrivateIndex {
+  add(item: PrivateItem): Promise<void>;
+  get(owner: string, id: string): Promise<PrivateItem | null>;
+  list(owner: string): Promise<PrivateItem[]>;
+  update(
+    owner: string,
+    id: string,
+    patch: Partial<Omit<PrivateItem, 'id' | 'owner'>>,
+  ): Promise<void>;
+  remove(owner: string, id: string): Promise<void>;
+}
+
+export function createMemoryPrivateIndex(): PrivateIndex {
+  const byOwner = new Map<string, Map<string, PrivateItem>>();
+  const bucket = (owner: string) => {
+    let m = byOwner.get(owner);
+    if (!m) {
+      m = new Map();
+      byOwner.set(owner, m);
+    }
+    return m;
+  };
+  return {
+    async add(item) {
+      bucket(item.owner).set(item.id, item);
+    },
+    async get(owner, id) {
+      return bucket(owner).get(id) ?? null;
+    },
+    async list(owner) {
+      return [...bucket(owner).values()].sort((a, b) => b.createdAt - a.createdAt);
+    },
+    async update(owner, id, patch) {
+      const item = bucket(owner).get(id);
+      if (item) bucket(owner).set(id, { ...item, ...patch });
+    },
+    async remove(owner, id) {
+      bucket(owner).delete(id);
+    },
+  };
+}