@croacroa/react-native-template 2.0.1 → 3.2.0

package/services/auth/social/apple.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Apple Sign-In adapter using expo-apple-authentication
+ * Provides native Apple Sign-In on iOS devices.
+ * @module services/auth/social/apple
+ */
+
+import { Platform } from "react-native";
+import * as AppleAuthentication from "expo-apple-authentication";
+
+import type { SocialAuthResult } from "./types";
+
+// ============================================================================
+// Availability Check
+// ============================================================================
+
+/**
+ * Checks whether Apple Sign-In is available on the current device.
+ * Apple Sign-In is only available on iOS 13+.
+ *
+ * @returns true if the device supports Apple Sign-In
+ *
+ * @example
+ * ```ts
+ * if (isAppleSignInAvailable()) {
+ *   // Show Apple Sign-In button
+ * }
+ * ```
+ */
+export function isAppleSignInAvailable(): boolean {
+  return Platform.OS === "ios";
+}
+
+// ============================================================================
+// Apple Sign-In
+// ============================================================================
+
+/**
+ * Initiates the native Apple Sign-In flow.
+ *
+ * Requests the user's full name and email on first sign-in.
+ * Note that Apple only provides the user's name on the FIRST sign-in;
+ * subsequent sign-ins will not include the name.
+ *
+ * @returns SocialAuthResult on success, null if the user cancelled
+ * @throws Error if Apple Sign-In is not available or fails unexpectedly
+ *
+ * @example
+ * ```ts
+ * if (isAppleSignInAvailable()) {
+ *   const result = await signInWithApple();
+ *   if (result) {
+ *     console.log('Signed in as:', result.user.email);
+ *   }
+ * }
+ * ```
+ */
+export async function signInWithApple(): Promise<SocialAuthResult | null> {
+  if (!isAppleSignInAvailable()) {
+    throw new Error("Apple Sign-In is only available on iOS devices");
+  }
+
+  try {
+    const credential = await AppleAuthentication.signInAsync({
+      requestedScopes: [
+        AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+        AppleAuthentication.AppleAuthenticationScope.EMAIL,
+      ],
+    });
+
+    const { identityToken, user, fullName, email } = credential;
+
+    if (!identityToken) {
+      throw new Error("Apple Sign-In did not return an identity token");
+    }
+
+    // Build display name from fullName components
+    // Apple only provides the name on the first sign-in
+    const nameParts: string[] = [];
+    if (fullName?.givenName) {
+      nameParts.push(fullName.givenName);
+    }
+    if (fullName?.familyName) {
+      nameParts.push(fullName.familyName);
+    }
+    const displayName = nameParts.length > 0 ? nameParts.join(" ") : "";
+
+    return {
+      provider: "apple",
+      idToken: identityToken,
+      user: {
+        id: user,
+        email: email ?? "",
+        name: displayName,
+        avatar: undefined,
+      },
+    };
+  } catch (error: unknown) {
+    // Handle user cancellation gracefully
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code: string }).code === "ERR_REQUEST_CANCELED"
+    ) {
+      return null;
+    }
+
+    throw error;
+  }
+}

package/services/auth/social/google.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Google Sign-In adapter using expo-auth-session
+ * Implements OAuth 2.0 with PKCE for secure Google authentication.
+ * @module services/auth/social/google
+ */
+
+import * as WebBrowser from "expo-web-browser";
+import {
+  makeRedirectUri,
+  AuthRequest,
+  exchangeCodeAsync,
+  type AuthSessionResult,
+} from "expo-auth-session";
+import { Platform } from "react-native";
+
+import type { SocialAuthResult, GoogleSignInOptions } from "./types";
+
+// Required for web-based auth session completion
+WebBrowser.maybeCompleteAuthSession();
+
+// ============================================================================
+// Google OAuth Discovery Document
+// ============================================================================
+
+/**
+ * Google OAuth 2.0 endpoint configuration.
+ * @see https://accounts.google.com/.well-known/openid-configuration
+ */
+const GOOGLE_DISCOVERY = {
+  authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+  tokenEndpoint: "https://oauth2.googleapis.com/token",
+  revocationEndpoint: "https://oauth2.googleapis.com/revoke",
+};
+
+// ============================================================================
+// JWT Decoding
+// ============================================================================
+
+/**
+ * Decodes a JWT token payload without verification.
+ * Used to extract user information from the Google ID token.
+ *
+ * NOTE: In production, you should verify the token on your backend.
+ * This client-side decode is only for extracting display information.
+ */
+function decodeJwtPayload(token: string): Record<string, unknown> {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new Error("Invalid JWT format");
+    }
+
+    const payload = parts[1];
+    // Handle base64url encoding (replace URL-safe chars and pad)
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const decoded = atob(padded);
+
+    return JSON.parse(decoded);
+  } catch {
+    throw new Error("Failed to decode JWT token");
+  }
+}
+
+// ============================================================================
+// Google Sign-In
+// ============================================================================
+
+/**
+ * Initiates a Google Sign-In flow using expo-auth-session with PKCE.
+ *
+ * @param options - Google sign-in configuration options
+ * @returns SocialAuthResult on success, null if the user cancelled
+ * @throws Error if the sign-in flow fails
+ *
+ * @example
+ * ```ts
+ * const result = await signInWithGoogle({
+ *   clientId: 'your-client-id.apps.googleusercontent.com',
+ * });
+ *
+ * if (result) {
+ *   console.log('Signed in as:', result.user.name);
+ * }
+ * ```
+ */
+export async function signInWithGoogle(
+  options: GoogleSignInOptions
+): Promise<SocialAuthResult | null> {
+  const clientId = Platform.select({
+    ios: options.iosClientId ?? options.clientId,
+    android: options.androidClientId ?? options.clientId,
+    default: options.clientId,
+  });
+
+  if (!clientId) {
+    throw new Error(
+      "Google Sign-In requires a clientId. " +
+        "Call SocialAuth.configure({ google: { clientId: '...' } }) first."
+    );
+  }
+
+  const redirectUri = makeRedirectUri({
+    scheme: undefined, // Uses Expo's default scheme
+  });
+
+  // Create auth request with PKCE enabled
+  const authRequest = new AuthRequest({
+    clientId,
+    redirectUri,
+    scopes: ["openid", "profile", "email"],
+    usePKCE: true,
+  });
+
+  // Prompt the user to sign in
+  const authResult: AuthSessionResult =
+    await authRequest.promptAsync(GOOGLE_DISCOVERY);
+
+  // User cancelled or dismissed the dialog
+  if (authResult.type !== "success") {
+    return null;
+  }
+
+  const { code } = authResult.params;
+
+  // Exchange authorization code for tokens
+  const tokenResult = await exchangeCodeAsync(
+    {
+      clientId,
+      code,
+      redirectUri,
+      extraParams: {
+        code_verifier: authRequest.codeVerifier ?? "",
+      },
+    },
+    GOOGLE_DISCOVERY
+  );
+
+  const { idToken, accessToken } = tokenResult;
+
+  if (!idToken) {
+    throw new Error("Google Sign-In did not return an ID token");
+  }
+
+  // Decode user info from the ID token
+  const payload = decodeJwtPayload(idToken);
+
+  return {
+    provider: "google",
+    idToken,
+    accessToken: accessToken ?? undefined,
+    user: {
+      id: (payload.sub as string) ?? "",
+      email: (payload.email as string) ?? "",
+      name: (payload.name as string) ?? "",
+      avatar: (payload.picture as string) ?? undefined,
+    },
+  };
+}

package/services/auth/social/social-auth.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Social authentication orchestrator
+ * Provides a unified API for Google and Apple sign-in flows.
+ * Configure once, then call SocialAuth.signIn(provider) from anywhere.
+ * @module services/auth/social/social-auth
+ */
+
+import { signInWithGoogle } from "./google";
+import { signInWithApple } from "./apple";
+
+import type {
+  SocialProvider,
+  SocialAuthResult,
+  SocialAuthConfig,
+} from "./types";
+
+// Re-export commonly used types and utilities
+export { isAppleSignInAvailable } from "./apple";
+export type { SocialAuthResult, SocialProvider } from "./types";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Internal configuration state.
+ * Set via SocialAuth.configure() before calling signIn().
+ */
+let config: SocialAuthConfig = {};
+
+// ============================================================================
+// Social Auth API
+// ============================================================================
+
+/**
+ * Unified social authentication API.
+ *
+ * @example
+ * ```ts
+ * // Configure (typically in app startup)
+ * SocialAuth.configure({
+ *   google: {
+ *     clientId: 'your-client-id.apps.googleusercontent.com',
+ *     iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
+ *   },
+ * });
+ *
+ * // Sign in with a provider
+ * const result = await SocialAuth.signIn('google');
+ * if (result) {
+ *   // Send result.idToken to your backend for verification
+ * }
+ * ```
+ */
+export const SocialAuth = {
+  /**
+   * Configure social auth providers.
+   * Call this once during app initialization (e.g., in _layout.tsx).
+   *
+   * @param newConfig - Provider configuration
+   */
+  configure(newConfig: SocialAuthConfig): void {
+    config = { ...config, ...newConfig };
+  },
+
+  /**
+   * Initiate sign-in with the specified social provider.
+   *
+   * @param provider - The social provider to sign in with ('google' | 'apple')
+   * @returns SocialAuthResult on success, null if the user cancelled
+   * @throws Error if the provider is not configured or sign-in fails
+   */
+  async signIn(provider: SocialProvider): Promise<SocialAuthResult | null> {
+    switch (provider) {
+      case "google": {
+        if (!config.google?.clientId) {
+          throw new Error(
+            "Google Sign-In is not configured. " +
+              "Call SocialAuth.configure({ google: { clientId: '...' } }) first."
+          );
+        }
+
+        return signInWithGoogle({
+          clientId: config.google.clientId,
+          iosClientId: config.google.iosClientId,
+          androidClientId: config.google.androidClientId,
+        });
+      }
+
+      case "apple": {
+        return signInWithApple();
+      }
+
+      default: {
+        const _exhaustive: never = provider;
+        throw new Error(`Unknown social provider: ${_exhaustive}`);
+      }
+    }
+  },
+};

package/services/auth/social/types.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Social authentication type definitions
+ * Provides shared types for Google and Apple sign-in adapters.
+ * @module services/auth/social/types
+ */
+
+/**
+ * Supported social authentication providers.
+ */
+export type SocialProvider = "google" | "apple";
+
+/**
+ * User information returned from a social sign-in flow.
+ */
+export interface SocialUser {
+  /** Unique user ID from the provider */
+  id: string;
+  /** User's email address */
+  email: string;
+  /** User's display name */
+  name: string;
+  /** URL to the user's avatar/profile picture */
+  avatar?: string;
+}
+
+/**
+ * Result of a successful social authentication.
+ * Contains the provider identifier, tokens, and user info.
+ */
+export interface SocialAuthResult {
+  /** The social provider used for authentication */
+  provider: SocialProvider;
+  /** JWT ID token from the provider */
+  idToken: string;
+  /** OAuth access token (not always available, e.g., Apple) */
+  accessToken?: string;
+  /** Authenticated user information */
+  user: SocialUser;
+}
+
+/**
+ * Configuration for Google Sign-In.
+ */
+export interface GoogleAuthConfig {
+  /** Web client ID (required for expo-auth-session) */
+  clientId: string;
+  /** iOS-specific client ID (optional, falls back to clientId) */
+  iosClientId?: string;
+  /** Android-specific client ID (optional, falls back to clientId) */
+  androidClientId?: string;
+}
+
+/**
+ * Configuration for Apple Sign-In.
+ * Apple Sign-In requires no additional configuration beyond platform support.
+ */
+export type AppleAuthConfig = Record<string, never>;
+
+/**
+ * Combined social auth configuration.
+ * Pass to SocialAuth.configure() to set up providers.
+ */
+export interface SocialAuthConfig {
+  /** Google Sign-In configuration */
+  google?: GoogleAuthConfig;
+  /** Apple Sign-In configuration */
+  apple?: AppleAuthConfig;
+}
+
+/**
+ * Options passed to the Google sign-in function.
+ */
+export interface GoogleSignInOptions {
+  /** Web client ID (overrides configured value) */
+  clientId?: string;
+  /** iOS-specific client ID (overrides configured value) */
+  iosClientId?: string;
+  /** Android-specific client ID (overrides configured value) */
+  androidClientId?: string;
+}