@brightchain/brightchain-lib 0.13.0 → 0.15.0

package/src/lib/services/messaging/emailMessageService.js

@@ -0,0 +1,1030 @@
+"use strict";
+/**
+ * Email Message Service
+ *
+ * Main service for email operations in the BrightChain messaging system.
+ * Coordinates parsing, validation, storage, and delivery of RFC 5322
+ * compliant email messages.
+ *
+ * This service depends on:
+ * - MessageCBLService: For storing email content as CBL blocks
+ * - IGossipService: For delivering messages via gossip protocol
+ * - IEmailMetadataStore: For persisting email metadata
+ * - EmailParser, EmailSerializer, EmailValidator: For email processing
+ *
+ * @see RFC 5322 - Internet Message Format
+ * @see RFC 2045/2046 - MIME
+ *
+ * @remarks
+ * Requirements: 1.1-1.10
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailMessageService = exports.DEFAULT_EMAIL_SERVICE_CONFIG = void 0;
+const sha256_1 = require("@noble/hashes/sha256");
+const platformCrypto_1 = require("../../crypto/platformCrypto");
+const durabilityLevel_1 = require("../../enumerations/durabilityLevel");
+const deliveryStatus_1 = require("../../enumerations/messaging/deliveryStatus");
+const emailErrorType_1 = require("../../enumerations/messaging/emailErrorType");
+const messageEncryptionScheme_1 = require("../../enumerations/messaging/messageEncryptionScheme");
+const messagePriority_1 = require("../../enumerations/messaging/messagePriority");
+const replicationStatus_1 = require("../../enumerations/replicationStatus");
+const emailError_1 = require("../../errors/messaging/emailError");
+const mimePart_1 = require("../../interfaces/messaging/mimePart");
+const emailEncryptionService_1 = require("./emailEncryptionService");
+const emailValidator_1 = require("./emailValidator");
+/**
+ * Default configuration values for EmailMessageService.
+ */
+exports.DEFAULT_EMAIL_SERVICE_CONFIG = {
+    maxAttachmentSize: 25 * 1024 * 1024, // 25MB
+    maxMessageSize: 50 * 1024 * 1024, // 50MB
+    inlinePartThreshold: 64 * 1024, // 64KB
+    maxInlinePartsTotal: 256 * 1024, // 256KB
+    defaultPageSize: 50,
+    maxReferencesCount: 20,
+    maxRetryAttempts: 3,
+    deliveryTimeoutMs: 24 * 60 * 60 * 1000, // 24 hours
+    nodeId: 'localhost',
+};
+// ─── EmailMessageService Class ──────────────────────────────────────────────
+/**
+ * Main service for email operations in the BrightChain messaging system.
+ *
+ * Coordinates parsing, validation, storage, and delivery of RFC 5322
+ * compliant email messages. This service acts as the primary entry point
+ * for all email-related operations.
+ *
+ * @see Design Document: EmailMessageService Class
+ * @see Requirements 1.1-1.10
+ *
+ * @example
+ * ```typescript
+ * const emailService = new EmailMessageService(
+ *   messageCBLService,
+ *   metadataStore,
+ *   gossipService,
+ *   config,
+ * );
+ *
+ * const result = await emailService.sendEmail({
+ *   from: createMailbox('sender', 'example.com'),
+ *   to: [createMailbox('recipient', 'example.com')],
+ *   subject: 'Hello',
+ *   textBody: 'Hello, World!',
+ * });
+ * ```
+ */
+class EmailMessageService {
+    constructor(messageCBLService, metadataStore, gossipService, config) {
+        this.messageCBLService = messageCBLService;
+        this.metadataStore = metadataStore;
+        this.gossipService = gossipService;
+        this.config = { ...exports.DEFAULT_EMAIL_SERVICE_CONFIG, ...config };
+    }
+    // ─── Core Operations ────────────────────────────────────────────────
+    /**
+     * Sends an email message.
+     *
+     * Validates the email, auto-generates required headers (Message-ID, Date),
+     * stores the email content as CBL blocks, and initiates delivery to
+     * all recipients.
+     *
+     * @param email - The email input to send
+     * @returns The send result with message ID and delivery status
+     * @throws {EmailError} If validation fails or storage/delivery errors occur
+     *
+     * @see Requirement 15.1 - Validate at least one recipient
+     * @see Requirement 15.4 - Auto-generate required headers
+     */
+    /**
+     * Sends an email message.
+     *
+     * Validates the email, auto-generates required headers (Message-ID, Date),
+     * stores the email content as CBL blocks, and initiates delivery to
+     * all recipients.
+     *
+     * @param email - The email input to send
+     * @returns The send result with message ID and delivery status
+     * @throws {EmailError} If validation fails or storage/delivery errors occur
+     *
+     * @see Requirement 15.1 - Validate at least one recipient
+     * @see Requirement 15.4 - Auto-generate required headers
+     */
+    async sendEmail(email) {
+        // 1. Auto-generate required headers if missing
+        const messageId = email.messageId ?? this.generateMessageId();
+        const date = email.date ?? new Date();
+        // 2. Adapt service IEmailInput to validator's IEmailInput and validate
+        const validatorInput = {
+            from: email.from,
+            to: email.to,
+            cc: email.cc,
+            bcc: email.bcc,
+            subject: email.subject,
+            date,
+            messageId,
+            contentType: email.contentType,
+            attachments: email.attachments
+                ? email.attachments.map((a) => ({
+                    filename: a.filename,
+                    size: a.content.length,
+                }))
+                : undefined,
+            bodySize: (email.textBody ? new TextEncoder().encode(email.textBody).length : 0) +
+                (email.htmlBody ? new TextEncoder().encode(email.htmlBody).length : 0),
+        };
+        const emailValidator = new emailValidator_1.EmailValidator();
+        const validationResult = emailValidator.validate(validatorInput, {
+            maxAttachmentSize: this.config.maxAttachmentSize,
+            maxMessageSize: this.config.maxMessageSize,
+        });
+        if (!validationResult.valid) {
+            return {
+                messageId,
+                brightchainMessageId: '',
+                deliveryStatus: new Map(),
+                success: false,
+                error: validationResult.errors
+                    .map((e) => `${e.field}: ${e.message}`)
+                    .join('; '),
+            };
+        }
+        // 3. Build IEmailMetadata from the input
+        const brightchainMessageId = this.generateMessageId();
+        const now = new Date();
+        // Collect all recipient addresses for IMessageMetadata.recipients
+        const allRecipientAddresses = [];
+        if (email.to) {
+            allRecipientAddresses.push(...email.to.map((m) => m.address));
+        }
+        if (email.cc) {
+            allRecipientAddresses.push(...email.cc.map((m) => m.address));
+        }
+        if (email.bcc) {
+            allRecipientAddresses.push(...email.bcc.map((m) => m.address));
+        }
+        const contentType = email.contentType ??
+            (0, mimePart_1.createContentType)('text', 'plain', new Map([['charset', 'us-ascii']]));
+        const metadata = {
+            // IBlockMetadata fields
+            blockId: brightchainMessageId,
+            createdAt: now,
+            expiresAt: null,
+            durabilityLevel: durabilityLevel_1.DurabilityLevel.Standard,
+            parityBlockIds: [],
+            accessCount: 0,
+            lastAccessedAt: now,
+            replicationStatus: replicationStatus_1.ReplicationStatus.Pending,
+            targetReplicationFactor: 0,
+            replicaNodeIds: [],
+            size: (email.textBody ? new TextEncoder().encode(email.textBody).length : 0) +
+                (email.htmlBody ? new TextEncoder().encode(email.htmlBody).length : 0) +
+                (email.attachments
+                    ? email.attachments.reduce((sum, a) => sum + a.content.length, 0)
+                    : 0),
+            checksum: '',
+            // IMessageMetadata fields
+            messageType: 'email',
+            senderId: email.from.address,
+            recipients: allRecipientAddresses,
+            priority: messagePriority_1.MessagePriority.NORMAL,
+            deliveryStatus: new Map(allRecipientAddresses.map((addr) => [addr, deliveryStatus_1.DeliveryStatus.Pending])),
+            acknowledgments: new Map(),
+            encryptionScheme: email.encryptionScheme ?? messageEncryptionScheme_1.MessageEncryptionScheme.NONE,
+            isCBL: false,
+            cblBlockIds: [brightchainMessageId],
+            // IEmailMetadata fields
+            from: email.from,
+            sender: email.sender,
+            replyTo: email.replyTo,
+            to: email.to ?? [],
+            cc: email.cc,
+            bcc: email.bcc,
+            messageId,
+            inReplyTo: email.inReplyTo,
+            references: email.references,
+            subject: email.subject,
+            date,
+            mimeVersion: '1.0',
+            contentType,
+            customHeaders: email.customHeaders ?? new Map(),
+            parts: email.parts,
+            attachments: undefined,
+            deliveryReceipts: new Map(),
+            readReceipts: new Map(),
+        };
+        // 3b. Process attachments if provided
+        if (email.attachments && email.attachments.length > 0) {
+            metadata.attachments = await Promise.all(email.attachments.map((attachment) => this.storeAttachment(attachment)));
+        }
+        // 3c. Apply encryption if requested (Requirements 16.1, 16.3, 16.4, 16.7)
+        if (email.encryptionScheme &&
+            email.encryptionScheme !== messageEncryptionScheme_1.MessageEncryptionScheme.NONE) {
+            try {
+                const encryptionService = new emailEncryptionService_1.EmailEncryptionService();
+                // Build plaintext content from the email body
+                const bodyContent = new TextEncoder().encode((email.textBody ?? '') + (email.htmlBody ?? ''));
+                if (email.encryptionScheme === messageEncryptionScheme_1.MessageEncryptionScheme.RECIPIENT_KEYS) {
+                    // ECIES per-recipient encryption
+                    if (!email.recipientPublicKeys ||
+                        email.recipientPublicKeys.size === 0) {
+                        throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.ENCRYPTION_FAILED, 'Recipient public keys are required for RECIPIENT_KEYS encryption');
+                    }
+                    // Optionally sign if sender keys are provided
+                    let result;
+                    if (email.senderPrivateKey && email.senderPublicKey) {
+                        result = await encryptionService.encryptAndSign(bodyContent, email.recipientPublicKeys, email.senderPrivateKey, email.senderPublicKey);
+                    }
+                    else {
+                        result = await encryptionService.encryptForRecipients(bodyContent, email.recipientPublicKeys);
+                    }
+                    // Store encryption metadata in the email metadata
+                    metadata.encryptedKeys = result.encryptionMetadata.encryptedKeys;
+                    metadata.encryptionIv = result.encryptionMetadata.iv;
+                    metadata.encryptionAuthTag = result.encryptionMetadata.authTag;
+                    metadata.isSigned = result.encryptionMetadata.isSigned;
+                    metadata.contentSignature = result.encryptionMetadata.signature;
+                    metadata.signerPublicKey = result.encryptionMetadata.signerPublicKey;
+                }
+                else if (email.encryptionScheme === messageEncryptionScheme_1.MessageEncryptionScheme.SHARED_KEY) {
+                    // Symmetric encryption with shared key
+                    if (!email.sharedKey) {
+                        throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.ENCRYPTION_FAILED, 'Shared key is required for SHARED_KEY encryption');
+                    }
+                    const result = encryptionService.encryptContentSymmetric(bodyContent, email.sharedKey);
+                    metadata.encryptionIv = result.encryptionMetadata.iv;
+                    metadata.encryptionAuthTag = result.encryptionMetadata.authTag;
+                    // Optionally sign
+                    if (email.senderPrivateKey && email.senderPublicKey) {
+                        const sig = encryptionService.signContent(bodyContent, email.senderPrivateKey, email.senderPublicKey);
+                        metadata.isSigned = true;
+                        metadata.contentSignature = sig.signature;
+                        metadata.signerPublicKey = sig.signerPublicKey;
+                    }
+                }
+                else if (email.encryptionScheme === messageEncryptionScheme_1.MessageEncryptionScheme.S_MIME) {
+                    // S/MIME encryption: requires both recipient keys and sender keys
+                    if (!email.recipientPublicKeys ||
+                        email.recipientPublicKeys.size === 0) {
+                        throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.ENCRYPTION_FAILED, 'Recipient public keys are required for S/MIME encryption');
+                    }
+                    if (!email.senderPrivateKey || !email.senderPublicKey) {
+                        throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.ENCRYPTION_FAILED, 'Sender private and public keys are required for S/MIME encryption');
+                    }
+                    const result = await encryptionService.encryptSmime(bodyContent, email.recipientPublicKeys, email.senderPrivateKey, email.senderPublicKey);
+                    metadata.encryptedKeys = result.encryptionMetadata.encryptedKeys;
+                    metadata.encryptionIv = result.encryptionMetadata.iv;
+                    metadata.encryptionAuthTag = result.encryptionMetadata.authTag;
+                    metadata.isSigned = result.encryptionMetadata.isSigned;
+                    metadata.contentSignature = result.encryptionMetadata.signature;
+                    metadata.signerPublicKey = result.encryptionMetadata.signerPublicKey;
+                }
+            }
+            catch (err) {
+                if (err instanceof emailError_1.EmailError)
+                    throw err;
+                throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.ENCRYPTION_FAILED, `Failed to encrypt email: ${err instanceof Error ? err.message : String(err)}`, { messageId });
+            }
+        }
+        // 4. Store the sender's copy (retains BCC info for sender's records)
+        try {
+            await this.metadataStore.store(metadata);
+        }
+        catch (err) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.STORAGE_FAILED, `Failed to store email metadata: ${err instanceof Error ? err.message : String(err)}`, { messageId });
+        }
+        // 5. Initiate delivery to recipients via gossip with BCC privacy handling
+        //
+        // BCC Privacy (Requirements 9.2, 9.3, 6.3):
+        // - To/CC recipients receive a single gossip announcement WITHOUT BCC info
+        // - Each BCC recipient receives their own separate gossip announcement
+        // - All announcements have ackRequired=true (Requirement 6.5)
+        try {
+            // 5a. Deliver to To/CC recipients (no BCC info)
+            const toCcRecipientIds = [
+                ...(email.to ?? []).map((m) => m.address),
+                ...(email.cc ?? []).map((m) => m.address),
+            ];
+            if (toCcRecipientIds.length > 0) {
+                const toCcMetadata = this.createBccStrippedCopy(metadata);
+                await this.metadataStore.store(toCcMetadata);
+                await this.gossipService.announceMessage(toCcMetadata.cblBlockIds ?? [], {
+                    messageId,
+                    recipientIds: toCcRecipientIds,
+                    priority: 'normal',
+                    blockIds: toCcMetadata.cblBlockIds ?? [],
+                    cblBlockId: toCcMetadata.blockId,
+                    ackRequired: true,
+                });
+            }
+            // 5b. Deliver to each BCC recipient separately (BCC privacy)
+            // Each BCC recipient gets their own announcement with no BCC header and
+            // no information about other BCC recipients.
+            if (email.bcc && email.bcc.length > 0) {
+                for (const bccMailbox of email.bcc) {
+                    const bccCopy = this.createBccRecipientCopy(metadata, bccMailbox);
+                    await this.metadataStore.store(bccCopy);
+                    await this.gossipService.announceMessage(bccCopy.cblBlockIds ?? [], {
+                        messageId,
+                        recipientIds: [bccMailbox.address],
+                        priority: 'normal',
+                        blockIds: bccCopy.cblBlockIds ?? [],
+                        cblBlockId: bccCopy.blockId,
+                        ackRequired: true,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            // Delivery errors are non-fatal - the email is stored, delivery can be retried
+            // Return success with empty delivery status
+            return {
+                messageId,
+                brightchainMessageId,
+                deliveryStatus: new Map(),
+                success: true,
+                error: `Delivery initiation failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        // 6. Return result — gossip delivery is fire-and-forget; acks come later via gossip
+        return {
+            messageId,
+            brightchainMessageId,
+            deliveryStatus: new Map(),
+            success: true,
+        };
+    }
+    /**
+     * Retrieves email metadata by Message-ID.
+     *
+     * @param messageId - The Message-ID to look up
+     * @returns The email metadata, or null if not found
+     */
+    async getEmail(messageId) {
+        return this.metadataStore.get(messageId);
+    }
+    /**
+     * Retrieves the full email content including decoded body and attachments.
+     *
+     * Reconstructs the complete message from CBL blocks, decoding all
+     * MIME parts and attachments.
+     *
+     * @param messageId - The Message-ID to retrieve content for
+     * @returns The full email content
+     * @throws {EmailError} If the message is not found
+     *
+     * @see Requirement 13.5 - Reconstruct complete message including all MIME parts
+     */
+    async getEmailContent(messageId) {
+        const metadata = await this.metadataStore.get(messageId);
+        if (!metadata) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Email with messageId "${messageId}" not found`, { messageId });
+        }
+        // Extract textBody and htmlBody from MIME parts
+        let textBody;
+        let htmlBody;
+        const decoder = new TextDecoder();
+        if (metadata.parts) {
+            for (const part of metadata.parts) {
+                if (part.contentType.type === 'text' &&
+                    part.contentType.subtype === 'plain' &&
+                    part.body) {
+                    textBody = decoder.decode(part.body);
+                }
+                else if (part.contentType.type === 'text' &&
+                    part.contentType.subtype === 'html' &&
+                    part.body) {
+                    htmlBody = decoder.decode(part.body);
+                }
+            }
+        }
+        // Map attachment metadata to IRetrievedAttachment[]
+        const attachments = [];
+        if (metadata.attachments) {
+            for (const attachmentMeta of metadata.attachments) {
+                let content = new Uint8Array(0);
+                // Retrieve actual content from the attachment content store if available
+                if (this.metadataStore.getAttachmentContent) {
+                    const stored = await this.metadataStore.getAttachmentContent(attachmentMeta.checksum);
+                    if (stored) {
+                        content = new Uint8Array(stored);
+                    }
+                }
+                attachments.push({ metadata: attachmentMeta, content });
+            }
+        }
+        return {
+            metadata,
+            textBody,
+            htmlBody,
+            parts: metadata.parts ?? [],
+            attachments,
+        };
+    }
+    /**
+     * Deletes an email message and its associated blocks.
+     *
+     * @param messageId - The Message-ID to delete
+     * @throws {EmailError} If the message is not found
+     */
+    async deleteEmail(messageId) {
+        const metadata = await this.metadataStore.get(messageId);
+        if (!metadata) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Email with messageId "${messageId}" not found`, { messageId });
+        }
+        await this.metadataStore.delete(messageId);
+    }
+    // ─── Inbox Operations ───────────────────────────────────────────────
+    /**
+     * Queries a user's inbox with filtering, sorting, and pagination.
+     *
+     * @param userId - The user ID to query inbox for
+     * @param query - Query parameters for filtering and sorting
+     * @returns Paginated inbox results with unread count
+     *
+     * @see Requirement 13.1 - Inbox query for To, Cc, or Bcc recipients
+     * @see Requirement 13.2 - Sort by Date header (newest first by default)
+     * @see Requirement 13.6 - Pagination with configurable page size
+     */
+    async queryInbox(userId, query) {
+        // Apply defaults for pagination and sorting
+        const normalizedQuery = {
+            ...query,
+            page: query.page ?? 1,
+            pageSize: query.pageSize ?? this.config.defaultPageSize,
+            sortBy: query.sortBy ?? 'date',
+            sortDirection: query.sortDirection ?? 'desc',
+            readStatus: query.readStatus ?? 'all',
+        };
+        return this.metadataStore.queryInbox(userId, normalizedQuery);
+    }
+    /**
+     * Marks an email as read for a specific user.
+     *
+     * @param messageId - The Message-ID to mark as read
+     * @param userId - The user who read the email
+     *
+     * @see Requirement 13.8 - Track unread count
+     */
+    async markAsRead(messageId, userId) {
+        await this.metadataStore.markAsRead(messageId, userId);
+    }
+    /**
+     * Gets the unread email count for a user.
+     *
+     * @param userId - The user ID to get unread count for
+     * @returns The number of unread emails
+     *
+     * @see Requirement 13.8 - Return unread count for inbox queries
+     */
+    async getUnreadCount(userId) {
+        return this.metadataStore.getUnreadCount(userId);
+    }
+    // ─── Threading Operations ───────────────────────────────────────────
+    /**
+     * Retrieves all emails in a thread by following the References chain.
+     *
+     * Messages are ordered chronologically by Date header.
+     * Handles broken threads where intermediate messages are missing.
+     *
+     * @param messageId - Any Message-ID in the thread
+     * @returns Array of email metadata in the thread, ordered chronologically
+     *
+     * @see Requirement 10.4 - Retrieve all emails in a thread
+     * @see Requirement 10.5 - Order messages chronologically
+     * @see Requirement 10.7 - Handle broken threads
+     */
+    async getThread(messageId) {
+        // 1. Retrieve the starting email
+        const startEmail = await this.metadataStore.get(messageId);
+        if (!startEmail) {
+            return [];
+        }
+        // 2. Collect all known Message-IDs in the thread
+        //    Start from the given email's References + its own Message-ID
+        const knownIds = new Set();
+        const toVisit = [];
+        // Seed with the starting email
+        knownIds.add(startEmail.messageId);
+        if (startEmail.references) {
+            for (const ref of startEmail.references) {
+                if (!knownIds.has(ref)) {
+                    knownIds.add(ref);
+                    toVisit.push(ref);
+                }
+            }
+        }
+        if (startEmail.inReplyTo && !knownIds.has(startEmail.inReplyTo)) {
+            knownIds.add(startEmail.inReplyTo);
+            toVisit.push(startEmail.inReplyTo);
+        }
+        // 3. Walk the thread graph: for each known ID, try to fetch the email
+        //    and discover more IDs from its References/In-Reply-To
+        const found = new Map();
+        found.set(startEmail.messageId, startEmail);
+        while (toVisit.length > 0) {
+            const visitId = toVisit.pop();
+            if (found.has(visitId)) {
+                continue;
+            }
+            const email = await this.metadataStore.get(visitId);
+            if (!email) {
+                // Broken thread - intermediate message missing, skip gracefully
+                continue;
+            }
+            found.set(email.messageId, email);
+            // Discover more thread members from this email's references
+            if (email.references) {
+                for (const ref of email.references) {
+                    if (!knownIds.has(ref)) {
+                        knownIds.add(ref);
+                        toVisit.push(ref);
+                    }
+                }
+            }
+            if (email.inReplyTo && !knownIds.has(email.inReplyTo)) {
+                knownIds.add(email.inReplyTo);
+                toVisit.push(email.inReplyTo);
+            }
+        }
+        // 4. Also use the metadata store's getThread for any additional thread members
+        //    that might reference this thread but aren't in our References chain
+        try {
+            const storeThread = await this.metadataStore.getThread(messageId);
+            for (const email of storeThread) {
+                if (!found.has(email.messageId)) {
+                    found.set(email.messageId, email);
+                }
+            }
+        }
+        catch {
+            // If the store doesn't support getThread, that's fine - we have our graph walk
+        }
+        // 5. Order messages chronologically by Date header (Requirement 10.5)
+        const threadEmails = Array.from(found.values());
+        threadEmails.sort((a, b) => a.date.getTime() - b.date.getTime());
+        return threadEmails;
+    }
+    /**
+     * Retrieves the root message of a thread.
+     *
+     * Follows the References chain to find the first Message-ID.
+     *
+     * @param messageId - Any Message-ID in the thread
+     * @returns The root email metadata, or null if not found
+     *
+     * @see Requirement 10.6 - Retrieve root message by following References
+     */
+    async getRootMessage(messageId) {
+        // 1. Retrieve the starting email
+        const email = await this.metadataStore.get(messageId);
+        if (!email) {
+            return null;
+        }
+        // 2. If this email has no References, it is the root
+        if (!email.references || email.references.length === 0) {
+            return email;
+        }
+        // 3. The root is the first Message-ID in the References chain
+        const rootId = email.references[0];
+        const rootEmail = await this.metadataStore.get(rootId);
+        // If the root message is found, return it
+        if (rootEmail) {
+            return rootEmail;
+        }
+        // 4. If the root is missing (broken thread), walk up the chain
+        //    trying each Reference until we find one that exists
+        for (let i = 1; i < email.references.length; i++) {
+            const candidate = await this.metadataStore.get(email.references[i]);
+            if (candidate) {
+                // Check if this candidate has no further references (is a root)
+                if (!candidate.references || candidate.references.length === 0) {
+                    return candidate;
+                }
+                // Otherwise, recurse from this candidate
+                return this.getRootMessage(candidate.messageId);
+            }
+        }
+        // 5. If no referenced messages exist, the current email is the earliest we can find
+        return email;
+    }
+    // ─── Reply/Forward Operations ───────────────────────────────────────
+    /**
+     * Creates a reply to an existing email.
+     *
+     * Sets In-Reply-To to the parent's Message-ID and constructs the
+     * References header by appending the parent's Message-ID to the
+     * parent's References list (limited to maxReferencesCount).
+     *
+     * @param originalId - The Message-ID of the email being replied to
+     * @param replyContent - The reply content and options
+     * @returns The send result for the reply
+     * @throws {EmailError} If the original message is not found
+     *
+     * @see Requirement 10.1 - Set In-Reply-To to parent Message-ID
+     * @see Requirement 10.2 - Construct References header
+     * @see Requirement 10.3 - Limit References to 20 Message-IDs
+     */
+    async createReply(originalId, replyContent) {
+        // 1. Retrieve the original email
+        const original = await this.metadataStore.get(originalId);
+        if (!original) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Original email with messageId "${originalId}" not found`, { messageId: originalId });
+        }
+        // 2. Construct References header per RFC 5322:
+        //    Append parent's Message-ID to parent's References list
+        const parentReferences = original.references ?? [];
+        const allReferences = [...parentReferences, original.messageId];
+        // 3. Limit References to maxReferencesCount (default 20) per Requirement 10.3
+        //    Truncate from the beginning (keep most recent) if necessary
+        const maxRefs = this.config.maxReferencesCount;
+        const references = allReferences.length > maxRefs
+            ? allReferences.slice(allReferences.length - maxRefs)
+            : allReferences;
+        // 4. Build recipients list
+        let toRecipients;
+        if (replyContent.replyAll) {
+            // Reply-All: include original sender + original To + original Cc
+            // but exclude the replier themselves, and never include original Bcc
+            const replierAddress = replyContent.from.address;
+            const originalRecipients = [
+                original.from,
+                ...(original.to ?? []),
+                ...(original.cc ?? []),
+            ];
+            // Deduplicate by address and exclude the replier
+            const seen = new Set();
+            toRecipients = [];
+            for (const mailbox of originalRecipients) {
+                const addr = mailbox.address;
+                if (addr !== replierAddress && !seen.has(addr)) {
+                    seen.add(addr);
+                    toRecipients.push(mailbox);
+                }
+            }
+        }
+        else {
+            // Simple reply: reply to the original sender (or Reply-To if set)
+            toRecipients =
+                original.replyTo && original.replyTo.length > 0
+                    ? [...original.replyTo]
+                    : [original.from];
+        }
+        // Add any additional recipients specified in the reply
+        if (replyContent.additionalTo) {
+            toRecipients.push(...replyContent.additionalTo);
+        }
+        // 5. Build subject with "Re: " prefix if not already present
+        const originalSubject = original.subject ?? '';
+        const subject = replyContent.subject ??
+            (originalSubject.match(/^Re:/i)
+                ? originalSubject
+                : `Re: ${originalSubject}`);
+        // 6. Send the reply using sendEmail
+        const emailInput = {
+            from: replyContent.from,
+            to: toRecipients,
+            cc: replyContent.additionalCc,
+            subject,
+            textBody: replyContent.textBody,
+            htmlBody: replyContent.htmlBody,
+            attachments: replyContent.attachments,
+            inReplyTo: original.messageId,
+            references,
+        };
+        return this.sendEmail(emailInput);
+    }
+    /**
+     * Forwards an email to new recipients.
+     *
+     * Adds Resent-From, Resent-To, Resent-Date, and Resent-Message-ID
+     * headers per RFC 5322 Section 3.6.6. Preserves all original headers.
+     *
+     * @param originalId - The Message-ID of the email being forwarded
+     * @param forwardTo - The recipients to forward to
+     * @returns The send result for the forwarded email
+     * @throws {EmailError} If the original message is not found
+     *
+     * @see Requirement 17.1 - Add Resent-* headers per RFC 5322
+     * @see Requirement 17.2 - Preserve all original headers
+     */
+    async forwardEmail(originalId, forwardTo) {
+        // 1. Retrieve the original email
+        const original = await this.metadataStore.get(originalId);
+        if (!original) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Original email with messageId "${originalId}" not found`, { messageId: originalId });
+        }
+        // 2. Build the Resent-* header block per RFC 5322 Section 3.6.6
+        const resentHeaderBlock = {
+            resentFrom: original.from,
+            resentTo: forwardTo,
+            resentDate: new Date(),
+            resentMessageId: this.generateMessageId(),
+        };
+        // 3. Prepend the new Resent-* block (most recent first) per Requirement 17.4
+        const existingResentHeaders = original.resentHeaders ?? [];
+        const updatedResentHeaders = [resentHeaderBlock, ...existingResentHeaders];
+        // 4. Build the forwarded email input preserving all original headers (Requirement 17.2)
+        const emailInput = {
+            from: original.from,
+            sender: original.sender,
+            replyTo: original.replyTo,
+            to: forwardTo,
+            subject: original.subject
+                ? original.subject.match(/^Fwd:/i)
+                    ? original.subject
+                    : `Fwd: ${original.subject}`
+                : undefined,
+            textBody: undefined,
+            htmlBody: undefined,
+            messageId: resentHeaderBlock.resentMessageId,
+            customHeaders: original.customHeaders,
+        };
+        // 5. Send the forwarded email
+        const result = await this.sendEmail(emailInput);
+        // 6. Update the stored metadata with Resent-* headers
+        if (result.success) {
+            try {
+                await this.metadataStore.update(result.messageId, {
+                    resentHeaders: updatedResentHeaders,
+                });
+            }
+            catch {
+                // Non-fatal: the email was sent, resent headers are supplementary metadata
+            }
+        }
+        return result;
+    }
+    // ─── Delivery Tracking ──────────────────────────────────────────────
+    /**
+     * Gets the delivery status for all recipients of an email.
+     *
+     * @param messageId - The Message-ID to get delivery status for
+     * @returns Map of recipient ID to delivery receipt
+     *
+     * @see Requirement 12.1 - Track delivery status per recipient
+     */
+    async getDeliveryStatus(messageId) {
+        const metadata = await this.metadataStore.get(messageId);
+        if (!metadata) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Email with messageId "${messageId}" not found`, { messageId });
+        }
+        return metadata.deliveryReceipts;
+    }
+    // ─── Signature Verification (Requirement 16.5, 16.8) ─────────────
+    /**
+     * Verifies the digital signature on a stored email.
+     *
+     * Retrieves the email metadata, reconstructs the signed content,
+     * and verifies the signature using the signer's private key.
+     *
+     * @param messageId - The Message-ID of the email to verify
+     * @param signerPrivateKey - The signer's private key for HMAC verification
+     * @returns Object with verification result and metadata
+     * @throws {EmailError} If the message is not found
+     *
+     * @see Requirement 16.5 - S/MIME signatures for sender authentication
+     * @see Requirement 16.8 - Verify sender's signature on decryption
+     */
+    async verifyEmailSignature(messageId, signerPrivateKey) {
+        const metadata = await this.metadataStore.get(messageId);
+        if (!metadata) {
+            throw new emailError_1.EmailError(emailErrorType_1.EmailErrorType.MESSAGE_NOT_FOUND, `Email with messageId "${messageId}" not found`, { messageId });
+        }
+        if (!metadata.isSigned || !metadata.contentSignature) {
+            return { verified: false, isSigned: false };
+        }
+        // Reconstruct the content that was signed (textBody + htmlBody)
+        let bodyContent = '';
+        if (metadata.parts) {
+            for (const part of metadata.parts) {
+                if (part.contentType.type === 'text' &&
+                    (part.contentType.subtype === 'plain' ||
+                        part.contentType.subtype === 'html') &&
+                    part.body) {
+                    bodyContent += new TextDecoder().decode(part.body);
+                }
+            }
+        }
+        const content = new TextEncoder().encode(bodyContent);
+        const encryptionService = new emailEncryptionService_1.EmailEncryptionService();
+        const verified = encryptionService.verifySignature(content, metadata.contentSignature, signerPrivateKey);
+        return { verified, isSigned: true };
+    }
+    // ─── BCC Privacy Handling ─────────────────────────────────────────
+    /**
+     * Creates a copy of the email metadata with BCC information stripped.
+     * This copy is delivered to To and CC recipients.
+     *
+     * The copy has:
+     * - No `bcc` field (undefined)
+     * - No BCC recipients in the `recipients` array
+     * - No BCC delivery tracking in `deliveryReceipts`
+     * - A unique block ID for separate storage
+     *
+     * @param original - The original email metadata (sender's copy with full BCC info)
+     * @returns A new IEmailMetadata with BCC info removed
+     *
+     * @see Requirement 9.2 - BCC recipients excluded from all recipient copies
+     * @see Requirement 9.3 - Separate encrypted copies for BCC recipients
+     */
+    createBccStrippedCopy(original) {
+        // Filter out BCC addresses from the recipients list
+        const bccAddresses = new Set((original.bcc ?? []).map((m) => m.address));
+        const filteredRecipients = original.recipients.filter((addr) => !bccAddresses.has(addr));
+        // Filter out BCC delivery status entries
+        const filteredDeliveryStatus = new Map();
+        for (const [addr, status] of original.deliveryStatus) {
+            if (!bccAddresses.has(addr)) {
+                filteredDeliveryStatus.set(addr, status);
+            }
+        }
+        // Filter out BCC delivery receipts
+        const filteredDeliveryReceipts = new Map();
+        for (const [addr, receipt] of original.deliveryReceipts) {
+            if (!bccAddresses.has(addr)) {
+                filteredDeliveryReceipts.set(addr, receipt);
+            }
+        }
+        return {
+            ...original,
+            blockId: `${original.blockId}-tocc`,
+            bcc: undefined,
+            recipients: filteredRecipients,
+            deliveryStatus: filteredDeliveryStatus,
+            deliveryReceipts: filteredDeliveryReceipts,
+        };
+    }
+    /**
+     * Creates a private copy of the email for a single BCC recipient.
+     *
+     * The copy has:
+     * - No `bcc` field (no BCC header visible)
+     * - Only the specific BCC recipient in delivery tracking
+     * - A unique block ID for separate encrypted storage
+     * - Encryption scheme set to ECIES for per-recipient encryption
+     *
+     * This ensures that:
+     * - The BCC recipient cannot see other BCC recipients
+     * - To/CC recipients cannot see BCC recipients
+     * - Each BCC copy can be encrypted with the individual recipient's key
+     *
+     * @param original - The original email metadata
+     * @param bccRecipient - The specific BCC recipient this copy is for
+     * @returns A new IEmailMetadata for the BCC recipient
+     *
+     * @see Requirement 9.2 - BCC recipients excluded from all recipient copies
+     * @see Requirement 9.3 - Separate encrypted copies for BCC recipients
+     * @see Requirement 16.2 - BCC addresses cryptographically separated
+     */
+    createBccRecipientCopy(original, bccRecipient) {
+        // The BCC copy includes the original To/CC recipients in headers
+        // (so the BCC recipient can see who the email was addressed to)
+        // but has NO Bcc header at all.
+        // The BCC recipient is added to the 'to' field so they appear in
+        // inbox queries (isRecipient checks to/cc/bcc fields).
+        const toCcAddresses = [
+            ...original.to.map((m) => m.address),
+            ...(original.cc ?? []).map((m) => m.address),
+        ];
+        return {
+            ...original,
+            blockId: `${original.blockId}-bcc-${bccRecipient.address}`,
+            to: [...original.to, bccRecipient],
+            bcc: undefined,
+            recipients: [...toCcAddresses, bccRecipient.address],
+            deliveryStatus: new Map([[bccRecipient.address, deliveryStatus_1.DeliveryStatus.Pending]]),
+            deliveryReceipts: new Map(),
+            encryptionScheme: messageEncryptionScheme_1.MessageEncryptionScheme.RECIPIENT_KEYS,
+        };
+    }
+    // ─── CC Visibility ──────────────────────────────────────────────────
+    /**
+     * Ensures CC recipients are included in the Cc header for all recipient copies.
+     *
+     * This is already handled by the metadata construction in sendEmail() which
+     * preserves the `cc` field in all copies (both To/CC and BCC copies).
+     * The CC header is visible to all recipients per RFC 5322.
+     *
+     * @see Requirement 9.1 - CC recipients visible to all recipients
+     */
+    // ─── Undisclosed Recipients ─────────────────────────────────────────
+    /**
+     * Checks if the email has only BCC recipients (undisclosed recipients).
+     *
+     * When an email has only BCC recipients and no To or CC recipients,
+     * the To field is empty, which is valid per RFC 5322 for undisclosed
+     * recipients scenarios.
+     *
+     * @param email - The email input to check
+     * @returns true if the email has only BCC recipients
+     *
+     * @see Requirement 9.6 - Support empty To field when only Bcc recipients specified
+     */
+    isUndisclosedRecipients(email) {
+        const hasTo = email.to && email.to.length > 0;
+        const hasCc = email.cc && email.cc.length > 0;
+        const hasBcc = email.bcc && email.bcc.length > 0;
+        return !hasTo && !hasCc && hasBcc === true;
+    }
+    // ─── Attachment Storage ─────────────────────────────────────────────
+    /**
+     * Stores an attachment and produces its metadata.
+     *
+     * Calculates SHA-256 and MD5 checksums for integrity verification,
+     * generates a CBL magnet URL, and persists the attachment content
+     * via the metadata store's attachment content storage.
+     *
+     * @param input - The attachment input containing filename, mimeType, content, and optional contentId
+     * @returns The attachment metadata with checksums and storage references
+     *
+     * @see Requirement 8.1 - Store attachments as ExtendedCBL blocks
+     * @see Requirement 8.2 - Support multiple attachments per email
+     * @see Requirement 8.3 - Preserve filename, MIME type, and file size
+     * @see Requirement 8.9 - Support inline attachments with Content-ID
+     * @see Requirement 8.10 - Calculate and store MD5 Content-MD5 header per RFC 1864
+     */
+    async storeAttachment(input) {
+        // Calculate SHA-256 checksum (hex digest) using @noble/hashes (browser-compatible)
+        const sha256Hash = (0, sha256_1.sha256)(input.content);
+        const sha256Checksum = Array.from(sha256Hash)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+        // Calculate MD5 checksum (base64 digest per RFC 1864)
+        // NOTE: @noble/hashes intentionally excludes MD5. We use a conditional
+        // Node.js fallback here. For full browser compatibility, a lightweight
+        // MD5 library (e.g., js-md5) would be needed.
+        let md5Checksum;
+        if (typeof process !== 'undefined' &&
+            process.versions != null &&
+            process.versions.node != null) {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { createHash } = require('crypto');
+            md5Checksum = createHash('md5').update(input.content).digest('base64');
+        }
+        else {
+            // Browser fallback: use empty string (MD5 Content-MD5 is optional per RFC 1864)
+            md5Checksum = '';
+        }
+        // Generate CBL magnet URL using the checksum
+        const cblMagnetUrl = `magnet:?xt=urn:cbl:${sha256Checksum}`;
+        // Generate block ID based on the checksum
+        const blockId = `cbl-block-${sha256Checksum}`;
+        // Persist attachment content if the store supports it
+        if (this.metadataStore.storeAttachmentContent) {
+            await this.metadataStore.storeAttachmentContent(sha256Checksum, input.content);
+        }
+        return {
+            filename: input.filename,
+            mimeType: input.mimeType,
+            size: input.content.length,
+            contentId: input.contentId,
+            cblMagnetUrl,
+            blockIds: [blockId],
+            checksum: sha256Checksum,
+            contentMd5: md5Checksum,
+        };
+    }
+    // ─── Message-ID Generation ────────────────────────────────────────────
+    /**
+     * Generates a globally unique Message-ID in RFC 5322 format.
+     *
+     * The generated Message-ID has the format: `<id-left@id-right>` where:
+     * - **id-left**: A combination of timestamp (milliseconds since epoch) and
+     *   a cryptographically random hex string, separated by a dot.
+     * - **id-right**: The configured `nodeId` from the service configuration,
+     *   representing the sender's node ID or domain.
+     *
+     * This ensures global uniqueness by incorporating:
+     * 1. A high-resolution timestamp component
+     * 2. A cryptographically secure random component (16 bytes / 32 hex chars)
+     * 3. The node identifier
+     *
+     * @returns A unique Message-ID string in the format `<timestamp.random@nodeId>`
+     *
+     * @see Requirement 3.1 - Message-ID format per RFC 5322 Section 3.6.4
+     * @see Requirement 3.2 - Use sender's node ID as id-right portion
+     * @see Requirement 3.3 - Ensure global uniqueness with timestamp, random, and node ID
+     */
+    generateMessageId() {
+        const timestamp = Date.now().toString(36);
+        const randomBytesArr = (0, platformCrypto_1.getRandomBytes)(16);
+        const random = Array.from(randomBytesArr)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+        const idLeft = `${timestamp}.${random}`;
+        const idRight = this.config.nodeId;
+        return `<${idLeft}@${idRight}>`;
+    }
+    // ─── Configuration Access ───────────────────────────────────────────
+    /**
+     * Returns the current service configuration.
+     *
+     * Useful for checking configured limits and defaults.
+     */
+    getConfig() {
+        return this.config;
+    }
+}
+exports.EmailMessageService = EmailMessageService;
+//# sourceMappingURL=emailMessageService.js.map