nibula 2.5.0 → 3.0.1

package/src/backend/core/index.js

@@ -0,0 +1,329 @@
+"use strict";
+
+const DEBUG_HEADER = "Debug-Mode";
+const DEBUG_HEADER_VALUE = "true";
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const { createResponse, HALT } = require("./modules/Response");
+const { createValidator } = require("./modules/Validate");
+const { createRateLimiter } = require("./modules/RateLimiter");
+const { loadConfig, isDebug, handleException } = require("./init");
+
+const CORE_PATH = __dirname;
+
+const URL_PREFIX = "/api";
+const ENDPOINT_EXTENSION = ".js";
+const ERROR_PAGE = "404.html";
+const ENDPOINTS_FOLDER = "endpoints";
+const PUBLIC_FOLDER = "public";
+const PROTECTED_FOLDER = "protected";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = "3000";
+const RATE_LIMIT_REQUESTS = 60;
+const RATE_LIMIT_WINDOW_SECONDS = 60;
+
+const STATUS_NO_CONTENT = 204;
+const STATUS_BAD_REQUEST = 400;
+const STATUS_UNAUTHORIZED = 401;
+const STATUS_NOT_FOUND = 404;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+const STATUS_SERVER_ERROR = 500;
+
+const ALLOWED_METHODS = "GET, POST, PUT, PATCH, DELETE, OPTIONS";
+const ALLOWED_HEADERS = "Content-Type, X-Api-Key";
+const JSON_CONTENT_TYPE = "application/json; charset=UTF-8";
+const HTML_CONTENT_TYPE = "text/html; charset=UTF-8";
+
+const config = loadConfig();
+const debugMode = isDebug(config);
+
+const DOCUMENT_ROOT =
+  process.env.DOCUMENT_ROOT || path.join(CORE_PATH, "..", "..");
+const basePublic = path.join(CORE_PATH, "..", ENDPOINTS_FOLDER, PUBLIC_FOLDER);
+const baseProtected = path.join(
+  CORE_PATH,
+  "..",
+  ENDPOINTS_FOLDER,
+  PROTECTED_FOLDER,
+);
+
+function hashEquals(known, given) {
+  const knownBuffer = Buffer.from(String(known));
+  const givenBuffer = Buffer.from(String(given));
+
+  if (knownBuffer.length !== givenBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(knownBuffer, givenBuffer);
+}
+
+function sendErrorPage(res) {
+  const errorPage = path.join(DOCUMENT_ROOT, ERROR_PAGE);
+
+  res.statusCode = STATUS_NOT_FOUND;
+  res.setHeader("Content-Type", HTML_CONTENT_TYPE);
+  res.end(
+    fs.existsSync(errorPage)
+      ? fs.readFileSync(errorPage)
+      : "<h1>404 Not Found</h1>The requested URL was not found on this server.",
+  );
+}
+
+function parseSegments(pathname) {
+  const uri = pathname
+    .replace(new RegExp(`^${URL_PREFIX}`), "")
+    .replace(/\/+$/, "");
+
+  return uri.split("/").filter((segment) => segment !== "");
+}
+
+function resolveEndpoint(segments) {
+  const remaining = segments.slice();
+  const params = [];
+
+  while (remaining.length > 0) {
+    const relativePath = remaining.join("/") + ENDPOINT_EXTENSION;
+
+    const publicCandidate = path.join(basePublic, relativePath);
+    if (fs.existsSync(publicCandidate)) {
+      return {
+        file: publicCandidate,
+        base: basePublic,
+        isProtected: false,
+        params,
+      };
+    }
+
+    const protectedCandidate = path.join(baseProtected, relativePath);
+    if (fs.existsSync(protectedCandidate)) {
+      return {
+        file: protectedCandidate,
+        base: baseProtected,
+        isProtected: true,
+        params,
+      };
+    }
+
+    params.unshift(remaining.pop());
+  }
+
+  return null;
+}
+
+function toEndpointKey(file, base) {
+  return file
+    .split(path.sep)
+    .join("/")
+    .replace(base.split(path.sep).join("/"), "")
+    .replace(new RegExp(`\\${ENDPOINT_EXTENSION}$`), "")
+    .replace(/^\//, "");
+}
+
+function applySecurityHeaders(res) {
+  res.setHeader("Content-Type", JSON_CONTENT_TYPE);
+  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", ALLOWED_METHODS);
+  res.setHeader("Access-Control-Allow-Headers", ALLOWED_HEADERS);
+
+  if (debugMode) {
+    res.setHeader(DEBUG_HEADER, DEBUG_HEADER_VALUE);
+  }
+}
+
+function applyCors(res, endpointKey, origin) {
+  const allowedOrigins =
+    config.CUSTOM_ENDPOINT_ORIGINS?.[endpointKey] ??
+    config.GENERAL_ALLOWED_ORIGINS ??
+    [];
+
+  if (origin !== "" && allowedOrigins.includes(origin)) {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+
+    return;
+  }
+
+  if (allowedOrigins.includes("*")) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+  }
+}
+
+function authorize(endpointKey, givenKey, Response) {
+  const validKey =
+    config.CUSTOM_ENDPOINT_KEYS?.[endpointKey] ?? config.GENERAL_API_KEY ?? "";
+
+  if (validKey === "" || !hashEquals(validKey, givenKey)) {
+    Response.error(
+      "Unauthorized. X-Api-Key is incorrect or missing",
+      STATUS_UNAUTHORIZED,
+    );
+  }
+}
+
+function clientAddress(req) {
+  const forwarded = (req.headers["x-forwarded-for"] || "").split(",")[0].trim();
+
+  return forwarded || req.socket.remoteAddress || "";
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    const chunks = [];
+
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8");
+      let json = {};
+
+      try {
+        json = raw ? JSON.parse(raw) : {};
+      } catch (error) {
+        json = {};
+      }
+
+      resolve({ raw, json });
+    });
+    req.on("error", () => resolve({ raw: "", json: {} }));
+  });
+}
+
+function loadHandlers(file) {
+  if (debugMode) {
+    delete require.cache[require.resolve(file)];
+  }
+
+  return require(file);
+}
+
+async function dispatch(file, context, Response) {
+  const handlers = loadHandlers(file);
+
+  if (typeof handlers === "function") {
+    await handlers(context);
+
+    return;
+  }
+
+  const methodHandler = handlers[context.method.toLowerCase()];
+
+  if (typeof methodHandler !== "function") {
+    Response.error("Method not allowed", STATUS_METHOD_NOT_ALLOWED);
+  }
+
+  await methodHandler(context);
+}
+
+async function handleRequest(req, res) {
+  const Response = createResponse(res);
+
+  try {
+    const parsedUrl = new URL(req.url, `http://${DEFAULT_HOST}`);
+    const segments = parseSegments(parsedUrl.pathname);
+
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+      Response.error("Bad Request", STATUS_BAD_REQUEST);
+    }
+
+    const endpoint = resolveEndpoint(segments);
+
+    if (endpoint === null) {
+      sendErrorPage(res);
+
+      return;
+    }
+
+    const endpointKey = toEndpointKey(endpoint.file, endpoint.base);
+
+    applySecurityHeaders(res);
+    applyCors(res, endpointKey, req.headers.origin || "");
+
+    if (req.method === "OPTIONS") {
+      res.statusCode = STATUS_NO_CONTENT;
+      res.end();
+
+      return;
+    }
+
+    createRateLimiter(Response, res).check(
+      clientAddress(req),
+      RATE_LIMIT_REQUESTS,
+      RATE_LIMIT_WINDOW_SECONDS,
+    );
+
+    if (endpoint.isProtected) {
+      authorize(endpointKey, req.headers["x-api-key"] || "", Response);
+    }
+
+    const body = await readBody(req);
+
+    await dispatch(
+      endpoint.file,
+      {
+        method: req.method,
+        requestParams: endpoint.params,
+        query: Object.fromEntries(parsedUrl.searchParams),
+        body: body.json,
+        rawBody: body.raw,
+        headers: req.headers,
+        Response,
+        Validate: createValidator(Response),
+        config,
+        CORE_PATH,
+        req,
+        res,
+      },
+      Response,
+    );
+
+    if (!res.writableEnded) {
+      res.end();
+    }
+  } catch (error) {
+    if (error === HALT) {
+      return;
+    }
+
+    try {
+      handleException(error, config, Response);
+    } catch (inner) {
+      if (inner === HALT) {
+        return;
+      }
+
+      if (!res.writableEnded) {
+        res.statusCode = STATUS_SERVER_ERROR;
+        res.end(
+          JSON.stringify({
+            status: "error",
+            message: "Internal server error",
+            code: STATUS_SERVER_ERROR,
+          }),
+        );
+      }
+    }
+  }
+}
+
+const host = process.env.HOST || DEFAULT_HOST;
+const port = parseInt(process.env.PORT || DEFAULT_PORT, 10);
+
+const server = http.createServer(handleRequest);
+
+server.listen(port, host, () => {
+  console.log(`Backend started listening on http://${host}:${port}`);
+  if (debugMode) {
+    console.log(
+      'WARNING: error details are exposed in responses. Set APP_ENV to "production" in config.js before publishing.',
+    );
+  }
+});
+
+module.exports = server;

package/src/backend/core/index.php

@@ -0,0 +1,207 @@
+<?php
+
+declare(strict_types=1);
+
+define('CORE_PATH', __DIR__);
+
+const DEBUG_HEADER = 'Debug-Mode';
+const DEBUG_HEADER_VALUE = 'true';
+
+const URL_PREFIX = '/api';
+const ENDPOINT_EXTENSION = '.php';
+const ERROR_PAGE = '404.html';
+const ENDPOINTS_FOLDER = 'endpoints';
+const PUBLIC_FOLDER = 'public';
+const PROTECTED_FOLDER = 'protected';
+
+const RATE_LIMIT_REQUESTS = 60;
+const RATE_LIMIT_WINDOW_SECONDS = 60;
+
+const STATUS_NO_CONTENT = 204;
+const STATUS_BAD_REQUEST = 400;
+const STATUS_UNAUTHORIZED = 401;
+const STATUS_NOT_FOUND = 404;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+
+const ALLOWED_METHODS = 'GET, POST, PUT, PATCH, DELETE, OPTIONS';
+const ALLOWED_HEADERS = 'Content-Type, X-Api-Key';
+const JSON_CONTENT_TYPE = 'application/json; charset=UTF-8';
+const HTML_CONTENT_TYPE = 'text/html; charset=UTF-8';
+
+require_once __DIR__ . '/init.php';
+require_once __DIR__ . '/modules/Response.php';
+require_once __DIR__ . '/modules/RateLimiter.php';
+require_once __DIR__ . '/modules/Validate.php';
+
+$basePublic    = __DIR__ . '/../' . ENDPOINTS_FOLDER . '/' . PUBLIC_FOLDER . '/';
+$baseProtected = __DIR__ . '/../' . ENDPOINTS_FOLDER . '/' . PROTECTED_FOLDER . '/';
+
+function parseSegments(string $pathname): array
+{
+    $uri = rtrim(preg_replace('#^' . URL_PREFIX . '#', '', $pathname), '/');
+
+    return array_values(array_filter(explode('/', $uri)));
+}
+
+function resolveEndpoint(array $segments, string $basePublic, string $baseProtected): ?array
+{
+    $remaining = $segments;
+    $params    = [];
+
+    while (count($remaining) > 0) {
+        $relativePath = implode('/', $remaining) . ENDPOINT_EXTENSION;
+
+        if (file_exists($basePublic . $relativePath)) {
+            return [
+                'file'        => $basePublic . $relativePath,
+                'base'        => $basePublic,
+                'isProtected' => false,
+                'params'      => $params,
+            ];
+        }
+
+        if (file_exists($baseProtected . $relativePath)) {
+            return [
+                'file'        => $baseProtected . $relativePath,
+                'base'        => $baseProtected,
+                'isProtected' => true,
+                'params'      => $params,
+            ];
+        }
+
+        array_unshift($params, array_pop($remaining));
+    }
+
+    return null;
+}
+
+function toEndpointKey(string $file, string $base): string
+{
+    $normalizedBase = str_replace('\\', '/', $base);
+    $normalizedFile = str_replace('\\', '/', $file);
+
+    return preg_replace('#\\' . ENDPOINT_EXTENSION . '$#', '', str_replace($normalizedBase, '', $normalizedFile));
+}
+
+function sendErrorPage(): never
+{
+    http_response_code(STATUS_NOT_FOUND);
+    header_remove('WWW-Authenticate');
+    header_remove('X-Powered-By');
+    header('Content-Type: ' . HTML_CONTENT_TYPE);
+
+    $errorPage = ($_SERVER['DOCUMENT_ROOT'] ?? '') . '/' . ERROR_PAGE;
+
+    if (!file_exists($errorPage)) {
+        $errorPage = __DIR__ . '/../../' . ERROR_PAGE;
+    }
+
+    echo file_exists($errorPage)
+        ? file_get_contents($errorPage)
+        : '<h1>404 Not Found</h1>The requested URL was not found on this server.';
+
+    exit;
+}
+
+function applySecurityHeaders(bool $isDebug): void
+{
+    header('Content-Type: ' . JSON_CONTENT_TYPE);
+    header_remove('WWW-Authenticate');
+    header_remove('X-Powered-By');
+    header('X-Content-Type-Options: nosniff');
+    header('X-Frame-Options: DENY');
+    header('Referrer-Policy: strict-origin-when-cross-origin');
+    header('Access-Control-Allow-Methods: ' . ALLOWED_METHODS);
+    header('Access-Control-Allow-Headers: ' . ALLOWED_HEADERS);
+
+    if ($isDebug) {
+        header(DEBUG_HEADER . ': ' . DEBUG_HEADER_VALUE);
+    }
+}
+
+function applyCors(array $config, string $endpointKey, string $origin): void
+{
+    $allowedOrigins = $config['CUSTOM_ENDPOINT_ORIGINS'][$endpointKey]
+        ?? $config['GENERAL_ALLOWED_ORIGINS']
+        ?? [];
+
+    if ($origin !== '' && in_array($origin, $allowedOrigins, true)) {
+        header('Access-Control-Allow-Origin: ' . $origin);
+        header('Vary: Origin');
+
+        return;
+    }
+
+    if (in_array('*', $allowedOrigins, true)) {
+        header('Access-Control-Allow-Origin: *');
+    }
+}
+
+function authorize(array $config, string $endpointKey, string $givenKey): void
+{
+    $validKey = $config['CUSTOM_ENDPOINT_KEYS'][$endpointKey] ?? $config['GENERAL_API_KEY'] ?? '';
+
+    if ($validKey === '' || !hash_equals($validKey, $givenKey)) {
+        Response::error('Unauthorized. X-Api-Key is incorrect or missing', STATUS_UNAUTHORIZED);
+    }
+}
+
+function dispatch(string $endpointFile, array $request): void
+{
+    $handlers = require $endpointFile;
+
+    if (!is_array($handlers)) {
+        return;
+    }
+
+    $methodHandler = $handlers[strtolower($request['method'])] ?? null;
+
+    if (!is_callable($methodHandler)) {
+        Response::error('Method not allowed', STATUS_METHOD_NOT_ALLOWED);
+    }
+
+    $methodHandler($request);
+}
+
+$method   = $_SERVER['REQUEST_METHOD'];
+$segments = parseSegments(parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH));
+
+foreach ($segments as $segment) {
+    if ($segment === '.' || $segment === '..') {
+        Response::error('Bad Request', STATUS_BAD_REQUEST);
+    }
+}
+
+$endpoint = resolveEndpoint($segments, $basePublic, $baseProtected);
+
+if ($endpoint === null) {
+    sendErrorPage();
+}
+
+$endpointKey = toEndpointKey($endpoint['file'], $endpoint['base']);
+
+applySecurityHeaders($isDebug);
+applyCors($config, $endpointKey, $_SERVER['HTTP_ORIGIN'] ?? '');
+
+if ($method === 'OPTIONS') {
+    http_response_code(STATUS_NO_CONTENT);
+    exit;
+}
+
+RateLimiter::check($_SERVER['REMOTE_ADDR'] ?? '', RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW_SECONDS);
+
+if ($endpoint['isProtected']) {
+    authorize($config, $endpointKey, $_SERVER['HTTP_X_API_KEY'] ?? '');
+}
+
+$rawBody = file_get_contents('php://input');
+
+dispatch($endpoint['file'], [
+    'method'        => $method,
+    'requestParams' => $endpoint['params'],
+    'query'         => $_GET,
+    'body'          => json_decode($rawBody, true) ?? [],
+    'rawBody'       => $rawBody,
+    'headers'       => function_exists('getallheaders') ? getallheaders() : [],
+    'config'        => $config,
+]);

package/src/backend/core/init.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_FILE = "config.js";
+const EXAMPLE_CONFIG_FILE = "example.config.js";
+const DEFAULT_ENVIRONMENT = "production";
+
+function loadConfig() {
+  const backendRoot = path.join(__dirname, "..");
+  const configPath = path.join(backendRoot, CONFIG_FILE);
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `Missing ${CONFIG_FILE}. Copy ${EXAMPLE_CONFIG_FILE} to ${CONFIG_FILE} in ${backendRoot} and fill in your values.`,
+    );
+  }
+
+  return require(configPath);
+}
+
+function isDebug(config) {
+  return (config.APP_ENV ?? DEFAULT_ENVIRONMENT) !== DEFAULT_ENVIRONMENT;
+}
+
+function handleException(exception, config, Response) {
+  const debugMode = isDebug(config);
+
+  Response.error(
+    debugMode ? exception.message : "Internal server error",
+    500,
+    debugMode ? { stack: exception.stack } : null,
+  );
+}
+
+module.exports = { loadConfig, isDebug, handleException };

package/src/backend/core/init.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/vendor/autoload.php';
+require_once __DIR__ . '/modules/Response.php';
+
+const CONFIG_FILE = 'config.php';
+const EXAMPLE_CONFIG_FILE = 'example.config.php';
+const DEFAULT_ENVIRONMENT = 'production';
+
+$backendRoot = dirname(__DIR__);
+$configPath  = $backendRoot . '/' . CONFIG_FILE;
+
+if (!file_exists($configPath)) {
+    http_response_code(500);
+    header('Content-Type: application/json; charset=UTF-8');
+    echo json_encode([
+        'status'  => 'error',
+        'message' => 'Missing ' . CONFIG_FILE . '. Copy ' . EXAMPLE_CONFIG_FILE . ' to ' . CONFIG_FILE . ' in ' . $backendRoot . ' and fill in your values.',
+        'code'    => 500,
+    ]);
+    exit;
+}
+
+$config  = require $configPath;
+$isDebug = ($config['APP_ENV'] ?? DEFAULT_ENVIRONMENT) !== DEFAULT_ENVIRONMENT;
+
+set_exception_handler(function (Throwable $exception) use ($isDebug) {
+    Response::error(
+        $isDebug ? $exception->getMessage() : 'Internal server error',
+        500,
+        $isDebug ? [
+            'file' => $exception->getFile(),
+            'line' => $exception->getLine(),
+            'warning' => 'Error details are exposed. Set APP_ENV to "production" in config.php before publishing.',
+        ] : null
+    );
+});
+
+set_error_handler(function (int $severity, string $message, string $file, int $line) {
+    if (!(error_reporting() & $severity)) {
+        return false;
+    }
+    throw new ErrorException($message, 0, $severity, $file, $line);
+});
+
+if ($isDebug) {
+    ini_set('display_errors', '1');
+    error_reporting(E_ALL);
+} else {
+    ini_set('display_errors', '0');
+    error_reporting(0);
+}

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

@@ -0,0 +1,55 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const CACHE_FOLDER = "cache";
+const CACHE_PREFIX = "rl_";
+const CACHE_EXTENSION = ".json";
+const FOLDER_PERMISSIONS = 0o755;
+const TOO_MANY_REQUESTS = 429;
+const MILLISECONDS_PER_SECOND = 1000;
+
+function createRateLimiter(Response, res) {
+  return {
+    check(ip, maxRequests, windowSeconds) {
+      const cacheDir = path.join(__dirname, "..", "..", CACHE_FOLDER);
+
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true, mode: FOLDER_PERMISSIONS });
+      }
+
+      const hash = crypto.createHash("md5").update(ip).digest("hex");
+      const cacheFile = path.join(
+        cacheDir,
+        CACHE_PREFIX + hash + CACHE_EXTENSION,
+      );
+      const now = Math.floor(Date.now() / MILLISECONDS_PER_SECOND);
+
+      let timestamps = [];
+
+      if (fs.existsSync(cacheFile)) {
+        try {
+          timestamps = JSON.parse(fs.readFileSync(cacheFile, "utf8")) || [];
+        } catch (error) {
+          timestamps = [];
+        }
+      }
+
+      timestamps = timestamps.filter(
+        (timestamp) => timestamp > now - windowSeconds,
+      );
+      timestamps.push(now);
+
+      fs.writeFileSync(cacheFile, JSON.stringify(timestamps));
+
+      if (timestamps.length > maxRequests) {
+        res.setHeader("Retry-After", String(windowSeconds));
+        Response.error("Too Many Requests", TOO_MANY_REQUESTS);
+      }
+    },
+  };
+}
+
+module.exports = { createRateLimiter };