mulguard 1.1.6 → 1.1.7

package/README.md

@@ -1,76 +1,66 @@
 # Mulguard
 
-> A modern, backend-first authentication library for Next.js applications
+> A modern, production-ready authentication library for Next.js 16+ (App Router)
 
 [![License: MUV](https://img.shields.io/badge/License-MUV-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
-[![Next.js](https://img.shields.io/badge/Next.js-14.0+-black.svg)](https://nextjs.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-16.0+-black.svg)](https://nextjs.org/)
 
-**Mulguard** is a powerful, flexible authentication library designed specifically for Next.js applications. Built with a backend-first architecture, it gives you complete control over your authentication logic while providing a simple, intuitive API similar to popular libraries like `better-auth` and `auth.js`.
+**Mulguard** is a powerful, flexible authentication library designed specifically for Next.js 16+ applications. Built with a **backend-first architecture**, it gives you complete control over your authentication logic while providing a simple, intuitive API.
 
 **Part of the [Mulverse](https://mulverse.com) ecosystem** - Empowering modern web applications with robust, secure authentication.
 
 ---
 
-## Table of Contents
-
-- [Features](#-features)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Core Concepts](#-core-concepts)
-- [Authentication Methods](#-authentication-methods)
-- [Configuration](#-configuration)
-- [Server-Side Usage](#-server-side-usage)
-- [Client-Side Usage](#-client-side-usage)
-- [Components](#-components)
-- [Security](#-security)
-- [Backend Integration](#-backend-integration)
-- [Advanced Features](#-advanced-features)
-- [API Reference](#-api-reference)
-- [Examples](#-examples)
-- [Testing](#-testing)
-- [Contributing](#-contributing)
-- [License](#-license)
-- [Support](#-support)
-
----
-
 ## ✨ Features
 
 ### 🔐 Multiple Authentication Methods
-- **Email/Password** - Traditional credential-based authentication
-- **OAuth 2.1** - Support for Google, GitHub, and other OAuth providers
-- **PassKey/WebAuthn** - Passwordless authentication with biometric support
-- **Two-Factor Authentication (2FA/TOTP)** - Time-based one-time passwords with backup codes
+- **Email/Password** - Traditional email and password authentication
+- **OAuth 2.0 with PKCE** - Support for Google, GitHub, and other OAuth providers with automatic PKCE
 - **OTP** - One-time password authentication
+- **PassKey/WebAuthn** - Passwordless authentication (coming soon)
+- **Two-Factor Authentication (2FA/TOTP)** - Multi-factor authentication support
 
-### 🎯 Account Picker
-- Remember last logged-in users
-- Quick re-login experience
-- Encrypted local storage for security
-- Configurable account limits
+### ⚡ Performance
+- **Edge Runtime Support** - Optimized for Edge Runtime where possible
+- **Session Caching** - Built-in session caching for improved performance
+- **Optimized Bundle Size** - Tree-shakeable with minimal bundle impact
+- **Server Actions First** - Leverages Next.js Server Actions for optimal performance
 
 ### 🔒 Security First
-- **CSRF Protection** - Token-based cross-site request forgery protection
-- **XSS Prevention** - Input sanitization and HTML escaping
-- **Security Headers** - Automatic security headers configuration
-- **Input Validation** - Comprehensive validation and sanitization
-- **Rate Limiting** - Built-in rate limiting utilities
-- **Secure Cookies** - HttpOnly, Secure, SameSite cookie configuration
-
-### ⚡ Next.js Optimized
-- **Server Components** - Full support for React Server Components
-- **Client Hooks** - `useAuth`, `useSession` for client-side state management
-- **Middleware Integration** - Seamless Next.js middleware support
-- **API Route Handlers** - Pre-built route handlers for authentication endpoints
-- **Server Actions** - Native support for Next.js Server Actions
-
-### 🔌 Backend-First Architecture
-- **No Database Adapter Required** - Works with your existing backend API
-- **Custom Actions** - Implement your own authentication logic
-- **Flexible Integration** - Works with any backend (REST, GraphQL, etc.)
-- **Mulink Integration** - Optional integration with Mulink API client
-- **Full TypeScript Support** - Complete type safety throughout
+- **HttpOnly Cookies** - Secure cookie handling prevents XSS attacks
+- **PKCE for OAuth** - Automatic PKCE implementation for OAuth flows
+- **CSRF Protection** - Built-in CSRF token validation
+- **Rate Limiting** - Configurable rate limiting to prevent brute force attacks
+- **Input Validation** - Comprehensive input validation and sanitization
+- **XSS Prevention** - Automatic XSS protection for user inputs
+
+### 🎯 Developer Experience
+- **Type-Safe** - Full TypeScript support with generics and type inference
+- **Simple Setup** - Get started in minutes with minimal configuration
+- **Clear Errors** - Descriptive error messages with error codes
+- **Centralized Logging** - Professional logging system (no manual `console.log` needed)
+- **Unified API** - Single, consistent interface for all authentication methods
+
+### 🔌 Flexible & Extensible
+- **Backend-First** - Works with any backend or database (Prisma, Drizzle, MongoDB, etc.)
+- **Custom Actions** - Implement your own authentication logic without adapters
+- **Plugin System** - Extensible architecture for additional features
+- **Next.js 16+ Proxy** - Uses Proxy pattern instead of middleware (Next.js 16+)
+
+---
+
+## 🎯 Why Mulguard?
+
+### Problems We Solve
+
+- ✅ **High Stability** - Production-ready library without common bugs
+- ✅ **Simple Setup** - Quick and easy setup without complexity
+- ✅ **No console.log Needed** - Professional centralized logging system
+- ✅ **No SSR/CSR Issues** - Clear separation between server-side and client-side
+- ✅ **Easy OAuth** - Simple OAuth setup with automatic PKCE
+- ✅ **Excellent Error Handling** - Clear and coded error messages
+- ✅ **Type Safety** - Full TypeScript support with generics
 
 ---
 
@@ -82,10 +72,8 @@ npm install mulguard
 
 ### Peer Dependencies
 
-Mulguard requires the following peer dependencies:
-
 ```bash
-npm install next@>=14.0.0 react@>=18.0.0 react-dom@>=18.0.0
+npm install next@>=16.0.0 react@>=18.0.0 react-dom@>=18.0.0
 ```
 
 ---
@@ -103,19 +91,18 @@ import { db } from '@/lib/db'
 import { comparePassword } from '@/lib/password'
 
 export const auth = mulguard({
-  // Session configuration
+  // Session configuration (optional)
   session: {
     cookieName: '__mulguard_session',
     expiresIn: 60 * 60 * 24 * 7, // 7 days
     httpOnly: true,
-    secure: process.env.NODE_ENV === 'production', // HTTPS only in production
+    secure: process.env.NODE_ENV === 'production',
     sameSite: 'lax',
   },
   
   // Required: Implement your authentication actions
   actions: {
     signIn: {
-      // ✅ Unified interface: auth.signIn('credentials', {...}) or auth.signIn.email({...})
       email: async (credentials: EmailCredentials): Promise<AuthResult> => {
         // Your custom sign-in logic
         const user = await db.user.findUnique({ 
@@ -146,14 +133,13 @@ export const auth = mulguard({
     
     getSession: async (): Promise<Session | null> => {
       // Your custom session retrieval logic
-      // Can read from cookie or database
-      return await db.getSession()
+      // The library handles cookie reading automatically
+      return null
     },
     
-    signOut: async () => {
+    signOut: async (): Promise<void> => {
       // Your custom sign-out logic
-      await db.invalidateSession()
-      return { success: true }
+      // The library handles cookie deletion automatically
     },
   },
   
@@ -162,15 +148,10 @@ export const auth = mulguard({
     oauth: {
       google: {
         clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET, // Server-side only
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
         redirectUri: `${process.env.NEXT_PUBLIC_URL}/api/auth/callback/google`,
         scopes: ['openid', 'profile', 'email'],
-      },
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET,
-        redirectUri: `${process.env.NEXT_PUBLIC_URL}/api/auth/callback/github`,
-        scopes: ['user:email'],
+        pkce: true, // Enable PKCE (recommended)
       },
     },
   },
@@ -179,53 +160,26 @@ export const auth = mulguard({
   callbacks: {
     onSignIn: async (user, session) => {
       // Track sign-in analytics, update last login, etc.
-      console.log('User signed in:', user.email)
     },
     onError: async (error, context) => {
-      // Log errors for monitoring
-      console.error(`Auth error in ${context}:`, error)
-    },
-    // ✅ OAuth callback: receives userInfo with accessToken, refreshToken, profile, etc.
-    onOAuthUser: async (userInfo, provider) => {
-      // Backend API example:
-      // const response = await fetch('/api/v1/auth/oauth/callback', {
-      //   method: 'POST',
-      //   body: JSON.stringify({
-      //     provider,
-      //     access_token: userInfo.accessToken,
-      //     refresh_token: userInfo.refreshToken,
-      //     profile: userInfo,
-      //     email: userInfo.email,
-      //   })
-      // })
-      // return await response.json()
-      
-      // Database example:
-      let user = await db.user.findUnique({ where: { email: userInfo.email } })
-      if (!user) {
-        user = await db.user.create({
-          data: {
-            email: userInfo.email,
-            name: userInfo.name,
-            emailVerified: userInfo.emailVerified,
-            oauthProvider: provider,
-          }
-        })
-      }
-      return {
-        id: user.id,
-        email: user.email,
-        name: user.name,
-        emailVerified: user.emailVerified,
-      }
+      // Log errors for monitoring (centralized logging, no console.log needed)
     },
   },
 })
 ```
 
-> 📖 **For a complete guide with best practices**, see [GUIDE.md](./GUIDE.md)
+### 2. Create Route Handler
+
+Create `app/api/auth/[...mulguard]/route.ts`:
+
+```typescript
+import { toNextJsHandler } from 'mulguard/handlers/route'
+import { auth } from '@/lib/auth'
+
+export const { GET, POST } = toNextJsHandler(auth)
+```
 
-### 2. Server-Side Usage
+### 3. Server-Side Usage
 
 ```typescript
 // app/dashboard/page.tsx
@@ -249,7 +203,7 @@ export default async function DashboardPage() {
 }
 ```
 
-### 3. Client-Side Usage
+### 4. Client-Side Usage
 
 ```typescript
 // app/login/page.tsx
@@ -260,216 +214,112 @@ import { auth } from '@/lib/auth'
 import { useState } from 'react'
 
 export default function LoginPage() {
-  const { signIn, session, isLoading } = useAuth(auth)
-  const [email, setEmail] = useState('')
-  const [password, setPassword] = useState('')
+  const { signIn, isLoading } = useAuth(auth)
+  const [error, setError] = useState<string | null>(null)
 
-  const handleSubmit = async (e: React.FormEvent) => {
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
     e.preventDefault()
+    setError(null)
     
-    // ✅ Unified interface (recommended)
-    const result = await signIn('credentials', { email, password })
-    
-    // Or use direct method:
-    // const result = await signIn.email({ email, password })
+    const formData = new FormData(e.currentTarget)
+    const result = await signIn('credentials', {
+      email: formData.get('email') as string,
+      password: formData.get('password') as string,
+    })
     
     if (result.success) {
-      // Redirect to dashboard
       window.location.href = '/dashboard'
     } else {
-      // Handle error
-      alert(result.error)
+      setError(result.error || 'Login failed')
     }
   }
 
-  if (isLoading) return <div>Loading...</div>
-  if (session) return <div>Already logged in</div>
-
   return (
     <form onSubmit={handleSubmit}>
-      <input
-        type="email"
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-        placeholder="Email"
-        required
-      />
-      <input
-        type="password"
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-        placeholder="Password"
-        required
-      />
-      <button type="submit">Sign In</button>
+      <input name="email" type="email" placeholder="Email" required />
+      <input name="password" type="password" placeholder="Password" required />
+      {error && <p className="error">{error}</p>}
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? 'Signing in...' : 'Sign In'}
+      </button>
     </form>
   )
 }
 ```
 
-### 4. Middleware (Optional)
+### 5. Route Protection (Optional)
+
+Create `proxy.ts` in your project root:
 
 ```typescript
-// middleware.ts
-import { createAuthMiddleware } from 'mulguard/middleware'
+// proxy.ts (Next.js 16+)
+import { createProxyMiddleware } from 'mulguard/proxy'
 import { auth } from '@/lib/auth'
 
-export default createAuthMiddleware(auth, {
+export default createProxyMiddleware(auth, {
   protectedRoutes: ['/dashboard', '/profile'],
   redirectTo: '/login',
   redirectIfAuthenticated: '/dashboard',
 })
 
 export const config = {
-  matcher: ['/dashboard/:path*', '/profile/:path*'],
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
 }
 ```
 
----
-
-## 🎓 Core Concepts
-
-### Backend-First Architecture
-
-Mulguard follows a **backend-first** approach, meaning you implement your own authentication logic through **actions**. This gives you:
-
-- **Full Control** - Complete control over your authentication flow
-- **Flexibility** - Works with any backend architecture
-- **No Lock-in** - No database adapter required
-- **Custom Logic** - Implement business-specific authentication rules
-
-### Actions
-
-Actions are functions you provide to handle authentication operations:
-
-```typescript
-actions: {
-  signIn: {
-    email: async (credentials) => { /* ... */ },
-    oauth: async (provider) => { /* ... */ },
-    passkey: async (options) => { /* ... */ },
-  },
-  signUp: async (data) => { /* ... */ },
-  signOut: async () => { /* ... */ },
-  getSession: async () => { /* ... */ },
-  // ... more actions
-}
-```
-
-### Sessions
-
-Sessions are stored in HTTP-only cookies and contain:
-
-```typescript
-interface Session {
-  user: {
-    id: string
-    email: string
-    name?: string
-    avatar?: string
-    emailVerified?: boolean
-  }
-  expiresAt: Date
-  accessToken?: string
-  refreshToken?: string
-  tokenType?: string
-  expiresIn?: number
-}
-```
+> **Note**: In Next.js 16+, `middleware.ts` has been replaced with `proxy.ts`. Mulguard uses the Proxy pattern for route protection.
 
 ---
 
-## 🔐 Authentication Methods
+## 📋 API Overview
 
 ### Unified Sign-In Interface
 
-Mulguard provides a **unified interface** for all authentication methods, similar to auth.js:
+Mulguard provides a unified, type-safe API for all authentication methods:
 
 ```typescript
 // ✅ Unified interface (recommended)
-await auth.signIn('credentials', { email: 'user@example.com', password: 'password123' })
+await auth.signIn('credentials', { email, password })
 await auth.signIn('google')
-await auth.signIn('otp', { email: 'user@example.com', code: '123456' })
-await auth.signIn('passkey', { userId: 'user-id' })
+await auth.signIn('otp', { email, code })
 
-// ✅ Direct methods (for backward compatibility)
-await auth.signIn.email({ email: 'user@example.com', password: 'password123' })
+// ✅ Direct methods (also available)
+await auth.signIn.email({ email, password })
 await auth.signIn.oauth('google')
-await auth.signIn.otp('user@example.com', '123456')
 ```
 
-### Email/Password Authentication
+### Type Safety
+
+Full TypeScript support with generics:
 
 ```typescript
-// Using unified interface
-const result = await auth.signIn('credentials', {
-  email: 'user@example.com',
-  password: 'password123',
-})
+import type { User, Session } from 'mulguard'
 
-// Or using direct method
-const result = await auth.signIn.email({
-  email: 'user@example.com',
-  password: 'password123',
+const auth = mulguard<User, Session>({
+  // Type-safe configuration
+  actions: {
+    signIn: {
+      email: async (credentials) => {
+        // TypeScript knows the return type
+        return { success: true, user, session }
+      },
+    },
+  },
 })
 
+// Type-safe results
+const result = await auth.signIn('credentials', { email, password })
 if (result.success) {
-  console.log('Signed in:', result.user)
-} else {
-  console.error('Error:', result.error, result.errorCode)
+  // result.user and result.session are fully typed
+  console.log(result.user.email)
 }
 ```
 
-### OAuth Authentication
-
-```typescript
-// Initiate OAuth flow (unified interface)
-const { url } = await auth.signIn('google')
-window.location.href = url
-
-// Or using direct method
-const { url } = await auth.signIn.oauth('google')
-window.location.href = url
-
-// Handle callback (in your API route)
-const result = await auth.oauthCallback(provider, code, state)
-
-// ✅ OAuth providers are auto-configured when you add them to providers.oauth
-// No need to implement oauth action manually!
-```
-
-### PassKey/WebAuthn Authentication
-
-```typescript
-// Register PassKey
-const result = await auth.passkey.register({
-  name: 'My iPhone',
-  userId: 'user-id',
-})
-
-// Authenticate with PassKey
-const result = await auth.signIn.passkey({ userId: 'user-id' })
-```
-
-### Two-Factor Authentication (2FA)
-
-```typescript
-// Enable 2FA
-const enableResult = await auth.twoFactor.enable()
-// Display QR code to user
-
-// Verify 2FA code
-const verifyResult = await auth.twoFactor.verify('123456')
-
-// Check if 2FA is enabled
-const isEnabled = await auth.twoFactor.isEnabled()
-```
-
 ---
 
 ## ⚙️ Configuration
 
-### Full Configuration Options
+### Complete Configuration Example
 
 ```typescript
 import { mulguard } from 'mulguard'
@@ -478,167 +328,130 @@ export const auth = mulguard({
   // Session configuration
   session: {
     cookieName: '__mulguard_session',
-    expiresIn: 60 * 60 * 24 * 7, // 7 days in seconds
+    expiresIn: 60 * 60 * 24 * 7, // 7 days (in seconds)
     httpOnly: true,
     secure: process.env.NODE_ENV === 'production',
     sameSite: 'lax',
     path: '/',
-    domain: undefined,
-    cacheTtl: 5000, // Session cache TTL in milliseconds
   },
-  
-  // Required: Authentication actions
+
+  // Required: Custom authentication actions
   actions: {
     signIn: {
-      email: async (credentials) => { /* ... */ },
-      // Optional: oauth, passkey, otp
+      email: async (credentials) => {
+        // Your custom logic
+      },
+    },
+    signUp: async (data) => {
+      // Your custom logic
+    },
+    getSession: async () => {
+      // Your custom logic
+    },
+    signOut: async () => {
+      // Your custom logic
     },
-    getSession: async () => { /* ... */ },
-    signOut: async () => { /* ... */ },
-    // Optional: signUp, resetPassword, verifyEmail, refreshSession, etc.
   },
-  
+
   // Optional: OAuth providers
   providers: {
     oauth: {
       google: {
-        clientId: '...',
-        clientSecret: '...', // Server-side only
-        redirectUri: '...',
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        redirectUri: `${process.env.NEXT_PUBLIC_URL}/api/auth/callback/google`,
         scopes: ['openid', 'profile', 'email'],
-        name: 'Google',
+        pkce: true,
       },
       github: {
-        clientId: '...',
-        redirectUri: '...',
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        redirectUri: `${process.env.NEXT_PUBLIC_URL}/api/auth/callback/github`,
         scopes: ['user:email'],
+        pkce: true,
       },
     },
   },
-  
-  // Optional: Two-Factor Authentication
-  twoFactor: {
-    enabled: true,
-  },
-  
-  // Optional: Account Picker
-  accountPicker: {
-    enabled: true,
-    maxAccounts: 3,
-    encryptStorage: true,
-    storageKey: '__mulguard_accounts',
-  },
-  
-  // Optional: Security settings
+
+  // Optional: Security configuration
   security: {
     csrfProtection: true,
     rateLimiting: {
+      enabled: true,
       maxAttempts: 5,
       windowMs: 15 * 60 * 1000, // 15 minutes
     },
   },
-  
+
   // Optional: Callbacks
   callbacks: {
     onSignIn: async (user, session) => {
-      // Called after successful sign-in
+      // Called after successful sign in
     },
     onSignOut: async (user) => {
-      // Called after sign-out
+      // Called after sign out
     },
-    onSessionExpired: async (session) => {
-      // Called when session expires
+    onOAuthUser: async (userInfo, provider) => {
+      // Handle OAuth user creation/update
+      // Return user object for session
     },
     onError: async (error, context) => {
-      // Called on authentication errors
+      // Handle errors
     },
   },
-  
-  // Optional: Token refresh configuration
-  tokenRefresh: {
-    enabled: true,
-    refreshThreshold: 300, // 5 minutes before expiration
-    maxRetries: 0,
-    retryDelay: 1000,
-    rateLimit: 1, // 1 attempt per minute
-    autoSignOutOnFailure: true,
-    redirectToLogin: '/login',
-  },
 })
 ```
 
 ---
 
-## 🖥️ Server-Side Usage
+## 📖 Examples
 
-### Get Server Session
+### OAuth Sign-In
 
 ```typescript
-import { getServerSession } from 'mulguard/server'
+// app/login/page.tsx
+'use client'
+
+import { useAuth } from 'mulguard/client'
 import { auth } from '@/lib/auth'
 
-// In Server Components
-const session = await getServerSession(auth)
+export default function LoginPage() {
+  const { signIn } = useAuth(auth)
 
-// In API Routes
-export async function GET(request: Request) {
-  const session = await getServerSession(auth)
-  if (!session) {
-    return new Response('Unauthorized', { status: 401 })
+  const handleGoogleSignIn = async () => {
+    const { url } = await signIn('google')
+    window.location.href = url
   }
-  return Response.json({ user: session.user })
-}
-```
-
-### Server Actions
-
-```typescript
-'use server'
-
-import { auth } from '@/lib/auth'
 
-export async function signInAction(email: string, password: string) {
-  const result = await auth.signIn.email({ email, password })
-  return result
+  return (
+    <div>
+      <button onClick={handleGoogleSignIn}>
+        Sign in with Google
+      </button>
+    </div>
+  )
 }
 ```
 
-### API Route Handlers
+### Protected Route with Role Check
 
 ```typescript
-// app/api/auth/[...mulguard]/route.ts
-import { createAuthHandler } from 'mulguard/handlers/route'
+// app/admin/page.tsx
+import { requireRole } from 'mulguard/server'
 import { auth } from '@/lib/auth'
 
-export const { GET, POST } = createAuthHandler(auth)
-```
-
----
-
-## 💻 Client-Side Usage
-
-### React Hooks
-
-```typescript
-'use client'
-
-import { useAuth, useSession } from 'mulguard/client'
-import { auth } from '@/lib/auth'
-
-export function AuthComponent() {
-  const { signIn, signOut, isLoading } = useAuth(auth)
-  const { session, isLoading: sessionLoading } = useSession(auth)
+export default async function AdminPage() {
+  const session = await requireRole(auth, 'admin', '/unauthorized')
   
-  // Use hooks...
+  // If user doesn't have 'admin' role, redirects to /unauthorized
+  return <div>Admin Dashboard</div>
 }
 ```
 
-### Mulguard Provider
+### Using Provider (Recommended)
 
 ```typescript
 // app/layout.tsx
-'use client'
-
 import { MulguardProvider } from 'mulguard/client'
 import { auth } from '@/lib/auth'
 
@@ -655,339 +468,57 @@ export default function RootLayout({ children }) {
 }
 ```
 
-> **Note:** `AuthProvider` is still available for backward compatibility but is deprecated. Use `MulguardProvider` instead.
-
----
-
-## 🎨 Components
-
-### Account Picker
-
-```typescript
-import { AccountPicker } from 'mulguard'
-
-<AccountPicker
-  auth={auth}
-  onSelectUser={(user) => {
-    // Pre-fill email or handle quick login
-    setEmail(user.email)
-  }}
-  onUseDifferentAccount={() => {
-    // Show full login form
-  }}
-/>
-```
-
-### OAuth Button
-
-```typescript
-import { OAuthButton } from 'mulguard'
-
-<OAuthButton
-  auth={auth}
-  provider="google"
-  onSuccess={() => {
-    // Handle success
-  }}
-  onError={(error) => {
-    // Handle error
-  }}
->
-  Sign in with Google
-</OAuthButton>
-```
-
-### Two-Factor Setup
-
-```typescript
-import { TwoFactorSetup } from 'mulguard'
-
-<TwoFactorSetup
-  auth={auth}
-  onSuccess={() => {
-    // 2FA enabled
-  }}
-/>
-```
-
-### PassKey Components
-
 ```typescript
-import { PassKeyButton, PassKeyRegister } from 'mulguard'
-
-// Register PassKey
-<PassKeyRegister auth={auth} />
-
-// Authenticate with PassKey
-<PassKeyButton auth={auth} />
-```
-
----
-
-## 🔒 Security
-
-Mulguard implements **comprehensive security features** with automatic input validation and sanitization:
-
-### ✅ Built-in Security Features
-
-#### Input Validation & Sanitization
-- **Automatic email validation** - Validates and sanitizes email addresses
-- **Password length checks** - Prevents DoS attacks with extremely long passwords
-- **Provider validation** - Sanitizes OAuth provider strings to prevent injection
-- **OTP code validation** - Validates OTP code format before processing
-- **XSS Prevention** - Automatic HTML escaping and input sanitization
-
-#### CSRF Protection
-- Token-based CSRF protection for OAuth flows
-- State parameter validation with constant-time comparison
-- Secure state storage (pluggable for production - Redis, Database, etc.)
-
-#### Error Handling
-- **Generic error messages** - Prevents information disclosure
-- **Error codes** - Programmatic error handling without exposing details
-- **Security logging** - Logs authentication events (with sensitive data masked)
-
-#### Secure Cookies
-- HttpOnly cookies (prevents JavaScript access)
-- Secure flag in production (HTTPS only)
-- SameSite attribute (CSRF protection)
-- Configurable expiration
-
-#### Rate Limiting
-- Configurable rate limiting
-- Client-side tracking
-- Automatic throttling
-- Circuit breaker pattern for token refresh
-
-### Security Best Practices
+// app/profile/page.tsx
+'use client'
 
-```typescript
-// ✅ Good: Generic error messages
-return { 
-  success: false, 
-  error: 'Invalid credentials',
-  errorCode: 'INVALID_CREDENTIALS'
-}
+import { useAuthFromContext } from 'mulguard/client'
 
-// ❌ Bad: Information disclosure
-return { 
-  success: false, 
-  error: 'User not found with email: user@example.com'
+export default function ProfilePage() {
+  const { session, signOut } = useAuthFromContext()
+  
+  // No need to pass auth instance
+  return <div>...</div>
 }
 ```
 
-### Security Logging
-
-All authentication events are automatically logged with sensitive data masked:
-
-```typescript
-// Logs show: "Sign in successful" with email: "use***"
-// Never logs full email addresses or passwords
-```
-
-For detailed security documentation, see the [Security Guide](./docs/SECURITY.md) and [Complete Guide](./GUIDE.md).
-
 ---
 
-## 🔌 Backend Integration
+## 🏗️ Architecture
 
-Mulguard is designed to work with your existing backend. You implement the authentication logic through **actions**, which can:
+Mulguard follows a **modular, backend-first architecture**:
 
-- Connect to your database
-- Call your API endpoints
-- Use your existing authentication services
-- Integrate with third-party services
+- **Core Layer** - Framework-agnostic authentication logic
+- **Next.js Integration** - Server Actions, Server Components, Proxy middleware
+- **Plugin System** - Extensible features (MFA, Account Picker, etc.)
 
-### Example: Database Integration
-
-```typescript
-import { mulguard } from 'mulguard'
-import { db } from '@/lib/db'
-import { comparePassword, hashPassword } from '@/lib/password'
-
-export const auth = mulguard({
-  actions: {
-    signIn: {
-      email: async ({ email, password }) => {
-        const user = await db.user.findUnique({ where: { email } })
-        
-        if (!user || !await comparePassword(password, user.password)) {
-          return { success: false, error: 'Invalid credentials' }
-        }
-        
-        return {
-          success: true,
-          user: {
-            id: user.id,
-            email: user.email,
-            name: user.name,
-          },
-          session: {
-            user: { /* ... */ },
-            expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
-          },
-        }
-      },
-    },
-    // ... more actions
-  },
-})
-```
-
-### Example: API Integration
-
-```typescript
-import { mulguard } from 'mulguard'
-
-export const auth = mulguard({
-  actions: {
-    signIn: {
-      email: async ({ email, password }) => {
-        const response = await fetch('https://api.example.com/auth/signin', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ email, password }),
-        })
-        
-        if (!response.ok) {
-          return { success: false, error: 'Authentication failed' }
-        }
-        
-        const data = await response.json()
-        return {
-          success: true,
-          user: data.user,
-          session: data.session,
-        }
-      },
-    },
-  },
-})
-```
+The library is designed to be:
+- **Framework Agnostic** - Core logic works with any framework
+- **Backend-First** - You implement your own database logic
+- **Type-Safe** - Full TypeScript support throughout
+- **Secure by Default** - Security features enabled by default
 
 ---
 
-## 🚀 Advanced Features
-
-### Token Refresh
-
-Automatic token refresh is built-in when you provide a `refreshSession` action:
-
-```typescript
-actions: {
-  refreshSession: async () => {
-    // Your token refresh logic
-    const newSession = await yourApi.refreshToken()
-    return newSession
-  },
-}
-```
-
-### Custom Callbacks
-
-```typescript
-callbacks: {
-  onSignIn: async (user, session) => {
-    // Track sign-in analytics
-    await analytics.track('user_signed_in', { userId: user.id })
-  },
-  onSignOut: async (user) => {
-    // Cleanup logic
-    await cleanupUserSession(user.id)
-  },
-  onError: async (error, context) => {
-    // Error logging
-    console.error(`Auth error in ${context}:`, error)
-  },
-}
-```
-
-### OAuth State Store
-
-For production, use a persistent OAuth state store:
-
-```typescript
-import { createRedisOAuthStateStore } from 'mulguard'
-
-const auth = mulguard({
-  oauthStateStore: createRedisOAuthStateStore(redisClient),
-  // ... rest of config
-})
-```
-
----
-
-## 📚 API Reference
-
-### Core Functions
-
-#### `mulguard(config: MulguardConfig): MulguardInstance`
-
-Creates a new Mulguard authentication instance.
-
-#### `getServerSession(auth: MulguardInstance): Promise<Session | null>`
-
-Gets the current session on the server.
-
-### Client Hooks
-
-#### `useAuth(auth: MulguardInstance)`
-
-Returns authentication methods and state.
-
-```typescript
-const { signIn, signOut, isLoading } = useAuth(auth)
-```
-
-#### `useSession(auth: MulguardInstance)`
-
-Returns the current session.
-
-```typescript
-const { session, isLoading } = useSession(auth)
-```
-
-### Instance Methods
-
-#### `auth.getSession(): Promise<Session | null>`
-
-Gets the current session.
-
-#### `auth.signIn.email(credentials): Promise<AuthResult>`
-
-Signs in with email and password.
-
-#### `auth.signIn.oauth(provider): Promise<{ url: string; state: string }>`
-
-Initiates OAuth flow.
-
-#### `auth.signOut(): Promise<{ success: boolean }>`
+## 🔒 Security
 
-Signs out the current user.
+Mulguard implements **comprehensive security features**:
 
-For complete API documentation, see the [API Reference](./docs/API_REFERENCE.md).
+- ✅ **HttpOnly Cookies** - Prevents XSS attacks
+- ✅ **Secure Flag** - HTTPS-only cookies in production
+- ✅ **SameSite=Strict** - CSRF protection
+- ✅ **PKCE for OAuth** - Prevents code interception attacks
+- ✅ **Rate Limiting** - Prevents brute force attacks
+- ✅ **Input Validation** - Prevents injection attacks
+- ✅ **XSS Prevention** - Automatic XSS protection
+- ✅ **Generic Error Messages** - Prevents information disclosure
 
 ---
 
-## 📖 Examples & Guides
-
-### Complete Guide
-
-📚 **[Complete Usage Guide](./GUIDE.md)** - Comprehensive guide with:
-- Best practices for writing `auth.ts`
-- Production-ready examples
-- Security recommendations
-- Backend integration patterns
-- Advanced usage examples
+## 📚 Documentation
 
-### Code Examples
-
-- **[Basic Email Authentication](./src/examples/email-auth.ts)** - Simple email/password setup
-- **[OAuth Authentication](./src/examples/oauth-auth.ts)** - Google, GitHub, etc.
-- **[PassKey Authentication](./src/examples/passkey-auth.ts)** - WebAuthn/PassKey setup
-- **[Two-Factor Authentication](./src/examples/two-factor-auth.ts)** - 2FA/TOTP implementation
-- **[Middleware Integration](./src/examples/middleware-example.ts)** - Next.js middleware
-- **[Server Components](./src/examples/server-component-example.tsx)** - Server-side usage
+- **[GUIDE.md](./GUIDE.md)** - Complete usage guide with examples
+- **[API Reference](./docs/API_DESIGN.md)** - Full API documentation
 
 ---
 
@@ -1019,29 +550,13 @@ Contributions are welcome! Please read our contributing guidelines before submit
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/mulverse/mulguard.git
-
-# Install dependencies
-npm install
-
-# Run development build
-npm run dev
-
-# Run tests
-npm test
-```
-
 ---
 
 ## 📝 License
 
 This project is licensed under the **MUV (Mulverse M.U.V General Public License)**.
 
-Copyright (C) 2022 Mulverse Inc.
+Copyright (C) 2024 Mulverse Inc.
 
 See the [LICENSE](./LICENSE) file for details.
 
@@ -1049,22 +564,10 @@ See the [LICENSE](./LICENSE) file for details.
 
 ## 💬 Support
 
-- **📖 Complete Guide**: [GUIDE.md](./GUIDE.md) - Comprehensive usage guide with best practices
-- **📚 Documentation**: Check the [docs](./docs) directory for detailed guides
+- **📖 Documentation**: Check the [GUIDE.md](./GUIDE.md) for detailed usage examples
 - **🐛 Issues**: [GitHub Issues](https://github.com/mulverse/mulguard/issues)
 - **💬 Discussions**: [GitHub Discussions](https://github.com/mulverse/mulguard/discussions)
 
-## 🎯 Key Features & Improvements
-
-### ✨ Latest Updates
-
-- **✅ Unified Sign-In Interface** - Use `auth.signIn('credentials', {...})` or `auth.signIn.email({...})`
-- **✅ Automatic Input Validation** - Built-in email, password, and provider validation
-- **✅ Enhanced Security** - Generic error messages, security logging, XSS/Injection prevention
-- **✅ Single Unified Logic** - All sign-in methods use the same core logic
-- **✅ Type-Safe** - Full TypeScript support with proper typing
-- **✅ Production Ready** - Best practices built-in by default
-
 ---
 
 ## 🌟 About Mulverse
@@ -1076,3 +579,4 @@ Visit [mulverse.com](https://mulverse.com) to learn more about our other project
 ---
 
 **Made with ❤️ by the Mulverse Team**
+