@brightchain/brightchain-api-lib 0.25.0 → 0.26.0

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

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Email Authentication Verifier — parses SPF/DKIM/DMARC authentication
+ * results from inbound email messages.
+ *
+ * In a typical deployment, Postfix and its milters (e.g. OpenDKIM,
+ * opendmarc, pypolicyd-spf) perform the actual SPF, DKIM, and DMARC
+ * verification before depositing the message in the Mail Drop Directory.
+ * These results are recorded in the `Authentication-Results` header
+ * (RFC 8601).
+ *
+ * This verifier parses those headers from the raw message to extract
+ * structured `IEmailAuthenticationResult` metadata that the
+ * InboundProcessor stores alongside the message.
+ *
+ * @see Requirements 6.4, 6.5
+ * @module emailAuthVerifier
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailAuthVerifier = void 0;
+exports.defaultAuthResult = defaultAuthResult;
+const VALID_SPF_STATUSES = new Set([
+    'pass',
+    'fail',
+    'softfail',
+    'neutral',
+    'none',
+    'temperror',
+    'permerror',
+]);
+const VALID_DKIM_STATUSES = new Set([
+    'pass',
+    'fail',
+    'none',
+    'temperror',
+    'permerror',
+]);
+const VALID_DMARC_STATUSES = new Set([
+    'pass',
+    'fail',
+    'none',
+    'temperror',
+    'permerror',
+]);
+// ─── Default result ─────────────────────────────────────────────────────────
+/**
+ * Returns a default `IEmailAuthenticationResult` with all statuses set to `'none'`.
+ */
+function defaultAuthResult() {
+    return {
+        spf: { status: 'none' },
+        dkim: { status: 'none' },
+        dmarc: { status: 'none' },
+    };
+}
+// ─── Implementation ─────────────────────────────────────────────────────────
+/**
+ * Parses `Authentication-Results` headers from raw RFC 5322 messages to
+ * extract SPF, DKIM, and DMARC verification results.
+ *
+ * This is an adapter/stub that reads results already computed by
+ * Postfix milters. It does NOT perform cryptographic DKIM verification
+ * or DNS lookups itself.
+ *
+ * @see Requirements 6.4, 6.5
+ */
+class EmailAuthVerifier {
+    /**
+     * Parse authentication results from the raw message headers.
+     *
+     * Extracts the `Authentication-Results` header value and parses
+     * individual method results (spf=, dkim=, dmarc=).
+     *
+     * @param rawMessage - Raw RFC 5322 message bytes
+     * @param _senderIp  - Sender IP (unused; reserved for future direct verification)
+     * @returns Structured authentication results
+     */
+    verify(rawMessage, _senderIp) {
+        const headerValue = this.extractAuthResultsHeader(rawMessage);
+        if (!headerValue) {
+            return defaultAuthResult();
+        }
+        return this.parseAuthResultsHeader(headerValue);
+    }
+    /**
+     * Check whether the authentication result indicates a DMARC reject
+     * condition — i.e. DMARC status is `'fail'`.
+     *
+     * The caller (InboundProcessor) uses this to decide whether to move
+     * the message to the error directory with a 550-equivalent rejection.
+     *
+     * @param result - The parsed authentication result
+     * @returns `true` if DMARC failed (reject policy should apply)
+     *
+     * @see Requirement 6.5
+     */
+    static shouldRejectDmarc(result) {
+        return result.dmarc.status === 'fail';
+    }
+    // ─── Header extraction ──────────────────────────────────────────────
+    /**
+     * Extract the value of the first `Authentication-Results` header from
+     * the raw message bytes.
+     *
+     * RFC 5322 headers end at the first blank line (`\r\n\r\n` or `\n\n`).
+     * Header continuation (folding) is handled by joining lines that start
+     * with whitespace.
+     */
+    extractAuthResultsHeader(rawMessage) {
+        const text = typeof rawMessage === 'string'
+            ? rawMessage
+            : Buffer.isBuffer(rawMessage)
+                ? rawMessage.toString('utf-8')
+                : new TextDecoder().decode(rawMessage);
+        // Split headers from body at the first blank line.
+        const headerEndCrLf = text.indexOf('\r\n\r\n');
+        const headerEndLf = text.indexOf('\n\n');
+        let headerSection;
+        if (headerEndCrLf >= 0 &&
+            (headerEndLf < 0 || headerEndCrLf <= headerEndLf)) {
+            headerSection = text.substring(0, headerEndCrLf);
+        }
+        else if (headerEndLf >= 0) {
+            headerSection = text.substring(0, headerEndLf);
+        }
+        else {
+            // No blank line — treat entire content as headers.
+            headerSection = text;
+        }
+        // Unfold continuation lines (lines starting with whitespace are
+        // continuations of the previous header per RFC 5322 §2.2.3).
+        const unfolded = headerSection.replace(/\r?\n([ \t])/g, ' ');
+        // Split into individual header lines.
+        const lines = unfolded.split(/\r?\n/);
+        for (const line of lines) {
+            const match = line.match(/^Authentication-Results:\s*(.+)$/i);
+            if (match) {
+                return match[1].trim();
+            }
+        }
+        return null;
+    }
+    // ─── Header parsing ─────────────────────────────────────────────────
+    /**
+     * Parse an `Authentication-Results` header value into structured results.
+     *
+     * The header format (RFC 8601) is roughly:
+     *   `authserv-id; method=status (details); method=status ...`
+     *
+     * We split on `;` and look for `spf=`, `dkim=`, `dmarc=` prefixes.
+     */
+    parseAuthResultsHeader(headerValue) {
+        const result = defaultAuthResult();
+        // Split on semicolons — first segment is the authserv-id, rest are results.
+        const segments = headerValue.split(';').map((s) => s.trim());
+        // Skip the first segment (authserv-id).
+        for (let i = 1; i < segments.length; i++) {
+            const segment = segments[i];
+            if (!segment)
+                continue;
+            this.parseMethodResult(segment, result);
+        }
+        return result;
+    }
+    /**
+     * Parse a single method result segment like `spf=pass (details here)`.
+     */
+    parseMethodResult(segment, result) {
+        // Match pattern: method=status with optional details in parentheses or after whitespace
+        // Examples:
+        //   spf=pass (sender SPF authorized)
+        //   dkim=pass header.d=example.com
+        //   dmarc=fail (p=reject)
+        const methodMatch = segment.match(/^\s*(spf|dkim|dmarc)\s*=\s*(\S+)/i);
+        if (!methodMatch)
+            return;
+        const method = methodMatch[1].toLowerCase();
+        const rawStatus = methodMatch[2].toLowerCase();
+        // Extract optional details in parentheses.
+        const detailsMatch = segment.match(/\(([^)]*)\)/);
+        const details = detailsMatch ? detailsMatch[1].trim() : undefined;
+        switch (method) {
+            case 'spf':
+                if (VALID_SPF_STATUSES.has(rawStatus)) {
+                    result.spf = { status: rawStatus, details };
+                }
+                break;
+            case 'dkim':
+                if (VALID_DKIM_STATUSES.has(rawStatus)) {
+                    result.dkim = { status: rawStatus, details };
+                }
+                break;
+            case 'dmarc':
+                if (VALID_DMARC_STATUSES.has(rawStatus)) {
+                    result.dmarc = { status: rawStatus, details };
+                }
+                break;
+        }
+    }
+}
+exports.EmailAuthVerifier = EmailAuthVerifier;
+//# sourceMappingURL=emailAuthVerifier.js.map

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

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

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

@@ -0,0 +1,73 @@
+/**
+ * Email Gateway Configuration
+ *
+ * Defines the `IEmailGatewayConfig` interface and a `loadGatewayConfig()` loader
+ * that reads values from `CoreConstants.SiteEmailDomain` and environment variables
+ * with sensible defaults.
+ *
+ * All Node.js-specific gateway configuration lives here in brightchain-api-lib.
+ * The shared `ISpamThresholds` interface is imported from brightchain-lib.
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7
+ * @module emailGatewayConfig
+ */
+import { type ISpamThresholds } from '@brightchain/brightchain-lib';
+/**
+ * Complete configuration for the Email Gateway.
+ *
+ * Each field maps to an environment variable (noted in comments) with a
+ * default value applied by `loadGatewayConfig()` when the variable is unset.
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7
+ */
+export interface IEmailGatewayConfig {
+    /** Canonical email domain for this BrightChain instance (from CoreConstants.SiteEmailDomain). Req 8.1 */
+    canonicalDomain: string;
+    /** Postfix MTA hostname. env: GATEWAY_POSTFIX_HOST. Req 8.2 */
+    postfixHost: string;
+    /** Postfix MTA port. env: GATEWAY_POSTFIX_PORT. Req 8.2 */
+    postfixPort: number;
+    /** Optional Postfix authentication credentials. env: GATEWAY_POSTFIX_USER / GATEWAY_POSTFIX_PASS. Req 8.2 */
+    postfixAuth?: {
+        user: string;
+        pass: string;
+    };
+    /** Path to the DKIM private key file. env: GATEWAY_DKIM_KEY_PATH. Req 8.3 */
+    dkimKeyPath: string;
+    /** DKIM selector for DNS lookup. env: GATEWAY_DKIM_SELECTOR. Req 8.3 */
+    dkimSelector: string;
+    /** Directory where Postfix deposits inbound mail (Maildir format). env: GATEWAY_MAIL_DROP_DIR. Req 8.6 */
+    mailDropDirectory: string;
+    /** Directory for messages that fail inbound processing. env: GATEWAY_ERROR_DIR. Req 8.6 */
+    errorDirectory: string;
+    /** Maximum outbound message size in bytes. env: GATEWAY_MAX_MESSAGE_SIZE. Req 8.4 */
+    maxMessageSizeBytes: number;
+    /** TCP port for the Recipient Lookup Service (socketmap). env: GATEWAY_LOOKUP_PORT. Req 8.7 */
+    recipientLookupPort: number;
+    /** Cache TTL in seconds for positive recipient lookups. env: GATEWAY_LOOKUP_CACHE_TTL. Req 8.7 */
+    recipientLookupCacheTtlSeconds: number;
+    /** Anti-spam engine selection. env: GATEWAY_SPAM_ENGINE. Req 8.4 */
+    spamEngine: 'spamassassin' | 'rspamd';
+    /** Score thresholds for spam classification. env: GATEWAY_SPAM_PROBABLE / GATEWAY_SPAM_DEFINITE. Req 8.4 */
+    spamThresholds: ISpamThresholds;
+    /** Maximum concurrent outbound SMTP connections. env: GATEWAY_QUEUE_CONCURRENCY. Req 8.4 */
+    queueConcurrency: number;
+    /** Maximum number of delivery retry attempts. env: GATEWAY_RETRY_MAX_COUNT. Req 8.4 */
+    retryMaxCount: number;
+    /** Maximum total retry duration in milliseconds. env: GATEWAY_RETRY_MAX_DURATION. Req 8.4 */
+    retryMaxDurationMs: number;
+    /** Base interval in milliseconds for exponential back-off. env: GATEWAY_RETRY_BASE_INTERVAL. Req 8.4 */
+    retryBaseIntervalMs: number;
+}
+/**
+ * Load the Email Gateway configuration from `CoreConstants` and environment variables.
+ *
+ * Reads `CoreConstants.SiteEmailDomain` for the canonical domain (Req 8.1) and
+ * environment variables for all other settings, applying defaults where unset.
+ *
+ * @returns A fully populated `IEmailGatewayConfig`.
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7
+ */
+export declare function loadGatewayConfig(): IEmailGatewayConfig;
+//# sourceMappingURL=emailGatewayConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emailGatewayConfig.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/emailGatewayConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,yGAAyG;IACzG,eAAe,EAAE,MAAM,CAAC;IAExB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IAEpB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IAEpB,6GAA6G;IAC7G,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7C,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IAEpB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IAErB,0GAA0G;IAC1G,iBAAiB,EAAE,MAAM,CAAC;IAE1B,2FAA2F;IAC3F,cAAc,EAAE,MAAM,CAAC;IAEvB,qFAAqF;IACrF,mBAAmB,EAAE,MAAM,CAAC;IAE5B,+FAA+F;IAC/F,mBAAmB,EAAE,MAAM,CAAC;IAE5B,kGAAkG;IAClG,8BAA8B,EAAE,MAAM,CAAC;IAEvC,oEAAoE;IACpE,UAAU,EAAE,cAAc,GAAG,QAAQ,CAAC;IAEtC,4GAA4G;IAC5G,cAAc,EAAE,eAAe,CAAC;IAEhC,4FAA4F;IAC5F,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;IAEtB,6FAA6F;IAC7F,kBAAkB,EAAE,MAAM,CAAC;IAE3B,wGAAwG;IACxG,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAmED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAuDvD"}

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

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Email Gateway Configuration
+ *
+ * Defines the `IEmailGatewayConfig` interface and a `loadGatewayConfig()` loader
+ * that reads values from `CoreConstants.SiteEmailDomain` and environment variables
+ * with sensible defaults.
+ *
+ * All Node.js-specific gateway configuration lives here in brightchain-api-lib.
+ * The shared `ISpamThresholds` interface is imported from brightchain-lib.
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7
+ * @module emailGatewayConfig
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGatewayConfig = loadGatewayConfig;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/** Default mail drop directory path */
+const DEFAULT_MAIL_DROP_DIR = '/var/spool/brightchain/incoming/';
+/** Default error directory path */
+const DEFAULT_ERROR_DIR = '/var/spool/brightchain/errors/';
+/** Default maximum message size: 25 MB */
+const DEFAULT_MAX_MESSAGE_SIZE = 25 * 1024 * 1024;
+/** Default recipient lookup port */
+const DEFAULT_LOOKUP_PORT = 2526;
+/** Default recipient lookup cache TTL in seconds */
+const DEFAULT_LOOKUP_CACHE_TTL = 300;
+/** Default queue concurrency */
+const DEFAULT_QUEUE_CONCURRENCY = 10;
+/** Default retry max count */
+const DEFAULT_RETRY_MAX_COUNT = 5;
+/** Default retry max duration: 48 hours in ms */
+const DEFAULT_RETRY_MAX_DURATION = 48 * 60 * 60 * 1000;
+/** Default retry base interval: 60 seconds in ms */
+const DEFAULT_RETRY_BASE_INTERVAL = 60_000;
+/** Default probable spam score threshold */
+const DEFAULT_SPAM_PROBABLE = 5.0;
+/** Default definite spam score threshold */
+const DEFAULT_SPAM_DEFINITE = 10.0;
+/**
+ * Parse an integer from an environment variable, returning a default if unset or invalid.
+ */
+function envInt(name, defaultValue) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '') {
+        return defaultValue;
+    }
+    const parsed = parseInt(raw, 10);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Parse a float from an environment variable, returning a default if unset or invalid.
+ */
+function envFloat(name, defaultValue) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '') {
+        return defaultValue;
+    }
+    const parsed = parseFloat(raw);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Read a string environment variable, returning a default if unset.
+ */
+function envString(name, defaultValue) {
+    const raw = process.env[name];
+    return raw !== undefined && raw !== '' ? raw : defaultValue;
+}
+/**
+ * Load the Email Gateway configuration from `CoreConstants` and environment variables.
+ *
+ * Reads `CoreConstants.SiteEmailDomain` for the canonical domain (Req 8.1) and
+ * environment variables for all other settings, applying defaults where unset.
+ *
+ * @returns A fully populated `IEmailGatewayConfig`.
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7
+ */
+function loadGatewayConfig() {
+    const postfixUser = process.env['GATEWAY_POSTFIX_USER'];
+    const postfixPass = process.env['GATEWAY_POSTFIX_PASS'];
+    return {
+        canonicalDomain: brightchain_lib_1.CoreConstants.SiteEmailDomain,
+        postfixHost: envString('GATEWAY_POSTFIX_HOST', 'localhost'),
+        postfixPort: envInt('GATEWAY_POSTFIX_PORT', 25),
+        postfixAuth: postfixUser && postfixPass
+            ? { user: postfixUser, pass: postfixPass }
+            : undefined,
+        dkimKeyPath: envString('GATEWAY_DKIM_KEY_PATH', '/etc/dkim/private.key'),
+        dkimSelector: envString('GATEWAY_DKIM_SELECTOR', 'default'),
+        mailDropDirectory: envString('GATEWAY_MAIL_DROP_DIR', DEFAULT_MAIL_DROP_DIR),
+        errorDirectory: envString('GATEWAY_ERROR_DIR', DEFAULT_ERROR_DIR),
+        maxMessageSizeBytes: envInt('GATEWAY_MAX_MESSAGE_SIZE', DEFAULT_MAX_MESSAGE_SIZE),
+        recipientLookupPort: envInt('GATEWAY_LOOKUP_PORT', DEFAULT_LOOKUP_PORT),
+        recipientLookupCacheTtlSeconds: envInt('GATEWAY_LOOKUP_CACHE_TTL', DEFAULT_LOOKUP_CACHE_TTL),
+        spamEngine: envString('GATEWAY_SPAM_ENGINE', 'spamassassin'),
+        spamThresholds: {
+            probableSpamScore: envFloat('GATEWAY_SPAM_PROBABLE', DEFAULT_SPAM_PROBABLE),
+            definiteSpamScore: envFloat('GATEWAY_SPAM_DEFINITE', DEFAULT_SPAM_DEFINITE),
+        },
+        queueConcurrency: envInt('GATEWAY_QUEUE_CONCURRENCY', DEFAULT_QUEUE_CONCURRENCY),
+        retryMaxCount: envInt('GATEWAY_RETRY_MAX_COUNT', DEFAULT_RETRY_MAX_COUNT),
+        retryMaxDurationMs: envInt('GATEWAY_RETRY_MAX_DURATION', DEFAULT_RETRY_MAX_DURATION),
+        retryBaseIntervalMs: envInt('GATEWAY_RETRY_BASE_INTERVAL', DEFAULT_RETRY_BASE_INTERVAL),
+    };
+}
+//# sourceMappingURL=emailGatewayConfig.js.map

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

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

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

@@ -0,0 +1,152 @@
+/**
+ * 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
+ */
+import type { IBlockStore, IEmailMetadata, IGossipService } from '@brightchain/brightchain-lib';
+import { EmailMessageService, OutboundDeliveryStatus } from '@brightchain/brightchain-lib';
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+/**
+ * Minimal interface for the outbound email queue.
+ *
+ * The full `OutboundQueue` class (task 4.2) will implement this.
+ * Using an interface here keeps the orchestrator decoupled from the
+ * queue's internal persistence and concurrency details.
+ */
+export interface IOutboundQueue {
+    /**
+     * Add a message to the outbound delivery queue.
+     *
+     * @param message - Outbound message payload with recipient, content, and retry metadata
+     */
+    enqueue(message: IOutboundQueueItem): Promise<void>;
+}
+/**
+ * A single item placed on the outbound delivery queue.
+ */
+export interface IOutboundQueueItem {
+    /** RFC 5322 Message-ID */
+    messageId: string;
+    /** Sender email address */
+    from: string;
+    /** External recipient email addresses */
+    to: string[];
+    /** Email subject */
+    subject?: string;
+    /** Full email metadata for serialization */
+    metadata: IEmailMetadata;
+    /** Timestamp when the item was enqueued */
+    enqueuedAt: Date;
+    /** Current delivery status */
+    status: OutboundDeliveryStatus;
+    /** Number of delivery attempts so far */
+    retryCount: number;
+    /** Earliest time at which the next delivery attempt should be made */
+    nextAttemptAt?: Date;
+}
+/**
+ * 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
+ */
+export declare class EmailGatewayService {
+    private readonly config;
+    private readonly gossipService;
+    private readonly blockStore;
+    private readonly emailMessageService;
+    private outboundQueue?;
+    /** Bound reference kept so we can unsubscribe on stop(). */
+    private readonly boundAnnouncementHandler;
+    /** Whether the service is currently running. */
+    private running;
+    /**
+     * @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: IEmailGatewayConfig, gossipService: IGossipService, blockStore: IBlockStore, emailMessageService: EmailMessageService, outboundQueue?: IOutboundQueue | undefined);
+    /**
+     * Start the gateway service.
+     *
+     * Registers a gossip announcement listener that intercepts outbound
+     * email announcements and delegates them to the outbound queue.
+     */
+    start(): void;
+    /**
+     * Stop the gateway service.
+     *
+     * Removes the gossip listener and marks the service as stopped.
+     */
+    stop(): void;
+    /**
+     * Whether the service is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Wire the outbound queue after construction.
+     *
+     * Useful when the queue is created after the gateway service (e.g.
+     * during staged initialisation).
+     */
+    setOutboundQueue(queue: IOutboundQueue): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string[]): {
+        internal: string[];
+        external: string[];
+    };
+    /**
+     * 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
+     */
+    private handleAnnouncement;
+}
+//# sourceMappingURL=emailGatewayService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emailGatewayService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/emailGatewayService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,cAAc,EACd,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAOhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAElB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,EAAE,EAAE,MAAM,EAAE,CAAC;IAEb,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,QAAQ,EAAE,cAAc,CAAC;IAEzB,2CAA2C;IAC3C,UAAU,EAAE,IAAI,CAAC;IAEjB,8BAA8B;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAE/B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAiB5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,aAAa,CAAC;IApBxB,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAE/B;IAEV,gDAAgD;IAChD,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBAEgB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,cAAc,EAC7B,UAAU,EAAE,WAAW,EACvB,mBAAmB,EAAE,mBAAmB,EACjD,aAAa,CAAC,EAAE,cAAc,YAAA;IAQxC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAQb;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAM7C;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAUlD;;;;;;;OAOG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG;QACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB;IAeD;;;;;;;;;;;;;;OAcG;YACW,kBAAkB;CAoDjC"}