@bernierllc/sender-identity-verification 1.0.0

package/.env.test

@@ -0,0 +1,8 @@
+
+NAMECOM_TESTING_API_KEY=b5944374cc5398daea865ba0780906bca8bf4b14
+NAMECOM_TESTING_USERNAME=mkbernier-test
+NAMECOM_API_KEY=43bb0dbe1e762ce1900a459e8ebd4076e006418f
+NAMECOM_KEY_NAME=domain_testing_key
+SENDGRID_API_KEY=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
+
+TESTING_DOMAIN=bernierllc.com

package/.eslintrc.js

@@ -0,0 +1,30 @@
+/*
+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',
+    project: './tsconfig.json'
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/explicit-function-return-type': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { 'argsIgnorePattern': '^_' }],
+    'no-console': 'off'
+  },
+  env: {
+    node: true,
+    jest: true
+  }
+};

package/README.md

@@ -0,0 +1,376 @@
+# @bernierllc/sender-identity-verification
+
+Individual sender email address verification service for email production compliance. Manages sender identity creation, email address verification workflows, provider compliance validation, and administrative interfaces.
+
+## 📋 Overview
+
+This package enables production email sending by verifying individual sender identities and ensuring provider compliance for email addresses. Works in conjunction with `@bernierllc/email-domain-verification` to ensure complete email sending compliance.
+
+**Version**: 1.0.0
+**Category**: service
+**Priority**: critical
+
+## 🚀 Installation
+
+```bash
+npm install @bernierllc/sender-identity-verification
+```
+
+## 📦 Dependencies
+
+This package requires the following dependencies:
+
+- `@bernierllc/email-sender` - For sending verification emails
+- `@bernierllc/logger` - For audit logging
+- `@bernierllc/neverhub-adapter` - For service mesh integration
+- `@bernierllc/crypto-utils` - For secure token generation
+- `@bernierllc/retry-policy` - For retry logic
+- `@bernierllc/validators-email` - For email validation
+
+**Note**: `@bernierllc/email-domain-verification` is required but not yet published. Domain verification features will be available when this dependency is released.
+
+## 🎯 Quick Start
+
+```typescript
+import { SenderIdentityVerification, EmailProvider } from '@bernierllc/sender-identity-verification';
+
+// Initialize the service
+const service = new SenderIdentityVerification({
+  verificationBaseUrl: 'https://app.example.com',
+  verificationFromEmail: 'noreply@example.com',
+  verificationFromName: 'Example Verification',
+  sendgridApiKey: process.env.SENDGRID_API_KEY,
+  emailSenderConfig: {},
+  domainVerificationConfig: {}
+});
+
+await service.initialize();
+
+// Create a sender
+const result = await service.createSender({
+  email: 'hello@example.com',
+  name: 'Hello Team',
+  replyToEmail: 'support@example.com',
+  provider: EmailProvider.SENDGRID,
+  isDefault: true
+});
+
+console.log('Sender created:', result.data);
+// Verification email automatically sent to hello@example.com
+```
+
+## 📚 API Reference
+
+### SenderIdentityVerification
+
+Main service class for managing sender identities.
+
+#### Constructor
+
+```typescript
+new SenderIdentityVerification(config: SenderIdentityConfig)
+```
+
+**Configuration Options**:
+
+```typescript
+interface SenderIdentityConfig {
+  // Verification settings
+  verificationBaseUrl: string;        // Base URL for verification links
+  verificationFromEmail: string;       // From email for verification emails
+  verificationFromName: string;        // From name for verification emails
+
+  // Provider API keys
+  sendgridApiKey?: string;            // SendGrid API key
+  mailgunApiKey?: string;             // Mailgun API key
+  sesAccessKey?: string;              // AWS SES access key
+  sesSecretKey?: string;              // AWS SES secret key
+  sesRegion?: string;                 // AWS SES region (default: 'us-east-1')
+
+  // Email sender configuration
+  emailSenderConfig: object;
+
+  // Domain verification configuration
+  domainVerificationConfig: object;
+
+  // Retry configuration
+  retryConfig?: object;
+
+  // Database configuration
+  databaseUrl?: string;
+}
+```
+
+#### Methods
+
+##### `createSender(input: CreateSenderInput): Promise<SenderIdentityResult<SenderIdentity>>`
+
+Create a new sender identity.
+
+```typescript
+const result = await service.createSender({
+  email: 'hello@example.com',
+  name: 'Hello Team',
+  replyToEmail: 'support@example.com',
+  replyToName: 'Support Team',
+  provider: EmailProvider.SENDGRID,
+  isDefault: true,
+  skipVerification: false  // Set to true for testing
+});
+```
+
+##### `verifySender(token: string): Promise<VerificationResult>`
+
+Verify a sender using the verification token from the email.
+
+```typescript
+const result = await service.verifySender('abc123token');
+
+if (result.success) {
+  console.log('Sender verified:', result.senderId);
+}
+```
+
+##### `getSender(senderId: string): Promise<SenderIdentityResult<SenderIdentity>>`
+
+Get sender by ID.
+
+```typescript
+const result = await service.getSender('sender-id-123');
+console.log('Sender:', result.data);
+```
+
+##### `listSenders(options?: ListSendersOptions): Promise<SenderIdentityResult<SenderIdentity[]>>`
+
+List senders with optional filtering.
+
+```typescript
+const result = await service.listSenders({
+  provider: EmailProvider.SENDGRID,
+  status: SenderStatus.VERIFIED,
+  isActive: true,
+  limit: 50,
+  offset: 0
+});
+```
+
+##### `updateSender(senderId: string, input: UpdateSenderInput): Promise<SenderIdentityResult<SenderIdentity>>`
+
+Update sender details.
+
+```typescript
+const result = await service.updateSender('sender-id-123', {
+  name: 'Updated Name',
+  replyToEmail: 'new-support@example.com',
+  isDefault: true
+});
+```
+
+##### `deleteSender(senderId: string): Promise<SenderIdentityResult<void>>`
+
+Soft delete a sender.
+
+```typescript
+const result = await service.deleteSender('sender-id-123');
+```
+
+##### `checkCompliance(senderId: string): Promise<SenderIdentityResult<ComplianceCheckResult>>`
+
+Check provider compliance for a sender.
+
+```typescript
+const result = await service.checkCompliance('sender-id-123');
+
+if (result.success) {
+  console.log('Compliance status:', result.data?.isCompliant);
+  console.log('Domain verified:', result.data?.checks.domainVerified);
+  console.log('SPF valid:', result.data?.checks.spfValid);
+  console.log('DKIM valid:', result.data?.checks.dkimValid);
+}
+```
+
+##### `getDefaultSender(provider: EmailProvider): Promise<SenderIdentityResult<SenderIdentity>>`
+
+Get the default sender for a provider.
+
+```typescript
+const result = await service.getDefaultSender(EmailProvider.SENDGRID);
+console.log('Default sender:', result.data?.email);
+```
+
+##### `resendVerification(senderId: string): Promise<SenderIdentityResult<void>>`
+
+Resend verification email.
+
+```typescript
+const result = await service.resendVerification('sender-id-123');
+```
+
+## 🔌 Integration Status
+
+- **Logger**: integrated - Critical for audit trail of sender verification events
+- **Docs-Suite**: ready - Complete API documentation with TypeScript interfaces
+- **NeverHub**: required - Service mesh integration for event publishing
+
+## 🔒 Security Considerations
+
+### Verification Token Security
+- Tokens are cryptographically secure (32 bytes, URL-safe)
+- Single-use tokens (cleared after successful verification)
+- Time-limited (24 hour expiration)
+- Stored securely in database
+
+### Rate Limiting
+- Max 3 verification emails per hour per sender
+- Prevents abuse and spam
+- Locks sender after too many failed attempts
+
+### Provider API Key Storage
+- API keys stored in environment variables (never in code)
+- API keys never logged or exposed in responses
+- Encrypted at rest in database (if persisting config)
+
+## 📊 Monitoring & Observability
+
+### Key Metrics to Track
+
+- `sender.created` - Senders created
+- `sender.verified` - Senders verified
+- `sender.failed` - Verification failures
+- `sender.locked` - Senders locked
+- `verification.email_sent` - Verification emails sent
+- `verification.token_validated` - Token validations
+- `compliance.checked` - Compliance checks
+- `compliance.passed` - Compliance passes
+
+### Critical Events to Log
+
+```typescript
+logger.info('sender.created', { senderId, email, provider });
+logger.info('sender.verified', { senderId, email, verifiedAt });
+logger.warn('sender.verification_failed', { senderId, reason });
+logger.error('sender.locked', { senderId, attempts });
+logger.audit('sender.deleted', { senderId, email, deletedBy });
+```
+
+## 🔗 Related Packages
+
+### Dependencies
+- [@bernierllc/email-sender](../email-sender) - Email sending functionality
+- [@bernierllc/logger](../logger) - Logging infrastructure
+- [@bernierllc/neverhub-adapter](../neverhub-adapter) - Service mesh integration
+- [@bernierllc/crypto-utils](../crypto-utils) - Cryptographic utilities
+- [@bernierllc/retry-policy](../retry-policy) - Retry logic
+- [@bernierllc/validators-email](../validators-email) - Email validation
+
+### Dependent Packages
+- [@bernierllc/email-manager](../email-manager) - Email management suite
+- [@bernierllc/email-admin-ui](../email-admin-ui) - Email administration UI
+- [@bernierllc/email-webhook-events](../email-webhook-events) - Email event tracking
+
+## 📝 Examples
+
+### Basic Sender Creation
+
+```typescript
+import { SenderIdentityVerification, EmailProvider } from '@bernierllc/sender-identity-verification';
+
+const service = new SenderIdentityVerification({
+  verificationBaseUrl: 'https://app.example.com',
+  verificationFromEmail: 'noreply@example.com',
+  verificationFromName: 'Example Verification',
+  sendgridApiKey: process.env.SENDGRID_API_KEY,
+  emailSenderConfig: {},
+  domainVerificationConfig: {}
+});
+
+await service.initialize();
+
+// Create sender
+const result = await service.createSender({
+  email: 'hello@example.com',
+  name: 'Hello Team',
+  replyToEmail: 'support@example.com',
+  provider: EmailProvider.SENDGRID,
+  isDefault: true
+});
+
+console.log('Sender created:', result.data);
+```
+
+### Verify Sender Email
+
+```typescript
+// User clicks verification link in email
+// Link contains token: https://app.example.com/verify-sender?token=abc123
+
+const verifyResult = await service.verifySender('abc123');
+
+if (verifyResult.success) {
+  console.log('Sender verified:', verifyResult.senderId);
+  console.log('Verified at:', verifyResult.verifiedAt);
+} else {
+  console.error('Verification failed:', verifyResult.message);
+}
+```
+
+### List Verified Senders
+
+```typescript
+// List all verified senders for SendGrid
+const sendersResult = await service.listSenders({
+  provider: EmailProvider.SENDGRID,
+  status: SenderStatus.VERIFIED,
+  isActive: true
+});
+
+console.log('Verified SendGrid senders:', sendersResult.data);
+```
+
+### Check Compliance
+
+```typescript
+// Check compliance for a sender
+const complianceResult = await service.checkCompliance('sender-id-123');
+
+if (complianceResult.success) {
+  const compliance = complianceResult.data!;
+
+  console.log('Compliance Status:', compliance.isCompliant ? 'PASS' : 'FAIL');
+  console.log('Domain Verified:', compliance.checks.domainVerified);
+  console.log('SPF Valid:', compliance.checks.spfValid);
+  console.log('DKIM Valid:', compliance.checks.dkimValid);
+
+  if (!compliance.isCompliant) {
+    console.log('Errors:', compliance.errors);
+  }
+}
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue**: Domain not verified error
+**Solution**: Ensure the domain is verified using `@bernierllc/email-domain-verification` before creating senders
+
+**Issue**: Sender already exists
+**Solution**: Check for existing senders with `listSenders()` before creating new ones
+
+**Issue**: Verification token expired
+**Solution**: Use `resendVerification()` to send a new verification email
+
+**Issue**: Too many verification emails
+**Solution**: Rate limiting prevents more than 3 emails per hour - wait before retrying
+
+## 📜 License
+
+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.
+
+## 🤝 Support
+
+For issues, questions, or contributions, please contact Bernier LLC.