@payez/next-mvp 3.4.0 → 3.5.0

package/src/server/auth-guard.ts

@@ -0,0 +1,170 @@
+/**
+ * Server-Side Auth Guard for Layouts
+ *
+ * Replaces middleware's self-fetch auth checks with direct Redis/function calls.
+ * Call from server-component layouts to protect routes.
+ *
+ * Zero HTTP self-fetches. ~8ms total (Redis + in-memory checks).
+ */
+
+import 'server-only';
+import { redirect } from 'next/navigation';
+import { headers } from 'next/headers';
+import { decodeSession } from './decode-session';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import type { SessionData } from '../lib/session-store';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AuthGuardOptions {
+  /** Custom checks to run after standard auth validation */
+  checks?: AuthCheck[];
+  /** Override login redirect URL (default: /account-auth/login) */
+  loginUrl?: string;
+  /** Override 2FA redirect URL (default: /account-auth/verify-code) */
+  verifyCodeUrl?: string;
+  /** Override service unavailable URL (default: /service-unavailable) */
+  serviceUnavailableUrl?: string;
+}
+
+export interface AuthCheck {
+  /** Name for logging */
+  name: string;
+  /** Returns redirect URL if check fails, null if passes */
+  check: (session: SessionData, pathname: string) => Promise<string | null>;
+}
+
+export interface AuthGuardResult {
+  userId: string;
+  email: string;
+  roles: string[];
+  sessionData: SessionData;
+  accessToken?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const LOGIN_PAGE = '/account-auth/login';
+const VERIFY_CODE_PAGE = '/account-auth/verify-code';
+const SERVICE_UNAVAILABLE_PAGE = '/service-unavailable';
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Server-side auth guard. Call from async server layouts.
+ *
+ * Redirects (via next/navigation redirect()) if:
+ * - No session cookie / invalid JWT
+ * - Session not in Redis (stale)
+ * - Session force-invalidated
+ * - 2FA required but not completed / expired
+ * - Any custom check fails
+ *
+ * Returns the authenticated user's session data on success.
+ */
+export async function authGuard(options?: AuthGuardOptions): Promise<AuthGuardResult> {
+  const loginUrl = options?.loginUrl || LOGIN_PAGE;
+  const verifyCodeUrl = options?.verifyCodeUrl || VERIFY_CODE_PAGE;
+  const serviceUnavailableUrl = options?.serviceUnavailableUrl || SERVICE_UNAVAILABLE_PAGE;
+
+  // Get current pathname from headers (set by Next.js)
+  const headerStore = await headers();
+  const pathname = headerStore.get('x-next-pathname') ||
+                   headerStore.get('x-invoke-path') ||
+                   headerStore.get('x-matched-path') ||
+                   '/';
+
+  const callbackUrl = encodeURIComponent(pathname);
+
+  // --- Decode session (cookie → JWT → Redis) ---
+  let decoded: Awaited<ReturnType<typeof decodeSession>>;
+  try {
+    decoded = await decodeSession();
+  } catch (error) {
+    // Redis unreachable or startup failure → fail closed
+    console.error('[AUTH-GUARD] Session decode failed (service error):', error instanceof Error ? error.message : String(error));
+    redirect(serviceUnavailableUrl);
+  }
+
+  // No session at all → redirect to login
+  if (!decoded) {
+    redirect(`${loginUrl}?callbackUrl=${callbackUrl}`);
+  }
+
+  const { sessionData } = decoded;
+
+  // --- Force-invalidated session (admin action, password change) ---
+  if (sessionData.forceInvalidated) {
+    console.warn('[AUTH-GUARD] Session force-invalidated', {
+      userId: sessionData.userId,
+      pathname,
+    });
+    redirect(`${loginUrl}?callbackUrl=${callbackUrl}&reason=invalidated`);
+  }
+
+  // --- 2FA check ---
+  try {
+    const config = await getIDPClientConfig();
+    const requires2FA = config.authSettings?.require2FA ?? true;
+
+    if (requires2FA) {
+      const mfaVerified = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
+      const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
+      const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+
+      if (!mfaVerified || mfaExpired) {
+        console.log('[AUTH-GUARD] 2FA required', {
+          mfaVerified,
+          mfaExpired,
+          userId: sessionData.userId,
+          pathname,
+        });
+        redirect(`${verifyCodeUrl}?callbackUrl=${callbackUrl}`);
+      }
+    }
+  } catch (error) {
+    // If we can't check 2FA config, fail closed
+    console.error('[AUTH-GUARD] 2FA config check failed:', error instanceof Error ? error.message : String(error));
+    redirect(serviceUnavailableUrl);
+  }
+
+  // --- Custom checks (beta, admin, etc.) ---
+  if (options?.checks) {
+    for (const check of options.checks) {
+      try {
+        const redirectUrl = await check.check(sessionData, pathname);
+        if (redirectUrl) {
+          console.log(`[AUTH-GUARD] Custom check "${check.name}" failed`, {
+            userId: sessionData.userId,
+            pathname,
+            redirectUrl,
+          });
+          redirect(redirectUrl);
+        }
+      } catch (error) {
+        // If the error is a redirect (from next/navigation), re-throw it
+        if (error && typeof error === 'object' && 'digest' in error) {
+          throw error;
+        }
+        console.error(`[AUTH-GUARD] Custom check "${check.name}" error:`, error instanceof Error ? error.message : String(error));
+        redirect(serviceUnavailableUrl);
+      }
+    }
+  }
+
+  // --- All checks passed ---
+  return {
+    userId: sessionData.userId,
+    email: sessionData.email,
+    roles: sessionData.roles || [],
+    sessionData,
+    accessToken: sessionData.idpAccessToken,
+  };
+}

package/src/server/decode-session.ts

@@ -0,0 +1,91 @@
+/**
+ * Server-Side Session Decoder
+ *
+ * Reads the JWT session cookie, decodes it with jose, and fetches the
+ * full session from Redis. Used by authGuard (layouts) and withAuth (API routes).
+ *
+ * Zero HTTP self-fetches. Direct Redis reads only.
+ */
+
+import 'server-only';
+import { cookies } from 'next/headers';
+import { jwtVerify, type JWTPayload } from 'jose';
+import { getSession, type SessionData } from '../lib/session-store';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import { ensureInitialized } from '../lib/startup-init';
+
+export interface DecodedSession {
+  sessionData: SessionData;
+  jwtPayload: JWTPayload & { sessionToken?: string; redisSessionId?: string };
+}
+
+/**
+ * Decode the session from cookies and Redis.
+ * Returns null if no valid session exists.
+ *
+ * @param requestCookies Optional cookie getter for API route context (NextRequest.cookies).
+ *                       If omitted, uses next/headers cookies() for server components.
+ */
+export async function decodeSession(
+  requestCookies?: { get: (name: string) => { value: string } | undefined }
+): Promise<DecodedSession | null> {
+  try {
+    // Ensure startup initialization is complete (Redis, IDP config, etc.)
+    await ensureInitialized();
+
+    // Get the JWT cookie value
+    const cookieStore = requestCookies || (await cookies());
+    const sessionCookieName = getSessionCookieName();
+    const secureCookieName = getSecureSessionCookieName();
+
+    const cookieValue =
+      cookieStore.get(secureCookieName)?.value ||
+      cookieStore.get(sessionCookieName)?.value;
+
+    if (!cookieValue) {
+      return null;
+    }
+
+    // Get the NextAuth secret from IDP config
+    const config = await getIDPClientConfig();
+    const secret = config.nextAuthSecret;
+    if (!secret) {
+      console.error('[DECODE-SESSION] No nextAuthSecret available from IDP config');
+      return null;
+    }
+
+    // Decode the JWT (same pattern as test-aware-get-token.ts)
+    const secretKey = new TextEncoder().encode(secret);
+    let payload: JWTPayload;
+    try {
+      const result = await jwtVerify(cookieValue, secretKey);
+      payload = result.payload;
+    } catch (jwtError) {
+      // JWT decode failed - cookie may be corrupted or secret rotated
+      console.warn('[DECODE-SESSION] JWT verification failed:', jwtError instanceof Error ? jwtError.message : String(jwtError));
+      return null;
+    }
+
+    // Extract the Redis session ID from JWT payload
+    const sessionToken = (payload as any).sessionToken || (payload as any).redisSessionId;
+    if (!sessionToken) {
+      console.warn('[DECODE-SESSION] JWT payload missing sessionToken/redisSessionId');
+      return null;
+    }
+
+    // Fetch session from Redis (direct, no HTTP)
+    const sessionData = await getSession(sessionToken);
+    if (!sessionData) {
+      return null;
+    }
+
+    return {
+      sessionData,
+      jwtPayload: payload as DecodedSession['jwtPayload'],
+    };
+  } catch (error) {
+    console.error('[DECODE-SESSION] Error:', error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}

package/src/server/slim-middleware.ts

@@ -0,0 +1,117 @@
+/**
+ * Slim Middleware — Cookie-Only Auth Check
+ *
+ * Replaces the self-fetching middleware with a cookie existence check.
+ * All real auth validation happens in server-side layouts (authGuard).
+ *
+ * Zero self-fetches. Zero Redis calls. Zero JWT decoding.
+ * Just: does the session cookie exist? Yes → pass through. No → redirect to login.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface SlimMiddlewareOptions {
+  /** Routes that don't require authentication (glob-style patterns) */
+  publicRoutes?: string[];
+  /** Login page URL (default: /account-auth/login) */
+  loginUrl?: string;
+  /** Additional paths to always bypass (e.g., /api/auth/, /api/session/) */
+  bypassPrefixes?: string[];
+}
+
+// =============================================================================
+// DEFAULT BYPASS PATHS
+// =============================================================================
+
+/** Routes that must always bypass middleware (prevent infinite loops) */
+const DEFAULT_BYPASS_PREFIXES = [
+  '/api/auth/',
+  '/api/session/',
+  '/_next/',
+  '/favicon.ico',
+];
+
+/** Static file extensions to bypass */
+const STATIC_EXTENSIONS = /\.(svg|png|jpg|jpeg|gif|webp|ico|css|js|woff|woff2|ttf|eot|map)$/i;
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Create a slim middleware that only checks cookie existence.
+ * Auth validation is deferred to server-side layouts (authGuard).
+ */
+export function createSlimMiddleware(options?: SlimMiddlewareOptions) {
+  const publicRoutes = options?.publicRoutes || [];
+  const loginUrl = options?.loginUrl || '/account-auth/login';
+  const extraBypass = options?.bypassPrefixes || [];
+  const allBypass = [...DEFAULT_BYPASS_PREFIXES, ...extraBypass];
+
+  // Pre-compile public route patterns for fast matching
+  const publicMatchers = publicRoutes.map(pattern => {
+    if (pattern.endsWith('/*')) {
+      const prefix = pattern.slice(0, -2);
+      return (p: string) => p === prefix || p.startsWith(prefix + '/');
+    }
+    if (pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1);
+      return (p: string) => p.startsWith(prefix);
+    }
+    if (pattern.startsWith('/*.')) {
+      const ext = pattern.slice(2);
+      return (p: string) => p.endsWith(ext);
+    }
+    return (p: string) => p === pattern;
+  });
+
+  return function middleware(request: NextRequest): NextResponse {
+    const { pathname } = request.nextUrl;
+
+    // 1. Always bypass static/internal routes
+    if (STATIC_EXTENSIONS.test(pathname)) {
+      return NextResponse.next();
+    }
+    for (const prefix of allBypass) {
+      if (pathname.startsWith(prefix)) {
+        return NextResponse.next();
+      }
+    }
+
+    // 2. Check if it's a public route → pass through
+    for (const matcher of publicMatchers) {
+      if (matcher(pathname)) {
+        return NextResponse.next();
+      }
+    }
+
+    // 3. THE ONLY AUTH CHECK: Does a session cookie exist?
+    const sessionCookieName = getSessionCookieName();
+    const secureCookieName = getSecureSessionCookieName();
+    const hasCookie =
+      request.cookies.has(sessionCookieName) ||
+      request.cookies.has(secureCookieName);
+
+    if (!hasCookie) {
+      // No cookie on a protected route → redirect to login
+      // API routes get 401 instead of redirect
+      if (pathname.startsWith('/api/')) {
+        return NextResponse.json(
+          { error: 'Unauthorized', message: 'No session' },
+          { status: 401 }
+        );
+      }
+
+      const callbackUrl = encodeURIComponent(pathname);
+      return NextResponse.redirect(new URL(`${loginUrl}?callbackUrl=${callbackUrl}`, request.url));
+    }
+
+    // Cookie exists → pass through, layout authGuard does the real validation
+    return NextResponse.next();
+  };
+}

package/src/server/with-auth.ts

@@ -0,0 +1,93 @@
+/**
+ * Server-Side Auth Wrapper for API Routes & Server Actions
+ *
+ * Wraps route handlers with session validation. Uses direct Redis reads.
+ * Zero HTTP self-fetches.
+ *
+ * Usage:
+ *   export const GET = withAuth(async (req, auth) => {
+ *     return NextResponse.json({ userId: auth.userId });
+ *   });
+ *
+ *   // With role requirement:
+ *   export const POST = withAuth(async (req, auth) => { ... }, { requiredRoles: ['admin'] });
+ */
+
+import 'server-only';
+import { NextRequest, NextResponse } from 'next/server';
+import { decodeSession } from './decode-session';
+import type { SessionData } from '../lib/session-store';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface ApiAuthResult {
+  userId: string;
+  email: string;
+  roles: string[];
+  sessionData: SessionData;
+  accessToken?: string;
+}
+
+export interface WithAuthOptions {
+  /** Roles required to access the route (any match = allowed) */
+  requiredRoles?: string[];
+}
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Wrap an API route handler with auth validation.
+ * Returns 401 if not authenticated, 403 if missing required roles.
+ */
+export function withAuth(
+  handler: (req: NextRequest, auth: ApiAuthResult) => Promise<NextResponse>,
+  options?: WithAuthOptions
+): (req: NextRequest) => Promise<NextResponse> {
+  return async (req: NextRequest): Promise<NextResponse> => {
+    try {
+      // Decode session from request cookies (direct Redis, no self-fetch)
+      const decoded = await decodeSession(req.cookies);
+
+      if (!decoded) {
+        return NextResponse.json(
+          { error: 'Unauthorized', message: 'No valid session' },
+          { status: 401 }
+        );
+      }
+
+      const { sessionData } = decoded;
+
+      // Check required roles
+      if (options?.requiredRoles && options.requiredRoles.length > 0) {
+        const userRoles = sessionData.roles || [];
+        const hasRole = options.requiredRoles.some(r => userRoles.includes(r));
+        if (!hasRole) {
+          return NextResponse.json(
+            { error: 'Forbidden', message: 'Insufficient permissions' },
+            { status: 403 }
+          );
+        }
+      }
+
+      const auth: ApiAuthResult = {
+        userId: sessionData.userId,
+        email: sessionData.email,
+        roles: sessionData.roles || [],
+        sessionData,
+        accessToken: sessionData.idpAccessToken,
+      };
+
+      return handler(req, auth);
+    } catch (error) {
+      console.error('[WITH-AUTH] Error:', error instanceof Error ? error.message : String(error));
+      return NextResponse.json(
+        { error: 'Internal Server Error', message: 'Auth check failed' },
+        { status: 500 }
+      );
+    }
+  };
+}