nibula 1.0.2 → 1.1.1

package/src/backend/_core/modules/RateLimiter.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/modules/RateLimiter.php
+ *
+ * Same algorithm and same on-disk format: one JSON file per IP under ../../cache,
+ * holding an array of request timestamps. Old timestamps outside the window are
+ * pruned, the current one appended, and if the count exceeds the limit a 429 is
+ * returned (with a Retry-After header) through the request-bound Response helper.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+class RateLimiter {
+    /**
+     * @param {string} ip
+     * @param {number} maxRequests
+     * @param {number} windowSeconds
+     * @param {object} Response  request-bound helper from createResponse(res)
+     * @param {object} res       raw http response (to set Retry-After)
+     */
+    static check(ip, maxRequests = 60, windowSeconds = 60, Response, res) {
+        const cacheDir = path.join(__dirname, '..', '..', 'cache');
+
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true, mode: 0o755 });
+        }
+
+        const hash = crypto.createHash('md5').update(ip).digest('hex');
+        const cacheFile = path.join(cacheDir, 'rl_' + hash + '.json');
+        const now = Math.floor(Date.now() / 1000);
+        let data = [];
+
+        if (fs.existsSync(cacheFile)) {
+            try {
+                data = JSON.parse(fs.readFileSync(cacheFile, 'utf8')) || [];
+            } catch (e) {
+                data = [];
+            }
+        }
+
+        data = data.filter((ts) => ts > (now - windowSeconds));
+        data.push(now);
+
+        // LOCK_EX equivalent: an exclusive write. Node's writeFileSync is atomic
+        // enough for this single-process model.
+        fs.writeFileSync(cacheFile, JSON.stringify(data));
+
+        if (data.length > maxRequests) {
+            res.setHeader('Retry-After', String(windowSeconds));
+            Response.error('Too Many Requests', 429);
+        }
+    }
+}
+
+module.exports = RateLimiter;

package/src/backend/_core/modules/Response.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/modules/Response.php
+ *
+ * In PHP the Response helper writes JSON and calls exit() to stop execution.
+ * Node has no per-request exit, so each method writes to the response and then
+ * throws the HALT sentinel. The front controller catches HALT and stops the
+ * dispatch, reproducing the same "the endpoint stops here" behaviour.
+ *
+ * A fresh, response-bound helper is created per request via createResponse(res)
+ * so overlapping async requests never clash (PHP was process-per-request).
+ */
+
+// Sentinel thrown to unwind execution after a response has been sent (≈ PHP exit).
+const HALT = Symbol('RESPONSE_HALT');
+
+function jsonEncode(obj) {
+    // JSON.stringify already leaves unicode unescaped and does not escape slashes,
+    // matching PHP's JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES.
+    return JSON.stringify(obj);
+}
+
+function createResponse(res) {
+    return {
+        success(data = null, code = 200) {
+            res.statusCode = code;
+            res.setHeader('Content-Type', 'application/json; charset=UTF-8');
+            res.end(jsonEncode({
+                status: 'success',
+                data: data,
+            }));
+            throw HALT;
+        },
+
+        error(message, code = 400, details = null) {
+            res.statusCode = code;
+            res.setHeader('Content-Type', 'application/json; charset=UTF-8');
+            const body = {
+                status: 'error',
+                message: message,
+                code: code,
+            };
+            if (details !== null) {
+                body.details = details;
+            }
+            res.end(jsonEncode(body));
+            throw HALT;
+        },
+
+        noContent() {
+            res.statusCode = 204;
+            res.end();
+            throw HALT;
+        },
+    };
+}
+
+module.exports = { createResponse, HALT };

package/src/backend/api/protected/example-protected.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/api/protected/example-protected.php
+ *
+ * Protected endpoint: the API key check (X-Api-Key header) runs automatically in
+ * the front controller before this file is loaded, so here we just handle logic.
+ */
+
+module.exports = ({ method, requestParams, Response }) => {
+    if (method !== 'GET') {
+        Response.error('Method not allowed', 405);
+    }
+
+    //
+    // Your endpoint logic here. You can access route parameters in requestParams
+    //
+
+    Response.success({
+        message: 'Protected endpoint is working',
+        params: requestParams,
+    });
+};

package/src/backend/api/public/example-public.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/api/public/example-public.php
+ *
+ * Public endpoint: no API key required. Receives the request context and calls
+ * the request-bound Response helper, exactly like the PHP file used the global
+ * Response class and $method / $requestParams.
+ */
+
+module.exports = ({ method, requestParams, Response }) => {
+    if (method !== 'GET') {
+        Response.error('Method not allowed', 405);
+    }
+
+    //
+    // Your endpoint logic here. You can access route parameters in requestParams
+    //
+
+    Response.success({
+        message: 'Public endpoint is working',
+        params: requestParams,
+    });
+};

package/src/backend/backend-node.service.example

@@ -0,0 +1,30 @@
+# Example systemd unit to keep the Node backend running on your server.
+#
+# 1. Copy your built site to the server (the `out` folder).
+# 2. Adjust WorkingDirectory below to point at out/backend on your server.
+# 3. Copy this file to /etc/systemd/system/backend-node.service (drop the .example).
+# 4. Enable and start it:
+#       sudo systemctl daemon-reload
+#       sudo systemctl enable --now backend-node
+#       sudo systemctl status backend-node
+#
+# Check the Node path with `which node` and update ExecStart if it isn't /usr/bin/node
+# (nvm installs live elsewhere, e.g. /home/<user>/.nvm/versions/node/<v>/bin/node).
+
+[Unit]
+Description=Nibula Node backend
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/var/www/your-site/out/backend
+ExecStart=/usr/bin/node _core/index.js
+Environment=PORT=3000
+Environment=HOST=127.0.0.1
+Environment=APP_ENV=production
+Restart=on-failure
+RestartSec=2
+User=www-data
+
+[Install]
+WantedBy=multi-user.target

package/src/backend/database/Database.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/database/Database.php
+ *
+ * PDO singleton → a single shared mysql2 connection pool. Config is read from
+ * ../config.js (same relative location as the PHP version's ../config.php).
+ * Options map the PDO attributes as closely as mysql2 allows:
+ *   - ERRMODE_EXCEPTION      → mysql2 rejects/throws on error by default
+ *   - FETCH_ASSOC            → rowsAsArray:false (objects keyed by column) is default
+ *   - EMULATE_PREPARES false → native prepared statements via pool.execute()
+ *
+ * Requires the "mysql2" package (npm install mysql2). getInstance() returns the
+ * promise-based pool; use pool.execute(sql, params) for prepared statements.
+ */
+
+const path = require('path');
+
+let instance = null;
+
+class Database {
+    static getInstance() {
+        if (instance === null) {
+            // Lazy require so the backend boots even without a DB configured.
+            // eslint-disable-next-line global-require
+            const mysql = require('mysql2/promise');
+
+            // eslint-disable-next-line global-require
+            const config = require(path.join(__dirname, '..', 'config.js'));
+
+            instance = mysql.createPool({
+                host: config.DB_HOST,
+                database: config.DB_NAME,
+                user: config.DB_USER,
+                password: config.DB_PASS,
+                charset: 'utf8mb4',
+                waitForConnections: true,
+                connectionLimit: 10,
+                namedPlaceholders: false,
+            });
+        }
+        return instance;
+    }
+}
+
+module.exports = Database;

package/src/backend/example.config.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/example.config.php
+ *
+ * Versioned, secret-free template. On setup, copy this file to config.js and
+ * fill in real values. config.js is git-ignored and stays local.
+ */
+
+module.exports = {
+    // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
+    GENERAL_API_KEY: 'DEFAULT_KEY',
+
+    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
+    // For subfolder endpoints, use the relative path ('subfolder/endpoint')
+    CUSTOM_ENDPOINT_KEYS: {
+        'subfolder/example-protected': 'custom-key',
+    },
+
+    GENERAL_ALLOWED_ORIGINS: [
+        '*',
+        // 'https://example.com',
+    ],
+
+    CUSTOM_ENDPOINT_ORIGINS: {
+        'subfolder/example-protected': ['https://app.example.com'],
+    },
+
+    // Database configuration
+    DB_HOST: '127.0.0.1',
+    DB_NAME: 'example_db',
+    DB_USER: 'root',
+    DB_PASS: '',
+
+    // Environment: 'production' hides error details; anything else = debug.
+    APP_ENV: 'production',
+};

package/src/backend/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "backend-node",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Node.js backend for a Nibula site. Coexists with the PHP backend; pick one at scaffold time. Front controller: _core/index.js.",
+  "main": "_core/index.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node _core/index.js",
+    "dev": "APP_ENV=development node _core/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mysql2": "^3.11.0"
+  }
+}

package/src/frontend/.htaccess

@@ -6,11 +6,46 @@ ErrorDocument 403 /404.html
     RewriteEngine On
     RewriteBase /
 
+    # Block sensitive files (web.config, dotfiles)
     RewriteRule ^(web\.config|\..*)$ /404.html [L,NC]
+</IfModule>
 
+# === /api routing — covers BOTH backends ====================================
+#
+# Apache (unlike nginx) cannot health-check an upstream, so it cannot auto-fall
+# back from Node to PHP. The behaviour is:
+#
+#   - mod_proxy available  -> /api is proxied to the Node backend (127.0.0.1:3000)
+#   - mod_proxy NOT present -> /api is rewritten to the PHP front controller
+#
+# Typical shared hosting (Aruba, cPanel) has no mod_proxy, so it uses PHP
+# automatically. On a VPS running Node, mod_proxy sends /api to Node.
+#
+# If you are on a server that HAS mod_proxy but you want to use PHP, comment out
+# the mod_proxy block below.
+
+# --- Node backend (if mod_proxy is available) ---
+<IfModule mod_proxy.c>
+    ProxyPreserveHost On
+    ProxyPass        /api/ http://127.0.0.1:3000/api/ retry=0
+    ProxyPassReverse /api/ http://127.0.0.1:3000/api/
+
+    <IfModule mod_headers.c>
+        RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"
+        RequestHeader set X-Forwarded-Proto "https"
+    </IfModule>
+</IfModule>
+
+# --- PHP backend (fallback when mod_proxy is absent) ---
+<IfModule mod_rewrite.c>
+    RewriteEngine On
+    RewriteBase /
     RewriteRule ^api/(.*)$ backend/_core/index.php [QSA,L]
+</IfModule>
 
+# === Static files ===========================================================
+<IfModule mod_rewrite.c>
     RewriteCond %{REQUEST_FILENAME} -f [OR]
     RewriteCond %{REQUEST_FILENAME} -d
     RewriteRule ^ - [L]
-</IfModule>
+</IfModule>

package/src/frontend/assets/brand/favicon.svg

@@ -1,54 +1,54 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Nibula">
-  <defs>
-    <linearGradient id="nibulaShieldBorder" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#8b6fc4"/>
-      <stop offset="0.5" stop-color="#c9a06a"/>
-      <stop offset="1" stop-color="#f2c17a"/>
-    </linearGradient>
-    <linearGradient id="nibulaN" x1="0" y1="1" x2="1" y2="0">
-      <stop offset="0" stop-color="#6d4fa8"/>
-      <stop offset="0.45" stop-color="#a978b0"/>
-      <stop offset="0.75" stop-color="#e7a55f"/>
-      <stop offset="1" stop-color="#f7d08a"/>
-    </linearGradient>
-    <linearGradient id="nibulaNib" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#f7d89a"/>
-      <stop offset="0.55" stop-color="#e0a95f"/>
-      <stop offset="1" stop-color="#b07d3e"/>
-    </linearGradient>
-    <linearGradient id="nibulaField" x1="0" y1="0" x2="0.6" y2="1">
-      <stop offset="0" stop-color="#3a2c63"/>
-      <stop offset="1" stop-color="#2a2150"/>
-    </linearGradient>
-  </defs>
-
-  <path fill="none" stroke="url(#nibulaShieldBorder)" stroke-width="10" stroke-linejoin="round"
-        d="M256 40 L440 132 L440 320 L256 472 L72 320 L72 132 Z"/>
-  <path fill="url(#nibulaField)" stroke="url(#nibulaShieldBorder)" stroke-width="6" stroke-linejoin="round"
-        d="M256 66 L418 147 L418 310 L256 442 L94 310 L94 147 Z"/>
-
-  <!-- N as one closed outline: up left post, down inner-left, diagonal to inner-bottom-right,
-       up right post, cut corner, down outer-right, close along the bottom -->
-  <path fill="url(#nibulaN)" stroke="#1a1533" stroke-width="7" stroke-linejoin="round"
-        d="M148 362
-           L148 150
-           L206 150
-           L312 300
-           L312 150
-           L370 150
-           L370 205
-           L340 205
-           L340 362
-           L282 362
-           L206 255
-           L206 362
-           Z"/>
-
-  <g stroke="#1a1533" stroke-width="7" stroke-linejoin="round" stroke-linecap="round">
-    <path fill="url(#nibulaNib)" d="M326 300 L382 300 L392 326 L336 326 Z"/>
-    <path fill="none" stroke-width="5" d="M338 313 L386 313"/>
-    <path fill="url(#nibulaNib)" d="M336 326 L392 326 L428 414 L370 380 Z"/>
-    <path fill="none" stroke-width="5" d="M366 342 L402 384"/>
-    <circle cx="376" cy="360" r="6.5" fill="#1a1533" stroke="none"/>
-  </g>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Nibula">
+  <defs>
+    <linearGradient id="nibulaShieldBorder" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#8b6fc4"/>
+      <stop offset="0.5" stop-color="#c9a06a"/>
+      <stop offset="1" stop-color="#f2c17a"/>
+    </linearGradient>
+    <linearGradient id="nibulaN" x1="0" y1="1" x2="1" y2="0">
+      <stop offset="0" stop-color="#6d4fa8"/>
+      <stop offset="0.45" stop-color="#a978b0"/>
+      <stop offset="0.75" stop-color="#e7a55f"/>
+      <stop offset="1" stop-color="#f7d08a"/>
+    </linearGradient>
+    <linearGradient id="nibulaNib" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f7d89a"/>
+      <stop offset="0.55" stop-color="#e0a95f"/>
+      <stop offset="1" stop-color="#b07d3e"/>
+    </linearGradient>
+    <linearGradient id="nibulaField" x1="0" y1="0" x2="0.6" y2="1">
+      <stop offset="0" stop-color="#3a2c63"/>
+      <stop offset="1" stop-color="#2a2150"/>
+    </linearGradient>
+  </defs>
+
+  <path fill="none" stroke="url(#nibulaShieldBorder)" stroke-width="10" stroke-linejoin="round"
+        d="M256 40 L440 132 L440 320 L256 472 L72 320 L72 132 Z"/>
+  <path fill="url(#nibulaField)" stroke="url(#nibulaShieldBorder)" stroke-width="6" stroke-linejoin="round"
+        d="M256 66 L418 147 L418 310 L256 442 L94 310 L94 147 Z"/>
+
+  <!-- N as one closed outline: up left post, down inner-left, diagonal to inner-bottom-right,
+       up right post, cut corner, down outer-right, close along the bottom -->
+  <path fill="url(#nibulaN)" stroke="#1a1533" stroke-width="7" stroke-linejoin="round"
+        d="M148 362
+           L148 150
+           L206 150
+           L312 300
+           L312 150
+           L370 150
+           L370 205
+           L340 205
+           L340 362
+           L282 362
+           L206 255
+           L206 362
+           Z"/>
+
+  <g stroke="#1a1533" stroke-width="7" stroke-linejoin="round" stroke-linecap="round">
+    <path fill="url(#nibulaNib)" d="M326 300 L382 300 L392 326 L336 326 Z"/>
+    <path fill="none" stroke-width="5" d="M338 313 L386 313"/>
+    <path fill="url(#nibulaNib)" d="M336 326 L392 326 L428 414 L370 380 Z"/>
+    <path fill="none" stroke-width="5" d="M366 342 L402 384"/>
+    <circle cx="376" cy="360" r="6.5" fill="#1a1533" stroke="none"/>
+  </g>
+</svg>

package/src/frontend/assets/brand/logo.svg

@@ -1,54 +1,54 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Nibula">
-  <defs>
-    <linearGradient id="nibulaShieldBorder" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#8b6fc4"/>
-      <stop offset="0.5" stop-color="#c9a06a"/>
-      <stop offset="1" stop-color="#f2c17a"/>
-    </linearGradient>
-    <linearGradient id="nibulaN" x1="0" y1="1" x2="1" y2="0">
-      <stop offset="0" stop-color="#6d4fa8"/>
-      <stop offset="0.45" stop-color="#a978b0"/>
-      <stop offset="0.75" stop-color="#e7a55f"/>
-      <stop offset="1" stop-color="#f7d08a"/>
-    </linearGradient>
-    <linearGradient id="nibulaNib" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#f7d89a"/>
-      <stop offset="0.55" stop-color="#e0a95f"/>
-      <stop offset="1" stop-color="#b07d3e"/>
-    </linearGradient>
-    <linearGradient id="nibulaField" x1="0" y1="0" x2="0.6" y2="1">
-      <stop offset="0" stop-color="#3a2c63"/>
-      <stop offset="1" stop-color="#2a2150"/>
-    </linearGradient>
-  </defs>
-
-  <path fill="none" stroke="url(#nibulaShieldBorder)" stroke-width="10" stroke-linejoin="round"
-        d="M256 40 L440 132 L440 320 L256 472 L72 320 L72 132 Z"/>
-  <path fill="url(#nibulaField)" stroke="url(#nibulaShieldBorder)" stroke-width="6" stroke-linejoin="round"
-        d="M256 66 L418 147 L418 310 L256 442 L94 310 L94 147 Z"/>
-
-  <!-- N as one closed outline: up left post, down inner-left, diagonal to inner-bottom-right,
-       up right post, cut corner, down outer-right, close along the bottom -->
-  <path fill="url(#nibulaN)" stroke="#1a1533" stroke-width="7" stroke-linejoin="round"
-        d="M148 362
-           L148 150
-           L206 150
-           L312 300
-           L312 150
-           L370 150
-           L370 205
-           L340 205
-           L340 362
-           L282 362
-           L206 255
-           L206 362
-           Z"/>
-
-  <g stroke="#1a1533" stroke-width="7" stroke-linejoin="round" stroke-linecap="round">
-    <path fill="url(#nibulaNib)" d="M326 300 L382 300 L392 326 L336 326 Z"/>
-    <path fill="none" stroke-width="5" d="M338 313 L386 313"/>
-    <path fill="url(#nibulaNib)" d="M336 326 L392 326 L428 414 L370 380 Z"/>
-    <path fill="none" stroke-width="5" d="M366 342 L402 384"/>
-    <circle cx="376" cy="360" r="6.5" fill="#1a1533" stroke="none"/>
-  </g>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Nibula">
+  <defs>
+    <linearGradient id="nibulaShieldBorder" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#8b6fc4"/>
+      <stop offset="0.5" stop-color="#c9a06a"/>
+      <stop offset="1" stop-color="#f2c17a"/>
+    </linearGradient>
+    <linearGradient id="nibulaN" x1="0" y1="1" x2="1" y2="0">
+      <stop offset="0" stop-color="#6d4fa8"/>
+      <stop offset="0.45" stop-color="#a978b0"/>
+      <stop offset="0.75" stop-color="#e7a55f"/>
+      <stop offset="1" stop-color="#f7d08a"/>
+    </linearGradient>
+    <linearGradient id="nibulaNib" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f7d89a"/>
+      <stop offset="0.55" stop-color="#e0a95f"/>
+      <stop offset="1" stop-color="#b07d3e"/>
+    </linearGradient>
+    <linearGradient id="nibulaField" x1="0" y1="0" x2="0.6" y2="1">
+      <stop offset="0" stop-color="#3a2c63"/>
+      <stop offset="1" stop-color="#2a2150"/>
+    </linearGradient>
+  </defs>
+
+  <path fill="none" stroke="url(#nibulaShieldBorder)" stroke-width="10" stroke-linejoin="round"
+        d="M256 40 L440 132 L440 320 L256 472 L72 320 L72 132 Z"/>
+  <path fill="url(#nibulaField)" stroke="url(#nibulaShieldBorder)" stroke-width="6" stroke-linejoin="round"
+        d="M256 66 L418 147 L418 310 L256 442 L94 310 L94 147 Z"/>
+
+  <!-- N as one closed outline: up left post, down inner-left, diagonal to inner-bottom-right,
+       up right post, cut corner, down outer-right, close along the bottom -->
+  <path fill="url(#nibulaN)" stroke="#1a1533" stroke-width="7" stroke-linejoin="round"
+        d="M148 362
+           L148 150
+           L206 150
+           L312 300
+           L312 150
+           L370 150
+           L370 205
+           L340 205
+           L340 362
+           L282 362
+           L206 255
+           L206 362
+           Z"/>
+
+  <g stroke="#1a1533" stroke-width="7" stroke-linejoin="round" stroke-linecap="round">
+    <path fill="url(#nibulaNib)" d="M326 300 L382 300 L392 326 L336 326 Z"/>
+    <path fill="none" stroke-width="5" d="M338 313 L386 313"/>
+    <path fill="url(#nibulaNib)" d="M336 326 L392 326 L428 414 L370 380 Z"/>
+    <path fill="none" stroke-width="5" d="M366 342 L402 384"/>
+    <circle cx="376" cy="360" r="6.5" fill="#1a1533" stroke="none"/>
+  </g>
+</svg>