nibula 1.1.0 → 1.1.2

package/src/backend/_core/index.js

@@ -1,267 +1,267 @@
-'use strict';
-
-/**
- * Mirror of src/backend/_core/index.php  (the front controller).
- *
- * PHP was invoked once per request by the web server through PHP-FPM. Node is
- * the server itself, so this file boots an HTTP listener and runs the exact same
- * pipeline for every request:
- *
- *   1. request parsing (strip /api prefix, split segments, reject . / ..)
- *   2. endpoint resolution (dynamic routing with subdirectories + route params)
- *   3. headers + CORS
- *   4. rate limiting
- *   5. authentication guard for protected endpoints
- *   6. dispatch to the matched endpoint file
- *
- * Endpoints keep the same authoring style as PHP: a file that receives
- * { method, requestParams, Response, ... } and calls Response.success/error.
- */
-
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const { createResponse, HALT } = require('./modules/Response');
-const RateLimiter = require('./modules/RateLimiter');
-const { loadConfig, handleException } = require('./init');
-
-const CORE_PATH = __dirname;
-
-// Load configuration once (init.php loaded it per invocation; here per process).
-const config = loadConfig();
-
-// Environment: mirror the display_errors toggle by picking the debug flag.
-const APP_ENV = config.APP_ENV || 'production';
-
-// Where to look for the 404.html generated by the static build.
-// In a Nibula build the backend lives at out/backend/, so the site root (out/)
-// is two levels up from _core. We default to that, so 404.html is found without
-// any extra configuration; override with the DOCUMENT_ROOT env var if needed.
-// (equivalent of $_SERVER['DOCUMENT_ROOT'] in the PHP front controller).
-const DOCUMENT_ROOT = process.env.DOCUMENT_ROOT || path.join(CORE_PATH, '..', '..');
-
-const basePublic = path.join(CORE_PATH, '..', 'api', 'public');
-const baseProtected = path.join(CORE_PATH, '..', 'api', 'protected');
-
-/**
- * hash_equals equivalent: constant-time string comparison, safe on unequal
- * lengths (timingSafeEqual throws if buffers differ in length).
- */
-function hashEquals(known, given) {
-    const a = Buffer.from(String(known));
-    const b = Buffer.from(String(given));
-    if (a.length !== b.length) {
-        return false;
-    }
-    return crypto.timingSafeEqual(a, b);
-}
-
-/** Serve the static 404 page if available, else a plain fallback. */
-function send404(res) {
-    res.statusCode = 404;
-    const errorPage = DOCUMENT_ROOT ? path.join(DOCUMENT_ROOT, '404.html') : '';
-    if (errorPage && fs.existsSync(errorPage)) {
-        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
-        res.end(fs.readFileSync(errorPage));
-    } else {
-        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
-        res.end('<h1>404 Not Found</h1>The requested URL was not found on this server.');
-    }
-}
-
-/** Read and JSON-parse the request body (available to endpoints as ctx.body). */
-function readBody(req) {
-    return new Promise((resolve) => {
-        const chunks = [];
-        req.on('data', (c) => chunks.push(c));
-        req.on('end', () => {
-            const raw = Buffer.concat(chunks).toString('utf8');
-            if (!raw) return resolve({ raw: '', json: null });
-            let json = null;
-            try { json = JSON.parse(raw); } catch (e) { json = null; }
-            resolve({ raw, json });
-        });
-        req.on('error', () => resolve({ raw: '', json: null }));
-    });
-}
-
-async function handleRequest(req, res) {
-    const Response = createResponse(res);
-
-    try {
-        // =====================================================
-        // 1. REQUEST PARSING
-        // =====================================================
-        const method = req.method;
-        const parsedUrl = new URL(req.url, 'http://localhost');
-        let uri = parsedUrl.pathname;
-
-        // Strip a leading /api, then trim trailing slash (rtrim(..., '/') ?: '/').
-        uri = uri.replace(/^\/api/, '');
-        uri = uri.replace(/\/+$/, '');
-        if (uri === '') uri = '/';
-
-        const parts = uri.split('/').filter((p) => p !== '');
-
-        for (const part of parts) {
-            if (part === '..' || part === '.') {
-                Response.error('Bad Request', 400);
-            }
-        }
-
-        // =====================================================
-        // 2. ENDPOINT RESOLUTION (ROUTING WITH SUBDIRECTORIES)
-        // =====================================================
-        let endpointFile = null;
-        let isProtected = false;
-
-        const checkParts = parts.slice();
-        const params = [];
-
-        while (checkParts.length > 0) {
-            const relativePath = checkParts.join('/') + '.js';
-
-            const publicCandidate = path.join(basePublic, relativePath);
-            if (fs.existsSync(publicCandidate)) {
-                endpointFile = publicCandidate;
-                isProtected = false;
-                break;
-            }
-
-            const protectedCandidate = path.join(baseProtected, relativePath);
-            if (fs.existsSync(protectedCandidate)) {
-                endpointFile = protectedCandidate;
-                isProtected = true;
-                break;
-            }
-
-            // No match: peel the last segment as a route param and retry.
-            params.unshift(checkParts.pop());
-        }
-
-        // No endpoint → HTML 404 page.
-        if (!endpointFile) {
-            send404(res);
-            return;
-        }
-
-        // Compute the endpoint path (relative, without extension) used as the key
-        // for CUSTOM_ENDPOINT_KEYS / CUSTOM_ENDPOINT_ORIGINS.
-        const base = isProtected ? baseProtected : basePublic;
-        let endpointPath = endpointFile
-            .split(path.sep).join('/')
-            .replace(base.split(path.sep).join('/'), '')
-            .replace(/\.js$/, '')
-            .replace(/^\//, '');
-
-        // =====================================================
-        // 3. HEADERS AND CORS (only if the endpoint exists)
-        // =====================================================
-        res.setHeader('Content-Type', 'application/json; charset=UTF-8');
-        res.setHeader('X-Content-Type-Options', 'nosniff');
-        res.setHeader('X-Frame-Options', 'DENY');
-        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Api-Key');
-
-        const originsForEndpoint =
-            (config.CUSTOM_ENDPOINT_ORIGINS && config.CUSTOM_ENDPOINT_ORIGINS[endpointPath]) ||
-            config.GENERAL_ALLOWED_ORIGINS ||
-            [];
-
-        const origin = req.headers['origin'] || '';
-
-        if (origin !== '' && originsForEndpoint.includes(origin)) {
-            res.setHeader('Access-Control-Allow-Origin', origin);
-            res.setHeader('Vary', 'Origin');
-        } else if (originsForEndpoint.includes('*')) {
-            res.setHeader('Access-Control-Allow-Origin', '*');
-        }
-
-        if (method === 'OPTIONS') {
-            res.statusCode = 204;
-            res.end();
-            return;
-        }
-
-        // Rate limit: 60 requests / 60 seconds per IP (same defaults as PHP).
-        const ip = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
-            || req.socket.remoteAddress
-            || '';
-        RateLimiter.check(ip, 60, 60, Response, res);
-
-        // =====================================================
-        // 4. AUTHENTICATION GUARD
-        // =====================================================
-        if (isProtected) {
-            const validKey =
-                (config.CUSTOM_ENDPOINT_KEYS && config.CUSTOM_ENDPOINT_KEYS[endpointPath]) ||
-                config.GENERAL_API_KEY ||
-                '';
-            const apiKey = req.headers['x-api-key'] || '';
-
-            if (validKey === '' || !hashEquals(validKey, apiKey)) {
-                Response.error('Unauthorized. X_API_KEY is incorrect or missing', 401);
-            }
-        }
-
-        // =====================================================
-        // 5. DISPATCH
-        // =====================================================
-        const body = await readBody(req);
-
-        // eslint-disable-next-line import/no-dynamic-require, global-require
-        const handler = require(endpointFile);
-
-        const context = {
-            method,               // HTTP method
-            requestParams: params, // leftover URL segments (route params)
-            Response,             // request-bound Response helper
-            query: Object.fromEntries(parsedUrl.searchParams), // parsed query string
-            body: body.json,      // parsed JSON body (or null)
-            rawBody: body.raw,    // raw body string
-            headers: req.headers,
-            req,
-            res,
-            config,
-            CORE_PATH,
-        };
-
-        await handler(context);
-
-        // If the endpoint returned without sending a response, mirror PHP's
-        // implicit end of script: nothing more to do. Close if still open.
-        if (!res.writableEnded) {
-            res.end();
-        }
-    } catch (err) {
-        if (err === HALT) {
-            // A response was already sent; unwind quietly (≈ PHP exit).
-            return;
-        }
-        // set_exception_handler equivalent: any real error → 500.
-        try {
-            handleException(err, config, Response);
-        } catch (inner) {
-            if (inner === HALT) return;
-            if (!res.writableEnded) {
-                res.statusCode = 500;
-                res.end(JSON.stringify({ status: 'error', message: 'Internal server error', code: 500 }));
-            }
-        }
-    }
-}
-
-const HOST = process.env.HOST || '127.0.0.1';
-const PORT = parseInt(process.env.PORT || '3000', 10);
-
-const server = http.createServer(handleRequest);
-
-server.listen(PORT, HOST, () => {
-    // eslint-disable-next-line no-console
-    console.log(`[backend-node] listening on http://${HOST}:${PORT} (env: ${APP_ENV})`);
-});
-
-module.exports = server;
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/index.php  (the front controller).
+ *
+ * PHP was invoked once per request by the web server through PHP-FPM. Node is
+ * the server itself, so this file boots an HTTP listener and runs the exact same
+ * pipeline for every request:
+ *
+ *   1. request parsing (strip /api prefix, split segments, reject . / ..)
+ *   2. endpoint resolution (dynamic routing with subdirectories + route params)
+ *   3. headers + CORS
+ *   4. rate limiting
+ *   5. authentication guard for protected endpoints
+ *   6. dispatch to the matched endpoint file
+ *
+ * Endpoints keep the same authoring style as PHP: a file that receives
+ * { method, requestParams, Response, ... } and calls Response.success/error.
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { createResponse, HALT } = require('./modules/Response');
+const RateLimiter = require('./modules/RateLimiter');
+const { loadConfig, handleException } = require('./init');
+
+const CORE_PATH = __dirname;
+
+// Load configuration once (init.php loaded it per invocation; here per process).
+const config = loadConfig();
+
+// Environment: mirror the display_errors toggle by picking the debug flag.
+const APP_ENV = config.APP_ENV || 'production';
+
+// Where to look for the 404.html generated by the static build.
+// In a Nibula build the backend lives at out/backend/, so the site root (out/)
+// is two levels up from _core. We default to that, so 404.html is found without
+// any extra configuration; override with the DOCUMENT_ROOT env var if needed.
+// (equivalent of $_SERVER['DOCUMENT_ROOT'] in the PHP front controller).
+const DOCUMENT_ROOT = process.env.DOCUMENT_ROOT || path.join(CORE_PATH, '..', '..');
+
+const basePublic = path.join(CORE_PATH, '..', 'api', 'public');
+const baseProtected = path.join(CORE_PATH, '..', 'api', 'protected');
+
+/**
+ * hash_equals equivalent: constant-time string comparison, safe on unequal
+ * lengths (timingSafeEqual throws if buffers differ in length).
+ */
+function hashEquals(known, given) {
+    const a = Buffer.from(String(known));
+    const b = Buffer.from(String(given));
+    if (a.length !== b.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(a, b);
+}
+
+/** Serve the static 404 page if available, else a plain fallback. */
+function send404(res) {
+    res.statusCode = 404;
+    const errorPage = DOCUMENT_ROOT ? path.join(DOCUMENT_ROOT, '404.html') : '';
+    if (errorPage && fs.existsSync(errorPage)) {
+        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
+        res.end(fs.readFileSync(errorPage));
+    } else {
+        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
+        res.end('<h1>404 Not Found</h1>The requested URL was not found on this server.');
+    }
+}
+
+/** Read and JSON-parse the request body (available to endpoints as ctx.body). */
+function readBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (!raw) return resolve({ raw: '', json: null });
+            let json = null;
+            try { json = JSON.parse(raw); } catch (e) { json = null; }
+            resolve({ raw, json });
+        });
+        req.on('error', () => resolve({ raw: '', json: null }));
+    });
+}
+
+async function handleRequest(req, res) {
+    const Response = createResponse(res);
+
+    try {
+        // =====================================================
+        // 1. REQUEST PARSING
+        // =====================================================
+        const method = req.method;
+        const parsedUrl = new URL(req.url, 'http://localhost');
+        let uri = parsedUrl.pathname;
+
+        // Strip a leading /api, then trim trailing slash (rtrim(..., '/') ?: '/').
+        uri = uri.replace(/^\/api/, '');
+        uri = uri.replace(/\/+$/, '');
+        if (uri === '') uri = '/';
+
+        const parts = uri.split('/').filter((p) => p !== '');
+
+        for (const part of parts) {
+            if (part === '..' || part === '.') {
+                Response.error('Bad Request', 400);
+            }
+        }
+
+        // =====================================================
+        // 2. ENDPOINT RESOLUTION (ROUTING WITH SUBDIRECTORIES)
+        // =====================================================
+        let endpointFile = null;
+        let isProtected = false;
+
+        const checkParts = parts.slice();
+        const params = [];
+
+        while (checkParts.length > 0) {
+            const relativePath = checkParts.join('/') + '.js';
+
+            const publicCandidate = path.join(basePublic, relativePath);
+            if (fs.existsSync(publicCandidate)) {
+                endpointFile = publicCandidate;
+                isProtected = false;
+                break;
+            }
+
+            const protectedCandidate = path.join(baseProtected, relativePath);
+            if (fs.existsSync(protectedCandidate)) {
+                endpointFile = protectedCandidate;
+                isProtected = true;
+                break;
+            }
+
+            // No match: peel the last segment as a route param and retry.
+            params.unshift(checkParts.pop());
+        }
+
+        // No endpoint → HTML 404 page.
+        if (!endpointFile) {
+            send404(res);
+            return;
+        }
+
+        // Compute the endpoint path (relative, without extension) used as the key
+        // for CUSTOM_ENDPOINT_KEYS / CUSTOM_ENDPOINT_ORIGINS.
+        const base = isProtected ? baseProtected : basePublic;
+        let endpointPath = endpointFile
+            .split(path.sep).join('/')
+            .replace(base.split(path.sep).join('/'), '')
+            .replace(/\.js$/, '')
+            .replace(/^\//, '');
+
+        // =====================================================
+        // 3. HEADERS AND CORS (only if the endpoint exists)
+        // =====================================================
+        res.setHeader('Content-Type', 'application/json; charset=UTF-8');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Api-Key');
+
+        const originsForEndpoint =
+            (config.CUSTOM_ENDPOINT_ORIGINS && config.CUSTOM_ENDPOINT_ORIGINS[endpointPath]) ||
+            config.GENERAL_ALLOWED_ORIGINS ||
+            [];
+
+        const origin = req.headers['origin'] || '';
+
+        if (origin !== '' && originsForEndpoint.includes(origin)) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Vary', 'Origin');
+        } else if (originsForEndpoint.includes('*')) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+
+        if (method === 'OPTIONS') {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+
+        // Rate limit: 60 requests / 60 seconds per IP (same defaults as PHP).
+        const ip = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
+            || req.socket.remoteAddress
+            || '';
+        RateLimiter.check(ip, 60, 60, Response, res);
+
+        // =====================================================
+        // 4. AUTHENTICATION GUARD
+        // =====================================================
+        if (isProtected) {
+            const validKey =
+                (config.CUSTOM_ENDPOINT_KEYS && config.CUSTOM_ENDPOINT_KEYS[endpointPath]) ||
+                config.GENERAL_API_KEY ||
+                '';
+            const apiKey = req.headers['x-api-key'] || '';
+
+            if (validKey === '' || !hashEquals(validKey, apiKey)) {
+                Response.error('Unauthorized. X_API_KEY is incorrect or missing', 401);
+            }
+        }
+
+        // =====================================================
+        // 5. DISPATCH
+        // =====================================================
+        const body = await readBody(req);
+
+        // eslint-disable-next-line import/no-dynamic-require, global-require
+        const handler = require(endpointFile);
+
+        const context = {
+            method,               // HTTP method
+            requestParams: params, // leftover URL segments (route params)
+            Response,             // request-bound Response helper
+            query: Object.fromEntries(parsedUrl.searchParams), // parsed query string
+            body: body.json,      // parsed JSON body (or null)
+            rawBody: body.raw,    // raw body string
+            headers: req.headers,
+            req,
+            res,
+            config,
+            CORE_PATH,
+        };
+
+        await handler(context);
+
+        // If the endpoint returned without sending a response, mirror PHP's
+        // implicit end of script: nothing more to do. Close if still open.
+        if (!res.writableEnded) {
+            res.end();
+        }
+    } catch (err) {
+        if (err === HALT) {
+            // A response was already sent; unwind quietly (≈ PHP exit).
+            return;
+        }
+        // set_exception_handler equivalent: any real error → 500.
+        try {
+            handleException(err, config, Response);
+        } catch (inner) {
+            if (inner === HALT) return;
+            if (!res.writableEnded) {
+                res.statusCode = 500;
+                res.end(JSON.stringify({ status: 'error', message: 'Internal server error', code: 500 }));
+            }
+        }
+    }
+}
+
+const HOST = process.env.HOST || '127.0.0.1';
+const PORT = parseInt(process.env.PORT || '3000', 10);
+
+const server = http.createServer(handleRequest);
+
+server.listen(PORT, HOST, () => {
+    // eslint-disable-next-line no-console
+    console.log(`[backend-node] listening on http://${HOST}:${PORT} (env: ${APP_ENV})`);
+});
+
+module.exports = server;

package/src/backend/_core/init.js

@@ -1,52 +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 };
+'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 };