@nauth-toolkit/core 0.1.0

package/src/services/geo-location.service.ts

@@ -0,0 +1,599 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { GeoLocationConfig, NAuthConfig } from '../interfaces/config.interface';
+import { StorageAdapter } from '../interfaces/storage-adapter.interface';
+import { NAuthLogger } from '../utils/nauth-logger';
+import { NAuthException } from '../exceptions/nauth.exception';
+import { AuthErrorCode } from '../enums/error-codes.enum';
+import { isPrivateIp } from '../utils/ip-extractor';
+
+// ============================================================================
+// Optional MaxMind Types
+// ============================================================================
+
+/**
+ * MaxMind GeoIP2 Reader type (optional dependency)
+ * Only available if @maxmind/geoip2-node is installed
+ *
+ * The Reader class has city() and country() methods that return response objects
+ */
+type MaxMindReader = {
+  city: (ip: string) => {
+    country?: { isoCode?: string; names?: { en?: string }; isInEuropeanUnion?: boolean };
+    city?: { names?: { en?: string } };
+    subdivisions?: Array<{ names?: { en?: string } }>;
+    postal?: { code?: string };
+    location?: { latitude?: number; longitude?: number; timeZone?: string };
+    continent?: { code?: string; names?: { en?: string } };
+  };
+  country: (ip: string) => {
+    country?: { isoCode?: string; names?: { en?: string }; isInEuropeanUnion?: boolean };
+    continent?: { code?: string; names?: { en?: string } };
+  };
+};
+
+/**
+ * MaxMind library module type (optional peer dependency)
+ * Injected via dependency injection if package is installed
+ */
+type MaxMindModule = {
+  Reader: {
+    open: (dbPath: string) => Promise<MaxMindReader>;
+  };
+};
+
+/**
+ * GeoLocation Service
+ *
+ * Provides IP geolocation using MaxMind GeoIP2 database files.
+ * Platform-agnostic - works on all platforms where Node.js runs.
+ *
+ * Features:
+ * - IP to country/city lookup from MaxMind .mmdb files
+ * - Distributed locking for database updates (multi-server safe)
+ * - Configurable database path (defaults to system temp directory)
+ * - Graceful degradation if MaxMind not installed
+ *
+ * Requirements:
+ * - @maxmind/geoip2-node peer dependency must be installed
+ * - MaxMind license key and account ID for database downloads
+ * - Storage adapter (for distributed locking)
+ *
+ * @example
+ * ```typescript
+ * // Get geolocation for an IP
+ * const geo = await geoLocationService.getIpGeolocation('8.8.8.8');
+ * console.log(geo.country); // 'US'
+ * console.log(geo.city); // 'Mountain View'
+ * ```
+ */
+export class GeoLocationService {
+  private readonly config: GeoLocationConfig['maxMind'];
+  private readonly dbPath: string;
+  private readonly maxMindLib: MaxMindModule | null;
+  private cityReader: MaxMindReader | null = null;
+  private countryReader: MaxMindReader | null = null;
+  private readonly defaultEditions = ['GeoLite2-City', 'GeoLite2-Country'];
+  private readonly lockKey = 'maxmind-db-update-lock';
+  private readonly lockTtlSeconds = 300; // 5 minutes
+
+  constructor(
+    nauthConfig: NAuthConfig,
+    private readonly storageAdapter: StorageAdapter,
+    maxMindLib?: MaxMindModule | null,
+    private readonly logger?: NAuthLogger,
+  ) {
+    // ============================================================================
+    // Extract Configuration
+    // ============================================================================
+    this.config = nauthConfig.geoLocation?.maxMind;
+
+    // ============================================================================
+    // Initialize MaxMind Library (Optional)
+    // ============================================================================
+    this.maxMindLib = maxMindLib ?? null;
+
+    if (!this.maxMindLib && this.config) {
+      this.logger?.warn?.(
+        'MaxMind GeoIP2 is configured but @maxmind/geoip2-node package is not installed. ' +
+          'Install it with: yarn add @maxmind/geoip2-node\n' +
+          'Or remove geoLocation.maxMind from your configuration to disable geolocation.',
+      );
+    }
+
+    // ============================================================================
+    // Resolve Database Path
+    // ============================================================================
+    if (this.config?.dbPath) {
+      // Use configured path (absolute or relative to cwd)
+      this.dbPath = path.isAbsolute(this.config.dbPath)
+        ? this.config.dbPath
+        : path.resolve(process.cwd(), this.config.dbPath);
+    } else {
+      // Default to system temp directory
+      const systemTemp = os.tmpdir();
+      this.dbPath = path.join(systemTemp, 'nauth_maxmind');
+    }
+  }
+
+  /**
+   * Initialize service on module startup
+   *
+   * - Loads database files if they exist
+   * - Optionally downloads databases if autoDownloadOnStartup is enabled
+   */
+  async onModuleInit(): Promise<void> {
+    if (!this.config) {
+      // No config provided - service disabled
+      return;
+    }
+
+    if (!this.maxMindLib) {
+      // MaxMind not installed - service disabled
+      this.logger?.warn?.('MaxMind GeoIP2 library not available. Install @maxmind/geoip2-node to enable geolocation.');
+      return;
+    }
+
+    // Ensure database directory exists
+    await this.ensureDbDirectoryExists();
+
+    // Load existing database files
+    await this.loadDatabaseFiles();
+
+    // Auto-download if enabled and files don't exist (only if downloads not skipped)
+    if (!this.config.skipDownloads && this.config.autoDownloadOnStartup && (!this.cityReader || !this.countryReader)) {
+      try {
+        await this.updateGeoLocationDatabase();
+      } catch (error) {
+        this.logger?.warn?.(
+          `Failed to auto-download MaxMind databases on startup: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Get geolocation information for an IP address
+   *
+   * @param ip - IP address to lookup
+   * @returns Geolocation info with country, city, and coordinates (if available)
+   *
+   * @example
+   * ```typescript
+   * const geo = await geoLocationService.getIpGeolocation('8.8.8.8');
+   * // { country: 'US', city: 'Mountain View', latitude: 37.386, longitude: -122.0838 }
+   * ```
+   */
+  async getIpGeolocation(ip: string): Promise<{ 
+    country?: string; 
+    city?: string; 
+    latitude?: number; 
+    longitude?: number 
+  }> {
+    // ============================================================================
+    // Check if Service is Available
+    // ============================================================================
+    if (!this.config || !this.maxMindLib) {
+      // Service not configured or MaxMind not installed
+      return {};
+    }
+
+    // ============================================================================
+    // Skip Private IP Addresses
+    // ============================================================================
+    // MaxMind databases only contain public IP addresses. Private IPs (localhost,
+    // 192.168.x.x, 10.x.x.x, etc.) will always fail lookup and generate unnecessary
+    // error logs. Skip the lookup entirely for private IPs.
+    if (isPrivateIp(ip)) {
+      // Silently return empty result for private IPs (no lookup attempted)
+      this.logger?.debug?.(`Skipping private IP ${ip} for geolocation lookup`);
+      return {};
+    }
+
+    // ============================================================================
+    // Try City Database First (More Detailed)
+    // ============================================================================
+    if (this.cityReader) {
+      try {
+        const result = this.cityReader.city(ip);
+        const geoData = {
+          country: result.country?.isoCode,
+          city: result.city?.names?.en,
+          latitude: result.location?.latitude,
+          longitude: result.location?.longitude,
+        };
+        
+        // Warn if coordinates are missing (useful for production debugging)
+        if (!geoData.latitude || !geoData.longitude) {
+          this.logger?.warn?.(
+            `MaxMind city lookup for IP ${ip} returned city/country but NO coordinates: ` +
+            `city=${geoData.city}, country=${geoData.country}`,
+          );
+        }
+        
+        return geoData;
+      } catch (error) {
+        // Non-fatal: Try country database (error logged at warn level if needed)
+      }
+    } else {
+      this.logger?.warn?.(
+        `MaxMind cityReader is not initialized for IP ${ip}. ` +
+        `Only country database available (no coordinates).`,
+      );
+    }
+
+    // ============================================================================
+    // Fallback to Country Database
+    // ============================================================================
+    if (this.countryReader) {
+      try {
+        const result = this.countryReader.country(ip);
+        return {
+          country: result.country?.isoCode,
+        };
+      } catch (error) {
+        // Non-fatal: Return empty result (error handled gracefully)
+      }
+    }
+
+    // No databases loaded or lookup failed
+    return {};
+  }
+
+  /**
+   * Update MaxMind GeoIP2 database files
+   *
+   * Downloads the latest database files from MaxMind using distributed locking
+   * to prevent concurrent downloads in multi-server deployments.
+   *
+   * Uses storage adapter for distributed locking:
+   * - Lock key: 'maxmind-db-update-lock'
+   * - Lock TTL: 5 minutes (300 seconds)
+   * - Only one server/process can download at a time
+   *
+   * @throws {NAuthException} If MaxMind credentials are missing or download fails
+   *
+   * @example
+   * ```typescript
+   * // Call this method via cron job for periodic updates
+   * await geoLocationService.updateGeoLocationDatabase();
+   * ```
+   */
+  async updateGeoLocationDatabase(): Promise<void> {
+    // ============================================================================
+    // Validate Configuration
+    // ============================================================================
+    if (!this.config) {
+      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'MaxMind configuration not provided');
+    }
+
+    if (!this.maxMindLib) {
+      throw new NAuthException(
+        AuthErrorCode.VALIDATION_FAILED,
+        'MaxMind library not available. Install @maxmind/geoip2-node peer dependency.',
+      );
+    }
+
+    if (this.config.skipDownloads) {
+      throw new NAuthException(
+        AuthErrorCode.VALIDATION_FAILED,
+        'Database downloads are disabled (skipDownloads: true). Use existing files or disable skipDownloads to enable downloads.',
+      );
+    }
+
+    if (!this.config.licenseKey || !this.config.accountId) {
+      throw new NAuthException(
+        AuthErrorCode.VALIDATION_FAILED,
+        'MaxMind licenseKey and accountId are required for database downloads',
+      );
+    }
+
+    // ============================================================================
+    // Acquire Distributed Lock (if using distributed storage)
+    // ============================================================================
+    // Memory storage: Lock works within single process (fine for single-server deployments)
+    // Redis/Database storage: Lock works across multiple servers (prevents concurrent downloads)
+    const lockAcquired = await this.storageAdapter.set(this.lockKey, `lock-${Date.now()}`, this.lockTtlSeconds, {
+      nx: true,
+    });
+
+    if (!lockAcquired) {
+      // Another process/server is already updating
+      this.logger?.warn?.('MaxMind database update already in progress, skipping...');
+      return;
+    }
+
+    try {
+      // ============================================================================
+      // Download and Update Databases
+      // ============================================================================
+      const editions = this.config.editions || this.defaultEditions;
+      const accountId = this.config.accountId;
+      const licenseKey = this.config.licenseKey;
+
+      let successCount = 0;
+      let failureCount = 0;
+
+      for (const edition of editions) {
+        try {
+          await this.downloadDatabase(edition, accountId, licenseKey);
+          successCount++;
+        } catch (error) {
+          failureCount++;
+          this.logger?.error?.(
+            `Failed to download MaxMind database ${edition}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          );
+          // Continue with other editions even if one fails
+        }
+      }
+
+      // ============================================================================
+      // Reload Database Files
+      // ============================================================================
+      await this.loadDatabaseFiles();
+
+      // Only log success if at least one database was downloaded
+      if (successCount > 0) {
+        this.logger?.log?.(`MaxMind database update completed: ${successCount} succeeded, ${failureCount} failed`);
+      } else if (failureCount > 0) {
+        this.logger?.warn?.(
+          `MaxMind database update failed: All ${failureCount} database(s) failed to download. See error messages above.`,
+        );
+      }
+    } finally {
+      // ============================================================================
+      // Release Lock
+      // ============================================================================
+      try {
+        await this.storageAdapter.del(this.lockKey);
+      } catch (error) {
+        // Non-fatal: Lock will expire automatically after TTL
+        this.logger?.warn?.(
+          `Failed to release MaxMind update lock: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+  }
+
+  // ============================================================================
+  // Private Helper Methods
+  // ============================================================================
+
+  /**
+   * Ensure database directory exists
+   *
+   * Creates the directory if it doesn't exist.
+   */
+  private async ensureDbDirectoryExists(): Promise<void> {
+    try {
+      await fs.mkdir(this.dbPath, { recursive: true });
+      this.logger?.debug?.(`MaxMind database directory: ${this.dbPath}`);
+    } catch (error) {
+      throw new NAuthException(
+        AuthErrorCode.INTERNAL_ERROR,
+        `Failed to create MaxMind database directory at ${this.dbPath}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  /**
+   * Load database files from disk
+   *
+   * Loads .mmdb files for City and Country databases if they exist.
+   */
+  private async loadDatabaseFiles(): Promise<void> {
+    if (!this.maxMindLib) {
+      return;
+    }
+
+    try {
+      // Try to load City database
+      const cityDbPath = path.join(this.dbPath, 'GeoLite2-City.mmdb');
+      try {
+        // Reader.open returns a Reader instance with city()/country() methods
+        this.cityReader = await this.maxMindLib.Reader.open(cityDbPath);
+        if (typeof this.cityReader.city !== 'function') {
+          this.logger?.warn?.('MaxMind Reader instance does not have city() method');
+          this.cityReader = null;
+        } else {
+          this.logger?.debug?.('Loaded GeoLite2-City database');
+        }
+      } catch (error) {
+        // City database not found or failed to load
+        this.logger?.debug?.(
+          `Failed to load City database: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+        this.cityReader = null;
+      }
+
+      // Try to load Country database
+      const countryDbPath = path.join(this.dbPath, 'GeoLite2-Country.mmdb');
+      try {
+        this.countryReader = await this.maxMindLib.Reader.open(countryDbPath);
+        if (typeof this.countryReader.country !== 'function') {
+          this.logger?.warn?.('MaxMind Reader instance does not have country() method');
+          this.countryReader = null;
+        } else {
+          this.logger?.debug?.('Loaded GeoLite2-Country database');
+        }
+      } catch (error) {
+        // Country database not found or failed to load
+        this.logger?.debug?.(
+          `Failed to load Country database: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+        this.countryReader = null;
+      }
+
+      if (!this.cityReader && !this.countryReader) {
+        if (this.config?.skipDownloads) {
+          this.logger?.warn?.(
+            `No MaxMind database files found in ${this.dbPath}. ` +
+              `Downloads are disabled (skipDownloads: true). ` +
+              `Ensure database files are available in the configured path, or set skipDownloads: false to enable downloads.`,
+          );
+        } else {
+          this.logger?.warn?.(
+            `No MaxMind database files found in ${this.dbPath}. ` +
+              `Files will be downloaded when updateGeoLocationDatabase() is called or autoDownloadOnStartup is enabled.`,
+          );
+        }
+      } else {
+        // Log which databases were loaded
+        const loaded = [];
+        if (this.cityReader) loaded.push('GeoLite2-City');
+        if (this.countryReader) loaded.push('GeoLite2-Country');
+        this.logger?.debug?.(`Loaded MaxMind databases: ${loaded.join(', ')}`);
+      }
+    } catch (error) {
+      this.logger?.warn?.(
+        `Failed to load MaxMind database files: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  /**
+   * Download a MaxMind database file
+   *
+   * Downloads the specified edition from MaxMind's download API,
+   * extracts the .mmdb file from the tar.gz archive, and saves it.
+   *
+   * Uses Node.js built-in zlib for gzip decompression and implements
+   * basic tar parsing to extract the .mmdb file.
+   *
+   * @param edition - Edition name (e.g., 'GeoLite2-City')
+   * @param accountId - MaxMind account ID
+   * @param licenseKey - MaxMind license key
+   */
+  private async downloadDatabase(edition: string, _accountId: number, licenseKey: string): Promise<void> {
+    // MaxMind Download API URL
+    const url = `https://download.maxmind.com/app/geoip_download?edition_id=${edition}&license_key=${licenseKey}&suffix=tar.gz`;
+    const tempTarPath = path.join(this.dbPath, `${edition}.tar.gz`);
+    const outputPath = path.join(this.dbPath, `${edition}.mmdb`);
+
+    try {
+      // ============================================================================
+      // Download tar.gz file
+      // ============================================================================
+      this.logger?.debug?.(`Downloading MaxMind database ${edition}...`);
+
+      // Wrap fetch in timeout and better error handling
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          // Add timeout to prevent hanging requests
+          signal: AbortSignal.timeout(30000), // 30 second timeout
+        });
+      } catch (fetchError: any) {
+        // Handle network errors (DNS failures, connection errors, etc.)
+        if (
+          fetchError?.code === 'ENOTFOUND' ||
+          fetchError?.code === 'ECONNREFUSED' ||
+          fetchError?.name === 'AbortError'
+        ) {
+          throw new NAuthException(
+            AuthErrorCode.INTERNAL_ERROR,
+            `Network error while downloading MaxMind database ${edition}: ${fetchError.message || 'DNS lookup failed or connection refused'}. Check your network connection and proxy settings.`,
+          );
+        }
+        throw fetchError;
+      }
+
+      if (!response.ok) {
+        throw new Error(`MaxMind API returned ${response.status}: ${response.statusText}`);
+      }
+
+      const buffer = Buffer.from(await response.arrayBuffer());
+      await fs.writeFile(tempTarPath, buffer);
+
+      // ============================================================================
+      // Extract .mmdb file from tar.gz
+      // ============================================================================
+      // MaxMind tar.gz contains: <edition>_<date>/<edition>.mmdb
+      // We need to decompress gzip, then parse tar to find the .mmdb file
+      await this.extractTarGz(tempTarPath, outputPath, edition);
+
+      // Clean up temp tar.gz file
+      await fs.unlink(tempTarPath).catch(() => {
+        // Ignore cleanup errors
+      });
+
+      this.logger?.debug?.(`Successfully downloaded and extracted ${edition}`);
+    } catch (error) {
+      // Clean up temp file on error
+      await fs.unlink(tempTarPath).catch(() => {
+        // Ignore cleanup errors
+      });
+
+      if (error instanceof NAuthException) {
+        throw error;
+      }
+
+      throw new NAuthException(
+        AuthErrorCode.INTERNAL_ERROR,
+        `Failed to download MaxMind database ${edition}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  /**
+   * Extract .mmdb file from tar.gz archive
+   *
+   * Uses Node.js built-in zlib for gzip decompression and implements
+   * basic tar parsing to find and extract the .mmdb file.
+   *
+   * @param tarGzPath - Path to the .tar.gz file
+   * @param outputPath - Path where .mmdb file should be saved
+   * @param edition - Edition name (to find correct file in archive)
+   */
+  private async extractTarGz(tarGzPath: string, outputPath: string, edition: string): Promise<void> {
+    // Prefer OS tar (no extra deps) per project guidance
+    const { exec } = await import('child_process');
+    const { promisify } = await import('util');
+    const execAsync = promisify(exec);
+
+    // Use a dedicated extraction directory to avoid polluting dbPath
+    const extractDir = path.join(this.dbPath, `extract_${edition}_${Date.now()}`);
+    await fs.mkdir(extractDir, { recursive: true });
+
+    try {
+      // Extract archive
+      await execAsync(`tar -xzf "${tarGzPath}" -C "${extractDir}"`);
+
+      // Find the .mmdb file (usually in a subdirectory like GeoLite2-City_YYYYMMDD/GeoLite2-City.mmdb)
+      const entries = await fs.readdir(extractDir);
+      let mmdbPath: string | null = null;
+      for (const entry of entries) {
+        const entryPath = path.join(extractDir, entry);
+        const stat = await fs.stat(entryPath);
+        if (stat.isDirectory()) {
+          const inner = await fs.readdir(entryPath);
+          for (const f of inner) {
+            if (f.endsWith('.mmdb') && f.includes(edition)) {
+              mmdbPath = path.join(entryPath, f);
+              break;
+            }
+          }
+        } else if (entry.endsWith('.mmdb') && entry.includes(edition)) {
+          mmdbPath = entryPath;
+        }
+        if (mmdbPath) break;
+      }
+
+      if (!mmdbPath) {
+        throw new Error(`Could not find extracted .mmdb file for ${edition}`);
+      }
+
+      // Move to final location
+      await fs.rename(mmdbPath, outputPath);
+    } finally {
+      // Cleanup extraction directory
+      try {
+        // Best-effort cleanup
+        await execAsync(`rm -rf "${extractDir}"`).catch(() => undefined);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,13 @@
+export * from './password.service';
+export * from './jwt.service';
+export * from './session.service';
+export * from './auth.service';
+export * from './email-verification.service';
+export * from './client-info.service';
+export * from './challenge.service';
+export * from './auth-challenge-helper.service';
+export * from './mfa-base.service';
+export * from './mfa.service';
+export * from './risk-detection.service';
+export * from './risk-scoring.service';
+export * from './adaptive-mfa-decision.service';