@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/utils/SecureNonce.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * SecureNonce - Cryptographically secure nonce generation
+ *
+ * SECURITY FIX (NEW-H-3): Provides secure random nonce generation
+ * to prevent weak randomness vulnerabilities in EIP-712 message signing.
+ *
+ * Reference: V7 Re-Audit NEW-H-3 (Weak Random Nonce Generation)
+ *
+ * @module utils/SecureNonce
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSecureNonces = exports.isValidNonce = exports.generateSecureNonce = void 0;
+const ethers_1 = require("ethers");
+/**
+ * Generate a cryptographically secure random nonce (bytes32)
+ *
+ * Uses ethers.js randomBytes() which:
+ * - Uses Node.js crypto.randomBytes() (CSPRNG)
+ * - Uses Web Crypto API in browsers (window.crypto.getRandomValues)
+ * - Guaranteed to be cryptographically secure
+ *
+ * @returns 32-byte hex string (0x...)
+ *
+ * @example
+ * ```typescript
+ * import { generateSecureNonce } from '@agirails/sdk';
+ *
+ * const nonce = generateSecureNonce();
+ * console.log(nonce); // 0x1234...abcd (64 hex chars)
+ * ```
+ */
+function generateSecureNonce() {
+    return ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(32));
+}
+exports.generateSecureNonce = generateSecureNonce;
+/**
+ * Validate nonce format (must be bytes32)
+ *
+ * @param nonce - Nonce to validate
+ * @returns true if valid bytes32 format
+ *
+ * @example
+ * ```typescript
+ * isValidNonce('0x' + '00'.repeat(32)); // true
+ * isValidNonce('0x1234'); // false (too short)
+ * isValidNonce('not-hex'); // false (invalid format)
+ * ```
+ */
+function isValidNonce(nonce) {
+    return /^0x[a-fA-F0-9]{64}$/.test(nonce);
+}
+exports.isValidNonce = isValidNonce;
+/**
+ * Generate an array of secure nonces
+ *
+ * @param count - Number of nonces to generate
+ * @returns Array of bytes32 hex strings
+ *
+ * @example
+ * ```typescript
+ * const nonces = generateSecureNonces(10);
+ * console.log(nonces.length); // 10
+ * ```
+ */
+function generateSecureNonces(count) {
+    if (count <= 0) {
+        throw new Error('Count must be positive');
+    }
+    if (count > 10000) {
+        throw new Error('Count exceeds maximum allowed (10000)');
+    }
+    const nonces = [];
+    for (let i = 0; i < count; i++) {
+        nonces.push(generateSecureNonce());
+    }
+    return nonces;
+}
+exports.generateSecureNonces = generateSecureNonces;
+//# sourceMappingURL=SecureNonce.js.map

package/dist/utils/SecureNonce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureNonce.js","sourceRoot":"","sources":["../../src/utils/SecureNonce.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,mCAAgC;AAEhC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,mBAAmB;IACjC,OAAO,eAAM,CAAC,OAAO,CAAC,eAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAChD,CAAC;AAFD,kDAEC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,YAAY,CAAC,KAAa;IACxC,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAFD,oCAEC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAAC,KAAa;IAChD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAbD,oDAaC"}

package/dist/utils/Semaphore.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 declare class Semaphore {
+    private permits;
+    private readonly maxPermits;
+    private readonly waitQueue;
+    /**
+     * Create a semaphore with specified concurrency limit
+     *
+     * @param maxPermits - Maximum concurrent permits (default: 10)
+     * @throws Error if maxPermits is not positive
+     */
+    constructor(maxPermits?: number);
+    /**
+     * 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
+     */
+    acquire(timeoutMs?: number): Promise<void>;
+    /**
+     * Try to acquire a permit without waiting
+     *
+     * @returns true if permit was acquired, false if none available
+     */
+    tryAcquire(): boolean;
+    /**
+     * Release a permit
+     *
+     * @throws Error if releasing more permits than acquired
+     */
+    release(): void;
+    /**
+     * 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
+     */
+    run<T>(fn: () => Promise<T> | T, timeoutMs?: number): Promise<T>;
+    /**
+     * Get current available permits
+     */
+    get availablePermits(): number;
+    /**
+     * Get number of waiters in queue
+     */
+    get queueLength(): number;
+    /**
+     * Get maximum permits
+     */
+    get limit(): number;
+    /**
+     * Check if semaphore is fully utilized
+     */
+    get isFull(): boolean;
+    /**
+     * Cancel all waiting tasks
+     *
+     * @param reason - Error message for rejected promises
+     */
+    cancelAll(reason?: string): void;
+}
+/**
+ * Rate limiter using sliding window algorithm
+ *
+ * SECURITY FIX (MEDIUM-4): Complements semaphore for rate-based limiting
+ */
+export declare class RateLimiter {
+    private readonly timestamps;
+    private readonly windowMs;
+    private readonly maxRequests;
+    /**
+     * Create a rate limiter
+     *
+     * @param maxRequests - Maximum requests per window
+     * @param windowMs - Time window in milliseconds
+     */
+    constructor(maxRequests: number, windowMs: number);
+    /**
+     * Check if a request is allowed and record it
+     *
+     * @returns true if request is allowed, false if rate limited
+     */
+    tryAcquire(): boolean;
+    /**
+     * Wait until a request is allowed
+     *
+     * @param timeoutMs - Optional timeout
+     * @returns Promise that resolves when request is allowed
+     */
+    acquire(timeoutMs?: number): Promise<void>;
+    /**
+     * Get time until next slot is available
+     *
+     * @returns Milliseconds until next slot, or 0 if slot available
+     */
+    timeUntilNextSlot(): number;
+    /**
+     * Get current usage stats
+     */
+    get stats(): {
+        current: number;
+        max: number;
+        windowMs: number;
+    };
+}
+//# sourceMappingURL=Semaphore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Semaphore.d.ts","sourceRoot":"","sources":["../../src/utils/Semaphore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGlB;IAER;;;;;OAKG;gBACS,UAAU,GAAE,MAAW;IAQnC;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BnD;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAQrB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAcf;;;;;;;;;OASG;IACG,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,SAAS,GAAE,MAAU,GAAG,OAAO,CAAC,CAAC,CAAC;IASzE;;OAEG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,GAAE,MAA8B,GAAG,IAAI;CAMxD;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAWjD;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAmBrB;;;;;OAKG;IACG,OAAO,CAAC,SAAS,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnD;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAgB3B;;OAEG;IACH,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAa9D;CACF"}

package/dist/utils/Semaphore.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = exports.Semaphore = void 0;
+/**
+ * Simple semaphore for limiting concurrent operations
+ *
+ * Uses a FIFO queue to ensure fair scheduling of waiting tasks.
+ */
+class Semaphore {
+    /**
+     * Create a semaphore with specified concurrency limit
+     *
+     * @param maxPermits - Maximum concurrent permits (default: 10)
+     * @throws Error if maxPermits is not positive
+     */
+    constructor(maxPermits = 10) {
+        this.waitQueue = [];
+        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 = 0) {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        // No permits available, queue the request
+        return new Promise((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() {
+        if (this.permits > 0) {
+            this.permits--;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Release a permit
+     *
+     * @throws Error if releasing more permits than acquired
+     */
+    release() {
+        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(fn, timeoutMs = 0) {
+        await this.acquire(timeoutMs);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    /**
+     * Get current available permits
+     */
+    get availablePermits() {
+        return this.permits;
+    }
+    /**
+     * Get number of waiters in queue
+     */
+    get queueLength() {
+        return this.waitQueue.length;
+    }
+    /**
+     * Get maximum permits
+     */
+    get limit() {
+        return this.maxPermits;
+    }
+    /**
+     * Check if semaphore is fully utilized
+     */
+    get isFull() {
+        return this.permits === 0;
+    }
+    /**
+     * Cancel all waiting tasks
+     *
+     * @param reason - Error message for rejected promises
+     */
+    cancelAll(reason = 'Semaphore cancelled') {
+        while (this.waitQueue.length > 0) {
+            const waiter = this.waitQueue.shift();
+            waiter.reject(new Error(reason));
+        }
+    }
+}
+exports.Semaphore = Semaphore;
+/**
+ * Rate limiter using sliding window algorithm
+ *
+ * SECURITY FIX (MEDIUM-4): Complements semaphore for rate-based limiting
+ */
+class RateLimiter {
+    /**
+     * Create a rate limiter
+     *
+     * @param maxRequests - Maximum requests per window
+     * @param windowMs - Time window in milliseconds
+     */
+    constructor(maxRequests, windowMs) {
+        this.timestamps = [];
+        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() {
+        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 = 0) {
+        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() {
+        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() {
+        // 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,
+        };
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=Semaphore.js.map

package/dist/utils/Semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Semaphore.js","sourceRoot":"","sources":["../../src/utils/Semaphore.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH;;;;GAIG;AACH,MAAa,SAAS;IAQpB;;;;;OAKG;IACH,YAAY,aAAqB,EAAE;QAXlB,cAAS,GAGrB,EAAE,CAAC;QASN,IAAI,UAAU,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,+CAA+C,UAAU,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,YAAoB,CAAC;QACjC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QAED,0CAA0C;QAC1C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAE5B,8BAA8B;YAC9B,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;oBAChC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;oBAC7C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;wBACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;wBAChC,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,SAAS,IAAI,CAAC,CAAC,CAAC;oBACtE,CAAC;gBACH,CAAC,EAAE,SAAS,CAAC,CAAC;gBAEd,8BAA8B;gBAC9B,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC;gBACvC,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE;oBACpB,YAAY,CAAC,SAAS,CAAC,CAAC;oBACxB,eAAe,EAAE,CAAC;gBACpB,CAAC,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QAED,6DAA6D;QAC7D,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAG,CAAC;YACvC,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG,CAAI,EAAwB,EAAE,YAAoB,CAAC;QAC1D,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,SAAiB,qBAAqB;QAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAG,CAAC;YACvC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;CACF;AAtJD,8BAsJC;AAED;;;;GAIG;AACH,MAAa,WAAW;IAKtB;;;;;OAKG;IACH,YAAY,WAAmB,EAAE,QAAgB;QAVhC,eAAU,GAAa,EAAE,CAAC;QAWzC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QAExC,uCAAuC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC;YACtE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAC1B,CAAC;QAED,8BAA8B;QAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC/C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,sBAAsB;QACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,YAAoB,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YAC1B,IAAI,SAAS,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;gBACzD,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,IAAI,CAAC,CAAC;YAC/D,CAAC;YAED,oCAAoC;YACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;YACzD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,iBAAiB;QACf,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC9C,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QACxC,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAE3C,IAAI,eAAe,IAAI,WAAW,EAAE,CAAC;YACnC,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,eAAe,GAAG,WAAW,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,0BAA0B;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QACxC,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC;YACtE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAC1B,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM;YAC/B,GAAG,EAAE,IAAI,CAAC,WAAW;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC;IACJ,CAAC;CACF;AAxGD,kCAwGC"}

package/dist/utils/UsedAttestationTracker.d.ts

@@ -0,0 +1,167 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare class InMemoryUsedAttestationTracker implements IUsedAttestationTracker {
+    private usedAttestations;
+    private readonly maxSize;
+    /**
+     * Create in-memory tracker with optional max size
+     * @param maxSize - Maximum entries to store (default: 100,000)
+     */
+    constructor(maxSize?: number);
+    /**
+     * 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
+     */
+    recordUsage(attestationUID: string, txId: string): Promise<boolean>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Clear all tracked attestations
+     */
+    clear(): void;
+    /**
+     * Get all tracked attestations (for debugging/persistence)
+     */
+    getAllUsages(): Record<string, string>;
+    /**
+     * Get count of tracked attestations
+     */
+    getCount(): number;
+    /**
+     * 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;
+}
+/**
+ * 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 declare class FileBasedUsedAttestationTracker implements IUsedAttestationTracker {
+    private inMemory;
+    private filePath;
+    private fs;
+    private path;
+    private lockfile;
+    constructor(stateDirectory: string);
+    private loadFromFile;
+    /**
+     * 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 saveToFile;
+    /**
+     * Record attestation usage with guaranteed persistence
+     *
+     * SECURITY FIX (HIGH-1): Now properly awaits persistence to prevent data loss
+     */
+    recordUsage(attestationUID: string, txId: string): Promise<boolean>;
+    /**
+     * Fire-and-forget version for backward compatibility
+     * WARNING: May lose data if process crashes before save completes
+     */
+    recordUsageSync(attestationUID: string, txId: string): boolean;
+    getUsageForAttestation(attestationUID: string): string | null;
+    isValidForTransaction(attestationUID: string, txId: string): boolean;
+    clear(): void;
+}
+/**
+ * Factory to create attestation tracker
+ * @param stateDirectory - Optional directory for persistent storage
+ * @returns IUsedAttestationTracker instance
+ */
+export declare function createUsedAttestationTracker(stateDirectory?: string): IUsedAttestationTracker;
+//# sourceMappingURL=UsedAttestationTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UsedAttestationTracker.d.ts","sourceRoot":"","sources":["../../src/utils/UsedAttestationTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpE;;;;OAIG;IACH,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,qBAAqB,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAErE;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,8BAA+B,YAAW,uBAAuB;IAE5E,OAAO,CAAC,gBAAgB,CAAkC;IAG1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;OAGG;gBACS,OAAO,GAAE,MAAe;IAOpC;;;;;;;;OAQG;IACG,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzE;;;;;OAKG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IA4B9D;;;;;;;OAOG;IACH,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAc7D;;;;;;;OAOG;IACH,qBAAqB,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAgBpE;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAItC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;CAS/C;AAED;;;;;;;GAOG;AACH,qBAAa,+BAAgC,YAAW,uBAAuB;IAC7E,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,EAAE,CAAsB;IAChC,OAAO,CAAC,IAAI,CAAwB;IACpC,OAAO,CAAC,QAAQ,CAAmC;gBAEvC,cAAc,EAAE,MAAM;IAiBlC,OAAO,CAAC,YAAY;IA6BpB;;;;;OAKG;YACW,UAAU;IAgDxB;;;;OAIG;IACG,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASzE;;;OAGG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAU9D,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI7D,qBAAqB,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpE,KAAK,IAAI,IAAI;CAMd;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,CAAC,EAAE,MAAM,GACtB,uBAAuB,CAKzB"}