@agirails/sdk 2.0.0-beta

package/src/utils/NonceManager.ts

@@ -0,0 +1,293 @@
+/**
+ * Nonce Manager Implementation
+ * Tracks nonces per DID + message type for AIP-4 delivery proofs
+ * Reference: AIP-4 §3.2 (nonce field requirement)
+ */
+
+/**
+ * Nonce Manager Interface (from DeliveryProofBuilder)
+ */
+export interface NonceManager {
+  /**
+   * Get next nonce for message type
+   * @param messageType - Message type identifier (e.g., "agirails.delivery.v1")
+   * @returns Monotonically increasing nonce
+   */
+  getNextNonce(messageType: string): number;
+
+  /**
+   * Record nonce usage
+   * @param messageType - Message type identifier
+   * @param nonce - Nonce used
+   */
+  recordNonce(messageType: string, nonce: number): void;
+
+  /**
+   * Get current nonce (last used)
+   * @param messageType - Message type identifier
+   * @returns Current nonce or 0 if none used
+   */
+  getCurrentNonce(messageType: string): number;
+
+  /**
+   * Reset nonce for message type
+   * @param messageType - Message type identifier
+   */
+  resetNonce(messageType: string): void;
+}
+
+/**
+ * In-Memory Nonce Manager
+ * Simple implementation using Map for per-message-type nonce tracking
+ *
+ * ⚠️ WARNING: Nonces are lost on process restart. For production:
+ * - Use persistent storage (Redis, PostgreSQL, etc.)
+ * - Implement nonce recovery from blockchain events
+ * - Add DID-scoped nonce tracking
+ */
+export class InMemoryNonceManager implements NonceManager {
+  private nonces: Map<string, number> = new Map();
+
+  /**
+   * Create in-memory nonce manager
+   * @param initialNonces - Optional initial nonce values (for recovery)
+   */
+  constructor(initialNonces?: Record<string, number>) {
+    if (initialNonces) {
+      Object.entries(initialNonces).forEach(([messageType, nonce]) => {
+        this.nonces.set(messageType, nonce);
+      });
+    }
+  }
+
+  /**
+   * Get next nonce for message type
+   * @param messageType - Message type identifier
+   * @returns Monotonically increasing nonce
+   */
+  getNextNonce(messageType: string): number {
+    const current = this.nonces.get(messageType) || 0;
+    return current + 1;
+  }
+
+  /**
+   * Record nonce usage
+   * @param messageType - Message type identifier
+   * @param nonce - Nonce used
+   */
+  recordNonce(messageType: string, nonce: number): void {
+    const current = this.nonces.get(messageType) || 0;
+
+    // Ensure monotonic increase
+    if (nonce <= current) {
+      throw new Error(
+        `Nonce must be strictly increasing: attempted ${nonce}, current is ${current}`
+      );
+    }
+
+    this.nonces.set(messageType, nonce);
+  }
+
+  /**
+   * Get current nonce (last used)
+   * @param messageType - Message type identifier
+   * @returns Current nonce or 0 if none used
+   */
+  getCurrentNonce(messageType: string): number {
+    return this.nonces.get(messageType) || 0;
+  }
+
+  /**
+   * Reset nonce for message type
+   * @param messageType - Message type identifier
+   */
+  resetNonce(messageType: string): void {
+    this.nonces.delete(messageType);
+  }
+
+  /**
+   * Get all nonces (for persistence)
+   * @returns Record of all message type nonces
+   */
+  getAllNonces(): Record<string, number> {
+    return Object.fromEntries(this.nonces.entries());
+  }
+
+  /**
+   * Clear all nonces
+   */
+  clearAll(): void {
+    this.nonces.clear();
+  }
+}
+
+/**
+ * DID-Scoped Nonce Manager
+ * Tracks nonces per DID + message type combination
+ * Recommended for multi-agent scenarios
+ */
+export class DIDScopedNonceManager implements NonceManager {
+  private nonces: Map<string, Map<string, number>> = new Map();
+  private currentDID: string;
+
+  /**
+   * Create DID-scoped nonce manager
+   * @param did - DID to track nonces for
+   * @param initialNonces - Optional initial nonce values
+   */
+  constructor(did: string, initialNonces?: Record<string, number>) {
+    this.currentDID = did;
+
+    if (initialNonces) {
+      const didNonces = new Map<string, number>();
+      Object.entries(initialNonces).forEach(([messageType, nonce]) => {
+        didNonces.set(messageType, nonce);
+      });
+      this.nonces.set(did, didNonces);
+    }
+  }
+
+  /**
+   * Get next nonce for message type (current DID)
+   * @param messageType - Message type identifier
+   * @returns Monotonically increasing nonce
+   */
+  getNextNonce(messageType: string): number {
+    return this.getNextNonceForDID(this.currentDID, messageType);
+  }
+
+  /**
+   * Record nonce usage (current DID)
+   * @param messageType - Message type identifier
+   * @param nonce - Nonce used
+   */
+  recordNonce(messageType: string, nonce: number): void {
+    this.recordNonceForDID(this.currentDID, messageType, nonce);
+  }
+
+  /**
+   * Get current nonce (current DID)
+   * @param messageType - Message type identifier
+   * @returns Current nonce or 0 if none used
+   */
+  getCurrentNonce(messageType: string): number {
+    return this.getCurrentNonceForDID(this.currentDID, messageType);
+  }
+
+  /**
+   * Reset nonce for message type (current DID)
+   * @param messageType - Message type identifier
+   */
+  resetNonce(messageType: string): void {
+    this.resetNonceForDID(this.currentDID, messageType);
+  }
+
+  /**
+   * Get next nonce for specific DID + message type
+   * @param did - DID identifier
+   * @param messageType - Message type identifier
+   * @returns Monotonically increasing nonce
+   */
+  getNextNonceForDID(did: string, messageType: string): number {
+    const didNonces = this.nonces.get(did);
+    if (!didNonces) {
+      return 1;
+    }
+    const current = didNonces.get(messageType) || 0;
+    return current + 1;
+  }
+
+  /**
+   * Record nonce usage for specific DID + message type
+   * @param did - DID identifier
+   * @param messageType - Message type identifier
+   * @param nonce - Nonce used
+   */
+  recordNonceForDID(did: string, messageType: string, nonce: number): void {
+    let didNonces = this.nonces.get(did);
+
+    if (!didNonces) {
+      didNonces = new Map<string, number>();
+      this.nonces.set(did, didNonces);
+    }
+
+    const current = didNonces.get(messageType) || 0;
+
+    // Ensure monotonic increase
+    if (nonce <= current) {
+      throw new Error(
+        `Nonce must be strictly increasing for ${did}: attempted ${nonce}, current is ${current}`
+      );
+    }
+
+    didNonces.set(messageType, nonce);
+  }
+
+  /**
+   * Get current nonce for specific DID + message type
+   * @param did - DID identifier
+   * @param messageType - Message type identifier
+   * @returns Current nonce or 0 if none used
+   */
+  getCurrentNonceForDID(did: string, messageType: string): number {
+    const didNonces = this.nonces.get(did);
+    return didNonces?.get(messageType) || 0;
+  }
+
+  /**
+   * Reset nonce for specific DID + message type
+   * @param did - DID identifier
+   * @param messageType - Message type identifier
+   */
+  resetNonceForDID(did: string, messageType: string): void {
+    const didNonces = this.nonces.get(did);
+    if (didNonces) {
+      didNonces.delete(messageType);
+    }
+  }
+
+  /**
+   * Switch current DID context
+   * @param did - New DID to track
+   */
+  switchDID(did: string): void {
+    this.currentDID = did;
+  }
+
+  /**
+   * Get all nonces for all DIDs (for persistence)
+   * @returns Nested record of DID → message type → nonce
+   */
+  getAllNonces(): Record<string, Record<string, number>> {
+    const result: Record<string, Record<string, number>> = {};
+
+    this.nonces.forEach((didNonces, did) => {
+      result[did] = Object.fromEntries(didNonces.entries());
+    });
+
+    return result;
+  }
+
+  /**
+   * Clear all nonces for all DIDs
+   */
+  clearAll(): void {
+    this.nonces.clear();
+  }
+}
+
+/**
+ * Create nonce manager based on environment
+ * @param did - Optional DID for scoped tracking
+ * @param initialNonces - Optional initial nonces
+ * @returns NonceManager instance
+ */
+export function createNonceManager(
+  did?: string,
+  initialNonces?: Record<string, number>
+): NonceManager {
+  if (did) {
+    return new DIDScopedNonceManager(did, initialNonces);
+  }
+  return new InMemoryNonceManager(initialNonces);
+}

package/src/utils/ReceivedNonceTracker.ts

@@ -0,0 +1,397 @@
+/**
+ * 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; // bytes32 format
+  receivedNonce?: string;   // bytes32 format
+}
+
+/**
+ * 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 class InMemoryReceivedNonceTracker implements IReceivedNonceTracker {
+  // Map: sender -> messageType -> highest nonce (as BigInt for comparison)
+  private highestNonces: Map<string, Map<string, bigint>> = new Map();
+
+  /**
+   * Validate and record a received nonce
+   */
+  validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult {
+    // Validate nonce format (must be bytes32: 0x + 64 hex chars)
+    if (!/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
+      return {
+        valid: false,
+        reason: 'Invalid nonce format (must be bytes32)',
+        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<string, bigint>();
+      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 {
+        valid: false,
+        reason: `Nonce replay detected: nonce must be > ${this.bigintToBytes32(highestNonce)}`,
+        expectedMinimum,
+        receivedNonce: nonce
+      };
+    }
+
+    // Valid nonce - record it
+    senderNonces.set(messageType, nonceValue);
+    return { valid: true };
+  }
+
+  /**
+   * Check if a nonce has been used (non-mutating)
+   */
+  hasBeenUsed(sender: string, messageType: string, nonce: string): boolean {
+    const nonceValue = BigInt(nonce);
+    const senderNonces = this.highestNonces.get(sender);
+
+    if (!senderNonces) {
+      return false; // No nonces seen from this sender
+    }
+
+    const highestNonce = senderNonces.get(messageType);
+    if (highestNonce === undefined) {
+      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: string, messageType: string): string | null {
+    const senderNonces = this.highestNonces.get(sender);
+    if (!senderNonces) {
+      return null;
+    }
+
+    const highestNonce = senderNonces.get(messageType);
+    if (highestNonce === undefined) {
+      return null;
+    }
+
+    return this.bigintToBytes32(highestNonce);
+  }
+
+  /**
+   * Reset tracking for sender + message type
+   */
+  reset(sender: string, messageType: string): void {
+    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(): void {
+    this.highestNonces.clear();
+  }
+
+  /**
+   * Convert BigInt to bytes32 hex string
+   */
+  private bigintToBytes32(value: bigint): string {
+    return '0x' + value.toString(16).padStart(64, '0');
+  }
+
+  /**
+   * Get all nonces (for debugging/persistence)
+   */
+  getAllNonces(): Record<string, Record<string, string>> {
+    const result: Record<string, Record<string, string>> = {};
+
+    this.highestNonces.forEach((senderNonces, sender) => {
+      result[sender] = {};
+      senderNonces.forEach((nonce, messageType) => {
+        result[sender][messageType] = this.bigintToBytes32(nonce);
+      });
+    });
+
+    return result;
+  }
+}
+
+/**
+ * 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)
+ *
+ * Trade-off:
+ * - Higher memory usage (stores every nonce)
+ * - More flexible (allows out-of-order delivery)
+ * - Requires periodic cleanup to prevent unbounded growth
+ */
+export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
+  // Map: sender -> messageType -> Set of used nonces
+  private usedNonces: Map<string, Map<string, Set<string>>> = new Map();
+
+  /**
+   * Validate and record a received nonce
+   */
+  validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult {
+    // Validate nonce format
+    if (!/^0x[a-fA-F0-9]{64}$/.test(nonce)) {
+      return {
+        valid: false,
+        reason: 'Invalid nonce format (must be bytes32)',
+        receivedNonce: nonce
+      };
+    }
+
+    // Get sender's nonce map
+    let senderNonces = this.usedNonces.get(sender);
+    if (!senderNonces) {
+      senderNonces = new Map<string, Set<string>>();
+      this.usedNonces.set(sender, senderNonces);
+    }
+
+    // Get set of used nonces for this message type
+    let usedSet = senderNonces.get(messageType);
+    if (!usedSet) {
+      usedSet = new Set<string>();
+      senderNonces.set(messageType, usedSet);
+    }
+
+    // Check if nonce was already used
+    if (usedSet.has(nonce)) {
+      return {
+        valid: false,
+        reason: 'Nonce replay detected: this nonce has already been used',
+        receivedNonce: nonce
+      };
+    }
+
+    // Valid nonce - record it
+    usedSet.add(nonce);
+    return { valid: true };
+  }
+
+  /**
+   * Check if a nonce has been used
+   */
+  hasBeenUsed(sender: string, messageType: string, nonce: string): boolean {
+    const senderNonces = this.usedNonces.get(sender);
+    if (!senderNonces) {
+      return false;
+    }
+
+    const usedSet = senderNonces.get(messageType);
+    if (!usedSet) {
+      return false;
+    }
+
+    return usedSet.has(nonce);
+  }
+
+  /**
+   * Get highest nonce seen (for this strategy, compute from set)
+   */
+  getHighestNonce(sender: string, messageType: string): string | null {
+    const senderNonces = this.usedNonces.get(sender);
+    if (!senderNonces) {
+      return null;
+    }
+
+    const usedSet = senderNonces.get(messageType);
+    if (!usedSet || usedSet.size === 0) {
+      return null;
+    }
+
+    // Find maximum nonce in set
+    let maxNonce = BigInt(0);
+    usedSet.forEach(nonce => {
+      const value = BigInt(nonce);
+      if (value > maxNonce) {
+        maxNonce = value;
+      }
+    });
+
+    return '0x' + maxNonce.toString(16).padStart(64, '0');
+  }
+
+  /**
+   * Reset tracking for sender + message type
+   */
+  reset(sender: string, messageType: string): void {
+    const senderNonces = this.usedNonces.get(sender);
+    if (senderNonces) {
+      senderNonces.delete(messageType);
+      if (senderNonces.size === 0) {
+        this.usedNonces.delete(sender);
+      }
+    }
+  }
+
+  /**
+   * Clear all tracked nonces
+   */
+  clearAll(): void {
+    this.usedNonces.clear();
+  }
+
+  /**
+   * Get nonce count for sender + message type (for monitoring)
+   */
+  getNonceCount(sender: string, messageType: string): number {
+    const senderNonces = this.usedNonces.get(sender);
+    if (!senderNonces) {
+      return 0;
+    }
+
+    const usedSet = senderNonces.get(messageType);
+    return usedSet ? usedSet.size : 0;
+  }
+
+  /**
+   * Cleanup old nonces (keep only last N)
+   * This prevents unbounded memory growth
+   */
+  cleanup(sender: string, messageType: string, keepLast: number = 1000): void {
+    const senderNonces = this.usedNonces.get(sender);
+    if (!senderNonces) {
+      return;
+    }
+
+    const usedSet = senderNonces.get(messageType);
+    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 toKeep = new Set(sortedNonces.slice(-keepLast));
+    senderNonces.set(messageType, toKeep);
+  }
+}
+
+/**
+ * Factory function to create a nonce tracker
+ * @param strategy - 'memory-efficient' (highest nonce) or 'set-based' (all nonces)
+ * @returns IReceivedNonceTracker instance
+ */
+export function createReceivedNonceTracker(
+  strategy: 'memory-efficient' | 'set-based' = 'memory-efficient'
+): IReceivedNonceTracker {
+  if (strategy === 'set-based') {
+    return new SetBasedReceivedNonceTracker();
+  }
+  return new InMemoryReceivedNonceTracker();
+}