@bernierllc/email-domain-verification 1.0.0

package/src/EmailDomainVerificationService.ts

@@ -0,0 +1,992 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { Logger, LogLevel, ConsoleTransport } from '@bernierllc/logger';
+import { generateUUIDKey } from '@bernierllc/crypto-utils';
+import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';
+import { Resolver } from 'dns2';
+import axios, { AxiosInstance } from 'axios';
+import { CronJob } from 'cron';
+import { generateKeyPairSync } from 'crypto';
+import {
+  DomainConfig,
+  DomainVerificationResult,
+  DNSPropagationResult,
+  DomainHealthStatus,
+  VerificationHistoryEntry,
+  DNSRecord,
+  DKIMConfig,
+  VerificationStatus,
+  EmailProvider
+} from './types';
+import { InvalidDomainError } from './errors';
+
+/**
+ * Email Domain Verification Service
+ *
+ * Manages domain verification for email service providers including
+ * DNS record generation, propagation monitoring, and health checks.
+ */
+export class EmailDomainVerificationService {
+  private logger: Logger;
+  private neverhub?: NeverHubAdapter;
+  private httpClient: AxiosInstance;
+  private healthCheckJobs: Map<string, CronJob>;
+  private verificationHistory: Map<string, VerificationHistoryEntry[]>;
+
+  constructor(config?: {
+    logger?: Logger;
+    neverhub?: NeverHubAdapter;
+    healthCheckInterval?: string; // Cron expression
+  }) {
+    this.logger = config?.logger || new Logger({
+      level: LogLevel.INFO,
+      transports: [new ConsoleTransport({ level: LogLevel.INFO })]
+    });
+    this.neverhub = config?.neverhub;
+    this.httpClient = axios.create({
+      timeout: 30000,
+      headers: { 'User-Agent': '@bernierllc/email-domain-verification/1.0.0' }
+    });
+    this.healthCheckJobs = new Map();
+    this.verificationHistory = new Map();
+  }
+
+  /**
+   * Initialize service with NeverHub registration
+   */
+  async initialize(): Promise<void> {
+    if (await NeverHubAdapter.detect()) {
+      this.neverhub = new NeverHubAdapter();
+      await this.registerWithNeverHub();
+    }
+
+    this.logger.info('Email Domain Verification Service initialized', {
+      neverhubEnabled: !!this.neverhub
+    });
+  }
+
+  /**
+   * Setup domain verification for a provider
+   *
+   * @param config - Domain configuration
+   * @returns Verification result with DNS records to configure
+   */
+  async setupDomain(config: DomainConfig): Promise<DomainVerificationResult> {
+    this.logger.info('Setting up domain verification', {
+      domain: config.domain,
+      provider: config.provider
+    });
+
+    try {
+      // Validate domain
+      this.validateDomain(config.domain);
+
+      // Generate DNS records based on provider and configuration
+      const dnsRecords = await this.generateDNSRecords(config);
+
+      // Generate DKIM keypair if enabled
+      let dkimConfig: DKIMConfig | undefined;
+      if (config.dkim.enabled) {
+        dkimConfig = await this.generateDKIMConfig(config);
+        dnsRecords.push(dkimConfig.dnsRecord);
+      }
+
+      // Register domain with provider
+      const providerData = await this.registerWithProvider(config, dkimConfig);
+
+      // Record verification initiation
+      this.addHistoryEntry(config.domain, {
+        eventType: 'initiated',
+        details: `Domain verification initiated for ${config.provider}`,
+        newStatus: 'pending'
+      });
+
+      // Publish event
+      await this.publishEvent('domain.verification.initiated', {
+        domain: config.domain,
+        provider: config.provider,
+        recordCount: dnsRecords.length
+      });
+
+      return {
+        success: true,
+        domain: config.domain,
+        status: 'pending',
+        dnsRecords,
+        dkimConfig,
+        providerData,
+        estimatedPropagationTime: 3600, // 1 hour typical
+        nextSteps: [
+          'Add the DNS records to your domain registrar',
+          'Wait for DNS propagation (typically 1-24 hours)',
+          'Use checkPropagation() to monitor DNS propagation status',
+          'Use verifyDomain() to complete verification with provider'
+        ]
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Domain setup failed for ${config.domain}: ${errorMessage}`);
+
+      return {
+        success: false,
+        domain: config.domain,
+        status: 'failed',
+        dnsRecords: [],
+        errors: [error instanceof Error ? error.message : 'Unknown error']
+      };
+    }
+  }
+
+  /**
+   * Check DNS propagation status for domain records
+   *
+   * @param domain - Domain name
+   * @param records - DNS records to check
+   * @returns Propagation results for each record
+   */
+  async checkPropagation(
+    domain: string,
+    records: DNSRecord[]
+  ): Promise<DNSPropagationResult[]> {
+    this.logger.info('Checking DNS propagation', {
+      domain,
+      recordCount: records.length
+    });
+
+    const results: DNSPropagationResult[] = [];
+
+    for (const record of records) {
+      try {
+        const result = await this.checkRecordPropagation(domain, record);
+        results.push(result);
+
+        if (result.propagated && result.valuesMatch) {
+          this.logger.info('DNS record propagated successfully', {
+            domain,
+            type: record.type,
+            host: record.host
+          });
+        } else {
+          this.logger.warn('DNS record not yet propagated', {
+            domain,
+            type: record.type,
+            host: record.host,
+            propagationPercentage: result.propagationPercentage
+          });
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Propagation check failed for ${domain} ${record.type}: ${errorMessage}`);
+
+        results.push({
+          domain,
+          record,
+          propagated: false,
+          nameservers: [],
+          propagationPercentage: 0,
+          expectedValue: record.value,
+          valuesMatch: false,
+          errors: [error instanceof Error ? error.message : 'Unknown error']
+        });
+      }
+    }
+
+    // Publish propagation status event
+    const overallPropagation = results.reduce((acc, r) => acc + r.propagationPercentage, 0) / results.length;
+    await this.publishEvent('domain.propagation.checked', {
+      domain,
+      propagationPercentage: overallPropagation,
+      recordCount: records.length,
+      propagatedCount: results.filter(r => r.propagated).length
+    });
+
+    return results;
+  }
+
+  /**
+   * Verify domain with email provider
+   *
+   * @param domain - Domain name
+   * @param provider - Email provider
+   * @param providerCredentials - Provider API credentials
+   * @returns Verification result
+   */
+  async verifyDomain(
+    domain: string,
+    provider: EmailProvider,
+    providerCredentials: Record<string, unknown>
+  ): Promise<DomainVerificationResult> {
+    this.logger.info('Verifying domain with provider', { domain, provider });
+
+    try {
+      const providerData = await this.verifyWithProvider(domain, provider, providerCredentials);
+
+      const status: VerificationStatus = providerData.verified ? 'verified' : 'failed';
+      const detailsMessage = typeof providerData.message === 'string' ? providerData.message : 'Verification completed';
+
+      this.addHistoryEntry(domain, {
+        eventType: status === 'verified' ? 'verified' : 'failed',
+        details: detailsMessage,
+        newStatus: status,
+        previousStatus: 'propagating'
+      });
+
+      await this.publishEvent('domain.verification.completed', {
+        domain,
+        provider,
+        status,
+        success: status === 'verified'
+      });
+
+      // Start health monitoring if verified
+      if (status === 'verified') {
+        this.startHealthMonitoring(domain, provider, providerCredentials);
+      }
+
+      const errorMessage = typeof providerData.message === 'string' ? providerData.message : 'Verification failed';
+      return {
+        success: status === 'verified',
+        domain,
+        status,
+        dnsRecords: [],
+        providerData,
+        errors: status === 'failed' ? [errorMessage] : undefined
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Domain verification failed for ${domain} with ${provider}: ${errMsg}`);
+
+      return {
+        success: false,
+        domain,
+        status: 'failed',
+        dnsRecords: [],
+        errors: [error instanceof Error ? error.message : 'Unknown error']
+      };
+    }
+  }
+
+  /**
+   * Get domain health status
+   *
+   * @param domain - Domain name
+   * @returns Health status
+   */
+  async getDomainHealth(domain: string): Promise<DomainHealthStatus> {
+    this.logger.info('Checking domain health', { domain });
+
+    // Implementation would check DNS records, provider status, etc.
+    // Returning basic structure for type safety
+    return {
+      domain,
+      healthy: true,
+      verificationStatus: 'verified',
+      lastChecked: new Date(),
+      records: []
+    };
+  }
+
+  /**
+   * Get verification history for domain
+   *
+   * @param domain - Domain name
+   * @param limit - Maximum number of entries to return
+   * @returns History entries
+   */
+  getVerificationHistory(domain: string, limit = 50): VerificationHistoryEntry[] {
+    const history = this.verificationHistory.get(domain) || [];
+    return history.slice(-limit);
+  }
+
+  /**
+   * Start automated health monitoring for domain
+   *
+   * @param domain - Domain name
+   * @param provider - Email provider
+   * @param credentials - Provider credentials
+   */
+  private startHealthMonitoring(
+    domain: string,
+    provider: EmailProvider,
+    credentials: Record<string, unknown>
+  ): void {
+    // Stop existing job if any
+    this.stopHealthMonitoring(domain);
+
+    // Create new cron job (runs every 6 hours)
+    const job = new CronJob('0 */6 * * *', async () => {
+      try {
+        const health = await this.performHealthCheck(domain, provider, credentials);
+
+        if (!health.healthy) {
+          this.logger.warn('Domain health check failed', { domain, warnings: health.warnings });
+
+          await this.publishEvent('domain.health.unhealthy', {
+            domain,
+            provider,
+            warnings: health.warnings
+          });
+        }
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Health check failed for ${domain}: ${errMsg}`);
+      }
+    });
+
+    job.start();
+    this.healthCheckJobs.set(domain, job);
+
+    this.logger.info('Health monitoring started', { domain });
+  }
+
+  /**
+   * Stop health monitoring for domain
+   *
+   * @param domain - Domain name
+   */
+  stopHealthMonitoring(domain: string): void {
+    const job = this.healthCheckJobs.get(domain);
+    if (job) {
+      job.stop();
+      this.healthCheckJobs.delete(domain);
+      this.logger.info('Health monitoring stopped', { domain });
+    }
+  }
+
+  /**
+   * Perform health check for domain
+   *
+   * @param domain - Domain name
+   * @param provider - Email provider
+   * @param credentials - Provider credentials
+   * @returns Health status
+   */
+  private async performHealthCheck(
+    domain: string,
+    _provider: EmailProvider,
+    _credentials: Record<string, unknown>
+  ): Promise<DomainHealthStatus> {
+    // Implementation would check DNS records, provider API status, etc.
+    // Returning basic structure for type safety
+    return {
+      domain,
+      healthy: true,
+      verificationStatus: 'verified',
+      lastChecked: new Date(),
+      records: []
+    };
+  }
+
+  /**
+   * Generate DNS records for domain configuration
+   */
+  private async generateDNSRecords(config: DomainConfig): Promise<DNSRecord[]> {
+    const records: DNSRecord[] = [];
+
+    // Generate SPF record
+    if (config.spf.enabled) {
+      records.push(this.generateSPFRecord(config));
+    }
+
+    // Generate DMARC record
+    if (config.dmarc.enabled) {
+      records.push(this.generateDMARCRecord(config));
+    }
+
+    // Generate provider-specific records
+    const providerRecords = await this.generateProviderRecords(config);
+    records.push(...providerRecords);
+
+    return records;
+  }
+
+  /**
+   * Generate SPF DNS record
+   */
+  private generateSPFRecord(config: DomainConfig): DNSRecord {
+    const includes = config.spf.includes || [];
+    const ipv4s = config.spf.ipv4Addresses || [];
+    const ipv6s = config.spf.ipv6Addresses || [];
+    const strict = config.spf.strict !== false;
+
+    let spfValue = 'v=spf1';
+
+    // Add provider-specific includes
+    if (config.provider === 'sendgrid') {
+      includes.push('include:sendgrid.net');
+    } else if (config.provider === 'mailgun') {
+      includes.push('include:mailgun.org');
+    } else if (config.provider === 'ses') {
+      includes.push('include:amazonses.com');
+    }
+
+    includes.forEach(inc => {
+      spfValue += ` ${inc}`;
+    });
+
+    ipv4s.forEach(ip => {
+      spfValue += ` ip4:${ip}`;
+    });
+
+    ipv6s.forEach(ip => {
+      spfValue += ` ip6:${ip}`;
+    });
+
+    spfValue += strict ? ' -all' : ' ~all';
+
+    return {
+      type: 'SPF',
+      host: config.domain,
+      value: spfValue,
+      ttl: 3600,
+      provider: config.provider,
+      required: true,
+      instructions: `Add this TXT record to your domain:\n\nHost: ${config.domain}\nValue: ${spfValue}\nTTL: 3600`
+    };
+  }
+
+  /**
+   * Generate DMARC DNS record
+   */
+  private generateDMARCRecord(config: DomainConfig): DNSRecord {
+    const policy = config.dmarc.policy || 'none';
+    const percentage = config.dmarc.percentage || 100;
+    const reportEmail = config.dmarc.reportEmail;
+    const aggregateEmail = config.dmarc.aggregateEmail;
+    const subdomain = config.dmarc.subdomain || 'none';
+
+    let dmarcValue = `v=DMARC1; p=${policy}; pct=${percentage}; sp=${subdomain};`;
+
+    if (reportEmail) {
+      dmarcValue += ` rua=mailto:${reportEmail};`;
+    }
+
+    if (aggregateEmail) {
+      dmarcValue += ` ruf=mailto:${aggregateEmail};`;
+    }
+
+    return {
+      type: 'DMARC',
+      host: `_dmarc.${config.domain}`,
+      value: dmarcValue,
+      ttl: 3600,
+      provider: config.provider,
+      required: true,
+      instructions: `Add this TXT record to your domain:\n\nHost: _dmarc.${config.domain}\nValue: ${dmarcValue}\nTTL: 3600`
+    };
+  }
+
+  /**
+   * Generate provider-specific DNS records
+   */
+  private async generateProviderRecords(config: DomainConfig): Promise<DNSRecord[]> {
+    switch (config.provider) {
+      case 'sendgrid':
+        return this.generateSendGridRecords(config);
+      case 'mailgun':
+        return this.generateMailgunRecords(config);
+      case 'ses':
+        return this.generateSESRecords(config);
+      default:
+        return [];
+    }
+  }
+
+  /**
+   * Generate SendGrid-specific DNS records
+   */
+  private generateSendGridRecords(config: DomainConfig): DNSRecord[] {
+    const records: DNSRecord[] = [];
+
+    // SendGrid domain authentication requires CNAME records
+    // These would normally come from SendGrid API
+    records.push({
+      type: 'CNAME',
+      host: `em123.${config.domain}`,
+      value: 'u123.wl.sendgrid.net',
+      ttl: 3600,
+      provider: 'sendgrid',
+      required: true,
+      instructions: 'Add this CNAME record (actual values will come from SendGrid API)'
+    });
+
+    return records;
+  }
+
+  /**
+   * Generate Mailgun-specific DNS records
+   */
+  private generateMailgunRecords(config: DomainConfig): DNSRecord[] {
+    const records: DNSRecord[] = [];
+
+    // Mailgun requires specific TXT records
+    records.push({
+      type: 'TXT',
+      host: config.domain,
+      value: 'v=spf1 include:mailgun.org ~all',
+      ttl: 3600,
+      provider: 'mailgun',
+      required: true,
+      instructions: 'Add this TXT record for Mailgun SPF'
+    });
+
+    return records;
+  }
+
+  /**
+   * Generate AWS SES-specific DNS records
+   */
+  private generateSESRecords(config: DomainConfig): DNSRecord[] {
+    const records: DNSRecord[] = [];
+
+    // SES requires TXT record for verification
+    records.push({
+      type: 'TXT',
+      host: `_amazonses.${config.domain}`,
+      value: 'verification-token-from-ses',
+      ttl: 3600,
+      provider: 'ses',
+      required: true,
+      instructions: 'Add this TXT record (actual token will come from AWS SES)'
+    });
+
+    return records;
+  }
+
+  /**
+   * Generate DKIM configuration with keypair
+   */
+  private async generateDKIMConfig(config: DomainConfig): Promise<DKIMConfig> {
+    const selector = config.dkim.selector || 'default';
+    const keySize = config.dkim.keySize || 2048;
+
+    // Generate DKIM keypair using Node.js crypto
+    const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+      modulusLength: keySize,
+      publicKeyEncoding: {
+        type: 'spki',
+        format: 'pem'
+      },
+      privateKeyEncoding: {
+        type: 'pkcs8',
+        format: 'pem'
+      }
+    });
+
+    // Format public key for DNS (remove headers/newlines, base64)
+    const publicKeyForDNS = publicKey
+      .replace(/-----BEGIN PUBLIC KEY-----/, '')
+      .replace(/-----END PUBLIC KEY-----/, '')
+      .replace(/\n/g, '')
+      .replace(/\r/g, '');
+
+    const dkimValue = `v=DKIM1; k=rsa; p=${publicKeyForDNS}`;
+
+    const dnsRecord: DNSRecord = {
+      type: 'DKIM',
+      host: `${selector}._domainkey.${config.domain}`,
+      value: dkimValue,
+      ttl: 3600,
+      provider: config.provider,
+      required: true,
+      instructions: `Add this TXT record to your domain:\n\nHost: ${selector}._domainkey.${config.domain}\nValue: ${dkimValue}\nTTL: 3600`
+    };
+
+    return {
+      selector,
+      privateKey,
+      publicKey,
+      keySize,
+      dnsRecord
+    };
+  }
+
+  /**
+   * Register domain with email provider
+   */
+  private async registerWithProvider(
+    config: DomainConfig,
+    _dkimConfig?: DKIMConfig
+  ): Promise<Record<string, unknown>> {
+    switch (config.provider) {
+      case 'sendgrid':
+        return this.registerWithSendGrid(config);
+      case 'mailgun':
+        return this.registerWithMailgun(config);
+      case 'ses':
+        return this.registerWithSES(config);
+      default:
+        return { registered: false, message: 'Provider not supported' };
+    }
+  }
+
+  /**
+   * Register domain with SendGrid
+   */
+  private async registerWithSendGrid(
+    config: DomainConfig
+  ): Promise<Record<string, unknown>> {
+    try {
+      const response = await this.httpClient.post(
+        'https://api.sendgrid.com/v3/whitelabel/domains',
+        {
+          domain: config.domain,
+          subdomain: 'em',
+          username: 'sendgrid',
+          ips: [],
+          custom_spf: false,
+          default: true,
+          automatic_security: true
+        },
+        {
+          headers: {
+            Authorization: `Bearer ${config.providerCredentials.apiKey as string}`
+          }
+        }
+      );
+
+      return {
+        registered: true,
+        domainId: response.data.id,
+        dnsRecords: response.data.dns,
+        message: 'Domain registered with SendGrid'
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.error(`SendGrid registration failed for ${config.domain}: ${errMsg}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Register domain with Mailgun
+   */
+  private async registerWithMailgun(
+    config: DomainConfig
+  ): Promise<Record<string, unknown>> {
+    try {
+      const response = await this.httpClient.post(
+        'https://api.mailgun.net/v3/domains',
+        new URLSearchParams({
+          name: config.domain,
+          smtp_password: (config.providerCredentials.smtpPassword as string) || '',
+          spam_action: 'disabled',
+          wildcard: 'false'
+        }),
+        {
+          auth: {
+            username: 'api',
+            password: config.providerCredentials.apiKey as string
+          }
+        }
+      );
+
+      return {
+        registered: true,
+        domain: response.data.domain,
+        dnsRecords: response.data.receiving_dns_records.concat(response.data.sending_dns_records),
+        message: 'Domain registered with Mailgun'
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Mailgun registration failed for ${config.domain}: ${errMsg}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Register domain with AWS SES
+   */
+  private async registerWithSES(
+    config: DomainConfig
+  ): Promise<Record<string, unknown>> {
+    // AWS SES registration would use AWS SDK
+    // This is a placeholder implementation
+    this.logger.info('AWS SES registration not yet implemented', {
+      domain: config.domain
+    });
+
+    return {
+      registered: false,
+      message: 'AWS SES registration requires AWS SDK integration'
+    };
+  }
+
+  /**
+   * Verify domain with email provider
+   */
+  private async verifyWithProvider(
+    domain: string,
+    provider: EmailProvider,
+    credentials: Record<string, unknown>
+  ): Promise<Record<string, unknown>> {
+    switch (provider) {
+      case 'sendgrid':
+        return this.verifyWithSendGrid(domain, credentials);
+      case 'mailgun':
+        return this.verifyWithMailgun(domain, credentials);
+      case 'ses':
+        return this.verifyWithSES(domain, credentials);
+      default:
+        return { verified: false, message: 'Provider not supported' };
+    }
+  }
+
+  /**
+   * Verify domain with SendGrid
+   */
+  private async verifyWithSendGrid(
+    domain: string,
+    credentials: Record<string, unknown>
+  ): Promise<Record<string, unknown>> {
+    try {
+      // Get domain ID from SendGrid
+      const domainsResponse = await this.httpClient.get(
+        'https://api.sendgrid.com/v3/whitelabel/domains',
+        {
+          headers: {
+            Authorization: `Bearer ${credentials.apiKey as string}`
+          }
+        }
+      );
+
+      const domainData = domainsResponse.data.find((d: { domain: string }) => d.domain === domain);
+      if (!domainData) {
+        return { verified: false, message: 'Domain not found in SendGrid' };
+      }
+
+      // Trigger verification
+      const verifyResponse = await this.httpClient.post(
+        `https://api.sendgrid.com/v3/whitelabel/domains/${domainData.id}/validate`,
+        {},
+        {
+          headers: {
+            Authorization: `Bearer ${credentials.apiKey as string}`
+          }
+        }
+      );
+
+      return {
+        verified: verifyResponse.data.valid,
+        validationResults: verifyResponse.data.validation_results,
+        message: verifyResponse.data.valid ? 'Domain verified' : 'Verification failed'
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.error(`SendGrid verification failed for ${domain}: ${errMsg}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Verify domain with Mailgun
+   */
+  private async verifyWithMailgun(
+    domain: string,
+    credentials: Record<string, unknown>
+  ): Promise<Record<string, unknown>> {
+    try {
+      const response = await this.httpClient.get(
+        `https://api.mailgun.net/v3/domains/${domain}`,
+        {
+          auth: {
+            username: 'api',
+            password: credentials.apiKey as string
+          }
+        }
+      );
+
+      return {
+        verified: response.data.domain.state === 'active',
+        state: response.data.domain.state,
+        message: response.data.domain.state === 'active' ? 'Domain verified' : 'Verification pending'
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Mailgun verification failed for ${domain}: ${errMsg}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Verify domain with AWS SES
+   */
+  private async verifyWithSES(
+    domain: string,
+    _credentials: Record<string, unknown>
+  ): Promise<Record<string, unknown>> {
+    // AWS SES verification would use AWS SDK
+    this.logger.info('AWS SES verification not yet implemented', { domain });
+
+    return {
+      verified: false,
+      message: 'AWS SES verification requires AWS SDK integration'
+    };
+  }
+
+  /**
+   * Check propagation for single DNS record
+   */
+  private async checkRecordPropagation(
+    domain: string,
+    record: DNSRecord
+  ): Promise<DNSPropagationResult> {
+    const nameservers = await this.getNameservers(domain);
+    const results: { ns: string; value?: string; error?: string }[] = [];
+
+    for (const ns of nameservers) {
+      try {
+        const resolver = new Resolver({ nameServers: [ns] });
+        const response = await resolver.resolve(record.host, 'TXT');
+        const value = response.answers
+          .filter((a: { type: string }) => a.type === 'TXT')
+          .map((a: { data: string }) => a.data)
+          .join('');
+
+        results.push({ ns, value });
+      } catch (error) {
+        results.push({
+          ns,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+      }
+    }
+
+    const propagatedCount = results.filter(
+      r => r.value && r.value.includes(record.value.substring(0, 20))
+    ).length;
+
+    const propagationPercentage = (propagatedCount / nameservers.length) * 100;
+    const propagated = propagationPercentage >= 80; // 80% threshold
+    const actualValue = results.find(r => r.value)?.value;
+    const valuesMatch = actualValue?.includes(record.value.substring(0, 20)) || false;
+
+    return {
+      domain,
+      record,
+      propagated,
+      nameservers,
+      propagationPercentage,
+      actualValue,
+      expectedValue: record.value,
+      valuesMatch,
+      errors: results.filter(r => r.error).map(r => r.error!)
+    };
+  }
+
+  /**
+   * Get nameservers for domain
+   */
+  private async getNameservers(domain: string): Promise<string[]> {
+    try {
+      const resolver = new Resolver();
+      const response = await resolver.resolve(domain, 'NS');
+      return response.answers
+        .filter((a) => a.ns !== undefined)
+        .map((a) => a.ns as string);
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`Failed to get nameservers for ${domain}, using defaults: ${errMsg}`);
+
+      // Return common public DNS servers as fallback
+      return [
+        '8.8.8.8',    // Google
+        '1.1.1.1',    // Cloudflare
+        '208.67.222.222' // OpenDNS
+      ];
+    }
+  }
+
+  /**
+   * Validate domain name format
+   */
+  private validateDomain(domain: string): void {
+    const domainRegex = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/i;
+
+    if (!domainRegex.test(domain)) {
+      throw new InvalidDomainError(`Invalid domain name: ${domain}`);
+    }
+  }
+
+  /**
+   * Add entry to verification history
+   */
+  private async addHistoryEntry(
+    domain: string,
+    entry: Omit<VerificationHistoryEntry, 'id' | 'domain' | 'timestamp'>
+  ): Promise<void> {
+    const history = this.verificationHistory.get(domain) || [];
+
+    const result = await generateUUIDKey();
+    history.push({
+      id: result.key,
+      domain,
+      timestamp: new Date(),
+      ...entry
+    });
+
+    this.verificationHistory.set(domain, history);
+  }
+
+  /**
+   * Register with NeverHub
+   */
+  private async registerWithNeverHub(): Promise<void> {
+    if (!this.neverhub) return;
+
+    await this.neverhub.register({
+      type: 'email-domain-verification',
+      name: '@bernierllc/email-domain-verification',
+      version: '1.0.0',
+      capabilities: [
+        { type: 'email', name: 'domain-verification', version: '1.0.0' },
+        { type: 'dns', name: 'record-management', version: '1.0.0' },
+        { type: 'monitoring', name: 'health-checks', version: '1.0.0' }
+      ],
+      dependencies: ['logging', 'crypto']
+    });
+
+    this.logger.info('Registered with NeverHub');
+  }
+
+  /**
+   * Publish event to NeverHub
+   */
+  private async publishEvent(eventType: string, data: Record<string, unknown>): Promise<void> {
+    if (!this.neverhub) return;
+
+    try {
+      await this.neverhub.publishEvent({
+        type: eventType,
+        data,
+        source: '@bernierllc/email-domain-verification',
+        timestamp: new Date().toISOString()
+      });
+    } catch (error) {
+      this.logger.warn('Failed to publish event to NeverHub', {
+        eventType,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async shutdown(): Promise<void> {
+    // Stop all health monitoring jobs
+    for (const [domain, job] of this.healthCheckJobs.entries()) {
+      job.stop();
+      this.logger.info('Stopped health monitoring', { domain });
+    }
+
+    this.healthCheckJobs.clear();
+    this.logger.info('Email Domain Verification Service shut down');
+  }
+}