feat(security): replace Record<string, any> getUIntOption with typed helper

The previous getUIntOption signature defeated the type checker:

    function getUIntOption(options: Record<string, any>, key: string)

`any` everywhere meant the value extracted by `options[key]` was typed
as `any` and passed to the cipher constructor with zero validation
beyond the cryptic `value >>> 0 !== value` check. The function also
returned `-1` as a sentinel for "missing", forcing every caller into
the awkward `getUIntOption(...) !== -1 ? getUIntOption(...) : default`
pattern (which double-evaluates).

Replace with a typed helper:
- Input: `Readonly<Record<string, unknown>> | undefined` — narrows from
  `any` to `unknown`, requiring runtime checks before use.
- Return: `number | undefined` — the missing case is type-encoded.
- Validation: explicit `Number.isFinite/Integer + range [0, 2^32-1]`
  with a typed `RangeError` and a descriptive message.

The single call site collapses from a 4-line conditional to:

    const authTagLen = getUIntOption(options, 'authTagLength') ?? 16;

Adds 4 regression tests covering negative, NaN, fractional, and
missing-defaults-to-16 paths.

Phase 1.4 of plans/todo/security-audit.md.

Author: boorad

example/src/tests/cipher/cipher_tests.ts

@@ -492,3 +492,48 @@ test(
     expect(() => decipher.final()).to.throw();
   },
 );
+
+// --- getUIntOption type-safety regression (Phase 1.4) ---
+//
+// Ensure the AEAD `authTagLength` option is validated at the JS boundary.
+// The previous implementation used `Record<string, any>` and the cryptic
+// `value >>> 0 !== value` check; the typed replacement throws RangeError
+// with a clear "must be a non-negative 32-bit integer" message.
+
+test(SUITE, 'createCipheriv: rejects negative authTagLength', () => {
+  expect(() => {
+    createCipheriv('aes-256-gcm', key32, iv12, {
+      authTagLength: -1,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+  }).to.throw(/non-negative/i);
+});
+
+test(SUITE, 'createCipheriv: rejects NaN authTagLength', () => {
+  expect(() => {
+    createCipheriv('aes-256-gcm', key32, iv12, {
+      authTagLength: NaN,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+  }).to.throw(/non-negative/i);
+});
+
+test(SUITE, 'createCipheriv: rejects fractional authTagLength', () => {
+  expect(() => {
+    createCipheriv('aes-256-gcm', key32, iv12, {
+      authTagLength: 12.5,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+  }).to.throw(/non-negative/i);
+});
+
+test(
+  SUITE,
+  'createCipheriv: missing authTagLength still defaults to 16',
+  () => {
+    // Sanity check that the new helper's `?? 16` default still kicks in.
+    expect(() => {
+      createCipheriv('aes-256-gcm', key32, iv12, {});
+    }).to.not.throw();
+  },
+);

packages/react-native-quick-crypto/src/cipher.ts

@@ -107,10 +107,12 @@ class CipherCommon extends Stream.Transform {
     }
     super(streamOptions); // Pass filtered options
 
-    const authTagLen: number =
-      getUIntOption(options ?? {}, 'authTagLength') !== -1
-        ? getUIntOption(options ?? {}, 'authTagLength')
-        : 16; // defaults to 16 bytes
+    // defaults to 16 bytes for AEAD modes; non-AEAD callers ignore it.
+    const authTagLen =
+      getUIntOption(
+        options as Readonly<Record<string, unknown>> | undefined,
+        'authTagLength',
+      ) ?? 16;
 
     const factory =
       NitroModules.createHybridObject<CipherFactory>('CipherFactory');

packages/react-native-quick-crypto/src/utils/cipher.ts

@@ -48,13 +48,35 @@ export function validateEncoding(data: string, encoding: string) {
   }
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getUIntOption(options: Record<string, any>, key: string) {
-  let value;
-  if (options && (value = options[key]) != null) {
-    // >>> Turns any type into a positive integer (also sets the sign bit to 0)
-    if (value >>> 0 !== value) throw new Error(`options.${key}: ${value}`);
-    return value;
+/**
+ * Reads an unsigned-integer option from an options-like object.
+ *
+ * Returns `undefined` if the option is missing, `null`, or `undefined`.
+ * Throws `RangeError` if the value is present but not a non-negative
+ * 32-bit integer (NaN, Infinity, fractional, negative, or > 2^32 - 1).
+ *
+ * Replaces the previous `Record<string, any>` + sentinel-`-1` signature,
+ * which defeated the type checker (audit Phase 1.4). Callers that used
+ * `getUIntOption(opts ?? {}, key) !== -1 ? getUIntOption(...) : default`
+ * collapse to `getUIntOption(opts, key) ?? default`.
+ */
+export function getUIntOption(
+  options: Readonly<Record<string, unknown>> | undefined,
+  key: string,
+): number | undefined {
+  if (options == null) return undefined;
+  const value = options[key];
+  if (value == null) return undefined;
+  if (
+    typeof value !== 'number' ||
+    !Number.isFinite(value) ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > 0xffff_ffff
+  ) {
+    throw new RangeError(
+      `options.${key} must be a non-negative 32-bit integer, got ${String(value)}`,
+    );
   }
-  return -1;
+  return value;
 }