Authentication Flow

Relevant source files

The following files were used as context for generating this wiki page:

• src/hooks/useSupabaseAuth.ts
• src/lib/auth-utils.ts
• src/app/login/page.tsx
• src/components/auth/SignupForm.tsx
• src/app/auth/page.tsx
• src/app/auth/auth-code-error/page.tsx
• src/app/layout.tsx
• src/components/layout/LayoutContent.tsx
• AGENTS.md

The authentication system in Vinesight is built upon Supabase, providing secure user management with support for both email/password credentials and Google OAuth. The flow is managed through a combination of a custom React hook (useSupabaseAuth), client-side UI components for login and signup, and server-side utilities for session validation and error handling.

This system is designed to handle user sign-up, sign-in, sign-out, session management across the application, and robust error recovery, particularly for session expiry and token-related issues. It ensures that authenticated users have access to protected routes and features, while unauthenticated users are directed to the appropriate login or sign-up pages.

Core Components

The authentication architecture revolves around a few key components that work together to manage the user's session state.

Sources: src/hooks/useSupabaseAuth.ts, src/lib/auth-utils.ts, src/app/layout.tsx

Component Interaction Diagram

This diagram illustrates how the main authentication components interact.

useSupabaseAuth Hook

This custom hook is the centerpiece of client-side authentication logic. It abstracts all interactions with the Supabase client for authentication actions.

Feature	Description
State Management	Manages user, loading, and error states related to authentication.
Sign-In	Provides signInWithEmail and signInWithGoogle methods.
Sign-Up	Provides signUpWithEmail method, which handles email confirmation requirements.
Sign-Out	Provides a signOut method.
Error Handling	Catches errors from Supabase, checks for refresh token issues, and exposes an error state.

Sources: src/hooks/useSupabaseAuth.ts:14-20

auth-utils.ts

This utility file contains helper functions for handling common authentication scenarios, especially error recovery and server-side validation.

Function	Description
clearAuthStorage()	Clears all Supabase-related authentication data from localStorage and sessionStorage and signs the user out locally. Used to resolve token issues.
isRefreshTokenError()	Checks if a given error message indicates a refresh token failure.
handleRefreshTokenError()	A routine that calls clearAuthStorage() and redirects the user to /auth?message=session_expired to force re-authentication.
validateUserSession()	A server-side function to validate a user's session from a Request object, intended for use in API routes.

Sources: src/lib/auth-utils.ts

GlobalAuthErrorHandler

A client component included in the root layout that listens for authentication errors from the useSupabaseAuth hook. If a refresh token error is detected, it invokes handleRefreshTokenError to clear the session and redirect the user.

Sources: src/app/layout.tsx:143

Authentication Methods

Vinesight supports two primary methods for user authentication: email/password and Google OAuth.

Email and Password Flow

This flow is used for users who sign up and sign in directly with their email and a password.

Sign-Up

1. The user fills out the SignupForm with an email and password.
2. On submission, the handleSubmit function calls signUpWithEmail from the useSupabaseAuth hook.
3. If the sign-up is successful and Supabase requires email confirmation, the user is redirected to /auth/verify-email.
4. Otherwise, the user is logged in and redirected to the /dashboard.

Sources: src/components/auth/SignupForm.tsx:49-63

Sign-In

The following diagram shows the sequence for a user signing in with their email and password.

Google OAuth Flow

This flow allows users to sign in using their Google account.

1. The user clicks the "Continue with Google" button (LoginButton) on the /auth or /login page.
2. This triggers the signInWithGoogle function from the useSupabaseAuth hook.
3. signInWithGoogle calls supabase.auth.signInWithOAuth with Google as the provider.
4. Supabase redirects the user to Google's authentication page.
5. After the user authenticates with Google, Google redirects back to the application's configured callback URL.
6. If an error occurs during this process (e.g., the user denies access), the user is redirected to /auth/auth-code-error with an error code in the query parameters.

Sources: src/app/auth/page.tsx:43-45, src/hooks/useSupabaseAuth.ts, src/app/auth/auth-code-error/page.tsx:23-32

Session Management and Route Protection

Session state is managed on the client and used to control access to different parts of the application.

LayoutContent Component

This component acts as a router guard at the layout level. It uses the useSupabaseAuth hook to check the user's authentication status.

• It defines a list of publicRoutes (e.g., /, /auth).
• If the current route is not public and a user object exists, it renders the main application layout with navigation (<Navigation /> and <BottomNavigation />).
• If the route is public or no user is authenticated, it renders a simpler layout without the main navigation elements.
• This effectively protects private routes by only showing the full application UI to authenticated users.

Sources: src/components/layout/LayoutContent.tsx:16-25, 66-72

Redirection

• On Login/Sign-up: After a successful authentication, users are programmatically redirected to /dashboard.
• Authenticated User on Public Page: If an authenticated user (with a confirmed email) visits a public auth page like /auth or /login, an effect in the component redirects them to the dashboard or a specified return URL.

Sources: src/app/login/page.tsx:21-25, src/app/auth/page.tsx:16-22

Error Handling

The system has specific mechanisms to handle authentication errors, ensuring a smooth user experience even when sessions become invalid.

Refresh Token Errors

Refresh token errors can occur if the token is expired, invalid, or not found. These errors are handled globally.

The flow for handling a refresh token error is as follows:

OAuth Code Exchange Errors

If an error occurs after the user authenticates with Google but before Supabase can exchange the authorization code for a session, the user is redirected to the /auth/auth-code-error page.

This page displays a user-friendly error message based on the error query parameter and provides options to "Refresh Page" or "Try Again," which clears the session and redirects to the home page.

Error Code	Message Displayed
exchange_failed	"Failed to exchange authorization code. This might be a temporary issue."
no_code	"No authorization code received from the authentication provider."
access_denied	"You denied access to the application. Please try again if you want to sign in."
unexpected	"An unexpected error occurred during authentication."

Sources: src/app/auth/auth-code-error/page.tsx:23-32

Conclusion

The authentication flow in Vinesight is a robust system leveraging Supabase for its core functionality. It provides a clean, hook-based interface for UI components (useSupabaseAuth), supports multiple authentication strategies, and implements comprehensive session management and error handling. The combination of client-side logic in React components and hooks with server-side utilities ensures both a secure and user-friendly experience.