Handle refresh token errors (#3771)

* Handle refresh token errors

Author: unandyala

packages/commerce-sdk-react/CHANGELOG.md

@@ -2,6 +2,7 @@
 - Add HttpOnly session cookies for SLAS private client proxy [#3680](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3680)
 - use nightly release of isomorphic sdk that supports httponly cookies [#3754](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3754)
 - Handle refresh token flow for HttpOnly session cookies [#3759](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3759)
+- Handle missing refresh token for HttpOnly session cookies [#3771](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3771)
 
 ## v5.2.0-dev (Mar 20, 2026)
 

packages/commerce-sdk-react/src/auth/index.test.ts

@@ -1563,6 +1563,45 @@ describe('HttpOnly Session Cookies', () => {
         )
     })
 
+    test('ready skips refresh and goes straight to guest login on first visit (no cc-nx-exists)', async () => {
+        const auth = new Auth({...config, enableHttpOnlySessionCookies: true})
+        const loginGuestMock = helpers.loginGuestUser as jest.Mock
+        loginGuestMock.mockResolvedValueOnce(httpOnlyTokenResponse)
+
+        // First visit: no cc-nx-exists cookie, no refresh token, no cc-at-expires
+        // Should NOT attempt refresh — should go straight to loginGuestUser
+        await auth.ready()
+
+        expect(helpers.refreshAccessToken).not.toHaveBeenCalled()
+        expect(helpers.loginGuestUser).toHaveBeenCalledTimes(1)
+    })
+
+    test('ready attempts refresh when cc-nx-exists is set (returning visitor)', async () => {
+        const auth = new Auth({...config, enableHttpOnlySessionCookies: true})
+
+        // Simulate a returning visitor: expired access token + cc-nx-exists indicator
+        const expiredTime = Math.floor(Date.now() / 1000) - 100
+        // @ts-expect-error private method
+        auth.set('cc-at-expires', String(expiredTime))
+        // @ts-expect-error private method
+        auth.set('cc-nx-exists', '1')
+        // @ts-expect-error private method
+        auth.set('customer_type', 'guest')
+        // @ts-expect-error private method
+        auth.set('access_token', JWTExpired)
+
+        const refreshMock = helpers.refreshAccessToken as jest.Mock
+        refreshMock.mockResolvedValueOnce(httpOnlyTokenResponse)
+
+        await auth.ready()
+
+        // Should attempt refresh because cc-nx-exists indicates an HttpOnly refresh token exists
+        expect(helpers.refreshAccessToken).toHaveBeenCalledTimes(1)
+        expect(helpers.refreshAccessToken).toHaveBeenCalledWith(
+            expect.objectContaining({enableHttpOnlySessionCookies: true})
+        )
+    })
+
     test('ready triggers refresh when cc-at-expires cookie is expired', async () => {
         const auth = new Auth({...config, enableHttpOnlySessionCookies: true})
 

packages/commerce-sdk-react/src/auth/index.ts

@@ -140,6 +140,7 @@ type AuthDataKeys =
     | 'idp_refresh_token'
     | 'dnt'
     | 'cc-at-expires'
+    | 'cc-nx-exists'
 
 type AuthDataMap = Record<
     AuthDataKeys,
@@ -258,6 +259,10 @@ const DATA_MAP: AuthDataMap = {
     'cc-at-expires': {
         storageType: 'cookie',
         key: 'cc-at-expires'
+    },
+    'cc-nx-exists': {
+        storageType: 'cookie',
+        key: 'cc-nx-exists'
     }
 }
 
@@ -527,6 +532,15 @@ class Auth {
         return validTimeSeconds <= tokenAgeSeconds
     }
 
+    /**
+     * Returns whether a refresh token exists in an HttpOnly cookie. Since JavaScript cannot
+     * read HttpOnly cookies, we check the non-HttpOnly indicator cookie (cc-nx-exists) that
+     * is set alongside the refresh token with the same expiry.
+     */
+    private hasHttpOnlyRefreshToken(): boolean {
+        return this.enableHttpOnlySessionCookies && onClient() && this.get('cc-nx-exists') === '1'
+    }
+
     /**
      * Returns whether the access token is expired. When enableHttpOnlySessionCookies is true,
      * uses cc-at-expires cookie from store; otherwise decodes the JWT from getAccessToken().
@@ -748,12 +762,11 @@ class Auth {
         const refreshToken = refreshTokenRegistered || refreshTokenGuest
 
         // When HttpOnly session cookies are enabled on the client, the refresh token is in an
-        // HttpOnly cookie that JavaScript cannot read. We still attempt the refresh request —
-        // the SLAS private proxy injects the refresh token via the sfdc_refresh_token header.
-        const hasHttpOnlyRefreshToken =
-            !refreshToken && this.enableHttpOnlySessionCookies && onClient()
-
-        if (refreshToken || hasHttpOnlyRefreshToken) {
+        // HttpOnly cookie that JavaScript cannot read. We check the non-HttpOnly indicator
+        // cookie (cc-nx-exists) to avoid a wasted round-trip when the refresh token is absent.
+        // If cc-nx-exists is also missing (e.g. cleared by the user), the proxy layer will
+        // catch the missing refresh token and return a 401, falling through to guest login.
+        if (refreshToken || (!refreshToken && this.hasHttpOnlyRefreshToken())) {
             try {
                 const isGuest = this.get('customer_type') !== 'registered'
                 // Signal the proxy that this is a refresh token request so it can

packages/pwa-kit-runtime/CHANGELOG.md

@@ -5,6 +5,7 @@
 - Rename the configuration flag `disableHttpOnlySessionCookies` to `enableHttpOnlySessionCookies` [#3723](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3723)
 - updated package-lock [#3754](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3754)
 - Handle refresh token flow and consolidate `x-site-id` header usage for HttpOnly session cookies [#3759](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3759)
+- Handle missing refresh token for HttpOnly session cookies [#3771](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3771)
 
 ## v3.18.0-dev (Mar 20, 2026)
 - Add additional logging and error handling for SLAS error handling [#3750](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3750)

packages/pwa-kit-runtime/src/ssr/server/build-remote-server.js

@@ -96,34 +96,51 @@ export const isBinary = (headers) => {
     return isContentTypeBinary(headers)
 }
 
+/**
+ * Error thrown when the refresh token HttpOnly cookie is not found on the incoming request.
+ * Handled specifically in the SLAS proxy to return a 401 instead of forwarding to SLAS.
+ */
+export class RefreshTokenNotFoundError extends Error {
+    constructor(message) {
+        super(message)
+        this.name = 'RefreshTokenNotFoundError'
+    }
+}
+
 /**
  * Inject the refresh token from HttpOnly cookies as the sfdc_refresh_token header.
  * SLAS uses sfdc_refresh_token as a fallback when the refresh_token body parameter is
  * missing or empty (which is the case when HttpOnly session cookies are enabled, because
  * client-side JavaScript cannot read the HttpOnly refresh token cookie).
+ * @throws {RefreshTokenNotFoundError} If the refresh token cookie is missing.
  * @private
  */
 export const setRefreshTokenHeader = (proxyRequest, incomingRequest) => {
     const cookieHeader = incomingRequest.headers.cookie
-    if (!cookieHeader) return
+    if (!cookieHeader) {
+        throw new RefreshTokenNotFoundError(
+            'No cookies present on request. Cannot inject refresh token.'
+        )
+    }
 
     const cookies = cookie.parse(cookieHeader)
     const siteId = incomingRequest.headers[X_SITE_ID]
     if (!siteId) {
-        logger.warn(
+        throw new RefreshTokenNotFoundError(
             'x-site-id header is missing on SLAS token request. ' +
-                'Refresh token header injection skipped. ' +
-                'Ensure the x-site-id header is set in CommerceApiProvider headers.',
-            {namespace: 'setRefreshTokenHeader'}
+                'Cannot inject refresh token. ' +
+                'Ensure the x-site-id header is set in CommerceApiProvider headers.'
         )
-        return
     }
 
     // Try registered refresh token first, then guest
     const refreshToken = cookies[`cc-nx_${siteId}`] || cookies[`cc-nx-g_${siteId}`]
-    if (refreshToken) {
-        proxyRequest.setHeader('sfdc_refresh_token', refreshToken)
+    if (!refreshToken) {
+        throw new RefreshTokenNotFoundError(
+            'Refresh token cookie not found. Cannot proceed with refresh token flow.'
+        )
     }
+    proxyRequest.setHeader('sfdc_refresh_token', refreshToken)
 }
 
 /**
@@ -1097,6 +1114,18 @@ export const RemoteServerFactory = {
                             }
                         }
                     } catch (error) {
+                        if (error instanceof RefreshTokenNotFoundError) {
+                            logger.warn(error.message, {
+                                namespace: 'setRefreshTokenHeader'
+                            })
+                            if (!res.headersSent) {
+                                proxyRequest.destroy()
+                                res.status(401).json({
+                                    message: 'invalid refresh_token'
+                                })
+                            }
+                            return
+                        }
                         logger.error('Error in SLAS private proxy request handling', {
                             namespace: '_setupSlasPrivateClientProxy',
                             additionalProperties: {

packages/pwa-kit-runtime/src/ssr/server/build-remote-server.test.js

@@ -926,6 +926,111 @@ describe('HttpOnly session cookies', () => {
             const cookies = response.headers['set-cookie']
             expect(cookies.some((c) => c.includes('cc-at_testsite'))).toBe(true)
             expect(cookies.some((c) => c.includes('cc-nx-g_testsite'))).toBe(true)
+            // cc-nx-exists indicator cookie is set (non-HttpOnly)
+            expect(cookies.some((c) => c.includes('cc-nx-exists_testsite=1'))).toBe(true)
+        } finally {
+            mockSlasServerInstance.close()
+        }
+    })
+
+    test('returns 401 when refresh token cookie is missing on a refresh_token request', async () => {
+        process.env.MRT_ENABLE_HTTPONLY_SESSION_COOKIES = 'true'
+
+        const mockSlasServer = mockExpress()
+        // The mock server should NOT be hit — the proxy should short-circuit with 401
+        const slasHit = jest.fn()
+        mockSlasServer.post('/shopper/auth/v1/oauth2/token', (req, res) => {
+            slasHit()
+            res.status(200).json({access_token: 'should-not-reach'})
+        })
+
+        const mockSlasServerInstance = mockSlasServer.listen(0)
+        const mockSlasPort = mockSlasServerInstance.address().port
+
+        try {
+            const app = mockExpress()
+            const options = RemoteServerFactory._configure({
+                useSLASPrivateClient: true,
+                slasTarget: `http://localhost:${mockSlasPort}`,
+                mobify: {
+                    app: {
+                        commerceAPI: {
+                            parameters: {
+                                shortCode: 'test',
+                                organizationId: 'f_ecom_test',
+                                clientId: 'test-client-id',
+                                siteId: 'testsite'
+                            }
+                        }
+                    }
+                }
+            })
+
+            process.env.PWA_KIT_SLAS_CLIENT_SECRET = 'test-secret'
+
+            RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+            // Send refresh_token request with NO cookies at all
+            const response = await request(app)
+                .post('/mobify/slas/private/shopper/auth/v1/oauth2/token')
+                .set(X_SITE_ID, 'testsite')
+                .set(X_GRANT_TYPE, 'refresh_token')
+
+            expect(response.status).toBe(401)
+            expect(response.body.message).toBe('invalid refresh_token')
+            // SLAS server should NOT have been called
+            expect(slasHit).not.toHaveBeenCalled()
+        } finally {
+            mockSlasServerInstance.close()
+        }
+    })
+
+    test('returns 401 when refresh token cookie is missing but other cookies are present', async () => {
+        process.env.MRT_ENABLE_HTTPONLY_SESSION_COOKIES = 'true'
+
+        const mockSlasServer = mockExpress()
+        const slasHit = jest.fn()
+        mockSlasServer.post('/shopper/auth/v1/oauth2/token', (req, res) => {
+            slasHit()
+            res.status(200).json({access_token: 'should-not-reach'})
+        })
+
+        const mockSlasServerInstance = mockSlasServer.listen(0)
+        const mockSlasPort = mockSlasServerInstance.address().port
+
+        try {
+            const app = mockExpress()
+            const options = RemoteServerFactory._configure({
+                useSLASPrivateClient: true,
+                slasTarget: `http://localhost:${mockSlasPort}`,
+                mobify: {
+                    app: {
+                        commerceAPI: {
+                            parameters: {
+                                shortCode: 'test',
+                                organizationId: 'f_ecom_test',
+                                clientId: 'test-client-id',
+                                siteId: 'testsite'
+                            }
+                        }
+                    }
+                }
+            })
+
+            process.env.PWA_KIT_SLAS_CLIENT_SECRET = 'test-secret'
+
+            RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+            // Has cookies but NOT the refresh token cookie
+            const response = await request(app)
+                .post('/mobify/slas/private/shopper/auth/v1/oauth2/token')
+                .set('Cookie', 'cc-at-expires_testsite=12345')
+                .set(X_SITE_ID, 'testsite')
+                .set(X_GRANT_TYPE, 'refresh_token')
+
+            expect(response.status).toBe(401)
+            expect(response.body.message).toBe('invalid refresh_token')
+            expect(slasHit).not.toHaveBeenCalled()
         } finally {
             mockSlasServerInstance.close()
         }

packages/pwa-kit-runtime/src/ssr/server/process-token-response.js

@@ -198,6 +198,21 @@ export function setHttpOnlySessionCookies(responseBuffer, proxyRes, req, res, op
             })
         )
 
+        // Non-HttpOnly indicator so the client can check if a refresh token cookie exists
+        // (JavaScript cannot read HttpOnly cookies). Shares the same expiry as the refresh token.
+        res.append(
+            SET_COOKIE,
+            cookieAsString({
+                name: `cc-nx-exists_${site}`,
+                value: '1',
+                path: '/',
+                secure: true,
+                sameSite: 'lax',
+                httpOnly: false,
+                expires: refreshExpires
+            })
+        )
+
         // Delete the opposite refresh token cookie to mirror client-side behavior:
         // Login (guest → registered): delete guest cookie cc-nx-g
         // Logout (registered → guest): delete registered cookie cc-nx

packages/pwa-kit-runtime/src/ssr/server/process-token-response.test.js

@@ -188,6 +188,14 @@ describe('setHttpOnlySessionCookies', () => {
         expect(uidoCookie.value).toBe('ecom')
         expect(uidoCookie.httpOnly).toBeUndefined()
 
+        // cc-nx-exists: non-HttpOnly indicator that a refresh token cookie exists
+        const nxExistsCookie = parseCookie(
+            res.cookies.find((c) => c.includes('cc-nx-exists_testsite='))
+        )
+        expect(nxExistsCookie.value).toBe('1')
+        expect(nxExistsCookie.httpOnly).toBeUndefined()
+        expect(nxExistsCookie.secure).toBe(true)
+
         // Registered refresh cookie should be expired (deleted)
         const staleRegisteredCookie = parseCookie(
             res.cookies.find((c) => c.startsWith('cc-nx_testsite='))
@@ -237,6 +245,13 @@ describe('setHttpOnlySessionCookies', () => {
         const uidoCookie = parseCookie(res.cookies.find((c) => c.includes('uido_testsite=')))
         expect(uidoCookie.value).toBe('ecom')
 
+        // cc-nx-exists: non-HttpOnly indicator that a refresh token cookie exists
+        const nxExistsCookie = parseCookie(
+            res.cookies.find((c) => c.includes('cc-nx-exists_testsite='))
+        )
+        expect(nxExistsCookie.value).toBe('1')
+        expect(nxExistsCookie.httpOnly).toBeUndefined()
+
         // Guest refresh cookie should be expired (deleted)
         const staleGuestCookie = parseCookie(
             res.cookies.find((c) => c.startsWith('cc-nx-g_testsite='))
@@ -292,6 +307,8 @@ describe('setHttpOnlySessionCookies', () => {
         const body = JSON.parse(result.toString('utf8'))
 
         expect(res.cookies).toHaveLength(0)
+        // cc-nx-exists should NOT be set when there is no refresh token
+        expect(res.cookies.find((c) => c.includes('cc-nx-exists'))).toBeUndefined()
         expect(body.other_field).toBe('value')
     })