@payez/next-mvp 4.1.10 → 4.1.11-idealvibe.1

package/dist/auth/better-auth.js

@@ -126,24 +126,16 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
         // Redis-backed session storage via secondaryStorage
         secondaryStorage: {
             get: async (key) => {
-                try {
-                    return await (0, redis_1.getRedis)().get(`ba:${appSlug}:${key}`);
-                }
-                catch {
-                    return null;
-                }
+                return await (0, redis_1.getRedis)().get(`ba:${appSlug}:${key}`);
             },
             set: async (key, value, ttl) => {
-                try {
-                    const redis = (0, redis_1.getRedis)();
-                    if (ttl) {
-                        await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-                    }
-                    else {
-                        await redis.setex(`ba:${appSlug}:${key}`, session_store_1.SESSION_TTL, value);
-                    }
+                const redis = (0, redis_1.getRedis)();
+                if (ttl) {
+                    await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
+                }
+                else {
+                    await redis.setex(`ba:${appSlug}:${key}`, session_store_1.SESSION_TTL, value);
                 }
-                catch { /* Redis unavailable — cookie cache still works */ }
             },
             delete: async (key) => {
                 try {
@@ -327,8 +319,20 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             return false;
         }
         // Build IDP token data
-        // CRITICAL: If the IDP withholds refresh_token without setting requiresTwoFactor,
-        // treat missing refresh token as "2FA required" so middleware redirects to verify-code.
+        // ORIGINAL INTENT: IDP withholds refresh_token until 2FA is complete, so
+        // !hasRefreshToken was a reliable "2FA required" signal.
+        //
+        // BUG [IDP-2FA-BUG]: IDP is currently returning refresh_token on the initial
+        // oauth-callback even for require_2fa tenants that haven't done 2FA yet.
+        // This made !hasRefreshToken=false → requiresTwoFactor=false → mfaVerified=true,
+        // bypassing the 2FA gate entirely.
+        //
+        // FIX: Always set mfaVerified=false on the initial OAuth exchange.
+        // The tenant's require_2fa setting is enforced by the viability endpoint
+        // (tenantRequiresTwoFactor=true), which redirects to verify-code whenever
+        // mfaVerified=false. After real 2FA, transitionTo2FASession() sets it true.
+        // Revert this comment + restore `mfaVerified: !requiresTwoFactor` once the
+        // IDP correctly withholds refresh_token until post-2FA.
         const hasRefreshToken = !!result.refresh_token;
         const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? !hasRefreshToken;
         const idpTokenData = {
@@ -342,7 +346,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             name: result.user?.full_name || result.user?.name || result.name || name,
             image: image,
             roles: result.user?.roles || result.roles || [],
-            mfaVerified: !requiresTwoFactor,
+            mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
             idpClientId: result.client_id ? String(result.client_id) : undefined,
             merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
         };

package/dist/client/better-auth-client.d.ts

@@ -814,7 +814,13 @@ export declare const authClient: {
         isPending: boolean;
         isRefetching: boolean;
         error: import("@better-fetch/fetch").BetterFetchError | null;
-        refetch: (queryParams?: {
+        refetch: (queryParams
+        /**
+         * NextAuth-compatible signOut wrapper.
+         *
+         * Maps NextAuth signOut({ redirect, callbackUrl }) to Better Auth.
+         */
+        ?: {
             query?: import("better-auth/types").SessionQueryParams;
         } | undefined) => Promise<void>;
     };
@@ -988,7 +994,13 @@ export declare const useSession: () => {
     isPending: boolean;
     isRefetching: boolean;
     error: import("@better-fetch/fetch").BetterFetchError | null;
-    refetch: (queryParams?: {
+    refetch: (queryParams
+    /**
+     * NextAuth-compatible signOut wrapper.
+     *
+     * Maps NextAuth signOut({ redirect, callbackUrl }) to Better Auth.
+     */
+    ?: {
         query?: import("better-auth/types").SessionQueryParams;
     } | undefined) => Promise<void>;
 }, signIn: {

package/dist/lib/ensure-fresh-access-token.js

@@ -158,8 +158,16 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         if (isOAuthSession && session.mfaVerified && acrValue === '1') {
             acrValue = '2';
         }
+        // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
+        // `session` was read before we acquired the lock; a concurrent refresh that
+        // completed while we waited rotates the token, so the pre-lock value is stale
+        // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
+        // the round-trip is wasted). `latest` is the authoritative post-lock session.
+        // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
+        // the identity context of THIS request, unchanged by a token rotation.
+        const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
         const body = {
-            refresh_token: session.idpRefreshToken,
+            refresh_token: sentRefreshToken,
             amr: authMethods,
             acr: acrValue,
         };
@@ -209,7 +217,10 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                 // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
                 // a concurrent rotation is NOT a terminal condition.
                 const postRefresh = await (0, session_store_1.getSession)(sessionToken);
-                const tokenUnchanged = !!session.idpRefreshToken && postRefresh?.idpRefreshToken === session.idpRefreshToken;
+                // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
+                // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
+                // between pre-lock read and our send would be misjudged.
+                const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
                 if (tokenUnchanged) {
                     await (0, session_store_1.updateSession)(sessionToken, {
                         idpRefreshToken: '',

package/dist/lib/session-store.js

@@ -489,27 +489,27 @@ async function releaseRefreshLock(sessionToken, requestId, lockVersion) {
     const lockKey = getRefreshLockKey(sessionToken);
     try {
         // Lua script for atomic lock validation and release
-        const luaScript = `
-      local lockKey = KEYS[1]
-      local expectedRequestId = ARGV[1]
-      local expectedVersion = ARGV[2]
-
-      local lockData = redis.call('GET', lockKey)
-      if not lockData then
-        return 0  -- Lock doesn't exist
-      end
-
-      local lockInfo = cjson.decode(lockData)
-      if lockInfo.acquiredBy == expectedRequestId then
-        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
-          redis.call('DEL', lockKey)
-          return 1  -- Successfully released
-        else
-          return -2  -- Version mismatch
-        end
-      else
-        return -1  -- Wrong owner
-      end
+        const luaScript = `
+      local lockKey = KEYS[1]
+      local expectedRequestId = ARGV[1]
+      local expectedVersion = ARGV[2]
+
+      local lockData = redis.call('GET', lockKey)
+      if not lockData then
+        return 0  -- Lock doesn't exist
+      end
+
+      local lockInfo = cjson.decode(lockData)
+      if lockInfo.acquiredBy == expectedRequestId then
+        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
+          redis.call('DEL', lockKey)
+          return 1  -- Successfully released
+        else
+          return -2  -- Version mismatch
+        end
+      else
+        return -1  -- Wrong owner
+      end
     `;
         const result = await redis_1.default.eval(luaScript, 1, lockKey, requestId, lockVersion ? lockVersion.toString() : '');
         if (result === 1) {

package/dist/lib/startup-init.js

@@ -213,25 +213,25 @@ async function performInitialization() {
         const connectionLine = isConnectionError
             ? '║   🔌 CONNECTION REFUSED - IDP appears to be down             ║\n║                                                              ║\n'
             : '';
-        console.error(`
-╔══════════════════════════════════════════════════════════════╗
-║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║
-║                                                              ║
-║   The app cannot start without a valid auth signing secret.  ║
-║   This should be fetched from IDP at startup.                ║
-║                                                              ║
-${connectionLine}║   Possible causes:                                           ║
-║   • IDP is not running or unreachable                        ║
-║   • CLIENT_ID is not registered in IDP                       ║
-║   • IDP_URL is incorrect                                     ║
-║   • Network connectivity issue                               ║
-║                                                              ║
-║   Current config:                                            ║
-║   • IDP_URL: ${idpUrl}║
-║   • CLIENT_ID: ${clientId}║
-╚══════════════════════════════════════════════════════════════╝
-
-[STARTUP] Error: ${errorMsg}
+        console.error(`
+╔══════════════════════════════════════════════════════════════╗
+║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║
+║                                                              ║
+║   The app cannot start without a valid auth signing secret.  ║
+║   This should be fetched from IDP at startup.                ║
+║                                                              ║
+${connectionLine}║   Possible causes:                                           ║
+║   • IDP is not running or unreachable                        ║
+║   • CLIENT_ID is not registered in IDP                       ║
+║   • IDP_URL is incorrect                                     ║
+║   • Network connectivity issue                               ║
+║                                                              ║
+║   Current config:                                            ║
+║   • IDP_URL: ${idpUrl}║
+║   • CLIENT_ID: ${clientId}║
+╚══════════════════════════════════════════════════════════════╝
+
+[STARTUP] Error: ${errorMsg}
 `);
         // Re-throw so callers know initialization failed
         throw lastInitError;

package/dist/lib/token-lifecycle.d.ts

@@ -31,6 +31,8 @@ export interface TokenError {
     error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
     message: string;
     terminal?: boolean;
+    code?: string;
+    resolution?: string;
 }
 export type EnsureFreshTokenResult = TokenResult | TokenError;
 /**

package/dist/lib/token-lifecycle.js

@@ -150,7 +150,16 @@ async function triggerRefresh(request, sessionToken, retryCount = 0) {
             // 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
             if (response.status === 401 && retryCount < maxRetries) {
@@ -318,12 +327,21 @@ async function ensureFreshToken(request) {
             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,
                     };
                 }
                 console.warn('[TOKEN_LIFECYCLE] Refresh failed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.1.10",
+  "version": "4.1.11-idealvibe.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/check-internal-url-usage.sh

@@ -1,73 +1,73 @@
-#!/bin/bash
-#
-# CI Check: Detect incorrect internal API URL patterns
-#
-# This script fails if code is using req.url or req.nextUrl.origin to construct
-# URLs for internal API calls. These patterns cause 403 errors in Kubernetes
-# because they use the external HTTPS URL instead of INTERNAL_API_URL.
-#
-# CORRECT:   Use internalFetch() or internalRefresh() from @payez/next-mvp/lib/internal-api
-# INCORRECT: new URL('/api/...', req.url) or fetch(`${req.nextUrl.origin}/api/...`)
-#
-# NOTE: new URL(req.url) alone is FINE - it just parses the incoming request URL.
-#       The problem is when you construct a NEW path using req.url as the base.
-#
-
-set -e
-
-SEARCH_PATH="${1:-.}"
-ERRORS_FOUND=0
-
-echo "Checking for incorrect internal URL patterns in: $SEARCH_PATH"
-echo "========================================================================"
-
-# Pattern 1: new URL('/api/...', req.url) - constructing internal API URL from request
-# This catches: new URL('/api/...', req.url) and new URL("/api/...", req.url)
-# But NOT: new URL(req.url) which is just parsing the request
-echo ""
-echo "Checking for: new URL('/api/...', req.url) pattern"
-if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\(['\"][^'\"]*['\"],\s*req\.url" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'new URL(path, req.url)' pattern. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 2: new URL('/api/...', req.nextUrl) or new URL(..., req.nextUrl.origin)
-echo ""
-echo "Checking for: new URL(..., req.nextUrl) pattern"
-if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\([^)]+,\s*req\.nextUrl" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'new URL(..., req.nextUrl)' pattern. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 3: fetch with req.nextUrl.origin and /api/
-echo ""
-echo "Checking for: fetch with req.nextUrl.origin and /api/"
-if grep -rn --include="*.ts" --include="*.tsx" "req\.nextUrl\.origin.*\/api\/" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
-    echo "ERROR: Found 'req.nextUrl.origin' used with internal API route. Use internalFetch() instead."
-    ERRORS_FOUND=1
-fi
-
-# Pattern 4: Direct fetch to /api/auth/refresh without using internalRefresh (warning only)
-echo ""
-echo "Checking for: Direct fetch to /api/auth/refresh (should use internalRefresh)"
-if grep -rn --include="*.ts" --include="*.tsx" "fetch.*\/api\/auth\/refresh" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts" | grep -v "internal-api\.ts"; then
-    echo "WARNING: Found direct fetch to /api/auth/refresh. Consider using internalRefresh() helper."
-    # Not failing on this one as it might be intentional in some cases (client-side refresh)
-fi
-
-echo ""
-echo "========================================================================"
-
-if [ $ERRORS_FOUND -eq 1 ]; then
-    echo "FAILED: Dangerous internal URL patterns detected!"
-    echo ""
-    echo "Fix: Import and use helpers from @payez/next-mvp/lib/internal-api:"
-    echo "  import { internalFetch, internalRefresh } from '@payez/next-mvp/lib/internal-api';"
-    echo ""
-    echo "Why: Server-to-server calls must use INTERNAL_API_URL (http://service.namespace.svc.cluster.local)"
-    echo "     not the external URL from the request (https://api.example.com) which fails in Kubernetes."
-    exit 1
-else
-    echo "PASSED: No dangerous internal URL patterns found."
-    exit 0
-fi
+#!/bin/bash
+#
+# CI Check: Detect incorrect internal API URL patterns
+#
+# This script fails if code is using req.url or req.nextUrl.origin to construct
+# URLs for internal API calls. These patterns cause 403 errors in Kubernetes
+# because they use the external HTTPS URL instead of INTERNAL_API_URL.
+#
+# CORRECT:   Use internalFetch() or internalRefresh() from @payez/next-mvp/lib/internal-api
+# INCORRECT: new URL('/api/...', req.url) or fetch(`${req.nextUrl.origin}/api/...`)
+#
+# NOTE: new URL(req.url) alone is FINE - it just parses the incoming request URL.
+#       The problem is when you construct a NEW path using req.url as the base.
+#
+
+set -e
+
+SEARCH_PATH="${1:-.}"
+ERRORS_FOUND=0
+
+echo "Checking for incorrect internal URL patterns in: $SEARCH_PATH"
+echo "========================================================================"
+
+# Pattern 1: new URL('/api/...', req.url) - constructing internal API URL from request
+# This catches: new URL('/api/...', req.url) and new URL("/api/...", req.url)
+# But NOT: new URL(req.url) which is just parsing the request
+echo ""
+echo "Checking for: new URL('/api/...', req.url) pattern"
+if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\(['\"][^'\"]*['\"],\s*req\.url" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'new URL(path, req.url)' pattern. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 2: new URL('/api/...', req.nextUrl) or new URL(..., req.nextUrl.origin)
+echo ""
+echo "Checking for: new URL(..., req.nextUrl) pattern"
+if grep -rn --include="*.ts" --include="*.tsx" -E "new URL\([^)]+,\s*req\.nextUrl" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'new URL(..., req.nextUrl)' pattern. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 3: fetch with req.nextUrl.origin and /api/
+echo ""
+echo "Checking for: fetch with req.nextUrl.origin and /api/"
+if grep -rn --include="*.ts" --include="*.tsx" "req\.nextUrl\.origin.*\/api\/" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts"; then
+    echo "ERROR: Found 'req.nextUrl.origin' used with internal API route. Use internalFetch() instead."
+    ERRORS_FOUND=1
+fi
+
+# Pattern 4: Direct fetch to /api/auth/refresh without using internalRefresh (warning only)
+echo ""
+echo "Checking for: Direct fetch to /api/auth/refresh (should use internalRefresh)"
+if grep -rn --include="*.ts" --include="*.tsx" "fetch.*\/api\/auth\/refresh" "$SEARCH_PATH" 2>/dev/null | grep -v "node_modules" | grep -v "\.d\.ts" | grep -v "internal-api\.ts"; then
+    echo "WARNING: Found direct fetch to /api/auth/refresh. Consider using internalRefresh() helper."
+    # Not failing on this one as it might be intentional in some cases (client-side refresh)
+fi
+
+echo ""
+echo "========================================================================"
+
+if [ $ERRORS_FOUND -eq 1 ]; then
+    echo "FAILED: Dangerous internal URL patterns detected!"
+    echo ""
+    echo "Fix: Import and use helpers from @payez/next-mvp/lib/internal-api:"
+    echo "  import { internalFetch, internalRefresh } from '@payez/next-mvp/lib/internal-api';"
+    echo ""
+    echo "Why: Server-to-server calls must use INTERNAL_API_URL (http://service.namespace.svc.cluster.local)"
+    echo "     not the external URL from the request (https://api.example.com) which fails in Kubernetes."
+    exit 1
+else
+    echo "PASSED: No dangerous internal URL patterns found."
+    exit 0
+fi

package/src/api/index.ts

@@ -1,18 +1,18 @@
-/**
- * @payez/next-mvp API Module Exports
- *
- * Provides enhanced API route handlers with automatic token management
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-export {
-  createAuthHandler,
-  type AuthContext,
-  type AuthHandlerOptions,
-  type HandlerFunction
-} from './auth-handler';
-
-// Default export for convenience
+/**
+ * @payez/next-mvp API Module Exports
+ *
+ * Provides enhanced API route handlers with automatic token management
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+export {
+  createAuthHandler,
+  type AuthContext,
+  type AuthHandlerOptions,
+  type HandlerFunction
+} from './auth-handler';
+
+// Default export for convenience
 export { default } from './auth-handler';

package/src/api-handlers/account/masked-info.ts

@@ -1,45 +1,45 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-
-// IDP masked-info is POST and uses capital 'A' in /api/Account
-export async function POST(req: NextRequest) {
-  const url = `${ENV_CONFIG.IDP_URL}/api/Account/masked-info`;
-
-  // Forward request body if present; IDP often accepts empty object
-  let body = '{}';
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) body = raw;
-  } catch {}
-
-  const result = await idpFetchJSON(req, url, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body
-  });
-
-  if (!result.ok) {
-    return NextResponse.json(
-      {
-        success: false,
-        message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
-        meta: { attemptedRefresh: result.attemptedRefresh },
-      },
-      { status: result.status }
-    );
-  }
-
-  const bodyJson: any = result.json;
-  // Unwrap if IDP returns envelope { success, data }
-  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if ((bodyJson as any).success === true) {
-      return NextResponse.json((bodyJson as any).data, { status: 200 });
-    }
-    return NextResponse.json(bodyJson, { status: 200 });
-  }
-
-  // Passthrough otherwise
-  return NextResponse.json(bodyJson ?? {}, { status: 200 });
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+// IDP masked-info is POST and uses capital 'A' in /api/Account
+export async function POST(req: NextRequest) {
+  const url = `${ENV_CONFIG.IDP_URL}/api/Account/masked-info`;
+
+  // Forward request body if present; IDP often accepts empty object
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status }
+    );
+  }
+
+  const bodyJson: any = result.json;
+  // Unwrap if IDP returns envelope { success, data }
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if ((bodyJson as any).success === true) {
+      return NextResponse.json((bodyJson as any).data, { status: 200 });
+    }
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+
+  // Passthrough otherwise
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}