cyberia 3.2.5 → 3.2.12

package/src/api/object-layer/object-layer.service.js

@@ -10,7 +10,7 @@
  * @namespace CyberiaObjectLayerService
  */
 
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { ObjectLayerRenderFramesDto } from '../object-layer-render-frames/object-layer-render-frames.model.js';
 import { FileFactory } from '../file/file.service.js';
@@ -36,7 +36,7 @@ const logger = loggerFactory(import.meta);
  * @namespace CyberiaObjectLayerService.ObjectLayerService
  * @memberof CyberiaObjectLayerService
  */
-const ObjectLayerService = {
+class ObjectLayerService {
   /**
    * POST handler for creating object layers and uploading frame images.
    *
@@ -59,7 +59,7 @@ const ObjectLayerService = {
    * @returns {Promise<Object>} The created object layer document or frame upload result.
    * @throws {Error} If file validation fails or required parameters are missing.
    */
-  post: async (req, res, options) => {
+  static post = async (req, res, options) => {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
 
     if (req.path.startsWith('/frame-image')) {
@@ -149,9 +149,9 @@ const ObjectLayerService = {
       fs.writeFileSync(`${publicFolder}/metadata.json`, metadataContent);
 
       // Build object layer data from the asset directory
-      const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+      const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
       const ObjectLayerRenderFrames =
-        DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+        DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
 
       const { objectLayerRenderFramesData, objectLayerData } =
         await ObjectLayerEngine.buildObjectLayerDataFromDirectory({
@@ -183,9 +183,9 @@ const ObjectLayerService = {
     }
 
     // create object layer from body – cut-over consistency: stage all CIDs before writing to DB
-    const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
     const ObjectLayerRenderFrames =
-      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
 
     const bodyData = { ...req.body };
     if (!bodyData.data) bodyData.data = {};
@@ -245,7 +245,7 @@ const ObjectLayerService = {
     }
 
     return newObjectLayer;
-  },
+  };
 
   /**
    * GET handler for retrieving object layers.
@@ -268,9 +268,9 @@ const ObjectLayerService = {
    * @returns {Promise<Object>} The requested object layer data, list, or frame counts.
    * @throws {Error} If the requested object layer is not found.
    */
-  get: async (req, res, options) => {
+  static get = async (req, res, options) => {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
 
     // GET /search-item-ids?q=<partial> - Fast partial match search on data.item.id
     if (req.path.startsWith('/search-item-ids')) {
@@ -360,8 +360,8 @@ const ObjectLayerService = {
       if (objectLayer.atlasSpriteSheetId) {
         try {
           const AtlasSpriteSheet =
-            DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.AtlasSpriteSheet;
-          const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+            DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+          const File = DataBaseProviderService.getModel("File", options);
 
           const atlasDoc = await AtlasSpriteSheet.findById(objectLayer.atlasSpriteSheetId);
 
@@ -432,7 +432,7 @@ const ObjectLayerService = {
       ObjectLayer.countDocuments(query), // { userId: req.auth.user._id }
     ]);
     return { data, total, page, totalPages: Math.ceil(total / limit) };
-  },
+  };
 
   /**
    * Generates a WebP animation from PNG frame images for a specific direction of an object layer.
@@ -449,9 +449,9 @@ const ObjectLayerService = {
    * @returns {Promise<Buffer>} The generated WebP animation as a Buffer.
    * @throws {Error} If required parameters are missing, frames directory is not found, or img2webp fails.
    */
-  generateWebp: async (req, res, options) => {
+  static generateWebp = async (req, res, options) => {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
 
     // GET /generate-webp/:itemType/:itemId/:directionCode - Generate webp animation from PNG frames
     const itemType = req.params.itemType;
@@ -515,7 +515,10 @@ const ObjectLayerService = {
 
       logger.info(`Executing command: ${cmd}`);
 
-      const result = shellExec(cmd, { silent: false });
+      // silentOnError so we can build a domain-specific Error with the
+      // captured stderr/stdout context (callers want a friendly message,
+      // not a generic ShellExecError).
+      const result = shellExec(cmd, { silent: false, silentOnError: true });
 
       if (result.code !== 0) {
         throw new Error(`img2webp command failed: ${result.stderr || result.stdout}`);
@@ -560,7 +563,7 @@ const ObjectLayerService = {
 
       throw error;
     }
-  },
+  };
 
   /**
    * PUT handler for updating object layers, their frame images, and metadata.
@@ -584,9 +587,9 @@ const ObjectLayerService = {
    * @returns {Promise<Object>} The updated object layer document or frame upload result.
    * @throws {Error} If file validation fails, object layer is not found, or required parameters are missing.
    */
-  put: async (req, res, options) => {
+  static put = async (req, res, options) => {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
 
     // PUT /:id/frame-image/:itemType/:itemId/:directionCode - Update frame images for specific direction
     if (req.path.includes('/frame-image/')) {
@@ -686,7 +689,7 @@ const ObjectLayerService = {
       fs.writeFileSync(`${publicFolder}/metadata.json`, metadataContent);
 
       const ObjectLayerRenderFrames =
-        DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+        DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
 
       // Build object layer data from the asset directory
       const { objectLayerRenderFramesData, objectLayerData } =
@@ -775,7 +778,7 @@ const ObjectLayerService = {
     }).populate('objectLayerRenderFramesId');
 
     return updatedObjectLayer;
-  },
+  };
 
   /**
    * DELETE handler for removing object layers and all associated resources.
@@ -801,11 +804,11 @@ const ObjectLayerService = {
    * @returns {Promise<Object>} The deleted object layer document or bulk delete count.
    * @throws {Error} If the object layer is not found.
    */
-  delete: async (req, res, options) => {
+  static delete = async (req, res, options) => {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayer;
+    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
     const ObjectLayerRenderFrames =
-      DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
 
     if (req.params.id) {
       // Load the full object layer so we can access all references
@@ -890,7 +893,7 @@ const ObjectLayerService = {
       }
       return { deletedCount: allObjectLayers.length };
     }
-  },
-};
+  };
+}
 
 export { ObjectLayerService };

package/src/api/object-layer-render-frames/object-layer-render-frames.controller.js

@@ -3,8 +3,8 @@ import { ObjectLayerRenderFramesService } from './object-layer-render-frames.ser
 
 const logger = loggerFactory(import.meta);
 
-const ObjectLayerRenderFramesController = {
-  post: async (req, res, options) => {
+class ObjectLayerRenderFramesController {
+  static post = async (req, res, options) => {
     try {
       const result = await ObjectLayerRenderFramesService.post(req, res, options);
       return res.status(200).json({
@@ -18,8 +18,8 @@ const ObjectLayerRenderFramesController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const { page, limit } = req.query;
       const result = await ObjectLayerRenderFramesService.get(
@@ -38,8 +38,8 @@ const ObjectLayerRenderFramesController = {
         message: error.message,
       });
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     try {
       const result = await ObjectLayerRenderFramesService.put(req, res, options);
       return res.status(200).json({
@@ -53,8 +53,8 @@ const ObjectLayerRenderFramesController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await ObjectLayerRenderFramesService.delete(req, res, options);
       return res.status(200).json({
@@ -68,7 +68,7 @@ const ObjectLayerRenderFramesController = {
         message: error.message,
       });
     }
-  },
-};
+  };
+}
 
 export { ObjectLayerRenderFramesController };

package/src/api/object-layer-render-frames/object-layer-render-frames.model.js

@@ -3,9 +3,7 @@
  * @module src/api/object-layer-render-frames/object-layer-render-frames.model.js
  * @namespace CyberiaObjectLayerRenderFramesModel
  */
-
 import { Schema, model } from 'mongoose';
-
 /**
  * @typedef {Object} ObjectLayerRenderFramesDirections
  * @property {number[][][]} up_idle - Up idle animation frames
@@ -51,13 +49,11 @@ const ObjectLayerRenderFramesDirectionsSchema = new Schema(
   },
   { _id: false },
 );
-
 /**
  * @typedef {Object} ObjectLayerRenderFrames
  * @property {RenderFrames} frames - Animation frames for different states
  * @property {number[][]} colors - Color palette for rendering
  * @property {number} frame_duration - Duration of each frame in milliseconds
- * @property {boolean} is_stateless - Whether the render is stateless
  * @property {Date} createdAt - When the document was created
  * @property {Date} updatedAt - When the document was last updated
  * @memberof CyberiaObjectLayerRenderFramesModel
@@ -67,7 +63,6 @@ const ObjectLayerRenderFramesSchema = new Schema(
     frames: { type: ObjectLayerRenderFramesDirectionsSchema, required: true },
     colors: { type: [[Number]], required: true },
     frame_duration: { type: Number, required: true, min: 0 },
-    is_stateless: { type: Boolean, default: false },
   },
   {
     timestamps: true,
@@ -75,7 +70,6 @@ const ObjectLayerRenderFramesSchema = new Schema(
     toObject: { virtuals: true },
   },
 );
-
 // Pre-save hook to ensure data consistency
 ObjectLayerRenderFramesSchema.pre('save', function () {
   // Ensure all required fields are present
@@ -83,21 +77,17 @@ ObjectLayerRenderFramesSchema.pre('save', function () {
     throw new Error('Missing required fields: frames, colors, or frame_duration');
   }
 });
-
 // Create and export the model
 const ObjectLayerRenderFramesModel = model('ObjectLayerRenderFrames', ObjectLayerRenderFramesSchema);
-
 const ProviderSchema = ObjectLayerRenderFramesSchema;
-
-const ObjectLayerRenderFramesDto = {
-  select: {
+class ObjectLayerRenderFramesDto {
+  static select = {
     get: () => {
-      return { _id: 1, frame_duration: 1, is_stateless: 1 };
+      return { _id: 1, frame_duration: 1 };
     },
     getFull: () => {
-      return { _id: 1, frames: 1, colors: 1, frame_duration: 1, is_stateless: 1 };
+      return { _id: 1, frames: 1, colors: 1, frame_duration: 1 };
     },
-  },
-};
-
+  };
+}
 export { ObjectLayerRenderFramesSchema, ObjectLayerRenderFramesModel, ProviderSchema, ObjectLayerRenderFramesDto };

package/src/api/object-layer-render-frames/object-layer-render-frames.router.js

@@ -4,24 +4,28 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const ObjectLayerRenderFramesRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.post(req, res, options));
-  router.post(`/`, async (req, res) => await ObjectLayerRenderFramesController.post(req, res, options));
-  router.get(
-    `/:id`,
-    // authMiddleware,
-    async (req, res) => await ObjectLayerRenderFramesController.get(req, res, options),
-  );
-  router.get(`/`, async (req, res) => await ObjectLayerRenderFramesController.get(req, res, options));
-  router.put(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.put(req, res, options));
-  router.put(`/`, async (req, res) => await ObjectLayerRenderFramesController.put(req, res, options));
-  router.delete(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.delete(req, res, options));
-  router.delete(`/`, async (req, res) => await ObjectLayerRenderFramesController.delete(req, res, options));
-  return router;
-};
+class ObjectLayerRenderFramesRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.post(req, res, options));
+    router.post(`/`, async (req, res) => await ObjectLayerRenderFramesController.post(req, res, options));
+    router.get(`/:id`,
+      // options.authMiddleware,
+      async (req, res) => await ObjectLayerRenderFramesController.get(req, res, options),
+    );
+    router.get(`/`, async (req, res) => await ObjectLayerRenderFramesController.get(req, res, options));
+    router.put(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.put(req, res, options));
+    router.put(`/`, async (req, res) => await ObjectLayerRenderFramesController.put(req, res, options));
+    router.delete(`/:id`, async (req, res) => await ObjectLayerRenderFramesController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await ObjectLayerRenderFramesController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = ObjectLayerRenderFramesRouter;
+const ApiRouter = (options) => ObjectLayerRenderFramesRouter.router(options);
 
 export { ApiRouter, ObjectLayerRenderFramesRouter };

package/src/api/object-layer-render-frames/object-layer-render-frames.service.js

@@ -1,18 +1,20 @@
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
 
 const logger = loggerFactory(import.meta);
 
-const ObjectLayerRenderFramesService = {
-  post: async (req, res, options) => {
+class ObjectLayerRenderFramesService {
+  static post = async (req, res, options) => {
     /** @type {import('./object-layer-render-frames.model.js').ObjectLayerRenderFramesModel} */
-    const ObjectLayerRenderFrames = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+    const ObjectLayerRenderFrames =
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
     return await new ObjectLayerRenderFrames(req.body).save();
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     /** @type {import('./object-layer-render-frames.model.js').ObjectLayerRenderFramesModel} */
-    const ObjectLayerRenderFrames = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+    const ObjectLayerRenderFrames =
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
     if (req.params.id) return await ObjectLayerRenderFrames.findById(req.params.id);
 
     // Parse query parameters using DataQuery helper
@@ -25,18 +27,20 @@ const ObjectLayerRenderFramesService = {
 
     const totalPages = Math.ceil(total / limit);
     return { data, total, page, totalPages };
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     /** @type {import('./object-layer-render-frames.model.js').ObjectLayerRenderFramesModel} */
-    const ObjectLayerRenderFrames = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+    const ObjectLayerRenderFrames =
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
     return await ObjectLayerRenderFrames.findByIdAndUpdate(req.params.id, req.body);
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     /** @type {import('./object-layer-render-frames.model.js').ObjectLayerRenderFramesModel} */
-    const ObjectLayerRenderFrames = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.ObjectLayerRenderFrames;
+    const ObjectLayerRenderFrames =
+      DataBaseProviderService.getModel("ObjectLayerRenderFrames", options);
     if (req.params.id) return await ObjectLayerRenderFrames.findByIdAndDelete(req.params.id);
     else return await ObjectLayerRenderFrames.deleteMany();
-  },
-};
+  };
+}
 
 export { ObjectLayerRenderFramesService };

package/src/api/test/test.controller.js

@@ -3,8 +3,8 @@ import { TestService } from './test.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const TestController = {
-  post: async (req, res, options) => {
+class TestController {
+  static post = async (req, res, options) => {
     try {
       return res.status(200).json({
         status: 'success',
@@ -17,8 +17,8 @@ const TestController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const result = await TestService.get(req, res, options);
       if (result)
@@ -37,8 +37,8 @@ const TestController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await TestService.delete(req, res, options);
 
@@ -53,7 +53,7 @@ const TestController = {
         message: error.message,
       });
     }
-  },
-};
+  };
+}
 
 export { TestController };

package/src/api/test/test.router.js

@@ -4,18 +4,23 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const TestRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, async (req, res) => await TestController.post(req, res, options));
-  router.post(`/`, authMiddleware, async (req, res) => await TestController.post(req, res, options));
-  router.get(`/:id`, async (req, res) => await TestController.get(req, res, options));
-  router.get(`/`, async (req, res) => await TestController.get(req, res, options));
-  router.delete(`/:id`, async (req, res) => await TestController.delete(req, res, options));
-  router.delete(`/`, async (req, res) => await TestController.delete(req, res, options));
-  return router;
-};
+class TestRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await TestController.post(req, res, options));
+    router.post(`/`, options.authMiddleware, async (req, res) => await TestController.post(req, res, options));
+    router.get(`/:id`, async (req, res) => await TestController.get(req, res, options));
+    router.get(`/`, async (req, res) => await TestController.get(req, res, options));
+    router.delete(`/:id`, async (req, res) => await TestController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await TestController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = TestRouter;
+const ApiRouter = (options) => TestRouter.router(options);
 
 export { ApiRouter, TestRouter };

package/src/api/test/test.service.js

@@ -5,14 +5,14 @@ import { getYouTubeID, validatePassword } from '../../client/components/core/Com
 
 const logger = loggerFactory(import.meta);
 
-const TestService = {
-  post: async (req, res, options) => {
+class TestService {
+  static post = async (req, res, options) => {
     switch (req.params.id) {
       default:
         break;
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     switch (req.params.id) {
       case 'verify-email':
         return validator.isEmail(req.query.email);
@@ -23,13 +23,13 @@ const TestService = {
 
       default:
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     switch (req.params.id) {
       default:
         break;
     }
-  },
-};
+  };
+}
 
 export { TestService };

package/src/api/types.js

@@ -0,0 +1,24 @@
+/**
+ * @module src/api/types
+ * @description Shared type definitions for the Express router layer.
+ */
+
+/**
+ * Injected dependencies and runtime configuration for every API router instance.
+ * Keyed per-host/path by the multi-tenant engine (see src/runtime/express/Express.js).
+ *
+ * @typedef {Object} RouterOptions
+ * @property {import('express').Application} app - Express application instance.
+ * @property {string} host - Per-runtime host identifier (e.g. "nexodev.org").
+ * @property {string} path - Per-runtime path prefix (e.g. "/" or "/cyberia").
+ * @property {string} apiPath - Computed base URL for the API layer.
+ * @property {string[]} origins - Allowed origins for CORS validation.
+ * @property {import('express').RequestHandler} authMiddleware - Dynamically generated JWT auth middleware (keyed by host+path).
+ * @property {Object} [db] - DataBaseProviderService configuration or instance reference.
+ * @property {Object} [mailer] - MailerProvider configuration or instance reference.
+ * @property {Object} [png] - Cached mailer image buffers (populated by UserRouter on first load).
+ * @property {Record<string, Buffer>} [png.buffer] - Map of image key to raw PNG buffer.
+ * @property {Function} [png.header] - Sets CORS/Content-Type response headers for PNG responses.
+ */
+
+export { };

package/src/api/user/guest.service.js

@@ -0,0 +1,100 @@
+import mongoose from 'mongoose';
+import { UserDto } from './user.model.js';
+import { ValkeyAPI } from '../../server/valkey.js';
+import { hashPassword, getBearerToken, jwtSign } from '../../server/auth.js';
+
+// ─── TTL ──────────────────────────────────────────────────────────────────────
+
+const _guestTtlMs = () => {
+  const minutes = Number.parseInt(process.env.REFRESH_EXPIRE_MINUTES || '60', 10);
+  return Number.isFinite(minutes) && minutes > 0 ? minutes * 60 * 1000 : 60 * 60 * 1000;
+};
+
+// ─── Domain helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Constructs a new ephemeral guest user object.
+ * This is domain logic specific to the guest lifecycle; it does not belong
+ * in the generic Valkey storage module.
+ *
+ * @param {{ host?: string }} options
+ * @returns {object}
+ */
+const buildGuestUser = (options) => {
+  const now = new Date().toISOString();
+  const objectId = new mongoose.Types.ObjectId().toString();
+  const role = 'guest';
+  const username = `${role}${objectId.slice(-5)}`;
+  return {
+    _id: `${role}${objectId}`,
+    username,
+    email: `${username}@${options.host || 'localhost'}`,
+    password: hashPassword(process.env.JWT_SECRET),
+    role,
+    emailConfirmed: false,
+    profileImageId: null,
+    publicKey: [],
+    phoneNumbers: [],
+    activeSessions: [],
+    failedLoginAttempts: 0,
+    recoverTimeOut: null,
+    lastLoginDate: null,
+    createdAt: now,
+    updatedAt: now,
+    guestSessionExpiresAt: Date.now() + _guestTtlMs(),
+  };
+};
+
+/**
+ * Projects a user object to the public-safe fields defined by UserDto.select.get().
+ * Keeps this logic next to the guest domain instead of in a generic utility.
+ *
+ * @param {object} user
+ * @returns {object}
+ */
+const _toPublicUser = (user) => {
+  const select = UserDto.select.get();
+  return Object.fromEntries(
+    Object.keys(select)
+      .filter((k) => select[k] === 1 && k in user)
+      .map((k) => [k, user[k]]),
+  );
+};
+
+const _withRefreshedExpiry = (user) => ({ ...user, guestSessionExpiresAt: Date.now() + _guestTtlMs() });
+
+// ─── Service ──────────────────────────────────────────────────────────────────
+
+class GuestService {
+  static async create(req, options) {
+    const user = buildGuestUser(options);
+
+    await ValkeyAPI.set(options, user.email, user, _guestTtlMs());
+
+    return {
+      token: jwtSign(
+        UserDto.auth.payload(user, null, req.ip, req.headers['user-agent'], options.host, options.path),
+        options,
+      ),
+      user: _toPublicUser(user),
+    };
+  }
+
+  static async auth(req, options) {
+    const user = await ValkeyAPI.get(options, req.auth.user.email);
+    if (!user) throw new Error('guest user expired');
+
+    const expiresAt = Number(user.guestSessionExpiresAt || 0);
+    if (expiresAt && expiresAt <= Date.now()) throw new Error('guest user expired');
+
+    const refreshed = _withRefreshedExpiry(user);
+    await ValkeyAPI.set(options, refreshed.email, refreshed, _guestTtlMs());
+
+    return {
+      user: _toPublicUser(refreshed),
+      token: getBearerToken(req),
+    };
+  }
+}
+
+export { GuestService };

package/src/api/user/user.controller.js

@@ -25,11 +25,11 @@ const handleRequest = (serviceMethod) => async (req, res, options) => {
   }
 };
 
-const UserController = {
-  post: handleRequest(UserService.post),
-  get: handleRequest(UserService.get),
-  delete: handleRequest(UserService.delete),
-  put: handleRequest(UserService.put),
-};
+class UserController {
+  static post = handleRequest(UserService.post);
+  static get = handleRequest(UserService.get);
+  static delete = handleRequest(UserService.delete);
+  static put = handleRequest(UserService.put);
+}
 
 export { UserController };