@payez/next-mvp 3.0.0

package/src/api-handlers/auth/signout.ts

@@ -0,0 +1,212 @@
+/**
+ * Authentication Signout API Handler
+ *
+ * Handles user session termination and cookie cleanup.
+ * This handler is designed to be imported and used by Next.js applications
+ * using the @payez/next-mvp package.
+ *
+ * @version 2.0
+ * @requires No authentication (public endpoint)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+import { deleteSession } from '../../lib/session-store';
+import { getToken } from 'next-auth/jwt';
+import {
+  getSessionCookieName,
+  getSecureSessionCookieName,
+  getCsrfCookieName,
+  getSecureCsrfCookieName,
+  getCallbackUrlCookieName,
+  getJwtCookieName
+} from '../../lib/app-slug';
+
+// JWT decode helper - simple base64 decode without verification
+function jwtDecode(token: string): any {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = parts[1];
+    const decoded = Buffer.from(payload, 'base64').toString('utf-8');
+    return JSON.parse(decoded);
+  } catch (e) {
+    return null;
+  }
+}
+
+// Add protection headers to all responses
+function addSecurityHeaders(response: NextResponse) {
+  response.headers.set('Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';");
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('X-XSS-Protection', '1; mode=block');
+  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()');
+  response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+  response.headers.set('Pragma', 'no-cache');
+  response.headers.set('Expires', '0');
+  return response;
+}
+
+interface SignoutResponse {
+  success: boolean;
+  message: string;
+  sessionDeleted?: boolean;
+  chunkCookiesDeleted?: number;
+}
+
+interface SignoutConfig {
+  nextAuthSecret: string;
+}
+
+/**
+ * Creates a signout handler for Next.js API routes
+ *
+ * @param config Configuration for NextAuth
+ * @returns Next.js POST handler function
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/signout/route.ts
+ * import { createSignoutHandler } from '@payez/next-mvp/api-handlers/auth/signout';
+ *
+ * export const POST = createSignoutHandler({
+ *   nextAuthSecret: process.env.NEXTAUTH_SECRET!
+ * });
+ * ```
+ */
+export function createSignoutHandler(config: SignoutConfig) {
+  const { nextAuthSecret } = config;
+
+  return async function POST(req: NextRequest) {
+    const cookieStore = await cookies();
+
+    // Get app-slug prefixed cookie names
+    const sessionCookieName = getSessionCookieName();
+    const secureSessionCookieName = getSecureSessionCookieName();
+
+    // Handle chunked session tokens (for large JWTs)
+    let sessionToken: string | undefined;
+    const sessionTokenCookie = cookieStore.get(sessionCookieName);
+
+    if (sessionTokenCookie?.value) {
+      // Single cookie case
+      sessionToken = sessionTokenCookie.value;
+    } else {
+      // Chunked cookie case - reconstruct from parts
+      const chunkCookies = cookieStore.getAll()
+        .filter(cookie => cookie.name.startsWith(`${sessionCookieName}.`))
+        .sort((a, b) => {
+          const aIndex = parseInt(a.name.split('.').pop() || '0');
+          const bIndex = parseInt(b.name.split('.').pop() || '0');
+          return aIndex - bIndex;
+        });
+
+      if (chunkCookies.length > 0) {
+        sessionToken = chunkCookies.map(cookie => cookie.value).join('');
+      }
+    }
+
+    // Get chunk cookies for cleanup count
+    const chunkCookies = cookieStore.getAll()
+      .filter(cookie => cookie.name.startsWith(`${sessionCookieName}.`));
+
+    // Decode NextAuth JWT to extract the Redis session UUID before deletion
+    let redisSessionToken: string | null = null;
+
+    // First attempt: NextAuth getToken (verified + robust in most cases)
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    try {
+      const token = await getToken({ req, secret: nextAuthSecret, cookieName: getJwtCookieName() });
+      redisSessionToken = (token as any)?.sessionToken || (token as any)?.redisSessionId || null;
+    } catch (e) {
+      console.warn('[SIGNOUT] getToken() failed to extract session token (will try manual decode)');
+    }
+
+    // Second attempt: manual decode of the session cookie JWT (no verification)
+    if (!redisSessionToken && (sessionToken || cookieStore.getAll().some(c => c.name.startsWith(`${sessionCookieName}.`)))) {
+      try {
+        // Reconstruct raw JWT from chunked cookies if necessary
+        let rawJwt: string | null = null;
+        const direct = cookieStore.get(sessionCookieName);
+        if (direct?.value) {
+          rawJwt = direct.value;
+        } else {
+          const chunks = cookieStore.getAll()
+            .filter(c => c.name.startsWith(`${sessionCookieName}.`))
+            .sort((a, b) => {
+              const ai = parseInt(a.name.split('.').pop() || '0');
+              const bi = parseInt(b.name.split('.').pop() || '0');
+              return ai - bi;
+            })
+            .map(c => c.value);
+          if (chunks.length > 0) rawJwt = chunks.join('');
+        }
+
+        if (rawJwt) {
+          const decoded: any = jwtDecode(rawJwt);
+          if (decoded && typeof decoded === 'object' && typeof decoded.sessionToken === 'string') {
+            redisSessionToken = decoded.sessionToken;
+          }
+        }
+      } catch (e) {
+        console.warn('[SIGNOUT] Manual JWT decode failed to extract session token');
+      }
+    }
+
+    // Delete Redis session if UUID was extracted
+    if (redisSessionToken) {
+      try {
+        await deleteSession(redisSessionToken);
+        console.info('[SIGNOUT] Redis session cleanup successful', {
+          sessionToken: redisSessionToken.substring(0, 8) + '...'
+        });
+      } catch (sessionError) {
+        // Log error but don't fail the signout process
+        console.error('[SIGNOUT] Redis session cleanup failed', { error: sessionError });
+      }
+    } else {
+      console.warn('[SIGNOUT] No Redis session token (UUID) extracted from cookie; skipping Redis deletion');
+    }
+
+    // Build response
+    const responseData: SignoutResponse = {
+      success: true,
+      message: sessionToken ? 'Session deleted successfully' : 'No active session found',
+      sessionDeleted: !!sessionToken,
+      chunkCookiesDeleted: chunkCookies.length
+    };
+
+    const response = NextResponse.json(responseData);
+
+    // Always clear cookies, regardless of success/failure (using app-slug prefixed names)
+    try {
+      response.cookies.delete(sessionCookieName);
+      response.cookies.delete(secureSessionCookieName);
+      response.cookies.delete(getCsrfCookieName());
+      response.cookies.delete(getSecureCsrfCookieName());
+      response.cookies.delete(getCallbackUrlCookieName());
+      response.cookies.delete(`__Secure-${getCallbackUrlCookieName()}`);
+      response.cookies.delete('twoFactorSessionVerified');
+
+      // Delete chunked session cookies
+      chunkCookies.forEach(cookie => {
+        response.cookies.delete(cookie.name);
+      });
+    } catch (cookieError) {
+      console.error('[SIGNOUT] Cookie cleanup failed:', cookieError);
+    }
+
+    return addSecurityHeaders(response);
+  };
+}
+
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export const POST = createSignoutHandler({
+  nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/src/api-handlers/auth/status.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { resolveNextAuthSecret } from '../../lib/nextauth-secret';
+import { getSession as getRedisSession } from '../../lib/session-store';
+import { getJwtCookieName } from '../../lib/app-slug';
+
+export async function GET(req: NextRequest) {
+  try {
+    let token: any = await getToken({ req, secret: await resolveNextAuthSecret(), cookieName: getJwtCookieName() });
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const sessionToken = (token as any)?.sessionToken || (token as any)?.redisSessionId;
+    if (!sessionToken) {
+      return NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
+    }
+    const sessionModel = await getRedisSession(sessionToken);
+    if (!sessionModel) {
+      return NextResponse.json({ success: false, error: 'Session missing in Redis' }, { status: 401 });
+    }
+    return NextResponse.json({ success: true, userId: (sessionModel as any).userId || null });
+  } catch (err) {
+    return NextResponse.json({ success: false, error: err instanceof Error ? err.message : 'Unknown error' }, { status: 500 });
+  }
+}

package/src/api-handlers/auth/update-session.ts

@@ -0,0 +1,125 @@
+/**
+ * Authentication Update Session API Handler
+ *
+ * Handles session updates, particularly for 2FA status changes.
+ * This handler is designed to be imported and used by Next.js applications
+ * using the @payez/next-mvp package.
+ *
+ * @version 2.0
+ * @requires Authentication (authenticated endpoint)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { getJwtCookieName } from '../../lib/app-slug';
+
+// Add protection headers to all responses
+function addSecurityHeaders(response: NextResponse) {
+  response.headers.set('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';");
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('X-XSS-Protection', '1; mode=block');
+  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()');
+  response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+  response.headers.set('Pragma', 'no-cache');
+  response.headers.set('Expires', '0');
+  return response;
+}
+
+interface UpdateSessionRequest {
+  twoFactorSessionVerified?: boolean;
+  twoFactorMethod?: string;
+}
+
+interface UpdateSessionResponse {
+  success: boolean;
+  twoFactorSessionVerified: boolean;
+  twoFactorMethod?: string;
+}
+
+interface UpdateSessionConfig {
+  nextAuthSecret: string;
+}
+
+/**
+ * Creates an update-session handler for Next.js API routes
+ *
+ * @param config Configuration for NextAuth
+ * @returns Next.js POST handler function
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/update-session/route.ts
+ * import { createUpdateSessionHandler } from '@payez/next-mvp/api-handlers/auth/update-session';
+ *
+ * export const POST = createUpdateSessionHandler({
+ *   nextAuthSecret: process.env.NEXTAUTH_SECRET!
+ * });
+ * ```
+ */
+export function createUpdateSessionHandler(config: UpdateSessionConfig) {
+  const { nextAuthSecret } = config;
+
+  return async function POST(req: NextRequest) {
+    try {
+      let body: UpdateSessionRequest;
+
+      try {
+        body = await req.json();
+      } catch (parseError) {
+        return addSecurityHeaders(NextResponse.json(
+          { error: 'Invalid JSON format' },
+          { status: 400 }
+        ));
+      }
+
+      const { twoFactorSessionVerified, twoFactorMethod } = body;
+
+      // Get the current token
+      const token = await getToken({ req, secret: nextAuthSecret, cookieName: getJwtCookieName() });
+      if (!token) {
+        return addSecurityHeaders(NextResponse.json(
+          { error: 'No session token available' },
+          { status: 401 }
+        ));
+      }
+
+      // Update the token with 2FA challenge completion status
+      const updatedToken = {
+        ...token,
+        twoFactorSessionVerified: !!twoFactorSessionVerified,
+        twoFactorMethod: twoFactorMethod || token.twoFactorMethod
+      };
+
+      console.info('[UPDATE-SESSION] Session updated successfully', {
+        userId: token.sub,
+        twoFactorSessionVerified: updatedToken.twoFactorSessionVerified,
+        twoFactorMethod: updatedToken.twoFactorMethod
+      });
+
+      const responseData: UpdateSessionResponse = {
+        success: true,
+        twoFactorSessionVerified: updatedToken.twoFactorSessionVerified as boolean,
+        twoFactorMethod: updatedToken.twoFactorMethod as string | undefined
+      };
+
+      return addSecurityHeaders(NextResponse.json(responseData));
+    } catch (error) {
+      console.error('[UPDATE-SESSION] Error updating session', { error });
+      return addSecurityHeaders(NextResponse.json(
+        { error: 'Failed to update session' },
+        { status: 500 }
+      ));
+    }
+  };
+}
+
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export const POST = createUpdateSessionHandler({
+  nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/src/api-handlers/auth/validate.ts

@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG, API_ENDPOINTS } from '../../config/env';
+import { getTokenTestAware } from '../../lib/test-aware-get-token';
+import { getSession } from '../../lib/session-store';
+
+/**
+ * Validates current access token with the IDP and returns normalized info.
+ * Sources access token from Authorization header or Redis session via cookie.
+ */
+export async function GET(req: NextRequest) {
+  try {
+    // 1) Prefer Authorization header if present
+    let bearer: string | undefined = undefined;
+    const authHeader = req.headers.get('authorization') || req.headers.get('Authorization');
+    if (authHeader && /^Bearer\s+/i.test(authHeader)) bearer = authHeader.replace(/^Bearer\s+/i, '').trim();
+
+    // 2) If not, resolve from session
+    if (!bearer) {
+      const tok = await getTokenTestAware(req);
+      const sessionToken = tok?.sessionToken as string | undefined;
+      if (sessionToken) {
+        const sess = await getSession(sessionToken);
+        bearer = sess?.accessToken;
+      }
+    }
+
+    if (!bearer) {
+      return NextResponse.json({ success: false, error: { code: 'UNAUTHORIZED', message: 'No access token available' } }, { status: 401 });
+    }
+
+    const url = `${ENV_CONFIG.IDP_URL}${API_ENDPOINTS.externalAuth.validate}`;
+    const result = await idpFetchJSON(req, url, { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } });
+
+    if (!result.ok) {
+      return NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status }, data: result.json }, { status: result.status });
+    }
+
+    // Passthrough normalized
+    return NextResponse.json(result.json ?? { success: true }, { status: 200 });
+  } catch (e: any) {
+    return NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: e?.message || 'validate error' } }, { status: 500 });
+  }
+}

package/src/api-handlers/auth/verify-code.ts

@@ -0,0 +1,129 @@
+/**
+ * Authentication Verify Code / Complete 2FA API Handler
+ *
+ * Handles 2FA verification and token updates after successful verification.
+ * This handler is designed to be imported and used by Next.js applications
+ * using the @payez/next-mvp package.
+ *
+ * @version 2.0
+ * @requires Authentication (authenticated endpoint)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { updateTokens, mark2FAComplete } from '../../lib/session-store';
+import { getJwtCookieName } from '../../lib/app-slug';
+
+interface VerifyCodeRequest {
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpires: number;
+  refreshTokenExpires?: number;
+}
+
+interface VerifyCodeConfig {
+  nextAuthSecret: string;
+}
+
+/**
+ * Creates a verify-code/complete-2FA handler for Next.js API routes
+ *
+ * @param config Configuration for NextAuth
+ * @returns Next.js POST handler function
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/verify-code/route.ts
+ * import { createVerifyCodeHandler } from '@payez/next-mvp/api-handlers/auth/verify-code';
+ *
+ * export const POST = createVerifyCodeHandler({
+ *   nextAuthSecret: process.env.NEXTAUTH_SECRET!
+ * });
+ * ```
+ */
+export function createVerifyCodeHandler(config: VerifyCodeConfig) {
+  const { nextAuthSecret } = config;
+
+  return async function POST(req: NextRequest) {
+    try {
+      let body: VerifyCodeRequest;
+
+      try {
+        body = await req.json();
+      } catch (parseError) {
+        return NextResponse.json(
+          { success: false, message: 'Invalid JSON format' },
+          { status: 400 }
+        );
+      }
+
+      const { accessToken, refreshToken, accessTokenExpires, refreshTokenExpires } = body;
+
+      // Get current session token from JWT
+      let token: any = await getToken({ req, secret: nextAuthSecret, cookieName: getJwtCookieName() });
+
+      // The sessionToken is stored in the JWT token object
+      // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+      const sessionToken = (token?.sessionToken || token?.redisSessionId) as string;
+
+      if (!sessionToken) {
+        console.error('[VERIFY-CODE] No session token found in JWT', {
+          hasToken: !!token,
+          tokenKeys: token ? Object.keys(token) : []
+        });
+        return NextResponse.json(
+          { success: false, message: 'No session found' },
+          { status: 401 }
+        );
+      }
+
+      console.info('[VERIFY-CODE] Updating session with new tokens after 2FA', {
+        sessionToken: sessionToken.substring(0, 8) + '...',
+        userId: token?.sub,
+        hasAccessToken: !!accessToken,
+        hasRefreshToken: !!refreshToken,
+        accessTokenLength: accessToken?.length,
+        refreshTokenLength: refreshToken?.length
+      });
+
+      // Update tokens in Redis
+      await updateTokens(
+        sessionToken,
+        accessToken,
+        refreshToken,
+        accessTokenExpires,
+        refreshTokenExpires
+      );
+
+      // Mark 2FA as complete
+      await mark2FAComplete(sessionToken);
+
+      console.info('[VERIFY-CODE] 2FA completion successful', {
+        sessionToken: sessionToken.substring(0, 8) + '...',
+        userId: token?.sub
+      });
+
+      return NextResponse.json({
+        success: true,
+        message: '2FA verification complete'
+      });
+    } catch (error) {
+      console.error('[VERIFY-CODE] Failed to complete 2FA', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+
+      return NextResponse.json(
+        { success: false, message: 'Failed to complete 2FA' },
+        { status: 500 }
+      );
+    }
+  };
+}
+
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export const POST = createVerifyCodeHandler({
+  nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/src/api-handlers/session/refresh-viability.ts

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession, isRefreshInProgress } from '../../lib/session-store';
+import { checkRefreshViability } from '../../lib/refresh-token-validator';
+import { getTokenTestAware } from '../../lib/test-aware-get-token';
+import { logger } from '../../config/logger';
+
+export async function GET(req: NextRequest) {
+  try {
+    const sessionToken = req.nextUrl.searchParams.get('token');
+    let finalSessionToken = sessionToken;
+    if (!finalSessionToken) {
+      const token = await getTokenTestAware(req);
+      // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+      finalSessionToken = (token?.sessionToken || token?.redisSessionId) as string;
+    }
+    if (!finalSessionToken) {
+      return NextResponse.json({ canRefresh: false, reason: 'not_logged_in', sessionToken: null }, { status: 200 });
+    }
+    const refreshInProgress = await isRefreshInProgress(finalSessionToken);
+    if (refreshInProgress) {
+      // Still need to get session data for twoFactorComplete even when refresh is in progress
+      const sessionData = await getSession(finalSessionToken);
+      logger.info('[REFRESH-VIABILITY] Refresh already in progress, telling middleware to wait', { sessionToken: finalSessionToken.substring(0, 8) + '...' });
+      return NextResponse.json({ canRefresh: true, reason: 'refresh_in_progress', refreshInProgress: true, sessionToken: finalSessionToken, twoFactorComplete: sessionData?.mfaVerified ?? (sessionData as any)?.twoFactorComplete ?? false }, { status: 200 });
+    }
+    const sessionData = await getSession(finalSessionToken);
+    if (!sessionData) {
+      return NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionToken: finalSessionToken }, { status: 200 });
+    }
+    const viabilityCheck = checkRefreshViability(sessionData);
+    return NextResponse.json({ canRefresh: viabilityCheck.canRefresh, reason: viabilityCheck.reason, timeRemaining: viabilityCheck.timeRemaining, expiresAt: viabilityCheck.expiresAt, accessTokenExpired: viabilityCheck.accessTokenExpired, accessTokenTimeRemaining: viabilityCheck.accessTokenTimeRemaining, sessionToken: finalSessionToken, twoFactorComplete: sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false, userId: sessionData.userId, refreshInProgress: false });
+  } catch (error) {
+    logger.error('[REFRESH-VIABILITY] Error checking refresh viability', { error: error instanceof Error ? error.message : String(error) });
+    return NextResponse.json({ canRefresh: false, reason: 'check_error', error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+  }
+}