@troykelly/openclaw-projects 0.0.11 → 0.0.12

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

package/dist/utils/spam-filter.js.map

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

package/dist/utils/token-budget.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Token budget tracking utility for inbound message processing.
+ *
+ * Provides configurable daily and monthly caps on token expenditure
+ * to protect against cost overruns from bulk inbound messages.
+ *
+ * Part of Issue #1225 — rate limiting and spam protection.
+ */
+/** Configuration for token budget tracking */
+export interface TokenBudgetConfig {
+    /** Whether token budget enforcement is enabled */
+    enabled: boolean;
+    /** Maximum tokens per day (optional, no limit if omitted) */
+    dailyTokenLimit?: number;
+    /** Maximum tokens per month (optional, no limit if omitted) */
+    monthlyTokenLimit?: number;
+}
+/** Result of a token budget check */
+export interface TokenBudgetResult {
+    /** Whether the token request is allowed */
+    allowed: boolean;
+    /** Human-readable reason if denied, null if allowed */
+    reason: string | null;
+    /** Tokens remaining in daily budget (undefined if no daily limit) */
+    remainingDaily?: number;
+    /** Tokens remaining in monthly budget (undefined if no monthly limit) */
+    remainingMonthly?: number;
+}
+/** Token budget usage statistics */
+export interface TokenBudgetStats {
+    /** Tokens used today */
+    dailyUsed: number;
+    /** Tokens used this month */
+    monthlyUsed: number;
+    /** Daily token limit (undefined if not set) */
+    dailyLimit?: number;
+    /** Monthly token limit (undefined if not set) */
+    monthlyLimit?: number;
+}
+/** Token budget instance */
+export interface TokenBudget {
+    /** Check if a token expenditure is allowed (read-only, does not record) */
+    check(tokens: number): TokenBudgetResult;
+    /** Record actual token usage */
+    record(tokens: number): void;
+    /**
+     * Atomically check and record token usage.
+     * Prevents TOCTOU races where concurrent check() calls both pass
+     * before either records, allowing the budget to be exceeded.
+     * Returns the check result; if allowed, tokens are already recorded.
+     */
+    tryConsume(tokens: number): TokenBudgetResult;
+    /** Get current usage statistics */
+    getStats(): TokenBudgetStats;
+}
+/** Default configuration (budget disabled) */
+export declare const DEFAULT_TOKEN_BUDGET_CONFIG: TokenBudgetConfig;
+/**
+ * Create a token budget tracker.
+ *
+ * Tracks daily and monthly token usage with automatic reset at
+ * UTC midnight (daily) and UTC month boundary (monthly).
+ *
+ * @param config - Token budget configuration
+ * @returns TokenBudget instance
+ */
+export declare function createTokenBudget(config?: TokenBudgetConfig): TokenBudget;
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/utils/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/utils/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACzC,gCAAgC;IAChC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAC9C,mCAAmC;IACnC,QAAQ,IAAI,gBAAgB,CAAC;CAC9B;AAED,8CAA8C;AAC9C,eAAO,MAAM,2BAA2B,EAAE,iBAEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,iBAA+C,GAAG,WAAW,CAyItG"}