react-native-oauth-essentials 1.0.12 → 1.1.1

package/src/oauth.ts

@@ -0,0 +1,140 @@
+import { createCredentialError } from './errors';
+import { warnOnce } from './platform';
+import { CredentialError } from './types';
+
+export type PkcePair = {
+  codeVerifier: string;
+  codeChallenge: string;
+  state: string;
+};
+
+export type AuthorizationUrlParams = {
+  authorizationEndpoint: string;
+  clientId: string;
+  redirectUri: string;
+  scopes?: string[];
+  additionalParameters?: Record<string, string>;
+  state: string;
+  codeChallenge?: string;
+};
+
+function encodeQuery(params: Record<string, string>): string {
+  return Object.keys(params)
+    .map(
+      (key) => `${encodeURIComponent(key)}=${encodeURIComponent(params[key]!)}`
+    )
+    .join('&');
+}
+
+/**
+ * Decodes a query component, keeping it raw when its percent-encoding is malformed (`50%off`), so
+ * a provider bug does not turn into an error without `code`.
+ */
+function decodeComponent(value: string): string {
+  const spaced = value.replace(/\+/g, ' ');
+  try {
+    return decodeURIComponent(spaced);
+  } catch {
+    return spaced;
+  }
+}
+
+/**
+ * Set by the library and checked or reused later (state, PKCE, token exchange), so
+ * `additionalParameters` cannot override them.
+ */
+export const RESERVED_AUTHORIZATION_PARAMS = [
+  'response_type',
+  'client_id',
+  'redirect_uri',
+  'state',
+  'code_challenge',
+  'code_challenge_method',
+] as const;
+
+export function buildAuthorizationUrl(p: AuthorizationUrlParams): string {
+  const params: Record<string, string> = {
+    response_type: 'code',
+    client_id: p.clientId,
+    redirect_uri: p.redirectUri,
+    state: p.state,
+  };
+  if (p.scopes && p.scopes.length > 0) {
+    params.scope = p.scopes.join(' ');
+  }
+  if (p.codeChallenge) {
+    params.code_challenge = p.codeChallenge;
+    params.code_challenge_method = 'S256';
+  }
+  const reserved: readonly string[] = RESERVED_AUTHORIZATION_PARAMS;
+  for (const [key, value] of Object.entries(p.additionalParameters ?? {})) {
+    if (reserved.includes(key)) {
+      warnOnce(
+        'oauthSignIn',
+        `additionalParameters.${key}`,
+        `additionalParameters.${key} is ignored: the library sets it (use the matching option instead).`
+      );
+      continue;
+    }
+    params[key] = value;
+  }
+
+  const separator = p.authorizationEndpoint.includes('?') ? '&' : '?';
+  return `${p.authorizationEndpoint}${separator}${encodeQuery(params)}`;
+}
+
+/**
+ * Reads the query and fragment parameters of a redirect url.
+ */
+export function parseRedirectParams(url: string): Record<string, string> {
+  const params: Record<string, string> = {};
+  const queryStart = url.indexOf('?');
+  const hashStart = url.indexOf('#');
+  const parts: string[] = [];
+  if (queryStart >= 0) {
+    parts.push(
+      url.slice(queryStart + 1, hashStart > queryStart ? hashStart : undefined)
+    );
+  }
+  if (hashStart >= 0) {
+    parts.push(url.slice(hashStart + 1));
+  }
+  for (const part of parts) {
+    for (const pair of part.split('&')) {
+      if (!pair) continue;
+      const eq = pair.indexOf('=');
+      const key = decodeComponent(eq >= 0 ? pair.slice(0, eq) : pair);
+      params[key] = eq >= 0 ? decodeComponent(pair.slice(eq + 1)) : '';
+    }
+  }
+  return params;
+}
+
+export function getUrlScheme(url: string): string {
+  const index = url.indexOf(':');
+  if (index <= 0) {
+    throw createCredentialError(
+      CredentialError.CONFIGURATION_ERROR,
+      `Invalid redirect uri: ${url}`
+    );
+  }
+  return url.slice(0, index);
+}
+
+export function buildTokenRequestBody(p: {
+  code: string;
+  clientId: string;
+  redirectUri: string;
+  codeVerifier: string | null;
+}): string {
+  const params: Record<string, string> = {
+    grant_type: 'authorization_code',
+    code: p.code,
+    client_id: p.clientId,
+    redirect_uri: p.redirectUri,
+  };
+  if (p.codeVerifier) {
+    params.code_verifier = p.codeVerifier;
+  }
+  return encodeQuery(params);
+}

package/src/platform.ts

@@ -0,0 +1,121 @@
+import type { GoogleClientId, GoogleSignInOptions } from './types';
+
+type OS = 'ios' | 'android' | string;
+
+/**
+ * Picks the client id the native module of `os` expects.
+ *
+ * A string is passed as is. With `{ iosClientId, webClientId }`, iOS gets `iosClientId` (or '' so
+ * the native side reads `GIDClientID` from Info.plist) and `webClientId` as the default
+ * `serverClientId`; Android gets `webClientId` (or '', which rejects with `CONFIGURATION_ERROR`).
+ */
+export function resolveGoogleClientId<T extends GoogleSignInOptions>(
+  os: OS,
+  clientId: GoogleClientId | null | undefined,
+  options: T
+): { clientId: string; options: T } {
+  if (typeof clientId === 'string') {
+    return { clientId, options };
+  }
+  const ids = clientId ?? {};
+  if (os === 'ios') {
+    const resolved = { ...options };
+    if (resolved.serverClientId === undefined && ids.webClientId) {
+      resolved.serverClientId = ids.webClientId;
+    }
+    return { clientId: ids.iosClientId ?? '', options: resolved };
+  }
+  return { clientId: ids.webClientId ?? '', options };
+}
+
+/**
+ * Splits the `(clientId?, options?)` arguments of the Google methods, which also accept
+ * `(options)`: an object with `iosClientId` or `webClientId` is the client id, any other object is
+ * the options. Without a client id the native side reads it from the app config (Info.plist,
+ * AndroidManifest meta-data or the Firebase files).
+ */
+export function splitGoogleArgs<T extends object>(
+  first: GoogleClientId | T | null | undefined,
+  second: T | undefined
+): { clientId: GoogleClientId | undefined; options: T | undefined } {
+  if (first === null || first === undefined) {
+    return { clientId: undefined, options: second };
+  }
+  if (
+    typeof first === 'string' ||
+    'iosClientId' in first ||
+    'webClientId' in first
+  ) {
+    return { clientId: first as GoogleClientId, options: second };
+  }
+  return { clientId: undefined, options: first as T };
+}
+
+/**
+ * Message thrown when the native module is not in the binary: Expo Go (which only ships the Expo
+ * SDK native modules) or an app that was not rebuilt after installing the library.
+ */
+export function missingNativeModuleMessage(): string {
+  const expo = (globalThis as { expo?: { modules?: Record<string, unknown> } })
+    .expo;
+  if (expo?.modules?.ExpoGo) {
+    return (
+      'react-native-oauth-essentials does not work in Expo Go, which only contains the Expo SDK ' +
+      'native code. Create a development build instead: `npx expo run:ios` / `npx expo run:android` ' +
+      'or `eas build --profile development`.'
+    );
+  }
+  return (
+    'react-native-oauth-essentials: the native module "OauthEssentials" was not found. Rebuild the ' +
+    'app after installing the library (run `pod install` in ios/ and build again; reloading Metro is ' +
+    'not enough) and make sure the New Architecture is enabled. With Expo, use a development build ' +
+    '(Expo Go is not supported).'
+  );
+}
+
+const warned = new Set<string>();
+
+/**
+ * In development, warns once per method and option that an option set by the app has no effect on
+ * the current platform. `options` must be the options as passed by the app (before defaults).
+ */
+export function warnIgnored(
+  method: string,
+  platform: string,
+  options: object | null | undefined,
+  keys: readonly string[]
+): void {
+  if (!__DEV__ || !options) {
+    return;
+  }
+  for (const key of keys) {
+    if ((options as Record<string, unknown>)[key] !== undefined) {
+      warnOnce(
+        method,
+        key,
+        `"${key}" is ignored on ${platformName(platform)}.`
+      );
+    }
+  }
+}
+
+function platformName(platform: string): string {
+  if (platform === 'ios') return 'iOS';
+  if (platform === 'android') return 'Android';
+  return platform;
+}
+
+/**
+ * In development, logs `message` once per method and key.
+ */
+export function warnOnce(method: string, key: string, message: string): void {
+  if (!__DEV__) {
+    return;
+  }
+  const id = `${method}:${key}`;
+  if (warned.has(id)) {
+    return;
+  }
+  warned.add(id);
+  console.warn(`[react-native-oauth-essentials] ${method}: ${message}`);
+}

package/src/types.ts

@@ -1,11 +1,142 @@
 export type GoogleSignInOptions = {
+  /**
+   * Only show accounts that already signed in to the app. [Android only]
+   */
   authorizedAccounts?: boolean;
+  /**
+   * Automatically sign in when a single authorized account is available. [Android only]
+   */
   autoSelectEnabled?: boolean;
+  /**
+   * Android UI flow. `bottomSheet` (default) shows the Credential Manager sheet and, unless
+   * `authorizedAccounts` is set, falls back to `button` when no credential is available
+   * (no account on the device or the sheet is in cooldown after being dismissed).
+   * `button` always shows the "Sign in with Google" flow, which is what a sign-in button tap
+   * should use. [Android only]
+   */
+  mode?: 'bottomSheet' | 'button';
+  /**
+   * Nonce embedded as-is in the returned idToken, so your backend can prevent replay attacks.
+   * Ignored by `googleSilentSignIn` on iOS.
+   */
+  nonce?: string;
+  /**
+   * Email to preselect in the Google page. [iOS only]
+   */
+  hint?: string;
+  /**
+   * Restricts sign in to a Google Workspace domain. On Android it only applies to the
+   * "Sign in with Google" (`button`) flow and to the authorization step, not to the bottom sheet.
+   */
+  hostedDomain?: string;
+  /**
+   * Additional OAuth scopes the user must grant.
+   * iOS: requested during sign in; `accessToken` and `grantedScopes` are always returned.
+   * Android: requested in a second step (Authorization API, may show a consent screen); without
+   * `scopes`/`offlineAccess`, `accessToken` and `grantedScopes` are null.
+   */
+  scopes?: string[];
+  /**
+   * Android: requests a `serverAuthCode` (for `serverClientId`, or the main client id) your backend
+   * can exchange for refresh tokens. iOS: no effect, `serverAuthCode` is returned whenever
+   * `serverClientId` is set.
+   */
+  offlineAccess?: boolean;
+  /**
+   * iOS: web (server) client id. Makes it the idToken audience and returns a `serverAuthCode`.
+   * Android: client id the `serverAuthCode` is issued for (defaults to the main client id).
+   */
+  serverClientId?: string;
 };
 
+/**
+ * Google OAuth client ids per platform, all from the same Google Cloud project.
+ *
+ * Both are optional: a missing id is read from the app config, which the Expo plugin writes (from
+ * its options or the Firebase files).
+ */
+export type GoogleClientIds = {
+  /**
+   * iOS client id (created with the iOS bundle id). Used on iOS only. When missing, the `GIDClientID`
+   * key of Info.plist is used, then `CLIENT_ID` of GoogleService-Info.plist.
+   */
+  iosClientId?: string;
+  /**
+   * Web client id. Android: the client id passed to Credential Manager; when missing, the
+   * `com.oauthessentials.GOOGLE_WEB_CLIENT_ID` meta-data of AndroidManifest is used, then the
+   * `default_web_client_id` string generated by the Firebase `google-services` Gradle plugin.
+   * iOS: the default `serverClientId` (idToken audience); when missing, the `GIDServerClientID` key
+   * of Info.plist is used.
+   */
+  webClientId?: string;
+};
+
+/**
+ * A {@link GoogleClientIds} object, or a single client id string, used as is on both platforms
+ * (it must be the iOS client id on iOS and the web client id on Android).
+ */
+export type GoogleClientId = string | GoogleClientIds;
+
+export type AppleSignInOptions = {
+  /**
+   * Nonce passed as-is to Apple and embedded in the idToken. Firebase and Supabase expect the
+   * SHA-256 of the raw nonce here. [iOS only, on Android put it in your `androidWebUrl`]
+   */
+  nonce?: string;
+  /**
+   * Opaque value returned in the credential. [iOS only]
+   */
+  state?: string;
+};
+
+export type HybridSignInOptions = GoogleSignInOptions;
+
 export type PasskeyOptions = {
+  /**
+   * WebAuthn options JSON from your server: `PublicKeyCredentialCreationOptions` for
+   * `createPassKey`, `PublicKeyCredentialRequestOptions` for `getPassKey`.
+   */
   requestJson: string;
-  preferImmediatelyAvailableCredentials?: boolean; // [Android only]
+  /**
+   * Only offer credentials already available on the device. [Android only, iOS modal requests
+   * always behave this way]
+   */
+  preferImmediatelyAvailableCredentials?: boolean;
+  /**
+   * `autofill` shows passkeys in the QuickType bar of a text field with
+   * `textContentType="username"` instead of a modal sheet. [iOS 16+ only]
+   */
+  mediation?: 'modal' | 'autofill';
+};
+
+export type OAuthSignInOptions = {
+  authorizationEndpoint: string;
+  clientId: string;
+  /**
+   * Defaults to `OAUTH_REDIRECT_URI` (`<bundle or application id>://oauth/callback`).
+   */
+  redirectUri?: string;
+  scopes?: string[];
+  /**
+   * Extra authorization request parameters (e.g. `prompt`, `login_hint`, `nonce`). They may
+   * override `scope`, but `response_type`, `client_id`, `redirect_uri`, `state`, `code_challenge`
+   * and `code_challenge_method` are set by the library and ignored here (with a warning in
+   * development).
+   */
+  additionalParameters?: Record<string, string>;
+  /**
+   * When set, the authorization code is exchanged for tokens on the device.
+   * Leave it out to exchange the code on your backend (recommended for confidential clients).
+   */
+  tokenEndpoint?: string;
+  /**
+   * Defaults to true.
+   */
+  usePKCE?: boolean;
+  /**
+   * Do not share cookies with the browser. [iOS only]
+   */
+  prefersEphemeralSession?: boolean;
 };
 
 export type PassKeyCredentialResult = {
@@ -24,13 +155,20 @@ export type PasswordCredentialResult = {
 export type GoogleIdCredentialResult = {
   type: CredentialsType.GOOGLE_ID;
   data: {
+    /** iOS: Google user id (the idToken `sub`). Android: the account email. */
     id: string;
     idToken: string;
     displayName: string;
     givenName: string;
     familyName: string;
+    email?: string;
+    /** iOS: 200px picture url or "". */
     profilePictureUri?: string | null;
+    /** Android only. */
     phoneNumber?: string | null;
+    accessToken?: string | null;
+    serverAuthCode?: string | null;
+    grantedScopes?: string[] | null;
   };
 };
 
@@ -48,6 +186,7 @@ export type AppleIdCredentialResult = {
     email: string;
     fullName: string;
     likelyReal: boolean;
+    state?: string | null;
   };
 };
 
@@ -62,6 +201,30 @@ export type WebAppleIdCredentialResult = {
   };
 };
 
+export type OAuthCredentialResult = {
+  type: CredentialsType.OAUTH;
+  data: {
+    code: string;
+    state: string;
+    redirectUri: string;
+    codeVerifier: string | null;
+    /** All parameters received in the redirect url. */
+    params: Record<string, string>;
+    /** Token endpoint response, only when `tokenEndpoint` is set. */
+    tokens: Record<string, unknown> | null;
+  };
+};
+
+export type CredentialSuccessEvent = {
+  type: string;
+  data: Object;
+};
+
+export type CredentialFailureEvent = {
+  code: CredentialErrorCode;
+  message: string;
+};
+
 export enum CredentialsType {
   GOOGLE_ID = 'GOOGLE_ID', // GoogleId credentials type
   PASSWORD = 'PASSWORD', // Password credentials type
@@ -69,10 +232,46 @@ export enum CredentialsType {
   WEB_APPLE_ID = 'WEB_APPLE_ID', // Android AppleId credentials type
   CANCELLED = 'CANCELLED', // type when the user cancels it
   PASSKEY = 'PASSKEY', // Passkey credential type
+  OAUTH = 'OAUTH', // Generic OAuth2/OIDC authorization code
+}
+
+export enum AppleIdCredentialState {
+  AUTHORIZED = 'AUTHORIZED',
+  REVOKED = 'REVOKED',
+  NOT_FOUND = 'NOT_FOUND',
+  TRANSFERRED = 'TRANSFERRED',
 }
 
 export enum CredentialError {
+  /**
+   * @deprecated Never thrown: missing Play Services rejects with `NOT_SUPPORTED_ERROR`.
+   */
   NO_PLAY_SERVICES_ERROR = 'NO_PLAY_SERVICES_ERROR',
+  /** No Android activity, or no iOS view controller attached to a window, to present the UI. */
   NO_ACTIVITY_ERROR = 'NO_ACTIVITY_ERROR',
+  /** The provider failed or returned something unexpected; `message` has the native error. */
   INVALID_RESULT_ERROR = 'INVALID_RESULT_ERROR',
+  /** There is no credential to return (no account / passkey / previous sign in). */
+  NO_SIGN_IN_AVAILABLE = 'NO_SIGN_IN_AVAILABLE',
+  /** iOS: the same method (or method group) is still waiting for the previous call. */
+  SIMULTANEOUS_CALL_ERROR = 'SIMULTANEOUS_CALL_ERROR',
+  /** The OS version, missing Play Services or the platform does not support the method. */
+  NOT_SUPPORTED_ERROR = 'NOT_SUPPORTED_ERROR',
+  /** The browser session could not be opened (app in background, Guided Access, no browser). */
+  BROWSER_UNAVAILABLE = 'BROWSER_UNAVAILABLE',
+  /**
+   * The app is misconfigured: missing Google client id, missing iOS URL scheme (the message has
+   * the exact scheme to add) or an invalid `redirectUri`.
+   */
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
+  /** `oauthSignIn`: the token endpoint request failed (offline, DNS, TLS...). */
+  NETWORK_ERROR = 'NETWORK_ERROR',
 }
+
+/** A {@link CredentialError} value, as an enum member or its string. */
+export type CredentialErrorCode = `${CredentialError}`;
+
+/** Every promise of the library rejects with an `Error` that has one of these codes. */
+export type OauthEssentialsError<
+  C extends CredentialErrorCode = CredentialErrorCode
+> = Error & { code: C };