@payez/next-mvp 4.1.14 → 4.1.21

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

@@ -371,7 +371,7 @@ function createRefreshHandler(config) {
                     const errorMessage = idpError.message || 'Token refresh failed';
                     // CRITICAL: 401 means token is definitively invalid - always discard
                     // This prevents redirect loops where viability check keeps returning canRefresh:true
-                    const discardToken = refreshResponse.status === 401 || idpError.discard_token === true;
+                    let discardToken = refreshResponse.status === 401 || idpError.discard_token === true;
                     const retryable = refreshResponse.status !== 401 && idpError.retryable === true;
                     const resolution = idpError.resolution || null;
                     // ============================================================================
@@ -408,20 +408,43 @@ function createRefreshHandler(config) {
                     console.error('[AUTH_REFRESH] Full IDP error response:', JSON.stringify(responseData, null, 2).substring(0, 1000));
                     // If IDP signals to discard token, clear it from Redis
                     if (discardToken) {
-                        console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP signaled discard_token', {
-                            reason: 'IDP_DISCARD_TOKEN',
-                            errorCode,
-                            userId,
-                            sessionToken: sessionToken.substring(0, 8) + '...',
-                            hadRefreshToken: !!currentSession.idpRefreshToken,
-                            stack: new Error().stack
-                        });
-                        await (0, session_store_1.updateSession)(sessionToken, {
-                            idpRefreshToken: '',
-                            idpRefreshTokenExpires: undefined,
-                            refreshTokenClearedAt: Date.now(),
-                            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
-                        });
+                        // Race-safe discard (CAS): only clear if the refresh token we sent is STILL
+                        // the current one. A concurrent refresh may have already rotated it — our 401
+                        // is then stale, and wiping here would silently log out a healthy session
+                        // (the rotation-race wipe, QA 6873 site 2). Skip the wipe + drop terminal if changed.
+                        const postRefresh = await (0, session_store_1.getSession)(sessionToken);
+                        const tokenUnchanged = !!originalRefreshToken && postRefresh?.idpRefreshToken === originalRefreshToken;
+                        if (tokenUnchanged) {
+                            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP signaled discard_token', {
+                                reason: 'IDP_DISCARD_TOKEN',
+                                errorCode,
+                                userId,
+                                sessionToken: sessionToken.substring(0, 8) + '...',
+                                hadRefreshToken: !!currentSession.idpRefreshToken,
+                                stack: new Error().stack
+                            });
+                            await (0, session_store_1.updateSession)(sessionToken, {
+                                idpRefreshToken: '',
+                                idpRefreshTokenExpires: undefined,
+                                refreshTokenClearedAt: Date.now(),
+                                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
+                            });
+                        }
+                        else {
+                            // Concurrent refresh already rotated the token — our 401 is stale. Return the
+                            // freshly-rotated token directly so the loser succeeds without a retry
+                            // (race-fix follow-up #1).
+                            discardToken = false;
+                            console.warn('[AUTH_REFRESH] Discard suppressed: refresh token already rotated by a concurrent refresh — returning the fresh token (race-safe).');
+                            if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+                                return server_1.NextResponse.json({
+                                    refreshed: true,
+                                    reason: 'completed_by_concurrent_request',
+                                    accessTokenExpires: postRefresh.idpAccessTokenExpires,
+                                    hasRefreshToken: !!postRefresh.idpRefreshToken,
+                                });
+                            }
+                        }
                     }
                     return server_1.NextResponse.json({
                         error: errorMessage,

package/dist/api-handlers/mfa/backup-code-verify.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Verify Backup Code 2FA Challenge Handler
+ *
+ * Verifies a single-use recovery code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped backup-code GENERATION (backup-codes.ts, POST
+ * /api/Account/mfa/backup-codes) and no way to SPEND one. Codes could be
+ * generated, displayed once, written down — and then never used to satisfy a
+ * login challenge. Exactly the gap TOTP had before totp-verify: the enrolment
+ * half without the challenge half.
+ *
+ * THIS IS THE FACTOR OF LAST RESORT. A user reaches for a backup code when they
+ * have lost the authenticator, so it is the one path that must work when
+ * everything else has already failed. A recovery mechanism that cannot be
+ * redeemed is worse than none: it invites people to rely on it.
+ *
+ * FIELD NAME: the IDP expects { "code": ... }
+ * (MfaBackupCodeVerifyRequest, [JsonPropertyName("code")]). The dash in
+ * 'xxxx-xxxx' is optional per the IDP contract, so the code is forwarded as
+ * typed and normalisation is left to the IDP rather than guessed here.
+ *
+ * SINGLE USE, CONSUMED ATOMICALLY. The IDP hash-compares against unused codes
+ * and stamps used_at + used_by_ip in the same operation (MfaController 5g).
+ * NEVER retry this call on a network error or an ambiguous response — a retry
+ * can burn a second code, and the user has ten.
+ *
+ * DO NOT MAKE GENERATION TRANSITION THE SESSION, the same trap totp-confirm
+ * carries: generating recovery codes is not proof of possessing one.
+ *
+ * THE STORED 2FA METHOD IS 'totp', NOT 'backup_code'. READ THIS BEFORE
+ * "CORRECTING" IT — it looks wrong and is not.
+ *
+ *   1. IT MATCHES THE IDP. MfaController 5g sets
+ *      `TwoFactorMethod = TwoFactorMethodType.Totp` for this exact path,
+ *      commented "Backup code = recovery proof of the TOTP factor", and the
+ *      reissued token's amr carries mfa+totp. A backup code is not a separate
+ *      factor; it is recovery proof of the authenticator factor.
+ *
+ *   2. INVENTING A NEW VALUE SILENTLY BREAKS TOKEN REFRESH. refresh.ts:279
+ *      resolves the method with ['sms','totp','email'].includes(m). Anything
+ *      outside that set is dropped, so `two_factor_method` never reaches the
+ *      IDP on refresh, and a session established with a recovery code refreshes
+ *      differently from one established with the authenticator — for the same
+ *      underlying factor. It fails quietly, days later, as "sessions
+ *      occasionally drop", with nothing pointing back to this string.
+ *
+ * The type union (email|sms|totp) is not the reason for the choice, it is a
+ * coincidence that caught it. Widening the union would have compiled and
+ * shipped the refresh bug.
+ *
+ * @package @payez/next-mvp
+ */
+import { NextRequest, NextResponse } from 'next/server';
+export declare function POST(req: NextRequest): Promise<NextResponse<{
+    success: boolean;
+    error: string;
+    code: string;
+}> | NextResponse<{
+    success: boolean;
+    error: any;
+    code: any;
+    meta: {
+        attemptedRefresh: boolean;
+    };
+}> | NextResponse<{
+    success: boolean;
+    verificationSuccessful: boolean;
+    twoFactorSessionVerified: boolean;
+    codeConsumed: boolean;
+    message: any;
+}>>;

package/dist/api-handlers/mfa/backup-code-verify.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Verify Backup Code 2FA Challenge Handler
+ *
+ * Verifies a single-use recovery code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped backup-code GENERATION (backup-codes.ts, POST
+ * /api/Account/mfa/backup-codes) and no way to SPEND one. Codes could be
+ * generated, displayed once, written down — and then never used to satisfy a
+ * login challenge. Exactly the gap TOTP had before totp-verify: the enrolment
+ * half without the challenge half.
+ *
+ * THIS IS THE FACTOR OF LAST RESORT. A user reaches for a backup code when they
+ * have lost the authenticator, so it is the one path that must work when
+ * everything else has already failed. A recovery mechanism that cannot be
+ * redeemed is worse than none: it invites people to rely on it.
+ *
+ * FIELD NAME: the IDP expects { "code": ... }
+ * (MfaBackupCodeVerifyRequest, [JsonPropertyName("code")]). The dash in
+ * 'xxxx-xxxx' is optional per the IDP contract, so the code is forwarded as
+ * typed and normalisation is left to the IDP rather than guessed here.
+ *
+ * SINGLE USE, CONSUMED ATOMICALLY. The IDP hash-compares against unused codes
+ * and stamps used_at + used_by_ip in the same operation (MfaController 5g).
+ * NEVER retry this call on a network error or an ambiguous response — a retry
+ * can burn a second code, and the user has ten.
+ *
+ * DO NOT MAKE GENERATION TRANSITION THE SESSION, the same trap totp-confirm
+ * carries: generating recovery codes is not proof of possessing one.
+ *
+ * THE STORED 2FA METHOD IS 'totp', NOT 'backup_code'. READ THIS BEFORE
+ * "CORRECTING" IT — it looks wrong and is not.
+ *
+ *   1. IT MATCHES THE IDP. MfaController 5g sets
+ *      `TwoFactorMethod = TwoFactorMethodType.Totp` for this exact path,
+ *      commented "Backup code = recovery proof of the TOTP factor", and the
+ *      reissued token's amr carries mfa+totp. A backup code is not a separate
+ *      factor; it is recovery proof of the authenticator factor.
+ *
+ *   2. INVENTING A NEW VALUE SILENTLY BREAKS TOKEN REFRESH. refresh.ts:279
+ *      resolves the method with ['sms','totp','email'].includes(m). Anything
+ *      outside that set is dropped, so `two_factor_method` never reaches the
+ *      IDP on refresh, and a session established with a recovery code refreshes
+ *      differently from one established with the authenticator — for the same
+ *      underlying factor. It fails quietly, days later, as "sessions
+ *      occasionally drop", with nothing pointing back to this string.
+ *
+ * The type union (email|sms|totp) is not the reason for the choice, it is a
+ * coincidence that caught it. Widening the union would have compiled and
+ * shipped the refresh bug.
+ *
+ * @package @payez/next-mvp
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+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");
+const jwt_decode_1 = require("../../lib/jwt-decode");
+async function POST(req) {
+    try {
+        const body = await req.json();
+        const code = body.code || body.backupCode || body.verificationCode || body.verification_code;
+        if (!code) {
+            return server_1.NextResponse.json({
+                success: false,
+                error: 'Backup code is required',
+                code: 'INVALID_REQUEST',
+            }, { status: 400 });
+        }
+        const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/backup-code/verify`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ code }),
+        });
+        if (!result.ok) {
+            return server_1.NextResponse.json({
+                success: false,
+                error: result.json?.message || 'Verification failed',
+                code: result.json?.code || 'IDP_ERROR',
+                meta: { attemptedRefresh: result.attemptedRefresh },
+            }, { status: result.status });
+        }
+        const unwrappedData = result.json?.data || result.json;
+        // Only a challenge that returns fresh tokens may transition the session.
+        let sessionTransitioned = false;
+        if (unwrappedData.access_token && unwrappedData.refresh_token) {
+            const token = await (0, test_aware_get_token_1.getTokenTestAware)(req);
+            const sessionToken = (token?.sessionToken || token?.redisSessionId);
+            if (sessionToken) {
+                let accessTokenExpires = Date.now() + 15 * 60 * 1000;
+                try {
+                    const decoded = (0, jwt_decode_1.jwtDecode)(unwrappedData.access_token);
+                    if (decoded?.exp)
+                        accessTokenExpires = decoded.exp * 1000;
+                }
+                catch {
+                    console.warn('[VERIFY_BACKUP_CODE] Could not decode access token, using default expiration');
+                }
+                let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
+                try {
+                    const decoded = (0, jwt_decode_1.jwtDecode)(unwrappedData.refresh_token);
+                    if (decoded?.exp)
+                        refreshTokenExpires = decoded.exp * 1000;
+                }
+                catch {
+                    // Refresh token may carry no exp claim; default stands.
+                }
+                await (0, session_store_1.transitionTo2FASession)(sessionToken, {
+                    accessToken: unwrappedData.access_token,
+                    refreshToken: unwrappedData.refresh_token,
+                    accessTokenExpires,
+                    refreshTokenExpires,
+                }, 
+                // 'totp' is deliberate and load-bearing. See "THE STORED 2FA METHOD"
+                // in the file header before changing it.
+                'totp');
+                sessionTransitioned = true;
+                console.log('[VERIFY_BACKUP_CODE] Session transitioned to 2FA-verified');
+            }
+            else {
+                console.warn('[VERIFY_BACKUP_CODE] IDP accepted the code but no session token was resolvable — session NOT transitioned. THE CODE IS ALREADY SPENT.');
+            }
+        }
+        else {
+            console.warn('[VERIFY_BACKUP_CODE] IDP returned 2xx without tokens — session NOT transitioned. THE CODE IS ALREADY SPENT.');
+        }
+        // twoFactorSessionVerified reports WHAT ACTUALLY HAPPENED, never a copy of
+        // `success`. It matters more here than anywhere else: the code is consumed
+        // the moment the IDP accepts it, so a client that trusted a hardcoded true
+        // would show the user as verified, leave the session unverified, and have
+        // burned one of their ten recovery codes to do it.
+        return server_1.NextResponse.json({
+            success: true,
+            verificationSuccessful: true,
+            twoFactorSessionVerified: sessionTransitioned,
+            codeConsumed: true,
+            message: unwrappedData.message || 'Backup code verified successfully',
+        }, { status: 200 });
+    }
+    catch (error) {
+        console.error('[VERIFY_BACKUP_CODE] Error:', error);
+        return server_1.NextResponse.json({
+            success: false,
+            error: 'Failed to verify backup code',
+            code: 'INTERNAL_ERROR',
+        }, { status: 500 });
+    }
+}

package/dist/api-handlers/mfa/backup-codes.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Generate MFA backup codes (POST /api/Account/mfa/backup-codes, user JWT).
+ * Regeneration REPLACES the prior set — the response carries the new codes
+ * once; they are shown once and never retrievable again.
+ */
+export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/mfa/backup-codes.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Generate MFA backup codes (POST /api/Account/mfa/backup-codes, user JWT).
+ * Regeneration REPLACES the prior set — the response carries the new codes
+ * once; they are shown once and never retrievable again.
+ */
+async function POST(req) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/mfa/backup-codes`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/mfa/methods.d.ts

@@ -0,0 +1,3 @@
+import { NextRequest, NextResponse } from 'next/server';
+export declare function GET(req: NextRequest): Promise<NextResponse<any>>;
+export declare function DELETE(req: NextRequest, id: string): Promise<NextResponse<any>>;

package/dist/api-handlers/mfa/methods.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+exports.DELETE = DELETE;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * MFA methods (GET list / DELETE one, /api/Account/mfa/methods[/{id}],
+ * user JWT). Drives the method picker: an EMPTY list must route the user to
+ * ENROLMENT, never to a verify screen for a factor they do not hold.
+ */
+function upstreamError(result) {
+    return server_1.NextResponse.json({
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+    }, { status: result.status });
+}
+function passthrough(json) {
+    const bodyJson = json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data ?? { success: true }, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? { success: true }, { status: 200 });
+}
+async function GET(req) {
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/mfa/methods`, { method: 'GET' });
+    if (!result.ok)
+        return upstreamError(result);
+    return passthrough(result.json);
+}
+async function DELETE(req, id) {
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/mfa/methods/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    if (!result.ok)
+        return upstreamError(result);
+    return passthrough(result.json);
+}

package/dist/api-handlers/mfa/totp-confirm.d.ts

@@ -0,0 +1,8 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Confirm TOTP enrolment with the first authenticator code
+ * (POST /api/Account/mfa/totp/confirm, user JWT). Body forwarded verbatim —
+ * it carries the enrolment handle plus the code. Only after this succeeds is
+ * the method ACTIVE.
+ */
+export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/mfa/totp-confirm.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Confirm TOTP enrolment with the first authenticator code
+ * (POST /api/Account/mfa/totp/confirm, user JWT). Body forwarded verbatim —
+ * it carries the enrolment handle plus the code. Only after this succeeds is
+ * the method ACTIVE.
+ */
+async function POST(req) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/mfa/totp/confirm`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/mfa/totp-enroll.d.ts

@@ -0,0 +1,8 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Begin TOTP enrolment (POST /api/Account/mfa/totp/enroll, user JWT).
+ * Returns the shared secret / otpauth URI for the QR. An enrolment left
+ * UNCONFIRMED is pending — it can only be RESTARTED, and must never render
+ * as "Active" (MFA honesty fixes, 2026-08-01).
+ */
+export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/mfa/totp-enroll.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Begin TOTP enrolment (POST /api/Account/mfa/totp/enroll, user JWT).
+ * Returns the shared secret / otpauth URI for the QR. An enrolment left
+ * UNCONFIRMED is pending — it can only be RESTARTED, and must never render
+ * as "Active" (MFA honesty fixes, 2026-08-01).
+ */
+async function POST(req) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/mfa/totp/enroll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/mfa/totp-verify.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Verify TOTP 2FA Challenge Handler
+ *
+ * Verifies an authenticator-app code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped TOTP ENROLMENT (totp-enroll, totp-confirm, against
+ * /api/Account/mfa/totp/*) but no TOTP CHALLENGE. SMS and email both had one
+ * (verify-sms, verify-email, against /api/ExternalAuth/twofa/*), so TOTP could
+ * be enrolled and then never used to satisfy a login challenge — mfaVerified
+ * stayed false forever for authenticator-app users, even though the IDP
+ * advertises totp in allowed2FAMethods and exposes the endpoint.
+ *
+ * DO NOT "FIX" THIS BY MAKING totp-confirm TRANSITION THE SESSION. Three people
+ * proposed exactly that on the grounds that its SMS/email "siblings" do it. They
+ * are not siblings: totp-confirm is ENROLMENT. Flipping mfaVerified there would
+ * mean enrolling a factor counts as passing a challenge, letting a
+ * password-only session self-promote to MFA-verified by adding an
+ * authenticator. Enrolment must never set mfaVerified.
+ *
+ * FIELD NAME: the IDP expects { "code": ... } here
+ * (MfaTotpVerifyRequest, [JsonPropertyName("code")]), NOT the
+ * { "verification_code": ... } that the SMS endpoint takes. Copying verify-sms
+ * and changing only the URL produces a handler that reaches the IDP and is
+ * rejected, which reads as "wrong code" rather than "wrong shape".
+ *
+ * @package @payez/next-mvp
+ */
+import { NextRequest, NextResponse } from 'next/server';
+export declare function POST(req: NextRequest): Promise<NextResponse<{
+    success: boolean;
+    error: string;
+    code: string;
+}> | NextResponse<{
+    success: boolean;
+    error: any;
+    code: any;
+    meta: {
+        attemptedRefresh: boolean;
+    };
+}> | NextResponse<{
+    success: boolean;
+    verificationSuccessful: boolean;
+    twoFactorSessionVerified: boolean;
+    message: any;
+}>>;