Better auth

Better Auth

This project uses better-auth for its hybrid authentication system, providing both email/password authentication and social OAuth providers (currently Google).

Instead of duplicating extensive documentation, this guide provides links to the official resources. Please refer to them for detailed setup, configuration, and API usage.

Key Resources

When working on authentication-related tasks, always refer to these official documents to ensure you are following the correct patterns and security best practices:

• Convex & Svelte Adapter: This project uses a specific adapter for integrating better-auth with Convex and SvelteKit. The README for this adapter is a crucial resource.

  • Better Auth - SvelteKit Convex Integration
  • Convex Better Auth - Local Install (needed for admin and organization plugins)

• Official Documentation: The primary source for all better-auth concepts, API, and guides.

  • Better Auth Docs - Introduction

• Email Authentication Concepts: For a deep dive into how email/password authentication is handled.

  • Better Auth - Email Concepts

• Admin Plugin: Documentation for the admin plugin functionality.

  • Better Auth - Admin Plugin

• Google OAuth: Documentation for setting up Google Sign-In.

  • Better Auth - Google OAuth

Google OAuth Setup

This project has Google OAuth pre-configured. To enable it:

1. Create Google OAuth Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to “APIs & Services” > “Credentials”
4. Click “Create Credentials” > “OAuth client ID”
5. Choose “Web application” as the application type
6. Add authorized redirect URIs:
   • For development: http://localhost:5173/api/auth/callback/google
   • For production: https://yourdomain.com/api/auth/callback/google
7. Copy the Client ID and Client Secret

2. Set Environment Variables

npx convex env set GOOGLE_CLIENT_ID your_google_client_id_here
npx convex env set GOOGLE_CLIENT_SECRET your_google_client_secret_here

3. Update Authorized Redirect URIs

Make sure your redirect URI follows this pattern:

• Development: http://localhost:5173/api/auth/callback/google
• Production: https://yourdomain.com/api/auth/callback/google

The path /api/auth/callback/google is handled automatically by Better Auth through the SvelteKit API route.

4. How It Works

The Google OAuth flow is already implemented in:

• Server: src/convex/auth.ts - Contains the Google OAuth configuration in socialProviders
• Client: src/lib/auth-client.ts - No additional plugin needed; social auth is built-in
• UI: src/lib/components/login-form.svelte - Has the “Login with Google” button

The button in the login form calls:

await authClient.signIn.social({
	provider: 'google',
	callbackURL: '/dashboard'
});

This will redirect users to Google for authentication, then back to your app.

GitHub OAuth Setup

This project has GitHub OAuth pre-configured for both authentication and automatic integration setup.

1. Create GitHub OAuth App

1. Go to GitHub Developer Settings
2. Click “New OAuth App”
3. Fill in the application details:
   • Application name: Dashtray (or your app name)
   • Homepage URL:
     • Development: http://localhost:5173
     • Production: https://yourdomain.com
   • Authorization callback URL:
     • Development: http://localhost:5173/api/auth/callback/github
     • Production: https://yourdomain.com/api/auth/callback/github
4. Click “Register application”
5. Copy the Client ID
6. Click “Generate a new client secret” and copy it

2. Set Environment Variables

npx convex env set GITHUB_CLIENT_ID your_github_client_id_here
npx convex env set GITHUB_CLIENT_SECRET your_github_client_secret_here

3. How It Works

The GitHub OAuth flow is implemented in:

• Server: src/convex/auth.ts - Contains the GitHub OAuth configuration in socialProviders
• Client: src/lib/auth-client.ts - Social auth is built-in
• UI: src/lib/components/login-form.svelte - Has the “Sign in with GitHub” button

The button in the login form calls:

await authClient.signIn.social({
	provider: 'github',
	callbackURL: '/overview'
});

4. Automatic Integration Connection

When a user signs in with GitHub, the system automatically:

1. Creates a GitHub integration connection for their default project
2. Uses the OAuth access token for API calls
3. Starts syncing repository metrics immediately

This provides a seamless onboarding experience - users get both authentication and GitHub integration in one step.

5. Token Permissions

The GitHub OAuth app requests these scopes:

• repo - Access to repositories (public and private)
• read:user - Read user profile information
• user:email - Access to user email addresses

These permissions allow the integration to:

• Fetch repository metrics (commits, PRs, issues, stars, forks)
• Access both public and private repositories
• Display user information in the dashboard