@brightchain/brightchain-api-lib 0.25.0 → 0.27.0

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

@@ -0,0 +1,99 @@
+/**
+ * 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
+ */
+import type { IEmailAuthenticationResult } from '@brightchain/brightchain-lib';
+/**
+ * Interface for verifying email authentication results.
+ *
+ * Implementations parse the `Authentication-Results` header from a raw
+ * RFC 5322 message and return structured SPF/DKIM/DMARC results.
+ *
+ * @see Requirements 6.4, 6.5
+ */
+export interface IEmailAuthVerifier {
+    /**
+     * Verify authentication results for an inbound email message.
+     *
+     * @param rawMessage - The raw RFC 5322 message bytes (as deposited by Postfix)
+     * @param senderIp  - Optional IP address of the sending server (for logging)
+     * @returns Structured authentication results for SPF, DKIM, and DMARC
+     */
+    verify(rawMessage: Uint8Array | Buffer, senderIp?: string): IEmailAuthenticationResult;
+}
+/**
+ * Returns a default `IEmailAuthenticationResult` with all statuses set to `'none'`.
+ */
+export declare function defaultAuthResult(): IEmailAuthenticationResult;
+/**
+ * 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
+ */
+export declare class EmailAuthVerifier implements IEmailAuthVerifier {
+    /**
+     * 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: Uint8Array | Buffer, _senderIp?: string): IEmailAuthenticationResult;
+    /**
+     * 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: IEmailAuthenticationResult): boolean;
+    /**
+     * 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.
+     */
+    private extractAuthResultsHeader;
+    /**
+     * 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.
+     */
+    private parseAuthResultsHeader;
+    /**
+     * Parse a single method result segment like `spf=pass (details here)`.
+     */
+    private parseMethodResult;
+}
+//# sourceMappingURL=emailAuthVerifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emailAuthVerifier.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/emailAuthVerifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAI/E;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,MAAM,CACJ,UAAU,EAAE,UAAU,GAAG,MAAM,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,0BAA0B,CAAC;CAC/B;AAoCD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,0BAA0B,CAM9D;AAID;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D;;;;;;;;;OASG;IACH,MAAM,CACJ,UAAU,EAAE,UAAU,GAAG,MAAM,EAC/B,SAAS,CAAC,EAAE,MAAM,GACjB,0BAA0B;IAQ7B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO;IAMrE;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IA8ChC;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAmB9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAqC1B"}

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,74 @@
+/**
+ * Email Gateway Configuration
+ *
+ * Defines the `IEmailGatewayConfig` interface and a `loadGatewayConfig()` loader
+ * that reads values from `environment.emailDomain` (EMAIL_DOMAIN env var) and
+ * other 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 environment.emailDomain / EMAIL_DOMAIN env var). 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 environment variables.
+ *
+ * The canonical domain is read from the `EMAIL_DOMAIN` env var (matching
+ * `environment.emailDomain`). All other settings are read from their
+ * respective `GATEWAY_*` env vars with sensible defaults.
+ *
+ * @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,EACL,KAAK,eAAe,EACrB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,0HAA0H;IAC1H,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;;;;;;;;;;GAUG;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 `environment.emailDomain` (EMAIL_DOMAIN env var) and
+ * other 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;
+/** 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 environment variables.
+ *
+ * The canonical domain is read from the `EMAIL_DOMAIN` env var (matching
+ * `environment.emailDomain`). All other settings are read from their
+ * respective `GATEWAY_*` env vars with sensible defaults.
+ *
+ * @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: envString('EMAIL_DOMAIN', 'example.com'),
+        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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"}