@bernierllc/sender-identity-verification 1.0.0

package/src/config.ts

@@ -0,0 +1,81 @@
+/*
+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 { IEmailDomainVerification } from './types.js';
+
+/**
+ * Configuration for sender identity verification service
+ */
+export interface SenderIdentityConfig {
+  // Email sender configuration (for sending verification emails)
+  emailSenderConfig: {
+    provider?: string;
+    apiKey?: string;
+  };
+
+  // Domain verification configuration
+  domainVerificationConfig: {
+    instance?: IEmailDomainVerification;
+  };
+
+  // Retry configuration
+  retryConfig?: {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+
+  // Verification settings
+  verificationBaseUrl: string;
+  verificationFromEmail: string;
+  verificationFromName: string;
+
+  // Provider API keys
+  sendgridApiKey?: string;
+  mailgunApiKey?: string;
+  sesAccessKey?: string;
+  sesSecretKey?: string;
+  sesRegion?: string;
+
+  // Database configuration
+  databaseUrl?: string;
+}
+
+/**
+ * Load configuration from environment variables
+ */
+export function loadConfigFromEnv(overrides: Partial<SenderIdentityConfig> = {}): SenderIdentityConfig {
+  const config: SenderIdentityConfig = {
+    verificationBaseUrl: process.env.SENDER_VERIFICATION_BASE_URL || overrides.verificationBaseUrl || '',
+    verificationFromEmail: process.env.SENDER_VERIFICATION_FROM_EMAIL || overrides.verificationFromEmail || 'noreply@example.com',
+    verificationFromName: process.env.SENDER_VERIFICATION_FROM_NAME || overrides.verificationFromName || 'Email Verification',
+
+    sendgridApiKey: process.env.SENDGRID_API_KEY || overrides.sendgridApiKey,
+    mailgunApiKey: process.env.MAILGUN_API_KEY || overrides.mailgunApiKey,
+    sesAccessKey: process.env.AWS_SES_ACCESS_KEY || overrides.sesAccessKey,
+    sesSecretKey: process.env.AWS_SES_SECRET_KEY || overrides.sesSecretKey,
+    sesRegion: process.env.AWS_SES_REGION || overrides.sesRegion || 'us-east-1',
+
+    databaseUrl: process.env.DATABASE_URL || overrides.databaseUrl,
+
+    emailSenderConfig: overrides.emailSenderConfig || {},
+    domainVerificationConfig: overrides.domainVerificationConfig || {},
+    retryConfig: overrides.retryConfig
+  };
+
+  // Log configuration (without sensitive data)
+  console.log('⚙️ Sender Identity Verification Configuration:');
+  console.log(`   └── Verification Base URL: ${config.verificationBaseUrl || '(not set)'}`);
+  console.log(`   └── From Email: ${config.verificationFromEmail}`);
+  console.log(`   └── SendGrid: ${config.sendgridApiKey ? '***configured***' : '(not set)'}`);
+  console.log(`   └── Mailgun: ${config.mailgunApiKey ? '***configured***' : '(not set)'}`);
+  console.log(`   └── SES: ${config.sesAccessKey ? '***configured***' : '(not set)'}`);
+  console.log(`   └── Database: ${config.databaseUrl ? '***configured***' : '(not set)'}`);
+
+  return config;
+}

package/src/errors.ts

@@ -0,0 +1,64 @@
+/*
+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 { SenderIdentityResult } from './types.js';
+
+/**
+ * Sender error codes
+ */
+export enum SenderErrorCode {
+  SENDER_NOT_FOUND = 'SENDER_NOT_FOUND',
+  SENDER_ALREADY_EXISTS = 'SENDER_ALREADY_EXISTS',
+  SENDER_LOCKED = 'SENDER_LOCKED',
+  VERIFICATION_EXPIRED = 'VERIFICATION_EXPIRED',
+  VERIFICATION_FAILED = 'VERIFICATION_FAILED',
+  DOMAIN_NOT_VERIFIED = 'DOMAIN_NOT_VERIFIED',
+  PROVIDER_ERROR = 'PROVIDER_ERROR',
+  INVALID_EMAIL = 'INVALID_EMAIL',
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+}
+
+/**
+ * Custom error class for sender verification errors
+ */
+export class SenderVerificationError extends Error {
+  constructor(
+    message: string,
+    public code: SenderErrorCode,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'SenderVerificationError';
+    Object.setPrototypeOf(this, SenderVerificationError.prototype);
+  }
+}
+
+/**
+ * Error handling wrapper
+ */
+export function handleSenderError(error: unknown): SenderIdentityResult<never> {
+  if (error instanceof SenderVerificationError) {
+    return {
+      success: false,
+      error: error.message,
+      errors: [error.code]
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+
+  return {
+    success: false,
+    error: 'Unknown error occurred'
+  };
+}

package/src/global.d.ts

@@ -0,0 +1,24 @@
+/*
+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.
+*/
+
+// Node.js global types
+declare const process: {
+  env: {
+    [key: string]: string | undefined;
+  };
+};
+
+// Fetch API types (minimal declaration)
+declare function fetch(url: string, init?: {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}): Promise<{
+  ok: boolean;
+  json(): Promise<unknown>;
+}>;

package/src/index.ts

@@ -0,0 +1,24 @@
+/*
+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.
+*/
+
+export { SenderIdentityVerification } from './SenderIdentityVerification.js';
+export { SenderIdentityConfig, loadConfigFromEnv } from './config.js';
+export { SenderVerificationError, SenderErrorCode, handleSenderError } from './errors.js';
+export {
+  SenderIdentity,
+  SenderStatus,
+  EmailProvider,
+  CreateSenderInput,
+  UpdateSenderInput,
+  VerificationResult,
+  ComplianceCheckResult,
+  ListSendersOptions,
+  SenderIdentityResult,
+  DomainVerificationStatus,
+  IEmailDomainVerification
+} from './types.js';

package/src/providers/MailgunProvider.ts

@@ -0,0 +1,35 @@
+/*
+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, SenderIdentityResult } from '../types.js';
+
+/**
+ * Mailgun provider for sender verification
+ * Note: Mailgun doesn't have sender-level verification, only domain verification
+ */
+export class MailgunProvider {
+  constructor(_apiKey: string) {
+    // apiKey parameter reserved for future Mailgun API integration
+    void _apiKey;
+  }
+
+  /**
+   * Verify sender with Mailgun
+   * Mailgun only verifies domains, not individual senders
+   */
+  async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
+    // Mailgun doesn't require individual sender verification
+    // Domain verification is handled by @bernierllc/email-domain-verification
+    return {
+      success: true,
+      data: {
+        note: 'Mailgun does not require individual sender verification'
+      }
+    };
+  }
+}

package/src/providers/SESProvider.ts

@@ -0,0 +1,51 @@
+/*
+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, SenderIdentityResult } from '../types.js';
+
+/**
+ * AWS SES provider for sender verification
+ */
+export class SESProvider {
+  constructor(
+    _accessKey: string,
+    _secretKey: string,
+    _region: string
+  ) {
+    // Parameters reserved for future AWS SDK integration
+    void _accessKey;
+    void _secretKey;
+    void _region;
+  }
+
+  /**
+   * Verify sender with AWS SES
+   * TODO: Implement AWS SDK integration for SES VerifyEmailIdentity
+   */
+  async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
+    try {
+      // TODO: Call SES VerifyEmailIdentity API
+      // For now, return success (stub implementation)
+      // Real implementation would use AWS SDK:
+      // const ses = new SES({ region: this.region, credentials: {...} });
+      // await ses.verifyEmailIdentity({ EmailAddress: sender.email });
+
+      return {
+        success: true,
+        data: {
+          note: 'SES verification stubbed - AWS SDK integration pending'
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'SES verification failed'
+      };
+    }
+  }
+}

package/src/providers/SMTPProvider.ts

@@ -0,0 +1,29 @@
+/*
+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, SenderIdentityResult } from '../types.js';
+
+/**
+ * SMTP provider for sender verification
+ * Note: SMTP doesn't require provider-level verification
+ */
+export class SMTPProvider {
+  /**
+   * Verify sender with SMTP
+   * SMTP doesn't require provider verification - just email validation
+   */
+  async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
+    // SMTP doesn't require provider-level verification
+    return {
+      success: true,
+      data: {
+        note: 'SMTP does not require provider-level verification'
+      }
+    };
+  }
+}

package/src/providers/SendGridProvider.ts

@@ -0,0 +1,108 @@
+/*
+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, SenderIdentityResult } from '../types.js';
+
+/**
+ * SendGrid provider for sender verification
+ */
+export class SendGridProvider {
+  constructor(private apiKey: string) {}
+
+  /**
+   * Verify sender with SendGrid
+   */
+  async verifySender(sender: SenderIdentity): Promise<SenderIdentityResult<{
+    providerId: string;
+    metadata: Record<string, unknown>;
+  }>> {
+    try {
+      if (!this.apiKey) {
+        return {
+          success: false,
+          error: 'SendGrid API key not configured'
+        };
+      }
+
+      // Create verified sender in SendGrid
+      const response = await this.sendGridRequest('POST', '/verified_senders', {
+        nickname: sender.name,
+        from_email: sender.email,
+        from_name: sender.name,
+        reply_to: sender.replyToEmail,
+        reply_to_name: sender.replyToName,
+        address: '123 Main St',
+        city: 'Anytown',
+        state: 'CA', // Must be 2-character state code per SendGrid API requirements
+        zip: '12345',
+        country: 'US'
+      });
+
+      if (!response.success) {
+        return {
+          success: false,
+          error: 'SendGrid verification failed',
+          errors: [response.error || 'Unknown SendGrid error']
+        };
+      }
+
+      return {
+        success: true,
+        data: {
+          providerId: response.data?.id as string || '',
+          metadata: response.data || {}
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'SendGrid verification failed'
+      };
+    }
+  }
+
+  /**
+   * Make SendGrid API request
+   */
+  private async sendGridRequest(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>
+  ): Promise<SenderIdentityResult<Record<string, unknown>>> {
+    try {
+      const response = await fetch(`https://api.sendgrid.com/v3${path}`, {
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json'
+        },
+        body: body ? JSON.stringify(body) : undefined
+      });
+
+      const data = await response.json() as { errors?: Array<{ message: string }>; id?: string };
+
+      if (!response.ok) {
+        return {
+          success: false,
+          error: data.errors?.[0]?.message || 'SendGrid API error',
+          errors: data.errors?.map((e) => e.message)
+        };
+      }
+
+      return {
+        success: true,
+        data: data as Record<string, unknown>
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'SendGrid request failed'
+      };
+    }
+  }
+}

package/src/templates/verification-email.ts

@@ -0,0 +1,67 @@
+/*
+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 } from '../types.js';
+
+/**
+ * Build HTML verification email
+ */
+export function buildVerificationEmailHtml(sender: SenderIdentity, verificationUrl: string): string {
+  return `
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <style>
+        body { font-family: Arial, sans-serif; line-height: 1.6; color: #333; }
+        .container { max-width: 600px; margin: 0 auto; padding: 20px; }
+        .button { background-color: #007bff; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; display: inline-block; margin: 20px 0; }
+        .footer { margin-top: 40px; padding-top: 20px; border-top: 1px solid #ddd; font-size: 12px; color: #666; }
+      </style>
+    </head>
+    <body>
+      <div class="container">
+        <h1>Verify Your Sender Email Address</h1>
+        <p>Hello ${sender.name},</p>
+        <p>You've added <strong>${sender.email}</strong> as a sender email address for ${sender.provider}.</p>
+        <p>To complete the verification process, please click the button below:</p>
+        <a href="${verificationUrl}" class="button">Verify Email Address</a>
+        <p>Or copy and paste this URL into your browser:</p>
+        <p>${verificationUrl}</p>
+        <p><strong>This link will expire in 24 hours.</strong></p>
+        <div class="footer">
+          <p>If you didn't request this verification, please ignore this email.</p>
+          <p>Sender ID: ${sender.id}</p>
+        </div>
+      </div>
+    </body>
+    </html>
+  `;
+}
+
+/**
+ * Build plain text verification email
+ */
+export function buildVerificationEmailText(sender: SenderIdentity, verificationUrl: string): string {
+  return `
+Verify Your Sender Email Address
+
+Hello ${sender.name},
+
+You've added ${sender.email} as a sender email address for ${sender.provider}.
+
+To complete the verification process, please visit:
+
+${verificationUrl}
+
+This link will expire in 24 hours.
+
+If you didn't request this verification, please ignore this email.
+
+Sender ID: ${sender.id}
+  `.trim();
+}

package/src/types.ts

@@ -0,0 +1,163 @@
+/*
+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.
+*/
+
+/**
+ * Sender identity record
+ */
+export interface SenderIdentity {
+  id: string;
+  email: string;
+  name: string;
+  replyToEmail?: string;
+  replyToName?: string;
+  domain: string;
+  provider: EmailProvider;
+
+  // Status tracking
+  status: SenderStatus;
+  isDefault: boolean;
+  isActive: boolean;
+
+  // Verification
+  verifiedAt?: Date;
+  verificationToken?: string;
+  verificationSentAt?: Date;
+  verificationExpiresAt?: Date;
+  verificationAttempts: number;
+
+  // Provider-specific data
+  providerSenderId?: string; // SendGrid verified sender ID
+  providerMetadata?: Record<string, unknown>;
+
+  // Validation
+  lastValidated?: Date;
+  validationErrors?: string[];
+
+  // Timestamps
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date;
+}
+
+/**
+ * Sender status enum
+ */
+export enum SenderStatus {
+  PENDING = 'pending',           // Created, awaiting verification
+  VERIFICATION_SENT = 'verification_sent', // Verification email sent
+  VERIFIED = 'verified',         // Email verified, ready to use
+  FAILED = 'failed',             // Verification failed
+  EXPIRED = 'expired',           // Verification token expired
+  LOCKED = 'locked',             // Too many failed attempts
+  INACTIVE = 'inactive',         // Deactivated by admin
+}
+
+/**
+ * Email provider enum
+ */
+export enum EmailProvider {
+  SENDGRID = 'sendgrid',
+  MAILGUN = 'mailgun',
+  SES = 'ses',
+  SMTP = 'smtp',
+}
+
+/**
+ * Sender creation input
+ */
+export interface CreateSenderInput {
+  email: string;
+  name: string;
+  replyToEmail?: string;
+  replyToName?: string;
+  provider: EmailProvider;
+  isDefault?: boolean;
+  skipVerification?: boolean; // For testing/dev
+}
+
+/**
+ * Sender update input
+ */
+export interface UpdateSenderInput {
+  name?: string;
+  replyToEmail?: string;
+  replyToName?: string;
+  isDefault?: boolean;
+  isActive?: boolean;
+}
+
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+  success: boolean;
+  senderId: string;
+  status: SenderStatus;
+  message: string;
+  verifiedAt?: Date;
+  errors?: string[];
+}
+
+/**
+ * Provider compliance check result
+ */
+export interface ComplianceCheckResult {
+  isCompliant: boolean;
+  checks: {
+    domainVerified: boolean;
+    spfValid: boolean;
+    dkimValid: boolean;
+    emailFormat: boolean;
+  };
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Sender list options
+ */
+export interface ListSendersOptions {
+  provider?: EmailProvider;
+  status?: SenderStatus;
+  isActive?: boolean;
+  domain?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Package result wrapper
+ */
+export interface SenderIdentityResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  errors?: string[];
+}
+
+/**
+ * Domain verification status (interface for missing @bernierllc/email-domain-verification)
+ * TODO: Replace with actual import when email-domain-verification package is available
+ */
+export interface DomainVerificationStatus {
+  isVerified: boolean;
+  domain: string;
+  verificationUrl?: string;
+  dnsRecords?: {
+    spf?: { isValid: boolean };
+    dkim?: { isValid: boolean };
+  };
+}
+
+/**
+ * Email domain verification interface (stub for missing dependency)
+ * TODO: Replace with actual @bernierllc/email-domain-verification when available
+ */
+export interface IEmailDomainVerification {
+  getDomainStatus(domain: string): Promise<DomainVerificationStatus>;
+}

package/src/utils/domain-extractor.ts

@@ -0,0 +1,18 @@
+/*
+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.
+*/
+
+/**
+ * Extract domain from email address
+ */
+export function extractDomain(email: string): string {
+  const parts = email.split('@');
+  if (parts.length !== 2) {
+    throw new Error(`Invalid email format: ${email}`);
+  }
+  return parts[1].toLowerCase();
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020", "DOM"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}