@xivdyetools/auth 1.0.0

package/src/timing.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tests for Timing-Safe Comparison Utilities
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { timingSafeEqual, timingSafeEqualBytes } from './timing.js';
+
+describe('timing.ts', () => {
+  describe('timingSafeEqual', () => {
+    it('should return true for equal strings', async () => {
+      const result = await timingSafeEqual('hello', 'hello');
+      expect(result).toBe(true);
+    });
+
+    it('should return false for different strings', async () => {
+      const result = await timingSafeEqual('hello', 'world');
+      expect(result).toBe(false);
+    });
+
+    it('should return false for strings of different lengths', async () => {
+      const result = await timingSafeEqual('short', 'much longer string');
+      expect(result).toBe(false);
+    });
+
+    it('should return true for empty strings', async () => {
+      const result = await timingSafeEqual('', '');
+      expect(result).toBe(true);
+    });
+
+    it('should return false when one string is empty', async () => {
+      const result = await timingSafeEqual('hello', '');
+      expect(result).toBe(false);
+    });
+
+    it('should handle unicode strings', async () => {
+      const result = await timingSafeEqual('こんにちは', 'こんにちは');
+      expect(result).toBe(true);
+    });
+
+    it('should correctly compare similar strings', async () => {
+      // These strings differ only in the last character
+      const result = await timingSafeEqual('password1', 'password2');
+      expect(result).toBe(false);
+    });
+
+    it('should correctly compare strings that differ only in first character', async () => {
+      const result = await timingSafeEqual('apassword', 'bpassword');
+      expect(result).toBe(false);
+    });
+
+    describe('fallback implementation', () => {
+      let originalTimingSafeEqual: typeof crypto.subtle.timingSafeEqual;
+
+      beforeEach(() => {
+        // Save original and make it throw to test fallback
+        originalTimingSafeEqual = crypto.subtle.timingSafeEqual;
+        vi.stubGlobal('crypto', {
+          ...crypto,
+          subtle: {
+            ...crypto.subtle,
+            timingSafeEqual: () => {
+              throw new Error('Not available');
+            },
+          },
+        });
+      });
+
+      afterEach(() => {
+        vi.unstubAllGlobals();
+      });
+
+      it('should use fallback when crypto.subtle.timingSafeEqual throws', async () => {
+        const result = await timingSafeEqual('hello', 'hello');
+        expect(result).toBe(true);
+      });
+
+      it('should correctly compare different strings in fallback', async () => {
+        const result = await timingSafeEqual('hello', 'world');
+        expect(result).toBe(false);
+      });
+
+      it('should handle different lengths in fallback', async () => {
+        const result = await timingSafeEqual('short', 'longer');
+        expect(result).toBe(false);
+      });
+    });
+  });
+
+  describe('timingSafeEqualBytes', () => {
+    it('should return true for equal byte arrays', async () => {
+      const a = new Uint8Array([1, 2, 3, 4, 5]);
+      const b = new Uint8Array([1, 2, 3, 4, 5]);
+      const result = await timingSafeEqualBytes(a, b);
+      expect(result).toBe(true);
+    });
+
+    it('should return false for different byte arrays', async () => {
+      const a = new Uint8Array([1, 2, 3, 4, 5]);
+      const b = new Uint8Array([1, 2, 3, 4, 6]);
+      const result = await timingSafeEqualBytes(a, b);
+      expect(result).toBe(false);
+    });
+
+    it('should return false for arrays of different lengths', async () => {
+      const a = new Uint8Array([1, 2, 3]);
+      const b = new Uint8Array([1, 2, 3, 4, 5]);
+      const result = await timingSafeEqualBytes(a, b);
+      expect(result).toBe(false);
+    });
+
+    it('should return true for empty arrays', async () => {
+      const a = new Uint8Array([]);
+      const b = new Uint8Array([]);
+      const result = await timingSafeEqualBytes(a, b);
+      expect(result).toBe(true);
+    });
+  });
+});

package/src/timing.ts

@@ -0,0 +1,84 @@
+/**
+ * Timing-Safe Comparison Utilities
+ *
+ * Provides constant-time comparison to prevent timing attacks.
+ * Regular string comparison (===) can leak information about secrets
+ * because it short-circuits on the first non-matching character.
+ *
+ * @module timing
+ */
+
+/**
+ * Performs a constant-time string comparison to prevent timing attacks.
+ *
+ * Uses `crypto.subtle.timingSafeEqual()` when available (Cloudflare Workers),
+ * with a fallback XOR-based implementation for other environments.
+ *
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @returns true if strings are equal, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = await timingSafeEqual(providedToken, expectedToken);
+ * ```
+ */
+export async function timingSafeEqual(a: string, b: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const aBytes = encoder.encode(a);
+  const bBytes = encoder.encode(b);
+
+  // If lengths differ, we still need to do constant-time comparison
+  // to avoid leaking length information. Use the longer length.
+  const maxLength = Math.max(aBytes.length, bBytes.length);
+
+  // Pad shorter array to match length (prevents length-based timing leak)
+  const aPadded = new Uint8Array(maxLength);
+  const bPadded = new Uint8Array(maxLength);
+  aPadded.set(aBytes);
+  bPadded.set(bBytes);
+
+  // Use crypto.subtle.timingSafeEqual if available (Cloudflare Workers)
+  try {
+    const result = await crypto.subtle.timingSafeEqual(aPadded, bPadded);
+    // Also check original lengths matched
+    return result && aBytes.length === bBytes.length;
+  } catch {
+    // Fallback: manual constant-time comparison (for environments without timingSafeEqual)
+    let diff = aBytes.length ^ bBytes.length;
+    for (let i = 0; i < maxLength; i++) {
+      diff |= aPadded[i] ^ bPadded[i];
+    }
+    return diff === 0;
+  }
+}
+
+/**
+ * Performs constant-time comparison on Uint8Arrays.
+ *
+ * @param a - First array to compare
+ * @param b - Second array to compare
+ * @returns true if arrays are equal, false otherwise
+ */
+export async function timingSafeEqualBytes(
+  a: Uint8Array,
+  b: Uint8Array
+): Promise<boolean> {
+  const maxLength = Math.max(a.length, b.length);
+
+  const aPadded = new Uint8Array(maxLength);
+  const bPadded = new Uint8Array(maxLength);
+  aPadded.set(a);
+  bPadded.set(b);
+
+  try {
+    const result = await crypto.subtle.timingSafeEqual(aPadded, bPadded);
+    return result && a.length === b.length;
+  } catch {
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < maxLength; i++) {
+      diff |= aPadded[i] ^ bPadded[i];
+    }
+    return diff === 0;
+  }
+}