@firela/billclaw-core 0.1.5 → 0.3.0

package/dist/webhooks/security.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Webhook security layer (P0)
+ *
+ * Provides replay attack protection, signature verification, and
+ * rate limiting coordination for inbound webhooks.
+ *
+ * Security features:
+ * - Replay attack protection using timestamp + nonce validation
+ * - HMAC-SHA256 signature verification with timing-safe comparison
+ * - Rate limiting coordination
+ */
+import type { Logger } from "../errors/errors.js";
+import type { WebhookDeduplication } from "./deduplication.js";
+/**
+ * Configuration for webhook security
+ */
+export interface WebhookSecurityConfig {
+    /**
+     * Maximum allowed timestamp age in milliseconds
+     * Default: 15 minutes
+     */
+    maxTimestampAge?: number;
+    /**
+     * Future timestamp tolerance in milliseconds
+     * Default: 5 minutes (to handle clock skew)
+     */
+    futureTimestampTolerance?: number;
+    /**
+     * Deduplication cache for nonce tracking
+     */
+    deduplication: WebhookDeduplication;
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+}
+/**
+ * Webhook security layer
+ *
+ * Provides P0 security features for webhook processing.
+ */
+export declare class WebhookSecurity {
+    private readonly maxTimestampAge;
+    private readonly futureTolerance;
+    private readonly deduplication;
+    private readonly logger;
+    constructor(config: WebhookSecurityConfig);
+    /**
+     * Validate replay protection (timestamp + nonce)
+     *
+     * Checks that:
+     * 1. Timestamp is within valid range (not too old, not too far in future)
+     * 2. Nonce has not been used before
+     *
+     * @param timestamp - Webhook timestamp (Unix milliseconds)
+     * @param nonce - Unique webhook identifier
+     * @returns True if valid, false if replay detected
+     */
+    validateReplayProtection(timestamp: number | undefined, nonce: string | undefined): Promise<boolean>;
+    /**
+     * Verify webhook signature
+     *
+     * Uses timing-safe comparison to prevent timing attacks.
+     *
+     * @param payload - Request payload (stringified JSON)
+     * @param signature - Signature to verify (format: "sha256=<hex>")
+     * @param secret - Webhook secret key
+     * @returns True if signature is valid
+     */
+    verifySignature(payload: string, signature: string | undefined, secret: string): boolean;
+    /**
+     * Generate HMAC-SHA256 signature for testing
+     *
+     * @param payload - Payload to sign
+     * @param secret - Secret key for HMAC
+     * @returns Signature in format "sha256=<hex>"
+     */
+    generateSignature(payload: string, secret: string): string;
+    /**
+     * Create a nonce for testing
+     *
+     * @returns Unique nonce string
+     */
+    generateNonce(): string;
+}
+/**
+ * Create a webhook security instance with default configuration
+ */
+export declare function createWebhookSecurity(deduplication: WebhookDeduplication, logger: Logger): WebhookSecurity;
+//# sourceMappingURL=security.d.ts.map

package/dist/webhooks/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/webhooks/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IAEjC;;OAEG;IACH,aAAa,EAAE,oBAAoB,CAAA;IAEnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAQD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,MAAM,EAAE,qBAAqB;IAOzC;;;;;;;;;;OAUG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAAC,OAAO,CAAC;IA4CnB;;;;;;;;;OASG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,GACb,OAAO;IA2BV;;;;;;OAMG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAM1D;;;;OAIG;IACH,aAAa,IAAI,MAAM;CAGxB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,GACb,eAAe,CAKjB"}

package/dist/webhooks/security.js

@@ -0,0 +1,138 @@
+/**
+ * Webhook security layer (P0)
+ *
+ * Provides replay attack protection, signature verification, and
+ * rate limiting coordination for inbound webhooks.
+ *
+ * Security features:
+ * - Replay attack protection using timestamp + nonce validation
+ * - HMAC-SHA256 signature verification with timing-safe comparison
+ * - Rate limiting coordination
+ */
+import * as crypto from "node:crypto";
+/**
+ * Default configuration values
+ */
+const DEFAULT_MAX_TIMESTAMP_AGE = 15 * 60 * 1000; // 15 minutes
+const DEFAULT_FUTURE_TOLERANCE = 5 * 60 * 1000; // 5 minutes
+/**
+ * Webhook security layer
+ *
+ * Provides P0 security features for webhook processing.
+ */
+export class WebhookSecurity {
+    maxTimestampAge;
+    futureTolerance;
+    deduplication;
+    logger;
+    constructor(config) {
+        this.maxTimestampAge = config.maxTimestampAge ?? DEFAULT_MAX_TIMESTAMP_AGE;
+        this.futureTolerance = config.futureTimestampTolerance ?? DEFAULT_FUTURE_TOLERANCE;
+        this.deduplication = config.deduplication;
+        this.logger = config.logger;
+    }
+    /**
+     * Validate replay protection (timestamp + nonce)
+     *
+     * Checks that:
+     * 1. Timestamp is within valid range (not too old, not too far in future)
+     * 2. Nonce has not been used before
+     *
+     * @param timestamp - Webhook timestamp (Unix milliseconds)
+     * @param nonce - Unique webhook identifier
+     * @returns True if valid, false if replay detected
+     */
+    async validateReplayProtection(timestamp, nonce) {
+        const now = Date.now();
+        // Check if timestamp is provided
+        if (timestamp === undefined) {
+            this.logger.debug?.("Webhook missing timestamp");
+            return false;
+        }
+        // Check if nonce is provided
+        if (nonce === undefined) {
+            this.logger.debug?.("Webhook missing nonce");
+            return false;
+        }
+        // Check timestamp is not too old
+        if (now - timestamp > this.maxTimestampAge) {
+            this.logger.warn?.(`Webhook rejected: timestamp too old (${now - timestamp}ms ago)`);
+            return false;
+        }
+        // Check timestamp is not too far in future (allow clock skew)
+        if (timestamp - now > this.futureTolerance) {
+            this.logger.warn?.(`Webhook rejected: timestamp too far in future (${timestamp - now}ms)`);
+            return false;
+        }
+        // Check nonce has not been used before
+        const isProcessed = await this.deduplication.isProcessed(nonce);
+        if (isProcessed) {
+            this.logger.warn?.(`Webhook rejected: nonce already used (${nonce})`);
+            return false;
+        }
+        // Mark nonce as processed
+        await this.deduplication.markProcessed(nonce, 60_000); // 60 second TTL
+        return true;
+    }
+    /**
+     * Verify webhook signature
+     *
+     * Uses timing-safe comparison to prevent timing attacks.
+     *
+     * @param payload - Request payload (stringified JSON)
+     * @param signature - Signature to verify (format: "sha256=<hex>")
+     * @param secret - Webhook secret key
+     * @returns True if signature is valid
+     */
+    verifySignature(payload, signature, secret) {
+        if (!signature) {
+            this.logger.debug?.("Webhook missing signature");
+            return false;
+        }
+        try {
+            // Compute expected signature
+            const expectedSignature = crypto
+                .createHmac("sha256", secret)
+                .update(payload)
+                .digest("hex");
+            // Extract provided signature (remove "sha256=" prefix if present)
+            const providedSignature = signature.replace(/^sha256=/i, "");
+            // Use timing-safe comparison to prevent timing attacks
+            return crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(providedSignature));
+        }
+        catch (error) {
+            this.logger.error?.("Signature verification failed:", error);
+            return false;
+        }
+    }
+    /**
+     * Generate HMAC-SHA256 signature for testing
+     *
+     * @param payload - Payload to sign
+     * @param secret - Secret key for HMAC
+     * @returns Signature in format "sha256=<hex>"
+     */
+    generateSignature(payload, secret) {
+        const hmac = crypto.createHmac("sha256", secret);
+        hmac.update(payload);
+        return `sha256=${hmac.digest("hex")}`;
+    }
+    /**
+     * Create a nonce for testing
+     *
+     * @returns Unique nonce string
+     */
+    generateNonce() {
+        return `nonce_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+    }
+}
+/**
+ * Create a webhook security instance with default configuration
+ */
+export function createWebhookSecurity(deduplication, logger) {
+    return new WebhookSecurity({
+        deduplication,
+        logger,
+    });
+}
+//# sourceMappingURL=security.js.map

package/dist/webhooks/security.js.map

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

package/dist/webhooks/sync-rate-limiter.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Sync rate limiter (P0)
+ *
+ * Prevents Plaid API bans from webhook-triggered sync floods.
+ * Implements separate rate limit buckets for manual vs webhook-triggered syncs.
+ *
+ * Design:
+ * - Separate rate limit buckets: manual vs webhook-triggered
+ * - Circuit breaker to disable webhook syncs when rate limit near
+ * - Sliding window for accurate rate limiting
+ */
+import type { Logger } from "../errors/errors.js";
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /**
+     * Maximum number of requests allowed
+     */
+    requests: number;
+    /**
+     * Time window in milliseconds
+     */
+    window: number;
+}
+/**
+ * Sync rate limiter configuration
+ */
+export interface SyncRateLimiterConfig {
+    /**
+     * Rate limit for manual syncs
+     */
+    manual: RateLimitConfig;
+    /**
+     * Rate limit for webhook-triggered syncs
+     */
+    webhook: RateLimitConfig;
+    /**
+     * Circuit breaker threshold (0-1)
+     * Disable webhook syncs when usage exceeds this ratio
+     */
+    circuitThreshold?: number;
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+}
+/**
+ * Sync rate limiter
+ *
+ * Tracks sync requests and enforces rate limits separately for
+ * manual and webhook-triggered syncs.
+ */
+export declare class SyncRateLimiter {
+    private readonly config;
+    private readonly logger;
+    private readonly requests;
+    private circuitOpen;
+    private circuitOpenUntil;
+    constructor(config: SyncRateLimiterConfig);
+    /**
+     * Record a manual sync request
+     *
+     * @param accountId - Account ID for the sync
+     */
+    recordManualSync(accountId: string): void;
+    /**
+     * Record a webhook-triggered sync request
+     *
+     * @param accountId - Account ID for the sync
+     */
+    recordWebhookSync(accountId: string): void;
+    /**
+     * Check if webhook sync is allowed
+     *
+     * @param accountId - Account ID for the sync
+     * @returns True if sync is allowed
+     */
+    isWebhookSyncAllowed(accountId: string): boolean;
+    /**
+     * Check if manual sync is allowed
+     *
+     * @param accountId - Account ID for the sync
+     * @returns True if sync is allowed
+     */
+    isManualSyncAllowed(accountId: string): boolean;
+    /**
+     * Check if circuit breaker is open
+     */
+    isCircuitOpen(): boolean;
+    /**
+     * Open circuit breaker
+     *
+     * Disables webhook syncs for a cooldown period.
+     */
+    openCircuit(): void;
+    /**
+     * Close circuit breaker
+     */
+    closeCircuit(): void;
+    /**
+     * Get rate limiter statistics
+     */
+    getStats(): {
+        manualCount: number;
+        webhookCount: number;
+        circuitOpen: boolean;
+        usageRatio: number;
+    };
+    /**
+     * Reset rate limiter (for testing)
+     */
+    reset(): void;
+    /**
+     * Clean up old requests
+     */
+    cleanup(): void;
+    /**
+     * Record a request
+     */
+    private recordRequest;
+}
+/**
+ * Create a sync rate limiter with default configuration
+ */
+export declare function createSyncRateLimiter(logger: Logger, config?: Partial<SyncRateLimiterConfig>): SyncRateLimiter;
+/**
+ * In-memory rate limiter for testing
+ */
+export declare class InMemoryRateLimiter {
+    private readonly config;
+    private readonly counters;
+    constructor(config: RateLimitConfig, _logger: Logger);
+    recordRequest(identifier: string): Promise<void>;
+    isRateLimited(identifier: string): Promise<boolean>;
+    reset(): void;
+}
+//# sourceMappingURL=sync-rate-limiter.d.ts.map

package/dist/webhooks/sync-rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/webhooks/sync-rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,eAAe,CAAA;IAEvB;;OAEG;IACH,OAAO,EAAE,eAAe,CAAA;IAExB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAyBD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiD;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,gBAAgB,CAAI;gBAEhB,MAAM,EAAE,qBAAqB;IAKzC;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;OAIG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI1C;;;;;OAKG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAyChD;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAmB/C;;OAEG;IACH,aAAa,IAAI,OAAO;IAcxB;;;;OAIG;IACH,WAAW,IAAI,IAAI;IAKnB;;OAEG;IACH,YAAY,IAAI,IAAI;IAMpB;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,WAAW,EAAE,OAAO,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;KACnB;IAsBD;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,IAAI,IAAI;IAmBf;;OAEG;IACH,OAAO,CAAC,aAAa;CAWtB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,GACtC,eAAe,CAQjB;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;gBAGlC,MAAM,EAAE,eAAe,EACxC,OAAO,EAAE,MAAM;IAGX,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzD,KAAK,IAAI,IAAI;CAGd"}

package/dist/webhooks/sync-rate-limiter.js

@@ -0,0 +1,228 @@
+/**
+ * Sync rate limiter (P0)
+ *
+ * Prevents Plaid API bans from webhook-triggered sync floods.
+ * Implements separate rate limit buckets for manual vs webhook-triggered syncs.
+ *
+ * Design:
+ * - Separate rate limit buckets: manual vs webhook-triggered
+ * - Circuit breaker to disable webhook syncs when rate limit near
+ * - Sliding window for accurate rate limiting
+ */
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    manual: {
+        requests: 10,
+        window: 60_000, // 1 minute
+    },
+    webhook: {
+        requests: 3,
+        window: 60_000, // 1 minute
+    },
+    circuitThreshold: 0.8, // 80%
+};
+/**
+ * Sync rate limiter
+ *
+ * Tracks sync requests and enforces rate limits separately for
+ * manual and webhook-triggered syncs.
+ */
+export class SyncRateLimiter {
+    config;
+    logger;
+    requests = [];
+    circuitOpen = false;
+    circuitOpenUntil = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.logger = config.logger;
+    }
+    /**
+     * Record a manual sync request
+     *
+     * @param accountId - Account ID for the sync
+     */
+    recordManualSync(accountId) {
+        this.recordRequest("manual", accountId);
+    }
+    /**
+     * Record a webhook-triggered sync request
+     *
+     * @param accountId - Account ID for the sync
+     */
+    recordWebhookSync(accountId) {
+        this.recordRequest("webhook", accountId);
+    }
+    /**
+     * Check if webhook sync is allowed
+     *
+     * @param accountId - Account ID for the sync
+     * @returns True if sync is allowed
+     */
+    isWebhookSyncAllowed(accountId) {
+        // Check circuit breaker
+        if (this.isCircuitOpen()) {
+            this.logger.warn?.(`Webhook sync blocked for ${accountId}: circuit breaker open`);
+            return false;
+        }
+        // Check rate limit
+        const now = Date.now();
+        const windowStart = now - this.config.webhook.window;
+        // Count webhook requests in window
+        const webhookCount = this.requests.filter((r) => r.type === "webhook" && r.timestamp >= windowStart).length;
+        if (webhookCount >= this.config.webhook.requests) {
+            this.logger.warn?.(`Webhook sync blocked for ${accountId}: rate limit exceeded (${webhookCount}/${this.config.webhook.requests})`);
+            return false;
+        }
+        // Check if we should open circuit breaker
+        const totalCount = this.requests.filter((r) => r.timestamp >= windowStart).length;
+        const totalLimit = this.config.manual.requests + this.config.webhook.requests;
+        const usageRatio = totalCount / totalLimit;
+        if (usageRatio >= this.config.circuitThreshold) {
+            this.openCircuit();
+            this.logger.warn?.(`Circuit breaker opened: usage at ${Math.round(usageRatio * 100)}%`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Check if manual sync is allowed
+     *
+     * @param accountId - Account ID for the sync
+     * @returns True if sync is allowed
+     */
+    isManualSyncAllowed(accountId) {
+        const now = Date.now();
+        const windowStart = now - this.config.manual.window;
+        // Count manual requests in window
+        const manualCount = this.requests.filter((r) => r.type === "manual" && r.timestamp >= windowStart).length;
+        if (manualCount >= this.config.manual.requests) {
+            this.logger.warn?.(`Manual sync blocked for ${accountId}: rate limit exceeded (${manualCount}/${this.config.manual.requests})`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Check if circuit breaker is open
+     */
+    isCircuitOpen() {
+        if (!this.circuitOpen) {
+            return false;
+        }
+        // Check if circuit should close
+        if (Date.now() > this.circuitOpenUntil) {
+            this.closeCircuit();
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Open circuit breaker
+     *
+     * Disables webhook syncs for a cooldown period.
+     */
+    openCircuit() {
+        this.circuitOpen = true;
+        this.circuitOpenUntil = Date.now() + this.config.manual.window; // Open for 1 window period
+    }
+    /**
+     * Close circuit breaker
+     */
+    closeCircuit() {
+        this.circuitOpen = false;
+        this.circuitOpenUntil = 0;
+        this.logger.info?.("Circuit breaker closed");
+    }
+    /**
+     * Get rate limiter statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const windowStart = now - this.config.manual.window;
+        const manualCount = this.requests.filter((r) => r.type === "manual" && r.timestamp >= windowStart).length;
+        const webhookCount = this.requests.filter((r) => r.type === "webhook" && r.timestamp >= windowStart).length;
+        const totalLimit = this.config.manual.requests + this.config.webhook.requests;
+        const usageRatio = (manualCount + webhookCount) / totalLimit;
+        return {
+            manualCount,
+            webhookCount,
+            circuitOpen: this.isCircuitOpen(),
+            usageRatio,
+        };
+    }
+    /**
+     * Reset rate limiter (for testing)
+     */
+    reset() {
+        this.requests.splice(0, this.requests.length);
+        this.closeCircuit();
+    }
+    /**
+     * Clean up old requests
+     */
+    cleanup() {
+        const now = Date.now();
+        const windowStart = now - this.config.manual.window;
+        const initialLength = this.requests.length;
+        const toKeep = [];
+        for (const req of this.requests) {
+            if (req.timestamp >= windowStart) {
+                toKeep.push(req);
+            }
+        }
+        this.requests.splice(0, this.requests.length, ...toKeep);
+        const removed = initialLength - this.requests.length;
+        if (removed > 0) {
+            this.logger.debug?.(`Cleaned up ${removed} old request entries`);
+        }
+    }
+    /**
+     * Record a request
+     */
+    recordRequest(type, _accountId) {
+        this.requests.push({
+            timestamp: Date.now(),
+            type,
+        });
+        // Cleanup old entries periodically
+        if (this.requests.length > 1000) {
+            this.cleanup();
+        }
+    }
+}
+/**
+ * Create a sync rate limiter with default configuration
+ */
+export function createSyncRateLimiter(logger, config) {
+    return new SyncRateLimiter({
+        manual: { requests: 10, window: 60_000 },
+        webhook: { requests: 3, window: 60_000 },
+        circuitThreshold: 0.8,
+        logger,
+        ...config,
+    });
+}
+/**
+ * In-memory rate limiter for testing
+ */
+export class InMemoryRateLimiter {
+    config;
+    counters = new Map();
+    constructor(config, _logger) {
+        this.config = config;
+    }
+    async recordRequest(identifier) {
+        const count = (this.counters.get(identifier) || 0) + 1;
+        this.counters.set(identifier, count);
+    }
+    async isRateLimited(identifier) {
+        const count = this.counters.get(identifier) || 0;
+        return count >= this.config.requests;
+    }
+    reset() {
+        this.counters.clear();
+    }
+}
+//# sourceMappingURL=sync-rate-limiter.js.map

package/dist/webhooks/sync-rate-limiter.js.map

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