0.2.1 Release (#32)

* feat(security): implement CSRF protection

* chore: clean up CSRF implementation

  - Remove unused generateCsrfToken export from security.ts
  - Remove redundant /csrf-token path check (GET already exempt)
  - Restore defineConfig wrapper in vitest.config.ts for type safety

* add K8S note in README, fix broken e2e

* feat/upload-bar (#30)

* feat/upload-bar: add a upload bar when user upload file, indicate the upload process

* feat/save-loading-status: add save status when click back button from editor

* fix: address PR review issues in upload and save features

- Replace deprecated substr() with substring() in UploadContext
- Fix broken error handling that checked stale task status
- Fix missing useEffect dependency in UploadStatus
- Fix CSS class conflict in progress bar styling
- Add error recovery for save state in Editor (reset on failure)
- Use .finally() instead of .then() to ensure refresh on upload failure
- Fix inconsistent indentation in UploadContext

* fix e2e tests

---------

Co-authored-by: Zimeng Xiong <zxzimeng@gmail.com>

* chore: pre-release v0.2.1-dev

* Update backend/src/security.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix filename/math random UUID generation

---------

Co-authored-by: AdrianAcala <adrianacala017@gmail.com>
Co-authored-by: adamant368 <60790941+Yiheng-Liu@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

backend/src/__tests__/csrf.integration.ts

@@ -0,0 +1,168 @@
+/**
+ * CSRF Tests - Horizontal Scaling (K8s) Validation
+ *
+ * PR #20 review concern:
+ * "Worried that in memory token store might not work on horizontal scaling"
+ *
+ * Fix:
+ * - CSRF tokens are now stateless and HMAC-signed using a shared `CSRF_SECRET`.
+ * - Any pod can validate any token as long as all pods share the same secret.
+ *
+ * These tests prove:
+ * - Tokens validate correctly for the issuing client id
+ * - Tokens do NOT validate for a different client id
+ * - Tokens expire after 24 hours
+ * - Tokens validate across separate module instances (simulated pods)
+ */
+
+import { describe, it, expect, beforeAll, afterEach, vi } from "vitest";
+
+const SHARED_SECRET = "test-shared-csrf-secret";
+
+beforeAll(() => {
+  // Must be shared across instances/pods for horizontal scaling.
+  process.env.CSRF_SECRET = SHARED_SECRET;
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("CSRF - stateless HMAC tokens", () => {
+  it("creates a token in payload.signature format and validates for same client id", async () => {
+    const { createCsrfToken, validateCsrfToken } = await import("../security");
+
+    const clientId = "test-client-1";
+    const token = createCsrfToken(clientId);
+
+    expect(typeof token).toBe("string");
+    // base64url(payload).base64url(signature)
+    expect(token).toMatch(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/);
+    expect(validateCsrfToken(clientId, token)).toBe(true);
+  });
+
+  it("rejects validation for a different client id (token binding)", async () => {
+    const { createCsrfToken, validateCsrfToken } = await import("../security");
+
+    const token = createCsrfToken("client-a");
+    expect(validateCsrfToken("client-b", token)).toBe(false);
+  });
+
+  it("rejects malformed tokens", async () => {
+    const { validateCsrfToken } = await import("../security");
+
+    expect(validateCsrfToken("client", "not-a-token")).toBe(false);
+    expect(validateCsrfToken("client", "a.b.c")).toBe(false);
+    expect(validateCsrfToken("client", "")).toBe(false);
+  });
+
+  it("revokeCsrfToken is a no-op for stateless tokens (does not break callers)", async () => {
+    const { createCsrfToken, validateCsrfToken, revokeCsrfToken } = await import(
+      "../security"
+    );
+
+    const clientId = "client-revoke";
+    const token = createCsrfToken(clientId);
+
+    expect(validateCsrfToken(clientId, token)).toBe(true);
+    revokeCsrfToken(clientId);
+    // Stateless token remains valid until expiry
+    expect(validateCsrfToken(clientId, token)).toBe(true);
+  });
+
+  it("expires tokens after 24 hours", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2025-01-01T00:00:00.000Z"));
+
+    const { createCsrfToken, validateCsrfToken } = await import("../security");
+
+    const clientId = "client-expiry";
+    const token = createCsrfToken(clientId);
+    expect(validateCsrfToken(clientId, token)).toBe(true);
+
+    // 24h + 1ms later
+    vi.setSystemTime(new Date("2025-01-02T00:00:00.001Z"));
+    expect(validateCsrfToken(clientId, token)).toBe(false);
+  });
+});
+
+describe("CSRF - horizontal scaling (simulated pods)", () => {
+  it("validates across module instances (pod A issues, pod B validates)", async () => {
+    const clientId = "user-123";
+
+    vi.resetModules();
+    const podA = await import("../security");
+    const token = podA.createCsrfToken(clientId);
+
+    // Simulate a different pod (new Node.js process / fresh module state)
+    vi.resetModules();
+    const podB = await import("../security");
+
+    expect(podB.validateCsrfToken(clientId, token)).toBe(true);
+  });
+
+  it("has 0% failure rate under round-robin validation across 3 pods", async () => {
+    const clientId = "user-round-robin";
+
+    const pods: Array<{
+      createCsrfToken: (clientId: string) => string;
+      validateCsrfToken: (clientId: string, token: string) => boolean;
+    }> = [];
+
+    for (let i = 0; i < 3; i++) {
+      vi.resetModules();
+      pods.push(await import("../security"));
+    }
+
+    // Token issued on one pod
+    const token = pods[0].createCsrfToken(clientId);
+
+    // Validate on alternating pods (simulates a non-sticky load balancer)
+    const attempts = 60;
+    let failures = 0;
+
+    for (let i = 0; i < attempts; i++) {
+      const pod = pods[i % pods.length];
+      if (!pod.validateCsrfToken(clientId, token)) failures++;
+    }
+
+    expect(failures).toBe(0);
+  });
+});
+
+describe("CSRF - referer origin parsing", () => {
+  it("extracts exact origin from a referer URL", async () => {
+    const { getOriginFromReferer } = await import("../security");
+
+    expect(getOriginFromReferer("https://example.com/path?x=1")).toBe(
+      "https://example.com"
+    );
+    expect(getOriginFromReferer("http://localhost:5173/some/page")).toBe(
+      "http://localhost:5173"
+    );
+  });
+
+  it("does not allow prefix tricks (origin must be parsed)", async () => {
+    const { getOriginFromReferer } = await import("../security");
+
+    expect(
+      getOriginFromReferer("https://example.com.evil.com/anything")
+    ).toBe("https://example.com.evil.com");
+
+    // `startsWith("https://example.com")` would incorrectly allow this.
+    expect(getOriginFromReferer("https://example.com@evil.com/anything")).toBe(
+      "https://evil.com"
+    );
+  });
+
+  it("returns null for invalid or non-http(s) referers", async () => {
+    const { getOriginFromReferer } = await import("../security");
+
+    expect(getOriginFromReferer("")).toBeNull();
+    expect(getOriginFromReferer("not a url")).toBeNull();
+    expect(getOriginFromReferer("file:///etc/passwd")).toBeNull();
+    expect(getOriginFromReferer(null)).toBeNull();
+  });
+});
+
+

backend/src/index.ts

@@ -18,6 +18,10 @@ import {
   sanitizeSvg,
   elementSchema,
   appStateSchema,
+  createCsrfToken,
+  validateCsrfToken,
+  getCsrfTokenHeader,
+  getOriginFromReferer,
 } from "./security";
 
 dotenv.config();
@@ -34,9 +38,22 @@ const resolveDatabaseUrl = (rawUrl?: string) => {
   }
 
   const filePath = rawUrl.replace(/^file:/, "");
+
+  // Prisma treats relative SQLite paths as relative to the schema directory
+  // (i.e. `backend/prisma/schema.prisma`). Historically this project used
+  // `file:./prisma/dev.db`, which Prisma interprets as `prisma/prisma/dev.db`.
+  // To keep runtime and migrations aligned:
+  // - Prefer resolving relative paths against `backend/prisma`
+  // - But if the path already includes a leading `prisma/`, resolve from repo root
+  const prismaDir = path.resolve(backendRoot, "prisma");
+  const normalizedRelative = filePath.replace(/^\.\/?/, "");
+  const hasLeadingPrismaDir =
+    normalizedRelative === "prisma" ||
+    normalizedRelative.startsWith("prisma/");
+
   const absolutePath = path.isAbsolute(filePath)
     ? filePath
-    : path.resolve(backendRoot, filePath);
+    : path.resolve(hasLeadingPrismaDir ? backendRoot : prismaDir, normalizedRelative);
 
   return `file:${absolutePath}`;
 };
@@ -63,11 +80,15 @@ const normalizeOrigins = (rawOrigins?: string | null): string[] => {
   const ensureProtocol = (origin: string) =>
     /^https?:\/\//i.test(origin) ? origin : `http://${origin}`;
 
+  const removeTrailingSlash = (origin: string) =>
+    origin.endsWith("/") ? origin.slice(0, -1) : origin;
+
   const parsed = rawOrigins
     .split(",")
     .map((origin) => origin.trim())
     .filter((origin) => origin.length > 0)
-    .map(ensureProtocol);
+    .map(ensureProtocol)
+    .map(removeTrailingSlash);
 
   return parsed.length > 0 ? parsed : [fallback];
 };
@@ -211,6 +232,8 @@ app.use(
   cors({
     origin: allowedOrigins,
     credentials: true,
+    allowedHeaders: ["Content-Type", "Authorization", "x-csrf-token"],
+    exposedHeaders: ["x-csrf-token"],
   })
 );
 app.use(express.json({ limit: "50mb" }));
@@ -244,12 +267,12 @@ app.use((req, res, next) => {
   res.setHeader(
     "Content-Security-Policy",
     "default-src 'self'; " +
-      "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net https://unpkg.com; " +
-      "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
-      "font-src 'self' https://fonts.gstatic.com; " +
-      "img-src 'self' data: blob: https:; " +
-      "connect-src 'self' ws: wss:; " +
-      "frame-ancestors 'none';"
+    "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net https://unpkg.com; " +
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+    "font-src 'self' https://fonts.gstatic.com; " +
+    "img-src 'self' data: blob: https:; " +
+    "connect-src 'self' ws: wss:; " +
+    "frame-ancestors 'none';"
   );
 
   next();
@@ -296,6 +319,128 @@ app.use((req, res, next) => {
   next();
 });
 
+// CSRF Protection Middleware
+// Generates a unique client ID based on IP and User-Agent for token association
+const getClientId = (req: express.Request): string => {
+  const ip = req.ip || req.connection.remoteAddress || "unknown";
+  const userAgent = req.headers["user-agent"] || "unknown";
+  // Create a simple hash for client identification
+  // In production, you might use a session ID instead
+  return `${ip}:${userAgent}`.slice(0, 256);
+};
+
+// Rate limiter specifically for CSRF token generation to prevent store exhaustion
+const csrfRateLimit = new Map<string, { count: number; resetTime: number }>();
+const CSRF_RATE_LIMIT_WINDOW = 60 * 1000; // 1 minute
+const CSRF_MAX_REQUESTS = (() => {
+  const parsed = Number(process.env.CSRF_MAX_REQUESTS);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return 60; // 1 per second average
+  }
+  return parsed;
+})();
+
+// CSRF token endpoint - clients should call this to get a token
+app.get("/csrf-token", (req, res) => {
+  const ip = req.ip || req.connection.remoteAddress || "unknown";
+  const now = Date.now();
+  const clientLimit = csrfRateLimit.get(ip);
+
+  if (clientLimit && now < clientLimit.resetTime) {
+    if (clientLimit.count >= CSRF_MAX_REQUESTS) {
+      return res.status(429).json({
+        error: "Rate limit exceeded",
+        message: "Too many CSRF token requests",
+      });
+    }
+    clientLimit.count++;
+  } else {
+    csrfRateLimit.set(ip, { count: 1, resetTime: now + CSRF_RATE_LIMIT_WINDOW });
+  }
+
+  // Cleanup old rate limit entries occasionally
+  if (Math.random() < 0.01) {
+    for (const [key, data] of csrfRateLimit.entries()) {
+      if (now > data.resetTime) csrfRateLimit.delete(key);
+    }
+  }
+
+  const clientId = getClientId(req);
+  const token = createCsrfToken(clientId);
+
+  res.json({
+    token,
+    header: getCsrfTokenHeader()
+  });
+});
+
+// CSRF validation middleware for state-changing requests
+const csrfProtectionMiddleware = (
+  req: express.Request,
+  res: express.Response,
+  next: express.NextFunction
+) => {
+  // Skip CSRF validation for safe methods (GET, HEAD, OPTIONS)
+  // Note: /csrf-token is a GET endpoint, so it's automatically exempt
+  const safeMethods = ["GET", "HEAD", "OPTIONS"];
+  if (safeMethods.includes(req.method)) {
+    return next();
+  }
+
+  // Origin/Referer check for defense in depth
+  const origin = req.headers["origin"];
+  const referer = req.headers["referer"];
+
+  // If Origin is present, it must match allowed origins
+  const originValue = Array.isArray(origin) ? origin[0] : origin;
+  const refererValue = Array.isArray(referer) ? referer[0] : referer;
+
+  if (originValue) {
+    if (!allowedOrigins.includes(originValue)) {
+      return res.status(403).json({
+        error: "CSRF origin mismatch",
+        message: "Origin not allowed",
+      });
+    }
+  } else if (refererValue) {
+    // If no Origin but Referer exists, validate its *origin* (avoid prefix bypass)
+    const refererOrigin = getOriginFromReferer(refererValue);
+    if (!refererOrigin || !allowedOrigins.includes(refererOrigin)) {
+      return res.status(403).json({
+        error: "CSRF referer mismatch",
+        message: "Referer not allowed",
+      });
+    }
+  }
+  // Note: If neither Origin nor Referer is present, we proceed to token check.
+  // Some legitimate clients/proxies might strip these, so we don't block strictly on their absence,
+  // but relying on the token is the primary defense.
+
+  const clientId = getClientId(req);
+  const headerName = getCsrfTokenHeader();
+  const tokenHeader = req.headers[headerName];
+  const token = Array.isArray(tokenHeader) ? tokenHeader[0] : tokenHeader;
+
+  if (!token) {
+    return res.status(403).json({
+      error: "CSRF token missing",
+      message: `Missing ${headerName} header`,
+    });
+  }
+
+  if (!validateCsrfToken(clientId, token)) {
+    return res.status(403).json({
+      error: "CSRF token invalid",
+      message: "Invalid or expired CSRF token. Please refresh and try again.",
+    });
+  }
+
+  next();
+};
+
+// Apply CSRF protection to all routes
+app.use(csrfProtectionMiddleware);
+
 const filesFieldSchema = z
   .union([z.record(z.string(), z.any()), z.null()])
   .optional()
@@ -922,8 +1067,7 @@ app.get("/export", async (req, res) => {
     res.setHeader("Content-Type", "application/octet-stream");
     res.setHeader(
       "Content-Disposition",
-      `attachment; filename="excalidash-db-${
-        new Date().toISOString().split("T")[0]
+      `attachment; filename="excalidash-db-${new Date().toISOString().split("T")[0]
       }.${extension}"`
     );
 
@@ -946,8 +1090,7 @@ app.get("/export/json", async (req, res) => {
     res.setHeader("Content-Type", "application/zip");
     res.setHeader(
       "Content-Disposition",
-      `attachment; filename="excalidraw-drawings-${
-        new Date().toISOString().split("T")[0]
+      `attachment; filename="excalidraw-drawings-${new Date().toISOString().split("T")[0]
       }.zip"`
     );
 
@@ -1012,8 +1155,8 @@ Total Drawings: ${drawings.length}
 
 Collections:
 ${Object.entries(drawingsByCollection)
-  .map(([name, drawings]) => `- ${name}: ${drawings.length} drawings`)
-  .join("\n")}
+        .map(([name, drawings]) => `- ${name}: ${drawings.length} drawings`)
+        .join("\n")}
 `;
 
     archive.append(readmeContent, { name: "README.txt" });
@@ -1085,7 +1228,7 @@ app.post("/import/sqlite", upload.single("db"), async (req, res) => {
       try {
         await fsPromises.access(dbPath);
         await fsPromises.copyFile(dbPath, backupPath);
-      } catch {}
+      } catch { }
 
       await moveFile(stagedPath, dbPath);
     } catch (error) {

backend/src/security.ts

@@ -1,6 +1,10 @@
+/**
+ * Security utilities for XSS prevention, data sanitization, and CSRF protection
+ */
 import { z } from "zod";
 import DOMPurify from "dompurify";
 import { JSDOM } from "jsdom";
+import crypto from "crypto";
 
 // Create a DOM environment for DOMPurify (Node.js compatibility)
 const window = new JSDOM("").window;
@@ -523,3 +527,179 @@ export const validateImportedDrawing = (data: any): boolean => {
     return false;
   }
 };
+
+// ============================================================================
+// CSRF Protection
+// ============================================================================
+
+const CSRF_TOKEN_HEADER = "x-csrf-token";
+const CSRF_TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CSRF_TOKEN_FUTURE_SKEW_MS = 5 * 60 * 1000; // 5 minutes clock skew tolerance
+const CSRF_NONCE_BYTES = 16;
+const CSRF_TOKEN_MAX_LENGTH = 2048; // sanity limit against abuse
+
+/**
+ * IMPORTANT (Horizontal Scaling / K8s)
+ * -----------------------------------
+ * CSRF tokens must validate across multiple stateless instances.
+ *
+ * The prior in-memory Map-based token store breaks under horizontal scaling
+ * because each pod has its own memory. This implementation is stateless:
+ *
+ * - Token payload: { ts, nonce }
+ * - Signature: HMAC_SHA256(secret, `${clientId}|${ts}|${nonce}`)
+ *
+ * As long as all pods share the same `CSRF_SECRET`, any pod can validate
+ * any token without shared state (works on Kubernetes).
+ */
+
+let cachedCsrfSecret: Buffer | null = null;
+const getCsrfSecret = (): Buffer => {
+  if (cachedCsrfSecret) return cachedCsrfSecret;
+
+  const secretFromEnv = process.env.CSRF_SECRET;
+  if (secretFromEnv && secretFromEnv.trim().length > 0) {
+    cachedCsrfSecret = Buffer.from(secretFromEnv, "utf8");
+    return cachedCsrfSecret;
+  }
+
+  // If not configured, generate an ephemeral secret for this process.
+  // This keeps single-instance deployments working out of the box, but:
+  // - Horizontal scaling will BREAK unless CSRF_SECRET is set and shared.
+  cachedCsrfSecret = crypto.randomBytes(32);
+  const envLabel = process.env.NODE_ENV ? ` (${process.env.NODE_ENV})` : "";
+  console.warn(
+    `[security] CSRF_SECRET is not set${envLabel}. Using an ephemeral per-process secret. ` +
+    "For horizontal scaling (k8s), set CSRF_SECRET to the same value on all instances."
+  );
+  return cachedCsrfSecret;
+};
+
+const base64UrlEncode = (input: Buffer | string): string => {
+  const buf = typeof input === "string" ? Buffer.from(input, "utf8") : input;
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+};
+
+const base64UrlDecode = (input: string): Buffer => {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded, "base64");
+};
+
+type CsrfTokenPayload = {
+  /** Issued-at timestamp (ms since epoch) */
+  ts: number;
+  /** Random nonce (base64url) */
+  nonce: string;
+};
+
+const signCsrfToken = (clientId: string, payload: CsrfTokenPayload): Buffer => {
+  const secret = getCsrfSecret();
+  const data = `${clientId}|${payload.ts}|${payload.nonce}`;
+  return crypto.createHmac("sha256", secret).update(data, "utf8").digest();
+};
+
+/**
+ * Create a new CSRF token for a client
+ * Returns the token to be sent to the client
+ */
+export const createCsrfToken = (clientId: string): string => {
+  const payload: CsrfTokenPayload = {
+    ts: Date.now(),
+    nonce: base64UrlEncode(crypto.randomBytes(CSRF_NONCE_BYTES)),
+  };
+
+  const payloadJson = JSON.stringify(payload);
+  const payloadB64 = base64UrlEncode(payloadJson);
+  const sigB64 = base64UrlEncode(signCsrfToken(clientId, payload));
+
+  return `${payloadB64}.${sigB64}`;
+};
+
+/**
+ * Validate a CSRF token for a client
+ * Uses timing-safe comparison to prevent timing attacks
+ */
+export const validateCsrfToken = (clientId: string, token: string): boolean => {
+  if (!token || typeof token !== "string") {
+    return false;
+  }
+
+  if (token.length > CSRF_TOKEN_MAX_LENGTH) {
+    return false;
+  }
+
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 2) return false;
+
+    const [payloadB64, sigB64] = parts;
+    const payloadJson = base64UrlDecode(payloadB64).toString("utf8");
+    const payload = JSON.parse(payloadJson) as Partial<CsrfTokenPayload>;
+
+    if (
+      typeof payload.ts !== "number" ||
+      !Number.isFinite(payload.ts) ||
+      typeof payload.nonce !== "string" ||
+      payload.nonce.length < 8
+    ) {
+      return false;
+    }
+
+    const now = Date.now();
+    // Expiry check
+    if (now - payload.ts > CSRF_TOKEN_EXPIRY_MS) return false;
+    // Future skew check (clock mismatch)
+    if (payload.ts - now > CSRF_TOKEN_FUTURE_SKEW_MS) return false;
+
+    const expectedSig = signCsrfToken(clientId, {
+      ts: payload.ts,
+      nonce: payload.nonce,
+    });
+
+    const providedSig = base64UrlDecode(sigB64);
+    if (providedSig.length !== expectedSig.length) return false;
+
+    return crypto.timingSafeEqual(providedSig, expectedSig);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Revoke a CSRF token (e.g., on logout or token refresh)
+ */
+export const revokeCsrfToken = (clientId: string): void => {
+  // Stateless CSRF tokens cannot be selectively revoked without shared state.
+  // If revocation is required, implement token blacklisting in a shared store
+  // (e.g., Redis) or rotate CSRF_SECRET.
+  void clientId;
+};
+
+/**
+ * Get the CSRF token header name
+ */
+export const getCsrfTokenHeader = (): string => {
+  return CSRF_TOKEN_HEADER;
+};
+
+export const getOriginFromReferer = (referer: unknown): string | null => {
+  if (typeof referer !== "string" || referer.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    const url = new URL(referer);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return null;
+    }
+
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return null;
+  }
+};