@dax-crafta/auth 2.1.6 → 2.1.8

package/src/services/passwordless.service.js

@@ -0,0 +1,66 @@
+// packages/auth/src/services/passwordless.service.js
+/**
+ * PasswordlessService — magic-link login.
+ *
+ * Flow:
+ *   1. POST /auth/magic-link  { email }  → creates a single-use token, emails it
+ *   2. GET  /auth/magic-link/verify?token=...  → validates, logs user in
+ *
+ * Tokens are short-lived (default 15 min) and single-use.
+ */
+const crypto = require('crypto');
+const ApiError = require('../utils/api-error');
+
+class PasswordlessService {
+  constructor(config = {}) {
+    this.config = config;
+    this.emailService = config.emailService;
+    this.tokenTtlMs = (config.passwordless && config.passwordless.tokenTtlMs) || 15 * 60 * 1000;
+  }
+
+  generateToken() {
+    return crypto.randomBytes(32).toString('hex');
+  }
+
+  async requestMagicLink(email, baseUrl) {
+    const User = require('../models/user');
+    const user = await User.findOne({ email });
+    // Don't reveal whether the email exists — just return success either way.
+    if (!user) return { sent: false, reason: 'user_not_found' };
+
+    const token = this.generateToken();
+    user.magicLinkToken = token;
+    user.magicLinkExpires = Date.now() + this.tokenTtlMs;
+    await user.save();
+
+    const linkPath = this.config.routes?.magicLink || '/auth/magic-link/verify';
+    const url = `${baseUrl || ''}${linkPath}?token=${token}`;
+
+    if (this.emailService) {
+      await this.emailService.sendMagicLink(user, url);
+    }
+
+    return { sent: true };
+  }
+
+  async verifyMagicLink(token) {
+    const User = require('../models/user');
+    const user = await User.findOne({
+      magicLinkToken: token,
+      magicLinkExpires: { $gt: Date.now() }
+    }).select('+magicLinkToken +magicLinkExpires');
+
+    if (!user) {
+      throw ApiError.invalidToken('Invalid or expired magic link');
+    }
+
+    // Single-use: consume the token.
+    user.magicLinkToken = undefined;
+    user.magicLinkExpires = undefined;
+    await user.save();
+
+    return user;
+  }
+}
+
+module.exports = PasswordlessService;

package/src/services/role.service.js

@@ -1,7 +1,12 @@
 const Role = require('../models/role');
+const ApiError = require('../utils/api-error');
 
 class RoleService {
   async createRole(roleData) {
+    const existing = await Role.findOne({ name: roleData.name });
+    if (existing) {
+      throw ApiError.conflict(`Role "${roleData.name}" already exists`);
+    }
     const role = new Role(roleData);
     await role.save();
     return role;

package/src/services/session.service.js

@@ -0,0 +1,141 @@
+// packages/auth/src/services/session.service.js
+/**
+ * SessionService — manages user sessions with a global "session version"
+ * stamp so that a password change, admin action, or logout-all can invalidate
+ * every existing JWT issued before the event.
+ *
+ * This is the backbone of true "log out everywhere" behaviour.
+ */
+const ApiError = require('../utils/api-error');
+
+class SessionService {
+  constructor(config = {}) {
+    this.config = config;
+    this.maxSessions = (config.session && config.session.maxSessions) || 5;
+    this.sessionExpiryMs =
+      (config.session && config.session.sessionExpiryMs) || 30 * 24 * 60 * 60 * 1000; // 30d
+    this.ipBinding = (config.session && config.session.ipBinding) || false;
+  }
+
+  /**
+   * Bump the user's session version. Every existing JWT issued before this
+   * moment becomes invalid.
+   */
+  async bumpSessionVersion(user) {
+    user.sessionVersion = (user.sessionVersion || 0) + 1;
+    await user.save();
+    return user.sessionVersion;
+  }
+
+  /**
+   * Enforce per-user session cap. If the user has more active sessions than
+   * `maxSessions`, drop the oldest ones.
+   */
+  async enforceSessionCap(user) {
+    const sessions = user.sessions || [];
+    if (sessions.length <= this.maxSessions) return;
+
+    // sort oldest-first by createdAt
+    sessions.sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+    const toRemove = sessions.length - this.maxSessions;
+    sessions.splice(0, toRemove);
+    user.sessions = sessions;
+    await user.save();
+  }
+
+  /**
+   * Validate that a decoded JWT's sessionVersion matches the user's current
+   * version. If not, the session has been revoked globally.
+   */
+  validateSession(decoded, user, currentIp = null) {
+    const tokenVersion = decoded.sessionVersion || 0;
+    const currentVersion = user.sessionVersion || 0;
+    if (tokenVersion !== currentVersion) {
+      throw ApiError.unauthorized(
+        'Session has been invalidated. Please log in again.'
+      );
+    }
+
+    if (this.ipBinding && currentIp && decoded.ip && decoded.ip !== currentIp) {
+      throw ApiError.unauthorized(
+        'Session IP address mismatch. Please log in again.'
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Create a new session record for a user (used during login / social login).
+   *
+   * Tracks device info (userAgent, IP) and timestamps. If a session for the
+   * same device already exists, updates its activity timestamp instead of
+   * creating a duplicate — preventing session bloat from repeated logins.
+   */
+  async createSession(user, info = {}) {
+    const crypto = require('crypto');
+    const userAgent = info.userAgent || 'unknown';
+    const ip = info.ip || 'unknown';
+
+    user.sessions = user.sessions || [];
+
+    // Reuse an existing session from the same device: refresh activity stamp.
+    const existing = user.sessions.find(
+      (s) => s.userAgent === userAgent && s.ip === ip
+    );
+    if (existing) {
+      existing.lastActiveAt = new Date();
+      await this.enforceSessionCap(user);
+      return existing;
+    }
+
+    const session = {
+      sessionId: crypto.randomBytes(16).toString('hex'),
+      userAgent,
+      ip,
+      createdAt: new Date(),
+      lastActiveAt: new Date()
+    };
+    user.sessions.push(session);
+    await this.enforceSessionCap(user);
+    return session;
+  }
+
+  /**
+   * Touch a session's activity timestamp (e.g. on token refresh).
+   * No-op if the session is not found.
+   */
+  async touchSession(user, sessionId) {
+    if (!user.sessions) return null;
+    const session = user.sessions.find((s) => s.sessionId === sessionId);
+    if (session) {
+      session.lastActiveAt = new Date();
+      await user.save();
+    }
+    return session;
+  }
+
+  /**
+   * Revoke a single session by sessionId.
+   */
+  async revokeSession(user, sessionId) {
+    if (!user.sessions) return;
+    user.sessions = user.sessions.filter((s) => s.sessionId !== sessionId);
+    await user.save();
+  }
+
+  /**
+   * Revoke ALL sessions for a user (logout everywhere).
+   */
+  async revokeAllSessions(user) {
+    user.sessions = [];
+    await this.save(user);
+    return this.bumpSessionVersion(user);
+  }
+
+  async save(user) {
+    await user.save();
+  }
+}
+
+module.exports = SessionService;

package/src/services/webhook.service.js

@@ -0,0 +1,134 @@
+// packages/auth/src/services/webhook.service.js
+/**
+ * WebhookService — fire HTTP callbacks for auth events so downstream
+ * systems (CRM, analytics, SIEM) can react to registration, login, etc.
+ *
+ * Failures are swallowed (logged) so they never break auth flows.
+ */
+const https = require('https');
+const http = require('http');
+const URL = require('url');
+const crypto = require('crypto');
+
+class WebhookService {
+  constructor(config = {}) {
+    this.config = config;
+    this.enabled = !!(config.webhooks && config.webhooks.url);
+    this.url = this.enabled ? config.webhooks.url : null;
+    this.secret = this.enabled ? config.webhooks.secret : null;
+    this.events = this.enabled
+      ? config.webhooks.events || ['user.registered', 'user.login', 'user.logout', 'user.password_changed']
+      : [];
+    this.deliveryStats = {
+      total: 0,
+      success: 0,
+      failure: 0,
+      lastEvent: null,
+      lastStatus: null
+    };
+  }
+
+  /**
+   * Sign the payload with HMAC-SHA256 so receivers can verify authenticity.
+   */
+  sign(payload) {
+    if (!this.secret) return null;
+    return crypto
+      .createHmac('sha256', this.secret)
+      .update(payload)
+      .digest('hex');
+  }
+
+  /**
+   * Fire a webhook event. Non-blocking — failures are caught and returned,
+   * never thrown.
+   */
+  async emit(event, data = {}) {
+    if (!this.enabled) return { delivered: false, reason: 'webhooks_disabled' };
+    if (this.events.length && !this.events.includes(event)) {
+      return { delivered: false, reason: 'event_not_subscribed', event };
+    }
+
+    const body = JSON.stringify({
+      event,
+      timestamp: new Date().toISOString(),
+      data
+    });
+    const signature = this.sign(body);
+
+    const parsed = URL.parse(this.url);
+    const transport = parsed.protocol === 'https:' ? https : http;
+
+    return new Promise((resolve) => {
+      const req = transport.request(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+          path: parsed.path || '/',
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+            'X-Crafta-Event': event,
+            ...(signature ? { 'X-Crafta-Signature': signature } : {})
+          }
+        },
+        (res) => {
+          let payload = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => (payload += chunk));
+          res.on('end', () => {
+            const success = res.statusCode >= 200 && res.statusCode < 300;
+            this.deliveryStats.total++;
+            if (success) {
+              this.deliveryStats.success++;
+            } else {
+              this.deliveryStats.failure++;
+            }
+            this.deliveryStats.lastEvent = event;
+            this.deliveryStats.lastStatus = res.statusCode;
+
+            resolve({
+              delivered: success,
+              status: res.statusCode,
+              body: payload.slice(0, 500)
+            });
+          });
+        }
+      );
+
+      req.on('error', (err) => {
+        this.deliveryStats.total++;
+        this.deliveryStats.failure++;
+        this.deliveryStats.lastEvent = event;
+        this.deliveryStats.lastStatus = 'error';
+
+        resolve({ delivered: false, reason: err.message });
+      });
+
+      req.setTimeout(5000, () => {
+        req.destroy();
+        resolve({ delivered: false, reason: 'request_timeout' });
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+
+  /**
+   * Returns delivery monitoring statistics.
+   */
+  getDeliveryStatus() {
+    const rate = this.deliveryStats.total > 0
+      ? (this.deliveryStats.success / this.deliveryStats.total) * 100
+      : 0;
+
+    return {
+      ...this.deliveryStats,
+      successRate: `${rate.toFixed(2)}%`
+    };
+  }
+}
+
+module.exports = WebhookService;

package/src/utils/api-error.js

@@ -1,8 +1,165 @@
-class ApiError extends Error {
-  constructor(message, status = 400) {
-    super(message);
-    this.status = status;
-  }
-}
-
-module.exports = ApiError;
+// packages/auth/src/utils/api-error.js
+/**
+ * Standardized, machine-readable auth errors.
+ *
+ * Every error thrown by the library carries:
+ *   - code    : stable, namespaced error code (AUTH_*)
+ *   - message : human-readable description
+ *   - status  : HTTP status code
+ *   - details : optional structured payload (e.g. field-level messages)
+ *
+ * Frontends can switch on `code` instead of parsing prose strings.
+ */
+class ApiError extends Error {
+  constructor(message, code = 'AUTH_INTERNAL', status = 400, details = undefined) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = status;
+    if (details !== undefined) this.details = details;
+
+    // keep V8 stack trace behaviour intact
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  // ---- factory helpers -------------------------------------------------
+  static unauthorized(message = 'Authentication required', details) {
+    return new ApiError(message, 'AUTH_UNAUTHORIZED', 401, details);
+  }
+
+  static forbidden(message = 'Insufficient permissions', details) {
+    return new ApiError(message, 'AUTH_FORBIDDEN', 403, details);
+  }
+
+  static notFound(message = 'Resource not found', details) {
+    return new ApiError(message, 'AUTH_NOT_FOUND', 404, details);
+  }
+
+  static validation(message = 'Invalid request data', details) {
+    return new ApiError(message, 'AUTH_VALIDATION', 400, details);
+  }
+
+  static badRequest(message = 'Bad request', details) {
+    return new ApiError(message, 'AUTH_BAD_REQUEST', 400, details);
+  }
+
+  static conflict(message = 'Resource already exists', details) {
+    return new ApiError(message, 'AUTH_CONFLICT', 409, details);
+  }
+
+  static tooManyRequests(message = 'Too many requests, please try later', details) {
+    return new ApiError(message, 'AUTH_RATE_LIMITED', 429, details);
+  }
+
+  static accountLocked(message = 'Account locked. Try again later.', details) {
+    return new ApiError(message, 'AUTH_ACCOUNT_LOCKED', 403, details);
+  }
+
+  static invalidCredentials(message = 'Invalid credentials', details) {
+    return new ApiError(message, 'AUTH_INVALID_CREDENTIALS', 401, details);
+  }
+
+  static invalidToken(message = 'Invalid or expired token', details) {
+    return new ApiError(message, 'AUTH_INVALID_TOKEN', 401, details);
+  }
+
+  static expiredToken(message = 'Token expired', details) {
+    return new ApiError(message, 'AUTH_EXPIRED_TOKEN', 401, details);
+  }
+
+  static emailNotVerified(message = 'Email not verified', details) {
+    return new ApiError(message, 'AUTH_EMAIL_NOT_VERIFIED', 403, details);
+  }
+
+  static twoFactorRequired(message = 'Two-factor authentication required', details) {
+    return new ApiError(message, 'AUTH_2FA_REQUIRED', 403, details);
+  }
+
+  static twoFactorFailed(message = 'Invalid 2FA code', details) {
+    return new ApiError(message, 'AUTH_2FA_FAILED', 401, details);
+  }
+
+  static passwordPolicy(message = 'Password policy violation', details) {
+    return new ApiError(message, 'AUTH_PASSWORD_POLICY', 400, details);
+  }
+
+  static passwordReuse(message = 'Cannot reuse previous passwords', details) {
+    return new ApiError(message, 'AUTH_PASSWORD_REUSE', 400, details);
+  }
+
+  static smtpDisabled(message = 'Email delivery is not configured', details) {
+    return new ApiError(message, 'AUTH_SMTP_DISABLED', 503, details);
+  }
+
+  static socialAuthFailed(message = 'Social login failed', details) {
+    return new ApiError(message, 'AUTH_SOCIAL_FAILED', 400, details);
+  }
+
+  static internal(message = 'Internal server error', details) {
+    return new ApiError(message, 'AUTH_INTERNAL', 500, details);
+  }
+
+  // ---- predicates -------------------------------------------------------
+  /** true when the thrown value is one of our ApiError instances */
+  static isApiError(err) {
+    return err instanceof ApiError;
+  }
+
+  /** Coerce any thrown value into an ApiError (never throws) */
+  static normalize(err) {
+    if (err instanceof ApiError) return err;
+
+    if (err && typeof err === 'object') {
+      // mongoose ValidationError
+      if (err.name === 'ValidationError') {
+        const details = {};
+        for (const [k, v] of Object.entries(err.errors || {})) {
+          details[k] = v.message;
+        }
+        return new ApiError(
+          'Validation failed',
+          'AUTH_VALIDATION',
+          400,
+          Object.keys(details).length ? details : undefined
+        );
+      }
+      // jwt errors
+      if (err.name === 'JsonWebTokenError' || err.name === 'TokenExpiredError') {
+        return new ApiError(
+          err.message || 'Invalid token',
+          err.name === 'TokenExpiredError' ? 'AUTH_EXPIRED_TOKEN' : 'AUTH_INVALID_TOKEN',
+          401
+        );
+      }
+      // CastError (invalid ObjectId etc.)
+      if (err.name === 'CastError') {
+        return new ApiError('Invalid identifier', 'AUTH_INVALID_ID', 400);
+      }
+      // duplicate key
+      if (err.code === 11000) {
+        const field = err.keyValue ? Object.keys(err.keyValue)[0] : 'field';
+        return new ApiError(
+          `${field} already exists`,
+          'AUTH_CONFLICT',
+          409,
+          { field }
+        );
+      }
+      if (typeof err.status === 'number') {
+        return new ApiError(
+          err.message || 'Request failed',
+          err.code || 'AUTH_EXTERNAL',
+          err.status
+        );
+      }
+    }
+
+    if (err instanceof Error) {
+      return new ApiError(err.message, 'AUTH_INTERNAL', 500);
+    }
+
+    return new ApiError('Internal server error', 'AUTH_INTERNAL', 500);
+  }
+}
+
+module.exports = ApiError;

package/src/utils/email.js

@@ -2,10 +2,12 @@
 const nodemailer = require('nodemailer');
 const fs = require('fs');
 const path = require('path');
+const ApiError = require('./api-error');
 
 class EmailService {
   constructor(config) {
     this.config = config;
+    this.baseUrl = (config && config.baseUrl) || '';
     this.smtpEnabled = !!(
       config.smtp &&
       config.smtp.host &&
@@ -20,10 +22,21 @@ class EmailService {
     this.templateDir = config.emailTemplateDir || path.join(process.cwd(), "templates/email");
   }
 
+  // Build a safe absolute URL from a base and a path, avoiding double slashes
+  // or `undefined/...` when baseUrl is missing.
+  joinUrl(base, urlPath) {
+    let b = (base == null ? '' : String(base)).trim();
+    if (b && b !== '/' && b.endsWith('/')) b = b.slice(0, -1);
+    let p = (urlPath == null ? '' : String(urlPath)).trim();
+    if (!p) p = '/';
+    if (!p.startsWith('/')) p = '/' + p;
+    return `${b}${p}`;
+  }
+
   // Reusable sender
   async send({ to, subject, html, text }) {
     if (!this.smtpEnabled) {
-      return { sent: false, reason: 'smtp_disabled' };
+      throw ApiError.smtpDisabled('Email delivery is not configured. Configure smtp in auth config.');
     }
 
     try {
@@ -48,9 +61,10 @@ class EmailService {
 
     let content = fs.readFileSync(filePath, "utf8");
 
-    // Replace {{variable}}
-    for (const key of Object.keys(variables)) {
-      content = content.replace(new RegExp(`{{${key}}}`, "g"), variables[key]);
+    // Replace {{variable}} using a safer approach
+    for (const [key, value] of Object.entries(variables)) {
+      const regex = new RegExp(`{{\\s*${key}\\s*}}`, "g");
+      content = content.replace(regex, value);
     }
 
     return content;
@@ -58,7 +72,7 @@ class EmailService {
 
   async sendVerificationEmail(user, token) {
     const verifyPath = this.config.routes?.verify || '/verify';
-    const url = `${this.config.baseUrl}${verifyPath}?token=${token}`;
+    const url = `${this.joinUrl(this.baseUrl, verifyPath)}?token=${token}`;
 
     const html = this.loadTemplate("email-verification", {
       name: user.name || user.email,
@@ -75,7 +89,7 @@ class EmailService {
 
   async sendPasswordResetEmail(user, token) {
     const resetPath = this.config.routes?.resetPassword || '/reset-password';
-    const url = `${this.config.baseUrl}${resetPath}?token=${token}`;
+    const url = `${this.joinUrl(this.baseUrl, resetPath)}?token=${token}`;
 
     const html = this.loadTemplate("password-reset", {
       name: user.name || user.email,
@@ -91,21 +105,25 @@ class EmailService {
   }
 
   async sendLoginAlert(user, info) {
+    info = info || {};
+    const ip = info.ip || 'unknown';
+    const userAgent = info.userAgent || 'unknown';
+
     const html = this.loadTemplate("login-alert", {
       name: user.name || user.email,
-      ip: info.ip,
-      agent: info.userAgent
+      ip,
+      agent: userAgent
     }) || `
       New login detected.<br>
-      IP: ${info.ip}<br>
-      User Agent: ${info.userAgent}
+      IP: ${ip}<br>
+      User Agent: ${userAgent}
     `;
 
     return this.send({
       to: user.email,
       subject: "New Login Detected",
       html,
-      text: `New login from IP ${info.ip}`
+      text: `New login from IP ${ip}`
     });
   }
 
@@ -123,6 +141,34 @@ class EmailService {
     });
   }
 
+  async sendMagicLink(user, url) {
+    const html = this.loadTemplate("magic-link", {
+      name: user.name || user.email,
+      url
+    }) || `Sign in with this magic link: <a href="${url}">${url}</a><br>This link expires in 15 minutes.`;
+
+    return this.send({
+      to: user.email,
+      subject: "Your Magic Sign-In Link",
+      html,
+      text: `Sign in here: ${url} (expires in 15 minutes)`
+    });
+  }
+
+  async sendMagicLink(user, url) {
+    const html = this.loadTemplate("magic-link", {
+      name: user.name || user.email,
+      url
+    }) || `Sign in with this magic link: <a href="${url}">${url}</a><br>This link expires in 15 minutes.`;
+
+    return this.send({
+      to: user.email,
+      subject: "Your Magic Sign-In Link",
+      html,
+      text: `Sign in here: ${url} (expires in 15 minutes)`
+    });
+  }
+
   async sendAccountLockEmail(user) {
     const html = this.loadTemplate("account-locked", {
       name: user.name || user.email