@payez/next-mvp 4.5.6 → 4.7.9

package/src/middleware/create-middleware.ts

@@ -24,6 +24,14 @@ import { getInternalApiUrl } from '../edge/internal-api-url';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { checkPagePermission, isRBACEnabled } from './rbac-check';
 import { tokenLogId } from '../lib/token-log-id';
+import { expireSessionCookies } from '../auth/session-cookie-clear';
+import {
+  DEFAULT_SESSION_RESET_ROUTE,
+  boundSessionCookie,
+  normaliseResetParams,
+  resetSecret,
+  signedResetHref,
+} from '../auth/session-reset-link';
 
 // =============================================================================
 // TYPES
@@ -113,6 +121,19 @@ export interface MvpMiddlewareOptions {
   bypassPaths?: string[];
   /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
   rbacExemptPaths?: string[];
+  /**
+   * PAY-2218 - send a page's session-ending redirect through the session-reset ROUTE instead of clearing the
+   * cookies in the middleware response. Next strips the router's prefetch headers before middleware runs
+   * (15.5.x and 16.x; 16.2.x restores them only with `skipProxyUrlNormalize: true`), so a middleware clear also
+   * fires on a router PREFETCH and signs the user out of a page they never opened. The route sees those headers.
+   *
+   * Requires the app to mount the route:  app/api/auth/session-reset/route.ts
+   *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+   * `true` uses that default path; a string names another mount point under /api/auth/ (middleware bypasses it).
+   * Needs BETTER_AUTH_SECRET (or NEXTAUTH_SECRET) to sign the hand-off; without one the direct clear is kept and
+   * an error is logged once. Default: off (the direct clear), because an unmounted route would 404 every sign-out.
+   */
+  sessionResetRoute?: boolean | string;
   /**
    * PAY-1882 step 4 - how this app treats a producer that reports the session's
    * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
@@ -137,6 +158,18 @@ export interface MvpMiddlewareOptions {
    * is signed out for not implementing the check).
    */
   revocationFailMode?: 'closed' | 'open';
+
+  /**
+   * PAY-2302 cut 1c (BAPert 73585): this app has NO revocation source - for example a development environment
+   * provisioned without a vibe client id / HMAC key - and says so EXPLICITLY. Under it a viability answer of
+   * `revocationStatus: 'not_configured'` is viable, and a loud warning is logged once at startup.
+   *
+   * It relaxes ONLY 'not_configured'. 'unknown' (a revocation read that FAILED) and 'revoked' stay closed whatever
+   * `revocationFailMode` says, and the default (option absent) is unchanged: 'not_configured' fails closed, because
+   * for an app that HAS a vibe client it means a misconfiguration (BAPert 66356). Do not use this to paper over a
+   * misconfigured production app; remove it when the environment has a vibe client + HMAC key.
+   */
+  noRevocationSource?: boolean;
 }
 
 // =============================================================================
@@ -174,8 +207,13 @@ const defaultLogger: MiddlewareLogger = {
 const LOGIN_PAGE = '/account-auth/login';
 const VERIFY_CODE_PAGE = '/account-auth/verify-code';
 
+// PAY-2315 (4.7.1): /login is a public alias of the login page. It used to take the 'public: allow' arm and never reached the
+// 'already_authenticated' redirect, so a signed-in user was shown the sign-in form. It is the login page for every arm now.
+// (safe-callback refuses /login as a destination, so this cannot redirect to itself.)
+const LOGIN_ALIAS = '/login';
+
 function isLoginPage(pathname: string): boolean {
-  return pathname === LOGIN_PAGE;
+  return pathname === LOGIN_PAGE || pathname === LOGIN_ALIAS;
 }
 
 /**
@@ -221,26 +259,7 @@ export function isPrefetchRequest(request: NextRequest): boolean {
  */
 function clearSessionCookies(response: NextResponse, request: NextRequest): void {
   if (isPrefetchRequest(request)) return;
-  const sessionCookie = getSessionCookieName();
-  const secureCookie = getSecureSessionCookieName();
-
-  // Clear main cookies
-  response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
-  response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
-
-  // Clear any chunked cookies (NextAuth chunks large cookies)
-  for (const [name] of request.cookies) {
-    if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
-      const isSecure = name.startsWith('__Secure-');
-      response.cookies.set(name, '', {
-        path: '/',
-        expires: new Date(0),
-        httpOnly: true,
-        sameSite: 'lax',
-        ...(isSecure && { secure: true })
-      });
-    }
-  }
+  expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
 }
 
 /** Create redirect response, optionally clearing cookies */
@@ -256,6 +275,35 @@ function redirectTo(
   return response;
 }
 
+/** PAY-2218: where a page's clearing redirect goes when the app has mounted the session-reset route. */
+interface ResetConfig {
+  route: string;
+  secret: string;
+}
+
+/**
+ * A redirect that must also END the session. With the reset route configured, a page request is sent through it
+ * WITHOUT any Set-Cookie here: the route sees the flight headers this middleware cannot (Next strips them before
+ * middleware), answers a prefetch 204 + no-store, and clears on the real navigation. `/api/` requests and apps
+ * without the route keep the direct clear exactly as before.
+ */
+async function clearingRedirect(request: NextRequest, location: string, reset?: ResetConfig): Promise<NextResponse> {
+  if (!reset || request.nextUrl.pathname.startsWith('/api/')) {
+    return redirectTo(request, location, true);
+  }
+  const target = new URL(location, request.url);
+  const params = normaliseResetParams({
+    callbackUrl: target.searchParams.get('callbackUrl'),
+    reason: target.searchParams.get('reason'),
+    error: target.searchParams.get('error'),
+  });
+  // Bound to THIS request's session cookie: the route clears only when its own request carries the same one.
+  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
+  const response = NextResponse.redirect(new URL(await signedResetHref(reset.route, params, reset.secret, bound), request.url));
+  response.headers.set('cache-control', 'no-store');
+  return response;
+}
+
 /**
  * Terminal response for a FAILED token refresh.
  *
@@ -274,12 +322,13 @@ function redirectTo(
  * higher would intercept 'refresh_needed' and disable middleware token refresh across
  * the whole API surface (card 340024 C1).
  */
-function refreshFailureResponse(
+async function refreshFailureResponse(
   request: NextRequest,
   location: string,
   errorCode: string,
-  clearCookies = false
-): NextResponse {
+  clearCookies = false,
+  reset?: ResetConfig
+): Promise<NextResponse> {
   if (request.nextUrl.pathname.startsWith('/api/')) {
     const response = NextResponse.json({ error: errorCode }, { status: 401 });
     if (clearCookies) {
@@ -287,7 +336,7 @@ function refreshFailureResponse(
     }
     return response;
   }
-  return redirectTo(request, location, clearCookies);
+  return clearCookies ? clearingRedirect(request, location, reset) : redirectTo(request, location);
 }
 
 /**
@@ -497,6 +546,9 @@ function redirect2FA(callbackUrl: string): AuthAction {
 // MIDDLEWARE FACTORY
 // =============================================================================
 
+/** PAY-2218: the stripped-flight-headers warning is logged once per process, not once per request. */
+let flightHeadersStrippedWarned = false;
+
 export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   // Resolve options with defaults
   const cb = options.circuitBreaker || defaultCircuitBreaker;
@@ -507,6 +559,30 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   const rbacExemptPaths = options.rbacExemptPaths || [];
   // PAY-1882 step 4: default 'closed' (Jon's option A / BAPert 66316).
   const revocationFailMode = options.revocationFailMode || 'closed';
+  // PAY-2302 cut 1c: strictly `=== true`, so a truthy string in a config file cannot switch revocation off.
+  const noRevocationSource = options.noRevocationSource === true;
+  if (noRevocationSource) {
+    log.warn(
+      '[next-mvp] noRevocationSource is ON: sessions of this app CANNOT be revoked server-side (no vibe client / HMAC key). ' +
+      "revocationStatus 'not_configured' is treated as viable; 'unknown' and 'revoked' still sign the user out. " +
+      'Remove this option once the environment has a vibe client id and HMAC key.'
+    );
+  }
+  const sessionResetRoute =
+    options.sessionResetRoute === true ? DEFAULT_SESSION_RESET_ROUTE
+    : typeof options.sessionResetRoute === 'string' && options.sessionResetRoute ? options.sessionResetRoute
+    : undefined;
+  let resetSecretMissingLogged = false;
+  const resolveReset = (): ResetConfig | undefined => {
+    if (!sessionResetRoute) return undefined;
+    const secret = resetSecret();
+    if (secret) return { route: sessionResetRoute, secret };
+    if (!resetSecretMissingLogged) {
+      resetSecretMissingLogged = true;
+      log.error('sessionResetRoute is set but no BETTER_AUTH_SECRET/NEXTAUTH_SECRET is available to sign the hand-off; clearing in middleware instead', { sessionResetRoute });
+    }
+    return undefined;
+  };
 
   return async function middleware(request: NextRequest): Promise<NextResponse> {
     const { pathname, searchParams } = request.nextUrl;
@@ -529,6 +605,13 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       }
     }
 
+    // PAY-2218: a router request (it carries `next-url`) that arrives WITHOUT `rsc` had its flight headers stripped
+    // by Next before middleware ran, so isPrefetchRequest() cannot see a router prefetch on this app. Say so once.
+    if (!sessionResetRoute && !flightHeadersStrippedWarned && request.headers.has('next-url') && !request.headers.has('rsc')) {
+      flightHeadersStrippedWarned = true;
+      log.warn('Next strips router prefetch headers before middleware on this app, so a session-ending redirect can fire on a prefetch. Mount @payez/next-mvp/routes/auth/session-reset and set sessionResetRoute (PAY-2218).', { pathname });
+    }
+
     const isPublic = isUnauthenticatedRoute(pathname);
     const isLogin = isLoginPage(pathname);
 
@@ -547,7 +630,8 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       request,
       viabilityEndpoint,
       log,
-      revocationFailMode
+      revocationFailMode,
+      noRevocationSource
     );
 
     // --- Stale session (cookie exists but session doesn't): OBSERVE ONLY, DO NOT DECIDE ---
@@ -608,6 +692,7 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       logger: log,
       refreshEndpoint,
       rbacExemptPaths,
+      reset: resolveReset(),
       onRefreshSuccess: options.onRefreshSuccess,
       onRefreshFailure: options.onRefreshFailure,
     });
@@ -629,11 +714,14 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
 export function decideForceInvalid(
   data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
   revocationFailMode: 'closed' | 'open',
+  noRevocationSource: boolean = false,
 ): boolean {
   const status = data.revocationStatus;
   if (typeof status === 'string') {
     if (status === 'revoked') return true;
     if (status === 'active') return false;
+    // PAY-2302 cut 1c: an app that declared it has no revocation source. ONLY the exact 'not_configured' string.
+    if (status === 'not_configured' && noRevocationSource === true) return false;
     // S1 (NightHawk 66409): ANY other string - 'unknown', 'not_configured', a
     // typo like 'Revoked', 'error', or '' - is treated as 'unknown' (fail mode
     // applies), NEVER as 'active'. Returning false here would let the first
@@ -662,7 +750,8 @@ async function checkViability(
   request: NextRequest,
   endpoint: string,
   log: MiddlewareLogger,
-  revocationFailMode: 'closed' | 'open'
+  revocationFailMode: 'closed' | 'open',
+  noRevocationSource: boolean = false
 ): Promise<{
   sessionStatus: SessionStatus;
   sessionPointer: SessionPointer;
@@ -740,7 +829,7 @@ async function checkViability(
       // revocations status, decide from it + failMode and ignore the folded
       // booleans for unknown/not_configured. The booleans are read ONLY when
       // revocationStatus is ABSENT (idealresume.online's older boolean route).
-      sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode);
+      sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode, noRevocationSource);
       // PAY-2216: a STALE session - the cookie resolved to a token, but no store holds the session - used to set
       // pointer.exists=false, so makeAuthDecision took no_session (login, cookie NOT cleared) and its stale_session
       // arm (clearCookies) was unreachable: a dead cookie lingered and re-ran viability on every request.
@@ -778,6 +867,8 @@ interface ExecuteOptions {
   logger: MiddlewareLogger;
   refreshEndpoint: string;
   rbacExemptPaths: string[];
+  /** PAY-2218: set when the app mounted the session-reset route AND a signing secret exists. */
+  reset?: ResetConfig;
   onRefreshSuccess?: () => void;
   onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
 }
@@ -798,7 +889,9 @@ async function executeDecision(
       return handleAllow(request, pathname, sessionPointer, sessionStatus, opts.rbacExemptPaths);
 
     case 'redirect':
-      return redirectTo(request, decision.location, decision.clearCookies);
+      return decision.clearCookies
+        ? clearingRedirect(request, decision.location, opts.reset)
+        : redirectTo(request, decision.location);
 
     case 'service_error':
       return serviceUnavailableResponse(request);
@@ -943,7 +1036,8 @@ async function handleRefresh(
       request,
       `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`,
       errorParam,
-      isPermanentFailure
+      isPermanentFailure,
+      opts.reset
     );
   } catch (error: any) {
     const isNetwork = cb.isNetworkError(error);

package/src/pages/login/page.tsx

@@ -29,6 +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';
 
 function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
   const searchParams = useSearchParams();
@@ -117,46 +118,20 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
   // Atomic state management - only ONE can be true at a time
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [loginSuccess, setLoginSuccess] = useState(false);
-  const [loginError, setLoginError] = useState<string | null>(null);
+  // undefined = the user has not acted yet (show what the URL says); null/string = an explicit state set by a handler below.
+  const [loginError, setLoginError] = useState<string | null | undefined>(undefined);
   const [loading, setLoading] = useState(false);
   const [showRecoveryOptions, setShowRecoveryOptions] = useState(false);
 
   // Force show form after timeout if stuck in loading
   const [forceShowForm, setForceShowForm] = useState(false);
 
-  // Surface OAuth failures the Better Auth mount bounced back here.
+  // PAY-2319 (4.7.2): what the URL says, derived at render (no effect) so it is shown on the FIRST paint and in a static render.
+  // 4.7.1 mapped these in effects that only set loginError, which was never rendered. Unknown codes are NOT echoed (see lib/login-error-message).
+  const urlMessage = oauthFailureMessage(oauthError) ?? friendlyLoginError(urlError);
+  const shownError: string | null = loginError !== undefined ? loginError : urlMessage;
   useEffect(() => {
-    if (oauthError) {
-      const name = oauthError.charAt(0).toUpperCase() + oauthError.slice(1);
-      setLoginError(`${name} sign-in did not complete. Please try again.`);
-    }
-  }, [oauthError]);
-
-  // Handle URL errors with user-friendly messages
-  useEffect(() => {
-    if (urlError) {
-      let friendlyError: string | null = urlError;
-
-      if (urlError === 'SessionExpired') {
-        // Session expiration is normal - don't show as error
-        console.log('[LOGIN] SessionExpired detected - normal behavior');
-        friendlyError = null;
-      } else if (urlError === 'TwoFactorTimeout') {
-        // PAY-884: the sign-in expired while the verification code was outstanding. Unlike
-        // SessionExpired this is NOT silent - the user was mid-2FA and must know why they are here.
-        friendlyError = 'Your verification step timed out before the code was confirmed. Please sign in again.';
-      } else if (urlError === 'ServiceUnavailable') {
-        friendlyError = 'Authentication service is temporarily unavailable. Please try again in a few minutes.';
-      } else if (urlError.startsWith("Unexpected token")) {
-        friendlyError = 'An authentication error occurred. Please try signing in again.';
-      } else if (urlError.includes('not valid JSON')) {
-        friendlyError = 'An authentication error occurred. Please try signing in again.';
-      } else if (urlError === 'CredentialsSignin') {
-        friendlyError = 'Invalid email or password. Please try again.';
-      }
-
-      setLoginError(friendlyError);
-    }
+    if (urlError === 'SessionExpired') console.log('[LOGIN] SessionExpired detected - normal behavior');
   }, [urlError]);
 
   // Timeout to prevent infinite loading states
@@ -186,7 +161,7 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
   // package never configures emailAndPassword. See the note at the render site.
 
   // Show loading spinner for initial loads
-  if (!forceShowForm && !loginError && (loading || (status === 'loading' && !session))) {
+  if (!forceShowForm && !shownError && (loading || (status === 'loading' && !session))) {
     return (
       <div className={`flex flex-col items-center justify-center min-h-screen ${colors.background}`}>
         <svg className="animate-spin h-6 w-6" style={{ color: buttonColor }} viewBox="0 0 24 24" fill="none">
@@ -246,6 +221,17 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
             </p>
           </div>
 
+          {/* PAY-2319 (4.7.2): the error sentence. 4.7.1 set loginError but never rendered it. */}
+          {shownError && (
+            <div
+              role="alert"
+              data-testid="login-error"
+              className="mb-6 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700"
+            >
+              {shownError}
+            </div>
+          )}
+
           {/* Social sign-in — rendered ONLY from the IDP client config's
               enabled providers (see the /api/auth/settings discovery above).
               Above the form, divider idiom per the package's ModeAwareLoginPage. */}

package/src/routes/auth/credential-login-email-code.ts

@@ -0,0 +1,6 @@
+/**
+ * PAY-2302 cut 1: ask the IdP to email a code when the authenticator lane failed on our side.
+ * The handler lives in api-handlers/auth/credential-login-email-code.ts (moved from VibeID-Customer-Portal src/app/api/auth/admin-login/email-code/route.ts). A consuming app's route file
+ * re-exports POST and writes `export const runtime = 'nodejs'` literally.
+ */
+export { POST } from '../../api-handlers/auth/credential-login-email-code';

package/src/routes/auth/credential-login.ts

@@ -0,0 +1,6 @@
+/**
+ * PAY-2302 cut 1: password sign-in route (IdP ExternalAuth/login, session written via lib/session-store, 2FA-outstanding handling).
+ * The handler lives in api-handlers/auth/credential-login.ts (moved from VibeID-Customer-Portal src/app/api/auth/admin-login/route.ts). A consuming app's route file
+ * re-exports POST and writes `export const runtime = 'nodejs'` literally.
+ */
+export { POST } from '../../api-handlers/auth/credential-login';

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

@@ -0,0 +1,37 @@
+/**
+ * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
+ *
+ *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+ *
+ * and turn it on with createMvpMiddleware({ sessionResetRoute: true }). The middleware then sends a page's
+ * session-ending redirect (stale session, force-invalidated, pre-2FA timeout, refresh 401/403) here instead of
+ * clearing the cookies itself. See src/auth/session-reset-link.ts for the measurements behind each rule.
+ *
+ *  - Router PREFETCH (the route sees `next-router-prefetch`, which Next strips before middleware): 204 + no-store,
+ *    no redirect, no Set-Cookie. A redirect here would be cached by the 15.5.x router and reused by the click, so
+ *    the real navigation would never come back to clear.
+ *  - Real navigation with a valid signed hand-off: expire the session cookies and 307 to the login page.
+ *  - Anything unsigned, tampered, expired, or bound to a DIFFERENT session than this request's cookie: 307 to the
+ *    login page and touch NO cookie (nobody can link a signed-in user here to log them out; a second use is a no-op).
+ *
+ * The login URL is always rebuilt from allowlisted parts; the route never redirects to a URL it was given.
+ */
+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';
+
+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;
+}

package/src/routes/oauth/resume.ts

@@ -0,0 +1,11 @@
+/**
+ * PAY-2302 cut 2: post-2FA OAuth authorize resume route. The handler lives in api-handlers/oauth/resume.ts
+ * (moved from VibeID-Customer-Portal src/app/api/oauth/resume/route.ts). A consuming app's route file re-exports GET
+ * and writes `export const runtime = 'nodejs'` literally.
+ *
+ * 4.7.3: `createOAuthResumeHandler({ refusalLocation })` and `DEFAULT_REFUSAL_LOCATION` are re-exported HERE because a consumer can only
+ * import what `package.json` `exports` lists, and this route module is the entry. An app whose sign-in page is not
+ * /account-auth/login (the portal uses /sign-in) writes `export const GET = createOAuthResumeHandler({ refusalLocation: '/sign-in?error=AUTHORIZE_RESUME_REFUSED' });`.
+ */
+export { GET, createOAuthResumeHandler, DEFAULT_REFUSAL_LOCATION } from '../../api-handlers/oauth/resume';
+export type { OAuthResumeOptions, OAuthResumeDeps } from '../../api-handlers/oauth/resume';