@brightchain/brightchain-api-lib 0.25.0 → 0.27.0

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

@@ -0,0 +1,110 @@
+/**
+ * Outbound Queue Store — persistence interface and in-memory implementation
+ * for the outbound email delivery queue.
+ *
+ * The `IOutboundQueueStore` interface defines the contract for queue persistence,
+ * allowing different backends (in-memory for testing, database/filesystem for
+ * production) to be swapped without changing the queue logic.
+ *
+ * The `InMemoryOutboundQueueStore` provides a FIFO-ordered, Map-backed
+ * implementation suitable for unit/integration testing.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ * @module outboundQueueStore
+ */
+import type { IOutboundQueueItem } from './emailGatewayService';
+/**
+ * Persistence interface for the outbound email delivery queue.
+ *
+ * Implementations must maintain FIFO ordering (Req 9.3) and support
+ * concurrent access patterns (Req 9.4). The store is responsible only
+ * for persistence — concurrency limiting and processing loops are
+ * handled by the `OutboundQueue` class (task 4.2).
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+export interface IOutboundQueueStore {
+    /**
+     * Add a message to the end of the queue.
+     *
+     * @param item - The outbound queue item to enqueue
+     * @throws If the store is unavailable (Req 9.5)
+     */
+    enqueue(item: IOutboundQueueItem): Promise<void>;
+    /**
+     * Remove and return the next item from the front of the queue
+     * that is in `Queued` status and ready for delivery.
+     *
+     * @returns The next queue item, or `undefined` if the queue is empty
+     *          or no items are ready
+     */
+    dequeue(): Promise<IOutboundQueueItem | undefined>;
+    /**
+     * Return the next item from the front of the queue without removing it.
+     *
+     * @returns The next queue item, or `undefined` if the queue is empty
+     */
+    peek(): Promise<IOutboundQueueItem | undefined>;
+    /**
+     * Mark a message as successfully delivered and remove it from the queue.
+     *
+     * @param messageId - The RFC 5322 Message-ID of the completed message
+     */
+    markCompleted(messageId: string): Promise<void>;
+    /**
+     * Mark a message as permanently failed and remove it from the active queue.
+     *
+     * @param messageId - The RFC 5322 Message-ID of the failed message
+     * @param reason - Human-readable failure reason
+     */
+    markFailed(messageId: string, reason: string): Promise<void>;
+    /**
+     * Re-enqueue a message for retry with updated retry count and status.
+     *
+     * The item is placed at the end of the queue to maintain FIFO fairness
+     * among messages at the same priority level (Req 9.3).
+     *
+     * @param item - The updated queue item with incremented retryCount
+     */
+    requeue(item: IOutboundQueueItem): Promise<void>;
+    /**
+     * Return the current number of items in the queue.
+     *
+     * @returns The queue depth (number of pending items)
+     */
+    getQueueDepth(): Promise<number>;
+    /**
+     * Retrieve a queue item by its Message-ID.
+     *
+     * @param messageId - The RFC 5322 Message-ID to look up
+     * @returns The queue item, or `undefined` if not found
+     */
+    getByMessageId(messageId: string): Promise<IOutboundQueueItem | undefined>;
+}
+/**
+ * In-memory implementation of `IOutboundQueueStore` for testing.
+ *
+ * Uses a `Map` keyed by messageId for O(1) lookups and an insertion-ordered
+ * array (`queue`) to maintain strict FIFO ordering (Req 9.3).
+ *
+ * This implementation is NOT suitable for production — it does not survive
+ * process restarts (Req 9.1 requires durable storage). Use a database-backed
+ * or filesystem-backed implementation for production deployments.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+export declare class InMemoryOutboundQueueStore implements IOutboundQueueStore {
+    /** Ordered list of message IDs representing FIFO queue order. */
+    private readonly queue;
+    /** Map from messageId → queue item for O(1) lookups. */
+    private readonly items;
+    enqueue(item: IOutboundQueueItem): Promise<void>;
+    dequeue(): Promise<IOutboundQueueItem | undefined>;
+    peek(): Promise<IOutboundQueueItem | undefined>;
+    markCompleted(messageId: string): Promise<void>;
+    markFailed(messageId: string, _reason: string): Promise<void>;
+    requeue(item: IOutboundQueueItem): Promise<void>;
+    getQueueDepth(): Promise<number>;
+    getByMessageId(messageId: string): Promise<IOutboundQueueItem | undefined>;
+}
+//# sourceMappingURL=outboundQueueStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outboundQueueStore.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundQueueStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAEnD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAEhD;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;CAC5E;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IAE9D,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,OAAO,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAoClD,IAAI,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAW/C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAWhC,cAAc,CAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;CAI3C"}

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

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Outbound Queue Store — persistence interface and in-memory implementation
+ * for the outbound email delivery queue.
+ *
+ * The `IOutboundQueueStore` interface defines the contract for queue persistence,
+ * allowing different backends (in-memory for testing, database/filesystem for
+ * production) to be swapped without changing the queue logic.
+ *
+ * The `InMemoryOutboundQueueStore` provides a FIFO-ordered, Map-backed
+ * implementation suitable for unit/integration testing.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ * @module outboundQueueStore
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryOutboundQueueStore = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/**
+ * In-memory implementation of `IOutboundQueueStore` for testing.
+ *
+ * Uses a `Map` keyed by messageId for O(1) lookups and an insertion-ordered
+ * array (`queue`) to maintain strict FIFO ordering (Req 9.3).
+ *
+ * This implementation is NOT suitable for production — it does not survive
+ * process restarts (Req 9.1 requires durable storage). Use a database-backed
+ * or filesystem-backed implementation for production deployments.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+class InMemoryOutboundQueueStore {
+    /** Ordered list of message IDs representing FIFO queue order. */
+    queue = [];
+    /** Map from messageId → queue item for O(1) lookups. */
+    items = new Map();
+    async enqueue(item) {
+        // If an item with the same messageId already exists, replace it
+        // (this can happen on requeue after status update).
+        if (!this.items.has(item.messageId)) {
+            this.queue.push(item.messageId);
+        }
+        this.items.set(item.messageId, { ...item });
+    }
+    async dequeue() {
+        // Walk the queue front-to-back to find the first item in Queued status
+        // that is ready for processing (nextAttemptAt <= now or not set).
+        const now = Date.now();
+        for (let i = 0; i < this.queue.length; i++) {
+            const messageId = this.queue[i];
+            const item = this.items.get(messageId);
+            if (!item) {
+                // Stale entry — item was removed (markCompleted/markFailed).
+                this.queue.splice(i, 1);
+                i--;
+                continue;
+            }
+            if (item.status !== brightchain_lib_1.OutboundDeliveryStatus.Queued) {
+                // Item exists but is not in Queued status — remove stale entry.
+                this.queue.splice(i, 1);
+                i--;
+                continue;
+            }
+            // Respect nextAttemptAt: skip items that are not yet ready.
+            if (item.nextAttemptAt && item.nextAttemptAt.getTime() > now) {
+                continue;
+            }
+            // Item is ready — remove from queue and return.
+            this.queue.splice(i, 1);
+            this.items.delete(messageId);
+            return { ...item };
+        }
+        return undefined;
+    }
+    async peek() {
+        // Walk the queue front-to-back to find the first item in Queued status.
+        for (const messageId of this.queue) {
+            const item = this.items.get(messageId);
+            if (item && item.status === brightchain_lib_1.OutboundDeliveryStatus.Queued) {
+                return { ...item };
+            }
+        }
+        return undefined;
+    }
+    async markCompleted(messageId) {
+        const item = this.items.get(messageId);
+        if (item) {
+            item.status = brightchain_lib_1.OutboundDeliveryStatus.Delivered;
+            this.items.delete(messageId);
+            const idx = this.queue.indexOf(messageId);
+            if (idx !== -1) {
+                this.queue.splice(idx, 1);
+            }
+        }
+    }
+    async markFailed(messageId, _reason) {
+        const item = this.items.get(messageId);
+        if (item) {
+            item.status = brightchain_lib_1.OutboundDeliveryStatus.PermanentFailure;
+            this.items.delete(messageId);
+            const idx = this.queue.indexOf(messageId);
+            if (idx !== -1) {
+                this.queue.splice(idx, 1);
+            }
+        }
+    }
+    async requeue(item) {
+        // Remove old position if present, then append to end for FIFO fairness.
+        const existingIdx = this.queue.indexOf(item.messageId);
+        if (existingIdx !== -1) {
+            this.queue.splice(existingIdx, 1);
+        }
+        this.queue.push(item.messageId);
+        this.items.set(item.messageId, { ...item });
+    }
+    async getQueueDepth() {
+        // Count only items that are still in the items map (not stale references).
+        let count = 0;
+        for (const messageId of this.queue) {
+            if (this.items.has(messageId)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    async getByMessageId(messageId) {
+        const item = this.items.get(messageId);
+        return item ? { ...item } : undefined;
+    }
+}
+exports.InMemoryOutboundQueueStore = InMemoryOutboundQueueStore;
+//# sourceMappingURL=outboundQueueStore.js.map

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

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

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

@@ -0,0 +1,146 @@
+/**
+ * RecipientLookupService — TCP socketmap server for Postfix recipient validation.
+ *
+ * Implements the Postfix `socketmap` lookup protocol over TCP so that Postfix
+ * can validate whether a recipient address corresponds to a registered
+ * BrightChain user *before* accepting the message (preventing backscatter).
+ *
+ * Protocol (simplified):
+ *   Client sends: `<name> <key>\n`   (e.g. `virtual alice@brightchain.org\n`)
+ *   Server responds: `OK <value>\n` | `NOTFOUND \n` | `TEMP <reason>\n`
+ *
+ * The service:
+ * - Listens on a configurable TCP port (default 2526) on localhost
+ * - Queries a user-registry dependency for the local part at the canonical domain
+ * - Caches positive results in an LRU cache with configurable TTL (default 300 s)
+ * - Responds within 5 seconds (timeout handling)
+ *
+ * @see Requirements 13.1, 13.2, 13.3, 13.4, 13.5, 13.6, 13.7, 4.1, 4.2, 4.3
+ * @module recipientLookupService
+ */
+import type { IRecipientLookupService } from '@brightchain/brightchain-lib';
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+import type { IDomainAwareComponent } from './emailGatewayService';
+/**
+ * Minimal interface for querying the BrightChain user registry.
+ *
+ * Concrete implementations may delegate to `IMemberStore.queryIndex` or
+ * any other backing store. The recipient lookup service only needs to know
+ * whether a given email address belongs to a registered user.
+ */
+export interface IUserRegistry {
+    /**
+     * Check whether `emailAddress` corresponds to a registered BrightChain user.
+     *
+     * @returns `true` if the user exists, `false` otherwise.
+     * @throws When the registry is unreachable (triggers TEMP response).
+     */
+    hasUser(emailAddress: string): Promise<boolean>;
+}
+/**
+ * Simple LRU cache for positive recipient lookup results.
+ *
+ * Only positive (`OK`) results are cached — negative and temporary results
+ * are always re-queried so that newly registered users are found promptly.
+ *
+ * @see Requirement 13.6
+ */
+export declare class RecipientLookupCache {
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(maxSize: number, ttlMs: number);
+    /**
+     * Retrieve a cached positive result for `key`.
+     *
+     * @returns `true` if the key is cached and not expired, `false` otherwise.
+     */
+    get(key: string): boolean;
+    /**
+     * Store a positive lookup result for `key`.
+     */
+    set(key: string): void;
+    /** Number of entries currently in the cache. */
+    get size(): number;
+    /** Remove all entries. */
+    clear(): void;
+}
+/**
+ * TCP socketmap server that Postfix queries to validate recipient addresses
+ * against the BrightChain user registry.
+ *
+ * Implements `IRecipientLookupService` from brightchain-lib for the `lookup`
+ * contract, and adds TCP server lifecycle (`start` / `stop`).
+ *
+ * @see Requirements 13.1, 13.2, 13.3, 13.4, 13.5, 13.6, 13.7
+ */
+export declare class RecipientLookupService implements IRecipientLookupService, IDomainAwareComponent {
+    private readonly config;
+    private readonly userRegistry;
+    private server;
+    private readonly cache;
+    private readonly port;
+    private canonicalDomain;
+    constructor(config: IEmailGatewayConfig, userRegistry: IUserRegistry);
+    /**
+     * Update the canonical domain used for recipient validation.
+     *
+     * Clears the lookup cache since cached entries may belong to the old domain.
+     *
+     * @param newDomain - The new canonical domain
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    updateCanonicalDomain(newDomain: string): void;
+    /**
+     * Look up whether `emailAddress` corresponds to a registered BrightChain
+     * user at the canonical domain.
+     *
+     * 1. Check the LRU cache for a positive hit.
+     * 2. Query the user registry (with a 5-second timeout).
+     * 3. Cache positive results.
+     *
+     * @returns `'OK'` | `'NOTFOUND'` | `'TEMP'`
+     *
+     * @see Requirements 13.2, 13.3, 13.4, 13.5, 13.6
+     */
+    lookup(emailAddress: string): Promise<'OK' | 'NOTFOUND' | 'TEMP'>;
+    /**
+     * Start the TCP socketmap server on the configured port (localhost only).
+     *
+     * @see Requirement 13.1
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the TCP server and clear the cache.
+     */
+    stop(): Promise<void>;
+    /** Whether the TCP server is currently listening. */
+    isRunning(): boolean;
+    /** Expose cache for testing purposes. */
+    getCache(): RecipientLookupCache;
+    /**
+     * Handle a single TCP connection from Postfix.
+     *
+     * Postfix socketmap protocol:
+     *   Request:  `<mapname> <key>\n`
+     *   Response: `OK <value>\n` | `NOTFOUND \n` | `TEMP <reason>\n`
+     *
+     * The connection may carry multiple newline-delimited requests.
+     */
+    private handleConnection;
+    /**
+     * Parse a socketmap request line and return the response string.
+     *
+     * @param line - A single request line, e.g. `virtual alice@brightchain.org`
+     * @returns The response string, e.g. `OK alice@brightchain.org`
+     */
+    private handleRequest;
+    /**
+     * Race a promise against a timeout.
+     *
+     * @throws If the timeout fires first.
+     */
+    private withTimeout;
+}
+//# sourceMappingURL=recipientLookupService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recipientLookupService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/recipientLookupService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAInE;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjD;AAUD;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;gBAGpC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;IAGhC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAezB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAetB,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0BAA0B;IAC1B,KAAK,IAAI,IAAI;CAGd;AAaD;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,uBAAuB,EAAE,qBAAqB;IAOzF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAP/B,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAS;gBAGb,MAAM,EAAE,mBAAmB,EAC3B,YAAY,EAAE,aAAa;IAU9C;;;;;;;;OAQG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO9C;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;IAsCvE;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrB,qDAAqD;IACrD,SAAS,IAAI,OAAO;IAIpB,yCAAyC;IACzC,QAAQ,IAAI,oBAAoB;IAMhC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IAqCxB;;;;;OAKG;YACW,aAAa;IA0B3B;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAiBpB"}