cursedbelt-server 1.0.0

package/dist/server/private-media/index-store.d.ts

@@ -0,0 +1,31 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import type { KeyMode } from './crypto';
+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 declare const toPublic: (item: PrivateItem) => PrivateIndexRow;
+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 declare function createMemoryPrivateIndex(): PrivateIndex;

package/dist/server/private-media/index-store.js

@@ -0,0 +1,36 @@
+export const toPublic = (item) => ({
+    id: item.id,
+    sizeBytes: item.sizeBytes,
+    createdAt: item.createdAt,
+    status: item.status,
+});
+export function createMemoryPrivateIndex() {
+    const byOwner = new Map();
+    const bucket = (owner) => {
+        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);
+        },
+    };
+}

package/dist/server/private-media/mountPrivateRoutes.d.ts

@@ -0,0 +1,26 @@
+import type { Context, Hono } from 'hono';
+import { type MediaStore } from '../storage/types';
+import type { PrivateIndex } from './index-store';
+import type { UnlockPasswordPolicy, UnlockService } from './unlock';
+/** 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);
+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 declare function mountPrivateRoutes(app: Hono, opts: MountPrivateOptions): void;

package/dist/server/private-media/mountPrivateRoutes.js

@@ -0,0 +1,219 @@
+import { decodeRange, serveRange } from '../storage/streamRange';
+import { privateHlsFileKey, privateSourceKey } from '../storage/types';
+import { cryptBlobRangeStream, cryptBlobStream, openMeta, unwrapContentKey } from './crypto';
+import { toPublic } from './index-store';
+function resolveAcao(cors, reqOrigin) {
+    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 function mountPrivateRoutes(app, opts) {
+    const base = opts.basePath ?? '/_private';
+    const { store, index, unlock } = opts;
+    const cors = (c, res) => {
+        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' };
+    /** 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, who, password) => {
+        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(() => ({})));
+        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, setKey) => {
+        const revealed = [];
+        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(() => ({})));
+        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(() => ({})));
+        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(grant.setKey, item.sealedMeta);
+        const baseHeaders = {
+            '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' };
+        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 = {
+                '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/dist/server/private-media/pipeline.d.ts

@@ -0,0 +1,37 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import { type MediaStore } from '../storage/types';
+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;
+};
+export declare function processPrivateVideo(opts: PrivateProcessOptions): Promise<PrivateProcessResult>;
+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 declare 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>;

package/dist/server/private-media/pipeline.js

@@ -0,0 +1,97 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { hlsLadderArgs, isFfmpegAvailable, LIBRARY_CRF, probeVideoStream, resolveLadder, runFfmpegProgress, } from '../media-bun';
+import { 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
+async function uploadTree(store, dir, owner, id) {
+    const walk = async (rel) => {
+        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) {
+    const { store, workDir, owner, id, sourcePath, setKey, onProgress } = opts;
+    const report = (s, p) => onProgress?.(s, p);
+    const failed = {
+        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(() => { });
+    }
+}
+export async function processPrivateBlob(opts) {
+    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 };
+    }
+}

package/dist/server/private-media/unlock.d.ts

@@ -0,0 +1,52 @@
+import { type KeyMode } from './crypto';
+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 declare 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;

package/dist/server/private-media/unlock.js

@@ -0,0 +1,55 @@
+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 } 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 function createUnlockService(opts) {
+    const ttl = opts.ttlSeconds ?? 6 * 60 * 60;
+    const sealKey = deriveKey(opts.unlockSecret, 'pm-unlock-seal');
+    const deriveSetKey = ({ userId, userSalt, password, }) => password
+        ? derivePasswordSetKey(password, userSalt)
+        : deriveServerSetKey(opts.serverSecret, userId);
+    return {
+        deriveSetKey,
+        async unlock(args) {
+            const mode = 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.sk;
+                const mode = p.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/dist/server/resume/index.d.ts

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

package/dist/server/resume/index.js

@@ -0,0 +1,2 @@
+export { createSqliteResumeStore, MAX_LOCATION_LENGTH, } from './store';
+export { mountResumeRoutes } from './routes';

package/dist/server/resume/routes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { 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;
+}
+/**
+ * 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 declare const RESUME_KEY_PATTERN: RegExp;
+export declare function mountResumeRoutes(app: Hono, options: ResumeRoutesOptions): void;

package/dist/server/resume/routes.js

@@ -0,0 +1,50 @@
+import { MAX_LOCATION_LENGTH } from './store';
+const NO_STORE = { 'cache-control': 'no-store, private' };
+/**
+ * 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) => {
+    const raw = c.req.query('key') ?? 'default';
+    return RESUME_KEY_PATTERN.test(raw) ? raw : null;
+};
+export function mountResumeRoutes(app, options) {
+    const { store, authorize } = options;
+    const base = options.basePath ?? '/api/resume';
+    const withUser = (handler) => async (c) => {
+        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));
+        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);
+    }));
+}