@mikkelscheike/email-provider-links 2.5.1 → 2.6.0

package/README.md

@@ -6,10 +6,11 @@ A TypeScript library providing direct links to **93 email providers** (178 domai
 
 ## ✨ Features
 
-- 🚀 **Fast & Lightweight**: Zero dependencies, minimal footprint
+- 🚀 **Fast & Lightweight**: Zero dependencies, ultra-low memory (~0.39MB initial, ~0.02MB per 1000 ops)
 - 📧 **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
+- 🌍 **IDN Support**: Full internationalized domain name (punycode) support with RFC compliance
+- ✅ **Email Validation**: International email validation following RFC 5321, 5322, and 6530 standards
 - 🏢 **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
@@ -28,15 +29,9 @@ Using npm:
 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
 
@@ -160,6 +155,39 @@ console.log('Max requests:', Config.MAX_DNS_REQUESTS_PER_MINUTE); // 10
 console.log('Default timeout:', Config.DEFAULT_DNS_TIMEOUT);       // 5000ms
 ```
 
+## Email Validation
+
+The library includes comprehensive email validation following international standards:
+
+```typescript
+import { validateInternationalEmail } from '@mikkelscheike/email-provider-links';
+
+// Validate any email address
+const result = validateInternationalEmail('user@example.com');
+
+// Returns undefined for valid emails
+console.log(result); // undefined
+
+// Returns detailed error information for invalid emails
+const invalid = validateInternationalEmail('user@münchen.com');
+if (invalid) {
+  console.log(invalid.code);    // IDN_VALIDATION_ERROR
+  console.log(invalid.message); // Human-readable error message
+}
+```
+
+### Validation Features
+
+- ✅ **RFC Compliance**: Follows RFC 5321, 5322, and 6530 standards
+- 🌍 **International Support**: Full IDN (Punycode) validation
+- 📝 **Detailed Errors**: Clear, translatable error messages
+- 🔍 **Comprehensive Checks**:
+  - Local part validation (username)
+  - Domain format validation
+  - IDN encoding validation
+  - Length limits (local part, domain, total)
+  - TLD validation
+
 ## Advanced Usage
 
 <details>
@@ -262,6 +290,12 @@ interface EmailProviderResult {
   loginUrl: string | null;
   detectionMethod?: 'domain_match' | 'mx_record' | 'txt_record' | 'proxy_detected';
   proxyService?: string;
+  error?: {
+    type: 'INVALID_EMAIL' | 'DNS_TIMEOUT' | 'RATE_LIMITED' | 'UNKNOWN_DOMAIN' | 
+          'NETWORK_ERROR' | 'IDN_VALIDATION_ERROR';
+    message: string;
+    idnError?: string;  // Specific IDN validation error message
+  };
 }
 
 interface ConfigConstants {
@@ -318,6 +352,24 @@ if (result.securityReport.securityLevel === 'CRITICAL') {
 }
 ```
 
+## Performance Benchmarks
+
+This package is designed to be extremely memory efficient and fast. We continuously monitor performance metrics through automated benchmarks that run on every PR and release.
+
+Latest benchmark results show:
+- Provider loading: ~0.39MB heap usage, <0.5ms
+- Email lookups: ~0.02MB heap usage per 100 operations
+- Concurrent DNS: ~0.03MB heap usage, ~110ms for 10 lookups
+- Large scale (1000 ops): ~0.02MB heap usage, <3ms total
+- Cache effectiveness: ~0.01MB impact on subsequent loads
+
+To run benchmarks locally:
+```bash
+npm run benchmark
+```
+
+Benchmarks are automatically run in CI to catch any performance regressions.
+
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on adding new email providers.

package/dist/api.d.ts

@@ -29,9 +29,10 @@ export interface EmailProviderResult {
     proxyService?: string;
     /** Error information if detection failed */
     error?: {
-        type: 'INVALID_EMAIL' | 'DNS_TIMEOUT' | 'RATE_LIMITED' | 'UNKNOWN_DOMAIN' | 'NETWORK_ERROR';
+        type: 'INVALID_EMAIL' | 'DNS_TIMEOUT' | 'RATE_LIMITED' | 'UNKNOWN_DOMAIN' | 'NETWORK_ERROR' | 'IDN_VALIDATION_ERROR';
         message: string;
         retryAfter?: number;
+        idnError?: string;
     };
 }
 /**

package/dist/concurrent-dns.d.ts

@@ -69,7 +69,7 @@ export interface ConcurrentDNSResult {
  */
 export declare class ConcurrentDNSDetector {
     private activeQueries;
-    cleanup(): void;
+    cleanup(): Promise<void>;
     private config;
     private providers;
     constructor(providers: EmailProvider[], config?: Partial<ConcurrentDNSConfig>);

package/dist/concurrent-dns.js

@@ -30,7 +30,13 @@ const DEFAULT_CONFIG = {
 class ConcurrentDNSDetector {
     // Cleanup method for tests
     cleanup() {
+        // Cancel any in-progress timeouts
+        const timeoutError = new Error('Operation cancelled by cleanup');
+        for (const { reject } of this.activeQueries) {
+            reject(timeoutError);
+        }
         this.activeQueries.clear();
+        return Promise.resolve();
     }
     constructor(providers, config = {}) {
         // Store active query states
@@ -384,13 +390,28 @@ class ConcurrentDNSDetector {
      * Wrap a promise with a timeout
      */
     withTimeout(promise, ms) {
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => reject(new Error(`DNS query timeout after ${ms}ms`)), ms);
+        let rejectFn;
+        const timeoutPromise = new Promise((resolve, reject) => {
+            rejectFn = reject;
+            const timeout = setTimeout(() => reject(new Error(`DNS query timeout after ${ms}ms`)), ms).unref();
             promise
                 .then(resolve)
                 .catch(reject)
-                .finally(() => clearTimeout(timeout));
+                .finally(() => {
+                clearTimeout(timeout);
+                // Clean up active query
+                const queryEntry = Array.from(this.activeQueries).find(entry => entry.promise === timeoutPromise);
+                if (queryEntry) {
+                    this.activeQueries.delete(queryEntry);
+                }
+            });
         });
+        // Only add to active queries if we have a reject function
+        if (rejectFn) {
+            const queryEntry = { promise: timeoutPromise, reject: rejectFn };
+            this.activeQueries.add(queryEntry);
+        }
+        return timeoutPromise;
     }
 }
 exports.ConcurrentDNSDetector = ConcurrentDNSDetector;

package/dist/{security/hash-verifier.js → 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': '92cc46fb47a1466bf3f448cd2f289d51e65daf7e7a93b389e956a49b6ffc4bbe'
+    'package.json': 'da14e15d9602b7e2cdf3d08f4756ca7ff9af842906e4de1af7664c1d1cce8e9e'
 };
 /**
  * Calculates SHA-256 hash of a file or string content
@@ -140,7 +140,7 @@ function generateSecurityHashes(basePath = __dirname) {
     const hashes = {};
     for (const file of files) {
         try {
-            const fullPath = (0, path_1.join)(basePath, '..', '..', file);
+            const fullPath = (0, path_1.join)(basePath, '..', file);
             const hash = calculateFileHash(fullPath);
             hashes[file.split('/').pop() || file] = hash;
             console.log(`✅ ${file}: ${hash}`);
@@ -231,7 +231,7 @@ function handleHashMismatch(result, options = {}) {
  * @returns Complete security audit result
  */
 function performSecurityAudit(providersFilePath) {
-    const filePath = providersFilePath || (0, path_1.join)(__dirname, '..', '..', 'providers', 'emailproviders.json');
+    const filePath = providersFilePath || (0, path_1.join)(__dirname, '..', 'providers', 'emailproviders.json');
     const hashResult = verifyProvidersIntegrity(filePath);
     const recommendations = [];
     let securityLevel = 'HIGH';

package/dist/idn.d.ts

@@ -14,3 +14,33 @@ export declare function domainToPunycode(domain: string): string;
  * @returns Email with Punycode encoded domain
  */
 export declare function emailToPunycode(email: string): string;
+/**
+ * Error codes for IDN validation
+ * These can be used as keys for translation systems
+ */
+export declare enum IDNValidationError {
+    MISSING_INPUT = "MISSING_INPUT",
+    EMAIL_TOO_LONG = "EMAIL_TOO_LONG",
+    MISSING_AT_SYMBOL = "MISSING_AT_SYMBOL",
+    LOCAL_PART_EMPTY = "LOCAL_PART_EMPTY",
+    LOCAL_PART_TOO_LONG = "LOCAL_PART_TOO_LONG",
+    LOCAL_PART_INVALID = "LOCAL_PART_INVALID",
+    DOMAIN_EMPTY = "DOMAIN_EMPTY",
+    DOMAIN_TOO_LONG = "DOMAIN_TOO_LONG",
+    DOMAIN_INVALID_FORMAT = "DOMAIN_INVALID_FORMAT",
+    MISSING_TLD = "MISSING_TLD",
+    NUMERIC_TLD = "NUMERIC_TLD",
+    INVALID_ENCODING = "INVALID_ENCODING"
+}
+/**
+ * Validates an email address according to international standards (IDNA)
+ * This implementation follows RFC 5321, 5322, and 6530 standards for email addresses
+ *
+ * @param email The email address to validate
+ * @returns Error information if validation fails, undefined if valid
+ */
+export declare function validateInternationalEmail(email: string): {
+    type: 'IDN_VALIDATION_ERROR';
+    code: IDNValidationError;
+    message: string;
+} | undefined;

package/dist/idn.js

@@ -4,8 +4,10 @@
  * Zero-dependency implementation for domain name handling
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDNValidationError = void 0;
 exports.domainToPunycode = domainToPunycode;
 exports.emailToPunycode = emailToPunycode;
+exports.validateInternationalEmail = validateInternationalEmail;
 const BASE = 36;
 const INITIAL_N = 128;
 const INITIAL_BIAS = 72;
@@ -101,3 +103,146 @@ function emailToPunycode(email) {
         return email;
     return `${local}@${domainToPunycode(domain)}`;
 }
+/**
+ * Error codes for IDN validation
+ * These can be used as keys for translation systems
+ */
+var IDNValidationError;
+(function (IDNValidationError) {
+    IDNValidationError["MISSING_INPUT"] = "MISSING_INPUT";
+    IDNValidationError["EMAIL_TOO_LONG"] = "EMAIL_TOO_LONG";
+    IDNValidationError["MISSING_AT_SYMBOL"] = "MISSING_AT_SYMBOL";
+    IDNValidationError["LOCAL_PART_EMPTY"] = "LOCAL_PART_EMPTY";
+    IDNValidationError["LOCAL_PART_TOO_LONG"] = "LOCAL_PART_TOO_LONG";
+    IDNValidationError["LOCAL_PART_INVALID"] = "LOCAL_PART_INVALID";
+    IDNValidationError["DOMAIN_EMPTY"] = "DOMAIN_EMPTY";
+    IDNValidationError["DOMAIN_TOO_LONG"] = "DOMAIN_TOO_LONG";
+    IDNValidationError["DOMAIN_INVALID_FORMAT"] = "DOMAIN_INVALID_FORMAT";
+    IDNValidationError["MISSING_TLD"] = "MISSING_TLD";
+    IDNValidationError["NUMERIC_TLD"] = "NUMERIC_TLD";
+    IDNValidationError["INVALID_ENCODING"] = "INVALID_ENCODING";
+})(IDNValidationError || (exports.IDNValidationError = IDNValidationError = {}));
+/**
+ * Validates an email address according to international standards (IDNA)
+ * This implementation follows RFC 5321, 5322, and 6530 standards for email addresses
+ *
+ * @param email The email address to validate
+ * @returns Error information if validation fails, undefined if valid
+ */
+function validateInternationalEmail(email) {
+    // Basic checks
+    if (!email || typeof email !== 'string') {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.MISSING_INPUT,
+            message: 'The email field cannot be empty'
+        };
+    }
+    // Split into local and domain parts
+    const atIndex = email.lastIndexOf('@');
+    if (atIndex === -1) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.MISSING_AT_SYMBOL,
+            message: 'The email address must contain an @ symbol'
+        };
+    }
+    const local = email.slice(0, atIndex);
+    const domain = email.slice(atIndex + 1);
+    // Check for max length - RFC 5321
+    if (email.length > 254) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.EMAIL_TOO_LONG,
+            message: 'The email address is too long'
+        };
+    }
+    // Validate domain part
+    if (domain.length === 0) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.DOMAIN_EMPTY,
+            message: 'The domain part of the email cannot be empty'
+        };
+    }
+    if (domain.length > 255) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.DOMAIN_TOO_LONG,
+            message: 'The domain part of the email is too long'
+        };
+    }
+    // Validate local part
+    if (local.length === 0) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.LOCAL_PART_EMPTY,
+            message: 'The username part of the email cannot be empty'
+        };
+    }
+    if (local.length > 64) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.LOCAL_PART_TOO_LONG,
+            message: 'The username part of the email is too long'
+        };
+    }
+    // Check local part characters
+    // Allows: letters, numbers, and !#$%&'*+-/=?^_`{|}~.
+    // Dot can't be first, last, or consecutive
+    if (!/^[a-zA-Z0-9!#$%&'*+\-/=?^_`{|}~]([a-zA-Z0-9!#$%&'*+\-/=?^_`{|}~.]*[a-zA-Z0-9!#$%&'*+\-/=?^_`{|}~])?$/.test(local) || local.includes('..')) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.LOCAL_PART_INVALID,
+            message: 'The username contains invalid characters or dots in wrong places'
+        };
+    }
+    // Check domain format (including IDN domains)
+    try {
+        // Check for lone surrogates and control characters
+        if (/[\uD800-\uDFFF]/.test(domain)) {
+            return {
+                type: 'IDN_VALIDATION_ERROR',
+                code: IDNValidationError.INVALID_ENCODING,
+                message: 'The domain contains invalid characters or encoding'
+            };
+        }
+        // Convert to punycode to handle IDN
+        const punycodeDomain = domainToPunycode(domain);
+        // Check basic domain format
+        // Allows: letters, numbers, hyphens (not first/last), dots separating labels
+        if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$/.test(punycodeDomain)) {
+            return {
+                type: 'IDN_VALIDATION_ERROR',
+                code: IDNValidationError.DOMAIN_INVALID_FORMAT,
+                message: 'The domain format is invalid'
+            };
+        }
+        // Check if domain has at least one dot (TLD required)
+        if (!punycodeDomain.includes('.')) {
+            return {
+                type: 'IDN_VALIDATION_ERROR',
+                code: IDNValidationError.MISSING_TLD,
+                message: 'The email domain must include a top-level domain (like .com or .org)'
+            };
+        }
+        // Check TLD is not all-numeric
+        const tld = punycodeDomain.split('.').pop();
+        if (/^[0-9]+$/.test(tld)) {
+            return {
+                type: 'IDN_VALIDATION_ERROR',
+                code: IDNValidationError.NUMERIC_TLD,
+                message: 'The top-level domain cannot be all numbers'
+            };
+        }
+    }
+    catch (error) {
+        return {
+            type: 'IDN_VALIDATION_ERROR',
+            code: IDNValidationError.INVALID_ENCODING,
+            message: 'The domain contains invalid characters or encoding'
+        };
+    }
+    // If we get here, the email is valid
+    return undefined;
+}

package/dist/{security/secure-loader.d.ts → secure-loader.d.ts}

@@ -4,7 +4,7 @@
  * Integrates URL validation and hash verification to create a secure
  * loading system for email provider data.
  */
-import type { EmailProvider } from '../index';
+import type { EmailProvider } from './index';
 export interface SecureLoadResult {
     success: boolean;
     providers: EmailProvider[];

package/dist/{security/secure-loader.js → secure-loader.js}

@@ -21,7 +21,7 @@ const hash_verifier_1 = require("./hash-verifier");
  * @returns Secure load result with validation details
  */
 function secureLoadProviders(providersPath, expectedHash) {
-    const filePath = providersPath || (0, path_1.join)(__dirname, '..', '..', 'providers', 'emailproviders.json');
+    const filePath = providersPath || (0, path_1.join)(__dirname, '..', 'providers', 'emailproviders.json');
     const issues = [];
     let providers = [];
     // Step 1: Hash verification

package/dist/{security/url-validator.js → url-validator.js}

@@ -134,7 +134,7 @@ const URL_SHORTENERS = [
     'is.gd',
     'buff.ly'
 ];
-const idn_1 = require("../idn");
+const idn_1 = require("./idn");
 /**
  * Validates if a URL is safe for email provider redirects
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikkelscheike/email-provider-links",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "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",
@@ -8,8 +8,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "providers/emailproviders.json",
-    "!dist/**/*.map",
-    "!dist/**/security-demo.*"
+    "!dist/**/*.map"
   ],
   "scripts": {
     "build": "tsc",
@@ -24,7 +23,8 @@
     "update-hashes": "tsx scripts/update-hashes.ts",
     "release:major": "tsx scripts/prepare-release.ts",
     "release:minor": "tsx scripts/prepare-release.ts",
-    "release:patch": "tsx scripts/prepare-release.ts"
+    "release:patch": "tsx scripts/prepare-release.ts",
+    "benchmark": "tsx --expose-gc benchmark/memory.ts"
   },
   "keywords": [
     "email",
@@ -61,13 +61,13 @@
     "access": "public"
   },
   "devDependencies": {
+    "@jest/globals": "^30.0.2",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@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",

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

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

package/dist/__tests__/basic.test.js

@@ -1,8 +0,0 @@
-"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);
-    });
-});