@aaqu/fromcubes-portal-react 0.1.0-alpha.3 → 0.1.0-alpha.30

package/examples/WebGPU Shader.json

@@ -0,0 +1,110 @@
+[
+    {
+        "id": "fc-webgpu-flow",
+        "type": "tab",
+        "label": "WebGPU TSL Demo",
+        "disabled": false
+    },
+    {
+        "id": "8098c4fd7a54a6b0",
+        "type": "comment",
+        "z": "fc-webgpu-flow",
+        "name": "WebGPU TSL Shader Demo",
+        "info": "WebGPU-backed Three.js scene using the TSL (Three Shading Language) node graph API.\n\n## What it demonstrates\nModern `three` WebGPU renderer + TSL. Demonstrates that the bundler tolerates importing the\n`three/webgpu` subpath and that TSL helpers (`time`, `Fn`, …) work in user JSX.\n\n## How to run\n1. Import this flow, deploy (auto-installs `three`).\n2. Open `http://<host>:1880/fromcubes/webgpu` in a WebGPU-capable browser (Chrome ≥113, Safari ≥18).\n\n## Expected result\nAnimated shader effect. Browsers without WebGPU fall back to an error message in the canvas.",
+        "x": 160,
+        "y": 60,
+        "wires": []
+    },
+    {
+        "id": "fc-webgpu-comp-canvas",
+        "type": "fc-portal-component",
+        "z": "fc-webgpu-flow",
+        "compName": "TSLCanvas",
+        "compCode": "import { AmbientLight, Color, Mesh, MeshStandardNodeMaterial, PerspectiveCamera, PointLight, Scene, Timer, TorusKnotGeometry, WebGPURenderer } from 'three/webgpu';\nimport { uniform, sin, cos, time, uv, vec3, mix, float, positionLocal, normalLocal } from 'three/tsl';\n\nfunction TSLCanvas({ params }) {\n  const mountRef = useRef(null);\n  const stateRef = useRef(null);\n\n  useEffect(() => {\n    const el = mountRef.current;\n    const w = el.clientWidth;\n    const h = el.clientHeight;\n\n    const scene = new Scene();\n    const camera = new PerspectiveCamera(50, w / h, 0.1, 100);\n    camera.position.z = 4;\n\n    const renderer = new WebGPURenderer({ antialias: true });\n    renderer.setSize(w, h);\n    renderer.setPixelRatio(window.devicePixelRatio);\n    el.appendChild(renderer.domElement);\n\n    scene.add(new AmbientLight(0xffffff, 0.5));\n    const point = new PointLight(0xffffff, 1.5, 100);\n    point.position.set(5, 5, 5);\n    scene.add(point);\n\n    const colorAU = uniform(new Color(0x22d3ee));\n    const colorBU = uniform(new Color(0xa78bfa));\n\n    const t = time;\n    const uvNode = uv();\n    const wave = sin(uvNode.x.mul(6.28).add(t)).mul(0.5).add(0.5);\n    const pulse = cos(t.mul(0.7)).mul(0.5).add(0.5);\n    const blend = mix(vec3(colorAU), vec3(colorBU), wave.mul(pulse));\n\n    const mat = new MeshStandardNodeMaterial();\n    mat.colorNode = blend;\n    mat.roughnessNode = float(0.3);\n    mat.metalnessNode = float(0.7);\n\n    const displaceAmount = sin(positionLocal.y.mul(4.0).add(t)).mul(0.08);\n    mat.positionNode = positionLocal.add(normalLocal.mul(displaceAmount));\n\n    const geo = new TorusKnotGeometry(1, 0.35, 128, 32);\n    const mesh = new Mesh(geo, mat);\n    scene.add(mesh);\n\n    const targetA = new Color(0x22d3ee);\n    const targetB = new Color(0xa78bfa);\n    const st = { mesh, scene, camera, renderer, colorAU, colorBU, targetA, targetB };\n    stateRef.current = st;\n\n    let raf;\n    const timer = new Timer();\n    function animate() {\n      raf = requestAnimationFrame(animate);\n      timer.update();\n      const dt = timer.getDelta();\n      mesh.rotation.x += 0.3 * dt;\n      mesh.rotation.y += 0.6 * dt;\n      st.colorAU.value.lerp(st.targetA, Math.min(1, 2.5 * dt));\n      st.colorBU.value.lerp(st.targetB, Math.min(1, 2.5 * dt));\n      renderer.render(scene, camera);\n    }\n\n    renderer.init().then(() => animate());\n\n    const onResize = () => {\n      const w2 = el.clientWidth;\n      const h2 = el.clientHeight;\n      camera.aspect = w2 / h2;\n      camera.updateProjectionMatrix();\n      renderer.setSize(w2, h2);\n    };\n    window.addEventListener('resize', onResize);\n\n    return () => {\n      cancelAnimationFrame(raf);\n      window.removeEventListener('resize', onResize);\n      renderer.dispose();\n      geo.dispose();\n      mat.dispose();\n      el.removeChild(renderer.domElement);\n    };\n  }, []);\n\n  useEffect(() => {\n    const s = stateRef.current;\n    if (!s) return;\n    s.targetA.set(params.colorA);\n    s.targetB.set(params.colorB);\n  }, [params.colorA, params.colorB]);\n\n  return <div ref={mountRef} className=\"flex-1\" />;\n}",
+        "x": 160,
+        "y": 300,
+        "wires": []
+    },
+    {
+        "id": "fc-webgpu-comp-statusbar",
+        "type": "fc-portal-component",
+        "z": "fc-webgpu-flow",
+        "compName": "TSLStatusBar",
+        "compCode": "function TSLStatusBar({ params }) {\n  return (\n    <div className=\"px-6 py-4 bg-zinc-900/50 border-t border-zinc-800/50 flex items-center gap-6 flex-wrap\">\n      <Stat label=\"Color A\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{backgroundColor: params.colorA}} />\n      </Stat>\n      <Stat label=\"Color B\">\n        <span className=\"w-4 h-4 rounded-full border border-zinc-700\" style={{backgroundColor: params.colorB}} />\n      </Stat>\n      <Stat label=\"Backend\">\n        <span className=\"text-xs font-mono px-2 py-0.5 rounded bg-violet-500/20 text-violet-300\">WebGPU / TSL</span>\n      </Stat>\n    </div>\n  );\n}",
+        "x": 360,
+        "y": 300,
+        "wires": []
+    },
+    {
+        "id": "fc-webgpu-inject",
+        "type": "inject",
+        "z": "fc-webgpu-flow",
+        "name": "Tick",
+        "props": [
+            {
+                "p": "payload"
+            }
+        ],
+        "repeat": "3",
+        "payload": "{}",
+        "payloadType": "json",
+        "x": 160,
+        "y": 160,
+        "wires": [
+            [
+                "fc-webgpu-func"
+            ]
+        ]
+    },
+    {
+        "id": "fc-webgpu-func",
+        "type": "function",
+        "z": "fc-webgpu-flow",
+        "name": "Random TSL params",
+        "func": "const pairs = [\n  ['#22d3ee','#a78bfa'],\n  ['#a78bfa','#f97316'],\n  ['#34d399','#e879f9'],\n  ['#f97316','#60a5fa'],\n  ['#f87171','#34d399'],\n  ['#e879f9','#22d3ee'],\n  ['#fbbf24','#f87171']\n];\nconst p = pairs[Math.floor(Math.random() * pairs.length)];\nmsg.payload = { colorA: p[0], colorB: p[1] };\nreturn msg;",
+        "outputs": 1,
+        "x": 360,
+        "y": 160,
+        "wires": [
+            [
+                "fc-webgpu-portal"
+            ]
+        ]
+    },
+    {
+        "id": "fc-webgpu-portal",
+        "type": "portal-react",
+        "z": "fc-webgpu-flow",
+        "name": "WebGPU Portal",
+        "subPath": "webgpu",
+        "pageTitle": "fromcubes WebGPU",
+        "customHead": "",
+        "portalAuth": false,
+        "showWsStatus": false,
+        "libs": [
+            {
+                "module": "three",
+                "var": "THREE"
+            }
+        ],
+        "componentCode": "function App() {\n  const { data } = useNodeRed();\n  const params = data || { colorA: '#22d3ee', colorB: '#a78bfa' };\n\n  return (\n    <Page>\n      <Header title=\"fromcubes WebGPU\" subtitle=\"Three.js TSL + live Node-RED data\" />\n      <TSLCanvas params={params} />\n      <TSLStatusBar params={params} />\n    </Page>\n  );\n}",
+        "x": 560,
+        "y": 160,
+        "wires": [
+            [
+                "fc-webgpu-debug"
+            ]
+        ]
+    },
+    {
+        "id": "fc-webgpu-debug",
+        "type": "debug",
+        "z": "fc-webgpu-flow",
+        "name": "WebGPU output",
+        "active": true,
+        "tosidebar": true,
+        "x": 750,
+        "y": 160,
+        "wires": []
+    }
+]

package/nodes/lib/admin-api.js

@@ -0,0 +1,160 @@
+const path = require("path");
+
+/**
+ * Register editor/admin/public support routes for portal-react.
+ *
+ * This module intentionally owns only HTTP route registration. Runtime page
+ * state and registries remain owned by portal-react.js and are passed in so
+ * deploy/rebuild lifecycle stays in one place.
+ *
+ * @param {Object} RED
+ * @param {Object} deps
+ * @param {import("express")} deps.express
+ * @param {Function} deps.permRead
+ * @param {Function} deps.permWrite
+ * @param {Function} deps.csrfGuard
+ * @param {Function} deps.rateLimit
+ * @param {string} deps.jsonBodyLimit
+ * @param {string} deps.userDir
+ * @param {Object<string, Object>} deps.pageState
+ * @param {Object<string, Object>} deps.registry
+ * @param {Object<string, Object>} deps.utilities
+ * @param {(code: string) => Set<string>} deps.extractUtilitySymbols
+ * @returns {void}
+ */
+function registerAdminApi(RED, deps) {
+  const {
+    express,
+    permRead,
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    jsonBodyLimit,
+    userDir,
+    pageState,
+    registry,
+    utilities,
+    extractUtilitySymbols,
+  } = deps;
+
+  const monacoPath = path.dirname(
+    require.resolve("monaco-editor/package.json"),
+  );
+  RED.httpAdmin.use(
+    "/portal-react/vs",
+    permRead,
+    express.static(path.join(monacoPath, "min", "vs")),
+  );
+
+  const { generateCandidates } = require("../tw-candidates");
+  let twClassesCache = null;
+  RED.httpAdmin.get("/portal-react/tw-classes", permRead, (_req, res) => {
+    if (!twClassesCache) {
+      twClassesCache = generateCandidates();
+    }
+    res.json(twClassesCache);
+  });
+
+  const CSS_HASH_RE = /^[a-f0-9]{1,64}$/;
+  function findCssByHash(reqHash) {
+    for (const ep in pageState) {
+      if (pageState[ep]?.cssHash === reqHash) return pageState[ep].css;
+    }
+    return null;
+  }
+  function serveCss(req, res) {
+    const reqHash = req.params.hash;
+    if (!CSS_HASH_RE.test(reqHash)) {
+      res.status(400).send("Bad request");
+      return;
+    }
+    const css = findCssByHash(reqHash);
+    if (!css) {
+      res.status(404).send("Not found");
+      return;
+    }
+    res.set({
+      "Content-Type": "text/css",
+      "Cache-Control": "public, max-age=31536000, immutable",
+    });
+    res.send(css);
+  }
+
+  RED.httpNode.get("/fromcubes/css/:hash.css", serveCss);
+  RED.httpAdmin.get("/portal-react/css/:hash.css", serveCss);
+
+  const { registerAssets } = require("./assets");
+  registerAssets(RED, express, path.join(userDir, "fromcubes", "public"), {
+    csrfGuard,
+    rateLimit,
+    jsonLimit: jsonBodyLimit,
+  });
+
+  RED.httpAdmin.get("/portal-react/registry", permRead, (_req, res) => {
+    res.json(registry);
+  });
+
+  RED.httpAdmin.post(
+    "/portal-react/registry",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    express.json({ limit: jsonBodyLimit }),
+    (_req, res) => {
+      res.status(410).json({
+        error: "registry writes are deprecated; use fc-portal-component nodes",
+      });
+    },
+  );
+
+  RED.httpAdmin.delete(
+    "/portal-react/registry/:name",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    (_req, res) => {
+      res.status(410).json({
+        error: "registry writes are deprecated; use fc-portal-component nodes",
+      });
+    },
+  );
+
+  RED.httpAdmin.get("/portal-react/utilities", permRead, (_req, res) => {
+    const out = {};
+    for (const [name, u] of Object.entries(utilities)) {
+      out[name] = {
+        code: u.code,
+        error: u.error || null,
+        symbols: [...extractUtilitySymbols(u.code || "")],
+      };
+    }
+    res.json(out);
+  });
+
+  RED.httpAdmin.post(
+    "/portal-react/utilities",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    express.json({ limit: jsonBodyLimit }),
+    (_req, res) => {
+      res.status(410).json({
+        error: "utility writes are deprecated; use fc-portal-utility nodes",
+      });
+    },
+  );
+
+  RED.httpAdmin.delete(
+    "/portal-react/utilities/:name",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    (_req, res) => {
+      res.status(410).json({
+        error: "utility writes are deprecated; use fc-portal-utility nodes",
+      });
+    },
+  );
+}
+
+module.exports = { registerAdminApi };

package/nodes/lib/assets.js

@@ -0,0 +1,342 @@
+/** @module nodes/lib/assets */
+
+/**
+ * Portal Assets — static file serving with security validation.
+ *
+ * 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");
+const path = require("path");
+
+// ── Constants ─────────────────────────────────────────────────
+
+const UNSAFE_EXTS = new Set([".html", ".htm", ".svg", ".js", ".mjs", ".xml", ".xhtml"]);
+const RESERVED_NAMES = /^(CON|PRN|AUX|NUL|COM\d|LPT\d)(\.|$)/i;
+const MAX_PATH_DEPTH = 10;
+const MAX_ASSETS_BYTES = 500 * 1024 * 1024; // 500 MB total
+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" &&
+    s.length > 0 &&
+    s.length <= 255 &&
+    !/[\\:*?"<>|\0]/.test(s) &&
+    !s.startsWith(".") &&
+    !s.endsWith(".") &&
+    !s.endsWith(" ") &&
+    s !== ".." &&
+    !RESERVED_NAMES.test(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;
+  const resolved = path.resolve(assetsDir, ...segments);
+  if (!resolved.startsWith(assetsDir + path.sep) && resolved !== assetsDir)
+    return null;
+  try {
+    const real = fs.realpathSync(resolved);
+    if (!real.startsWith(assetsDir + path.sep) && real !== assetsDir)
+      return null;
+  } catch (_e) { /* path doesn't exist yet — OK for mkdir/upload */ }
+  return resolved;
+}
+
+// ── 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 })) {
+    if (entry.isSymbolicLink()) continue;
+    const rel = prefix ? prefix + "/" + entry.name : entry.name;
+    if (entry.isDirectory()) {
+      results.push({ name: rel, type: "dir" });
+      results.push(...scanDir(path.join(dir, entry.name), rel));
+    } else if (entry.isFile()) {
+      const stat = fs.statSync(path.join(dir, entry.name));
+      results.push({ name: rel, type: "file", size: stat.size, mtime: stat.mtimeMs });
+    }
+  }
+  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) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isSymbolicLink()) continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile()) { size += fs.statSync(p).size; count++; }
+    }
+  }
+  try { walk(assetsDir); } catch (_e) { /* ignore */ }
+  return { size, count };
+}
+
+// ── Route registration ────────────────────────────────────────
+
+/**
+ * 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",
+    (req, res, next) => {
+      res.set("X-Content-Type-Options", "nosniff");
+      res.set("Content-Security-Policy", "default-src 'none'");
+      const ext = path.extname(req.path).toLowerCase();
+      if (UNSAFE_EXTS.has(ext)) {
+        res.set("Content-Disposition", "attachment");
+      }
+      next();
+    },
+    // 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", 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", 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 {
+      fs.mkdirSync(target, { recursive: true });
+      res.json({ ok: true });
+    } catch (e) {
+      RED.log.error("portal-react assets mkdir: " + e.message);
+      res.status(500).json({ error: "internal error" });
+    }
+  });
+
+  // Move / rename
+  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" });
+    const toName = path.basename(to);
+    if (!toName || !toName.trim()) return res.status(400).json({ error: "name cannot be empty" });
+    try {
+      const toDir = path.dirname(to);
+      fs.mkdirSync(toDir, { recursive: true });
+      fs.renameSync(from, to);
+      res.json({ ok: true });
+    } catch (e) {
+      RED.log.error("portal-react assets move: " + e.message);
+      res.status(500).json({ error: "internal error" });
+    }
+  });
+
+  // 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 + 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)" });
+      try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, req.body);
+        res.json({ ok: true });
+      } catch (e) {
+        RED.log.error("portal-react assets upload: " + e.message);
+        res.status(500).json({ error: "internal error" });
+      }
+    },
+  );
+
+  // Delete
+  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" });
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      res.json({ ok: true });
+    } catch (e) {
+      RED.log.error("portal-react assets delete: " + e.message);
+      res.status(404).json({ error: "not found" });
+    }
+  });
+
+  // Download
+  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" });
+    try {
+      const stat = fs.statSync(target);
+      if (stat.isDirectory()) return res.status(400).json({ error: "is a directory" });
+      const filename = path.basename(target);
+      res.set({
+        "Content-Disposition": 'attachment; filename="' + filename.replace(/"/g, '\\"') + '"',
+        "Content-Length": stat.size,
+      });
+      fs.createReadStream(target).pipe(res);
+    } catch (e) {
+      res.status(404).json({ error: "not found" });
+    }
+  });
+}
+
+module.exports = {
+  UNSAFE_EXTS,
+  RESERVED_NAMES,
+  MAX_PATH_DEPTH,
+  MAX_REL_PATH_LEN,
+  MAX_ASSETS_BYTES,
+  MAX_ASSETS_FILES,
+  isSafePathSegment,
+  safePath,
+  scanDir,
+  getAssetsStats,
+  registerAssets,
+};