@teneo-protocol/sdk 1.0.0

package/src/utils/retry-policy.ts

@@ -0,0 +1,272 @@
+/**
+ * RetryPolicy - Configurable retry strategy for connection and webhook retries
+ * Supports exponential, linear, and constant backoff strategies
+ */
+
+import { z } from "zod";
+
+/**
+ * Retry strategy types
+ */
+export type RetryStrategyType = "exponential" | "linear" | "constant";
+
+/**
+ * Retry strategy configuration
+ */
+export interface RetryStrategy {
+  /** Strategy type: exponential, linear, or constant */
+  type: RetryStrategyType;
+  /** Base delay in milliseconds (first retry delay) */
+  baseDelay: number;
+  /** Maximum delay cap in milliseconds */
+  maxDelay: number;
+  /** Maximum number of retry attempts (0 = no retries) */
+  maxAttempts: number;
+  /** Add random jitter to prevent thundering herd */
+  jitter: boolean;
+  /** Backoff multiplier for exponential strategy (default: 2) */
+  backoffMultiplier?: number;
+}
+
+/**
+ * Zod schema for retry strategy validation
+ */
+export const RetryStrategySchema = z.object({
+  type: z.enum(["exponential", "linear", "constant"]),
+  baseDelay: z.number().min(0).max(300000), // 0-5 minutes
+  maxDelay: z.number().min(0).max(3600000), // 0-1 hour
+  maxAttempts: z.number().min(0).max(1000),
+  jitter: z.boolean(),
+  backoffMultiplier: z.number().min(1).max(10).optional()
+});
+
+/**
+ * RetryPolicy - Calculates retry delays and determines retry eligibility
+ *
+ * Supports three retry strategies:
+ * - **Exponential**: Delay increases exponentially (e.g., 1s, 2s, 4s, 8s, ...)
+ * - **Linear**: Delay increases linearly (e.g., 1s, 2s, 3s, 4s, ...)
+ * - **Constant**: Delay remains constant (e.g., 1s, 1s, 1s, 1s, ...)
+ *
+ * All strategies respect maxDelay cap and support optional jitter.
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff with default multiplier of 2
+ * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+ * console.log(policy.calculateDelay(1)); // ~1000ms
+ * console.log(policy.calculateDelay(2)); // ~2000ms
+ * console.log(policy.calculateDelay(3)); // ~4000ms
+ *
+ * // Linear backoff
+ * const policy = RetryPolicy.linear(2000, 30000, 5, false);
+ * console.log(policy.calculateDelay(1)); // 2000ms
+ * console.log(policy.calculateDelay(2)); // 4000ms
+ * console.log(policy.calculateDelay(3)); // 6000ms
+ *
+ * // Constant delay
+ * const policy = RetryPolicy.constant(5000, 3);
+ * console.log(policy.calculateDelay(1)); // 5000ms
+ * console.log(policy.calculateDelay(2)); // 5000ms
+ * console.log(policy.calculateDelay(3)); // 5000ms
+ * ```
+ */
+export class RetryPolicy {
+  private readonly strategy: RetryStrategy;
+
+  /**
+   * Creates a new retry policy with the specified strategy
+   *
+   * @param strategy - Retry strategy configuration
+   * @throws {z.ZodError} If strategy is invalid
+   */
+  constructor(strategy: RetryStrategy) {
+    // Validate strategy with Zod
+    this.strategy = RetryStrategySchema.parse(strategy);
+
+    // Additional validation: maxDelay must be >= baseDelay
+    if (this.strategy.maxDelay < this.strategy.baseDelay) {
+      throw new Error("maxDelay must be greater than or equal to baseDelay");
+    }
+  }
+
+  /**
+   * Calculates the retry delay for a given attempt number
+   *
+   * @param attempt - Attempt number (1-indexed: 1 = first retry)
+   * @returns Delay in milliseconds before next retry
+   *
+   * @example
+   * ```typescript
+   * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+   *
+   * // First retry after 1st failure
+   * policy.calculateDelay(1); // ~1000ms (+ jitter if enabled)
+   *
+   * // Second retry after 2nd failure
+   * policy.calculateDelay(2); // ~2000ms (+ jitter if enabled)
+   * ```
+   */
+  public calculateDelay(attempt: number): number {
+    // Validate attempt number
+    if (attempt < 1) {
+      throw new Error("Attempt number must be >= 1");
+    }
+
+    let delay: number;
+
+    switch (this.strategy.type) {
+      case "exponential": {
+        const multiplier = this.strategy.backoffMultiplier || 2;
+        delay = this.strategy.baseDelay * Math.pow(multiplier, attempt - 1);
+        break;
+      }
+      case "linear": {
+        delay = this.strategy.baseDelay * attempt;
+        break;
+      }
+      case "constant": {
+        delay = this.strategy.baseDelay;
+        break;
+      }
+    }
+
+    // Cap at maxDelay
+    delay = Math.min(delay, this.strategy.maxDelay);
+
+    // Add jitter if enabled
+    if (this.strategy.jitter) {
+      // Add random jitter between 0 and 1000ms
+      delay += Math.random() * 1000;
+    }
+
+    return Math.floor(delay);
+  }
+
+  /**
+   * Determines if a retry should be attempted based on attempt count
+   *
+   * @param attempt - Current attempt number (1-indexed)
+   * @returns True if retry should be attempted, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const policy = RetryPolicy.exponential(1000, 60000, 3, false);
+   *
+   * policy.shouldRetry(1); // true
+   * policy.shouldRetry(2); // true
+   * policy.shouldRetry(3); // true
+   * policy.shouldRetry(4); // false - exceeded maxAttempts
+   * ```
+   */
+  public shouldRetry(attempt: number): boolean {
+    return attempt <= this.strategy.maxAttempts;
+  }
+
+  /**
+   * Gets the retry strategy configuration
+   *
+   * @returns Copy of the retry strategy
+   */
+  public getStrategy(): Readonly<RetryStrategy> {
+    return { ...this.strategy };
+  }
+
+  // Static factory methods for common patterns
+
+  /**
+   * Creates a retry policy with exponential backoff
+   *
+   * Delay formula: `min(baseDelay * multiplier^(attempt-1), maxDelay) + jitter`
+   *
+   * @param baseDelay - Initial delay in milliseconds
+   * @param maxDelay - Maximum delay cap in milliseconds
+   * @param maxAttempts - Maximum retry attempts
+   * @param jitter - Add random jitter (0-1000ms)
+   * @param backoffMultiplier - Exponential multiplier (default: 2)
+   * @returns RetryPolicy instance with exponential strategy
+   *
+   * @example
+   * ```typescript
+   * // Standard exponential backoff (2^n)
+   * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+   *
+   * // Faster exponential backoff (3^n)
+   * const aggressive = RetryPolicy.exponential(1000, 60000, 10, true, 3);
+   * ```
+   */
+  public static exponential(
+    baseDelay: number,
+    maxDelay: number,
+    maxAttempts: number,
+    jitter: boolean,
+    backoffMultiplier: number = 2
+  ): RetryPolicy {
+    return new RetryPolicy({
+      type: "exponential",
+      baseDelay,
+      maxDelay,
+      maxAttempts,
+      jitter,
+      backoffMultiplier
+    });
+  }
+
+  /**
+   * Creates a retry policy with linear backoff
+   *
+   * Delay formula: `min(baseDelay * attempt, maxDelay) + jitter`
+   *
+   * @param baseDelay - Delay increment per attempt in milliseconds
+   * @param maxDelay - Maximum delay cap in milliseconds
+   * @param maxAttempts - Maximum retry attempts
+   * @param jitter - Add random jitter (0-1000ms)
+   * @returns RetryPolicy instance with linear strategy
+   *
+   * @example
+   * ```typescript
+   * // Linear backoff: 2s, 4s, 6s, 8s, ...
+   * const policy = RetryPolicy.linear(2000, 30000, 10, false);
+   * ```
+   */
+  public static linear(
+    baseDelay: number,
+    maxDelay: number,
+    maxAttempts: number,
+    jitter: boolean
+  ): RetryPolicy {
+    return new RetryPolicy({
+      type: "linear",
+      baseDelay,
+      maxDelay,
+      maxAttempts,
+      jitter
+    });
+  }
+
+  /**
+   * Creates a retry policy with constant delay
+   *
+   * Delay formula: `baseDelay + jitter`
+   *
+   * @param delay - Constant delay in milliseconds
+   * @param maxAttempts - Maximum retry attempts
+   * @param jitter - Add random jitter (0-1000ms, default: false)
+   * @returns RetryPolicy instance with constant strategy
+   *
+   * @example
+   * ```typescript
+   * // Retry every 5 seconds, max 3 times
+   * const policy = RetryPolicy.constant(5000, 3);
+   * ```
+   */
+  public static constant(delay: number, maxAttempts: number, jitter: boolean = false): RetryPolicy {
+    return new RetryPolicy({
+      type: "constant",
+      baseDelay: delay,
+      maxDelay: delay,
+      maxAttempts,
+      jitter
+    });
+  }
+}

package/src/utils/secure-private-key.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Tests for SecurePrivateKey class
+ * Verifies secure encryption, decryption, memory cleanup, and integration with viem
+ */
+
+import { SecurePrivateKey } from './secure-private-key';
+import { privateKeyToAccount } from 'viem/accounts';
+
+describe('SecurePrivateKey', () => {
+  // Test private key (do NOT use in production)
+  const testPrivateKey = '0x1234567890123456789012345678901234567890123456789012345678901234';
+
+  describe('constructor', () => {
+    it('should create instance with valid private key', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      expect(secureKey).toBeInstanceOf(SecurePrivateKey);
+      expect(secureKey.isDestroyed()).toBe(false);
+      secureKey.destroy();
+    });
+
+    it('should throw error with empty private key', () => {
+      expect(() => new SecurePrivateKey('')).toThrow('Private key must be a non-empty string');
+    });
+
+    it('should throw error with null private key', () => {
+      expect(() => new SecurePrivateKey(null as any)).toThrow('Private key must be a non-empty string');
+    });
+
+    it('should throw error with undefined private key', () => {
+      expect(() => new SecurePrivateKey(undefined as any)).toThrow(
+        'Private key must be a non-empty string'
+      );
+    });
+
+    it('should throw error with non-string private key', () => {
+      expect(() => new SecurePrivateKey(123 as any)).toThrow('Private key must be a non-empty string');
+    });
+  });
+
+  describe('use()', () => {
+    it('should decrypt and pass key to callback', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const result = secureKey.use((key) => {
+        expect(key).toBe(testPrivateKey);
+        return 'success';
+      });
+
+      expect(result).toBe('success');
+      secureKey.destroy();
+    });
+
+    it('should return callback result', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const result = secureKey.use((key) => {
+        return { key: key.substring(0, 10), length: key.length };
+      });
+
+      expect(result).toEqual({ key: testPrivateKey.substring(0, 10), length: testPrivateKey.length });
+      secureKey.destroy();
+    });
+
+    it('should work with async callbacks', async () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const result = await secureKey.use(async (key) => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return key.length;
+      });
+
+      expect(result).toBe(testPrivateKey.length);
+      secureKey.destroy();
+    });
+
+    it('should allow multiple uses', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const result1 = secureKey.use((key) => key.length);
+      const result2 = secureKey.use((key) => key.substring(0, 5));
+      const result3 = secureKey.use((key) => key);
+
+      expect(result1).toBe(testPrivateKey.length);
+      expect(result2).toBe(testPrivateKey.substring(0, 5));
+      expect(result3).toBe(testPrivateKey);
+
+      secureKey.destroy();
+    });
+
+    it('should throw if key has been destroyed', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      secureKey.destroy();
+
+      expect(() => {
+        secureKey.use((key) => key);
+      }).toThrow('SecurePrivateKey has been destroyed and can no longer be used');
+    });
+
+    it('should propagate errors from callback', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      expect(() => {
+        secureKey.use((key) => {
+          throw new Error('Test error');
+        });
+      }).toThrow('Test error');
+
+      secureKey.destroy();
+    });
+
+    it('should clean up even if callback throws', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      try {
+        secureKey.use((key) => {
+          throw new Error('Test error');
+        });
+      } catch (error) {
+        // Expected
+      }
+
+      // Key should still be usable after error
+      const result = secureKey.use((key) => key.length);
+      expect(result).toBe(testPrivateKey.length);
+
+      secureKey.destroy();
+    });
+  });
+
+  describe('destroy()', () => {
+    it('should mark instance as destroyed', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      expect(secureKey.isDestroyed()).toBe(false);
+
+      secureKey.destroy();
+      expect(secureKey.isDestroyed()).toBe(true);
+    });
+
+    it('should be idempotent (safe to call multiple times)', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      secureKey.destroy();
+      secureKey.destroy();
+      secureKey.destroy();
+
+      expect(secureKey.isDestroyed()).toBe(true);
+    });
+
+    it('should prevent further use after destruction', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      secureKey.destroy();
+
+      expect(() => {
+        secureKey.use((key) => key);
+      }).toThrow('SecurePrivateKey has been destroyed');
+    });
+  });
+
+  describe('isDestroyed()', () => {
+    it('should return false for new instance', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      expect(secureKey.isDestroyed()).toBe(false);
+      secureKey.destroy();
+    });
+
+    it('should return true after destruction', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+      secureKey.destroy();
+      expect(secureKey.isDestroyed()).toBe(true);
+    });
+  });
+
+  describe('encryption/decryption', () => {
+    it('should correctly encrypt and decrypt private key', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const decrypted = secureKey.use((key) => key);
+      expect(decrypted).toBe(testPrivateKey);
+
+      secureKey.destroy();
+    });
+
+    it('should handle keys with special characters', () => {
+      const specialKey = '0xABCDEF123456!@#$%^&*()_+-=[]{}|;:,.<>?';
+      const secureKey = new SecurePrivateKey(specialKey);
+
+      const decrypted = secureKey.use((key) => key);
+      expect(decrypted).toBe(specialKey);
+
+      secureKey.destroy();
+    });
+
+    it('should handle very long keys', () => {
+      const longKey = '0x' + 'a'.repeat(1000);
+      const secureKey = new SecurePrivateKey(longKey);
+
+      const decrypted = secureKey.use((key) => key);
+      expect(decrypted).toBe(longKey);
+
+      secureKey.destroy();
+    });
+
+    it('should produce different encrypted data for same key (random IV)', () => {
+      const secureKey1 = new SecurePrivateKey(testPrivateKey);
+      const secureKey2 = new SecurePrivateKey(testPrivateKey);
+
+      // Access private encrypted buffers via any to verify they're different
+      const encrypted1 = (secureKey1 as any).encrypted;
+      const encrypted2 = (secureKey2 as any).encrypted;
+
+      // Encrypted data should be different due to random IV
+      expect(Buffer.compare(encrypted1, encrypted2)).not.toBe(0);
+
+      // But decrypted should be the same
+      const decrypted1 = secureKey1.use((key) => key);
+      const decrypted2 = secureKey2.use((key) => key);
+
+      expect(decrypted1).toBe(testPrivateKey);
+      expect(decrypted2).toBe(testPrivateKey);
+
+      secureKey1.destroy();
+      secureKey2.destroy();
+    });
+  });
+
+  describe('integration with viem', () => {
+    it('should work with privateKeyToAccount', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const account = secureKey.use((key) => {
+        return privateKeyToAccount(key as `0x${string}`);
+      });
+
+      expect(account).toBeDefined();
+      expect(account.address).toBeDefined();
+      expect(account.address).toMatch(/^0x[a-fA-F0-9]{40}$/);
+
+      secureKey.destroy();
+    });
+
+    it('should allow signing messages with account created from secure key', async () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const account = secureKey.use((key) => {
+        return privateKeyToAccount(key as `0x${string}`);
+      });
+
+      const message = 'Hello, Teneo!';
+      const signature = await account.signMessage({ message });
+
+      expect(signature).toBeDefined();
+      expect(signature).toMatch(/^0x[a-fA-F0-9]+$/);
+      expect(signature.length).toBeGreaterThan(100);
+
+      secureKey.destroy();
+    });
+
+    it('should create consistent account address across multiple uses', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const address1 = secureKey.use((key) => {
+        return privateKeyToAccount(key as `0x${string}`).address;
+      });
+
+      const address2 = secureKey.use((key) => {
+        return privateKeyToAccount(key as `0x${string}`).address;
+      });
+
+      expect(address1).toBe(address2);
+
+      secureKey.destroy();
+    });
+  });
+
+  describe('security properties', () => {
+    it('should not expose private key in toString()', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const stringified = String(secureKey);
+      expect(stringified).not.toContain(testPrivateKey);
+      expect(stringified).not.toContain(testPrivateKey.substring(5, 20));
+
+      secureKey.destroy();
+    });
+
+    it('should not expose private key in JSON.stringify()', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      const jsonString = JSON.stringify(secureKey);
+      expect(jsonString).not.toContain(testPrivateKey);
+      expect(jsonString).not.toContain(testPrivateKey.substring(5, 20));
+
+      secureKey.destroy();
+    });
+
+    it('should not expose private key when inspecting object', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      // Try to access private properties (they're still accessible via 'any' but not exposed)
+      const keys = Object.keys(secureKey);
+      const values = Object.values(secureKey);
+
+      // Should not contain the plaintext key
+      const allValues = JSON.stringify(values);
+      expect(allValues).not.toContain(testPrivateKey);
+
+      secureKey.destroy();
+    });
+
+    it('should store key encrypted in memory', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      // Access encrypted buffer via any
+      const encrypted = (secureKey as any).encrypted as Buffer;
+
+      // Encrypted data should not contain the plaintext key
+      const encryptedString = encrypted.toString('utf8');
+      expect(encryptedString).not.toContain(testPrivateKey);
+      expect(encryptedString).not.toContain('1234567890');
+
+      secureKey.destroy();
+    });
+  });
+
+  describe('memory cleanup', () => {
+    it('should zero out encryption key on destroy', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      // Get reference to encryption key before destroy
+      const encryptionKey = (secureKey as any).encryptionKey as Buffer;
+      const originalKeyData = Buffer.from(encryptionKey);
+
+      expect(originalKeyData.some((byte) => byte !== 0)).toBe(true);
+
+      secureKey.destroy();
+
+      // After destroy, encryption key should be zeroed
+      expect(encryptionKey.every((byte) => byte === 0)).toBe(true);
+    });
+
+    it('should zero out encrypted buffer on destroy', () => {
+      const secureKey = new SecurePrivateKey(testPrivateKey);
+
+      // Get reference to encrypted buffer before destroy
+      const encrypted = (secureKey as any).encrypted as Buffer;
+      const originalEncryptedData = Buffer.from(encrypted);
+
+      expect(originalEncryptedData.some((byte) => byte !== 0)).toBe(true);
+
+      secureKey.destroy();
+
+      // After destroy, encrypted buffer should be zeroed
+      expect(encrypted.every((byte) => byte === 0)).toBe(true);
+    });
+  });
+});