cursedbelt-server 1.0.0

package/src/server/storage/files/fileRoutes.ts

@@ -0,0 +1,462 @@
+import type { Context, Hono } from 'hono';
+import { MAX_SINGLE_UPLOAD_BYTES } from 'cursedbelt-core/media/upload-limits';
+import type { UnlockPasswordPolicy, UnlockService } from '../../private-media/unlock';
+import { serveRange } from '../streamRange';
+import type { StreamTokenService } from '../streamToken';
+import type { MediaCtx, MediaStore } from '../types';
+import { fileBinaryKey } from './catalogue';
+import type { ChunkedUploadService } from './chunkedUpload';
+import {
+  FILE_SORTS,
+  type FileCatalogue,
+  type ListFilesOptions,
+  type PrivateFileCatalogue,
+} 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: unknown): boolean =>
+  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: Context,
+  body: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> | Response {
+  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<Uint8Array, Uint8Array>({
+      transform(chunk, ctrl) {
+        seen += chunk.byteLength;
+        if (seen > MAX_SINGLE_UPLOAD_BYTES) {
+          ctrl.error(new UploadTooLargeError());
+          return;
+        }
+        ctrl.enqueue(chunk);
+      },
+    }),
+  );
+}
+
+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 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 {
+  const ownerOf = opts.owner ?? ((c: MediaCtx) => 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 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 function mountFileRoutes(app: Hono, opts: MountFileRoutesOptions): void {
+  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: Buffer;
+      let keyMode: 'standard' | 'deniable';
+      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' as const };
+        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: MediaCtx = { 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(() => ({}))) as {
+        name?: string;
+        mime?: string;
+        size?: number;
+        tags?: string[];
+      };
+      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(() => ({}))) as { sid?: string; size?: number };
+      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(() => ({}))) as { sid?: string };
+      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 as readonly string[]).includes(q.sort ?? '')
+        ? (q.sort as ListFilesOptions['sort'])
+        : undefined;
+      const limit = q.limit ? Number(q.limit) : undefined;
+      const page = await catalogue.list(ctx, {
+        type: q.type as ListFilesOptions['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(() => ({}))) as {
+        name?: string;
+        visibility?: string;
+      };
+      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(() => ({}))) as {
+        name?: string;
+        visibility?: string;
+      };
+      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(() => ({}))) as { fileIds?: string[] };
+      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(() => ({}))) as { fileIds?: string[] };
+      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(() => ({}))) as {
+        fileId?: string;
+        favorite?: boolean;
+      };
+      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(() => ({}))) as { fileId?: string };
+      if (!body.fileId) return c.json({ error: 'fileId required' }, 400);
+      await catalogue.recordView(ctx, body.fileId);
+      return c.json({ ok: true });
+    });
+  }
+}

package/src/server/storage/files/index.ts

@@ -0,0 +1,66 @@
+// 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,
+  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';