react-native-nitro-auth 0.5.0 → 0.5.3

package/README.md

@@ -12,12 +12,13 @@ Nitro Auth is a modern authentication library for React Native built on top of [
 
 Nitro Auth is designed to replace legacy modules like `@react-native-google-signin/google-signin` with a modern, high-performance architecture.
 
-| Feature         | Legacy Modules               | Nitro Auth                     |
-| :-------------- | :--------------------------- | :----------------------------- |
-| **Performance** | Async bridge overhead (JSON) | **Direct JSI C++ (Zero-copy)** |
-| **Persistence** | Varies / Manual              | **Built-in & Automatic**       |
-| **Setup**       | Manual async initialization  | **Sync & declarative plugins** |
-| **Types**       | Manual / Brittle             | **Fully Generated (Nitrogen)** |
+| 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**                                                    |
 
 ## Features
 
@@ -26,24 +27,56 @@ Nitro Auth is designed to replace legacy modules like `@react-native-google-sign
 - **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.
-- **Auto-Refresh**: Synchronous access to tokens with automatic silent refresh.
+- **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.
-- **Custom Storage**: Pluggable storage adapters for secure persistence (e.g. Keychain, MMKV, AsyncStorage).
-- **Refresh Interceptors**: Listen to token updates globally.
+- **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
 bun add react-native-nitro-auth react-native-nitro-modules
-# or
-npm install react-native-nitro-auth react-native-nitro-modules
-# or
-yarn add react-native-nitro-auth react-native-nitro-modules
-# or
-pnpm 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`                      | `*`         |
+
 For Expo projects, rebuild native code after installation:
 
 ```bash
@@ -58,43 +91,54 @@ Fastest way to confirm the package and Microsoft login work:
    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>`  
+   - 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**.
+     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.
 
 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`:
@@ -294,7 +338,9 @@ Nitro Auth reads web configuration from `expo.extra`:
       "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
       "microsoftTenant": "common",
       "microsoftB2cDomain": "your-tenant.b2clogin.com",
-      "appleWebClientId": "com.example.web"
+      "appleWebClientId": "com.example.web",
+      "nitroAuthWebStorage": "session",
+      "nitroAuthPersistTokensOnWeb": false
     }
   }
 }
@@ -302,6 +348,9 @@ Nitro Auth reads web configuration from `expo.extra`:
 
 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.
 
+- `nitroAuthWebStorage`: `"session"` (default), `"local"`, or `"memory"`.
+- `nitroAuthPersistTokensOnWeb`: `false` by default (recommended). Set `true` only if you need cross-reload token persistence.
+
 ## Quick Start
 
 ### Using the Hook
@@ -450,7 +499,11 @@ If you previously called `GoogleSignin.configure()` at app startup, remove it. N
 
 ### Silent Restore
 
-Automatically restore the user session on app startup. This is faster than a full login and works offline if the session is cached.
+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.
 
 ```tsx
 useEffect(() => {
@@ -507,56 +560,90 @@ const handleCalendar = async () => {
 };
 ```
 
-### Pluggable Storage Adapters
-
-Nitro Auth persists the session automatically. By default, it uses secure storage on native (Keychain on iOS, EncryptedSharedPreferences on Android) and `localStorage` on web.
+### App-Owned Persistence
 
-#### 1) JS Storage (AsyncStorage, MMKV, etc.)
+Nitro Auth is intentionally stateless in-process. Persist only what your app needs.
 
-Easily swap the default storage with your preferred library from the JS layer:
+#### Using react-native-nitro-storage (Recommended)
 
 ```ts
-import { AuthService, type JSStorageAdapter } from "react-native-nitro-auth";
-import { MMKV } from "react-native-mmkv";
-
-const storage = new MMKV();
+import { AuthService, type AuthUser } from "react-native-nitro-auth";
+import { createStorageItem, StorageScope } from "react-native-nitro-storage";
 
-const mmkvAdapter: JSStorageAdapter = {
-  save: (key, value) => storage.set(key, value),
-  load: (key) => storage.getString(key),
-  remove: (key) => storage.delete(key),
+type AuthSnapshot = {
+  user: AuthUser | undefined;
+  scopes: string[];
+  updatedAt: number | undefined;
 };
 
-// Set it once at app startup
-AuthService.setJSStorageAdapter(mmkvAdapter);
-```
-
-> [!NOTE]
-> Call `setJSStorageAdapter` before your first `useAuth()` or `AuthService` call so cached values are loaded before UI renders.
+const authSnapshotItem = createStorageItem<AuthSnapshot>({
+  key: "auth_snapshot",
+  scope: StorageScope.Disk,
+  defaultValue: {
+    user: undefined,
+    scopes: [],
+    updatedAt: undefined,
+  },
+});
 
-#### 2) Native Storage (Keychain, etc.)
+// Save on auth changes (do not overwrite snapshot with empty user on app refresh)
+AuthService.onAuthStateChanged((user) => {
+  if (!user) return;
 
-For maximum security, you can implement a native HybridObject (C++, Swift, or Kotlin) and pass it to Nitro. This runs directly in memory at the C++ layer.
+  authSnapshotItem.set({
+    user,
+    scopes: AuthService.grantedScopes,
+    updatedAt: Date.now(),
+  });
+});
 
-```ts
-import { AuthService } from "react-native-nitro-auth";
-// Import your native Nitro module
-import { KeychainStorage } from "./native/KeychainStorage";
+// 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(),
+    };
+  });
+});
 
-AuthService.setStorageAdapter(KeychainStorage);
+// Clear on logout
+function logout() {
+  AuthService.logout();
+  authSnapshotItem.set({
+    user: undefined,
+    scopes: [],
+    updatedAt: undefined,
+  });
+}
 ```
 
-**Production recommendation:** If you need custom storage policies, auditability, or a different encryption model, provide your own adapter (Keychain, EncryptedSharedPreferences, or a secure JS store). See [Pluggable Storage Adapters](#pluggable-storage-adapters) above.
-
 ### Production Readiness
 
-Nitro Auth is suitable for production use:
+Nitro Auth is suitable for production use when configured with provider-accurate expectations:
+
+- **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.
 
-- **Google Sign-In**: Full support including One-Tap / Sheet, incremental scopes, and token refresh on iOS, Android, and Web.
-- **Apple Sign-In**: Supported on iOS and Web (not available on Android).
-- **Microsoft (Azure AD / B2C)**: Login, incremental scopes, and token refresh are supported on all platforms. Uses PKCE, state, and nonce for security.
+Production checklist:
 
-**Token storage:** By default, tokens are stored in secure platform storage on native (Keychain / EncryptedSharedPreferences) and in `localStorage` on web. On Android API < 23, storage falls back to unencrypted `SharedPreferences`. For high-security web requirements or custom storage needs, configure a [custom storage adapter](#pluggable-storage-adapters).
+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
 
@@ -568,9 +655,9 @@ import { AuthService } from "react-native-nitro-auth";
 AuthService.setLoggingEnabled(true);
 ```
 
-### Sync Access to Tokens
+### Sync State + Async Tokens
 
-Nitro Auth provides synchronous access to the current state, while still supporting silent refresh:
+Nitro Auth provides synchronous access to in-memory state, while token retrieval remains async:
 
 ```ts
 // Quick access to what we have in memory
@@ -614,7 +701,7 @@ try {
 
 ### Native Error Metadata
 
-For more detailed debugging, Nitro Auth captures the raw native error message. You can access it from the authenticated user or cast the error:
+For more detailed debugging, Nitro Auth captures raw provider/native details in `underlyingError` where available:
 
 ```ts
 // From authenticated user (on success)
@@ -663,54 +750,6 @@ if (user?.serverAuthCode) {
 }
 ```
 
-### Custom Storage Adapter
-
-By default, Nitro Auth uses secure native storage on iOS/Android and `localStorage` on web. You can provide a custom adapter for different security or storage requirements.
-
-> [!IMPORTANT]
-> `AuthStorageAdapter` must be implemented as a **native Nitro HybridObject** in C++, Swift, or Kotlin. Plain JavaScript objects are not supported due to Nitro's type system. See [Nitro Hybrid Objects documentation](https://nitro.margelo.com/docs/hybrid-objects) for implementation details.
-
-**Example (Swift):**
-
-```swift
-class HybridKeychainStorage: HybridAuthStorageAdapterSpec {
-  func save(key: String, value: String) {
-    // Save to Keychain
-  }
-
-  func load(key: String) -> String? {
-    // Load from Keychain
-  }
-
-  func remove(key: String) {
-    // Remove from Keychain
-  }
-}
-```
-
-**Usage (TypeScript):**
-
-```ts
-import { NitroModules } from "react-native-nitro-modules";
-import { AuthService, AuthStorageAdapter } from "react-native-nitro-auth";
-
-const keychainStorage =
-  NitroModules.createHybridObject<AuthStorageAdapter>("KeychainStorage");
-AuthService.setStorageAdapter(keychainStorage);
-```
-
-### Token Refresh Listeners
-
-Perfect for updating your API client (e.g., Axios/Fetch) whenever tokens are refreshed in the background:
-
-```ts
-AuthService.onTokensRefreshed((tokens) => {
-  console.log("Tokens were updated!", tokens.accessToken);
-  apiClient.defaults.headers.common["Authorization"] =
-    `Bearer ${tokens.accessToken}`;
-});
-```
-
 ### Google One-Tap & Sheet
 
 Explicitly enable the modern One-Tap flow on Android or the Sign-In Sheet on iOS:
@@ -725,6 +764,15 @@ await login("google", {
 > [!NOTE]
 > One-Tap requires Google Play Services. You can check `hasPlayServices` from `useAuth()` and show a fallback UI if needed.
 
+### Android Legacy Google Sign-In (Server Auth Code)
+
+Credential Manager is the recommended default on Android, but it **does not return** `serverAuthCode`.
+If your backend requires `serverAuthCode`, opt into the legacy flow:
+
+```ts
+await login("google", { useLegacyGoogleSignIn: true });
+```
+
 ### 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:
@@ -744,94 +792,231 @@ This is useful for scenarios where:
 
 ## API Reference
 
-### useAuth Hook
-
-| Property          | Type                              | Description                                            |
-| ----------------- | --------------------------------- | ------------------------------------------------------ |
-| `user`            | `AuthUser \| undefined`           | Current authenticated user (includes `serverAuthCode`) |
-| `scopes`          | `string[]`                        | Currently granted OAuth scopes                         |
-| `loading`         | `boolean`                         | True during auth operations                            |
-| `error`           | `Error \| undefined`              | Last error that occurred                               |
-| `hasPlayServices` | `boolean`                         | (Android) True if Play Services available              |
-| `login`           | `(provider, options?) => Promise` | Start login flow                                       |
-| `logout`          | `() => void`                      | Clear session (synchronous)                            |
-| `silentRestore`   | `() => Promise<void>`             | Restore session automatically on startup               |
-| `requestScopes`   | `(scopes) => Promise`             | Request additional OAuth scopes                        |
-| `revokeScopes`    | `(scopes) => Promise`             | Revoke previously granted scopes                       |
-| `getAccessToken`  | `() => Promise<string?>`          | Get current access token (auto-refreshes)              |
-| `refreshToken`    | `() => Promise<AuthTokens>`       | Explicitly refresh and return new tokens               |
-
-### AuthService
-
-| Method                     | Type                                      | Description                                        |
-| -------------------------- | ----------------------------------------- | -------------------------------------------------- |
-| `login`                    | `(provider, options?) => Promise<void>`   | Start login flow                                   |
-| `logout`                   | `() => void`                              | Clear session                                      |
-| `silentRestore`            | `() => Promise<void>`                     | Restore session on startup                         |
-| `requestScopes`            | `(scopes) => Promise<void>`               | Request additional OAuth scopes                    |
-| `revokeScopes`             | `(scopes) => Promise<void>`               | Revoke previously granted scopes                   |
-| `getAccessToken`           | `() => Promise<string \| undefined>`      | Get current access token (auto-refreshes)          |
-| `refreshToken`             | `() => Promise<AuthTokens>`               | Explicitly refresh and return new tokens           |
-| `onAuthStateChanged`       | `(callback) => () => void`                | Subscribe to auth state changes                    |
-| `onTokensRefreshed`        | `(callback) => () => void`                | Subscribe to token refresh events                  |
-| `setLoggingEnabled`        | `(enabled: boolean) => void`              | Enable or disable verbose logging                  |
-| `setStorageAdapter`        | `(adapter?: AuthStorageAdapter) => void`  | Set native storage adapter                         |
-| `setJSStorageAdapter`      | `(adapter?: JSStorageAdapter) => Promise<void>` | Set JS storage adapter                       |
-
-### AuthUser
-
-| Field            | Type                 | Description                                      |
-| --------------- | -------------------- | ------------------------------------------------ |
-| `provider`      | `"google" \| "apple" \| "microsoft"` | Provider that authenticated the user |
-| `email`         | `string?`            | User email (if provided)                         |
-| `name`          | `string?`            | User display name                                |
-| `photo`         | `string?`            | Profile image URL (Google only)                  |
-| `idToken`       | `string?`            | OIDC ID token                                    |
-| `accessToken`   | `string?`            | Access token (if available)                      |
-| `serverAuthCode`| `string?`            | Google server auth code (if configured)          |
-| `scopes`        | `string[]?`          | Granted OAuth scopes                             |
-| `expirationTime`| `number?`            | Token expiration time (ms since epoch)           |
-| `underlyingError` | `string?`          | Raw native error message                         |
-
-### LoginOptions
-
-| Option               | Type       | Platform | Description                                     |
-| -------------------- | ---------- | -------- | ----------------------------------------------- |
-| `scopes`             | `string[]` | All      | Required OAuth scopes (default: email, profile) |
-| `loginHint`          | `string`   | All      | Pre-fill email address in the login picker      |
-| `useOneTap`          | `boolean`  | Android  | Enable Google One-Tap (Credential Manager)      |
-| `useSheet`           | `boolean`  | iOS      | Enable iOS Google Sign-In Sheet                 |
-| `forceAccountPicker` | `boolean`  | All      | Always show the account selection screen        |
-| `tenant`             | `string`   | Microsoft | Azure AD tenant (`common`, `organizations`, etc.) |
-| `prompt`             | `string`   | Microsoft | Prompt behavior (`login`, `consent`, `select_account`, `none`) |
-
-### SocialButton Props
-
-| Prop           | Type                                           | Default     | Description                                   |
-| -------------- | ---------------------------------------------- | ----------- | --------------------------------------------- |
-| `provider`     | `"google" \| "apple" \| "microsoft"`           | required    | Authentication provider                       |
-| `variant`      | `"primary" \| "outline" \| "white" \| "black"` | `"primary"` | Button style variant                          |
-| `onPress`      | `() => void`                                   | —           | Custom handler (disables default login)       |
-| `onSuccess`    | `(user: AuthUser) => void`                     | —           | Called with user data on success (auto-login) |
-| `onError`      | `(error: unknown) => void`                     | —           | Called on failure (auto-login)                |
-| `disabled`     | `boolean`                                      | `false`     | Disable button interaction                    |
-| `style`        | `ViewStyle`                                    | —           | Custom container styles                       |
-| `textStyle`    | `TextStyle`                                    | —           | Custom text styles                            |
-| `borderRadius` | `number`                                       | `8`         | Button border radius                          |
+### Package Exports
+
+```ts
+import {
+  AuthService,
+  SocialButton,
+  useAuth,
+  type UseAuthReturn,
+  type Auth,
+  type AuthUser,
+  type AuthTokens,
+  type AuthProvider,
+  type AuthErrorCode,
+  type LoginOptions,
+} from "react-native-nitro-auth";
+```
+
+### Core Types
+
+| Type              | Definition                                                                                                                                                                                                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AuthProvider`    | `"google" \| "apple" \| "microsoft"`                                                                                                                                                                                                          |
+| `AuthErrorCode`   | `"cancelled" \| "timeout" \| "popup_blocked" \| "network_error" \| "configuration_error" \| "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                                                       |
+| `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;
+```
+
+| 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`           | `Error \| undefined`                                                | Last operation error                                 |
+| `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 |
+
+### Error semantics
+
+Errors are surfaced as `Error` with `message` as a normalized code when possible, and `underlyingError` with provider/native details.
+
+| 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         |
+
+## Quality Gates
+
+From monorepo root:
+
+```bash
+bun run format:check
+bun run lint
+bun run typecheck
+```
+
+Workspace-local commands:
+
+```bash
+# apps/example
+bun run format
+bun run lint
+bun run typecheck
+
+# packages/react-native-nitro-auth
+bun run format
+bun run lint
+bun run typecheck
+bun run test
+```
 
 ## Platform Support
 
-| Feature                   | iOS | Android | Web |
-| ------------------------- | --- | ------- | --- |
-| Google Sign-In            | ✅  | ✅      | ✅  |
-| Apple Sign-In             | ✅  | ❌      | ✅  |
-| Microsoft Sign-In         | ✅  | ✅      | ✅  |
-| Custom OAuth Scopes       | ✅  | ✅      | ✅  |
-| Incremental Authorization | ✅  | ✅      | ✅  |
-| Token Refresh             | ✅  | ✅      | ✅  |
-| Session Persistence       | ✅  | ✅      | ✅  |
-| Auto-Refresh              | ✅  | ✅      | ✅  |
-| Native C++ Performance    | ✅  | ✅      | —   |
+| 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