feat: Implement User Onboarding & Wallet Connection (closes #17) by rafamiziara · Pull Request #34 · rm30-dev/superpool

rafamiziara · 2025-08-18T08:28:50Z

Summary

This PR implements the complete user onboarding and wallet connection feature for the SuperPool mobile application, closing issue #17. This represents the foundation for Sprint 1 and enables users to securely connect their blockchain wallets and establish authenticated sessions.

Key Components Implemented

🔧 Backend Infrastructure:

generateAuthMessage Cloud Function - Creates secure nonce-based authentication messages
verifySignatureAndLogin Cloud Function - Validates wallet signatures and creates Firebase sessions
Custom App Check Provider - Enhances security with custom token minting
Firestore user profile management with automatic creation/updates
Comprehensive unit tests for all authentication functions

📱 Mobile Application:

Complete Expo/React Native app with TypeScript
Multi-wallet support via Reown AppKit (WalletConnect v2)
Chain support for Mainnet, Polygon, and Polygon Amoy
Auth-based routing with protected dashboard access
Comprehensive error handling and user feedback systems
Session management with automatic cleanup

⚙️ Infrastructure & DevOps:

PNPM monorepo setup with proper workspace configuration
TypeScript configurations across all packages
ESLint setup with consistent code quality rules
Firebase project configuration with emulators
GitHub Actions workflows for automated testing

Features Delivered

✅ Wallet Connection Flow

Users can connect multiple wallet types (MetaMask, WalletConnect, etc.)
Seamless chain switching and network management
Real-time connection status and error handling

✅ Authentication System

Cryptographic signature-based authentication
Secure nonce generation and validation
Firebase Custom Claims integration
Session persistence across app restarts

✅ User Experience

Intuitive onboarding flow with clear CTAs
Toast notifications for success/error states
Loading states and connection feedback
Graceful error recovery and retry mechanisms

Test Plan

Manual Testing Checklist:

Fresh app install shows connect wallet screen
Wallet connection works across different providers
Authentication flow completes successfully
Dashboard access is properly protected
Error states display appropriate messages
Session persists across app restarts
Logout functionality works correctly

Backend Testing:

All unit tests pass (pnpm test in packages/backend)
Firebase emulator integration works
Authentication functions respond correctly

Technical Verification:

No TypeScript errors (pnpm build across workspaces)
ESLint passes (pnpm lint across workspaces)
Firebase deployment succeeds

Deployment Notes

This PR includes all necessary configuration for:

Firebase Cloud Functions deployment
Mobile app builds (iOS/Android/Web)
Environment variable templates
Development workflow setup

Next Steps: Ready for pool creation functionality to complete Sprint 1.

🤖 Generated with Claude Code

Sets up the foundational project structure using pnpm workspaces. The project is now split into 'apps' and 'packages' directories to follow best practices for monorepo organization. Closes #1

This commit sets up the foundational Firebase environment for the project. - Initializes a new Firebase project with Firestore, Functions, and the Emulator Suite. - Relocates the functions source code to the `packages/backend` directory. - Updates `firebase.json` to correctly point to the new backend location. - Prepares the project for local development and future production deployments. Closes #2

This commit sets up the base Expo project for the mobile application. - Creates a new Expo app using the "Blank (TypeScript)" template. - Configures the project with standard run scripts. Closes #18

This commit sets up environment variables for both the mobile app and backend. - Adds `.env` files for local configuration in `apps/mobile` and `packages/backend`. - Configures Expo to handle public keys for the mobile app. - Integrates `dotenv` for local development in Cloud Functions. - Updates `firebase.config.ts` to read keys from environment variables. Closes #3

This commit adds the first Cloud Function for the project's authentication flow. - Implements a callable function that generates a unique, verifiable message for a user's wallet. - Uses a timestamp and nonce to prevent replay attacks. - Stores the nonce in Firestore for later verification. - Adds `ethers` and `uuid` dependencies to the backend package. Closes #4

This commit adds the core backend function for wallet-based authentication. - Implements a callable function that verifies a user's signed message. - Checks for a valid nonce in Firestore to prevent replay attacks. - Uses `ethers.verifyMessage` to cryptographically verify the signature. - Issues a Firebase custom token upon successful verification. - Cleans up the used nonce in Firestore for security. Closes #5

…ndling This commit adds a new feature to the `verifySignatureAndLogin` Cloud Function and makes the function more resilient with comprehensive error handling. - **Implement User Profile Management**: After a successful signature verification, the function now checks for an existing user profile in Firestore. If the profile doesn't exist, it creates a new one; otherwise, it updates the `updatedAt` timestamp. This ensures every authenticated user has a corresponding Firestore document. - **Add Robust Error Handling**: Critical operations like custom token creation and user profile management are now wrapped in `try/catch` blocks. This prevents the function from crashing and allows for specific, client-facing error messages. - **Graceful Nonce Deletion**: The temporary nonce deletion is also in a `try/catch` block, but with a non-critical error handling approach, ensuring that a cleanup failure does not block a successful user login. Closes #6

This commit centralizes the TypeScript and ESLint configurations at the monorepo root to ensure consistent standards and streamline dependency management. - **Unified tsconfig:** The root `tsconfig.json` now acts as a project reference map, resolving the ESLint parsing errors by correctly pointing to the `tsconfig.json` file in each package. - **Shared ESLint Setup:** ESLint and its related plugins are now installed and configured once at the root level. - **Improved Module Handling:** Corrected module-related errors by renaming configuration files to `.cjs` and setting the `env.node` flag. - **Dependency Cleanup:** Redundant ESLint dependencies have been removed from the individual package.json files. This setup resolves configuration conflicts and establishes a single source of truth for code quality and formatting. Closes #19

This commit adds a custom App Check provider to enable secure client verification for our app. This is necessary because the default providers are not fully compatible with our Expo setup. **Key Changes:** - **Frontend:** Implemented `customAppCheckProviderFactory` to get a unique device ID and request a token from our backend. - **Backend:** Created a new `onRequest` Cloud Function (`customAppCheckMinter`) that validates the device ID and mints App Check tokens using the Firebase Admin SDK. - **Security:** Configured service account credentials and environment variables (`APP_ID_FIREBASE`) to ensure secure token minting in both production and emulator environments. Closes #7

This commit refactors the backend directory structure to a domain-based organization. - Moves functions and related files into domain-specific folders (e.g., `auth`, `appCheck`). - Relocates shared services to a dedicated `src/services` directory. - Moves local development scripts into `packages/backend/scripts`. - Updates all import paths and test configurations to reflect the new structure. Closes #20

This commit adds a comprehensive suite of unit tests for all backend functions. The tests ensure the reliability and correctness of the following areas: Authentication Flow: Validates the end-to-end process of generating a message, verifying a signature, and issuing a Firebase token. Data Handling: Confirms that data is correctly stored, updated, and retrieved from Firestore. Edge Cases & Error Handling: Covers a wide range of failure scenarios, such as invalid inputs, missing data, and external service failures, ensuring graceful and predictable error responses. Utility Functions: Verifies that helper functions, such as those for message formatting, are working as expected. This extensive test coverage significantly improves the stability and maintainability of the application by preventing future regressions. Closes #8

This commit implements the core wallet connection functionality and integrates the Reown AppKit SDK. Key changes include: - Installation of libraries: Added `@reown/appkit-wagmi-react-native`, `@tanstack/react-query`, `viem`, and `wagmi` for wallet connection and state management. - Reown AppKit Integration: The application is configured with the Reown AppKit, using the <AppKit /> component to handle wallet connection UI and logic. - Configuration: The Wagmi configuration is set up to support the Polygon and Polygon Amoy chains. Closes #9 #10

This commit completes the client-side authentication flow, integrating wallet connection with Firebase. Key changes: - Integrated Wagmi for wallet state and `useSignMessage` to get user signatures. - Created a custom hook (useAuthentication) that orchestrates the entire process: 1. Generates a message. 2. Signs a message & gets a wallet signature. 3. Calls a backend Cloud Function for verification. 4. Uses the returned custom token to sign the user into Firebase. Added robust error handling, including disconnecting the wallet on authentication failure. Closes #11 #12

…4250254' into feat/wallet-connection

Implements conditional navigation based on authentication status to redirect users to the main dashboard upon successful authentication and keep them on onboarding if not authenticated. Key changes: - Migrated from React Navigation to Expo Router for file-based routing - Replaced App.tsx and AppContainer.tsx with new app directory structure - Added auth guards to protect authenticated routes - Updated entry point to use Expo Router architecture - Enhanced Firebase config with null checks for NGROK environment variables - Updated authentication hook to work with new routing system - Added TypeScript path mapping for improved imports Closes #13 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

…loses #14, #15, #16) Major improvements to wallet connection reliability and developer experience: 🔧 WalletConnect Session Management: - Add SessionManager utility for automatic session cleanup - Implement "No matching key" error detection and recovery - Enhanced authentication error handling with user-friendly messages - Session debugging tools for troubleshooting connection issues 🚀 Development Automation: - Create automated dev-start.js script for local development - Integrate Firebase emulators + ngrok + Expo in single command - Auto-update mobile app environment variables with ngrok URLs - Add ngrok configuration template with security best practices ✨ User Experience Enhancements: - Improved toast notification system with context-aware messaging - Session-specific error messages for connection issues - Better error categorization and user guidance - Deep link configuration fixes for AppKit integration 🛠️ Developer Experience: - One-command development environment setup (pnpm dev) - Automatic session cleanup on connection failures - Comprehensive session state debugging and logging - ESLint configuration for development scripts This completes the user onboarding quality assurance phase, bringing wallet connection reliability to production-ready standards. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

…g and UX 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>