Prevent duplicate iOS biometric prompts & silent reads

Avoid double Face ID / Touch ID prompts and keep metadata-only operations silent on iOS. Native Swift changes add an allowAuthentication flag, an itemExists fast-path, and set kSecUseAuthenticationUIFail for non-auth probes so hasItem and metadata enumeration never trigger authentication. JS API separates option normalization into storage-scope vs prompted-read helpers (normalizeStorageScopeOptions, normalizePromptedReadOptions) and updates core storage functions and hooks to only forward prompts when values are explicitly requested. Tests, docs, README and example iOS lockfile updated to reflect behavior and API clarifications.

Author: mCodex

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [6.1.3](https://github.com/mCodex/react-native-sensitive-info/compare/v6.1.2...v6.1.3) (2026-04-29)
 
+### Bug Fixes
+
+* **ios:** prevent duplicate biometric prompts on existence checks and prompted value reads
+
 ## [6.1.2](https://github.com/mCodex/react-native-sensitive-info/compare/v6.1.1...v6.1.2) (2026-04-29)
 
 ### 🛠️ Other changes

README.md

@@ -413,8 +413,8 @@ All functions live at the top level export and return Promises.
 ### 🧩 Options shared by all operations
 
 - `service` (default: bundle identifier or `default`) — logical namespace for secrets.
-- `accessControl` (default: `secureEnclaveBiometry`) — preferred policy; the native layer chooses the strongest supported fallback.
-- `authenticationPrompt` — localized strings for biometric/device credential prompts.
+- `accessControl` (default on writes: `secureEnclaveBiometry`) — preferred write policy; the native layer chooses the strongest supported fallback.
+- `authenticationPrompt` — localized strings for biometric/device credential prompts. Forwarded for value reads/writes, ignored by silent probes such as `hasItem`, `getKeyVersion`, and metadata-only `getAllItems`.
 - `iosSynchronizable` — enable iCloud Keychain sync.
 - `keychainGroup` — custom Keychain access group.
 

docs/ARCHITECTURE.md

@@ -64,3 +64,10 @@ or eagerly walks the existing entries when `reEncryptEagerly: true`.
 The package sets `"sideEffects": false` and ships ESM via subpath exports. Hooks live behind
 `react-native-sensitive-info/hooks` so apps that only use the imperative API never pay for the
 hook bundle. Errors are also re-exported from `/errors` for the same reason.
+
+## iOS prompt boundaries
+
+On iOS, Keychain queries against biometric-protected entries can authenticate even when callers
+only ask for attributes. The native layer keeps `hasItem` and metadata-only enumeration on a
+dedicated silent path, while value reads own an `LAContext` from the first `SecItemCopyMatching`
+attempt so one user action maps to one Face ID / Touch ID sheet.

example/ios/Podfile.lock

@@ -3,7 +3,7 @@ PODS:
   - hermes-engine (250829098.0.10):
     - hermes-engine/Pre-built (= 250829098.0.10)
   - hermes-engine/Pre-built (250829098.0.10)
-  - NitroModules (0.35.5):
+  - NitroModules (0.35.6):
     - hermes-engine
     - RCTRequired
     - RCTTypeSafety
@@ -1839,7 +1839,7 @@ PODS:
     - React-utils (= 0.85.2)
     - ReactNativeDependencies
   - ReactNativeDependencies (0.85.2)
-  - SensitiveInfo (6.0.0):
+  - SensitiveInfo (6.1.3):
     - hermes-engine
     - NitroModules
     - RCTRequired
@@ -2102,7 +2102,7 @@ EXTERNAL SOURCES:
 SPEC CHECKSUMS:
   FBLazyVector: 26fd21c75314e101f280d401e97f27d54f3f7064
   hermes-engine: 8d55ae9d2bb7d186d7e4b27fb3d197434d8a7d02
-  NitroModules: 8146b7b58cd5a478a21485fc2a0d542076f9f1ba
+  NitroModules: c41b7b778d6557f1e517a80ec681a670321fa001
   RCTDeprecation: c7a2768f905d76ca6d2cfefb26e4349eacbdfca3
   RCTRequired: 5e502c3553cfbed090a991c444448da452fb752e
   RCTSwiftUI: 5ce3ccbdc58b78cc4ebbaace01709ec22d58e131
@@ -2174,7 +2174,7 @@ SPEC CHECKSUMS:
   ReactCodegen: 75cd4d6498ab93ae4eed4d384b78383987e7558e
   ReactCommon: a804bb8d1dcf3ecdec3a77eb8bba19b7863bbbdb
   ReactNativeDependencies: 16dfbcfc63bf756df236d05cd69638f95019c528
-  SensitiveInfo: 83b9376b4a48bc310795daa351a64a5495c58b1b
+  SensitiveInfo: 6d078d9b88039d9316f58ae103c3c68900d22455
   Yoga: 04bb4bfeb02c0000b940c1e6e89e856cd8de5a71
 
 PODFILE CHECKSUM: 7ee3efea19ddd1156f9f61f93fc84a48ff536985

ios/HybridSensitiveInfo.swift

@@ -157,7 +157,11 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
         query[kSecReturnData as String] = kCFBooleanTrue
       }
 
-      guard let raw = try copyMatching(query: query, prompt: request.authenticationPrompt) as? NSDictionary else {
+      guard let raw = try copyMatching(
+        query: query,
+        prompt: includeValue ? request.authenticationPrompt : nil,
+        allowAuthentication: includeValue
+      ) as? NSDictionary else {
         return Variant_NullType_SensitiveInfoItem.first(NullType.null)
       }
 
@@ -196,17 +200,14 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
   public func hasItem(request: SensitiveInfoHasRequest) throws -> Promise<Bool> {
     Promise.parallel(workQueue) { [self] in
       let service = normalizedService(request.service)
-      var query = makeBaseQuery(
+      let query = makeBaseQuery(
         key: request.key,
         service: service,
         synchronizable: request.iosSynchronizable,
         accessGroup: request.keychainGroup
       )
-      query[kSecMatchLimit as String] = kSecMatchLimitOne
-      query[kSecReturnAttributes as String] = kCFBooleanTrue
 
-      let result = try copyMatching(query: query, prompt: request.authenticationPrompt)
-      return result != nil
+      return try itemExists(query: query)
     }
   }
 
@@ -232,7 +233,11 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
         query[kSecReturnData as String] = kCFBooleanTrue
       }
 
-      let result = try copyMatching(query: query, prompt: request?.authenticationPrompt)
+      let result = try copyMatching(
+        query: query,
+        prompt: includeValues ? request?.authenticationPrompt : nil,
+        allowAuthentication: includeValues
+      )
       guard let array = result as? [NSDictionary] else {
         return []
       }
@@ -368,18 +373,31 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
     SecItemDelete(deleteQuery as CFDictionary)
   }
 
-  private func copyMatching(query: [String: Any], prompt: AuthenticationPrompt?) throws -> AnyObject? {
+  private func copyMatching(
+    query: [String: Any],
+    prompt: AuthenticationPrompt?,
+    allowAuthentication: Bool = true
+  ) throws -> AnyObject? {
 #if targetEnvironment(simulator)
-    try performSimulatorBiometricPromptIfNeeded(prompt: prompt)
+    if allowAuthentication {
+      try performSimulatorBiometricPromptIfNeeded(prompt: prompt)
+    }
 #endif
+    var workingQuery = query
+    if !allowAuthentication {
+      workingQuery[kSecUseAuthenticationUI as String] = kSecUseAuthenticationUIFail
+    } else if let prompt {
+      workingQuery[kSecUseOperationPrompt as String] = prompt.title
+      workingQuery[kSecUseAuthenticationContext as String] = makeLAContext(prompt: prompt)
+    }
+
     var result: CFTypeRef?
-    var status = performCopyMatching(query as CFDictionary, result: &result)
+    var status = performCopyMatching(workingQuery as CFDictionary, result: &result)
 
-    if status == errSecInteractionNotAllowed || status == errSecAuthFailed {
-      var authQuery = query
-      authQuery[kSecUseOperationPrompt as String] = prompt?.title ?? "Authenticate to access sensitive data"
-      let context = makeLAContext(prompt: prompt)
-      authQuery[kSecUseAuthenticationContext as String] = context
+    if allowAuthentication && prompt == nil && (status == errSecInteractionNotAllowed || status == errSecAuthFailed) {
+      var authQuery = workingQuery
+      authQuery[kSecUseOperationPrompt as String] = "Authenticate to access sensitive data"
+      authQuery[kSecUseAuthenticationContext as String] = makeLAContext(prompt: nil)
       status = performCopyMatching(authQuery as CFDictionary, result: &result)
     }
 
@@ -388,11 +406,36 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
       return result as AnyObject?
     case errSecItemNotFound:
       return nil
+    case errSecInteractionNotAllowed, errSecAuthFailed:
+      if !allowAuthentication { return nil }
+      throw runtimeError(for: status, operation: "fetch")
     default:
       throw runtimeError(for: status, operation: "fetch")
     }
   }
 
+  private func itemExists(query: [String: Any]) throws -> Bool {
+    var existenceQuery = query
+    existenceQuery[kSecMatchLimit as String] = kSecMatchLimitOne
+    existenceQuery[kSecReturnData as String] = kCFBooleanFalse
+    existenceQuery[kSecReturnAttributes as String] = kCFBooleanFalse
+    existenceQuery[kSecUseAuthenticationUI as String] = kSecUseAuthenticationUIFail
+
+    var result: CFTypeRef?
+    let status = performCopyMatching(existenceQuery as CFDictionary, result: &result)
+
+    switch status {
+    case errSecSuccess:
+      return true
+    case errSecItemNotFound:
+      return false
+    case errSecInteractionNotAllowed, errSecAuthFailed:
+      return true
+    default:
+      throw runtimeError(for: status, operation: "existence check")
+    }
+  }
+
   private func makeItem(from dictionary: NSDictionary, includeValue: Bool) throws -> SensitiveInfoItem {
     guard
       let key = dictionary[kSecAttrAccount as String] as? String,

src/__tests__/core.storage.test.ts

@@ -29,6 +29,26 @@ describe('core/storage', () => {
 			service: 'normalized',
 			accessControl: 'secureEnclaveBiometry',
 		})
+	const normalizePromptedReadOptions = jest
+		.fn<
+			ReturnType<
+				typeof import('../internal/options').normalizePromptedReadOptions
+			>,
+			[SensitiveInfoOptions | undefined]
+		>()
+		.mockReturnValue({
+			service: 'normalized',
+		})
+	const normalizeStorageScopeOptions = jest
+		.fn<
+			ReturnType<
+				typeof import('../internal/options').normalizeStorageScopeOptions
+			>,
+			[SensitiveInfoOptions | undefined]
+		>()
+		.mockReturnValue({
+			service: 'normalized',
+		})
 
 	const isNotFoundError = jest.fn()
 
@@ -42,6 +62,8 @@ describe('core/storage', () => {
 
 		jest.doMock('../internal/options', () => ({
 			normalizeOptions,
+			normalizePromptedReadOptions,
+			normalizeStorageScopeOptions,
 		}))
 
 		jest.doMock('../internal/errors', () => ({
@@ -63,6 +85,14 @@ describe('core/storage', () => {
 			service: 'normalized',
 			accessControl: 'secureEnclaveBiometry',
 		})
+		normalizePromptedReadOptions.mockClear()
+		normalizePromptedReadOptions.mockReturnValue({
+			service: 'normalized',
+		})
+		normalizeStorageScopeOptions.mockClear()
+		normalizeStorageScopeOptions.mockReturnValue({
+			service: 'normalized',
+		})
 		isNotFoundError.mockReset()
 	})
 
@@ -92,7 +122,7 @@ describe('core/storage', () => {
 		const result = await getItem('token', { service: 'service' })
 
 		expect(result).toBeNull()
-		expect(normalizeOptions).toHaveBeenCalled()
+		expect(normalizePromptedReadOptions).toHaveBeenCalled()
 	})
 
 	it('rethrows unexpected errors during getItem', async () => {
@@ -116,7 +146,31 @@ describe('core/storage', () => {
 			key: 'token',
 			includeValue: true,
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
+		} as SensitiveInfoGetRequest)
+	})
+
+	it('keeps metadata-only getItem calls silent', async () => {
+		const { getItem } = await loadModule()
+
+		nativeHandle.getItem.mockResolvedValueOnce({ key: 'token' })
+		const prompt = { title: 'Authenticate' }
+
+		await getItem('token', {
+			service: 'service',
+			includeValue: false,
+			authenticationPrompt: prompt,
+		})
+
+		expect(normalizeStorageScopeOptions).toHaveBeenCalledWith({
+			service: 'service',
+			includeValue: false,
+			authenticationPrompt: prompt,
+		})
+		expect(normalizePromptedReadOptions).not.toHaveBeenCalled()
+		expect(nativeHandle.getItem).toHaveBeenCalledWith({
+			key: 'token',
+			includeValue: false,
+			service: 'normalized',
 		} as SensitiveInfoGetRequest)
 	})
 
@@ -186,7 +240,6 @@ describe('core/storage', () => {
 		expect(nativeHandle.hasItem).toHaveBeenCalledWith({
 			key: 'token',
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		} as SensitiveInfoHasRequest)
 	})
 
@@ -201,7 +254,6 @@ describe('core/storage', () => {
 		expect(nativeHandle.deleteItem).toHaveBeenCalledWith({
 			key: 'token',
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		} as SensitiveInfoDeleteRequest)
 	})
 
@@ -215,10 +267,29 @@ describe('core/storage', () => {
 		expect(nativeHandle.getAllItems).toHaveBeenCalledWith({
 			includeValues: true,
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		} as SensitiveInfoEnumerateRequest)
 	})
 
+	it('keeps metadata-only enumeration silent', async () => {
+		const { getAllItems } = await loadModule()
+
+		nativeHandle.getAllItems.mockResolvedValueOnce([])
+		const prompt = { title: 'Authenticate' }
+
+		await getAllItems({
+			service: 'service',
+			includeValues: false,
+			authenticationPrompt: prompt,
+		})
+
+		expect(normalizeStorageScopeOptions).toHaveBeenCalledWith({
+			service: 'service',
+			includeValues: false,
+			authenticationPrompt: prompt,
+		})
+		expect(normalizePromptedReadOptions).not.toHaveBeenCalled()
+	})
+
 	it('clears a service via native call', async () => {
 		const { clearService } = await loadModule()
 
@@ -228,7 +299,6 @@ describe('core/storage', () => {
 
 		expect(nativeHandle.clearService).toHaveBeenCalledWith({
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		})
 	})
 
@@ -284,7 +354,6 @@ describe('core/storage', () => {
 		expect(nativeHandle.rotateKeys).toHaveBeenCalledWith({
 			reEncryptEagerly: false,
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		})
 	})
 
@@ -324,7 +393,6 @@ describe('core/storage', () => {
 		await expect(getKeyVersion({ service: 'auth' })).resolves.toBe(4)
 		expect(nativeHandle.getKeyVersion).toHaveBeenCalledWith({
 			service: 'normalized',
-			accessControl: 'secureEnclaveBiometry',
 		})
 	})
 

src/__tests__/hooks.useHasSecret.test.tsx

@@ -34,6 +34,28 @@ describe('useHasSecret', () => {
 		expect(mockedHasItem).toHaveBeenCalledWith('token', { service: 'auth' })
 	})
 
+	it('keeps existence checks silent when prompt options are provided', async () => {
+		mockedHasItem.mockResolvedValueOnce(true)
+
+		renderHook(
+			({ opts }: { opts: Parameters<typeof useHasSecret>[1] }) =>
+				useHasSecret('token', opts),
+			{
+				initialProps: {
+					opts: {
+						service: 'auth',
+						accessControl: 'biometryCurrentSet',
+						authenticationPrompt: { title: 'Unlock' },
+					},
+				},
+			}
+		)
+
+		await waitFor(() => expect(mockedHasItem).toHaveBeenCalled())
+
+		expect(mockedHasItem).toHaveBeenCalledWith('token', { service: 'auth' })
+	})
+
 	it('skips querying when requested', async () => {
 		const { result } = renderHook(
 			({ opts }: { opts: Parameters<typeof useHasSecret>[1] }) =>