@bernierllc/sender-identity-verification 1.0.0

package/dist/SenderIdentityVerification.js

@@ -0,0 +1,643 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SenderIdentityVerification = void 0;
+const types_js_1 = require("./types.js");
+const SendGridProvider_js_1 = require("./providers/SendGridProvider.js");
+const MailgunProvider_js_1 = require("./providers/MailgunProvider.js");
+const SESProvider_js_1 = require("./providers/SESProvider.js");
+const SMTPProvider_js_1 = require("./providers/SMTPProvider.js");
+const verification_email_js_1 = require("./templates/verification-email.js");
+const domain_extractor_js_1 = require("./utils/domain-extractor.js");
+/**
+ * Sender identity verification service
+ */
+class SenderIdentityVerification {
+    constructor(config) {
+        this.config = config;
+        this.senders = new Map();
+        // Initialize domain verification from config if provided
+        if (config.domainVerificationConfig?.instance) {
+            this.domainVerification = config.domainVerificationConfig.instance;
+        }
+    }
+    /**
+     * Initialize service and register with NeverHub
+     */
+    async initialize() {
+        // 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) {
+        try {
+            // 1. Validate email format
+            if (!this.isValidEmail(input.email)) {
+                return {
+                    success: false,
+                    error: 'Invalid email format'
+                };
+            }
+            // 2. Extract domain
+            const domain = (0, domain_extractor_js_1.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 = {
+                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 ? types_js_1.SenderStatus.VERIFIED : types_js_1.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) {
+        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 = types_js_1.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: (0, verification_email_js_1.buildVerificationEmailHtml)(sender, verificationUrl),
+                    text: (0, verification_email_js_1.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) {
+        try {
+            // 1. Find sender by token
+            const sender = await this.findSenderByToken(token);
+            if (!sender) {
+                return {
+                    success: false,
+                    senderId: '',
+                    status: types_js_1.SenderStatus.FAILED,
+                    message: 'Invalid verification token',
+                    errors: ['Token not found or already used']
+                };
+            }
+            // 2. Check if already verified
+            if (sender.status === types_js_1.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 = types_js_1.SenderStatus.EXPIRED;
+                sender.updatedAt = new Date();
+                await this.saveSenderToDatabase(sender);
+                return {
+                    success: false,
+                    senderId: sender.id,
+                    status: types_js_1.SenderStatus.EXPIRED,
+                    message: 'Verification token expired. Please request a new verification email.',
+                    errors: ['Token expired']
+                };
+            }
+            // 4. Check if locked
+            if (sender.status === types_js_1.SenderStatus.LOCKED) {
+                return {
+                    success: false,
+                    senderId: sender.id,
+                    status: types_js_1.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 = types_js_1.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: types_js_1.SenderStatus.FAILED,
+                    message: 'Provider verification failed',
+                    errors: sender.validationErrors
+                };
+            }
+            // 6. Mark as verified
+            sender.status = types_js_1.SenderStatus.VERIFIED;
+            sender.verifiedAt = new Date();
+            sender.verificationToken = undefined;
+            sender.providerSenderId = providerResult.data?.providerId;
+            sender.providerMetadata = providerResult.data?.metadata;
+            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: types_js_1.SenderStatus.FAILED,
+                message: error instanceof Error ? error.message : 'Verification failed',
+                errors: [error instanceof Error ? error.message : 'Unknown error']
+            };
+        }
+    }
+    /**
+     * Verify sender with email provider
+     */
+    async verifyWithProvider(sender) {
+        switch (sender.provider) {
+            case types_js_1.EmailProvider.SENDGRID:
+                if (this.config.sendgridApiKey) {
+                    const provider = new SendGridProvider_js_1.SendGridProvider(this.config.sendgridApiKey);
+                    return provider.verifySender(sender);
+                }
+                return { success: false, error: 'SendGrid API key not configured' };
+            case types_js_1.EmailProvider.MAILGUN:
+                if (this.config.mailgunApiKey) {
+                    const provider = new MailgunProvider_js_1.MailgunProvider(this.config.mailgunApiKey);
+                    return provider.verifySender(sender);
+                }
+                return { success: true, data: {} }; // Mailgun doesn't require verification
+            case types_js_1.EmailProvider.SES:
+                if (this.config.sesAccessKey && this.config.sesSecretKey && this.config.sesRegion) {
+                    const provider = new SESProvider_js_1.SESProvider(this.config.sesAccessKey, this.config.sesSecretKey, this.config.sesRegion);
+                    return provider.verifySender(sender);
+                }
+                return { success: false, error: 'SES credentials not configured' };
+            case types_js_1.EmailProvider.SMTP: {
+                const provider = new SMTPProvider_js_1.SMTPProvider();
+                return provider.verifySender(sender);
+            }
+            default:
+                return {
+                    success: false,
+                    error: `Unsupported provider: ${sender.provider}`
+                };
+        }
+    }
+    /**
+     * Get sender by ID
+     */
+    async getSender(senderId) {
+        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 = {}) {
+        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, input) {
+        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 = types_js_1.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) {
+        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) {
+        try {
+            const sender = this.senders.get(senderId);
+            if (!sender) {
+                return {
+                    success: false,
+                    error: `Sender not found: ${senderId}`
+                };
+            }
+            const errors = [];
+            const warnings = [];
+            // 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 === types_js_1.EmailProvider.SENDGRID) {
+                if (!sender.providerSenderId) {
+                    warnings.push('SendGrid sender ID not set - may need re-verification');
+                }
+            }
+            const isCompliant = errors.length === 0;
+            const result = {
+                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) {
+        const senders = Array.from(this.senders.values());
+        const defaultSender = senders.find(s => s.provider === provider &&
+            s.isDefault &&
+            s.status === types_js_1.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) {
+        try {
+            const sender = this.senders.get(senderId);
+            if (!sender) {
+                return {
+                    success: false,
+                    error: `Sender not found: ${senderId}`
+                };
+            }
+            if (sender.status === types_js_1.SenderStatus.VERIFIED) {
+                return {
+                    success: false,
+                    error: 'Sender already verified'
+                };
+            }
+            if (sender.status === types_js_1.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
+    // ============================================
+    generateSenderId() {
+        return this.cryptoUtils?.generateSecureToken(16) || this.fallbackGenerateToken(16);
+    }
+    fallbackGenerateToken(length) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        return result;
+    }
+    isValidEmail(email) {
+        if (this.emailValidator) {
+            return this.emailValidator.validate(email).isValid;
+        }
+        // Fallback basic validation
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+    async findSenderByEmail(email) {
+        return Array.from(this.senders.values()).find(s => s.email === email && !s.deletedAt);
+    }
+    async findSenderByToken(token) {
+        return Array.from(this.senders.values()).find(s => s.verificationToken === token);
+    }
+    async unsetOtherDefaults(provider) {
+        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);
+        }
+    }
+    async loadSendersFromDatabase() {
+        // TODO: Implement database loading
+        // For now, no-op
+    }
+    async saveSenderToDatabase(sender) {
+        // TODO: Implement database persistence
+        // For now, just update in-memory map
+        this.senders.set(sender.id, sender);
+    }
+}
+exports.SenderIdentityVerification = SenderIdentityVerification;

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+import { IEmailDomainVerification } from './types.js';
+/**
+ * Configuration for sender identity verification service
+ */
+export interface SenderIdentityConfig {
+    emailSenderConfig: {
+        provider?: string;
+        apiKey?: string;
+    };
+    domainVerificationConfig: {
+        instance?: IEmailDomainVerification;
+    };
+    retryConfig?: {
+        maxRetries?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    verificationBaseUrl: string;
+    verificationFromEmail: string;
+    verificationFromName: string;
+    sendgridApiKey?: string;
+    mailgunApiKey?: string;
+    sesAccessKey?: string;
+    sesSecretKey?: string;
+    sesRegion?: string;
+    databaseUrl?: string;
+}
+/**
+ * Load configuration from environment variables
+ */
+export declare function loadConfigFromEnv(overrides?: Partial<SenderIdentityConfig>): SenderIdentityConfig;