nibula 2.5.0 → 3.0.1

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);
+  },
+};

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

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+require_once CORE_PATH . '/modules/Validate.php';
+
+/**
+ * Return one closure per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself.
+ *
+ * Each closure receives $request, an array with:
+ *   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 decoded into an array
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.php
+ *
+ * Response::success($data, $code) and Response::error($message, $code) send the
+ * answer and stop the request: nothing after them runs.
+ */
+
+return [
+    'get' => function (array $request) {
+        Response::success([
+            'message' => 'Endpoint is working',
+            'params'  => $request['requestParams'],
+            'query'   => $request['query'],
+        ]);
+    },
+
+    'post' => function (array $request) {
+        $body = $request['body'];
+
+        // Validate:: stops the request with a 422 when a value is missing or
+        // malformed, so the returned value is always safe to use.
+        $name  = Validate::required($body['name'] ?? null, 'name');
+        $email = Validate::email($body['email'] ?? null, 'email');
+
+        Response::success([
+            'name'  => $name,
+            'email' => $email,
+        ], 201);
+    },
+];

package/src/backend/endpoints/public/example-public.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);
+  },
+};

package/src/backend/endpoints/public/example-public.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+require_once CORE_PATH . '/modules/Validate.php';
+
+/**
+ * Return one closure per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself
+ *
+ * Each closure receives $request, an array with:
+ *   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 decoded into an array
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.php
+ *
+ * Response::success($data, $code) and Response::error($message, $code) send the
+ * answer and stop the request: nothing after them runs
+ */
+
+return [
+    'get' => function (array $request) {
+        Response::success([
+            'message' => 'Endpoint is working',
+            'params'  => $request['requestParams'],
+            'query'   => $request['query'],
+        ]);
+    },
+
+    'post' => function (array $request) {
+        $body = $request['body'];
+
+        // Validate:: stops the request with a 422 when a value is missing or
+        // malformed, so the returned value is always safe to use
+        $name  = Validate::required($body['name'] ?? null, 'name');
+        $email = Validate::email($body['email'] ?? null, 'email');
+
+        Response::success([
+            'name'  => $name,
+            'email' => $email,
+        ], 201);
+    },
+];

package/src/backend/example.config.js

@@ -1,12 +1,16 @@
 "use strict";
 
 /**
- * Mirror of src/backend/example.config.php
- *
- * Copy this file to config.js and fill in real values. config.js is git-ignored and stays local.
+ * Template for config.php, which holds the real values and is git-ignored.
+ * If config.js is missing, copy this file over it.
  */
 
 module.exports = {
+
+  // Environment: "production" hides error details from anyone calling your API
+  // Switch to "debug" while you build to see full error messages
+  APP_ENV: "production",
+
   // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
   GENERAL_API_KEY: "DEFAULT_KEY",
 
@@ -30,7 +34,4 @@ module.exports = {
   DB_NAME: "example_db",
   DB_USER: "root",
   DB_PASS: "",
-
-  // Environment: 'production' hides error details; anything else = debug.
-  APP_ENV: "production",
 };

package/src/backend/example.config.php

@@ -2,12 +2,16 @@
 declare(strict_types=1);
 
 /**
- * Mirror of src/backend/example.config.php
- *
- * Copy this file to config.php and fill in real values. config.php is git-ignored and stays local.
+ * Template for config.php, which holds the real values and is git-ignored.
+ * If config.php is missing, copy this file over it.
  */
 
 return [
+
+    // Environment: 'production' hides error details from anyone calling your API
+    // Switch to 'debug' while you build to see full error messages
+    'APP_ENV' => 'production',
+
     // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
     'GENERAL_API_KEY' => 'DEFAULT_KEY',
 
@@ -30,8 +34,5 @@ return [
     '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',
+    'DB_PASS' => ''
 ];

package/src/backend/package.json

@@ -2,11 +2,11 @@
   "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",
+  "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"
+    "start": "node core/index.js"
   },
   "engines": {
     "node": ">=18"

package/src/backend/web.config

@@ -19,13 +19,13 @@
             <rules>
 
                 <rule name="PassThroughCoreIndex" stopProcessing="true">
-                    <match url="^_core/index\.php$" ignoreCase="true" />
+                    <match url="^core/index\.php$" ignoreCase="true" />
                     <action type="None" />
                 </rule>
 
                 <rule name="RewriteToFrontController" stopProcessing="true">
                     <match url="^(.*)$" ignoreCase="true" />
-                    <action type="Rewrite" url="_core/index.php" appendQueryString="true" />
+                    <action type="Rewrite" url="core/index.php" appendQueryString="true" />
                 </rule>
 
             </rules>

package/src/frontend/hosting/.htaccess

@@ -40,7 +40,7 @@ ErrorDocument 403 /404.html
 <IfModule mod_rewrite.c>
     RewriteEngine On
     RewriteBase /
-    RewriteRule ^api/(.*)$ backend/_core/index.php [QSA,L]
+    RewriteRule ^api/(.*)$ backend/core/index.php [QSA,L]
 </IfModule>
 
 # === Static files ===========================================================

package/src/frontend/hosting/web.config

@@ -27,7 +27,7 @@
                 <!-- PHP backend: 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" />
+                    <action type="Rewrite" url="backend/core/index.php" appendQueryString="true" />
                 </rule>
 
                 <!-- Node backend (requires ARR). Delete "ApiToPhp" above to use this.

package/src/frontend/layouts/base.njk

@@ -86,6 +86,9 @@
         {# Syntax highlighting for code blocks #}
         <link rel="stylesheet" href="{{ '/css/prism.css' | url }}">
 
+        {# Global CSS #}
+        <link rel="stylesheet" href="{{ '/css/global.css' | url }}"/>
+
         {# Page CSS #}
         <link rel="stylesheet" href="{{ ('/css/pages/' + title + '.css') | url }}"/>
 
@@ -116,13 +119,6 @@
         {# Bootstrap JS #}
         <script src="{{ '/js/bootstrap.bundle.min.js' | url }}" defer></script>
 
-        {# Foundation JS #}
-        {# <script src="{{ '/js/foundation.min.js' | url }}" defer></script> #}
-
-        {# UIkit JS #}
-        {# <script src="{{ '/js/uikit.min.js' | url }}" defer></script> #}
-        {# <script src="{{ '/js/uikit-icons.min.js' | url }}" defer></script> #}
-
         {# Bulma — no JS needed #}
 
         {# Per-page CDN JS #}

package/src/frontend/scss/{_global.scss → global.scss}

@@ -4,8 +4,6 @@
 // Frameworks imports
 @import "modules/frameworks/bootstrap";
 // @import "modules/frameworks/bulma";
-// @import "modules/frameworks/foundation";
-// @import "modules/frameworks/uikit";
 
 // Markdown styling. Applies to content rendered with renderFile
 @import "modules/markdown";

package/src/frontend/scss/modules/frameworks/_bootstrap.scss

@@ -5,8 +5,6 @@
 // ╚══════════════════════════════════════════════════════╝
 
 // Imports can be filtered by commenting them
-// Example:
-// @import "bootstrap/scss/example-bootstrap-module";
 
 //==========================
 // 1️⃣ CORE – Functions and variables

package/src/frontend/scss/modules/frameworks/_bulma.scss

@@ -5,8 +5,6 @@
 // ╚══════════════════════════════════════════════════════╝
 
 // Imports can be filtered by commenting them
-// Example:
-// @import "bulma/sass/example-bulma-module";
 
 //==========================
 // 1️⃣ CORE – Utilities and variables

package/src/frontend/scss/pages/404.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";
 

package/src/frontend/scss/pages/homepage.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";
 

package/tools/res/templates/template.json

@@ -0,0 +1,13 @@
+{
+  "seo": {
+    "title": "{title}",
+    "description": "Description",
+    "keywords": "",
+    "noindex": false,
+    "canonical": ""
+  },
+  "cdn": {
+    "css": [],
+    "js": []
+  }
+}

package/tools/res/templates/template.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";