exp-node-server 1.1.7 → 2.0.0

package/templates/mongoose/package.json

@@ -4,40 +4,79 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
-    "build": "tsc"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "check": "tsc --noEmit"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "type": "commonjs",
+  "type": "module",
   "dependencies": {
+    "@agendajs/mongo-backend": "^4.0.3",
+    "agenda": "^6.2.6",
     "bcrypt": "^6.0.0",
     "cloudinary": "^2.7.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
-    "dotenv": "^17.2.3",
+    "dotenv": "^17.4.2",
     "express": "^5.1.0",
+    "express-rate-limit": "^8.7.1",
+    "helmet": "^8.3.0",
     "jsonwebtoken": "^9.0.2",
+    "mongodb": "^7.7.0",
+    "mongoose": "^9.11.2",
     "multer": "^2.0.2",
-    "nodemailer": "^7.0.9",
+    "nodemailer": "^8.0.5",
+    "passport": "^0.7.0",
+    "passport-facebook": "^3.0.0",
+    "passport-github": "^1.1.0",
+    "passport-google-oauth20": "^2.0.0",
+    "passport-oauth1": "^1.3.0",
+    "passport-oauth2": "^1.8.0",
+    "pino": "^10.3.1",
     "swagger-jsdoc": "^6.2.8",
     "swagger-ui-express": "^5.0.1",
-    "ts-node-dev": "^2.0.0",
     "zod": "^4.1.12"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/bcrypt": "^6.0.0",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/mongoose": "^5.11.96",
     "@types/multer": "^2.0.0",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.12.2",
     "@types/nodemailer": "^7.0.2",
+    "@types/passport": "^1.0.17",
+    "@types/passport-facebook": "^3.0.4",
+    "@types/passport-github": "^1.1.13",
+    "@types/passport-google-oauth20": "^2.0.17",
+    "@types/passport-oauth2": "^1.8.0",
+    "@types/supertest": "^7.2.1",
     "@types/swagger-jsdoc": "^6.0.4",
-    "@types/swagger-ui-express": "^4.1.8"
+    "@types/swagger-ui-express": "^4.1.8",
+    "@typescript-eslint/eslint-plugin": "^8.59.0",
+    "@typescript-eslint/parser": "^8.59.0",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "mongodb-memory-server": "^11.3.0",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.8.3",
+    "supertest": "^7.3.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^5.0.4"
+  },
+  "engines": {
+    "node": ">=22.12.0"
   }
 }

package/templates/mongoose/readme.md

@@ -93,9 +93,94 @@ Swagger docs available at:
 http://localhost:5000/docs
 ```
 
+## 🔐 Environment
+
+Copy `.env.example` to `.env` and fill it in. The app validates its environment
+on startup and exits with a list of anything missing or invalid.
+
+`ACCESS_TOKEN`, `VERIFIED_TOKEN` and `RESET_SECRET` must be **different** random
+values of at least 32 characters:
+
+```bash
+openssl rand -hex 32
+```
+
+## 🗄️ Database
+
+`docker compose up -d` starts MongoDB on `localhost:27017` (matching `DATABASE_URL`
+in `.env.example`). Indexes (unique email, TTLs) are created automatically on start.
+
+## 📬 Background Jobs
+
+Emails (account verification and password reset) are sent through a single
+`email` job powered by [Agenda](https://github.com/agenda/agenda). Jobs are stored
+in the same MongoDB (`agendaJobs` collection), so no Redis is needed. Failed sends
+are retried with exponential backoff, and finished jobs are deleted because they
+carry OTPs and reset links.
+
+To add a new email, add a variant to `EmailJob` in `src/app/queues/email.queue.ts`
+and handle it in `render()`.
+
+## 🔐 Sessions & Refresh Tokens
+
+Signing in (password or social) returns a short-lived **access token** (`ACCESS_EXPIRES`,
+15 minutes by default) and a **refresh token** (`REFRESH_EXPIRES_DAYS`, 30 by default).
+Both are also set as httpOnly cookies; the refresh cookie is only sent to `/api/auth`.
+
+- `POST /api/auth/refresh-token`: when the access token expires (401), get new tokens.
+  Browsers send the cookie automatically; other clients send `{ "refreshToken": "..." }`.
+- `POST /api/auth/sign-out`: ends this device's session.
+- `POST /api/auth/sign-out-all`: ends every session (also happens on password change/reset).
+
+Refresh tokens are random strings stored only as hashes, and are **rotated** on every
+refresh. If an already-used refresh token shows up again, it was most likely stolen,
+so the whole session is revoked. (A reuse within 30 seconds is treated as two tabs
+refreshing at once and only that request fails.)
+
+## 🔑 Social Login
+
+Supported: **Google, Facebook, GitHub, X (Twitter), LinkedIn and Discord**. Set
+`IS_<PROVIDER>_LOGIN=true` and fill in the credentials in `.env`.
+
+- `GET /api/auth/social/providers`: enabled providers, for rendering buttons
+- `GET /api/auth/social/<provider>?returnTo=/dashboard`: start the login (a link, not `fetch`)
+- `GET /api/auth/social/<provider>/callback`: OAuth callback (register this URL at the provider)
+- `POST /api/auth/social/exchange` `{ "code": "..." }`: trade the code for an access token
+
+After the provider, the browser lands on `SOCIAL_REDIRECT_URL` (default
+`FRONT_END_URL/auth/social/callback`) with either `?code=...&returnTo=...` or
+`?error=...`. The front-end posts the code (single-use, valid for 60 seconds) to
+`/exchange`, which returns the access token and sets the cookie, like `/sign-in`.
+
+Every login is protected by an OAuth `state` (and PKCE for Google), stored in a
+short-lived encrypted cookie, so no session store is needed. Identities are linked
+by the provider's user id, and only verified provider emails are used to create or
+link accounts. Providers are defined in `src/app/passport-js/providers.ts`.
+
+## 🛡️ Rate Limiting
+
+The auth endpoints have their own limits (sign-in per IP + email, emails per
+recipient, OTP / reset guesses per IP), stored in the `rate_limits` collection so they are
+shared by every instance — no Redis needed. A TTL index removes expired counters.
+The whole API also has a lenient per-instance in-memory limit. Tune them in
+`src/app/middlewares/rate_limiter.ts`, and set `TRUST_PROXY` when running behind a
+proxy so the real client IP is used.
+
+## 🧪 Tests
+
+```bash
+npm test
+```
+
+Route tests with [supertest](https://github.com/ladjs/supertest) run each request
+through the route, controller and service against a real in-memory MongoDB
+([mongodb-memory-server](https://github.com/typegoose/mongodb-memory-server), downloaded
+on the first run). Only the email queue and Cloudinary are mocked.
+
 ## 🧠 Tech Stack
 
 - Express.js — Backend framework
+- Agenda — MongoDB job queue
 - TypeScript — Strongly typed JavaScript
 - Mongoose — MongoDB ODM
 - Prisma — PostgreSQL ORM

package/templates/mongoose/src/app/configs/index.ts

@@ -1,26 +1,178 @@
-import "dotenv/config";
-
-export const configs = {
-  port: process.env.PORT,
-  env: process.env.NODE_ENV,
-  db_url: process.env.DATABASE_URL,
-  jwt: {
-    access_token: process.env.ACCESS_TOKEN,
-    refresh_token: process.env.REFRESH_TOKEN,
-    access_expires: process.env.ACCESS_EXPIRES,
-    refresh_expires: process.env.REFRESH_EXPIRES,
-    reset_secret: process.env.RESET_SECRET,
-    reset_expires: process.env.RESET_EXPIRES,
-    front_end_url: process.env.FRONT_END_URL,
-    verified_token: process.env.VERIFIED_TOKEN,
-  },
-  email: {
-    app_email: process.env.APP_USER_EMAIL,
-    app_password: process.env.APP_PASSWORD,
-  },
-  cloudinary: {
-    cloud_name: process.env.CLOUD_NAME,
-    cloud_api_key: process.env.CLOUD_API_KEY,
-    cloud_api_secret: process.env.CLOUD_API_SECRET,
-  },
-};
+import 'dotenv/config';
+import { z } from 'zod';
+
+const bool = z
+  .enum(['true', 'false'])
+  .default('false')
+  .transform((v) => v === 'true');
+
+// JWT/session secrets must be long and random, e.g. `openssl rand -hex 32`
+const secret = z.string().min(32, 'must be at least 32 characters');
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().int().positive().default(5000),
+  // mongodb:// or mongodb+srv:// (replica set host lists aren't valid URLs, so no z.url())
+  DATABASE_URL: z
+    .string()
+    .regex(/^mongodb(\+srv)?:\/\/\S+$/, 'must be a MongoDB connection string'),
+
+  // auth
+  ACCESS_TOKEN: secret,
+  // short-lived; clients get a new one from POST /api/auth/refresh-token
+  ACCESS_EXPIRES: z.string().default('15m'),
+  REFRESH_EXPIRES_DAYS: z.coerce.number().int().positive().default(30),
+  VERIFIED_TOKEN: secret,
+  RESET_SECRET: secret,
+  RESET_EXPIRES: z.string().default('15m'),
+  FRONT_END_URL: z.url(),
+  CORS_ORIGINS: z.string().optional(),
+  TRUST_PROXY: z.coerce.number().int().min(0).default(0),
+
+  // email
+  APP_USER_EMAIL: z.string().optional(),
+  APP_PASSWORD: z.string().optional(),
+  MAIL_FROM: z.string().optional(),
+
+  // cloudinary
+  CLOUD_NAME: z.string().optional(),
+  CLOUD_API_KEY: z.string().optional(),
+  CLOUD_API_SECRET: z.string().optional(),
+
+  // swagger
+  ENABLE_SWAGGER: z.enum(['true', 'false']).optional(),
+  DEVELOPMENT_BASE_URL: z.string().default('http://localhost:5000'),
+  PRODUCTION_BASE_URL: z.string().default(''),
+
+  // social login
+  // where the browser is sent after a social login, with `?code=` or `?error=`
+  SOCIAL_REDIRECT_URL: z.url().optional(),
+
+  IS_GOOGLE_LOGIN: bool,
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+  GOOGLE_CALLBACK_URL: z.string().optional(),
+
+  IS_FACEBOOK_LOGIN: bool,
+  FACEBOOK_APP_ID: z.string().optional(),
+  FACEBOOK_APP_SECRET: z.string().optional(),
+  FACEBOOK_CALLBACK_URL: z.string().optional(),
+
+  IS_GITHUB_LOGIN: bool,
+  GITHUB_CLIENT_ID: z.string().optional(),
+  GITHUB_CLIENT_SECRET: z.string().optional(),
+  GITHUB_CALLBACK_URL: z.string().optional(),
+
+  IS_TWITTER_LOGIN: bool,
+  TWITTER_CONSUMER_KEY: z.string().optional(),
+  TWITTER_CONSUMER_SECRET: z.string().optional(),
+  TWITTER_CALLBACK_URL: z.string().optional(),
+
+  IS_LINKEDIN_LOGIN: bool,
+  LINKEDIN_CLIENT_ID: z.string().optional(),
+  LINKEDIN_CLIENT_SECRET: z.string().optional(),
+  LINKEDIN_CALLBACK_URL: z.string().optional(),
+
+  IS_DISCORD_LOGIN: bool,
+  DISCORD_CLIENT_ID: z.string().optional(),
+  DISCORD_CLIENT_SECRET: z.string().optional(),
+  DISCORD_CALLBACK_URL: z.string().optional(),
+});
+
+type Env = z.infer<typeof envSchema>;
+
+// logger depends on configs, so failures here are reported with console
+const fail = (message: string): never => {
+  // eslint-disable-next-line no-console
+  console.error(message);
+  process.exit(1);
+};
+
+const parsed = envSchema.safeParse(process.env);
+if (!parsed.success) {
+  const issues = parsed.error.issues.map((i) => `  - ${i.path.join('.')}: ${i.message}`);
+  fail(`Invalid environment variables:\n${issues.join('\n')}`);
+}
+const env = parsed.data as Env;
+
+/** Credentials for a social provider; all are required once the provider is enabled. */
+const provider = (enabled: boolean, keys: [keyof Env, keyof Env, keyof Env]) => {
+  const [clientId, clientSecret, callbackUrl] = keys.map((key) => {
+    const value = env[key];
+    if (enabled && (typeof value !== 'string' || !value)) {
+      fail(`${key} is required when its login provider is enabled`);
+    }
+    return typeof value === 'string' ? value : '';
+  }) as [string, string, string];
+
+  return { enabled, client_id: clientId, client_secret: clientSecret, callback_url: callbackUrl };
+};
+
+export const configs = {
+  port: env.PORT,
+  env: env.NODE_ENV,
+  is_production: env.NODE_ENV === 'production',
+  is_test: env.NODE_ENV === 'test',
+  db_url: env.DATABASE_URL,
+  cors_origins: (env.CORS_ORIGINS ?? env.FRONT_END_URL).split(',').map((o) => o.trim()),
+  trust_proxy: env.TRUST_PROXY,
+  enable_swagger: env.ENABLE_SWAGGER
+    ? env.ENABLE_SWAGGER === 'true'
+    : env.NODE_ENV !== 'production',
+  jwt: {
+    access_token: env.ACCESS_TOKEN,
+    access_expires: env.ACCESS_EXPIRES,
+    refresh_expires_days: env.REFRESH_EXPIRES_DAYS,
+    reset_secret: env.RESET_SECRET,
+    reset_expires: env.RESET_EXPIRES,
+    verified_token: env.VERIFIED_TOKEN,
+    front_end_url: env.FRONT_END_URL,
+  },
+  email: {
+    app_email: env.APP_USER_EMAIL,
+    app_password: env.APP_PASSWORD,
+    from: env.MAIL_FROM ?? env.APP_USER_EMAIL,
+  },
+  cloudinary: {
+    cloud_name: env.CLOUD_NAME,
+    cloud_api_key: env.CLOUD_API_KEY,
+    cloud_api_secret: env.CLOUD_API_SECRET,
+  },
+  swagger_config: {
+    development_base_url: env.DEVELOPMENT_BASE_URL,
+    production_base_url: env.PRODUCTION_BASE_URL,
+  },
+  social: {
+    redirect_url: env.SOCIAL_REDIRECT_URL ?? `${env.FRONT_END_URL}/auth/social/callback`,
+    google: provider(env.IS_GOOGLE_LOGIN, [
+      'GOOGLE_CLIENT_ID',
+      'GOOGLE_CLIENT_SECRET',
+      'GOOGLE_CALLBACK_URL',
+    ]),
+    facebook: provider(env.IS_FACEBOOK_LOGIN, [
+      'FACEBOOK_APP_ID',
+      'FACEBOOK_APP_SECRET',
+      'FACEBOOK_CALLBACK_URL',
+    ]),
+    github: provider(env.IS_GITHUB_LOGIN, [
+      'GITHUB_CLIENT_ID',
+      'GITHUB_CLIENT_SECRET',
+      'GITHUB_CALLBACK_URL',
+    ]),
+    twitter: provider(env.IS_TWITTER_LOGIN, [
+      'TWITTER_CONSUMER_KEY',
+      'TWITTER_CONSUMER_SECRET',
+      'TWITTER_CALLBACK_URL',
+    ]),
+    linkedin: provider(env.IS_LINKEDIN_LOGIN, [
+      'LINKEDIN_CLIENT_ID',
+      'LINKEDIN_CLIENT_SECRET',
+      'LINKEDIN_CALLBACK_URL',
+    ]),
+    discord: provider(env.IS_DISCORD_LOGIN, [
+      'DISCORD_CLIENT_ID',
+      'DISCORD_CLIENT_SECRET',
+      'DISCORD_CALLBACK_URL',
+    ]),
+  },
+};

package/templates/mongoose/src/app/errors/zodError.ts

@@ -1,20 +1,20 @@
-import { ZodError, ZodIssue } from 'zod'
-import { TErrorSources, TGenericErrorResponse } from '../types/error'
+import { ZodError, ZodIssue } from 'zod';
+import { TErrorSources, TGenericErrorResponse } from '../types/error.js';
 
 const handleZodError = (err: ZodError): TGenericErrorResponse => {
-    const errorSources: TErrorSources = err.issues.map((issue: ZodIssue) => {
-        return {
-            path: issue?.path[issue.path.length - 1] as string,
-            message: issue.message
-        }
-    })
-
-    const statusCode = 400
+  const errorSources: TErrorSources = err.issues.map((issue: ZodIssue) => {
     return {
-        statusCode,
-        message: 'Validation Error',
-        errorSources
-    }
-}
+      path: issue?.path[issue.path.length - 1] as string,
+      message: issue.message,
+    };
+  });
+
+  const statusCode = 400;
+  return {
+    statusCode,
+    message: 'Validation Error',
+    errorSources,
+  };
+};
 
-export default handleZodError
+export default handleZodError;

package/templates/mongoose/src/app/lib/db.ts

@@ -0,0 +1,18 @@
+import mongoose from 'mongoose';
+import { configs } from '../configs/index.js';
+import { logger } from './logger.js';
+
+// reject unknown fields in queries instead of silently ignoring them
+mongoose.set('strictQuery', true);
+
+export const connectDatabase = async () => {
+  await mongoose.connect(configs.db_url, {
+    // fail fast on startup instead of buffering queries forever
+    serverSelectionTimeoutMS: 10_000,
+    // autoIndex stays on: the unique email and TTL indexes are needed for correctness
+  });
+  mongoose.connection.on('error', (err) => logger.error(err, 'MongoDB error'));
+  logger.info('Connected to MongoDB');
+};
+
+export const disconnectDatabase = () => mongoose.disconnect();

package/templates/mongoose/src/app/lib/logger.ts

@@ -0,0 +1,12 @@
+import pino from 'pino';
+import { configs } from '../configs/index.js';
+
+export const logger = pino({
+  level: configs.is_test ? 'silent' : configs.env === 'development' ? 'debug' : 'info',
+  transport:
+    configs.env === 'development'
+      ? {
+          target: 'pino-pretty',
+        }
+      : undefined,
+});

package/templates/mongoose/src/app/middlewares/auth.ts

@@ -1,50 +1,54 @@
-import { NextFunction, Request, Response } from 'express';
-import { AppError } from '../utils/app_error';
-import { configs } from '../configs';
-import { jwtHelpers, JwtPayloadType } from '../utils/JWT';
-import { Account_Model } from '../modules/auth/auth.schema';
+import { isValidObjectId } from 'mongoose';
+import type { NextFunction, Request, Response } from 'express';
+import { configs } from '../configs/index.js';
+import type { ROLE } from '../modules/account/account.interface.js';
+import { account_model } from '../modules/account/account.schema.js';
+import { AppError } from '../utils/app_error.js';
+import { ACCESS_TOKEN_COOKIE } from '../utils/auth_cookie.js';
+import { type JwtPayloadType, jwtHelpers } from '../utils/JWT.js';
 
+const getToken = (req: Request): string | undefined => {
+  const header = req.headers.authorization;
+  if (header) return header.startsWith('Bearer ') ? header.slice(7) : header;
+  return req.cookies?.[ACCESS_TOKEN_COOKIE];
+};
+
+/**
+ * Requires a valid access token. With roles, also requires one of them:
+ * `auth()` = any signed-in user, `auth('ADMIN')` = admins only.
+ */
+const auth = (...roles: ROLE[]) => {
+  return async (req: Request, _res: Response, next: NextFunction) => {
+    try {
+      const token = getToken(req);
+      if (!token) {
+        throw new AppError('You are not authorized', 401);
+      }
+
+      const payload = jwtHelpers.verifyToken<JwtPayloadType>(token, configs.jwt.access_token);
 
-type Role = "ADMIN" | "USER"
+      // tokens outlive account changes, so check the account is still active and
+      // the token wasn't revoked (password change/reset, sign out everywhere)
+      const account = isValidObjectId(payload.accountId)
+        ? await account_model
+            .findById(payload.accountId)
+            .select('email role isDeleted tokenVersion')
+            .lean()
+        : null;
+      if (!account || account.isDeleted || account.tokenVersion !== payload.tv) {
+        throw new AppError('You are not authorized', 401);
+      }
 
+      if (roles.length && !roles.includes(account.role)) {
+        throw new AppError('You do not have permission to perform this action', 403);
+      }
 
-const auth = (...roles: Role[]) => {
-    return async (req: Request, res: Response, next: NextFunction) => {
-        try {
-            const token = req.headers.authorization;
-            if (!token) {
-                throw new AppError('You are not authorize!!', 401);
-            }
-            const verifiedUser = jwtHelpers.verifyToken(
-                token,
-                configs.jwt.access_token as string,
-            );
-            if (!roles.length || !roles.includes(verifiedUser.role)) {
-                throw new AppError('You are not authorize!!', 401);
-            }
-            // check user
-            const isUserExist = await Account_Model.findOne({ email: verifiedUser?.email }).lean()
-            if (!isUserExist) {
-                throw new AppError("Account not found !", 404)
-            }
-            if (isUserExist?.accountStatus == "SUSPENDED") {
-                throw new AppError("This Account is suspended !", 401)
-            }
-            if (isUserExist?.accountStatus == "INACTIVE") {
-                throw new AppError("This Account is inactive !", 401)
-            }
-            if (isUserExist?.isDeleted) {
-                throw new AppError("This account is deleted", 401)
-            }
-            if (!isUserExist?.isVerified) {
-                throw new AppError("This account is not verified ", 401)
-            }
-            req.user = verifiedUser as JwtPayloadType;
-            next();
-        } catch (err) {
-            next(err);
-        }
-    };
+      req.user = { accountId: String(account._id), email: account.email, role: account.role };
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
 };
 
-export default auth;
+export default auth;