feat(security): Phase 1 audit foundation — shared helpers (validateUInt, secureZero, EVP_CIPHER_CTX RAII, typed getUIntOption)

[boorad]

Summary

Phase 1 of the security audit (plans/todo/security-audit.md) — adds the four shared foundation helpers that the Phase 2 / Phase 3 sweeps consume. Each helper closes a class of audit findings; this PR adds the helper, applies it to a representative reference site, and adds regression tests. The bulk sweep across all remaining sites comes in the next PRs.

#	Commit	Helper added	Reference site applied	Tests added
1.1	`dcbcd73`	`validateUInt` — rejects NaN, +/-Infinity, negative, fractional, out-of-range before the cast	`HybridArgon2` (parallelism / tagLength / memory / passes / version)	7
1.2	`2fae6bd`	`secureZero()` — `OPENSSL_cleanse` wrapper, never elided by the compiler	`XSalsa20Cipher` + `XSalsa20Poly1305Cipher` destructors	— (covered by existing round-trips)
1.3	`73ea9f3`	`EvpCipherCtxPtr` — `unique_ptr` for `EVP_CIPHER_CTX` in `HybridCipher` base	All cipher subclasses (CCM/ChaCha20/ChaCha20-Poly1305/GCM/OCB/XSalsa20)	— (covered by existing AEAD round-trips)
1.4	`7766d42`	typed `getUIntOption` returning `number | undefined`	The `authTagLength` parsing in `Cipheriv` constructor	4

Changes

1.1 — `validateUInt` helper

• `static_cast<uint32_t>(NaN | +/-Infinity | -1)` is undefined behavior in C++. The audit found ~20 sites doing the cast naked at the JS↔C++ boundary; `HybridArgon2.cpp:50` was the most prominent (parallelism, memory, passes, version, tagLength all unchecked).
• New templated `validateUInt(value, paramName, [min], [max])` in `QuickCryptoUtils.hpp` that throws `std::runtime_error` with the parameter name on any invalid input.
• Applied as the reference site to `HybridArgon2::hashImpl`. Remaining ~19 sites (PBKDF2, Scrypt, HKDF, Hash, HMAC, KMAC, BLAKE3, RSA, ML-DSA, AES-CCM) get swept in Phase 2/3.
• 7 regression tests covering NaN, +/-Infinity, negative, fractional, out-of-range parameters on the sync API and one async path proving Promise-rejection wiring.

1.2 — `secureZero()` helper

• `std::memset` for wiping secret memory is unsafe under `-O2` — the compiler sees the writes are dead and elides them.
• New `secureZero()` in `QuickCryptoUtils.hpp` wrapping `OPENSSL_cleanse` with overloads for `void* + size`, `std::vector<uint8_t>`, `std::string`, and fixed-size `uint8_t[N]` arrays.
• Applied to:
  • `XSalsa20Cipher` destructor: previously did not zero key/nonce at all (audit HIGH); also wipes the leftover_keystream from Phase 0.2.
  • `XSalsa20Poly1305Cipher` destructor: collapses the `#ifdef BLSALLOC_SODIUM` fork that fell through to plain `std::memset` (audit MEDIUM).
• Remaining ~28 sites (XChaCha20-Poly1305, all KDF derived bits, DH/ECDH shared secrets, RSA/EC/Ed/DSA DER private-key strings) get swept in Phase 2.

1.3 — `EVP_CIPHER_CTX` ownership in HybridCipher base

• Three subclasses (`CCMCipher`, `ChaCha20Cipher`, `ChaCha20Poly1305Cipher`) implemented destructors as `~SubClass() { ctx = nullptr; }` — they nulled the parent's raw pointer without freeing it first, expecting the parent destructor to do the cleanup. The parent then saw `ctx == nullptr` and skipped the `EVP_CIPHER_CTX_free` entirely. Result: every cipher object of those three types leaked its OpenSSL context.
• New `using EvpCipherCtxPtr = std::unique_ptr<EVP_CIPHER_CTX, decltype(&EVP_CIPHER_CTX_free)>` in `HybridCipher.hpp`. The base now holds the cipher context as a smart pointer with the `EVP_CIPHER_CTX_free` deleter baked in.
• Subclasses can no longer mismanage `ctx` — destruction order (subclass → base) makes the parent's `unique_ptr` destructor run automatically and free the context exactly once.
• The buggy three subclass destructors are removed (defaulted). `XSalsa20Cipher`'s destructor drops its now-redundant `ctx = nullptr` line while keeping the secureZero calls from 1.2.
• Internally every `EVP_Foo(ctx, ...)` OpenSSL call uses `ctx.get()`; every `ctx = EVP_CIPHER_CTX_new()` becomes `ctx.reset(EVP_CIPHER_CTX_new())`; every manual cleanup of `EVP_CIPHER_CTX_free(ctx); ctx = nullptr;` collapses to `ctx.reset()`. ~70 touch points across 11 cipher files.

1.4 — typed `getUIntOption`

• Old signature: `getUIntOption(options: Record<string, any>, key: string)` returning `number | -1` (sentinel).
• `any` defeated the type checker; the cryptic `value >>> 0 !== value` validation was opaque; the `-1` sentinel forced every caller into a 4-line double-evaluating conditional.
• New signature: `getUIntOption(options: Readonly<Record<string, unknown>> | undefined, key: string): number | undefined` with explicit `Number.isFinite/isInteger + range [0, 2^32-1]` validation that throws `RangeError` with a descriptive message.
• Single call site collapses from a 4-line conditional to `getUIntOption(options, 'authTagLength') ?? 16`.
• 4 regression tests covering negative, NaN, fractional, missing-defaults-to-16.

Test plan

Tests run in the example RN app (project convention — not a Node test runner). Verified locally on iOS:

• 1.1 — `argon2` suite: 7 new "rejects ..." tests pass + existing argon2 round-trips still pass.
• 1.2 — `cipher` suite (xsalsa20 + xsalsa20-poly1305): existing round-trips still pass; destructor refactor is invisible from JS.
• 1.3 — `cipher` suite (every AEAD: GCM, CCM, OCB, ChaCha20-Poly1305, ChaCha20): all existing round-trip tests still pass — biggest refactor of the PR.
• 1.4 — `cipher` suite: 4 new `createCipheriv: rejects ...` tests pass + existing GCM/CCM/OCB tests still pass.

Notes

• Each commit is independent and bisectable; the PR is broken into 4 commits matching plan items 1.1–1.4.
• Phase 1 closes the "Depends on Phase 1" precondition for Phase 2 (memory-safety sweep) and Phase 3 (TS-boundary validation) — those phases now have the helpers ready to consume.
• Test-verification rule (`.claude/rules/test-verification.xml` from PR fix(security): Phase 0 audit fixes — actively exploitable findings #982) was honored: each commit was verified by the user in the example app before this push.

[github-actions]

🤖 End-to-End Test Results - Android

Status: ✅ Passed
Platform: Android
Run: 24973841834

📸 Final Test Screenshot

Screenshot automatically captured from End-to-End tests and will expire in 30 days

---

This comment is automatically updated on each test run.

[github-actions]

🤖 End-to-End Test Results - iOS

Status: ✅ Passed
Platform: iOS
Run: 24973841839

📸 Final Test Screenshot

Screenshot automatically captured from End-to-End tests and will expire in 30 days

---

This comment is automatically updated on each test run.