nodejs-quickstart-structure 2.1.2 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
  
+## [2.2.1] - 2026-05-12
+
+### Added
+- **Secure OAuth CSRF Protection**: Implemented robust state-validation using cryptographically secure random tokens and `HttpOnly` cookies to mitigate CSRF attacks in social authentication flows.
+- **Improved CLI Robustness**: Enhanced argument parsing to support comma-separated strings for variadic flags like `--social-auth` and `--auth`.
+
+### Fixed
+- **Architectural Parity & Type Safety**: Standardized `HTTP_STATUS.FORBIDDEN` across all templates and resolved TypeScript type inference issues (`never` type) in generated Clean Architecture controllers.
+
+## [2.2.0] - 2026-05-05
+
+### Added
+- **Social Login Support**: Integrated Google and GitHub authentication into the Clean Architecture and MVC templates.
+- **Expanded Validation Matrix**: Scaled the mathematical validation matrix to **7,920+ unique project scenarios**, ensuring 100% template rendering accuracy across all permutations.
+
+### Changed
+- **Clean Architecture Restructuring**: Moved use cases from `src/domain/usecases` to `src/usecases` (Application Layer) to strictly follow architectural boundaries.
+- **Improved EJS Alignment**: Optimized all templates with whitespace-slurping tags (`<%_`, `_%>`) to eliminate redundant blank lines in generated code.
+- **Environment Validation**: Added social authentication credentials to Zod-based environment schemas.
+ 
 ## [2.1.2] - 2026-04-27
 
 ### Changed

package/README.md

@@ -17,7 +17,7 @@ A powerful ecosystem to scaffold production-ready Node.js microservices with bui
 - [What's New](#whats-new-in-v21-the-authentication-release)
 - [Key Features](#key-features)
 - [Professional Standards](#professional-standards)
-- [5,280+ Project Combinations](#5280-project-combinations)
+- [7,920+ Project Combinations](#7920-project-combinations)
 - [Configuration Options](#configuration-options)
 - [Generated Project Structure](#generated-project-structure)
 - [Documentation](#documentation)
@@ -50,20 +50,15 @@ nodejs-quickstart init
 
 ---
 
-## What's New in v2.1 (The Authentication Release)
+## What's New in v2.2 (The Social Auth Release)
  
- The v2.1.0 release is a major leap forward, turning the generator into a **Community Standard**:
+ The v2.2.0 release brings enterprise-grade identity management to your microservices:
  
-- **Pluggable JWT Authentication**: Production-ready access & refresh token patterns with automatic PM2/Environment configuration.
-- **AI-Native Foundation**: Built-in `.cursorrules` optimized for **Cursor** & AI agents—projects are "Born to be Autonomously Coded."
-- **Next-Gen Web UI**: A browser-based visual project simulator with real-time folder previews.
-- **Enterprise Clean Architecture**: High-fidelity structure for professional Microservices (TS/JS).
-- **Hardened Security**: Integrated Snyk & SonarCloud logic in core templates.
-- **Zero-Prompt Workflow**: Generate projects with a single CLI command.
+- **OAuth2 Social Login**: Seamlessly integrate **Google** and **GitHub** authentication with automatic user provisioning and JWT session linking.
+- **Massive Matrix Expansion**: Now supporting **7,920+ unique project scenarios**, mathematically validated for template consistency.
 
 ---
 
-
 ## Key Features
 
 - **Interactive CLI**: Smooth, guided configuration process.
@@ -72,7 +67,7 @@ nodejs-quickstart init
 - **Database Ready**: Pre-configured for **MySQL**, **PostgreSQL**, or **MongoDB**.
 - **Communication Patterns**: Supports **REST**, **GraphQL** (Apollo), and **Kafka** (Event-driven).
 - **Multi-layer Caching**: Integrated **Redis** or built-in **Memory Cache**.
-- **Pluggable Authentication**: Built-in **JWT** support (Refresh/Access tokens).
+- **Pluggable Authentication**: Built-in **JWT** and **OAuth2 (Google/GitHub)** support with Access/Refresh token rotation.
 - **AI-Native Optimized**: specifically designed for **Cursor** and AI agents, including built-in `.cursorrules` and Agent Skill prompts.
 
 ---
@@ -90,14 +85,14 @@ We don't just generate boilerplate; we generate **production-ready** foundations
 
 ---
 
-## 5,280+ Project Combinations
+## 7,920+ Project Combinations
 
 The CLI supports a massive number of configurations to fit your exact needs:
 
-- **480 Core Combinations**:
-  - **MVC Architecture**: 360 variants (Languages × View Engines × Databases × Communication Patterns × Caching × Auth)
-  - **Clean Architecture**: 120 variants (Languages × Databases × Communication Patterns × Caching × Auth)
-- **5,280+ Total Scenarios**:
+- **720 Core Combinations**:
+  - **MVC Architecture**: 540 variants (Languages × View Engines × Databases × Communication Patterns × Caching × Auth)
+  - **Clean Architecture**: 180 variants (Languages × Databases × Communication Patterns × Caching × Auth)
+- **7,920+ Total Scenarios**:
   - Every combination can be generated across 5 CI/CD providers.
   - Optional **Enterprise-Grade Security Hardening** doubles the scenarios.
   - Every single scenario is verified to be compatible with our **80% Coverage Threshold** policy.
@@ -114,7 +109,7 @@ The CLI will guide you through:
 5. **Database**: `MySQL` | `PostgreSQL` | `MongoDB`
 6. **Communication**: `REST` | `GraphQL` | `Kafka`
 7. **Caching**: `None` | `Redis` | `Memory Cache`
-8. **Auth**: `None` | `JWT`
+8. **Auth**: `None` | `JWT` | `OAuth2 (Google/GitHub) + JWT`
 9. **CI/CD**: `GitHub Actions` | `Jenkins` | `GitLab CI` | `CircleCI` | `Bitbucket Pipelines`
 10. **Security**: (Optional) Snyk & SonarCloud Hardening
 

package/bin/index.js

@@ -34,6 +34,7 @@ program
     .option('--no-include-security', 'Exclude Enterprise Security Hardening')
     .option('--caching <type>', 'Caching Layer (None/Redis/Memory Cache)')
     .option('--auth <modes...>', 'Authentication Modes (None, JWT)')
+    .option('--social-auth <providers...>', 'Social Authentication Providers (None, Google, GitHub)')
     .option('--advanced-options', 'Enable Advanced Options')
     .option('--no-advanced-options', 'Disable Advanced Options')
     .action(async (options) => {

package/lib/generator.js

@@ -112,7 +112,7 @@ export const generateProject = async (config) => {
       Language: ${language}
       Database: ${config.database}
       Communication: ${config.communication}${config.caching && config.caching !== 'None' ? `\n      Caching: ${config.caching}` : ''}
-      Authentication: ${config.auth.join(', ')}
+      Authentication: ${[...(config.socialAuth || []).filter(s => s !== 'None'), ...config.auth.filter(a => a !== 'None')].join(' - ') || 'None'}
 
       ----------------------------------------------------
       ✨  High-Quality Standards Applied:

package/lib/modules/app-setup.js

@@ -175,6 +175,22 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
             await fs.remove(path.join(targetDir, 'src/interfaces/routes', `${routeName}.ejs`));
         }
 
+        // --- Render All Domain Entities ---
+        const domainDir = path.join(targetDir, 'src/domain');
+        if (await fs.pathExists(domainDir)) {
+            const domainFiles = await fs.readdir(domainDir);
+            for (const file of domainFiles) {
+                if (file.endsWith('.ejs')) {
+                    const templatePathObj = path.join(domainDir, file);
+                    const destPathObj = path.join(domainDir, file.replace('.ejs', ''));
+                    const template = await fs.readFile(templatePathObj, 'utf-8');
+                    const content = ejs.render(template, { ...config });
+                    await fs.writeFile(destPathObj, content);
+                    await fs.remove(templatePathObj);
+                }
+            }
+        }
+
         // --- Render All Use Cases ---
         const useCaseDir = path.join(targetDir, 'src/usecases');
         if (await fs.pathExists(useCaseDir)) {

package/lib/modules/auth-setup.js

@@ -13,6 +13,10 @@ export const setupAuth = async (templatesDir, targetDir, config) => {
     // 1. JWT Service
     await renderAuthComponent(authSource, targetDir, 'services', `jwtService.${langExt}`, config);
 
+    if (config.socialAuth && config.socialAuth.filter(a => a !== 'None').length > 0) {
+        await renderAuthComponent(authSource, targetDir, 'services', `socialAuthService.${langExt}`, config);
+    }
+
     // 2. Auth Middleware
     await renderAuthComponent(authSource, targetDir, 'middleware', `authMiddleware.${langExt}`, config);
 
@@ -22,7 +26,12 @@ export const setupAuth = async (templatesDir, targetDir, config) => {
     // 4. Auth Routes
     await renderAuthComponent(authSource, targetDir, 'routes', `authRoutes.${langExt}`, config);
 
-    // 5. MVC Views (if applicable)
+    // 5. Social Login Use Case (Clean Architecture only)
+    if (architecture === 'Clean Architecture' && config.socialAuth && config.socialAuth.filter(a => a !== 'None').length > 0) {
+        await renderAuthComponent(authSource, targetDir, 'usecases', `SocialLoginUseCase.${langExt}`, config);
+    }
+
+    // 6. MVC Views (if applicable)
     if (architecture === 'MVC' && viewEngine && viewEngine !== 'None') {
         const engine = viewEngine.toLowerCase();
         const views = ['login', 'signup'];
@@ -37,7 +46,7 @@ export const setupAuth = async (templatesDir, targetDir, config) => {
         }
     }
 
-    // 6. Restructuring for Clean Architecture
+    // 7. Restructuring for Clean Architecture
     if (architecture === 'Clean Architecture') {
         await restructureAuthForCleanArch(targetDir, langExt);
     }
@@ -82,6 +91,21 @@ async function restructureAuthForCleanArch(targetDir, ext) {
         }
     }
 
+    if (await fs.pathExists(path.join(targetDir, `src/services/socialAuthService.${ext}`))) {
+        await fs.move(
+            path.join(targetDir, `src/services/socialAuthService.${ext}`),
+            path.join(targetDir, `src/infrastructure/auth/socialAuthService.${ext}`),
+            { overwrite: true }
+        );
+        if (await fs.pathExists(path.join(targetDir, `tests/unit/services/socialAuthService.spec.${ext}`))) {
+            await fs.move(
+                path.join(targetDir, `tests/unit/services/socialAuthService.spec.${ext}`),
+                path.join(targetDir, `tests/unit/infrastructure/auth/socialAuthService.spec.${ext}`),
+                { overwrite: true }
+            );
+        }
+    }
+
     // Controllers -> Interfaces/Controllers/auth
     await fs.ensureDir(path.join(targetDir, 'src/interfaces/controllers/auth'));
     await fs.ensureDir(path.join(targetDir, 'tests/unit/interfaces/controllers/auth'));
@@ -128,10 +152,28 @@ async function restructureAuthForCleanArch(targetDir, ext) {
         );
     }
 
+    // UseCases -> UseCases/auth
+    if (await fs.pathExists(path.join(targetDir, `src/usecases/SocialLoginUseCase.${ext}`))) {
+        await fs.ensureDir(path.join(targetDir, 'src/usecases/auth'));
+        await fs.ensureDir(path.join(targetDir, 'tests/unit/usecases/auth'));
+        await fs.move(
+            path.join(targetDir, `src/usecases/SocialLoginUseCase.${ext}`),
+            path.join(targetDir, `src/usecases/auth/socialLoginUseCase.${ext}`),
+            { overwrite: true }
+        );
+        if (await fs.pathExists(path.join(targetDir, `tests/unit/usecases/SocialLoginUseCase.spec.${ext}`))) {
+            await fs.move(
+                path.join(targetDir, `tests/unit/usecases/SocialLoginUseCase.spec.${ext}`),
+                path.join(targetDir, `tests/unit/usecases/auth/socialLoginUseCase.spec.${ext}`),
+                { overwrite: true }
+            );
+        }
+    }
+
     // Cleanup empty dirs in src and tests/unit
     const dirsToCleanup = [
-        'src/services', 'src/controllers', 'src/middleware', 'src/routes',
-        'tests/unit/services', 'tests/unit/controllers', 'tests/unit/middleware'
+        'src/services', 'src/controllers', 'src/middleware', 'src/routes', 'src/usecases',
+        'tests/unit/services', 'tests/unit/controllers', 'tests/unit/middleware', 'tests/unit/usecases'
     ];
     for (const dir of dirsToCleanup) {
         const fullDir = path.join(targetDir, dir);

package/lib/prompts.js

@@ -96,9 +96,9 @@ export const getProjectDetails = async (options = {}) => {
         },
         {
             type: 'select',
-            name: 'auth',
+            name: 'authChoice',
             message: 'Select Authentication Mode:',
-            choices: ['None', 'JWT'],
+            choices: ['None', 'JWT', 'Google - Github - JWT'],
             default: 'None',
             when: (answers) => {
                 const advanced = options.advancedOptions !== undefined ? options.advancedOptions : answers.advancedOptions;
@@ -119,9 +119,37 @@ export const getProjectDetails = async (options = {}) => {
         result.advancedOptions = result.advancedOptions === 'Yes';
     }
 
-    // Normalize auth to array if it's a string from the list prompt
+    // Map authChoice to auth and socialAuth if not provided via options
+    if (!options.auth && result.authChoice) {
+        const choice = result.authChoice.toLowerCase();
+        if (choice.includes('google') || choice.includes('github')) {
+            result.auth = ['JWT'];
+            result.socialAuth = ['Google', 'GitHub'];
+        } else if (choice.includes('jwt')) {
+            result.auth = ['JWT'];
+            result.socialAuth = ['None'];
+        } else {
+            result.auth = ['None'];
+            result.socialAuth = ['None'];
+        }
+    }
+    
+    // Cleanup the temporary authChoice
+    delete result.authChoice;
+
+    // Normalize auth to array if it's a string from the options
     if (typeof result.auth === 'string') {
-        result.auth = [result.auth];
+        result.auth = result.auth.split(',').map(s => s.trim());
+    } else if (Array.isArray(result.auth)) {
+        result.auth = result.auth.flatMap(s => s.split(',').map(ss => ss.trim()));
+    }
+
+    // Map friendly CLI strings to actual values
+    if (result.auth && (result.auth.includes('Google - Github - JWT') || result.auth.includes('Google - GitHub - JWT'))) {
+        result.auth = ['JWT'];
+        if (!result.socialAuth || result.socialAuth.includes('None')) {
+            result.socialAuth = ['Google', 'GitHub'];
+        }
     }
 
     // Default auth if not provided
@@ -134,6 +162,22 @@ export const getProjectDetails = async (options = {}) => {
         result.auth = result.auth.filter(a => a !== 'None');
     }
 
+    // Normalize socialAuth to array from options
+    if (typeof result.socialAuth === 'string') {
+        result.socialAuth = result.socialAuth.split(',').map(s => s.trim());
+    } else if (Array.isArray(result.socialAuth)) {
+        result.socialAuth = result.socialAuth.flatMap(s => s.split(',').map(ss => ss.trim()));
+    }
+
+    // Default socialAuth if not provided
+    if (!result.socialAuth) {
+        result.socialAuth = ['None'];
+    }
+
+    // Filter out 'None' if providers are selected
+    if (result.socialAuth.includes('Google') || result.socialAuth.includes('GitHub') || result.socialAuth.includes('Github')) {
+        result.socialAuth = result.socialAuth.filter(a => a !== 'None');
+    }
+
     return result;
 };
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "type": "module",
   "description": "The ultimate nodejs quickstart structure CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",

package/templates/clean-architecture/js/src/infrastructure/config/env.js.ejs

@@ -33,12 +33,22 @@ const envSchema = z.object({
 <%_ if (communication === 'Kafka') { -%>
   KAFKA_BROKER: z.string(),
 <%_ } -%>
-<%_ if (auth.includes('JWT')) { -%>
+<%_ if (auth.includes('JWT')) { _%>
   JWT_SECRET: z.string(),
   JWT_EXPIRES_IN: z.string().default('15m'),
   JWT_REFRESH_SECRET: z.string().default('your-secret-refresh-key'),
   JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
-<%_ } -%>
+<%_ if (socialAuth && socialAuth.includes('Google')) { _%>
+  GOOGLE_CLIENT_ID: z.string(),
+  GOOGLE_CLIENT_SECRET: z.string(),
+  GOOGLE_CALLBACK_URL: z.string().optional(),
+<%_ } _%>
+<%_ if (socialAuth && socialAuth.includes('GitHub')) { _%>
+  GITHUB_CLIENT_ID: z.string(),
+  GITHUB_CLIENT_SECRET: z.string(),
+  GITHUB_CALLBACK_URL: z.string().optional(),
+<%_ } _%>
+<%_ } _%>
 });
 
 const _env = envSchema.safeParse(process.env);

package/templates/clean-architecture/js/src/infrastructure/repositories/UserRepository.js.ejs

@@ -38,6 +38,33 @@ class UserRepository {
 <%_ } -%>
   }
 
+  async findByEmail(email) {
+<%_ if (database === 'MongoDB') { -%>
+    const user = await UserModel.findOne({ email });
+    if (!user) return null;
+    return { 
+      id: user._id.toString(), 
+      name: user.name, 
+      email: user.email,
+      googleId: user.googleId,
+      githubId: user.githubId
+    };
+<%_ } else if (database === 'None') { -%>
+    return await UserModel.findOne({ email });
+<%_ } else { -%>
+    const user = await UserModel.findOne({ where: { email } });
+    if (!user) return null;
+    return { 
+      id: user.id, 
+      name: user.name, 
+      email: user.email,
+      googleId: user.googleId,
+      githubId: user.githubId
+    };
+<%_ } -%>
+  }
+
+
   async getUsers() {
 <%_ if (database === 'None') { -%>
     return await UserModel.find();

package/templates/clean-architecture/js/src/infrastructure/repositories/UserRepository.spec.js.ejs

@@ -5,6 +5,7 @@ jest.mock('@/infrastructure/database/models/User', () => ({
     create: jest.fn(),
     findAll: jest.fn(),
     findByPk: jest.fn(),
+    findOne: jest.fn(),
     update: jest.fn(),
     destroy: jest.fn(),
     find: jest.fn(),
@@ -83,6 +84,29 @@ describe('UserRepository', () => {
         });
     });
 
+    describe('findByEmail', () => {
+        it('should find and return a user by email', async () => {
+            const email = 'test@example.com';
+<%_ if (database === 'MongoDB') { -%>
+            const mockDbRecord = { _id: '1', name: 'TestUser', email: 'test@example.com' };
+<%_ } else { -%>
+            const mockDbRecord = { id: '1', name: 'TestUser', email: 'test@example.com' };
+<%_ } -%>
+            UserModel.findOne.mockResolvedValue(mockDbRecord);
+
+            const result = await userRepository.findByEmail(email);
+
+            expect(result.email).toBe(email);
+            expect(UserModel.findOne).toHaveBeenCalled();
+        });
+
+        it('should return null if email not found', async () => {
+            UserModel.findOne.mockResolvedValue(null);
+            const result = await userRepository.findByEmail('not@found.com');
+            expect(result).toBeNull();
+        });
+    });
+
     describe('getUsers', () => {
         it('should return a list of mapped UserEntities (Happy Path)', async () => {
 <%_ if (database === 'MongoDB') { -%>

package/templates/clean-architecture/js/src/infrastructure/webserver/server.js.ejs

@@ -1,5 +1,6 @@
 const express = require('express');
 const cors = require('cors');
+const cookieParser = require('cookie-parser');
 const logger = require('../log/logger');
 const morgan = require('morgan');
 const { errorMiddleware } = require('./middleware/errorMiddleware');
@@ -30,12 +31,15 @@ const startServer = async () => {
     const app = express();
 
     app.use(cors());
+    app.use(cookieParser());
     app.use(express.json());
     app.use(morgan('combined', { stream: { write: message => logger.info(message.trim()) } }));
     <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
     app.use('/api', apiRoutes);
     <%_ } -%>
-    <%_ if (auth.includes('JWT')) { -%>app.use('/api/auth', authRoutes);<%_ } -%>
+    <%_ if (auth.includes('JWT')) { -%>
+    app.use('/api/auth', authRoutes);
+    <%_ } -%>
     <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
     app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
     <%_ } -%>

package/templates/clean-architecture/ts/src/config/env.ts.ejs

@@ -34,12 +34,22 @@ const envSchema = z.object({
 <%_ if (communication === 'Kafka') { -%>
   KAFKA_BROKER: z.string(),
 <%_ } -%>
-<%_ if (auth.includes('JWT')) { -%>
+<%_ if (auth.includes('JWT')) { _%>
   JWT_SECRET: z.string(),
   JWT_EXPIRES_IN: z.string().default('15m'),
   JWT_REFRESH_SECRET: z.string().default('your-secret-refresh-key'),
   JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
-<%_ } -%>
+<%_ if (socialAuth && socialAuth.includes('Google')) { _%>
+  GOOGLE_CLIENT_ID: z.string(),
+  GOOGLE_CLIENT_SECRET: z.string(),
+  GOOGLE_CALLBACK_URL: z.string().optional(),
+<%_ } _%>
+<%_ if (socialAuth && socialAuth.includes('GitHub')) { _%>
+  GITHUB_CLIENT_ID: z.string(),
+  GITHUB_CLIENT_SECRET: z.string(),
+  GITHUB_CALLBACK_URL: z.string().optional(),
+<%_ } _%>
+<%_ } _%>
 });
 
 const _env = envSchema.safeParse(process.env);

package/templates/clean-architecture/ts/src/domain/user.ts.ejs

@@ -0,0 +1,14 @@
+export class User {
+    constructor(
+        public id: number | string | null,
+        public name: string,
+        public email: string,
+        public password?: string | null,
+        <%_ if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('Google')) { _%>
+        public googleId?: string | null,
+        <%_ } _%>
+        <%_ if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('GitHub')) { _%>
+        public githubId?: string | null,
+        <%_ } _%>
+    ) { }
+}

package/templates/clean-architecture/ts/src/index.ts.ejs

@@ -4,6 +4,7 @@ import cors from 'cors';
 import helmet from 'helmet';
 import hpp from 'hpp';
 import rateLimit from 'express-rate-limit';
+import cookieParser from 'cookie-parser';
 import logger from '@/infrastructure/log/logger';
 import morgan from 'morgan';
 import { errorMiddleware } from '@/utils/errorMiddleware';
@@ -50,6 +51,7 @@ app.use(cors({ origin: '*', methods: ['GET', 'POST', 'PUT', 'DELETE'] }));
 const limiter = rateLimit({ windowMs: 10 * 60 * 1000, max: 100 });
 app.use(limiter);
 
+app.use(cookieParser());
 app.use(express.json());
 app.use(morgan('combined', { stream: { write: (message) => logger.info(message.trim()) } }));
 

package/templates/clean-architecture/ts/src/infrastructure/repositories/UserRepository.spec.ts.ejs

@@ -9,6 +9,7 @@ jest.mock('@/infrastructure/database/models/User', () => {
       create: jest.fn(),
       findAll: jest.fn(),
       findByPk: jest.fn(),
+      findOne: jest.fn(),
       update: jest.fn(),
       destroy: jest.fn(),
       find: jest.fn(),
@@ -115,6 +116,29 @@ describe('UserRepository', () => {
         });
     });
 
+    describe('findByEmail', () => {
+        it('should find and return a user by email', async () => {
+            const email = 'test@example.com';
+<%_ if (database === 'MongoDB') { -%>
+            const mockDbRecord = { _id: { toString: () => '1' }, name: 'TestUser', email: 'test@example.com' };
+<%_ } else { -%>
+            const mockDbRecord = { id: '1', name: 'TestUser', email: 'test@example.com' };
+<%_ } -%>
+            (UserModel.findOne as jest.Mock).mockResolvedValue(mockDbRecord);
+
+            const result = await userRepository.findByEmail(email);
+
+            expect(result?.email).toBe(email);
+            expect(UserModel.findOne).toHaveBeenCalled();
+        });
+
+        it('should return null if email not found', async () => {
+            (UserModel.findOne as jest.Mock).mockResolvedValue(null);
+            const result = await userRepository.findByEmail('not@found.com');
+            expect(result).toBeNull();
+        });
+    });
+
     describe('getUsers', () => {
         it('should return a list of mapped UserEntities (Happy Path)', async () => {
             // Arrange