Refactor Android biometric storage and update types

Major refactor of Android secure storage module: removes Nitro module view components, updates biometric authentication flow, and improves documentation for all core classes. Updates type definitions for AccessControl and SecurityLevel, revises tests to match new types, and adds src/types.ts. Cleans up README and .gitignore, and updates example usage and configuration. This prepares the codebase for new architecture and clarifies API usage for developers.

Author: mCodex

.gitignore

@@ -82,8 +82,7 @@ lib/
 ios/generated
 android/generated
 
-# React Native Nitro Modules
-nitrogen/
+
 
 # Coverage
 coverage/

README.md

@@ -42,9 +42,6 @@ npm install react-native-sensitive-info@5.6.0
 
 # Old Architecture (RN <0.73)
 npm install react-native-sensitive-info@5.5.x
-
-# Bleeding edge (Nitro Modules, v6)
-npm install github:mCodex/react-native-sensitive-info#master
 ```
 
 ---

__tests__/comprehensive.test.ts

@@ -42,9 +42,9 @@ describe('SensitiveInfo API - Complete Coverage', () => {
   describe('Error Types', () => {
     it('should define all error codes', () => {
       const codes: ErrorCode[] = [
+        ErrorCode.NOT_FOUND,
         ErrorCode.AUTH_FAILED,
         ErrorCode.AUTH_CANCELED,
-        ErrorCode.AUTH_TIMEOUT,
         ErrorCode.BIOMETRY_LOCKOUT,
         ErrorCode.KEY_INVALIDATED,
         ErrorCode.DECRYPTION_FAILED,
@@ -53,7 +53,7 @@ describe('SensitiveInfo API - Complete Coverage', () => {
         ErrorCode.MIGRATION_FAILED,
       ];
 
-      expect(codes).toHaveLength(10);
+      expect(codes).toHaveLength(9);
       codes.forEach((code) => {
         expect(code).toMatch(/^E_/);
       });
@@ -81,13 +81,14 @@ describe('SensitiveInfo API - Complete Coverage', () => {
   describe('Type Definitions', () => {
     it('should support all AccessControl types', () => {
       const controls: AccessControl[] = [
-        'devicePasscode',
-        'biometryOrDevicePasscode',
-        'biometryAndDevicePasscode',
+        'secureEnclaveBiometry',
         'biometryCurrentSet',
+        'biometryAny',
+        'devicePasscode',
+        'none',
       ];
 
-      expect(controls).toHaveLength(4);
+      expect(controls).toHaveLength(5);
       controls.forEach((control) => {
         expect(typeof control).toBe('string');
       });
@@ -97,13 +98,12 @@ describe('SensitiveInfo API - Complete Coverage', () => {
       const levels: SecurityLevel[] = [
         'secureEnclave',
         'strongBox',
-        'hardwareBacked',
-        'biometricProtected',
-        'passcodeProtected',
+        'biometry',
+        'deviceCredential',
         'software',
       ];
 
-      expect(levels).toHaveLength(6);
+      expect(levels).toHaveLength(5);
       levels.forEach((level) => {
         expect(typeof level).toBe('string');
       });
@@ -250,8 +250,8 @@ describe('SensitiveInfo API - Complete Coverage', () => {
     });
 
     it('should define default access control level', () => {
-      const defaultControl = 'biometryOrDevicePasscode' as AccessControl;
-      expect(defaultControl).toBe('biometryOrDevicePasscode');
+      const defaultControl = 'secureEnclaveBiometry' as AccessControl;
+      expect(defaultControl).toBe('secureEnclaveBiometry');
     });
 
     it('should define keychain service constants', () => {
@@ -366,7 +366,7 @@ describe('SensitiveInfo API - Complete Coverage', () => {
         metadata: {
           timestamp: Date.now(),
           securityLevel: 'secureEnclave' as SecurityLevel,
-          accessControl: 'biometryOrDevicePasscode' as AccessControl,
+          accessControl: 'secureEnclaveBiometry' as AccessControl,
           migratedFromV5: false,
         },
       };
@@ -420,15 +420,15 @@ describe('SensitiveInfo API - Complete Coverage', () => {
       const code = async () => {
         // const secret = await SensitiveInfo.getItem('password', {
         //   keychainService: 'myapp',
-        //   accessControl: 'biometryOrDevicePasscode',
+        //   accessControl: 'secureEnclaveBiometry',
         //   prompt: {
         //     title: 'Unlock Your Account',
         //     subtitle: 'Authenticate with Face ID or Touch ID'
         //   }
         // });
         return {
           keychainService: 'myapp',
-          accessControl: 'biometryOrDevicePasscode' as const,
+          accessControl: 'secureEnclaveBiometry' as const,
           prompt: {
             title: 'Unlock Your Account',
             subtitle: 'Authenticate with Face ID or Touch ID',
@@ -438,7 +438,7 @@ describe('SensitiveInfo API - Complete Coverage', () => {
 
       const result = await code();
       expect(result.keychainService).toBe('myapp');
-      expect(result.accessControl).toBe('biometryOrDevicePasscode');
+      expect(result.accessControl).toBe('secureEnclaveBiometry');
     });
 
     it('Example 3: Detect capabilities', async () => {

__tests__/index.test.ts

@@ -6,6 +6,7 @@
  * on real devices/simulators.
  */
 
+import type { AccessControl, SecurityLevel } from '../src/index';
 import {
   SensitiveInfo,
   SensitiveInfoError,
@@ -56,7 +57,7 @@ describe('SensitiveInfo API', () => {
     it('should accept valid setItem options', () => {
       const options = {
         keychainService: 'com.example.app',
-        accessControl: 'biometryOrDevicePasscode' as const,
+        accessControl: 'secureEnclaveBiometry' as const,
       };
       expect(options.keychainService).toBe('com.example.app');
     });
@@ -73,28 +74,28 @@ describe('SensitiveInfo API', () => {
     });
 
     it('should support all access control types', () => {
-      const controls = [
-        'devicePasscode' as const,
-        'biometryOrDevicePasscode' as const,
-        'biometryAndDevicePasscode' as const,
-        'biometryCurrentSet' as const,
+      const controls: AccessControl[] = [
+        'secureEnclaveBiometry',
+        'biometryCurrentSet',
+        'biometryAny',
+        'devicePasscode',
+        'none',
       ];
 
-      expect(controls).toHaveLength(4);
+      expect(controls).toHaveLength(5);
       expect(controls.every((c) => typeof c === 'string')).toBe(true);
     });
 
     it('should support all security levels', () => {
-      const levels = [
+      const levels: SecurityLevel[] = [
         'secureEnclave',
         'strongBox',
-        'hardwareBacked',
-        'biometricProtected',
-        'passcodeProtected',
+        'biometry',
+        'deviceCredential',
         'software',
       ];
 
-      expect(levels).toHaveLength(6);
+      expect(levels).toHaveLength(5);
     });
   });
 
@@ -181,7 +182,7 @@ describe('SensitiveInfo API', () => {
       const expectedCode = async () => {
         const options = {
           keychainService: 'com.myapp',
-          accessControl: 'biometryOrDevicePasscode' as const,
+          accessControl: 'secureEnclaveBiometry' as const,
           prompt: {
             title: 'Authenticate',
             subtitle: 'Verify your identity',
@@ -192,7 +193,7 @@ describe('SensitiveInfo API', () => {
       };
 
       const result = await expectedCode();
-      expect(result.accessControl).toBe('biometryOrDevicePasscode');
+      expect(result.accessControl).toBe('secureEnclaveBiometry');
       expect(result.prompt.title).toBe('Authenticate');
     });
 

android/build.gradle

@@ -72,16 +72,51 @@ repositories {
 def kotlin_version = getExtOrDefault("kotlinVersion")
 
 dependencies {
+  // React Native - Core library for bridging JavaScript and Native code
+  // Version: From parent gradle configuration
+  // Purpose: React Native bridge, component registry, etc.
   implementation "com.facebook.react:react-android"
+  
+  // Kotlin Standard Library - Runtime for Kotlin code
+  // Version: Configured in project gradle.properties
+  // Purpose: Core Kotlin stdlib functions, collections, etc.
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 
-  // Biometric authentication (Face ID, Fingerprint, etc)
+  // AndroidX Biometric - Modern biometric authentication API
+  // Version: 1.1.0 (stable)
+  // Purpose: Face ID, Fingerprint, Iris recognition
+  // Minimum API: 14 (works on API 28+)
+  // Docs: https://developer.android.com/reference/androidx/biometric/BiometricPrompt
+  // Security: Handles authentication state, error codes, callbacks
+  // Performance: Async-first design, non-blocking UI
+  // Features:
+  //  - BiometricPrompt: System-level biometric UI
+  //  - BiometricManager: Check device capabilities
+  //  - Device credential fallback (PIN/Pattern/Password)
+  //  - Biometric template invalidation tracking
+  //  - Crypto object wrapping for cipher authentication
   implementation "androidx.biometric:biometric:1.1.0"
 
-  // Fragment support (required by BiometricPrompt)
+  // AndroidX Fragment - Lifecycle-aware fragments for BiometricPrompt
+  // Version: 1.6.2 (stable)
+  // Purpose: FragmentActivity support for BiometricPrompt UI rendering
+  // Why needed: BiometricPrompt requires FragmentActivity context
+  // Performance: Lightweight, no overhead if not using fragments directly
+  // Security: Integrates with fragment lifecycle for proper cleanup
   implementation "androidx.fragment:fragment-ktx:1.6.2"
 
-  // Coroutines support for suspend functions
+  // Kotlin Coroutines - Async/suspend functions for non-blocking operations
+  // Core library (1.7.3):
+  //  - Purpose: Suspend functions, async context switching
+  //  - Security: Thread-safe continuation handling
+  //  - Performance: Efficient, minimal allocations vs callbacks
+  // Android library (1.7.3):
+  //  - Purpose: Dispatcher.Main for UI operations
+  //  - Performance: Integrates with main thread event loop
+  //  - Usage in this library: All setItem/getItem are suspend functions
+  // Example:
+  //  suspend fun setItem(...): StorageResult
+  //  // Called from coroutineScope.launch { setItem(...) }
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
 }