npm - react-native-nitro-auth - Versions diffs - 0.5.7 → 0.5.8 - Mend

react-native-nitro-auth 0.5.7 → 0.5.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +288 -913
package/android/src/main/java/com/auth/AuthAdapter.kt +22 -6
package/cpp/HybridAuth.cpp +58 -7
package/cpp/HybridAuth.hpp +1 -0
package/ios/AuthAdapter.swift +2 -2
package/lib/commonjs/utils/auth-error.js +8 -1
package/lib/commonjs/utils/auth-error.js.map +1 -1
package/lib/module/utils/auth-error.js +8 -1
package/lib/module/utils/auth-error.js.map +1 -1
package/lib/typescript/commonjs/utils/auth-error.d.ts.map +1 -1
package/lib/typescript/module/utils/auth-error.d.ts.map +1 -1
package/package.json +7 -6
package/src/utils/auth-error.ts +10 -1

package/README.md CHANGED Viewed

@@ -1,213 +1,70 @@
 # react-native-nitro-auth
-[![npm version](https://img.shields.io/npm/v/react-native-nitro-auth?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-auth)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+Fast React Native authentication for Google Sign-In, Apple Sign-In, and Microsoft Entra ID, built on Nitro Modules and JSI.
-🚀 **High-performance, JSI-powered Authentication for React Native.**
+`react-native-nitro-auth` gives Expo and React Native apps one typed API for native social login, web OAuth, token refresh, incremental scopes, and auth state listeners without owning your app's long-term token storage.
-Nitro Auth is a modern authentication library for React Native built on top of [Nitro Modules](https://github.com/mrousavy/nitro). It provides a unified, type-safe API for Google, Apple, and Microsoft Sign-In with zero-bridge overhead.
+## Why Use It?
-## Why Nitro Auth?
+- One package for Google, Apple, and Microsoft authentication on React Native.
+- Native iOS and Android bridges powered by `react-native-nitro-modules`.
+- Expo config plugin for client IDs, URL schemes, entitlements, and Android resources.
+- Web implementation for Expo web with Google, Apple, and Microsoft OAuth.
+- Typed `useAuth()` hook, `AuthService`, `SocialButton`, and `AuthError`.
+- App-owned persistence model: tokens stay in memory unless your app stores a snapshot.
+- Built-in flows for silent restore, token refresh, account picker, login hints, and incremental Google scopes.
-Nitro Auth is designed to replace legacy modules like `@react-native-google-signin/google-signin` with a modern, high-performance architecture.
+## Choose Your Path
-| Feature           | Legacy Modules               | Nitro Auth                                                                     |
-| :---------------- | :--------------------------- | :----------------------------------------------------------------------------- |
-| **Performance**   | Async bridge overhead (JSON) | **Direct JSI C++ (Zero-copy)**                                                 |
-| **Storage**       | Varies / Hidden defaults     | **Native: in-memory only; Web: session cache (tokens memory-only by default)** |
-| **Setup**         | Manual async initialization  | **Sync & declarative plugins**                                                 |
-| **Types**         | Manual / Brittle             | **Fully Generated (Nitrogen)**                                                 |
-| **Provider Data** | Varies                       | **Normalized auth payload**                                                    |
+| Need | Use |
+| --- | --- |
+| Google, Apple, or Microsoft sign-in in an Expo or React Native app | `react-native-nitro-auth` |
+| Generic OAuth or OIDC provider not covered by this package | `expo-auth-session` or `react-native-app-auth` |
+| Firebase user management, password auth, MFA, and hosted auth platform | `@react-native-firebase/auth`, Auth0, Authgear, or your IDaaS SDK |
+| Server-side session validation | Your backend; client JWT decode is display-only |
-## Features
+## Install
-- **Ultra-fast**: Direct C++ calls using JSI (no JSON serialization).
-- **Fully Type-Safe**: Shared types between TypeScript, C++, Swift, and Kotlin.
-- **Incremental Auth**: Request additional OAuth scopes on the fly.
-- **Expo Ready**: Comes with a powerful Config Plugin for zero-config setup.
-- **Cross-Platform**: Unified API for iOS, Android, and Web.
-- **Token Lifecycle Helpers**: `getAccessToken()` refreshes near-expiry tokens; `refreshToken()` allows explicit refresh control.
-- **Google One-Tap / Sheet**: Modern login experience on Android (Credential Manager) and iOS (Sign-In Sheet).
-- **Error Metadata**: Detailed native error messages for easier debugging.
-- **Normalized Provider Payload**: Exposes provider/user/token fields in a consistent cross-platform shape.
-- **App-Owned Persistence**: Native is stateless by default. Web keeps a non-sensitive session snapshot; apps decide long-term persistence strategy.
-## Design Philosophy
-This is an **auth-only package** - on **native** (iOS/Android) it does NOT store auth data by default.
-On **web**, Nitro Auth stores a non-sensitive auth snapshot in `sessionStorage` by default; sensitive tokens stay memory-only unless explicitly enabled.
-The package provides:
-- Login/logout functionality for Google, Apple, and Microsoft
-- Token management (access token, refresh token, ID token)
-- Scope management (request/revoke scopes)
-- Consistent provider/user/token field exposure across iOS, Android, and Web
-**Storage is the responsibility of the app using this package.** Use your own storage layer (for example [react-native-nitro-storage](https://github.com/JoaoPauloCMarra/react-native-nitro-storage)) to persist app-level auth snapshots/tokens when needed.
-### Provider Data Availability
-Token/data shape is normalized, but provider SDKs do not always return all fields at login time:
-| Provider + Flow             | `idToken`  | `accessToken`                | `serverAuthCode`             | `expirationTime`                    |
-| --------------------------- | ---------- | ---------------------------- | ---------------------------- | ----------------------------------- |
-| Google (iOS)                | Usually ✅ | Provider-dependent           | Optional (if configured)     | Optional                            |
-| Google (Android One-Tap)    | ✅         | Usually `undefined` at login | `undefined`                  | Derived from ID token when possible |
-| Google (Android Legacy)     | ✅         | Usually `undefined` at login | ✅ (if server client is set) | Derived from ID token when possible |
-| Google (Web)                | ✅         | ✅                           | Optional (`code`)            | Usually ✅                          |
-| Microsoft (iOS/Android/Web) | ✅         | Usually ✅                   | `undefined`                  | Usually ✅                          |
-| Apple (iOS/Web)             | ✅         | `undefined`                  | `undefined`                  | `undefined`                         |
-> [!NOTE]
-> On Apple, email/name can be limited after first consent depending on Apple policy.
-## Installation
-```bash
+```sh
 bun add react-native-nitro-auth react-native-nitro-modules
 ```
-### Requirements
-| Dependency                   | Version      |
-| ---------------------------- | ------------ |
-| `react-native`               | `>= 0.75.0`  |
-| `react-native-nitro-modules` | `>= 0.35.0`  |
-| `react`                      | `*`          |
-For Expo projects, rebuild native code after installation:
+For Expo projects, prebuild after adding the config plugin:
-```bash
-bunx expo prebuild
+```sh
+bunx expo prebuild --clean
 ```
-### Testing locally (example app + Microsoft login)
-Fastest way to confirm the package and Microsoft login work:
-1. **Azure app (one-time)**
-   In [Azure Portal](https://portal.azure.com) → **Azure Active Directory** → **App registrations** → **New registration**:
-   - Name: e.g. `Nitro Auth Example`
-   - Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
-   - Redirect URI (add after creation):
-     - **Android**: `msauth://com.auth.example/<client-id>`
-     - **iOS**: `msauth.com.auth.example://auth` (use your bundle id)
-   - Under **Authentication** → **Platform configurations** → add **Mobile and desktop applications** with the Android redirect URI above and the iOS one if testing on iOS.
-     Copy the **Application (client) ID**.
-2. **Env file**
-   From the repo root:
-   ```bash
-   cd apps/example
-   cp .env.example .env.local
-   ```
-   Edit `.env.local` and set at least:
-   ```bash
-   MICROSOFT_CLIENT_ID=<your-application-client-id>
-   MICROSOFT_TENANT=common
-   ```
-   (Google/Apple can stay placeholder if you only care about Microsoft.)
-3. **Run the app**
-   From the **monorepo root**:
-   ```bash
-   bun install
-   bun run start
-   ```
-   In a second terminal:
-   ```bash
-   bun run example:android
-   # or
-   bun run example:ios
-   ```
-   Wait for the app to install and open.
+For bare React Native projects, install pods after installing the package:
-4. **Test Microsoft**
-   In the app, tap **Sign in with Microsoft**. A browser or in-app tab opens; sign in with a Microsoft/personal account, then you should return to the app with the user shown (email, name, provider MICROSOFT).
-   If you see "configuration_error", check `MICROSOFT_CLIENT_ID` and that the redirect URI in Azure matches your app (e.g. `msauth://com.auth.example/<client-id>` for the example app).
-> [!TIP]
-> In the example app on Android, you can toggle **Legacy Google Sign-In** to compare Credential Manager vs legacy GoogleSignIn (and to get `serverAuthCode`).
-### Expo Setup
-Add the plugin to `app.json` or `app.config.js`:
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "react-native-nitro-auth",
-        {
-          "ios": {
-            "googleClientId": "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com",
-            "googleServerClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-            "googleUrlScheme": "com.googleusercontent.apps.YOUR_IOS_CLIENT_ID",
-            "appleSignIn": true,
-            "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-            "microsoftTenant": "common",
-            "microsoftB2cDomain": "your-tenant.b2clogin.com"
-          },
-          "android": {
-            "googleClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-            "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-            "microsoftTenant": "common",
-            "microsoftB2cDomain": "your-tenant.b2clogin.com"
-          }
-        }
-      ]
-    ],
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-      "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-      "microsoftTenant": "common",
-      "microsoftB2cDomain": "your-tenant.b2clogin.com",
-      "appleWebClientId": "com.example.web"
-    }
-  }
-}
+```sh
+cd ios && pod install
 ```
-**Using environment variables (recommended):**
-Create a `.env.local` file:
+## Requirements
-```bash
-# iOS Client ID
-GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com
-GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.your-ios-client-id
-GOOGLE_SERVER_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
+| Runtime | Requirement |
+| --- | --- |
+| React Native | `>=0.75` |
+| Nitro Modules | `>=0.35` |
+| iOS | 15.1+ recommended |
+| Android | min SDK 24+ recommended |
+| Expo example baseline | Expo SDK 55, React Native 0.83, React 19 |
-# Web Client ID (used for Android OAuth flow)
-GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
+## Expo Setup
-# Microsoft/Azure AD (optional)
-MICROSOFT_CLIENT_ID=your-azure-ad-application-id
-MICROSOFT_TENANT=common
-MICROSOFT_B2C_DOMAIN=your-tenant.b2clogin.com
-# Apple (web only)
-APPLE_WEB_CLIENT_ID=com.example.web
-```
-Then reference them in `app.config.js`:
-```javascript
-import "dotenv/config";
+Add the plugin to `app.json` or `app.config.js`.
+```js
 export default {
   expo: {
+    scheme: "myapp",
+    ios: {
+      bundleIdentifier: "com.company.myapp",
+    },
+    android: {
+      package: "com.company.myapp",
+    },
     plugins: [
       [
         "react-native-nitro-auth",
@@ -232,841 +89,359 @@ export default {
     ],
     extra: {
       googleWebClientId: process.env.GOOGLE_WEB_CLIENT_ID,
+      appleWebClientId: process.env.APPLE_WEB_CLIENT_ID,
       microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
       microsoftTenant: process.env.MICROSOFT_TENANT,
       microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
-      appleWebClientId: process.env.APPLE_WEB_CLIENT_ID,
+      nitroAuthWebStorage: "memory",
+      nitroAuthPersistTokensOnWeb: false,
     },
   },
 };
 ```
-> [!NOTE]
->
-> - `appleSignIn` on iOS is `false` by default to avoid unnecessary entitlements. Set it to `true` to enable Apple Sign-In.
-> - For Android, use your **Web Client ID** (not Android Client ID) for proper OAuth flow.
-> - If you need `serverAuthCode`, set `googleServerClientId` to your Web Client ID.
-> - Add `googleWebClientId` to `expo.extra` for web platform support.
-> - The `serverAuthCode` is automatically included in `AuthUser` when available (requires backend integration setup in Google Cloud Console).
-> - For Microsoft Sign-In, use `common` tenant for multi-tenant apps, or specify your Azure AD tenant ID for single-tenant apps.
-> - For Azure AD B2C, set `microsoftB2cDomain` and pass the B2C tenant in `microsoftTenant`.
-### Google OAuth Setup
-1. Create OAuth client IDs in Google Cloud Console:
-   - **iOS client ID** (used by iOS)
-   - **Web client ID** (used by Android and for `serverAuthCode`)
-2. Configure your app:
-   - Expo: set `googleClientId`, `googleServerClientId`, and `googleUrlScheme`
-   - Bare iOS: add `GIDClientID`, `GIDServerClientID`, and URL scheme in `Info.plist`
-   - Bare Android: set `nitro_auth_google_client_id` to your **Web client ID**
-3. If you use `serverAuthCode`, make sure OAuth consent screen is configured in Google Cloud.
-### Apple Sign-In Setup
-1. **iOS**: enable the “Sign in with Apple” capability in Xcode and in your Apple Developer account.
-2. **Web**: create a Service ID and configure the domain + return URL in Apple Developer.
-3. Configure your app:
-   - Expo: set `appleSignIn: true` for iOS.
-   - Web: set `appleWebClientId` in `expo.extra` (or `.env`).
-### Microsoft Azure AD Setup
-To enable Microsoft Sign-In, you need to register an application in the Azure Portal:
-1. Go to [Azure Portal](https://portal.azure.com) > Azure Active Directory > App registrations
-2. Click "New registration"
-3. Set the redirect URIs:
-   - **iOS**: `msauth.{bundle-identifier}://auth` (e.g., `msauth.com.myapp://auth`)
-   - **Android**: `msauth://{package-name}/{client-id}` (e.g., `msauth://com.myapp/00000000-0000-0000-0000-000000000000`)
-   - **Web**: `https://your-domain.com` (the page that loads the app)
-4. Under "API permissions", add `openid`, `email`, `profile`, and `User.Read` (Microsoft Graph)
-5. Copy the Application (client) ID for use in your config
-**Tenant Options:**
-- `common` - Any Azure AD or personal Microsoft account
-- `organizations` - Any Azure AD account (work/school)
-- `consumers` - Personal Microsoft accounts only
-- `{tenant-id}` - Specific Azure AD tenant
-- **B2C**: set `microsoftB2cDomain` (e.g. `your-tenant.b2clogin.com`) and use a tenant value like `your-tenant.onmicrosoft.com/B2C_1_signin` (or pass a full `https://.../` authority URL).
-### Bare React Native
-**iOS**
-- Add to `Info.plist`: `GIDClientID`, `GIDServerClientID` (optional), `MSALClientID`, `MSALTenant` (optional), `MSALB2cDomain` (optional).
-- Add URL schemes in `Info.plist`:
-  - Google: `com.googleusercontent.apps.<YOUR_IOS_CLIENT_ID>`
-  - Microsoft: `msauth.<your.bundle.id>` (used for `msauth.<bundle.id>://auth`)
-- Enable the “Sign in with Apple” capability if you use Apple Sign-In.
-**Android**
-- Add string resources in `res/values/strings.xml`:
-  - `nitro_auth_google_client_id` (Web client ID)
-  - `nitro_auth_microsoft_client_id`
-  - `nitro_auth_microsoft_tenant` (optional)
-  - `nitro_auth_microsoft_b2c_domain` (optional)
-- `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: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"
-      android:host="${applicationId}"
-      android:path="/YOUR_MICROSOFT_CLIENT_ID" />
-  </intent-filter>
-</activity>
-```
-### Web Setup
-Nitro Auth reads web configuration from `expo.extra`:
-```json
-{
-  "expo": {
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-      "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-      "microsoftTenant": "common",
-      "microsoftB2cDomain": "your-tenant.b2clogin.com",
-      "appleWebClientId": "com.example.web",
-      "nitroAuthWebStorage": "session",
-      "nitroAuthPersistTokensOnWeb": false
-    }
-  }
-}
-```
-For Apple web sign-in, `appleWebClientId` must be your Apple Service ID. For Microsoft web, make sure your Azure app includes a Web redirect URI matching your site.
+### Plugin Options
-- `nitroAuthWebStorage`: `"session"` (default), `"local"`, or `"memory"`.
-- `nitroAuthPersistTokensOnWeb`: `false` by default (recommended). Set `true` only if you need cross-reload token persistence.
+| Option | Platform | Purpose |
+| --- | --- | --- |
+| `ios.googleClientId` | iOS | Google iOS OAuth client ID |
+| `ios.googleServerClientId` | iOS | Google web/server client ID for server auth code flows |
+| `ios.googleUrlScheme` | iOS | Reversed iOS client ID URL scheme |
+| `ios.appleSignIn` | iOS | Adds Apple Sign-In entitlement when `true` |
+| `ios.microsoftClientId` | iOS | Microsoft app/client ID |
+| `ios.microsoftTenant` | iOS | Microsoft tenant, `common`, `organizations`, `consumers`, or tenant ID |
+| `ios.microsoftB2cDomain` | iOS | Azure AD B2C domain |
+| `android.googleClientId` | Android | Google web OAuth client ID |
+| `android.microsoftClientId` | Android | Microsoft app/client ID |
+| `android.microsoftTenant` | Android | Microsoft tenant |
+| `android.microsoftB2cDomain` | Android | Azure AD B2C domain |
-## Quick Start
+## Provider Setup
-### Using the Hook
+### Google Sign-In
-```tsx
-import { useAuth, SocialButton } from "react-native-nitro-auth";
-function LoginScreen() {
-  const { user, loading, error, login, logout, hasPlayServices } = useAuth();
-  if (user) {
-    return (
-      <View>
-        <Image source={{ uri: user.photo }} />
-        <Text>{user.name}</Text>
-        <Button title="Sign Out" onPress={logout} />
-      </View>
-    );
-  }
+Create OAuth clients in Google Cloud Console:
-  return (
-    <View>
-      {error && <Text style={{ color: "red" }}>{error.message}</Text>}
-      {!hasPlayServices && <Text>Please install Google Play Services</Text>}
+- iOS client ID for your bundle identifier.
+- Web client ID for Android, web, and server auth code flows.
+- Android SHA-1/SHA-256 entries for local debug and release signing.
-      <SocialButton
-        provider="google"
-        onPress={() => login("google")}
-        disabled={loading || !hasPlayServices}
-      />
-      <SocialButton
-        provider="apple"
-        onPress={() => login("apple")}
-        disabled={loading}
-      />
-      <SocialButton
-        provider="microsoft"
-        onPress={() => login("microsoft")}
-        disabled={loading}
-      />
-    </View>
-  );
-}
-```
-### Microsoft Login Options
-```tsx
-// Login with specific tenant
-await login("microsoft", {
-  tenant: "your-tenant-id",
-  prompt: "select_account", // 'login' | 'consent' | 'select_account' | 'none'
-  scopes: ["openid", "email", "profile", "User.Read"],
-  loginHint: "user@example.com",
-});
-```
+Use the iOS reversed client ID as `GOOGLE_IOS_URL_SCHEME`.
-**B2C example:**
-```tsx
-await login("microsoft", {
-  tenant: "your-tenant.onmicrosoft.com/B2C_1_signin",
-  scopes: ["openid", "email", "profile", "offline_access"],
-});
-```
+### Apple Sign-In
-## Migration from @react-native-google-signin/google-signin
+Set `ios.appleSignIn: true` in the config plugin. Apple returns name and email only on the first authorization for a user. Store any profile fields you need in your own backend or app state.
-If you are using `@react-native-google-signin/google-signin`, the migration to Nitro Auth is mostly a drop-in at the API level, but the setup is different because Nitro Auth uses a config plugin and JSI.
+Apple Sign-In is supported on iOS and web. It is intentionally reported as `unsupported_provider` on Android.
-### 1) Replace the dependency
+### Microsoft Entra ID
-```bash
-bun remove @react-native-google-signin/google-signin
-bun add react-native-nitro-auth react-native-nitro-modules
-```
+Create an app registration in Microsoft Entra ID and add redirect URIs:
-### 2) Move configuration to the Nitro Auth plugin
+- iOS: `msauth.<bundleIdentifier>://auth`
+- Android: `msauth://<androidPackage>/<clientId>`
+- Web: your web origin, for example `https://app.example.com`
-Nitro Auth does not use `GoogleSignin.configure(...)`. Instead, set your client IDs via the config plugin (Expo) or native config (bare).
+Use `microsoftTenant` for `common`, `organizations`, `consumers`, a tenant ID, or a B2C policy path. Use `microsoftB2cDomain` for Azure AD B2C.
-**Expo** (recommended):
+## Quick Start
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "react-native-nitro-auth",
-        {
-          "ios": {
-            "googleClientId": "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com",
-            "googleUrlScheme": "com.googleusercontent.apps.YOUR_IOS_CLIENT_ID"
-          },
-          "android": {
-            "googleClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
-          }
-        }
-      ]
-    ],
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
+```tsx
+import { Button, Text, View } from "react-native";
+import { AuthError, useAuth } from "react-native-nitro-auth";
+export function SignInScreen() {
+  const { user, loading, login, logout, getAccessToken } = useAuth();
+  async function signInWithGoogle() {
+    try {
+      await login("google", {
+        scopes: ["email", "profile"],
+      });
+    } catch (e) {
+      const error = AuthError.from(e);
+      console.warn(error.code, error.underlyingMessage);
     }
   }
-}
-```
-**Bare React Native:**
-- iOS: add `GIDClientID` (and optionally `GIDServerClientID`) to `Info.plist` and set the URL scheme.
-- Android: add `nitro_auth_google_client_id` string resource in `res/values/strings.xml` (use your Web Client ID).
-### 3) Update API usage
-| @react-native-google-signin/google-signin | Nitro Auth                                                |
-| ----------------------------------------- | --------------------------------------------------------- |
-| `GoogleSignin.configure({...})`           | Configure in plugin / native config                       |
-| `GoogleSignin.signIn()`                   | `login("google")` or `<SocialButton provider="google" />` |
-| `GoogleSignin.signOut()`                  | `logout()`                                                |
-| `GoogleSignin.getTokens()`                | `getAccessToken()` or `refreshToken()`                    |
-| `GoogleSignin.hasPlayServices()`          | `hasPlayServices` from `useAuth()`                        |
-**Example migration:**
-```tsx
-// Before
-import { GoogleSignin } from "@react-native-google-signin/google-signin";
-await GoogleSignin.signIn();
-const tokens = await GoogleSignin.getTokens();
-// After
-import { useAuth } from "react-native-nitro-auth";
-const { login, getAccessToken } = useAuth();
+  async function readToken() {
+    const token = await getAccessToken();
+    console.log(token);
+  }
-await login("google");
-const accessToken = await getAccessToken();
+  return (
+    <View>
+      <Text>{user?.email ?? "Signed out"}</Text>
+      <Button
+        title={loading ? "Signing in..." : "Sign in with Google"}
+        onPress={signInWithGoogle}
+      />
+      <Button title="Get access token" onPress={readToken} />
+      <Button title="Sign out" onPress={logout} />
+    </View>
+  );
+}
 ```
-### 4) Remove manual init
-If you previously called `GoogleSignin.configure()` at app startup, remove it. Nitro Auth loads configuration from the plugin/native settings at runtime.
-## Advanced Features
-### Silent Restore
-Attempts to restore provider SDK sessions on app startup.
-- Google: restore is supported via provider SDK session state.
-- Apple: provider credentials are re-requested by OS flow.
-- Microsoft: no internal persistence; restore requires your app/backend session strategy.
+## SocialButton
 ```tsx
-useEffect(() => {
-  AuthService.silentRestore();
-}, []);
+import { SocialButton } from "react-native-nitro-auth";
+export function AuthButtons() {
+  return (
+    <>
+      <SocialButton provider="google" />
+      <SocialButton provider="apple" variant="black" />
+      <SocialButton provider="microsoft" variant="outline" />
+    </>
+  );
+}
 ```
-### Global Auth State Listener
+## AuthService
-Subscribe to authentication changes outside of React components:
+Use `AuthService` when you need auth outside React components.
 ```ts
 import { AuthService } from "react-native-nitro-auth";
+await AuthService.silentRestore();
 const unsubscribe = AuthService.onAuthStateChanged((user) => {
-  if (user) {
-    console.log("Logged in:", user.email);
-  } else {
-    console.log("Logged out");
-  }
+  console.log(user?.email);
+});
+const tokensUnsubscribe = AuthService.onTokensRefreshed((tokens) => {
+  console.log(tokens.expirationTime);
 });
-// Later...
 unsubscribe();
+tokensUnsubscribe();
 ```
-### Global Token Refresh Listener
-Be notified whenever tokens are refreshed automatically (or manually):
+## Login Options
 ```ts
-import { AuthService } from "react-native-nitro-auth";
-const unsubscribe = AuthService.onTokensRefreshed((tokens) => {
-  console.log("New tokens:", tokens.accessToken);
-  // Update your API client / Apollo links
+await login("google", {
+  scopes: ["email", "profile"],
+  loginHint: "user@example.com",
+  useOneTap: true,
+  useSheet: true,
+  forceAccountPicker: true,
+  useLegacyGoogleSignIn: true,
 });
-```
-### Incremental Authorization
-Request new scopes when you need them without logging the user out:
-```tsx
-const { requestScopes, revokeScopes, scopes } = useAuth();
-const handleCalendar = async () => {
-  try {
-    await requestScopes(["https://www.googleapis.com/auth/calendar.readonly"]);
-    console.log("Got calendar access!");
-  } catch (e) {
-    console.error("Scope request failed");
-  }
-};
+await login("microsoft", {
+  scopes: ["openid", "profile", "email", "offline_access", "User.Read"],
+  tenant: "organizations",
+  prompt: "select_account",
+});
 ```
-### App-Owned Persistence
-Nitro Auth is intentionally stateless in-process. Persist only what your app needs.
+| Option | Applies to | Notes |
+| --- | --- | --- |
+| `scopes` | Google, Microsoft | Requested OAuth scopes |
+| `loginHint` | Google, Microsoft | Prefills account selection when supported |
+| `useOneTap` | Android Google | Enables Credential Manager auto-select |
+| `useSheet` | iOS Google | Uses native sign-in sheet behavior |
+| `forceAccountPicker` | Google | Forces account picker |
+| `useLegacyGoogleSignIn` | Android Google | Uses legacy Google Sign-In path for server auth code |
+| `tenant` | Microsoft | Overrides configured tenant |
+| `prompt` | Microsoft | `login`, `consent`, `select_account`, or `none` |
-#### Using react-native-nitro-storage (Recommended)
+## Incremental Scopes
 ```ts
-import { AuthService, type AuthUser } from "react-native-nitro-auth";
-import { createStorageItem, StorageScope } from "react-native-nitro-storage";
-type AuthSnapshot = {
-  user: AuthUser | undefined;
-  scopes: string[];
-  updatedAt: number | undefined;
-};
-const authSnapshotItem = createStorageItem<AuthSnapshot>({
-  key: "auth_snapshot",
-  scope: StorageScope.Disk,
-  defaultValue: {
-    user: undefined,
-    scopes: [],
-    updatedAt: undefined,
-  },
-});
+const calendarScope = "https://www.googleapis.com/auth/calendar.readonly";
-// Save on auth changes (do not overwrite snapshot with empty user on app refresh)
-AuthService.onAuthStateChanged((user) => {
-  if (!user) return;
-  authSnapshotItem.set({
-    user,
-    scopes: AuthService.grantedScopes,
-    updatedAt: Date.now(),
-  });
-});
-// Keep token/expiration fields fresh in persisted snapshot
-AuthService.onTokensRefreshed((tokens) => {
-  authSnapshotItem.set((prev) => {
-    if (!prev.user) return prev;
-    return {
-      ...prev,
-      user: {
-        ...prev.user,
-        accessToken: tokens.accessToken ?? prev.user.accessToken,
-        idToken: tokens.idToken ?? prev.user.idToken,
-        refreshToken: tokens.refreshToken ?? prev.user.refreshToken,
-        expirationTime: tokens.expirationTime ?? prev.user.expirationTime,
-      },
-      updatedAt: Date.now(),
-    };
-  });
-});
-// Clear on logout
-function logout() {
-  AuthService.logout();
-  authSnapshotItem.set({
-    user: undefined,
-    scopes: [],
-    updatedAt: undefined,
-  });
-}
+await requestScopes([calendarScope]);
+await revokeScopes([calendarScope]);
 ```
-### Production Readiness
+On Android, incremental Google scope requests use the legacy Google Sign-In APIs because Credential Manager does not expose an equivalent existing-account scope query.
-Nitro Auth is suitable for production use when configured with provider-accurate expectations:
+## Storage Model
-- **Google Sign-In**: One-Tap + legacy on Android, native on iOS, popup on web.
-- **Apple Sign-In**: iOS + web only.
-- **Microsoft (Azure AD / B2C)**: iOS, Android, and web with PKCE/state/nonce protections.
+Native tokens are kept in memory by design. The package does not persist Microsoft refresh tokens or provider tokens to disk. Your app owns persistence and secure storage policy.
-Production checklist:
-1. Configure client IDs, URL schemes, and redirect URIs per platform/provider.
-2. Call `silentRestore()` during app startup to rehydrate provider session state when available.
-3. Persist only app-owned snapshots/tokens (for example with `react-native-nitro-storage`), then clear them on logout.
-4. On Android Google, use `useLegacyGoogleSignIn: true` when backend flows require `serverAuthCode`.
-5. Treat token fields as optional and branch by provider/flow.
-6. Keep web sensitive tokens memory-only unless you explicitly require persistent web tokens (`nitroAuthPersistTokensOnWeb: true`).
-7. Enable logging only in development, and monitor normalized error codes in production.
-### Logging & Debugging
-Enable verbose logging to see detailed OAuth flow information in the console:
+For app-managed persistence, store only the minimum state your product needs:
 ```ts
 import { AuthService } from "react-native-nitro-auth";
-AuthService.setLoggingEnabled(true);
-```
-### Sync State + Async Tokens
-Nitro Auth provides synchronous access to in-memory state, while token retrieval remains async:
-```ts
-// Quick access to what we have in memory
-const user = AuthService.currentUser;
-const scopes = AuthService.grantedScopes;
-// Async access ensures fresh tokens (will refresh if expired)
-const freshToken = await AuthService.getAccessToken();
+const snapshot = {
+  user: AuthService.currentUser,
+  scopes: AuthService.grantedScopes,
+  updatedAt: Date.now(),
+};
 ```
-### Standardized Error Codes
-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";
+On web, the default is also memory storage. You can opt into browser storage with:
-try {
-  await login("google");
-} catch (e) {
-  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);
-    }
-  }
+```js
+extra: {
+  nitroAuthWebStorage: "session", // "session", "local", or "memory"
+  nitroAuthPersistTokensOnWeb: true,
 }
 ```
-| 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      |
-| `not_signed_in`        | The operation requires an authenticated user/session            |
-| `operation_in_progress`| Another auth flow of the same kind is already running           |
-| `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
-`AuthError` carries the raw provider/native message in `underlyingMessage` when the platform error didn't map to a known code:
+## Error Contract
-```ts
-import { AuthError } from "react-native-nitro-auth";
+All public async APIs throw `AuthError`.
+```ts
 try {
-  await login("google");
+  await AuthService.login("microsoft");
 } catch (e) {
-  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);
+  const error = AuthError.from(e);
+  switch (error.code) {
+    case "cancelled":
+      break;
+    case "configuration_error":
+      break;
+    case "token_error":
+      break;
+    default:
+      break;
   }
 }
 ```
-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. 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
-The `getAccessToken()` method automatically checks if the current token is expired (or about to expire) and triggers a silent refresh if possible:
-```ts
-const { getAccessToken } = useAuth();
-// This will silently refresh if needed!
-const token = await getAccessToken();
-```
-### Offline Access (Server Auth Code)
-If you need to access Google APIs from your backend (e.g., Google Calendar integration), you can use the `serverAuthCode`. This code is returned during login and can be exchanged for tokens on your server:
+Known error codes:
 ```ts
-const { user } = useAuth();
+type AuthErrorCode =
+  | "cancelled"
+  | "timeout"
+  | "popup_blocked"
+  | "network_error"
+  | "configuration_error"
+  | "not_signed_in"
+  | "operation_in_progress"
+  | "unsupported_provider"
+  | "invalid_state"
+  | "invalid_nonce"
+  | "token_error"
+  | "no_id_token"
+  | "parse_error"
+  | "refresh_failed"
+  | "unknown";
+```
+`underlyingMessage` keeps the raw native or OAuth message when it differs from the stable code.
-if (user?.serverAuthCode) {
-  // Send this to your backend!
-  await api.verifyGoogleAccess(user.serverAuthCode);
-}
-```
-### Google One-Tap & Sheet
+## API Reference
-Explicitly enable the modern One-Tap flow on Android or the Sign-In Sheet on iOS:
+### Exports
 ```ts
-await login("google", {
-  useOneTap: true, // Android
-  useSheet: true, // iOS
-});
+export * from "react-native-nitro-auth";
 ```
-> [!NOTE]
-> One-Tap requires Google Play Services. You can check `hasPlayServices` from `useAuth()` and show a fallback UI if needed.
+Main exports:
-### Android Legacy Google Sign-In (Server Auth Code)
+- `useAuth()`
+- `AuthService`
+- `SocialButton`
+- `AuthError`
+- `isAuthErrorCode()`
+- `toAuthErrorCode()`
+- `AuthProvider`
+- `AuthUser`
+- `AuthTokens`
+- `LoginOptions`
-Credential Manager is the recommended default on Android, but it **does not return** `serverAuthCode`.
-If your backend requires `serverAuthCode`, opt into the legacy flow:
+### useAuth()
 ```ts
-await login("google", { useLegacyGoogleSignIn: true });
+type UseAuthReturn = {
+  user: AuthUser | undefined;
+  scopes: string[];
+  loading: boolean;
+  error: AuthError | undefined;
+  hasPlayServices: boolean;
+  login(provider: AuthProvider, options?: LoginOptions): Promise<void>;
+  logout(): void;
+  requestScopes(scopes: string[]): Promise<void>;
+  revokeScopes(scopes: string[]): Promise<void>;
+  getAccessToken(): Promise<string | undefined>;
+  refreshToken(): Promise<AuthTokens>;
+  silentRestore(): Promise<void>;
+};
 ```
-### Force Account Picker
-When connecting additional services (like Google Calendar), you may want to let users pick a different account than the one they signed in with. Use `forceAccountPicker` to clear any cached session and show the account picker:
+### AuthUser
 ```ts
-await login("google", {
-  scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
-  forceAccountPicker: true, // Always show account picker
-});
+type AuthUser = {
+  provider: "google" | "apple" | "microsoft";
+  email?: string;
+  name?: string;
+  photo?: string;
+  idToken?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  serverAuthCode?: string;
+  scopes?: string[];
+  expirationTime?: number;
+  underlyingError?: string;
+};
 ```
-This is useful for scenarios where:
-- Users want to connect a different Google account for calendar integration
-- You need to ensure the user can select any account they've added to their device
-- The cached session is interfering with the expected account selection UX
+## Example App
-On Android, `forceAccountPicker` routes through the legacy Google Sign-In chooser to guarantee the account picker appears. Credential Manager / One-Tap remains the default when the chooser is not forced.
+The example app is the fastest way to verify setup and read a complete integration.
-## API Reference
-### Package Exports
-```ts
-import {
-  AuthService,
-  AuthError,
-  isAuthErrorCode,
-  toAuthErrorCode,
-  SocialButton,
-  useAuth,
-  type UseAuthReturn,
-  type Auth,
-  type AuthUser,
-  type AuthTokens,
-  type AuthProvider,
-  type AuthErrorCode,
-  type LoginOptions,
-} from "react-native-nitro-auth";
+```sh
+cp apps/example/.env.example apps/example/.env.local
+bun install
+bun example:prebuild:clean
+bun example:ios
+bun example:android
 ```
-### Core Types
-| Type              | Definition                                                                                                                                                                                                                                    |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AuthProvider`    | `"google" \| "apple" \| "microsoft"`                                                                                                                                                                                                          |
-| `AuthErrorCode`   | `"cancelled" \| "timeout" \| "popup_blocked" \| "network_error" \| "configuration_error" \| "not_signed_in" \| "operation_in_progress" \| "unsupported_provider" \| "invalid_state" \| "invalid_nonce" \| "token_error" \| "no_id_token" \| "parse_error" \| "refresh_failed" \| "unknown"` |
-| `MicrosoftPrompt` | `"login" \| "consent" \| "select_account" \| "none"`                                                                                                                                                                                          |
-### `AuthUser`
-| Field             | Type                    | Description                                                                |
-| ----------------- | ----------------------- | -------------------------------------------------------------------------- |
-| `provider`        | `AuthProvider`          | Provider that authenticated the user                                       |
-| `email`           | `string \| undefined`   | User email                                                                 |
-| `name`            | `string \| undefined`   | Display name                                                               |
-| `photo`           | `string \| undefined`   | Profile image URL (Google)                                                 |
-| `idToken`         | `string \| undefined`   | OIDC ID token                                                              |
-| `accessToken`     | `string \| undefined`   | OAuth access token                                                         |
-| `refreshToken`    | `string \| undefined`   | OAuth refresh token                                                        |
-| `serverAuthCode`  | `string \| undefined`   | Google server auth code (legacy Android flow + backend exchange scenarios) |
-| `scopes`          | `string[] \| undefined` | Granted scopes for current session                                         |
-| `expirationTime`  | `number \| undefined`   | Expiration timestamp in milliseconds since epoch                           |
-| `underlyingError` | `string \| undefined`   | Raw provider/native error message                                          |
-> [!NOTE]
-> On Android Google One-Tap/Credential Manager, `idToken` is typically available immediately, while `accessToken` and `expirationTime` may be `undefined` until refresh/exchange flow provides them.
-### `AuthTokens`
-| Field            | Type                  | Description                   |
-| ---------------- | --------------------- | ----------------------------- |
-| `accessToken`    | `string \| undefined` | Refreshed access token        |
-| `idToken`        | `string \| undefined` | Refreshed ID token            |
-| `refreshToken`   | `string \| undefined` | Refresh token (if available)  |
-| `expirationTime` | `number \| undefined` | Optional expiration timestamp |
-### `LoginOptions`
-| Option                  | Type              | Platform  | Description                                                                       |
-| ----------------------- | ----------------- | --------- | --------------------------------------------------------------------------------- |
-| `scopes`                | `string[]`        | All       | Requested scopes (defaults are provider-specific)                                 |
-| `loginHint`             | `string`          | All       | Prefills account identifier                                                       |
-| `useOneTap`             | `boolean`         | Android   | Use Credential Manager/One-Tap flow                                               |
-| `useSheet`              | `boolean`         | iOS       | Use native Google Sign-In sheet                                                   |
-| `forceAccountPicker`    | `boolean`         | All       | Always show account chooser; Android Google uses the legacy chooser path          |
-| `useLegacyGoogleSignIn` | `boolean`         | Android   | Use legacy Google Sign-In (required when you need `serverAuthCode`)               |
-| `tenant`                | `string`          | Microsoft | Tenant (`common`, `organizations`, `consumers`, tenant id, or full authority URL) |
-| `prompt`                | `MicrosoftPrompt` | Microsoft | Prompt behavior                                                                   |
-### `useAuth()`
-```ts
-declare function useAuth(): UseAuthReturn;
-```
+The demo includes:
-| Property          | Type                                                                | Description                                          |
-| ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
-| `user`            | `AuthUser \| undefined`                                             | Current in-memory user                               |
-| `scopes`          | `string[]`                                                          | Current granted scopes                               |
-| `loading`         | `boolean`                                                           | `true` while an auth operation is in-flight          |
-| `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                               |
-| `requestScopes`   | `(scopes: string[]) => Promise<void>`                               | Requests additional scopes                           |
-| `revokeScopes`    | `(scopes: string[]) => Promise<void>`                               | Revokes scopes in current session                    |
-| `getAccessToken`  | `() => Promise<string \| undefined>`                                | Returns access token, auto-refreshing when supported |
-| `refreshToken`    | `() => Promise<AuthTokens>`                                         | Explicit refresh                                     |
-| `silentRestore`   | `() => Promise<void>`                                               | Restores provider SDK session (if available)         |
-### `AuthService`
-Synchronous state + async operations (useful outside React trees).
-#### Readonly state
-| Property          | Type                    | Description                        |
-| ----------------- | ----------------------- | ---------------------------------- |
-| `name`            | `string`                | Hybrid object name (`"Auth"`)      |
-| `currentUser`     | `AuthUser \| undefined` | Current user snapshot              |
-| `grantedScopes`   | `string[]`              | Current scope snapshot             |
-| `hasPlayServices` | `boolean`               | Android Play Services availability |
-#### Methods
-| Method               | Signature                                                | Description                      |
-| -------------------- | -------------------------------------------------------- | -------------------------------- |
-| `login`              | `(provider, options?) => Promise<void>`                  | Starts login                     |
-| `logout`             | `() => void`                                             | Clears session                   |
-| `requestScopes`      | `(scopes) => Promise<void>`                              | Incremental auth                 |
-| `revokeScopes`       | `(scopes) => Promise<void>`                              | Scope revoke                     |
-| `getAccessToken`     | `() => Promise<string \| undefined>`                     | Access token getter with refresh |
-| `refreshToken`       | `() => Promise<AuthTokens>`                              | Explicit token refresh           |
-| `silentRestore`      | `() => Promise<void>`                                    | Restore provider SDK session     |
-| `onAuthStateChanged` | `(callback: (user?: AuthUser) => void) => () => void`    | Auth change listener             |
-| `onTokensRefreshed`  | `(callback: (tokens: AuthTokens) => void) => () => void` | Token refresh listener           |
-| `setLoggingEnabled`  | `(enabled: boolean) => void`                             | Debug logging toggle             |
-| `dispose`            | `() => void`                                             | Disposes hybrid object           |
-| `equals`             | `(other: unknown) => boolean`                            | Hybrid object identity check     |
-### Storage Contract
-Nitro Auth does not provide persistence APIs. Persist the auth data you need in your app layer (for example with `react-native-nitro-storage`, MMKV, Keychain wrappers, or backend-issued sessions).
-There is no public `setStorageAdapter`/`setJSStorageAdapter` API in this package.
-### `SocialButton`
-| Prop           | Type                                           | Default     | Description                                 |
-| -------------- | ---------------------------------------------- | ----------- | ------------------------------------------- |
-| `provider`     | `AuthProvider`                                 | required    | Provider                                    |
-| `variant`      | `"primary" \| "outline" \| "white" \| "black"` | `"primary"` | Visual style                                |
-| `borderRadius` | `number`                                       | `8`         | Border radius                               |
-| `style`        | `ViewStyle`                                    | `undefined` | Container style override                    |
-| `textStyle`    | `TextStyle`                                    | `undefined` | Text style override                         |
-| `disabled`     | `boolean`                                      | `false`     | Disabled state                              |
-| `onPress`      | `() => void`                                   | `undefined` | Custom press handler (skips built-in login) |
-| `onSuccess`    | `(user: AuthUser) => void`                     | `undefined` | Called after successful default login       |
-| `onError`      | `(error: unknown) => void`                     | `undefined` | Called when default login fails             |
-### Config Plugin API (`app.json` / `app.config.js`)
-`plugins: [["react-native-nitro-auth", { ios: {...}, android: {...} }]]`
-#### iOS plugin options
-| Option                 | Type      | Description                                  |
-| ---------------------- | --------- | -------------------------------------------- |
-| `googleClientId`       | `string`  | Writes `GIDClientID`                         |
-| `googleServerClientId` | `string`  | Writes `GIDServerClientID`                   |
-| `googleUrlScheme`      | `string`  | Adds Google URL scheme                       |
-| `appleSignIn`          | `boolean` | Enables Apple Sign-In entitlement            |
-| `microsoftClientId`    | `string`  | Writes `MSALClientID` + MSAL redirect scheme |
-| `microsoftTenant`      | `string`  | Writes `MSALTenant`                          |
-| `microsoftB2cDomain`   | `string`  | Writes `MSALB2cDomain`                       |
-#### Android plugin options
-| Option               | Type     | Description                                                      |
-| -------------------- | -------- | ---------------------------------------------------------------- |
-| `googleClientId`     | `string` | Writes `nitro_auth_google_client_id` string                      |
-| `microsoftClientId`  | `string` | Writes `nitro_auth_microsoft_client_id` + redirect intent filter |
-| `microsoftTenant`    | `string` | Writes `nitro_auth_microsoft_tenant`                             |
-| `microsoftB2cDomain` | `string` | Writes `nitro_auth_microsoft_b2c_domain`                         |
-### Web runtime config (`expo.extra`)
-| Key                           | Type                               | Default     | Description                                               |
-| ----------------------------- | ---------------------------------- | ----------- | --------------------------------------------------------- |
-| `googleWebClientId`           | `string`                           | `undefined` | Google web OAuth client id                                |
-| `microsoftClientId`           | `string`                           | `undefined` | Microsoft app client id                                   |
-| `microsoftTenant`             | `string`                           | `"common"`  | Microsoft tenant/authority                                |
-| `microsoftB2cDomain`          | `string`                           | `undefined` | B2C domain when applicable                                |
-| `appleWebClientId`            | `string`                           | `undefined` | Apple Service ID                                          |
-| `nitroAuthWebStorage`         | `"session" \| "local" \| "memory"` | `"session"` | Storage for non-sensitive web cache                       |
-| `nitroAuthPersistTokensOnWeb` | `boolean`                          | `false`     | Persist sensitive tokens on web storage instead of memory |
-### `AuthError`
-All thrown errors from `AuthService` and `useAuth` are `AuthError` instances.
+- Provider cards for Google, Apple, and Microsoft.
+- Token and scope operations.
+- Silent restore and account picker actions.
+- App-owned disk snapshot example with `react-native-nitro-storage`.
+- Runtime smoke tests for the public API.
-```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
-}
+## Troubleshooting
-function isAuthErrorCode(value: string): value is AuthErrorCode;
-function toAuthErrorCode(raw: string): AuthErrorCode; // Returns "unknown" for unrecognized strings
-```
+| Symptom | Check |
+| --- | --- |
+| `configuration_error` on Google | Client ID is missing or wrong for the current platform |
+| Google works in debug but not release | Add release SHA-1/SHA-256 fingerprints to Google Cloud Console |
+| Android `hasPlayServices` is false | Use an emulator image with Google Play Services |
+| Apple email/name missing | Apple only returns these fields on first authorization |
+| Microsoft `invalid_state` | Redirect URI or app resume path is wrong, or an old auth redirect completed late |
+| Microsoft `token_error` | Check tenant, client ID, redirect URI, and requested scopes |
+| Web popup blocked | Call `login()` from a user gesture such as a button press |
+| `operation_in_progress` | A provider flow is already active; wait for it to finish or sign out |
-| `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         |
-| `not_signed_in`        | Operation requires an active authenticated user |
-| `operation_in_progress`| Another auth flow is already running           |
-| `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
-From monorepo root:
-```bash
-bun run format:check
-bun run lint
-bun run typecheck
-```
+## Production Notes
-Workspace-local commands:
+- Verify ID tokens on your backend. Client-side JWT parsing is for display and expiration hints only.
+- Store refresh tokens only in storage your app explicitly owns and secures.
+- Keep Google debug and release signing fingerprints in sync with your OAuth clients.
+- Add provider-specific redirect URIs for every environment.
+- Run the example app on iOS and Android before shipping provider config changes.
-```bash
-# apps/example
-bun run format
-bun run lint
-bun run typecheck
+## Release Checks
-# packages/react-native-nitro-auth
-bun run format
-bun run lint
-bun run typecheck
-bun run test
+```sh
+bun run codegen
+bun run build
+bun run check
+bun run test:cpp
+bun example:prebuild:clean
+bun example:ios
+bun example:android
 ```
-## Platform Support
-| Feature                    | iOS | Android | Web |
-| -------------------------- | --- | ------- | --- |
-| Google Sign-In             | ✅  | ✅      | ✅  |
-| Apple Sign-In              | ✅  | ❌      | ✅  |
-| Microsoft Sign-In          | ✅  | ✅      | ✅  |
-| Custom OAuth Scopes        | ✅  | ✅      | ✅  |
-| Incremental Authorization  | ✅  | ✅      | ✅  |
-| Token Refresh              | ✅  | ✅      | ✅  |
-| Native Session Persistence | ❌  | ❌      | —   |
-| Web Auth Snapshot Cache    | —   | —       | ✅  |
-| App-Owned Persistence      | ✅  | ✅      | ✅  |
-| Auto-Refresh               | ✅  | ✅      | ✅  |
-| Native C++ Performance     | ✅  | ✅      | —   |
-## Architecture
-`react-native-nitro-auth` is built using [Nitro Modules](https://github.com/mrousavy/nitro). Unlike traditional React Native modules, Nitro uses JSI to provide:
-- **Zero-bridge overhead**: Calls are made directly from JS to C++.
-- **Type safety**: TypeScript types are automatically kept in sync with native C++ and Swift/Kotlin code.
-- **Synchronous access**: Properties like `currentUser` are accessible synchronously without async overhead.
 ## License
 MIT