@payez/next-mvp 4.1.14 → 4.1.21

package/src/routes/auth/passkey-signin.ts

@@ -0,0 +1,13 @@
+/**
+ * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkey/sign-in/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * // (optionsPOST is exported as POST; mount verify at its own path:)
+ * // app/api/passkey/sign-in/verify/route.ts
+ * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * ```
+ */
+export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';

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/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/server/auth.ts

@@ -20,7 +20,15 @@ let authInitPromise: Promise<ReturnType<typeof createBetterAuthInstance>> | null
 
 export type IdpTokenResult =
   | { success: true; accessToken: string; sessionData: SessionData }
-  | { success: false; error: 'NO_SESSION' | 'NO_TOKEN'; terminal: true };
+  | { success: false; error: 'NO_SESSION'; terminal: true }
+  // Card 187871: a Better Auth session can exist with NO idpAccessToken yet
+  // because 2FA is required and not yet completed - the IDP never issued the
+  // full token. That is a RECOVERABLE state (route to 2FA), not a dead
+  // session. Only collapse it to NO_TOKEN/terminal when the session itself
+  // already claims 2FA is done (sessionData.mfaVerified === true) and there is
+  // still no token - that combination is genuinely broken.
+  | { success: false; error: 'NO_TOKEN'; terminal: true }
+  | { success: false; error: 'NO_TOKEN_PENDING_2FA'; terminal: false; sessionData: SessionData };
 
 function buildSessionDataFromAuthSession(session: any): SessionData | null {
   const user = session?.user;
@@ -271,6 +279,14 @@ export async function getIdpToken(request?: Request): Promise<IdpTokenResult> {
 
   const accessToken = sessionData.idpAccessToken || (sessionData as any).accessToken;
   if (!accessToken) {
+    // Card 187871: a live Better Auth session with no idpAccessToken and
+    // mfaVerified !== true is a user mid-2FA, not a dead session - the IDP
+    // withholds the full token until 2FA completes (idp-fetch.ts:81/113).
+    // Only treat this as terminal once the session itself claims 2FA is
+    // already done; a token missing AFTER that is genuinely broken.
+    if (sessionData.mfaVerified !== true) {
+      return { success: false, error: 'NO_TOKEN_PENDING_2FA', terminal: false, sessionData };
+    }
     return { success: false, error: 'NO_TOKEN', terminal: true };
   }
 

package/src/server/decode-session.ts

@@ -71,8 +71,29 @@ async function tryBetterAuthSession(
     try {
       const { getRedis } = await import('../lib/redis');
       const { getAppSlug } = await import('../lib/app-slug');
-      const baKey = `ba:${getAppSlug()}:${result.session.token}`;
-      const baRaw = await getRedis().get(baKey);
+      // KEY-COMPOSER MISMATCH FIX (2026-08-02).
+      // better-auth writes this key as `ba:${idpConfig.clientSlug || getAppSlug()}:...`
+      // (better-auth.ts:99). This reader used getAppSlug() ALONE, so on any
+      // deployment where the IDP returns a clientSlug that differs from
+      // APP_SLUG the lookup missed entirely: idpTokens stayed null, and every
+      // caller looked unauthenticated regardless of their real session.
+      // Observed live: writer produced ba:idp_admin_ui_graft:<token> while this
+      // reader asked for ba:payez_idp_admin_web:<token>.
+      //
+      // Try the writer's composition FIRST, then the original as a fallback.
+      // Additive on purpose: it can only ever find MORE sessions than before,
+      // so no consumer whose keys already resolved can regress.
+      let baRaw: string | null = null;
+      try {
+        const idpCfg = await getIDPClientConfig();
+        const writerSlug = (idpCfg as { clientSlug?: string } | null)?.clientSlug;
+        if (writerSlug) {
+          baRaw = await getRedis().get(`ba:${writerSlug}:${result.session.token}`);
+        }
+      } catch { /* config unavailable — fall through to the legacy key */ }
+      if (!baRaw) {
+        baRaw = await getRedis().get(`ba:${getAppSlug()}:${result.session.token}`);
+      }
       if (baRaw) {
         const baData = JSON.parse(baRaw);
         idpTokens = baData.idpTokens;
@@ -90,7 +111,19 @@ async function tryBetterAuthSession(
       idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
         || (result.session.expiresAt ? new Date(result.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
       mfaVerified: idpTokens?.mfaVerified ?? false,
-      oauthProvider: 'google',
+      /**
+       * ⚠ WAS HARDCODED `'google'` — third site of QAPert finding #3 (card
+       * 167892), found by sweeping rather than by report.
+       *
+       * Note the line ABOVE is already honest: mfaVerified derives from what
+       * was stored. This one asserted the provider anyway, so a passkey
+       * sign-in decoded here was relabelled a Google OAuth sign-in — the
+       * provenance the sign-in path deliberately records, overwritten on read.
+       *
+       * The IDP emits NO provider claim (DotNetPert), so when it was not
+       * stored the honest answer is UNSET, not a guess.
+       */
+      oauthProvider: idpTokens?.oauthProvider ?? undefined,
       idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId,
       merchantId: idpTokens?.merchantId,
     };