@bernierllc/sender-identity-verification 1.3.1 → 1.4.0

package/src/SenderIdentityVerification.ts

@@ -19,12 +19,19 @@ import {
   IEmailDomainVerification
 } from './types.js';
 import { SenderIdentityConfig } from './config.js';
-import { SendGridProvider } from './providers/SendGridProvider.js';
-import { MailgunProvider } from './providers/MailgunProvider.js';
-import { SESProvider } from './providers/SESProvider.js';
-import { SMTPProvider } from './providers/SMTPProvider.js';
 import { buildVerificationEmailHtml, buildVerificationEmailText } from './templates/verification-email.js';
 import { extractDomain } from './utils/domain-extractor.js';
+import { isManualVerificationProvider, getManualInstructions } from './manual-instructions.js';
+import type {
+  EmailSenderManager,
+  SenderProviderPlugin,
+  SenderConfiguration,
+  CreateSenderRequest as CoreCreateSenderRequest,
+} from '@bernierllc/email-sender-manager';
+import {
+  isManagedSenderProvider,
+  isVerifiableSenderProvider,
+} from '@bernierllc/email-sender-manager';
 
 // Import types for dependencies (actual imports would be from npm packages)
 type EmailSender = {
@@ -75,10 +82,23 @@ type NeverHubAdapter = {
 };
 
 /**
- * Sender identity verification service
+ * Sender identity verification service.
+ *
+ * When configured with an `EmailSenderManager` (via config.senderManager) and
+ * provider plugins (via config.providerPlugins or registerProviderPlugin()),
+ * all persistence and provider API calls are delegated. Without those, the
+ * service falls back to the legacy in-memory store.
  */
 export class SenderIdentityVerification {
+  // Legacy in-memory store — used only when no senderManager is configured
   private senders: Map<string, SenderIdentity> = new Map();
+
+  // Provider plugin registry (keyed by providerId)
+  private providerPlugins: Map<string, SenderProviderPlugin> = new Map();
+
+  // Core persistence layer (optional, new path)
+  private senderManager?: EmailSenderManager;
+
   private emailSender?: EmailSender;
   private domainVerification?: IEmailDomainVerification;
   private cryptoUtils?: CryptoUtils;
@@ -91,15 +111,43 @@ export class SenderIdentityVerification {
     if (config.domainVerificationConfig?.instance) {
       this.domainVerification = config.domainVerificationConfig.instance;
     }
+
+    // Wire core sender manager if provided
+    if (config.senderManager) {
+      this.senderManager = config.senderManager;
+    }
+
+    // Register initial provider plugins
+    if (config.providerPlugins) {
+      for (const plugin of config.providerPlugins) {
+        this.providerPlugins.set(plugin.providerId, plugin);
+      }
+    }
+  }
+
+  /**
+   * Register a provider plugin at runtime.
+   */
+  registerProviderPlugin(plugin: SenderProviderPlugin): void {
+    this.providerPlugins.set(plugin.providerId, plugin);
+    this.logger?.info('Provider plugin registered', { providerId: plugin.providerId, name: plugin.name });
+  }
+
+  /**
+   * Get a registered provider plugin by providerId.
+   */
+  getProviderPlugin(providerId: string): SenderProviderPlugin | undefined {
+    return this.providerPlugins.get(providerId);
   }
 
   /**
    * Initialize service and register with NeverHub
    */
   async initialize(): Promise<void> {
-    // Initialize dependencies (would import from actual packages)
-    // For now, we'll use stubs since we're missing dependencies
-    await this.loadSendersFromDatabase();
+    // Load from database if no senderManager (legacy path)
+    if (!this.senderManager) {
+      await this.loadSendersFromDatabase();
+    }
 
     this.logger?.info('Sender identity verification service initialized');
   }
@@ -120,7 +168,7 @@ export class SenderIdentityVerification {
       // 2. Extract domain
       const domain = extractDomain(input.email);
 
-      // 3. Check if domain is verified (stub for missing dependency)
+      // 3. Check if domain is verified
       if (this.domainVerification) {
         const domainStatus = await this.domainVerification.getDomainStatus(domain);
         if (!domainStatus.isVerified) {
@@ -163,16 +211,52 @@ export class SenderIdentityVerification {
         await this.unsetOtherDefaults(input.provider);
       }
 
-      // 6. Persist to database
-      await this.saveSenderToDatabase(sender);
-      this.senders.set(sender.id, sender);
+      // 6. Persist — delegate to senderManager if available, else legacy
+      if (this.senderManager) {
+        const coreRequest = this.toCoreSenderRequest(input, sender);
+        const created = await this.senderManager.createSender(coreRequest);
+        sender.id = created.id;
+        sender.providerSenderId = created.providerSenderId;
+      } else {
+        await this.saveSenderToDatabase(sender);
+        this.senders.set(sender.id, sender);
+      }
 
-      // 7. Send verification email (unless skipped)
-      if (!input.skipVerification) {
+      // 7. Delegate to provider plugin for API-level creation
+      const plugin = this.providerPlugins.get(input.provider);
+      if (plugin && isManagedSenderProvider(plugin) && !input.skipVerification) {
+        const providerResult = await plugin.createSender({
+          fromEmail: input.email,
+          fromName: input.name,
+          replyToEmail: input.replyToEmail,
+          replyToName: input.replyToName,
+          providerFields: input.providerFields,
+        });
+        if (providerResult.success) {
+          sender.providerSenderId = providerResult.providerSenderId;
+          sender.providerMetadata = providerResult.metadata;
+          // Persist the provider sender ID
+          if (this.senderManager) {
+            await this.senderManager.updateSender(sender.id, {
+              providerSenderId: providerResult.providerSenderId,
+              providerMetadata: providerResult.metadata,
+              lastModifiedBy: input.createdBy || 'system',
+            });
+          }
+        } else {
+          this.logger?.warn('Provider creation failed, sender saved locally', {
+            senderId: sender.id,
+            error: providerResult.error?.message,
+          });
+        }
+      }
+
+      // 8. Send verification email (unless skipped or provider handles it)
+      if (!input.skipVerification && !plugin) {
         await this.sendVerificationEmail(sender);
       }
 
-      // 8. Publish event
+      // 9. Publish event
       if (this.neverhub) {
         await this.neverhub.publishEvent({
           type: 'sender-identity.created',
@@ -307,7 +391,7 @@ export class SenderIdentityVerification {
         };
       }
 
-      // 5. Verify with provider
+      // 5. Verify with provider — use plugin system first, fall back to legacy
       const providerResult = await this.verifyWithProvider(sender);
       if (!providerResult.success) {
         sender.status = SenderStatus.FAILED;
@@ -336,6 +420,18 @@ export class SenderIdentityVerification {
 
       await this.saveSenderToDatabase(sender);
 
+      // Update core layer if available
+      if (this.senderManager) {
+        await this.senderManager.updateSender(sender.id, {
+          isVerified: true,
+          verificationStatus: 'verified',
+          lastVerifiedAt: sender.verifiedAt,
+          providerSenderId: sender.providerSenderId,
+          providerMetadata: sender.providerMetadata,
+          lastModifiedBy: 'system',
+        });
+      }
+
       // 7. Publish event
       if (this.neverhub) {
         await this.neverhub.publishEvent({
@@ -371,15 +467,74 @@ export class SenderIdentityVerification {
   }
 
   /**
-   * Verify sender with email provider
+   * Verify sender with email provider.
+   *
+   * Uses the plugin registry first. If no plugin is registered for the
+   * provider, falls back to the legacy provider classes.
    */
   private async verifyWithProvider(sender: SenderIdentity): Promise<SenderIdentityResult<{
     providerId?: string;
     metadata?: Record<string, unknown>;
   }>> {
+    // Try plugin-based verification
+    const plugin = this.providerPlugins.get(sender.provider);
+    if (plugin) {
+      if (isVerifiableSenderProvider(plugin) && sender.providerSenderId) {
+        const result = await plugin.checkVerificationStatus(sender.providerSenderId);
+        if (result.status === 'verified') {
+          return {
+            success: true,
+            data: {
+              providerId: result.providerSenderId,
+              metadata: { verificationType: result.verificationType },
+            },
+          };
+        }
+        return {
+          success: false,
+          error: result.error?.message || `Verification status: ${result.status}`,
+        };
+      }
+
+      // Plugin exists but is not verifiable — validate only
+      const validation = await plugin.validateSender(sender.email);
+      if (validation.isVerified) {
+        return {
+          success: true,
+          data: { metadata: validation.metadata },
+        };
+      }
+      return { success: true, data: {} };
+    }
+
+    // Manual verification providers
+    if (isManualVerificationProvider(sender.provider)) {
+      const instructions = getManualInstructions(sender.provider);
+      return {
+        success: true,
+        data: {
+          metadata: instructions ? { manualInstructions: instructions } : {},
+        },
+      };
+    }
+
+    // Legacy fallback — for backward compatibility when no plugins are registered
+    return this.legacyVerifyWithProvider(sender);
+  }
+
+  /**
+   * Legacy provider verification using inline provider classes.
+   * Preserved for backward compatibility when no plugins are configured.
+   */
+  private async legacyVerifyWithProvider(sender: SenderIdentity): Promise<SenderIdentityResult<{
+    providerId?: string;
+    metadata?: Record<string, unknown>;
+  }>> {
+    // Dynamic imports to avoid breaking if legacy providers are removed later
     switch (sender.provider) {
       case EmailProvider.SENDGRID:
         if (this.config.sendgridApiKey) {
+          const { SendGridProvider } = await import('./providers/SendGridProvider.js');
           const provider = new SendGridProvider(this.config.sendgridApiKey);
           return provider.verifySender(sender);
         }
@@ -387,13 +542,15 @@ export class SenderIdentityVerification {
 
       case EmailProvider.MAILGUN:
         if (this.config.mailgunApiKey) {
+          const { MailgunProvider } = await import('./providers/MailgunProvider.js');
           const provider = new MailgunProvider(this.config.mailgunApiKey);
           return provider.verifySender(sender);
         }
-        return { success: true, data: {} }; // Mailgun doesn't require verification
+        return { success: true, data: {} };
 
       case EmailProvider.SES:
         if (this.config.sesAccessKey && this.config.sesSecretKey && this.config.sesRegion) {
+          const { SESProvider } = await import('./providers/SESProvider.js');
           const provider = new SESProvider(
             this.config.sesAccessKey,
             this.config.sesSecretKey,
@@ -404,6 +561,7 @@ export class SenderIdentityVerification {
         return { success: false, error: 'SES credentials not configured' };
 
       case EmailProvider.SMTP: {
+        const { SMTPProvider } = await import('./providers/SMTPProvider.js');
         const provider = new SMTPProvider();
         return provider.verifySender(sender);
       }
@@ -411,8 +569,6 @@ export class SenderIdentityVerification {
       case EmailProvider.POSTMARK:
       case EmailProvider.MANDRILL:
       case EmailProvider.SMTP2GO:
-        // These providers handle sender verification through their own dashboards.
-        // Return success to allow the sender to be registered locally.
         return { success: true, data: {} };
 
       default:
@@ -427,6 +583,14 @@ export class SenderIdentityVerification {
    * Get sender by ID
    */
   async getSender(senderId: string): Promise<SenderIdentityResult<SenderIdentity>> {
+    if (this.senderManager) {
+      const config = await this.senderManager.getSender(senderId);
+      if (!config) {
+        return { success: false, error: `Sender not found: ${senderId}` };
+      }
+      return { success: true, data: this.coreConfigToIdentity(config) };
+    }
+
     const sender = this.senders.get(senderId);
     if (!sender) {
       return {
@@ -446,6 +610,22 @@ export class SenderIdentityVerification {
    */
   async listSenders(options: ListSendersOptions = {}): Promise<SenderIdentityResult<SenderIdentity[]>> {
     try {
+      if (this.senderManager) {
+        const result = await this.senderManager.listSenders({
+          provider: options.provider,
+          isActive: options.isActive,
+          domain: options.domain,
+          offset: options.offset,
+          limit: options.limit,
+        });
+        const identities = result.items.map((c: SenderConfiguration) => this.coreConfigToIdentity(c));
+        // Apply status filter locally (core layer doesn't have SenderStatus enum)
+        const filtered = options.status
+          ? identities.filter((s: SenderIdentity) => s.status === options.status)
+          : identities;
+        return { success: true, data: filtered };
+      }
+
       let senders = Array.from(this.senders.values());
 
       // Filter by provider
@@ -493,13 +673,12 @@ export class SenderIdentityVerification {
    */
   async updateSender(senderId: string, input: UpdateSenderInput): Promise<SenderIdentityResult<SenderIdentity>> {
     try {
-      const sender = this.senders.get(senderId);
-      if (!sender) {
-        return {
-          success: false,
-          error: `Sender not found: ${senderId}`
-        };
+      // Fetch from appropriate store
+      const getResult = await this.getSender(senderId);
+      if (!getResult.success || !getResult.data) {
+        return { success: false, error: `Sender not found: ${senderId}` };
       }
+      const sender = getResult.data;
 
       // Update fields
       if (input.name !== undefined) sender.name = input.name;
@@ -523,7 +702,32 @@ export class SenderIdentityVerification {
         sender.lastValidated = undefined;
       }
 
-      await this.saveSenderToDatabase(sender);
+      // Persist
+      if (this.senderManager) {
+        await this.senderManager.updateSender(senderId, {
+          name: input.name,
+          fromName: input.name,
+          replyToEmail: input.replyToEmail,
+          replyToName: input.replyToName,
+          isDefault: input.isDefault,
+          isActive: input.isActive,
+          lastModifiedBy: input.lastModifiedBy || 'system',
+        });
+      } else {
+        await this.saveSenderToDatabase(sender);
+      }
+
+      // Delegate to provider plugin if available
+      const plugin = this.providerPlugins.get(sender.provider);
+      if (plugin && isManagedSenderProvider(plugin) && sender.providerSenderId) {
+        await plugin.updateSender({
+          providerSenderId: sender.providerSenderId,
+          fromName: input.name,
+          replyToEmail: input.replyToEmail,
+          replyToName: input.replyToName,
+          providerFields: input.providerFields,
+        });
+      }
 
       // Publish event
       if (this.neverhub) {
@@ -553,21 +757,28 @@ export class SenderIdentityVerification {
    */
   async deleteSender(senderId: string): Promise<SenderIdentityResult<void>> {
     try {
-      const sender = this.senders.get(senderId);
-      if (!sender) {
-        return {
-          success: false,
-          error: `Sender not found: ${senderId}`
-        };
+      const getResult = await this.getSender(senderId);
+      if (!getResult.success || !getResult.data) {
+        return { success: false, error: `Sender not found: ${senderId}` };
       }
+      const sender = getResult.data;
 
-      // Soft delete
-      sender.deletedAt = new Date();
-      sender.isActive = false;
-      sender.updatedAt = new Date();
+      // Delete from provider if plugin supports it
+      const plugin = this.providerPlugins.get(sender.provider);
+      if (plugin && isManagedSenderProvider(plugin) && sender.providerSenderId) {
+        await plugin.deleteSender(sender.providerSenderId);
+      }
 
-      await this.saveSenderToDatabase(sender);
-      this.senders.delete(senderId);
+      // Persist deletion
+      if (this.senderManager) {
+        await this.senderManager.deleteSender(senderId);
+      } else {
+        sender.deletedAt = new Date();
+        sender.isActive = false;
+        sender.updatedAt = new Date();
+        await this.saveSenderToDatabase(sender);
+        this.senders.delete(senderId);
+      }
 
       // Publish event
       if (this.neverhub) {
@@ -594,13 +805,11 @@ export class SenderIdentityVerification {
    */
   async checkCompliance(senderId: string): Promise<SenderIdentityResult<ComplianceCheckResult>> {
     try {
-      const sender = this.senders.get(senderId);
-      if (!sender) {
-        return {
-          success: false,
-          error: `Sender not found: ${senderId}`
-        };
+      const getResult = await this.getSender(senderId);
+      if (!getResult.success || !getResult.data) {
+        return { success: false, error: `Sender not found: ${senderId}` };
       }
+      const sender = getResult.data;
 
       const errors: string[] = [];
       const warnings: string[] = [];
@@ -611,7 +820,7 @@ export class SenderIdentityVerification {
         errors.push('Invalid email format');
       }
 
-      // 2. Check domain verification (stub)
+      // 2. Check domain verification
       let domainVerified = true;
       let spfValid = true;
       let dkimValid = true;
@@ -633,11 +842,15 @@ export class SenderIdentityVerification {
         }
       }
 
-      // 3. Provider-specific checks
-      if (sender.provider === EmailProvider.SENDGRID) {
-        if (!sender.providerSenderId) {
-          warnings.push('SendGrid sender ID not set - may need re-verification');
+      // 3. Provider-specific checks via plugin
+      const plugin = this.providerPlugins.get(sender.provider);
+      if (plugin && isVerifiableSenderProvider(plugin) && sender.providerSenderId) {
+        const verificationResult = await plugin.checkVerificationStatus(sender.providerSenderId);
+        if (verificationResult.status !== 'verified') {
+          warnings.push(`Provider verification status: ${verificationResult.status}`);
         }
+      } else if (sender.provider === EmailProvider.SENDGRID && !sender.providerSenderId) {
+        warnings.push('SendGrid sender ID not set - may need re-verification');
       }
 
       const isCompliant = errors.length === 0;
@@ -676,6 +889,19 @@ export class SenderIdentityVerification {
    * Get default sender for provider
    */
   async getDefaultSender(provider: EmailProvider): Promise<SenderIdentityResult<SenderIdentity>> {
+    if (this.senderManager) {
+      const result = await this.senderManager.listSenders({
+        provider,
+        isActive: true,
+        isVerified: true,
+      });
+      const defaultSender = result.items.find((s: SenderConfiguration) => s.isDefault);
+      if (!defaultSender) {
+        return { success: false, error: `No default sender found for provider ${provider}` };
+      }
+      return { success: true, data: this.coreConfigToIdentity(defaultSender) };
+    }
+
     const senders = Array.from(this.senders.values());
     const defaultSender = senders.find(s =>
       s.provider === provider &&
@@ -702,13 +928,11 @@ export class SenderIdentityVerification {
    */
   async resendVerification(senderId: string): Promise<SenderIdentityResult<void>> {
     try {
-      const sender = this.senders.get(senderId);
-      if (!sender) {
-        return {
-          success: false,
-          error: `Sender not found: ${senderId}`
-        };
+      const getResult = await this.getSender(senderId);
+      if (!getResult.success || !getResult.data) {
+        return { success: false, error: `Sender not found: ${senderId}` };
       }
+      const sender = getResult.data;
 
       if (sender.status === SenderStatus.VERIFIED) {
         return {
@@ -735,6 +959,15 @@ export class SenderIdentityVerification {
         }
       }
 
+      // If provider supports verification, use it
+      const plugin = this.providerPlugins.get(sender.provider);
+      if (plugin && isVerifiableSenderProvider(plugin) && sender.providerSenderId) {
+        const result = await plugin.initiateVerification(sender.providerSenderId);
+        if (result.success) {
+          return { success: true };
+        }
+      }
+
       return this.sendVerificationEmail(sender);
     } catch (error) {
       this.logger?.error('Failed to resend verification', { error, senderId });
@@ -745,6 +978,42 @@ export class SenderIdentityVerification {
     }
   }
 
+  /**
+   * Check verification status for a sender using the provider plugin.
+   */
+  async checkVerificationStatus(senderId: string): Promise<SenderIdentityResult<{
+    status: string;
+    verificationType?: string;
+    dnsRecords?: unknown[];
+  }>> {
+    const getResult = await this.getSender(senderId);
+    if (!getResult.success || !getResult.data) {
+      return { success: false, error: `Sender not found: ${senderId}` };
+    }
+    const sender = getResult.data;
+
+    const plugin = this.providerPlugins.get(sender.provider);
+    if (!plugin || !isVerifiableSenderProvider(plugin) || !sender.providerSenderId) {
+      return {
+        success: true,
+        data: {
+          status: sender.status,
+          verificationType: 'manual',
+        },
+      };
+    }
+
+    const result = await plugin.checkVerificationStatus(sender.providerSenderId);
+    return {
+      success: result.success,
+      data: {
+        status: result.status,
+        verificationType: result.verificationType,
+        dnsRecords: result.dnsRecords,
+      },
+    };
+  }
+
   // ============================================
   // Private Helper Methods
   // ============================================
@@ -772,14 +1041,34 @@ export class SenderIdentityVerification {
   }
 
   private async findSenderByEmail(email: string): Promise<SenderIdentity | undefined> {
+    if (this.senderManager) {
+      const result = await this.senderManager.listSenders({ limit: 1000 });
+      return result.items
+        .map((c: SenderConfiguration) => this.coreConfigToIdentity(c))
+        .find((s: SenderIdentity) => s.email === email && !s.deletedAt);
+    }
     return Array.from(this.senders.values()).find(s => s.email === email && !s.deletedAt);
   }
 
   private async findSenderByToken(token: string): Promise<SenderIdentity | undefined> {
+    // Token lookup is always in-memory (tokens live in the service layer)
     return Array.from(this.senders.values()).find(s => s.verificationToken === token);
   }
 
   private async unsetOtherDefaults(provider: EmailProvider): Promise<void> {
+    if (this.senderManager) {
+      const result = await this.senderManager.listSenders({ provider });
+      for (const sender of result.items) {
+        if (sender.isDefault) {
+          await this.senderManager.updateSender(sender.id, {
+            isDefault: false,
+            lastModifiedBy: 'system',
+          });
+        }
+      }
+      return;
+    }
+
     const senders = Array.from(this.senders.values())
       .filter(s => s.provider === provider && s.isDefault);
 
@@ -791,13 +1080,61 @@ export class SenderIdentityVerification {
   }
 
   private async loadSendersFromDatabase(): Promise<void> {
-    // TODO: Implement database loading
+    // TODO: Implement database loading for legacy path
     // For now, no-op
   }
 
   private async saveSenderToDatabase(sender: SenderIdentity): Promise<void> {
-    // TODO: Implement database persistence
+    // TODO: Implement database persistence for legacy path
     // For now, just update in-memory map
     this.senders.set(sender.id, sender);
   }
+
+  // ============================================
+  // Mapping helpers between service and core types
+  // ============================================
+
+  private toCoreSenderRequest(input: CreateSenderInput, sender: SenderIdentity): CoreCreateSenderRequest {
+    return {
+      name: input.name,
+      fromEmail: input.email,
+      fromName: input.name,
+      replyToEmail: input.replyToEmail,
+      replyToName: input.replyToName,
+      provider: input.provider,
+      allowedDomains: [sender.domain],
+      createdBy: input.createdBy || 'system',
+    };
+  }
+
+  private coreConfigToIdentity(config: SenderConfiguration): SenderIdentity {
+    return {
+      id: config.id,
+      email: config.fromEmail,
+      name: config.fromName,
+      replyToEmail: config.replyToEmail,
+      replyToName: config.replyToName,
+      domain: config.domain,
+      provider: config.provider as EmailProvider,
+      status: this.mapVerificationStatus(config.verificationStatus),
+      isDefault: config.isDefault,
+      isActive: config.isActive,
+      verificationAttempts: 0,
+      verifiedAt: config.lastVerifiedAt,
+      providerSenderId: config.providerSenderId,
+      providerMetadata: config.providerMetadata,
+      createdAt: config.createdAt,
+      updatedAt: config.updatedAt,
+    };
+  }
+
+  private mapVerificationStatus(status: string): SenderStatus {
+    switch (status) {
+      case 'verified': return SenderStatus.VERIFIED;
+      case 'failed': return SenderStatus.FAILED;
+      case 'expired': return SenderStatus.EXPIRED;
+      case 'pending':
+      default: return SenderStatus.PENDING;
+    }
+  }
 }