zyket 1.2.18 → 1.2.20

package/README.md

@@ -1,279 +1,175 @@
-# Zyket
-
-Zyket is a Node.js framework designed to simplify the development of real-time applications with Socket.IO and Express. Inspired by the structured approach of frameworks like Symfony, Zyket provides a robust, service-oriented architecture for building scalable and maintainable server-side applications.
-
-Upon initial boot, Zyket automatically scaffolds a default project structure, including handlers, routes, and configuration files, allowing you to get started immediately.
-
-## Getting Started
-
-### Quick Start (Recommended)
-
-The easiest way to get started with Zyket is to use the CLI initialization command:
-
-```bash
-# Create a new directory for your project
-mkdir my-zyket-app
-cd my-zyket-app
-
-# Install zyket
-npm install zyket
-
-# Initialize the project (one command!)
-npx zyket init
-
-# Start your application
-npm run dev
-```
-
-The `init` command will:
-- Create an `index.js` file with the kernel boilerplate
-- Generate a `.env` file with sensible defaults
-- Create a `package.json` if one doesn't exist
-- Set up your project ready to run
-
-You can also run `npx zyket` without arguments for an interactive menu with more options.
-
-### Manual Setup (Alternative)
-
-If you prefer to set up manually, install Zyket in your project:
-
-```bash
-npm i zyket
-```
-
-Then, create an `index.js` file and boot the Zyket Kernel:
-
-```javascript
-// index.js
-const { Kernel } = require("zyket");
-
-// Instantiate the kernel
-const kernel = new Kernel();
-
-// Boot the kernel to start all services
-kernel.boot().then(() => {
-    console.log("Kernel booted successfully!");
-});
-```
-
-When you run this for the first time, Zyket will create a default `.env` file and a `src` directory containing boilerplate for routes, handlers, guards, and middlewares.
-
-## Core Concepts
-
-Zyket is built around a few key architectural concepts:
-
-*   **Socket.IO Handlers & Guards**: For managing real-time WebSocket events and their authorization.
-*   **Express Routes & Middlewares**: For handling traditional RESTful API endpoints.
-*   **Services**: Reusable components that are managed by a dependency injection container.
-*   **CLI**: A command-line tool to scaffold features from templates.
-
-### Socket.IO Development
-
-#### Handlers
-
-Handlers are classes that process incoming Socket.IO events. The name of the handler file (e.g., `message.js`) determines the event it listens to (`message`).
-
-```javascript
-// src/handlers/message.js
-const { Handler } = require("zyket");
-
-module.exports = class MessageHandler extends Handler {
-  // Array of guard names to execute before the handler
-  guards = ["default"];
-
-  async handle({ container, socket, data, io }) {
-    const logger = container.get("logger");
-    logger.info(`Received message: ${JSON.stringify(data)}`);
-    socket.emit("response", { received: data });
-  }
-};
-```
-
-#### Guards
-
-Guards are used to protect Socket.IO handlers or the initial connection. They run before the handler's `handle` method and are ideal for authorization logic.
-
-```javascript
-// src/guards/default.js
-const { Guard } = require("zyket");
-
-module.exports = class DefaultGuard extends Guard {
-  async handle({ container, socket, io }) {
-    container.get("logger").info(`Executing default guard for socket ${socket.id}`);
-    
-    // Example: Check for an auth token. If invalid, disconnect the user.
-    // if (!socket.token) {
-    //   socket.disconnect();
-    // }
-  }
-};
-```
-
-### Express API Development
-
-#### Routes
-
-Routes handle HTTP requests. The file path maps directly to the URL endpoint. For example, `src/routes/index.js` handles requests to `/`, and `src/routes/[test]/message.js` handles requests to `/:test/message`.
-
-```javascript
-// src/routes/index.js
-const { Route } = require("zyket");
-const DefaultMiddleware = require("../middlewares/default");
-
-module.exports = class DefaultRoute extends Route {
-  // Apply middlewares to specific HTTP methods
-  middlewares = {
-    get: [ new DefaultMiddleware() ],
-    post: [ new DefaultMiddleware() ]
-  }
-
-  async get({ container, request }) {
-    container.get("logger").info("Default route GET");
-    return { test: "Hello World GET!" };
-  }
-
-  async post({ container, request }) {
-    container.get("logger").info("Default route POST");
-    return { test: "Hello World POST!" };
-  }
-};
-```
-
-#### Middlewares
-
-Middlewares process the request before it reaches the route handler. They follow the standard Express middleware pattern.
-
-```javascript
-// src/middlewares/default.js
-const { Middleware } = require("zyket");
-
-module.exports = class DefaultMiddleware extends Middleware {
-  async handle({ container, request, response, next }) {
-    container.get("logger").info("Default Express middleware executing");
-    next(); // Pass control to the next middleware or route handler
-  }
-};
-```
-
-## Services
-
-Services are the cornerstone of Zyket's architecture, providing reusable functionality across your application. Zyket includes several default services and allows you to register your own.
-
-### Custom Services
-
-You can create your own services by extending the `Service` class and registering it with the Kernel.
-
-```javascript
-// src/services/MyCustomService.js
-const { Service } = require("zyket");
-
-module.exports = class MyCustomService extends Service {
-    constructor() {
-        super("my-custom-service");
-    }
-
-    async boot() {
-        console.log("MyCustomService has been booted!");
-    }
-
-    doSomething() {
-        return "Something was done.";
-    }
-}
-```
-
-Register the service in your main `index.js` file:
-
-```javascript
-// index.js
-const { Kernel } = require("zyket");
-const MyCustomService = require("./src/services/MyCustomService");
-
-const kernel = new Kernel({
-    services: [
-        // [name, class, [constructor_args]]
-        ["my-service", MyCustomService, []]
-    ]
-});
-
-kernel.boot();
-```
-Services are reusable components specified in the kernel configuration. Each service must include a boot() function that is executed when the kernel starts.
-
-```javascript
-module.exports = class LoggerService {
-    this.#container;
-    
-    boot(container, enableLogging = true) {
-        this.#container = container;
-        console.log("LoggerService Booted");
-    }
-
-    info(message) {
-        if(!enableLogging) return;
-        console.log(`[INFO]: ${message}`);
-    }
-};
-```
-
-Then, when booting the kernel, specify the service:
-
-```javascript
-const { Kernel } = require("zyket");
-const LoggerService = require("./LoggerService");
-
-const kernel = new Kernel({
-    services: [["logger", LoggerService, ['@service_container', true]],
-});
-
-kernel.boot().then(() => console.log(`Kernel Booted`));
-```
-
-## Default Services
-Zyket includes some default services that provide essential functionality. These services can be overridden or extended if needed.
-
-#### Cache Services
-- **Name** `cache`
-- **Description** Provides caching functionality using a Redis adapter.
-- **Configuration** Add `CACHE_URL` in your `.env` file to activate caching.
-
-#### Database Service
-- **Name** `database`
-- **Description** Manages database connections using a MariaDB/Sequelize adapter.
-- **Configuration** Add `DATABASE_URL` in your `.env` file to enable the database connection.
-
-#### S3 Service
-- **Name** `s3`
-- **Description** Provides S3-compatible object storage using MinIO.
-- **Configuration** Add the following variables in your `.env` file to enable the service
-    - `S3_ENDPOINT`
-    - `S3_PORT`
-    - `S3_USE_SSL`
-    - `S3_ACCESS_KEY`
-    - `S3_SECRET_KEY`
-
-#### Logger Service
-- **Name** `logger`
-- **Description** Handles logging for the application.
-- **Configuration**
-    - Change `LOG_DIRECTORY` in `.env` file to set a custom log directory.
-    - Set `DEBUG` in `.env` file to enable or disable debug logging.
-
-#### Socket.io Service
-- **Name** `socketio`
-- **Description** Manages the WebSocket server.
-- **Configuration** Add `PORT` in your `.env` file to define the listening port for Socket.io.
-
-
-## Contributing
-
-We welcome contributions from the community! If you'd like to improve Zyket, feel free to:
-
-- Report issues and suggest features on GitHub Issues
-
-- Submit pull requests with bug fixes or enhancements
-
-- Improve the documentation
-
-Let's build a better framework together! 🚀
-
+# Zyket
+
+Zyket is a service-oriented Node.js framework for building real-time and REST applications with **Express 5**, **Socket.IO**, **better-auth**, and **Sequelize/BullMQ/MinIO**. Inspired by Symfony, it pairs a dependency-injection container with filesystem-based auto-discovery: drop a file in the right folder and the framework wires it up.
+
+> **Building with an AI agent?** See **[AGENTS.md](AGENTS.md)** for a complete, machine-readable reference, and **[SECURITY.md](SECURITY.md)** for hardening guidance.
+
+## Getting started
+
+```bash
+mkdir my-app && cd my-app
+npm install zyket
+
+# Initialize from a template (interactive picker)
+npx zyket init
+# …or pick one directly:
+npx zyket init api-rest      # default | api-rest | saas-multitenant | realtime-chat
+```
+
+`init` scaffolds the template, generates a `.env`, writes `package.json` with the right dependencies, and installs them. Templates that ship authentication need their tables created once:
+
+```bash
+npx @better-auth/cli migrate
+node index.js
+```
+
+### Templates
+
+| Template | What you get |
+|----------|--------------|
+| `default` | General starter (backend + optional React frontend) |
+| `api-rest` | Backend-only REST API with auth and a protected CRUD resource |
+| `saas-multitenant` | Multi-tenant SaaS (organizations, roles) + React dashboard |
+| `realtime-chat` | Authenticated real-time chat (Socket.IO) + React UI |
+
+### Manual boot
+
+```js
+// index.js
+const { Kernel } = require("zyket");
+
+const kernel = new Kernel({
+  services: [
+    ["auth", require("./src/services/auth"), ["@service_container"]],
+  ],
+});
+
+kernel.boot().then(() => console.log("Kernel booted!"));
+```
+
+On first run Zyket creates a `.env` and a `src/` directory with boilerplate.
+
+## Core concepts
+
+- **Routes & Middlewares** — REST endpoints via Express, auto-discovered from `src/routes`.
+- **Handlers & Guards** — Socket.IO events and their authorization, from `src/handlers` / `src/guards`.
+- **Services** — reusable units managed by a DI container (`logger`, `database`, `cache`, `s3`, `events`, `scheduler`, `bullmq`, `socketio`, `express`, `auth`).
+- **Extensions** — post-boot plugins (e.g. BullBoard, interactive storage).
+- **Templates & CLI** — scaffold whole projects or individual components.
+
+### Routes
+
+File path maps to the URL: `src/routes/index.js` → `/`, `src/routes/users/[id].js` → `/users/:id`. Methods: `get`, `post`, `put`, `delete`.
+
+```js
+const { Route, RequireAuthMiddleware } = require("zyket");
+
+module.exports = class extends Route {
+  middlewares = { post: [new RequireAuthMiddleware()] };
+
+  async get({ container, request }) {
+    return { items: [] };                       // → { success: true, items: [] }
+  }
+  async post({ container, request }) {
+    if (!request.body.name) return { success: false, message: "name required", status: 400 };
+    return { created: true, status: 201 };
+  }
+};
+```
+
+Return an object (wrapped as `{ success: true, ... }`), set `status` to change the HTTP code, return a `Buffer` for a download, or `new RedirectResponse(url)` to redirect.
+
+### Middlewares
+
+```js
+const { Middleware } = require("zyket");
+
+module.exports = class extends Middleware {
+  async handle({ container, request, response, next }) {
+    next(); // respond to block, or next() to continue
+  }
+};
+```
+
+### Socket.IO handlers & guards
+
+```js
+// src/handlers/message.js  → "message" event
+const { Handler } = require("zyket");
+
+module.exports = class extends Handler {
+  guards = ["auth"];
+  async handle({ container, socket, data, io }) {
+    io.emit("message", data);
+    return { ok: true };
+  }
+};
+```
+
+```js
+// src/guards/auth.js — reuse the built-in session guard
+module.exports = require("zyket").AuthGuard;
+```
+
+## Authentication
+
+Zyket ships first-class auth via [better-auth](https://better-auth.com) mounted at `/api/auth/*`, with the admin, bearer, and (optional) organization plugins. Customize by subclassing `AuthService`; protect routes/sockets with `RequireAuthMiddleware`, `RequireAdminMiddleware`, and `AuthGuard`.
+
+```js
+const { Route, RequireAdminMiddleware } = require("zyket");
+
+module.exports = class extends Route {
+  middlewares = { get: [new RequireAdminMiddleware()] };
+  async get() { return { secret: "admins only" }; }
+};
+```
+
+Cookies are environment-aware: `sameSite=lax` in local dev (works over `http://localhost`), and `sameSite=none; secure` when `AUTH_CROSS_DOMAIN=true` for cross-domain HTTPS deployments. See [AGENTS.md §6](AGENTS.md#6-authentication-better-auth).
+
+## Services
+
+Default services activate from environment variables (see [AGENTS.md §3–4](AGENTS.md#3-environment-variables)). Register your own in the Kernel:
+
+```js
+const { Service } = require("zyket");
+
+module.exports = class MyService extends Service {
+  #container;
+  constructor(container) { super("my-service"); this.#container = container; }
+  async boot() { /* init */ }
+  doThing() { return "done"; }
+};
+```
+
+```js
+const kernel = new Kernel({
+  services: [["my-service", MyService, ["@service_container"]]],
+});
+```
+
+Default services and their activation:
+
+| Service | Env to enable |
+|---------|---------------|
+| `database` | `DATABASE_URL` (+ `DATABASE_DIALECT`, default `sqlite`) |
+| `cache` | always (`CACHE_URL=redis://…` for Redis, else in-memory) |
+| `s3` | `S3_ENDPOINT` + `S3_ACCESS_KEY` + `S3_SECRET_KEY` (MinIO) |
+| `socketio` | `DISABLE_SOCKET=false` |
+| `bullmq` | `DISABLE_BULLMQ=false` + `QUEUES=...` |
+| `scheduler` | `DISABLE_SCHEDULER=false` |
+| `events` | `DISABLE_EVENTS=false` |
+| `vite` | `VITE_ROOT` + `DISABLE_VITE=false` |
+| `auth` | manual registration (requires `sqlite`/`postgresql`) |
+
+## Security
+
+Zyket bakes in several defaults (random per-project `AUTH_SECRET`, fail-closed BullBoard, configurable payload limits, path-traversal guards on storage). Review **[SECURITY.md](SECURITY.md)** before going to production — notably rate limiting and `helmet` are not bundled.
+
+## Tooling for AI agents
+
+- **[AGENTS.md](AGENTS.md)** — full framework reference.
+- **Claude Code plugin** (`plugin/`) — skills to scaffold and use Zyket (`generate`, `build`).
+
+## Contributing
+
+Issues and pull requests are welcome — bug fixes, features, and documentation improvements. Let's build a better framework together. 🚀

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Seguridad — Zyket
+
+Auditoría de seguridad del framework y estado de las correcciones.
+Leyenda: `[x]` hecho · `[ ]` pendiente · 🔴 crítico · 🟠 alto · 🟡 medio · 🔵 bajo
+
+---
+
+## ✅ Resuelto
+
+- [x] 🔴 **`.env` ignorado en git.** Añadido `.env` / `*.sqlite` al `.gitignore` para evitar fuga de `AUTH_SECRET`, claves S3 y credenciales de BD.
+- [x] 🔴 **`AUTH_SECRET` aleatorio + fail-closed.** `#addAuthEnvVariables` genera ahora un secreto con `crypto.randomBytes(32)` por proyecto y lo inyecta en `process.env` para el primer arranque. `#requireAuthSecret()` aborta el boot si el secreto falta o es uno de los valores estáticos conocidos. → [src/services/auth/index.js](src/services/auth/index.js)
+- [x] 🔴 **Autenticación en Storage realmente aplicada.** Antes los `middlewares` del constructor se guardaban pero no se usaban; ahora se aplican a todas las rutas y métodos (auth antes de multer en `upload`). La autenticación se inyecta vía `new InteractiveStorageExtension({ middlewares: [authMiddleware] })`. → [src/extensions/interactive-storage/index.js](src/extensions/interactive-storage/index.js)
+- [x] 🔴 **BullBoard fail-closed.** Si no hay `BULLBOARD_ADMIN_PASSWORD` ni `middlewares`, el panel **no se monta** (antes quedaba público). Soporta `middlewares` por constructor. → [src/extensions/bullboard/index.js](src/extensions/bullboard/index.js)
+- [x] 🟠 **Inyección de cabecera en descarga.** `Content-Disposition` ahora sanea el nombre (basename + ASCII filtrado + `filename*=UTF-8''`) evitando breakout de comillas/CRLF. → [src/extensions/interactive-storage/routes/download.js](src/extensions/interactive-storage/routes/download.js)
+- [x] 🟠 **Path traversal en `normalizePath`.** Se eliminan segmentos `..` / `.` además de normalizar slashes. → [src/extensions/interactive-storage/index.js](src/extensions/interactive-storage/index.js#L150)
+- [x] 🟡 **Límite en borrado masivo.** `delete` ahora rechaza lotes mayores a `maxDeleteBatch` (por defecto 100, configurable en el constructor de la extensión) → evita borrado masivo / agotamiento de recursos en una sola petición. → [src/extensions/interactive-storage/routes/delete.js](src/extensions/interactive-storage/routes/delete.js)
+- [x] 🟡 **`requireEmailVerification` personalizable.** Nuevo getter `requireEmailVerification` (por defecto `false`, manteniendo el comportamiento previo) sobreescribible al extender `AuthService`. → [src/services/auth/index.js](src/services/auth/index.js#L71)
+- [x] 🟡 **Límite en borrado de carpeta.** `delete-folder` rechaza prefijos con más de `maxDeleteBatch` archivos (mismo tope configurable que `delete`). → [src/extensions/interactive-storage/routes/delete-folder.js](src/extensions/interactive-storage/routes/delete-folder.js)
+- [x] 🟠 **Validación de `fileName` en `download`/`info`.** Se rechazan (`400`) claves con segmentos `..`/`.`, backslashes o que empiecen por `/` antes de llegar al cliente S3. → [download.js](src/extensions/interactive-storage/routes/download.js), [info.js](src/extensions/interactive-storage/routes/info.js)
+- [x] 🟡 **Límites de payload configurables (default 10 MB).** Body JSON vía `HTTP_JSON_LIMIT` y socket vía `SOCKET_MAX_HTTP_BUFFER_SIZE` (ambos por defecto 10 MB, incluidos en el `.env` generado). → [Express.js](src/services/express/Express.js#L32), [SocketIO.js](src/services/socketio/SocketIO.js#L32), [EnvManager.js](src/utils/EnvManager.js)
+- [x] 🟡 **Swagger protegible opcionalmente.** `SWAGGER_PASSWORD` activa HTTP Basic auth (usuario configurable con `SWAGGER_USER`, default `admin`); `DISABLE_SWAGGER=true` lo desactiva por completo. Si queda abierto se emite un warning. → [src/services/express/Express.js](src/services/express/Express.js#L44)
+- [x] 🟡 **No se filtra `error.message` al cliente.** Las 4 respuestas `500` (rutas y middlewares, en `boot` y `registerRoutes`) devuelven ahora un genérico `Internal Server Error`; el detalle (incluido el stack) queda solo en los logs del servidor. → [src/services/express/Express.js](src/services/express/Express.js)
+- [x] 🟠 **Cookies dependientes del entorno.** Ya no se fuerza `sameSite:"none"` + `secure` + cross-subdomain siempre. Por defecto `sameSite:"lax"` y `secure` solo en producción (login funciona en `http://localhost`); `AUTH_CROSS_DOMAIN=true` activa `none`+`secure`+cross-subdomain para front/back en dominios distintos (HTTPS). → [src/services/auth/index.js](src/services/auth/index.js#L126-L165)
+- [x] 🟢 **Helpers de autorización en el framework.** Nuevos `RequireAuthMiddleware`, `RequireAdminMiddleware` (rutas) y `AuthGuard` (sockets), exportados desde `zyket`, para proteger rutas/eventos con la sesión de better-auth. → [src/services/express/RequireAuthMiddleware.js](src/services/express/RequireAuthMiddleware.js), [src/services/socketio/AuthGuard.js](src/services/socketio/AuthGuard.js)
+
+---
+
+## ⏳ Pendiente
+
+### 🟠 Alto
+- [ ] **CSRF de OAuth / account linking.** `account.skipStateCookieCheck: true` junto a `accountLinking.enabled: true` desactiva la verificación de `state` → riesgo de account takeover. Quitar `skipStateCookieCheck`. → [src/services/auth/index.js](src/services/auth/index.js#L189-L191)
+- [ ] **Socket.IO CORS `origin:"*"` + guard por defecto que no bloquea.** Restringir origins (reutilizar `TRUSTED_ORIGINS`) y que el guard por defecto deniegue sin sesión válida. → [src/services/socketio/SocketIO.js](src/services/socketio/SocketIO.js#L32), [src/templates/default/src/guards/default.js](src/templates/default/src/guards/default.js)
+
+### 🟡 Medio
+- [ ] **Rate limiting** (login, reset password, upload) con `express-rate-limit`. → [src/services/express/Express.js](src/services/express/Express.js)
+- [ ] **Cabeceras de seguridad** con `helmet`. → [src/services/express/Express.js](src/services/express/Express.js)
+
+### 🔵 Bajo / Higiene
+- [ ] **Reducir superficie de drivers de BD** (`sqlite3` + `better-sqlite3` + `pg` + `mariadb`).
+- [ ] **Documentar guía de despliegue seguro** (variables obligatorias en producción, HTTPS, secretos).