mulguard 1.1.7 → 1.1.9

package/LICENSE

@@ -21,17 +21,17 @@
 
 2.2 **Copy and Distribution**: You may distribute copies of the Software, either in its original form or as modified, provided that all copies include the same license terms.
 
-2.3 **Modification**: You may modify the Software and distribute the modified versions, provided that the modified Software is also licensed under this GPL and that you include a prominent notice stating the changes made.
+2.3 **Modification**: You may modify the Software and distribute the modified versions, provided that the modified Software is also licensed under this Mulverse M.U.V General Public License and that you include a prominent notice stating the changes made.
 
 **3. Copyleft**
 
 3.1 **Source Code**: If you distribute the Software or any derivative works, you must either include the source code or make it available in a manner specified by this license.
 
-3.2 **License Continuity**: All copies and derivative works of the Software must be distributed under the terms of this GPL. You must include a copy of this license with all distributions.
+3.2 **License Continuity**: All copies and derivative works of the Software must be distributed under the terms of this Mulverse M.U.V General Public License. You must include a copy of this license with all distributions.
 
 **4. Conditions**
 
-4.1 **Attribution**: You must provide appropriate credit to Mulverse Inc., including a notice that the Software is licensed under the Mulverse S.N.E General Public License.
+4.1 **Attribution**: You must provide appropriate credit to Mulverse Inc., including a notice that the Software is licensed under the Mulverse M.U.V General Public License.
 
 4.2 **No Warranty**: The Software is provided "as is," without any warranty of any kind. Mulverse Inc. disclaims all warranties and conditions, including but not limited to implied warranties of merchantability and fitness for a particular purpose.
 

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 {};