@bernierllc/sender-identity-verification 1.0.0

package/src/SenderIdentityVerification.ts

@@ -0,0 +1,796 @@
+/*
+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 {
+  SenderIdentity,
+  SenderStatus,
+  EmailProvider,
+  CreateSenderInput,
+  UpdateSenderInput,
+  VerificationResult,
+  ComplianceCheckResult,
+  ListSendersOptions,
+  SenderIdentityResult,
+  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 types for dependencies (actual imports would be from npm packages)
+type EmailSender = {
+  sendEmail(options: {
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+    from: string;
+    fromName: string;
+  }): Promise<{ success: boolean; error?: string }>;
+};
+
+type CryptoUtils = {
+  generateSecureToken(length: number): string;
+};
+
+type Logger = {
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+};
+
+type EmailValidator = {
+  validate(email: string): { isValid: boolean; errors: string[] };
+};
+
+type NeverHubAdapter = {
+  register(config: {
+    type: string;
+    name: string;
+    version: string;
+    capabilities: Array<{
+      type: string;
+      name: string;
+      version: string;
+      metadata?: Record<string, unknown>;
+    }>;
+    dependencies: string[];
+    discoveryEnabled: boolean;
+    discoverySubscriptions: Array<{
+      subscriptionType: string;
+      filterCriteria: { capabilityTypes: string[] };
+    }>;
+  }): Promise<void>;
+  publishEvent(event: { type: string; data: Record<string, unknown> }): Promise<void>;
+  subscribe(eventType: string, handler: (event: { data: Record<string, unknown> }) => Promise<void>): Promise<void>;
+};
+
+/**
+ * Sender identity verification service
+ */
+export class SenderIdentityVerification {
+  private senders: Map<string, SenderIdentity> = new Map();
+  private emailSender?: EmailSender;
+  private domainVerification?: IEmailDomainVerification;
+  private cryptoUtils?: CryptoUtils;
+  private logger?: Logger;
+  private emailValidator?: EmailValidator;
+  private neverhub?: NeverHubAdapter;
+
+  constructor(private config: SenderIdentityConfig) {
+    // Initialize domain verification from config if provided
+    if (config.domainVerificationConfig?.instance) {
+      this.domainVerification = config.domainVerificationConfig.instance;
+    }
+  }
+
+  /**
+   * 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();
+
+    this.logger?.info('Sender identity verification service initialized');
+  }
+
+  /**
+   * Create a new sender identity
+   */
+  async createSender(input: CreateSenderInput): Promise<SenderIdentityResult<SenderIdentity>> {
+    try {
+      // 1. Validate email format
+      if (!this.isValidEmail(input.email)) {
+        return {
+          success: false,
+          error: 'Invalid email format'
+        };
+      }
+
+      // 2. Extract domain
+      const domain = extractDomain(input.email);
+
+      // 3. Check if domain is verified (stub for missing dependency)
+      if (this.domainVerification) {
+        const domainStatus = await this.domainVerification.getDomainStatus(domain);
+        if (!domainStatus.isVerified) {
+          return {
+            success: false,
+            error: `Domain ${domain} is not verified. Please verify the domain first.`,
+            errors: [`Domain verification required`]
+          };
+        }
+      }
+
+      // 4. Check for duplicate sender
+      const existing = await this.findSenderByEmail(input.email);
+      if (existing) {
+        return {
+          success: false,
+          error: `Sender with email ${input.email} already exists (ID: ${existing.id})`
+        };
+      }
+
+      // 5. Create sender record
+      const sender: SenderIdentity = {
+        id: this.generateSenderId(),
+        email: input.email,
+        name: input.name,
+        replyToEmail: input.replyToEmail || input.email,
+        replyToName: input.replyToName || input.name,
+        domain,
+        provider: input.provider,
+        status: input.skipVerification ? SenderStatus.VERIFIED : SenderStatus.PENDING,
+        isDefault: input.isDefault || false,
+        isActive: true,
+        verificationAttempts: 0,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      // If setting as default, unset other defaults for this provider
+      if (input.isDefault) {
+        await this.unsetOtherDefaults(input.provider);
+      }
+
+      // 6. Persist to database
+      await this.saveSenderToDatabase(sender);
+      this.senders.set(sender.id, sender);
+
+      // 7. Send verification email (unless skipped)
+      if (!input.skipVerification) {
+        await this.sendVerificationEmail(sender);
+      }
+
+      // 8. Publish event
+      if (this.neverhub) {
+        await this.neverhub.publishEvent({
+          type: 'sender-identity.created',
+          data: { senderId: sender.id, email: sender.email, provider: sender.provider }
+        });
+      }
+
+      this.logger?.info('Sender identity created', { senderId: sender.id, email: sender.email });
+
+      return {
+        success: true,
+        data: sender
+      };
+    } catch (error) {
+      this.logger?.error('Failed to create sender identity', { error, input });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error creating sender'
+      };
+    }
+  }
+
+  /**
+   * Send verification email to sender
+   */
+  async sendVerificationEmail(sender: SenderIdentity): Promise<SenderIdentityResult<void>> {
+    try {
+      // 1. Generate verification token
+      const token = this.cryptoUtils?.generateSecureToken(32) || this.fallbackGenerateToken(32);
+      const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
+
+      // 2. Update sender record
+      sender.verificationToken = token;
+      sender.verificationSentAt = new Date();
+      sender.verificationExpiresAt = expiresAt;
+      sender.status = SenderStatus.VERIFICATION_SENT;
+      sender.verificationAttempts++;
+      sender.updatedAt = new Date();
+
+      await this.saveSenderToDatabase(sender);
+
+      // 3. Build verification URL
+      const verificationUrl = `${this.config.verificationBaseUrl}/verify-sender?token=${token}`;
+
+      // 4. Send verification email
+      if (this.emailSender) {
+        const emailResult = await this.emailSender.sendEmail({
+          to: sender.email,
+          subject: 'Verify your sender email address',
+          html: buildVerificationEmailHtml(sender, verificationUrl),
+          text: buildVerificationEmailText(sender, verificationUrl),
+          from: this.config.verificationFromEmail,
+          fromName: this.config.verificationFromName,
+        });
+
+        if (!emailResult.success) {
+          throw new Error(`Failed to send verification email: ${emailResult.error}`);
+        }
+      }
+
+      // 5. Publish event
+      if (this.neverhub) {
+        await this.neverhub.publishEvent({
+          type: 'sender-identity.verification-sent',
+          data: { senderId: sender.id, email: sender.email, expiresAt }
+        });
+      }
+
+      this.logger?.info('Verification email sent', { senderId: sender.id, email: sender.email });
+
+      return { success: true };
+    } catch (error) {
+      this.logger?.error('Failed to send verification email', { error, senderId: sender.id });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to send verification email'
+      };
+    }
+  }
+
+  /**
+   * Verify sender email with token
+   */
+  async verifySender(token: string): Promise<VerificationResult> {
+    try {
+      // 1. Find sender by token
+      const sender = await this.findSenderByToken(token);
+      if (!sender) {
+        return {
+          success: false,
+          senderId: '',
+          status: SenderStatus.FAILED,
+          message: 'Invalid verification token',
+          errors: ['Token not found or already used']
+        };
+      }
+
+      // 2. Check if already verified
+      if (sender.status === SenderStatus.VERIFIED) {
+        return {
+          success: true,
+          senderId: sender.id,
+          status: sender.status,
+          message: 'Sender already verified',
+          verifiedAt: sender.verifiedAt
+        };
+      }
+
+      // 3. Check if token expired
+      if (sender.verificationExpiresAt && sender.verificationExpiresAt < new Date()) {
+        sender.status = SenderStatus.EXPIRED;
+        sender.updatedAt = new Date();
+        await this.saveSenderToDatabase(sender);
+
+        return {
+          success: false,
+          senderId: sender.id,
+          status: SenderStatus.EXPIRED,
+          message: 'Verification token expired. Please request a new verification email.',
+          errors: ['Token expired']
+        };
+      }
+
+      // 4. Check if locked
+      if (sender.status === SenderStatus.LOCKED) {
+        return {
+          success: false,
+          senderId: sender.id,
+          status: SenderStatus.LOCKED,
+          message: 'Sender locked due to too many failed verification attempts',
+          errors: ['Account locked']
+        };
+      }
+
+      // 5. Verify with provider
+      const providerResult = await this.verifyWithProvider(sender);
+      if (!providerResult.success) {
+        sender.status = SenderStatus.FAILED;
+        sender.validationErrors = providerResult.errors || [providerResult.error || 'Provider verification failed'];
+        sender.updatedAt = new Date();
+        await this.saveSenderToDatabase(sender);
+
+        return {
+          success: false,
+          senderId: sender.id,
+          status: SenderStatus.FAILED,
+          message: 'Provider verification failed',
+          errors: sender.validationErrors
+        };
+      }
+
+      // 6. Mark as verified
+      sender.status = SenderStatus.VERIFIED;
+      sender.verifiedAt = new Date();
+      sender.verificationToken = undefined;
+      sender.providerSenderId = providerResult.data?.providerId as string | undefined;
+      sender.providerMetadata = providerResult.data?.metadata as Record<string, unknown> | undefined;
+      sender.lastValidated = new Date();
+      sender.validationErrors = undefined;
+      sender.updatedAt = new Date();
+
+      await this.saveSenderToDatabase(sender);
+
+      // 7. Publish event
+      if (this.neverhub) {
+        await this.neverhub.publishEvent({
+          type: 'sender-identity.verified',
+          data: {
+            senderId: sender.id,
+            email: sender.email,
+            provider: sender.provider,
+            verifiedAt: sender.verifiedAt
+          }
+        });
+      }
+
+      this.logger?.info('Sender verified successfully', { senderId: sender.id, email: sender.email });
+
+      return {
+        success: true,
+        senderId: sender.id,
+        status: sender.status,
+        message: 'Sender verified successfully',
+        verifiedAt: sender.verifiedAt
+      };
+    } catch (error) {
+      this.logger?.error('Failed to verify sender', { error, token });
+      return {
+        success: false,
+        senderId: '',
+        status: SenderStatus.FAILED,
+        message: error instanceof Error ? error.message : 'Verification failed',
+        errors: [error instanceof Error ? error.message : 'Unknown error']
+      };
+    }
+  }
+
+  /**
+   * Verify sender with email provider
+   */
+  private async verifyWithProvider(sender: SenderIdentity): Promise<SenderIdentityResult<{
+    providerId?: string;
+    metadata?: Record<string, unknown>;
+  }>> {
+    switch (sender.provider) {
+      case EmailProvider.SENDGRID:
+        if (this.config.sendgridApiKey) {
+          const provider = new SendGridProvider(this.config.sendgridApiKey);
+          return provider.verifySender(sender);
+        }
+        return { success: false, error: 'SendGrid API key not configured' };
+
+      case EmailProvider.MAILGUN:
+        if (this.config.mailgunApiKey) {
+          const provider = new MailgunProvider(this.config.mailgunApiKey);
+          return provider.verifySender(sender);
+        }
+        return { success: true, data: {} }; // Mailgun doesn't require verification
+
+      case EmailProvider.SES:
+        if (this.config.sesAccessKey && this.config.sesSecretKey && this.config.sesRegion) {
+          const provider = new SESProvider(
+            this.config.sesAccessKey,
+            this.config.sesSecretKey,
+            this.config.sesRegion
+          );
+          return provider.verifySender(sender);
+        }
+        return { success: false, error: 'SES credentials not configured' };
+
+      case EmailProvider.SMTP: {
+        const provider = new SMTPProvider();
+        return provider.verifySender(sender);
+      }
+
+      default:
+        return {
+          success: false,
+          error: `Unsupported provider: ${sender.provider}`
+        };
+    }
+  }
+
+  /**
+   * Get sender by ID
+   */
+  async getSender(senderId: string): Promise<SenderIdentityResult<SenderIdentity>> {
+    const sender = this.senders.get(senderId);
+    if (!sender) {
+      return {
+        success: false,
+        error: `Sender not found: ${senderId}`
+      };
+    }
+
+    return {
+      success: true,
+      data: sender
+    };
+  }
+
+  /**
+   * List senders
+   */
+  async listSenders(options: ListSendersOptions = {}): Promise<SenderIdentityResult<SenderIdentity[]>> {
+    try {
+      let senders = Array.from(this.senders.values());
+
+      // Filter by provider
+      if (options.provider) {
+        senders = senders.filter(s => s.provider === options.provider);
+      }
+
+      // Filter by status
+      if (options.status) {
+        senders = senders.filter(s => s.status === options.status);
+      }
+
+      // Filter by active
+      if (options.isActive !== undefined) {
+        senders = senders.filter(s => s.isActive === options.isActive);
+      }
+
+      // Filter by domain
+      if (options.domain) {
+        senders = senders.filter(s => s.domain === options.domain);
+      }
+
+      // Sort by created date (newest first)
+      senders.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+
+      // Pagination
+      const limit = options.limit || 50;
+      const offset = options.offset || 0;
+      senders = senders.slice(offset, offset + limit);
+
+      return {
+        success: true,
+        data: senders
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to list senders'
+      };
+    }
+  }
+
+  /**
+   * Update sender
+   */
+  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}`
+        };
+      }
+
+      // Update fields
+      if (input.name !== undefined) sender.name = input.name;
+      if (input.replyToEmail !== undefined) sender.replyToEmail = input.replyToEmail;
+      if (input.replyToName !== undefined) sender.replyToName = input.replyToName;
+      if (input.isDefault !== undefined) {
+        // If setting as default, unset other defaults
+        if (input.isDefault) {
+          await this.unsetOtherDefaults(sender.provider);
+        }
+        sender.isDefault = input.isDefault;
+      }
+      if (input.isActive !== undefined) sender.isActive = input.isActive;
+
+      sender.updatedAt = new Date();
+
+      // If changing email-related fields, require re-verification
+      if (input.replyToEmail && input.replyToEmail !== sender.email) {
+        sender.status = SenderStatus.PENDING;
+        sender.verifiedAt = undefined;
+        sender.lastValidated = undefined;
+      }
+
+      await this.saveSenderToDatabase(sender);
+
+      // Publish event
+      if (this.neverhub) {
+        await this.neverhub.publishEvent({
+          type: 'sender-identity.updated',
+          data: { senderId: sender.id, updates: input }
+        });
+      }
+
+      this.logger?.info('Sender updated', { senderId, updates: input });
+
+      return {
+        success: true,
+        data: sender
+      };
+    } catch (error) {
+      this.logger?.error('Failed to update sender', { error, senderId, input });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to update sender'
+      };
+    }
+  }
+
+  /**
+   * Delete sender
+   */
+  async deleteSender(senderId: string): Promise<SenderIdentityResult<void>> {
+    try {
+      const sender = this.senders.get(senderId);
+      if (!sender) {
+        return {
+          success: false,
+          error: `Sender not found: ${senderId}`
+        };
+      }
+
+      // Soft delete
+      sender.deletedAt = new Date();
+      sender.isActive = false;
+      sender.updatedAt = new Date();
+
+      await this.saveSenderToDatabase(sender);
+      this.senders.delete(senderId);
+
+      // Publish event
+      if (this.neverhub) {
+        await this.neverhub.publishEvent({
+          type: 'sender-identity.deleted',
+          data: { senderId, email: sender.email }
+        });
+      }
+
+      this.logger?.info('Sender deleted', { senderId, email: sender.email });
+
+      return { success: true };
+    } catch (error) {
+      this.logger?.error('Failed to delete sender', { error, senderId });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to delete sender'
+      };
+    }
+  }
+
+  /**
+   * Check provider compliance for sender
+   */
+  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 errors: string[] = [];
+      const warnings: string[] = [];
+
+      // 1. Check email format
+      const emailFormat = this.isValidEmail(sender.email);
+      if (!emailFormat) {
+        errors.push('Invalid email format');
+      }
+
+      // 2. Check domain verification (stub)
+      let domainVerified = true;
+      let spfValid = true;
+      let dkimValid = true;
+
+      if (this.domainVerification) {
+        const domainStatus = await this.domainVerification.getDomainStatus(sender.domain);
+        domainVerified = domainStatus.isVerified;
+        spfValid = domainStatus.dnsRecords?.spf?.isValid || false;
+        dkimValid = domainStatus.dnsRecords?.dkim?.isValid || false;
+
+        if (!domainVerified) {
+          errors.push(`Domain ${sender.domain} is not verified`);
+        }
+        if (!spfValid) {
+          errors.push('SPF record not configured or invalid');
+        }
+        if (!dkimValid) {
+          errors.push('DKIM record not configured or invalid');
+        }
+      }
+
+      // 3. Provider-specific checks
+      if (sender.provider === EmailProvider.SENDGRID) {
+        if (!sender.providerSenderId) {
+          warnings.push('SendGrid sender ID not set - may need re-verification');
+        }
+      }
+
+      const isCompliant = errors.length === 0;
+
+      const result: ComplianceCheckResult = {
+        isCompliant,
+        checks: {
+          domainVerified,
+          spfValid,
+          dkimValid,
+          emailFormat
+        },
+        errors,
+        warnings
+      };
+
+      // Update sender validation
+      sender.lastValidated = new Date();
+      sender.validationErrors = errors.length > 0 ? errors : undefined;
+      await this.saveSenderToDatabase(sender);
+
+      return {
+        success: true,
+        data: result
+      };
+    } catch (error) {
+      this.logger?.error('Failed to check compliance', { error, senderId });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to check compliance'
+      };
+    }
+  }
+
+  /**
+   * Get default sender for provider
+   */
+  async getDefaultSender(provider: EmailProvider): Promise<SenderIdentityResult<SenderIdentity>> {
+    const senders = Array.from(this.senders.values());
+    const defaultSender = senders.find(s =>
+      s.provider === provider &&
+      s.isDefault &&
+      s.status === SenderStatus.VERIFIED &&
+      s.isActive
+    );
+
+    if (!defaultSender) {
+      return {
+        success: false,
+        error: `No default sender found for provider ${provider}`
+      };
+    }
+
+    return {
+      success: true,
+      data: defaultSender
+    };
+  }
+
+  /**
+   * Resend verification email
+   */
+  async resendVerification(senderId: string): Promise<SenderIdentityResult<void>> {
+    try {
+      const sender = this.senders.get(senderId);
+      if (!sender) {
+        return {
+          success: false,
+          error: `Sender not found: ${senderId}`
+        };
+      }
+
+      if (sender.status === SenderStatus.VERIFIED) {
+        return {
+          success: false,
+          error: 'Sender already verified'
+        };
+      }
+
+      if (sender.status === SenderStatus.LOCKED) {
+        return {
+          success: false,
+          error: 'Sender locked due to too many attempts'
+        };
+      }
+
+      // Check rate limiting (max 3 emails per hour)
+      if (sender.verificationSentAt) {
+        const hourAgo = new Date(Date.now() - 60 * 60 * 1000);
+        if (sender.verificationSentAt > hourAgo && sender.verificationAttempts >= 3) {
+          return {
+            success: false,
+            error: 'Too many verification emails sent. Please try again later.'
+          };
+        }
+      }
+
+      return this.sendVerificationEmail(sender);
+    } catch (error) {
+      this.logger?.error('Failed to resend verification', { error, senderId });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to resend verification'
+      };
+    }
+  }
+
+  // ============================================
+  // Private Helper Methods
+  // ============================================
+
+  private generateSenderId(): string {
+    return this.cryptoUtils?.generateSecureToken(16) || this.fallbackGenerateToken(16);
+  }
+
+  private fallbackGenerateToken(length: number): string {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+      result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+  }
+
+  private isValidEmail(email: string): boolean {
+    if (this.emailValidator) {
+      return this.emailValidator.validate(email).isValid;
+    }
+    // Fallback basic validation
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+
+  private async findSenderByEmail(email: string): Promise<SenderIdentity | undefined> {
+    return Array.from(this.senders.values()).find(s => s.email === email && !s.deletedAt);
+  }
+
+  private async findSenderByToken(token: string): Promise<SenderIdentity | undefined> {
+    return Array.from(this.senders.values()).find(s => s.verificationToken === token);
+  }
+
+  private async unsetOtherDefaults(provider: EmailProvider): Promise<void> {
+    const senders = Array.from(this.senders.values())
+      .filter(s => s.provider === provider && s.isDefault);
+
+    for (const sender of senders) {
+      sender.isDefault = false;
+      sender.updatedAt = new Date();
+      await this.saveSenderToDatabase(sender);
+    }
+  }
+
+  private async loadSendersFromDatabase(): Promise<void> {
+    // TODO: Implement database loading
+    // For now, no-op
+  }
+
+  private async saveSenderToDatabase(sender: SenderIdentity): Promise<void> {
+    // TODO: Implement database persistence
+    // For now, just update in-memory map
+    this.senders.set(sender.id, sender);
+  }
+}