@brightchain/brightchain-api-lib 0.25.0 → 0.26.0

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

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * EmailGatewayService — orchestrator that bridges BrightChain's internal
+ * gossip-based messaging with external SMTP email delivery via Postfix.
+ *
+ * Responsibilities:
+ * - Listen for gossip announcements containing outbound email
+ * - Extract message blocks from the Block Store
+ * - Detect external recipients by comparing domain against canonicalDomain
+ * - Enqueue outbound messages for SMTP delivery
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ * @module emailGatewayService
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailGatewayService = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// ─── EmailGatewayService ────────────────────────────────────────────────────
+/**
+ * Orchestrator service for the Email Gateway.
+ *
+ * Listens for gossip announcements that carry outbound email, extracts the
+ * message content from the Block Store, identifies external recipients by
+ * comparing their domain against the configured `canonicalDomain`, and
+ * enqueues qualifying messages in the OutboundQueue for SMTP delivery.
+ *
+ * Lifecycle:
+ * - `start()` registers the gossip announcement listener
+ * - `stop()` removes the listener and performs cleanup
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ */
+class EmailGatewayService {
+    config;
+    gossipService;
+    blockStore;
+    emailMessageService;
+    outboundQueue;
+    /** Bound reference kept so we can unsubscribe on stop(). */
+    boundAnnouncementHandler;
+    /** Whether the service is currently running. */
+    running = false;
+    /**
+     * @param config          - Gateway configuration (canonical domain, limits, etc.)
+     * @param gossipService   - Gossip protocol service for subscribing to announcements
+     * @param blockStore      - Block store for retrieving message content blocks
+     * @param emailMessageService - Email message service for retrieving email metadata
+     * @param outboundQueue   - Queue for outbound SMTP delivery (optional; set later via `setOutboundQueue`)
+     */
+    constructor(config, gossipService, blockStore, emailMessageService, outboundQueue) {
+        this.config = config;
+        this.gossipService = gossipService;
+        this.blockStore = blockStore;
+        this.emailMessageService = emailMessageService;
+        this.outboundQueue = outboundQueue;
+        // Bind once so the same reference is used for on/off.
+        this.boundAnnouncementHandler = this.handleAnnouncement.bind(this);
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Start the gateway service.
+     *
+     * Registers a gossip announcement listener that intercepts outbound
+     * email announcements and delegates them to the outbound queue.
+     */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.gossipService.onMessageDelivery(this.boundAnnouncementHandler);
+        this.running = true;
+    }
+    /**
+     * Stop the gateway service.
+     *
+     * Removes the gossip listener and marks the service as stopped.
+     */
+    stop() {
+        if (!this.running) {
+            return;
+        }
+        this.gossipService.offMessageDelivery(this.boundAnnouncementHandler);
+        this.running = false;
+    }
+    /**
+     * Whether the service is currently running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Wire the outbound queue after construction.
+     *
+     * Useful when the queue is created after the gateway service (e.g.
+     * during staged initialisation).
+     */
+    setOutboundQueue(queue) {
+        this.outboundQueue = queue;
+    }
+    // ─── Domain Check ──────────────────────────────────────────────────
+    /**
+     * Determine whether an email address is external (not on the canonical domain).
+     *
+     * Extracts the domain portion of the address and compares it
+     * case-insensitively against `config.canonicalDomain`.
+     *
+     * @param emailAddress - A full email address (e.g. `alice@example.com`)
+     * @returns `true` when the address belongs to an external domain
+     *
+     * @see Requirement 1.1 — detect recipients whose domain ≠ canonical domain
+     */
+    isExternalRecipient(emailAddress) {
+        const atIndex = emailAddress.lastIndexOf('@');
+        if (atIndex === -1) {
+            // Malformed address — treat as external to be safe.
+            return true;
+        }
+        const domain = emailAddress.slice(atIndex + 1).toLowerCase();
+        return domain !== this.config.canonicalDomain.toLowerCase();
+    }
+    /**
+     * Partition a list of email addresses into internal and external groups.
+     *
+     * @param addresses - Array of email addresses
+     * @returns Object with `internal` and `external` arrays
+     *
+     * @see Requirement 1.4 — mixed internal/external recipient handling
+     */
+    partitionRecipients(addresses) {
+        const internal = [];
+        const external = [];
+        for (const addr of addresses) {
+            if (this.isExternalRecipient(addr)) {
+                external.push(addr);
+            }
+            else {
+                internal.push(addr);
+            }
+        }
+        return { internal, external };
+    }
+    // ─── Gossip Announcement Handler ───────────────────────────────────
+    /**
+     * Handle a gossip message-delivery announcement.
+     *
+     * When an announcement carries `messageDelivery` metadata the handler:
+     * 1. Retrieves the email metadata from the EmailMessageService
+     * 2. Identifies external recipients
+     * 3. Enqueues the message in the OutboundQueue for SMTP delivery
+     *
+     * Internal-only messages are ignored — they are already delivered via gossip.
+     *
+     * @param announcement - The gossip BlockAnnouncement with messageDelivery metadata
+     *
+     * @see Requirement 1.2 — extract message from Block Store and enqueue
+     * @see Requirement 1.4 — route external recipients to gateway
+     */
+    async handleAnnouncement(announcement) {
+        const delivery = announcement.messageDelivery;
+        if (!delivery) {
+            return;
+        }
+        // Retrieve the email metadata via the message ID.
+        const metadata = await this.emailMessageService.getEmail(delivery.messageId);
+        if (!metadata) {
+            // Message not found — nothing to route.
+            return;
+        }
+        // Collect all recipient addresses from the metadata.
+        const allRecipients = [
+            ...metadata.to.map((m) => m.address),
+            ...(metadata.cc ?? []).map((m) => m.address),
+            ...(metadata.bcc ?? []).map((m) => m.address),
+        ];
+        // Partition into internal / external.
+        const { external } = this.partitionRecipients(allRecipients);
+        if (external.length === 0) {
+            // Purely internal delivery — nothing for the gateway to do.
+            return;
+        }
+        if (!this.outboundQueue) {
+            // Queue not wired yet — cannot enqueue. This is a configuration issue.
+            // In production this would be logged/alerted; for now we silently skip.
+            return;
+        }
+        // Build the queue item and enqueue.
+        const queueItem = {
+            messageId: metadata.messageId,
+            from: metadata.from.address,
+            to: external,
+            subject: metadata.subject,
+            metadata,
+            enqueuedAt: new Date(),
+            status: brightchain_lib_1.OutboundDeliveryStatus.Queued,
+            retryCount: 0,
+        };
+        await this.outboundQueue.enqueue(queueItem);
+    }
+}
+exports.EmailGatewayService = EmailGatewayService;
+//# sourceMappingURL=emailGatewayService.js.map

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

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

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

@@ -0,0 +1,123 @@
+/**
+ * Gateway Observability
+ *
+ * Provides unified logging, metrics collection, and alerting for all
+ * Email Gateway components. Wraps the existing `IMessageLogger`,
+ * `IMessageMetricsCollector`, and `AlertMonitor` services to add
+ * gateway-specific observability.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ * @module gatewayObservability
+ */
+import type { IEmailAuthenticationResult } from '@brightchain/brightchain-lib';
+import { type IMessageLogger, type IMessageMetricsCollector, AlertMonitor } from '@brightchain/brightchain-lib';
+/**
+ * Gateway-specific metrics snapshot exposed by `GatewayObservability`.
+ *
+ * @see Requirement 10.3
+ */
+export interface IGatewayMetricsSnapshot {
+    /** Current number of messages in the outbound queue */
+    outboundQueueDepth: number;
+    /** Total successful deliveries since last reset */
+    deliverySuccessCount: number;
+    /** Total failed deliveries since last reset */
+    deliveryFailureCount: number;
+    /** Delivery success rate (0–1) */
+    deliverySuccessRate: number;
+    /** Delivery failure rate (0–1) */
+    deliveryFailureRate: number;
+    /** Average delivery latency in milliseconds */
+    averageDeliveryLatencyMs: number;
+    /** Total spam rejections since last reset */
+    spamRejectionCount: number;
+    /** Spam rejection rate (0–1, relative to total inbound) */
+    spamRejectionRate: number;
+    /** Total inbound messages processed since last reset */
+    totalInboundProcessed: number;
+}
+/**
+ * Centralised observability for the Email Gateway.
+ *
+ * Integrates with the existing `IMessageLogger`, `IMessageMetricsCollector`,
+ * and `AlertMonitor` services so that all gateway events flow through the
+ * same infrastructure used by the rest of BrightChain.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+export declare class GatewayObservability {
+    private readonly logger;
+    private readonly metrics;
+    private readonly alertMonitor;
+    private _outboundQueueDepth;
+    private _deliverySuccessCount;
+    private _deliveryFailureCount;
+    private _totalDeliveryLatencyMs;
+    private _spamRejectionCount;
+    private _totalInboundProcessed;
+    constructor(logger: IMessageLogger, metrics: IMessageMetricsCollector, alertMonitor: AlertMonitor);
+    /**
+     * Log an outbound delivery attempt.
+     *
+     * Delegates to `IMessageLogger.logMessageCreated` for consistent logging
+     * and records the attempt in the metrics collector.
+     *
+     * @see Requirement 10.1
+     */
+    logOutboundAttempt(recipient: string, statusCode: number, retryCount: number, timestamp: Date): void;
+    /**
+     * Log an inbound email processing event.
+     *
+     * @see Requirement 10.2
+     */
+    logInboundProcessing(sender: string, recipient: string, spamScore: number, authResults: IEmailAuthenticationResult, accepted: boolean): void;
+    /**
+     * Record the current outbound queue depth.
+     *
+     * @see Requirement 10.3
+     */
+    recordQueueDepth(depth: number): void;
+    /**
+     * Record a successful delivery and its latency.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliverySuccess(latencyMs?: number): void;
+    /**
+     * Record a delivery failure.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryFailure(): void;
+    /**
+     * Record delivery latency in milliseconds.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryLatency(ms: number): void;
+    /**
+     * Record a spam rejection.
+     *
+     * @see Requirement 10.3
+     */
+    recordSpamRejection(): void;
+    /**
+     * Emit an alert when delivery fails after all retries are exhausted.
+     *
+     * Delegates to the existing `AlertMonitor` for consistent alerting.
+     *
+     * @see Requirement 10.5
+     */
+    alertDeliveryExhausted(messageId: string, recipient: string, retryCount: number): void;
+    /**
+     * Return a point-in-time snapshot of all gateway-specific metrics.
+     *
+     * @see Requirement 10.3
+     */
+    getMetricsSnapshot(): IGatewayMetricsSnapshot;
+    /**
+     * Reset all gateway-specific counters.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=gatewayObservability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayObservability.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/gatewayObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,YAAY,EACb,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,wBAAwB,EAAE,MAAM,CAAC;IACjC,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAU7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAV/B,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,sBAAsB,CAAK;gBAGhB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,wBAAwB,EACjC,YAAY,EAAE,YAAY;IAK7C;;;;;;;OAOG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,IAAI,GACd,IAAI;IA2BP;;;;OAIG;IACH,oBAAoB,CAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,0BAA0B,EACvC,QAAQ,EAAE,OAAO,GAChB,IAAI;IAoBP;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;OAIG;IACH,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAU/C;;;;OAIG;IACH,qBAAqB,IAAI,IAAI;IAK7B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;OAIG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;;;;;OAMG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,IAAI;IAqBP;;;;OAIG;IACH,kBAAkB,IAAI,uBAAuB;IAwB7C;;OAEG;IACH,KAAK,IAAI,IAAI;CASd"}

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

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Gateway Observability
+ *
+ * Provides unified logging, metrics collection, and alerting for all
+ * Email Gateway components. Wraps the existing `IMessageLogger`,
+ * `IMessageMetricsCollector`, and `AlertMonitor` services to add
+ * gateway-specific observability.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ * @module gatewayObservability
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayObservability = void 0;
+/**
+ * Centralised observability for the Email Gateway.
+ *
+ * Integrates with the existing `IMessageLogger`, `IMessageMetricsCollector`,
+ * and `AlertMonitor` services so that all gateway events flow through the
+ * same infrastructure used by the rest of BrightChain.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+class GatewayObservability {
+    logger;
+    metrics;
+    alertMonitor;
+    // Gateway-specific counters (Req 10.3)
+    _outboundQueueDepth = 0;
+    _deliverySuccessCount = 0;
+    _deliveryFailureCount = 0;
+    _totalDeliveryLatencyMs = 0;
+    _spamRejectionCount = 0;
+    _totalInboundProcessed = 0;
+    constructor(logger, metrics, alertMonitor) {
+        this.logger = logger;
+        this.metrics = metrics;
+        this.alertMonitor = alertMonitor;
+    }
+    // ── Outbound delivery logging (Req 10.1) ──────────────────────────
+    /**
+     * Log an outbound delivery attempt.
+     *
+     * Delegates to `IMessageLogger.logMessageCreated` for consistent logging
+     * and records the attempt in the metrics collector.
+     *
+     * @see Requirement 10.1
+     */
+    logOutboundAttempt(recipient, statusCode, retryCount, timestamp) {
+        // Use the existing logger infrastructure (Req 10.4)
+        this.logger.logMessageCreated(`outbound:${recipient}:${timestamp.toISOString()}`, 'gateway-outbound', 1);
+        this.logger.logRoutingDecision(`outbound:${recipient}`, `smtp-status:${statusCode}:retry:${retryCount}`, 1);
+        // Track success/failure in metrics (Req 10.3)
+        if (statusCode >= 200 && statusCode < 300) {
+            this._deliverySuccessCount++;
+            this.metrics.recordMessageDelivered(0);
+        }
+        else {
+            this._deliveryFailureCount++;
+            this.metrics.recordMessageFailed();
+        }
+        this.metrics.recordMessageSent();
+    }
+    // ── Inbound processing logging (Req 10.2) ─────────────────────────
+    /**
+     * Log an inbound email processing event.
+     *
+     * @see Requirement 10.2
+     */
+    logInboundProcessing(sender, recipient, spamScore, authResults, accepted) {
+        this._totalInboundProcessed++;
+        const messageId = `inbound:${sender}->${recipient}:${Date.now()}`;
+        // Log via existing logger (Req 10.4)
+        this.logger.logMessageCreated(messageId, sender, 1);
+        this.logger.logRoutingDecision(messageId, `spam:${spamScore}|spf:${authResults.spf.status}|dkim:${authResults.dkim.status}|dmarc:${authResults.dmarc.status}|${accepted ? 'accepted' : 'rejected'}`, 1);
+        if (!accepted) {
+            this.logger.logDeliveryFailure(messageId, recipient, 'rejected');
+        }
+    }
+    // ── Metrics recording (Req 10.3) ──────────────────────────────────
+    /**
+     * Record the current outbound queue depth.
+     *
+     * @see Requirement 10.3
+     */
+    recordQueueDepth(depth) {
+        this._outboundQueueDepth = depth;
+        this.metrics.recordStorageUtilization(depth);
+    }
+    /**
+     * Record a successful delivery and its latency.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliverySuccess(latencyMs) {
+        this._deliverySuccessCount++;
+        if (latencyMs !== undefined) {
+            this._totalDeliveryLatencyMs += latencyMs;
+            this.metrics.recordMessageDelivered(latencyMs);
+        }
+        else {
+            this.metrics.recordMessageDelivered(0);
+        }
+    }
+    /**
+     * Record a delivery failure.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryFailure() {
+        this._deliveryFailureCount++;
+        this.metrics.recordMessageFailed();
+    }
+    /**
+     * Record delivery latency in milliseconds.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryLatency(ms) {
+        this._totalDeliveryLatencyMs += ms;
+        this.metrics.recordMessageDelivered(ms);
+    }
+    /**
+     * Record a spam rejection.
+     *
+     * @see Requirement 10.3
+     */
+    recordSpamRejection() {
+        this._spamRejectionCount++;
+        this._totalInboundProcessed++;
+        this.metrics.recordMessageFailed();
+    }
+    // ── Alert emission (Req 10.5) ─────────────────────────────────────
+    /**
+     * Emit an alert when delivery fails after all retries are exhausted.
+     *
+     * Delegates to the existing `AlertMonitor` for consistent alerting.
+     *
+     * @see Requirement 10.5
+     */
+    alertDeliveryExhausted(messageId, recipient, retryCount) {
+        // Use AlertMonitor's failure rate check to trigger handler (Req 10.5)
+        this.alertMonitor.checkFailureRate(this._deliverySuccessCount, this._deliveryFailureCount);
+        // Also emit a specific event-emission alert with context
+        this.alertMonitor.checkEventEmission(`Delivery exhausted: messageId=${messageId}, recipient=${recipient}, retries=${retryCount}`);
+        // Log via existing logger
+        this.logger.logDeliveryFailure(messageId, recipient, `retries exhausted after ${retryCount} attempts`);
+    }
+    // ── Metrics snapshot (Req 10.3) ───────────────────────────────────
+    /**
+     * Return a point-in-time snapshot of all gateway-specific metrics.
+     *
+     * @see Requirement 10.3
+     */
+    getMetricsSnapshot() {
+        const totalDeliveries = this._deliverySuccessCount + this._deliveryFailureCount;
+        const deliveredCount = this._deliverySuccessCount;
+        return {
+            outboundQueueDepth: this._outboundQueueDepth,
+            deliverySuccessCount: this._deliverySuccessCount,
+            deliveryFailureCount: this._deliveryFailureCount,
+            deliverySuccessRate: totalDeliveries > 0 ? deliveredCount / totalDeliveries : 0,
+            deliveryFailureRate: totalDeliveries > 0 ? this._deliveryFailureCount / totalDeliveries : 0,
+            averageDeliveryLatencyMs: deliveredCount > 0 ? this._totalDeliveryLatencyMs / deliveredCount : 0,
+            spamRejectionCount: this._spamRejectionCount,
+            spamRejectionRate: this._totalInboundProcessed > 0
+                ? this._spamRejectionCount / this._totalInboundProcessed
+                : 0,
+            totalInboundProcessed: this._totalInboundProcessed,
+        };
+    }
+    /**
+     * Reset all gateway-specific counters.
+     */
+    reset() {
+        this._outboundQueueDepth = 0;
+        this._deliverySuccessCount = 0;
+        this._deliveryFailureCount = 0;
+        this._totalDeliveryLatencyMs = 0;
+        this._spamRejectionCount = 0;
+        this._totalInboundProcessed = 0;
+        this.metrics.reset();
+    }
+}
+exports.GatewayObservability = GatewayObservability;
+//# sourceMappingURL=gatewayObservability.js.map

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

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

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

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+import type { IBlockStore, IGossipService } from '@brightchain/brightchain-lib';
+import { EmailMessageService, EmailParser } from '@brightchain/brightchain-lib';
+import type { IEmailAuthVerifier } from './emailAuthVerifier';
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+/**
+ * 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
+ */
+export declare class InboundProcessor {
+    private readonly config;
+    private readonly emailMessageService;
+    private readonly blockStore;
+    private readonly gossipService;
+    private readonly parser;
+    /** Authentication verifier for SPF/DKIM/DMARC. Req 6.4, 6.5 */
+    private readonly authVerifier;
+    /** fs.watch handle — `null` when stopped. */
+    private watcher;
+    /** Whether the processor is currently running. */
+    private running;
+    /** Filenames that have already been processed (idempotency guard). Req 4.7 */
+    private readonly processedFiles;
+    constructor(config: IEmailGatewayConfig, emailParser: EmailParser | null, emailMessageService: EmailMessageService, blockStore: IBlockStore, gossipService: IGossipService, authVerifier?: IEmailAuthVerifier);
+    /**
+     * 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(): void;
+    /**
+     * Stop watching the Mail Drop Directory.
+     */
+    stop(): void;
+    /**
+     * Whether the processor is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Process all files already present in the Mail Drop Directory.
+     * Called once on startup to handle files deposited while the processor
+     * was not running.
+     */
+    private processExistingFiles;
+    /**
+     * 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
+     */
+    processFile(filename: string): Promise<void>;
+    /**
+     * 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
+     */
+    private mergeAuthHeaders;
+    /**
+     * Extract plain-text body from parsed email metadata.
+     */
+    private extractTextBody;
+    /**
+     * Extract HTML body from parsed email metadata.
+     */
+    private extractHtmlBody;
+    /**
+     * Get the set of processed filenames (for testing / inspection).
+     */
+    getProcessedFiles(): ReadonlySet<string>;
+    /**
+     * Clear the processed files set (for testing).
+     */
+    clearProcessedFiles(): void;
+}
+//# sourceMappingURL=inboundProcessor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inboundProcessor.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/inboundProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAEV,WAAW,EAGX,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAgBzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAnBhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,6CAA6C;IAC7C,OAAO,CAAC,OAAO,CAA6B;IAE5C,kDAAkD;IAClD,OAAO,CAAC,OAAO,CAAS;IAExB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAGtC,MAAM,EAAE,mBAAmB,EAC5C,WAAW,EAAE,WAAW,GAAG,IAAI,EACd,mBAAmB,EAAE,mBAAmB,EACxC,UAAU,EAAE,WAAW,EACvB,aAAa,EAAE,cAAc,EAC9C,YAAY,CAAC,EAAE,kBAAkB;IAQnC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IA4Bb;;OAEG;IACH,IAAI,IAAI,IAAI;IAWZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAMpB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4GlD;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,iBAAiB,IAAI,WAAW,CAAC,MAAM,CAAC;IAIxC;;OAEG;IACH,mBAAmB,IAAI,IAAI;CAG5B"}