react-native-nitro-auth 0.5.4 → 0.5.6

package/README.md

@@ -71,11 +71,11 @@ bun add react-native-nitro-auth react-native-nitro-modules
 
 ### Requirements
 
-| Dependency                   | Version     |
-| ---------------------------- | ----------- |
-| `react-native`               | `>= 0.75.0` |
-| `react-native-nitro-modules` | `>= 0.33.9` |
-| `react`                      | `*`         |
+| Dependency                   | Version      |
+| ---------------------------- | ------------ |
+| `react-native`               | `>= 0.75.0`  |
+| `react-native-nitro-modules` | `>= 0.35.0`  |
+| `react`                      | `*`          |
 
 For Expo projects, rebuild native code after installation:
 
@@ -308,12 +308,13 @@ To enable Microsoft Sign-In, you need to register an application in the Azure Po
   - `nitro_auth_microsoft_client_id`
   - `nitro_auth_microsoft_tenant` (optional)
   - `nitro_auth_microsoft_b2c_domain` (optional)
-- Add the Microsoft redirect activity to `AndroidManifest.xml`:
+- `MicrosoftAuthActivity` is **automatically declared** by the library manifest — no manual `AndroidManifest.xml` entry is required for basic Microsoft OAuth redirect handling. If you need to customize the intent-filter (e.g., restrict the host/path to your specific package and client ID), you can override it in your app manifest:
 
 ```xml
 <activity
   android:name="com.auth.MicrosoftAuthActivity"
-  android:exported="true">
+  android:exported="true"
+  android:launchMode="singleTask">
   <intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
@@ -670,61 +671,73 @@ const freshToken = await AuthService.getAccessToken();
 
 ### Standardized Error Codes
 
-Handle failures reliably with predictable error strings. Some flows can surface provider-specific codes (listed below):
+All errors thrown by `AuthService` and `useAuth` are `AuthError` instances with a type-safe `code` field (always a valid `AuthErrorCode`) and an optional `underlyingMessage` with the raw provider string when it differs from the code.
 
 ```ts
+import { AuthError } from "react-native-nitro-auth";
+
 try {
   await login("google");
 } catch (e) {
-  const error = e as Error;
-  if (error.message === "cancelled") {
-    // User closed the popup/picker
-  } else if (error.message === "network_error") {
-    // Connection issues
+  if (e instanceof AuthError) {
+    switch (e.code) {
+      case "cancelled":
+        // User closed the popup/picker
+        break;
+      case "network_error":
+        // Connection issues
+        break;
+      default:
+        console.error(e.code, e.underlyingMessage);
+    }
   }
 }
 ```
 
-| Error Code             | Description                                    |
-| ---------------------- | ---------------------------------------------- |
-| `cancelled`            | The user cancelled the sign-in flow            |
-| `network_error`        | A network error occurred                       |
-| `configuration_error`  | Missing client IDs or invalid setup            |
-| `unsupported_provider` | The provider is not supported on this platform |
-| `invalid_state`        | PKCE state mismatch (possible CSRF)            |
-| `invalid_nonce`        | Nonce mismatch in token response               |
-| `token_error`          | Token exchange failed                          |
-| `no_id_token`          | No `id_token` in token response                |
-| `parse_error`          | Failed to parse token response                 |
-| `refresh_failed`       | Refresh token flow failed                      |
-| `unknown`              | An unknown error occurred                      |
+| Error Code             | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `cancelled`            | The user cancelled the sign-in flow or dismissed the popup      |
+| `timeout`              | The login popup/flow timed out                                  |
+| `popup_blocked`        | The browser blocked the popup window                            |
+| `network_error`        | A network or connectivity error occurred                        |
+| `configuration_error`  | Missing client IDs, invalid tenant, or misconfigured setup      |
+| `unsupported_provider` | The provider is not supported on this platform                  |
+| `invalid_state`        | PKCE state mismatch — possible CSRF attack                      |
+| `invalid_nonce`        | Nonce mismatch in token response — possible replay attack       |
+| `token_error`          | Token exchange or storage failed                                |
+| `no_id_token`          | No `id_token` in token response                                 |
+| `parse_error`          | Failed to parse token response                                  |
+| `refresh_failed`       | Refresh token flow failed (token may be expired or revoked)     |
+| `unknown`              | An unknown or unmapped error occurred                           |
 
 ### Native Error Metadata
 
-For more detailed debugging, Nitro Auth captures raw provider/native details in `underlyingError` where available:
+`AuthError` carries the raw provider/native message in `underlyingMessage` when the platform error didn't map to a known code:
 
 ```ts
-// From authenticated user (on success)
-const { user } = useAuth();
-if (user?.underlyingError) {
-  console.warn("Auth warning:", user.underlyingError);
-}
+import { AuthError } from "react-native-nitro-auth";
 
-// From error (on failure)
 try {
   await login("google");
 } catch (e) {
-  const error = e as Error & { underlyingError?: string };
-  console.log("Native error:", error.underlyingError);
+  if (e instanceof AuthError) {
+    // e.code is always a valid AuthErrorCode
+    // e.underlyingMessage is the original native string (or undefined if it equalled the code)
+    console.log(e.code, e.underlyingMessage);
+  }
 }
 ```
 
+The `AuthUser.underlyingError` field carries a raw warning string when the provider returns one alongside a successful result.
+
 ### Troubleshooting
 
-- `configuration_error`: verify client IDs, URL schemes, and redirect URIs are set for the current platform.
-- `invalid_state` or `invalid_nonce`: ensure the redirect URI in your provider console matches your app config exactly.
+- `configuration_error`: verify client IDs, URL schemes, and redirect URIs are set for the current platform. On Android, check that the `microsoftTenant` is a non-empty valid value.
+- `invalid_state` or `invalid_nonce`: ensure the redirect URI in your provider console matches your app config exactly. These indicate a potential CSRF or replay attack — do not retry silently.
+- `refresh_failed`: the refresh token is likely expired or revoked. Clear the session and prompt the user to sign in again. On Android and web, structured error details from the provider (e.g. `invalid_grant`) are surfaced via `error.underlyingMessage`.
 - `hasPlayServices` is false: prompt the user to install/update Google Play Services or disable One-Tap.
 - Apple web login fails: confirm `appleWebClientId` is set and your domain is registered with Apple.
+- Microsoft Android redirect hangs: confirm the `msauth://` redirect URI in your Azure app matches your package name and client ID.
 
 ### Automatic Token Refresh
 
@@ -797,6 +810,9 @@ This is useful for scenarios where:
 ```ts
 import {
   AuthService,
+  AuthError,
+  isAuthErrorCode,
+  toAuthErrorCode,
   SocialButton,
   useAuth,
   type UseAuthReturn,
@@ -869,7 +885,7 @@ declare function useAuth(): UseAuthReturn;
 | `user`            | `AuthUser \| undefined`                                             | Current in-memory user                               |
 | `scopes`          | `string[]`                                                          | Current granted scopes                               |
 | `loading`         | `boolean`                                                           | `true` while an auth operation is in-flight          |
-| `error`           | `Error \| undefined`                                                | Last operation error                                 |
+| `error`           | `AuthError \| undefined`                                            | Last operation error (typed, safe to switch on `.code`) |
 | `hasPlayServices` | `boolean`                                                           | Android Play Services availability                   |
 | `login`           | `(provider: AuthProvider, options?: LoginOptions) => Promise<void>` | Starts provider login                                |
 | `logout`          | `() => void`                                                        | Clears current session                               |
@@ -965,17 +981,36 @@ There is no public `setStorageAdapter`/`setJSStorageAdapter` API in this package
 | `nitroAuthWebStorage`         | `"session" \| "local" \| "memory"` | `"session"` | Storage for non-sensitive web cache                       |
 | `nitroAuthPersistTokensOnWeb` | `boolean`                          | `false`     | Persist sensitive tokens on web storage instead of memory |
 
-### Error semantics
+### `AuthError`
 
-Errors are surfaced as `Error` with `message` as a normalized code when possible, and `underlyingError` with provider/native details.
+All thrown errors from `AuthService` and `useAuth` are `AuthError` instances.
 
-| Normalized message    | Meaning                                        |
-| --------------------- | ---------------------------------------------- |
-| `cancelled`           | User cancelled popup/login flow                |
-| `timeout`             | Provider popup did not complete before timeout |
-| `popup_blocked`       | Browser blocked popup opening                  |
-| `network_error`       | Network failure                                |
-| `configuration_error` | Missing/invalid provider configuration         |
+```ts
+class AuthError extends Error {
+  readonly code: AuthErrorCode;           // Always a valid AuthErrorCode — safe to switch on
+  readonly underlyingMessage?: string;    // Raw native/platform string when it differs from code
+  static from(e: unknown): AuthError;     // Wraps any value; passes AuthError instances through
+}
+
+function isAuthErrorCode(value: string): value is AuthErrorCode;
+function toAuthErrorCode(raw: string): AuthErrorCode; // Returns "unknown" for unrecognized strings
+```
+
+| `code`                 | Meaning                                        |
+| ---------------------- | ---------------------------------------------- |
+| `cancelled`            | User cancelled the login flow                  |
+| `timeout`              | Provider popup did not complete before timeout |
+| `popup_blocked`        | Browser blocked popup opening                  |
+| `network_error`        | Network failure                                |
+| `configuration_error`  | Missing/invalid provider configuration         |
+| `unsupported_provider` | Provider not supported on this platform        |
+| `invalid_state`        | PKCE state mismatch (possible CSRF)            |
+| `invalid_nonce`        | Nonce mismatch in token response               |
+| `token_error`          | Token exchange failed                          |
+| `no_id_token`          | No `id_token` in token response                |
+| `parse_error`          | Failed to parse token response                 |
+| `refresh_failed`       | Refresh token flow failed                      |
+| `unknown`              | Unrecognized error                             |
 
 ## Quality Gates
 

package/android/proguard-rules.pro

@@ -1,4 +1,10 @@
 # Nitro Auth Proguard Rules
--keep class com.auth.** { *; }
+-keep class com.auth.AuthAdapter {
+    public static <methods>;
+}
+-keep class com.auth.MicrosoftAuthActivity { *; }
+-keep class com.auth.GoogleSignInActivity { *; }
+-keep class com.auth.NitroAuthModule { *; }
+-keep class com.auth.NitroAuthPackage { *; }
 -keep class com.margelo.nitro.com.auth.** { *; }
 -keep class com.google.android.gms.auth.api.signin.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -8,5 +8,17 @@
             android:name="com.auth.GoogleSignInActivity"
             android:theme="@android:style/Theme.Translucent.NoTitleBar"
             android:exported="false" />
+        <activity
+            android:name="com.auth.MicrosoftAuthActivity"
+            android:exported="true"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar"
+            android:launchMode="singleTask">
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="msauth" />
+            </intent-filter>
+        </activity>
     </application>
 </manifest>

package/android/src/main/cpp/JniOnLoad.cpp

@@ -4,5 +4,7 @@
 
 extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
   (void)reserved;
-  return margelo::nitro::NitroAuth::initialize(vm);
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::NitroAuth::registerAllNatives();
+  });
 }