feat: WIP solution for authentication (issue #24)

Author: danieldanielecki

AUTHENTICATION_SETUP.md

@@ -0,0 +1,150 @@
+# Authentication Setup Guide
+
+This guide will help you set up Appwrite authentication for your Practice Exams Platform.
+
+## Prerequisites
+
+1. An Appwrite account (sign up at [appwrite.io](https://appwrite.io))
+2. A new Appwrite project
+
+## Step 1: Create Appwrite Project
+
+1. Log in to your Appwrite console
+2. Click "Create Project"
+3. Give your project a name (e.g., "Practice Exams Platform")
+4. Choose your preferred region
+5. Click "Create"
+
+## Step 2: Configure Authentication
+
+### Enable Authentication Methods
+
+1. In your project dashboard, go to **Auth** → **Settings**
+2. Enable the following authentication methods:
+   - **Email/Password** (for OTP)
+   - **Google OAuth**
+   - **Apple OAuth**
+
+### Configure OAuth Providers
+
+#### Google OAuth
+
+1. Go to **Auth** → **OAuth2 Providers**
+2. Click on **Google**
+3. Enable the provider
+4. Add your Google OAuth credentials:
+   - Client ID
+   - Client Secret
+5. Set redirect URL: `https://yourdomain.com/auth/callback`
+
+#### Apple OAuth
+
+1. Go to **Auth** → **OAuth2 Providers**
+2. Click on **Apple**
+3. Enable the provider
+4. Add your Apple OAuth credentials:
+   - Client ID
+   - Client Secret
+   - Team ID
+5. Set redirect URL: `https://yourdomain.com/auth/callback`
+
+### Configure Email Templates
+
+1. Go to **Auth** → **Templates**
+2. Customize the email templates for:
+   - Magic URL (email OTP)
+   - Email verification
+
+## Step 3: Environment Variables
+
+Create a `.env.local` file in your project root with:
+
+```bash
+NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+NEXT_PUBLIC_APPWRITE_PROJECT_ID=your_project_id_here
+```
+
+Replace `your_project_id_here` with your actual Appwrite project ID.
+
+## Step 4: Update Callback URLs
+
+In your Appwrite project settings, add these callback URLs:
+
+- **Success URL**: `https://yourdomain.com/auth/callback?success=true`
+- **Failure URL**: `https://yourdomain.com/auth/callback?failure=true`
+
+## Step 5: Test Authentication
+
+1. Start your development server
+2. Navigate to any practice or exam page
+3. You should see the 15-minute trial timer
+4. After 15 minutes, the authentication modal should appear
+5. Test all three authentication methods:
+   - Email OTP
+   - Google OAuth
+   - Apple OAuth
+
+## Features Implemented
+
+### Authentication Methods
+
+- **Email OTP**: Magic link authentication via email
+- **Google OAuth**: Sign in with Google account
+- **Apple OAuth**: Sign in with Apple ID
+
+### Trial System
+
+- **15-minute trial** for unauthenticated users
+- **Automatic blocking** after trial expires
+- **Persistent trial state** across browser sessions
+- **Visual indicators** for trial status
+
+### User Experience
+
+- **Seamless integration** with existing UI
+- **Responsive design** for mobile and desktop
+- **User profile management** in navigation
+- **Automatic redirects** after authentication
+
+## PWA Compatibility
+
+This authentication system is fully compatible with PWA Builder for:
+
+- **Android** deployment
+- **iOS** deployment
+- **Microsoft Store** deployment
+
+The authentication flow works seamlessly across all platforms.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **OAuth redirect errors**: Ensure callback URLs are correctly configured
+2. **Email not sending**: Check Appwrite email service configuration
+3. **Trial timer not working**: Clear localStorage and refresh page
+4. **Authentication state not persisting**: Check browser console for errors
+
+### Debug Mode
+
+Enable debug logging by adding to your `.env.local`:
+
+```bash
+NEXT_PUBLIC_DEBUG_AUTH=true
+```
+
+## Security Considerations
+
+- All authentication is handled server-side by Appwrite
+- No sensitive credentials are stored in the frontend
+- Session management is handled securely by Appwrite
+- OAuth tokens are never exposed to the client
+
+## Next Steps
+
+After setup, consider:
+
+1. Adding user profile management
+2. Implementing role-based access control
+3. Adding analytics for user engagement
+4. Setting up email notifications for user actions

app/auth/callback/page.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
+import { AuthService } from "../../../lib/appwrite/auth";
+import LoadingIndicator from "../../../components/LoadingIndicator";
+
+export default function AuthCallback() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const [status, setStatus] = useState<"loading" | "success" | "error">(
+    "loading",
+  );
+  const [message, setMessage] = useState("");
+
+  useEffect(() => {
+    const handleCallback = async () => {
+      try {
+        // Check if this is an OAuth callback
+        const userId = searchParams.get("userId");
+        const secret = searchParams.get("secret");
+        const success = searchParams.get("success");
+        const failure = searchParams.get("failure");
+
+        if (failure) {
+          setStatus("error");
+          setMessage("Authentication failed. Please try again.");
+          setTimeout(() => router.push("/"), 3000);
+          return;
+        }
+
+        if (success === "true") {
+          setStatus("success");
+          setMessage("Authentication successful! Redirecting...");
+          setTimeout(() => router.push("/"), 2000);
+          return;
+        }
+
+        // Handle magic link callback
+        if (userId && secret) {
+          const result = await AuthService.updateEmailSession(userId, secret);
+          if (result.success) {
+            setStatus("success");
+            setMessage("Email verified successfully! Redirecting...");
+            setTimeout(() => router.push("/"), 2000);
+          } else {
+            setStatus("error");
+            setMessage(result.error?.message || "Verification failed");
+            setTimeout(() => router.push("/"), 3000);
+          }
+          return;
+        }
+
+        // If no callback parameters, redirect to home
+        router.push("/");
+      } catch (error) {
+        setStatus("error");
+        setMessage("An error occurred during authentication");
+        setTimeout(() => router.push("/"), 3000);
+      }
+    };
+
+    handleCallback();
+  }, [router, searchParams]);
+
+  if (status === "loading") {
+    return (
+      <div className="min-h-screen bg-slate-900 flex items-center justify-center">
+        <div className="text-center">
+          <LoadingIndicator />
+          <p className="text-white mt-4">Processing authentication...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen bg-slate-900 flex items-center justify-center">
+      <div className="text-center">
+        {status === "success" ? (
+          <div className="w-16 h-16 bg-green-500 rounded-full flex items-center justify-center mx-auto mb-4">
+            <svg
+              className="w-8 h-8 text-white"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M5 13l4 4L19 7"
+              />
+            </svg>
+          </div>
+        ) : (
+          <div className="w-16 h-16 bg-red-500 rounded-full flex items-center justify-center mx-auto mb-4">
+            <svg
+              className="w-8 h-8 text-white"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </div>
+        )}
+
+        <h2 className="text-2xl font-bold text-white mb-2">
+          {status === "success" ? "Success!" : "Error"}
+        </h2>
+        <p className="text-slate-300 mb-4">{message}</p>
+
+        <button
+          onClick={() => router.push("/")}
+          className="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700 transition-colors"
+        >
+          Go to Home
+        </button>
+      </div>
+    </div>
+  );
+}

app/exam/page.tsx

@@ -9,6 +9,7 @@ import QuizExamForm from "@azure-fundamentals/components/QuizExamFormUF";
 import { Question } from "@azure-fundamentals/components/types";
 import ExamResult from "@azure-fundamentals/components/ExamResult";
 import LoadingIndicator from "@azure-fundamentals/components/LoadingIndicator";
+import { useTrialAccess } from "@azure-fundamentals/hooks/useTrialAccess";
 
 const questionsQuery = gql`
   query RandomQuestions($range: Int!, $link: String) {
@@ -29,6 +30,7 @@ const questionsQuery = gql`
 const Exam: NextPage<{ searchParams: { url: string; name: string } }> = ({
   searchParams,
 }) => {
+  const { isAccessBlocked, isInTrial } = useTrialAccess();
   const { url } = searchParams;
   const { minutes, seconds } = {
     minutes: 15,
@@ -87,13 +89,57 @@ const Exam: NextPage<{ searchParams: { url: string; name: string } }> = ({
     setCurrentQuestion(data?.randomQuestions[0]);
   }, [data]);
 
+  // Show loading while checking trial access
+  if (isAccessBlocked === undefined) {
+    return <LoadingIndicator />;
+  }
+
+  // Block access if trial expired
+  if (isAccessBlocked) {
+    return (
+      <div className="py-10 px-5 mb-6 mx-auto w-[90vw] lg:w-[60vw] 2xl:w-[45%] bg-slate-800 border-2 border-slate-700 rounded-lg text-center">
+        <div className="text-red-400 text-lg mb-4">
+          ⏰ Trial expired. Please sign in to continue taking exams.
+        </div>
+        <button
+          onClick={() => (window.location.href = "/")}
+          className="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700 transition-colors"
+        >
+          Go to Home
+        </button>
+      </div>
+    );
+  }
+
   if (loading) return <LoadingIndicator />;
   if (error) return <p>Oh no... {error.message}</p>;
 
   const numberOfQuestions = data.randomQuestions.length || 0;
 
   return (
     <div className="py-10 px-5 mb-6 mx-auto w-[90vw] lg:w-[60vw] 2xl:w-[45%] bg-slate-800 border-2 border-slate-700 rounded-lg">
+      {isInTrial && (
+        <div className="mb-6 p-4 bg-amber-600/20 border border-amber-600/40 rounded-lg">
+          <div className="flex items-center gap-2 text-amber-300">
+            <svg
+              className="w-5 h-5"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"
+              />
+            </svg>
+            <span className="font-medium">
+              Trial Mode - Sign in to unlock unlimited access
+            </span>
+          </div>
+        </div>
+      )}
       <div>
         <div className="px-2 sm:px-10 w-full flex flex-row justify-between items-center">
           <p className="text-white font-bold text-sm sm:text-2xl">

app/layout.tsx

@@ -4,6 +4,8 @@ import TopNav from "@azure-fundamentals/components/TopNav";
 import Footer from "@azure-fundamentals/components/Footer";
 import ApolloProvider from "@azure-fundamentals/components/ApolloProvider";
 import Cookie from "@azure-fundamentals/components/Cookie";
+import { AuthProvider } from "@azure-fundamentals/contexts/AuthContext";
+import { TrialWarning } from "@azure-fundamentals/components/TrialWarning";
 import "styles/globals.css";
 
 export const viewport: Viewport = {
@@ -106,12 +108,15 @@ export default function RootLayout({ children }: RootLayoutProps) {
     <html lang="en">
       <body className="bg-slate-900">
         <ApolloProvider>
-          <TopNav />
-          <main className="flex flex-col justify-between md:h-[calc(100vh-2.5rem-64px)] h-full">
-            {children}
-            <Footer />
-            <Cookie />
-          </main>
+          <AuthProvider>
+            <TopNav />
+            <main className="flex flex-col justify-between md:h-[calc(100vh-2.5rem-64px)] h-full">
+              {children}
+              <Footer />
+              <Cookie />
+              <TrialWarning />
+            </main>
+          </AuthProvider>
         </ApolloProvider>
       </body>
     </html>