@payez/next-mvp 4.8.0 → 4.8.2

package/src/api-handlers/mfa/totp-enroll.ts

@@ -1,43 +1,43 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-import { projectIdpError } from '../../lib/safe-error-response';
-
-/**
- * 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 async function POST(req: NextRequest) {
-  let body = '{}';
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) body = raw;
-  } catch {}
-
-  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/mfa/totp/enroll`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body,
-  });
-
-  if (!result.ok) {
-    return NextResponse.json(
-      {
-        success: false,
-        message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
-        meta: { attemptedRefresh: result.attemptedRefresh },
-      },
-      { status: result.status },
-    );
-  }
-
-  const bodyJson: any = result.json;
-  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
-    return NextResponse.json(bodyJson, { status: 200 });
-  }
-  return NextResponse.json(bodyJson ?? {}, { status: 200 });
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
+
+/**
+ * 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 async function POST(req: NextRequest) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/mfa/totp/enroll`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status },
+    );
+  }
+
+  const bodyJson: any = result.json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/src/api-handlers/mfa/totp-verify.ts

@@ -1,172 +1,172 @@
-/**
- * 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';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-import { getTokenTestAware } from '../../lib/test-aware-get-token';
-import { transitionTo2FASession } from '../../lib/session-store';
-import { jwtDecode } from '../../lib/jwt-decode';
-import { twoFactorVerifyFailure } from '../../lib/two-factor-verify-failure';
-
-export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    // Accept the same aliases the client might send; the IDP field is `code`.
-    const code = body.code || body.totpCode || body.verificationCode || body.verification_code;
-
-    if (!code) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: 'Authenticator code is required',
-          code: 'INVALID_REQUEST',
-        },
-        { status: 400 }
-      );
-    }
-
-    // idpFetchJSON injects the caller's Bearer from the session store.
-    const result = await idpFetchJSON(
-      req,
-      `${ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/totp/verify`,
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ code }),
-      }
-    );
-
-    if (!result.ok) {
-      // PAY-1443: never relay the IDP's error text - it arrives as a C# anonymous-object
-      // ToString ("{ message = ... }") on the deployed IDP. Classify it, answer a fixed sentence.
-      return twoFactorVerifyFailure(result, 'totp');
-    }
-
-    // Unwrap IDP envelope { success, data }
-    const unwrappedData = result.json?.data || result.json;
-
-    // Only a successful challenge that returns fresh tokens may transition the
-    // session. No tokens => no transition: we must not mark 2FA complete on the
-    // strength of a 200 alone.
-    let sessionTransitioned = false;
-    // R908(e): "we could not establish MFA" is a THIRD outcome, distinct from
-    // both success and failure. It must reach the client as a challenge, not as
-    // a silent success (fail-open) and not as a rejection (fail-closed).
-    let requiresChallenge = false;
-
-    if (unwrappedData.access_token && unwrappedData.refresh_token) {
-      const token = await getTokenTestAware(req);
-      const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
-
-      if (sessionToken) {
-        let accessTokenExpires = Date.now() + 15 * 60 * 1000;
-        try {
-          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.access_token);
-          if (decoded?.exp) accessTokenExpires = decoded.exp * 1000;
-        } catch {
-          console.warn('[VERIFY_TOTP] Could not decode access token, using default expiration');
-        }
-
-        let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
-        try {
-          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.refresh_token);
-          if (decoded?.exp) refreshTokenExpires = decoded.exp * 1000;
-        } catch {
-          // Refresh token may carry no exp claim; default stands.
-        }
-
-        // R908(e): the transition can now decline to grant. Read what was
-        // actually written instead of assuming the call granted - the store
-        // withholds mfaVerified when the stepped-up token carries no
-        // mfa_expires, and reports the re-challenge via nextStep.
-        const transitioned = await transitionTo2FASession(
-          sessionToken,
-          {
-            accessToken: unwrappedData.access_token,
-            refreshToken: unwrappedData.refresh_token,
-            accessTokenExpires,
-            refreshTokenExpires,
-          },
-          'totp' // 2FA method, used by the refresh-token flow
-        );
-
-        sessionTransitioned = transitioned?.mfaVerified === true;
-        requiresChallenge = transitioned?.nextStep === 'mfa_verify';
-
-        if (sessionTransitioned) {
-          console.log('[VERIFY_TOTP] Session transitioned to 2FA-verified');
-        } else {
-          console.warn(
-            '[VERIFY_TOTP] R908(e): IDP verified the code but the session was NOT ' +
-              'marked MFA-verified (no mfa_expires on the returned token). Reporting ' +
-              'requiresChallenge so the client re-challenges rather than proceeding.'
-          );
-        }
-      } else {
-        console.warn('[VERIFY_TOTP] IDP verified the code but no session token was resolvable — session NOT transitioned');
-      }
-    } else {
-      console.warn('[VERIFY_TOTP] IDP returned 2xx without tokens — session NOT transitioned');
-    }
-
-    // Do not expose tokens to the client.
-    //
-    // twoFactorSessionVerified REPORTS WHAT ACTUALLY HAPPENED. It is NOT a copy
-    // of `success`. The code can verify at the IDP while the session is not
-    // transitioned — no tokens returned, or no resolvable session token — and a
-    // client that trusted a hardcoded `true` would show the user as MFA-verified
-    // while the session still says otherwise. That divergence between the guard
-    // and the report is the defect this field exists to avoid.
-    // (verify-sms.ts hardcodes it true and has the same flaw — reported upstream.)
-    return NextResponse.json(
-      {
-        success: true,
-        verificationSuccessful: true,
-        twoFactorSessionVerified: sessionTransitioned,
-        // R908(e): tells the client to re-challenge. Present only when the code
-        // verified at the IDP but produced no evidence we could record.
-        ...(requiresChallenge ? { requiresChallenge: true, nextStep: 'mfa_verify' as const } : {}),
-        message: unwrappedData.message || 'Authenticator code verified successfully',
-      },
-      { status: 200 }
-    );
-  } catch (error) {
-    console.error('[VERIFY_TOTP] Error:', error);
-    return NextResponse.json(
-      {
-        success: false,
-        error: 'Failed to verify code',
-        code: 'INTERNAL_ERROR',
-      },
-      { status: 500 }
-    );
-  }
-}
+/**
+ * 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';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+import { getTokenTestAware } from '../../lib/test-aware-get-token';
+import { transitionTo2FASession } from '../../lib/session-store';
+import { jwtDecode } from '../../lib/jwt-decode';
+import { twoFactorVerifyFailure } from '../../lib/two-factor-verify-failure';
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    // Accept the same aliases the client might send; the IDP field is `code`.
+    const code = body.code || body.totpCode || body.verificationCode || body.verification_code;
+
+    if (!code) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: 'Authenticator code is required',
+          code: 'INVALID_REQUEST',
+        },
+        { status: 400 }
+      );
+    }
+
+    // idpFetchJSON injects the caller's Bearer from the session store.
+    const result = await idpFetchJSON(
+      req,
+      `${ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/totp/verify`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+      }
+    );
+
+    if (!result.ok) {
+      // PAY-1443: never relay the IDP's error text - it arrives as a C# anonymous-object
+      // ToString ("{ message = ... }") on the deployed IDP. Classify it, answer a fixed sentence.
+      return twoFactorVerifyFailure(result, 'totp');
+    }
+
+    // Unwrap IDP envelope { success, data }
+    const unwrappedData = result.json?.data || result.json;
+
+    // Only a successful challenge that returns fresh tokens may transition the
+    // session. No tokens => no transition: we must not mark 2FA complete on the
+    // strength of a 200 alone.
+    let sessionTransitioned = false;
+    // R908(e): "we could not establish MFA" is a THIRD outcome, distinct from
+    // both success and failure. It must reach the client as a challenge, not as
+    // a silent success (fail-open) and not as a rejection (fail-closed).
+    let requiresChallenge = false;
+
+    if (unwrappedData.access_token && unwrappedData.refresh_token) {
+      const token = await getTokenTestAware(req);
+      const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
+
+      if (sessionToken) {
+        let accessTokenExpires = Date.now() + 15 * 60 * 1000;
+        try {
+          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.access_token);
+          if (decoded?.exp) accessTokenExpires = decoded.exp * 1000;
+        } catch {
+          console.warn('[VERIFY_TOTP] Could not decode access token, using default expiration');
+        }
+
+        let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
+        try {
+          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.refresh_token);
+          if (decoded?.exp) refreshTokenExpires = decoded.exp * 1000;
+        } catch {
+          // Refresh token may carry no exp claim; default stands.
+        }
+
+        // R908(e): the transition can now decline to grant. Read what was
+        // actually written instead of assuming the call granted - the store
+        // withholds mfaVerified when the stepped-up token carries no
+        // mfa_expires, and reports the re-challenge via nextStep.
+        const transitioned = await transitionTo2FASession(
+          sessionToken,
+          {
+            accessToken: unwrappedData.access_token,
+            refreshToken: unwrappedData.refresh_token,
+            accessTokenExpires,
+            refreshTokenExpires,
+          },
+          'totp' // 2FA method, used by the refresh-token flow
+        );
+
+        sessionTransitioned = transitioned?.mfaVerified === true;
+        requiresChallenge = transitioned?.nextStep === 'mfa_verify';
+
+        if (sessionTransitioned) {
+          console.log('[VERIFY_TOTP] Session transitioned to 2FA-verified');
+        } else {
+          console.warn(
+            '[VERIFY_TOTP] R908(e): IDP verified the code but the session was NOT ' +
+              'marked MFA-verified (no mfa_expires on the returned token). Reporting ' +
+              'requiresChallenge so the client re-challenges rather than proceeding.'
+          );
+        }
+      } else {
+        console.warn('[VERIFY_TOTP] IDP verified the code but no session token was resolvable — session NOT transitioned');
+      }
+    } else {
+      console.warn('[VERIFY_TOTP] IDP returned 2xx without tokens — session NOT transitioned');
+    }
+
+    // Do not expose tokens to the client.
+    //
+    // twoFactorSessionVerified REPORTS WHAT ACTUALLY HAPPENED. It is NOT a copy
+    // of `success`. The code can verify at the IDP while the session is not
+    // transitioned — no tokens returned, or no resolvable session token — and a
+    // client that trusted a hardcoded `true` would show the user as MFA-verified
+    // while the session still says otherwise. That divergence between the guard
+    // and the report is the defect this field exists to avoid.
+    // (verify-sms.ts hardcodes it true and has the same flaw — reported upstream.)
+    return NextResponse.json(
+      {
+        success: true,
+        verificationSuccessful: true,
+        twoFactorSessionVerified: sessionTransitioned,
+        // R908(e): tells the client to re-challenge. Present only when the code
+        // verified at the IDP but produced no evidence we could record.
+        ...(requiresChallenge ? { requiresChallenge: true, nextStep: 'mfa_verify' as const } : {}),
+        message: unwrappedData.message || 'Authenticator code verified successfully',
+      },
+      { status: 200 }
+    );
+  } catch (error) {
+    console.error('[VERIFY_TOTP] Error:', error);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Failed to verify code',
+        code: 'INTERNAL_ERROR',
+      },
+      { status: 500 }
+    );
+  }
+}