@payez/next-mvp 4.8.0 → 4.8.2

package/src/auth/auth-decision.ts

@@ -1,293 +1,293 @@
-/**
- * Auth Decision Engine - Pure function for middleware auth flow
- * 
- * This module provides a deterministic decision tree for authentication middleware.
- * All auth flow logic is centralized here for testability and maintainability.
- */
-
-import { safeCallbackPath } from './safe-callback';
-import { tokenLogId } from '../lib/token-log-id';
-
-// Input types for the decision engine
-export interface AuthContext {
-  pathname: string;
-  isPublicRoute: boolean;
-  isLoginPage: boolean;
-  searchParams: URLSearchParams;
-  sessionPointer: {
-    exists: boolean;
-    sessionToken?: string;
-    expired?: boolean;
-  };
-  sessionStatus: {
-    exists: boolean | null; // null = check failed/timeout
-    forceInvalid: boolean | null; // null = check failed/timeout
-    /** PAY-2339: the producer said the revocation backend could not answer. makeAuthDecision HOLDS (no sign-out). */
-    unavailable?: boolean;
-    requires2FA: boolean;
-    twoFactorComplete: boolean;
-  };
-  circuitBreakerOpen: boolean;
-  /** PAY-2136: the request is a router prefetch. A prefetch never clears cookies (see isPrefetchRequest). */
-  isPrefetch?: boolean;
-}
-
-// Output types for the decision engine
-export type AuthAction = 
-  | { type: 'allow' }
-  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
-  | { type: 'service_error'; reason: string; check?: 'revocation' | 'viability' };
-
-/** PAY-2180: warn once per process, not per request. */
-let deprecationWarned = false;
-
-/**
- * Main decision function - pure, testable, deterministic.
- * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
- * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
- *
- * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
- * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
- * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
- * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
- */
-export function makeAuthDecision(context: AuthContext): AuthAction {
-  if (!deprecationWarned) {
-    deprecationWarned = true;
-    console.warn(
-      '[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
-        'createMvpMiddleware does not use it. Use createMvpMiddleware.'
-    );
-  }
-  const action = decide(context);
-  if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
-    const { clearCookies: _dropped, ...rest } = action;
-    return rest;
-  }
-  return action;
-}
-
-function decide(context: AuthContext): AuthAction {
-  const {
-    pathname,
-    isPublicRoute,
-    isLoginPage,
-    searchParams,
-    sessionPointer,
-    sessionStatus,
-    circuitBreakerOpen
-  } = context;
-
-  // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops.
-  // 375656: `pathname` is our own request path rather than an attacker-supplied
-  // parameter, so this site was not the open redirect - but it is routed through
-  // the same guard so the package has ONE definition of an acceptable callback,
-  // and so the value is parser-normalised before being carried into a redirect.
-  const safeCallbackUrl = safeCallbackPath(pathname);
-
-  // Public routes are allowed, but we need to check login page separately
-  if (isPublicRoute && !isLoginPage) {
-    // For non-login public routes, check if authenticated user needs 2FA
-    if (sessionPointer.exists && sessionStatus.exists && sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
-      // Skip redirect for verify-code page
-      if (pathname === '/account-auth/verify-code') {
-        return { type: 'allow' };
-      }
-    }
-    return { type: 'allow' };
-  }
-
-  // Circuit breaker open - redirect to login with service unavailable
-  if (circuitBreakerOpen) {
-    if (isLoginPage) {
-      return { type: 'allow' }; // Let them see login page
-    }
-    return {
-      type: 'redirect',
-      location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
-      reason: 'CircuitBreakerOpen'
-      // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
-      // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
-      // page - createMvpMiddleware does, see serviceUnavailableResponse.)
-    };
-  }
-
-  // No session pointer (JWT cookie) - need to login
-  if (!sessionPointer.exists) {
-    if (isLoginPage) {
-      return { type: 'allow' };
-    }
-    // Redirect root to configured URL for unauthenticated users
-    if (pathname === '/') {
-      const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login';
-      return {
-        type: 'redirect',
-        location: unauthUrl,
-        reason: 'unauthenticated_root_redirect'
-      };
-    }
-    return {
-      type: 'redirect',
-      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
-      reason: 'no_session_pointer'
-    };
-  }
-
-  // Redis/service errors - can't verify session
-  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
-    return { 
-      type: 'service_error', 
-      reason: 'redis_unavailable' 
-    };
-  }
-
-  // PAY-2339 (BAPert 74633): the revocation backend could not answer. Hold: not a verdict on the session, so no
-  // sign-out and no cookie is touched. A caller maps this to its own "temporarily unavailable" answer (the
-  // createMvpMiddleware twin sends /service-unavailable or a 503 with unavailable:true, check:'revocation').
-  if (sessionStatus.unavailable) {
-    if (isLoginPage) {
-      return { type: 'allow' };
-    }
-    return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
-  }
-
-  // Session force invalidated - need fresh login
-  if (sessionStatus.forceInvalid) {
-    if (isLoginPage) {
-      return { type: 'allow' };
-    }
-    return {
-      type: 'redirect',
-      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=force_invalidated`,
-      reason: 'force_invalidated',
-      clearCookies: true
-    };
-  }
-
-  // Stale session (cookie exists but not in Redis) - need fresh login
-  if (!sessionStatus.exists) {
-    if (isLoginPage) {
-      return { type: 'allow' };
-    }
-    return {
-      type: 'redirect',
-      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=stale_session`,
-      reason: 'stale_session',
-      clearCookies: true
-    };
-  }
-
-  // PRIORITIZE 2FA: If session exists and 2FA is required but not complete, handle this before token-expired logic
-  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
-    console.log('[MIDDLEWARE-DECISION] 2FA required but not complete', {
-      pathname,
-      isLoginPage,
-      sessionExists: sessionStatus.exists,
-      sessionToken: tokenLogId(sessionPointer.sessionToken)
-    });
-    
-    // Already on the 2FA page
-    if (pathname === '/account-auth/verify-code') {
-      console.log('[MIDDLEWARE-DECISION] Already on verify-code page, allowing');
-      return { type: 'allow' };
-    }
-    // If user is on the login page, send them to verify-code with the original callback
-    if (isLoginPage) {
-      const callbackUrl = searchParams.get('callbackUrl') || '/';
-      // 375656: this previously tested the raw parameter with a prefix check against
-      // the auth path, and returned the parameter itself when it did not match.
-      // (The vulnerable expression is deliberately NOT reproduced verbatim here: a
-      // comment carrying it puts the string into dist, and a reviewer grepping for
-      // that pattern would score this FIXED build as vulnerable - the exact
-      // sink-counting inversion recorded on 375936.)
-      // That is a redirect-LOOP guard in the seat where an ORIGIN check belongs:
-      // `https://evil.example.com` does not start with `/account-auth/`, so it passed
-      // through untouched. safeCallbackPath() asks the URL parser instead, so every
-      // spelling that escapes the origin fails one comparison. See ./safe-callback.
-      const safeCallbackUrl = safeCallbackPath(callbackUrl);
-      console.log('[MIDDLEWARE-DECISION] On login page with 2FA incomplete, redirecting to verify-code', {
-        originalCallback: callbackUrl,
-        safeCallback: safeCallbackUrl,
-        originalUrl: pathname
-      });
-      return {
-        type: 'redirect',
-        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
-        reason: '2fa_required_login_redirect'
-      };
-    }
-    // For protected routes, allow middleware to proceed (it may refresh tokens); pages will enforce 2FA
-    console.log('[MIDDLEWARE-DECISION] Protected route with incomplete 2FA, allowing middleware to handle');
-    return { type: 'allow' };
-  }
-
-  // Token expired - redirect to login
-  if (sessionPointer.expired) {
-    if (isLoginPage) {
-      return { type: 'allow' };
-    }
-    return {
-      type: 'redirect',
-      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&error=SessionExpired`,
-      reason: 'token_expired'
-    };
-  }
-
-  // Authenticated root path should land on dashboards
-  if (pathname === '/') {
-    return {
-      type: 'redirect',
-      location: '/',
-      reason: 'authenticated_root_redirect'
-    };
-  }
-
-  // Valid session but 2FA required and not complete - more intelligent handling
-  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
-    if (pathname === '/account-auth/verify-code') {
-      return { type: 'allow' }; // Already on 2FA page
-    }
-
-    // For login page, redirect to 2FA with original callback
-    if (isLoginPage) {
-      const callbackUrl = searchParams.get('callbackUrl') || '/';
-      // 375656: origin-checked, not prefix-checked. See ./safe-callback.
-      const safeCallbackUrl = safeCallbackPath(callbackUrl);
-      return {
-        type: 'redirect',
-        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
-        reason: '2fa_required'
-      };
-    }
-
-    // For protected routes:
-    // - If access token is expired and we have a valid refresh token, let middleware handle refresh first
-    // - Only redirect to verify-code if access token is still valid or refresh failed
-    // - Allow middleware to pass - it will either refresh successfully or handle redirect appropriately
-    return { type: 'allow' };
-  }
-
-  // Authenticated user on login page - redirect to dashboard or callback
-  if (isLoginPage) {
-    const callbackUrl = searchParams.get('callbackUrl') || '/';
-    // 375656 - THE PUBLISHED OPEN REDIRECT. This value becomes `location` VERBATIM
-    // below (not a query parameter on a relative path, as at the two sites above),
-    // so the old `startsWith('/account-auth/')` test sent an authenticated user
-    // straight to any absolute URL an attacker put in `?callbackUrl=`. Its own
-    // comment says "prevents infinite loop", which is what it was written for -
-    // loop prevention, never origin validation. See ./safe-callback.
-    const safeCallbackUrl = safeCallbackPath(callbackUrl);
-    console.log('[MIDDLEWARE-DECISION] Authenticated user on login page, redirecting', {
-      originalCallback: callbackUrl,
-      safeCallback: safeCallbackUrl
-    });
-    return {
-      type: 'redirect',
-      location: safeCallbackUrl,
-      reason: 'already_authenticated'
-    };
-  }
-
-  // All checks passed - allow access
-  return { type: 'allow' };
+/**
+ * Auth Decision Engine - Pure function for middleware auth flow
+ * 
+ * This module provides a deterministic decision tree for authentication middleware.
+ * All auth flow logic is centralized here for testability and maintainability.
+ */
+
+import { safeCallbackPath } from './safe-callback';
+import { tokenLogId } from '../lib/token-log-id';
+
+// Input types for the decision engine
+export interface AuthContext {
+  pathname: string;
+  isPublicRoute: boolean;
+  isLoginPage: boolean;
+  searchParams: URLSearchParams;
+  sessionPointer: {
+    exists: boolean;
+    sessionToken?: string;
+    expired?: boolean;
+  };
+  sessionStatus: {
+    exists: boolean | null; // null = check failed/timeout
+    forceInvalid: boolean | null; // null = check failed/timeout
+    /** PAY-2339: the producer said the revocation backend could not answer. makeAuthDecision HOLDS (no sign-out). */
+    unavailable?: boolean;
+    requires2FA: boolean;
+    twoFactorComplete: boolean;
+  };
+  circuitBreakerOpen: boolean;
+  /** PAY-2136: the request is a router prefetch. A prefetch never clears cookies (see isPrefetchRequest). */
+  isPrefetch?: boolean;
+}
+
+// Output types for the decision engine
+export type AuthAction = 
+  | { type: 'allow' }
+  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
+  | { type: 'service_error'; reason: string; check?: 'revocation' | 'viability' };
+
+/** PAY-2180: warn once per process, not per request. */
+let deprecationWarned = false;
+
+/**
+ * Main decision function - pure, testable, deterministic.
+ * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
+ * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
+ */
+export function makeAuthDecision(context: AuthContext): AuthAction {
+  if (!deprecationWarned) {
+    deprecationWarned = true;
+    console.warn(
+      '[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
+        'createMvpMiddleware does not use it. Use createMvpMiddleware.'
+    );
+  }
+  const action = decide(context);
+  if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
+    const { clearCookies: _dropped, ...rest } = action;
+    return rest;
+  }
+  return action;
+}
+
+function decide(context: AuthContext): AuthAction {
+  const {
+    pathname,
+    isPublicRoute,
+    isLoginPage,
+    searchParams,
+    sessionPointer,
+    sessionStatus,
+    circuitBreakerOpen
+  } = context;
+
+  // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops.
+  // 375656: `pathname` is our own request path rather than an attacker-supplied
+  // parameter, so this site was not the open redirect - but it is routed through
+  // the same guard so the package has ONE definition of an acceptable callback,
+  // and so the value is parser-normalised before being carried into a redirect.
+  const safeCallbackUrl = safeCallbackPath(pathname);
+
+  // Public routes are allowed, but we need to check login page separately
+  if (isPublicRoute && !isLoginPage) {
+    // For non-login public routes, check if authenticated user needs 2FA
+    if (sessionPointer.exists && sessionStatus.exists && sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+      // Skip redirect for verify-code page
+      if (pathname === '/account-auth/verify-code') {
+        return { type: 'allow' };
+      }
+    }
+    return { type: 'allow' };
+  }
+
+  // Circuit breaker open - redirect to login with service unavailable
+  if (circuitBreakerOpen) {
+    if (isLoginPage) {
+      return { type: 'allow' }; // Let them see login page
+    }
+    return {
+      type: 'redirect',
+      location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
+      reason: 'CircuitBreakerOpen'
+      // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
+      // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
+      // page - createMvpMiddleware does, see serviceUnavailableResponse.)
+    };
+  }
+
+  // No session pointer (JWT cookie) - need to login
+  if (!sessionPointer.exists) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    // Redirect root to configured URL for unauthenticated users
+    if (pathname === '/') {
+      const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login';
+      return {
+        type: 'redirect',
+        location: unauthUrl,
+        reason: 'unauthenticated_root_redirect'
+      };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+      reason: 'no_session_pointer'
+    };
+  }
+
+  // Redis/service errors - can't verify session
+  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+    return { 
+      type: 'service_error', 
+      reason: 'redis_unavailable' 
+    };
+  }
+
+  // PAY-2339 (BAPert 74633): the revocation backend could not answer. Hold: not a verdict on the session, so no
+  // sign-out and no cookie is touched. A caller maps this to its own "temporarily unavailable" answer (the
+  // createMvpMiddleware twin sends /service-unavailable or a 503 with unavailable:true, check:'revocation').
+  if (sessionStatus.unavailable) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
+  }
+
+  // Session force invalidated - need fresh login
+  if (sessionStatus.forceInvalid) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=force_invalidated`,
+      reason: 'force_invalidated',
+      clearCookies: true
+    };
+  }
+
+  // Stale session (cookie exists but not in Redis) - need fresh login
+  if (!sessionStatus.exists) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=stale_session`,
+      reason: 'stale_session',
+      clearCookies: true
+    };
+  }
+
+  // PRIORITIZE 2FA: If session exists and 2FA is required but not complete, handle this before token-expired logic
+  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+    console.log('[MIDDLEWARE-DECISION] 2FA required but not complete', {
+      pathname,
+      isLoginPage,
+      sessionExists: sessionStatus.exists,
+      sessionToken: tokenLogId(sessionPointer.sessionToken)
+    });
+    
+    // Already on the 2FA page
+    if (pathname === '/account-auth/verify-code') {
+      console.log('[MIDDLEWARE-DECISION] Already on verify-code page, allowing');
+      return { type: 'allow' };
+    }
+    // If user is on the login page, send them to verify-code with the original callback
+    if (isLoginPage) {
+      const callbackUrl = searchParams.get('callbackUrl') || '/';
+      // 375656: this previously tested the raw parameter with a prefix check against
+      // the auth path, and returned the parameter itself when it did not match.
+      // (The vulnerable expression is deliberately NOT reproduced verbatim here: a
+      // comment carrying it puts the string into dist, and a reviewer grepping for
+      // that pattern would score this FIXED build as vulnerable - the exact
+      // sink-counting inversion recorded on 375936.)
+      // That is a redirect-LOOP guard in the seat where an ORIGIN check belongs:
+      // `https://evil.example.com` does not start with `/account-auth/`, so it passed
+      // through untouched. safeCallbackPath() asks the URL parser instead, so every
+      // spelling that escapes the origin fails one comparison. See ./safe-callback.
+      const safeCallbackUrl = safeCallbackPath(callbackUrl);
+      console.log('[MIDDLEWARE-DECISION] On login page with 2FA incomplete, redirecting to verify-code', {
+        originalCallback: callbackUrl,
+        safeCallback: safeCallbackUrl,
+        originalUrl: pathname
+      });
+      return {
+        type: 'redirect',
+        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+        reason: '2fa_required_login_redirect'
+      };
+    }
+    // For protected routes, allow middleware to proceed (it may refresh tokens); pages will enforce 2FA
+    console.log('[MIDDLEWARE-DECISION] Protected route with incomplete 2FA, allowing middleware to handle');
+    return { type: 'allow' };
+  }
+
+  // Token expired - redirect to login
+  if (sessionPointer.expired) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&error=SessionExpired`,
+      reason: 'token_expired'
+    };
+  }
+
+  // Authenticated root path should land on dashboards
+  if (pathname === '/') {
+    return {
+      type: 'redirect',
+      location: '/',
+      reason: 'authenticated_root_redirect'
+    };
+  }
+
+  // Valid session but 2FA required and not complete - more intelligent handling
+  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+    if (pathname === '/account-auth/verify-code') {
+      return { type: 'allow' }; // Already on 2FA page
+    }
+
+    // For login page, redirect to 2FA with original callback
+    if (isLoginPage) {
+      const callbackUrl = searchParams.get('callbackUrl') || '/';
+      // 375656: origin-checked, not prefix-checked. See ./safe-callback.
+      const safeCallbackUrl = safeCallbackPath(callbackUrl);
+      return {
+        type: 'redirect',
+        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+        reason: '2fa_required'
+      };
+    }
+
+    // For protected routes:
+    // - If access token is expired and we have a valid refresh token, let middleware handle refresh first
+    // - Only redirect to verify-code if access token is still valid or refresh failed
+    // - Allow middleware to pass - it will either refresh successfully or handle redirect appropriately
+    return { type: 'allow' };
+  }
+
+  // Authenticated user on login page - redirect to dashboard or callback
+  if (isLoginPage) {
+    const callbackUrl = searchParams.get('callbackUrl') || '/';
+    // 375656 - THE PUBLISHED OPEN REDIRECT. This value becomes `location` VERBATIM
+    // below (not a query parameter on a relative path, as at the two sites above),
+    // so the old `startsWith('/account-auth/')` test sent an authenticated user
+    // straight to any absolute URL an attacker put in `?callbackUrl=`. Its own
+    // comment says "prevents infinite loop", which is what it was written for -
+    // loop prevention, never origin validation. See ./safe-callback.
+    const safeCallbackUrl = safeCallbackPath(callbackUrl);
+    console.log('[MIDDLEWARE-DECISION] Authenticated user on login page, redirecting', {
+      originalCallback: callbackUrl,
+      safeCallback: safeCallbackUrl
+    });
+    return {
+      type: 'redirect',
+      location: safeCallbackUrl,
+      reason: 'already_authenticated'
+    };
+  }
+
+  // All checks passed - allow access
+  return { type: 'allow' };
 }