nibula 1.0.1 → 1.1.0

package/src/backend/_core/init.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/init.php
+ *
+ * init.php did three things:
+ *   1. registered a global exception handler that turns any throwable into a
+ *      500 JSON response (verbose in debug, generic in production);
+ *   2. registered an error handler that promoted PHP warnings to exceptions;
+ *   3. loaded config.php.
+ *
+ * In Node there is no per-request global handler, so the exception-to-500
+ * translation lives in the front controller (index.js), which calls
+ * handleException() below. Here we expose config loading and that helper.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load configuration. dirname(__dirname) in PHP pointed at the folder holding
+ * config.php (the backend root). Here that is the parent of _core.
+ * If config.js is missing (e.g. fresh clone) we fall back to example.config.js,
+ * mirroring the "copy example.config to config" guidance.
+ */
+function loadConfig() {
+    const backendRoot = path.join(__dirname, '..');
+    const configPath = path.join(backendRoot, 'config.js');
+    const examplePath = path.join(backendRoot, 'example.config.js');
+
+    if (fs.existsSync(configPath)) {
+        return require(configPath);
+    }
+    return require(examplePath);
+}
+
+/**
+ * Turn any thrown error into a 500 response, mirroring set_exception_handler.
+ * @param {Error} exception
+ * @param {object} config
+ * @param {object} Response request-bound helper
+ */
+function handleException(exception, config, Response) {
+    const isDebug = (config.APP_ENV || 'production') !== 'production';
+    Response.error(
+        isDebug ? exception.message : 'Internal server error',
+        500,
+        isDebug ? { stack: exception.stack } : null
+    );
+}
+
+module.exports = { loadConfig, handleException };

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

@@ -1,16 +1,51 @@
-Options -Indexes
-ErrorDocument 404 /404.html
-ErrorDocument 403 /404.html
-
-<IfModule mod_rewrite.c>
-    RewriteEngine On
-    RewriteBase /
-
-    RewriteRule ^(web\.config|\..*)$ /404.html [L,NC]
-
-    RewriteRule ^api/(.*)$ backend/_core/index.php [QSA,L]
-
-    RewriteCond %{REQUEST_FILENAME} -f [OR]
-    RewriteCond %{REQUEST_FILENAME} -d
-    RewriteRule ^ - [L]
-</IfModule>
+Options -Indexes
+ErrorDocument 404 /404.html
+ErrorDocument 403 /404.html
+
+<IfModule mod_rewrite.c>
+    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>

package/src/frontend/data/site.json

@@ -1,54 +1,54 @@
-{
-  "site_name": "Site name",
-  "title": "Site title",
-  "description": "Site description",
-  "keywords": "keyword1, keyword2, keyword3",
-  "domain": "yoursite.com",
-  "url": "https://yoursite.com",
-  "lang": "en",
-  "author": "Name and surname",
-  "data_bs_theme": "dark",
-  "theme_color": {
-    "light": "#ffffff",
-    "dark": "#0d1117"
-  },
-  "favicon": "/assets/brand/favicon.svg",
-  "logo": "/assets/brand/logo.svg",
-  "legal": {
-    "privacy": "",
-    "cookie": "",
-    "cookieControls": "",
-    "terms": "",
-    "copyright": {
-      "year": "2026",
-      "text": "All rights reserved."
-    }
-  },
-  "pages": {
-    "404": {
-      "seo": {
-        "title": "404 - Not found",
-        "keywords": "",
-        "noindex": true,
-        "canonical": ""
-      },
-      "cdn": {
-        "css": [],
-        "js": []
-      }
-    },
-    "homepage": {
-      "seo": {
-        "title": "Homepage",
-        "description": "Description",
-        "keywords": "",
-        "noindex": false,
-        "canonical": ""
-      },
-      "cdn": {
-        "css": [],
-        "js": []
-      }
-    }
-  }
-}
+{
+  "site_name": "Site name",
+  "title": "Site title",
+  "description": "Site description",
+  "keywords": "keyword1, keyword2, keyword3",
+  "domain": "yoursite.com",
+  "url": "https://yoursite.com",
+  "lang": "en",
+  "author": "Name and surname",
+  "data_bs_theme": "dark",
+  "theme_color": {
+    "light": "#ffffff",
+    "dark": "#0d1117"
+  },
+  "favicon": "/assets/brand/favicon.svg",
+  "logo": "/assets/brand/logo.svg",
+  "legal": {
+    "privacy": "",
+    "cookie": "",
+    "cookieControls": "",
+    "terms": "",
+    "copyright": {
+      "year": "2026",
+      "text": "All rights reserved."
+    }
+  },
+  "pages": {
+    "404": {
+      "seo": {
+        "title": "404 - Not found",
+        "keywords": "",
+        "noindex": true,
+        "canonical": ""
+      },
+      "cdn": {
+        "css": [],
+        "js": []
+      }
+    },
+    "homepage": {
+      "seo": {
+        "title": "Homepage",
+        "description": "Description",
+        "keywords": "",
+        "noindex": false,
+        "canonical": ""
+      },
+      "cdn": {
+        "css": [],
+        "js": []
+      }
+    }
+  }
+}

package/src/frontend/web.config

@@ -1,27 +1,55 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<configuration>
-    <system.webServer>
-        <directoryBrowse enabled="false" />
-
-        <httpErrors errorMode="Custom" existingResponse="Replace">
-            <remove statusCode="403" />
-            <remove statusCode="404" />
-            <error statusCode="403" path="/404.html" responseMode="ExecuteURL" />
-            <error statusCode="404" path="/404.html" responseMode="ExecuteURL" />
-        </httpErrors>
-
-        <rewrite>
-            <rules>
-                <rule name="BlockFiles" stopProcessing="true">
-                    <match url="^(web\.config|\.htaccess|\..*)$" ignoreCase="true" />
-                    <action type="Rewrite" url="/404.html" />
-                </rule>
-
-                <rule name="ApiRoute" stopProcessing="true">
-                    <match url="^api/(.*)$" ignoreCase="true" />
-                    <action type="Rewrite" url="backend/_core/index.php" appendQueryString="true" />
-                </rule>
-            </rules>
-        </rewrite>
-    </system.webServer>
-</configuration>
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  IIS config for a Nibula site — covers BOTH backends.
+
+  IIS (like Apache, unlike nginx) cannot health-check an upstream, so it cannot
+  auto-fall back from Node to PHP. URL Rewrite processes rules top-down and the
+  first match with stopProcessing="true" wins:
+
+    - "ApiToNode" wins if present -> /api is reverse-proxied to the Node backend
+      (requires the Application Request Routing + URL Rewrite modules, with proxy
+      enabled: ARR > Server Proxy Settings > Enable proxy).
+    - To use the PHP backend instead, remove or comment the "ApiToNode" rule;
+      "ApiToPhp" then rewrites /api to the PHP front controller.
+
+  On Windows shared hosting without ARR, keep only "ApiToPhp".
+-->
+<configuration>
+    <system.webServer>
+        <rewrite>
+            <rules>
+
+                <!-- Block sensitive files -->
+                <rule name="BlockSensitive" stopProcessing="true">
+                    <match url="^(web\.config|\..*)$" ignoreCase="true" />
+                    <action type="CustomResponse" statusCode="404" />
+                </rule>
+
+                <!-- Node backend (requires ARR). Remove this rule to use PHP. -->
+                <rule name="ApiToNode" stopProcessing="true">
+                    <match url="^api/(.*)" ignoreCase="true" />
+                    <action type="Rewrite" url="http://127.0.0.1:3000/api/{R:1}" appendQueryString="true" />
+                    <serverVariables>
+                        <set name="HTTP_X_FORWARDED_PROTO" value="https" />
+                    </serverVariables>
+                </rule>
+
+                <!-- PHP backend fallback: rewrite /api to the PHP front controller. -->
+                <rule name="ApiToPhp" stopProcessing="true">
+                    <match url="^api/(.*)" ignoreCase="true" />
+                    <action type="Rewrite" url="backend/_core/index.php" appendQueryString="true" />
+                </rule>
+
+            </rules>
+        </rewrite>
+
+        <directoryBrowse enabled="false" />
+
+        <httpErrors errorMode="Custom" existingResponse="Replace">
+            <remove statusCode="404" />
+            <remove statusCode="403" />
+            <error statusCode="404" path="/404.html" responseMode="ExecuteURL" />
+            <error statusCode="403" path="/404.html" responseMode="ExecuteURL" />
+        </httpErrors>
+    </system.webServer>
+</configuration>