@bernierllc/email-domain-verification 1.0.0

package/.eslintrc.cjs

@@ -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.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+  env: {
+    node: true,
+    es6: true,
+    jest: true,
+  },
+};

package/README.md

@@ -0,0 +1,397 @@
+# @bernierllc/email-domain-verification
+
+Programmatic domain setup and DNS management for production email sending with multi-provider support.
+
+## Overview
+
+The Email Domain Verification package provides comprehensive programmatic domain setup and DNS record management for production email sending. It supports multiple email service providers (SendGrid, Mailgun, AWS SES), manages SPF/DKIM/DMARC records, monitors domain health, and provides NeverAdmin UI integration for domain management workflows.
+
+## Features
+
+- **Multi-Provider Support**: SendGrid, Mailgun, AWS SES
+- **DNS Record Generation**: SPF, DKIM, DMARC, MX records
+- **DKIM Key Management**: Automatic keypair generation and DNS configuration
+- **DNS Propagation Monitoring**: Track DNS propagation across multiple nameservers
+- **Health Monitoring**: Automated health checks with cron scheduling
+- **Verification History**: Complete audit trail of domain verification events
+- **NeverHub Integration**: Event publishing and service discovery
+- **NeverAdmin UI**: Admin panels for domain management
+
+## Installation
+
+```bash
+npm install @bernierllc/email-domain-verification
+```
+
+## Dependencies
+
+This package requires the following @bernierllc packages:
+
+- `@bernierllc/email-sender-manager` - Email provider integration patterns
+- `@bernierllc/crypto-utils` - DKIM keypair generation
+- `@bernierllc/logger` - Structured logging
+- `@bernierllc/neverhub-adapter` - Service discovery and event bus
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { EmailDomainVerificationService } from '@bernierllc/email-domain-verification';
+import { Logger } from '@bernierllc/logger';
+
+// Initialize service
+const logger = new Logger({ context: 'email-verification' });
+const service = new EmailDomainVerificationService({ logger });
+await service.initialize();
+
+// Setup domain verification
+const result = await service.setupDomain({
+  domain: 'example.com',
+  provider: 'sendgrid',
+  providerCredentials: {
+    apiKey: process.env.SENDGRID_API_KEY!
+  },
+  dkim: {
+    enabled: true,
+    selector: 'default',
+    keySize: 2048
+  },
+  spf: {
+    enabled: true,
+    strict: true
+  },
+  dmarc: {
+    enabled: true,
+    policy: 'quarantine',
+    reportEmail: 'dmarc@example.com'
+  }
+});
+
+if (result.success) {
+  console.log('DNS records to configure:');
+  result.dnsRecords.forEach(record => {
+    console.log(`${record.type}: ${record.host} -> ${record.value}`);
+  });
+
+  if (result.dkimConfig) {
+    console.log('DKIM Private Key (store securely):', result.dkimConfig.privateKey);
+  }
+}
+```
+
+### Check DNS Propagation
+
+```typescript
+// Check if DNS records have propagated
+const propagationResults = await service.checkPropagation(
+  'example.com',
+  result.dnsRecords
+);
+
+propagationResults.forEach(result => {
+  console.log(`${result.record.type}: ${result.propagationPercentage}% propagated`);
+  if (result.propagated && result.valuesMatch) {
+    console.log('✓ Record fully propagated and values match');
+  }
+});
+```
+
+### Verify Domain with Provider
+
+```typescript
+// Verify domain with email provider
+const verificationResult = await service.verifyDomain(
+  'example.com',
+  'sendgrid',
+  { apiKey: process.env.SENDGRID_API_KEY! }
+);
+
+if (verificationResult.success) {
+  console.log('Domain verified successfully!');
+  // Health monitoring starts automatically
+}
+```
+
+### Monitor Domain Health
+
+```typescript
+// Get current domain health
+const health = await service.getDomainHealth('example.com');
+
+console.log(`Domain: ${health.domain}`);
+console.log(`Status: ${health.verificationStatus}`);
+console.log(`Healthy: ${health.healthy}`);
+
+if (health.warnings && health.warnings.length > 0) {
+  console.log('Warnings:', health.warnings);
+}
+```
+
+### Verification History
+
+```typescript
+// Get verification history
+const history = service.getVerificationHistory('example.com', 10);
+
+history.forEach(entry => {
+  console.log(`[${entry.timestamp}] ${entry.eventType}: ${entry.details}`);
+});
+```
+
+## Provider-Specific Examples
+
+### SendGrid
+
+```typescript
+const result = await service.setupDomain({
+  domain: 'example.com',
+  provider: 'sendgrid',
+  providerCredentials: {
+    apiKey: process.env.SENDGRID_API_KEY!
+  },
+  dkim: { enabled: true, keySize: 2048 },
+  spf: { enabled: true, strict: true },
+  dmarc: {
+    enabled: true,
+    policy: 'quarantine',
+    reportEmail: 'dmarc@example.com'
+  }
+});
+```
+
+### Mailgun
+
+```typescript
+const result = await service.setupDomain({
+  domain: 'example.com',
+  provider: 'mailgun',
+  providerCredentials: {
+    apiKey: process.env.MAILGUN_API_KEY!,
+    smtpPassword: process.env.MAILGUN_SMTP_PASSWORD!
+  },
+  dkim: { enabled: true, keySize: 2048 },
+  spf: { enabled: true },
+  dmarc: { enabled: true, policy: 'none' }
+});
+```
+
+### AWS SES
+
+```typescript
+const result = await service.setupDomain({
+  domain: 'example.com',
+  provider: 'ses',
+  providerCredentials: {
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
+  },
+  dkim: { enabled: true, keySize: 2048 },
+  spf: { enabled: true },
+  dmarc: { enabled: true, policy: 'quarantine' }
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Email Domain Verification Configuration
+EMAIL_DOMAIN_VERIFICATION_HEALTH_CHECK_INTERVAL="0 */6 * * *"
+EMAIL_DOMAIN_VERIFICATION_DNS_TIMEOUT=30000
+EMAIL_DOMAIN_VERIFICATION_PROPAGATION_THRESHOLD=80
+
+# Provider API Keys (optional - can be passed per-domain)
+SENDGRID_API_KEY=""
+MAILGUN_API_KEY=""
+AWS_SES_REGION=""
+AWS_SES_ACCESS_KEY_ID=""
+AWS_SES_SECRET_ACCESS_KEY=""
+
+# NeverHub Configuration (optional)
+NEVERHUB_API_URL=""
+NEVERHUB_API_KEY=""
+```
+
+### Constructor Options
+
+```typescript
+const service = new EmailDomainVerificationService({
+  logger: customLogger,
+  neverhub: customNeverHub,
+  healthCheckInterval: '0 */6 * * *' // Cron expression
+});
+```
+
+## API Reference
+
+### EmailDomainVerificationService
+
+#### `setupDomain(config: DomainConfig): Promise<DomainVerificationResult>`
+
+Setup domain verification for an email provider. Generates DNS records, DKIM keypairs, and registers with the provider.
+
+**Parameters:**
+- `config.domain` - Domain name (e.g., 'example.com')
+- `config.provider` - Email provider ('sendgrid', 'mailgun', 'ses')
+- `config.providerCredentials` - Provider API credentials
+- `config.dkim` - DKIM configuration
+- `config.spf` - SPF configuration
+- `config.dmarc` - DMARC configuration
+
+**Returns:** Domain verification result with DNS records to configure
+
+#### `checkPropagation(domain: string, records: DNSRecord[]): Promise<DNSPropagationResult[]>`
+
+Check DNS propagation status for domain records across multiple nameservers.
+
+**Parameters:**
+- `domain` - Domain name
+- `records` - DNS records to check
+
+**Returns:** Propagation results for each record
+
+#### `verifyDomain(domain: string, provider: EmailProvider, credentials: object): Promise<DomainVerificationResult>`
+
+Verify domain with email provider. Starts health monitoring if verification succeeds.
+
+**Parameters:**
+- `domain` - Domain name
+- `provider` - Email provider
+- `credentials` - Provider API credentials
+
+**Returns:** Verification result
+
+#### `getDomainHealth(domain: string): Promise<DomainHealthStatus>`
+
+Get current domain health status.
+
+**Parameters:**
+- `domain` - Domain name
+
+**Returns:** Health status with record details
+
+#### `getVerificationHistory(domain: string, limit?: number): VerificationHistoryEntry[]`
+
+Get verification history for domain.
+
+**Parameters:**
+- `domain` - Domain name
+- `limit` - Maximum number of entries (default: 50)
+
+**Returns:** History entries
+
+#### `stopHealthMonitoring(domain: string): void`
+
+Stop automated health monitoring for domain.
+
+**Parameters:**
+- `domain` - Domain name
+
+#### `shutdown(): Promise<void>`
+
+Cleanup resources and stop all health monitoring jobs.
+
+## Integration Status
+
+- **Logger**: integrated - All verification events, DNS propagation checks, and health monitoring logged
+- **Docs-Suite**: ready - TypeDoc format, complete API reference
+- **NeverHub**: required - Event publishing for domain verification lifecycle
+- **NeverAdmin**: required - Admin UI components for domain management
+
+## NeverHub Events
+
+**Events Published:**
+- `domain.verification.initiated` - Domain verification setup started
+- `domain.propagation.checked` - DNS propagation check completed
+- `domain.verification.completed` - Verification with provider completed
+- `domain.health.unhealthy` - Health check detected issues
+
+**Events Subscribed:**
+- `email.domain.required` - Email service requests domain verification
+- `monitoring.health.check` - System-wide health check triggered
+
+## TypeScript Support
+
+This package is written in TypeScript and includes complete type definitions.
+
+```typescript
+import {
+  EmailDomainVerificationService,
+  DomainConfig,
+  DomainVerificationResult,
+  DNSRecord,
+  DKIMConfig,
+  VerificationStatus
+} from '@bernierllc/email-domain-verification';
+```
+
+## Error Handling
+
+The package provides structured error types:
+
+```typescript
+import {
+  DomainVerificationError,
+  DNSPropagationError,
+  ProviderAPIError,
+  InvalidDomainError
+} from '@bernierllc/email-domain-verification';
+
+try {
+  await service.setupDomain(config);
+} catch (error) {
+  if (error instanceof InvalidDomainError) {
+    console.error('Invalid domain:', error.message);
+  } else if (error instanceof DNSPropagationError) {
+    console.error('DNS propagation failed:', error.message);
+    // Retryable error
+  }
+}
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests once
+npm run test:run
+
+# Run with coverage
+npm run test:coverage
+```
+
+## Building
+
+```bash
+# Build TypeScript to JavaScript
+npm run build
+
+# Clean dist directory
+npm run clean
+```
+
+## Linting
+
+```bash
+# Lint source code
+npm run lint
+```
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+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.
+
+## Related Packages
+
+- [@bernierllc/email-sender-manager](../email-sender-manager) - Email sending orchestration
+- [@bernierllc/crypto-utils](../../core/crypto-utils) - Cryptographic utilities
+- [@bernierllc/logger](../../core/logger) - Structured logging
+- [@bernierllc/neverhub-adapter](../../core/neverhub-adapter) - Service discovery
+- [@bernierllc/email-suite](../../suite/email-suite) - Complete email management system

package/__mocks__/@bernierllc/crypto-utils.ts

@@ -0,0 +1,15 @@
+/*
+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 async function generateUUIDKey(): Promise<{ key: string }> {
+  return { key: `test-uuid-${Date.now()}-${Math.random().toString(36).substr(2, 9)}` };
+}
+
+export function generateSecureToken(length = 32): string {
+  return Array(length).fill(0).map(() => Math.random().toString(36).charAt(2)).join('');
+}

package/__mocks__/@bernierllc/logger.ts

@@ -0,0 +1,42 @@
+/*
+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 enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  FATAL = 4,
+  SILENT = 5
+}
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  transports?: unknown[];
+  context?: Record<string, unknown>;
+  enableCorrelation?: boolean;
+  sanitize?: boolean;
+  sanitizeFields?: string[];
+  onError?: (error: Error, transport: string) => void;
+}
+
+export class Logger {
+  constructor(_options: LoggerOptions) {}
+
+  debug(_message: string, _metadata?: Record<string, unknown>): void {}
+  info(_message: string, _metadata?: Record<string, unknown>): void {}
+  warn(_message: string, _metadata?: Record<string, unknown>): void {}
+  error(_message: string, _metadata?: Record<string, unknown>): void {}
+  fatal(_message: string, _metadata?: Record<string, unknown>): void {}
+}
+
+export class ConsoleTransport {
+  constructor(_options: { level?: LogLevel } = {}) {}
+}
+
+export const createLogger = (options: LoggerOptions = { level: LogLevel.SILENT }) => new Logger(options);

package/__mocks__/@bernierllc/neverhub-adapter.ts

@@ -0,0 +1,17 @@
+/*
+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 class NeverHubAdapter {
+  static async detect(): Promise<boolean> {
+    return false;
+  }
+
+  async register(_config: Record<string, unknown>): Promise<void> {}
+  async publishEvent(_event: Record<string, unknown>): Promise<void> {}
+  async subscribe(_eventType: string, _handler: (event: unknown) => void): Promise<void> {}
+}