@pricava/react-native-google-credential 0.1.0

package/IMPLEMENTATION.md

@@ -0,0 +1,351 @@
+# React Native Google Credential Package
+
+This package provides one platform-agnostic JavaScript API for acquiring a Google
+ID token from the current runtime. It hides Android, iOS, and web differences
+inside the native module so consuming features do not need to branch on
+`Platform.OS`.
+
+It returns the Google credential payload, especially `idToken`, It support adapters can exchange
+that ID token with third party auth like Supabase, can support other auth
+providers such as Clerk, Auth0, Convex, Firebase Auth, or a custom backend.
+
+## Public API
+
+Import from the package root:
+
+```ts
+import {
+  clearGoogleCredentialState,
+  isGoogleCredentialAvailable,
+  signInWithGoogleCredential,
+} from "@pricava/react-native-google-credential";
+```
+
+### `signInWithGoogleCredential(options)`
+
+The main API for application code.
+
+```ts
+const credential = await signInWithGoogleCredential({
+  webClientId: process.env.GOOGLE_WEB_CLIENT_ID,
+  iosClientId: process.env.GOOGLE_IOS_CLIENT_ID,
+  nonce: hashedNonce,
+  android: {
+    flow: "sign-in-button",
+    accountFilter: "authorized-first",
+    autoSelect: true,
+  },
+  web: {
+    autoSelect: true,
+    useFedCm: true,
+  },
+});
+```
+
+It checks package-level availability, then dispatches to the active platform
+implementation. Consumers should not check `Platform.OS` before calling it.
+
+### `isGoogleCredentialAvailable()`
+
+Returns whether the package can attempt Google credential sign-in on the current
+runtime. Unsupported platforms return `false`.
+
+### `clearGoogleCredentialState()`
+
+Clears or disables the platform's saved credential state where supported. It is
+safe to call on unsupported platforms; the package returns without throwing.
+
+### Lower-Level Exports
+
+The package still exports `signInAsync`, `isAvailableAsync`, and
+`clearCredentialStateAsync` for advanced callers that explicitly need the raw
+native module shape. App features should prefer the platform-agnostic methods.
+
+## Options
+
+| Option                  | Required                | Platforms         | Purpose                                                                                                                                                                            |
+| ----------------------- | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `webClientId`           | Yes                     | Android, iOS, Web | OAuth Web client ID. This value becomes the ID token audience that the selected auth provider or backend verifies.                                                                 |
+| `iosClientId`           | iOS only unless bundled | iOS               | OAuth iOS client ID. If omitted, the iOS module tries `GIDClientID` from `Info.plist`, then `CLIENT_ID` from `GoogleService-Info.plist`.                                           |
+| `nonce`                 | No                      | Android, iOS, Web | OIDC nonce. If the selected auth provider validates nonces, pass the hashed nonce here and send the original nonce to that provider during token exchange.                         |
+| `android.flow`          | No                      | Android           | `"sign-in-button"` uses Android's explicit Sign in with Google option. `"credential"` uses the regular Google ID credential option. Defaults to `"sign-in-button"`.                |
+| `android.accountFilter` | No                      | Android           | `"authorized-first"` starts with accounts that previously authorized the app, then falls back to all accounts. `"all"` starts with all accounts. Defaults to `"authorized-first"`. |
+| `android.autoSelect`    | No                      | Android           | Enables Android auto-select when one eligible credential is available. Defaults to `true`.                                                                                         |
+| `web.autoSelect`        | No                      | Web               | Enables Google Identity Services auto-select. Defaults to `true`.                                                                                                                  |
+| `web.useFedCm`          | No                      | Web               | Enables Google Identity Services FedCM prompt support. Defaults to `true`.                                                                                                         |
+
+## Result
+
+All platforms return the same `GoogleCredentialResult` shape:
+
+```ts
+type GoogleCredentialResult = {
+  idToken: string;
+  displayName: string | null;
+  email: string | null;
+  familyName: string | null;
+  givenName: string | null;
+  id: string | null;
+  phoneNumber: string | null;
+  profilePictureUri: string | null;
+};
+```
+
+The only required field is `idToken`.
+
+## Platform Support
+
+| Platform | Status      | Implementation                                                                           |
+| -------- | ----------- | ---------------------------------------------------------------------------------------- |
+| Android  | Supported   | AndroidX Credential Manager with Google ID credential options.                           |
+| iOS      | Supported   | GoogleSignIn iOS SDK through the native module.                                          |
+| Web      | Supported   | Google Identity Services loaded on demand in `PricavaGoogleCredentialModule.web.ts`.     |
+| Other    | Unsupported | Availability returns `false`; high-level calls throw `GoogleCredentialUnavailableError`. |
+
+## Android Implementation
+
+Android lives in:
+
+```txt
+android/src/main/java/com/pricava/googlecredential/
+```
+
+`PricavaGoogleCredentialReactModule.kt` uses Android Credential Manager:
+
+- `GetSignInWithGoogleOption` when `android.flow` is `"sign-in-button"`.
+- `GetGoogleIdOption` when `android.flow` is `"credential"`.
+- `android.accountFilter: "authorized-first"` first, then fallback to all
+  Google accounts if Android returns `NoCredentialException`.
+- `setNonce` when a nonce is supplied.
+- `clearCredentialStateAsync` maps to `CredentialManager.clearCredentialState`.
+
+The Android result is mapped from `GoogleIdTokenCredential` into the shared
+TypeScript result shape.
+
+## iOS Implementation
+
+iOS lives in:
+
+```txt
+ios/PricavaGoogleCredential.h
+ios/PricavaGoogleCredential.mm
+ios/PricavaGoogleCredential.podspec
+```
+
+`PricavaGoogleCredential.mm` uses the GoogleSignIn iOS SDK:
+
+- `GIDConfiguration(clientID:serverClientID:)` is configured for each sign-in.
+- `clientID` comes from `options.iosClientId`, `Info.plist` key `GIDClientID`,
+  or `GoogleService-Info.plist` key `CLIENT_ID`.
+- `serverClientID` comes from `options.webClientId`.
+- The current React Native presenter is resolved through `RCTPresentedViewController()`.
+- The nonce is passed to `GIDSignIn.sharedInstance.signIn(... nonce: ...)`.
+- `clearCredentialStateAsync` maps to `GIDSignIn.sharedInstance.signOut()`.
+- Bare React Native apps must forward the Google redirect URL to
+  `GIDSignIn.sharedInstance.handle(_:)` in the app delegate. Expo apps can use
+  the config plugin for URL scheme setup.
+
+The podspec declares:
+
+```ruby
+s.dependency "GoogleSignIn", "~> 9.0"
+install_modules_dependencies(s)
+```
+
+The app also needs a Google URL scheme so Google can redirect back to the app.
+This project uses the local `plugins/withGoogleCredentialIos.js` Expo config
+plugin for that. The plugin writes `GIDClientID` from
+`GOOGLE_IOS_CLIENT_ID` and registers the redirect URL scheme from
+`GOOGLE_IOS_URL_SCHEME`, or derives the scheme from the iOS client
+ID when possible.
+
+## Web Implementation
+
+Web lives in:
+
+```txt
+src/PricavaGoogleCredentialModule.web.ts
+```
+
+The web module:
+
+- Returns available when `window` and `document` exist.
+- Loads `https://accounts.google.com/gsi/client` on demand.
+- Initializes Google Identity Services with `client_id`, `nonce`,
+  `web.autoSelect`, and `web.useFedCm`.
+- Resolves with the returned ID token.
+- Decodes the ID token payload locally to populate display/profile fields.
+- Calls `google.accounts.id.disableAutoSelect()` for clear state.
+
+Only the ID token is security-critical. Decoded profile fields are used as
+display metadata and should not be treated as verified authorization data by the
+client.
+
+## Auth Provider Integration
+
+The package core is provider-neutral. It only acquires a Google credential and
+returns a Google ID token. Provider exchange helpers live in the package
+`adapters` folder so consumers can opt into third-party auth integrations
+without duplicating the Google credential and nonce orchestration code.
+
+The provider-neutral adapter helper lives in:
+
+```txt
+modules/pricava-google-credential/src/adapters/google-auth-provider.ts
+```
+
+That helper:
+
+1. Accepts explicit `credentialOptions` from the consuming app.
+2. Creates an OIDC nonce pair.
+3. Calls the package-level `signInWithGoogleCredential`.
+4. Passes `credential`, `idToken`, and the original nonce to an
+   `exchangeCredential` callback.
+
+The current Supabase adapter factory lives in:
+
+```txt
+modules/pricava-google-credential/src/adapters/supabase.ts
+```
+
+That wrapper reads environment configuration and passes the existing Supabase
+exchange function into the package adapter:
+
+```ts
+const signIn = createSupabaseGoogleAuthAdapter({
+  credentialOptions,
+  exchangeGoogleIdToken: signInWithSupabaseGoogleIdToken,
+});
+```
+
+Future providers should follow the same shape. For example:
+
+```ts
+signInWithGoogleAuthProvider({
+  credentialOptions,
+  exchangeCredential: ({ idToken, nonce, credential }) =>
+    exchangeGoogleTokenWithProvider({
+      idToken,
+      nonce,
+      email: credential.email,
+    }),
+});
+```
+
+Provider-specific concerns stay in provider-specific adapters:
+
+- Supabase: exchange Google ID token through `/auth/v1/token?grant_type=id_token`.
+- Clerk: hand the Google ID token to a Clerk-supported custom or OIDC flow.
+- Auth0: exchange the Google ID token with an Auth0 connection or custom backend.
+- Convex: send the Google ID token to a Convex action or mutation that verifies it
+  or delegates verification to an auth service.
+- Custom backend: verify the Google ID token server-side and mint an app session.
+
+This separation keeps Android, iOS, and web credential acquisition independent
+from any one auth vendor while still letting the package offer first-class
+adapter helpers.
+
+## Required Configuration
+
+### Shared
+
+Set the OAuth Web client ID:
+
+```txt
+GOOGLE_WEB_CLIENT_ID=...
+```
+
+This value is used on all platforms as the Google ID token audience for
+backend token verification.
+
+### iOS
+
+Provide an iOS OAuth client ID using one of these options:
+
+```txt
+GOOGLE_IOS_CLIENT_ID=...
+```
+
+or bundle `GoogleService-Info.plist` so the native SDK can read `CLIENT_ID`.
+
+The app must also register the reversed iOS client ID as a URL scheme. With the
+local Google credential config plugin, either set it explicitly:
+
+```txt
+GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.<reversed-ios-client-id>
+```
+
+or let `plugins/withGoogleCredentialIos.js` derive it from
+`GOOGLE_IOS_CLIENT_ID`.
+
+### Android
+
+Android requires the package name and signing certificate fingerprints to be
+registered for the OAuth client in Google Cloud/Firebase. It should use `google-services.json` for Android configuration.
+
+### Web
+
+The OAuth web client must allow the deployed web origin. Local development also
+needs the localhost origins registered when testing browser sign-in. Google
+Identity Services validates the exact page origin, so register the bare
+localhost origin and every local host/port combination you use:
+
+```txt
+http://localhost
+http://localhost:8081
+http://localhost:8082
+http://127.0.0.1:8081
+http://127.0.0.1:8082
+```
+
+These entries belong in **Authorized JavaScript origins** on the same Web OAuth
+client ID configured as `GOOGLE_WEB_CLIENT_ID`. Redirect URIs are
+not used by the current web implementation because Google returns the ID token
+through the JavaScript callback.
+
+## Error Behavior
+
+The high-level API throws `GoogleCredentialUnavailableError` when the current
+platform cannot support Google credential sign-in.
+
+Platform implementations can also throw errors from their native SDKs, for
+example:
+
+- missing iOS presenter
+- missing iOS client ID
+- user-cancelled sign-in
+- Google Identity Services script load failure
+- Android Credential Manager request failure
+
+App features should catch and convert these into user-facing auth messages.
+
+## File Map
+
+```txt
+modules/pricava-google-credential/
+  adapters.ts
+  index.ts
+  IMPLEMENTATION.md
+  README.md
+  react-native.config.js
+  android/
+    build.gradle
+    src/main/java/com/pricava/googlecredential/
+      PricavaGoogleCredentialPackage.kt
+      PricavaGoogleCredentialReactModule.kt
+      ReactGoogleCredentialOptions.kt
+  ios/
+    PricavaGoogleCredential.h
+    PricavaGoogleCredential.mm
+    PricavaGoogleCredential.podspec
+  src/
+    NativePricavaGoogleCredential.ts
+    adapters/
+      google-auth-provider.ts
+      index.ts
+      supabase.ts
+    index.ts
+    types.ts
+    PricavaGoogleCredentialModule.ts
+    PricavaGoogleCredentialModule.web.ts
+```

package/README.md

@@ -0,0 +1,63 @@
+# React Native Google Credential
+
+Google credential sign-in package for React Native and Expo apps across Android, iOS, and web.
+The native runtime is implemented as a React Native TurboModule/native module.
+Expo development builds and prebuild projects use the same native module path.
+
+The JavaScript API intentionally returns only the Google credential payload. App
+features decide how to exchange the ID token with an auth provider, which keeps
+this module extractable as a standalone package later.
+
+## API
+
+Use `signInWithGoogleCredential` from app code. The package checks platform
+availability internally and dispatches to the matching native or web
+implementation, so consumers do not need to check `Platform.OS`.
+
+The lower-level `signInAsync`, `isAvailableAsync`, and
+`clearCredentialStateAsync` exports remain available for advanced use.
+
+Use generic environment variable names in app config and examples:
+
+```text
+GOOGLE_WEB_CLIENT_ID=...
+GOOGLE_IOS_CLIENT_ID=...
+GOOGLE_IOS_URL_SCHEME=...
+```
+
+Optional auth provider helpers are exported from:
+
+```ts
+import { createSupabaseGoogleAuthAdapter } from "@pricava/react-native-google-credential/adapters";
+```
+
+Future provider integrations such as Clerk, Auth0, and Convex should live in
+the package `src/adapters/` folder.
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for the full architecture,
+platform support matrix, setup requirements, and feature behavior.
+
+## Android
+
+`signInAsync` uses Credential Manager with `GetSignInWithGoogleOption` by
+default for an explicit "Sign in with Google" button. Set
+`android.flow: "credential"` to use `GetGoogleIdOption` instead. Pass the OAuth
+web client ID as `webClientId`. If your auth provider validates an OIDC nonce,
+pass the hashed nonce to this module and the original nonce to the provider
+exchange.
+
+## Web
+
+`signInAsync` loads Google Identity Services on demand and returns the same ID
+token result shape as Android. The web implementation uses the OAuth web client
+ID as `webClientId`, passes through the nonce for provider-side validation,
+uses FedCM prompts by default, and disables auto-select in
+`clearCredentialStateAsync`.
+
+## iOS
+
+`signInAsync` uses the GoogleSignIn iOS SDK. Pass the OAuth web client ID as
+`webClientId` and the OAuth iOS client ID as `iosClientId`, or bundle
+`GoogleService-Info.plist` so the native SDK can resolve the iOS client ID.
+The iOS app must also register the reversed iOS client ID URL scheme.
+

package/adapters.ts

@@ -0,0 +1 @@
+export * from "./src/adapters";

package/android/build.gradle

@@ -0,0 +1,25 @@
+plugins {
+  id 'com.android.library'
+  id 'org.jetbrains.kotlin.android'
+  id 'com.facebook.react'
+}
+
+group = 'com.pricava'
+version = '0.1.0'
+
+android {
+  namespace "com.pricava.googlecredential"
+
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "androidx.credentials:credentials:1.6.0-beta03"
+  implementation "androidx.credentials:credentials-play-services-auth:1.6.0-beta03"
+  implementation "com.google.android.libraries.identity.googleid:googleid:1.1.1"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/pricava/googlecredential/PricavaGoogleCredentialPackage.kt

@@ -0,0 +1,35 @@
+package com.pricava.googlecredential
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class PricavaGoogleCredentialPackage : BaseReactPackage() {
+  override fun getModule(
+    name: String,
+    reactContext: ReactApplicationContext
+  ): NativeModule? {
+    return if (name == PricavaGoogleCredentialReactModule.NAME) {
+      PricavaGoogleCredentialReactModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      mapOf(
+        PricavaGoogleCredentialReactModule.NAME to ReactModuleInfo(
+          PricavaGoogleCredentialReactModule.NAME,
+          PricavaGoogleCredentialReactModule::class.java.name,
+          false,
+          false,
+          false,
+          true
+        )
+      )
+    }
+  }
+}

package/android/src/main/java/com/pricava/googlecredential/PricavaGoogleCredentialReactModule.kt

@@ -0,0 +1,172 @@
+package com.pricava.googlecredential
+
+import android.os.Bundle
+import androidx.credentials.ClearCredentialStateRequest
+import androidx.credentials.CredentialOption
+import androidx.credentials.CredentialManager
+import androidx.credentials.GetCredentialRequest
+import androidx.credentials.GetCredentialResponse
+import androidx.credentials.exceptions.GetCredentialException
+import androidx.credentials.exceptions.NoCredentialException
+import androidx.credentials.exceptions.publickeycredential.GetPublicKeyCredentialException
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+import com.google.android.libraries.identity.googleid.GetGoogleIdOption
+import com.google.android.libraries.identity.googleid.GetSignInWithGoogleOption
+import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential
+import com.google.android.libraries.identity.googleid.GoogleIdTokenParsingException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+
+@ReactModule(name = PricavaGoogleCredentialReactModule.NAME)
+class PricavaGoogleCredentialReactModule(
+  private val reactContext: ReactApplicationContext
+) : NativePricavaGoogleCredentialSpec(reactContext) {
+  private val coroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+
+  override fun getName() = NAME
+
+  override fun isAvailableAsync(promise: Promise) {
+    promise.resolve(true)
+  }
+
+  override fun signInAsync(options: ReadableMap, promise: Promise) {
+    val parsedOptions = ReactGoogleCredentialOptions.fromMap(options)
+
+    coroutineScope.launch {
+      try {
+        val response = requestCredential(parsedOptions)
+        promise.resolve(Arguments.fromBundle(mapCredentialResponse(response)))
+      } catch (exception: NoCredentialException) {
+        if (parsedOptions.androidAccountFilter == "authorized-first") {
+          try {
+            val fallbackOptions = parsedOptions.copy(
+              androidAccountFilter = "all",
+              androidAutoSelect = false
+            )
+            val response = requestCredential(fallbackOptions)
+            promise.resolve(Arguments.fromBundle(mapCredentialResponse(response)))
+          } catch (fallbackException: Exception) {
+            reject(promise, fallbackException)
+          }
+        } else {
+          reject(promise, exception)
+        }
+      } catch (exception: Exception) {
+        reject(promise, exception)
+      }
+    }
+  }
+
+  override fun clearCredentialStateAsync(promise: Promise) {
+    coroutineScope.launch {
+      try {
+        val activity = reactContext.currentActivity
+          ?: throw IllegalStateException("No current activity found for Google credential sign-in.")
+        val credentialManager = CredentialManager.create(activity)
+        credentialManager.clearCredentialState(ClearCredentialStateRequest())
+        promise.resolve(null)
+      } catch (exception: Exception) {
+        reject(promise, exception)
+      }
+    }
+  }
+
+  private suspend fun requestCredential(
+    options: ReactGoogleCredentialOptions
+  ): GetCredentialResponse {
+    val activity = reactContext.currentActivity
+      ?: throw IllegalStateException("No current activity found for Google credential sign-in.")
+    val credentialManager = CredentialManager.create(activity)
+    val request = GetCredentialRequest.Builder()
+      .addCredentialOption(createCredentialOption(options))
+      .build()
+
+    return credentialManager.getCredential(
+      context = activity,
+      request = request
+    )
+  }
+
+  private fun createGoogleIdOption(options: ReactGoogleCredentialOptions): GetGoogleIdOption {
+    val builder = GetGoogleIdOption.Builder()
+      .setFilterByAuthorizedAccounts(options.androidAccountFilter == "authorized-first")
+      .setServerClientId(options.webClientId)
+      .setAutoSelectEnabled(options.androidAutoSelect)
+
+    options.nonce?.takeIf { it.isNotBlank() }?.let { builder.setNonce(it) }
+
+    return builder.build()
+  }
+
+  private fun createSignInWithGoogleOption(
+    options: ReactGoogleCredentialOptions
+  ): GetSignInWithGoogleOption {
+    val builder = GetSignInWithGoogleOption.Builder(options.webClientId)
+
+    options.nonce?.takeIf { it.isNotBlank() }?.let { builder.setNonce(it) }
+
+    return builder.build()
+  }
+
+  private fun createCredentialOption(options: ReactGoogleCredentialOptions): CredentialOption {
+    return if (options.androidFlow == "sign-in-button") {
+      createSignInWithGoogleOption(options)
+    } else {
+      createGoogleIdOption(options)
+    }
+  }
+
+  private fun mapCredentialResponse(response: GetCredentialResponse): Bundle {
+    val credential = response.credential
+
+    if (credential.type != GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
+      throw IllegalStateException(
+        "Credential Manager returned unsupported credential type: ${credential.type}."
+      )
+    }
+
+    val googleCredential = try {
+      GoogleIdTokenCredential.createFrom(credential.data)
+    } catch (exception: GoogleIdTokenParsingException) {
+      throw IllegalStateException(
+        "Credential Manager returned a Google credential that could not be parsed.",
+        exception
+      )
+    }
+
+    return Bundle().apply {
+      putString("idToken", googleCredential.idToken)
+      putString("displayName", googleCredential.displayName)
+      putString("email", googleCredential.id)
+      putString("familyName", googleCredential.familyName)
+      putString("givenName", googleCredential.givenName)
+      putString("id", googleCredential.id)
+      putString("phoneNumber", googleCredential.phoneNumber)
+      putString("profilePictureUri", googleCredential.profilePictureUri?.toString())
+    }
+  }
+
+  private fun reject(promise: Promise, exception: Exception) {
+    val code = when (exception) {
+      is GetPublicKeyCredentialException -> "ERR_GOOGLE_CREDENTIAL_REQUEST"
+      is GetCredentialException -> "ERR_GOOGLE_CREDENTIAL_REQUEST"
+      else -> "ERR_GOOGLE_CREDENTIAL_REQUEST"
+    }
+
+    promise.reject(
+      code,
+      exception.localizedMessage ?: "Google credential request failed.",
+      exception
+    )
+  }
+
+  companion object {
+    const val NAME = "PricavaGoogleCredential"
+  }
+}