mulguard 1.1.6 → 1.1.8

package/README.md

@@ -1,1078 +1,21 @@
-# Mulguard
-
-> A modern, backend-first authentication library for Next.js applications
-
-[![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/)
-
-**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`.
-
-**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
-- **OTP** - One-time password authentication
-
-### 🎯 Account Picker
-- Remember last logged-in users
-- Quick re-login experience
-- Encrypted local storage for security
-- Configurable account limits
-
-### 🔒 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
-
----
-
-## 📦 Installation
-
-```bash
-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
-```
-
----
-
-## 🚀 Quick Start
-
-### 1. Create Auth Configuration
-
-Create a new file `lib/auth.ts`:
-
-```typescript
-import { mulguard } from 'mulguard'
-import type { EmailCredentials, AuthResult, Session } from 'mulguard'
-import { db } from '@/lib/db'
-import { comparePassword } from '@/lib/password'
-
-export const auth = mulguard({
-  // Session configuration
-  session: {
-    cookieName: '__mulguard_session',
-    expiresIn: 60 * 60 * 24 * 7, // 7 days
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production', // HTTPS only in 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({ 
-          where: { email: credentials.email }
-        })
-        
-        if (!user || !await comparePassword(credentials.password, user.password)) {
-          return { 
-            success: false, 
-            error: 'Invalid credentials',
-            errorCode: 'INVALID_CREDENTIALS'
-          }
-        }
-        
-        const session: Session = {
-          user: {
-            id: user.id,
-            email: user.email,
-            name: user.name,
-            emailVerified: user.emailVerified,
-          },
-          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
-        }
-        
-        return { success: true, user: session.user, session }
-      },
-    },
-    
-    getSession: async (): Promise<Session | null> => {
-      // Your custom session retrieval logic
-      // Can read from cookie or database
-      return await db.getSession()
-    },
-    
-    signOut: async () => {
-      // Your custom sign-out logic
-      await db.invalidateSession()
-      return { success: true }
-    },
-  },
-  
-  // Optional: OAuth providers (auto-generates OAuth actions)
-  providers: {
-    oauth: {
-      google: {
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET, // Server-side only
-        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'],
-      },
-    },
-  },
-  
-  // Optional: Callbacks for lifecycle events
-  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,
-      }
-    },
-  },
-})
-```
-
-> 📖 **For a complete guide with best practices**, see [GUIDE.md](./GUIDE.md)
-
-### 2. Server-Side Usage
-
-```typescript
-// app/dashboard/page.tsx
-import { getServerSession } from 'mulguard/server'
-import { auth } from '@/lib/auth'
-import { redirect } from 'next/navigation'
-
-export default async function DashboardPage() {
-  const session = await getServerSession(auth)
-  
-  if (!session) {
-    redirect('/login')
-  }
-  
-  return (
-    <div>
-      <h1>Welcome, {session.user.name}!</h1>
-      <p>Email: {session.user.email}</p>
-    </div>
-  )
-}
-```
-
-### 3. Client-Side Usage
-
-```typescript
-// app/login/page.tsx
-'use client'
-
-import { useAuth } from 'mulguard/client'
-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 handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault()
-    
-    // ✅ Unified interface (recommended)
-    const result = await signIn('credentials', { email, password })
-    
-    // Or use direct method:
-    // const result = await signIn.email({ email, password })
-    
-    if (result.success) {
-      // Redirect to dashboard
-      window.location.href = '/dashboard'
-    } else {
-      // Handle error
-      alert(result.error)
-    }
-  }
-
-  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>
-    </form>
-  )
-}
-```
-
-### 4. Middleware (Optional)
-
-```typescript
-// middleware.ts
-import { createAuthMiddleware } from 'mulguard/middleware'
-import { auth } from '@/lib/auth'
-
-export default createAuthMiddleware(auth, {
-  protectedRoutes: ['/dashboard', '/profile'],
-  redirectTo: '/login',
-  redirectIfAuthenticated: '/dashboard',
-})
-
-export const config = {
-  matcher: ['/dashboard/:path*', '/profile/:path*'],
-}
-```
-
----
-
-## 🎓 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
-}
-```
-
----
-
-## 🔐 Authentication Methods
-
-### Unified Sign-In Interface
-
-Mulguard provides a **unified interface** for all authentication methods, similar to auth.js:
-
-```typescript
-// ✅ Unified interface (recommended)
-await auth.signIn('credentials', { email: 'user@example.com', password: 'password123' })
-await auth.signIn('google')
-await auth.signIn('otp', { email: 'user@example.com', code: '123456' })
-await auth.signIn('passkey', { userId: 'user-id' })
-
-// ✅ Direct methods (for backward compatibility)
-await auth.signIn.email({ email: 'user@example.com', password: 'password123' })
-await auth.signIn.oauth('google')
-await auth.signIn.otp('user@example.com', '123456')
-```
-
-### Email/Password Authentication
-
-```typescript
-// Using unified interface
-const result = await auth.signIn('credentials', {
-  email: 'user@example.com',
-  password: 'password123',
-})
-
-// Or using direct method
-const result = await auth.signIn.email({
-  email: 'user@example.com',
-  password: 'password123',
-})
-
-if (result.success) {
-  console.log('Signed in:', result.user)
-} else {
-  console.error('Error:', result.error, result.errorCode)
-}
-```
-
-### 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
-
-```typescript
-import { mulguard } from 'mulguard'
-
-export const auth = mulguard({
-  // Session configuration
-  session: {
-    cookieName: '__mulguard_session',
-    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
-  actions: {
-    signIn: {
-      email: async (credentials) => { /* ... */ },
-      // Optional: oauth, passkey, otp
-    },
-    getSession: async () => { /* ... */ },
-    signOut: async () => { /* ... */ },
-    // Optional: signUp, resetPassword, verifyEmail, refreshSession, etc.
-  },
-  
-  // Optional: OAuth providers
-  providers: {
-    oauth: {
-      google: {
-        clientId: '...',
-        clientSecret: '...', // Server-side only
-        redirectUri: '...',
-        scopes: ['openid', 'profile', 'email'],
-        name: 'Google',
-      },
-      github: {
-        clientId: '...',
-        redirectUri: '...',
-        scopes: ['user:email'],
-      },
-    },
-  },
-  
-  // Optional: Two-Factor Authentication
-  twoFactor: {
-    enabled: true,
-  },
-  
-  // Optional: Account Picker
-  accountPicker: {
-    enabled: true,
-    maxAccounts: 3,
-    encryptStorage: true,
-    storageKey: '__mulguard_accounts',
-  },
-  
-  // Optional: Security settings
-  security: {
-    csrfProtection: true,
-    rateLimiting: {
-      maxAttempts: 5,
-      windowMs: 15 * 60 * 1000, // 15 minutes
-    },
-  },
-  
-  // Optional: Callbacks
-  callbacks: {
-    onSignIn: async (user, session) => {
-      // Called after successful sign-in
-    },
-    onSignOut: async (user) => {
-      // Called after sign-out
-    },
-    onSessionExpired: async (session) => {
-      // Called when session expires
-    },
-    onError: async (error, context) => {
-      // Called on authentication 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
-
-### Get Server Session
-
-```typescript
-import { getServerSession } from 'mulguard/server'
-import { auth } from '@/lib/auth'
-
-// In Server Components
-const session = await getServerSession(auth)
-
-// In API Routes
-export async function GET(request: Request) {
-  const session = await getServerSession(auth)
-  if (!session) {
-    return new Response('Unauthorized', { status: 401 })
-  }
-  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
-}
-```
-
-### API Route Handlers
-
-```typescript
-// app/api/auth/[...mulguard]/route.ts
-import { createAuthHandler } from 'mulguard/handlers/route'
-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)
-  
-  // Use hooks...
-}
-```
-
-### Mulguard Provider
-
-```typescript
-// app/layout.tsx
-'use client'
-
-import { MulguardProvider } from 'mulguard/client'
-import { auth } from '@/lib/auth'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <MulguardProvider auth={auth}>
-          {children}
-        </MulguardProvider>
-      </body>
-    </html>
-  )
-}
-```
-
-> **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
-
-```typescript
-// ✅ Good: Generic error messages
-return { 
-  success: false, 
-  error: 'Invalid credentials',
-  errorCode: 'INVALID_CREDENTIALS'
-}
-
-// ❌ Bad: Information disclosure
-return { 
-  success: false, 
-  error: 'User not found with email: user@example.com'
-}
-```
-
-### 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
-
-Mulguard is designed to work with your existing backend. You implement the authentication logic through **actions**, which can:
-
-- Connect to your database
-- Call your API endpoints
-- Use your existing authentication services
-- Integrate with third-party services
-
-### 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,
-        }
-      },
-    },
-  },
-})
-```
-
----
-
-## 🚀 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 }>`
-
-Signs out the current user.
-
-For complete API documentation, see the [API Reference](./docs/API_REFERENCE.md).
-
----
-
-## 📖 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
-
-### 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
-
----
-
-## 🧪 Testing
-
-```bash
-# Run tests
-npm test
-
-# Watch mode
-npm run test:watch
-
-# Coverage
-npm run test:coverage
-
-# Type checking
-npm run type-check
-```
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting a pull request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-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.
-
-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
-- **🐛 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
-
-**Mulguard** is part of the **Mulverse** ecosystem - a collection of modern, developer-friendly libraries and tools for building next-generation web applications.
-
-Visit [mulverse.com](https://mulverse.com) to learn more about our other projects.
-
----
-
-**Made with ❤️ by the Mulverse Team**
+<p align="center">
+  <a href="https://nextjs.org" target="_blank"><img height="96px" src="https://authjs.dev/img/etc/nextjs.svg" /></a>
+  <a href="https://mulverse.com" target="_blank"><img height="96px" src="https://authjs.dev/img/logo-sm.png" /></a>
+  <h1 align="center">MulGuard</h1>
+</p>
+<p align="center">
+  Authentication for Next.js with Backend-First Architecture.
+</p>
+<p align="center">
+  Part of the <a href="https://mulverse.com" target="_blank">Mulverse Network</a>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/mulguard"><img src="https://img.shields.io/npm/v/mulguard/beta?style=flat-square&label=latest&color=purple" alt="npm beta release" /></a>
+  <a href="https://www.npmtrends.com/mulguard"><img src="https://img.shields.io/npm/dm/mulguard?style=flat-square&color=cyan" alt="Downloads" /></a>
+  <a href="https://github.com/mulguard/mulguard/stargazers"><img src="https://img.shields.io/github/stars/mulguard/mulguard?style=flat-square&color=orange" alt="GitHub Stars" /></a>
+  <img src="https://shields.io/badge/TypeScript-3178C6?logo=TypeScript&logoColor=fff&style=flat-square" alt="TypeScript" />
+</p>
+
+---
+
+Check out the documentation at [mulverse.com](https://mulverse.com) or visit the [Mulverse Network](https://mulverse.com) for more information.