mulguard 1.1.7 → 1.1.8

package/README.md

@@ -1,582 +1,21 @@
-# Mulguard
-
-> 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-16.0+-black.svg)](https://nextjs.org/)
-
-**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.
-
----
-
-## ✨ Features
-
-### 🔐 Multiple Authentication Methods
-- **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
-
-### ⚡ 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
-- **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
-
----
-
-## 📦 Installation
-
-```bash
-npm install mulguard
-```
-
-### Peer Dependencies
-
-```bash
-npm install next@>=16.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 (optional)
-  session: {
-    cookieName: '__mulguard_session',
-    expiresIn: 60 * 60 * 24 * 7, // 7 days
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
-    sameSite: 'lax',
-  },
-  
-  // Required: Implement your authentication actions
-  actions: {
-    signIn: {
-      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
-      // The library handles cookie reading automatically
-      return null
-    },
-    
-    signOut: async (): Promise<void> => {
-      // Your custom sign-out logic
-      // The library handles cookie deletion automatically
-    },
-  },
-  
-  // Optional: OAuth providers (auto-generates OAuth actions)
-  providers: {
-    oauth: {
-      google: {
-        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'],
-        pkce: true, // Enable PKCE (recommended)
-      },
-    },
-  },
-  
-  // Optional: Callbacks for lifecycle events
-  callbacks: {
-    onSignIn: async (user, session) => {
-      // Track sign-in analytics, update last login, etc.
-    },
-    onError: async (error, context) => {
-      // Log errors for monitoring (centralized logging, no console.log needed)
-    },
-  },
-})
-```
-
-### 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)
-```
-
-### 3. 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>
-  )
-}
-```
-
-### 4. 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, isLoading } = useAuth(auth)
-  const [error, setError] = useState<string | null>(null)
-
-  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault()
-    setError(null)
-    
-    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) {
-      window.location.href = '/dashboard'
-    } else {
-      setError(result.error || 'Login failed')
-    }
-  }
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <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>
-  )
-}
-```
-
-### 5. Route Protection (Optional)
-
-Create `proxy.ts` in your project root:
-
-```typescript
-// proxy.ts (Next.js 16+)
-import { createProxyMiddleware } from 'mulguard/proxy'
-import { auth } from '@/lib/auth'
-
-export default createProxyMiddleware(auth, {
-  protectedRoutes: ['/dashboard', '/profile'],
-  redirectTo: '/login',
-  redirectIfAuthenticated: '/dashboard',
-})
-
-export const config = {
-  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
-}
-```
-
-> **Note**: In Next.js 16+, `middleware.ts` has been replaced with `proxy.ts`. Mulguard uses the Proxy pattern for route protection.
-
----
-
-## 📋 API Overview
-
-### Unified Sign-In Interface
-
-Mulguard provides a unified, type-safe API for all authentication methods:
-
-```typescript
-// ✅ Unified interface (recommended)
-await auth.signIn('credentials', { email, password })
-await auth.signIn('google')
-await auth.signIn('otp', { email, code })
-
-// ✅ Direct methods (also available)
-await auth.signIn.email({ email, password })
-await auth.signIn.oauth('google')
-```
-
-### Type Safety
-
-Full TypeScript support with generics:
-
-```typescript
-import type { User, Session } from 'mulguard'
-
-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) {
-  // result.user and result.session are fully typed
-  console.log(result.user.email)
-}
-```
-
----
-
-## ⚙️ Configuration
-
-### Complete Configuration Example
-
-```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: '/',
-  },
-
-  // Required: Custom authentication actions
-  actions: {
-    signIn: {
-      email: async (credentials) => {
-        // Your custom logic
-      },
-    },
-    signUp: async (data) => {
-      // Your custom logic
-    },
-    getSession: async () => {
-      // Your custom logic
-    },
-    signOut: async () => {
-      // Your custom logic
-    },
-  },
-
-  // Optional: OAuth providers
-  providers: {
-    oauth: {
-      google: {
-        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'],
-        pkce: true,
-      },
-      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,
-      },
-    },
-  },
-
-  // 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
-    },
-    onSignOut: async (user) => {
-      // Called after sign out
-    },
-    onOAuthUser: async (userInfo, provider) => {
-      // Handle OAuth user creation/update
-      // Return user object for session
-    },
-    onError: async (error, context) => {
-      // Handle errors
-    },
-  },
-})
-```
-
----
-
-## 📖 Examples
-
-### OAuth Sign-In
-
-```typescript
-// app/login/page.tsx
-'use client'
-
-import { useAuth } from 'mulguard/client'
-import { auth } from '@/lib/auth'
-
-export default function LoginPage() {
-  const { signIn } = useAuth(auth)
-
-  const handleGoogleSignIn = async () => {
-    const { url } = await signIn('google')
-    window.location.href = url
-  }
-
-  return (
-    <div>
-      <button onClick={handleGoogleSignIn}>
-        Sign in with Google
-      </button>
-    </div>
-  )
-}
-```
-
-### Protected Route with Role Check
-
-```typescript
-// app/admin/page.tsx
-import { requireRole } from 'mulguard/server'
-import { auth } from '@/lib/auth'
-
-export default async function AdminPage() {
-  const session = await requireRole(auth, 'admin', '/unauthorized')
-  
-  // If user doesn't have 'admin' role, redirects to /unauthorized
-  return <div>Admin Dashboard</div>
-}
-```
-
-### Using Provider (Recommended)
-
-```typescript
-// app/layout.tsx
-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>
-  )
-}
-```
-
-```typescript
-// app/profile/page.tsx
-'use client'
-
-import { useAuthFromContext } from 'mulguard/client'
-
-export default function ProfilePage() {
-  const { session, signOut } = useAuthFromContext()
-  
-  // No need to pass auth instance
-  return <div>...</div>
-}
-```
-
----
-
-## 🏗️ Architecture
-
-Mulguard follows a **modular, backend-first architecture**:
-
-- **Core Layer** - Framework-agnostic authentication logic
-- **Next.js Integration** - Server Actions, Server Components, Proxy middleware
-- **Plugin System** - Extensible features (MFA, Account Picker, etc.)
-
-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
-
----
-
-## 🔒 Security
-
-Mulguard implements **comprehensive security features**:
-
-- ✅ **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
-
----
-
-## 📚 Documentation
-
-- **[GUIDE.md](./GUIDE.md)** - Complete usage guide with examples
-- **[API Reference](./docs/API_DESIGN.md)** - Full API documentation
-
----
-
-## 🧪 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
-
----
-
-## 📝 License
-
-This project is licensed under the **MUV (Mulverse M.U.V General Public License)**.
-
-Copyright (C) 2024 Mulverse Inc.
-
-See the [LICENSE](./LICENSE) file for details.
-
----
-
-## 💬 Support
-
-- **📖 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)
-
----
-
-## 🌟 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.

package/adapters.d.ts

@@ -0,0 +1,2 @@
+export type * from "@mulverse/mulguard-core/adapters";
+//# sourceMappingURL=adapters.d.ts.map

package/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["src/adapters.ts"],"names":[],"mappings":"AAAA,mBAAmB,kCAAkC,CAAA"}

package/adapters.js

@@ -0,0 +1 @@
+export {};