@firela/billclaw-core 0.1.4 → 0.2.0

package/dist/webhooks/router.js

@@ -0,0 +1,107 @@
+/**
+ * Webhook router registry
+ *
+ * Registry pattern for managing webhook handlers.
+ * Provides handler registration and lookup functionality.
+ */
+/**
+ * Webhook router
+ *
+ * Registry for webhook handlers with routing functionality.
+ */
+export class WebhookRouter {
+    handlers = new Map();
+    logger;
+    constructor(options) {
+        this.logger = options.logger;
+    }
+    /**
+     * Register a webhook handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     * @param handler - Handler implementation
+     */
+    register(source, handler) {
+        if (this.handlers.has(source)) {
+            this.logger.warn?.(`Handler already registered for ${source}, replacing`);
+        }
+        this.handlers.set(source, handler);
+        this.logger.info?.(`Registered webhook handler for ${source}`);
+    }
+    /**
+     * Unregister a handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     */
+    unregister(source) {
+        if (this.handlers.delete(source)) {
+            this.logger.info?.(`Unregistered webhook handler for ${source}`);
+        }
+    }
+    /**
+     * Get handler by source
+     *
+     * @param source - Webhook source identifier
+     * @returns Handler or undefined if not found
+     */
+    getHandler(source) {
+        return this.handlers.get(source);
+    }
+    /**
+     * Check if handler is registered for source
+     *
+     * @param source - Webhook source identifier
+     * @returns True if handler exists
+     */
+    hasHandler(source) {
+        return this.handlers.has(source);
+    }
+    /**
+     * Get all registered sources
+     *
+     * @returns Array of registered source identifiers
+     */
+    getSources() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * Route request to appropriate handler
+     *
+     * @param request - Webhook request
+     * @returns Response from handler or error if not found
+     */
+    async route(request) {
+        const handler = this.handlers.get(request.source);
+        if (!handler) {
+            this.logger.warn?.(`No handler registered for source: ${request.source}`);
+            return {
+                status: 400,
+                body: {
+                    received: false,
+                    error: `No handler registered for source: ${request.source}`,
+                },
+            };
+        }
+        return handler.handle(request);
+    }
+    /**
+     * Clear all registered handlers
+     */
+    clear() {
+        this.handlers.clear();
+        this.logger.info?.("Cleared all webhook handlers");
+    }
+    /**
+     * Get number of registered handlers
+     */
+    get size() {
+        return this.handlers.size;
+    }
+}
+/**
+ * Create a webhook router with default configuration
+ */
+export function createWebhookRouter(logger) {
+    return new WebhookRouter({ logger });
+}
+//# sourceMappingURL=router.js.map

package/dist/webhooks/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/webhooks/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACP,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAA;IACnD,MAAM,CAAQ;IAE/B,YAAY,OAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,MAAqB,EAAE,OAAuB;QACrD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,kCAAkC,MAAM,aAAa,CAAC,CAAA;QAC3E,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAClC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAA;IAChE,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,MAAqB;QAC9B,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,oCAAoC,MAAM,EAAE,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,MAAqB;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,MAAqB;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IACzC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,OAAuB;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAEjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,qCAAqC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;YACzE,OAAO;gBACL,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE;oBACJ,QAAQ,EAAE,KAAK;oBACf,KAAK,EAAE,qCAAqC,OAAO,CAAC,MAAM,EAAE;iBAC7D;aACF,CAAA;QACH,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAChC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,8BAA8B,CAAC,CAAA;IACpD,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAA;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,IAAI,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AACtC,CAAC"}

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":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AA+BrC;;GAEG;AACH,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,aAAa;AAC9D,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,YAAY;AAE3D;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACT,eAAe,CAAQ;IACvB,eAAe,CAAQ;IACvB,aAAa,CAAsB;IACnC,MAAM,CAAQ;IAE/B,YAAY,MAA6B;QACvC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,yBAAyB,CAAA;QAC1E,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,wBAAwB,IAAI,wBAAwB,CAAA;QAClF,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAA;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC7B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,wBAAwB,CAC5B,SAA6B,EAC7B,KAAyB;QAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,iCAAiC;QACjC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,2BAA2B,CAAC,CAAA;YAChD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,6BAA6B;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,uBAAuB,CAAC,CAAA;YAC5C,OAAO,KAAK,CAAA;QACd,CAAC;QAED,iCAAiC;QACjC,IAAI,GAAG,GAAG,SAAS,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAChB,wCAAwC,GAAG,GAAG,SAAS,SAAS,CACjE,CAAA;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,8DAA8D;QAC9D,IAAI,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAChB,kDAAkD,SAAS,GAAG,GAAG,KAAK,CACvE,CAAA;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,uCAAuC;QACvC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QAC/D,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,yCAAyC,KAAK,GAAG,CAAC,CAAA;YACrE,OAAO,KAAK,CAAA;QACd,CAAC;QAED,0BAA0B;QAC1B,MAAM,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA,CAAC,gBAAgB;QAEtE,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;;OASG;IACH,eAAe,CACb,OAAe,EACf,SAA6B,EAC7B,MAAc;QAEd,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,2BAA2B,CAAC,CAAA;YAChD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,CAAC;YACH,6BAA6B;YAC7B,MAAM,iBAAiB,GAAG,MAAM;iBAC7B,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;iBAC5B,MAAM,CAAC,OAAO,CAAC;iBACf,MAAM,CAAC,KAAK,CAAC,CAAA;YAEhB,kEAAkE;YAClE,MAAM,iBAAiB,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;YAE5D,uDAAuD;YACvD,OAAO,MAAM,CAAC,eAAe,CAC3B,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAC9B,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAC/B,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,gCAAgC,EAAE,KAAK,CAAC,CAAA;YAC5D,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,OAAe,EAAE,MAAc;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACpB,OAAO,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;IACvC,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,OAAO,SAAS,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;IAC7E,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,aAAmC,EACnC,MAAc;IAEd,OAAO,IAAI,eAAe,CAAC;QACzB,aAAa;QACb,MAAM;KACP,CAAC,CAAA;AACJ,CAAC"}

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"}