@payez/next-mvp 4.13.0 → 4.14.0

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
@@ -525,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/first-enrol-confirm.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+export { POST_CONFIRM as POST } from '../../api-handlers/mfa/first-enrol';

package/src/routes/mfa/first-enrol-enroll.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+export { POST_ENROLL as POST } from '../../api-handlers/mfa/first-enrol';

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 } : {})
         };
     }