feat: add Passkey.getImmediate for silent credential checks

Adds support for silent / opportunistic passkey checks via a new
`Passkey.getImmediate(request)` API that returns a `NoCredentials`
error without showing the system modal when no credential is
available on the device.

- iOS 16+: uses `ASAuthorizationController.preferImmediatelyAvailableCredentials`
- Android: passes `preferImmediatelyAvailableCredentials = true` on `GetCredentialRequest`
- iOS < 16: falls back to a regular `get()` (no native silent support)

Also tightens native error surfacing and Android null-safety:

- iOS: maps `ASAuthorizationError` code 1005 to a new `NoCredentials` case.
- Android: maps `androidx.credentials.exceptions.domerrors.*` to the existing
  cross-platform error codes via a new `mapDomError` helper, replacing the
  raw error message that previously leaked through. Adds `InvalidStateError ->
  CredentialAlreadyExists` and explicit handling of `TimeoutError`,
  `NotSupportedError`, etc.
- Android: returns `RequestFailed` / `UnknownError` instead of silently
  resolving with `null` when there is no foreground activity or the native
  bundle response is missing.

Updates README with usage docs for `getImmediate` and a normalised
error-code reference table.

Closes #91

Author: plgrazon

README.md

@@ -153,6 +153,58 @@ try {
 }
 ```
 
+#### Silent / Immediate Authentication
+
+Use `Passkey.getImmediate()` to authenticate **only** when a credential is
+already available on the device, without surfacing the system modal when
+nothing matches. This is useful for opportunistic sign-in checks (e.g. on app
+launch or on a sign-in screen) where you do not want to interrupt the user
+with a credential picker if no passkey exists.
+
+- iOS 16+: uses `ASAuthorizationController.preferImmediatelyAvailableCredentials`
+- Android: uses the `preferImmediatelyAvailableCredentials` flag on
+  `GetCredentialRequest` (Credential Manager)
+- iOS < 16: falls back to a normal `get()` request (no silent behaviour
+  available on the platform)
+
+When no credential is available the call rejects with a `NoCredentials` error
+and no UI is shown. Handle this error to fall back to your usual sign-in flow.
+
+```ts
+import { Passkey } from 'react-native-passkey';
+
+try {
+  const result = await Passkey.getImmediate(requestJson);
+  // Credential available — pass to your server
+} catch (error) {
+  if (error.error === 'NoCredentials') {
+    // No passkey on device — fall back to password / OTP / etc.
+  } else if (error.error === 'UserCancelled') {
+    // User dismissed the sheet
+  } else {
+    // Handle other errors
+  }
+}
+```
+
+#### Error codes
+
+The library normalises native error codes into the following set:
+
+| `error` value        | Meaning                                                                |
+| -------------------- | ---------------------------------------------------------------------- |
+| `NotSupported`       | Passkeys are not supported on this device / OS version                 |
+| `RequestFailed`      | Generic request failure (e.g. transport / network / invalid response)  |
+| `UserCancelled`      | User dismissed the system sheet                                        |
+| `InvalidChallenge`   | The provided challenge could not be decoded                            |
+| `InvalidUserId`      | The provided user id could not be decoded (registration only)          |
+| `BadConfiguration`   | App is not configured correctly (associated domain / asset links)      |
+| `NoCredentials`      | No credential is available — also returned for silent `getImmediate()` |
+| `CredentialAlreadyExists` | A passkey already exists for this account on this device (registration) |
+| `Interrupted`        | The operation was interrupted and may be retried                       |
+| `TimedOut`           | The operation timed out                                                |
+| `UnknownError`       | Unknown / unmapped error                                               |
+
 ### Force Platform or Security Key (iOS-specific)
 
 You can force users to register and authenticate using either a platform key, a security key (like [Yubikey](https://www.yubico.com/)) or allow both using the following methods. This only works on iOS, Android will ignore these instructions.

android/src/main/java/com/reactnativepasskey/PasskeyModule.kt

@@ -10,7 +10,7 @@ import androidx.credentials.CreatePublicKeyCredentialRequest
 import androidx.credentials.GetCredentialRequest
 import androidx.credentials.GetPublicKeyCredentialOption
 import androidx.credentials.exceptions.*
-import androidx.credentials.exceptions.domerrors.InvalidStateError
+import androidx.credentials.exceptions.domerrors.*
 import androidx.credentials.exceptions.publickeycredential.CreatePublicKeyCredentialDomException
 import androidx.credentials.exceptions.publickeycredential.GetPublicKeyCredentialDomException
 
@@ -32,10 +32,14 @@ class PasskeyModule(reactContext: ReactApplicationContext) : ReactContextBaseJav
 
     mainScope.launch {
       try {
-        val result = reactApplicationContext.currentActivity?.let { credentialManager.createCredential(it, createPublicKeyCredentialRequest) }
+        val activity = reactApplicationContext.currentActivity
+          ?: run { promise.reject("RequestFailed", "No active Activity"); return@launch }
+
+        val result = credentialManager.createCredential(activity, createPublicKeyCredentialRequest)
 
         val response =
-          result?.data?.getString("androidx.credentials.BUNDLE_KEY_REGISTRATION_RESPONSE_JSON")
+          result.data.getString("androidx.credentials.BUNDLE_KEY_REGISTRATION_RESPONSE_JSON")
+            ?: run { promise.reject("UnknownError", "Empty credential response"); return@launch }
         promise.resolve(response)
       } catch (e: CreateCredentialException) {
         val errorCode = handleRegistrationException(e)
@@ -48,14 +52,7 @@ class PasskeyModule(reactContext: ReactApplicationContext) : ReactContextBaseJav
     e.printStackTrace()
     when (e) {
       is CreatePublicKeyCredentialDomException -> {
-        val msg = e.errorMessage?.toString().orEmpty()
-        val isExcludedMatch = e.domError is InvalidStateError &&
-          msg.contains("excluded credential", ignoreCase = true)
-
-        if (isExcludedMatch) {
-          return "CredentialAlreadyExists"
-        }
-        return msg
+        return mapDomError(e.domError)
       }
       is CreateCredentialCancellationException -> {
         return "UserCancelled"
@@ -79,18 +76,24 @@ class PasskeyModule(reactContext: ReactApplicationContext) : ReactContextBaseJav
   }
 
   @ReactMethod
-  fun get(requestJson: String, forcePlatformKey: Boolean, forceSecurityKey: Boolean, promise: Promise) {
+  fun get(requestJson: String, forcePlatformKey: Boolean, forceSecurityKey: Boolean, preferImmediatelyAvailable: Boolean, promise: Promise) {
       val credentialManager = CredentialManager.create(reactApplicationContext.applicationContext)
       val getCredentialRequest =
-        GetCredentialRequest(listOf(GetPublicKeyCredentialOption(requestJson)))
+        GetCredentialRequest(
+          listOf(GetPublicKeyCredentialOption(requestJson)),
+          preferImmediatelyAvailableCredentials = preferImmediatelyAvailable
+        )
 
       mainScope.launch {
         try {
-          val result =
-            reactApplicationContext.currentActivity?.let { credentialManager.getCredential(it, getCredentialRequest) }
+          val activity = reactApplicationContext.currentActivity
+            ?: run { promise.reject("RequestFailed", "No active Activity"); return@launch }
+
+          val result = credentialManager.getCredential(activity, getCredentialRequest)
 
           val response =
-            result?.credential?.data?.getString("androidx.credentials.BUNDLE_KEY_AUTHENTICATION_RESPONSE_JSON")
+            result.credential.data.getString("androidx.credentials.BUNDLE_KEY_AUTHENTICATION_RESPONSE_JSON")
+              ?: run { promise.reject("UnknownError", "Empty credential response"); return@launch }
           promise.resolve(response)
         } catch (e: GetCredentialException) {
           val errorCode = handleAuthenticationException(e)
@@ -103,7 +106,7 @@ class PasskeyModule(reactContext: ReactApplicationContext) : ReactContextBaseJav
     e.printStackTrace()
     when (e) {
       is GetPublicKeyCredentialDomException -> {
-        return e.errorMessage.toString()
+        return mapDomError(e.domError)
       }
       is GetCredentialCancellationException -> {
         return "UserCancelled"
@@ -128,4 +131,18 @@ class PasskeyModule(reactContext: ReactApplicationContext) : ReactContextBaseJav
       }
     }
   }
+
+  private fun mapDomError(domError: DomError): String {
+    return when (domError) {
+      is InvalidStateError -> "CredentialAlreadyExists"
+      is SecurityError -> "RequestFailed"
+      is ConstraintError -> "BadConfiguration"
+      is NotAllowedError -> "RequestFailed"
+      is TimeoutError -> "TimedOut"
+      is AbortError -> "UserCancelled"
+      is DataError -> "RequestFailed"
+      is NotSupportedError -> "NotSupported"
+      else -> "UnknownError"
+    }
+  }
 }

ios/Passkey.m

@@ -12,6 +12,7 @@ @interface RCT_EXTERN_MODULE(Passkey, NSObject)
 RCT_EXTERN_METHOD(get:(NSString)request
                   withForcePlatformKey:(BOOL)forcePlatformKey
                   withForceSecurityKey:(BOOL)forceSecurityKey
+                  withPreferImmediatelyAvailable:(BOOL)preferImmediatelyAvailable
                   withResolver:(RCTPromiseResolveBlock)resolve
                   withRejecter:(RCTPromiseRejectBlock)reject);
 

ios/Passkey.swift

@@ -64,8 +64,8 @@ class Passkey: NSObject, RNPasskeyResultHandler {
   /**
    Main get entrypoint
    */
-  @objc(get:withForcePlatformKey:withForceSecurityKey:withResolver:withRejecter:)
-  func get(_ request: String, forcePlatformKey: Bool, forceSecurityKey: Bool, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) -> Void {
+  @objc(get:withForcePlatformKey:withForceSecurityKey:withPreferImmediatelyAvailable:withResolver:withRejecter:)
+  func get(_ request: String, forcePlatformKey: Bool, forceSecurityKey: Bool, preferImmediatelyAvailable: Bool, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) -> Void {
     do {
       passkeyHandler = RNPasskeyHandler(resolve, reject);
 
@@ -91,8 +91,8 @@ class Passkey: NSObject, RNPasskeyResultHandler {
       self.passkeyDelegate = passkeyDelegate;
 
       // Perform the authorization
-      passkeyDelegate.performAuthForController(controller: authController);
-      
+      passkeyDelegate.performAuthForController(controller: authController, preferImmediatelyAvailable: preferImmediatelyAvailable);
+
     } catch let error as NSError {
       reject(error.debugDescription, error.debugDescription, nil);
     }
@@ -302,6 +302,10 @@ class Passkey: NSObject, RNPasskeyResultHandler {
       return RNPasskeyError(type: .cancelled, message: error.localizedDescription);
       case 1004:
       return RNPasskeyError(type: .requestFailed, message: error.localizedDescription);
+      case 1005:
+      return RNPasskeyError(type: .noCredentials, message: error.localizedDescription);
+      case 1006:
+      return RNPasskeyError(type: .credentialAlreadyExists, message: error.localizedDescription);
       case 4004:
       return RNPasskeyError(type: .badConfiguration, message: error.localizedDescription);
       case 31:

ios/PasskeyDelegate.swift

@@ -19,10 +19,18 @@ class PasskeyDelegate: NSObject, ASAuthorizationControllerDelegate, ASAuthorizat
   }
 
   // Perform the authorization request for a given ASAuthorizationController instance
-  func performAuthForController(controller: ASAuthorizationController) {
+  func performAuthForController(controller: ASAuthorizationController, preferImmediatelyAvailable: Bool = false) {
     controller.delegate = self;
     controller.presentationContextProvider = self;
-    controller.performRequests();
+    if preferImmediatelyAvailable {
+      if #available(iOS 16.0, *) {
+        controller.performRequests(options: .preferImmediatelyAvailableCredentials);
+      } else {
+        controller.performRequests();
+      }
+    } else {
+      controller.performRequests();
+    }
   }
 
   func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {

ios/PasskeyErrors.swift

@@ -19,11 +19,13 @@ enum RNPasskeyErrorType: String {
   case badConfiguration = "BadConfiguration"
 
   case timedOut = "TimedOut"
-  
+
   case HandlerUndefined = "HandlerUndefined"
 
+  case noCredentials = "NoCredentials"
+
   case credentialAlreadyExists = "CredentialAlreadyExists"
 
   case unknown = "UnknownError"
-  
+
 }

src/Passkey.ts

@@ -128,7 +128,45 @@ export class Passkey {
       const response = await NativePasskey.get(
         stringifyPasskeyRequest(request, Platform.OS),
         false, // forcePlatformKey
-        false // forceSecurityKey
+        false, // forceSecurityKey
+        false // preferImmediatelyAvailable
+      );
+
+      if (typeof response === 'string') {
+        return JSON.parse(response) as PasskeyGetResult;
+      }
+      return response as PasskeyGetResult;
+    } catch (error: unknown) {
+      throw handleNativeError(error as TNativeError);
+    }
+  }
+
+  /**
+   * Authenticates using an existing Passkey, but only if a credential is
+   * immediately available on the device. On iOS 16+ this uses
+   * `ASAuthorizationController.preferImmediatelyAvailableCredentials` and on
+   * Android the `preferImmediatelyAvailableCredentials` flag of
+   * `GetCredentialRequest`. When no credential is available the request fails
+   * silently (no modal) with a `NoCredentials` error, making this suitable for
+   * silent / opportunistic checks.
+   *
+   * @param request The FIDO2 Assertion Request in JSON format
+   * @returns The FIDO2 Assertion Result in JSON format
+   * @throws
+   */
+  public static async getImmediate(
+    request: PasskeyGetRequest
+  ): Promise<PasskeyGetResult> {
+    if (!Passkey.isSupported()) {
+      throw NotSupportedError;
+    }
+
+    try {
+      const response = await NativePasskey.get(
+        stringifyPasskeyRequest(request, Platform.OS),
+        true, // forcePlatformKey (immediate is platform-only)
+        false, // forceSecurityKey
+        true // preferImmediatelyAvailable
       );
 
       if (typeof response === 'string') {
@@ -160,7 +198,8 @@ export class Passkey {
       const response = await NativePasskey.get(
         stringifyPasskeyRequest(request, Platform.OS),
         true, // forcePlatformKey
-        false // forceSecurityKey
+        false, // forceSecurityKey
+        false // preferImmediatelyAvailable
       );
 
       if (typeof response === 'string') {
@@ -192,7 +231,8 @@ export class Passkey {
       const response = await NativePasskey.get(
         stringifyPasskeyRequest(request, Platform.OS),
         false, // forcePlatformKey
-        true // forceSecurityKey
+        true, // forceSecurityKey
+        false // preferImmediatelyAvailable
       );
 
       if (typeof response === 'string') {

src/__tests__/PasskeyAndroid.spec.ts

@@ -1,6 +1,7 @@
 // @ts-ignore
 import { Platform, NativeModules } from 'react-native';
 import { Passkey } from '../Passkey';
+import { stringifyPasskeyRequest } from '../PasskeyRequest';
 import type { PasskeyCreateRequest, PasskeyGetRequest } from '../PasskeyTypes';
 
 import AuthRequestJson from './testData/AuthRequest.json';
@@ -80,4 +81,18 @@ describe('Test Passkey Module', () => {
     await Passkey.get(AuthRequest);
     expect(authSpy).toHaveBeenCalled();
   });
+
+  test('should call native auth method with preferImmediatelyAvailable for getImmediate', async () => {
+    const authSpy = jest
+      .spyOn(NativeModules.Passkey, 'get')
+      .mockResolvedValue(JSON.stringify(AuthAndroidResult));
+
+    await Passkey.getImmediate(AuthRequest);
+    expect(authSpy).toHaveBeenCalledWith(
+      stringifyPasskeyRequest(AuthRequest, 'android'),
+      true,
+      false,
+      true
+    );
+  });
 });

src/__tests__/PasskeyiOS.spec.ts

@@ -1,6 +1,7 @@
 // @ts-ignore
 import { Platform, NativeModules } from 'react-native';
 import { Passkey } from '../Passkey';
+import { stringifyPasskeyRequest } from '../PasskeyRequest';
 import type { PasskeyCreateRequest, PasskeyGetRequest } from '../PasskeyTypes';
 
 import AuthRequestJson from './testData/AuthRequest.json';
@@ -41,4 +42,18 @@ describe('Test Passkey Module', () => {
     await Passkey.get(AuthRequest);
     expect(authSpy).toHaveBeenCalled();
   });
+
+  test('should call native auth method with preferImmediatelyAvailable for getImmediate', async () => {
+    const authSpy = jest
+      .spyOn(NativeModules.Passkey, 'get')
+      .mockResolvedValue(AuthiOSResult);
+
+    await Passkey.getImmediate(AuthRequest);
+    expect(authSpy).toHaveBeenCalledWith(
+      stringifyPasskeyRequest(AuthRequest, 'ios'),
+      true,
+      false,
+      true
+    );
+  });
 });