@onekeyfe/react-native-check-biometric-auth-changed 3.0.179 → 6.7.0-1

package/README.md

@@ -29,14 +29,16 @@ if (changed) {
 
 - iOS reads LocalAuthentication's evaluated policy domain state and compares it
   with the previous value stored in Keychain. A check with available state
-  stores that state as the baseline for subsequent calls.
+  successfully saves that state as the baseline before resolving the current call.
 - The first available state establishes a baseline unless legacy stored state
-  exists. A missing current domain state returns `false`.
+  exists. Missing current domain state or failed Keychain reads/writes reject.
+  Only `errSecItemNotFound` means an absent stored baseline; legacy state is
+  deleted only after the new baseline has been saved successfully.
 - Android currently returns `false` from a stub implementation. It does not
   detect enrollment changes.
 
 A `false` result is not proof that biometrics are available or that the user has
-authenticated: it can also mean no comparison was possible. This API does not
+authenticated: on iOS it can also mean a first baseline was established. This API does not
 replace an authentication challenge, and has no Web implementation.
 
 The wrapper is in [src/index.tsx](src/index.tsx); its native interface is
@@ -44,6 +46,40 @@ The wrapper is in [src/index.tsx](src/index.tsx); its native interface is
 Review the platform sources when integrating this signal into an authentication
 workflow.
 
+## Interpreting repeated checks
+
+`checkBiometricAuthChanged()` returns only a boolean: there is no enrollment
+count, authentication credential or event subscription in this API. On iOS the
+check persists an available comparison baseline before resolving. A process-wide
+synchronous transaction lock serializes checks on the native background queue;
+callers still own authentication and UI policy.
+
+A changed result is consumed by that baseline update. Persist a checkpoint before
+checking, and retain it if the application cannot finish disabling biometrics.
+After an interrupted check, require password/passcode recovery rather than
+trusting a fresh `false`; see the transaction requirements in the contract.
+
+Handle native-operation rejection separately from a resolved `false`. Neither
+an Android stub result nor an iOS rejection establishes that enrollment
+has remained unchanged. Applications must handle rejection as unavailable, rather
+than substituting `false`. See [the contract](docs/SPEC.md) for error and migration
+boundaries. These iOS changes require a new SDK release and an application rebuild. The package exports the Nitro interface as a type for
+adapters; the public JavaScript call remains `checkBiometricAuthChanged()`.
+
 ## License
 
 MIT.
+
+## Focused state tests
+
+From this package directory in a repository source checkout on macOS with the
+Xcode command-line tools, run the actual state transaction core
+with deterministic provider failures (without accessing a real Keychain):
+
+```sh
+xcrun swiftc ios/BiometricAuthStateStore.swift tests/BiometricAuthStateStoreTests.swift -o /tmp/biometric-state-tests
+/tmp/biometric-state-tests
+```
+
+The runner checks eleven scenarios, including concurrent transactions. It does not
+replace device enrollment, locked-Keychain or native bridge acceptance tests.

package/docs/SPEC.md

@@ -0,0 +1,87 @@
+# Biometric authentication state contract
+
+Status: Implemented. Eleven deterministic Swift core scenarios and the iOS Simulator
+module build pass; real device Keychain/LocalAuthentication acceptance is pending.
+
+## Purpose and ownership
+
+`checkBiometricAuthChanged(): Promise<boolean>` compares the current iOS
+LocalAuthentication domain state with a saved comparison baseline. The application
+owns authentication challenges and the security policy applied to the result.
+The package neither authenticates a user nor authorizes a password operation.
+The Keychain baseline is shared within the native process, including independent
+JavaScript runtimes. It is not a JavaScript-runtime-local store.
+
+## API and platform behavior
+
+- iOS resolves `true` when a previous Keychain or legacy baseline differs from
+  the current domain state, and `false` when it matches or when a first baseline
+  is successfully established. Every successful comparison persists the current
+  state as the next baseline before resolving.
+- `false` is not proof of authentication or biometric availability. Callers MUST
+  distinguish promise rejection from a resolved `false` and MUST NOT continue a
+  biometric-only path when the state check is unavailable.
+- Android retains its existing stub: it resolves `false`, does not persist a
+  baseline and does not detect enrollment changes. Web is unsupported.
+- No new JavaScript return type, event or configuration API is introduced.
+
+## Transaction, migration and concurrency
+
+A synchronous process-wide lock serializes the complete iOS operation: obtain
+current state, read the saved state, compare and persist. Work runs through Nitro `Promise.parallel` on its default global dispatch queue,
+not on the UI thread or an inherited Swift task executor. Lock release is required on every exit.
+The opaque domain state is neither returned to JavaScript nor logged.
+
+The comparison is consumptive: after a changed result advances the baseline,
+the same state returns `false` on a subsequent check. Application-side handling
+is a separate transaction. Before invoking this API, a security-sensitive caller
+must durably checkpoint that a check is in progress, serialize its check and
+settings update, and clear the checkpoint only after an unchanged result or
+successful handling of a changed result. A failed or interrupted operation must
+remain blocked across UI remounts and process restarts until password/passcode
+verification resolves the uncertainty. JavaScript component state alone is
+insufficient; independent runtimes share the native baseline, not their heaps.
+This caller requirement does not change the SDK boolean API or baseline behavior.
+
+Only `errSecItemNotFound` means the Keychain baseline is absent. In that case,
+legacy `UserDefaults["biometricAuthState"]` participates in the comparison.
+The legacy value is removed only after current-state persistence succeeds;
+read/write failure MUST leave it intact. A first-use result can resolve `false`
+only after persistence succeeds. Updating the Keychain item may fall back to add
+only on `errSecItemNotFound`; other update errors MUST NOT attempt an add.
+
+## Failure and safety
+
+A missing current domain state, a Keychain read failure, successful read with
+non-Data result, update failure or add failure rejects the promise. These cases
+MUST NOT silently become an absent baseline or a resolved `false`. Keychain
+failures include operation and OSStatus in the error message, without state data;
+errors use the `BiometricAuthChanged` NSError domain. Unavailable current state
+uses code 1; malformed successful reads use `errSecDecode`; Keychain operations
+retain their OSStatus code. Native error transport need not expose NSError fields
+as stable JavaScript properties.
+
+Changing this failure contract does not add enrollment notification, cancellation,
+late-loading recovery, or a new biometric prompt. Consumers can keep password or
+passcode authentication available when the state check fails. Already-published
+3.0.165 artifacts remain unchanged; the new native contract takes effect only
+when the SDK is published, upgraded and rebuilt by the application.
+
+## Conformance and acceptance
+
+The iOS wrapper owns LocalAuthentication and Security calls. A small state core
+uses injected current-state, Keychain and legacy operations so deterministic Swift
+executable tests exercise the actual transaction and error handling without
+altering a user's Keychain. Checks cover read errors/type mismatch, nil state,
+update/add failures, successful absent baseline, changed/unchanged comparisons,
+legacy preservation/removal and serialized concurrent checks.
+
+A real package build and tarball must contain the core and this spec, preserve the
+Nitro boolean signature, and resolve the existing native module name. App tests
+must prove that rejection blocks automatic, manual and foreground biometric
+attempts while password entry remains available, without falsely disabling the
+persistent biometric switch or showing an enrollment-change warning.
+
+Actual iOS device Keychain/LocalAuthentication behavior, protected-data states,
+biometric enrollment changes and App authentication UI remain runtime acceptance
+requirements; deterministic injected-operation tests do not establish those.

package/ios/BiometricAuthStateStore.swift

@@ -0,0 +1,57 @@
+import Foundation
+import Security
+
+enum BiometricAuthStateStore {
+  private static let transactionLock = NSLock()
+
+  static func check(
+    currentState: () -> Data?,
+    read: () -> (OSStatus, AnyObject?),
+    update: (Data) -> OSStatus,
+    add: (Data) -> OSStatus,
+    legacyState: () -> Data?,
+    removeLegacyState: () -> Void
+  ) throws -> Bool {
+    transactionLock.lock()
+    defer { transactionLock.unlock() }
+
+    guard let current = currentState() else {
+      throw failure("Current biometric domain state is unavailable", status: 1)
+    }
+    let (readStatus, result) = read()
+    let previous: Data?
+    let migrating: Bool
+    switch readStatus {
+    case errSecSuccess:
+      guard let data = result as? Data else {
+        throw failure("Keychain read returned invalid data", status: errSecDecode)
+      }
+      previous = data
+      migrating = false
+    case errSecItemNotFound:
+      previous = legacyState()
+      migrating = previous != nil
+    default:
+      throw failure("Keychain read failed", status: readStatus)
+    }
+
+    let updateStatus = update(current)
+    if updateStatus == errSecItemNotFound {
+      let addStatus = add(current)
+      guard addStatus == errSecSuccess else {
+        throw failure("Keychain add failed", status: addStatus)
+      }
+    } else if updateStatus != errSecSuccess {
+      throw failure("Keychain update failed", status: updateStatus)
+    }
+    if migrating { removeLegacyState() }
+    return previous.map { $0 != current } ?? false
+  }
+
+  private static func failure(_ message: String, status: OSStatus) -> NSError {
+    NSError(
+      domain: "BiometricAuthChanged", code: Int(status),
+      userInfo: [NSLocalizedDescriptionKey: "\(message) (OSStatus \(status))"]
+    )
+  }
+}

package/ios/ReactNativeCheckBiometricAuthChanged.swift

@@ -1,74 +1,46 @@
-
 import NitroModules
 import LocalAuthentication
 import Security
-import ReactNativeNativeLogger
 
 class ReactNativeCheckBiometricAuthChanged: HybridReactNativeCheckBiometricAuthChangedSpec {
-
   private static let keychainKey = "com.onekey.biometricAuthState"
-
-  private static func loadDomainState() -> Data? {
-    let query: [String: Any] = [
+  private static var identityQuery: [String: Any] {
+    [
       kSecClass as String: kSecClassGenericPassword,
       kSecAttrAccount as String: keychainKey,
-      kSecReturnData as String: true,
-      kSecMatchLimit as String: kSecMatchLimitOne
     ]
-    var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
-    if status == errSecSuccess {
-      return result as? Data
-    }
-    return nil
-  }
-
-  private static func saveDomainState(_ data: Data?) {
-    guard let data = data else { return }
-    let query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrAccount as String: keychainKey,
-      kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-    ]
-    let attrs: [String: Any] = [
-      kSecValueData as String: data
-    ]
-    let status = SecItemUpdate(query as CFDictionary, attrs as CFDictionary)
-    if status == errSecItemNotFound {
-      var addQuery = query
-      addQuery[kSecValueData as String] = data
-      SecItemAdd(addQuery as CFDictionary, nil)
-    }
   }
 
   func checkChanged() throws -> Promise<Bool> {
-    return Promise.async {
-      var changed = false
-      let context = LAContext()
-      _ = context.canEvaluatePolicy(.deviceOwnerAuthentication, error: nil)
-      let domainState = context.evaluatedPolicyDomainState
-      if domainState == nil {
-          OneKeyLog.warn("Biometric", "evaluatedPolicyDomainState is nil, cannot determine biometric changes")
-          return false
-      }
-      let oldDomainState = Self.loadDomainState()
-      if let oldDomainState = oldDomainState {
-          changed = oldDomainState != domainState
-      } else {
-          // Migrate from UserDefaults if exists
-          let defaults = UserDefaults.standard
-          if let legacyState = defaults.data(forKey: "biometricAuthState") {
-              changed = legacyState != domainState
-              defaults.removeObject(forKey: "biometricAuthState")
-          } else {
-              OneKeyLog.info("Biometric", "No previous biometric state stored, saving initial state")
-          }
-      }
-      Self.saveDomainState(domainState)
-      if changed {
-          OneKeyLog.info("Biometric", "Biometric auth change detected")
-      }
-      return changed
+    Promise.parallel {
+      let defaults = UserDefaults.standard
+      return try BiometricAuthStateStore.check(
+        currentState: {
+          let context = LAContext()
+          _ = context.canEvaluatePolicy(.deviceOwnerAuthentication, error: nil)
+          return context.evaluatedPolicyDomainState
+        },
+        read: {
+          var query = Self.identityQuery
+          query[kSecReturnData as String] = true
+          query[kSecMatchLimit as String] = kSecMatchLimitOne
+          var result: AnyObject?
+          let status = SecItemCopyMatching(query as CFDictionary, &result)
+          return (status, result)
+        },
+        update: { data in
+          let attributes: [String: Any] = [kSecValueData as String: data]
+          return SecItemUpdate(Self.identityQuery as CFDictionary, attributes as CFDictionary)
+        },
+        add: { data in
+          var query = Self.identityQuery
+          query[kSecAttrAccessible as String] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+          query[kSecValueData as String] = data
+          return SecItemAdd(query as CFDictionary, nil)
+        },
+        legacyState: { defaults.data(forKey: "biometricAuthState") },
+        removeLegacyState: { defaults.removeObject(forKey: "biometricAuthState") }
+      )
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-check-biometric-auth-changed",
-  "version": "3.0.179",
+  "version": "6.7.0-1",
   "description": "Detect stored biometric authentication state changes on iOS",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -19,6 +19,7 @@
     "ios",
     "cpp",
     "nitrogen",
+    "docs",
     "nitro.json",
     "*.podspec",
     "react-native.config.js",