@agirails/sdk 2.0.1-beta → 2.0.2

package/src/utils/Semaphore.ts

@@ -0,0 +1,276 @@
+/**
+ * Semaphore - Concurrency limiter for ACTP SDK
+ *
+ * SECURITY FIX (MEDIUM-4): Prevents unbounded concurrent execution
+ * which could lead to resource exhaustion (memory/CPU DoS).
+ *
+ * @module utils/Semaphore
+ */
+
+/**
+ * Simple semaphore for limiting concurrent operations
+ *
+ * Uses a FIFO queue to ensure fair scheduling of waiting tasks.
+ */
+export class Semaphore {
+  private permits: number;
+  private readonly maxPermits: number;
+  private readonly waitQueue: Array<{
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }> = [];
+
+  /**
+   * Create a semaphore with specified concurrency limit
+   *
+   * @param maxPermits - Maximum concurrent permits (default: 10)
+   * @throws Error if maxPermits is not positive
+   */
+  constructor(maxPermits: number = 10) {
+    if (maxPermits <= 0 || !Number.isInteger(maxPermits)) {
+      throw new Error(`maxPermits must be a positive integer, got: ${maxPermits}`);
+    }
+    this.maxPermits = maxPermits;
+    this.permits = maxPermits;
+  }
+
+  /**
+   * Acquire a permit, waiting if necessary
+   *
+   * @param timeoutMs - Optional timeout in milliseconds (0 = no timeout)
+   * @returns Promise that resolves when permit is acquired
+   * @throws Error if timeout is exceeded
+   */
+  async acquire(timeoutMs: number = 0): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return;
+    }
+
+    // No permits available, queue the request
+    return new Promise<void>((resolve, reject) => {
+      const waiter = { resolve, reject };
+      this.waitQueue.push(waiter);
+
+      // Set up timeout if specified
+      if (timeoutMs > 0) {
+        const timeoutId = setTimeout(() => {
+          const index = this.waitQueue.indexOf(waiter);
+          if (index >= 0) {
+            this.waitQueue.splice(index, 1);
+            reject(new Error(`Semaphore acquire timeout after ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+
+        // Clear timeout when resolved
+        const originalResolve = waiter.resolve;
+        waiter.resolve = () => {
+          clearTimeout(timeoutId);
+          originalResolve();
+        };
+      }
+    });
+  }
+
+  /**
+   * Try to acquire a permit without waiting
+   *
+   * @returns true if permit was acquired, false if none available
+   */
+  tryAcquire(): boolean {
+    if (this.permits > 0) {
+      this.permits--;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Release a permit
+   *
+   * @throws Error if releasing more permits than acquired
+   */
+  release(): void {
+    if (this.permits >= this.maxPermits) {
+      throw new Error('Cannot release: no permits held');
+    }
+
+    // If there are waiters, give permit to first in queue (FIFO)
+    if (this.waitQueue.length > 0) {
+      const waiter = this.waitQueue.shift()!;
+      waiter.resolve();
+    } else {
+      this.permits++;
+    }
+  }
+
+  /**
+   * Execute a function with semaphore protection
+   *
+   * Automatically acquires before execution and releases after,
+   * even if the function throws.
+   *
+   * @param fn - Function to execute
+   * @param timeoutMs - Optional timeout for acquiring permit
+   * @returns Result of the function
+   */
+  async run<T>(fn: () => Promise<T> | T, timeoutMs: number = 0): Promise<T> {
+    await this.acquire(timeoutMs);
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+
+  /**
+   * Get current available permits
+   */
+  get availablePermits(): number {
+    return this.permits;
+  }
+
+  /**
+   * Get number of waiters in queue
+   */
+  get queueLength(): number {
+    return this.waitQueue.length;
+  }
+
+  /**
+   * Get maximum permits
+   */
+  get limit(): number {
+    return this.maxPermits;
+  }
+
+  /**
+   * Check if semaphore is fully utilized
+   */
+  get isFull(): boolean {
+    return this.permits === 0;
+  }
+
+  /**
+   * Cancel all waiting tasks
+   *
+   * @param reason - Error message for rejected promises
+   */
+  cancelAll(reason: string = 'Semaphore cancelled'): void {
+    while (this.waitQueue.length > 0) {
+      const waiter = this.waitQueue.shift()!;
+      waiter.reject(new Error(reason));
+    }
+  }
+}
+
+/**
+ * Rate limiter using sliding window algorithm
+ *
+ * SECURITY FIX (MEDIUM-4): Complements semaphore for rate-based limiting
+ */
+export class RateLimiter {
+  private readonly timestamps: number[] = [];
+  private readonly windowMs: number;
+  private readonly maxRequests: number;
+
+  /**
+   * Create a rate limiter
+   *
+   * @param maxRequests - Maximum requests per window
+   * @param windowMs - Time window in milliseconds
+   */
+  constructor(maxRequests: number, windowMs: number) {
+    if (maxRequests <= 0) {
+      throw new Error('maxRequests must be positive');
+    }
+    if (windowMs <= 0) {
+      throw new Error('windowMs must be positive');
+    }
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+  }
+
+  /**
+   * Check if a request is allowed and record it
+   *
+   * @returns true if request is allowed, false if rate limited
+   */
+  tryAcquire(): boolean {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    // Remove timestamps outside the window
+    while (this.timestamps.length > 0 && this.timestamps[0] < windowStart) {
+      this.timestamps.shift();
+    }
+
+    // Check if we're at the limit
+    if (this.timestamps.length >= this.maxRequests) {
+      return false;
+    }
+
+    // Record this request
+    this.timestamps.push(now);
+    return true;
+  }
+
+  /**
+   * Wait until a request is allowed
+   *
+   * @param timeoutMs - Optional timeout
+   * @returns Promise that resolves when request is allowed
+   */
+  async acquire(timeoutMs: number = 0): Promise<void> {
+    const startTime = Date.now();
+
+    while (!this.tryAcquire()) {
+      if (timeoutMs > 0 && Date.now() - startTime >= timeoutMs) {
+        throw new Error(`Rate limiter timeout after ${timeoutMs}ms`);
+      }
+
+      // Wait a short time before retrying
+      const waitTime = Math.min(100, this.timeUntilNextSlot());
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+    }
+  }
+
+  /**
+   * Get time until next slot is available
+   *
+   * @returns Milliseconds until next slot, or 0 if slot available
+   */
+  timeUntilNextSlot(): number {
+    if (this.timestamps.length < this.maxRequests) {
+      return 0;
+    }
+
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    const oldestTimestamp = this.timestamps[0];
+
+    if (oldestTimestamp <= windowStart) {
+      return 0;
+    }
+
+    return oldestTimestamp - windowStart;
+  }
+
+  /**
+   * Get current usage stats
+   */
+  get stats(): { current: number; max: number; windowMs: number } {
+    // Clean up old timestamps
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    while (this.timestamps.length > 0 && this.timestamps[0] < windowStart) {
+      this.timestamps.shift();
+    }
+
+    return {
+      current: this.timestamps.length,
+      max: this.maxRequests,
+      windowMs: this.windowMs,
+    };
+  }
+}

package/src/utils/UsedAttestationTracker.ts

@@ -0,0 +1,387 @@
+/**
+ * UsedAttestationTracker - Prevents EAS Attestation Replay Attacks (C-1)
+ *
+ * Tracks which attestation UIDs have been used for which transaction IDs.
+ * This prevents a malicious provider from reusing an attestation from
+ * Transaction A to settle Transaction B.
+ *
+ * SECURITY: ACTPKernel V1 contract accepts any attestationUID without validation.
+ * This tracker provides SDK-side protection until contract is upgraded.
+ *
+ * @module utils/UsedAttestationTracker
+ */
+
+import { assertSafeFileForRead, ensureSafeDir, ensureSafeFile } from './fsSafe';
+
+/**
+ * Interface for tracking used attestations
+ */
+export interface IUsedAttestationTracker {
+  /**
+   * Record that an attestation was used for a transaction
+   * @param attestationUID - EAS attestation UID (bytes32)
+   * @param txId - Transaction ID (bytes32)
+   * @returns true if recorded, false if already used for different transaction
+   *
+   * SECURITY FIX (HIGH-1): This method is now async to ensure persistence completes
+   * before returning. Use recordUsageSync() for fire-and-forget behavior.
+   */
+  recordUsage(attestationUID: string, txId: string): Promise<boolean>;
+
+  /**
+   * Check if attestation has been used
+   * @param attestationUID - EAS attestation UID (bytes32)
+   * @returns Transaction ID if used, null if not used
+   */
+  getUsageForAttestation(attestationUID: string): string | null;
+
+  /**
+   * Check if attestation is valid for transaction
+   * @param attestationUID - EAS attestation UID
+   * @param txId - Transaction ID
+   * @returns true if attestation is unused or already used for this txId
+   */
+  isValidForTransaction(attestationUID: string, txId: string): boolean;
+
+  /**
+   * Clear all tracked attestations
+   */
+  clear(): void;
+}
+
+/**
+ * In-Memory Used Attestation Tracker
+ *
+ * SECURITY FIX (C-1): Prevents attestation replay attacks by tracking
+ * which attestation UIDs have been used for which transactions.
+ *
+ * SECURITY FIX (NEW-H-2): LRU-style cache with max size to prevent DoS
+ *
+ * WARNING: In-memory only. For production:
+ * - Use persistent storage (Redis, PostgreSQL, etc.)
+ * - Implement recovery from blockchain events
+ */
+export class InMemoryUsedAttestationTracker implements IUsedAttestationTracker {
+  // Map: attestationUID -> txId
+  private usedAttestations: Map<string, string> = new Map();
+
+  // SECURITY FIX (NEW-H-2): Maximum size to prevent memory exhaustion DoS
+  private readonly maxSize: number;
+
+  /**
+   * Create in-memory tracker with optional max size
+   * @param maxSize - Maximum entries to store (default: 100,000)
+   */
+  constructor(maxSize: number = 100000) {
+    if (maxSize <= 0) {
+      throw new Error('maxSize must be positive');
+    }
+    this.maxSize = maxSize;
+  }
+
+  /**
+   * Record that an attestation was used for a transaction
+   * @param attestationUID - EAS attestation UID (bytes32)
+   * @param txId - Transaction ID (bytes32)
+   * @returns true if recorded, false if already used for different transaction
+   *
+   * SECURITY FIX (NEW-H-2): LRU eviction when max size reached
+   * SECURITY FIX (HIGH-1): Now async for interface consistency
+   */
+  async recordUsage(attestationUID: string, txId: string): Promise<boolean> {
+    return this.recordUsageSync(attestationUID, txId);
+  }
+
+  /**
+   * Synchronous version of recordUsage (for backward compatibility)
+   * @param attestationUID - EAS attestation UID (bytes32)
+   * @param txId - Transaction ID (bytes32)
+   * @returns true if recorded, false if already used for different transaction
+   */
+  recordUsageSync(attestationUID: string, txId: string): boolean {
+    const normalizedUID = attestationUID.toLowerCase();
+    const normalizedTxId = txId.toLowerCase();
+
+    const existingTxId = this.usedAttestations.get(normalizedUID);
+
+    // If attestation was already used for a different transaction, reject
+    if (existingTxId && existingTxId !== normalizedTxId) {
+      return false;
+    }
+
+    // SECURITY FIX (NEW-H-2): Enforce max size limit with true LRU behavior
+    if (this.usedAttestations.size >= this.maxSize && !existingTxId) {
+      // Remove oldest entry (first entry in Map)
+      const firstKey = this.usedAttestations.keys().next().value;
+      if (firstKey) {
+        this.usedAttestations.delete(firstKey);
+      }
+    } else if (existingTxId) {
+      // SECURITY FIX (M-3): True LRU - delete and re-add to move to end
+      this.usedAttestations.delete(normalizedUID);
+    }
+
+    // Record the usage (at end for LRU)
+    this.usedAttestations.set(normalizedUID, normalizedTxId);
+    return true;
+  }
+
+  /**
+   * Check if attestation has been used
+   * @param attestationUID - EAS attestation UID (bytes32)
+   * @returns Transaction ID if used, null if not used
+   *
+   * SECURITY FIX (MEDIUM-4): Updates access order for true LRU behavior
+   * Accessed items are moved to end of Map (most recently used)
+   */
+  getUsageForAttestation(attestationUID: string): string | null {
+    const normalizedUID = attestationUID.toLowerCase();
+    const txId = this.usedAttestations.get(normalizedUID);
+
+    // SECURITY FIX (MEDIUM-4): True LRU - move accessed item to end
+    // Without this, eviction uses insertion order, not access order
+    if (txId !== undefined) {
+      this.usedAttestations.delete(normalizedUID);
+      this.usedAttestations.set(normalizedUID, txId);
+    }
+
+    return txId || null;
+  }
+
+  /**
+   * Check if attestation is valid for transaction
+   * @param attestationUID - EAS attestation UID
+   * @param txId - Transaction ID
+   * @returns true if attestation is unused or already used for this txId
+   *
+   * SECURITY FIX (MEDIUM-4): Updates access order for true LRU behavior
+   */
+  isValidForTransaction(attestationUID: string, txId: string): boolean {
+    const normalizedUID = attestationUID.toLowerCase();
+    const normalizedTxId = txId.toLowerCase();
+
+    const existingTxId = this.usedAttestations.get(normalizedUID);
+
+    // SECURITY FIX (MEDIUM-4): True LRU - move accessed item to end
+    if (existingTxId !== undefined) {
+      this.usedAttestations.delete(normalizedUID);
+      this.usedAttestations.set(normalizedUID, existingTxId);
+    }
+
+    // Valid if: not used OR used for same transaction
+    return !existingTxId || existingTxId === normalizedTxId;
+  }
+
+  /**
+   * Clear all tracked attestations
+   */
+  clear(): void {
+    this.usedAttestations.clear();
+  }
+
+  /**
+   * Get all tracked attestations (for debugging/persistence)
+   */
+  getAllUsages(): Record<string, string> {
+    return Object.fromEntries(this.usedAttestations.entries());
+  }
+
+  /**
+   * Get count of tracked attestations
+   */
+  getCount(): number {
+    return this.usedAttestations.size;
+  }
+
+  /**
+   * Cleanup old entries based on timestamp (optional)
+   *
+   * SECURITY FIX (NEW-H-2): Manual cleanup for old entries
+   * Note: This requires external timestamp tracking. For automatic cleanup,
+   * use FileBasedUsedAttestationTracker with periodic cleanup.
+   *
+   * @param maxAgeHours - Remove entries older than this many hours
+   */
+  cleanupOldEntries(maxAgeHours: number): number {
+    // In-memory tracker doesn't track timestamps
+    // This is a placeholder for future enhancement
+    console.warn(
+      'cleanupOldEntries not implemented for InMemoryUsedAttestationTracker. ' +
+      'Consider using FileBasedUsedAttestationTracker for time-based cleanup.'
+    );
+    return 0;
+  }
+}
+
+/**
+ * File-based Used Attestation Tracker for persistence
+ *
+ * SECURITY FIX (C-1): Persistent storage for attestation tracking
+ * SECURITY FIX (NEW-H-4): File locking to prevent concurrent write corruption
+ *
+ * Survives process restarts.
+ */
+export class FileBasedUsedAttestationTracker implements IUsedAttestationTracker {
+  private inMemory: InMemoryUsedAttestationTracker;
+  private filePath: string;
+  private fs: typeof import('fs');
+  private path: typeof import('path');
+  private lockfile: typeof import('proper-lockfile');
+
+  constructor(stateDirectory: string) {
+    this.inMemory = new InMemoryUsedAttestationTracker();
+    this.fs = require('fs');
+    this.path = require('path');
+    // SECURITY FIX (NEW-H-4): File locking to prevent race conditions
+    this.lockfile = require('proper-lockfile');
+
+    // Ensure directory exists
+    const actpDir = this.path.join(stateDirectory, '.actp');
+    ensureSafeDir(actpDir, 0o755);
+
+    this.filePath = this.path.join(actpDir, 'used-attestations.json');
+
+    // Load existing data
+    this.loadFromFile();
+  }
+
+  private loadFromFile(): void {
+    if (!this.fs.existsSync(this.filePath)) return;
+
+    // SECURITY: Refuse to read from symlinked tracker files
+    assertSafeFileForRead(this.filePath);
+
+    // Basic size limit to avoid memory DoS on parse
+    const MAX_TRACKER_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+    const st = this.fs.statSync(this.filePath);
+    if (st.size > MAX_TRACKER_FILE_SIZE) {
+      throw new Error(
+        `used-attestations.json exceeds ${MAX_TRACKER_FILE_SIZE / 1024 / 1024}MB limit: ${this.filePath}`
+      );
+    }
+
+    try {
+      const data = JSON.parse(this.fs.readFileSync(this.filePath, 'utf-8'));
+      for (const [uid, txId] of Object.entries(data)) {
+        this.inMemory.recordUsageSync(uid, txId as string);
+      }
+    } catch (e: any) {
+      // Fail closed: losing replay-protection state is a security issue.
+      throw new Error(
+        `Failed to parse used-attestations.json (replay protection would be disabled). ` +
+          `Fix/delete the file: ${this.filePath}. Error: ${e?.message || String(e)}`
+      );
+    }
+  }
+
+  /**
+   * Save data to file with file locking
+   *
+   * SECURITY FIX (NEW-H-4): File locking prevents concurrent write corruption
+   * SECURITY FIX (NEW-HIGH-1): Create file before locking if it doesn't exist
+   */
+  private async saveToFile(): Promise<void> {
+    const data = this.inMemory.getAllUsages();
+    const tempPath = `${this.filePath}.tmp`;
+
+    // SECURITY FIX (NEW-HIGH-1): Ensure file exists before locking
+    // proper-lockfile.lock() fails on non-existent files
+    ensureSafeFile(this.filePath, '{}', 0o644);
+
+    // SECURITY FIX (NEW-H-4): Acquire file lock before writing
+    let release: (() => Promise<void>) | null = null;
+    try {
+      release = await this.lockfile.lock(this.filePath, {
+        stale: 10000, // Lock expires after 10 seconds if process crashes
+        retries: {
+          retries: 5,
+          minTimeout: 100,
+          maxTimeout: 500
+        }
+      });
+
+      // Atomic write: temp file + rename
+      if (this.fs.existsSync(tempPath)) {
+        this.fs.unlinkSync(tempPath);
+      }
+      this.fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), {
+        encoding: 'utf-8',
+        mode: 0o644,
+        flag: 'wx'
+      });
+      this.fs.renameSync(tempPath, this.filePath);
+    } catch (error) {
+      // Clean up temp file on error
+      if (this.fs.existsSync(tempPath)) {
+        try {
+          this.fs.unlinkSync(tempPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+      throw error;
+    } finally {
+      // Always release lock if acquired
+      if (release) {
+        await release();
+      }
+    }
+  }
+
+  /**
+   * Record attestation usage with guaranteed persistence
+   *
+   * SECURITY FIX (HIGH-1): Now properly awaits persistence to prevent data loss
+   */
+  async recordUsage(attestationUID: string, txId: string): Promise<boolean> {
+    const result = this.inMemory.recordUsageSync(attestationUID, txId);
+    if (result) {
+      // SECURITY FIX (HIGH-1): Await persistence to ensure data is saved
+      await this.saveToFile();
+    }
+    return result;
+  }
+
+  /**
+   * Fire-and-forget version for backward compatibility
+   * WARNING: May lose data if process crashes before save completes
+   */
+  recordUsageSync(attestationUID: string, txId: string): boolean {
+    const result = this.inMemory.recordUsageSync(attestationUID, txId);
+    if (result) {
+      this.saveToFile().catch((err) => {
+        console.error('Failed to save attestation tracker state:', err);
+      });
+    }
+    return result;
+  }
+
+  getUsageForAttestation(attestationUID: string): string | null {
+    return this.inMemory.getUsageForAttestation(attestationUID);
+  }
+
+  isValidForTransaction(attestationUID: string, txId: string): boolean {
+    return this.inMemory.isValidForTransaction(attestationUID, txId);
+  }
+
+  clear(): void {
+    this.inMemory.clear();
+    if (this.fs.existsSync(this.filePath)) {
+      this.fs.unlinkSync(this.filePath);
+    }
+  }
+}
+
+/**
+ * Factory to create attestation tracker
+ * @param stateDirectory - Optional directory for persistent storage
+ * @returns IUsedAttestationTracker instance
+ */
+export function createUsedAttestationTracker(
+  stateDirectory?: string
+): IUsedAttestationTracker {
+  if (stateDirectory) {
+    return new FileBasedUsedAttestationTracker(stateDirectory);
+  }
+  return new InMemoryUsedAttestationTracker();
+}