@brightchain/brightchain-api-lib 0.24.1 → 0.26.0

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

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * AntiSpamFilter — milter integration adapter for SpamAssassin/Rspamd
+ * score classification of inbound email messages.
+ *
+ * The filter wraps a configurable spam engine client (SpamAssassin via
+ * spamc protocol or Rspamd via HTTP API) and classifies messages as
+ * ham, probable-spam, or definite-spam based on configurable score
+ * thresholds from `ISpamThresholds`.
+ *
+ * Integration with Postfix is via the milter protocol (RFC 6008):
+ * - Definite-spam → signal rejection (SMFIS_REJECT, 550)
+ * - Probable-spam → accept and tag metadata with spam flag and score
+ * - Ham → accept without modification
+ *
+ * @see Requirements 7.1, 7.2, 7.3, 7.4, 7.5
+ * @module antiSpamFilter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AntiSpamFilter = exports.RspamdClient = exports.SpamAssassinClient = void 0;
+const tslib_1 = require("tslib");
+const http = tslib_1.__importStar(require("http"));
+const net = tslib_1.__importStar(require("net"));
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// ─── SpamAssassin Client ────────────────────────────────────────────────────
+/**
+ * SpamAssassin engine client — communicates with spamd via the spamc
+ * TCP protocol (default port 783).
+ *
+ * Protocol overview:
+ * 1. Connect to spamd TCP socket
+ * 2. Send `SYMBOLS SPAMC/1.5\r\nContent-length: <len>\r\n\r\n<message>`
+ * 3. Parse response for `Spam: True/False ; <score> / <threshold>` header
+ *
+ * @see Requirement 7.1
+ */
+class SpamAssassinClient {
+    host;
+    port;
+    timeoutMs;
+    constructor(host = 'localhost', port = 783, timeoutMs = 30_000) {
+        this.host = host;
+        this.port = port;
+        this.timeoutMs = timeoutMs;
+    }
+    async scan(rawMessage) {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection({ host: this.host, port: this.port }, () => {
+                const request = `SYMBOLS SPAMC/1.5\r\n` +
+                    `Content-length: ${rawMessage.length}\r\n` +
+                    `\r\n`;
+                socket.write(request);
+                socket.write(rawMessage);
+            });
+            socket.setTimeout(this.timeoutMs);
+            const chunks = [];
+            socket.on('data', (chunk) => {
+                chunks.push(chunk);
+            });
+            socket.on('end', () => {
+                const response = Buffer.concat(chunks).toString('utf-8');
+                resolve(SpamAssassinClient.parseResponse(response));
+            });
+            socket.on('timeout', () => {
+                socket.destroy();
+                reject(new Error('SpamAssassin spamd connection timed out'));
+            });
+            socket.on('error', (err) => {
+                reject(new Error(`SpamAssassin spamd connection error: ${err.message}`));
+            });
+        });
+    }
+    /**
+     * Parse the spamd response to extract score and spam determination.
+     *
+     * Expected header line format:
+     *   `Spam: True ; 15.3 / 5.0`
+     *   `Spam: False ; 1.2 / 5.0`
+     */
+    static parseResponse(response) {
+        const spamMatch = response.match(/Spam:\s*(True|False|Yes|No)\s*;\s*([\d.]+)\s*\/\s*([\d.]+)/i);
+        if (!spamMatch) {
+            return {
+                score: 0,
+                isSpam: false,
+                details: 'Unable to parse spamd response',
+            };
+        }
+        const isSpam = spamMatch[1].toLowerCase() === 'true' ||
+            spamMatch[1].toLowerCase() === 'yes';
+        const score = parseFloat(spamMatch[2]);
+        // Extract rule matches from the body (lines after headers)
+        const bodyStart = response.indexOf('\r\n\r\n');
+        const details = bodyStart >= 0 ? response.substring(bodyStart + 4).trim() : undefined;
+        return { score, isSpam, details: details || undefined };
+    }
+}
+exports.SpamAssassinClient = SpamAssassinClient;
+// ─── Rspamd Client ──────────────────────────────────────────────────────────
+/**
+ * Rspamd engine client — communicates with rspamd via its HTTP API
+ * (default port 11333).
+ *
+ * Protocol overview:
+ * 1. POST raw message to `http://<host>:<port>/checkv2`
+ * 2. Parse JSON response for `score`, `is_spam`/`action`, and `symbols`
+ *
+ * @see Requirement 7.1
+ */
+class RspamdClient {
+    host;
+    port;
+    timeoutMs;
+    constructor(host = 'localhost', port = 11333, timeoutMs = 30_000) {
+        this.host = host;
+        this.port = port;
+        this.timeoutMs = timeoutMs;
+    }
+    async scan(rawMessage) {
+        return new Promise((resolve, reject) => {
+            const options = {
+                hostname: this.host,
+                port: this.port,
+                path: '/checkv2',
+                method: 'POST',
+                headers: {
+                    'Content-Length': rawMessage.length,
+                },
+                timeout: this.timeoutMs,
+            };
+            const req = http.request(options, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => {
+                    chunks.push(chunk);
+                });
+                res.on('end', () => {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    try {
+                        resolve(RspamdClient.parseResponse(body));
+                    }
+                    catch (err) {
+                        reject(new Error(`Rspamd response parse error: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                });
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Rspamd HTTP connection timed out'));
+            });
+            req.on('error', (err) => {
+                reject(new Error(`Rspamd HTTP connection error: ${err.message}`));
+            });
+            req.write(rawMessage);
+            req.end();
+        });
+    }
+    /**
+     * Parse the Rspamd JSON response.
+     *
+     * Expected JSON structure:
+     * ```json
+     * {
+     *   "score": 15.3,
+     *   "required_score": 15.0,
+     *   "action": "reject" | "add header" | "no action" | ...,
+     *   "symbols": { ... }
+     * }
+     * ```
+     */
+    static parseResponse(body) {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return {
+                score: 0,
+                isSpam: false,
+                details: 'Unable to parse Rspamd JSON response',
+            };
+        }
+        const score = typeof parsed['score'] === 'number' ? parsed['score'] : 0;
+        const action = typeof parsed['action'] === 'string' ? parsed['action'] : '';
+        // Rspamd actions: "reject", "rewrite subject", "add header",
+        // "greylist", "no action", "soft reject"
+        const isSpam = action === 'reject' || action === 'add header';
+        // Summarize matched symbols if available
+        let details;
+        if (parsed['symbols'] &&
+            typeof parsed['symbols'] === 'object' &&
+            parsed['symbols'] !== null) {
+            const symbolNames = Object.keys(parsed['symbols']);
+            if (symbolNames.length > 0) {
+                details = symbolNames.join(', ');
+            }
+        }
+        return { score, isSpam, details };
+    }
+}
+exports.RspamdClient = RspamdClient;
+// ─── Anti-Spam Filter Implementation ────────────────────────────────────────
+/**
+ * Milter integration adapter for SpamAssassin/Rspamd score classification.
+ *
+ * Wraps a configurable spam engine client and classifies messages based
+ * on `ISpamThresholds`:
+ * - score < probableSpamScore → Ham (accept)
+ * - probableSpamScore ≤ score < definiteSpamScore → ProbableSpam (tag metadata)
+ * - score ≥ definiteSpamScore → DefiniteSpam (reject 550)
+ *
+ * @see Requirements 7.1, 7.2, 7.3, 7.4, 7.5
+ */
+class AntiSpamFilter {
+    engineClient;
+    thresholds;
+    /**
+     * Create an AntiSpamFilter with the specified engine and thresholds.
+     *
+     * @param engine - Which spam engine to use: `'spamassassin'` or `'rspamd'`
+     * @param thresholds - Score thresholds for classification
+     * @param engineClient - Optional pre-configured engine client (for testing / DI)
+     * @param engineHost - Host for the spam engine (default: localhost)
+     * @param enginePort - Port for the spam engine (default: engine-specific)
+     */
+    constructor(engine, thresholds, engineClient, engineHost, enginePort) {
+        this.thresholds = thresholds;
+        if (engineClient) {
+            this.engineClient = engineClient;
+        }
+        else if (engine === 'rspamd') {
+            this.engineClient = new RspamdClient(engineHost ?? 'localhost', enginePort ?? 11333);
+        }
+        else {
+            this.engineClient = new SpamAssassinClient(engineHost ?? 'localhost', enginePort ?? 783);
+        }
+    }
+    /**
+     * Classify a spam score against the configured thresholds.
+     *
+     * @param score - Numeric spam score from the engine
+     * @returns The spam classification
+     *
+     * @see Requirement 7.2
+     */
+    classify(score) {
+        if (score >= this.thresholds.definiteSpamScore) {
+            return brightchain_lib_1.SpamClassification.DefiniteSpam;
+        }
+        if (score >= this.thresholds.probableSpamScore) {
+            return brightchain_lib_1.SpamClassification.ProbableSpam;
+        }
+        return brightchain_lib_1.SpamClassification.Ham;
+    }
+    /**
+     * Scan a raw email message and return the spam classification result.
+     *
+     * Delegates to the configured spam engine client, then classifies
+     * the returned score against the configured thresholds.
+     *
+     * @param rawMessage - The raw RFC 5322 message bytes
+     * @returns Scan result with score, classification, and optional details
+     *
+     * @see Requirements 7.1, 7.2
+     */
+    async scan(rawMessage) {
+        const engineResult = await this.engineClient.scan(rawMessage);
+        const classification = this.classify(engineResult.score);
+        return {
+            score: engineResult.score,
+            classification,
+            details: engineResult.details,
+        };
+    }
+    /**
+     * Scan a message and return the milter protocol response for Postfix.
+     *
+     * Maps classification to milter actions:
+     * - DefiniteSpam → reject (SMFIS_REJECT, 550)
+     * - ProbableSpam → continue with X-Spam-Flag / X-Spam-Score headers
+     * - Ham → accept
+     *
+     * @param rawMessage - The raw RFC 5322 message bytes
+     * @returns Milter response with action, optional reply code, and headers
+     *
+     * @see Requirements 7.3, 7.4, 7.5
+     */
+    async milterCheck(rawMessage) {
+        const scanResult = await this.scan(rawMessage);
+        switch (scanResult.classification) {
+            case brightchain_lib_1.SpamClassification.DefiniteSpam:
+                // Req 7.3: reject at SMTP time with 550
+                return {
+                    action: 'reject',
+                    replyCode: 550,
+                    replyText: '5.7.1 Message rejected as spam',
+                    scanResult,
+                };
+            case brightchain_lib_1.SpamClassification.ProbableSpam:
+                // Req 7.4: accept and tag metadata with spam flag and score
+                return {
+                    action: 'continue',
+                    addHeaders: {
+                        'X-Spam-Flag': 'YES',
+                        'X-Spam-Score': scanResult.score.toFixed(2),
+                        'X-Spam-Status': `Yes, score=${scanResult.score.toFixed(2)}${scanResult.details ? ` tests=${scanResult.details}` : ''}`,
+                    },
+                    scanResult,
+                };
+            case brightchain_lib_1.SpamClassification.Ham:
+            default:
+                // Ham: accept without modification
+                return {
+                    action: 'accept',
+                    addHeaders: {
+                        'X-Spam-Flag': 'NO',
+                        'X-Spam-Score': scanResult.score.toFixed(2),
+                        'X-Spam-Status': `No, score=${scanResult.score.toFixed(2)}${scanResult.details ? ` tests=${scanResult.details}` : ''}`,
+                    },
+                    scanResult,
+                };
+        }
+    }
+}
+exports.AntiSpamFilter = AntiSpamFilter;
+//# sourceMappingURL=antiSpamFilter.js.map

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

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

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

@@ -0,0 +1,171 @@
+/**
+ * BounceProcessor — parses DSN (Delivery Status Notification) messages
+ * per RFC 3464, correlates them to original outbound messages, updates
+ * delivery status, and notifies the original sender via Gossip Protocol.
+ *
+ * DSN correlation strategy:
+ * 1. Extract `Original-Message-ID` or `Message-ID` from the DSN body
+ * 2. Parse VERP-encoded bounce address to extract original message ID
+ *    (e.g. `bounces+msgid=domain@canonical.domain`)
+ * 3. Fall back to fixed bounce address matching
+ *
+ * On permanent failure (5xx / "failed" action):
+ * - Update delivery status to FAILED in the metadata store
+ * - Generate an IBounceNotification and deliver to the original sender
+ *   via the Gossip Protocol
+ *
+ * On transient failure (4xx / "delayed" action):
+ * - Record the transient bounce but do not mark as permanently failed
+ *
+ * @see Requirements 5.1, 5.2, 5.3, 5.4
+ * @module bounceProcessor
+ */
+import type { IGossipService } from '@brightchain/brightchain-lib';
+import { EmailMessageService } from '@brightchain/brightchain-lib';
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+import type { IOutboundQueueStore } from './outboundQueueStore';
+/**
+ * Parsed result from a DSN message (RFC 3464).
+ */
+export interface IParsedDsn {
+    /** The original Message-ID that this DSN refers to */
+    originalMessageId: string | undefined;
+    /** The recipient address that bounced */
+    recipientAddress: string | undefined;
+    /** DSN action: failed, delayed, delivered, relayed, expanded */
+    action: 'failed' | 'delayed' | 'delivered' | 'relayed' | 'expanded' | undefined;
+    /** SMTP diagnostic code (e.g. "550 5.1.1 User unknown") */
+    diagnosticCode: string | undefined;
+    /** SMTP status code (e.g. "5.1.1") */
+    statusCode: string | undefined;
+    /** The envelope-to / return-path from the DSN */
+    envelopeSender: string | undefined;
+}
+/**
+ * Interface for the BounceProcessor to allow dependency injection in tests.
+ */
+export interface IBounceProcessor {
+    /**
+     * Process a raw DSN message.
+     *
+     * @param rawDsn - The raw RFC 3464 DSN message content
+     * @param envelopeSender - Optional envelope sender (Return-Path) for VERP correlation
+     */
+    processDsn(rawDsn: string | Uint8Array, envelopeSender?: string): Promise<void>;
+}
+/**
+ * Processes DSN (Delivery Status Notification) messages to track bounce
+ * status for outbound email.
+ *
+ * @see Requirements 5.1, 5.2, 5.3, 5.4
+ */
+export declare class BounceProcessor implements IBounceProcessor {
+    private readonly config;
+    private readonly emailMessageService;
+    private readonly outboundQueueStore;
+    private readonly gossipService;
+    constructor(config: IEmailGatewayConfig, emailMessageService: EmailMessageService, outboundQueueStore: IOutboundQueueStore, gossipService: IGossipService);
+    /**
+     * Process a raw DSN message.
+     *
+     * Pipeline:
+     * 1. Parse the DSN to extract original message ID, recipient, action, and diagnostic
+     * 2. Correlate to the original outbound message via Message-ID or VERP
+     * 3. On permanent failure: update delivery status to FAILED, notify sender via gossip
+     * 4. On transient failure: log but do not mark as permanently failed
+     *
+     * @param rawDsn - The raw RFC 3464 DSN message content (string or bytes)
+     * @param envelopeSender - Optional envelope sender (Return-Path) for VERP correlation
+     *
+     * @see Requirements 5.1, 5.2, 5.3, 5.4
+     */
+    processDsn(rawDsn: string | Uint8Array, envelopeSender?: string): Promise<void>;
+    /**
+     * Parse a raw DSN message (RFC 3464) to extract the original message
+     * identifier, recipient address, action, and diagnostic code.
+     *
+     * RFC 3464 DSN messages are multipart/report with:
+     * - Part 1: Human-readable explanation
+     * - Part 2: message/delivery-status with per-recipient fields
+     * - Part 3: (optional) original message or headers
+     *
+     * This parser extracts key fields from the delivery-status part using
+     * simple line-based parsing (no full MIME parser needed for DSN fields).
+     *
+     * @param dsnText - The raw DSN message as a string
+     * @returns Parsed DSN fields
+     *
+     * @see Requirement 5.1
+     */
+    static parseDsnMessage(dsnText: string): IParsedDsn;
+    /**
+     * Parse a VERP (Variable Envelope Return Path) encoded bounce address
+     * to extract the original message identifier.
+     *
+     * VERP format: `bounces+<encoded-msgid>=<encoded-domain>@<canonical-domain>`
+     *
+     * Examples:
+     * - `bounces+abc123=example.com@brightchain.org` → `<abc123@example.com>`
+     * - `bounces+msg-001=mail.test.org@brightchain.org` → `<msg-001@mail.test.org>`
+     *
+     * @param bounceAddress - The envelope sender / Return-Path address
+     * @param canonicalDomain - The canonical domain to validate against
+     * @returns The extracted original Message-ID, or undefined if not VERP-encoded
+     *
+     * @see Requirement 5.4
+     */
+    static parseVerpAddress(bounceAddress: string, canonicalDomain: string): string | undefined;
+    /**
+     * Classify a parsed DSN as permanent or transient bounce.
+     *
+     * - Action "failed" or status code starting with "5" → permanent
+     * - Action "delayed" or status code starting with "4" → transient
+     * - Default: permanent (fail-safe)
+     *
+     * @param parsed - The parsed DSN fields
+     * @returns 'permanent' or 'transient'
+     */
+    static classifyBounce(parsed: IParsedDsn): 'permanent' | 'transient';
+    /**
+     * Correlate a parsed DSN to the original outbound message.
+     *
+     * Strategy (in order):
+     * 1. Use `originalMessageId` extracted from DSN headers
+     * 2. Parse VERP-encoded envelope sender to extract message ID
+     * 3. Return undefined if correlation fails
+     *
+     * @param parsed - The parsed DSN fields
+     * @returns The original Message-ID, or undefined if correlation fails
+     *
+     * @see Requirement 5.4
+     */
+    private correlateToOriginal;
+    /**
+     * Update the delivery status of the original message to FAILED.
+     *
+     * Updates both:
+     * - The outbound queue store (OutboundDeliveryStatus.PermanentFailure)
+     * - The email metadata store (DeliveryStatus.Failed on the delivery receipt)
+     *
+     * @param messageId - The original Message-ID
+     * @param recipientAddress - The recipient that bounced
+     * @param failureReason - Human-readable failure reason
+     *
+     * @see Requirement 5.2
+     */
+    private updateDeliveryStatusToFailed;
+    /**
+     * Find the key in the delivery receipts map that matches a recipient address.
+     */
+    private findRecipientKey;
+    /**
+     * Generate a bounce notification and deliver it to the original sender
+     * via the Gossip Protocol.
+     *
+     * @param notification - The bounce notification to deliver
+     *
+     * @see Requirement 5.3
+     */
+    private sendBounceNotification;
+}
+//# sourceMappingURL=bounceProcessor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bounceProcessor.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/bounceProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAEL,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,gEAAgE;IAChE,MAAM,EACF,QAAQ,GACR,SAAS,GACT,WAAW,GACX,SAAS,GACT,UAAU,GACV,SAAS,CAAC;IAEd,2DAA2D;IAC3D,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,sCAAsC;IACtC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/B,iDAAiD;IACjD,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAID;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IAEpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAHb,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,mBAAmB,EACxC,kBAAkB,EAAE,mBAAmB,EACvC,aAAa,EAAE,cAAc;IAKhD;;;;;;;;;;;;;OAaG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAiDhB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAuFnD;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,gBAAgB,CACrB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,GACtB,MAAM,GAAG,SAAS;IAiCrB;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW;IAgBpE;;;;;;;;;;;;OAYG;YACW,mBAAmB;IAkCjC;;;;;;;;;;;;OAYG;YACW,4BAA4B;IAgD1C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;;;;OAOG;YACW,sBAAsB;CAkCrC"}