react-native-nitro-auth 0.6.1 → 0.6.3

package/README.md

@@ -1,33 +1,19 @@
 # react-native-nitro-auth
 
-[![npm](https://img.shields.io/badge/npm-v0.6.1-f97316?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-auth)
-[![license](https://img.shields.io/badge/license-MIT-007ec6?style=flat-square)](https://github.com/JoaoPauloCMarra/react-native-nitro-auth/blob/main/LICENSE)
-[![react-native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb?style=flat-square)](https://reactnative.dev/)
-[![nitro-modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.0-black?style=flat-square)](https://nitro.margelo.com/)
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-auth?color=f97316&label=npm)](https://www.npmjs.com/package/react-native-nitro-auth)
+[![license](https://img.shields.io/npm/l/react-native-nitro-auth?color=007ec6)](https://github.com/JoaoPauloCMarra/react-native-nitro-auth/blob/main/LICENSE)
+[![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/)
+[![Expo](https://img.shields.io/badge/expo-SDK%2056-000020)](https://expo.dev/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.7-black)](https://nitro.margelo.com/)
+[![TypeScript](https://img.shields.io/badge/typescript-6.0-3178c6)](https://www.typescriptlang.org/)
 
-Fast React Native authentication for Google Sign-In, Apple Sign-In, and Microsoft Entra ID, built on Nitro Modules and JSI.
+Google Sign-In, Apple Sign-In, and Microsoft Entra ID for React Native and
+Expo, powered by Nitro Modules.
 
-`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.
-
-## Why Use It?
-
-- 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.
-- Consistent `AuthError` mapping for async `AuthService` failures on native and web.
-
-## Choose Your Path
-
-| 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                   |
+Use it when you want one typed authentication API for native social login, web
+OAuth, token refresh, incremental scopes, account listeners, and consistent
+`AuthError` handling. The package keeps tokens in memory; your app decides what
+to persist and where.
 
 ## Install
 
@@ -35,35 +21,25 @@ Fast React Native authentication for Google Sign-In, Apple Sign-In, and Microsof
 bun add react-native-nitro-auth react-native-nitro-modules
 ```
 
-For Expo projects, prebuild after adding the config plugin:
+For Expo development builds:
 
 ```sh
-bunx expo prebuild --clean
+bunx expo install react-native-nitro-auth react-native-nitro-modules
+bunx expo prebuild
 ```
 
-The example app uses Expo Continuous Native Generation. Its `apps/example/android` and `apps/example/ios` folders are generated local artifacts and intentionally ignored by git.
-
-For bare React Native projects, install pods after installing the package:
+For bare React Native apps:
 
 ```sh
 cd ios && pod install
 ```
 
-## Requirements
+Expo Go cannot load Nitro native modules. Use an Expo development build or a
+bare app.
 
-| Runtime            | Requirement                              |
-| ------------------ | ---------------------------------------- |
-| React Native       | `>=0.75` peer range                      |
-| Nitro Modules      | `>=0.35` peer range                      |
-| iOS                | 16.4+ for Expo SDK 56                    |
-| Android            | min SDK 24+ recommended                  |
-| Validated baseline | Expo SDK 56, React Native 0.85, React 19 |
+## Expo Config
 
-The package keeps a wide React Native peer range for existing consumers, but this release is validated against Expo SDK 56, React Native 0.85.3, React 19.2.3, and Nitro Modules 0.35.7.
-
-## Expo Setup
-
-Add the plugin to `app.json` or `app.config.js`.
+Add the plugin to `app.json` or `app.config.js` before prebuild:
 
 ```js
 export default {
@@ -103,464 +79,176 @@ export default {
       microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
       microsoftTenant: process.env.MICROSOFT_TENANT,
       microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
-      nitroAuthWebStorage: "memory",
-      nitroAuthPersistTokensOnWeb: false,
+      nitroAuthWebStorage: "session",
     },
   },
 };
 ```
 
-### Plugin Options
-
-| 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                                                    |
-
-## Provider Setup
-
-### Google Sign-In
-
-Create OAuth clients in Google Cloud Console:
-
-- 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.
-
-Use the iOS reversed client ID as `GOOGLE_IOS_URL_SCHEME`.
-
-### Apple Sign-In
-
-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.
-
-Apple Sign-In is supported on iOS and web. It is intentionally reported as `unsupported_provider` on Android.
-
-### Microsoft Entra ID
-
-Create an app registration in Microsoft Entra ID and add redirect URIs:
-
-- iOS: `msauth.<bundleIdentifier>://auth`
-- Android: `msauth://<androidPackage>/<clientId>`
-- Web: your web origin, for example `https://app.example.com`
-
-Use `microsoftTenant` for `common`, `organizations`, `consumers`, a tenant ID, or a B2C policy path. Use `microsoftB2cDomain` for Azure AD B2C.
+Plugin options:
+
+| Option                       | Platform | Required for                     |
+| ---------------------------- | -------- | -------------------------------- |
+| `ios.googleClientId`         | iOS      | Google Sign-In on iOS.           |
+| `ios.googleServerClientId`   | iOS      | Google server auth code flow.    |
+| `ios.googleUrlScheme`        | iOS      | Google redirect URL scheme.      |
+| `ios.appleSignIn`            | iOS      | Apple Sign-In entitlement.       |
+| `ios.microsoftClientId`      | iOS      | Microsoft Entra ID native login. |
+| `ios.microsoftTenant`        | iOS      | Microsoft tenant override.       |
+| `ios.microsoftB2cDomain`     | iOS      | Microsoft B2C hostname.          |
+| `android.googleClientId`     | Android  | Google Sign-In on Android.       |
+| `android.microsoftClientId`  | Android  | Microsoft Entra ID native login. |
+| `android.microsoftTenant`    | Android  | Microsoft tenant override.       |
+| `android.microsoftB2cDomain` | Android  | Microsoft B2C hostname.          |
+
+Web reads provider client IDs from `expo.extra`; native platforms read values
+written by the plugin during prebuild.
+
+Microsoft tenant values are validated before opening the authorization URL. Use
+`common`, `organizations`, `consumers`, a tenant ID, or a tenant domain for
+standard Entra ID. For B2C, set `microsoftB2cDomain` to a hostname such as
+`contoso.b2clogin.com` and set `microsoftTenant` to a policy such as
+`B2C_1_signin`. For custom B2C domains, set `microsoftTenant` to a tenant/policy
+path such as `contoso.onmicrosoft.com/B2C_1_signin`.
 
 ## Quick Start
 
 ```tsx
-import { Button, Text, View } from "react-native";
 import {
-  AuthError,
-  type GoogleLoginOptions,
+  AuthService,
   useAuth,
+  type ProviderLoginOptions,
 } from "react-native-nitro-auth";
 
-const googleOptions = {
-  scopes: ["email", "profile"],
-  forceAccountPicker: true,
-} satisfies GoogleLoginOptions;
-
-export function SignInScreen() {
-  const { user, loading, login, logout, getAccessToken } = useAuth();
+export function SignInButton() {
+  const { user, login, logout } = useAuth();
 
   async function signInWithGoogle() {
-    try {
-      await login("google", googleOptions);
-    } catch (e) {
-      const error = AuthError.from(e);
-      console.warn(error.code, error.underlyingMessage);
-    }
-  }
+    const options: ProviderLoginOptions<"google"> = {
+      scopes: ["openid", "profile", "email"],
+    };
 
-  async function readToken() {
-    const token = await getAccessToken();
-    console.log(token);
+    await login("google", options);
   }
 
-  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>
-  );
-}
-```
-
-## SocialButton
+  if (user) {
+    return <Button title="Sign out" onPress={logout} />;
+  }
 
-```tsx
-import { SocialButton } from "react-native-nitro-auth";
-
-export function AuthButtons() {
-  return (
-    <>
-      <SocialButton provider="google" />
-      <SocialButton provider="apple" variant="black" />
-      <SocialButton provider="microsoft" variant="outline" />
-    </>
-  );
+  return <Button title="Continue with Google" onPress={signInWithGoogle} />;
 }
-```
-
-## AuthService
-
-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) => {
-  console.log(user?.email);
-});
-
-const tokensUnsubscribe = AuthService.onTokensRefreshed((tokens) => {
-  console.log(tokens.expirationTime);
-});
-
-unsubscribe();
-tokensUnsubscribe();
-```
-
-## Login Options
-
-```ts
-await login("google", {
-  scopes: ["email", "profile"],
-  loginHint: "user@example.com",
-  nonce: "opaque-nonce",
-  useOneTap: true,
-  forceAccountPicker: true,
-  filterByAuthorizedAccounts: true,
-  useLegacyGoogleSignIn: true,
-  forceCodeForRefreshToken: true,
-  hostedDomain: "company.com",
-  requestVerifiedPhoneNumber: true,
-});
-
-await login("apple", {
-  scopes: ["email", "name"],
-  nonce: "opaque-nonce",
-});
-
-await login("microsoft", {
-  scopes: ["openid", "profile", "email", "offline_access", "User.Read"],
-  loginHint: "user@example.com",
+await AuthService.login("microsoft", {
   tenant: "organizations",
   prompt: "select_account",
 });
 ```
 
-| Option                       | Provider     | Platform         | Notes                                                       |
-| ---------------------------- | ------------ | ---------------- | ----------------------------------------------------------- |
-| `scopes`                     | All          | iOS, Android, web | Requested OAuth scopes. Apple is unavailable on Android.    |
-| `loginHint`                  | Google, Microsoft | iOS, Android, web | Prefills account selection when supported by the provider.  |
-| `nonce`                      | Google, Apple | iOS, Android, web | Passed to provider ID-token flows when the SDK supports it. |
-| `useOneTap`                  | Google       | Android          | Enables Credential Manager auto-select.                     |
-| `useSheet`                   | Google       | iOS              | Compatibility alias; prefer `forceAccountPicker`.           |
-| `forceAccountPicker`         | Google       | iOS, Android, web | Forces an account picker. Android uses the legacy chooser.  |
-| `filterByAuthorizedAccounts` | Google       | Android          | Limits Credential Manager to authorized accounts.           |
-| `useLegacyGoogleSignIn`      | Google       | Android          | Uses legacy Google Sign-In for server auth code flows.      |
-| `forceCodeForRefreshToken`   | Google       | Android          | Forces a new server auth code on the legacy Google path.    |
-| `hostedDomain`               | Google       | iOS, Android, web | Hints or filters Google Workspace hosted-domain accounts.   |
-| `openIDRealm`                | Google       | iOS, web         | Adds OpenID realm support where the SDK exposes it.         |
-| `requestVerifiedPhoneNumber` | Google       | Android          | Requests verified phone number through Credential Manager.  |
-| `tenant`                     | Microsoft    | iOS, Android, web | Overrides configured tenant.                                |
-| `prompt`                     | Microsoft    | iOS, Android, web | `login`, `consent`, `select_account`, or `none`.            |
-
-## Incremental Scopes
+## Providers
 
-```ts
-const calendarScope = "https://www.googleapis.com/auth/calendar.readonly";
+| Provider  | Native       | Web | Notes                                                                 |
+| --------- | ------------ | --- | --------------------------------------------------------------------- |
+| Google    | iOS, Android | Yes | Supports account picker, login hint, refresh, and incremental scopes. |
+| Apple     | iOS          | Yes | Apple returns name and email only on first authorization.             |
+| Microsoft | iOS, Android | Yes | Supports tenant and B2C configuration.                                |
 
-await requestScopes([calendarScope]);
-await revokeScopes([calendarScope]);
-```
+Use `expo-auth-session`, `react-native-app-auth`, Auth0, Firebase Auth, or your
+identity provider SDK when you need a generic OAuth/OIDC provider, password
+auth, MFA, hosted user management, or server session management.
 
-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.
-
-## Storage Model
-
-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.
-
-For app-managed persistence, store only the minimum state your product needs:
-
-```ts
-import { AuthService } from "react-native-nitro-auth";
-
-const snapshot = {
-  user: AuthService.currentUser,
-  scopes: AuthService.grantedScopes,
-  updatedAt: Date.now(),
-};
-```
-
-On web, the default is also memory storage. You can opt into browser storage with:
-
-```js
-extra: {
-  nitroAuthWebStorage: "session", // "session", "local", or "memory"
-  nitroAuthPersistTokensOnWeb: true,
-}
-```
-
-## Error Contract
-
-All public async APIs throw `AuthError`, including provider errors surfaced by native and web `AuthService` implementations.
-
-```ts
-try {
-  await AuthService.login("microsoft");
-} catch (e) {
-  const error = AuthError.from(e);
-  switch (error.code) {
-    case "cancelled":
-      break;
-    case "configuration_error":
-      break;
-    case "token_error":
-      break;
-    default:
-      break;
-  }
-}
-```
-
-Known error codes:
-
-```ts
-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.
-
-## API Reference
-
-### Exports
-
-```ts
-export * from "react-native-nitro-auth";
-```
+## API
 
 Main exports:
 
-- `useAuth()`
-- `AuthService`
-- `SocialButton`
-- `AuthError`
-- `isAuthErrorCode()`
-- `toAuthErrorCode()`
-- `AuthProvider`
-- `AuthUser`
-- `AuthTokens`
-- `LoginOptions`
-- `ProviderLoginOptions`
-- `LoginOptionsByProvider`
-- `GoogleLoginOptions`
-- `GoogleIOSLoginOptions`
-- `GoogleAndroidLoginOptions`
-- `GoogleWebLoginOptions`
-- `AppleLoginOptions`
-- `AppleIOSLoginOptions`
-- `AppleWebLoginOptions`
-- `MicrosoftLoginOptions`
-- `AuthLogin`
-- `TypedAuth`
-
-### useAuth()
+- `useAuth()` for React state, login, logout, refresh, and listeners.
+- `AuthService` for imperative login, refresh, logout, and user reads.
+- `SocialButton` for provider-aware UI.
+- `AuthProvider` for the `"google"`, `"apple"`, and `"microsoft"` provider names.
+- `AuthError` and `AuthErrorCode` for deterministic failures.
+- Provider option types for strongly typed login calls.
 
-```ts
-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>;
-  revokeAccess(): Promise<void>;
-  getAccessToken(): Promise<string | undefined>;
-  refreshToken(): Promise<AuthTokens>;
-  silentRestore(): Promise<void>;
-};
-```
-
-### Strong Login Types
-
-`AuthService.login()` and `useAuth().login()` infer the allowed option object from the provider argument. Provider-specific option types intentionally reject unsupported keys, so TypeScript can catch mistakes before they become native configuration bugs.
-
-```ts
-await AuthService.login("apple", {
-  nonce: "opaque-nonce",
-});
-
-await AuthService.login("microsoft", {
-  tenant: "organizations",
-  prompt: "select_account",
-});
-```
-
-Provider/platform option helpers are exported for config builders and AI-generated integrations:
+Provider-aware login calls reject unsupported option fields at compile time:
 
 ```ts
 import type {
-  GoogleAndroidLoginOptions,
-  GoogleIOSLoginOptions,
+  ProviderLoginOptions,
   MicrosoftLoginOptions,
 } from "react-native-nitro-auth";
 
-const androidGoogleOptions = {
-  useOneTap: true,
-  filterByAuthorizedAccounts: true,
-  requestVerifiedPhoneNumber: true,
-} satisfies GoogleAndroidLoginOptions;
-
-const iosGoogleOptions = {
+const googleOptions: ProviderLoginOptions<"google"> = {
+  scopes: ["openid", "email"],
   hostedDomain: "company.com",
-  openIDRealm: "https://example.com",
-} satisfies GoogleIOSLoginOptions;
+  forceAccountPicker: true,
+};
 
-const microsoftOptions = {
+const microsoftOptions: MicrosoftLoginOptions = {
   tenant: "organizations",
   prompt: "select_account",
-} satisfies MicrosoftLoginOptions;
-```
-
-Examples of mistakes that TypeScript rejects:
-
-```ts
-await AuthService.login("apple", {
-  tenant: "organizations",
-});
-
-await AuthService.login("microsoft", {
-  nonce: "opaque-nonce",
-});
-```
-
-### AuthUser
-
-```ts
-type AuthUser = {
-  provider: "google" | "apple" | "microsoft";
-  email?: string;
-  name?: string;
-  photo?: string;
-  idToken?: string;
-  accessToken?: string;
-  refreshToken?: string;
-  serverAuthCode?: string;
-  authorizationCode?: string;
-  userId?: string;
-  phoneNumber?: string;
-  hostedDomain?: string;
-  scopes?: string[];
-  expirationTime?: number;
-  underlyingError?: string;
 };
 ```
 
-## Example App
+Supported login options:
 
-The example app is the fastest way to verify setup and read a complete integration.
+| Provider  | Options                                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Google    | `scopes`, `loginHint`, `nonce`, `forceAccountPicker`, `hostedDomain`, `useSheet`, `openIDRealm`, `useOneTap`, `filterByAuthorizedAccounts`, `useLegacyGoogleSignIn`, `forceCodeForRefreshToken`, `requestVerifiedPhoneNumber` |
+| Apple     | `scopes`, `nonce`                                                                                                                                                                                       |
+| Microsoft | `scopes`, `loginHint`, `tenant`, `prompt`                                                                                                                                                               |
 
-```sh
-cp apps/example/.env.example apps/example/.env.local
-bun install
-bun run example:prebuild:clean
-bun run example:ios
-bun run example:android
-```
+`prompt` is typed as `"login"`, `"consent"`, `"select_account"`, or `"none"`.
 
-The demo includes:
+## Storage Model
 
-- Provider cards for Google, Apple, and Microsoft.
-- Token and scope operations.
-- Silent restore, account picker, revoke access, and native logging actions.
-- Platform-gated controls for each supported Google, Apple, and Microsoft option.
-- App-owned disk snapshot example with `react-native-nitro-storage`.
-- Runtime smoke tests for the public API.
+Tokens are held in memory. Persist only the snapshot your app actually needs,
+preferably in your own secure storage or backend session. JWT decode on the
+client is for display and routing only; signature validation belongs on your
+server.
 
-## Troubleshooting
+## Error Contract
 
-| 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             |
+Async public APIs throw `AuthError` with a stable `code`, `provider`, `platform`,
+and `message`. Use `instanceof AuthError` when branching in UI code.
 
-## Production Notes
+Error codes are `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`, and `unknown`.
 
-- 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.
+## Platform Support
 
-## Release Checks
+| Platform | Status                                                      |
+| -------- | ----------------------------------------------------------- |
+| iOS      | Google, Apple, Microsoft native flows.                      |
+| Android  | Google and Microsoft native flows.                          |
+| Web      | Google, Apple, and Microsoft OAuth through Expo web config. |
+| Expo     | Development builds with the config plugin.                  |
 
-```sh
-bun run release:preflight
-```
+Validated baseline: Expo SDK 56, React Native 0.85.3, React 19.2.3, and Nitro
+Modules 0.35.7.
 
-The release preflight runs core-version verification, codegen, build, lint, typecheck, Jest, C++ tests, Expo dependency validation, Expo Doctor, Expo config introspection, package docs sync, pack dry run, and `bun publish --dry-run --ignore-scripts`.
+## Troubleshooting
 
-CI runs the same preflight with registry publish dry-run disabled because GitHub pull-request jobs do not have npm publish credentials.
+- **Expo Go error:** build a dev client; Expo Go cannot load Nitro modules.
+- **Provider not configured:** verify plugin values, `expo.extra`, and that you
+  prebuilt after changing config.
+- **Apple profile missing name/email:** Apple only sends those fields on the
+  first authorization.
+- **Microsoft redirect mismatch:** confirm bundle ID, Android package,
+  `microsoftClientId`, and tenant/B2C settings match the provider console.
 
-For faster local iteration before the full release dry run:
+## Development
 
 ```sh
+bun install
 bun run check
-bun run test:cpp
-bun run --cwd packages/react-native-nitro-auth test:coverage -- --runInBand
-bun run --cwd packages/react-native-nitro-auth test:cpp:coverage
-```
-
-Before shipping provider or native config changes, also verify the example app:
-
-```sh
-bun run example:prebuild
+bun run release:preflight
 bun run example:android
 bun run example:ios
 ```
 
+Run native example builds before release when changing plugin, native, Nitro, or
+packaging files.
+
 ## License
 
 MIT