Feat/biometry status

[mCodex]

This pull request introduces several new features and important fixes related to biometric authentication, developer experience, and build tooling. The main focus is on improving how biometric capability and enrollment status are detected and handled, preventing double biometric prompts, and enhancing the documentation and example app to showcase these features.

Biometric authentication improvements:

• Added a new biometryStatus field to SecurityAvailability (with values like 'available', 'notEnrolled', etc.) to distinguish between hardware absence, unenrolled hardware, and usable biometry. The legacy biometry boolean remains for backward compatibility. [1] [2] [3] [4] [5] [6]
• Introduced canUseAccessControl and canUseAccessControlSync functions to predict if a specific access control policy will succeed, allowing better UX decisions before prompting users. [1] [2]
• Added useSecurityAvailability({ refreshOnForeground: true }) to auto-refresh the biometry status when the app returns to the foreground, and useBiometryStatusWatcher to listen for actual enrollment state changes. [1] [2] [3]

Bug fixes for double biometric prompts:

• Fixed double-prompt regressions on both iOS and Android: biometric-protected entries are no longer silently re-encrypted during getItem, which previously triggered a second prompt. Now, such entries are only upgraded on explicit setItem or rotateKeys({ reEncryptEagerly: true }). [1] [2]

Documentation and example updates:

• Expanded documentation in README.md and HOOKS.md to cover the new biometry status, hooks, and usage patterns, including gating toggles and handling enrollment transitions. Added a dedicated section for biometrics. [1] [2] [3] [4]
• Updated the example app to showcase the new biometry status card and improved DX for access control. [1] [2]

Build tooling and DX:

• Improved Babel configuration to ensure babel-plugin-react-compiler runs in all build scenarios, both for the library and the example app. Updated package.json dependencies accordingly. [1] [2] [3]

Summary of most important changes:

Biometric capability and policy detection:

• Added biometryStatus to SecurityAvailability and mapped native error codes for fine-grained biometry state detection. [1] [2] [3] [4] [5] [6]
• Introduced canUseAccessControl/canUseAccessControlSync for pre-checking access control policy support. [1] [2]

Hooks and auto-refresh:

• Added useSecurityAvailability({ refreshOnForeground }) and useBiometryStatusWatcher for real-time and transition-only updates. [1] [2] [3]

Double-prompt bug fixes:

• Prevented double biometric prompts on both iOS and Android by skipping lazy re-encryption for biometric-protected entries. [1] [2]

Documentation and example enhancements:

• Expanded docs and example app to demonstrate new biometry features and recommended UX patterns. [1] [2] [3] [4] [5] [6]

Build tooling:

• Improved Babel config to reliably run the React Compiler across all build paths and updated dependencies. [1] [2] [3]

[Copilot]

Pull request overview

This PR enhances biometric capability detection and UX control by introducing a fine-grained biometryStatus, adding access-control precheck helpers, and extending hooks/docs/example app to support foreground refresh and enrollment-change watching.

Changes:

• Add BiometryStatus + SecurityAvailability.biometryStatus and wire it through iOS/Android resolvers and JS typings.
• Introduce canUseAccessControl / canUseAccessControlSync, plus hook improvements (refreshOnForeground, useBiometryStatusWatcher) with tests.
• Update documentation, example UI, and Babel/tooling to support React Compiler usage and showcase new features.

Reviewed changes

Copilot reviewed 29 out of 31 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
yarn.lock	Adds babel-plugin-react-compiler dependency resolution.
package.json	Ensures bob targets load Babel config via configFile: true.
babel.config.js	Makes React Compiler plugin run consistently across build callers.
src/sensitive-info.nitro.ts	Adds BiometryStatus and SecurityAvailability.biometryStatus typing/docs.
src/index.ts	Exports new access-control helpers and BiometryStatus type.
src/core/access-control.ts	New helpers for predicting whether an access-control policy can be satisfied.
src/hooks/useSecurityAvailability.ts	Adds refreshOnForeground option and AppState-based refetching.
src/hooks/useBiometryStatusWatcher.ts	New watcher hook that emits only on biometryStatus transitions.
src/hooks/index.ts	Re-exports the new watcher hook/types and new options type.
src/hooks/useStableOptions.ts	Adds React Compiler opt-out directive for manual memoization behavior.
src/hooks/useSecureStorage.ts	Adds React Compiler opt-out directive for ref-coordination during render.
src/hooks/useMutation.ts	Adds React Compiler opt-out directive for compiler-unsupported patterns.
src/hooks/useAsync.ts	Adds React Compiler opt-out directive for compiler-unsupported patterns.
src/tests/mocks/react-native.ts	Enhances RN mock with AppState event subscription + helpers.
src/tests/hooks.useSecurityAvailability.test.tsx	Tests new biometryStatus field and refreshOnForeground behavior.
src/tests/hooks.useBiometryStatusWatcher.test.tsx	New tests covering transition-only watcher semantics.
src/tests/core.access-control.test.ts	New tests for policy/status mapping and async wrapper behavior.
src/tests/core.storage.test.ts	Updates expected SecurityAvailability snapshots to include biometryStatus.
ios/Internal/Security/SecurityAvailabilityResolver.swift	Adds native biometryStatus classification via LAError codes.
ios/HybridSensitiveInfo.swift	Wires biometryStatus into availability; avoids double prompts by skipping lazy refresh for biometric policies; improves Keychain upsert robustness.
android/src/main/java/com/sensitiveinfo/internal/crypto/SecurityAvailabilityResolver.kt	Adds Android biometryStatus classification via BiometricManager results.
android/src/main/java/com/sensitiveinfo/HybridSensitiveInfo.kt	Wires biometryStatus; skips lazy re-encryption for auth-gated entries to prevent double prompts.
docs/HOOKS.md	Documents biometryStatus, refreshOnForeground, watcher hook, and policy gating.
README.md	Adds biometrics section and usage guidance for new API/hook behavior.
CHANGELOG.md	Documents new features/fixes for upcoming release.
example/package.json	Adds React Compiler plugin dependency for the example app.
example/babel.config.js	Runs React Compiler before other transforms in the example.
example/src/components/DiagnosticsCard.tsx	Displays biometryStatus in diagnostics.
example/src/components/BiometryStatusCard.tsx	New UI card showcasing status + policy precheck + refresh behavior.
example/src/App.tsx	Adds the new example card to the app screen.
example/ios/Podfile.lock	Updates RN/React pods and example’s SensitiveInfo pod version lock.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This doc comment says devicePasscode writes can be “re-encrypted silently”, but AccessControlResolver marks DEVICEPASSCODE as requiresAuthentication = true, meaning Cipher.init can prompt for device credentials. Consider updating the comment to reflect that devicePasscode entries are also auth-gated (even if the code already treats them via entry.requiresAuthentication).

Suggested change

	* to authorize a `Cipher.init` (i.e. the access policy maps to a biometric
	* or device-credential gate). `devicePasscode`/`none` writes can be
	* re-encrypted silently with no prompt.
	* to authorize a `Cipher.init` (for example, biometric- or
	* device-credential-gated entries). Entries marked with
	* `entry.requiresAuthentication`, including `devicePasscode`, may prompt
	* during re-encryption; only entries with no authentication requirement can
	* be re-encrypted silently.

[Copilot]

SecurityAvailability.secureEnclave is documented as “always false on Android”, but Android code populates it as hasStrongBox (same as strongBox), and tests expect secureEnclave: true on Android snapshots. Either adjust the native mapping (set secureEnclave=false on Android) or update this comment to match the cross-platform semantics you intend.

[Copilot]

This test introduces a real-time 600ms sleep to get past the foreground debounce window, which slows the suite and can be flaky under heavy load. Consider using Jest fake timers (advance by 600ms) or exposing the debounce duration for tests so you don’t need wall-clock delays.

Suggested change

	await act(async () => {
	// Wait past the 500 ms debounce window before emitting again.
	await new Promise((r) => setTimeout(r, 600))
	appState.__emit('background')
	appState.__emit('active')
	})
	jest.useFakeTimers()
	try {
	await act(async () => {
	// Advance past the 500 ms debounce window before emitting again.
	jest.advanceTimersByTime(600)
	appState.__emit('background')
	appState.__emit('active')
	})
	} finally {
	jest.useRealTimers()
	}

[Copilot]

The README claims canUseAccessControl(policy) requires “no extra native round-trip” and uses {@link SecurityAvailability} (JSDoc syntax) in Markdown. In reality, canUseAccessControl calls getSupportedSecurityLevels() unless a snapshot is passed, so this should be reworded (and SecurityAvailability should be in backticks or a real Markdown link).

[Copilot]

Changelog says canUseAccessControl(...) is “no extra IPC round-trip”, but the helper performs an IPC/native call via getSupportedSecurityLevels() when levels is not provided. Please clarify that it’s a pure mapping when a snapshot is supplied, otherwise it will fetch the snapshot first.

Suggested change

* **policy precheck:** New `canUseAccessControl(policy, levels?)` and `canUseAccessControlSync(policy, levels)` predict whether a given `AccessControl` policy will succeed on the current device. Pure TS mapping over `SecurityAvailability` — no extra IPC round-trip.

* **policy precheck:** New `canUseAccessControl(policy, levels?)` and `canUseAccessControlSync(policy, levels)` predict whether a given `AccessControl` policy will succeed on the current device. When a `SecurityAvailability` snapshot is supplied, they are a pure TS mapping over that snapshot; if `levels` is omitted, `canUseAccessControl(...)` first fetches the current snapshot via the existing native/IPC path.