mulguard 1.1.6 → 1.1.7

package/dist/index.d.ts

@@ -13,9 +13,6 @@
  */
 export * from './core';
 export * from './mulguard';
-export * from './server';
-export * from './handlers/route';
-export * from './handlers/api';
-export * from './middleware';
-export { createProxyMiddleware, checkRole as checkRoleProxy, } from './middleware/proxy';
-export * from './middleware/security';
+export * from './nextjs/server';
+export * from './nextjs/handlers';
+export * from './nextjs/proxy';

package/dist/{client → nextjs/client}/hooks.d.ts

@@ -1,5 +1,5 @@
-import { Session, AuthResult, EmailCredentials, RegisterData, RememberedUser, Verify2FAData } from '../core/types';
-import { MulguardInstance } from '../mulguard';
+import { Session, AuthResult, EmailCredentials, RegisterData, RememberedUser, Verify2FAData } from '../../core/types';
+import { MulguardInstance } from '../../mulguard';
 export interface UseAuthReturn {
     session: Session | null;
     isLoading: boolean;

package/dist/nextjs/client/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Next.js Client-Side Integration for Mulguard Authentication Library.
+ *
+ * Provides client-side utilities for Next.js including:
+ * - React hooks (useAuth, useSession)
+ * - Provider component
+ * - Client-side session management
+ *
+ * @module @mulguard/nextjs/client
+ */
+export * from './hooks';
+export * from './provider';
+export type { Session, User, AuthResult } from '../../core/types';

package/dist/{client → nextjs/client}/provider.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { MulguardInstance } from '../mulguard';
+import { MulguardInstance } from '../../mulguard';
 import { useSession, useAccountPicker } from './hooks';
 interface MulguardContextValue {
     auth: MulguardInstance;

package/dist/{client → nextjs/client}/server-actions-helper.d.ts

@@ -1,5 +1,5 @@
-import { MulguardInstance } from '../mulguard';
-import { Verify2FAData, AuthResult, EmailCredentials, RegisterData } from '../core/types';
+import { MulguardInstance } from '../../mulguard';
+import { Verify2FAData, AuthResult, EmailCredentials, RegisterData } from '../../core/types';
 /**
  * Verify 2FA with automatic fallback
  * Tries Server Action first, then falls back to Route Handler

package/dist/{handlers → nextjs/handlers}/api.d.ts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { MulguardInstance } from '../mulguard';
+import { MulguardInstance } from '../../mulguard';
 /**
  * Create API route handler
  */

package/dist/nextjs/handlers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Next.js Route Handlers for Mulguard Authentication Library.
+ *
+ * Provides route handlers for Next.js App Router API routes.
+ *
+ * @module @mulguard/nextjs/handlers
+ */
+export { toNextJsHandler } from './route';
+export { createApiHandler } from './api';

package/dist/{handlers → nextjs/handlers}/route.d.ts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { MulguardInstance } from '../mulguard';
+import { MulguardInstance } from '../../mulguard';
 /**
  * Route handler options.
  */

package/dist/nextjs/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Next.js Integration for Mulguard Authentication Library.
+ *
+ * Provides comprehensive Next.js integration including:
+ * - Server-side utilities (getServerSession, Server Actions)
+ * - Client-side hooks (useAuth, useSession, Provider)
+ * - Proxy middleware (Next.js 16+)
+ * - Route handlers (App Router)
+ *
+ * @module @mulguard/nextjs
+ */
+export * from './server';
+export * from './client';
+export * from './proxy';
+export * from './handlers';

package/dist/nextjs/proxy/index.d.ts

@@ -0,0 +1,149 @@
+import { NextResponse, NextRequest } from 'next/server';
+import { MulguardInstance } from '../../mulguard';
+/**
+ * Proxy middleware configuration.
+ */
+export interface ProxyMiddlewareConfig {
+    /**
+     * Mulguard auth instance.
+     */
+    readonly auth: MulguardInstance;
+    /**
+     * Protected routes that require authentication.
+     *
+     * @example
+     * ['/dashboard', '/profile', '/settings']
+     */
+    readonly protectedRoutes?: readonly string[];
+    /**
+     * Public routes accessible without authentication.
+     *
+     * @example
+     * ['/login', '/signup', '/about']
+     */
+    readonly publicRoutes?: readonly string[];
+    /**
+     * Redirect to this URL if not authenticated.
+     *
+     * @default '/login'
+     */
+    readonly redirectTo?: string;
+    /**
+     * Redirect to this URL if already authenticated (for login/register pages).
+     *
+     * @example
+     * '/dashboard'
+     */
+    readonly redirectIfAuthenticated?: string;
+    /**
+     * API routes prefix (default: '/api/auth').
+     */
+    readonly apiPrefix?: string;
+    /**
+     * Enable security headers.
+     *
+     * @default true
+     */
+    readonly enableSecurityHeaders?: boolean;
+}
+/**
+ * Creates proxy middleware for Next.js 16+.
+ *
+ * Replaces the old middleware.ts pattern with proxy-based approach.
+ *
+ * @param config - Proxy middleware configuration
+ * @returns Proxy middleware function
+ *
+ * @example
+ * ```typescript
+ * // proxy.ts (Next.js 16+)
+ * import { createProxyMiddleware } from 'mulguard/nextjs/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).*)'],
+ * }
+ * ```
+ */
+export declare function createProxyMiddleware(config: ProxyMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Checks if user has required role (for role-based access control).
+ *
+ * @param auth - Mulguard auth instance
+ * @param requiredRole - Required role
+ * @returns True if user has required role
+ *
+ * @example
+ * ```typescript
+ * const hasAdminRole = await checkRole(auth, 'admin')
+ * if (!hasAdminRole) {
+ *   return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+ * }
+ * ```
+ */
+export declare function checkRole(auth: MulguardInstance, requiredRole: string): Promise<boolean>;
+/**
+ * Creates a role-based proxy middleware.
+ *
+ * @param config - Proxy middleware configuration
+ * @param requiredRole - Required role
+ * @returns Proxy middleware function with role check
+ *
+ * @example
+ * ```typescript
+ * export default createRoleBasedProxy(
+ *   { auth, protectedRoutes: ['/admin'] },
+ *   'admin'
+ * )
+ * ```
+ */
+export declare function createRoleBasedProxy(config: ProxyMiddlewareConfig, requiredRole: string): (request: NextRequest) => Promise<NextResponse>;
+export { withSecurityHeaders } from './security';
+/**
+ * TODO: Performance
+ * - [ ] Add session caching for proxy middleware
+ * - [ ] Optimize route matching with compiled regex
+ * - [ ] Add request-level session cache
+ * - [ ] Implement route preloading
+ *
+ * TODO: Features
+ * - [ ] Add IP-based rate limiting in proxy
+ * - [ ] Implement request logging
+ * - [ ] Add custom redirect logic support
+ * - [ ] Create route permission system
+ * - [ ] Add middleware chaining support
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for routes
+ * - [ ] Create type-safe route matching
+ * - [ ] Implement compile-time route validation
+ *
+ * TODO: Security
+ * - [ ] Add request fingerprinting
+ * - [ ] Implement bot detection
+ * - [ ] Add DDoS protection
+ * - [ ] Create security event logging
+ *
+ * TODO: Testing
+ * - [ ] Add comprehensive unit tests
+ * - [ ] Test route matching logic
+ * - [ ] Test redirect behavior
+ * - [ ] Add Next.js integration tests
+ *
+ * TODO: Documentation
+ * - [ ] Document proxy middleware usage
+ * - [ ] Add route protection guide
+ * - [ ] Create security best practices guide
+ *
+ * TODO: Limitations
+ * - [ ] Proxy middleware runs on every request (consider caching)
+ * - [ ] Session check is synchronous (consider async optimization)
+ * - [ ] Route matching is simple (consider regex support)
+ */

package/dist/nextjs/server/actions.d.ts

@@ -0,0 +1,30 @@
+import { MulguardInstance } from '../../mulguard';
+import { Verify2FAData, AuthResult, EmailCredentials, RegisterData } from '../../core/types';
+/**
+ * Verify 2FA code - Server Action
+ *
+ * @example
+ * ```typescript
+ * 'use client'
+ * import { verify2FAAction } from 'mulguard/nextjs/server'
+ * import { auth } from '@/lib/auth'
+ *
+ * const result = await verify2FAAction(auth, { email, userId, code })
+ * ```
+ */
+export declare function verify2FAAction(auth: MulguardInstance, data: Verify2FAData): Promise<AuthResult>;
+/**
+ * Sign out - Server Action
+ */
+export declare function signOutAction(auth: MulguardInstance): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Sign in with email - Server Action
+ */
+export declare function signInEmailAction(auth: MulguardInstance, credentials: EmailCredentials): Promise<AuthResult>;
+/**
+ * Sign up - Server Action
+ */
+export declare function signUpAction(auth: MulguardInstance, data: RegisterData): Promise<AuthResult>;

package/dist/{server → nextjs/server}/auth.d.ts

@@ -1,12 +1,12 @@
-import { Session, User } from '../core/types';
-import { MulguardInstance } from '../mulguard';
+import { Session, User } from '../../core/types';
+import { MulguardInstance } from '../../mulguard';
 /**
  * Get server session using auth instance
  *
  * @example
  * ```typescript
  * import { auth } from '@/auth'
- * import { getServerSession } from 'mulguard/server'
+ * import { getServerSession } from 'mulguard/nextjs/server'
  *
  * export default async function Page() {
  *   const session = await getServerSession(auth)
@@ -24,7 +24,7 @@ export declare function getServerSession(auth: MulguardInstance): Promise<Sessio
  * @example
  * ```typescript
  * import { auth } from '@/auth'
- * import { requireAuth } from 'mulguard/server'
+ * import { requireAuth } from 'mulguard/nextjs/server'
  *
  * export default async function ProtectedPage() {
  *   const session = await requireAuth(auth, '/login')
@@ -39,7 +39,7 @@ export declare function requireAuth(auth: MulguardInstance, redirectTo?: string)
  * @example
  * ```typescript
  * import { auth } from '@/auth'
- * import { requireRole } from 'mulguard/server'
+ * import { requireRole } from 'mulguard/nextjs/server'
  *
  * export default async function AdminPage() {
  *   const session = await requireRole(auth, 'admin', '/unauthorized')
@@ -54,7 +54,7 @@ export declare function requireRole(auth: MulguardInstance, role: string, redire
  * @example
  * ```typescript
  * import { auth } from '@/auth'
- * import { getCurrentUser } from 'mulguard/server'
+ * import { getCurrentUser } from 'mulguard/nextjs/server'
  *
  * export default async function Page() {
  *   const user = await getCurrentUser(auth)

package/dist/{server → nextjs/server}/cookies.d.ts

@@ -1,4 +1,4 @@
-import { SessionConfig } from '../core/types';
+import { SessionConfig } from '../../core/types';
 export interface CookieOptions {
     name: string;
     value: string;
@@ -10,10 +10,6 @@ export interface CookieOptions {
     path?: string;
     domain?: string;
 }
-/**
- * Get cookie value from Next.js cookies
- */
-export declare function getCookie(name: string): Promise<string | undefined>;
 /**
  * Result of setting a cookie
  */
@@ -22,9 +18,12 @@ export interface SetCookieResult {
     error?: string;
     warning?: string;
 }
+/**
+ * Get cookie value from Next.js cookies
+ */
+export declare function getCookie(name: string): Promise<string | undefined>;
 /**
  * Set cookie in Next.js response
- * Note: This requires using Next.js 15+ with async cookies() or response cookies
  *
  * @returns Result indicating success or failure with error message
  */

package/dist/nextjs/server/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Next.js Server-Side Integration for Mulguard Authentication Library.
+ *
+ * Provides server-side utilities for Next.js App Router including:
+ * - Session management (getServerSession, getServerUser)
+ * - Server Actions helpers
+ * - Cookie utilities
+ * - Authentication helpers
+ *
+ * @module @mulguard/nextjs/server
+ */
+export * from './session';
+export * from './actions';
+export { requireAuth, requireRole, getCurrentUser } from './auth';
+export * from './cookies';
+export * from './session-helpers';
+export * from './oauth-state';
+export type { Session, User } from '../../core/types';

package/dist/{server → nextjs/server}/oauth-state.d.ts

@@ -1,12 +1,14 @@
 /**
- * Server-side OAuth state management
- * Stores OAuth state in httpOnly cookies for security
+ * Server-side OAuth state management for Next.js.
+ *
+ * Stores OAuth state in httpOnly cookies for security.
  *
  * ✅ SECURE: Uses httpOnly cookies to prevent XSS attacks
  * ✅ PRODUCTION-READY: Works with Next.js Server Actions
  *
  * ⚠️ NOTE: For production with multiple server instances, use Redis or Database store instead.
- * See: mulguard/core/auth/oauth-state-store-redis
+ *
+ * @module @mulguard/nextjs/server/oauth-state
  */
 /**
  * Store OAuth state in httpOnly cookie

package/dist/{server → nextjs/server}/session-helpers.d.ts

@@ -1,8 +1,6 @@
-import { Session } from '../core/types';
+import { Session } from '../../core/types';
 /**
  * Check if session is expired (helper version that accepts null)
- * Note: The main isSessionExpired is exported from session.ts
- * This is a convenience helper for nullable sessions
  */
 export declare function isSessionExpiredNullable(session: Session | null): boolean;
 /**

package/dist/nextjs/server/session.d.ts

@@ -0,0 +1,144 @@
+import { Session, User } from '../../core/types';
+import { MulguardInstance } from '../../mulguard';
+/**
+ * Gets the current session on the server side.
+ *
+ * Reads session from cookie and validates expiration.
+ * Works in Server Components, Server Actions, and API Routes.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
+ * @param auth - Mulguard instance
+ * @returns Current session or null if not authenticated
+ * @throws SessionExpiredError if session is expired
+ *
+ * @example
+ * ```typescript
+ * // In Server Component
+ * import { getServerSession } from 'mulguard/nextjs/server'
+ * import { auth } from '@/lib/auth'
+ *
+ * export default async function DashboardPage() {
+ *   const session = await getServerSession(auth)
+ *   if (!session) {
+ *     redirect('/login')
+ *   }
+ *   return <div>Welcome, {session.user.name}!</div>
+ * }
+ * ```
+ */
+export declare function getServerSession<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(auth: MulguardInstance): Promise<TSession | null>;
+/**
+ * Checks if user is authenticated on the server side.
+ *
+ * @param auth - Mulguard instance
+ * @returns True if user is authenticated
+ *
+ * @example
+ * ```typescript
+ * const isAuthenticated = await isAuthenticated(auth)
+ * if (!isAuthenticated) {
+ *   redirect('/login')
+ * }
+ * ```
+ */
+export declare function isAuthenticated(auth: MulguardInstance): Promise<boolean>;
+/**
+ * Gets the current user from session on the server side.
+ *
+ * @template TUser - User type
+ * @param auth - Mulguard instance
+ * @returns Current user or null if not authenticated
+ *
+ * @example
+ * ```typescript
+ * const user = await getServerUser(auth)
+ * if (user) {
+ *   console.log('User:', user.email)
+ * }
+ * ```
+ */
+export declare function getServerUser<TUser extends User = User>(auth: MulguardInstance): Promise<TUser | null>;
+/**
+ * Server Action wrapper for authentication operations.
+ *
+ * Provides type-safe server actions with automatic error handling.
+ *
+ * @template TResult - Result type
+ * @param action - Server action function
+ * @returns Server action result
+ *
+ * @example
+ * ```typescript
+ * 'use server'
+ *
+ * import { createServerAction } from 'mulguard/nextjs/server'
+ * import { auth } from '@/lib/auth'
+ *
+ * export const signInAction = createServerAction(async (email: string, password: string) => {
+ *   return await auth.signIn('credentials', { email, password })
+ * })
+ * ```
+ */
+export declare function createServerAction<TResult>(action: () => Promise<TResult>): () => Promise<TResult>;
+/**
+ * Server Action with authentication check.
+ *
+ * Ensures user is authenticated before executing action.
+ *
+ * @template TResult - Result type
+ * @template TUser - User type
+ * @param auth - Mulguard instance
+ * @param action - Server action function with user parameter
+ * @returns Server action result
+ *
+ * @example
+ * ```typescript
+ * 'use server'
+ *
+ * import { createAuthenticatedAction } from 'mulguard/nextjs/server'
+ * import { auth } from '@/lib/auth'
+ *
+ * export const updateProfileAction = createAuthenticatedAction(auth, async (user, data) => {
+ *   // User is guaranteed to be authenticated here
+ *   return await updateUserProfile(user.id, data)
+ * })
+ * ```
+ */
+export declare function createAuthenticatedAction<TResult, TUser extends User = User>(auth: MulguardInstance, action: (user: TUser) => Promise<TResult>): () => Promise<TResult>;
+export type { Session, User } from '../../core/types';
+export { SessionExpiredError } from '../../core/errors';
+/**
+ * TODO: Performance
+ * - [ ] Add session caching for Server Components
+ * - [ ] Implement request-level session cache
+ * - [ ] Optimize cookie reading
+ * - [ ] Add session preloading
+ *
+ * TODO: Features
+ * - [ ] Add session refresh helpers
+ * - [ ] Implement session invalidation
+ * - [ ] Add session middleware support
+ * - [ ] Create session debugging utilities
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for session IDs
+ * - [ ] Create type-safe cookie handling
+ * - [ ] Implement compile-time session validation
+ *
+ * TODO: Testing
+ * - [ ] Add comprehensive unit tests
+ * - [ ] Test Server Actions integration
+ * - [ ] Test cookie handling
+ * - [ ] Add Next.js integration tests
+ *
+ * TODO: Documentation
+ * - [ ] Document Server Actions usage
+ * - [ ] Add Server Components guide
+ * - [ ] Create API Routes guide
+ *
+ * TODO: Limitations
+ * - [ ] Cookie handling requires Next.js cookies() API
+ * - [ ] Server Actions require 'use server' directive
+ * - [ ] Session caching is per-request (consider global cache)
+ */

package/dist/oauth-state-Drwz6fES.js

@@ -0,0 +1 @@
+"use strict";var y=Object.defineProperty;var m=(t,e,r)=>e in t?y(t,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):t[e]=r;var a=(t,e,r)=>m(t,typeof e!="symbol"?e+"":e,r);const o=require("./actions-CMtg7FGv.js"),S=require("next/navigation");class l extends Error{constructor(r,s,i,E){super(s);a(this,"code");a(this,"statusCode");a(this,"details");this.name="AuthError",this.code=r,this.statusCode=i??o.getErrorStatusCode(r),this.details=E,Error.captureStackTrace&&Error.captureStackTrace(this,l)}toJSON(){return{code:this.code,message:this.message,statusCode:this.statusCode,details:this.details}}toErrorResult(){return{success:!1,error:this.message,errorCode:this.code,details:this.details}}}class c extends l{constructor(e="Session has expired",r){super(o.AuthErrorCode.SESSION_EXPIRED,e,void 0,r),this.name="SessionExpiredError"}}function f(t){return!t||!t.expiresAt?!1:new Date(t.expiresAt)<new Date}function O(t,e=5){if(!t||!t.expiresAt)return!1;const r=new Date(t.expiresAt),s=new Date,i=(r.getTime()-s.getTime())/(1e3*60);return i>0&&i<e}function T(t){if(!t||!t.expiresAt)return null;const e=new Date(t.expiresAt),r=new Date,s=(e.getTime()-r.getTime())/(1e3*60);return s>0?Math.floor(s):0}function v(t){return!(!t||!t.user||!t.user.id||!t.user.email||!t.user.name||f(t))}function h(t){if(!t||typeof t!="object")return!1;const e=t;if(!e.user||typeof e.user!="object")return!1;const r=e.user;if(typeof r.id!="string"||r.id.length===0||typeof r.email!="string"||r.email.length===0||typeof r.name!="string"||r.name.length===0||!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(r.email))return!1;if(e.expiresAt)if(e.expiresAt instanceof Date){if(isNaN(e.expiresAt.getTime()))return!1}else if(typeof e.expiresAt=="string"){const i=new Date(e.expiresAt);if(isNaN(i.getTime()))return!1}else return!1;return!0}async function u(t){try{const e=await t.getSession();if(!e)return null;if((typeof e.expiresAt=="string"?new Date(e.expiresAt):e.expiresAt).getTime()<Date.now())throw new c("Session has expired");return e}catch(e){if(e instanceof c)throw e;return null}}async function C(t){try{return await u(t)!==null}catch{return!1}}async function D(t){const e=await u(t);return(e==null?void 0:e.user)||null}function N(t){return async()=>{try{return await t()}catch(e){throw e}}}function _(t,e){return async()=>{const r=await u(t);if(!r)throw new Error("Authentication required");return await e(r.user)}}async function A(t){try{const e=await t.getSession();return!e||!h(e)||f(e)?null:e}catch(e){return process.env.NODE_ENV==="development"&&console.error("Failed to get server session:",e),null}}async function g(t,e="/login"){const r=await A(t);return r||S.redirect(e),r}async function k(t,e,r="/unauthorized"){const s=await g(t);return(!s.user.roles||!s.user.roles.includes(e))&&S.redirect(r),s}async function U(t){const e=await A(t);return(e==null?void 0:e.user)??null}const d="__mulguard_oauth_state",p=10*60;async function x(t,e){try{const r=JSON.stringify({state:t,provider:e,expiresAt:Date.now()+p*1e3}),s=process.env.NODE_ENV==="production";return await o.setCookie({name:d,value:r,httpOnly:!0,secure:s,sameSite:"lax",maxAge:p,path:"/"})}catch(r){return{success:!1,error:r instanceof Error?r.message:"Failed to store OAuth state"}}}async function w(){try{const t=await o.getCookie(d);if(!t)return null;const e=JSON.parse(t);return e.expiresAt<Date.now()?(await n(),null):(await n(),{state:e.state,provider:e.provider})}catch{return await n(),null}}async function n(){await o.deleteCookie(d,{path:"/"})}const b=Object.freeze(Object.defineProperty({__proto__:null,deleteOAuthStateCookie:n,getOAuthStateCookie:w,storeOAuthStateCookie:x},Symbol.toStringTag,{value:"Module"}));exports.SessionExpiredError=c;exports.createAuthenticatedAction=_;exports.createServerAction=N;exports.deleteOAuthStateCookie=n;exports.getCurrentUser=U;exports.getOAuthStateCookie=w;exports.getServerSession=u;exports.getServerUser=D;exports.getSessionTimeUntilExpiry=T;exports.isAuthenticated=C;exports.isSessionExpiredNullable=f;exports.isSessionExpiringSoon=O;exports.isSessionValid=v;exports.oauthState=b;exports.requireAuth=g;exports.requireRole=k;exports.storeOAuthStateCookie=x;exports.validateSessionStructure=h;