@dax-crafta/auth 2.1.6 → 2.1.7

package/src/services/webhook.service.js

@@ -0,0 +1,93 @@
+// 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']
+      : [];
+  }
+
+  /**
+   * 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', () => {
+            resolve({
+              delivered: res.statusCode >= 200 && res.statusCode < 300,
+              status: res.statusCode,
+              body: payload.slice(0, 500)
+            });
+          });
+        }
+      );
+
+      req.on('error', (err) => {
+        resolve({ delivered: false, reason: err.message });
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+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 {
@@ -58,7 +71,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 +88,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 +104,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 +140,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

package/src/utils/mfa.js

@@ -2,30 +2,39 @@
 const speakeasy = require('speakeasy');
 const qrcode = require('qrcode');
 const crypto = require('crypto');
+const ApiError = require('./api-error');
 
 class MFAService {
   async generateSecret(label, issuer = 'App') {
-    const secret = speakeasy.generateSecret({
-      length: 32,
-      name: label,
-      issuer
-    });
-
-    const qrCodeUrl = await qrcode.toDataURL(secret.otpauth_url);
-
-    return {
-      secret: secret.base32,
-      qrCode: qrCodeUrl
-    };
+    try {
+      const secret = speakeasy.generateSecret({
+        length: 32,
+        name: label,
+        issuer
+      });
+
+      const qrCodeUrl = await qrcode.toDataURL(secret.otpauth_url);
+
+      return {
+        secret: secret.base32,
+        qrCode: qrCodeUrl
+      };
+    } catch (err) {
+      throw ApiError.internal('Failed to generate MFA secret');
+    }
   }
 
   verifyToken(token, secret) {
-    return speakeasy.totp.verify({
-      secret,
-      encoding: 'base32',
-      token,
-      window: 1
-    });
+    try {
+      return speakeasy.totp.verify({
+        secret,
+        encoding: 'base32',
+        token,
+        window: 1
+      });
+    } catch (err) {
+      return false;
+    }
   }
 
   // Generate hashed backup codes (safer)