create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/plans/04-auth-system.md

@@ -0,0 +1,1466 @@
+# Authentication System Implementation Plan
+
+> **For AI Implementing This Plan:** This is document 04 of 13. Complete documents 01-03 first.
+
+**Goal:** Implement complete authentication system with login, logout, session management, and protected routes using PocketBase auth collection.
+
+**Architecture:** Admin-seeded authentication system (no public signup). Admin manages users through settings. Session persistence via PocketBase auth store + localStorage. Protected routes using higher-order components.
+
+**Tech Stack:** PocketBase auth, React hooks, Zustand state management, Zod validation, TanStack Query
+
+---
+
+## Prerequisites
+
+- ✅ Completed `01-infrastructure-setup.md`
+- ✅ Completed `02-pocketbase-setup.md` (users collection, seed data)
+- ✅ Completed `03-host-kernel.md` (host app, shared state, providers)
+
+---
+
+## Task 1: Create Auth Types and Interfaces
+
+**Files:**
+- Create: `host/src/kernel/auth/types.ts`
+- Create: `host/src/kernel/auth/schemas.ts`
+
+### Step 1: Create auth types
+
+**File:** `host/src/kernel/auth/types.ts`
+
+```typescript
+import type { RecordAuth } from 'pocketbase';
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+export interface RegisterData {
+  email: string;
+  password: string;
+  passwordConfirm: string;
+  name: string;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+  role?: string;
+  organizationId?: string;
+}
+
+export interface AuthResponse {
+  token: string;
+  user: User;
+}
+
+export interface AuthError {
+  message: string;
+  code?: number;
+}
+
+export interface SessionData {
+  token: string;
+  user: User;
+  organizationId?: string;
+}
+```
+
+### Step 2: Create Zod validation schemas
+
+**File:** `host/src/kernel/auth/schemas.ts`
+
+```typescript
+import { z } from 'zod';
+
+export const loginSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+export type LoginFormData = z.infer<typeof loginSchema>;
+
+export const registerSchema = z
+  .object({
+    email: z.string().email('Invalid email address'),
+    password: z
+      .string()
+      .min(8, 'Password must be at least 8 characters')
+      .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
+      .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
+      .regex(/[0-9]/, 'Password must contain at least one number'),
+    passwordConfirm: z.string(),
+    name: z.string().min(2, 'Name must be at least 2 characters'),
+  })
+  .refine((data) => data.password === data.passwordConfirm, {
+    message: 'Passwords do not match',
+    path: ['passwordConfirm'],
+  });
+
+export type RegisterFormData = z.infer<typeof registerSchema>;
+```
+
+---
+
+## Task 2: Create Auth Service
+
+**Files:**
+- Create: `host/src/kernel/auth/service.ts`
+
+### Step 1: Create auth service
+
+**File:** `host/src/kernel/auth/service.ts`
+
+```typescript
+import PocketBase from 'pocketbase';
+import type { LoginCredentials, RegisterData, User, AuthResponse, AuthError } from './types';
+import type { Record } from 'pocketbase';
+
+// Map PocketBase auth record to our User type
+function mapAuthRecordToUser(record: Record): User {
+  return {
+    id: record.id,
+    email: record.email,
+    name: record.name || record.email,
+    avatar: record.avatar,
+    role: record.role,
+    organizationId: record.organizationId,
+  };
+}
+
+export class AuthService {
+  constructor(private pb: PocketBase) {}
+
+  /**
+   * Login with email and password
+   */
+  async login(credentials: LoginCredentials): Promise<AuthResponse> {
+    try {
+      const authData = await this.pb.collection('users').authWithPassword(
+        credentials.email,
+        credentials.password
+      );
+
+      return {
+        token: authData.token,
+        user: mapAuthRecordToUser(authData.record),
+      };
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Register new user (admin only in our system)
+   */
+  async register(data: RegisterData, organizationId?: string): Promise<AuthResponse> {
+    try {
+      const record = await this.pb.collection('users').create({
+        email: data.email,
+        password: data.password,
+        passwordConfirm: data.passwordConfirm,
+        name: data.name,
+        organizationId,
+        role: 'member', // Default role
+      });
+
+      // Auto-login after registration
+      const authData = await this.pb.collection('users').authWithPassword(
+        data.email,
+        data.password
+      );
+
+      return {
+        token: authData.token,
+        user: mapAuthRecordToUser(authData.record),
+      };
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Logout current user
+   */
+  async logout(): Promise<void> {
+    this.pb.authStore.clear();
+    localStorage.removeItem('pocketbase_auth');
+  }
+
+  /**
+   * Get current authenticated user
+   */
+  getCurrentUser(): User | null {
+    if (!this.pb.authStore.isValid) return null;
+
+    const model = this.pb.authStore.model;
+    if (!model) return null;
+
+    return mapAuthRecordToUser(model);
+  }
+
+  /**
+   * Get current auth token
+   */
+  getToken(): string | null {
+    return this.pb.authStore.token;
+  }
+
+  /**
+   * Refresh auth token
+   */
+  async refreshToken(): Promise<string> {
+    try {
+      // PocketBase handles token refresh automatically
+      // This is a no-op but kept for interface consistency
+      return this.pb.authStore.token;
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Update user profile
+   */
+  async updateProfile(userId: string, data: Partial<User>): Promise<User> {
+    try {
+      const record = await this.pb.collection('users').update(userId, {
+        name: data.name,
+        avatar: data.avatar,
+      });
+
+      return mapAuthRecordToUser(record);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Change password
+   */
+  async changePassword(oldPassword: string, newPassword: string): Promise<void> {
+    try {
+      await this.pb.collection('users').update(this.pb.authStore.record?.id, {
+        oldPassword,
+        password: newPassword,
+        passwordConfirm: newPassword,
+      });
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Request password reset
+   */
+  async requestPasswordReset(email: string): Promise<void> {
+    try {
+      await this.pb.collection('users').requestPasswordReset(email);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Confirm password reset
+   */
+  async confirmPasswordReset(token: string, password: string): Promise<void> {
+    try {
+      await this.pb.collection('users').confirmPasswordReset(token, password, password);
+    } catch (error: any) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Handle PocketBase errors
+   */
+  private handleError(error: any): AuthError {
+    // PocketBase error format
+    if (error?.data?.message) {
+      return {
+        message: error.data.message,
+        code: error.status,
+      };
+    }
+
+    if (error?.message) {
+      return {
+        message: error.message,
+      };
+    }
+
+    return {
+      message: 'An unexpected error occurred',
+    };
+  }
+
+  /**
+   * Check if user is authenticated
+   */
+  isAuthenticated(): boolean {
+    return this.pb.authStore.isValid;
+  }
+
+  /**
+   * Listen to auth state changes
+   */
+  onAuthChange(callback: (token: string, record: Record | null) => void): () => void {
+    return this.pb.authStore.onChange(callback);
+  }
+}
+```
+
+---
+
+## Task 3: Create Auth Hooks
+
+**Files:**
+- Create: `host/src/kernel/auth/hooks.ts`
+
+### Step 1: Create auth hooks
+
+**File:** `host/src/kernel/auth/hooks.ts`
+
+```typescript
+import { useCallback, useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { usePocketBase } from '../providers';
+import { AuthService } from './service';
+import type { LoginCredentials, RegisterData, User } from './types';
+import { useGlobalKernelState } from '../shared-state';
+
+/**
+ * Get auth service instance
+ */
+function useAuthService(): AuthService | null {
+  const pb = usePocketBase();
+  if (!pb) return null;
+  return new AuthService(pb);
+}
+
+/**
+ * Main auth hook - provides auth state and actions
+ */
+export function useAuth() {
+  const pb = usePocketBase();
+  const queryClient = useQueryClient();
+  const { setUser, setToken, clearAuth, setIsLoading } = useGlobalKernelState();
+  const [authService, setAuthService] = useState<AuthService | null>(null);
+
+  // Initialize auth service
+  useEffect(() => {
+    if (pb) {
+      setAuthService(new AuthService(pb));
+
+      // Restore session from PocketBase auth store
+      if (pb.authStore.isValid && pb.authStore.model) {
+        setUser({
+          id: pb.authStore.model.id,
+          email: pb.authStore.model.email,
+          name: pb.authStore.model.name || pb.authStore.model.email,
+          avatar: pb.authStore.model.avatar,
+          role: pb.authStore.model.role,
+          organizationId: pb.authStore.model.organizationId,
+        });
+        setToken(pb.authStore.token);
+      }
+
+      setIsLoading(false);
+    }
+  }, [pb, setUser, setToken, setIsLoading]);
+
+  // Listen to auth state changes
+  useEffect(() => {
+    if (!pb) return;
+
+    const unsubscribe = pb.authStore.onChange((token, model) => {
+      if (model && token) {
+        setUser({
+          id: model.id,
+          email: model.email,
+          name: model.name || model.email,
+          avatar: model.avatar,
+          role: model.role,
+          organizationId: model.organizationId,
+        });
+        setToken(token);
+      } else {
+        clearAuth();
+      }
+    });
+
+    return unsubscribe;
+  }, [pb, setUser, setToken, clearAuth]);
+
+  const loginMutation = useMutation({
+    mutationFn: async (credentials: LoginCredentials) => {
+      if (!authService) throw new Error('Auth service not initialized');
+      return authService.login(credentials);
+    },
+    onSuccess: (data) => {
+      setUser(data.user);
+      setToken(data.token);
+      queryClient.invalidateQueries({ queryKey: ['auth', 'user'] });
+    },
+  });
+
+  const registerMutation = useMutation({
+    mutationFn: async (data: { registerData: RegisterData; organizationId?: string }) => {
+      if (!authService) throw new Error('Auth service not initialized');
+      return authService.register(data.registerData, data.organizationId);
+    },
+    onSuccess: (data) => {
+      setUser(data.user);
+      setToken(data.token);
+      queryClient.invalidateQueries({ queryKey: ['auth', 'user'] });
+    },
+  });
+
+  const logoutMutation = useMutation({
+    mutationFn: async () => {
+      if (!authService) throw new Error('Auth service not initialized');
+      return authService.logout();
+    },
+    onSuccess: () => {
+      clearAuth();
+      queryClient.clear();
+    },
+  });
+
+  const login = useCallback(
+    (credentials: LoginCredentials) => {
+      return loginMutation.mutateAsync(credentials);
+    },
+    [loginMutation]
+  );
+
+  const register = useCallback(
+    (registerData: RegisterData, organizationId?: string) => {
+      return registerMutation.mutateAsync({ registerData: registerData, organizationId });
+    },
+    [registerMutation]
+  );
+
+  const logout = useCallback(() => {
+    return logoutMutation.mutateAsync();
+  }, [logoutMutation]);
+
+  return {
+    user: authService?.getCurrentUser() || null,
+    isAuthenticated: !!pb?.authStore.isValid,
+    isLoading: loginMutation.isPending || registerMutation.isPending || logoutMutation.isPending,
+    login,
+    register,
+    logout,
+    error: loginMutation.error || registerMutation.error || logoutMutation.error,
+  };
+}
+
+/**
+ * Get current user data
+ */
+export function useCurrentUser() {
+  const { user, isAuthenticated } = useAuth();
+
+  const { data: currentUser, isLoading } = useQuery({
+    queryKey: ['auth', 'user'],
+    queryFn: () => Promise.resolve(user),
+    enabled: isAuthenticated,
+    staleTime: Infinity,
+  });
+
+  return {
+    user: currentUser,
+    isLoading,
+    isAuthenticated,
+  };
+}
+
+/**
+ * Require authentication - redirect if not logged in
+ */
+export function useRequireAuth() {
+  const { isAuthenticated, isLoading, user } = useAuth();
+  const [shouldRedirect, setShouldRedirect] = useState(false);
+
+  useEffect(() => {
+    if (!isLoading && !isAuthenticated) {
+      setShouldRedirect(true);
+    }
+  }, [isLoading, isAuthenticated]);
+
+  return {
+    user,
+    isAuthenticated,
+    isLoading,
+    shouldRedirect,
+  };
+}
+```
+
+---
+
+## Task 4: Create Protected Route Component
+
+**Files:**
+- Create: `host/src/kernel/auth/ProtectedRoute.tsx`
+
+### Step 1: Create protected route wrapper
+
+**File:** `host/src/kernel/auth/ProtectedRoute.tsx`
+
+```typescript
+import { useEffect } from 'react';
+import { useNavigate } from '@modern-js/runtime/router';
+import { useRequireAuth } from './hooks';
+import { Skeleton } from '../components/ui/skeleton';
+
+interface ProtectedRouteProps {
+  children: React.ReactNode;
+  redirectTo?: string;
+}
+
+export function ProtectedRoute({
+  children,
+  redirectTo = '/login',
+}: ProtectedRouteProps) {
+  const { isAuthenticated, isLoading, shouldRedirect } = useRequireAuth();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    if (shouldRedirect) {
+      navigate(redirectTo);
+    }
+  }, [shouldRedirect, navigate, redirectTo]);
+
+  if (isLoading) {
+    return (
+      <div className="flex min-h-[400px] items-center justify-center">
+        <div className="space-y-4 text-center">
+          <Skeleton className="mx-auto h-12 w-12 rounded-full" />
+          <Skeleton className="mx-auto h-4 w-48" />
+          <Skeleton className="mx-auto h-4 w-32" />
+        </div>
+      </div>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return null; // Will redirect
+  }
+
+  return <>{children}</>;
+}
+```
+
+---
+
+## Task 5: Create Login Page
+
+**Files:**
+- Create: `host/src/routes/login.tsx`
+- Create: `host/src/kernel/auth/components/LoginForm.tsx`
+
+### Step 1: Create login form component
+
+**File:** `host/src/kernel/auth/components/LoginForm.tsx`
+
+```typescript
+import { useState } from 'react';
+import { useNavigate } from '@modern-js/runtime/router';
+import { useAuth } from '../hooks';
+import { loginSchema, type LoginFormData } from '../schemas';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { Button } from '../../components/ui/button';
+import { Input } from '../../components/ui/input';
+import { Label } from '../../components/ui/label';
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../../components/ui/card';
+import { Alert, AlertDescription } from '../../components/ui/alert';
+import { Loader2 } from 'lucide-react';
+
+export function LoginForm() {
+  const navigate = useNavigate();
+  const { login, isLoading, error } = useAuth();
+  const [submitError, setSubmitError] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<LoginFormData>({
+    resolver: zodResolver(loginSchema),
+  });
+
+  const onSubmit = async (data: LoginFormData) => {
+    setSubmitError(null);
+    try {
+      await login(data);
+      navigate('/dashboard');
+    } catch (err: any) {
+      setSubmitError(err.message || 'Login failed. Please try again.');
+    }
+  };
+
+  return (
+    <Card className="w-full max-w-md">
+      <CardHeader>
+        <CardTitle className="text-2xl">Sign In</CardTitle>
+        <CardDescription>
+          Enter your credentials to access your account
+        </CardDescription>
+      </CardHeader>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <CardContent className="space-y-4">
+          {(submitError || error) && (
+            <Alert variant="destructive">
+              <AlertDescription>
+                {submitError || (error as any)?.message}
+              </AlertDescription>
+            </Alert>
+          )}
+
+          <div className="space-y-2">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              placeholder="admin@example.com"
+              {...register('email')}
+            />
+            {errors.email && (
+              <p className="text-sm text-destructive">{errors.email.message}</p>
+            )}
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              placeholder="••••••••"
+              {...register('password')}
+            />
+            {errors.password && (
+              <p className="text-sm text-destructive">{errors.password.message}</p>
+            )}
+          </div>
+        </CardContent>
+
+        <CardFooter>
+          <Button type="submit" className="w-full" disabled={isLoading}>
+            {isLoading ? (
+              <>
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                Signing in...
+              </>
+            ) : (
+              'Sign In'
+            )}
+          </Button>
+        </CardFooter>
+      </form>
+    </Card>
+  );
+}
+```
+
+### Step 2: Create login page route
+
+**File:** `host/src/routes/login.tsx`
+
+```typescript
+import { Link } from '@modern-js/runtime/router';
+import { LoginForm } from '../kernel/auth/components/LoginForm';
+import { useAuth } from '../kernel/auth/hooks';
+import { Navigate } from '@modern-js/runtime/router';
+
+export default function LoginPage() {
+  const { isAuthenticated } = useAuth();
+
+  if (isAuthenticated) {
+    return <Navigate to="/dashboard" replace />;
+  }
+
+  return (
+    <div className="flex min-h-[calc(100vh-4rem)] items-center justify-center p-6">
+      <div className="w-full max-w-md space-y-6">
+        {/* Logo and branding */}
+        <div className="text-center">
+          <div className="mx-auto flex h-12 w-12 items-center justify-center rounded-lg bg-primary text-primary-foreground text-xl font-bold">
+            L
+          </div>
+          <h1 className="mt-4 text-2xl font-bold">Lego-One</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Sign in to access your account
+          </p>
+        </div>
+
+        {/* Login form */}
+        <LoginForm />
+
+        {/* Help text */}
+        <div className="text-center text-sm text-muted-foreground">
+          <p>Default credentials: admin@example.com / admin123</p>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Task 6: Create Shadcn UI Components (Auth-Needed)
+
+**Files:**
+- Create: `host/src/kernel/components/ui/button.tsx`
+- Create: `host/src/kernel/components/ui/input.tsx`
+- Create: `host/src/kernel/components/ui/label.tsx`
+- Create: `host/src/kernel/components/ui/card.tsx`
+- Create: `host/src/kernel/components/ui/alert.tsx`
+
+### Step 1: Create button component
+
+**File:** `host/src/kernel/components/ui/button.tsx`
+
+```typescript
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../../../lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, ...props }, ref) => {
+    return (
+      <button
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };
+```
+
+### Step 2: Create input component
+
+**File:** `host/src/kernel/components/ui/input.tsx`
+
+```typescript
+import * as React from 'react';
+import { cn } from '../../../lib/utils';
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Input.displayName = 'Input';
+
+export { Input };
+```
+
+### Step 3: Create label component
+
+**File:** `host/src/kernel/components/ui/label.tsx`
+
+```typescript
+import * as React from 'react';
+import { cn } from '../../../lib/utils';
+
+export interface LabelProps
+  extends React.LabelHTMLAttributes<HTMLLabelElement> {}
+
+const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+  ({ className, ...props }, ref) => (
+    <label
+      ref={ref}
+      className={cn(
+        'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70',
+        className
+      )}
+      {...props}
+    />
+  )
+);
+Label.displayName = 'Label';
+
+export { Label };
+```
+
+### Step 4: Create card components
+
+**File:** `host/src/kernel/components/ui/card.tsx`
+
+```typescript
+import * as React from 'react';
+import { cn } from '../../../lib/utils';
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'rounded-lg border bg-card text-card-foreground shadow-sm',
+      className
+    )}
+    {...props}
+  />
+));
+Card.displayName = 'Card';
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex flex-col space-y-1.5 p-6', className)}
+    {...props}
+  />
+));
+CardHeader.displayName = 'CardHeader';
+
+const CardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      'text-2xl font-semibold leading-none tracking-tight',
+      className
+    )}
+    {...props}
+  />
+));
+CardTitle.displayName = 'CardTitle';
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('text-sm text-muted-foreground', className)}
+    {...props}
+  />
+));
+CardDescription.displayName = 'CardDescription';
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+));
+CardContent.displayName = 'CardContent';
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex items-center p-6 pt-0', className)}
+    {...props}
+  />
+));
+CardFooter.displayName = 'CardFooter';
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };
+```
+
+### Step 5: Create alert component
+
+**File:** `host/src/kernel/components/ui/alert.tsx`
+
+```typescript
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../../../lib/utils';
+
+const alertVariants = cva(
+  'relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground',
+  {
+    variants: {
+      variant: {
+        default: 'bg-background text-foreground',
+        destructive:
+          'border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+);
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div
+    ref={ref}
+    role="alert"
+    className={cn(alertVariants({ variant }), className)}
+    {...props}
+  />
+));
+Alert.displayName = 'Alert';
+
+const AlertTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h5
+    ref={ref}
+    className={cn('mb-1 font-medium leading-none tracking-tight', className)}
+    {...props}
+  />
+));
+AlertTitle.displayName = 'AlertTitle';
+
+const AlertDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('text-sm [&_p]:leading-relaxed', className)}
+    {...props}
+  />
+));
+AlertDescription.displayName = 'AlertDescription';
+
+export { Alert, AlertTitle, AlertDescription };
+```
+
+---
+
+## Task 7: Update Dependencies and Install react-hook-form
+
+**Files:**
+- Modify: `host/package.json`
+
+### Step 1: Add missing dependencies
+
+**File:** `host/package.json`
+
+Add to dependencies:
+```json
+{
+  "dependencies": {
+    "@hookform/resolvers": "^3.9.0",
+    "react-hook-form": "^7.53.0"
+  }
+}
+```
+
+### Step 2: Install new dependencies
+
+**Run:** From root directory
+
+```bash
+pnpm install
+```
+
+---
+
+## Task 8: Create Logout Functionality
+
+**Files:**
+- Create: `host/src/kernel/auth/components/LogoutButton.tsx`
+- Modify: `host/src/layout/Topbar.tsx`
+
+### Step 1: Create logout button component
+
+**File:** `host/src/kernel/auth/components/LogoutButton.tsx`
+
+```typescript
+import { useState } from 'react';
+import { useNavigate } from '@modern-js/runtime/router';
+import { useAuth } from '../hooks';
+import { Button } from '../../components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../../components/ui/dropdown-menu';
+import { Loader2, LogOut, Settings, User } from 'lucide-react';
+import { getInitials } from '../../lib/utils';
+import { useGlobalKernelState } from '../../shared-state';
+
+export function LogoutButton() {
+  const { logout, isLoading } = useAuth();
+  const navigate = useNavigate();
+  const { user } = useGlobalKernelState();
+  const [isLoggingOut, setIsLoggingOut] = useState(false);
+
+  const handleLogout = async () => {
+    setIsLoggingOut(true);
+    try {
+      await logout();
+      navigate('/login');
+    } finally {
+      setIsLoggingOut(false);
+    }
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" className="relative h-9 w-9 rounded-full">
+          {user?.name ? (
+            <span className="flex h-full w-full items-center justify-center bg-primary text-primary-foreground text-sm font-medium">
+              {getInitials(user.name)}
+            </span>
+          ) : (
+            <User className="h-5 w-5" />
+          )}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56" align="end" forceMount>
+        <DropdownMenuLabel className="font-normal">
+          <div className="flex flex-col space-y-1">
+            <p className="text-sm font-medium leading-none">{user?.name}</p>
+            <p className="text-xs leading-none text-muted-foreground">
+              {user?.email}
+            </p>
+          </div>
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={() => navigate('/settings/profile')}>
+          <User className="mr-2 h-4 w-4" />
+          <span>Profile</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={() => navigate('/settings')}>
+          <Settings className="mr-2 h-4 w-4" />
+          <span>Settings</span>
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          onClick={handleLogout}
+          disabled={isLoading || isLoggingOut}
+        >
+          {isLoggingOut ? (
+            <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+          ) : (
+            <LogOut className="mr-2 h-4 w-4" />
+          )}
+          <span>Log out</span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+```
+
+### Step 2: Create dropdown menu component
+
+**File:** `host/src/kernel/components/ui/dropdown-menu.tsx`
+
+```typescript
+import * as React from 'react';
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { Check, ChevronRight, Circle } from 'lucide-react';
+import { cn } from '../../../lib/utils';
+
+const DropdownMenu = DropdownMenuPrimitive.Root;
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
+const DropdownMenuGroup = DropdownMenuPrimitive.Group;
+const DropdownMenuPortal = DropdownMenuPrimitive.Portal;
+const DropdownMenuSub = DropdownMenuPrimitive.Sub;
+const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;
+
+const DropdownMenuSubTrigger = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubTrigger>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubTrigger> & {
+    inset?: boolean;
+  }
+>(({ className, inset, children, ...props }, ref) => (
+  <DropdownMenuPrimitive.SubTrigger
+    ref={ref}
+    className={cn(
+      'flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent data-[state=open]:bg-accent',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto h-4 w-4" />
+  </DropdownMenuPrimitive.SubTrigger>
+));
+DropdownMenuSubTrigger.displayName =
+  DropdownMenuPrimitive.SubTrigger.displayName;
+
+const DropdownMenuSubContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.SubContent
+    ref={ref}
+    className={cn(
+      'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+      className
+    )}
+    {...props}
+  />
+));
+DropdownMenuSubContent.displayName =
+  DropdownMenuPrimitive.SubContent.displayName;
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        className
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+));
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
+
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+  }
+>(({ className, inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  />
+));
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName;
+
+const DropdownMenuCheckboxItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.CheckboxItem>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.CheckboxItem>
+>(({ className, children, checked, ...props }, ref) => (
+  <DropdownMenuPrimitive.CheckboxItem
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    checked={checked}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.CheckboxItem>
+));
+DropdownMenuCheckboxItem.displayName =
+  DropdownMenuPrimitive.CheckboxItem.displayName;
+
+const DropdownMenuRadioItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.RadioItem>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.RadioItem>
+>(({ className, children, ...props }, ref) => (
+  <DropdownMenuPrimitive.RadioItem
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Circle className="h-2 w-2 fill-current" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.RadioItem>
+));
+DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName;
+
+const DropdownMenuLabel = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Label>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Label> & {
+    inset?: boolean;
+  }
+>(({ className, inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Label
+    ref={ref}
+    className={cn(
+      'px-2 py-1.5 text-sm font-semibold',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  />
+));
+DropdownMenuLabel.displayName = DropdownMenuPrimitive.Label.displayName;
+
+const DropdownMenuSeparator = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.Separator
+    ref={ref}
+    className={cn('-mx-1 my-1 h-px bg-muted', className)}
+    {...props}
+  />
+));
+DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName;
+
+const DropdownMenuShortcut = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) => {
+  return (
+    <span
+      className={cn('ml-auto text-xs tracking-widest opacity-60', className)}
+      {...props}
+    />
+  );
+};
+DropdownMenuShortcut.displayName = 'DropdownMenuShortcut';
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+};
+```
+
+### Step 3: Update topbar with logout button
+
+**File:** `host/src/layout/Topbar.tsx`
+
+```typescript
+import { useGlobalKernelState } from '../kernel/shared-state';
+import { Menu, Bell } from 'lucide-react';
+import { LogoutButton } from '../kernel/auth/components/LogoutButton';
+import { useAuth } from '../kernel/auth/hooks';
+
+export function Topbar() {
+  const { toggleMobileMenu } = useGlobalKernelState();
+  const { isAuthenticated } = useAuth();
+
+  return (
+    <header className="sticky top-0 z-20 flex h-16 items-center gap-4 border-b bg-background px-6">
+      {/* Mobile menu button */}
+      <button
+        onClick={toggleMobileMenu}
+        className="lg:hidden rounded-lg p-2 text-muted-foreground hover:bg-muted"
+      >
+        <Menu className="h-5 w-5" />
+      </button>
+
+      {/* Breadcrumb/spacer */}
+      <div className="flex-1" />
+
+      {/* Actions */}
+      <div className="flex items-center gap-2">
+        {isAuthenticated && (
+          <button className="rounded-lg p-2 text-muted-foreground hover:bg-muted">
+            <Bell className="h-5 w-5" />
+          </button>
+        )}
+
+        {isAuthenticated && <LogoutButton />}
+      </div>
+    </header>
+  );
+}
+```
+
+---
+
+## Task 9: Create Auth Module Barrel Export
+
+**Files:**
+- Create: `host/src/kernel/auth/index.ts`
+
+### Step 1: Create barrel export
+
+**File:** `host/src/kernel/auth/index.ts`
+
+```typescript
+export * from './types';
+export * from './schemas';
+export * from './service';
+export * from './hooks';
+export * from './ProtectedRoute';
+```
+
+---
+
+## Verification
+
+### Step 1: Build the host
+
+**Run:**
+
+```bash
+cd host
+pnpm run build
+```
+
+Expected: Build completes without errors.
+
+### Step 2: Start development server
+
+**Run:**
+
+```bash
+cd host
+pnpm run dev
+```
+
+Expected: Server starts on http://localhost:8080
+
+### Step 3: Test login flow
+
+1. Open http://localhost:8080
+2. Click "Sign In" button
+3. Enter credentials: `admin@example.com` / `admin123`
+4. Submit form
+5. Should redirect to `/dashboard`
+6. Verify logout button appears in topbar with user avatar
+7. Click logout button → "Log out"
+8. Should redirect back to `/login`
+
+### Step 4: Test protected routes
+
+1. Try accessing http://localhost:8080/dashboard while logged out
+2. Should redirect to `/login`
+3. After login, should access dashboard successfully
+
+---
+
+## Summary
+
+After completing this document, you will have:
+
+1. ✅ Complete authentication service with PocketBase integration
+2. ✅ Login page with form validation using Zod + react-hook-form
+3. ✅ Protected route component for guarding authenticated pages
+4. ✅ Auth hooks: `useAuth`, `useCurrentUser`, `useRequireAuth`
+5. ✅ Logout functionality with dropdown menu
+6. ✅ Session persistence via PocketBase auth store
+7. ✅ Error handling for auth failures
+8. ✅ All required Shadcn UI components (Button, Input, Label, Card, Alert, DropdownMenu)
+
+**Next:** `05-multitenancy-rbac.md` - Implement organizations, users management, roles, and permissions system.
+
+---
+
+## Files Created
+
+```
+host/
+└── src/
+    └── kernel/
+        ├── auth/
+        │   ├── types.ts
+        │   ├── schemas.ts
+        │   ├── service.ts
+        │   ├── hooks.ts
+        │   ├── ProtectedRoute.tsx
+        │   ├── components/
+        │   │   └── LoginForm.tsx
+        │   └── index.ts
+        ├── components/
+        │   └── ui/
+        │       ├── button.tsx
+        │       ├── input.tsx
+        │       ├── label.tsx
+        │       ├── card.tsx
+        │       ├── alert.tsx
+        │       └── dropdown-menu.tsx
+        └── layout/
+            └── Topbar.tsx (modified)
+
+host/src/routes/
+└── login.tsx
+```