@mikkelscheike/email-provider-links 1.6.0 → 1.8.0

package/README.md

@@ -1,14 +1,14 @@
 # Email Provider Links
 
-🔒 **Enterprise-grade secure email provider detection for login and password reset flows**
+🔒 **Modern email provider detection library with concurrent DNS resolution and enterprise security**
 
-A TypeScript package that provides direct links to email providers based on email addresses, with comprehensive security features to prevent malicious redirects and supply chain attacks.
+A TypeScript library providing direct links to **93 email providers** (178 domains) with **concurrent DNS resolution**, **optimized performance**, **email alias detection**, and comprehensive security features for login and password reset flows.
 
 ## ✨ Features
 
 - 🚀 **Fast & Lightweight**: Zero dependencies, minimal footprint
-- 📧 **74 Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and more
-- 🌐 **147+ Domains Supported**: Comprehensive international coverage
+- 📧 **93 Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and many more
+- 🌐 **178 Domains Supported**: Comprehensive international coverage
 - 🏢 **Business Domain Detection**: DNS-based detection for custom domains (Google Workspace, Microsoft 365, etc.)
 - 🔒 **Enterprise Security**: Multi-layer protection against malicious URLs and supply chain attacks
 - 🛡️ **URL Validation**: HTTPS-only enforcement with domain allowlisting
@@ -16,7 +16,9 @@ A TypeScript package that provides direct links to email providers based on emai
 - 📝 **Type Safe**: Full TypeScript support with comprehensive interfaces
 - ⚡ **Performance Optimized**: Smart DNS fallback with configurable timeouts
 - 🚦 **Rate Limiting**: Built-in DNS query rate limiting to prevent abuse
-- 🧪 **Thoroughly Tested**: 142+ tests with 94.69% code coverage
+- 🔄 **Email Alias Detection**: Normalize Gmail dots, plus addressing, and provider-specific aliases
+- 🛡️ **Fraud Prevention**: Detect duplicate accounts through email alias manipulation
+- 🧪 **Thoroughly Tested**: 371 tests with 91.75% code coverage
 
 ## Installation
 
@@ -26,21 +28,28 @@ npm install @mikkelscheike/email-provider-links
 
 ## Quick Start
 
+**One function handles everything** - consumer emails, business domains, and unknown providers:
+
 ```typescript
-import { getEmailProviderLinkWithDNS } from '@mikkelscheike/email-provider-links';
+import { getEmailProvider } from '@mikkelscheike/email-provider-links';
 
-// Works for any email address
-const result = await getEmailProviderLinkWithDNS('user@gmail.com');
-console.log(result.loginUrl); // "https://mail.google.com/mail/"
+// Works for ANY email address - the only function you need
+const result = await getEmailProvider('user@gmail.com');
+console.log(result.loginUrl);                    // "https://mail.google.com/mail/"
+console.log(result.provider?.companyProvider);   // "Gmail"
 
-// Business domains too
-const business = await getEmailProviderLinkWithDNS('user@mycompany.com');
+// Automatically detects business domains too
+const business = await getEmailProvider('user@mycompany.com');
 console.log(business.provider?.companyProvider); // "Google Workspace" (if detected)
+
+// Gracefully handles unknown providers
+const unknown = await getEmailProvider('user@unknown.com');
+console.log(unknown.loginUrl);                   // null
 ```
 
 ## Supported Providers
 
-**📊 Current Coverage: 74 providers supporting 147+ domains**
+**📊 Current Coverage: 93 providers supporting 178 domains**
 
 **Consumer Email Providers:**
 - **Gmail** (2 domains): gmail.com, googlemail.com
@@ -64,25 +73,26 @@ console.log(business.provider?.companyProvider); // "Google Workspace" (if detec
 - **Mailfence, SimpleLogin, AnonAddy**
 
 **International Providers:**
-- **Europe**: GMX, Web.de, Orange, Free.fr, T-Online, Libero
-- **Asia**: QQ Mail, NetEase, Sina Mail, Rakuten, Nifty, **Naver** (Korea), **Daum** (Korea), **Biglobe** (Japan)
-- **Other Regions**: UOL (Brazil), Telkom (South Africa), Xtra (New Zealand)
+- **Europe**: GMX, Web.de, Orange, Free.fr, T-Online, Libero, Virgilio, Telekom, Tiscali, Skynet, Telenet, Xs4All, Planet.nl, Bluewin, Eircom
+- **Asia**: QQ Mail, NetEase, Sina Mail, Alibaba Mail, Rakuten, Nifty, **Naver** (Korea), **Daum** (Korea), **Biglobe** (Japan), Sify, IndiatTimes (India)
+- **Eastern Europe**: Centrum (Czech/Slovak), Interia, Onet (Poland), Rambler (Russia)
+- **Other Regions**: UOL, Terra (Brazil), Telkom (South Africa), Xtra (New Zealand)
 
 ## API
 
-### `getEmailProviderLinkWithDNS(email, timeout?)`
+### `getEmailProvider(email, timeout?)`
 **Recommended** - Detects any email provider including business domains.
 
 ```typescript
-const result = await getEmailProviderLinkWithDNS('user@gmail.com', 3000);
+const result = await getEmailProvider('user@gmail.com', 3000);
 // Returns: { provider, loginUrl, detectionMethod, email }
 ```
 
-### `getEmailProviderLink(email)`
+### `getEmailProviderSync(email)`
 **Synchronous** - Only checks predefined domains (no DNS lookup).
 
 ```typescript
-const result = getEmailProviderLink('user@gmail.com');
+const result = getEmailProviderSync('user@gmail.com');
 // Returns: { provider, loginUrl, email }
 ```
 
@@ -90,7 +100,7 @@ const result = getEmailProviderLink('user@gmail.com');
 
 ```typescript
 async function handlePasswordReset(email: string) {
-  const result = await getEmailProviderLinkWithDNS(email);
+  const result = await getEmailProvider(email);
   
   return {
     providerUrl: result.loginUrl,
@@ -100,25 +110,112 @@ async function handlePasswordReset(email: string) {
 }
 ```
 
+
 ## Configuration
 
 ```typescript
 // Custom DNS timeout (default: 5000ms)
-const result = await getEmailProviderLinkWithDNS(email, 2000);
+const result = await getEmailProvider(email, 2000);
+
+// Rate limiting configuration
+import { Config } from '@mikkelscheike/email-provider-links';
+console.log('Max requests:', Config.MAX_DNS_REQUESTS_PER_MINUTE); // 10
+console.log('Default timeout:', Config.DEFAULT_DNS_TIMEOUT);       // 5000ms
+```
+
+## Advanced Usage
+
+<details>
+<summary><strong>📚 Secondary Functions & Specialized Use Cases</strong></summary>
+
+### Synchronous Provider Detection (No DNS)
+
+If you can't use async or don't want DNS lookups:
+
+```typescript
+import { getEmailProviderSync } from '@mikkelscheike/email-provider-links';
+
+// Synchronous - only checks predefined domains
+const result = getEmailProviderSync('user@gmail.com');
+console.log(result.loginUrl); // Works for known domains only
+```
+
+### Provider Support Checking
+
+```typescript
+import { isEmailProviderSupported, getSupportedProviders } from '@mikkelscheike/email-provider-links';
 
 // Check if provider is supported
-import { isEmailProviderSupported } from '@mikkelscheike/email-provider-links';
 const supported = isEmailProviderSupported('user@gmail.com');
 
-// Rate limiting configuration
-import { RateLimit } from '@mikkelscheike/email-provider-links';
-console.log('Max requests:', RateLimit.MAX_REQUESTS); // 10
-console.log('Time window:', RateLimit.WINDOW_MS);     // 60000ms
+// Get all supported providers
+const allProviders = getSupportedProviders();
+console.log(`Supports ${allProviders.length} providers`);
+```
 
-// Custom rate limiter for specific use cases
-const customLimiter = new RateLimit.SimpleRateLimiter(20, 120000); // 20 requests per 2 minutes
+### Advanced Provider Detection
+
+```typescript
+import { getEmailProviderFast, detectProviderConcurrent } from '@mikkelscheike/email-provider-links';
+
+// High-performance detection with concurrent DNS
+const fastResult = await getEmailProviderFast('user@mycompany.com', {
+  enableParallel: true,
+  collectDebugInfo: true
+});
+console.log(fastResult.provider?.companyProvider); // "Google Workspace"
+console.log(fastResult.timing);                    // Performance metrics
+```
+
+### Configuration Options
+
+```typescript
+import { Config } from '@mikkelscheike/email-provider-links';
+
+// Access configuration constants
+console.log(Config.DEFAULT_DNS_TIMEOUT);           // 5000ms
+console.log(Config.MAX_DNS_REQUESTS_PER_MINUTE);   // 10
+console.log(Config.SUPPORTED_PROVIDERS_COUNT);     // 93
 ```
 
+### 🔄 Email Alias Detection & Normalization
+
+**Specialized feature** for preventing duplicate accounts and fraud detection:
+
+```typescript
+import { 
+  normalizeEmail, 
+  emailsMatch 
+} from '@mikkelscheike/email-provider-links';
+
+// Prevent duplicate accounts
+async function registerUser(email: string) {
+  const canonical = normalizeEmail(email);
+  const existingUser = await findUserByEmail(canonical);
+  
+  if (existingUser) {
+    throw new Error('Email already registered');
+  }
+  
+  await createUser({ email: canonical });
+}
+
+// Check if login email matches registration
+const match = emailsMatch('user@gmail.com', 'u.s.e.r+work@gmail.com');
+console.log(match); // true - same person
+
+// Simple normalization
+const canonical = normalizeEmail('u.s.e.r+work@gmail.com');
+console.log(canonical);  // 'user@gmail.com'
+```
+
+**Supported alias types:**
+- **Gmail dots**: `u.s.e.r@gmail.com` → `user@gmail.com`
+- **Plus addressing**: `user+tag@provider.com` → `user@provider.com`
+- **Provider-specific rules**: Different providers have different capabilities
+
+</details>
+
 ## TypeScript Support
 
 ```typescript
@@ -130,11 +227,11 @@ interface EmailProviderResult {
   proxyService?: string;
 }
 
-interface RateLimitConfig {
-  MAX_REQUESTS: number;     // 10 requests
-  WINDOW_MS: number;        // 60000ms (1 minute)
-  SimpleRateLimiter: class; // Custom rate limiter class
-  getCurrentLimiter(): SimpleRateLimiter; // Get current global limiter
+interface ConfigConstants {
+  DEFAULT_DNS_TIMEOUT: number;          // 5000ms
+  MAX_DNS_REQUESTS_PER_MINUTE: number;  // 10 requests
+  SUPPORTED_PROVIDERS_COUNT: number;    // 93 providers
+  SUPPORTED_DOMAINS_COUNT: number;      // 178 domains
 }
 ```
 
@@ -145,7 +242,7 @@ This package implements **enterprise-grade security** to protect against malicio
 ### ✅ Multi-Layer Protection
 
 - **HTTPS-Only Enforcement**: All provider URLs must use HTTPS protocol
-- **Domain Allowlisting**: Only pre-approved domains are allowed (64+ verified providers)
+- **Domain Allowlisting**: Only pre-approved domains are allowed (93+ verified providers)
 - **Malicious Pattern Detection**: Blocks IP addresses, URL shorteners, suspicious TLDs
 - **Path Traversal Prevention**: Detects and blocks `../` and encoded variants
 - **JavaScript Injection Protection**: Prevents `javascript:`, `data:`, and script injections
@@ -165,7 +262,7 @@ Protects against common attack vectors:
 ### 🧪 Security Testing
 
 - **29 dedicated security tests** covering all attack vectors
-- **94% security code coverage** with edge case testing
+- **96% security module coverage** with edge case testing
 - **Automated security validation** in CI/CD pipeline
 - **Regular security audits** of provider database
 
@@ -188,6 +285,7 @@ if (result.securityReport.securityLevel === 'CRITICAL') {
 
 We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on adding new email providers.
 
+**Quality Assurance**: This project maintains high standards with 371 comprehensive tests achieving 91.75% code coverage.
 **Security Note**: All new providers undergo security validation and must pass our allowlist verification.
 
 ## Security

package/dist/alias-detection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Email Alias Detection Module
+ *
+ * Clean, focused implementation with only essential functions.
+ * Detects and normalizes email aliases across different providers.
+ */
+export interface AliasDetectionResult {
+    /** The normalized/canonical email address */
+    canonical: string;
+    /** The original email address */
+    original: string;
+    /** Whether an alias was detected */
+    isAlias: boolean;
+    /** Type of alias detected */
+    aliasType: 'plus' | 'dot' | 'none';
+    /** The alias part (if any) */
+    aliasPart?: string;
+    /** The provider that supports this alias type */
+    provider?: string;
+}
+/**
+ * Detects and analyzes email aliases
+ *
+ * @param email - Email address to analyze
+ * @returns Detailed analysis of the email alias
+ */
+export declare function detectEmailAlias(email: string): AliasDetectionResult;
+/**
+ * Normalizes an email address to its canonical form.
+ *
+ * This is the primary function for preventing duplicate accounts.
+ *
+ * @param email - Email address to normalize
+ * @returns Canonical email address
+ *
+ * @example
+ * ```typescript
+ * const canonical = normalizeEmail('U.S.E.R+work@GMAIL.COM');
+ * console.log(canonical); // 'user@gmail.com'
+ * ```
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * Checks if two email addresses are the same when normalized.
+ *
+ * This is the primary function for matching aliases during login.
+ *
+ * @param email1 - First email address
+ * @param email2 - Second email address
+ * @returns true if the emails represent the same person
+ *
+ * @example
+ * ```typescript
+ * const match = emailsMatch('user@gmail.com', 'u.s.e.r+work@gmail.com');
+ * console.log(match); // true
+ * ```
+ */
+export declare function emailsMatch(email1: string, email2: string): boolean;

package/dist/alias-detection.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Email Alias Detection Module
+ *
+ * Clean, focused implementation with only essential functions.
+ * Detects and normalizes email aliases across different providers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEmailAlias = detectEmailAlias;
+exports.normalizeEmail = normalizeEmail;
+exports.emailsMatch = emailsMatch;
+/**
+ * Email alias rules for major providers
+ */
+const ALIAS_RULES = [
+    {
+        domains: ['gmail.com', 'googlemail.com'],
+        supportsPlusAddressing: true,
+        ignoresDots: true,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            // Remove dots and everything after +
+            const cleanUsername = username.replace(/\./g, '').split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['outlook.com', 'hotmail.com', 'live.com', 'msn.com', 'hotmail.co.uk', 'hotmail.fr', 'hotmail.it', 'hotmail.es', 'hotmail.de', 'live.co.uk', 'live.fr', 'live.it', 'live.nl', 'live.com.au', 'live.ca', 'live.jp'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            // Only remove plus addressing for Outlook
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['yahoo.com', 'yahoo.co.uk', 'yahoo.fr', 'yahoo.co.in', 'yahoo.com.br', 'yahoo.co.jp', 'yahoo.it', 'yahoo.de', 'yahoo.in', 'yahoo.es', 'yahoo.ca', 'yahoo.com.au', 'yahoo.com.ar', 'yahoo.com.mx', 'yahoo.co.id', 'yahoo.com.sg', 'ymail.com', 'rocketmail.com'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['fastmail.com', 'fastmail.fm'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['proton.me', 'protonmail.com', 'protonmail.ch', 'pm.me'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['tutanota.com', 'tutanota.de', 'tutamail.com', 'tuta.io', 'keemail.me', 'tuta.com'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['zoho.com', 'zohomail.com', 'zoho.eu'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['icloud.com', 'me.com', 'mac.com'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['mail.com'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['aol.com', 'love.com', 'ygm.com', 'games.com', 'wow.com', 'aim.com'],
+        supportsPlusAddressing: false,
+        ignoresDots: false,
+        normalize: (email) => email.toLowerCase()
+    },
+    {
+        domains: ['mail.ru'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    },
+    {
+        domains: ['yandex.com', 'yandex.ru'],
+        supportsPlusAddressing: true,
+        ignoresDots: false,
+        normalize: (email) => {
+            const [username, domain] = email.toLowerCase().split('@');
+            const cleanUsername = username.split('+')[0];
+            return `${cleanUsername}@${domain}`;
+        }
+    }
+];
+/**
+ * Validates email format
+ */
+function isValidEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+}
+/**
+ * Gets the alias rule for a given domain
+ */
+function getAliasRule(domain) {
+    return ALIAS_RULES.find(rule => rule.domains.includes(domain.toLowerCase()));
+}
+/**
+ * Detects and analyzes email aliases
+ *
+ * @param email - Email address to analyze
+ * @returns Detailed analysis of the email alias
+ */
+function detectEmailAlias(email) {
+    if (!isValidEmail(email)) {
+        throw new Error('Invalid email format');
+    }
+    const originalEmail = email.trim();
+    const [username, domain] = originalEmail.toLowerCase().split('@');
+    const rule = getAliasRule(domain);
+    const result = {
+        canonical: originalEmail.toLowerCase(),
+        original: originalEmail,
+        isAlias: false,
+        aliasType: 'none'
+    };
+    if (!rule) {
+        // No specific rule, just normalize case
+        result.canonical = originalEmail.toLowerCase();
+        return result;
+    }
+    result.provider = domain;
+    // Check for plus addressing
+    if (rule.supportsPlusAddressing && username.includes('+')) {
+        const plusIndex = username.indexOf('+');
+        const baseUsername = username.substring(0, plusIndex);
+        const aliasPart = username.substring(plusIndex + 1);
+        result.isAlias = true;
+        result.aliasType = 'plus';
+        result.aliasPart = aliasPart;
+        result.canonical = rule.normalize ? rule.normalize(originalEmail) : `${baseUsername}@${domain}`;
+        return result;
+    }
+    // Check for dot variations (Gmail)
+    if (rule.ignoresDots && username.includes('.')) {
+        const baseUsername = username.replace(/\./g, '');
+        if (baseUsername !== username) {
+            result.isAlias = true;
+            result.aliasType = 'dot';
+            result.aliasPart = username;
+            result.canonical = rule.normalize ? rule.normalize(originalEmail) : `${baseUsername}@${domain}`;
+            return result;
+        }
+    }
+    // Apply provider-specific normalization
+    if (rule.normalize) {
+        const normalized = rule.normalize(originalEmail);
+        if (normalized !== originalEmail.toLowerCase()) {
+            result.isAlias = true;
+            result.canonical = normalized;
+        }
+    }
+    return result;
+}
+/**
+ * Normalizes an email address to its canonical form.
+ *
+ * This is the primary function for preventing duplicate accounts.
+ *
+ * @param email - Email address to normalize
+ * @returns Canonical email address
+ *
+ * @example
+ * ```typescript
+ * const canonical = normalizeEmail('U.S.E.R+work@GMAIL.COM');
+ * console.log(canonical); // 'user@gmail.com'
+ * ```
+ */
+function normalizeEmail(email) {
+    const result = detectEmailAlias(email);
+    return result.canonical;
+}
+/**
+ * Checks if two email addresses are the same when normalized.
+ *
+ * This is the primary function for matching aliases during login.
+ *
+ * @param email1 - First email address
+ * @param email2 - Second email address
+ * @returns true if the emails represent the same person
+ *
+ * @example
+ * ```typescript
+ * const match = emailsMatch('user@gmail.com', 'u.s.e.r+work@gmail.com');
+ * console.log(match); // true
+ * ```
+ */
+function emailsMatch(email1, email2) {
+    try {
+        return normalizeEmail(email1) === normalizeEmail(email2);
+    }
+    catch {
+        return false;
+    }
+}