fix: XSS escaping, DRY utils, agent undo batch, graceful shutdown

- Escape meta.licence in published HTML to prevent XSS
- Extract shared sanitizeName/docPath/DATA_DIR into utils.ts (DRY)
- Disable WS debug logging in production
- Fix startup log message (was /collab/:doc, now /collab)
- Remove unused NextFunction import in auth.ts
- Remove duplicate JSDoc in publisher/index.ts
- Add timeout to graceful shutdown (SIGTERM/SIGINT)
- Fix agent undo batch: close batch on stream finish (onFinish)
- Fix replaceSelection: return error when no text selected

Made-with: Cursor

backend/src/auth.ts

@@ -1,6 +1,6 @@
 import { whoAmI, type WhoAmIUser } from "@huggingface/hub";
 import { randomBytes } from "crypto";
-import type { Request, Response, NextFunction } from "express";
+import type { Request, Response } from "express";
 
 export interface AuthUser {
   name: string;

backend/src/hf-storage.ts

@@ -1,4 +1,5 @@
 import { uploadFile, downloadFile, createRepo, commit, type CommitFile, type RepoDesignation } from "@huggingface/hub";
+import { sanitizeName } from "./utils.js";
 
 const SPACE_ID = process.env.SPACE_ID || "";
 
@@ -57,10 +58,6 @@ export async function ensureDatasetExists(token?: string): Promise<void> {
   _datasetReady = true;
 }
 
-function sanitizeName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_-]/g, "_");
-}
-
 // ---------- Images ----------
 
 export async function uploadImageToHf(

backend/src/publisher/html-renderer.ts

@@ -992,7 +992,7 @@ function renderFooter(meta: PublishMeta): string {
     sections += `
     <section class="reuse-block">
       <p class="footer-heading" role="heading" aria-level="2">Reuse</p>
-      <p>${meta.licence}</p>
+      <p>${escapeHtml(meta.licence)}</p>
     </section>`;
   }
 

backend/src/publisher/index.ts

@@ -8,6 +8,7 @@ import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import * as Y from "yjs";
+import { DATA_DIR as SHARED_DATA_DIR, docPath } from "../utils.js";
 import { TiptapTransformer } from "@hocuspocus/transformer";
 import { renderArticleHTML, type PublishMeta } from "./html-renderer.js";
 import { getServerExtensions } from "./extensions.js";
@@ -19,11 +20,7 @@ import {
 } from "../hf-storage.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DATA_DIR = join(__dirname, "..", "..", "data");
-
-function docPath(name: string) {
-  return join(DATA_DIR, `${name.replace(/[^a-zA-Z0-9_-]/g, "_")}.yjs`);
-}
+const DATA_DIR = SHARED_DATA_DIR;
 
 export interface PublishCSS {
   variables: string;
@@ -36,11 +33,6 @@ export interface PublishCSS {
   components: string;
 }
 
-/**
- * Load CSS files for injection into the published HTML.
- * Reads the template CSS foundation + editor extensions.
- * Tries multiple paths: dev source, Docker copy, relative fallback.
- */
 /**
  * Resolve @custom-media at-rules so the CSS works in browsers.
  * PostCSS handles this in the Vite build, but the publisher reads raw source files.

backend/src/server.ts

@@ -5,8 +5,7 @@ import { WebSocketServer } from "ws";
 import { Hocuspocus } from "@hocuspocus/server";
 import { Database } from "@hocuspocus/extension-database";
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
 import { randomUUID } from "crypto";
 import multer from "multer";
 import * as Y from "yjs";
@@ -25,9 +24,8 @@ import {
 } from "./hf-storage.js";
 import { resolveUser, extractToken, isOAuthEnabled, handleOAuthAuthorize, handleOAuthCallback } from "./auth.js";
 import { publishDocument } from "./publisher/index.js";
+import { DATA_DIR, docPath, sanitizeName } from "./utils.js";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const DATA_DIR = join(__dirname, "..", "data");
 const PORT = parseInt(process.env.PORT || "8080", 10);
 
 /** Single collab document; URL `?doc=` is not supported. */
@@ -45,7 +43,7 @@ async function ensurePublishedRestored(token?: string): Promise<void> {
   if (_publishedRestored) return;
   if (!getDatasetId()) return;
 
-  const publishedPath = join(DATA_DIR, "published", DEFAULT_DOC_NAME.replace(/[^a-zA-Z0-9_-]/g, "_"), "index.html");
+  const publishedPath = join(DATA_DIR, "published", sanitizeName(DEFAULT_DOC_NAME), "index.html");
   if (existsSync(publishedPath)) {
     _publishedRestored = true;
     return;
@@ -78,10 +76,6 @@ async function ensurePublishedRestored(token?: string): Promise<void> {
 
 mkdirSync(DATA_DIR, { recursive: true });
 
-function docPath(name: string) {
-  return join(DATA_DIR, `${name.replace(/[^a-zA-Z0-9_-]/g, "_")}.yjs`);
-}
-
 if (isHfStorageEnabled()) {
   console.log("[server] HF Dataset persistence enabled");
 } else if (getDatasetId()) {
@@ -205,10 +199,12 @@ httpServer.on("upgrade", (req, socket, head) => {
       ws.on("error", (error) => {
         console.error("[ws] socket error:", error.message);
       });
-      ws.on("message", (data: Buffer, isBinary: boolean) => {
-        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data as any);
-        console.log(`[ws-debug] msg ${buf.length}B binary=${isBinary} first20=${buf.slice(0, 20).toString("hex")}`);
-      });
+      if (process.env.NODE_ENV !== "production") {
+        ws.on("message", (data: Buffer, isBinary: boolean) => {
+          const buf = Buffer.isBuffer(data) ? data : Buffer.from(data as any);
+          console.log(`[ws-debug] msg ${buf.length}B binary=${isBinary} first20=${buf.slice(0, 20).toString("hex")}`);
+        });
+      }
       const token = extractToken(req.headers.cookie);
       hocuspocus.handleConnection(ws, req, { token });
     });
@@ -454,22 +450,25 @@ if (existsSync(staticDir)) {
 
 const server = httpServer.listen(PORT, async () => {
   console.log(`[server] running on http://localhost:${PORT}`);
-  console.log(`[server] collab websocket at ws://localhost:${PORT}/collab/:doc`);
+  console.log(`[server] collab websocket at ws://localhost:${PORT}/collab`);
   console.log(`[server] SPACE_ID=${process.env.SPACE_ID || "(not set)"} HF_DATASET_ID=${getDatasetId() || "(empty)"} HF_TOKEN=${process.env.HF_TOKEN ? "set" : "not set"}`);
 
   // Eager restore: dataset is public, works without token
   await ensurePublishedRestored();
 });
 
-// Graceful shutdown: flush pending docs to HF
-process.on("SIGTERM", async () => {
-  console.log("[server] shutting down, flushing to HF...");
+async function gracefulShutdown(signal: string) {
+  console.log(`[server] ${signal} received, flushing to HF...`);
   await flushAll();
-  server.close();
-});
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+    setTimeout(() => {
+      console.warn("[server] force-closing after timeout");
+      resolve();
+    }, 5000);
+  });
+  process.exit(0);
+}
 
-process.on("SIGINT", async () => {
-  console.log("[server] shutting down, flushing to HF...");
-  await flushAll();
-  server.close();
-});
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));

backend/src/utils.ts

@@ -0,0 +1,14 @@
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const DATA_DIR = join(__dirname, "..", "data");
+
+export function sanitizeName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+export function docPath(name: string): string {
+  return join(DATA_DIR, `${sanitizeName(name)}.yjs`);
+}

frontend/src/hooks/useAgentChat.ts

@@ -205,13 +205,14 @@ export function useAgentChat({ editor, undoManager, frontmatterStore }: UseAgent
               .insertContent(newText)
               .run();
             pendingSelectionRef.current = null;
-          } else {
-            const { from, to } = editor.state.selection;
-            if (from !== to) {
-              editor.chain().focus().insertContent(newText).run();
-            }
+            return "Selection replaced successfully";
           }
-          return "Selection replaced successfully";
+          const { from, to } = editor.state.selection;
+          if (from !== to) {
+            editor.chain().focus().insertContent(newText).run();
+            return "Selection replaced successfully";
+          }
+          return "No text selected to replace";
         }
 
         case "insertAtCursor": {
@@ -271,6 +272,10 @@ export function useAgentChat({ editor, undoManager, frontmatterStore }: UseAgent
       });
     },
 
+    onFinish() {
+      endAgentBatch();
+    },
+
     onError(error) {
       console.error("[agent] chat error:", error);
       endAgentBatch();