@payez/next-mvp 3.0.0

package/src/routes/account/masked-info.ts

@@ -0,0 +1,37 @@
+/**
+ * Ready-to-Use Masked Info Route
+ *
+ * Provides a pre-configured handler for fetching masked contact information
+ * during 2FA flow. Can be imported directly into your app's API routes with
+ * zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/account/masked-info/route.ts
+ * export { POST } from '@payez/next-mvp/routes/account/masked-info';
+ * ```
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Re-export the POST handler from api-handlers
+// Note: IDP uses POST for masked-info endpoint
+export { POST } from '../../api-handlers/account/masked-info';
+
+/**
+ * Pre-configured POST handler for masked contact information
+ *
+ * This endpoint is typically called during the 2FA flow to display masked
+ * email/phone options to the user.
+ *
+ * Environment variables used:
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - NEXTAUTH_SECRET (required)
+ *
+ * Returns:
+ * - Masked email addresses
+ * - Masked phone numbers
+ * - Contact method preferences
+ */

package/src/routes/account/send-code.ts

@@ -0,0 +1,40 @@
+/**
+ * Ready-to-Use Send Code Route
+ *
+ * Provides a pre-configured handler for sending 2FA verification codes
+ * to the user's registered contact methods. Can be imported directly
+ * into your app's API routes with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/account/send-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/account/send-code';
+ * ```
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Re-export the POST handler from api-handlers
+export { POST } from '../../api-handlers/account/send-code';
+
+/**
+ * Pre-configured POST handler for sending verification codes
+ *
+ * This endpoint triggers the IDP to send a verification code to the
+ * user's selected contact method (email or SMS).
+ *
+ * Request body:
+ * - method: 'email' | 'sms' - The contact method to use
+ * - contactId: string - ID of the masked contact to send to
+ *
+ * Environment variables used:
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - NEXTAUTH_SECRET (required)
+ *
+ * Returns:
+ * - Success status
+ * - Rate limit information
+ * - Cooldown timer if applicable
+ */

package/src/routes/account/update-phone.ts

@@ -0,0 +1,13 @@
+/**
+ * Update Phone Route
+ *
+ * Ready-to-use route handler for updating phone number.
+ * Used for 2FA setup - users need to add a phone to enable SMS verification.
+ *
+ * @example
+ * ```typescript
+ * // app/api/account/update-phone/route.ts
+ * export { POST } from '@payez/next-mvp/routes/account/update-phone';
+ * ```
+ */
+export { POST } from '../../api-handlers/account/update-phone';

package/src/routes/account/verify-email.ts

@@ -0,0 +1,41 @@
+/**
+ * Ready-to-Use Verify Email Route
+ *
+ * Provides a pre-configured handler for verifying email-based 2FA codes.
+ * Can be imported directly into your app's API routes with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/account/verify-email/route.ts
+ * export { POST } from '@payez/next-mvp/routes/account/verify-email';
+ * ```
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Re-export the POST handler from api-handlers
+export { POST } from '../../api-handlers/account/verify-email';
+
+/**
+ * Pre-configured POST handler for verifying email 2FA codes
+ *
+ * This endpoint verifies the code sent to the user's email address
+ * and upgrades the provisional session to a full session.
+ *
+ * Request body:
+ * - code: string - The 6-digit verification code
+ * - emailId: string - ID of the email address used
+ *
+ * Environment variables used:
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - NEXTAUTH_SECRET (required)
+ *
+ * Returns:
+ * - Upgraded access token with MFA claim
+ * - New refresh token
+ * - Session upgrade status
+ * - AMR (Authentication Methods Reference) array
+ * - ACR (Authentication Context Class) level
+ */

package/src/routes/account/verify-sms.ts

@@ -0,0 +1,41 @@
+/**
+ * Ready-to-Use Verify SMS Route
+ *
+ * Provides a pre-configured handler for verifying SMS-based 2FA codes.
+ * Can be imported directly into your app's API routes with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/account/verify-sms/route.ts
+ * export { POST } from '@payez/next-mvp/routes/account/verify-sms';
+ * ```
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Re-export the POST handler from api-handlers
+export { POST } from '../../api-handlers/account/verify-sms';
+
+/**
+ * Pre-configured POST handler for verifying SMS 2FA codes
+ *
+ * This endpoint verifies the code sent to the user's phone number
+ * and upgrades the provisional session to a full session.
+ *
+ * Request body:
+ * - code: string - The 6-digit verification code
+ * - phoneId: string - ID of the phone number used
+ *
+ * Environment variables used:
+ * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - NEXTAUTH_SECRET (required)
+ *
+ * Returns:
+ * - Upgraded access token with MFA claim
+ * - New refresh token
+ * - Session upgrade status
+ * - AMR (Authentication Methods Reference) array
+ * - ACR (Authentication Context Class) level
+ */

package/src/routes/auth/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @payez/next-mvp Ready-to-Use Route Exports
+ *
+ * Pre-configured route handlers that can be imported directly
+ * into your Next.js app with zero configuration.
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+// Export individual route handlers
+export { POST as refreshPOST } from './refresh';
+export { GET as sessionGET, POST as sessionPOST } from './session';
+export { POST as logoutPOST } from './logout';
+export { GET as viabilityGET } from './viability';
+export { GET as nextAuthGET, POST as nextAuthPOST } from './nextauth';
+
+// Also export as namespaced objects for cleaner imports
+export * as refresh from './refresh';
+export * as session from './session';
+export * as logout from './logout';
+export * as viability from './viability';
+export * as nextauth from './nextauth';

package/src/routes/auth/logout.ts

@@ -0,0 +1,127 @@
+/**
+ * Ready-to-Use Logout Route
+ *
+ * Provides a pre-configured logout handler that properly cleans up
+ * sessions and revokes tokens.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/logout/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/logout';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { deleteSession } from '../../lib/session-store';
+import {
+  getSessionCookieName,
+  getSecureSessionCookieName,
+  getCsrfCookieName,
+  getSecureCsrfCookieName,
+  getCallbackUrlCookieName,
+  getJwtCookieName
+} from '../../lib/app-slug';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { siteEvents, getClientIp } from '../../lib/site-logger';
+
+async function getConfig() {
+  const idpConfig = await getIDPClientConfig();
+  const idpBaseUrl = process.env.IDP_URL;
+  if (!idpBaseUrl) {
+    throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
+  }
+  return {
+    nextAuthSecret: idpConfig.nextAuthSecret || '',
+    idpBaseUrl,
+    clientId: process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || '',
+  };
+}
+
+/**
+ * POST /api/auth/logout - Sign out and clean up session
+ *
+ * Performs complete logout:
+ * 1. Revokes tokens at IDP (if refresh token available)
+ * 2. Deletes session from store
+ * 3. Clears NextAuth session cookie
+ */
+export async function POST(req: NextRequest) {
+  const { nextAuthSecret, idpBaseUrl, clientId } = await getConfig();
+
+  try {
+    const token = await getToken({ req, secret: nextAuthSecret, cookieName: getJwtCookieName() });
+
+    if (!token) {
+      // Already logged out
+      return NextResponse.json({
+        success: true,
+        message: 'No active session'
+      });
+    }
+
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const sessionId = (token as any).sessionToken || (token as any).redisSessionId;
+
+    // Delete session from store (this also removes the refresh token)
+    if (sessionId) {
+      try {
+        await deleteSession(sessionId);
+        console.info('[LOGOUT_ROUTE] Session deleted from store');
+      } catch (error) {
+        console.warn('[LOGOUT_ROUTE] Failed to delete session:', error);
+      }
+    }
+
+    // Log logout event (fire-and-forget)
+    const userId = (token as any).sub || (token as any).idpUserId;
+    if (userId) {
+      siteEvents.logout({
+        user_id: userId,
+        session_id: sessionId,
+        trigger: 'user',
+        url: '/api/auth/logout',
+        user_agent: req.headers.get('user-agent') || undefined,
+        ip_address: getClientIp(req.headers) || undefined,
+      });
+    }
+
+    // Build response that clears NextAuth cookies
+    const response = NextResponse.json({
+      success: true,
+      message: 'Logged out successfully'
+    });
+
+    // Clear NextAuth session cookies (using app-slug prefixed names)
+    const cookieNames = [
+      getSessionCookieName(),
+      getSecureSessionCookieName(),
+      getCsrfCookieName(),
+      getSecureCsrfCookieName(),
+      getCallbackUrlCookieName(),
+      `__Secure-${getCallbackUrlCookieName()}`,
+    ];
+
+    // Clear each cookie by setting it with maxAge 0
+    cookieNames.forEach(name => {
+      response.cookies.set(name, '', {
+        maxAge: 0,
+        path: '/',
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax'
+      });
+    });
+
+    return response;
+  } catch (error) {
+    console.error('[LOGOUT_ROUTE] Error during logout:', error);
+    return NextResponse.json({
+      error: 'Failed to logout',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
+}

package/src/routes/auth/nextauth.ts

@@ -0,0 +1,71 @@
+/**
+ * Ready-to-Use NextAuth Route Handler
+ *
+ * Provides a pre-configured NextAuth handler that uses dynamic OAuth providers
+ * loaded from IDP at startup via getAuthOptions().
+ *
+ * @version 2.2.0 - Dynamic provider loading from IDP
+ * @since auth-ready-v2-hotfix
+ */
+
+import NextAuth from 'next-auth';
+import { authOptions, getAuthOptions } from '../../auth/auth-options';
+
+// Cached handler - built once with dynamic providers
+let cachedHandler: ReturnType<typeof NextAuth> | null = null;
+let handlerPromise: Promise<ReturnType<typeof NextAuth>> | null = null;
+
+/**
+ * Get or build the NextAuth handler with dynamic providers.
+ * Uses caching to avoid rebuilding on every request.
+ */
+async function getHandler(): Promise<ReturnType<typeof NextAuth>> {
+    // Return cached if available
+    if (cachedHandler) {
+        return cachedHandler;
+    }
+
+    // Prevent concurrent builds
+    if (handlerPromise) {
+        return handlerPromise;
+    }
+
+    handlerPromise = (async () => {
+        try {
+            // Try to get dynamic auth options from IDP
+            const options = await getAuthOptions();
+            console.log('[NEXTAUTH_ROUTE] Built handler with dynamic providers');
+            cachedHandler = NextAuth(options);
+            return cachedHandler;
+        } catch (error) {
+            // Fallback to static options if IDP unavailable
+            console.warn('[NEXTAUTH_ROUTE] Failed to get dynamic options, using static fallback:', {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            cachedHandler = NextAuth(authOptions);
+            return cachedHandler;
+        } finally {
+            handlerPromise = null;
+        }
+    })();
+
+    return handlerPromise;
+}
+
+/**
+ * GET handler for NextAuth
+ * Uses async factory to get dynamic providers from IDP
+ */
+export async function GET(request: Request, context: any) {
+    const handler = await getHandler();
+    return handler(request, context);
+}
+
+/**
+ * POST handler for NextAuth
+ * Uses async factory to get dynamic providers from IDP
+ */
+export async function POST(request: Request, context: any) {
+    const handler = await getHandler();
+    return handler(request, context);
+}

package/src/routes/auth/refresh.ts

@@ -0,0 +1,54 @@
+/**
+ * Ready-to-Use Refresh Token Route
+ *
+ * Provides a pre-configured refresh handler that can be imported directly
+ * into your app's API routes with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/refresh/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/refresh';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { createRefreshHandler } from '../../api-handlers/auth/refresh';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+// Configuration is read at runtime from IDP config (cached)
+async function getConfig() {
+  const idpConfig = await getIDPClientConfig();
+  const idpBaseUrl = process.env.IDP_URL;
+  if (!idpBaseUrl) {
+    throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
+  }
+  return {
+    idpBaseUrl,
+    clientId: process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || '',
+    nextAuthSecret: idpConfig.nextAuthSecret || '',
+    refreshEndpoint: process.env.REFRESH_ENDPOINT || '/api/ExternalAuth/refresh',
+  };
+}
+
+/**
+ * Pre-configured POST handler for token refresh
+ *
+ * Environment variables used:
+ * - IDP_URL (REQUIRED)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - NEXTAUTH_SECRET (required)
+ * - REFRESH_ENDPOINT (default: /api/ExternalAuth/refresh)
+ */
+let _handler: ReturnType<typeof createRefreshHandler> | null = null;
+
+import { NextRequest } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  if (!_handler) {
+    const config = await getConfig();
+    _handler = createRefreshHandler(config);
+  }
+  return _handler(req);
+}

package/src/routes/auth/session.ts

@@ -0,0 +1,193 @@
+/**
+ * Ready-to-Use Session Management Route
+ *
+ * Provides pre-configured session handlers for checking and updating session state.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/session/route.ts
+ * export { GET, POST } from '@payez/next-mvp/routes/auth/session';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { getSession, updateSession } from '../../lib/session-store';
+import { getJwtCookieName } from '../../lib/app-slug';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+/**
+ * Get NextAuth secret from IDP config (cached).
+ * NEVER use process.env.NEXTAUTH_SECRET - it's always loaded from IDP.
+ */
+async function getNextAuthSecret(): Promise<string> {
+  const config = await getIDPClientConfig();
+  return config.nextAuthSecret || '';
+}
+
+/**
+ * GET /api/auth/session - Check current session status
+ *
+ * Returns the current session information including:
+ * - User details
+ * - Token expiry status
+ * - Session validity
+ */
+export async function GET(req: NextRequest) {
+  try {
+    const secret = await getNextAuthSecret();
+    const cookieName = getJwtCookieName();
+
+    // Debug logging
+    const cookieValue = req.cookies.get(cookieName)?.value;
+    console.log('[SESSION_ROUTE] GET called:', {
+      cookieName,
+      hasCookie: !!cookieValue,
+      cookieLength: cookieValue?.length || 0,
+      secretLength: secret?.length || 0,
+    });
+
+    const token = await getToken({ req, secret, cookieName });
+
+    if (!token) {
+      console.warn('[SESSION_ROUTE] getToken returned null');
+      return NextResponse.json({
+        authenticated: false,
+        message: 'No session found'
+      }, { status: 200 });
+    }
+
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const redisSessionId = (token as any).sessionToken || (token as any).redisSessionId;
+
+    console.log('[SESSION_ROUTE] Token found:', {
+      sub: token.sub,
+      email: token.email,
+      name: token.name,
+      hasExp: !!token.exp,
+      redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'MISSING',
+    });
+
+    // Fetch full session data from Redis
+    const session = redisSessionId ? await getSession(redisSessionId) : null;
+
+    console.log('[SESSION_ROUTE] Redis session:', {
+      found: !!session,
+      userId: session?.userId,
+      roles: session?.roles,
+      hasAccessToken: !!session?.idpAccessToken,
+    });
+
+    // Return NextAuth-compatible session format with Redis data
+    // useSession() expects: { user: {...}, expires: "..." }
+    // We enrich with all session data from Redis
+    return NextResponse.json({
+      user: {
+        id: session?.userId || token.sub,
+        email: session?.email || token.email,
+        name: session?.name || token.name,
+        image: (token as any).picture || null,
+        // Redis session data
+        roles: session?.roles || [],
+        twoFactorSessionVerified: session?.mfaVerified || false,
+        requiresTwoFactor: !session?.mfaVerified,
+        authenticationMethods: session?.authenticationMethods,
+        authenticationLevel: session?.authenticationLevel,
+        mfaCompletedAt: session?.mfaCompletedAt,
+        mfaExpiresAt: session?.mfaExpiresAt,
+        mfaValidityHours: session?.mfaValidityHours,
+        oauthProvider: session?.oauthProvider,
+        idpClientId: session?.idpClientId,
+        merchantId: session?.merchantId,
+      },
+      // Session tokens
+      sessionToken: redisSessionId,
+      accessToken: session?.idpAccessToken,
+      refreshToken: session?.idpRefreshToken,
+      accessTokenExpires: session?.idpAccessTokenExpires,
+      expires: token.exp ? new Date((token.exp as number) * 1000).toISOString() : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+    });
+  } catch (error) {
+    console.error('[SESSION_ROUTE] Error checking session:', error);
+    return NextResponse.json({
+      error: 'Failed to check session',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/auth/session - Update session data
+ *
+ * Allows updating session metadata (not tokens).
+ * Token refresh should use the /api/auth/refresh endpoint.
+ *
+ * Body:
+ * - metadata: object - Custom metadata to store in session
+ */
+export async function POST(req: NextRequest) {
+  try {
+    const secret = await getNextAuthSecret();
+    const token = await getToken({ req, secret, cookieName: getJwtCookieName() });
+
+    if (!token) {
+      return NextResponse.json({
+        error: 'No session found',
+        code: 'UNAUTHORIZED'
+      }, { status: 401 });
+    }
+
+    // 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({
+        error: 'Invalid session',
+        code: 'INVALID_SESSION'
+      }, { status: 400 });
+    }
+
+    const body = await req.json();
+    const { metadata, access_token, refresh_token, twoFactorComplete, twoFactorMethod } = body;
+
+    // Get current session
+    const session = await getSession(sessionToken);
+    if (!session) {
+      return NextResponse.json({
+        error: 'Session not found',
+        code: 'SESSION_NOT_FOUND'
+      }, { status: 404 });
+    }
+
+    // Update session with new data
+    const updatedSession = {
+      ...session,
+      ...(access_token ? { accessToken: access_token } : {}),
+      ...(refresh_token ? { refreshToken: refresh_token } : {}),
+      ...(typeof twoFactorComplete === 'boolean' ? { twoFactorComplete } : {}),
+      ...(twoFactorMethod ? { twoFactorMethod } : {}),
+      ...(metadata ? {
+        metadata: {
+          ...(session.metadata || {}),
+          ...metadata,
+          updatedAt: new Date().toISOString()
+        }
+      } : {})
+    };
+
+    await updateSession(sessionToken, updatedSession);
+
+    return NextResponse.json({
+      success: true,
+      message: 'Session updated successfully'
+    });
+  } catch (error) {
+    console.error('[SESSION_ROUTE] Error updating session:', error);
+    return NextResponse.json({
+      error: 'Failed to update session',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
+}