@aaqu/fromcubes-react 0.0.0-stage → 0.1.0

package/nodes/icons/fromcubes-component.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="44" height="60" viewBox="0 0 44 60">
+  <!-- The fromcubes mark, traced from the project artwork by tools/build-icon.mjs.
+       The badge is cut out of the mark with a mask rather than hidden behind a
+       halo painted in the background colour: an icon cannot know what is behind
+       it, and masking keeps the traced edges exact instead of re-rasterising them.
+       The badge is the "component" icon from Lucide (https://lucide.dev), ISC —
+       see THIRD-PARTY-NOTICES.md. Worn by fc-portal-component. React's own logo is a
+       Meta trademark and is deliberately not used. -->
+  <mask id="fc-cut" maskUnits="userSpaceOnUse" x="0" y="0" width="44" height="60">
+    <rect width="44" height="60" fill="#ffffff"/>
+    <g transform="translate(25.216003874368653 34.26600387436865) scale(0.7903)" fill="none" stroke="#000000"
+     stroke-width="6.83" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M15.536 11.293a1 1 0 0 0 0 1.414l2.376 2.377a1 1 0 0 0 1.414 0l2.377-2.377a1 1 0 0 0 0-1.414l-2.377-2.377a1 1 0 0 0-1.414 0z"/>
+    <path d="M2.297 11.293a1 1 0 0 0 0 1.414l2.377 2.377a1 1 0 0 0 1.414 0l2.377-2.377a1 1 0 0 0 0-1.414L6.088 8.916a1 1 0 0 0-1.414 0z"/>
+    <path d="M8.916 17.912a1 1 0 0 0 0 1.415l2.377 2.376a1 1 0 0 0 1.414 0l2.377-2.376a1 1 0 0 0 0-1.415l-2.377-2.376a1 1 0 0 0-1.414 0z"/>
+    <path d="M8.916 4.674a1 1 0 0 0 0 1.414l2.377 2.376a1 1 0 0 0 1.414 0l2.377-2.376a1 1 0 0 0 0-1.414l-2.377-2.377a1 1 0 0 0-1.414 0z"/>
+    </g>
+  </mask>
+  <path fill="#10181d" fill-rule="evenodd" mask="url(#fc-cut)" d="M20.79 6.25L22.01 6.25L23.23 6.86L32.17 12.34L37.65 15.19L38.46 16.00L38.46 35.50L37.65 36.31L32.17 39.16L23.23 44.64L22.01 45.25L20.38 45.05L12.06 39.97L6.57 37.13L4.34 35.50L4.34 16.00L9.42 12.75L20.79 6.45ZM21.20 8.08L6.98 16.20L7.18 16.61L7.99 16.61L10.84 14.78L14.29 13.97L15.92 13.97L22.42 17.63L24.65 19.05L24.85 20.67L24.04 21.48L23.43 22.91L20.99 24.13L21.20 24.73L35.82 16.41L35.01 16.00L31.96 18.03L27.09 18.84L20.59 15.19L19.37 14.17L18.15 13.77L17.95 12.14L19.57 9.70L22.01 8.48L21.40 8.08ZM23.63 9.50L20.99 10.92L19.98 12.75L27.49 17.02L30.95 16.41L33.38 14.78L23.84 9.50ZM14.49 15.80L11.45 16.41L9.42 17.83L15.71 21.28L16.93 22.30L18.56 22.91L18.76 23.31L22.21 21.48L22.82 20.06L17.13 16.61L15.51 15.80L14.70 15.80ZM6.17 18.03L5.96 18.84L9.21 20.47L12.46 24.13L12.67 34.69L11.85 35.50L8.81 35.50L6.57 34.08L5.96 34.08L5.96 34.69L9.62 36.52L20.38 43.02L20.38 41.80L17.34 40.38L14.29 37.13L13.88 26.16L14.70 25.34L17.95 25.34L20.18 26.77L20.59 26.77L20.59 26.16L6.37 18.03ZM36.63 18.03L35.82 18.44L35.82 22.70L34.40 26.77L26.07 31.84L25.06 32.05L24.04 31.64L22.82 29.41L22.62 26.16L22.21 26.36L22.21 42.81L23.02 42.61L22.82 38.95L24.24 34.48L33.18 29.00L34.81 29.61L36.02 31.84L36.02 34.89L36.84 34.69L36.84 18.03ZM33.99 19.45L24.45 24.94L24.65 29.00L25.06 29.81L25.67 30.02L27.49 28.59L32.98 25.55L33.99 22.50L33.99 19.66ZM6.17 20.88L5.96 31.84L8.81 33.27L9.01 33.67L10.84 33.67L10.63 24.53L8.81 22.91L8.40 22.09L6.17 21.08ZM15.92 27.17L15.92 36.11L18.56 38.95L20.38 39.97L20.59 29.00L17.54 27.17L16.12 27.17ZM33.18 31.23L25.67 35.70L24.65 38.95L24.65 41.59L34.20 36.11L34.20 32.25L33.38 31.23Z"/>
+  <g transform="translate(25.216003874368653 34.26600387436865) scale(0.7903)" fill="none" stroke="#0f6f8c"
+     stroke-width="3.04" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M15.536 11.293a1 1 0 0 0 0 1.414l2.376 2.377a1 1 0 0 0 1.414 0l2.377-2.377a1 1 0 0 0 0-1.414l-2.377-2.377a1 1 0 0 0-1.414 0z"/>
+    <path d="M2.297 11.293a1 1 0 0 0 0 1.414l2.377 2.377a1 1 0 0 0 1.414 0l2.377-2.377a1 1 0 0 0 0-1.414L6.088 8.916a1 1 0 0 0-1.414 0z"/>
+    <path d="M8.916 17.912a1 1 0 0 0 0 1.415l2.377 2.376a1 1 0 0 0 1.414 0l2.377-2.376a1 1 0 0 0 0-1.415l-2.377-2.376a1 1 0 0 0-1.414 0z"/>
+    <path d="M8.916 4.674a1 1 0 0 0 0 1.414l2.377 2.376a1 1 0 0 0 1.414 0l2.377-2.376a1 1 0 0 0 0-1.414l-2.377-2.377a1 1 0 0 0-1.414 0z"/>
+  </g>
+</svg>

package/nodes/icons/fromcubes-react.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="44" height="60" viewBox="0 0 44 60">
+  <!-- The fromcubes mark, traced from the project artwork by tools/build-icon.mjs.
+       The badge is cut out of the mark with a mask rather than hidden behind a
+       halo painted in the background colour: an icon cannot know what is behind
+       it, and masking keeps the traced edges exact instead of re-rasterising them.
+       The badge is the "atom" icon from Lucide (https://lucide.dev), ISC —
+       see THIRD-PARTY-NOTICES.md. Worn by portal-react. React's own logo is a
+       Meta trademark and is deliberately not used. -->
+  <mask id="fc-cut" maskUnits="userSpaceOnUse" x="0" y="0" width="44" height="60">
+    <rect width="44" height="60" fill="#ffffff"/>
+    <g transform="translate(24.158614219195222 33.20861421919522) scale(0.8784)" fill="none" stroke="#000000"
+     stroke-width="6.15" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="1"/>
+    <path d="M20.2 20.2c2.04-2.03.02-7.36-4.5-11.9-4.54-4.52-9.87-6.54-11.9-4.5-2.04 2.03-.02 7.36 4.5 11.9 4.54 4.52 9.87 6.54 11.9 4.5Z"/>
+    <path d="M15.7 15.7c4.52-4.54 6.54-9.87 4.5-11.9-2.03-2.04-7.36-.02-11.9 4.5-4.52 4.54-6.54 9.87-4.5 11.9 2.03 2.04 7.36.02 11.9-4.5Z"/>
+    </g>
+  </mask>
+  <path fill="#10181d" fill-rule="evenodd" mask="url(#fc-cut)" d="M20.79 6.25L22.01 6.25L23.23 6.86L32.17 12.34L37.65 15.19L38.46 16.00L38.46 35.50L37.65 36.31L32.17 39.16L23.23 44.64L22.01 45.25L20.38 45.05L12.06 39.97L6.57 37.13L4.34 35.50L4.34 16.00L9.42 12.75L20.79 6.45ZM21.20 8.08L6.98 16.20L7.18 16.61L7.99 16.61L10.84 14.78L14.29 13.97L15.92 13.97L22.42 17.63L24.65 19.05L24.85 20.67L24.04 21.48L23.43 22.91L20.99 24.13L21.20 24.73L35.82 16.41L35.01 16.00L31.96 18.03L27.09 18.84L20.59 15.19L19.37 14.17L18.15 13.77L17.95 12.14L19.57 9.70L22.01 8.48L21.40 8.08ZM23.63 9.50L20.99 10.92L19.98 12.75L27.49 17.02L30.95 16.41L33.38 14.78L23.84 9.50ZM14.49 15.80L11.45 16.41L9.42 17.83L15.71 21.28L16.93 22.30L18.56 22.91L18.76 23.31L22.21 21.48L22.82 20.06L17.13 16.61L15.51 15.80L14.70 15.80ZM6.17 18.03L5.96 18.84L9.21 20.47L12.46 24.13L12.67 34.69L11.85 35.50L8.81 35.50L6.57 34.08L5.96 34.08L5.96 34.69L9.62 36.52L20.38 43.02L20.38 41.80L17.34 40.38L14.29 37.13L13.88 26.16L14.70 25.34L17.95 25.34L20.18 26.77L20.59 26.77L20.59 26.16L6.37 18.03ZM36.63 18.03L35.82 18.44L35.82 22.70L34.40 26.77L26.07 31.84L25.06 32.05L24.04 31.64L22.82 29.41L22.62 26.16L22.21 26.36L22.21 42.81L23.02 42.61L22.82 38.95L24.24 34.48L33.18 29.00L34.81 29.61L36.02 31.84L36.02 34.89L36.84 34.69L36.84 18.03ZM33.99 19.45L24.45 24.94L24.65 29.00L25.06 29.81L25.67 30.02L27.49 28.59L32.98 25.55L33.99 22.50L33.99 19.66ZM6.17 20.88L5.96 31.84L8.81 33.27L9.01 33.67L10.84 33.67L10.63 24.53L8.81 22.91L8.40 22.09L6.17 21.08ZM15.92 27.17L15.92 36.11L18.56 38.95L20.38 39.97L20.59 29.00L17.54 27.17L16.12 27.17ZM33.18 31.23L25.67 35.70L24.65 38.95L24.65 41.59L34.20 36.11L34.20 32.25L33.38 31.23Z"/>
+  <g transform="translate(24.158614219195222 33.20861421919522) scale(0.8784)" fill="none" stroke="#0f6f8c"
+     stroke-width="2.73" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="1"/>
+    <path d="M20.2 20.2c2.04-2.03.02-7.36-4.5-11.9-4.54-4.52-9.87-6.54-11.9-4.5-2.04 2.03-.02 7.36 4.5 11.9 4.54 4.52 9.87 6.54 11.9 4.5Z"/>
+    <path d="M15.7 15.7c4.52-4.54 6.54-9.87 4.5-11.9-2.03-2.04-7.36-.02-11.9 4.5-4.52 4.54-6.54 9.87-4.5 11.9 2.03 2.04 7.36.02 11.9-4.5Z"/>
+  </g>
+</svg>

package/nodes/icons/fromcubes-utility.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="44" height="60" viewBox="0 0 44 60">
+  <!-- The fromcubes mark, traced from the project artwork by tools/build-icon.mjs.
+       The badge is cut out of the mark with a mask rather than hidden behind a
+       halo painted in the background colour: an icon cannot know what is behind
+       it, and masking keeps the traced edges exact instead of re-rasterising them.
+       The badge is the "wrench" icon from Lucide (https://lucide.dev), ISC —
+       see THIRD-PARTY-NOTICES.md. Worn by fc-portal-utility. React's own logo is a
+       Meta trademark and is deliberately not used. -->
+  <mask id="fc-cut" maskUnits="userSpaceOnUse" x="0" y="0" width="44" height="60">
+    <rect width="44" height="60" fill="#ffffff"/>
+    <g transform="translate(25.219431250695457 34.25674619515118) scale(0.7906)" fill="none" stroke="#000000"
+     stroke-width="6.83" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.106-3.105c.32-.322.863-.22.983.218a6 6 0 0 1-8.259 7.057l-7.91 7.91a1 1 0 0 1-2.999-3l7.91-7.91a6 6 0 0 1 7.057-8.259c.438.12.54.662.219.984z"/>
+    </g>
+  </mask>
+  <path fill="#10181d" fill-rule="evenodd" mask="url(#fc-cut)" d="M20.79 6.25L22.01 6.25L23.23 6.86L32.17 12.34L37.65 15.19L38.46 16.00L38.46 35.50L37.65 36.31L32.17 39.16L23.23 44.64L22.01 45.25L20.38 45.05L12.06 39.97L6.57 37.13L4.34 35.50L4.34 16.00L9.42 12.75L20.79 6.45ZM21.20 8.08L6.98 16.20L7.18 16.61L7.99 16.61L10.84 14.78L14.29 13.97L15.92 13.97L22.42 17.63L24.65 19.05L24.85 20.67L24.04 21.48L23.43 22.91L20.99 24.13L21.20 24.73L35.82 16.41L35.01 16.00L31.96 18.03L27.09 18.84L20.59 15.19L19.37 14.17L18.15 13.77L17.95 12.14L19.57 9.70L22.01 8.48L21.40 8.08ZM23.63 9.50L20.99 10.92L19.98 12.75L27.49 17.02L30.95 16.41L33.38 14.78L23.84 9.50ZM14.49 15.80L11.45 16.41L9.42 17.83L15.71 21.28L16.93 22.30L18.56 22.91L18.76 23.31L22.21 21.48L22.82 20.06L17.13 16.61L15.51 15.80L14.70 15.80ZM6.17 18.03L5.96 18.84L9.21 20.47L12.46 24.13L12.67 34.69L11.85 35.50L8.81 35.50L6.57 34.08L5.96 34.08L5.96 34.69L9.62 36.52L20.38 43.02L20.38 41.80L17.34 40.38L14.29 37.13L13.88 26.16L14.70 25.34L17.95 25.34L20.18 26.77L20.59 26.77L20.59 26.16L6.37 18.03ZM36.63 18.03L35.82 18.44L35.82 22.70L34.40 26.77L26.07 31.84L25.06 32.05L24.04 31.64L22.82 29.41L22.62 26.16L22.21 26.36L22.21 42.81L23.02 42.61L22.82 38.95L24.24 34.48L33.18 29.00L34.81 29.61L36.02 31.84L36.02 34.89L36.84 34.69L36.84 18.03ZM33.99 19.45L24.45 24.94L24.65 29.00L25.06 29.81L25.67 30.02L27.49 28.59L32.98 25.55L33.99 22.50L33.99 19.66ZM6.17 20.88L5.96 31.84L8.81 33.27L9.01 33.67L10.84 33.67L10.63 24.53L8.81 22.91L8.40 22.09L6.17 21.08ZM15.92 27.17L15.92 36.11L18.56 38.95L20.38 39.97L20.59 29.00L17.54 27.17L16.12 27.17ZM33.18 31.23L25.67 35.70L24.65 38.95L24.65 41.59L34.20 36.11L34.20 32.25L33.38 31.23Z"/>
+  <g transform="translate(25.219431250695457 34.25674619515118) scale(0.7906)" fill="none" stroke="#0f6f8c"
+     stroke-width="3.04" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.106-3.105c.32-.322.863-.22.983.218a6 6 0 0 1-8.259 7.057l-7.91 7.91a1 1 0 0 1-2.999-3l7.91-7.91a6 6 0 0 1 7.057-8.259c.438.12.54.662.219.984z"/>
+  </g>
+</svg>

package/nodes/lib/admin-api.js

@@ -0,0 +1,238 @@
+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 {Object<string, Object>} deps.pageState
+ * @param {Object<string, Object>} deps.registry
+ * @param {Object<string, Object>} deps.utilities
+ * @param {(code: string) => Set<string>} deps.extractUtilitySymbols
+ * @param {Object} [deps.providers]          lib/providers registry (describe/select).
+ * @param {Function} [deps.onProviderChange] Called with the kind after a choice changed.
+ * @returns {void}
+ */
+function registerAdminApi(RED, deps) {
+  const {
+    express,
+    permRead,
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    pageState,
+    registry,
+    utilities,
+    extractUtilitySymbols,
+    providers,
+    onProviderChange,
+  } = deps;
+
+  // Since 0.56 monaco-editor has an `exports` map that hides package.json;
+  // its CommonJS entry is min/vs/index.js, so the AMD build (loader.js and
+  // editor/editor.main.js) sits in the same directory.
+  const monacoVsPath = path.dirname(require.resolve("monaco-editor"));
+  RED.httpAdmin.use(
+    "/fromcubes-react/vs",
+    permRead,
+    express.static(monacoVsPath),
+  );
+
+  // Editor-side workspace plugin (tree + full-screen Monaco overlay). Served
+  // as static files instead of being inlined into portal-react.html so the
+  // node's editor template stays readable.
+  RED.httpAdmin.use(
+    "/fromcubes-react/editor",
+    permRead,
+    express.static(path.join(__dirname, "..", "editor")),
+  );
+
+  // The node icon doubles as the editor's status-bar mark. Serving the icons
+  // directory here keeps one copy on disk and spares the client from having to
+  // know the package name that Node-RED's own /icons route is keyed by.
+  RED.httpAdmin.use(
+    "/fromcubes-react/icons",
+    permRead,
+    express.static(path.join(__dirname, "..", "icons")),
+  );
+
+  // Prettier's browser builds, straight from node_modules — same arrangement
+  // as Monaco at /fromcubes-react/vs. Nothing is fetched until someone formats.
+  RED.httpAdmin.use(
+    "/fromcubes-react/prettier",
+    permRead,
+    express.static(path.dirname(require.resolve("prettier/package.json"))),
+  );
+
+  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("/fromcubes-react/registry", permRead, (_req, res) => {
+    res.json(registry);
+  });
+
+  RED.httpAdmin.post(
+    "/fromcubes-react/registry",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    (_req, res) => {
+      res.status(410).json({
+        error: "registry writes are deprecated; use fc-portal-component nodes",
+      });
+    },
+  );
+
+  RED.httpAdmin.delete(
+    "/fromcubes-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("/fromcubes-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(
+    "/fromcubes-react/utilities",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    (_req, res) => {
+      res.status(410).json({
+        error: "utility writes are deprecated; use fc-portal-utility nodes",
+      });
+    },
+  );
+
+  RED.httpAdmin.delete(
+    "/fromcubes-react/utilities/:name",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    (_req, res) => {
+      res.status(410).json({
+        error: "utility writes are deprecated; use fc-portal-utility nodes",
+      });
+    },
+  );
+
+  if (providers) registerProviderRoutes(RED, deps);
+}
+
+// select() error code → HTTP status
+const SELECT_STATUS = { "bad-kind": 400, "bad-id": 400, unknown: 400, locked: 409 };
+
+/**
+ * Settings → Fromcubes: read and change the identity provider and CSS engine.
+ * Changing identity decides who counts as logged in, so the write sits
+ * behind the same permission, CSRF and rate-limit gates as every other
+ * admin write, and is logged with the editor user who made it.
+ *
+ * @param {Object} RED
+ * @param {Object} deps  See registerAdminApi.
+ * @returns {void}
+ * @private
+ */
+function registerProviderRoutes(RED, deps) {
+  const { express, permRead, permWrite, csrfGuard, rateLimit, providers, onProviderChange } = deps;
+  // Node-RED's admin app parses JSON already (capped by apiMaxLength); parse
+  // only where nothing upstream did — the same arrangement as lib/assets.js.
+  const parseJson = express.json({ limit: (RED.settings && RED.settings.apiMaxLength) || "5mb" });
+  const jsonBody = (req, res, next) => (req._body ? next() : parseJson(req, res, next));
+
+  RED.httpAdmin.get("/fromcubes-react/providers", permRead, (_req, res) => {
+    res.json(providers.describe());
+  });
+
+  // Completion list for className="…", from whichever CSS engine is in force.
+  // `engine` lets the editor tell a stale list from a fresh one.
+  RED.httpAdmin.get("/fromcubes-react/css-classes", permRead, async (_req, res) => {
+    try {
+      res.json(await providers.editorClasses());
+    } catch (e) {
+      RED.log.error("[portal-react] css-classes: " + e.message);
+      res.status(500).json({ error: "could not list classes" });
+    }
+  });
+
+  RED.httpAdmin.put(
+    "/fromcubes-react/providers",
+    permWrite,
+    csrfGuard,
+    rateLimit,
+    jsonBody,
+    (req, res) => {
+      const { kind, id } = req.body || {};
+      let changed;
+      try {
+        changed = providers.select(kind, id);
+      } catch (e) {
+        const status = SELECT_STATUS[e.code];
+        if (!status) {
+          RED.log.error("[portal-react] saving provider choice failed: " + e.message);
+          res.status(500).json({ error: "could not save the provider choice" });
+          return;
+        }
+        res.status(status).json({ error: e.message, code: e.code });
+        return;
+      }
+      if (changed) {
+        const who = (req.user && req.user.username) || "anonymous editor";
+        RED.log.warn(`[portal-react] ${kind} provider set to "${id}" by ${who}`);
+        if (onProviderChange) onProviderChange(kind);
+      }
+      res.json(providers.describe());
+    },
+  );
+}
+
+module.exports = { registerAdminApi };

package/nodes/lib/admin-security.js

@@ -0,0 +1,161 @@
+/** @module nodes/lib/admin-security */
+
+/**
+ * The gates every fromcubes admin route goes through — permission scopes,
+ * the CSRF header check and the per-IP rate limit — plus the express that
+ * Node-RED itself ships. Shared by the core and by the add-on packages
+ * (through the `api` export, lib/api.js), so an add-on's routes get exactly
+ * the same protection and the same rate-limit buckets as the core's.
+ */
+
+/**
+ * Borrow the express that the running Node-RED ships with instead of
+ * declaring our own copy. We only need its static/json/raw middleware; the
+ * server itself is RED.httpAdmin/RED.httpNode. This package lives in
+ * `<userDir>/node_modules`, from where a plain require cannot see Node-RED's
+ * install directory, so resolve from the entry script that started the
+ * process (node-red's red.js). Embedded Node-RED (an app that requires
+ * node-red itself) falls back to a plain require — such an app has express.
+ * @returns {typeof import("express")}
+ */
+function loadExpress() {
+  const entry = require.main && require.main.filename;
+  if (entry) {
+    try {
+      return require("module").createRequire(entry)("express");
+    } catch (_) {
+      // not launched through node-red's own entry script
+    }
+  }
+  return require("express");
+}
+
+/**
+ * Build the admin gates bound to `RED`. Safe to call more than once (core
+ * and each add-on do): the rate-limit buckets and their prune timer live on
+ * `RED.settings`, so every caller shares one bucket per client IP.
+ *
+ * @param {Object} RED
+ * @returns {{
+ *   permRead: import("express").RequestHandler,
+ *   permWrite: import("express").RequestHandler,
+ *   csrfGuard: import("express").RequestHandler,
+ *   rateLimit: import("express").RequestHandler,
+ * }}
+ */
+function createAdminSecurity(RED) {
+  // ── Admin auth gate (Node-RED 4.x adminAuth) ─────────────────
+  // When the user configures `adminAuth` in settings.js, RED.auth.needsPermission
+  // returns an Express middleware that enforces the named permission scope.
+  // Without this gate, any endpoint mounted on RED.httpAdmin is reachable
+  // without auth and can read/modify the registry, utilities, and assets.
+  // Fallback no-op for runtimes that do not expose RED.auth.
+  /**
+   * Resolve a Node-RED permission middleware. Returns a no-op when the runtime
+   * does not expose `RED.auth.needsPermission` (test harnesses, Node-RED <1.0)
+   * so unit tests don't have to mock auth.
+   *
+   * @param {string} scope  Permission scope (e.g. `"portal-react.write"`).
+   * @returns {import("express").RequestHandler}
+   * @private
+   */
+  function needsPerm(scope) {
+    if (RED.auth && typeof RED.auth.needsPermission === "function") {
+      return RED.auth.needsPermission(scope);
+    }
+    return function (_req, _res, next) { next(); };
+  }
+  const PERM_READ = needsPerm("portal-react.read");
+  const PERM_WRITE = needsPerm("portal-react.write");
+
+  // ── CSRF guard for admin write endpoints ──────────────────────
+  // The Node-RED editor sends `Node-RED-API-Version` on every XHR. Browsers
+  // refuse to attach custom headers on cross-origin form/fetch submissions
+  // without a CORS preflight, so requiring this header on write endpoints is
+  // sufficient CSRF protection without per-session tokens. Same trick the
+  // Node-RED core admin API uses for its own POST/PUT/DELETE routes.
+  /**
+   * Express middleware enforcing the `Node-RED-API-Version` header on write
+   * endpoints. The header is sent by the Node-RED editor XHR layer on every
+   * request; browser cross-origin form/fetch POSTs cannot attach custom
+   * headers without a CORS preflight, so requiring this header gives CSRF
+   * protection without per-session tokens.
+   *
+   * @param {import("express").Request}  req
+   * @param {import("express").Response} res
+   * @param {Function}                   next
+   * @returns {void}
+   * @private
+   */
+  function csrfGuard(req, res, next) {
+    if (!req.get("Node-RED-API-Version")) {
+      return res.status(403).json({ error: "missing Node-RED-API-Version header" });
+    }
+    next();
+  }
+
+  // ── Token-bucket rate limiter keyed by req.ip ─────────────────
+  // Steady-state: RATE_LIMIT_TOKENS tokens refilled over RATE_LIMIT_WINDOW_MS.
+  // Default = 60 tokens / 60 s → 1 req/s sustained, 60 burst. Tunable via
+  // RED.settings.portalReact.rateLimit = { tokens, windowMs }. The buckets
+  // are pruned every 5 minutes to bound memory usage.
+  const rateLimitCfg = (RED.settings.portalReact &&
+    RED.settings.portalReact.rateLimit) || {};
+  const RATE_LIMIT_TOKENS = Number.isFinite(rateLimitCfg.tokens)
+    ? rateLimitCfg.tokens
+    : 60;
+  const RATE_LIMIT_WINDOW_MS = Number.isFinite(rateLimitCfg.windowMs)
+    ? rateLimitCfg.windowMs
+    : 60_000;
+  if (!RED.settings.portalReactRateBuckets) RED.settings.portalReactRateBuckets = new Map();
+  const rateBuckets = RED.settings.portalReactRateBuckets;
+
+  /**
+   * Token-bucket rate limit middleware keyed by `req.ip`. Each bucket refills
+   * `RATE_LIMIT_TOKENS` over `RATE_LIMIT_WINDOW_MS`. Steady-state default is
+   * 1 request/second with a 60-token burst. On exhaustion: HTTP 429 with
+   * `Retry-After`. Buckets idle > 10 minutes get pruned by a separate
+   * interval (see below).
+   *
+   * @param {import("express").Request}  req
+   * @param {import("express").Response} res
+   * @param {Function}                   next
+   * @returns {void}
+   * @private
+   */
+  function rateLimit(req, res, next) {
+    const ip = req.ip || req.socket?.remoteAddress || "unknown";
+    const now = Date.now();
+    let b = rateBuckets.get(ip);
+    if (!b) {
+      b = { tokens: RATE_LIMIT_TOKENS, last: now };
+      rateBuckets.set(ip, b);
+    }
+    const elapsed = now - b.last;
+    b.tokens = Math.min(
+      RATE_LIMIT_TOKENS,
+      b.tokens + (elapsed * RATE_LIMIT_TOKENS) / RATE_LIMIT_WINDOW_MS,
+    );
+    b.last = now;
+    if (b.tokens < 1) {
+      res.set("Retry-After", Math.ceil(RATE_LIMIT_WINDOW_MS / 1000));
+      return res.status(429).json({ error: "rate limit exceeded" });
+    }
+    b.tokens -= 1;
+    next();
+  }
+
+  if (!RED.settings.portalReactRateBucketPruneIv) {
+    RED.settings.portalReactRateBucketPruneIv = setInterval(() => {
+      const now = Date.now();
+      for (const [ip, b] of rateBuckets) {
+        if (now - b.last > 10 * 60_000) rateBuckets.delete(ip);
+      }
+    }, 5 * 60_000);
+    RED.settings.portalReactRateBucketPruneIv.unref?.();
+  }
+
+  return { permRead: PERM_READ, permWrite: PERM_WRITE, csrfGuard, rateLimit };
+}
+
+module.exports = { createAdminSecurity, loadExpress };

package/nodes/lib/api.js

@@ -0,0 +1,29 @@
+/** @module nodes/lib/api */
+
+/**
+ * The core's public surface for add-ons. Add-on packages
+ * (@aaqu/fromcubes-auth-headers, -tailwind, -assets, and third-party ones)
+ * require `@aaqu/fromcubes-react/api` — package.json `exports` maps it here —
+ * and nothing else from the core (tests/addon-boundary.test.js).
+ *
+ * Keep it small and stable — anything exported here is a promise to every
+ * add-on, ours and third-party.
+ */
+
+const { createAdminSecurity, loadExpress } = require("./admin-security");
+const {
+  IDENTITY_TYPE,
+  CSS_TYPE,
+  API_VERSION,
+} = require("./providers");
+
+module.exports = {
+  // Plugin contract (see lib/providers.js)
+  IDENTITY_TYPE,
+  CSS_TYPE,
+  API_VERSION,
+  // Admin route gates shared with the core: permission, CSRF, rate limit
+  createAdminSecurity,
+  // The express Node-RED itself ships (static/json/raw middleware)
+  loadExpress,
+};