@mikkelscheike/email-provider-links 2.4.0 → 2.5.1

package/README.md

@@ -9,6 +9,7 @@ A TypeScript library providing direct links to **93 email providers** (178 domai
 - 🚀 **Fast & Lightweight**: Zero dependencies, minimal footprint
 - 📧 **93 Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and many more
 - 🌐 **178 Domains Supported**: Comprehensive international coverage
+- 🌍 **IDN Support**: Full internationalized domain name (punycode) support
 - 🏢 **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
@@ -18,14 +19,35 @@ A TypeScript library providing direct links to **93 email providers** (178 domai
 - 🚦 **Rate Limiting**: Built-in DNS query rate limiting to prevent abuse
 - 🔄 **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
+- 🧪 **Thoroughly Tested**: 370 tests with 92.89% code coverage
 
 ## Installation
 
+Using npm:
 ```bash
 npm install @mikkelscheike/email-provider-links
 ```
 
+Using pnpm:
+```bash
+pnpm add @mikkelscheike/email-provider-links
+```
+
+## Requirements
+
+- **Node.js**: `>=18.0.0` (Tested on 18.x, 20.x, 22.x, **24.x**)
+- **Package Managers**: npm and pnpm (Tested on pnpm 18.x through 24.x)
+- **TypeScript**: `>=4.0.0` (optional)
+- **Zero runtime dependencies** - No external packages required
+
+### Node.js 24 Support ✨
+
+Fully compatible with the latest Node.js 24.x! The library is tested on:
+- Node.js 18.x (LTS)
+- Node.js 20.x (LTS) 
+- Node.js 22.x (Current)
+- **Node.js 24.x (Latest)** - Full support with latest features
+
 ## Quick Start
 
 **One function handles everything** - consumer emails, business domains, and unknown providers:
@@ -84,8 +106,23 @@ console.log(unknown.loginUrl);                   // null
 **Recommended** - Detects any email provider including business domains.
 
 ```typescript
-const result = await getEmailProvider('user@gmail.com', 3000);
-// Returns: { provider, loginUrl, detectionMethod, email }
+// 🚀 SAME CALL, DIFFERENT SCENARIOS:
+
+// ✅ For known providers (Gmail, Yahoo, etc.) - INSTANT response
+const gmail1 = await getEmailProvider('user@gmail.com');        // No timeout needed
+const gmail2 = await getEmailProvider('user@gmail.com', 3000);  // Same speed - timeout ignored
+// Both return instantly: { provider: "Gmail", loginUrl: "https://mail.google.com/mail/" }
+
+// 🔍 For business domains - DNS lookup required, timeout matters
+const biz1 = await getEmailProvider('user@mycompany.com');        // 5000ms timeout (default)
+const biz2 = await getEmailProvider('user@mycompany.com', 2000);  // 2000ms timeout (faster fail)
+const biz3 = await getEmailProvider('user@mycompany.com', 10000); // 10000ms timeout (slower networks)
+// All may detect: { provider: "Google Workspace", detectionMethod: "mx_record" }
+
+// 🎯 WHY USE CUSTOM TIMEOUT?
+// - Faster apps: Use 2000ms to fail fast on unknown domains
+// - Slower networks: Use 10000ms to avoid premature timeouts
+// - Enterprise: Use 1000ms for strict SLA requirements
 ```
 
 ### `getEmailProviderSync(email)`
@@ -285,7 +322,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.
+**Quality Assurance**: This project maintains high standards with 370 comprehensive tests achieving 92.89% code coverage.
 **Security Note**: All new providers undergo security validation and must pass our allowlist verification.
 
 ## Security

package/dist/__tests__/basic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/basic.test.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+(0, globals_1.describe)('Basic Test', () => {
+    (0, globals_1.test)('true should be true', () => {
+        (0, globals_1.expect)(true).toBe(true);
+    });
+});

package/dist/concurrent-dns.d.ts

@@ -68,6 +68,8 @@ export interface ConcurrentDNSResult {
  * Concurrent DNS Detection Engine
  */
 export declare class ConcurrentDNSDetector {
+    private activeQueries;
+    cleanup(): void;
     private config;
     private providers;
     constructor(providers: EmailProvider[], config?: Partial<ConcurrentDNSConfig>);

package/dist/concurrent-dns.js

@@ -28,7 +28,13 @@ const DEFAULT_CONFIG = {
  * Concurrent DNS Detection Engine
  */
 class ConcurrentDNSDetector {
+    // Cleanup method for tests
+    cleanup() {
+        this.activeQueries.clear();
+    }
     constructor(providers, config = {}) {
+        // Store active query states
+        this.activeQueries = new Set();
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.providers = providers.filter(p => p.customDomainDetection &&
             (p.customDomainDetection.mxPatterns || p.customDomainDetection.txtPatterns));
@@ -38,7 +44,7 @@ class ConcurrentDNSDetector {
      */
     async detectProvider(domain) {
         const startTime = Date.now();
-        const normalizedDomain = domain.toLowerCase();
+        const normalizedDomain = domain.toLowerCase().trim().replace(/\.+$/, '');
         // Initialize result
         const result = {
             provider: null,

package/dist/idn.d.ts

@@ -0,0 +1,16 @@
+/**
+ * IDN (Internationalized Domain Names) utilities
+ * Zero-dependency implementation for domain name handling
+ */
+/**
+ * Convert domain to Punycode format
+ * @param domain Domain name to convert
+ * @returns Punycode encoded domain
+ */
+export declare function domainToPunycode(domain: string): string;
+/**
+ * Convert email address's domain to Punycode
+ * @param email Email address to convert
+ * @returns Email with Punycode encoded domain
+ */
+export declare function emailToPunycode(email: string): string;

package/dist/idn.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * IDN (Internationalized Domain Names) utilities
+ * Zero-dependency implementation for domain name handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainToPunycode = domainToPunycode;
+exports.emailToPunycode = emailToPunycode;
+const BASE = 36;
+const INITIAL_N = 128;
+const INITIAL_BIAS = 72;
+const DAMP = 700;
+const TMIN = 1;
+const TMAX = 26;
+const SKEW = 38;
+const DELIMITER = '-';
+function adaptBias(delta, numPoints, firstTime) {
+    delta = firstTime ? Math.floor(delta / DAMP) : Math.floor(delta / 2);
+    delta += Math.floor(delta / numPoints);
+    let k = 0;
+    while (delta > ((BASE - TMIN) * TMAX) / 2) {
+        delta = Math.floor(delta / (BASE - TMIN));
+        k += BASE;
+    }
+    return k + Math.floor(((BASE - TMIN + 1) * delta) / (delta + SKEW));
+}
+function digitToBasic(digit) {
+    return digit + 22 + 75 * Number(digit < 26);
+}
+function encode(str) {
+    const codePoints = Array.from(str).map(c => c.codePointAt(0));
+    let n = INITIAL_N;
+    let delta = 0;
+    let bias = INITIAL_BIAS;
+    let output = '';
+    // Copy ASCII chars directly
+    const basic = codePoints.filter(c => c < 0x80);
+    let h = basic.length;
+    let b = h;
+    if (b > 0) {
+        output = String.fromCodePoint(...basic);
+    }
+    if (b > 0) {
+        output += DELIMITER;
+    }
+    while (h < codePoints.length) {
+        let m = Number.MAX_SAFE_INTEGER;
+        for (const c of codePoints) {
+            if (c >= n && c < m)
+                m = c;
+        }
+        delta += (m - n) * (h + 1);
+        n = m;
+        for (const c of codePoints) {
+            if (c < n) {
+                delta++;
+            }
+            else if (c === n) {
+                let q = delta;
+                for (let k = BASE;; k += BASE) {
+                    const t = k <= bias ? TMIN : k >= bias + TMAX ? TMAX : k - bias;
+                    if (q < t)
+                        break;
+                    output += String.fromCodePoint(digitToBasic(t + (q - t) % (BASE - t)));
+                    q = Math.floor((q - t) / (BASE - t));
+                }
+                output += String.fromCodePoint(digitToBasic(q));
+                bias = adaptBias(delta, h + 1, h === b);
+                delta = 0;
+                h++;
+            }
+        }
+        delta++;
+        n++;
+    }
+    return output;
+}
+/**
+ * Convert domain to Punycode format
+ * @param domain Domain name to convert
+ * @returns Punycode encoded domain
+ */
+function domainToPunycode(domain) {
+    // Split domain into labels
+    return domain.toLowerCase().split('.').map(label => {
+        // Check if label needs encoding (contains non-ASCII)
+        if (!/[^\x00-\x7F]/.test(label)) {
+            return label;
+        }
+        return 'xn--' + encode(label);
+    }).join('.');
+}
+/**
+ * Convert email address's domain to Punycode
+ * @param email Email address to convert
+ * @returns Email with Punycode encoded domain
+ */
+function emailToPunycode(email) {
+    const [local, domain] = email.split('@');
+    if (!domain)
+        return email;
+    return `${local}@${domainToPunycode(domain)}`;
+}

package/dist/security/hash-verifier.js

@@ -29,7 +29,7 @@ const KNOWN_GOOD_HASHES = {
     // SHA-256 hash of the legitimate emailproviders.json
     'emailproviders.json': 'f77814bf0537019c6f38bf2744ae21640f04a2d39cb67c5116f6e03160c9486f',
     // You can add hashes for other critical files
-    'package.json': 'b9ef67d46c55b947ea366d49d66dadcf37e729cef7a319fa710a5d251fcac60c'
+    'package.json': '92cc46fb47a1466bf3f448cd2f289d51e65daf7e7a93b389e956a49b6ffc4bbe'
 };
 /**
  * Calculates SHA-256 hash of a file or string content

package/dist/security/secure-loader.d.ts

@@ -33,11 +33,13 @@ export declare function initializeSecurity(): Record<string, string>;
 /**
  * Express middleware for secure provider loading (if using in web apps)
  */
-export declare function createSecurityMiddleware(options?: {
+interface SecurityMiddlewareOptions {
     expectedHash?: string;
     allowInvalidUrls?: boolean;
     onSecurityIssue?: (report: SecureLoadResult['securityReport']) => void;
-}): (req: any, res: any, next: any) => any;
+    getProviders?: () => SecureLoadResult;
+}
+export declare function createSecurityMiddleware(options?: SecurityMiddlewareOptions): (req: any, res: any, next: any) => any;
 declare const _default: {
     secureLoadProviders: typeof secureLoadProviders;
     initializeSecurity: typeof initializeSecurity;

package/dist/security/secure-loader.js

@@ -118,12 +118,11 @@ function initializeSecurity() {
     console.log('\n⚠️  Remember to update hashes when making legitimate changes to provider data!');
     return hashes;
 }
-/**
- * Express middleware for secure provider loading (if using in web apps)
- */
 function createSecurityMiddleware(options = {}) {
     return (req, res, next) => {
-        const result = secureLoadProviders(undefined, options.expectedHash);
+        // If a custom providers getter is provided, use that instead of loading from file
+        const result = options.getProviders ? options.getProviders() : secureLoadProviders(undefined, options.expectedHash);
+        // Handle security level
         if (result.securityReport.securityLevel === 'CRITICAL' && !options.allowInvalidUrls) {
             if (options.onSecurityIssue) {
                 options.onSecurityIssue(result.securityReport);

package/dist/security/url-validator.js

@@ -134,6 +134,7 @@ const URL_SHORTENERS = [
     'is.gd',
     'buff.ly'
 ];
+const idn_1 = require("../idn");
 /**
  * Validates if a URL is safe for email provider redirects
  *
@@ -179,7 +180,7 @@ function validateEmailProviderUrl(url) {
         }
         // Parse and normalize the URL
         const urlObj = new URL(url);
-        const domain = urlObj.hostname.toLowerCase();
+        const domain = (0, idn_1.domainToPunycode)(urlObj.hostname.toLowerCase());
         const normalizedUrl = urlObj.toString();
         // Must use HTTPS
         if (urlObj.protocol !== 'https:') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikkelscheike/email-provider-links",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "TypeScript library for email provider detection with 93 providers (178 domains), concurrent DNS resolution, optimized performance, 91.75% test coverage, and enterprise security for login and password reset flows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -53,10 +53,13 @@
   "bugs": {
     "url": "https://github.com/mikkelscheike/email-provider-links/issues"
   },
+  "engines": {
+    "node": ">=18.0.0",
+    "comment": "Supports Node.js 18.x, 20.x, 22.x, and 24.x"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.11.1",
   "devDependencies": {
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/exec": "^6.0.3",
@@ -64,10 +67,11 @@
     "@semantic-release/github": "^11.0.3",
     "@semantic-release/npm": "^12.0.1",
     "@semantic-release/release-notes-generator": "^14.0.3",
+    "@jest/globals": "^30.0.2",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.3",
     "conventional-changelog-conventionalcommits": "^9.0.0",
-    "jest": "^30.0.1",
+    "jest": "^30.0.2",
     "semantic-release": "^24.2.5",
     "ts-jest": "^29.4.0",
     "tsx": "^4.20.3",