@brightchain/brightchain-api-lib 0.24.1 → 0.26.0

package/src/lib/services/emailGateway/inboundProcessor.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * InboundProcessor — watches the Mail Drop Directory for new Maildir-format
+ * files deposited by Postfix, parses each message via EmailParser, stores
+ * content in the Block Store, creates metadata via EmailMessageService, and
+ * announces delivery to the recipient via the Gossip Protocol.
+ *
+ * On success the processed file is deleted from the Mail Drop Directory.
+ * On failure the file is moved to a configurable error directory and the
+ * failure reason is logged.
+ *
+ * A Set of processed filenames provides idempotency — the same file will
+ * not be processed twice even if the watcher fires duplicate events.
+ *
+ * @see Requirements 4.4, 4.5, 4.6, 4.7, 4.8, 4.9
+ * @module inboundProcessor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboundProcessor = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+const emailAuthVerifier_1 = require("./emailAuthVerifier");
+// ─── InboundProcessor ───────────────────────────────────────────────────────
+/**
+ * Watches the Mail Drop Directory for new inbound email files and processes
+ * them into the BrightChain internal messaging system.
+ *
+ * Processing pipeline per file:
+ * 1. Read raw file content
+ * 2. Parse RFC 5322 message via EmailParser
+ * 3. Store content in Block Store
+ * 4. Create metadata via EmailMessageService
+ * 5. Announce to recipient via Gossip Protocol
+ * 6. Delete file on success / move to error directory on failure
+ *
+ * @see Requirements 4.4, 4.5, 4.6, 4.7, 4.8, 4.9
+ */
+class InboundProcessor {
+    config;
+    emailMessageService;
+    blockStore;
+    gossipService;
+    parser;
+    /** Authentication verifier for SPF/DKIM/DMARC. Req 6.4, 6.5 */
+    authVerifier;
+    /** fs.watch handle — `null` when stopped. */
+    watcher = null;
+    /** Whether the processor is currently running. */
+    running = false;
+    /** Filenames that have already been processed (idempotency guard). Req 4.7 */
+    processedFiles = new Set();
+    constructor(config, emailParser, emailMessageService, blockStore, gossipService, authVerifier) {
+        this.config = config;
+        this.emailMessageService = emailMessageService;
+        this.blockStore = blockStore;
+        this.gossipService = gossipService;
+        this.parser = emailParser ?? new brightchain_lib_1.EmailParser();
+        this.authVerifier = authVerifier ?? new emailAuthVerifier_1.EmailAuthVerifier();
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Start watching the Mail Drop Directory for new files.
+     *
+     * Creates the mail drop and error directories if they do not exist,
+     * then sets up an `fs.watch` listener that triggers processing for
+     * every new or renamed file.
+     *
+     * @see Requirement 4.5 — watch via inotify / fs.watch
+     */
+    start() {
+        if (this.running) {
+            return;
+        }
+        // Ensure directories exist.
+        fs.mkdirSync(this.config.mailDropDirectory, { recursive: true });
+        fs.mkdirSync(this.config.errorDirectory, { recursive: true });
+        // Process any files already present in the directory.
+        this.processExistingFiles();
+        // Watch for new files.
+        this.watcher = fs.watch(this.config.mailDropDirectory, (eventType, filename) => {
+            if (filename && (eventType === 'rename' || eventType === 'change')) {
+                // Small delay to allow the file to be fully written.
+                setTimeout(() => {
+                    void this.processFile(filename);
+                }, 100);
+            }
+        });
+        this.running = true;
+    }
+    /**
+     * Stop watching the Mail Drop Directory.
+     */
+    stop() {
+        if (!this.running) {
+            return;
+        }
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        this.running = false;
+    }
+    /**
+     * Whether the processor is currently running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    // ─── File Processing ────────────────────────────────────────────────
+    /**
+     * Process all files already present in the Mail Drop Directory.
+     * Called once on startup to handle files deposited while the processor
+     * was not running.
+     */
+    processExistingFiles() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.config.mailDropDirectory);
+        }
+        catch {
+            return;
+        }
+        for (const filename of entries) {
+            const fullPath = path.join(this.config.mailDropDirectory, filename);
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.isFile()) {
+                    void this.processFile(filename);
+                }
+            }
+            catch {
+                // Skip entries we cannot stat.
+            }
+        }
+    }
+    /**
+     * Process a single inbound email file.
+     *
+     * Idempotency: if the file has already been processed (tracked in
+     * `processedFiles`) the call is a no-op. Req 4.7
+     *
+     * @param filename - The filename (not full path) within the Mail Drop Directory
+     *
+     * @see Requirement 4.6 — parse, store, create metadata
+     * @see Requirement 4.7 — delete on success
+     * @see Requirement 4.8 — move to error directory on failure
+     * @see Requirement 4.9 — announce via gossip
+     */
+    async processFile(filename) {
+        // Idempotency guard (Req 4.7).
+        if (this.processedFiles.has(filename)) {
+            return;
+        }
+        const filePath = path.join(this.config.mailDropDirectory, filename);
+        // Verify the file still exists (it may have been removed between
+        // the watcher event and this handler running).
+        if (!fs.existsSync(filePath)) {
+            return;
+        }
+        // Mark as in-progress immediately to prevent duplicate processing
+        // from concurrent watcher events.
+        this.processedFiles.add(filename);
+        try {
+            // 1. Read raw file content.
+            const rawContent = fs.readFileSync(filePath);
+            // 2. Parse RFC 5322 message via EmailParser (Req 4.6).
+            const metadata = await this.parser.parse(rawContent);
+            // 2b. Verify SPF/DKIM/DMARC authentication results (Req 6.4).
+            const authResult = this.authVerifier.verify(rawContent);
+            // 2c. Reject messages failing DMARC with reject policy (Req 6.5).
+            if (emailAuthVerifier_1.EmailAuthVerifier.shouldRejectDmarc(authResult)) {
+                throw new Error(`DMARC verification failed (550 reject): ${authResult.dmarc.details ?? 'policy=reject'}`);
+            }
+            // 3. Store content in Block Store.
+            const blockId = metadata.messageId;
+            await this.blockStore.put(blockId, rawContent);
+            // 4. Create metadata via EmailMessageService (Req 4.6).
+            //    We use sendEmail with the parsed metadata to go through the
+            //    standard storage and delivery pipeline.
+            const recipientAddresses = [
+                ...metadata.to.map((m) => m.address),
+                ...(metadata.cc ?? []).map((m) => m.address),
+            ];
+            await this.emailMessageService.sendEmail({
+                from: metadata.from,
+                to: metadata.to,
+                cc: metadata.cc,
+                bcc: metadata.bcc,
+                subject: metadata.subject,
+                messageId: metadata.messageId,
+                date: metadata.date,
+                inReplyTo: metadata.inReplyTo,
+                references: metadata.references,
+                contentType: metadata.contentType,
+                parts: metadata.parts,
+                textBody: this.extractTextBody(metadata),
+                htmlBody: this.extractHtmlBody(metadata),
+                customHeaders: this.mergeAuthHeaders(metadata.customHeaders, authResult),
+            });
+            // 5. Announce to recipients via Gossip Protocol (Req 4.9).
+            await this.gossipService.announceMessage(metadata.cblBlockIds ?? [blockId], {
+                messageId: metadata.messageId,
+                recipientIds: recipientAddresses,
+                priority: 'normal',
+                blockIds: metadata.cblBlockIds ?? [blockId],
+                cblBlockId: metadata.blockId ?? blockId,
+                ackRequired: true,
+            });
+            // 6. Delete processed file on success (Req 4.7).
+            fs.unlinkSync(filePath);
+        }
+        catch (err) {
+            // On failure: move to error directory and log reason (Req 4.8).
+            const reason = err instanceof Error ? err.message : String(err);
+            try {
+                const errorPath = path.join(this.config.errorDirectory, filename);
+                fs.renameSync(filePath, errorPath);
+            }
+            catch {
+                // If we can't move the file, leave it in place — it won't be
+                // reprocessed because it's already in processedFiles.
+            }
+            // Log the failure reason.
+            console.error(`[InboundProcessor] Failed to process ${filename}: ${reason}`);
+            // Remove from processedFiles so a retry can be attempted if the
+            // file is re-deposited.
+            this.processedFiles.delete(filename);
+        }
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────
+    /**
+     * Merge authentication results into custom headers as a serialized
+     * `X-BrightChain-Auth-Results` header so the auth metadata is
+     * preserved alongside the message.
+     *
+     * @see Requirement 6.4
+     */
+    mergeAuthHeaders(existing, authResult) {
+        const merged = new Map(existing);
+        const summary = [
+            `spf=${authResult.spf.status}`,
+            `dkim=${authResult.dkim.status}`,
+            `dmarc=${authResult.dmarc.status}`,
+        ].join('; ');
+        merged.set('X-BrightChain-Auth-Results', [summary]);
+        return merged;
+    }
+    /**
+     * Extract plain-text body from parsed email metadata.
+     */
+    extractTextBody(metadata) {
+        if (metadata.parts && metadata.parts.length > 0) {
+            for (const part of metadata.parts) {
+                if (part.contentType?.type === 'text' &&
+                    part.contentType?.subtype === 'plain' &&
+                    part.body) {
+                    return typeof part.body === 'string'
+                        ? part.body
+                        : new TextDecoder().decode(part.body);
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Extract HTML body from parsed email metadata.
+     */
+    extractHtmlBody(metadata) {
+        if (metadata.parts && metadata.parts.length > 0) {
+            for (const part of metadata.parts) {
+                if (part.contentType?.type === 'text' &&
+                    part.contentType?.subtype === 'html' &&
+                    part.body) {
+                    return typeof part.body === 'string'
+                        ? part.body
+                        : new TextDecoder().decode(part.body);
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get the set of processed filenames (for testing / inspection).
+     */
+    getProcessedFiles() {
+        return this.processedFiles;
+    }
+    /**
+     * Clear the processed files set (for testing).
+     */
+    clearProcessedFiles() {
+        this.processedFiles.clear();
+    }
+}
+exports.InboundProcessor = InboundProcessor;
+//# sourceMappingURL=inboundProcessor.js.map

package/src/lib/services/emailGateway/inboundProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboundProcessor.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/inboundProcessor.ts"],"names":[],"mappings":"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"}

package/src/lib/services/emailGateway/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Email Gateway module barrel export.
+ *
+ * Re-exports all public gateway components so consumers can import from
+ * `@brightchain/brightchain-api-lib` (via the services barrel) with a
+ * single import path.
+ *
+ * @see Requirements 11.2, 11.3
+ * @module emailGateway
+ */
+export * from './antiSpamFilter';
+export * from './bounceProcessor';
+export * from './emailAuthVerifier';
+export * from './emailGatewayConfig';
+export * from './emailGatewayService';
+export * from './gatewayObservability';
+export * from './inboundProcessor';
+export * from './outboundDeliveryWorker';
+export * from './outboundQueue';
+export * from './outboundQueueStore';
+export * from './recipientLookupService';
+export * from './retryBackoff';
+//# sourceMappingURL=index.d.ts.map

package/src/lib/services/emailGateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC"}

package/src/lib/services/emailGateway/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Email Gateway module barrel export.
+ *
+ * Re-exports all public gateway components so consumers can import from
+ * `@brightchain/brightchain-api-lib` (via the services barrel) with a
+ * single import path.
+ *
+ * @see Requirements 11.2, 11.3
+ * @module emailGateway
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./antiSpamFilter"), exports);
+tslib_1.__exportStar(require("./bounceProcessor"), exports);
+tslib_1.__exportStar(require("./emailAuthVerifier"), exports);
+tslib_1.__exportStar(require("./emailGatewayConfig"), exports);
+tslib_1.__exportStar(require("./emailGatewayService"), exports);
+tslib_1.__exportStar(require("./gatewayObservability"), exports);
+tslib_1.__exportStar(require("./inboundProcessor"), exports);
+tslib_1.__exportStar(require("./outboundDeliveryWorker"), exports);
+tslib_1.__exportStar(require("./outboundQueue"), exports);
+tslib_1.__exportStar(require("./outboundQueueStore"), exports);
+tslib_1.__exportStar(require("./recipientLookupService"), exports);
+tslib_1.__exportStar(require("./retryBackoff"), exports);
+//# sourceMappingURL=index.js.map

package/src/lib/services/emailGateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,2DAAiC;AACjC,4DAAkC;AAClC,8DAAoC;AACpC,+DAAqC;AACrC,gEAAsC;AACtC,iEAAuC;AACvC,6DAAmC;AACnC,mEAAyC;AACzC,0DAAgC;AAChC,+DAAqC;AACrC,mEAAyC;AACzC,yDAA+B"}

package/src/lib/services/emailGateway/outboundDeliveryWorker.d.ts

@@ -0,0 +1,111 @@
+/**
+ * OutboundDeliveryWorker — dequeues messages from the OutboundQueue,
+ * serializes them to RFC 5322 format, applies DKIM signing, and
+ * delegates delivery to Postfix via sendmail or LMTP.
+ *
+ * The worker registers itself as the OutboundQueue's handler so that
+ * each dequeued item flows through the delivery pipeline:
+ *   1. Enforce max message size
+ *   2. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+ *   3. Apply DKIM signature
+ *   4. Send via Postfix transport
+ *   5. Update queue status on success/failure
+ *
+ * Transport and DKIM signing are injected as interfaces so the worker
+ * can be tested without real Postfix or key material.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ * @module outboundDeliveryWorker
+ */
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+import type { IOutboundQueueItem } from './emailGatewayService';
+import type { OutboundQueue } from './outboundQueue';
+import type { IOutboundQueueStore } from './outboundQueueStore';
+/**
+ * Result returned by the Postfix transport after attempting delivery.
+ */
+export interface IPostfixTransportResult {
+    /** Whether the delivery succeeded. */
+    success: boolean;
+    /** SMTP response code (e.g. 250 for success, 4xx for temp failure, 5xx for permanent). */
+    responseCode: number;
+    /** Human-readable response message from the MTA. */
+    responseMessage: string;
+}
+/**
+ * Interface for delegating email delivery to Postfix via sendmail or LMTP.
+ *
+ * Implementations wrap the actual transport mechanism (child_process sendmail,
+ * LMTP socket, etc.) behind a simple async interface.
+ *
+ * @see Requirement 2.4
+ */
+export interface IPostfixTransport {
+    /**
+     * Send a raw RFC 5322 message to the specified recipients.
+     *
+     * @param from - Envelope sender address
+     * @param to - Envelope recipient addresses
+     * @param rawMessage - Complete RFC 5322 message bytes (with DKIM signature)
+     * @returns Delivery result with SMTP response code
+     */
+    send(from: string, to: string[], rawMessage: Uint8Array): Promise<IPostfixTransportResult>;
+}
+/**
+ * Interface for applying DKIM signatures to outbound messages.
+ *
+ * Implementations read the private key from the configured path and
+ * produce a signed message with the DKIM-Signature header prepended.
+ *
+ * @see Requirement 6.1
+ */
+export interface IDkimSigner {
+    /**
+     * Sign a raw RFC 5322 message with DKIM.
+     *
+     * @param rawMessage - The unsigned RFC 5322 message bytes
+     * @param domain - The signing domain (canonical domain)
+     * @param selector - The DKIM selector for DNS lookup
+     * @returns The signed message bytes with DKIM-Signature header prepended
+     */
+    sign(rawMessage: Uint8Array, domain: string, selector: string): Promise<Uint8Array>;
+}
+/**
+ * Worker that processes outbound email delivery from the queue.
+ *
+ * Registers as the OutboundQueue's handler and processes each dequeued
+ * item through the serialization → DKIM → transport pipeline.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ */
+export declare class OutboundDeliveryWorker {
+    private readonly queue;
+    private readonly store;
+    private readonly config;
+    private readonly transport;
+    private readonly dkimSigner;
+    private readonly serializer;
+    /**
+     * @param queue - The outbound queue to register as handler on
+     * @param store - Queue store for updating item status on success/failure
+     * @param config - Gateway configuration (max message size, DKIM settings)
+     * @param transport - Postfix transport for actual SMTP delivery
+     * @param dkimSigner - DKIM signer for message authentication
+     */
+    constructor(queue: OutboundQueue, store: IOutboundQueueStore, config: IEmailGatewayConfig, transport: IPostfixTransport, dkimSigner: IDkimSigner);
+    /**
+     * Handle a single dequeued outbound queue item.
+     *
+     * Pipeline:
+     * 1. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+     * 2. Enforce max message size (Req 2.5)
+     * 3. Apply DKIM signature (Req 6.1)
+     * 4. Delegate to Postfix transport (Req 2.4)
+     * 5. Mark completed or failed in the store
+     *
+     * @param item - The dequeued outbound queue item
+     * @throws Re-throws transport errors so the OutboundQueue can requeue
+     */
+    handleItem(item: IOutboundQueueItem): Promise<void>;
+}
+//# sourceMappingURL=outboundDeliveryWorker.d.ts.map

package/src/lib/services/emailGateway/outboundDeliveryWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundDeliveryWorker.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundDeliveryWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EAAE,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,IAAI,CACF,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAID;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IAW/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAd7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAE7C;;;;;;OAMG;gBAEgB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,SAAS,EAAE,iBAAiB,EAC5B,UAAU,EAAE,WAAW;IAO1C;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;CAuC1D"}

package/src/lib/services/emailGateway/outboundDeliveryWorker.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * OutboundDeliveryWorker — dequeues messages from the OutboundQueue,
+ * serializes them to RFC 5322 format, applies DKIM signing, and
+ * delegates delivery to Postfix via sendmail or LMTP.
+ *
+ * The worker registers itself as the OutboundQueue's handler so that
+ * each dequeued item flows through the delivery pipeline:
+ *   1. Enforce max message size
+ *   2. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+ *   3. Apply DKIM signature
+ *   4. Send via Postfix transport
+ *   5. Update queue status on success/failure
+ *
+ * Transport and DKIM signing are injected as interfaces so the worker
+ * can be tested without real Postfix or key material.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ * @module outboundDeliveryWorker
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboundDeliveryWorker = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// ─── OutboundDeliveryWorker ─────────────────────────────────────────────────
+/**
+ * Worker that processes outbound email delivery from the queue.
+ *
+ * Registers as the OutboundQueue's handler and processes each dequeued
+ * item through the serialization → DKIM → transport pipeline.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ */
+class OutboundDeliveryWorker {
+    queue;
+    store;
+    config;
+    transport;
+    dkimSigner;
+    serializer;
+    /**
+     * @param queue - The outbound queue to register as handler on
+     * @param store - Queue store for updating item status on success/failure
+     * @param config - Gateway configuration (max message size, DKIM settings)
+     * @param transport - Postfix transport for actual SMTP delivery
+     * @param dkimSigner - DKIM signer for message authentication
+     */
+    constructor(queue, store, config, transport, dkimSigner) {
+        this.queue = queue;
+        this.store = store;
+        this.config = config;
+        this.transport = transport;
+        this.dkimSigner = dkimSigner;
+        this.serializer = new brightchain_lib_1.EmailSerializer();
+        // Register this worker as the queue's handler.
+        this.queue.setHandler(this.handleItem.bind(this));
+    }
+    /**
+     * Handle a single dequeued outbound queue item.
+     *
+     * Pipeline:
+     * 1. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+     * 2. Enforce max message size (Req 2.5)
+     * 3. Apply DKIM signature (Req 6.1)
+     * 4. Delegate to Postfix transport (Req 2.4)
+     * 5. Mark completed or failed in the store
+     *
+     * @param item - The dequeued outbound queue item
+     * @throws Re-throws transport errors so the OutboundQueue can requeue
+     */
+    async handleItem(item) {
+        // 1. Serialize metadata to RFC 5322
+        const rawMessage = this.serializer.serialize(item.metadata);
+        // 2. Enforce max message size (Req 2.5)
+        if (rawMessage.byteLength > this.config.maxMessageSizeBytes) {
+            await this.store.markFailed(item.messageId, `Message size ${rawMessage.byteLength} bytes exceeds maximum ${this.config.maxMessageSizeBytes} bytes`);
+            return;
+        }
+        // 3. Apply DKIM signature (Req 6.1)
+        const signedMessage = await this.dkimSigner.sign(rawMessage, this.config.canonicalDomain, this.config.dkimSelector);
+        // 4. Delegate to Postfix transport (Req 2.4)
+        const result = await this.transport.send(item.from, item.to, signedMessage);
+        // 5. Update status based on transport result
+        if (result.success) {
+            await this.store.markCompleted(item.messageId);
+        }
+        else if (result.responseCode >= 500) {
+            // Permanent failure (5xx) — mark failed, do not retry
+            await this.store.markFailed(item.messageId, `Permanent failure (${result.responseCode}): ${result.responseMessage}`);
+        }
+        else {
+            // Temporary failure (4xx) — throw so OutboundQueue requeues with retry logic
+            throw new Error(`Temporary failure (${result.responseCode}): ${result.responseMessage}`);
+        }
+    }
+}
+exports.OutboundDeliveryWorker = OutboundDeliveryWorker;
+//# sourceMappingURL=outboundDeliveryWorker.js.map

package/src/lib/services/emailGateway/outboundDeliveryWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundDeliveryWorker.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundDeliveryWorker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,kEAA+D;AAqE/D,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAa,sBAAsB;IAWd;IACA;IACA;IACA;IACA;IAdF,UAAU,CAAkB;IAE7C;;;;;;OAMG;IACH,YACmB,KAAoB,EACpB,KAA0B,EAC1B,MAA2B,EAC3B,SAA4B,EAC5B,UAAuB;QAJvB,UAAK,GAAL,KAAK,CAAe;QACpB,UAAK,GAAL,KAAK,CAAqB;QAC1B,WAAM,GAAN,MAAM,CAAqB;QAC3B,cAAS,GAAT,SAAS,CAAmB;QAC5B,eAAU,GAAV,UAAU,CAAa;QAExC,IAAI,CAAC,UAAU,GAAG,IAAI,iCAAe,EAAE,CAAC;QACxC,+CAA+C;QAC/C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,CAAC,IAAwB;QACvC,oCAAoC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE5D,wCAAwC;QACxC,IAAI,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC5D,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CACzB,IAAI,CAAC,SAAS,EACd,gBAAgB,UAAU,CAAC,UAAU,0BAA0B,IAAI,CAAC,MAAM,CAAC,mBAAmB,QAAQ,CACvG,CAAC;YACF,OAAO;QACT,CAAC;QAED,oCAAoC;QACpC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAC9C,UAAU,EACV,IAAI,CAAC,MAAM,CAAC,eAAe,EAC3B,IAAI,CAAC,MAAM,CAAC,YAAY,CACzB,CAAC;QAEF,6CAA6C;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QAE5E,6CAA6C;QAC7C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,CAAC;aAAM,IAAI,MAAM,CAAC,YAAY,IAAI,GAAG,EAAE,CAAC;YACtC,sDAAsD;YACtD,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CACzB,IAAI,CAAC,SAAS,EACd,sBAAsB,MAAM,CAAC,YAAY,MAAM,MAAM,CAAC,eAAe,EAAE,CACxE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,6EAA6E;YAC7E,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,CAAC,YAAY,MAAM,MAAM,CAAC,eAAe,EAAE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AA1ED,wDA0EC"}