feat: add Uint8Array compare function

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `areUint8ArraysEqual` function to compare two `Uint8Array` types ([#268](https://github.com/MetaMask/utils/pull/268))
+
 ## [11.7.0]
 
 ### Added

src/bytes.test.ts

@@ -7,6 +7,7 @@ import {
   UTF_8_BYTES_FIXTURES,
 } from './__fixtures__';
 import {
+  areUint8ArraysEqual,
   assertIsBytes,
   base64ToBytes,
   bigIntToBytes,
@@ -537,3 +538,103 @@ describe('createDataView', () => {
     });
   });
 });
+
+describe('areUint8ArraysEqual', () => {
+  it('returns true if the Uint8Arrays are equal', () => {
+    expect(
+      areUint8ArraysEqual(
+        new Uint8Array(32).fill(1),
+        new Uint8Array(32).fill(1),
+      ),
+    ).toBe(true);
+  });
+
+  it('returns false if the Uint8Arrays are not equal', () => {
+    expect(
+      areUint8ArraysEqual(
+        new Uint8Array(32).fill(1),
+        new Uint8Array(32).fill(2),
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false if the Uint8Arrays length is different', () => {
+    expect(
+      areUint8ArraysEqual(
+        new Uint8Array(32).fill(1),
+        new Uint8Array(31).fill(1),
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false if the first Uint8Array is shorter than the second', () => {
+    expect(
+      areUint8ArraysEqual(
+        new Uint8Array(31).fill(1),
+        new Uint8Array(32).fill(1),
+      ),
+    ).toBe(false);
+  });
+
+  it('returns true if the Uint8Arrays are both empty', () => {
+    expect(areUint8ArraysEqual(new Uint8Array(), new Uint8Array())).toBe(true);
+  });
+
+  it('returns false if there is a subtle difference in the Uint8Arrays', () => {
+    expect(
+      areUint8ArraysEqual(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]),
+        new Uint8Array([1, 2, 3, 4, 5, 6, 2, 8, 9, 10, 11, 12]),
+      ),
+    ).toBe(false);
+  });
+
+  it('has similar runtime for early vs late differences on large arrays', () => {
+    const LENGTH = 100_000;
+    const ITERATIONS = 200;
+
+    const base = new Uint8Array(LENGTH).fill(7);
+    const early = base.slice();
+    const late = base.slice();
+    early[0] = 6; // first element differs
+    late[LENGTH - 1] = 6; // last element differs
+
+    // Warm up JIT
+    for (let i = 0; i < 20; i++) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      areUint8ArraysEqual(base, base);
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      areUint8ArraysEqual(early, base);
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      areUint8ArraysEqual(late, base);
+    }
+
+    const now = () => Number(process.hrtime.bigint());
+
+    let earlyTotal = 0;
+    let lateTotal = 0;
+
+    // Measure early difference
+    const startEarly = now();
+    for (let i = 0; i < ITERATIONS; i++) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      areUint8ArraysEqual(early, base);
+    }
+    earlyTotal = now() - startEarly;
+
+    // Measure late difference
+    const startLate = now();
+    for (let i = 0; i < ITERATIONS; i++) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      areUint8ArraysEqual(late, base);
+    }
+    lateTotal = now() - startLate;
+
+    // Ratio ≈ 1.0 ⇒ similar runtimes regardless of diff position.
+    // The threshold enforces the same order of magnitude while allowing normal system jitter.
+    // It's an empirical upper bound (~p95). To tune: run multiple trials, take a high percentile, and set slightly above it.
+    const ratio =
+      earlyTotal > lateTotal ? earlyTotal / lateTotal : lateTotal / earlyTotal;
+    expect(ratio).toBeLessThan(1.1);
+  });
+});

src/bytes.ts

@@ -459,3 +459,32 @@ export function createDataView(bytes: Uint8Array): DataView {
 
   return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 }
+
+/**
+ * Compare two Uint8Arrays using a constant-time style loop to reduce timing
+ * side-channels when comparing sensitive data (e.g., mnemonic bytes, keys,
+ * authentication tags). Does not early-return on the first difference:
+ * work done depends only on the input lengths, so byte content does not affect timing.
+ *
+ * When to use:
+ * - Use for secret or security-sensitive byte comparisons to avoid content-based timing leaks.
+ * - Prefer when inputs are fixed-length (or validated to equal length) at the API boundary.
+ *
+ * @param a - The first Uint8Array to compare.
+ * @param b - The second Uint8Array to compare.
+ * @returns Whether the Uint8Arrays are equal.
+ */
+export function areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean {
+  // eslint-disable-next-line no-bitwise
+  let diff = a.byteLength ^ b.byteLength;
+  const len = Math.max(a.byteLength, b.byteLength);
+
+  for (let i = 0; i < len; i++) {
+    const aByte = a[i] ?? 0;
+    const bByte = b[i] ?? 0;
+    // eslint-disable-next-line no-bitwise
+    diff |= aByte ^ bByte;
+  }
+
+  return diff === 0;
+}

src/index.test.ts

@@ -52,6 +52,7 @@ describe('index', () => {
         "VersionRangeStruct",
         "VersionStruct",
         "add0x",
+        "areUint8ArraysEqual",
         "assert",
         "assertExhaustive",
         "assertIsBytes",

src/node.test.ts

@@ -52,6 +52,7 @@ describe('node', () => {
         "VersionRangeStruct",
         "VersionStruct",
         "add0x",
+        "areUint8ArraysEqual",
         "assert",
         "assertExhaustive",
         "assertIsBytes",