@aaqu/fromcubes-portal-react 0.1.0-alpha.21 → 0.1.0-alpha.23

package/nodes/lib/assets.js

@@ -1,8 +1,25 @@
+/** @module nodes/lib/assets */
+
 /**
  * Portal Assets — static file serving with security validation.
  *
- * Exports pure validation functions (for testing) and a registerAssets factory
- * that mounts Express routes on RED.httpAdmin / RED.httpNode.
+ * Exports pure validators (for unit-testing without RED) and a
+ * `registerAssets` factory that mounts Express routes on `RED.httpAdmin`
+ * (admin CRUD, auth-gated) and `RED.httpNode` (public read-only serving).
+ */
+
+/**
+ * @typedef {Object} AssetEntry
+ * @property {string} name             Relative path (POSIX, forward slashes).
+ * @property {"file"|"dir"} type
+ * @property {number} [size]           Bytes — file only.
+ * @property {number} [mtime]          fs.statSync.mtimeMs — file only.
+ */
+
+/**
+ * @typedef {Object} AssetsStats
+ * @property {number} size             Total bytes across all files (excluding symlinks).
+ * @property {number} count            Total file count.
  */
 
 const fs = require("fs");
@@ -18,6 +35,15 @@ const MAX_ASSETS_FILES = 1000;
 
 // ── Pure validators ───────────────────────────────────────────
 
+/**
+ * True when `s` is a single path segment safe to use under the assets root:
+ * non-empty string ≤255 chars, no Windows-illegal characters (`\:*?"<>|\0`),
+ * not a Windows reserved name (CON, PRN, …), no leading dot, no trailing
+ * `.` or space, and not the special `..` / `.` traversal markers.
+ *
+ * @param {*} s
+ * @returns {boolean}
+ */
 function isSafePathSegment(s) {
   return (
     typeof s === "string" &&
@@ -32,8 +58,35 @@ function isSafePathSegment(s) {
   );
 }
 
+// Combined relative-path cap. MAX_PATH_DEPTH=10 segments already constrains
+// fan-out; this bounds total characters so an attacker can't craft a 10-segment
+// path of 255-char names (~2.5 KB) that defeats higher-level URL length checks.
+const MAX_REL_PATH_LEN = 1024;
+
+/**
+ * Resolve a user-supplied relative path against `assetsDir`, applying every
+ * layer of path-traversal protection:
+ *
+ *  1. Non-empty string input.
+ *  2. Total length ≤ MAX_REL_PATH_LEN bytes.
+ *  3. Split on "/" and reject empty segments — `..`, `.`, `\0`, Windows
+ *     reserved names (CON/PRN/AUX/NUL/COM1-9/LPT1-9), invalid characters,
+ *     dotfiles, names ending in space/dot, length > 255 — see
+ *     `isSafePathSegment`.
+ *  4. Segment count ≤ MAX_PATH_DEPTH.
+ *  5. After `path.resolve`, the resulting absolute path must stay inside
+ *     `assetsDir + path.sep`.
+ *  6. If the path already exists on disk, `fs.realpathSync` must also stay
+ *     inside `assetsDir` — blocks symlink-escape attacks.
+ *
+ * @param {string} rel
+ * @param {string} assetsDir
+ * @returns {string|null}  Absolute resolved path, or null if any check fails.
+ */
 function safePath(rel, assetsDir) {
   if (!rel || typeof rel !== "string") return null;
+  if (rel.length > MAX_REL_PATH_LEN) return null;
+  if (rel.indexOf("\0") !== -1) return null;
   const segments = rel.split("/").filter(Boolean);
   if (segments.length === 0 || segments.length > MAX_PATH_DEPTH) return null;
   if (!segments.every(isSafePathSegment)) return null;
@@ -50,6 +103,15 @@ function safePath(rel, assetsDir) {
 
 // ── Filesystem helpers ────────────────────────────────────────
 
+/**
+ * Recursively list the contents of an assets directory. Symbolic links are
+ * skipped to defend against symlink-escape. Names are returned relative to
+ * the initial call (using `/` as separator).
+ *
+ * @param {string} dir       Absolute filesystem directory to scan.
+ * @param {string} [prefix]  Path prefix accumulated by recursion ("" at the root).
+ * @returns {Array<AssetEntry>}
+ */
 function scanDir(dir, prefix) {
   const results = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -66,6 +128,15 @@ function scanDir(dir, prefix) {
   return results;
 }
 
+/**
+ * Compute total file count and aggregate byte size under the assets root.
+ * Used to enforce the per-portal `MAX_ASSETS_BYTES` / `MAX_ASSETS_FILES`
+ * quotas before accepting an upload. Symbolic links are skipped. Filesystem
+ * errors (e.g. assets dir doesn't exist yet) yield `{size:0, count:0}`.
+ *
+ * @param {string} assetsDir
+ * @returns {{size: number, count: number}}
+ */
 function getAssetsStats(assetsDir) {
   let size = 0, count = 0;
   function walk(dir) {
@@ -82,9 +153,54 @@ function getAssetsStats(assetsDir) {
 
 // ── Route registration ────────────────────────────────────────
 
-function registerAssets(RED, express, assetsDir) {
+/**
+ * Resolve a `RED.auth.needsPermission(scope)` middleware, with a no-op fallback
+ * for runtimes (older Node-RED versions / test harnesses) where `RED.auth` is
+ * absent. Admin endpoints would otherwise be unprotected when an editor
+ * `adminAuth` is configured.
+ *
+ * @param {Object} RED
+ * @param {string} scope  Permission name, e.g. `"portal-react.write"`.
+ * @returns {Function}    Express middleware.
+ */
+function authMiddleware(RED, scope) {
+  if (RED.auth && typeof RED.auth.needsPermission === "function") {
+    return RED.auth.needsPermission(scope);
+  }
+  return function (_req, _res, next) { next(); };
+}
+
+/**
+ * Mount the Assets HTTP API on Node-RED's admin (write paths, auth-gated) and
+ * node (public read-only static) HTTP routers.
+ *
+ * @param {Object} RED                 Node-RED runtime object.
+ * @param {import('express')} express  Express factory (for json/raw/static).
+ * @param {string} assetsDir           Absolute filesystem path of the assets root.
+ * @param {Object} [opts]              Optional middleware hooks supplied by the
+ *                                     host module (CSRF, rate-limit) so the
+ *                                     same protections apply to assets POSTs.
+ * @param {Function} [opts.csrfGuard]
+ * @param {Function} [opts.rateLimit]
+ * @param {string}   [opts.jsonLimit]  Body-parser limit (default "1mb").
+ * @returns {void}
+ *
+ * @fires RED.log#info on first-time directory creation
+ *
+ * @example
+ *   const { registerAssets } = require("./lib/assets");
+ *   registerAssets(RED, require("express"), path.join(userDir, "fromcubes", "public"));
+ */
+function registerAssets(RED, express, assetsDir, opts) {
   fs.mkdirSync(assetsDir, { recursive: true });
 
+  const READ = authMiddleware(RED, "portal-react.read");
+  const WRITE = authMiddleware(RED, "portal-react.write");
+  const passthrough = (_req, _res, next) => next();
+  const csrfGuard = (opts && opts.csrfGuard) || passthrough;
+  const rateLimit = (opts && opts.rateLimit) || passthrough;
+  const jsonLimit = (opts && opts.jsonLimit) || "1mb";
+
   // Security middleware for public serving
   RED.httpNode.use(
     "/fromcubes/public",
@@ -97,20 +213,24 @@ function registerAssets(RED, express, assetsDir) {
       }
       next();
     },
-    express.static(assetsDir, { maxAge: "1d" }),
+    // dotfiles: 'deny' → never serve .git/, .htaccess, .env, etc. that may
+    // have been written into assetsDir by mistake. fallthrough: false makes
+    // express.static return 404 directly instead of leaking to the next mw.
+    express.static(assetsDir, { maxAge: "1d", dotfiles: "deny", fallthrough: false }),
   );
 
   // List assets
-  RED.httpAdmin.get("/portal-react/assets", (_req, res) => {
+  RED.httpAdmin.get("/portal-react/assets", READ, (_req, res) => {
     try {
       res.json(scanDir(assetsDir, ""));
     } catch (e) {
+      RED.log.error("portal-react assets list: " + e.message);
       res.json([]);
     }
   });
 
   // Create directory
-  RED.httpAdmin.post("/portal-react/assets/mkdir", express.json(), (req, res) => {
+  RED.httpAdmin.post("/portal-react/assets/mkdir", WRITE, csrfGuard, rateLimit, express.json({ limit: jsonLimit }), (req, res) => {
     const target = safePath(req.body && req.body.path, assetsDir);
     if (!target) return res.status(400).json({ error: "invalid path" });
     try {
@@ -123,7 +243,7 @@ function registerAssets(RED, express, assetsDir) {
   });
 
   // Move / rename
-  RED.httpAdmin.post("/portal-react/assets/move", express.json(), (req, res) => {
+  RED.httpAdmin.post("/portal-react/assets/move", WRITE, csrfGuard, rateLimit, express.json({ limit: jsonLimit }), (req, res) => {
     const from = safePath(req.body && req.body.from, assetsDir);
     const to = safePath(req.body && req.body.to, assetsDir);
     if (!from || !to) return res.status(400).json({ error: "invalid path" });
@@ -140,16 +260,25 @@ function registerAssets(RED, express, assetsDir) {
     }
   });
 
-  // Upload
+  // Upload — 100mb cap is intentionally higher than json/text endpoints.
   RED.httpAdmin.post(
     "/portal-react/assets/upload/*",
+    WRITE,
+    csrfGuard,
+    rateLimit,
     express.raw({ type: "*/*", limit: "100mb" }),
     (req, res) => {
       const rel = req.params[0];
       const target = safePath(rel, assetsDir);
       if (!target) return res.status(400).json({ error: "invalid path" });
+      // Guard: when nothing was uploaded (Content-Length 0 or wrong type),
+      // express.raw yields an empty {} object instead of a Buffer.
+      const bodyLen = Buffer.isBuffer(req.body) ? req.body.length : 0;
+      if (bodyLen === 0) {
+        return res.status(400).json({ error: "empty upload" });
+      }
       const stats = getAssetsStats(assetsDir);
-      if (stats.size + req.body.length > MAX_ASSETS_BYTES)
+      if (stats.size + bodyLen > MAX_ASSETS_BYTES)
         return res.status(413).json({ error: "storage limit exceeded (500MB)" });
       if (stats.count >= MAX_ASSETS_FILES)
         return res.status(413).json({ error: "file count limit exceeded (1000)" });
@@ -165,7 +294,7 @@ function registerAssets(RED, express, assetsDir) {
   );
 
   // Delete
-  RED.httpAdmin.delete("/portal-react/assets/*", (req, res) => {
+  RED.httpAdmin.delete("/portal-react/assets/*", WRITE, csrfGuard, rateLimit, (req, res) => {
     const rel = req.params[0];
     const target = safePath(rel, assetsDir);
     if (!target) return res.status(400).json({ error: "invalid path" });
@@ -179,7 +308,7 @@ function registerAssets(RED, express, assetsDir) {
   });
 
   // Download
-  RED.httpAdmin.get("/portal-react/assets/download/*", (req, res) => {
+  RED.httpAdmin.get("/portal-react/assets/download/*", READ, (req, res) => {
     const rel = req.params[0];
     const target = safePath(rel, assetsDir);
     if (!target) return res.status(400).json({ error: "invalid path" });
@@ -202,6 +331,7 @@ module.exports = {
   UNSAFE_EXTS,
   RESERVED_NAMES,
   MAX_PATH_DEPTH,
+  MAX_REL_PATH_LEN,
   MAX_ASSETS_BYTES,
   MAX_ASSETS_FILES,
   isSafePathSegment,