@payez/next-mvp 4.1.11 → 4.1.20

package/src/routes/auth/session.ts

@@ -1,167 +1,167 @@
-/**
- * Ready-to-Use Session Management Route
- *
- * Provides pre-configured session handlers for checking and updating session state.
- *
- * @example
- * ```typescript
- * // app/api/auth/session/route.ts
- * export { GET, POST } from '@payez/next-mvp/routes/auth/session';
- * ```
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getBetterAuthSession } from '../../server/auth';
-import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
-
-/**
- * GET /api/auth/session - Check current session status
- *
- * Returns the current session information including:
- * - User details
- * - Token expiry status
- * - Session validity
- */
-export async function GET(req: NextRequest) {
-  try {
-    const authSession = await getBetterAuthSession(req);
-
-    if (!authSession) {
-      console.warn('[SESSION_ROUTE] Better Auth session not found');
-      // MUST return empty {} — useSession() treats any non-empty
-      // response object as "authenticated", causing redirect loops on login page.
-      return NextResponse.json({});
-    }
-
-    const redisSessionId = authSession.session?.token;
-
-    console.log('[SESSION_ROUTE] Session found:', {
-      userId: authSession.user?.id,
-      email: authSession.user?.email,
-      name: authSession.user?.name,
-      redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'MISSING',
-    });
-
-    // Fetch full session data from Redis
-    const session = redisSessionId ? await getRedisSession(redisSessionId) : null;
-
-    console.log('[SESSION_ROUTE] Redis session:', {
-      found: !!session,
-      userId: session?.userId,
-      roles: session?.roles,
-      hasAccessToken: !!session?.idpAccessToken,
-    });
-
-    // Return session format with Redis data
-    // useSession() expects: { user: {...}, expires: "..." }
-    // We enrich with all session data from Redis
-    return NextResponse.json({
-      user: {
-        id: session?.userId || authSession.user?.id,
-        email: session?.email || authSession.user?.email,
-        name: session?.name || authSession.user?.name,
-        image: authSession.user?.image || session?.image || null,
-        // Redis session data
-        roles: session?.roles || [],
-        twoFactorSessionVerified: session?.mfaVerified || false,
-        requiresTwoFactor: !session?.mfaVerified,
-        authenticationMethods: session?.authenticationMethods,
-        authenticationLevel: session?.authenticationLevel,
-        mfaCompletedAt: session?.mfaCompletedAt,
-        mfaExpiresAt: session?.mfaExpiresAt,
-        mfaValidityHours: session?.mfaValidityHours,
-        oauthProvider: session?.oauthProvider,
-        idpClientId: session?.idpClientId,
-        merchantId: session?.merchantId,
-      },
-      // Session tokens
-      sessionToken: redisSessionId,
-      accessToken: session?.idpAccessToken,
-      refreshToken: session?.idpRefreshToken,
-      accessTokenExpires: session?.idpAccessTokenExpires,
-      expires: authSession.session?.expiresAt
-        ? new Date(authSession.session.expiresAt).toISOString()
-        : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
-    });
-  } catch (error) {
-    console.error('[SESSION_ROUTE] Error checking session:', error);
-    return NextResponse.json({
-      error: 'Failed to check session',
-      details: error instanceof Error ? error.message : 'Unknown error'
-    }, { status: 500 });
-  }
-}
-
-/**
- * POST /api/auth/session - Update session data
- *
- * Allows updating session metadata (not tokens).
- * Token refresh should use the /api/auth/refresh endpoint.
- *
- * Body:
- * - metadata: object - Custom metadata to store in session
- */
-export async function POST(req: NextRequest) {
-  try {
-    const authSession = await getBetterAuthSession(req);
-
-    if (!authSession) {
-      return NextResponse.json({
-        error: 'No session found',
-        code: 'UNAUTHORIZED'
-      }, { status: 401 });
-    }
-
-    const sessionToken = authSession.session?.token;
-    if (!sessionToken) {
-      return NextResponse.json({
-        error: 'Invalid session',
-        code: 'INVALID_SESSION'
-      }, { status: 400 });
-    }
-
-    const body = await req.json();
-    const { metadata, access_token, refresh_token, twoFactorComplete, twoFactorMethod } = body;
-
-    // Get current session from Redis
-    const session = await getRedisSession(sessionToken);
-    if (!session) {
-      return NextResponse.json({
-        error: 'Session not found',
-        code: 'SESSION_NOT_FOUND'
-      }, { status: 404 });
-    }
-
-    // Update session with new data
-    const updatedSession = {
-      ...session,
-      ...(access_token ? { accessToken: access_token } : {}),
-      ...(refresh_token ? { refreshToken: refresh_token } : {}),
-      ...(typeof twoFactorComplete === 'boolean' ? { twoFactorComplete } : {}),
-      ...(twoFactorMethod ? { twoFactorMethod } : {}),
-      ...(metadata ? {
-        metadata: {
-          ...(session.metadata || {}),
-          ...metadata,
-          updatedAt: new Date().toISOString()
-        }
-      } : {})
-    };
-
-    await updateSession(sessionToken, updatedSession);
-
-    return NextResponse.json({
-      success: true,
-      message: 'Session updated successfully'
-    });
-  } catch (error) {
-    console.error('[SESSION_ROUTE] Error updating session:', error);
-    return NextResponse.json({
-      error: 'Failed to update session',
-      details: error instanceof Error ? error.message : 'Unknown error'
-    }, { status: 500 });
-  }
+/**
+ * Ready-to-Use Session Management Route
+ *
+ * Provides pre-configured session handlers for checking and updating session state.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/session/route.ts
+ * export { GET, POST } from '@payez/next-mvp/routes/auth/session';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession as getBetterAuthSession } from '../../server/auth';
+import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
+
+/**
+ * GET /api/auth/session - Check current session status
+ *
+ * Returns the current session information including:
+ * - User details
+ * - Token expiry status
+ * - Session validity
+ */
+export async function GET(req: NextRequest) {
+  try {
+    const authSession = await getBetterAuthSession(req);
+
+    if (!authSession) {
+      console.warn('[SESSION_ROUTE] Better Auth session not found');
+      // MUST return empty {} — useSession() treats any non-empty
+      // response object as "authenticated", causing redirect loops on login page.
+      return NextResponse.json({});
+    }
+
+    const redisSessionId = authSession.session?.token;
+
+    console.log('[SESSION_ROUTE] Session found:', {
+      userId: authSession.user?.id,
+      email: authSession.user?.email,
+      name: authSession.user?.name,
+      redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'MISSING',
+    });
+
+    // Fetch full session data from Redis
+    const session = redisSessionId ? await getRedisSession(redisSessionId) : null;
+
+    console.log('[SESSION_ROUTE] Redis session:', {
+      found: !!session,
+      userId: session?.userId,
+      roles: session?.roles,
+      hasAccessToken: !!session?.idpAccessToken,
+    });
+
+    // Return session format with Redis data
+    // useSession() expects: { user: {...}, expires: "..." }
+    // We enrich with all session data from Redis
+    return NextResponse.json({
+      user: {
+        id: session?.userId || authSession.user?.id,
+        email: session?.email || authSession.user?.email,
+        name: session?.name || authSession.user?.name,
+        image: authSession.user?.image || session?.image || null,
+        // Redis session data
+        roles: session?.roles || [],
+        twoFactorSessionVerified: session?.mfaVerified || false,
+        requiresTwoFactor: !session?.mfaVerified,
+        authenticationMethods: session?.authenticationMethods,
+        authenticationLevel: session?.authenticationLevel,
+        mfaCompletedAt: session?.mfaCompletedAt,
+        mfaExpiresAt: session?.mfaExpiresAt,
+        mfaValidityHours: session?.mfaValidityHours,
+        oauthProvider: session?.oauthProvider,
+        idpClientId: session?.idpClientId,
+        merchantId: session?.merchantId,
+      },
+      // Session tokens
+      sessionToken: redisSessionId,
+      accessToken: session?.idpAccessToken,
+      refreshToken: session?.idpRefreshToken,
+      accessTokenExpires: session?.idpAccessTokenExpires,
+      expires: authSession.session?.expiresAt
+        ? new Date(authSession.session.expiresAt).toISOString()
+        : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+    });
+  } catch (error) {
+    console.error('[SESSION_ROUTE] Error checking session:', error);
+    return NextResponse.json({
+      error: 'Failed to check session',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/auth/session - Update session data
+ *
+ * Allows updating session metadata (not tokens).
+ * Token refresh should use the /api/auth/refresh endpoint.
+ *
+ * Body:
+ * - metadata: object - Custom metadata to store in session
+ */
+export async function POST(req: NextRequest) {
+  try {
+    const authSession = await getBetterAuthSession(req);
+
+    if (!authSession) {
+      return NextResponse.json({
+        error: 'No session found',
+        code: 'UNAUTHORIZED'
+      }, { status: 401 });
+    }
+
+    const sessionToken = authSession.session?.token;
+    if (!sessionToken) {
+      return NextResponse.json({
+        error: 'Invalid session',
+        code: 'INVALID_SESSION'
+      }, { status: 400 });
+    }
+
+    const body = await req.json();
+    const { metadata, access_token, refresh_token, twoFactorComplete, twoFactorMethod } = body;
+
+    // Get current session from Redis
+    const session = await getRedisSession(sessionToken);
+    if (!session) {
+      return NextResponse.json({
+        error: 'Session not found',
+        code: 'SESSION_NOT_FOUND'
+      }, { status: 404 });
+    }
+
+    // Update session with new data
+    const updatedSession = {
+      ...session,
+      ...(access_token ? { accessToken: access_token } : {}),
+      ...(refresh_token ? { refreshToken: refresh_token } : {}),
+      ...(typeof twoFactorComplete === 'boolean' ? { twoFactorComplete } : {}),
+      ...(twoFactorMethod ? { twoFactorMethod } : {}),
+      ...(metadata ? {
+        metadata: {
+          ...(session.metadata || {}),
+          ...metadata,
+          updatedAt: new Date().toISOString()
+        }
+      } : {})
+    };
+
+    await updateSession(sessionToken, updatedSession);
+
+    return NextResponse.json({
+      success: true,
+      message: 'Session updated successfully'
+    });
+  } catch (error) {
+    console.error('[SESSION_ROUTE] Error updating session:', error);
+    return NextResponse.json({
+      error: 'Failed to update session',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
 }

package/src/routes/auth/viability.ts

@@ -35,6 +35,60 @@ async function getTenantRequiresTwoFactor(): Promise<boolean> {
   }
 }
 
+/**
+ * Which 2FA methods the TENANT permits — cards 141688 + 141741.
+ *
+ * WHY THIS IS HERE: this endpoint answered "is 2FA required, and is it done?"
+ * and said nothing about WITH WHAT. Both the middleware gate and the
+ * verify-code page call this route, and NEITHER had any method data — so
+ * nothing in the system asked whether the user CAN complete the challenge it
+ * is about to demand. A user whose tenant allows only `totp`, with no
+ * authenticator enrolled, is sent to a page that offers email and sms.
+ *
+ * ⚠ THIS IS NOT A COMPLETION SIGNAL AND MUST NEVER BE READ AS ONE.
+ * It says what the tenant PERMITS. It says nothing about what the user has
+ * enrolled, and nothing about whether they have verified. The invariant
+ * (QAPert, acceptance J2/J5) is: METHOD-PRESENCE IS NOT VERIFIED. A user with
+ * one method is still challenged and still gated until they actually verify.
+ * `userHasCompletedTenantTwoFactorRequirements` remains the only field that
+ * answers "are they through".
+ *
+ * STILL MISSING, deliberately not guessed here: the ENROLLED set. That lives
+ * behind /api/mfa/methods and needs a call this route does not currently make.
+ * Allowed-only closes the "offered a method the tenant forbids" half; it does
+ * NOT close "has nothing enrolled and no way to enrol". Both halves are named
+ * in the cards so neither gets lost.
+ *
+ * NULL MEANS UNKNOWN — IT DOES NOT MEAN "NONE", AND IT DOES NOT MEAN
+ * "email and sms". If the client config cannot be read we do not know what the
+ * tenant permits, and every available guess is wrong in a way that matters:
+ *
+ *   - guessing ['email','sms'] fails OPEN. On a totp-only tenant that offers
+ *     the user two methods the tenant forbids — which is defect 141688 itself,
+ *     re-created by its own fix during a config outage.
+ *   - guessing [] fails CLOSED but locks the user out of a challenge they may
+ *     be perfectly able to complete.
+ *
+ * So we report the truth (we don't know) and let the consumer decide, rather
+ * than encoding a guess that reads like a measurement. Same reasoning as the
+ * nullable require_2fa fix: "absent" has to be expressible, or callers cannot
+ * tell a real value from a default.
+ *
+ * No local default: `allowed2FAMethods` is non-optional on AuthSettings and is
+ * populated on BOTH config construction paths (idp-client-config.ts:333, :514)
+ * with the tenant's value or the layer's own ['email','sms']. Repeating that
+ * default here would be a second source for one setting, free to drift.
+ */
+async function getTenantAllowed2FAMethods(): Promise<string[] | null> {
+  try {
+    const config = await getIDPClientConfig();
+    return config.authSettings.allowed2FAMethods;
+  } catch {
+    console.warn('[VIABILITY] Could not get client config — reporting allowed 2FA methods as UNKNOWN (null), not guessing');
+    return null;
+  }
+}
+
 /**
  * GET /api/session/viability - Check if session is viable
  *
@@ -86,6 +140,31 @@ export async function GET(req: NextRequest) {
       });
     }
 
+    // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+    // See the SessionData.nextStep doc. This is the field that tells the gate
+    // whether the user CAN complete a challenge; without it both consumers were
+    // sending zero-method users to a page they had no way to act on.
+    //
+    // Declared once, here, above every return: `session` is settled by this
+    // point, and all three authenticated responses must carry the SAME value.
+    // Deriving it per-branch would let the paths drift apart silently.
+    //
+    // NO `?? null` HERE, DELIBERATELY — and this is the whole safety argument:
+    //
+    //   undefined = we never captured it. Every session minted BEFORE this
+    //               change is in that state, and there are live ones in Redis
+    //               right now. JSON.stringify omits the key, so the consumer
+    //               sees no field and knows it is uninformed.
+    //   null      = the IDP affirmatively said "nothing outstanding".
+    //
+    // Collapsing the first into the second with `?? null` would tell the gate
+    // "fully authenticated, nothing to do" about every pre-existing session —
+    // including a zero-method user who must be sent to enrol. That is a
+    // fail-open on the entire existing session population, produced by a
+    // default that reads like a measurement. Same mistake as the nullable
+    // require_2fa case: absent has to stay expressible.
+    const nextStep = session?.nextStep;
+
     // Check access token expiry
     const now = Math.floor(Date.now() / 1000);
     const accessTokenExpires = (token as any).accessTokenExpires || token.exp;
@@ -93,6 +172,8 @@ export async function GET(req: NextRequest) {
     if (!accessTokenExpires) {
       // No expiry info, assume viable but recommend refresh
       const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+      // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
+      const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
 
       // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
       const mfaExpiresAt = session?.mfaExpiresAt || 0;
@@ -115,6 +196,8 @@ export async function GET(req: NextRequest) {
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
         userStillNeedsTwoFactor,
+        tenantAllowed2FAMethods,
+        nextStep,
         // Legacy field names for backwards compatibility
         requires2FA: tenantRequiresTwoFactor,
         twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
@@ -137,6 +220,8 @@ export async function GET(req: NextRequest) {
 
     // CLEAR NAMING: Tenant-wide 2FA requirement from client config
     const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+    // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
+    const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
 
     // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
     // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
@@ -181,6 +266,8 @@ export async function GET(req: NextRequest) {
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
         userStillNeedsTwoFactor,
+        tenantAllowed2FAMethods,
+        nextStep,
         // Legacy names for backwards compatibility
         requires2FA: tenantRequiresTwoFactor,
         twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
@@ -203,6 +290,8 @@ export async function GET(req: NextRequest) {
       tenantRequiresTwoFactor,
       userHasCompletedTenantTwoFactorRequirements,
       userStillNeedsTwoFactor,
+      tenantAllowed2FAMethods,
+      nextStep,
       // Legacy names for backwards compatibility
       requires2FA: tenantRequiresTwoFactor,
       twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,

package/src/routes/index.ts

@@ -1,18 +1,18 @@
-/**
- * @payez/next-mvp Route Module Exports
- *
- * Ready-to-use route handlers for quick integration
- *
- * @version 2.3.0
- * @since auth-ready-v2
- */
-
-// Export auth routes
-export * from './auth';
-
-// Export account/2FA routes
-export * from './account';
-
-// Namespace exports for cleaner imports
-export * as auth from './auth';
+/**
+ * @payez/next-mvp Route Module Exports
+ *
+ * Ready-to-use route handlers for quick integration
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Export auth routes
+export * from './auth';
+
+// Export account/2FA routes
+export * from './account';
+
+// Namespace exports for cleaner imports
+export * as auth from './auth';
 export * as account from './account';

package/src/routes/mfa/backup-code-verify.ts

@@ -0,0 +1 @@
+export { POST } from '../../api-handlers/mfa/backup-code-verify';

package/src/routes/mfa/backup-codes.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use MFA Backup Codes Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/backup-codes/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/backup-codes';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/backup-codes';

package/src/routes/mfa/methods.ts

@@ -0,0 +1,22 @@
+/**
+ * Ready-to-Use MFA Methods Route (list / remove)
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/methods/route.ts
+ * export { GET } from '@payez/next-mvp/routes/mfa/methods';
+ * // app/api/mfa/methods/[id]/route.ts
+ * export { DELETE } from '@payez/next-mvp/routes/mfa/methods';
+ * ```
+ */
+import { NextRequest } from 'next/server';
+import { GET as listMethods, DELETE as deleteMethod } from '../../api-handlers/mfa/methods';
+
+export const GET = listMethods;
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function DELETE(req: NextRequest, ctx: Ctx) {
+  const { id } = await ctx.params;
+  return deleteMethod(req, id);
+}

package/src/routes/mfa/totp-confirm.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use TOTP Confirm Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/totp/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/totp-confirm';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/totp-confirm';

package/src/routes/mfa/totp-enroll.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use TOTP Enrol Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/totp/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/totp-enroll';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/totp-enroll';

package/src/routes/mfa/totp-verify.ts

@@ -0,0 +1,14 @@
+/**
+ * Ready-to-Use TOTP Verify Route (2FA CHALLENGE, not enrolment)
+ *
+ * Verifies an authenticator code at LOGIN and transitions the session to
+ * MFA-verified. Pair with totp-enroll/totp-confirm, which only ENROL a factor
+ * and deliberately do not touch session 2FA state.
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/totp/verify/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/totp-verify';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/totp-verify';

package/src/routes/passkeys/list.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use Passkey List Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/route.ts
+ * export { GET } from '@payez/next-mvp/routes/passkeys/list';
+ * ```
+ */
+export { GET } from '../../api-handlers/passkeys/list';

package/src/routes/passkeys/manage.ts

@@ -0,0 +1,23 @@
+/**
+ * Ready-to-Use Passkey Manage Route (rename / revoke one key)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/[id]/route.ts
+ * export { PATCH, DELETE } from '@payez/next-mvp/routes/passkeys/manage';
+ * ```
+ */
+import { NextRequest } from 'next/server';
+import { PATCH as patchOne, DELETE as deleteOne } from '../../api-handlers/passkeys/manage';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function PATCH(req: NextRequest, ctx: Ctx) {
+  const { id } = await ctx.params;
+  return patchOne(req, id);
+}
+
+export async function DELETE(req: NextRequest, ctx: Ctx) {
+  const { id } = await ctx.params;
+  return deleteOne(req, id);
+}

package/src/routes/passkeys/register-options.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use Passkey Registration Options Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/register/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/passkeys/register-options';
+ * ```
+ */
+export { POST } from '../../api-handlers/passkeys/register-options';

package/src/routes/passkeys/register-verify.ts

@@ -0,0 +1,10 @@
+/**
+ * Ready-to-Use Passkey Registration Verify Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/register/verify/route.ts
+ * export { POST } from '@payez/next-mvp/routes/passkeys/register-verify';
+ * ```
+ */
+export { POST } from '../../api-handlers/passkeys/register-verify';

package/src/routes/session/index.ts

@@ -1,7 +1,7 @@
-/**
- * Session Routes Index
- *
- * Re-exports all session-related route handlers for easy importing.
- */
-
-export { GET as refreshViabilityGET } from './refresh-viability';
+/**
+ * Session Routes Index
+ *
+ * Re-exports all session-related route handlers for easy importing.
+ */
+
+export { GET as refreshViabilityGET } from './refresh-viability';