mulguard 1.0.1 → 1.1.1

package/README.md

@@ -1,93 +1,201 @@
-# Mukey - Modern Authentication Library
+# Mulguard
 
-> Backend-first authentication library for Next.js and modern web applications
+> A modern, backend-first authentication library for Next.js applications
 
-[![License](https://img.shields.io/badge/license-MUV-blue.svg)](LICENSE)
+[![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/)
 
-Mukey is a modern, secure authentication library designed for Next.js applications with a backend-first architecture. It provides a simple API similar to `better-auth` and `auth.js`, while maintaining full control over your backend authentication logic.
+**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 Auth Methods**
-  - Email/Password authentication
-  - OAuth 2.1 (Google, GitHub, etc.)
-  - PassKey/WebAuthn support
-  - Two-Factor Authentication (2FA/TOTP)
-
-- 🎯 **Account Picker**
-  - Remember last logged-in users
-  - Quick re-login experience
-  - Encrypted local storage
-
-- 🔒 **Security First**
-  - CSRF protection
-  - XSS prevention
-  - Input validation & sanitization
-  - Security headers
-  - Rate limiting utilities
-
-- ⚡ **Next.js Optimized**
-  - Server Components support
-  - Client hooks (`useAuth`, `useSession`)
-  - Middleware integration
-  - API route handlers
-
-- 🔌 **Backend-First**
-  - No database adapter required
-  - Works with your existing backend API
-  - Mulink integration support
-  - Full TypeScript support
+### 🔐 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 mukey
+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
 
-```typescript
-// lib/auth.ts
-import { mukey } from 'mukey'
-// import { apiClient } from '@mulink/client' // Optional: Use Mulink
+Create a new file `lib/auth.ts`:
 
-export const auth = mukey({
-  // Option 1: Use Mulink API client
-  // apiClient: apiClient,
+```typescript
+import { mulguard } from 'mulguard'
+import type { EmailCredentials, AuthResult, Session } from 'mulguard'
+import { db } from '@/lib/db'
+import { comparePassword } from '@/lib/password'
 
-  // Option 2: Use baseURL
-  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001',
-  
+export const auth = mulguard({
+  // Session configuration
   session: {
-    cookieName: '__mukey_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'],
+      },
     },
   },
   
-  accountPicker: {
-    enabled: true,
-    maxAccounts: 3,
+  // 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)
+    },
   },
 })
 ```
 
+> 📖 **For a complete guide with best practices**, see [GUIDE.md](./GUIDE.md)
+
 ### 2. Server-Side Usage
 
 ```typescript
 // app/dashboard/page.tsx
-import { getServerSession } from 'mukey/server'
+import { getServerSession } from 'mulguard/server'
 import { auth } from '@/lib/auth'
 import { redirect } from 'next/navigation'
 
@@ -98,7 +206,12 @@ export default async function DashboardPage() {
     redirect('/login')
   }
   
-  return <div>Welcome, {session.user.name}!</div>
+  return (
+    <div>
+      <h1>Welcome, {session.user.name}!</h1>
+      <p>Email: {session.user.email}</p>
+    </div>
+  )
 }
 ```
 
@@ -108,7 +221,7 @@ export default async function DashboardPage() {
 // app/login/page.tsx
 'use client'
 
-import { useAuth } from 'mukey/client'
+import { useAuth } from 'mulguard/client'
 import { auth } from '@/lib/auth'
 import { useState } from 'react'
 
@@ -119,9 +232,19 @@ export default function LoginPage() {
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
-    const result = await signIn.email({ email, password })
+    
+    // ✅ 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)
     }
   }
 
@@ -135,12 +258,14 @@ export default function LoginPage() {
         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>
@@ -152,7 +277,7 @@ export default function LoginPage() {
 
 ```typescript
 // middleware.ts
-import { createAuthMiddleware } from 'mukey/middleware'
+import { createAuthMiddleware } from 'mulguard/middleware'
 import { auth } from '@/lib/auth'
 
 export default createAuthMiddleware(auth, {
@@ -160,44 +285,191 @@ export default createAuthMiddleware(auth, {
   redirectTo: '/login',
   redirectIfAuthenticated: '/dashboard',
 })
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/profile/:path*'],
+}
 ```
 
-## 📚 Documentation
+---
+
+## 🎓 Core Concepts
+
+### Backend-First Architecture
+
+Mulguard follows a **backend-first** approach, meaning you implement your own authentication logic through **actions**. This gives you:
 
-- [Getting Started](./docs/GETTING_STARTED.md)
-- [Authentication Methods](./docs/AUTH_METHODS.md)
-- [Server-Side Usage](./docs/SERVER_USAGE.md)
-- [Client-Side Usage](./docs/CLIENT_USAGE.md)
-- [Security](./docs/SECURITY.md)
-- [Backend Integration](./docs/BACKEND_INTEGRATION.md)
-- [API Reference](./docs/API_REFERENCE.md)
+- **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
 
-## 🔧 Configuration
+### 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 { mukey } from 'mukey'
+import { mulguard } from 'mulguard'
 
-export const auth = mukey({
-  // API Client (from Mulink) or baseURL
-  apiClient: apiClient, // Optional
-  baseURL: 'http://localhost:3001', // Required if apiClient not provided
-  
+export const auth = mulguard({
   // Session configuration
   session: {
-    cookieName: '__mukey_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
   },
   
-  // OAuth providers
+  // 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',
@@ -210,20 +482,20 @@ export const auth = mukey({
     },
   },
   
-  // 2FA configuration
+  // Optional: Two-Factor Authentication
   twoFactor: {
     enabled: true,
   },
   
-  // Account Picker
+  // Optional: Account Picker
   accountPicker: {
     enabled: true,
     maxAccounts: 3,
     encryptStorage: true,
-    storageKey: '__mukey_accounts',
+    storageKey: '__mulguard_accounts',
   },
   
-  // Security
+  // Optional: Security settings
   security: {
     csrfProtection: true,
     rateLimiting: {
@@ -231,15 +503,134 @@ export const auth = mukey({
       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 'mukey'
+import { AccountPicker } from 'mulguard'
 
 <AccountPicker
   auth={auth}
@@ -256,7 +647,7 @@ import { AccountPicker } from 'mukey'
 ### OAuth Button
 
 ```typescript
-import { OAuthButton } from 'mukey'
+import { OAuthButton } from 'mulguard'
 
 <OAuthButton
   auth={auth}
@@ -264,13 +655,18 @@ import { OAuthButton } from 'mukey'
   onSuccess={() => {
     // Handle success
   }}
-/>
+  onError={(error) => {
+    // Handle error
+  }}
+>
+  Sign in with Google
+</OAuthButton>
 ```
 
-### 2FA Setup
+### Two-Factor Setup
 
 ```typescript
-import { TwoFactorSetup } from 'mukey'
+import { TwoFactorSetup } from 'mulguard'
 
 <TwoFactorSetup
   auth={auth}
@@ -280,53 +676,286 @@ import { TwoFactorSetup } from 'mukey'
 />
 ```
 
+### 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
 
-Mukey expects your backend to provide the following endpoints:
+Mulguard is designed to work with your existing backend. You implement the authentication logic through **actions**, which can:
 
-### Authentication Endpoints
+- Connect to your database
+- Call your API endpoints
+- Use your existing authentication services
+- Integrate with third-party services
 
-- `POST /api/auth/sign-in` - Sign in with email/password
-- `POST /api/auth/sign-up` - Register new user
-- `POST /api/auth/sign-out` - Sign out
-- `GET /api/auth/session` - Get current session
-- `POST /api/auth/reset-password` - Request password reset
-- `POST /api/auth/verify-email` - Verify email address
+### Example: Database Integration
 
-### OAuth Endpoints
+```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
+  },
+})
+```
 
-- `GET /api/auth/oauth/:provider` - Initiate OAuth flow
-- `POST /api/auth/oauth/:provider/callback` - Handle OAuth callback
+### Example: API Integration
 
-### 2FA Endpoints
+```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,
+        }
+      },
+    },
+  },
+})
+```
 
-- `POST /api/auth/2fa/enable` - Enable 2FA
-- `POST /api/auth/2fa/verify` - Verify 2FA code
-- `POST /api/auth/2fa/disable` - Disable 2FA
-- `POST /api/auth/2fa/regenerate` - Generate backup codes
-- `GET /api/auth/2fa/status` - Check 2FA status
+---
 
-### PassKey Endpoints
+## 🚀 Advanced Features
 
-- `POST /api/auth/passkey/register` - Register PassKey
-- `POST /api/auth/passkey/authenticate` - Authenticate with PassKey
-- `GET /api/auth/passkey/list` - List registered PassKeys
-- `DELETE /api/auth/passkey/:id` - Remove PassKey
+### Token Refresh
 
-See [Backend Integration Guide](./docs/BACKEND_INTEGRATION.md) for detailed API specifications.
+Automatic token refresh is built-in when you provide a `refreshSession` action:
 
-## 🔒 Security
+```typescript
+actions: {
+  refreshSession: async () => {
+    // Your token refresh logic
+    const newSession = await yourApi.refreshToken()
+    return newSession
+  },
+}
+```
 
-Mukey implements multiple security features:
+### Custom Callbacks
 
-- **CSRF Protection** - Token-based CSRF protection
-- **XSS Prevention** - Input sanitization and HTML escaping
-- **Rate Limiting** - Client-side rate limit tracking
-- **Security Headers** - Automatic security headers
-- **Input Validation** - Comprehensive input validation
-- **Secure Cookies** - HttpOnly, Secure, SameSite cookies
+```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.
 
-See [Security Guide](./docs/SECURITY.md) for more details.
+#### `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
 
@@ -339,30 +968,77 @@ npm run test:watch
 
 # Coverage
 npm run test:coverage
+
+# Type checking
+npm run type-check
 ```
 
-## 🚀 CI/CD
+---
+
+## 🤝 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
 
-This project uses GitHub Actions with npm Trusted Publisher for secure publishing.
+```bash
+# Clone the repository
+git clone https://github.com/mulverse/mulguard.git
+
+# Install dependencies
+npm install
 
-- **CI**: Runs on every push/PR (lint, test, build)
-- **Publishing**: Automatic publishing via Changesets or manual release
-- **Security**: Uses OIDC (OpenID Connect) for authentication
+# Run development build
+npm run dev
 
-See [README_CI.md](./README_CI.md) for setup instructions.
+# Run tests
+npm test
+```
+
+---
 
 ## 📝 License
 
-MUV License - See [LICENSE](./LICENSE) file for details.
+This project is licensed under the **MUV (Mulverse M.U.V General Public License)**.
 
-## 🤝 Contributing
+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
+
+---
 
-Contributions are welcome! Please read our contributing guidelines first.
+## 🌟 About Mulverse
 
-## 📧 Support
+**Mulguard** is part of the **Mulverse** ecosystem - a collection of modern, developer-friendly libraries and tools for building next-generation web applications.
 
-For questions and support, please open an issue on GitHub.
+Visit [mulverse.com](https://mulverse.com) to learn more about our other projects.
 
 ---
 
-Made with ❤️ by the Mukey Team
+**Made with ❤️ by the Mulverse Team**