@troykelly/openclaw-projects 0.0.10 → 0.0.12

package/dist/utils/nominatim.js

@@ -0,0 +1,56 @@
+/**
+ * Nominatim reverse geocoding client with LRU cache.
+ * Resolves lat/lng to human-readable address and place label.
+ */
+const geocodeCache = new Map();
+const MAX_CACHE_SIZE = 500;
+/**
+ * Rounds coordinates to ~100m precision for cache key deduplication.
+ */
+function cacheKey(lat, lng) {
+    return `${Math.round(lat * 1000) / 1000},${Math.round(lng * 1000) / 1000}`;
+}
+/**
+ * Reverse geocode a lat/lng pair via Nominatim.
+ * Returns null on any failure (timeout, network error, bad response).
+ */
+export async function reverseGeocode(lat, lng, nominatimUrl) {
+    const key = cacheKey(lat, lng);
+    if (geocodeCache.has(key))
+        return geocodeCache.get(key);
+    try {
+        const url = `${nominatimUrl}/reverse?format=jsonv2&lat=${lat}&lon=${lng}`;
+        const response = await fetch(url, {
+            headers: { 'User-Agent': 'openclaw-projects/1.0' },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            console.warn(`[Nominatim] Reverse geocode failed: HTTP ${response.status} for (${lat}, ${lng})`);
+            return null;
+        }
+        const data = (await response.json());
+        const result = {
+            address: data.display_name ?? '',
+            placeLabel: data.name || data.address?.suburb || data.address?.city || '',
+        };
+        if (geocodeCache.size >= MAX_CACHE_SIZE) {
+            const oldest = geocodeCache.keys().next().value;
+            if (oldest !== undefined)
+                geocodeCache.delete(oldest);
+        }
+        geocodeCache.set(key, result);
+        return result;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(`[Nominatim] Reverse geocode error for (${lat}, ${lng}): ${msg}`);
+        return null;
+    }
+}
+/**
+ * Clears the geocode cache (for testing).
+ */
+export function clearGeocodeCache() {
+    geocodeCache.clear();
+}
+//# sourceMappingURL=nominatim.js.map

package/dist/utils/nominatim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nominatim.js","sourceRoot":"","sources":["../../src/utils/nominatim.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,YAAY,GAAG,IAAI,GAAG,EAA4B,CAAC;AACzD,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,GAAW,EACX,YAAoB;IAEpB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC/B,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;IAEzD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,YAAY,8BAA8B,GAAG,QAAQ,GAAG,EAAE,CAAC;QAC1E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE,EAAE,YAAY,EAAE,uBAAuB,EAAE;YAClD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,4CAA4C,QAAQ,CAAC,MAAM,SAAS,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC;YACjG,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAUlC,CAAC;QAEF,MAAM,MAAM,GAAqB;YAC/B,OAAO,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;YAChC,UAAU,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE;SAC1E,CAAC;QAEF,IAAI,YAAY,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,MAAM,KAAK,SAAS;gBAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;QACD,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnE,OAAO,CAAC,IAAI,CAAC,0CAA0C,GAAG,KAAK,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Sliding window rate limiter for inbound message processing.
+ *
+ * Provides per-sender and per-recipient rate limiting with
+ * contact-trust-level awareness. Uses in-memory sliding window
+ * with automatic cleanup of expired entries.
+ *
+ * NOTE: State is in-memory and does not persist across process restarts
+ * or span multiple instances. For multi-instance deployments, a
+ * skill_store-backed implementation would be needed to share rate
+ * limit state across processes.
+ *
+ * Part of Issue #1225 — rate limiting and spam protection.
+ */
+import { type MessageChannel } from './spam-filter.js';
+/** Trust levels for sender classification */
+export type SenderTrust = 'trusted' | 'known' | 'unknown' | 'blocked';
+/** Configuration for the rate limiter */
+export interface RateLimiterConfig {
+    /** Max messages per window for trusted senders (active thread, replied) */
+    trustedSenderLimit: number;
+    /** Max messages per window for known contacts */
+    knownSenderLimit: number;
+    /** Max messages per window for unknown senders */
+    unknownSenderLimit: number;
+    /** Global max messages per window for a single recipient */
+    recipientGlobalLimit: number;
+    /** Sliding window duration in milliseconds */
+    windowMs: number;
+    /**
+     * Maximum number of tracked sender entries before forced eviction.
+     * Prevents unbounded memory growth if traffic burst creates many keys
+     * and then stops (entries would persist until the next cleanup cycle).
+     * When exceeded, the oldest entries are evicted during the next check.
+     */
+    maxSenderEntries?: number;
+}
+/** Result of a rate limit check */
+export interface RateLimitResult {
+    /** Whether the message is allowed */
+    allowed: boolean;
+    /** Human-readable reason if denied, null if allowed */
+    reason: string | null;
+    /** Messages remaining in current window */
+    remaining: number;
+    /** The limit that applies to this sender */
+    limit: number;
+    /** Milliseconds until the earliest entry expires (for retry-after) */
+    retryAfterMs: number | null;
+}
+/** Statistics about the rate limiter state */
+export interface RateLimiterStats {
+    /** Number of currently tracked senders */
+    activeSenders: number;
+    /** Number of currently tracked recipients */
+    activeRecipients: number;
+}
+/** Rate limiter instance */
+export interface RateLimiter {
+    /**
+     * Check if a message is allowed and record it if so.
+     * Sender and recipient are normalized for consistent matching
+     * (phone number formatting, email alias stripping).
+     */
+    check(sender: string, recipient: string, trust: SenderTrust, channel?: MessageChannel): RateLimitResult;
+    /** Get current stats about the limiter */
+    getStats(): RateLimiterStats;
+}
+/** Default rate limiter configuration */
+export declare const DEFAULT_RATE_LIMITER_CONFIG: RateLimiterConfig;
+/**
+ * Create a rate limiter instance.
+ *
+ * Uses a sliding window approach: each message records a timestamp,
+ * and only timestamps within the current window are counted.
+ *
+ * @param config - Rate limiter configuration (uses defaults if omitted)
+ * @returns RateLimiter instance
+ */
+export declare function createRateLimiter(config?: RateLimiterConfig): RateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,eAAe,CAAC;IACxG,0CAA0C;IAC1C,QAAQ,IAAI,gBAAgB,CAAC;CAC9B;AAED,yCAAyC;AACzC,eAAO,MAAM,2BAA2B,EAAE,iBAOzC,CAAC;AAKF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,iBAA+C,GAAG,WAAW,CA0KtG"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,188 @@
+/**
+ * Sliding window rate limiter for inbound message processing.
+ *
+ * Provides per-sender and per-recipient rate limiting with
+ * contact-trust-level awareness. Uses in-memory sliding window
+ * with automatic cleanup of expired entries.
+ *
+ * NOTE: State is in-memory and does not persist across process restarts
+ * or span multiple instances. For multi-instance deployments, a
+ * skill_store-backed implementation would be needed to share rate
+ * limit state across processes.
+ *
+ * Part of Issue #1225 — rate limiting and spam protection.
+ */
+import { normalizeSender } from './spam-filter.js';
+/** Default rate limiter configuration */
+export const DEFAULT_RATE_LIMITER_CONFIG = {
+    trustedSenderLimit: 100,
+    knownSenderLimit: 50,
+    unknownSenderLimit: 5,
+    recipientGlobalLimit: 200,
+    windowMs: 3_600_000, // 1 hour
+    maxSenderEntries: 10_000,
+};
+/** Interval for running cleanup of expired entries */
+const CLEANUP_INTERVAL_CHECKS = 100;
+/**
+ * Create a rate limiter instance.
+ *
+ * Uses a sliding window approach: each message records a timestamp,
+ * and only timestamps within the current window are counted.
+ *
+ * @param config - Rate limiter configuration (uses defaults if omitted)
+ * @returns RateLimiter instance
+ */
+export function createRateLimiter(config = DEFAULT_RATE_LIMITER_CONFIG) {
+    /** Map of sender -> array of message timestamps */
+    const senderWindows = new Map();
+    /** Map of recipient -> array of message timestamps */
+    const recipientWindows = new Map();
+    /** Counter for triggering periodic cleanup */
+    let checkCount = 0;
+    /**
+     * Get the rate limit for a given trust level.
+     */
+    function getLimitForTrust(trust) {
+        switch (trust) {
+            case 'trusted':
+                return config.trustedSenderLimit;
+            case 'known':
+                return config.knownSenderLimit;
+            case 'unknown':
+                return config.unknownSenderLimit;
+            case 'blocked':
+                return 0;
+        }
+    }
+    /**
+     * Prune timestamps older than the window from an array.
+     * Returns only timestamps within the current window.
+     */
+    function pruneWindow(timestamps, now) {
+        const cutoff = now - config.windowMs;
+        return timestamps.filter((ts) => ts > cutoff);
+    }
+    /**
+     * Clean up expired entries from all windows.
+     */
+    function cleanup(now) {
+        for (const [key, timestamps] of senderWindows) {
+            const pruned = pruneWindow(timestamps, now);
+            if (pruned.length === 0) {
+                senderWindows.delete(key);
+            }
+            else {
+                senderWindows.set(key, pruned);
+            }
+        }
+        for (const [key, timestamps] of recipientWindows) {
+            const pruned = pruneWindow(timestamps, now);
+            if (pruned.length === 0) {
+                recipientWindows.delete(key);
+            }
+            else {
+                recipientWindows.set(key, pruned);
+            }
+        }
+    }
+    /**
+     * Evict oldest sender entries when max capacity is exceeded.
+     * Prevents unbounded memory growth from traffic bursts that create
+     * many keys and then stop before the next cleanup cycle runs.
+     *
+     * TODO: This only evicts senderWindows, not recipientWindows. In practice
+     * recipientWindows is bounded by the number of distinct recipients (typically
+     * small), but a similar cap should be added if this assumption changes.
+     */
+    function evictIfOverCapacity() {
+        const maxEntries = config.maxSenderEntries ?? 10_000;
+        if (senderWindows.size <= maxEntries) {
+            return;
+        }
+        // Find entries with the oldest most-recent timestamp and evict them
+        const entries = Array.from(senderWindows.entries()).map(([key, timestamps]) => ({
+            key,
+            newestTs: timestamps.length > 0 ? timestamps[timestamps.length - 1] : 0,
+        }));
+        entries.sort((a, b) => a.newestTs - b.newestTs);
+        const toEvict = senderWindows.size - maxEntries;
+        for (let i = 0; i < toEvict; i++) {
+            senderWindows.delete(entries[i].key);
+        }
+    }
+    return {
+        check(sender, recipient, trust, channel) {
+            const now = Date.now();
+            checkCount++;
+            // Periodic cleanup and eviction to prevent memory leaks
+            if (checkCount % CLEANUP_INTERVAL_CHECKS === 0) {
+                cleanup(now);
+                evictIfOverCapacity();
+            }
+            const limit = getLimitForTrust(trust);
+            // Blocked senders are always denied
+            if (trust === 'blocked') {
+                return {
+                    allowed: false,
+                    reason: 'sender is blocked (zero rate limit)',
+                    remaining: 0,
+                    limit: 0,
+                    retryAfterMs: null,
+                };
+            }
+            // Normalize sender/recipient for consistent tracking across format variants
+            const ch = channel ?? (sender.includes('@') ? 'email' : 'sms');
+            const senderKey = normalizeSender(sender, ch);
+            let senderTimestamps = senderWindows.get(senderKey) ?? [];
+            senderTimestamps = pruneWindow(senderTimestamps, now);
+            if (senderTimestamps.length >= limit) {
+                // Calculate retry-after from the oldest entry in window
+                const oldestTs = senderTimestamps[0];
+                const retryAfterMs = oldestTs + config.windowMs - now;
+                return {
+                    allowed: false,
+                    reason: `per-sender rate limit exceeded (${senderTimestamps.length}/${limit} in window)`,
+                    remaining: 0,
+                    limit,
+                    retryAfterMs: Math.max(0, retryAfterMs),
+                };
+            }
+            // Check per-recipient global limit
+            const recipientCh = channel ?? (recipient.includes('@') ? 'email' : 'sms');
+            const recipientKey = normalizeSender(recipient, recipientCh);
+            let recipientTimestamps = recipientWindows.get(recipientKey) ?? [];
+            recipientTimestamps = pruneWindow(recipientTimestamps, now);
+            if (recipientTimestamps.length >= config.recipientGlobalLimit) {
+                const oldestTs = recipientTimestamps[0];
+                const retryAfterMs = oldestTs + config.windowMs - now;
+                return {
+                    allowed: false,
+                    reason: `global recipient rate limit exceeded (${recipientTimestamps.length}/${config.recipientGlobalLimit} in window)`,
+                    remaining: 0,
+                    limit: config.recipientGlobalLimit,
+                    retryAfterMs: Math.max(0, retryAfterMs),
+                };
+            }
+            // Message is allowed — record it
+            senderTimestamps.push(now);
+            senderWindows.set(senderKey, senderTimestamps);
+            recipientTimestamps.push(now);
+            recipientWindows.set(recipientKey, recipientTimestamps);
+            return {
+                allowed: true,
+                reason: null,
+                remaining: limit - senderTimestamps.length,
+                limit,
+                retryAfterMs: null,
+            };
+        },
+        getStats() {
+            return {
+                activeSenders: senderWindows.size,
+                activeRecipients: recipientWindows.size,
+            };
+        },
+    };
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/utils/spam-filter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Spam filtering utility for inbound message processing.
+ *
+ * Provides pre-processing gate that detects bulk/marketing email,
+ * SMS spam signals, and supports configurable allowlist/blocklist.
+ *
+ * LIMITATION: Header-based spam detection is inherently best-effort.
+ * Sophisticated spammers can omit or forge headers to bypass these checks.
+ * This filter catches the majority of bulk/marketing email and common SMS
+ * spam patterns, but should be complemented with content-based analysis
+ * and external reputation services for production use at scale.
+ *
+ * Part of Issue #1225 — rate limiting and spam protection.
+ */
+/** Supported inbound message channels */
+export type MessageChannel = 'email' | 'sms';
+/** Inbound message to evaluate for spam */
+export interface InboundMessage {
+    /** Message channel (email or sms) */
+    channel: MessageChannel;
+    /** Sender identifier (email address or phone number) */
+    sender: string;
+    /** Recipient identifier */
+    recipient: string;
+    /** Message body text */
+    body: string;
+    /** Email headers (only present for email channel) */
+    headers?: Record<string, string>;
+}
+/** Result of spam evaluation */
+export interface SpamFilterResult {
+    /** Whether the message is classified as spam */
+    isSpam: boolean;
+    /** Human-readable reason for the classification, null if not spam */
+    reason: string | null;
+    /** The channel of the evaluated message */
+    channel: MessageChannel;
+    /** The sender of the evaluated message */
+    sender: string;
+}
+/** Configurable spam filter settings */
+export interface SpamFilterConfig {
+    /** Senders that are always allowed (bypass all checks) */
+    allowlist: string[];
+    /** Senders that are always blocked */
+    blocklist: string[];
+    /** Threshold for X-Spam-Score header (emails scoring above this are spam) */
+    spamScoreThreshold: number;
+    /** Patterns in X-Mailer header that indicate bulk mailers */
+    bulkMailerPatterns: string[];
+    /** Patterns in SMS body that indicate spam */
+    smsSpamPatterns: string[];
+}
+/** Default spam filter configuration */
+export declare const DEFAULT_SPAM_FILTER_CONFIG: SpamFilterConfig;
+/**
+ * Normalize a sender identifier for consistent comparison.
+ *
+ * - Email: lowercased, with `+` alias portion stripped (e.g. user+tag@gmail.com -> user@gmail.com)
+ * - Phone: non-digit characters stripped, leading country code '1' normalized to '+1'
+ *
+ * This prevents bypass via formatting variants like `+1...` vs `1...`
+ * or `user+spam@gmail.com` vs `user@gmail.com`.
+ */
+export declare function normalizeSender(sender: string, channel: MessageChannel): string;
+/**
+ * Evaluate whether an inbound message is spam.
+ *
+ * Checks are applied in this order:
+ * 1. Allowlist (always passes)
+ * 2. Blocklist (always fails)
+ * 3. Channel-specific spam checks (email headers, SMS signals)
+ *
+ * @param message - The inbound message to evaluate
+ * @param config - Optional spam filter configuration (uses defaults if omitted)
+ * @returns SpamFilterResult with classification and reason
+ */
+export declare function isSpam(message: InboundMessage, config?: SpamFilterConfig): SpamFilterResult;
+//# sourceMappingURL=spam-filter.d.ts.map

package/dist/utils/spam-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spam-filter.d.ts","sourceRoot":"","sources":["../../src/utils/spam-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7C,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,OAAO,EAAE,cAAc,CAAC;IACxB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wCAAwC;AACxC,eAAO,MAAM,0BAA0B,EAAE,gBA4BxC,CAAC;AAWF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAK/E;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,GAAE,gBAA6C,GAAG,gBAAgB,CAiCvH"}

package/dist/utils/spam-filter.js

@@ -0,0 +1,237 @@
+/**
+ * Spam filtering utility for inbound message processing.
+ *
+ * Provides pre-processing gate that detects bulk/marketing email,
+ * SMS spam signals, and supports configurable allowlist/blocklist.
+ *
+ * LIMITATION: Header-based spam detection is inherently best-effort.
+ * Sophisticated spammers can omit or forge headers to bypass these checks.
+ * This filter catches the majority of bulk/marketing email and common SMS
+ * spam patterns, but should be complemented with content-based analysis
+ * and external reputation services for production use at scale.
+ *
+ * Part of Issue #1225 — rate limiting and spam protection.
+ */
+/** Default spam filter configuration */
+export const DEFAULT_SPAM_FILTER_CONFIG = {
+    allowlist: [],
+    blocklist: [],
+    spamScoreThreshold: 5.0,
+    bulkMailerPatterns: [
+        'mailchimp',
+        'sendgrid',
+        'constantcontact',
+        'mailgun',
+        'campaign monitor',
+        'hubspot',
+        'marketo',
+        'pardot',
+        'sendinblue',
+        'brevo',
+    ],
+    smsSpamPatterns: [
+        'you have won',
+        'you have been selected',
+        'click here',
+        'free gift',
+        'act now',
+        'limited time',
+        'congratulations',
+        'claim your',
+        'verify now',
+        'your account has been',
+    ],
+};
+/** Email header values indicating bulk/list mail */
+const BULK_PRECEDENCE_VALUES = new Set(['bulk', 'list', 'junk']);
+/** SMS opt-out keywords that indicate marketing messages */
+const SMS_OPT_OUT_KEYWORDS = ['stop', 'unsubscribe', 'opt-out', 'opt out', 'cancel', 'quit', 'end'];
+/** Maximum length for a short code sender (SMS) */
+const SHORT_CODE_MAX_LENGTH = 6;
+/**
+ * Normalize a sender identifier for consistent comparison.
+ *
+ * - Email: lowercased, with `+` alias portion stripped (e.g. user+tag@gmail.com -> user@gmail.com)
+ * - Phone: non-digit characters stripped, leading country code '1' normalized to '+1'
+ *
+ * This prevents bypass via formatting variants like `+1...` vs `1...`
+ * or `user+spam@gmail.com` vs `user@gmail.com`.
+ */
+export function normalizeSender(sender, channel) {
+    if (channel === 'email') {
+        return normalizeEmail(sender);
+    }
+    return normalizePhone(sender);
+}
+/**
+ * Normalize an email address for consistent comparison.
+ * Lowercases and strips `+` alias tags (e.g. user+tag@example.com -> user@example.com).
+ */
+function normalizeEmail(email) {
+    const lower = email.toLowerCase().trim();
+    const atIndex = lower.indexOf('@');
+    if (atIndex === -1) {
+        return lower;
+    }
+    const localPart = lower.slice(0, atIndex);
+    const domain = lower.slice(atIndex);
+    // Strip + alias
+    const plusIndex = localPart.indexOf('+');
+    if (plusIndex !== -1) {
+        return localPart.slice(0, plusIndex) + domain;
+    }
+    return lower;
+}
+/**
+ * Normalize a phone number for consistent comparison.
+ * Strips non-digit characters and normalizes country code.
+ *
+ * TODO: Non-US phone normalization is best-effort. Numbers like `442079460958`
+ * (without +) and `+442079460958` (with +) will normalize differently because
+ * we can only reliably detect US/NANP 10/11-digit patterns. A full solution
+ * would require a phone number parsing library (e.g. libphonenumber) to handle
+ * international formats consistently.
+ */
+function normalizePhone(phone) {
+    // Strip everything except digits and leading +
+    const hasPlus = phone.startsWith('+');
+    const digits = phone.replace(/[^0-9]/g, '');
+    if (digits.length === 0) {
+        return phone.toLowerCase();
+    }
+    // Normalize US numbers: 10 digits -> +1XXXXXXXXXX, 11 digits starting with 1 -> +1XXXXXXXXXX
+    if (digits.length === 10) {
+        return `+1${digits}`;
+    }
+    if (digits.length === 11 && digits.startsWith('1')) {
+        return `+${digits}`;
+    }
+    // For other formats, preserve the + prefix if it was present
+    return hasPlus ? `+${digits}` : digits;
+}
+/**
+ * Evaluate whether an inbound message is spam.
+ *
+ * Checks are applied in this order:
+ * 1. Allowlist (always passes)
+ * 2. Blocklist (always fails)
+ * 3. Channel-specific spam checks (email headers, SMS signals)
+ *
+ * @param message - The inbound message to evaluate
+ * @param config - Optional spam filter configuration (uses defaults if omitted)
+ * @returns SpamFilterResult with classification and reason
+ */
+export function isSpam(message, config = DEFAULT_SPAM_FILTER_CONFIG) {
+    const normalizedSender = normalizeSender(message.sender, message.channel);
+    const result = {
+        isSpam: false,
+        reason: null,
+        channel: message.channel,
+        sender: message.sender,
+    };
+    // Check allowlist first (always passes) — normalize both sides for consistent matching
+    if (config.allowlist.some((allowed) => normalizeSender(allowed, message.channel) === normalizedSender)) {
+        result.reason = 'allowlisted sender';
+        return result;
+    }
+    // Check blocklist (always fails) — normalize both sides for consistent matching
+    if (config.blocklist.some((blocked) => normalizeSender(blocked, message.channel) === normalizedSender)) {
+        result.isSpam = true;
+        result.reason = 'blocklisted sender';
+        return result;
+    }
+    // Channel-specific checks
+    if (message.channel === 'email') {
+        return checkEmailSpam(message, config, result);
+    }
+    if (message.channel === 'sms') {
+        return checkSmsSpam(message, config, result);
+    }
+    return result;
+}
+/**
+ * Check email-specific spam signals.
+ */
+function checkEmailSpam(message, config, result) {
+    const headers = normalizeHeaders(message.headers);
+    // Check Precedence header for bulk/list
+    const precedence = headers.precedence;
+    if (precedence && BULK_PRECEDENCE_VALUES.has(precedence.toLowerCase())) {
+        result.isSpam = true;
+        result.reason = 'bulk precedence header detected';
+        return result;
+    }
+    // Check List-Unsubscribe header
+    if (headers['list-unsubscribe']) {
+        result.isSpam = true;
+        result.reason = 'list-unsubscribe header detected (mailing list)';
+        return result;
+    }
+    // Check X-Spam-Score
+    const spamScore = headers['x-spam-score'];
+    if (spamScore) {
+        const score = Number.parseFloat(spamScore);
+        if (!Number.isNaN(score) && score >= config.spamScoreThreshold) {
+            result.isSpam = true;
+            result.reason = `high spam score (${score} >= ${config.spamScoreThreshold})`;
+            return result;
+        }
+    }
+    // Check X-Mailer for known bulk mailers
+    const xMailer = headers['x-mailer'];
+    if (xMailer) {
+        const mailerLower = xMailer.toLowerCase();
+        for (const pattern of config.bulkMailerPatterns) {
+            if (mailerLower.includes(pattern.toLowerCase())) {
+                result.isSpam = true;
+                result.reason = `bulk mailer detected: ${pattern}`;
+                return result;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Check SMS-specific spam signals.
+ */
+function checkSmsSpam(message, config, result) {
+    // Check for short code sender
+    const senderDigits = message.sender.replace(/[^0-9]/g, '');
+    if (senderDigits.length > 0 && senderDigits.length <= SHORT_CODE_MAX_LENGTH) {
+        result.isSpam = true;
+        result.reason = 'short code sender detected';
+        return result;
+    }
+    const bodyLower = message.body.toLowerCase();
+    // Check for opt-out keywords (indicates marketing/automated message)
+    for (const keyword of SMS_OPT_OUT_KEYWORDS) {
+        if (bodyLower.includes(keyword)) {
+            result.isSpam = true;
+            result.reason = `opt-out keyword detected: ${keyword}`;
+            return result;
+        }
+    }
+    // Check for common SMS spam patterns
+    for (const pattern of config.smsSpamPatterns) {
+        if (bodyLower.includes(pattern.toLowerCase())) {
+            result.isSpam = true;
+            result.reason = `spam pattern detected: ${pattern}`;
+            return result;
+        }
+    }
+    return result;
+}
+/**
+ * Normalize email headers to lowercase keys for consistent lookup.
+ */
+function normalizeHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[key.toLowerCase()] = value;
+    }
+    return normalized;
+}
+//# sourceMappingURL=spam-filter.js.map