@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/utils/ReceivedNonceTracker.d.ts

@@ -1,35 +1,210 @@
+/**
+ * ReceivedNonceTracker - Replay Attack Prevention for Message Receivers
+ *
+ * This utility tracks nonces of received messages to prevent replay attacks.
+ * It works in conjunction with NonceManager (for senders) but serves the receiver side.
+ *
+ * Reference: V4 Security Vulnerability (EIP-712 Replay Attack)
+ *
+ * Usage Pattern:
+ * - Sender: Uses NonceManager to generate monotonically increasing nonces
+ * - Receiver: Uses ReceivedNonceTracker to validate and track received nonces
+ *
+ * Security Properties:
+ * 1. Nonces must be monotonically increasing per sender + message type
+ * 2. Duplicate nonces are rejected (replay attack prevention)
+ * 3. Nonces that are lower than the highest seen are rejected (old replay prevention)
+ *
+ * ⚠️ WARNING: In-memory tracking only. For production:
+ * - Use persistent storage (Redis, PostgreSQL, etc.)
+ * - Implement nonce recovery from transaction history
+ * - Consider nonce expiry for long-running processes
+ */
+/**
+ * Nonce validation result
+ */
 export interface NonceValidationResult {
     valid: boolean;
     reason?: string;
     expectedMinimum?: string;
     receivedNonce?: string;
 }
+/**
+ * Interface for tracking received nonces
+ */
 export interface IReceivedNonceTracker {
+    /**
+     * Validate and record a received nonce
+     * @param sender - Sender DID (e.g., "did:ethr:0x...")
+     * @param messageType - Message type (e.g., "agirails.delivery.v1")
+     * @param nonce - Nonce value (bytes32 format: "0x...")
+     * @returns Validation result
+     */
     validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult;
+    /**
+     * Check if a nonce has been used (without recording)
+     * @param sender - Sender DID
+     * @param messageType - Message type
+     * @param nonce - Nonce value (bytes32 format)
+     * @returns true if nonce was already used
+     */
     hasBeenUsed(sender: string, messageType: string, nonce: string): boolean;
+    /**
+     * Get highest nonce seen for sender + message type
+     * @param sender - Sender DID
+     * @param messageType - Message type
+     * @returns Highest nonce (bytes32 format) or null if none seen
+     */
     getHighestNonce(sender: string, messageType: string): string | null;
+    /**
+     * Reset tracking for a specific sender + message type
+     * @param sender - Sender DID
+     * @param messageType - Message type
+     */
     reset(sender: string, messageType: string): void;
+    /**
+     * Clear all tracked nonces
+     */
     clearAll(): void;
 }
+/**
+ * In-Memory Received Nonce Tracker
+ *
+ * Strategy: Track highest nonce seen per sender + message type
+ * - Accept nonces that are strictly greater than the highest seen
+ * - Reject nonces that are <= highest seen (replay attack)
+ *
+ * Trade-off:
+ * - Memory efficient (one value per sender + type)
+ * - Requires ordered nonce sequences
+ * - Cannot skip nonces (nonce gaps are rejected)
+ */
 export declare class InMemoryReceivedNonceTracker implements IReceivedNonceTracker {
     private highestNonces;
+    /**
+     * Validate and record a received nonce
+     */
     validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult;
+    /**
+     * Check if a nonce has been used (non-mutating)
+     */
     hasBeenUsed(sender: string, messageType: string, nonce: string): boolean;
+    /**
+     * Get highest nonce seen
+     */
     getHighestNonce(sender: string, messageType: string): string | null;
+    /**
+     * Reset tracking for sender + message type
+     */
     reset(sender: string, messageType: string): void;
+    /**
+     * Clear all tracked nonces
+     */
     clearAll(): void;
+    /**
+     * Convert BigInt to bytes32 hex string
+     */
     private bigintToBytes32;
+    /**
+     * Get all nonces (for debugging/persistence)
+     */
     getAllNonces(): Record<string, Record<string, string>>;
 }
+/**
+ * Set-Based Received Nonce Tracker
+ *
+ * Strategy: Track exact set of used nonces per sender + message type
+ * - Accept nonces that haven't been seen before
+ * - Reject duplicate nonces (replay attack)
+ * - Allows non-sequential nonces (nonce gaps are OK)
+ *
+ * SECURITY FIX (NEW-H-2): Max size enforcement to prevent memory exhaustion
+ * SECURITY FIX (HIGH-2): Global total entries limit to prevent DoS via many sender combinations
+ * SECURITY FIX (H-2): Rate limiting per sender to prevent flood attacks
+ *
+ * Trade-off:
+ * - Higher memory usage (stores every nonce)
+ * - More flexible (allows out-of-order delivery)
+ * - Requires periodic cleanup to prevent unbounded growth
+ */
 export declare class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
     private usedNonces;
+    private readonly maxSizePerType;
+    private readonly maxTotalEntries;
+    private totalEntries;
+    private rateLimitState;
+    private readonly maxNoncesPerMinute;
+    private readonly rateLimitWindowMs;
+    /**
+     * Create set-based tracker with optional max size
+     * @param maxSizePerType - Maximum nonces per sender+messageType (default: 10,000)
+     * @param maxTotalEntries - Maximum total nonces across all combinations (default: 100,000)
+     * @param maxNoncesPerMinute - Maximum nonces per sender per minute (default: 100)
+     */
+    constructor(maxSizePerType?: number, maxTotalEntries?: number, maxNoncesPerMinute?: number);
+    /**
+     * SECURITY FIX (H-2): Check rate limit for sender
+     * @param sender - Sender DID
+     * @returns true if rate limit exceeded
+     */
+    private checkRateLimit;
+    /**
+     * SECURITY FIX (H-2): Periodic cleanup of rate limit state
+     * Removes expired rate limit entries (older than 5 minutes)
+     */
+    private cleanupRateLimitState;
+    /**
+     * Validate and record a received nonce
+     *
+     * SECURITY FIX (NEW-H-2): Automatic cleanup when max size reached
+     * SECURITY FIX (HIGH-2): Global limit check to prevent DoS
+     * SECURITY FIX (H-2): Rate limiting per sender (max 100 nonces/minute)
+     */
     validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult;
+    /**
+     * Get number of sender+messageType combinations (for monitoring)
+     * SECURITY FIX (HIGH-2): Monitoring method
+     */
+    private getCombinationCount;
+    /**
+     * Get memory usage statistics
+     * SECURITY FIX (HIGH-2): Monitoring method for DoS detection
+     */
+    getMemoryUsage(): {
+        totalEntries: number;
+        combinations: number;
+        maxTotalEntries: number;
+    };
+    /**
+     * Check if a nonce has been used
+     */
     hasBeenUsed(sender: string, messageType: string, nonce: string): boolean;
+    /**
+     * Get highest nonce seen (for this strategy, compute from set)
+     */
     getHighestNonce(sender: string, messageType: string): string | null;
+    /**
+     * Reset tracking for sender + message type
+     */
     reset(sender: string, messageType: string): void;
+    /**
+     * Clear all tracked nonces
+     */
     clearAll(): void;
+    /**
+     * Get nonce count for sender + message type (for monitoring)
+     */
     getNonceCount(sender: string, messageType: string): number;
+    /**
+     * Cleanup old nonces (keep only last N)
+     * This prevents unbounded memory growth
+     */
     cleanup(sender: string, messageType: string, keepLast?: number): void;
 }
+/**
+ * Factory function to create a nonce tracker
+ * @param strategy - 'memory-efficient' (highest nonce) or 'set-based' (all nonces)
+ * @returns IReceivedNonceTracker instance
+ */
 export declare function createReceivedNonceTracker(strategy?: 'memory-efficient' | 'set-based'): IReceivedNonceTracker;
 //# sourceMappingURL=ReceivedNonceTracker.d.ts.map

package/dist/utils/ReceivedNonceTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReceivedNonceTracker.d.ts","sourceRoot":"","sources":["../../src/utils/ReceivedNonceTracker.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAKD,MAAM,WAAW,qBAAqB;IAQpC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAS7F,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAQzE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAOpE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAKjD,QAAQ,IAAI,IAAI,CAAC;CAClB;AAcD,qBAAa,4BAA6B,YAAW,qBAAqB;IAExE,OAAO,CAAC,aAAa,CAA+C;IAKpE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB;IAgD5F,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAoBxE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiBnE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAchD,QAAQ,IAAI,IAAI;IAOhB,OAAO,CAAC,eAAe;IAOvB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAYvD;AAeD,qBAAa,4BAA6B,YAAW,qBAAqB;IAExE,OAAO,CAAC,UAAU,CAAoD;IAKtE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB;IAyC5F,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAiBxE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0BnE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAahD,QAAQ,IAAI,IAAI;IAOhB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAc1D,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAa,GAAG,IAAI;CAsB5E;AAOD,wBAAgB,0BAA0B,CACxC,QAAQ,GAAE,kBAAkB,GAAG,WAAgC,GAC9D,qBAAqB,CAKvB"}
+{"version":3,"file":"ReceivedNonceTracker.d.ts","sourceRoot":"","sources":["../../src/utils/ReceivedNonceTracker.ts"],"names":[],"mappings":"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"}

package/dist/utils/ReceivedNonceTracker.js

@@ -1,12 +1,50 @@
 "use strict";
+/**
+ * ReceivedNonceTracker - Replay Attack Prevention for Message Receivers
+ *
+ * This utility tracks nonces of received messages to prevent replay attacks.
+ * It works in conjunction with NonceManager (for senders) but serves the receiver side.
+ *
+ * Reference: V4 Security Vulnerability (EIP-712 Replay Attack)
+ *
+ * Usage Pattern:
+ * - Sender: Uses NonceManager to generate monotonically increasing nonces
+ * - Receiver: Uses ReceivedNonceTracker to validate and track received nonces
+ *
+ * Security Properties:
+ * 1. Nonces must be monotonically increasing per sender + message type
+ * 2. Duplicate nonces are rejected (replay attack prevention)
+ * 3. Nonces that are lower than the highest seen are rejected (old replay prevention)
+ *
+ * ⚠️ WARNING: In-memory tracking only. For production:
+ * - Use persistent storage (Redis, PostgreSQL, etc.)
+ * - Implement nonce recovery from transaction history
+ * - Consider nonce expiry for long-running processes
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SetBasedReceivedNonceTracker = exports.InMemoryReceivedNonceTracker = void 0;
-exports.createReceivedNonceTracker = createReceivedNonceTracker;
+exports.createReceivedNonceTracker = exports.SetBasedReceivedNonceTracker = exports.InMemoryReceivedNonceTracker = void 0;
+/**
+ * In-Memory Received Nonce Tracker
+ *
+ * Strategy: Track highest nonce seen per sender + message type
+ * - Accept nonces that are strictly greater than the highest seen
+ * - Reject nonces that are <= highest seen (replay attack)
+ *
+ * Trade-off:
+ * - Memory efficient (one value per sender + type)
+ * - Requires ordered nonce sequences
+ * - Cannot skip nonces (nonce gaps are rejected)
+ */
 class InMemoryReceivedNonceTracker {
     constructor() {
+        // Map: sender -> messageType -> highest nonce (as BigInt for comparison)
         this.highestNonces = new Map();
     }
+    /**
+     * Validate and record a received nonce
+     */
     validateAndRecord(sender, messageType, nonce) {
+        // Validate nonce format (must be bytes32: 0x + 64 hex chars)
         if (!/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
             return {
                 valid: false,
@@ -14,17 +52,22 @@ class InMemoryReceivedNonceTracker {
                 receivedNonce: nonce
             };
         }
+        // Convert nonce to BigInt for comparison
         const nonceValue = BigInt(nonce);
+        // Get sender's nonce map
         let senderNonces = this.highestNonces.get(sender);
         if (!senderNonces) {
             senderNonces = new Map();
             this.highestNonces.set(sender, senderNonces);
         }
+        // Get highest nonce for this message type
         const highestNonce = senderNonces.get(messageType);
         if (highestNonce === undefined) {
+            // First message from this sender for this type
             senderNonces.set(messageType, nonceValue);
             return { valid: true };
         }
+        // Nonce must be strictly greater than highest seen
         if (nonceValue <= highestNonce) {
             const expectedMinimum = '0x' + (highestNonce + BigInt(1)).toString(16).padStart(64, '0');
             return {
@@ -34,21 +77,29 @@ class InMemoryReceivedNonceTracker {
                 receivedNonce: nonce
             };
         }
+        // Valid nonce - record it
         senderNonces.set(messageType, nonceValue);
         return { valid: true };
     }
+    /**
+     * Check if a nonce has been used (non-mutating)
+     */
     hasBeenUsed(sender, messageType, nonce) {
         const nonceValue = BigInt(nonce);
         const senderNonces = this.highestNonces.get(sender);
         if (!senderNonces) {
-            return false;
+            return false; // No nonces seen from this sender
         }
         const highestNonce = senderNonces.get(messageType);
         if (highestNonce === undefined) {
-            return false;
+            return false; // No nonces seen for this message type
         }
+        // If the provided nonce is <= highest seen, it's been "used"
         return nonceValue <= highestNonce;
     }
+    /**
+     * Get highest nonce seen
+     */
     getHighestNonce(sender, messageType) {
         const senderNonces = this.highestNonces.get(sender);
         if (!senderNonces) {
@@ -60,21 +111,34 @@ class InMemoryReceivedNonceTracker {
         }
         return this.bigintToBytes32(highestNonce);
     }
+    /**
+     * Reset tracking for sender + message type
+     */
     reset(sender, messageType) {
         const senderNonces = this.highestNonces.get(sender);
         if (senderNonces) {
             senderNonces.delete(messageType);
+            // Clean up sender map if empty
             if (senderNonces.size === 0) {
                 this.highestNonces.delete(sender);
             }
         }
     }
+    /**
+     * Clear all tracked nonces
+     */
     clearAll() {
         this.highestNonces.clear();
     }
+    /**
+     * Convert BigInt to bytes32 hex string
+     */
     bigintToBytes32(value) {
         return '0x' + value.toString(16).padStart(64, '0');
     }
+    /**
+     * Get all nonces (for debugging/persistence)
+     */
     getAllNonces() {
         const result = {};
         this.highestNonces.forEach((senderNonces, sender) => {
@@ -87,11 +151,97 @@ class InMemoryReceivedNonceTracker {
     }
 }
 exports.InMemoryReceivedNonceTracker = InMemoryReceivedNonceTracker;
+/**
+ * Set-Based Received Nonce Tracker
+ *
+ * Strategy: Track exact set of used nonces per sender + message type
+ * - Accept nonces that haven't been seen before
+ * - Reject duplicate nonces (replay attack)
+ * - Allows non-sequential nonces (nonce gaps are OK)
+ *
+ * SECURITY FIX (NEW-H-2): Max size enforcement to prevent memory exhaustion
+ * SECURITY FIX (HIGH-2): Global total entries limit to prevent DoS via many sender combinations
+ * SECURITY FIX (H-2): Rate limiting per sender to prevent flood attacks
+ *
+ * Trade-off:
+ * - Higher memory usage (stores every nonce)
+ * - More flexible (allows out-of-order delivery)
+ * - Requires periodic cleanup to prevent unbounded growth
+ */
 class SetBasedReceivedNonceTracker {
-    constructor() {
+    /**
+     * Create set-based tracker with optional max size
+     * @param maxSizePerType - Maximum nonces per sender+messageType (default: 10,000)
+     * @param maxTotalEntries - Maximum total nonces across all combinations (default: 100,000)
+     * @param maxNoncesPerMinute - Maximum nonces per sender per minute (default: 100)
+     */
+    constructor(maxSizePerType = 10000, maxTotalEntries = 100000, maxNoncesPerMinute = 100) {
+        // Map: sender -> messageType -> Set of used nonces
         this.usedNonces = new Map();
+        this.totalEntries = 0;
+        // SECURITY FIX (H-2): Rate limiting per sender
+        // Map: sender -> { count: number, windowStart: number }
+        this.rateLimitState = new Map();
+        this.rateLimitWindowMs = 60000; // 1 minute window
+        if (maxSizePerType <= 0) {
+            throw new Error('maxSizePerType must be positive');
+        }
+        if (maxTotalEntries <= 0) {
+            throw new Error('maxTotalEntries must be positive');
+        }
+        if (maxNoncesPerMinute <= 0) {
+            throw new Error('maxNoncesPerMinute must be positive');
+        }
+        this.maxSizePerType = maxSizePerType;
+        this.maxTotalEntries = maxTotalEntries;
+        this.maxNoncesPerMinute = maxNoncesPerMinute;
+    }
+    /**
+     * SECURITY FIX (H-2): Check rate limit for sender
+     * @param sender - Sender DID
+     * @returns true if rate limit exceeded
+     */
+    checkRateLimit(sender) {
+        const now = Date.now();
+        const state = this.rateLimitState.get(sender);
+        if (!state) {
+            // First nonce from this sender
+            this.rateLimitState.set(sender, { count: 1, windowStart: now });
+            return false; // Not rate limited
+        }
+        // Check if window expired (reset counter)
+        if (now - state.windowStart >= this.rateLimitWindowMs) {
+            state.count = 1;
+            state.windowStart = now;
+            return false; // Not rate limited
+        }
+        // Increment counter
+        state.count++;
+        // Check if rate limit exceeded
+        return state.count > this.maxNoncesPerMinute;
+    }
+    /**
+     * SECURITY FIX (H-2): Periodic cleanup of rate limit state
+     * Removes expired rate limit entries (older than 5 minutes)
+     */
+    cleanupRateLimitState() {
+        const now = Date.now();
+        const expiryThreshold = 5 * 60 * 1000; // 5 minutes
+        for (const [sender, state] of this.rateLimitState.entries()) {
+            if (now - state.windowStart > expiryThreshold) {
+                this.rateLimitState.delete(sender);
+            }
+        }
     }
+    /**
+     * Validate and record a received nonce
+     *
+     * SECURITY FIX (NEW-H-2): Automatic cleanup when max size reached
+     * SECURITY FIX (HIGH-2): Global limit check to prevent DoS
+     * SECURITY FIX (H-2): Rate limiting per sender (max 100 nonces/minute)
+     */
     validateAndRecord(sender, messageType, nonce) {
+        // Validate nonce format
         if (!/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
             return {
                 valid: false,
@@ -99,16 +249,44 @@ class SetBasedReceivedNonceTracker {
                 receivedNonce: nonce
             };
         }
+        // SECURITY FIX (H-2): Rate limit check (BEFORE global limit to avoid unnecessary work)
+        if (this.checkRateLimit(sender)) {
+            return {
+                valid: false,
+                reason: `Rate limit exceeded for sender ${sender}: ` +
+                    `Maximum ${this.maxNoncesPerMinute} nonces per minute allowed. ` +
+                    `This may indicate a flood attack or misconfigured client. ` +
+                    `Wait 1 minute before retrying.`,
+                receivedNonce: nonce
+            };
+        }
+        // SECURITY FIX (H-2): Periodic cleanup every 100 validations (amortized cost)
+        if (this.totalEntries % 100 === 0) {
+            this.cleanupRateLimitState();
+        }
+        // SECURITY FIX (HIGH-2): Check global limit BEFORE adding
+        if (this.totalEntries >= this.maxTotalEntries) {
+            return {
+                valid: false,
+                reason: `Global nonce tracker limit reached (${this.maxTotalEntries} entries). ` +
+                    `This may indicate a DoS attack or need for cleanup. ` +
+                    `Current usage: ${this.totalEntries} entries across ${this.getCombinationCount()} sender+type combinations.`,
+                receivedNonce: nonce
+            };
+        }
+        // Get sender's nonce map
         let senderNonces = this.usedNonces.get(sender);
         if (!senderNonces) {
             senderNonces = new Map();
             this.usedNonces.set(sender, senderNonces);
         }
+        // Get set of used nonces for this message type
         let usedSet = senderNonces.get(messageType);
         if (!usedSet) {
             usedSet = new Set();
             senderNonces.set(messageType, usedSet);
         }
+        // Check if nonce was already used
         if (usedSet.has(nonce)) {
             return {
                 valid: false,
@@ -116,9 +294,52 @@ class SetBasedReceivedNonceTracker {
                 receivedNonce: nonce
             };
         }
+        // SECURITY FIX (NEW-H-2): Auto-cleanup if max size per type reached
+        if (usedSet.size >= this.maxSizePerType) {
+            // Keep only last 80% of entries (sorted by nonce value)
+            const keepCount = Math.floor(this.maxSizePerType * 0.8);
+            const sortedNonces = Array.from(usedSet).sort((a, b) => {
+                const aVal = BigInt(a);
+                const bVal = BigInt(b);
+                return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+            });
+            const removedCount = usedSet.size - keepCount;
+            usedSet = new Set(sortedNonces.slice(-keepCount));
+            senderNonces.set(messageType, usedSet);
+            // SECURITY FIX (HIGH-2): Update global counter
+            this.totalEntries -= removedCount;
+        }
+        // Valid nonce - record it
         usedSet.add(nonce);
+        // SECURITY FIX (HIGH-2): Update global counter
+        this.totalEntries++;
         return { valid: true };
     }
+    /**
+     * Get number of sender+messageType combinations (for monitoring)
+     * SECURITY FIX (HIGH-2): Monitoring method
+     */
+    getCombinationCount() {
+        let count = 0;
+        this.usedNonces.forEach(senderMap => {
+            count += senderMap.size;
+        });
+        return count;
+    }
+    /**
+     * Get memory usage statistics
+     * SECURITY FIX (HIGH-2): Monitoring method for DoS detection
+     */
+    getMemoryUsage() {
+        return {
+            totalEntries: this.totalEntries,
+            combinations: this.getCombinationCount(),
+            maxTotalEntries: this.maxTotalEntries
+        };
+    }
+    /**
+     * Check if a nonce has been used
+     */
     hasBeenUsed(sender, messageType, nonce) {
         const senderNonces = this.usedNonces.get(sender);
         if (!senderNonces) {
@@ -130,6 +351,9 @@ class SetBasedReceivedNonceTracker {
         }
         return usedSet.has(nonce);
     }
+    /**
+     * Get highest nonce seen (for this strategy, compute from set)
+     */
     getHighestNonce(sender, messageType) {
         const senderNonces = this.usedNonces.get(sender);
         if (!senderNonces) {
@@ -139,6 +363,7 @@ class SetBasedReceivedNonceTracker {
         if (!usedSet || usedSet.size === 0) {
             return null;
         }
+        // Find maximum nonce in set
         let maxNonce = BigInt(0);
         usedSet.forEach(nonce => {
             const value = BigInt(nonce);
@@ -148,18 +373,34 @@ class SetBasedReceivedNonceTracker {
         });
         return '0x' + maxNonce.toString(16).padStart(64, '0');
     }
+    /**
+     * Reset tracking for sender + message type
+     */
     reset(sender, messageType) {
         const senderNonces = this.usedNonces.get(sender);
         if (senderNonces) {
+            const usedSet = senderNonces.get(messageType);
+            if (usedSet) {
+                // SECURITY FIX (HIGH-2): Update global counter
+                this.totalEntries -= usedSet.size;
+            }
             senderNonces.delete(messageType);
             if (senderNonces.size === 0) {
                 this.usedNonces.delete(sender);
             }
         }
     }
+    /**
+     * Clear all tracked nonces
+     */
     clearAll() {
         this.usedNonces.clear();
+        // SECURITY FIX (HIGH-2): Reset global counter
+        this.totalEntries = 0;
     }
+    /**
+     * Get nonce count for sender + message type (for monitoring)
+     */
     getNonceCount(sender, messageType) {
         const senderNonces = this.usedNonces.get(sender);
         if (!senderNonces) {
@@ -168,6 +409,10 @@ class SetBasedReceivedNonceTracker {
         const usedSet = senderNonces.get(messageType);
         return usedSet ? usedSet.size : 0;
     }
+    /**
+     * Cleanup old nonces (keep only last N)
+     * This prevents unbounded memory growth
+     */
     cleanup(sender, messageType, keepLast = 1000) {
         const senderNonces = this.usedNonces.get(sender);
         if (!senderNonces) {
@@ -177,20 +422,31 @@ class SetBasedReceivedNonceTracker {
         if (!usedSet || usedSet.size <= keepLast) {
             return;
         }
+        // Convert to array and sort by nonce value
         const sortedNonces = Array.from(usedSet).sort((a, b) => {
             const aVal = BigInt(a);
             const bVal = BigInt(b);
             return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
         });
+        // Keep only the last N nonces
+        const removedCount = usedSet.size - keepLast;
         const toKeep = new Set(sortedNonces.slice(-keepLast));
         senderNonces.set(messageType, toKeep);
+        // SECURITY FIX (HIGH-2): Update global counter
+        this.totalEntries -= removedCount;
     }
 }
 exports.SetBasedReceivedNonceTracker = SetBasedReceivedNonceTracker;
+/**
+ * Factory function to create a nonce tracker
+ * @param strategy - 'memory-efficient' (highest nonce) or 'set-based' (all nonces)
+ * @returns IReceivedNonceTracker instance
+ */
 function createReceivedNonceTracker(strategy = 'memory-efficient') {
     if (strategy === 'set-based') {
         return new SetBasedReceivedNonceTracker();
     }
     return new InMemoryReceivedNonceTracker();
 }
+exports.createReceivedNonceTracker = createReceivedNonceTracker;
 //# sourceMappingURL=ReceivedNonceTracker.js.map