@payez/next-mvp 4.1.9 → 4.1.11

package/src/lib/test-aware-get-token.ts

@@ -1,41 +1,41 @@
-import { NextRequest } from 'next/server';
-import { logger } from '../config/logger';
-import { getSession } from '../server/auth';
-import { getSessionCookieName } from './app-slug';
-
-export async function getTokenTestAware(req: NextRequest): Promise<any> {
-  if (process.env.TEST_MODE === 'true') {
-    try {
-      let secret = process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET;
-      if (!secret || secret.trim() === '') {
-        const { getIDPClientConfig } = await import('./idp-client-config');
-        const idpConfig = await getIDPClientConfig();
-        secret = idpConfig.authSecret;
-      }
-      // Use app-slug prefixed cookie name
-      const cookieName = getSessionCookieName();
-      const cookies = req.headers.get('cookie'); if (!cookies) { logger.debug('[GET_TOKEN] No cookies in request'); return null; }
-      const cookieValue = cookies.split(';').find(c => c.trim().startsWith(`${cookieName}=`))?.split('=')[1];
-      if (!cookieValue) { logger.debug('[GET_TOKEN] Session token cookie not found'); return null; }
-      const { jwtVerify } = await import('jose');
-      const secretKey = new TextEncoder().encode(secret);
-      const { payload } = await jwtVerify(cookieValue, secretKey);
-      logger.debug('[GET_TOKEN] TEST_MODE token decoded:', { hasPayload: !!payload, redisSessionId: (payload as any).redisSessionId, sub: (payload as any).sub });
-      return payload;
-    } catch (error) { logger.error('[GET_TOKEN] TEST_MODE token decode error:', { error: error instanceof Error ? error.message : String(error) }); return null; }
-  }
-  // Production path: Better Auth session
-  const session = await getSession(req);
-  if (session?.user && session?.session?.token) {
-    return {
-      sub: session.user.id,
-      email: session.user.email,
-      name: session.user.name,
-      sessionToken: session.session.token,
-      roles: session.user.roles || [],
-      ...session.user,
-    };
-  }
-
-  return null;
-}
+import { NextRequest } from 'next/server';
+import { logger } from '../config/logger';
+import { getSession } from '../server/auth';
+import { getSessionCookieName } from './app-slug';
+
+export async function getTokenTestAware(req: NextRequest): Promise<any> {
+  if (process.env.TEST_MODE === 'true') {
+    try {
+      let secret = process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET;
+      if (!secret || secret.trim() === '') {
+        const { getIDPClientConfig } = await import('./idp-client-config');
+        const idpConfig = await getIDPClientConfig();
+        secret = idpConfig.authSecret;
+      }
+      // Use app-slug prefixed cookie name
+      const cookieName = getSessionCookieName();
+      const cookies = req.headers.get('cookie'); if (!cookies) { logger.debug('[GET_TOKEN] No cookies in request'); return null; }
+      const cookieValue = cookies.split(';').find(c => c.trim().startsWith(`${cookieName}=`))?.split('=')[1];
+      if (!cookieValue) { logger.debug('[GET_TOKEN] Session token cookie not found'); return null; }
+      const { jwtVerify } = await import('jose');
+      const secretKey = new TextEncoder().encode(secret);
+      const { payload } = await jwtVerify(cookieValue, secretKey);
+      logger.debug('[GET_TOKEN] TEST_MODE token decoded:', { hasPayload: !!payload, redisSessionId: (payload as any).redisSessionId, sub: (payload as any).sub });
+      return payload;
+    } catch (error) { logger.error('[GET_TOKEN] TEST_MODE token decode error:', { error: error instanceof Error ? error.message : String(error) }); return null; }
+  }
+  // Production path: Better Auth session
+  const session = await getSession(req);
+  if (session?.user && session?.session?.token) {
+    return {
+      sub: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      sessionToken: session.session.token,
+      roles: session.user.roles || [],
+      ...session.user,
+    };
+  }
+
+  return null;
+}

package/src/lib/token-lifecycle.ts

@@ -46,6 +46,13 @@ export interface TokenError {
   error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
   message: string;
   terminal?: boolean;  // If true, don't retry - redirect to login
+  // WO-1 (genuine-dead refresh): the VERBATIM upstream reason from the IDP, preserved
+  // end-to-end so the consumer can surface an honest error + halt a futile re-auth loop
+  // (e.g. an unapproved user whose login mints a bearer but whose refresh terminally
+  // fails). `error` stays the stable category for existing consumers; `code`/`resolution`
+  // carry the real cause. Never soften — surface it.
+  code?: string;        // Upstream IDP error code (e.g. UNAUTHORIZED, USER_NOT_APPROVED)
+  resolution?: string;  // Upstream human-readable resolution hint, if any
 }
 
 export type EnsureFreshTokenResult = TokenResult | TokenError;
@@ -123,6 +130,8 @@ interface RefreshResult {
   success: boolean;
   terminal?: boolean;  // If true, session is dead - don't retry, redirect to login
   code?: string;       // Error code from refresh endpoint
+  message?: string;    // WO-1: verbatim human message from the refresh endpoint
+  resolution?: string; // WO-1: verbatim resolution hint from the refresh endpoint
 }
 
 /**
@@ -201,7 +210,16 @@ async function triggerRefresh(
       // Don't retry - user must re-authenticate
       if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
         console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
-        return { success: false, terminal: true, code: responseData.code };
+        // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
+        // message in `error` and the code in `code`; carry both up so the consumer
+        // can tell the user WHY (not just "session expired") and stop a futile loop.
+        return {
+          success: false,
+          terminal: true,
+          code: responseData.code,
+          message: responseData.error,
+          resolution: responseData.resolution,
+        };
       }
 
       // For other 401s, check if maybe session was refreshed by another request
@@ -388,12 +406,21 @@ export async function ensureFreshToken(
       if (!refreshResult.success) {
         // Check for terminal state - session cannot be recovered
         if (refreshResult.terminal) {
-          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired with no refresh token - redirect to login');
+          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
+            code: refreshResult.code,
+            message: refreshResult.message,
+          });
+          // WO-1: keep `error` as the stable terminal category (existing consumers
+          // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
+          // reason via code/message/resolution so the user learns WHY and a genuinely
+          // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
           return {
             success: false,
             error: 'SESSION_EXPIRED_NO_REFRESH',
-            message: 'Session expired. Please sign in again.',
+            message: refreshResult.message || 'Session expired. Please sign in again.',
             terminal: true,
+            code: refreshResult.code,
+            resolution: refreshResult.resolution,
           };
         }
 

package/src/lib/user-agent-parser.ts

@@ -1,252 +1,252 @@
-/**
- * =============================================================================
- * USER AGENT PARSER
- * =============================================================================
- *
- * Lightweight user agent parsing without external dependencies.
- * Extracts device type, browser, and OS information from user agent strings.
- *
- * USAGE:
- * ------
- * import { parseUserAgent, DeviceInfo } from '@payez/next-mvp/lib/user-agent-parser';
- *
- * const info = parseUserAgent(request.headers.get('user-agent'));
- * console.log(info.browser); // 'Chrome'
- * console.log(info.deviceType); // 'desktop'
- *
- * =============================================================================
- */
-
-// -----------------------------------------------------------------------------
-// TYPES
-// -----------------------------------------------------------------------------
-
-export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'unknown';
-
-export interface DeviceInfo {
-  deviceType: DeviceType;
-  browser: string;
-  browserVersion?: string;
-  os: string;
-  osVersion?: string;
-  isMobile: boolean;
-  isTablet: boolean;
-  isDesktop: boolean;
-  isBot: boolean;
-  raw: string;
-}
-
-// -----------------------------------------------------------------------------
-// DETECTION PATTERNS
-// -----------------------------------------------------------------------------
-
-const MOBILE_KEYWORDS = [
-  'Mobile',
-  'Android',
-  'iPhone',
-  'iPod',
-  'BlackBerry',
-  'IEMobile',
-  'Opera Mini',
-  'Opera Mobi',
-  'Windows Phone',
-];
-
-const TABLET_KEYWORDS = [
-  'iPad',
-  'Tablet',
-  'PlayBook',
-  'Silk',
-  'Kindle',
-];
-
-const BOT_KEYWORDS = [
-  'bot',
-  'spider',
-  'crawler',
-  'slurp',
-  'googlebot',
-  'bingbot',
-  'yandex',
-  'baidu',
-  'duckduckbot',
-  'facebookexternalhit',
-  'twitterbot',
-  'linkedinbot',
-  'pinterest',
-  'semrush',
-  'ahref',
-];
-
-// Browser detection patterns (order matters - more specific first)
-const BROWSER_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
-  { name: 'Edge', pattern: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)*)/ },
-  { name: 'Opera', pattern: /(?:OPR|Opera)\/(\d+(?:\.\d+)*)/ },
-  { name: 'Samsung Browser', pattern: /SamsungBrowser\/(\d+(?:\.\d+)*)/ },
-  { name: 'UC Browser', pattern: /UCBrowser\/(\d+(?:\.\d+)*)/ },
-  { name: 'Firefox', pattern: /Firefox\/(\d+(?:\.\d+)*)/ },
-  { name: 'Chrome', pattern: /Chrome\/(\d+(?:\.\d+)*)/ },
-  { name: 'Safari', pattern: /Version\/(\d+(?:\.\d+)*).*Safari/ },
-  { name: 'Safari', pattern: /Safari\/(\d+(?:\.\d+)*)/ },
-  { name: 'IE', pattern: /(?:MSIE |rv:)(\d+(?:\.\d+)*)/ },
-];
-
-// OS detection patterns
-const OS_PATTERNS: Array<{ name: string; pattern: RegExp; versionPattern?: RegExp }> = [
-  { name: 'iOS', pattern: /iPhone|iPad|iPod/, versionPattern: /OS (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
-  { name: 'Android', pattern: /Android/, versionPattern: /Android (\d+(?:\.\d+)*)/ },
-  { name: 'Windows', pattern: /Windows/, versionPattern: /Windows NT (\d+(?:\.\d+)*)/ },
-  { name: 'macOS', pattern: /Mac OS X/, versionPattern: /Mac OS X (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
-  { name: 'Linux', pattern: /Linux/, versionPattern: undefined },
-  { name: 'Chrome OS', pattern: /CrOS/, versionPattern: undefined },
-];
-
-// Windows NT version mapping
-const WINDOWS_VERSIONS: Record<string, string> = {
-  '10.0': '10/11',
-  '6.3': '8.1',
-  '6.2': '8',
-  '6.1': '7',
-  '6.0': 'Vista',
-  '5.1': 'XP',
-};
-
-// -----------------------------------------------------------------------------
-// PARSER FUNCTION
-// -----------------------------------------------------------------------------
-
-/**
- * Parse a user agent string to extract device, browser, and OS information.
- *
- * @param userAgent - The user agent string from request headers
- * @returns Parsed device information
- */
-export function parseUserAgent(userAgent?: string | null): DeviceInfo {
-  const ua = userAgent || '';
-  const uaLower = ua.toLowerCase();
-
-  // Default result
-  const result: DeviceInfo = {
-    deviceType: 'unknown',
-    browser: 'Unknown',
-    os: 'Unknown',
-    isMobile: false,
-    isTablet: false,
-    isDesktop: false,
-    isBot: false,
-    raw: ua,
-  };
-
-  if (!ua) return result;
-
-  // Check for bots first
-  result.isBot = BOT_KEYWORDS.some(keyword => uaLower.includes(keyword));
-
-  // Detect device type
-  result.isTablet = TABLET_KEYWORDS.some(keyword => ua.includes(keyword));
-  result.isMobile = !result.isTablet && MOBILE_KEYWORDS.some(keyword => ua.includes(keyword));
-  result.isDesktop = !result.isMobile && !result.isTablet && !result.isBot;
-
-  if (result.isTablet) {
-    result.deviceType = 'tablet';
-  } else if (result.isMobile) {
-    result.deviceType = 'mobile';
-  } else if (result.isDesktop) {
-    result.deviceType = 'desktop';
-  }
-
-  // Detect browser
-  for (const { name, pattern } of BROWSER_PATTERNS) {
-    const match = ua.match(pattern);
-    if (match) {
-      result.browser = name;
-      result.browserVersion = match[1];
-      break;
-    }
-  }
-
-  // Detect OS
-  for (const { name, pattern, versionPattern } of OS_PATTERNS) {
-    if (pattern.test(ua)) {
-      result.os = name;
-      if (versionPattern) {
-        const versionMatch = ua.match(versionPattern);
-        if (versionMatch) {
-          let version = versionMatch[1].replace(/_/g, '.');
-
-          // Map Windows NT versions to friendly names
-          if (name === 'Windows' && WINDOWS_VERSIONS[version]) {
-            version = WINDOWS_VERSIONS[version];
-          }
-
-          result.osVersion = version;
-        }
-      }
-      break;
-    }
-  }
-
-  return result;
-}
-
-// -----------------------------------------------------------------------------
-// HELPER FUNCTIONS
-// -----------------------------------------------------------------------------
-
-/**
- * Get a short, human-readable description of the device
- */
-export function getDeviceDescription(info: DeviceInfo): string {
-  const parts: string[] = [];
-
-  if (info.browser !== 'Unknown') {
-    parts.push(info.browser);
-  }
-
-  if (info.os !== 'Unknown') {
-    let osDesc = info.os;
-    if (info.osVersion) {
-      osDesc += ` ${info.osVersion}`;
-    }
-    parts.push(osDesc);
-  }
-
-  if (parts.length === 0) {
-    if (info.isBot) return 'Bot';
-    return info.deviceType.charAt(0).toUpperCase() + info.deviceType.slice(1);
-  }
-
-  return parts.join(' / ');
-}
-
-/**
- * Get device type icon (emoji)
- */
-export function getDeviceIcon(deviceType: DeviceType): string {
-  switch (deviceType) {
-    case 'mobile':
-      return '📱';
-    case 'tablet':
-      return '📲';
-    case 'desktop':
-      return '💻';
-    default:
-      return '🔌';
-  }
-}
-
-/**
- * Get browser icon (emoji)
- */
-export function getBrowserIcon(browser: string): string {
-  const browserLower = browser.toLowerCase();
-
-  if (browserLower.includes('chrome')) return '🌐';
-  if (browserLower.includes('firefox')) return '🦊';
-  if (browserLower.includes('safari')) return '🧭';
-  if (browserLower.includes('edge')) return '🌐';
-  if (browserLower.includes('opera')) return '🔴';
-  if (browserLower.includes('ie') || browserLower.includes('internet explorer')) return '🌐';
-
-  return '🌐';
-}
+/**
+ * =============================================================================
+ * USER AGENT PARSER
+ * =============================================================================
+ *
+ * Lightweight user agent parsing without external dependencies.
+ * Extracts device type, browser, and OS information from user agent strings.
+ *
+ * USAGE:
+ * ------
+ * import { parseUserAgent, DeviceInfo } from '@payez/next-mvp/lib/user-agent-parser';
+ *
+ * const info = parseUserAgent(request.headers.get('user-agent'));
+ * console.log(info.browser); // 'Chrome'
+ * console.log(info.deviceType); // 'desktop'
+ *
+ * =============================================================================
+ */
+
+// -----------------------------------------------------------------------------
+// TYPES
+// -----------------------------------------------------------------------------
+
+export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'unknown';
+
+export interface DeviceInfo {
+  deviceType: DeviceType;
+  browser: string;
+  browserVersion?: string;
+  os: string;
+  osVersion?: string;
+  isMobile: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+  isBot: boolean;
+  raw: string;
+}
+
+// -----------------------------------------------------------------------------
+// DETECTION PATTERNS
+// -----------------------------------------------------------------------------
+
+const MOBILE_KEYWORDS = [
+  'Mobile',
+  'Android',
+  'iPhone',
+  'iPod',
+  'BlackBerry',
+  'IEMobile',
+  'Opera Mini',
+  'Opera Mobi',
+  'Windows Phone',
+];
+
+const TABLET_KEYWORDS = [
+  'iPad',
+  'Tablet',
+  'PlayBook',
+  'Silk',
+  'Kindle',
+];
+
+const BOT_KEYWORDS = [
+  'bot',
+  'spider',
+  'crawler',
+  'slurp',
+  'googlebot',
+  'bingbot',
+  'yandex',
+  'baidu',
+  'duckduckbot',
+  'facebookexternalhit',
+  'twitterbot',
+  'linkedinbot',
+  'pinterest',
+  'semrush',
+  'ahref',
+];
+
+// Browser detection patterns (order matters - more specific first)
+const BROWSER_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
+  { name: 'Edge', pattern: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)*)/ },
+  { name: 'Opera', pattern: /(?:OPR|Opera)\/(\d+(?:\.\d+)*)/ },
+  { name: 'Samsung Browser', pattern: /SamsungBrowser\/(\d+(?:\.\d+)*)/ },
+  { name: 'UC Browser', pattern: /UCBrowser\/(\d+(?:\.\d+)*)/ },
+  { name: 'Firefox', pattern: /Firefox\/(\d+(?:\.\d+)*)/ },
+  { name: 'Chrome', pattern: /Chrome\/(\d+(?:\.\d+)*)/ },
+  { name: 'Safari', pattern: /Version\/(\d+(?:\.\d+)*).*Safari/ },
+  { name: 'Safari', pattern: /Safari\/(\d+(?:\.\d+)*)/ },
+  { name: 'IE', pattern: /(?:MSIE |rv:)(\d+(?:\.\d+)*)/ },
+];
+
+// OS detection patterns
+const OS_PATTERNS: Array<{ name: string; pattern: RegExp; versionPattern?: RegExp }> = [
+  { name: 'iOS', pattern: /iPhone|iPad|iPod/, versionPattern: /OS (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
+  { name: 'Android', pattern: /Android/, versionPattern: /Android (\d+(?:\.\d+)*)/ },
+  { name: 'Windows', pattern: /Windows/, versionPattern: /Windows NT (\d+(?:\.\d+)*)/ },
+  { name: 'macOS', pattern: /Mac OS X/, versionPattern: /Mac OS X (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
+  { name: 'Linux', pattern: /Linux/, versionPattern: undefined },
+  { name: 'Chrome OS', pattern: /CrOS/, versionPattern: undefined },
+];
+
+// Windows NT version mapping
+const WINDOWS_VERSIONS: Record<string, string> = {
+  '10.0': '10/11',
+  '6.3': '8.1',
+  '6.2': '8',
+  '6.1': '7',
+  '6.0': 'Vista',
+  '5.1': 'XP',
+};
+
+// -----------------------------------------------------------------------------
+// PARSER FUNCTION
+// -----------------------------------------------------------------------------
+
+/**
+ * Parse a user agent string to extract device, browser, and OS information.
+ *
+ * @param userAgent - The user agent string from request headers
+ * @returns Parsed device information
+ */
+export function parseUserAgent(userAgent?: string | null): DeviceInfo {
+  const ua = userAgent || '';
+  const uaLower = ua.toLowerCase();
+
+  // Default result
+  const result: DeviceInfo = {
+    deviceType: 'unknown',
+    browser: 'Unknown',
+    os: 'Unknown',
+    isMobile: false,
+    isTablet: false,
+    isDesktop: false,
+    isBot: false,
+    raw: ua,
+  };
+
+  if (!ua) return result;
+
+  // Check for bots first
+  result.isBot = BOT_KEYWORDS.some(keyword => uaLower.includes(keyword));
+
+  // Detect device type
+  result.isTablet = TABLET_KEYWORDS.some(keyword => ua.includes(keyword));
+  result.isMobile = !result.isTablet && MOBILE_KEYWORDS.some(keyword => ua.includes(keyword));
+  result.isDesktop = !result.isMobile && !result.isTablet && !result.isBot;
+
+  if (result.isTablet) {
+    result.deviceType = 'tablet';
+  } else if (result.isMobile) {
+    result.deviceType = 'mobile';
+  } else if (result.isDesktop) {
+    result.deviceType = 'desktop';
+  }
+
+  // Detect browser
+  for (const { name, pattern } of BROWSER_PATTERNS) {
+    const match = ua.match(pattern);
+    if (match) {
+      result.browser = name;
+      result.browserVersion = match[1];
+      break;
+    }
+  }
+
+  // Detect OS
+  for (const { name, pattern, versionPattern } of OS_PATTERNS) {
+    if (pattern.test(ua)) {
+      result.os = name;
+      if (versionPattern) {
+        const versionMatch = ua.match(versionPattern);
+        if (versionMatch) {
+          let version = versionMatch[1].replace(/_/g, '.');
+
+          // Map Windows NT versions to friendly names
+          if (name === 'Windows' && WINDOWS_VERSIONS[version]) {
+            version = WINDOWS_VERSIONS[version];
+          }
+
+          result.osVersion = version;
+        }
+      }
+      break;
+    }
+  }
+
+  return result;
+}
+
+// -----------------------------------------------------------------------------
+// HELPER FUNCTIONS
+// -----------------------------------------------------------------------------
+
+/**
+ * Get a short, human-readable description of the device
+ */
+export function getDeviceDescription(info: DeviceInfo): string {
+  const parts: string[] = [];
+
+  if (info.browser !== 'Unknown') {
+    parts.push(info.browser);
+  }
+
+  if (info.os !== 'Unknown') {
+    let osDesc = info.os;
+    if (info.osVersion) {
+      osDesc += ` ${info.osVersion}`;
+    }
+    parts.push(osDesc);
+  }
+
+  if (parts.length === 0) {
+    if (info.isBot) return 'Bot';
+    return info.deviceType.charAt(0).toUpperCase() + info.deviceType.slice(1);
+  }
+
+  return parts.join(' / ');
+}
+
+/**
+ * Get device type icon (emoji)
+ */
+export function getDeviceIcon(deviceType: DeviceType): string {
+  switch (deviceType) {
+    case 'mobile':
+      return '📱';
+    case 'tablet':
+      return '📲';
+    case 'desktop':
+      return '💻';
+    default:
+      return '🔌';
+  }
+}
+
+/**
+ * Get browser icon (emoji)
+ */
+export function getBrowserIcon(browser: string): string {
+  const browserLower = browser.toLowerCase();
+
+  if (browserLower.includes('chrome')) return '🌐';
+  if (browserLower.includes('firefox')) return '🦊';
+  if (browserLower.includes('safari')) return '🧭';
+  if (browserLower.includes('edge')) return '🌐';
+  if (browserLower.includes('opera')) return '🔴';
+  if (browserLower.includes('ie') || browserLower.includes('internet explorer')) return '🌐';
+
+  return '🌐';
+}