https://github.com/KhaledSaeed18/node-authentication-template
🔐 A Node.js authentication template built with TypeScript, Express and PostgreSQL with Prisma. Includes secure JWT-based authentication, email verification (OTP), password reset, 2FA with QR codes, login history tracking, rate limiting, role-based access control.
https://github.com/KhaledSaeed18/node-authentication-template
authentication backend-api eslint express google-gmail-api jsonwebtoken nodejs nodemailer nodemon postgresql prisma-orm qrcode-generator rate-limiting two-factor-authentication typescript zod-validation
Last synced: 4 months ago
JSON representation
🔐 A Node.js authentication template built with TypeScript, Express and PostgreSQL with Prisma. Includes secure JWT-based authentication, email verification (OTP), password reset, 2FA with QR codes, login history tracking, rate limiting, role-based access control.
- Host: GitHub
- URL: https://github.com/KhaledSaeed18/node-authentication-template
- Owner: KhaledSaeed18
- License: mit
- Created: 2025-03-09T17:25:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-21T16:27:20.000Z (about 1 year ago)
- Last Synced: 2025-03-21T16:55:43.288Z (about 1 year ago)
- Topics: authentication, backend-api, eslint, express, google-gmail-api, jsonwebtoken, nodejs, nodemailer, nodemon, postgresql, prisma-orm, qrcode-generator, rate-limiting, two-factor-authentication, typescript, zod-validation
- Language: TypeScript
- Homepage:
- Size: 82 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 🔐 Node Authentication Template
## Introduction
The Node Authentication Template is a robust, secure, and feature-rich authentication system built with Node.js and TypeScript. It provides a complete authentication solution with advanced security features including email verification, password reset, two-factor authentication (2FA), rate limiting, and more. This template is designed to be easily integrated into any Node.js project requiring secure user authentication.
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://expressjs.com/)
[](https://www.postgresql.org/)
[](https://www.prisma.io/)
[](https://jwt.io/)
[](https://www.npmjs.com/package/bcryptjs)
[](https://www.npmjs.com/package/speakeasy)
[](https://nodemailer.com/)
[](https://www.npmjs.com/package/googleapis)
[](https://github.com/colinhacks/zod)
[](https://www.npmjs.com/package/dotenv)
[](https://eslint.org/)
[](https://nodemon.io/)
## Tech Stack & Dependencies
### Core Technologies
- Node.js
- TypeScript
- Express.js
- PostgreSQL
- Prisma ORM
### Key Dependencies
**Authentication & Security:**
- jsonwebtoken: JWT implementation for token-based authentication
- bcryptjs: Password hashing library
- speakeasy & qrcode: TOTP-based two-factor authentication
- express-rate-limit: API rate limiting to prevent abuse
- sanitize-html: Input sanitization to prevent XSS attacks
**Email Services:**
- nodemailer: Email sending functionality
- googleapis: Google OAuth2 integration for email services
**Validation:**
- zod: Schema validation and type checking
**Development Tools:**
- dotenv: Environment variable management
- eslint: Code linting
- prisma: ORM and database migration tool
- nodemon: Automatic server restarts during development
- ts-node: TypeScript execution environment
## Environment Variables
Create a .env file in the root directory with the following variables:
``` .env
# Server Configurations
PORT=
API_VERSION=
BASE_URL=
# App Configurations
SALT_ROUNDS=
# Database Configurations
DATABASE_URL=
#JWT Configurations
JWT_SECRET=
JWT_REFRESH_SECRET=
# Email Configurations
CLIENT_ID=
CLIENT_SECRET=
REFRESH_TOKEN=
USER_EMAIL=
REDIRECT_URI=
```
## Running the Application
### Setup
1. **Clone the repository**
```bash
git clone https://github.com/KhaledSaeed18/node-authentication-template.git
cd node-authentication-template
```
2. **Install dependencies with Yarn**
```bash
yarn install
```
3. **Set up environment variables**
- Create a `.env` file in the root directory
- Add all required environment variables as described in the section above
### Development Mode
Run the server in development mode with hot-reloading:
```bash
yarn dev
```
### Production Mode
1. **Build the application**
```bash
yarn build
```
2. **Start the production server**
```bash
yarn start
```
### Additional Scripts
- **Apply database migrations**
```bash
yarn prisma migrate dev
```
- **Generate Prisma client**
```bash
yarn prisma generate
```
## Project Structure
The project follows a modular architecture for better organization and maintainability:
``` bash
├── .gitignore
├── eslint.config.mjs
├── package.json
├── prisma
│ └── schema.prisma
├── src
│ ├── api
│ │ └── auth
│ │ ├── auth.controller.ts
│ │ ├── auth.rateLimiting.ts
│ │ ├── auth.routes.ts
│ │ ├── auth.service.ts
│ │ └── auth.validation.ts
│ ├── constants
│ │ ├── auth.constants.ts
│ │ └── emailTemplates.ts
│ ├── index.ts
│ ├── mails
│ │ ├── email.ts
│ │ └── nodemailer.config.ts
│ ├── middlewares
│ │ ├── authorization.middleware.ts
│ │ ├── error.middleware.ts
│ │ ├── sanitizeBody.middleware.ts
│ │ └── securityHeaders.middleware.ts
│ └── utils
│ ├── errorHandler.ts
│ ├── generateOTP.ts
│ ├── generateTokens.ts
│ └── totp.ts
├── tsconfig.json
└── yarn.lock
```
### Key Components
- **api/auth**: Contains all authentication-related logic
- **constants**: Application-wide constants and configurations
- **mails**: Email service implementation
- **middlewares**: Express middlewares for security and request processing
- **utils**: Utility functions for common operations
## Features & Endpoints
### Authentication
#### User Registration & Verification
- `POST /api/v1/auth/signup`: Register a new user
- Required fields: firstName, lastName, email, password
- Creates user and sends verification email
- `POST /api/v1/auth/verify-email`: Verify email with OTP
- Required fields: email, code (6-digit)
- `POST /api/v1/auth/resend-verification`: Resend verification code
- Required fields: email
#### Login & Session Management
- `POST /api/v1/auth/signin`: User login
- Required fields: email, password
- Returns JWT tokens and user info
- Handles 2FA if enabled
- `POST /api/v1/auth/refresh-token`: Refresh access token
- Required fields: refreshToken
- Returns new access token
- `GET /api/v1/auth/login-history`: Get user login history
- Protected route (requires authorization)
- Returns list of login attempts with device info
#### Password Management
- `POST /api/v1/auth/forgot-password`: Initiate password reset
- Required fields: email
- Sends password reset code via email
- `POST /api/v1/auth/reset-password`: Reset password with code
- Required fields: email, code, newPassword
#### Two-Factor Authentication (2FA)
- `POST /api/v1/auth/2fa/setup`: Set up 2FA
- Protected route
- Returns QR code and secret for TOTP apps
- `POST /api/v1/auth/2fa/verify`: Verify and enable 2FA
- Protected route
- Required fields: token (6-digit TOTP code)
- `POST /api/v1/auth/2fa/signin`: Complete login with 2FA
- Required fields: email, password, token
- `POST /api/v1/auth/2fa/disable`: Disable 2FA
- Protected route
- Required fields: token (6-digit TOTP code)
## Security Features
### Password Security
- Strong password requirements with complexity validation
- Bcrypt hashing with configurable salt rounds
- Common password detection and prevention
### Protection Against Attacks
- Rate limiting on all authentication endpoints
- CORS protection with configurable allowed origins
- Security headers (CSP, HSTS, XSS Protection, etc.)
- Input sanitization to prevent XSS attacks
### Session Management
- Short-lived JWT access tokens (20 minutes)
- Longer-lived refresh tokens (7 days)
- Login anomaly detection with IP, device tracking