Convex Authentication Setup

This document outlines the authentication setup for your Convex application.

Core Files

• convex/auth.config.js: Configures the authentication providers. Currently set up for Convex's built-in email/password authentication.
• convex/schema.ts: Defines the database schema, including the users table which stores user information. The users table has an index by_token on the tokenIdentifier field.
• convex/auth.ts: Contains server-side helper functions for authentication:
  • getUser(ctx, tokenIdentifier): Retrieves a user by their token identifier.
  • requireUser(ctx): Ensures a user is authenticated and returns the user and identity. Throws an error if not authenticated or user not found.
  • getMe(ctx): A query function to get the currently authenticated user.
• convex/users.ts: Contains mutations and queries related to user management:
  • store(): (Mutation) Stores the current user's identity in the users table if they don't already exist. Called after a successful login/signup to create a user profile.
  • get(): (Query) Retrieves the current authenticated user's profile from the users table.
  • createWithEmail(email, tokenIdentifier): (Mutation) Creates a new user with an email and token identifier. Used by the onSignUp hook in a more complete setupAuth.ts (which is currently not used in this simplified setup).
  • getByTokenIdentifier(tokenIdentifier): (Query) Retrieves a user by their token identifier.

How It Works

1. Configuration (auth.config.js): Specifies Convex's own auth system as the provider.
2. Schema (schema.ts): The users table is defined to store essential user details linked by a tokenIdentifier provided by the Convex authentication system.
3. Authentication Helpers (auth.ts): These functions provide reusable logic to fetch user data and enforce authentication in your Convex functions.
4. User Management (users.ts):
   • The store mutation is crucial. After a user signs up or logs in via the Convex client-side SDK, you should call this mutation to create a corresponding record in your users table.
   • The get query can be used by client-side components to fetch the current user's data.

Client-Side Integration (Conceptual)

While client-side files were removed from the convex directory (as they don't belong with server functions), here's a conceptual overview of how you'd integrate this on the client (e.g., in your React app):

1. Install Convex Client: npm install convex or pnpm add convex in your frontend project.
2. Initialize Convex Client: Create a ConvexReactClient instance.
3. Authentication UI: Build login and signup forms.
4. Sign-in/Sign-up: Use convex.auth.signIn({ email, password }) or convex.auth.signUp({ email, password }).
5. Store User: After successful sign-in/sign-up, call the store mutation from convex/users.ts to ensure the user's profile is created/updated in your database.

   // Example after successful sign-in
   const storeUser = useMutation(api.users.store);
   await storeUser();
   

6. Access User Data: Use the getMe query from convex/auth.ts or get query from convex/users.ts to fetch user data.

   const currentUser = useQuery(api.auth.getMe);
   // or
   const userProfile = useQuery(api.users.get);
   

7. Protect Routes/UI: Conditionally render components based on the authentication state.

Next Steps

• Implement the client-side authentication flow in your frontend application (e.g., React, Next.js).
• Use the requireUser helper in your Convex mutations and queries that require authentication.

  // Example in a Convex function
  import { query } from "./_generated/server";
  import { requireUser } from "./auth";
  
  export const getMySecretData = query({
    async handler(ctx) {
      const { user } = await requireUser(ctx);
      // Now you can access user._id, user.email, etc.
      // Proceed with logic that requires an authenticated user
      return `This is secret data for ${user.email}`;
    },
  });
  

This setup provides a basic but solid foundation for user authentication in your Convex application.