Authentication

Overview

The Authentication feature in the WikiSmith application allows users to sign in and manage their accounts. It integrates with GitHub for OAuth authentication, enabling users to access their repositories and perform actions based on their permissions.

User-facing behavior

Sign In: Users can sign in using their GitHub accounts. If successful, they are redirected to their dashboard.
Account Management: Signed-in users can view their account details and manage their sessions through an account menu.
Error Handling: Users receive clear error messages for authentication failures, missing tokens, or repository scope issues.
Session Summary: Users can view a summary of their session, including their email and session ID.

Architecture and data flow

Authentication Flow:
- Users initiate sign-in via a button that redirects to GitHub for OAuth.
- Upon successful authentication, GitHub redirects back to the application with tokens.
- The application verifies the tokens and checks for necessary permissions (e.g., repository access).
Session Management:
- The application maintains user sessions, storing user information and tokens securely.
- Users can sign out, which clears their session and redirects them to the home page.
Error Handling:
- The application handles various authentication errors and displays appropriate messages to users.

Key implementation details

Authentication Callback Handling: The authentication callback is managed in route.ts, where the application processes the response from GitHub and verifies user permissions.

const GET = handleAuth({
  baseURL: callbackBaseUrl,
  returnPathname: '/dashboard',
  onSuccess: async ({ user, oauthTokens, state }) => {
    await syncAuthenticatedUser({
      id: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      profilePictureUrl: user.profilePictureUrl,
    }, oauthTokens);
  }
});

This code snippet shows how user information is synchronized upon successful authentication apps/web/src/app/api/auth/callback/route.ts:40-56.

Account Menu Component: The AccountMenu component displays user information and provides options to navigate to the dashboard or sign out.

<details className={cn('relative', className)}>
  <summary aria-label="Account menu" className="flex cursor-pointer">
    <UserRound className="h-4 w-4 text-zinc-400" />
    <span className="hidden sm:inline">Account</span>
    <ChevronDown className="h-4 w-4 text-zinc-400" />
  </summary>
  ...
</details>

This structure allows users to interact with their account settings easily apps/web/src/components/auth/account-menu.tsx:1-20.

Sign-In Page Logic: The SignInPage component handles the logic for displaying the sign-in interface and managing redirect paths based on session state.
```
const signInUrl = getGitHubSignInUrl({
  returnPathname,
  promptConsent: requiresConsent,
  state: requiresConsent ? 'github_scope' : undefined,
  loginHint: session?.user.email,
});
```
This snippet demonstrates how the sign-in URL is generated based on user session and required permissions apps/web/src/app/sign-in/page.tsx:40-56.

Key files