cursedbelt-server 1.0.0

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

@@ -0,0 +1,265 @@
+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 { Hono } from 'hono';
+import { isFfmpegAvailable } from '../media-bun';
+import { createDiskStore } from '../storage/diskStore';
+import { generateUserSalt, sealMeta } from './crypto';
+import { createMemoryPrivateIndex, type PrivateItem } from './index-store';
+import { mountPrivateRoutes } from './mountPrivateRoutes';
+import { processPrivateVideo } from './pipeline';
+import { createUnlockService } from './unlock';
+
+const unlock = createUnlockService({ serverSecret: 'srv', unlockSecret: 'unlock' });
+
+describe('unlock service', () => {
+  test('round-trips a deniable set key through a token', async () => {
+    const { token, mode } = await unlock.unlock({ userId: 'u1', userSalt: 's', password: 'pw' });
+    expect(mode).toBe('deniable');
+    const grant = await unlock.verify(token);
+    expect(grant?.userId).toBe('u1');
+    expect(grant?.mode).toBe('deniable');
+    // The recovered key matches a fresh derivation from the same password.
+    expect(
+      grant?.setKey.equals(unlock.deriveSetKey({ userId: 'u1', userSalt: 's', password: 'pw' })),
+    ).toBe(true);
+  });
+  test('no password ⇒ standard (recoverable) mode', async () => {
+    const { mode } = await unlock.unlock({ userId: 'u1', userSalt: 's' });
+    expect(mode).toBe('standard');
+  });
+  test('a token from a different secret does not verify', async () => {
+    const other = createUnlockService({ serverSecret: 'srv', unlockSecret: 'DIFFERENT' });
+    const { token } = await other.unlock({ userId: 'u1', userSalt: 's', password: 'pw' });
+    expect(await unlock.verify(token)).toBeNull();
+  });
+});
+
+// Index + reveal need no ffmpeg — sealed metadata under two passwords, then the "try a password"
+// endpoint reveals only the matching set; the index endpoint leaks only size + createdAt.
+describe('index + reveal routes', () => {
+  const index = createMemoryPrivateIndex();
+  const salt = generateUserSalt();
+  const app = new Hono();
+  mountPrivateRoutes(app, {
+    store: createDiskStore('/tmp/unused-pm'),
+    index,
+    unlock,
+    authorize: async () => ({ userId: 'u1', userSalt: salt }),
+  });
+
+  beforeAll(async () => {
+    const keyA = unlock.deriveSetKey({ userId: 'u1', userSalt: salt, password: 'alpha' });
+    const keyB = unlock.deriveSetKey({ userId: 'u1', userSalt: salt, password: 'bravo' });
+    const mk = (id: string, key: Buffer, title: string): PrivateItem => ({
+      id,
+      owner: 'u1',
+      sizeBytes: 1234,
+      createdAt: Date.now(),
+      status: 'ready',
+      keyMode: 'deniable',
+      wrappedContentKey: 'x',
+      sealedMeta: sealMeta(key, { title, notes: 'secret' }),
+    });
+    await index.add(mk('a1', keyA, 'Alpha One'));
+    await index.add(mk('a2', keyA, 'Alpha Two'));
+    await index.add(mk('b1', keyB, 'Bravo One'));
+  });
+
+  test('index exposes only size/createdAt/status — no title/notes/mode', async () => {
+    const res = await app.request('/_private/index');
+    const body = (await res.json()) as { items: Array<Record<string, unknown>> };
+    expect(body.items.length).toBe(3);
+    for (const row of body.items) {
+      expect(row.sizeBytes).toBe(1234);
+      expect(row).not.toHaveProperty('title');
+      expect(row).not.toHaveProperty('sealedMeta');
+      expect(row).not.toHaveProperty('keyMode');
+      expect(row).not.toHaveProperty('wrappedContentKey');
+    }
+  });
+
+  test('reveal unlocks only the matching password set', async () => {
+    const res = await app.request('/_private/reveal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ password: 'alpha' }),
+    });
+    const body = (await res.json()) as { items: Array<{ id: string; meta: { title: string } }> };
+    expect(body.items.map((i) => i.id).sort()).toEqual(['a1', 'a2']);
+    expect(body.items.find((i) => i.id === 'a1')?.meta.title).toBe('Alpha One');
+  });
+
+  test('a wrong password reveals nothing (no info leak)', async () => {
+    const res = await app.request('/_private/reveal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ password: 'zzz' }),
+    });
+    expect(((await res.json()) as { items: unknown[] }).items).toEqual([]);
+  });
+
+  test('reveal-unlocked: an unlock token reveals the same set as its password', async () => {
+    const { token } = await unlock.unlock({ userId: 'u1', userSalt: salt, password: 'alpha' });
+    const res = await app.request('/_private/reveal-unlocked', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { items: Array<{ id: string; meta: { title: string } }> };
+    expect(body.items.map((i) => i.id).sort()).toEqual(['a1', 'a2']);
+    expect(body.items.find((i) => i.id === 'a1')?.meta.title).toBe('Alpha One');
+  });
+
+  test('reveal-unlocked: a token for a DIFFERENT set reveals only that set', async () => {
+    const { token } = await unlock.unlock({ userId: 'u1', userSalt: salt, password: 'bravo' });
+    const res = await app.request('/_private/reveal-unlocked', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token }),
+    });
+    const body = (await res.json()) as { items: Array<{ id: string }> };
+    expect(body.items.map((i) => i.id)).toEqual(['b1']);
+  });
+
+  test('reveal-unlocked: missing / invalid / other-user tokens are rejected', async () => {
+    const missing = await app.request('/_private/reveal-unlocked', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(missing.status).toBe(400);
+
+    const bogus = await app.request('/_private/reveal-unlocked', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: 'not-a-token' }),
+    });
+    expect(bogus.status).toBe(401);
+
+    // A valid token minted for ANOTHER user must not open this session's items.
+    const { token: foreign } = await unlock.unlock({
+      userId: 'u2',
+      userSalt: salt,
+      password: 'alpha',
+    });
+    const cross = await app.request('/_private/reveal-unlocked', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: foreign }),
+    });
+    expect(cross.status).toBe(401);
+  });
+});
+
+// Full encrypted playback path — needs ffmpeg (no-ops without it).
+describe('encrypted playback routes', () => {
+  let root: string;
+  let work: string;
+  let hasFfmpeg = false;
+
+  beforeAll(async () => {
+    hasFfmpeg = await isFfmpegAvailable();
+    root = await mkdtemp(path.join(tmpdir(), 'pm-r-store-'));
+    work = await mkdtemp(path.join(tmpdir(), 'pm-r-work-'));
+  });
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+    await rm(work, { recursive: true, force: true });
+  });
+
+  test('unlock → content key (gated) decrypts a served encrypted segment', async () => {
+    if (!hasFfmpeg) {
+      console.warn('[routes.spec] ffmpeg absent — skipping encrypted playback route test');
+      return;
+    }
+    const store = createDiskStore(root);
+    const index = createMemoryPrivateIndex();
+    const salt = generateUserSalt();
+    const setKey = unlock.deriveSetKey({ userId: 'u1', userSalt: salt, password: 'pw' });
+
+    // Produce an encrypted item + register it in the index.
+    const clip = path.join(work, 'src.mp4');
+    const gen = 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 gen.exited;
+    const res = await processPrivateVideo({
+      store,
+      workDir: work,
+      owner: 'u1',
+      id: 'v1',
+      sourcePath: clip,
+      setKey,
+    });
+    expect(res.status).toBe('ready');
+    await index.add({
+      id: 'v1',
+      owner: 'u1',
+      sizeBytes: 1000,
+      createdAt: Date.now(),
+      status: 'ready',
+      keyMode: 'deniable',
+      wrappedContentKey: res.wrappedContentKey as string,
+      sealedMeta: sealMeta(setKey, { title: 'Private Clip' }),
+    });
+
+    const app = new Hono();
+    mountPrivateRoutes(app, {
+      store,
+      index,
+      unlock,
+      authorize: async () => ({ userId: 'u1', userSalt: salt }),
+    });
+
+    // Unlock with the password → token.
+    const unlockRes = await app.request('/_private/unlock', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ password: 'pw' }),
+    });
+    const token = ((await unlockRes.json()) as { token: string }).token;
+
+    // The gated key route returns the 16-byte content key.
+    const keyRes = await app.request(`/_private/u/${token}/hls/gallery/v1/480/enc.key`);
+    expect(keyRes.status).toBe(200);
+    expect(keyRes.headers.get('cache-control')).toBe('no-store');
+    const contentKey = new Uint8Array(await keyRes.arrayBuffer());
+    expect(contentKey.length).toBe(16);
+
+    // The segment route serves the ENCRYPTED bytes; decrypting with the key → valid MPEG-TS.
+    const segRes = await app.request(`/_private/u/${token}/hls/gallery/v1/480/seg_00000.ts`);
+    expect([200, 206]).toContain(segRes.status);
+    const segBytes = new Uint8Array(await segRes.arrayBuffer());
+    // Recover the IV from the variant playlist (#EXT-X-KEY … IV=0x…).
+    const plRes = await app.request(`/_private/u/${token}/hls/gallery/v1/480/playlist.m3u8`);
+    const playlist = await plRes.text();
+    const iv = Buffer.from(/IV=0x([0-9a-fA-F]+)/.exec(playlist)?.[1] ?? '', 'hex');
+    const d = createDecipheriv('aes-128-cbc', Buffer.from(contentKey), iv);
+    const plain = Buffer.concat([d.update(Buffer.from(segBytes)), d.final()]);
+    expect(plain[0]).toBe(0x47);
+
+    // A bogus token is rejected.
+    expect((await app.request('/_private/u/bogus/hls/gallery/v1/480/enc.key')).status).toBe(401);
+  }, 30_000);
+});

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

@@ -0,0 +1,112 @@
+import { decryptSecret, deriveKey, encryptSecret } from 'cwip/node';
+// 🔴 `../auth/jwt`, NOT `../auth` — same reason as `storage/streamToken.ts`, and this is the
+// SECOND edge of the pair: `cursedbelt-server/storage` reaches private-media, so the barrel
+// import here put `otplib` (via `auth/index` → `totp.ts`) back into the storage graph after
+// streamToken.ts had been fixed. Found by bundling the graph and reading the externals, not by
+// grep — a two-hop edge is invisible to the obvious search.
+import { signToken, verifyPurposeToken } from '../auth/jwt';
+import { derivePasswordSetKey, deriveServerSetKey, type KeyMode } from './crypto';
+
+// ── Unlock service ──────────────────────────────────────────────────────────────
+// Turns a private-mode unlock into a short-lived token that CARRIES the set key so later
+// requests (the HLS content-key route, reveal) can unwrap without re-deriving. Two modes:
+//   • deniable  — password given → setKey = scrypt(password, userSalt); the server holds no
+//     copy, so the token is the ONLY way back to that set key until it expires.
+//   • standard  — no password → setKey = scrypt(serverSecret, userId); recoverable, session-gated.
+// The set key is SEALED inside the token (AES-GCM under a server seal key), so the client can't
+// read it out; only this server can. The JWT is signed via cursedbelt's one jose integration
+// under the existing 'pm-unlock' purpose, so it can't be replayed as an access token.
+
+const PURPOSE = 'pm-unlock';
+
+export type UnlockGrant = { userId: string; setKey: Buffer; mode: KeyMode };
+
+/**
+ * What a supplied password MEANS at the unlock/reveal/private-upload surfaces:
+ *   • derive (default) — the password derives the set key (deniable sets; the
+ *     historical behavior).
+ *   • gate — the password is an ACCESS CHECK against the app's own accounts
+ *     (verifyPassword, e.g. the login store's argon2id verify) and the set key
+ *     stays the recoverable server-derived one. Password changes never orphan
+ *     content, and a password is REQUIRED to unlock (no silent session unlock).
+ */
+export type UnlockPasswordPolicy =
+  | { mode: 'derive' }
+  | {
+      mode: 'gate';
+      verifyPassword: (
+        who: { userId: string; userSalt: string },
+        password: string,
+      ) => Promise<boolean>;
+    };
+
+export interface UnlockService {
+  /** Mint an unlock token. Pass `password` for a deniable set; omit for the standard server-key
+   * set (the caller must already have authenticated the user). */
+  unlock(args: { userId: string; userSalt: string; password?: string }): Promise<{
+    token: string;
+    mode: KeyMode;
+  }>;
+  /** Verify a token and recover the sealed set key, or null if invalid/expired/tampered. */
+  verify(token: string): Promise<UnlockGrant | null>;
+  /** Derive a set key without minting a token (for the reveal endpoint's per-item trials). */
+  deriveSetKey(args: { userId: string; userSalt: string; password?: string }): Buffer;
+}
+
+export function createUnlockService(opts: {
+  /** Derives the recoverable (standard) set key. */
+  serverSecret: string;
+  /** Signs the unlock JWT AND (domain-separated) seals the set key inside it. */
+  unlockSecret: string;
+  /** Token lifetime — long enough to survive a paused-and-resumed private video. Default 6h. */
+  ttlSeconds?: number;
+}): UnlockService {
+  const ttl = opts.ttlSeconds ?? 6 * 60 * 60;
+  const sealKey = deriveKey(opts.unlockSecret, 'pm-unlock-seal');
+
+  const deriveSetKey = ({
+    userId,
+    userSalt,
+    password,
+  }: {
+    userId: string;
+    userSalt: string;
+    password?: string;
+  }): Buffer =>
+    password
+      ? derivePasswordSetKey(password, userSalt)
+      : deriveServerSetKey(opts.serverSecret, userId);
+
+  return {
+    deriveSetKey,
+    async unlock(args) {
+      const mode: KeyMode = args.password ? 'deniable' : 'standard';
+      const setKey = deriveSetKey(args);
+      const token = await signToken(
+        {
+          userId: args.userId,
+          sessionId: 'pm',
+          roles: [],
+          purpose: PURPOSE,
+          sk: encryptSecret(setKey.toString('base64'), sealKey),
+          m: mode,
+        },
+        opts.unlockSecret,
+        ttl,
+      );
+      return { token, mode };
+    },
+    async verify(token) {
+      try {
+        const p = await verifyPurposeToken(token, opts.unlockSecret, PURPOSE);
+        const sealed = (p as { sk?: unknown }).sk;
+        const mode = (p as { m?: unknown }).m;
+        if (typeof sealed !== 'string' || (mode !== 'standard' && mode !== 'deniable')) return null;
+        const setKey = Buffer.from(decryptSecret(sealed, sealKey), 'base64');
+        return { userId: p.userId, setKey, mode };
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/server/resume/index.ts

@@ -0,0 +1,8 @@
+export {
+  createSqliteResumeStore,
+  MAX_LOCATION_LENGTH,
+  type ResumeRecord,
+  type ResumeStore,
+  type ResumeStoreOptions,
+} from './store';
+export { mountResumeRoutes, type ResumeRoutesOptions } from './routes';

package/src/server/resume/resume.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from 'bun:test';
+import { Database } from 'bun:sqlite';
+import { Hono } from 'hono';
+import { mountResumeRoutes } from './routes';
+import { createSqliteResumeStore, MAX_LOCATION_LENGTH } from './store';
+
+const storeOf = () => createSqliteResumeStore(new Database(':memory:'));
+
+describe('the store', () => {
+  test('remembers one place per user per key, and the last write wins', () => {
+    const store = storeOf();
+    expect(store.read('u1')).toBe(null);
+    store.write('u1', '#/?folder=Main%201&track=75');
+    store.write('u1', '#/queue', 'other');
+    store.write('u2', '#/albums');
+    expect(store.read('u1')?.location).toBe('#/?folder=Main%201&track=75');
+    expect(store.read('u1', 'other')?.location).toBe('#/queue');
+    expect(store.read('u2')?.location).toBe('#/albums');
+    store.write('u1', '#/albums/7');
+    expect(store.read('u1')?.location).toBe('#/albums/7');
+  });
+
+  test('clear drops one place, or every place for that user', () => {
+    const store = storeOf();
+    store.write('u1', '#/a');
+    store.write('u1', '#/b', 'other');
+    store.clear('u1', 'other');
+    expect(store.read('u1')?.location).toBe('#/a');
+    store.clear('u1');
+    expect(store.read('u1')).toBe(null);
+  });
+
+  test('an absurd location is truncated rather than stored whole', () => {
+    const store = storeOf();
+    store.write('u1', `#/${'x'.repeat(MAX_LOCATION_LENGTH * 2)}`);
+    expect(store.read('u1')!.location.length).toBe(MAX_LOCATION_LENGTH);
+  });
+
+  test('a table name that is not an identifier is refused', () => {
+    expect(() => createSqliteResumeStore(new Database(':memory:'), { table: 'a; drop table b' })).toThrow();
+  });
+});
+
+describe('the routes', () => {
+  const appWith = (user: string | null) => {
+    const store = storeOf();
+    const app = new Hono();
+    mountResumeRoutes(app, { store, authorize: () => user });
+    return { app, store };
+  };
+
+  test('round-trips a place and never lets a cache hold it', async () => {
+    const { app } = appWith('u1');
+    const put = await app.request('/api/resume?key=library', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ location: '#/?folder=Main+1&track=75' }),
+    });
+    expect(put.status).toBe(200);
+    const get = await app.request('/api/resume?key=library');
+    expect(get.headers.get('cache-control')).toBe('no-store, private');
+    expect((await get.json()).location).toBe('#/?folder=Main+1&track=75');
+
+    const cleared = await app.request('/api/resume?key=library', { method: 'DELETE' });
+    expect(cleared.status).toBe(200);
+    expect((await (await app.request('/api/resume?key=library')).json()).location).toBe(null);
+  });
+
+  test('nothing stored is a 200 with a null location, not a 404', async () => {
+    const { app } = appWith('u1');
+    const response = await app.request('/api/resume');
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ location: null, updatedAt: null });
+  });
+
+  test('a signed-out caller gets 401 and writes nothing', async () => {
+    const { app, store } = appWith(null);
+    expect((await app.request('/api/resume')).status).toBe(401);
+    const put = await app.request('/api/resume', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ location: '#/x' }),
+    });
+    expect(put.status).toBe(401);
+    expect(store.read('u1')).toBe(null);
+  });
+
+  test('a junk key or a junk body is refused', async () => {
+    const { app } = appWith('u1');
+    expect((await app.request('/api/resume?key=../etc')).status).toBe(400);
+    const empty = await app.request('/api/resume', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(empty.status).toBe(400);
+    const huge = await app.request('/api/resume', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ location: `#/${'x'.repeat(MAX_LOCATION_LENGTH + 1)}` }),
+    });
+    expect(huge.status).toBe(413);
+  });
+
+  test('one user cannot read another user’s place', async () => {
+    const store = storeOf();
+    const app = new Hono();
+    let who = 'u1';
+    mountResumeRoutes(app, { store, authorize: () => who });
+    await app.request('/api/resume', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ location: '#/private' }),
+    });
+    who = 'u2';
+    expect((await (await app.request('/api/resume')).json()).location).toBe(null);
+  });
+});

package/src/server/resume/routes.ts

@@ -0,0 +1,92 @@
+/**
+ * The three routes behind `useResume`:
+ *
+ *   GET    {base}?key=default  → { location, updatedAt } | { location: null }
+ *   PUT    {base}?key=default  → { ok: true }             body { location }
+ *   DELETE {base}?key=default  → { ok: true }
+ *
+ * ── Caching, decided here rather than left to a proxy ───────────────────────
+ * Every response is `no-store, private`. The body is one person's last screen —
+ * it is per-user, it changes on every navigation, and a shared cache holding it
+ * would hand one reader another reader's place. This is the ONE endpoint the
+ * deep-link work adds; the deep links themselves are same-document hash URLs and
+ * change nothing about how the app shell is cached.
+ *
+ * Authorization is the app's, passed in: every satellite already knows how to
+ * turn a cookie into a user id, and a resume row is exactly as sensitive as the
+ * screen it names.
+ */
+import type { Context, Hono } from 'hono';
+import { MAX_LOCATION_LENGTH, type ResumeStore } from './store';
+
+export interface ResumeRoutesOptions {
+  store: ResumeStore;
+  /** Resolve the caller to a user id, or null to refuse. */
+  authorize(c: Context): string | null | Promise<string | null>;
+  /** Default `/api/resume`. */
+  basePath?: string;
+}
+
+const NO_STORE = { 'cache-control': 'no-store, private' } as const;
+
+/**
+ * What a `?key=` may look like. 🔴 EXPORTED because a client that builds a key
+ * out of app data (`useTableViewMode`'s `table-view.<id>`) has no other way to
+ * know what this route will accept — and the failure is SILENT: the client
+ * swallows every error into "nothing stored", so a rejected key looks exactly
+ * like a preference that was never saved. `useTableViewMode.spec.tsx` asserts
+ * the keys that hook produces against this regex, so changing either end turns
+ * a test red instead of quietly un-remembering everybody's view.
+ *
+ * Note there is no `:` in the class, which is the separator a key builder
+ * reaches for first.
+ */
+export const RESUME_KEY_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+const keyOf = (c: Context): string | null => {
+  const raw = c.req.query('key') ?? 'default';
+  return RESUME_KEY_PATTERN.test(raw) ? raw : null;
+};
+
+export function mountResumeRoutes(app: Hono, options: ResumeRoutesOptions): void {
+  const { store, authorize } = options;
+  const base = options.basePath ?? '/api/resume';
+
+  const withUser = (handler: (c: Context, userId: string, key: string) => Response | Promise<Response>) =>
+    async (c: Context): Promise<Response> => {
+      const userId = await authorize(c);
+      if (!userId) return c.json({ error: 'unauthorized' }, 401, NO_STORE);
+      const key = keyOf(c);
+      if (!key) return c.json({ error: 'invalid key' }, 400, NO_STORE);
+      return handler(c, userId, key);
+    };
+
+  app.get(
+    base,
+    withUser((c, userId, key) => {
+      const record = store.read(userId, key);
+      return c.json(record ?? { location: null, updatedAt: null }, 200, NO_STORE);
+    }),
+  );
+
+  app.put(
+    base,
+    withUser(async (c, userId, key) => {
+      const body = (await c.req.json().catch(() => null)) as { location?: unknown } | null;
+      const location = typeof body?.location === 'string' ? body.location.trim() : '';
+      if (!location) return c.json({ error: 'location required' }, 400, NO_STORE);
+      if (location.length > MAX_LOCATION_LENGTH)
+        return c.json({ error: 'location too long' }, 413, NO_STORE);
+      store.write(userId, location, key);
+      return c.json({ ok: true }, 200, NO_STORE);
+    }),
+  );
+
+  app.delete(
+    base,
+    withUser((c, userId, key) => {
+      store.clear(userId, key);
+      return c.json({ ok: true }, 200, NO_STORE);
+    }),
+  );
+}

package/src/server/resume/store.ts

@@ -0,0 +1,82 @@
+/**
+ * Where "the last place you were" is kept — one small table, in the app's own
+ * database, keyed by the app's own user id.
+ *
+ * ── Why server-side at all ──────────────────────────────────────────────────
+ * `localStorage` would be one line and would answer the wrong question. The
+ * owner's report is about coming BACK to an app, and he does that from another
+ * device — the 2026-08-13 music sign-in from a second laptop is the same shape.
+ * A place remembered only in the browser that saw it is not remembered.
+ *
+ * ── Why the app's database and not a fleet service ──────────────────────────
+ * Same reasoning as `../notifications/migrations.ts`: the SCHEMA is shared, the
+ * DATA is local. A resume row is one string per user per app; a central service
+ * would put a network hop in front of the first paint of every app in the fleet,
+ * and the first thing each would do is cache it.
+ *
+ * The DDL is idempotent, so calling this twice — or beside a migration runner —
+ * converges on one table.
+ */
+import type { Database } from 'bun:sqlite';
+
+/** Longer than any real place, short enough that nobody can park a payload here. */
+export const MAX_LOCATION_LENGTH = 2048;
+
+export interface ResumeRecord {
+  location: string;
+  updatedAt: number;
+}
+
+export interface ResumeStore {
+  read(userId: string, key?: string): ResumeRecord | null;
+  write(userId: string, location: string, key?: string): void;
+  /** No key clears every remembered place for that user. */
+  clear(userId: string, key?: string): void;
+}
+
+export interface ResumeStoreOptions {
+  table?: string;
+  now?: () => number;
+}
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_KEY = 'default';
+
+export function createSqliteResumeStore(db: Database, options: ResumeStoreOptions = {}): ResumeStore {
+  const table = options.table ?? 'cb_resume';
+  if (!IDENTIFIER.test(table)) throw new Error(`invalid resume table name: ${table}`);
+  const now = options.now ?? Date.now;
+
+  db.run(`CREATE TABLE IF NOT EXISTS ${table} (
+    user_id TEXT NOT NULL,
+    place_key TEXT NOT NULL,
+    location TEXT NOT NULL,
+    updated_at INTEGER NOT NULL,
+    PRIMARY KEY (user_id, place_key)
+  )`);
+
+  return {
+    read(userId, key = DEFAULT_KEY) {
+      const row = db
+        .query<{ location: string; updated_at: number }, [string, string]>(
+          `SELECT location, updated_at FROM ${table} WHERE user_id = ? AND place_key = ?`,
+        )
+        .get(userId, key);
+      return row ? { location: row.location, updatedAt: row.updated_at } : null;
+    },
+    write(userId, location, key = DEFAULT_KEY) {
+      // Truncated rather than refused: a place that is somehow too long should
+      // cost the reader nothing, and the next navigation overwrites it anyway.
+      const value = location.slice(0, MAX_LOCATION_LENGTH);
+      db.run(
+        `INSERT INTO ${table} (user_id, place_key, location, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(user_id, place_key) DO UPDATE SET location = excluded.location, updated_at = excluded.updated_at`,
+        [userId, key, value, now()],
+      );
+    },
+    clear(userId, key) {
+      if (key === undefined) db.run(`DELETE FROM ${table} WHERE user_id = ?`, [userId]);
+      else db.run(`DELETE FROM ${table} WHERE user_id = ? AND place_key = ?`, [userId, key]);
+    },
+  };
+}