create-express-mongo-ts 1.0.0

package/template/src/middlewares/error.middleware.ts

@@ -0,0 +1,42 @@
+import { NextFunction, Request, Response } from 'express';
+import logger from './../core/logger.js';
+import { isProduction } from './../config.js';
+import { ApiError, ErrorType } from './../core/ApiError.js';
+
+export const errorHandler = (
+    err: Error,
+    req: Request,
+    res: Response,
+    _next: NextFunction,
+) => {
+    let statusCode = 500;
+    let message = 'Something went wrong';
+    const errors: string[] = [];
+
+    logger.error('Error:', {
+        error: err,
+    });
+
+    if (err instanceof ApiError) {
+        ApiError.handle(err, res);
+        if (err.type === ErrorType.INTERNAL)
+            logger.error(
+                `500 - ${err.message} - ${req.originalUrl} - ${req.method} - ${req.ip}`,
+            );
+        return;
+    }
+
+    if (!isProduction) {
+        message = err?.message || message;
+        errors.push(err?.message);
+    }
+
+    res.status(statusCode).json({
+        success: false,
+        statusCode,
+        message,
+        ...(errors.length > 0 && !isProduction && { errors }),
+        timeStamp: new Date().toISOString(),
+        path: req.originalUrl,
+    });
+};

package/template/src/middlewares/permission.middleware.ts

@@ -0,0 +1,20 @@
+import { Response, NextFunction } from 'express';
+import { ForbiddenError } from '../core/ApiError';
+import { PublicRequest } from '../types/app-requests';
+
+export default (permission: string) =>
+    (req: PublicRequest, _res: Response, next: NextFunction) => {
+        try {
+            if (!req.apiKey?.permissions)
+                return next(new ForbiddenError('Permission Denied'));
+
+            const exists = req.apiKey.permissions.find(
+                (entry) => entry === permission,
+            );
+            if (!exists) return next(new ForbiddenError('Permission Denied'));
+
+            next();
+        } catch (error) {
+            next(error);
+        }
+    };

package/template/src/middlewares/validator.middleware.ts

@@ -0,0 +1,170 @@
+import { RequestHandler } from 'express';
+import { ZodSchema } from 'zod';
+
+import { BadRequestError } from './../core/ApiError';
+import { isProduction } from '../config.js';
+import { ValidationSource } from './../helpers/validator';
+
+type ValidationErrorDetail = {
+    field: string;
+    message: string;
+    value?: unknown;
+};
+
+const formatFieldName = (path: (string | number)[]): string => {
+    if (path.length === 0) return 'body';
+
+    return path
+        .map((segment, index) => {
+            if (typeof segment === 'number') {
+                return `[${segment}]`;
+            }
+            // Convert camelCase to readable format
+            const readable = segment.replace(/([A-Z])/g, ' $1').toLowerCase();
+            return index === 0 ? readable : segment;
+        })
+        .join('.');
+};
+
+const getReadableErrorMessage = (
+    code: string,
+    path: (string | number)[],
+    message: string,
+    received?: unknown,
+    expected?: string[],
+): string => {
+    const fieldName = formatFieldName(path);
+
+    switch (code) {
+        case 'invalid_type':
+            if (received === 'undefined' || received === 'null') {
+                return `${fieldName} is required`;
+            }
+            return `${fieldName} must be a valid ${expected}`;
+
+        case 'invalid_string':
+            if (message.includes('email')) {
+                return `${fieldName} must be a valid email address`;
+            }
+            if (message.includes('url')) {
+                return `${fieldName} must be a valid URL`;
+            }
+            if (message.includes('uuid')) {
+                return `${fieldName} must be a valid UUID`;
+            }
+            return `${fieldName} format is invalid`;
+
+        case 'too_small':
+            if (message.includes('String')) {
+                const minMatch = message.match(/at least (\d+)/);
+                const min = minMatch ? minMatch[1] : 'minimum';
+                return `${fieldName} must be at least ${min} characters long`;
+            }
+            if (message.includes('Number')) {
+                const minMatch = message.match(
+                    /greater than or equal to (\d+)/,
+                );
+                const min = minMatch ? minMatch[1] : 'minimum value';
+                return `${fieldName} must be greater than or equal to ${min}`;
+            }
+            if (message.includes('Array')) {
+                const minMatch = message.match(/at least (\d+)/);
+                const min = minMatch ? minMatch[1] : 'minimum';
+                return `${fieldName} must contain at least ${min} item(s)`;
+            }
+            return message;
+
+        case 'too_big':
+            if (message.includes('String')) {
+                const maxMatch = message.match(/at most (\d+)/);
+                const max = maxMatch ? maxMatch[1] : 'maximum';
+                return `${fieldName} must be at most ${max} characters long`;
+            }
+            if (message.includes('Number')) {
+                const maxMatch = message.match(/less than or equal to (\d+)/);
+                const max = maxMatch ? maxMatch[1] : 'maximum value';
+                return `${fieldName} must be less than or equal to ${max}`;
+            }
+            if (message.includes('Array')) {
+                const maxMatch = message.match(/at most (\d+)/);
+                const max = maxMatch ? maxMatch[1] : 'maximum';
+                return `${fieldName} must contain at most ${max} item(s)`;
+            }
+            return message;
+
+        case 'invalid_enum_value':
+            const options = expected?.join(', ') || 'valid options';
+            return `${fieldName} must be one of: ${options}`;
+
+        case 'unrecognized_keys':
+            const keys = message.match(
+                /Unrecognized key\(s\) in object: (.+)/,
+            )?.[1];
+            return keys
+                ? `Unexpected field(s): ${keys}`
+                : 'Unexpected fields in request';
+
+        case 'invalid_date':
+            return `${fieldName} must be a valid date`;
+
+        case 'invalid_literal':
+            return `${fieldName} must be exactly ${expected}`;
+
+        case 'custom':
+            return message; // Custom error messages are already descriptive
+
+        default:
+            return message || `${fieldName} is invalid`;
+    }
+};
+
+type ZodSafeError = {
+    path: string[];
+    code: string;
+    message: string;
+    expected: string[];
+};
+
+export const validator = (
+    schema: ZodSchema,
+    source: ValidationSource,
+): RequestHandler => {
+    return (req, _res, next): void => {
+        const result = schema.safeParse(req[source]);
+
+        if (!result.success) {
+            const errors: ZodSafeError[] = JSON.parse(String(result.error));
+            const validationErrors: ValidationErrorDetail[] = errors.map(
+                (err: {
+                    path: string[];
+                    code: string;
+                    message: string;
+                    expected: string[];
+                }) => ({
+                    field: formatFieldName(err.path),
+                    message: getReadableErrorMessage(
+                        err.code,
+                        err.path,
+                        err.message,
+                        'received' in err ? err.received : undefined,
+                        'expected' in err ? err.expected : undefined,
+                    ),
+                    ...(!isProduction && {
+                        value: err.path.reduce(
+                            (obj: Record<string, unknown>, key: string | number) => obj?.[key],
+                            req.body,
+                        ),
+                    }),
+                }),
+            );
+
+            const mainMessage =
+                validationErrors.length === 1
+                    ? validationErrors[0].message
+                    : `Validation failed for ${validationErrors.length} field(s)`;
+
+            return next(new BadRequestError(mainMessage));
+        }
+        next();
+    };
+};

package/template/src/routes/auth/apiKey.ts

@@ -0,0 +1,29 @@
+import { Response, NextFunction } from 'express';
+import schema from './schema';
+import { validator } from './../../middlewares/validator.middleware';
+import { ValidationSource } from '../../helpers/validator';
+import { asyncHandler } from './../../core/asyncHandler';
+import { PublicRequest } from './../../types/app-requests';
+import { ForbiddenError } from './../../core/ApiError';
+import { Header } from './../../core/utils';
+import ApiKeyRepo from './../../database/repositories/ApiKeyRepo';
+
+export const apiKeyMiddleware = [
+    validator(schema.apiKey, ValidationSource.HEADER),
+
+    asyncHandler<PublicRequest>(
+        async (req: PublicRequest, _res: Response, next: NextFunction) => {
+            const key = req.headers[Header.API_KEY]?.toString();
+
+            if (!key) throw new ForbiddenError('Missing API Key');
+
+            const apiKey = await ApiKeyRepo.findByKey(key);
+
+            if (!apiKey) throw new ForbiddenError('Invalid API Key');
+
+            req.apiKey = apiKey;
+
+            next();
+        },
+    ),
+];

package/template/src/routes/auth/authentication.ts

@@ -0,0 +1,45 @@
+import { Router } from 'express';
+import { validator } from '../../middlewares/validator.middleware';
+import schema from './schema';
+import { ValidationSource } from '../../helpers/validator';
+import { asyncHandler } from '../../core/asyncHandler';
+import { ProtectedRequest } from '../../types/app-requests';
+import { getAccessToken, validateTokenData } from '../../core/authUtils';
+import { TokenExpiredError } from 'jsonwebtoken';
+import { AccessTokenError, AuthFailureError } from '../../core/ApiError';
+import jwtUtils from '../../core/jwtUtils';
+import UserRepo from '../../database/repositories/UserRepo';
+import { Types } from 'mongoose';
+import KeystoreRepo from '../../database/repositories/KeystoreRepo';
+const router = Router();
+
+export default router.use(
+    validator(schema.auth, ValidationSource.HEADER),
+    asyncHandler(async (req: ProtectedRequest, _res, next) => {
+        req.accessToken = getAccessToken(req.headers.authorization);
+
+        try {
+            const payload = await jwtUtils.validate(req.accessToken);
+            validateTokenData(payload);
+
+            const user = await UserRepo.findById(
+                new Types.ObjectId(payload.sub),
+            );
+            if (!user) throw new AuthFailureError('User not registered.');
+            req.user = user;
+
+            const keystore = await KeystoreRepo.findForKey(
+                req.user,
+                payload.prm,
+            );
+            if (!keystore) throw new AuthFailureError('Invalid access token.');
+            req.keystore = keystore;
+
+            return next();
+        } catch (e) {
+            if (e instanceof TokenExpiredError)
+                throw new AccessTokenError(e.message);
+            throw e;
+        }
+    }),
+);

package/template/src/routes/auth/index.ts

@@ -0,0 +1,14 @@
+import { Router } from 'express';
+import signupRoute from './signup';
+import signinRoute from './signin';
+import signoutRoute from './signout';
+import refreshTokenRouter from './token';
+
+const router = Router();
+
+router.use('/signup', signupRoute);
+router.use('/signin', signinRoute);
+router.use('/signout', signoutRoute);
+router.use('/token', refreshTokenRouter);
+
+export default router;

package/template/src/routes/auth/schema.ts

@@ -0,0 +1,34 @@
+import { Header } from './../../core/utils';
+import { ZodAuthBearer } from './../../helpers/validator';
+import z from 'zod';
+
+const apiKey = z.object({
+    [Header.API_KEY]: z.string(),
+});
+
+const auth = z.object({
+    authorization: ZodAuthBearer,
+});
+
+const signup = z.object({
+    name: z.string().min(3),
+    email: z.email(),
+    password: z.string().min(6),
+});
+
+const signin = z.object({
+    email: z.email(),
+    password: z.string().min(6),
+});
+
+const refreshToken = z.object({
+    refreshToken: z.string().min(1)
+});
+
+export default {
+    apiKey,
+    auth,
+    signup,
+    signin,
+    refreshToken
+};

package/template/src/routes/auth/signin.ts

@@ -0,0 +1,47 @@
+import { asyncHandler } from '../../core/asyncHandler';
+import { Router } from 'express';
+import { validator } from '../../middlewares/validator.middleware';
+import schema from './schema';
+import { PublicRequest } from '../../types/app-requests';
+import UserRepo from '../../database/repositories/UserRepo';
+import { AuthFailureError, BadRequestError } from '../../core/ApiError';
+import crypto from 'crypto';
+import KeystoreRepo from '../../database/repositories/KeystoreRepo';
+import { createTokens, isPasswordCorrect } from '../../core/authUtils';
+import { getUserData } from '../../core/utils';
+import { SuccessResponse } from '../../core/ApiResponse';
+import { ValidationSource } from '../../helpers/validator';
+
+const router = Router();
+
+router.post(
+    '/',
+    validator(schema.signin, ValidationSource.BODY),
+    asyncHandler(async (req: PublicRequest, res) => {
+        const user = await UserRepo.findByEmail(req.body.email);
+
+        if (!user) throw new BadRequestError('User not registered.');
+
+        const isValid = await isPasswordCorrect(req.body.password, user.password);
+
+        if (!isValid) throw new AuthFailureError('Authentication failure.');
+
+        const accessTokenKey = crypto.randomBytes(64).toString('hex');
+        const refreshTokenKey = crypto.randomBytes(64).toString('hex');
+
+        await KeystoreRepo.create(user, accessTokenKey, refreshTokenKey);
+        const tokens = await createTokens(
+            user,
+            accessTokenKey,
+            refreshTokenKey,
+        );
+        const userData = getUserData(user);
+
+        new SuccessResponse('Login success.', {
+            user: userData,
+            tokens: tokens,
+        }).send(res);
+    }),
+);
+
+export default router;

package/template/src/routes/auth/signout.ts

@@ -0,0 +1,20 @@
+import { SuccessMsgResponse } from '../../core/ApiResponse';
+import { asyncHandler } from '../../core/asyncHandler';
+import KeystoreRepo from '../../database/repositories/KeystoreRepo';
+import { Router } from 'express';
+import authentication from './authentication';
+import { ProtectedRequest } from '../../types/app-requests';
+
+const router = Router();
+
+router.use(authentication);
+
+router.delete(
+    '/',
+    asyncHandler(async (req: ProtectedRequest, res) => {
+        await KeystoreRepo.remove(req.keystore._id);
+        new SuccessMsgResponse('Logout Success').send(res);
+    }),
+);
+
+export default router;

package/template/src/routes/auth/signup.ts

@@ -0,0 +1,49 @@
+import { Router } from 'express';
+import { validator } from '../../middlewares/validator.middleware';
+import schema from './schema';
+import { asyncHandler } from './../../core/asyncHandler';
+import UserRepo from '../../database/repositories/UserRepo';
+import { BadRequestError } from '../../core/ApiError';
+import crypto from 'crypto';
+import User from './../../types/User';
+import { createTokens } from '../../core/authUtils';
+import { getUserData } from './../../core/utils';
+import { SuccessResponse } from './../../core/ApiResponse';
+import { RoleCode } from './../../types/Role';
+import { ValidationSource } from '../../helpers/validator';
+
+const router = Router();
+
+router.post(
+    '/',
+    validator(schema.signup, ValidationSource.BODY),
+    asyncHandler(async (req, res) => {
+        const user = await UserRepo.findByEmail(req.body.email);
+        if (user) throw new BadRequestError('User already registered.');
+
+        const accessTokenKey = crypto.randomBytes(64).toString('hex');
+        const refreshTokenKey = crypto.randomBytes(64).toString('hex');
+
+        const { user: createdUser, keystore } = await UserRepo.create(
+            req.body as User,
+            accessTokenKey,
+            refreshTokenKey,
+            RoleCode.USER,
+        );
+
+        const tokens = await createTokens(
+            createdUser,
+            keystore.primaryKey,
+            keystore.secondaryKey,
+        );
+
+        const userData = getUserData(createdUser);
+
+        new SuccessResponse('Signup successful.', {
+            user: userData,
+            tokens: tokens,
+        }).send(res);
+    }),
+);
+
+export default router;

package/template/src/routes/auth/token.ts

@@ -0,0 +1,68 @@
+import { Router } from 'express';
+import { validator } from '../../middlewares/validator.middleware';
+import schema from './schema';
+import { ValidationSource } from '../../helpers/validator';
+import { asyncHandler } from '../../core/asyncHandler';
+import { ProtectedRequest } from '../../types/app-requests';
+import { getAccessToken } from '../../core/authUtils';
+import JWT from './../../core/jwtUtils';
+import { validateTokenData, createTokens } from './../../core/authUtils';
+import UserRepo from '../../database/repositories/UserRepo';
+import KeystoreRepo from '../../database/repositories/KeystoreRepo';
+import { Types } from 'mongoose';
+import { AuthFailureError } from '../../core/ApiError';
+import crypto from 'crypto';
+import { TokenRefreshResponse } from '../../core/ApiResponse';
+const router = Router();
+
+router.post(
+    '/refresh',
+    validator(schema.auth, ValidationSource.HEADER),
+    validator(schema.refreshToken, ValidationSource.BODY),
+    asyncHandler(async (req: ProtectedRequest, res) => {
+        req.accessToken = getAccessToken(req.headers?.authorization);
+
+        const accessTokenPayload = await JWT.decode(req.accessToken);
+        validateTokenData(accessTokenPayload);
+
+        const user = await UserRepo.findById(
+            new Types.ObjectId(accessTokenPayload.sub),
+        );
+
+        if (!user) throw new AuthFailureError('User not registered');
+        req.user = user;
+
+        const refreshTokenPayload = await JWT.validate(req.body.refreshToken);
+        validateTokenData(refreshTokenPayload);
+
+        if (accessTokenPayload.sub !== refreshTokenPayload.sub)
+            throw new AuthFailureError('Invalid access token');
+
+        const keystore = await KeystoreRepo.find(
+            req.user,
+            accessTokenPayload.prm,
+            refreshTokenPayload.prm,
+        );
+
+        if (!keystore) throw new AuthFailureError('Invalid access token');
+        await KeystoreRepo.remove(keystore._id);
+
+        const accessTokenKey = crypto.randomBytes(64).toString('hex');
+        const refreshTokenKey = crypto.randomBytes(64).toString('hex');
+
+        await KeystoreRepo.create(req.user, accessTokenKey, refreshTokenKey);
+        const tokens = await createTokens(
+            req.user,
+            accessTokenKey,
+            refreshTokenKey,
+        );
+
+        new TokenRefreshResponse(
+            'Token Issued',
+            tokens.accessToken,
+            tokens.refreshToken,
+        ).send(res);
+    }),
+);
+
+export default router;

package/template/src/routes/health/index.ts

@@ -0,0 +1,14 @@
+import { SuccessMsgResponse } from '../../core/ApiResponse';
+import { Router } from 'express';
+
+const router = Router();
+
+router.get('/', async (_req, res) => {
+    new SuccessMsgResponse('Sample API server is running.').send(res);
+});
+
+router.get('/health', async (_req, res) => {
+    new SuccessMsgResponse('The server is healthy and running.').send(res);
+});
+
+export default router;

package/template/src/routes/index.ts

@@ -0,0 +1,19 @@
+import { Router, RequestHandler } from 'express';
+
+import healthRoutes from "./health/index.js";
+import { apiKeyMiddleware } from './auth/apiKey.js';
+import permission  from '../middlewares/permission.middleware.js';
+import { Permission } from './../types/permissions';
+import authRoutes from "./auth";
+
+const router = Router();
+
+router.use('/', healthRoutes);
+
+router.use(apiKeyMiddleware);
+
+router.use(permission(Permission.GENERAL) as RequestHandler);
+
+router.use('/auth', authRoutes);
+
+export default router;

package/template/src/types/ApiKey.ts

@@ -0,0 +1,13 @@
+import { Types } from "mongoose";
+import { Permission } from "./permissions";
+
+export default interface ApiKey {
+    _id: Types.ObjectId;
+    key: string;
+    version: number;
+    permissions: Permission[];
+    comments: string[];
+    status?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/template/src/types/Keystore.ts

@@ -0,0 +1,12 @@
+import { Types } from "mongoose";
+import User from "./User";
+
+export default interface Keystore {
+    _id: Types.ObjectId;
+    client: User;
+    primaryKey: string;
+    secondaryKey: string;
+    status?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/template/src/types/Role.ts

@@ -0,0 +1,14 @@
+import { Types } from "mongoose";
+
+export enum RoleCode {
+    USER = "user",
+    ADMIN = "admin"
+}
+
+export default interface Role {
+    _id: Types.ObjectId;
+    code: string;
+    status?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/template/src/types/User.ts

@@ -0,0 +1,16 @@
+import { Types } from "mongoose";
+import Role  from "./Role.js";
+
+export default interface User {
+    _id: Types.ObjectId;
+    name?: string;
+    email: string;
+    password: string;
+    roles: Role[];
+    verified?: boolean;
+    status?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+
+    isPasswordCorrect(password: string): Promise<boolean>;
+}

package/template/src/types/app-requests.d.ts

@@ -0,0 +1,22 @@
+import { Request } from 'express';
+import User from '../database/models/User';
+import Keystore from '../database/models/Keystore';
+import ApiKey from './ApiKey';
+declare interface PublicRequest extends Request {
+    apiKey: ApiKey;
+}
+
+declare interface RoleRequest extends PublicRequest {
+    currentRoleCodes: string[];
+}
+
+declare interface ProtectedRequest extends RoleRequest {
+    user: User;
+    accessToken: string;
+    keystore: Keystore;
+}
+
+declare interface Tokens {
+    accessToken: string;
+    refreshToken: string;
+}

package/template/src/types/permissions.ts

@@ -0,0 +1,3 @@
+export enum Permission {
+    GENERAL = 'GENERAL',
+}