@push.rocks/smartmta 14.2.0 → 14.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmta",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "description": "A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.",
   "keywords": [
     "mta",

package/readme.md

@@ -518,7 +518,9 @@ email.getEnvelopeTo();     // ['alice@example.com', 'archive@example.org']
 email.getAllRecipients();  // the same list: the RCPT TO of every delivery
 ```
 
-The `Email` of a received message (hook contexts, `processEmailByMode()`, `dispatchAcceptedEnvelope()`) always carries the SMTP envelope it was accepted with. `processEmailByMode(emailOrBuffer, session)` sets it from `session.envelope.rcptTo` on every call and throws when that list is empty. `sendEmail()` checks every recipient against the suppression list and takes suppressed addresses out of the envelope.
+`new Email({ ..., envelopeTo })` sets the envelope at construction. With an envelope, `to`, `cc` and `bcc` are the message's header fields: they take no part in delivery, and every copy of the message (one per MX domain or per recipient) shows the same To and Cc. Bcc is never written. No field entry is refused: CR and LF are removed, the entry is trimmed, and an entry that is then empty is dropped.
+
+The `Email` of a received message (hook contexts, `processEmailByMode()`, `dispatchAcceptedEnvelope()`) always carries the SMTP envelope it was accepted with, and its `to` and `cc` are the addresses of the message's To and Cc fields, in order; a relayed copy carries them, never addresses taken from the envelope, and a message without a To field is relayed without one. Display names, groups and comments are not carried: a relayed copy's To and Cc list the addresses only (a group's member addresses among them). A To or Cc entry that is not a valid mailbox address never refuses the message: relayed copies carry it, and `deliver` and `store` routes hand on the received bytes unchanged. `X-Forwarded-To` is added only to a forwarded copy with exactly one envelope recipient and names that recipient. `processEmailByMode(emailOrBuffer, session)` sets the envelope from `session.envelope.rcptTo` on every call and throws when that list is empty. `sendEmail()` and `enqueue()` never change the caller's `Email`: the queue item holds its own copy, whose envelope is the recipients at that call minus any address on the suppression list.
 
 ### 📮 Delivery Modes
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmta',
-  version: '14.2.0',
+  version: '14.3.0',
   description: 'A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration.'
 }

package/ts/mail/core/classes.email.ts

@@ -24,6 +24,13 @@ export interface IEmailOptions {
   priority?: 'high' | 'normal' | 'low'; // Optional email priority
   skipAdvancedValidation?: boolean; // Skip advanced validation for special cases
   variables?: Record<string, any>; // Template variables for placeholder replacement
+  /**
+   * The SMTP envelope recipients (RCPT TO), as setEnvelopeTo sets them. With
+   * an envelope, `to`, `cc` and `bcc` are the message's header fields: they
+   * take no part in delivery, every copy of the email shows the same entries,
+   * and no entry is refused (see headerFieldRecipients).
+   */
+  envelopeTo?: string[];
 }
 
 /**
@@ -70,13 +77,21 @@ export class Email {
     }
     this.from = options.from;
 
-    // Handle to addresses (single or multiple)
-    this.to = options.to ? this.parseRecipients(options.to) : [];
-    
-    // Handle optional cc and bcc
-    this.cc = options.cc ? this.parseRecipients(options.cc) : [];
-    this.bcc = options.bcc ? this.parseRecipients(options.bcc) : [];
-    
+    if (options.envelopeTo !== undefined) {
+      // The envelope alone receives the email; to, cc and bcc are header fields.
+      this.setEnvelopeTo(options.envelopeTo);
+      this.to = this.headerFieldRecipients(options.to);
+      this.cc = this.headerFieldRecipients(options.cc);
+      this.bcc = this.headerFieldRecipients(options.bcc);
+    } else {
+      // Handle to addresses (single or multiple)
+      this.to = options.to ? this.parseRecipients(options.to) : [];
+
+      // Handle optional cc and bcc
+      this.cc = options.cc ? this.parseRecipients(options.cc) : [];
+      this.bcc = options.bcc ? this.parseRecipients(options.bcc) : [];
+    }
+
     // Note: Templates may be created without recipients
     // Recipients will be added when the email is actually sent
 
@@ -216,6 +231,24 @@ export class Email {
     return result;
   }
 
+  /**
+   * The entries of a To, Cc or Bcc field of an email that has an envelope, for
+   * received and constructed emails alike. The envelope alone receives such an
+   * email, so an entry is kept whether or not it is a valid mailbox address:
+   * CR and LF are removed (an entry never adds a header line), the entry is
+   * trimmed, and an entry that is then empty is dropped. It never throws.
+   * @param recipients A string or array of field entries
+   * @returns The field entries, in order
+   */
+  private headerFieldRecipients(recipients: string | string[] | undefined): string[] {
+    if (recipients === undefined) {
+      return [];
+    }
+    return (Array.isArray(recipients) ? recipients : [recipients])
+      .map((entry) => entry.replace(/[\r\n]/g, '').trim())
+      .filter((entry) => entry.length > 0);
+  }
+
   /**
    * Basic sanitization for strings to prevent header injection
    * @param input The string to sanitize
@@ -563,8 +596,8 @@ export class Email {
     }
     
     // Validate recipients
-    const recipientsToCheck = options.checkFirstRecipientOnly ? 
-      [this.to[0]] : this.getAllRecipients();
+    const recipientsToCheck = options.checkFirstRecipientOnly ?
+      this.getAllRecipients().slice(0, 1) : this.getAllRecipients();
     
     for (const recipient of recipientsToCheck) {
       const recipientResult = await Email.emailValidator.validate(recipient, {

package/ts/mail/delivery/classes.delivery.queue.ts

@@ -461,11 +461,9 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
   private cloneEmail(emailArg: Email): Email {
     const options = deserialize(serialize(emailArg.toEmailOptions())) as IEmailOptions;
-    const email = new Email(options)
+    return new Email({ ...options, envelopeTo: emailArg.getEnvelopeTo() })
       .setMessageId(emailArg.getMessageId())
       .setEnvelopeFrom(emailArg.getEnvelopeFrom());
-    const envelopeTo = emailArg.getEnvelopeTo();
-    return envelopeTo ? email.setEnvelopeTo(envelopeTo) : email;
   }
 
   public [kQueueCreateItemSnapshot](itemArg: IQueueItem): IQueueItem {
@@ -1116,10 +1114,13 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     },
   ): Promise<string> {
     if (!raw) {
-      // The item's recipients become its envelope, the list serializeItem
-      // stores and deserializeItem restores. setEnvelopeTo refuses an empty
-      // list or a recipient that is not a mailbox, so the store never holds an
-      // item its reader refuses.
+      // The item owns a copy of the caller's email, so a caller that edits and
+      // sends its email again never changes or reuses this item. Its
+      // recipients become its envelope, the list serializeItem stores and
+      // deserializeItem restores. setEnvelopeTo refuses an empty list or a
+      // recipient that is not a mailbox, so the store never holds an item its
+      // reader refuses.
+      processingResult = this.cloneEmail(processingResult);
       try {
         processingResult.setEnvelopeTo(processingResult.getAllRecipients());
       } catch (error) {
@@ -2310,12 +2311,10 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
     let processingResult: Email;
     try {
-      processingResult = new Email(storedOptions)
+      // With its stored envelope, an item's to, cc and bcc are header fields.
+      processingResult = new Email({ ...storedOptions, envelopeTo: parsed.processingResult.envelopeTo })
         .setMessageId(parsed.processingResult.messageId)
         .setEnvelopeFrom(parsed.processingResult.envelopeFrom);
-      if (parsed.processingResult.envelopeTo !== undefined) {
-        processingResult.setEnvelopeTo(parsed.processingResult.envelopeTo);
-      }
     } catch (error) {
       throw new Error(`Invalid managed queue item at ${key}: ${getErrorMessage(error)}`);
     }

package/ts/mail/delivery/classes.delivery.system.ts

@@ -284,18 +284,15 @@ export class MultiModeDeliverySystem extends EventEmitter {
     }
   }
 
-  /** The copy of an email for one SMTP transaction: its envelope is exactly `recipients`. */
+  /**
+   * The copy of an email for one SMTP transaction: its envelope is exactly
+   * `recipients`, and its To, Cc and Bcc fields stay as they are, so every
+   * copy shows the same To and Cc.
+   */
   private createEmailForRecipients(email: Email, recipients: string[]): Email {
-    const recipientSet = new Set(recipients.map((recipient) => recipient.toLowerCase()));
-    return new Email({
-      ...email.toEmailOptions(),
-      to: email.to.filter((recipient) => recipientSet.has(recipient.toLowerCase())),
-      cc: (email.cc || []).filter((recipient) => recipientSet.has(recipient.toLowerCase())),
-      bcc: (email.bcc || []).filter((recipient) => recipientSet.has(recipient.toLowerCase())),
-    })
+    return new Email({ ...email.toEmailOptions(), envelopeTo: recipients })
       .setMessageId(email.getMessageId())
-      .setEnvelopeFrom(email.getEnvelopeFrom())
-      .setEnvelopeTo(recipients);
+      .setEnvelopeFrom(email.getEnvelopeFrom());
   }
 
   private contextualizeSmtpError(

package/ts/mail/routing/classes.email.action.executor.ts

@@ -136,9 +136,14 @@ export class EmailActionExecutor {
       }
     }
 
-    // Add standard forwarding headers
+    // Add standard forwarding headers. X-Forwarded-To names the one envelope
+    // recipient of a single-recipient copy and is never a list: the next hop
+    // has RCPT TO, and a list would show each recipient to every other.
     email.headers['X-Forwarded-For'] = context.session.remoteAddress || 'unknown';
-    email.headers['X-Forwarded-To'] = email.to.join(', ');
+    const forwardedRecipients = email.getAllRecipients();
+    if (forwardedRecipients.length === 1) {
+      email.headers['X-Forwarded-To'] = forwardedRecipients[0];
+    }
     email.headers['X-Forwarded-Date'] = new Date().toISOString();
 
     if (options.durableQueue) {

package/ts/mail/routing/classes.unified.email.server.ts

@@ -2597,13 +2597,17 @@ export class UnifiedEmailServer extends EventEmitter {
     }
   }
 
-  /** A copy of the email whose envelope is only the given SMTP envelope recipient. */
+  /**
+   * A copy of the email whose envelope is only the given SMTP envelope
+   * recipient; its To, Cc and Bcc fields stay as they are.
+   */
   private cloneEmailForRoutingRecipient(email: Email, recipient: string): Email {
     return new Email({
       from: email.from,
-      to: [recipient],
-      cc: [],
-      bcc: [],
+      to: [...email.to],
+      cc: [...email.cc],
+      bcc: [...email.bcc],
+      envelopeTo: [recipient],
       subject: email.subject,
       text: email.text,
       html: email.html,
@@ -2617,8 +2621,7 @@ export class UnifiedEmailServer extends EventEmitter {
       variables: structuredClone(email.variables),
     })
       .setMessageId(email.getMessageId())
-      .setEnvelopeFrom(email.getEnvelopeFrom())
-      .setEnvelopeTo([recipient]);
+      .setEnvelopeFrom(email.getEnvelopeFrom());
   }
 
   private scopeSessionForRoutingRecipient(
@@ -3566,9 +3569,12 @@ export class UnifiedEmailServer extends EventEmitter {
     return new Email({
       // The first mailbox of the From fields in message order, groups flattened
       from: headerFromMailboxes[0] || session.envelope.mailFrom.address,
-      to: envelopeRecipients,
+      // The message's To and Cc fields; the envelope alone receives it, and a
+      // Bcc field never travels on.
+      to: parsed.to.map(recipient => recipient.email),
       cc: parsed.cc.map(recipient => recipient.email),
       bcc: [],
+      envelopeTo: envelopeRecipients,
       subject: parsed.subject || '',
       text: bodies.text,
       html: bodies.html,
@@ -3579,7 +3585,7 @@ export class UnifiedEmailServer extends EventEmitter {
         contentType: attachment.contentType,
         ...(attachment.contentId ? { contentId: attachment.contentId } : {}),
       })),
-    }).setEnvelopeTo(envelopeRecipients);
+    });
   }
 
   private isStandardParsedHeader(headerName: string): boolean {
@@ -4298,6 +4304,8 @@ export class UnifiedEmailServer extends EventEmitter {
   ): Promise<string> {
     this.assertAcceptingOutboundWork();
     const recipients = email.getAllRecipients();
+    // What goes to the queue; the caller's email is never changed.
+    let outgoing = email;
     logger.log('info', `Sending email: ${email.subject} to ${recipients.join(', ')}`);
 
     try {
@@ -4331,12 +4339,17 @@ export class UnifiedEmailServer extends EventEmitter {
           }
 
           // The message's fields stay as written; the suppressed recipients
-          // only leave the envelope.
-          email.setEnvelopeTo(recipients.filter(recipient => !this.isEmailSuppressed(recipient)));
+          // only leave the envelope of the copy that is sent.
+          outgoing = new Email({
+            ...email.toEmailOptions(),
+            envelopeTo: recipients.filter(recipient => !this.isEmailSuppressed(recipient)),
+          })
+            .setMessageId(email.getMessageId())
+            .setEnvelopeFrom(email.getEnvelopeFrom());
         }
       }
 
-      const id = await this.deliveryQueue.enqueue(email, mode, route);
+      const id = await this.deliveryQueue.enqueue(outgoing, mode, route);
 
       logger.log('info', `Email queued with ID: ${id}`);
       return id;