@agirails/sdk 2.5.3 → 2.5.5

package/src/utils/Semaphore.ts

@@ -1,276 +0,0 @@
-/**
- * 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

@@ -1,385 +0,0 @@
-/**
- * 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';
-import { sdkLogger } from './Logger';
-
-/**
- * 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
-    sdkLogger.warn('cleanupOldEntries not implemented for InMemoryUsedAttestationTracker - use FileBasedUsedAttestationTracker');
-    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) => {
-        sdkLogger.error('Failed to save attestation tracker state', { error: err instanceof Error ? err.message : String(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();
-}

package/src/utils/canonicalJson.ts

@@ -1,38 +0,0 @@
-/**
- * Canonical JSON Serialization for AIP-4
- * Reference: AIP-4 §3.6
- *
- * CRITICAL: Uses fast-json-stable-stringify@^2.1.0 for deterministic hashing
- * This ensures resultHash is identical across all implementations (JS, Python, Go, Rust)
- */
-
-import stringify from 'fast-json-stable-stringify';
-import { keccak256, toUtf8Bytes } from 'ethers';
-
-/**
- * Canonical JSON stringify (sorted keys, no whitespace)
- * @param obj - Any JSON-serializable object
- * @returns Canonical JSON string
- */
-export function canonicalJsonStringify(obj: any): string {
-  return stringify(obj);
-}
-
-/**
- * Compute keccak256 hash of canonical JSON
- * @param obj - Any JSON-serializable object
- * @returns Keccak256 hash (0x-prefixed hex string)
- */
-export function computeCanonicalHash(obj: any): string {
-  const canonical = canonicalJsonStringify(obj);
-  return keccak256(toUtf8Bytes(canonical));
-}
-
-/**
- * Compute result hash for delivery proof (AIP-4)
- * @param resultData - Service result data
- * @returns Keccak256 hash of canonical result JSON
- */
-export function computeResultHash(resultData: any): string {
-  return computeCanonicalHash(resultData);
-}