@payez/next-mvp 4.12.1 → 4.13.1

package/src/pages/enroll/page.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import React from 'react';
+import { TotpEnrollPanel } from '../../components/mfa/TotpEnrollPanel';
+
+/**
+ * PAY-2631: /account-auth/enroll in a generated app. The page SHELL is public (every /account-auth/* path is public by default);
+ * what needs a session is each action: enrol and confirm answer 401 without one and the panel then says to sign in (measured on a
+ * scaffolded app: POST enrol with no cookie -> 401, no secret in the body). The scaffold lists the path on the 2FA bypass list
+ * because public routes still redirect a 2FA-incomplete session to verify-code, which sends enroll_mfa users back here: a loop.
+ */
+export default function EnrollPage() {
+  return (
+    <main style={{ maxWidth: 480, margin: '48px auto', padding: '0 16px' }}>
+      <h1>Set up an authenticator app</h1>
+      <TotpEnrollPanel />
+      <p style={{ marginTop: 24 }}>
+        <a href="/">Continue to the app</a>
+      </p>
+    </main>
+  );
+}

package/src/pages/login/page.tsx

@@ -29,7 +29,7 @@ import { Suspense } from 'react';
 import ReservedStatusBox from '../../components/reserved/ReservedStatusBox';
 import ReservedRecoveryWarning from '../../components/reserved/ReservedRecoveryWarning';
 import { useBranding, useColors, useLayout } from '../../theme/useTheme';
-import { friendlyLoginError, oauthFailureMessage } from '../../lib/login-error-message';
+import { friendlyLoginError, loginErrorCode, oauthFailureMessage } from '../../lib/login-error-message';
 
 function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
   const searchParams = useSearchParams();
@@ -226,6 +226,7 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
             <div
               role="alert"
               data-testid="login-error"
+              data-error-code={loginError === undefined ? (loginErrorCode(urlError) ?? undefined) : undefined}
               className="mb-6 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700"
             >
               {shownError}

package/src/routes/auth/session-reset.ts

@@ -20,18 +20,53 @@ import { NextRequest, NextResponse } from 'next/server';
 import { isPrefetchRequest } from '../../middleware/create-middleware';
 import { expireSessionCookies } from '../../auth/session-cookie-clear';
 import { getSessionCookieName, getSecureSessionCookieName } from '../../lib/app-slug';
-import { boundSessionCookie, loginLocation, readResetRequest, resetSecret } from '../../auth/session-reset-link';
+import { boundSessionCookie, loginLocation, readResetRequest, readResetRequestAnyKey, resetSecret } from '../../auth/session-reset-link';
 
 export const dynamic = 'force-dynamic';
 
-export async function GET(request: NextRequest): Promise<NextResponse> {
-  if (isPrefetchRequest(request)) {
-    return new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
-  }
-  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
-  const { params, signed } = await readResetRequest(request.nextUrl.searchParams, resetSecret(), bound);
-  const response = NextResponse.redirect(new URL(loginLocation(params), request.url), 307);
-  response.headers.set('cache-control', 'no-store');
-  if (signed) expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
-  return response;
+export interface SessionResetOptions {
+  /**
+   * PAY-2218 opt-in, OFF by default (BAPert 83102). OFF: only a link signed with the env secret (BETTER_AUTH_SECRET / NEXTAUTH_SECRET) clears, so every app that can
+   * see the secret stays strict. ON: a link signed with the key derived from this request's own session cookie also clears. Turn it on only where the EDGE middleware
+   * cannot see the env secret, and set `sessionResetCookieKey: true` on createMvpMiddleware too, or the route refuses the link the middleware signed.
+   */
+  cookieKey?: boolean;
 }
+
+export function createSessionResetHandler(options: SessionResetOptions = {}) {
+  const cookieKey = options.cookieKey === true;
+  let splitLogged = false;
+  let halfSetLogged = false;
+  return async function GET(request: NextRequest): Promise<NextResponse> {
+    if (isPrefetchRequest(request)) {
+      return new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+    }
+    const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
+    const env = resetSecret();
+    const { params, signed, via } = cookieKey
+      ? await readResetRequestAnyKey(request.nextUrl.searchParams, env, bound)
+      : { ...(await readResetRequest(request.nextUrl.searchParams, env, bound)), via: null as 'env' | 'cookie' | null };
+    // The dev-93 prefetch walk reads this line: a link that verified ONLY with the cookie-derived key while this route sees the env secret is the
+    // edge-blind / route-sighted split deployment. Once per process, no values.
+    if (cookieKey && signed && via === 'cookie' && env && !splitLogged) {
+      splitLogged = true;
+      console.info('[next-mvp] session-reset: a link verified with the cookie-derived key while the env secret is visible to this route (the edge middleware signed without it: split deployment)');
+    }
+    // HALF-SET (NightHawk 83161): this route is strict (cookieKey OFF) but the middleware signed with the cookie-derived key (sessionResetCookieKey ON). The link is refused
+    // and the stale cookie survives. Probe ONLY refused links, for the cookie-derived key alone, and say so once per process. No values.
+    if (!cookieKey && !signed && !halfSetLogged) {
+      const probe = await readResetRequestAnyKey(request.nextUrl.searchParams, undefined, bound);
+      if (probe.signed) {
+        halfSetLogged = true;
+        console.warn('[next-mvp] session-reset: refused a link signed with the cookie-derived key because this route has cookieKey OFF; the middleware has sessionResetCookieKey ON. Set createSessionResetHandler({ cookieKey: true }) or turn the middleware option off');
+      }
+    }
+    const response = NextResponse.redirect(new URL(loginLocation(params), request.url), 307);
+    response.headers.set('cache-control', 'no-store');
+    if (signed) expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
+    return response;
+  };
+}
+
+/** The strict default: env-signed links only. An app that opted in uses createSessionResetHandler({ cookieKey: true }). */
+export const GET = createSessionResetHandler();

package/src/routes/auth/session.ts

@@ -13,6 +13,7 @@
  * @since auth-ready-v2
  */
 
+import { noStore } from '../../lib/no-store';
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
@@ -27,7 +28,7 @@ import { tokenLogId } from '../../lib/token-log-id';
  * - Token expiry status
  * - Session validity
  */
-export async function GET(req: NextRequest) {
+async function getHandler(req: NextRequest) {
   try {
     const authSession = await getBetterAuthSession(req);
 
@@ -121,6 +122,9 @@ export async function GET(req: NextRequest) {
   }
 }
 
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export const GET = noStore(getHandler);
+
 /**
  * The fields this route USED to accept from the request body and must never accept
  * again. Cards 308833 (critical) / 312092 (remediation spec) / 318272 / 311425.

package/src/routes/auth/viability.ts

@@ -24,6 +24,7 @@ import {
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 import { tokenLogId } from '../../lib/token-log-id';
+import { noStore } from '../../lib/no-store';
 import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
 
 /**
@@ -141,7 +142,7 @@ function resolveClientId(sessionClientId: string | undefined): string | null {
  * - needsRefresh: boolean - Whether a refresh is recommended
  * - expiresIn: number - Seconds until token expires
  */
-export async function GET(req: NextRequest) {
+async function getHandler(req: NextRequest) {
   try {
     // PAY-2216: ask for the session's STATE, not a session-or-null. A null used to cover a store outage, a deleted
     // session and no cookie alike, so this route answered 'No session found' to all three and the middleware could
@@ -199,6 +200,9 @@ export async function GET(req: NextRequest) {
     // stack just resolved the cookie cleanly. Keeps the two viability impls
     // (this route + `api-handlers/session/viability.ts`) in lockstep.
     let session = sessionToken ? await getRedisSession(sessionToken) : null;
+    // PAY-2467: a row read from the CANONICAL store is the raw JSON the callback wrote, so an `mfaVerified` boolean on it is a
+    // MEASUREMENT (an absent key is a legacy row). Only the BA-record fallback collapses absent to false and needs mfaSignalPresent.
+    const fromCanonicalStore = !!session;
     if (sessionToken && !session) {
       session = await getBetterAuthRedisSession(sessionToken);
       if (session) {
@@ -294,9 +298,14 @@ export async function GET(req: NextRequest) {
      * it names TENANT policy, and this override is not tenant state.
      */
     const oauthSessionNeedsTwoFactor =
-      session?.mfaSignalPresent === true &&
+      // PAY-2467: the signal is present on the BA-fallback path (mfaSignalPresent) OR when the canonical row itself carries a boolean.
+      // Before this, the override was dead on the canonical path every consumer mounts, so gating rested on tenant config alone.
+      (session?.mfaSignalPresent === true || (fromCanonicalStore && typeof session?.mfaVerified === 'boolean')) &&
       session?.mfaVerified === false &&
-      !(session.idpRefreshToken || (session as any)?.refreshToken);
+      !(session.idpRefreshToken || (session as any)?.refreshToken) &&
+      // An IdP DISCARD (refresh.ts / ensure-fresh-access-token.ts write idpRefreshToken '' with refreshTokenClearedReason 'IDP_DISCARD_TOKEN:<code>') leaves
+      // mfaVerified false and no refresh token too, but that is a DEAD session, not a pending second factor: it must not be sent to verify-code (QAPert 84816).
+      !String((session as any)?.refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN');
 
     // --- Session revocation status (PAY-1882 step 4 producer half) ---
     /*
@@ -517,4 +526,7 @@ export async function GET(req: NextRequest) {
       correlationId
     }, { status: 500 });
   }
-}
+}
+
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export const GET = noStore(getHandler);

package/src/routes/health.ts

@@ -0,0 +1,14 @@
+/**
+ * Ready-to-use /api/health route: reports Redis reachability (PAY-2804).
+ *
+ * @example
+ * ```typescript
+ * // app/api/health/route.ts
+ * export const runtime = 'nodejs';
+ * export { GET } from '@payez/next-mvp/routes/health';
+ * ```
+ */
+import { createHealthHandler } from '../api-handlers/health';
+import { getRedis } from '../lib/redis';
+
+export const GET = createHealthHandler(() => getRedis());

package/src/routes/mfa/methods.ts

@@ -11,8 +11,10 @@
  */
 import { NextRequest } from 'next/server';
 import { GET as listMethods, DELETE as deleteMethod } from '../../api-handlers/mfa/methods';
+import { noStore } from '../../lib/no-store';
 
-export const GET = listMethods;
+/** PAY-2994: the user's MFA methods; never cached (noStore). */
+export const GET = noStore(listMethods);
 
 type Ctx = { params: Promise<{ id: string }> };
 

package/src/routes/passkeys/list.ts

@@ -7,4 +7,8 @@
  * export { GET } from '@payez/next-mvp/routes/passkeys/list';
  * ```
  */
-export { GET } from '../../api-handlers/passkeys/list';
+import { GET as listPasskeys } from '../../api-handlers/passkeys/list';
+import { noStore } from '../../lib/no-store';
+
+/** PAY-2994: the signed-in user's passkeys; never cached (noStore). */
+export const GET = noStore(listPasskeys);

package/src/routes/session/refresh-viability.ts

@@ -14,4 +14,8 @@
  * @since auth-ready-v2
  */
 
-export { GET } from '../../api-handlers/session/refresh-viability';
+import { GET as refreshViability } from '../../api-handlers/session/refresh-viability';
+import { noStore } from '../../lib/no-store';
+
+/** PAY-2994: refresh-token viability of this session; never cached (noStore). */
+export const GET = noStore(refreshViability);

package/src/utils/api.ts

@@ -133,6 +133,45 @@ export function resetFailureText(status: number, rules: string[] = [], policy =
     return "We couldn't reset your password just now. Please try again.";
 }
 
+/**
+ * SMS-first sign-up (door 3b): when the phone code is right but the email is still unconfirmed, the server answers 200 success with
+ * `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token. `verifyOnboardingSmsCode` surfaces that as `nextStep`;
+ * `interpretSmsVerification` turns a result into ONE outcome, testing `nextStep` BEFORE `success`, so a consumer that uses it can
+ * never reach "verified" without a reset token or with an unfinished step. The sentences are the package's own, never the server's text.
+ */
+export const SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED = 'EMAIL_CONFIRMATION_REQUIRED';
+export const SMS_EMAIL_CONFIRMATION_TEXT = 'Your phone is verified. Confirm your email to finish signing up.';
+export const SMS_MORE_STEPS_TEXT = 'One more step is needed to finish signing up.';
+
+export interface SmsCodeVerification {
+    success: boolean;
+    resetToken: string;
+    email: string;
+    clientKey: string;
+    /** Present when the server says more steps remain (an UNRECOGNISED value is kept as a non-empty string, never dropped). */
+    nextStep?: string;
+}
+
+export type SmsVerificationOutcome =
+    | { kind: 'verified'; resetToken: string; email: string; clientKey: string }
+    | { kind: 'email_confirmation_required'; message: string }
+    | { kind: 'more_steps'; message: string }
+    | { kind: 'not_verified' };
+
+export function interpretSmsVerification(result: SmsCodeVerification): SmsVerificationOutcome {
+    // success:false WINS over any step (BAPert 88508): a failed answer must never say "Your phone is verified".
+    if (!result.success) return { kind: 'not_verified' };
+    // For every answer that is not a failure, nextStep comes BEFORE the token test: a step that is not finished is never "verified".
+    if (result.nextStep) {
+        return result.nextStep === SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED
+            ? { kind: 'email_confirmation_required', message: SMS_EMAIL_CONFIRMATION_TEXT }
+            : { kind: 'more_steps', message: SMS_MORE_STEPS_TEXT };
+    }
+    // success with an EMPTY reset token is the shape that is dangerous (set-password would be called with ''): not verified.
+    if (!result.resetToken) return { kind: 'more_steps', message: SMS_MORE_STEPS_TEXT };
+    return { kind: 'verified', resetToken: result.resetToken, email: result.email, clientKey: result.clientKey };
+}
+
 export class AccountApi {
     /**
      * Get masked user info (email, phone, authenticator status)
@@ -338,17 +377,12 @@ export class AccountApi {
         };
     }
 
-    async verifyOnboardingSmsCode(onboardToken: string, code: string, clientKey?: string): Promise<{
-        success: boolean;
-        resetToken: string;
-        email: string;
-        clientKey: string;
-    }> {
+    async verifyOnboardingSmsCode(onboardToken: string, code: string, clientKey?: string): Promise<SmsCodeVerification> {
         const qs = clientKey ? `?clientId=${encodeURIComponent(clientKey)}` : '';
         const res = await fetch(`/api/onboarding/verify-sms-code${qs}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ 
+            body: JSON.stringify({
                 onboard_token: onboardToken,
                 code: code
             })
@@ -360,11 +394,19 @@ export class AccountApi {
         }
         // Extract from nested data structure
         const data = result.data?.data || result.data || {};
+        // next_step (door 3b): read from the nested shapes AND a flat body. Absent / null / '' = no step; a non-string value is an
+        // UNRECOGNISED step and is kept as a non-empty string (never dropped, never mistaken for the known one). That includes false and 0:
+        // a server that means "no step" must send nothing or null (or '').
+        const rawStep = data.next_step ?? result.next_step;
+        const nextStep = rawStep === undefined || rawStep === null || rawStep === ''
+            ? undefined
+            : typeof rawStep === 'string' ? rawStep : 'UNRECOGNISED_NEXT_STEP';
         return {
             success: data.success !== false,
             resetToken: data.reset_token || '',
             email: data.email || '',
-            clientKey: data.client_key || ''
+            clientKey: data.client_key || '',
+            ...(nextStep !== undefined ? { nextStep } : {})
         };
     }