cursedbelt-server 1.0.0

package/dist/server/storage/files/chunkedUpload.d.ts

@@ -0,0 +1,56 @@
+import type { MediaCtx } from '../types';
+import type { StorageOpsLedger } from './storageOps';
+import type { FileCatalogue, FileRecord } from './types';
+export type ChunkedInit = {
+    fileId: string;
+    /** Chunk session id — also the ledger op id; echoed to the backend as sid so its assemble event
+     * matches our storage_operations row. */
+    sid: string;
+    /** The storage key the assembled bytes land at (fsSourceKey for video, else fileBinaryKey). */
+    key: string;
+    chunkSize: number;
+    chunkCount: number;
+    /** One direct-to-backend PUT URL per chunk, in index order. */
+    chunkUploadUrls: string[];
+};
+export interface ChunkedUploadService {
+    /** Begin a chunked upload: reserve an id, record a pending `upload` op, and mint the per-chunk
+     * direct-to-backend PUT URLs. */
+    init(ctx: MediaCtx, req: {
+        name: string;
+        mime: string;
+        size: number;
+        tags?: string[];
+    }): Promise<ChunkedInit>;
+    /** Finish it: mark the op done and register the catalogue row over the assembled bytes. Returns
+     * the new record, or null if the session is unknown (already completed / server restarted). */
+    complete(sid: string, confirmed?: {
+        size?: number;
+    }): Promise<FileRecord | null>;
+    /** Give up on a session (client cancelled / a chunk failed) — mark the ledger op failed. */
+    abort(sid: string): void;
+    /** Open session count (observability / tests). */
+    pending(): number;
+}
+/**
+ * Mint the direct-to-backend PUT URL for one chunk. The app supplies this so the module stays
+ * backend-agnostic. For binary-server: `${base}/upload-chunk/${app}/${key}?token=` with a token
+ * carrying { k, uid, sid, ci, tc }.
+ */
+export type MintChunkUpload = (args: {
+    key: string;
+    sid: string;
+    ci: number;
+    tc: number;
+    owner: string;
+}) => Promise<string>;
+export declare function createChunkedUploadService(cfg: {
+    catalogue: FileCatalogue;
+    ledger: StorageOpsLedger;
+    /** Byte backend label recorded on the ledger op (e.g. 'binary'). */
+    backend: string;
+    mintChunkUpload: MintChunkUpload;
+    chunkSize?: number;
+    owner?: (ctx: MediaCtx) => string;
+    now?: () => number;
+}): ChunkedUploadService;

package/dist/server/storage/files/chunkedUpload.js

@@ -0,0 +1,70 @@
+import { DEFAULT_UPLOAD_CHUNK_SIZE } from 'cursedbelt-core/media/upload-limits';
+import { catalogueUploadKey } from './catalogue';
+// ── Chunked upload (large files, direct-to-backend) ──────────────────────────────
+// For multi-GB uploads we don't proxy bytes through the app origin. Instead: the client asks the
+// app to START an upload (init) → the app mints per-chunk PUT URLs that go DIRECT to the byte
+// backend (binary-server), records a durable `upload` ledger op, and hands the URLs back. The
+// client PUTs each chunk to the backend, which assembles them at the target key once the last
+// arrives. Then the client (or a backend webhook) calls COMPLETE, and the app registers the
+// catalogue row over the already-stored bytes (no re-upload) + kicks processing.
+//
+// This module is backend-AGNOSTIC: the app injects `mintChunkUpload` (the binary-server chunk URL
+// + signed sid/ci/tc token). On disk-only deploys, an app simply doesn't wire chunked uploads and
+// keeps the streamed `PUT /upload`. Sessions are in-memory (the transient name/mime/size); the
+// ledger row is the DURABLE record of intent, so an abandoned upload is observable/reconcilable.
+const DEFAULT_CHUNK_SIZE = DEFAULT_UPLOAD_CHUNK_SIZE;
+export function createChunkedUploadService(cfg) {
+    const ownerOf = cfg.owner ?? ((c) => c.tenantId);
+    const now = cfg.now ?? (() => Date.now());
+    const chunkSize = cfg.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const sessions = new Map();
+    return {
+        async init(ctx, req) {
+            const owner = ownerOf(ctx);
+            const fileId = crypto.randomUUID();
+            const sid = crypto.randomUUID();
+            const key = catalogueUploadKey(owner, fileId, req.mime);
+            const chunkCount = Math.max(1, Math.ceil((req.size || 1) / chunkSize));
+            // Durable record of intent — its op_id (sid) is what the backend echoes on assemble.
+            cfg.ledger.record({ owner, fileId, action: 'upload', key, backend: cfg.backend, opId: sid });
+            sessions.set(sid, {
+                fileId,
+                owner,
+                ctx,
+                name: req.name,
+                mime: req.mime,
+                size: req.size,
+                key,
+                chunkCount,
+                tags: req.tags,
+                createdAt: now(),
+            });
+            const chunkUploadUrls = await Promise.all(Array.from({ length: chunkCount }, (_, ci) => cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner })));
+            return { fileId, sid, key, chunkSize, chunkCount, chunkUploadUrls };
+        },
+        async complete(sid, confirmed) {
+            const s = sessions.get(sid);
+            if (!s)
+                return null;
+            cfg.ledger.markDone(sid);
+            const rec = await cfg.catalogue.registerUploaded(s.ctx, {
+                id: s.fileId,
+                name: s.name,
+                mime: s.mime,
+                size: confirmed?.size ?? s.size,
+                tags: s.tags,
+            });
+            sessions.delete(sid);
+            return rec;
+        },
+        abort(sid) {
+            if (!sessions.has(sid))
+                return;
+            cfg.ledger.markFailed(sid, 'aborted');
+            sessions.delete(sid);
+        },
+        pending() {
+            return sessions.size;
+        },
+    };
+}

package/dist/server/storage/files/fileRoutes.d.ts

@@ -0,0 +1,51 @@
+import type { Context, Hono } from 'hono';
+import type { UnlockPasswordPolicy, UnlockService } from '../../private-media/unlock';
+import type { StreamTokenService } from '../streamToken';
+import type { MediaCtx, MediaStore } from '../types';
+import type { ChunkedUploadService } from './chunkedUpload';
+import { type FileCatalogue, type PrivateFileCatalogue } from './types';
+/** The 413 message a single-PUT over the cap returns — the client treats it as a hard error. */
+export declare const SINGLE_UPLOAD_TOO_LARGE = "file too large for a single request \u2014 use chunked upload";
+export interface FileUrls {
+    /** A GET URL for a file's primary binary, carrying its mime as `?ct=`. */
+    build(ctx: MediaCtx, fileId: string, mime: string): Promise<{
+        url: string;
+    }>;
+}
+export declare function createFileUrls(opts: {
+    /** Path-only ('/_files') same-origin, or an absolute origin+path for split-origin. */
+    baseUrl: string;
+    token: StreamTokenService;
+    owner?: (ctx: MediaCtx) => string;
+}): FileUrls;
+export type MountFileRoutesOptions = {
+    store: MediaStore;
+    token: StreamTokenService;
+    /** Path mount (default '/_files'). */
+    basePath?: string;
+    /** Session auth for the upload PUTs (a fetch CAN send the Bearer). Return a ctx or null. */
+    authorizeUpload?: (c: Context) => Promise<MediaCtx | null> | MediaCtx | null;
+    /** The catalogue uploads land in. Required for the upload routes to be mounted. */
+    catalogue?: FileCatalogue & PrivateFileCatalogue;
+    /** Wire private uploads: derive a per-user set key from the request (password header ⇒ deniable,
+     * absent ⇒ standard server key). Omit ⇒ the private-upload route is disabled. */
+    privateUpload?: {
+        unlock: UnlockService;
+        authorize: (c: Context) => Promise<{
+            userId: string;
+            userSalt: string;
+        } | null>;
+        /** Header carrying the plaintext password for a deniable set (default 'x-private-password'). */
+        passwordHeader?: string;
+        /** Header carrying an UNLOCK TOKEN (an already-unlocked session) — takes precedence over the
+         * password header; setKey + keyMode come from the verified grant (default 'x-unlock-token'). */
+        tokenHeader?: string;
+        /** What a supplied password means (default derive — deniable set). `gate` verifies it
+         * against the app's accounts and wraps under the recoverable server key instead. */
+        passwordPolicy?: UnlockPasswordPolicy;
+    };
+    /** Wire large-file chunked uploads (direct-to-backend). Omit ⇒ init/complete routes are absent
+     * and clients use the streamed `PUT /upload`. Uses the same `authorizeUpload` guard. */
+    chunked?: ChunkedUploadService;
+};
+export declare function mountFileRoutes(app: Hono, opts: MountFileRoutesOptions): void;

package/dist/server/storage/files/fileRoutes.js

@@ -0,0 +1,405 @@
+import { MAX_SINGLE_UPLOAD_BYTES } from 'cursedbelt-core/media/upload-limits';
+import { serveRange } from '../streamRange';
+import { fileBinaryKey } from './catalogue';
+import { FILE_SORTS, } from './types';
+// ── File binary + upload routes ─────────────────────────────────────────────────
+// The FileCatalogue's byte edge for GENERAL files (images/docs/audio/any) — the piece
+// mountMediaRoutes (video-only: mp4/hls/poster/sprite) doesn't cover. A file's primary binary
+// lives at fs/<owner>/<id> and is served here, token-authorized like the media routes (an <img>
+// can't send a Bearer). Uploads DO carry the app Bearer, so the PUT routes are session-guarded.
+//
+// `sourceId` for a file token is the constant 'files'. The served Content-Type is carried as a
+// signed-URL query (`?ct=`) — the catalogue knows each file's mime when it builds the URL, so the
+// route needn't re-derive it. It only ever serves the token owner's own bytes.
+const FILE_SOURCE_ID = 'files';
+// Guard the echoed Content-Type: a plain type/subtype, no header injection.
+const SAFE_MIME = /^[\w.+-]+\/[\w.+-]+$/;
+/** The 413 message a single-PUT over the cap returns — the client treats it as a hard error. */
+export const SINGLE_UPLOAD_TOO_LARGE = 'file too large for a single request — use chunked upload';
+/** Thrown into the body stream when it exceeds the single-request cap mid-stream (no Content-Length
+ *  to fail fast on). Handlers catch it and turn it into a clean 413 instead of a 500. */
+class UploadTooLargeError extends Error {
+    constructor() {
+        super(SINGLE_UPLOAD_TOO_LARGE);
+        this.name = 'UploadTooLargeError';
+    }
+}
+const isUploadTooLarge = (e) => e instanceof UploadTooLargeError || (e instanceof Error && e.message === SINGLE_UPLOAD_TOO_LARGE);
+/**
+ * Enforce the single-request upload cap (MAX_SINGLE_UPLOAD_BYTES) on a streamed PUT body. The law:
+ * no single HTTP request may carry more than the cap — larger files MUST chunk. Fails FAST on the
+ * Content-Length header (browsers set it for a File/Blob body), and — for length-less chunked
+ * transfer — wraps the stream to abort once the accumulated bytes pass the cap (the wrapping error
+ * surfaces from `catalogue.ingest`, which the handlers turn into a 413). Returns either the body to
+ * hand to the catalogue, or a 413 Response to return immediately.
+ */
+function guardSingleUpload(c, body) {
+    const declared = Number(c.req.header('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_SINGLE_UPLOAD_BYTES) {
+        return c.json({ error: SINGLE_UPLOAD_TOO_LARGE }, 413);
+    }
+    let seen = 0;
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, ctrl) {
+            seen += chunk.byteLength;
+            if (seen > MAX_SINGLE_UPLOAD_BYTES) {
+                ctrl.error(new UploadTooLargeError());
+                return;
+            }
+            ctrl.enqueue(chunk);
+        },
+    }));
+}
+export function createFileUrls(opts) {
+    const ownerOf = opts.owner ?? ((c) => c.tenantId);
+    const base = opts.baseUrl.replace(/\/$/, '');
+    return {
+        async build(ctx, fileId, mime) {
+            const token = await opts.token.sign({
+                owner: ownerOf(ctx),
+                sourceId: FILE_SOURCE_ID,
+                videoId: fileId,
+            });
+            return { url: `${base}/s/${token}/${fileId}?ct=${encodeURIComponent(mime)}` };
+        },
+    };
+}
+export function mountFileRoutes(app, opts) {
+    const base = opts.basePath ?? '/_files';
+    const { store, token, catalogue } = opts;
+    // GET a file's primary binary (Range-capable). Prefers a backend redirect (binary-server edge).
+    app.get(`${base}/s/:token/:id`, async (c) => {
+        const grant = await token.verify(c.req.param('token'));
+        if (!grant || grant.videoId !== c.req.param('id'))
+            return c.body(null, 401);
+        const ct = c.req.query('ct');
+        const mime = ct && SAFE_MIME.test(ct) ? ct : 'application/octet-stream';
+        const key = fileBinaryKey(grant.owner, grant.videoId);
+        if (store.redirectUrl) {
+            const url = await store.redirectUrl(key, { mime });
+            if (url)
+                return c.redirect(url, 303);
+        }
+        return serveRange(store, key, mime, c.req.header('range'), { contentDisposition: 'inline' });
+    });
+    // PUT a regular (public) upload → catalogue.ingest (any file type). Streamed, not buffered.
+    if (opts.authorizeUpload && catalogue) {
+        app.put(`${base}/upload`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const raw = c.req.raw.body;
+            if (!raw)
+                return c.json({ error: 'empty body' }, 400);
+            const body = guardSingleUpload(c, raw);
+            if (body instanceof Response)
+                return body;
+            const tags = c.req.header('x-tags');
+            try {
+                const file = await catalogue.ingest(ctx, {
+                    name: c.req.header('x-filename') ?? 'upload',
+                    mime: c.req.header('content-type') ?? 'application/octet-stream',
+                    body,
+                    tags: tags
+                        ? tags
+                            .split(',')
+                            .map((t) => t.trim())
+                            .filter(Boolean)
+                        : undefined,
+                });
+                return c.json({ file });
+            }
+            catch (e) {
+                if (isUploadTooLarge(e))
+                    return c.json({ error: SINGLE_UPLOAD_TOO_LARGE }, 413);
+                throw e;
+            }
+        });
+        // PUT new bytes OVER an existing file (the editor's "overwrite original"). Same id — tags,
+        // collections, favorites and view history survive; derivatives wipe + re-derive. Streamed.
+        app.put(`${base}/replace/:id`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const raw = c.req.raw.body;
+            if (!raw)
+                return c.json({ error: 'empty body' }, 400);
+            const body = guardSingleUpload(c, raw);
+            if (body instanceof Response)
+                return body;
+            try {
+                const file = await catalogue.replaceContent(ctx, c.req.param('id'), {
+                    name: c.req.header('x-filename') || undefined,
+                    mime: c.req.header('content-type') ?? 'application/octet-stream',
+                    body,
+                });
+                if (!file)
+                    return c.json({ error: 'not found' }, 404);
+                return c.json({ file });
+            }
+            catch (e) {
+                if (isUploadTooLarge(e))
+                    return c.json({ error: SINGLE_UPLOAD_TOO_LARGE }, 413);
+                return c.json({ error: e instanceof Error ? e.message : 'invalid' }, 400);
+            }
+        });
+    }
+    // PUT a PRIVATE upload → catalogue.ingestPrivate under a set key derived from the request:
+    // either an UNLOCK TOKEN (an already-unlocked session — same mechanism the content-key route
+    // uses) or a password header (deniable) / neither (standard server key).
+    const pv = opts.privateUpload;
+    if (pv && catalogue) {
+        const passwordHeader = pv.passwordHeader ?? 'x-private-password';
+        const tokenHeader = pv.tokenHeader ?? 'x-unlock-token';
+        app.put(`${base}/upload-private`, async (c) => {
+            const who = await pv.authorize(c);
+            if (!who)
+                return c.json({ error: 'unauthorized' }, 401);
+            const raw = c.req.raw.body;
+            if (!raw)
+                return c.json({ error: 'empty body' }, 400);
+            const body = guardSingleUpload(c, raw);
+            if (body instanceof Response)
+                return body;
+            let setKey;
+            let keyMode;
+            const unlockToken = c.req.header(tokenHeader) || undefined;
+            if (unlockToken) {
+                // Token path: recover the sealed set key + mode from the grant. The token must belong
+                // to the session caller.
+                const grant = await pv.unlock.verify(unlockToken);
+                if (!grant || grant.userId !== who.userId) {
+                    return c.json({ error: 'invalid unlock token' }, 401);
+                }
+                setKey = grant.setKey;
+                keyMode = grant.mode;
+            }
+            else {
+                // Password path: derive fresh from the header (deniable) or the server key. Under the
+                // gate policy the password is an access check only — verify, then wrap standard.
+                const password = c.req.header(passwordHeader) || undefined;
+                const policy = pv.passwordPolicy ?? { mode: 'derive' };
+                let derivePassword = password;
+                if (policy.mode === 'gate' && password) {
+                    if (!(await policy.verifyPassword(who, password))) {
+                        return c.json({ error: 'invalid password' }, 401);
+                    }
+                    derivePassword = undefined;
+                }
+                setKey = pv.unlock.deriveSetKey({
+                    userId: who.userId,
+                    userSalt: who.userSalt,
+                    password: derivePassword,
+                });
+                keyMode = derivePassword ? 'deniable' : 'standard';
+            }
+            // The private owner axis is the userId (deniability is personal), matching mountPrivateRoutes.
+            const ctx = { userId: who.userId, tenantId: who.userId };
+            const tags = c.req.header('x-tags');
+            try {
+                const item = await catalogue.ingestPrivate(ctx, {
+                    name: c.req.header('x-filename') ?? 'upload',
+                    mime: c.req.header('content-type') ?? 'application/octet-stream',
+                    body,
+                    tags: tags
+                        ? tags
+                            .split(',')
+                            .map((t) => t.trim())
+                            .filter(Boolean)
+                        : undefined,
+                }, { setKey, keyMode });
+                return c.json({ item });
+            }
+            catch (e) {
+                if (isUploadTooLarge(e))
+                    return c.json({ error: SINGLE_UPLOAD_TOO_LARGE }, 413);
+                throw e;
+            }
+        });
+    }
+    // Chunked upload (large files, direct-to-backend). init → the client PUTs each chunk straight to
+    // the backend (URLs the app minted) → complete registers the row over the assembled bytes. The
+    // bytes never traverse this origin.
+    const chunked = opts.chunked;
+    if (chunked && opts.authorizeUpload) {
+        app.post(`${base}/upload-init`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!body.size || body.size <= 0)
+                return c.json({ error: 'size required' }, 400);
+            const init = await chunked.init(ctx, {
+                name: body.name ?? 'upload',
+                mime: body.mime ?? 'application/octet-stream',
+                size: body.size,
+                tags: body.tags,
+            });
+            return c.json(init);
+        });
+        app.post(`${base}/upload-complete`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!body.sid)
+                return c.json({ error: 'sid required' }, 400);
+            const file = await chunked.complete(body.sid, { size: body.size });
+            if (!file)
+                return c.json({ error: 'unknown session' }, 404);
+            return c.json({ file });
+        });
+        app.post(`${base}/upload-abort`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (body.sid)
+                chunked.abort(body.sid);
+            return c.json({ ok: true });
+        });
+    }
+    // ── Listing + collection routes ───────────────────────────────────────────────
+    // All require authorizeUpload (session auth) and a catalogue. They follow the same
+    // auth/ctx/envelope pattern as the upload routes above. The `includeUnlockable` gate is the
+    // caller's responsibility — the route passes the query param through, and it's the app's session
+    // middleware that decides whether the caller has unlocked.
+    if (opts.authorizeUpload && catalogue) {
+        // GET /_files/list → cursor-paginated catalogue listing. Query params mirror
+        // ListFilesOptions: type, tag, query (q), collectionId, favorite, includeUnlockable,
+        // sort (recent|oldest|name|size|random|lastViewed), cursor, limit.
+        app.get(`${base}/list`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const q = c.req.query();
+            const sort = FILE_SORTS.includes(q.sort ?? '')
+                ? q.sort
+                : undefined;
+            const limit = q.limit ? Number(q.limit) : undefined;
+            const page = await catalogue.list(ctx, {
+                type: q.type,
+                tag: q.tag || undefined,
+                query: q.q || undefined,
+                collectionId: q.collectionId || undefined,
+                favorite: q.favorite === '1' ? true : undefined,
+                includeUnlockable: q.includeUnlockable === '1' ? true : undefined,
+                sort,
+                cursor: q.cursor || undefined,
+                limit: limit && Number.isFinite(limit) ? limit : undefined,
+            });
+            return c.json(page);
+        });
+        // GET  /_files/collections           → list all visible collections
+        app.get(`${base}/collections`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const includeUnlockable = c.req.query('includeUnlockable') === '1';
+            const collections = await catalogue.listCollections(ctx, { includeUnlockable });
+            return c.json({ collections });
+        });
+        // POST /_files/collections           → create a collection
+        app.post(`${base}/collections`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!body.name)
+                return c.json({ error: 'name required' }, 400);
+            try {
+                const collection = await catalogue.createCollection(ctx, {
+                    name: body.name,
+                    visibility: body.visibility === 'unlock' || body.visibility === 'normal'
+                        ? body.visibility
+                        : undefined,
+                });
+                return c.json({ collection }, 201);
+            }
+            catch (e) {
+                return c.json({ error: e instanceof Error ? e.message : 'invalid' }, 400);
+            }
+        });
+        // PATCH /_files/collections/:id      → rename / change visibility
+        app.patch(`${base}/collections/:id`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            try {
+                const collection = await catalogue.updateCollection(ctx, c.req.param('id'), {
+                    name: body.name,
+                    visibility: body.visibility === 'unlock' || body.visibility === 'normal'
+                        ? body.visibility
+                        : undefined,
+                });
+                if (!collection)
+                    return c.json({ error: 'not found' }, 404);
+                return c.json({ collection });
+            }
+            catch (e) {
+                return c.json({ error: e instanceof Error ? e.message : 'invalid' }, 400);
+            }
+        });
+        // DELETE /_files/collections/:id     → remove collection (not files)
+        app.delete(`${base}/collections/:id`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            try {
+                await catalogue.removeCollection(ctx, c.req.param('id'));
+                return c.json({ ok: true });
+            }
+            catch (e) {
+                return c.json({ error: e instanceof Error ? e.message : 'invalid' }, 400);
+            }
+        });
+        // POST /_files/collections/:id/members   → add files to a collection
+        app.post(`${base}/collections/:id/members`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!Array.isArray(body.fileIds) || body.fileIds.length === 0) {
+                return c.json({ error: 'fileIds required' }, 400);
+            }
+            await catalogue.addToCollection(ctx, c.req.param('id'), body.fileIds);
+            return c.json({ ok: true });
+        });
+        // DELETE /_files/collections/:id/members → remove files from a collection
+        app.delete(`${base}/collections/:id/members`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!Array.isArray(body.fileIds) || body.fileIds.length === 0) {
+                return c.json({ error: 'fileIds required' }, 400);
+            }
+            await catalogue.removeFromCollection(ctx, c.req.param('id'), body.fileIds);
+            return c.json({ ok: true });
+        });
+        // POST /_files/favorites  → toggle favorite state for a single file
+        app.post(`${base}/favorites`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!body.fileId)
+                return c.json({ error: 'fileId required' }, 400);
+            await catalogue.setFavorite(ctx, body.fileId, body.favorite ?? true);
+            return c.json({ ok: true });
+        });
+        // POST /_files/view  → record a watch-open of a file (feeds the `lastViewed` sort). Idempotent
+        // in effect (upsert); an unknown/other-owner id records nothing but still returns ok.
+        app.post(`${base}/view`, async (c) => {
+            const ctx = await opts.authorizeUpload?.(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const body = (await c.req.json().catch(() => ({})));
+            if (!body.fileId)
+                return c.json({ error: 'fileId required' }, 400);
+            await catalogue.recordView(ctx, body.fileId);
+            return c.json({ ok: true });
+        });
+    }
+}

package/dist/server/storage/files/index.d.ts

@@ -0,0 +1,9 @@
+export { createCatalogueMediaSource, createCataloguePhotoSource, createCatalogueVideoSource, createFileToPlayable, } from './adapter';
+export { catalogueUploadKey, createSqliteFileCatalogue, fileBinaryKey, type ImageDerivatives, type ImageDerivativesOptions, type SqliteFileCatalogueOptions, type VideoProcessor, } from './catalogue';
+export type { CatalogueStats } from './types';
+export { type ChunkedInit, type ChunkedUploadService, createChunkedUploadService, type MintChunkUpload, } from './chunkedUpload';
+export { createFileUrls, type FileUrls, type MountFileRoutesOptions, mountFileRoutes, SINGLE_UPLOAD_TOO_LARGE, } from './fileRoutes';
+export { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+export { createFilesStack, type FilesStack, type FilesStackMountAuth, type FilesStackOptions, } from './stack';
+export { createLedgeredDeletes, createStorageOpsLedger, createStorageReconciler, type StorageAction, type StorageOpRow, type StorageOpsLedger, type StorageReconciler, } from './storageOps';
+export { type CollectionKind, type CollectionVisibility, classifyFileType, FILE_SORTS, type FileCatalogue, type FileCollection, type FilePage, type FileRecord, type FileSort, type FileToPlayable, type FileType, type ListFilesOptions, type PrivateFileCatalogue, type PrivateFileItem, type PrivateKeyMode, type TagFacet, } from './types';

package/dist/server/storage/files/index.js

@@ -0,0 +1,11 @@
+// cursedbelt-server/storage FileCatalogue — a SQLite-backed tagged flat file system over the
+// MediaStore + media pipeline + private-media. One source of truth for a user's binaries; the
+// video gallery is a video-filtered view over it.
+export { createCatalogueMediaSource, createCataloguePhotoSource, createCatalogueVideoSource, createFileToPlayable, } from './adapter';
+export { catalogueUploadKey, createSqliteFileCatalogue, fileBinaryKey, } from './catalogue';
+export { createChunkedUploadService, } from './chunkedUpload';
+export { createFileUrls, mountFileRoutes, SINGLE_UPLOAD_TOO_LARGE, } from './fileRoutes';
+export { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+export { createFilesStack, } from './stack';
+export { createLedgeredDeletes, createStorageOpsLedger, createStorageReconciler, } from './storageOps';
+export { classifyFileType, FILE_SORTS, } from './types';

package/dist/server/storage/files/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from '../../migration/types';
+export declare const FILE_CATALOGUE_MIGRATIONS: readonly Migration[];