nibula 2.5.0 → 3.0.0

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 };

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

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+class RateLimiter
+{
+    private const CACHE_FOLDER = '/../../cache';
+    private const CACHE_PREFIX = 'rl_';
+    private const CACHE_EXTENSION = '.json';
+    private const FOLDER_PERMISSIONS = 0755;
+    private const TOO_MANY_REQUESTS = 429;
+
+    public static function check(string $ip, int $maxRequests, int $windowSeconds): void
+    {
+        $cacheDir = __DIR__ . self::CACHE_FOLDER;
+
+        if (!is_dir($cacheDir)) {
+            mkdir($cacheDir, self::FOLDER_PERMISSIONS, true);
+        }
+
+        $cacheFile = $cacheDir . '/' . self::CACHE_PREFIX . md5($ip) . self::CACHE_EXTENSION;
+        $now       = time();
+        $timestamps = [];
+
+        if (file_exists($cacheFile)) {
+            $timestamps = json_decode(file_get_contents($cacheFile), true) ?: [];
+        }
+
+        $timestamps = array_filter($timestamps, fn($timestamp) => $timestamp > ($now - $windowSeconds));
+        $timestamps[] = $now;
+
+        file_put_contents($cacheFile, json_encode(array_values($timestamps)), LOCK_EX);
+
+        if (count($timestamps) > $maxRequests) {
+            header('Retry-After: ' . $windowSeconds);
+            Response::error('Too Many Requests', self::TOO_MANY_REQUESTS);
+        }
+    }
+}

package/src/backend/{_core → core}/modules/Response.js

@@ -2,17 +2,19 @@
 
 const HALT = Symbol("RESPONSE_HALT");
 
-function jsonEncode(obj) {
-  return JSON.stringify(obj);
-}
+const STATUS_OK = 200;
+const STATUS_BAD_REQUEST = 400;
+const STATUS_NO_CONTENT = 204;
+
+const JSON_CONTENT_TYPE = "application/json; charset=UTF-8";
 
 function createResponse(res) {
   return {
-    success(data = null, code = 200) {
+    success(data = null, code = STATUS_OK) {
       res.statusCode = code;
-      res.setHeader("Content-Type", "application/json; charset=UTF-8");
+      res.setHeader("Content-Type", JSON_CONTENT_TYPE);
       res.end(
-        jsonEncode({
+        JSON.stringify({
           status: "success",
           data: data,
         }),
@@ -20,23 +22,26 @@ function createResponse(res) {
       throw HALT;
     },
 
-    error(message, code = 400, details = null) {
+    error(message, code = STATUS_BAD_REQUEST, details = null) {
       res.statusCode = code;
-      res.setHeader("Content-Type", "application/json; charset=UTF-8");
+      res.setHeader("Content-Type", JSON_CONTENT_TYPE);
+
       const body = {
         status: "error",
         message: message,
         code: code,
       };
+
       if (details !== null) {
         body.details = details;
       }
-      res.end(jsonEncode(body));
+
+      res.end(JSON.stringify(body));
       throw HALT;
     },
 
     noContent() {
-      res.statusCode = 204;
+      res.statusCode = STATUS_NO_CONTENT;
       res.end();
       throw HALT;
     },

package/src/backend/{_core → core}/modules/Response.php

@@ -2,48 +2,45 @@
 
 declare(strict_types=1);
 
-if (!defined('CORE_ACCESS')) {
-    $errorPage = $_SERVER['DOCUMENT_ROOT'] . '/404.html';
-    http_response_code(404);
-    if (file_exists($errorPage)) {
-        header('Content-Type: text/html; charset=UTF-8');
-        echo file_get_contents($errorPage);
-    } else {
-        echo "404 Not Found";
-    }
-    exit;
-}
-
 class Response
 {
-    public static function success(mixed $data = null, int $code = 200): never
+    private const STATUS_OK = 200;
+    private const STATUS_BAD_REQUEST = 400;
+    private const STATUS_NO_CONTENT = 204;
+
+    private const JSON_FLAGS = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;
+
+    public static function success(mixed $data = null, int $code = self::STATUS_OK): never
     {
         http_response_code($code);
         echo json_encode([
             'status' => 'success',
             'data'   => $data,
-        ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+        ], self::JSON_FLAGS);
         exit;
     }
 
-    public static function error(string $message, int $code = 400, mixed $details = null): never
+    public static function error(string $message, int $code = self::STATUS_BAD_REQUEST, mixed $details = null): never
     {
         http_response_code($code);
+
         $body = [
             'status'  => 'error',
             'message' => $message,
             'code'    => $code,
         ];
+
         if ($details !== null) {
             $body['details'] = $details;
         }
-        echo json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+
+        echo json_encode($body, self::JSON_FLAGS);
         exit;
     }
 
     public static function noContent(): never
     {
-        http_response_code(204);
+        http_response_code(self::STATUS_NO_CONTENT);
         exit;
     }
 }

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

@@ -0,0 +1,56 @@
+"use strict";
+
+const VALIDATION_STATUS = 422;
+const EMAIL_PATTERN = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const INTEGER_PATTERN = /^\d+$/;
+
+function createValidator(Response) {
+  const validator = {
+    required(value, field) {
+      if (value === undefined || value === null || value === "") {
+        Response.error(`The ${field} field is required`, VALIDATION_STATUS);
+      }
+      return value;
+    },
+
+    integer(value, field) {
+      validator.required(value, field);
+
+      if (!INTEGER_PATTERN.test(String(value))) {
+        Response.error(
+          `The ${field} field must be a number`,
+          VALIDATION_STATUS,
+        );
+      }
+      return Number(value);
+    },
+
+    email(value, field) {
+      validator.required(value, field);
+
+      if (!EMAIL_PATTERN.test(String(value))) {
+        Response.error(
+          `The ${field} field must be a valid email`,
+          VALIDATION_STATUS,
+        );
+      }
+      return String(value);
+    },
+
+    minLength(value, field, length) {
+      validator.required(value, field);
+
+      if (String(value).length < length) {
+        Response.error(
+          `The ${field} field must be at least ${length} characters`,
+          VALIDATION_STATUS,
+        );
+      }
+      return String(value);
+    },
+  };
+
+  return validator;
+}
+
+module.exports = { createValidator };

package/src/backend/core/modules/Validate.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+class Validate
+{
+    private const VALIDATION_STATUS = 422;
+    private const EMAIL_PATTERN = '/^[^@\s]+@[^@\s]+\.[^@\s]+$/';
+    private const INTEGER_PATTERN = '/^\d+$/';
+
+    public static function required(mixed $value, string $field): mixed
+    {
+        if ($value === null || $value === '') {
+            Response::error("The {$field} field is required", self::VALIDATION_STATUS);
+        }
+
+        return $value;
+    }
+
+    public static function integer(mixed $value, string $field): int
+    {
+        self::required($value, $field);
+
+        if (!preg_match(self::INTEGER_PATTERN, (string) $value)) {
+            Response::error("The {$field} field must be a number", self::VALIDATION_STATUS);
+        }
+
+        return (int) $value;
+    }
+
+    public static function email(mixed $value, string $field): string
+    {
+        self::required($value, $field);
+
+        if (!preg_match(self::EMAIL_PATTERN, (string) $value)) {
+            Response::error("The {$field} field must be a valid email", self::VALIDATION_STATUS);
+        }
+
+        return (string) $value;
+    }
+
+    public static function minLength(mixed $value, string $field, int $length): string
+    {
+        self::required($value, $field);
+
+        if (mb_strlen((string) $value) < $length) {
+            Response::error("The {$field} field must be at least {$length} characters", self::VALIDATION_STATUS);
+        }
+
+        return (string) $value;
+    }
+}

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

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * Export one function per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself.
+ *
+ * Each function receives the request context:
+ *   method         the HTTP method, as a string
+ *   requestParams  extra URL segments after the endpoint path
+ *   query          query string values: ?page=2 gives { page: '2' }
+ *   body           the JSON body, already parsed into an object
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.js
+ *   Response       sends the answer
+ *   Validate       checks incoming values
+ *
+ * Response.success(data, code) and Response.error(message, code) send the
+ * answer and stop the request: nothing after them runs.
+ */
+
+module.exports = {
+  get: ({ requestParams, query, Response }) => {
+    Response.success({
+      message: "Endpoint is working",
+      params: requestParams,
+      query: query,
+    });
+  },
+
+  post: ({ body, Response, Validate }) => {
+    // Validate stops the request with a 422 when a value is missing or
+    // malformed, so the returned value is always safe to use.
+    const name = Validate.required(body.name, "name");
+    const email = Validate.email(body.email, "email");
+
+    Response.success({ name, email }, 201);
+  },
+};