@bhandari88/express-auth 1.0.0

package/INSTALLATION.md

@@ -0,0 +1,71 @@
+# Installation Guide
+
+## Quick Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+This will install all required dependencies including:
+- Node.js crypto (built-in, no installation needed - used for password hashing with scrypt)
+- jsonwebtoken (JWT tokens)
+- passport (authentication strategies)
+- passport-google-oauth20 (Google login)
+- passport-facebook (Facebook login)
+- validator (input validation)
+
+### 2. Install Peer Dependencies
+
+```bash
+npm install express
+```
+
+### 3. Build the Package
+
+```bash
+npm run build
+```
+
+This will compile TypeScript to JavaScript in the `dist/` directory.
+
+### 4. Set Environment Variables
+
+Create a `.env` file (or use environment variables):
+
+```bash
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+REFRESH_TOKEN_SECRET=your-super-secret-refresh-token-key
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+FACEBOOK_CLIENT_ID=your-facebook-app-id
+FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
+```
+
+### 5. Implement User Repository
+
+You need to implement the `UserRepository` interface for your database. See `example/usage.ts` for a MongoDB/Mongoose example.
+
+### 6. Use the Package
+
+```typescript
+import { Auth, AuthConfig } from './src';
+// or if installed as package: from '@auth-boiler/express-auth'
+
+const auth = new Auth(config, userRepository);
+auth.setupRoutes(app, '/api/auth');
+```
+
+## Development
+
+```bash
+npm run dev  # Watch mode for TypeScript compilation
+```
+
+## Publishing
+
+```bash
+npm run build  # Build first
+npm publish    # Publish to npm registry
+```

package/README.md

@@ -0,0 +1,425 @@
+# @auth-boiler/express-auth
+
+A plug-and-play authentication handler for Express.js with TypeScript supporting multiple authentication methods including email, username, phone, and social login (Google, Facebook).
+
+## Features
+
+- ✅ **Multiple Authentication Methods**
+  - Email/Password
+  - Username/Password
+  - Phone/Password
+  - Social Login (Google, Facebook)
+
+- ✅ **Security Best Practices**
+  - JWT-based authentication with access and refresh tokens
+  - Node.js crypto (scrypt) password hashing (memory-hard, highly secure)
+  - Input validation and sanitization
+  - Token expiration and refresh mechanism
+  - Secure password requirements
+  - Timing-safe password comparison to prevent timing attacks
+
+- ✅ **Easy Integration**
+  - Plug-and-play API
+  - Express middleware for protected routes
+  - Role-based access control
+  - Automatic route setup
+  - TypeScript support
+
+- ✅ **Flexible**
+  - Works with any database/user repository
+  - Configurable token expiration
+  - Optional refresh tokens
+  - Customizable user fields
+
+## Installation
+
+```bash
+npm install @auth-boiler/express-auth
+```
+
+## Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+npm install express
+```
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install @auth-boiler/express-auth express
+npm install --save-dev typescript @types/express @types/node
+```
+
+### 2. Create User Repository
+
+Implement the `UserRepository` interface for your database:
+
+```typescript
+import { UserRepository, UserDocument } from '@auth-boiler/express-auth';
+
+class MyUserRepository implements UserRepository {
+  async findById(id: string): Promise<UserDocument | null> {
+    // Your database query logic
+  }
+
+  async findByEmail(email: string): Promise<UserDocument | null> {
+    // Your database query logic
+  }
+
+  async findByUsername(username: string): Promise<UserDocument | null> {
+    // Your database query logic
+  }
+
+  async findByPhone(phone: string): Promise<UserDocument | null> {
+    // Your database query logic
+  }
+
+  async findByProvider(provider: string, providerId: string): Promise<UserDocument | null> {
+    // Your database query logic
+  }
+
+  async create(userData: Partial<UserDocument>): Promise<UserDocument> {
+    // Your database create logic
+  }
+
+  async update(id: string, updateData: Partial<UserDocument>): Promise<UserDocument | null> {
+    // Your database update logic
+  }
+
+  async delete(id: string): Promise<boolean> {
+    // Your database delete logic
+  }
+}
+```
+
+### 3. Configure and Initialize Auth
+
+```typescript
+import express from 'express';
+import { Auth, AuthConfig } from '@auth-boiler/express-auth';
+import MyUserRepository from './repositories/MyUserRepository';
+
+const app = express();
+app.use(express.json());
+
+const authConfig: AuthConfig = {
+  jwtSecret: process.env.JWT_SECRET || 'your-secret-key',
+  jwtExpiresIn: '15m',
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET || 'your-refresh-secret',
+  refreshTokenExpiresIn: '7d',
+  bcryptRounds: 16384, // Scrypt cost parameter (2^14, configurable)
+  enableRefreshTokens: true,
+  socialAuth: {
+    google: {
+      clientID: process.env.GOOGLE_CLIENT_ID || '',
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET || '',
+      callbackURL: 'http://localhost:3000/api/auth/google/callback',
+    },
+    facebook: {
+      clientID: process.env.FACEBOOK_CLIENT_ID || '',
+      clientSecret: process.env.FACEBOOK_CLIENT_SECRET || '',
+      callbackURL: 'http://localhost:3000/api/auth/facebook/callback',
+    },
+  },
+};
+
+const userRepository = new MyUserRepository();
+const auth = new Auth(authConfig, userRepository);
+
+// Setup all auth routes automatically
+auth.setupRoutes(app, '/api/auth');
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### 4. Use Protected Routes
+
+```typescript
+// Protect a route
+app.get('/api/profile', auth.getAuthMiddleware(), (req, res) => {
+  const user = (req as any).user;
+  res.json({ user });
+});
+
+// Optional authentication (doesn't fail if no token)
+app.get('/api/public', auth.getOptionalAuthMiddleware(), (req, res) => {
+  const user = (req as any).user; // May be undefined
+  res.json({ user });
+});
+
+// Role-based access control
+app.get('/api/admin', 
+  auth.getAuthMiddleware(), 
+  auth.requireRole(['admin', 'superadmin']), 
+  (req, res) => {
+    res.json({ message: 'Admin access granted' });
+  }
+);
+```
+
+## API Endpoints
+
+### Register User
+
+**POST** `/api/auth/register`
+
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword123"
+}
+```
+
+Or with username:
+```json
+{
+  "username": "johndoe",
+  "password": "securepassword123"
+}
+```
+
+Or with phone:
+```json
+{
+  "phone": "+1234567890",
+  "password": "securepassword123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "user": {
+    "id": "user-id",
+    "email": "user@example.com",
+    "verified": false
+  },
+  "tokens": {
+    "accessToken": "jwt-token",
+    "refreshToken": "refresh-token",
+    "expiresIn": 900
+  },
+  "message": "User registered successfully"
+}
+```
+
+### Login
+
+**POST** `/api/auth/login`
+
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword123"
+}
+```
+
+Or with username:
+```json
+{
+  "username": "johndoe",
+  "password": "securepassword123"
+}
+```
+
+Or with phone:
+```json
+{
+  "phone": "+1234567890",
+  "password": "securepassword123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "user": {
+    "id": "user-id",
+    "email": "user@example.com"
+  },
+  "tokens": {
+    "accessToken": "jwt-token",
+    "refreshToken": "refresh-token",
+    "expiresIn": 900
+  },
+  "message": "Login successful"
+}
+```
+
+### Refresh Token
+
+**POST** `/api/auth/refresh`
+
+```json
+{
+  "refreshToken": "your-refresh-token"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "tokens": {
+    "accessToken": "new-jwt-token",
+    "refreshToken": "new-refresh-token",
+    "expiresIn": 900
+  },
+  "message": "Token refreshed successfully"
+}
+```
+
+### Change Password
+
+**POST** `/api/auth/change-password`
+
+**Headers:**
+```
+Authorization: Bearer <access-token>
+```
+
+**Body:**
+```json
+{
+  "oldPassword": "oldpassword123",
+  "newPassword": "newpassword456"
+}
+```
+
+### Social Login
+
+**Google:**
+- **GET** `/api/auth/google` - Initiate Google login
+- **GET** `/api/auth/google/callback` - Google callback (configured automatically)
+
+**Facebook:**
+- **GET** `/api/auth/facebook` - Initiate Facebook login
+- **GET** `/api/auth/facebook/callback` - Facebook callback (configured automatically)
+
+## Programmatic Usage
+
+You can also use the auth methods programmatically:
+
+```typescript
+// Register
+const result = await auth.register({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Login
+const loginResult = await auth.login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Change password
+const changeResult = await auth.changePassword(
+  userId,
+  'oldPassword',
+  'newPassword'
+);
+
+// Refresh token
+const refreshResult = await auth.refreshToken(refreshToken);
+```
+
+## Configuration Options
+
+```typescript
+interface AuthConfig {
+  jwtSecret: string;                    // Required: Secret for JWT signing
+  jwtExpiresIn?: string;                // Optional: Access token expiration (default: '15m')
+  refreshTokenSecret?: string;          // Optional: Secret for refresh tokens (defaults to jwtSecret)
+  refreshTokenExpiresIn?: string;       // Optional: Refresh token expiration (default: '7d')
+  bcryptRounds?: number;                // Optional: Scrypt cost parameter N (default: 16384 = 2^14)
+  enableRefreshTokens?: boolean;        // Optional: Enable refresh tokens (default: true)
+  socialAuth?: {                        // Optional: Social auth configuration
+    google?: {
+      clientID: string;
+      clientSecret: string;
+      callbackURL: string;
+    };
+    facebook?: {
+      clientID: string;
+      clientSecret: string;
+      callbackURL: string;
+    };
+  };
+}
+```
+
+## Security Best Practices
+
+1. **Environment Variables**: Always use environment variables for secrets:
+   ```bash
+   JWT_SECRET=your-super-secret-key
+   REFRESH_TOKEN_SECRET=your-refresh-secret-key
+   GOOGLE_CLIENT_ID=your-google-client-id
+   GOOGLE_CLIENT_SECRET=your-google-client-secret
+   ```
+
+2. **Password Requirements**: 
+   - Minimum 6 characters
+   - Maximum 128 characters
+   - Hashed with Node.js crypto.scrypt (memory-hard, highly secure)
+   - Uses timing-safe comparison to prevent timing attacks
+   - Default cost parameter: 16384 (2^14)
+
+3. **Token Expiration**:
+   - Access tokens: Short-lived (15 minutes default)
+   - Refresh tokens: Long-lived (7 days default)
+
+4. **HTTPS**: Always use HTTPS in production
+
+5. **Input Validation**: All inputs are validated and sanitized automatically
+
+## Types
+
+```typescript
+interface User {
+  id: string;
+  email?: string;
+  username?: string;
+  phone?: string;
+  password?: string;
+  provider?: 'local' | 'google' | 'facebook';
+  providerId?: string;
+  verified?: boolean;
+  [key: string]: any; // Additional custom fields
+}
+
+interface AuthResult {
+  success: boolean;
+  user?: User;
+  tokens?: AuthTokens;
+  message?: string;
+  error?: string;
+}
+
+interface AuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn: number;
+}
+```
+
+## Example with MongoDB (Mongoose)
+
+See `example/usage.ts` for a complete example using MongoDB with Mongoose.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/handlers/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalAuthHandler } from './local-auth';
+export { SocialAuthHandler } from './social-auth';

package/dist/handlers/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialAuthHandler = exports.LocalAuthHandler = void 0;
+var local_auth_1 = require("./local-auth");
+Object.defineProperty(exports, "LocalAuthHandler", { enumerable: true, get: function () { return local_auth_1.LocalAuthHandler; } });
+var social_auth_1 = require("./social-auth");
+Object.defineProperty(exports, "SocialAuthHandler", { enumerable: true, get: function () { return social_auth_1.SocialAuthHandler; } });

package/dist/handlers/local-auth.d.ts

@@ -0,0 +1,12 @@
+import { UserRepository, LoginCredentials, RegisterData, AuthResult } from '../types';
+import { JwtService } from '../utils/jwt';
+import { PasswordService } from '../utils/password';
+export declare class LocalAuthHandler {
+    private userRepository;
+    private jwtService;
+    private passwordService;
+    constructor(userRepository: UserRepository, jwtService: JwtService, passwordService: PasswordService);
+    register(data: RegisterData): Promise<AuthResult>;
+    login(credentials: LoginCredentials): Promise<AuthResult>;
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<AuthResult>;
+}

package/dist/handlers/local-auth.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAuthHandler = void 0;
+const validator_1 = require("../utils/validator");
+class LocalAuthHandler {
+    constructor(userRepository, jwtService, passwordService) {
+        this.userRepository = userRepository;
+        this.jwtService = jwtService;
+        this.passwordService = passwordService;
+    }
+    async register(data) {
+        try {
+            // Validate input
+            const validation = validator_1.ValidatorService.validateRegisterData(data);
+            if (!validation.valid) {
+                return { success: false, error: validation.message };
+            }
+            // Check if user already exists
+            let existingUser = null;
+            if (data.email) {
+                const sanitizedEmail = validator_1.ValidatorService.sanitizeEmail(data.email);
+                existingUser = await this.userRepository.findByEmail(sanitizedEmail);
+                if (existingUser) {
+                    return { success: false, error: 'User with this email already exists' };
+                }
+            }
+            if (data.username) {
+                existingUser = await this.userRepository.findByUsername(data.username);
+                if (existingUser) {
+                    return { success: false, error: 'Username already taken' };
+                }
+            }
+            if (data.phone) {
+                const sanitizedPhone = validator_1.ValidatorService.sanitizePhone(data.phone);
+                existingUser = await this.userRepository.findByPhone(sanitizedPhone);
+                if (existingUser) {
+                    return { success: false, error: 'User with this phone number already exists' };
+                }
+            }
+            // Validate password
+            const passwordValidation = this.passwordService.validatePassword(data.password);
+            if (!passwordValidation.valid) {
+                return { success: false, error: passwordValidation.message };
+            }
+            // Hash password
+            const hashedPassword = await this.passwordService.hash(data.password);
+            // Create user
+            const userData = {
+                password: hashedPassword,
+                provider: 'local',
+                verified: false,
+            };
+            if (data.email) {
+                userData.email = validator_1.ValidatorService.sanitizeEmail(data.email);
+            }
+            if (data.username) {
+                userData.username = data.username.toLowerCase().trim();
+            }
+            if (data.phone) {
+                userData.phone = validator_1.ValidatorService.sanitizePhone(data.phone);
+            }
+            // Add any additional fields
+            const { email, username, phone, password, ...additionalFields } = data;
+            Object.assign(userData, additionalFields);
+            const user = await this.userRepository.create(userData);
+            // Generate tokens
+            const tokens = this.jwtService.generateTokens({
+                userId: user.id || user._id || '',
+                email: user.email,
+                username: user.username,
+                phone: user.phone,
+            });
+            // Remove password from response
+            const { password: _, ...userWithoutPassword } = user;
+            const userResponse = userWithoutPassword;
+            return {
+                success: true,
+                user: userResponse,
+                tokens,
+                message: 'User registered successfully',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Registration failed',
+            };
+        }
+    }
+    async login(credentials) {
+        try {
+            // Validate input
+            const validation = validator_1.ValidatorService.validateLoginCredentials(credentials);
+            if (!validation.valid) {
+                return { success: false, error: validation.message };
+            }
+            // Find user
+            let user = null;
+            if (credentials.email) {
+                const sanitizedEmail = validator_1.ValidatorService.sanitizeEmail(credentials.email);
+                user = await this.userRepository.findByEmail(sanitizedEmail);
+            }
+            else if (credentials.username) {
+                user = await this.userRepository.findByUsername(credentials.username);
+            }
+            else if (credentials.phone) {
+                const sanitizedPhone = validator_1.ValidatorService.sanitizePhone(credentials.phone);
+                user = await this.userRepository.findByPhone(sanitizedPhone);
+            }
+            if (!user) {
+                return { success: false, error: 'Invalid credentials' };
+            }
+            // Check if user has password (not social login only)
+            if (!user.password) {
+                return { success: false, error: 'Please use social login for this account' };
+            }
+            // Verify password
+            const isPasswordValid = await this.passwordService.compare(credentials.password, user.password);
+            if (!isPasswordValid) {
+                return { success: false, error: 'Invalid credentials' };
+            }
+            // Generate tokens
+            const tokens = this.jwtService.generateTokens({
+                userId: user.id || user._id || '',
+                email: user.email,
+                username: user.username,
+                phone: user.phone,
+            });
+            // Remove password from response
+            const { password: _, ...userWithoutPassword } = user;
+            const userResponse = userWithoutPassword;
+            return {
+                success: true,
+                user: userResponse,
+                tokens,
+                message: 'Login successful',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Login failed',
+            };
+        }
+    }
+    async changePassword(userId, oldPassword, newPassword) {
+        try {
+            const user = await this.userRepository.findById(userId);
+            if (!user) {
+                return { success: false, error: 'User not found' };
+            }
+            if (!user.password) {
+                return { success: false, error: 'Password change not available for social login accounts' };
+            }
+            // Verify old password
+            const isOldPasswordValid = await this.passwordService.compare(oldPassword, user.password);
+            if (!isOldPasswordValid) {
+                return { success: false, error: 'Current password is incorrect' };
+            }
+            // Validate new password
+            const passwordValidation = this.passwordService.validatePassword(newPassword);
+            if (!passwordValidation.valid) {
+                return { success: false, error: passwordValidation.message };
+            }
+            // Hash new password
+            const hashedPassword = await this.passwordService.hash(newPassword);
+            // Update user
+            await this.userRepository.update(userId, { password: hashedPassword });
+            return {
+                success: true,
+                message: 'Password changed successfully',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Password change failed',
+            };
+        }
+    }
+}
+exports.LocalAuthHandler = LocalAuthHandler;