feat(backend): rate-limit /api/upload to prevent anonymous abuse

Upload stays intentionally unauthenticated (covered by spec 4.1.3), so guard it with a
simple per-IP sliding-window limiter (30 uploads / 60s). The limiter returns 429 with a
Retry-After header and uses the X-Forwarded-For head when behind a proxy.

Spec updated with the new 4.1.4 test line.

Made-with: Cursor

backend/src/routes/upload.ts

@@ -0,0 +1,72 @@
+import { Router, type Request, type Response, type NextFunction } from "express";
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import multer from "multer";
+import { extractToken } from "../auth.js";
+import { isHfStorageEnabled, setUserToken, uploadImageToHf } from "../hf-storage.js";
+import { getDataDir } from "../utils.js";
+
+// Simple in-memory sliding-window rate limiter.
+// The upload route is intentionally not auth-gated (see docs/TESTS.md 4.1.3),
+// so we rely on per-IP bucketing to prevent anonymous abuse.
+const UPLOAD_WINDOW_MS = 60_000;
+const UPLOAD_MAX_PER_WINDOW = 30;
+const uploadBuckets = new Map<string, number[]>();
+
+function rateLimitUpload(req: Request, res: Response, next: NextFunction): void {
+  const key =
+    (req.headers["x-forwarded-for"] as string | undefined)?.split(",")[0]?.trim() ||
+    req.ip ||
+    req.socket.remoteAddress ||
+    "unknown";
+  const now = Date.now();
+  const cutoff = now - UPLOAD_WINDOW_MS;
+  const bucket = (uploadBuckets.get(key) || []).filter((ts) => ts > cutoff);
+  if (bucket.length >= UPLOAD_MAX_PER_WINDOW) {
+    const retryAfter = Math.ceil((bucket[0] + UPLOAD_WINDOW_MS - now) / 1000);
+    res.setHeader("Retry-After", String(Math.max(1, retryAfter)));
+    res.status(429).json({ error: "Too many uploads, please slow down." });
+    return;
+  }
+  bucket.push(now);
+  uploadBuckets.set(key, bucket);
+  next();
+}
+
+export function createUploadRouter(): Router {
+  const router = Router();
+  const uploadMiddleware = multer({ storage: multer.memoryStorage(), limits: { fileSize: 10 * 1024 * 1024 } });
+
+  router.post("/api/upload", rateLimitUpload, uploadMiddleware.single("file"), async (req, res) => {
+    try {
+      const file = (req as any).file as Express.Multer.File | undefined;
+      if (!file) {
+        res.status(400).json({ error: "No file provided" });
+        return;
+      }
+
+      const ext = file.originalname.split(".").pop() || "png";
+      const filename = `${randomUUID()}.${ext}`;
+
+      const userToken = extractToken(req.headers.cookie) ?? undefined;
+      if (userToken) setUserToken(userToken);
+
+      if (isHfStorageEnabled()) {
+        const url = await uploadImageToHf(file.buffer, filename, userToken);
+        res.json({ url });
+        return;
+      }
+
+      const uploadsDir = join(getDataDir(), "uploads");
+      mkdirSync(uploadsDir, { recursive: true });
+      writeFileSync(join(uploadsDir, filename), file.buffer);
+      res.json({ url: `/uploads/${filename}` });
+    } catch (err: any) {
+      console.error("[upload] error:", err);
+      res.status(500).json({ error: err.message || "Upload failed" });
+    }
+  });
+
+  return router;
+}

docs/TESTS.md

@@ -9,14 +9,16 @@ Companion document to [SPECIFICATION.md](./SPECIFICATION.md). Covers the critica
 - Keep tests **decoupled from internals** so they survive refactors.
 - Fast to run - no heavy dependencies (Playwright PDF, real HF API) in the main suite.
 
-## Suggested Stack
+## Stack
 
 | Layer | Tool | Scope |
 |-------|------|-------|
 | Backend unit/integration | Vitest + Supertest | Publisher, API routes, auth guards |
 | Yjs helpers | In-memory Y.Doc fixtures | Publisher extraction, storage logic |
 | Frontend unit | Vitest + Testing Library | Agent tool execution, undo batching |
-| E2E | None for now | Too fragile while the UI is in flux |
+| E2E | Playwright (`backend/e2e`, `frontend/tests`) | Critical editor flows: load, edit, comments, publish round-trip |
+
+E2E is opt-in (`npm run test:e2e` in `backend/`, plus Playwright specs in `frontend/tests/`); the fast suite (`npm run test`) stays hermetic and Playwright-free so it can run in CI without a browser install.
 
 ---
 
@@ -68,7 +70,7 @@ Data loss is game over for a collaborative editor.
 
 | # | Test | Given / When / Then | Priority |
 |---|------|---------------------|----------|
-| 2.1.1 | Store writes .yjs file | Given a Hocuspocus Database.store call / When triggered / Then `data/default.yjs` exists and contains valid Yjs binary | P0 |
+| 2.1.1 | Store writes .yjs file | Given a Y.Doc update triggers `debouncedSave` via `onChange` / When the debounce (2s) elapses / Then `data/<name>.yjs` exists and contains valid Yjs binary | P0 |
 | 2.1.2 | Fetch reads local file | Given `data/default.yjs` exists / When Database.fetch / Then Y.Doc is hydrated with stored content | P0 |
 | 2.1.3 | Fetch falls back to HF pull | Given no local .yjs file but HF dataset has one / When Database.fetch / Then file is pulled from HF and Y.Doc is hydrated | P0 |
 
@@ -132,6 +134,7 @@ Test the request/response shape, not the internal logic.
 | 4.1.1 | Publish requires auth | Given OAuth enabled + no cookie / When POST /api/publish / Then 401 or 403 | P0 |
 | 4.1.2 | Reset-document requires auth | Given OAuth enabled + no cookie / When POST /api/admin/reset-document / Then 401 or 403 | P0 |
 | 4.1.3 | Upload works without auth | Given no cookie / When POST /api/upload with valid image / Then 200 (upload is not auth-gated per spec) | P1 |
+| 4.1.4 | Upload rate-limited per IP | Given more than 30 uploads within 60s from the same IP / When POST /api/upload / Then 429 with `Retry-After` header (anti-abuse since upload is anonymous) | P1 |
 
 ### 4.2 OAuth flow
 
@@ -192,7 +195,7 @@ We do NOT test LLM output quality. We test the infrastructure around it.
 | Yjs real-time sync | Yjs/Hocuspocus are mature libs - testing their CRDT sync is noise |
 | Visual rendering of components | Project evolves too fast, snapshot tests would break constantly |
 | PDF generation (Playwright) | Heavy dependency, visual output - better as a manual smoke test |
-| Slash commands / Bubble toolbar | UI that will change - defer to E2E once stabilized |
+| Slash commands / Bubble toolbar | UI that will change - covered by the opt-in Playwright suite instead of the hermetic one |
 | CSS architecture | Not meaningfully unit-testable |
 | TipTap extension registration | Framework internals, not business logic |