@payez/next-mvp 3.0.0

package/dist/api-handlers/auth/signout.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+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 declare function createSignoutHandler(config: SignoutConfig): (req: NextRequest) => Promise<NextResponse<unknown>>;
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export declare const POST: (req: NextRequest) => Promise<NextResponse<unknown>>;
+export {};

package/dist/api-handlers/auth/signout.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+exports.createSignoutHandler = createSignoutHandler;
+const server_1 = require("next/server");
+const headers_1 = require("next/headers");
+const session_store_1 = require("../../lib/session-store");
+const jwt_1 = require("next-auth/jwt");
+const app_slug_1 = require("../../lib/app-slug");
+// JWT decode helper - simple base64 decode without verification
+function jwtDecode(token) {
+    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) {
+    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;
+}
+/**
+ * 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!
+ * });
+ * ```
+ */
+function createSignoutHandler(config) {
+    const { nextAuthSecret } = config;
+    return async function POST(req) {
+        const cookieStore = await (0, headers_1.cookies)();
+        // Get app-slug prefixed cookie names
+        const sessionCookieName = (0, app_slug_1.getSessionCookieName)();
+        const secureSessionCookieName = (0, app_slug_1.getSecureSessionCookieName)();
+        // Handle chunked session tokens (for large JWTs)
+        let sessionToken;
+        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 = 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 (0, jwt_1.getToken)({ req, secret: nextAuthSecret, cookieName: (0, app_slug_1.getJwtCookieName)() });
+            redisSessionToken = token?.sessionToken || token?.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 = 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 = 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 (0, session_store_1.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 = {
+            success: true,
+            message: sessionToken ? 'Session deleted successfully' : 'No active session found',
+            sessionDeleted: !!sessionToken,
+            chunkCookiesDeleted: chunkCookies.length
+        };
+        const response = server_1.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((0, app_slug_1.getCsrfCookieName)());
+            response.cookies.delete((0, app_slug_1.getSecureCsrfCookieName)());
+            response.cookies.delete((0, app_slug_1.getCallbackUrlCookieName)());
+            response.cookies.delete(`__Secure-${(0, app_slug_1.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
+ */
+exports.POST = createSignoutHandler({
+    nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/dist/api-handlers/auth/status.d.ts

@@ -0,0 +1,8 @@
+import { NextRequest, NextResponse } from 'next/server';
+export declare function GET(req: NextRequest): Promise<NextResponse<{
+    success: boolean;
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    userId: any;
+}>>;

package/dist/api-handlers/auth/status.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+const server_1 = require("next/server");
+const jwt_1 = require("next-auth/jwt");
+const nextauth_secret_1 = require("../../lib/nextauth-secret");
+const session_store_1 = require("../../lib/session-store");
+const app_slug_1 = require("../../lib/app-slug");
+async function GET(req) {
+    try {
+        let token = await (0, jwt_1.getToken)({ req, secret: await (0, nextauth_secret_1.resolveNextAuthSecret)(), cookieName: (0, app_slug_1.getJwtCookieName)() });
+        // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+        const sessionToken = token?.sessionToken || token?.redisSessionId;
+        if (!sessionToken) {
+            return server_1.NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
+        }
+        const sessionModel = await (0, session_store_1.getSession)(sessionToken);
+        if (!sessionModel) {
+            return server_1.NextResponse.json({ success: false, error: 'Session missing in Redis' }, { status: 401 });
+        }
+        return server_1.NextResponse.json({ success: true, userId: sessionModel.userId || null });
+    }
+    catch (err) {
+        return server_1.NextResponse.json({ success: false, error: err instanceof Error ? err.message : 'Unknown error' }, { status: 500 });
+    }
+}

package/dist/api-handlers/auth/update-session.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+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 declare function createUpdateSessionHandler(config: UpdateSessionConfig): (req: NextRequest) => Promise<NextResponse<unknown>>;
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export declare const POST: (req: NextRequest) => Promise<NextResponse<unknown>>;
+export {};

package/dist/api-handlers/auth/update-session.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+exports.createUpdateSessionHandler = createUpdateSessionHandler;
+const server_1 = require("next/server");
+const jwt_1 = require("next-auth/jwt");
+const app_slug_1 = require("../../lib/app-slug");
+// Add protection headers to all responses
+function addSecurityHeaders(response) {
+    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;
+}
+/**
+ * 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!
+ * });
+ * ```
+ */
+function createUpdateSessionHandler(config) {
+    const { nextAuthSecret } = config;
+    return async function POST(req) {
+        try {
+            let body;
+            try {
+                body = await req.json();
+            }
+            catch (parseError) {
+                return addSecurityHeaders(server_1.NextResponse.json({ error: 'Invalid JSON format' }, { status: 400 }));
+            }
+            const { twoFactorSessionVerified, twoFactorMethod } = body;
+            // Get the current token
+            const token = await (0, jwt_1.getToken)({ req, secret: nextAuthSecret, cookieName: (0, app_slug_1.getJwtCookieName)() });
+            if (!token) {
+                return addSecurityHeaders(server_1.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 = {
+                success: true,
+                twoFactorSessionVerified: updatedToken.twoFactorSessionVerified,
+                twoFactorMethod: updatedToken.twoFactorMethod
+            };
+            return addSecurityHeaders(server_1.NextResponse.json(responseData));
+        }
+        catch (error) {
+            console.error('[UPDATE-SESSION] Error updating session', { error });
+            return addSecurityHeaders(server_1.NextResponse.json({ error: 'Failed to update session' }, { status: 500 }));
+        }
+    };
+}
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+exports.POST = createUpdateSessionHandler({
+    nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/dist/api-handlers/auth/validate.d.ts

@@ -0,0 +1,6 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Validates current access token with the IDP and returns normalized info.
+ * Sources access token from Authorization header or Redis session via cookie.
+ */
+export declare function GET(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/auth/validate.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
+const session_store_1 = require("../../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.
+ */
+async function GET(req) {
+    try {
+        // 1) Prefer Authorization header if present
+        let bearer = 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 (0, test_aware_get_token_1.getTokenTestAware)(req);
+            const sessionToken = tok?.sessionToken;
+            if (sessionToken) {
+                const sess = await (0, session_store_1.getSession)(sessionToken);
+                bearer = sess?.accessToken;
+            }
+        }
+        if (!bearer) {
+            return server_1.NextResponse.json({ success: false, error: { code: 'UNAUTHORIZED', message: 'No access token available' } }, { status: 401 });
+        }
+        const url = `${env_1.ENV_CONFIG.IDP_URL}${env_1.API_ENDPOINTS.externalAuth.validate}`;
+        const result = await (0, idp_fetch_1.idpFetchJSON)(req, url, { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } });
+        if (!result.ok) {
+            return server_1.NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status }, data: result.json }, { status: result.status });
+        }
+        // Passthrough normalized
+        return server_1.NextResponse.json(result.json ?? { success: true }, { status: 200 });
+    }
+    catch (e) {
+        return server_1.NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: e?.message || 'validate error' } }, { status: 500 });
+    }
+}

package/dist/api-handlers/auth/verify-code.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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';
+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 declare function createVerifyCodeHandler(config: VerifyCodeConfig): (req: NextRequest) => Promise<NextResponse<{
+    success: boolean;
+    message: string;
+}>>;
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+export declare const POST: (req: NextRequest) => Promise<NextResponse<{
+    success: boolean;
+    message: string;
+}>>;
+export {};

package/dist/api-handlers/auth/verify-code.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+exports.createVerifyCodeHandler = createVerifyCodeHandler;
+const server_1 = require("next/server");
+const jwt_1 = require("next-auth/jwt");
+const session_store_1 = require("../../lib/session-store");
+const app_slug_1 = require("../../lib/app-slug");
+/**
+ * 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!
+ * });
+ * ```
+ */
+function createVerifyCodeHandler(config) {
+    const { nextAuthSecret } = config;
+    return async function POST(req) {
+        try {
+            let body;
+            try {
+                body = await req.json();
+            }
+            catch (parseError) {
+                return server_1.NextResponse.json({ success: false, message: 'Invalid JSON format' }, { status: 400 });
+            }
+            const { accessToken, refreshToken, accessTokenExpires, refreshTokenExpires } = body;
+            // Get current session token from JWT
+            let token = await (0, jwt_1.getToken)({ req, secret: nextAuthSecret, cookieName: (0, app_slug_1.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);
+            if (!sessionToken) {
+                console.error('[VERIFY-CODE] No session token found in JWT', {
+                    hasToken: !!token,
+                    tokenKeys: token ? Object.keys(token) : []
+                });
+                return server_1.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 (0, session_store_1.updateTokens)(sessionToken, accessToken, refreshToken, accessTokenExpires, refreshTokenExpires);
+            // Mark 2FA as complete
+            await (0, session_store_1.mark2FAComplete)(sessionToken);
+            console.info('[VERIFY-CODE] 2FA completion successful', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                userId: token?.sub
+            });
+            return server_1.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 server_1.NextResponse.json({ success: false, message: 'Failed to complete 2FA' }, { status: 500 });
+        }
+    };
+}
+/**
+ * Default export for backward compatibility
+ * Requires environment variable: NEXTAUTH_SECRET
+ */
+exports.POST = createVerifyCodeHandler({
+    nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
+});

package/dist/api-handlers/session/refresh-viability.d.ts

@@ -0,0 +1,14 @@
+import { NextRequest, NextResponse } from 'next/server';
+export declare function GET(req: NextRequest): Promise<NextResponse<{
+    canRefresh: boolean;
+    reason: string;
+    sessionToken: null;
+}> | NextResponse<{
+    canRefresh: boolean;
+    reason: string;
+    sessionToken: string;
+}> | NextResponse<{
+    canRefresh: boolean;
+    reason: string;
+    error: string;
+}>>;

package/dist/api-handlers/session/refresh-viability.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+const server_1 = require("next/server");
+const session_store_1 = require("../../lib/session-store");
+const refresh_token_validator_1 = require("../../lib/refresh-token-validator");
+const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
+const logger_1 = require("../../config/logger");
+async function GET(req) {
+    try {
+        const sessionToken = req.nextUrl.searchParams.get('token');
+        let finalSessionToken = sessionToken;
+        if (!finalSessionToken) {
+            const token = await (0, test_aware_get_token_1.getTokenTestAware)(req);
+            // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+            finalSessionToken = (token?.sessionToken || token?.redisSessionId);
+        }
+        if (!finalSessionToken) {
+            return server_1.NextResponse.json({ canRefresh: false, reason: 'not_logged_in', sessionToken: null }, { status: 200 });
+        }
+        const refreshInProgress = await (0, session_store_1.isRefreshInProgress)(finalSessionToken);
+        if (refreshInProgress) {
+            // Still need to get session data for twoFactorComplete even when refresh is in progress
+            const sessionData = await (0, session_store_1.getSession)(finalSessionToken);
+            logger_1.logger.info('[REFRESH-VIABILITY] Refresh already in progress, telling middleware to wait', { sessionToken: finalSessionToken.substring(0, 8) + '...' });
+            return server_1.NextResponse.json({ canRefresh: true, reason: 'refresh_in_progress', refreshInProgress: true, sessionToken: finalSessionToken, twoFactorComplete: sessionData?.mfaVerified ?? sessionData?.twoFactorComplete ?? false }, { status: 200 });
+        }
+        const sessionData = await (0, session_store_1.getSession)(finalSessionToken);
+        if (!sessionData) {
+            return server_1.NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionToken: finalSessionToken }, { status: 200 });
+        }
+        const viabilityCheck = (0, refresh_token_validator_1.checkRefreshViability)(sessionData);
+        return server_1.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.twoFactorComplete ?? false, userId: sessionData.userId, refreshInProgress: false });
+    }
+    catch (error) {
+        logger_1.logger.error('[REFRESH-VIABILITY] Error checking refresh viability', { error: error instanceof Error ? error.message : String(error) });
+        return server_1.NextResponse.json({ canRefresh: false, reason: 'check_error', error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+    }
+}

package/dist/api-handlers/session/viability.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Session Viability Check API Handler for `@payez/next-mvp`
+ *
+ * This API route is called by the middleware to securely check if a session is valid.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+export declare function GET(req: NextRequest): Promise<NextResponse<{
+    error: string;
+    message: string;
+    code: string;
+}> | NextResponse<{
+    authenticated: boolean;
+}>>;