@dax-crafta/auth 2.1.7 → 2.1.8

package/.mocharc.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  spec: 'test/*.test.js',
+  timeout: 30000,
+  reporter: 'spec',
+  require: [],
+};

package/README.md

@@ -1,274 +1,167 @@
-# @dax-crafta/auth
-
-Production-ready auth for Crafta apps with plug-and-play defaults and clean JSON customization.
-
-[![npm version](https://img.shields.io/npm/v/@dax-crafta/auth.svg)](https://www.npmjs.com/package/@dax-crafta/auth)
-[![License](https://img.shields.io/npm/l/@dax-crafta/auth.svg)](https://github.com/daxp472/crafta/blob/main/LICENSE)
-[![Downloads](https://img.shields.io/npm/dm/@dax-crafta/auth.svg)](https://www.npmjs.com/package/@dax-crafta/auth)
-
-## Why this package
-
-- You should not rebuild auth from scratch for every project.
-- This package gives you login, refresh tokens, password reset, RBAC, 2FA, audit logs, and feature toggles out of the box.
-- Keep defaults for speed, customize only where needed.
-
-## What you get
-
-- JWT auth with refresh token rotation
-- Register, login, verify, forgot/reset password routes
-- Optional 2FA (TOTP + backup codes)
-- RBAC with role and permission service
-- Route-level rate limiting
-- Password policy and password history checks
-- Optional Google OAuth
-- Audit logs (Mongo + file)
-
-## 1. Install
-
-```bash
-npm install crafta @dax-crafta/auth
-```
-
-## 2. Minimal setup (copy-paste)
-
-Create `server.js`:
-
-```js
-const { crafta } = require('crafta');
-const { auth } = require('@dax-crafta/auth');
-
-const app = crafta();
-
-auth({
-  env: {
-    JWT_SECRET: process.env.JWT_SECRET || 'dev-secret-123'
-  },
-  mongoUrl: process.env.MONGO_URL || 'mongodb://127.0.0.1:27017/crafta-auth-demo',
-
-  // Local dev ke liye simple mode
-  features: {
-    emailVerification: false,
-    loginAlerts: false,
-    csrf: false
-  }
-})(app);
-
-app.get('/health', (req, res) => {
-  res.json({ ok: true, message: 'Auth is running' });
-});
-
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
-Run it:
-
-```bash
-node server.js
-```
-
-## 3. First Postman test flow
-
-### Health
-- `GET /health`
-
-### Register
-- `POST /register`
-
-```json
-{
-  "name": "Test User",
-  "email": "testuser1@example.com",
-  "password": "Strong@1234"
-}
-```
-
-### Login
-- `POST /login`
-
-```json
-{
-  "email": "testuser1@example.com",
-  "password": "Strong@1234"
-}
-```
-
-Use returned `accessToken` on protected routes:
-- `Authorization: Bearer <token>`
-
-### Profile (protected)
-- `PUT /profile`
-
-```json
-{
-  "name": "Updated Name"
-}
-```
-
-### Refresh token
-- `POST /refresh-token`
-
-```json
-{
-  "refreshToken": "<token-from-login>"
-}
-```
-
-## 4. Customize with JSON (main power)
-
-Everything is controlled from one config object.
-
-```js
-auth({
-  strategy: 'jwt',
-  fields: ['name', 'email', 'password', 'age'],
-
-  routes: {
-    register: '/api/auth/register',
-    login: '/api/auth/login',
-    verify: '/api/auth/verify',
-    forgotPassword: '/api/auth/forgot-password',
-    resetPassword: '/api/auth/reset-password',
-    refreshToken: '/api/auth/refresh-token',
-    profile: '/api/auth/profile',
-    twoFactor: '/api/auth/2fa'
-  },
-
-  passwordPolicy: {
-    minLength: 10,
-    requireUppercase: true,
-    requireLowercase: true,
-    requireNumbers: true,
-    requireSpecialChars: true,
-    expiryDays: 90,
-    minStrength: 3
-  },
-
-  limits: {
-    loginMax: 10,
-    twoFAMax: 20,
-    forgotPasswordMax: 5,
-    refreshMax: 30
-  }
-})(app);
-```
-
-## 5. Feature toggles (fast on/off)
-
-Set any feature to `false` and it turns off.
-
-```js
-auth({
-  features: {
-    emailVerification: false,
-    loginAlerts: false,
-    securityAttempts: true,
-    rateLimit: true,
-    auditLogs: true,
-    twoFactor: true,
-    csrf: false
-  }
-})(app);
-```
-
-Notes:
-- If SMTP is missing, emailVerification/loginAlerts are auto-disabled with warning.
-- If `securityAttempts: false`, lockout attempt handling is disabled.
-
-## 6. Email setup (optional)
-
-Enable this only when SMTP is ready:
-
-```js
-auth({
-  features: {
-    emailVerification: true,
-    loginAlerts: true
-  },
-  smtp: {
-    host: process.env.SMTP_HOST,
-    port: Number(process.env.SMTP_PORT || 587),
-    auth: {
-      user: process.env.SMTP_USER,
-      pass: process.env.SMTP_PASS
-    },
-    from: process.env.SMTP_FROM
-  },
-  baseUrl: process.env.BASE_URL || 'http://localhost:3000'
-})(app);
-```
-
-## 7. Google OAuth setup (optional)
-
-```js
-auth({
-  social: {
-    google: {
-      clientID: process.env.GOOGLE_CLIENT_ID,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-      callbackURL: 'http://localhost:3000/auth/google/callback'
-    }
-  }
-})(app);
-```
-
-Routes:
-- `GET /auth/google`
-- `GET /auth/google/callback`
-
-## 8. RBAC quick use
-
-```js
-const role = await app.roleService.createRole({
-  name: 'admin',
-  permissions: [
-    { resource: 'users', actions: ['create', 'read', 'update', 'delete'] }
-  ]
-});
-
-const allowed = await app.roleService.checkPermission('admin', 'users', 'delete');
-```
-
-## 9. Environment variables
-
-```bash
-JWT_SECRET=my-super-secret
-MONGO_URL=mongodb://127.0.0.1:27017/crafta-auth-demo
-SMTP_HOST=smtp.example.com
-SMTP_PORT=587
-SMTP_USER=you@example.com
-SMTP_PASS=your-password
-SMTP_FROM=noreply@example.com
-BASE_URL=http://localhost:3000
-GOOGLE_CLIENT_ID=...
-GOOGLE_CLIENT_SECRET=...
-```
-
-## 10. Troubleshooting
-
-- 401 on protected route
-  - Token missing or expired.
-  - Send `Authorization: Bearer <accessToken>`.
-
-- Register fails on password policy
-  - Use uppercase + lowercase + number + special char.
-
-- Email not sending
-  - Check SMTP credentials and port.
-  - If SMTP absent, email features auto-disable by design.
-
-- Refresh token invalid
-  - Refresh token is rotated; use latest token returned by API.
-
-## 11. Release confidence
-
-- Built-in smoke suite is available:
-
-```bash
-npm test
-```
-
-## License
-
-MIT © Dax Crafta
+# @dax-crafta/auth
+
+Production-ready authentication library for Crafta apps, featuring plug-and-play defaults, robust security, and clean JSON-based customization.
+
+[![npm version](https://img.shields.io/npm/v/@dax-crafta/auth.svg)](https://www.npmjs.com/package/@dax-crafta/auth)
+[![License](https://img.shields.io/npm/l/@dax-crafta/auth.svg)](https://github.com/NPM-crafta/crafta-auth/blob/main/LICENSE)
+
+## Features
+1. **JWT Authentication**: Secure sessions with automatic refresh token rotation.
+2. **Standard Routes**: Built-in register, login, verify email, forgot/reset password, and refresh routes.
+3. **Multi-Factor Authentication (MFA)**: Optional TOTP-based 2FA with backup codes support.
+4. **RBAC**: Role-Based Access Control service to manage permissions and roles.
+5. **Rate Limiting**: Route-level protection for sensitive endpoints (login, register, 2FA).
+6. **Password Policy**: Strict policy enforcement with password history checks and strength validation.
+7. **Google OAuth**: Optional social login integration.
+8. **Audit Logs**: Comprehensive logging to MongoDB and local files.
+9. **Session Management**: Full session control with per-user session limits and global logout.
+10. **Webhooks**: Real-time event notifications for auth lifecycle events (registered, login, logout, password change).
+11. **Passwordless Login**: Magic link authentication.
+12. **Standardized Error Handling**: Unified error format with 19 distinct `AUTH_*` codes.
+13. **CORS Middleware**: Explicit origin whitelisting for secure cross-origin requests.
+14. **Customizable Fields**: Flexible user model customization.
+
+## Install
+```bash
+npm install @dax-crafta/auth
+```
+
+## Minimal Setup
+```javascript
+const { crafta } = require('crafta');
+const { auth } = require('@dax-crafta/auth');
+
+const app = crafta();
+
+auth({
+  env: {
+    JWT_SECRET: process.env.JWT_SECRET || 'dev-secret-123'
+  },
+  mongoUrl: process.env.MONGO_URL || 'mongodb://127.0.0.1:27017/crafta-auth-demo'
+})(app);
+
+app.listen(3000, () => console.log('Server running on http://localhost:3000'));
+```
+
+## Configuration Options
+The library is configured via a single object passed to the `auth()` function:
+
+```javascript
+auth({
+  strategy: 'jwt', // Currently defaults to 'jwt'
+  fields: ['name', 'email', 'password'],
+  routes: { /* Custom route paths */ },
+  passwordPolicy: {
+    minLength: 8,
+    requireUppercase: true,
+    requireNumbers: true,
+    requireSpecialChars: true,
+    expiryDays: 90
+  },
+  limits: {
+    loginMax: 10,
+    registerMax: 20
+  }
+})(app);
+```
+
+## Feature Toggles
+Enable or disable features via the `features` object:
+
+```javascript
+auth({
+  features: {
+    emailVerification: true,
+    twoFactor: true,
+    passwordless: false,
+    auditLogs: true,
+    webhooks: false,
+    rateLimit: true,
+    csrf: false
+  }
+})(app);
+```
+
+## Email Setup
+Configure SMTP to enable email-based features (Verification, Forgot Password, Magic Links, Login Alerts):
+
+```javascript
+auth({
+  smtp: {
+    host: process.env.SMTP_HOST,
+    port: 587,
+    auth: {
+      user: process.env.SMTP_USER,
+      pass: process.env.SMTP_PASS
+    },
+    from: process.env.SMTP_FROM
+  },
+  baseUrl: 'http://localhost:3000'
+})(app);
+```
+
+## Google OAuth Setup
+```javascript
+auth({
+  social: {
+    google: {
+      clientID: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      callbackURL: 'http://localhost:3000/auth/google/callback'
+    }
+  }
+})(app);
+```
+
+## RBAC Quick Use
+Access the role service directly from your app instance:
+
+```javascript
+// Check permission
+const allowed = await app.roleService.checkPermission('admin', 'users', 'delete');
+
+// Create role
+await app.roleService.createRole({
+  name: 'editor',
+  permissions: [{ resource: 'posts', actions: ['create', 'update'] }]
+});
+```
+
+## Environment Variables
+- `JWT_SECRET`: Secret key for signing tokens.
+- `MONGO_URL`: MongoDB connection string.
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`: SMTP configuration.
+- `BASE_URL`: Base URL for email links.
+- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`: Google OAuth credentials.
+
+## Troubleshooting
+- **401 Unauthorized**: Check if `Authorization: Bearer <accessToken>` header is present and valid.
+- **Password policy errors**: Ensure passwords meet length, uppercase, number, and special character requirements.
+- **Email issues**: Verify SMTP configuration; features relying on email will automatically disable if SMTP is misconfigured.
+
+## Error Codes
+| Code | Description | HTTP Status |
+| :--- | :--- | :--- |
+| `AUTH_BAD_REQUEST` | Generic bad request error | 400 |
+| `AUTH_VALIDATION` | Invalid request data | 400 |
+| `AUTH_PASSWORD_POLICY` | Password policy violation | 400 |
+| `AUTH_PASSWORD_REUSE` | Cannot reuse previous passwords | 400 |
+| `AUTH_SOCIAL_FAILED` | Social login failure | 400 |
+| `AUTH_INVALID_ID` | Invalid resource identifier | 400 |
+| `AUTH_UNAUTHORIZED` | Authentication required | 401 |
+| `AUTH_INVALID_CREDENTIALS` | Invalid email or password | 401 |
+| `AUTH_INVALID_TOKEN` | Token invalid or missing | 401 |
+| `AUTH_EXPIRED_TOKEN` | Token expired | 401 |
+| `AUTH_2FA_FAILED` | Invalid 2FA code | 401 |
+| `AUTH_FORBIDDEN` | Insufficient permissions | 403 |
+| `AUTH_ACCOUNT_LOCKED` | Account locked due to failed attempts | 403 |
+| `AUTH_EMAIL_NOT_VERIFIED` | Email verification required | 403 |
+| `AUTH_2FA_REQUIRED` | 2FA code input required | 403 |
+| `AUTH_NOT_FOUND` | Resource not found | 404 |
+| `AUTH_CONFLICT` | Resource already exists | 409 |
+| `AUTH_RATE_LIMITED` | Too many requests | 429 |
+| `AUTH_SMTP_DISABLED` | Email delivery service disabled | 503 |
+| `AUTH_INTERNAL` | Unexpected internal error | 500 |
+
+## License
+MIT © Dax Crafta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dax-crafta/auth",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "A powerful, flexible, and secure authentication plugin for the Crafta framework. Supports JWT, social login, 2FA, RBAC, audit logging, and enterprise-grade security features.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -61,5 +61,9 @@
   },
   "homepage": "https://github.com/daxp472/crafta#readme",
   "license": "MIT",
-  "author": "Dax Patel"
+  "author": "Dax Patel",
+  "devDependencies": {
+    "@types/mocha": "^10.0.10",
+    "mocha": "^10.8.2"
+  }
 }

package/src/index.d.ts

@@ -56,6 +56,8 @@ export interface RateLimitConfig {
   forgotPasswordMax?: number;
   refreshMax?: number;
   registerMax?: number;
+  /** Per-route max overrides keyed by route name (e.g. "login", "register", "2fa") */
+  [routeName: string]: number | undefined;
 }
 
 export interface WebhookConfig {
@@ -67,6 +69,8 @@ export interface WebhookConfig {
 export interface SessionConfig {
   maxSessions?: number;
   sessionExpiryMs?: number;
+  /** Milliseconds before expiry at which the X-Session-Expires-In warning header is emitted. Default: 300000 (5 min). */
+  warningThresholdMs?: number;
 }
 
 export interface LockoutConfig {
@@ -183,11 +187,14 @@ export interface MFAService {
 }
 
 export interface PasswordPolicyService {
-  validate(password: string, userInfo?: any): { isValid: boolean; errors: string[]; strength: number };
+  validate(password: string, userInfo?: any): { isValid: boolean; errors: string[]; strength: number; strengthScore: number };
   allowsReuse(password: string, passwordHistory: any[], bcrypt: any): Promise<boolean>;
   isExpired(lastChange: Date): boolean;
 }
 
+/** Returns a heuristic password strength score from 0 (very weak) to 4 (very strong). */
+export function getPasswordStrength(password: string): number;
+
 export function auth(config?: AuthConfig): (app: any) => void;
 export function normalizeError(err: unknown): ApiError;
 

package/src/index.js

@@ -3,6 +3,7 @@ const cookieParser = require('cookie-parser');
 const csrf = require('csurf');
 const helmet = require("helmet");
 const mongoose = require("mongoose");
+const jwt = require('jsonwebtoken');
 
 const GoogleStrategy = require('passport-google-oauth20').Strategy;
 const AuthService = require('./services/auth.service');
@@ -18,6 +19,7 @@ const corsMiddleware = require('./middlewares/cors.middleware');
 const validators = require('./middlewares/validation.middleware');
 const { createLogger } = require('./utils/logger');
 const ApiError = require('./utils/api-error');
+const { getPasswordStrength } = require('./utils/password-strength');
 const { runAdaptiveTests, inferFeatureFlags, testCatalog } = require('./testing/adaptive-runner');
 
 
@@ -78,7 +80,8 @@ const defaultConfig = {
   webhooks: null,
   session: {
     maxSessions: 5,
-    sessionExpiryMs: 30 * 24 * 60 * 60 * 1000
+    sessionExpiryMs: 30 * 24 * 60 * 60 * 1000,
+    warningThresholdMs: 5 * 60 * 1000
   }
 };
 
@@ -154,13 +157,24 @@ function auth(config = {}) {
   // ------------------------------------------
   // MongoDB Connection — support external connections
   // ------------------------------------------
+  const connectDB = () => {
+    mongoose.connect(finalConfig.mongoUrl)
+      .then(() => logger.logSuccess("MongoDB connected"))
+      .catch(err => {
+        logger.logError(`MongoDB connection error: ${err.message}`);
+        setTimeout(connectDB, 5000);
+      });
+  };
+
   if (finalConfig.mongooseConnection) {
     // Allow host app to pass an existing mongoose connection
     logger.logInfo("Using provided mongoose connection");
   } else if (mongoose.connection.readyState === 0) {
-    mongoose.connect(finalConfig.mongoUrl)
-      .then(() => logger.logSuccess("MongoDB connected"))
-      .catch(err => logger.logError(`MongoDB connection error: ${err.message}`));
+    connectDB();
+    mongoose.connection.on('disconnected', () => {
+      logger.logWarn("MongoDB disconnected, attempting to reconnect...");
+      connectDB();
+    });
   } else {
     logger.logInfo("Using existing mongoose connection");
   }
@@ -219,6 +233,29 @@ function auth(config = {}) {
       }
     };
 
+    // ------------------------------------------
+    // SESSION TIMEOUT WARNING MIDDLEWARE
+    // ------------------------------------------
+    const warningThresholdMs = finalConfig.session?.warningThresholdMs || 5 * 60 * 1000;
+    app.use((req, res, next) => {
+      const authHeader = req.headers.authorization;
+      if (authHeader && authHeader.startsWith('Bearer ')) {
+        const token = authHeader.split(' ')[1];
+        try {
+          const decoded = jwt.decode(token);
+          if (decoded && decoded.exp) {
+            const timeLeft = decoded.exp * 1000 - Date.now();
+            if (timeLeft > 0 && timeLeft < warningThresholdMs) {
+              res.setHeader('X-Session-Expires-In', Math.floor(timeLeft / 1000));
+            }
+          }
+        } catch (err) {
+          // Ignore decoding errors in middleware
+        }
+      }
+      next();
+    });
+
     app.use(cookieParser());
 
     // CORS — applied before routes
@@ -253,14 +290,45 @@ function auth(config = {}) {
     // ------------------------------------------
     // HEALTH CHECK
     // ------------------------------------------
-    app.get('/auth/health', (req, res) => {
+    app.get('/auth/health', async (req, res) => {
       const dbState = mongoose.connection.readyState;
       const dbStatus = dbState === 1 ? 'connected' : dbState === 2 ? 'connecting' : 'disconnected';
+
+      // Get active session count
+      let activeSessions = 0;
+      if (mongoose.connection.readyState === 1) {
+        try {
+          activeSessions = await mongoose.connection.db.collection('users').aggregate([
+            { $match: { sessions: { $exists: true, $not: { $size: 0 } } } },
+            { $unwind: '$sessions' },
+            { $match: { 'sessions.createdAt': { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) } } },
+            { $group: { _id: '$_id', count: { $sum: 1 } } },
+            { $group: { _id: null, total: { $sum: '$count' } } }
+          ]).toArray();
+          activeSessions = activeSessions[0]?.total || 0;
+        } catch (err) {
+          logger.logWarn(`Failed to count active sessions: ${err.message}`);
+        }
+      }
+
+      // Get memory usage
+      const memoryUsage = process.memoryUsage();
+
+      // Get uptime
+      const uptime = process.uptime();
+
       res.json({
         success: true,
         status: 'ok',
         db: dbStatus,
         version: require('../package.json').version,
+        uptime: `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`,
+        activeSessions,
+        memoryUsage: {
+          rss: `${Math.round(memoryUsage.rss / 1024 / 1024)}MB`,
+          heapTotal: `${Math.round(memoryUsage.heapTotal / 1024 / 1024)}MB`,
+          heapUsed: `${Math.round(memoryUsage.heapUsed / 1024 / 1024)}MB`
+        },
         features: {
           emailVerification: finalConfig.features.emailVerification,
           twoFactor: finalConfig.features.twoFactor,
@@ -482,7 +550,7 @@ function auth(config = {}) {
       verifyToken,
       async (req, res, next) => {
         try {
-          await authService.logout(req.user.id, req.body.sessionId);
+          await authService.logout(req.user.id, req.body.sessionId, req.body.refreshToken);
           await safeAudit({ userId: req.user.id, action: 'logout', status: 'success' });
           await safeWebhook('user.logout', { userId: req.user.id });
           res.json({ success: true, message: 'Logged out successfully' });
@@ -598,4 +666,4 @@ function auth(config = {}) {
   };
 }
 
-module.exports = { auth, ApiError, runAdaptiveTests, inferFeatureFlags, testCatalog };
+module.exports = { auth, ApiError, getPasswordStrength, runAdaptiveTests, inferFeatureFlags, testCatalog };