Add HttpOnly session cookies for SLAS private client proxy

When MRT_DISABLE_HTTPONLY_SESSION_COOKIES is 'false', token responses from
SLAS are intercepted: access_token, refresh_token, and idp_access_token are
set as HttpOnly cookies and stripped from the response body. The client
receives access_token_expires_at for expiry checks without needing the JWT.

Server-side (pwa-kit-runtime):
- applyHttpOnlySessionCookies() intercepts token responses, sets HttpOnly
  cookies with siteId suffix, and strips tokens from body
- applyProxyRequestAuthHeader() reads access token from HttpOnly cookie and
  sets Authorization header for SCAPI proxy requests
- isScapiDomain() utility for identifying Commerce API domains
- Configurable tokenResponseEndpoints and slasEndpointsRequiringAccessToken
  regexes for controlling which endpoints are processed

Client-side (commerce-sdk-react):
- useHttpOnlySessionCookies flag on Auth and CommerceApiProvider
- isAccessTokenExpired() uses access_token_expires_at when HttpOnly enabled
- handleTokenResponse() skips storing tokens in localStorage when HttpOnly
- Provider ensures fetch credentials allow cookies to be sent

Note: TAOB (Trusted Agent on Behalf) and refresh token flows with HttpOnly
cookies will be handled in follow-up work.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: unandyala

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

@@ -1502,3 +1502,68 @@ describe('hybridAuthEnabled property toggles clearECOMSession', () => {
         expect(auth.get('dwsid')).toBe('test-dwsid-value')
     })
 })
+
+describe('HttpOnly Session Cookies', () => {
+    const expiresAtFuture = Math.floor(Date.now() / 1000) + 3600
+
+    const httpOnlyTokenResponse: ShopperLoginTypes.TokenResponse = {
+        ...TOKEN_RESPONSE,
+        // When HttpOnly cookies are enabled, the proxy strips tokens from the body
+        // and adds access_token_expires_at for client-side expiry checks
+        access_token_expires_at: expiresAtFuture
+    }
+
+    beforeEach(() => {
+        jest.clearAllMocks()
+    })
+
+    test('loginGuestUser stores access_token_expires_at but not tokens', async () => {
+        const auth = new Auth({...config, useHttpOnlySessionCookies: true})
+        const loginGuestMock = helpers.loginGuestUser as jest.Mock
+        loginGuestMock.mockResolvedValueOnce(httpOnlyTokenResponse)
+
+        await auth.loginGuestUser()
+
+        // access_token_expires_at should be stored for client-side expiry checks
+        expect(auth.get('access_token_expires_at')).toBe(String(expiresAtFuture))
+        // Tokens should NOT be stored in localStorage (they're in HttpOnly cookies)
+        expect(auth.get('access_token')).toBeFalsy()
+        expect(auth.get('refresh_token_guest')).toBeFalsy()
+        // Common fields should still be stored
+        expect(auth.get('customer_id')).toBe(TOKEN_RESPONSE.customer_id)
+        expect(auth.get('usid')).toBe(TOKEN_RESPONSE.usid)
+    })
+
+    test('ready re-uses data when access_token_expires_at is still valid', async () => {
+        const auth = new Auth({...config, useHttpOnlySessionCookies: true})
+        const loginGuestMock = helpers.loginGuestUser as jest.Mock
+        loginGuestMock.mockResolvedValueOnce(httpOnlyTokenResponse)
+
+        // First call: triggers loginGuestUser
+        await auth.ready()
+        expect(helpers.loginGuestUser).toHaveBeenCalledTimes(1)
+
+        // Second call: access_token_expires_at is in the future, so it should re-use data
+        await auth.ready()
+        expect(helpers.loginGuestUser).toHaveBeenCalledTimes(1) // Not called again
+    })
+
+    test('ready triggers refresh when access_token_expires_at is expired', async () => {
+        const auth = new Auth({...config, useHttpOnlySessionCookies: true})
+
+        // Simulate a previous login that left behind stored data with an expired token
+        const expiredTime = Math.floor(Date.now() / 1000) - 100
+        // @ts-expect-error private method
+        auth.set('access_token_expires_at', String(expiredTime))
+        // @ts-expect-error private method
+        auth.set('refresh_token_guest', 'refresh_token')
+        // @ts-expect-error private method
+        auth.set('customer_type', 'guest')
+        // Set a valid JWT so parseSlasJWT works during the refresh flow
+        // @ts-expect-error private method
+        auth.set('access_token', JWTExpired)
+
+        await auth.ready()
+        expect(helpers.refreshAccessToken).toHaveBeenCalled()
+    })
+})

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

@@ -54,6 +54,8 @@ interface AuthConfig extends ApiClientConfigParams {
     refreshTokenRegisteredCookieTTL?: number
     refreshTokenGuestCookieTTL?: number
     hybridAuthEnabled?: boolean
+    /** When true, token response may be sanitized (tokens in HttpOnly cookies); only set non-token fields and use access_token_expires_at for expiry. */
+    useHttpOnlySessionCookies?: boolean
 }
 
 interface JWTHeaders {
@@ -136,6 +138,7 @@ type AuthDataKeys =
     | 'uido'
     | 'idp_refresh_token'
     | 'dnt'
+    | 'access_token_expires_at'
 
 type AuthDataMap = Record<
     AuthDataKeys,
@@ -250,6 +253,10 @@ const DATA_MAP: AuthDataMap = {
     uido: {
         storageType: 'local',
         key: 'uido'
+    },
+    access_token_expires_at: {
+        storageType: 'local',
+        key: 'access_token_expires_at'
     }
 }
 
@@ -284,6 +291,7 @@ class Auth {
         | undefined
 
     private hybridAuthEnabled: boolean
+    private useHttpOnlySessionCookies: boolean
 
     constructor(config: AuthConfig) {
         // Special proxy endpoint for injecting SLAS private client secret.
@@ -380,6 +388,7 @@ class Auth {
         this.passwordlessLoginCallbackURI = config.passwordlessLoginCallbackURI || ''
 
         this.hybridAuthEnabled = config.hybridAuthEnabled || false
+        this.useHttpOnlySessionCookies = config.useHttpOnlySessionCookies ?? false
     }
 
     get(name: AuthDataKeys) {
@@ -517,6 +526,23 @@ class Auth {
         return validTimeSeconds <= tokenAgeSeconds
     }
 
+    /**
+     * Returns whether the access token is expired. When useHttpOnlySessionCookies is true,
+     * uses access_token_expires_at from store; otherwise decodes the JWT from getAccessToken().
+     */
+    private isAccessTokenExpired(): boolean {
+        if (this.useHttpOnlySessionCookies) {
+            const expiresAt = this.get('access_token_expires_at')
+            if (expiresAt == null || expiresAt === '') return true
+            const expiresAtSec = Number(expiresAt)
+            if (Number.isNaN(expiresAtSec)) return true
+            const bufferSeconds = 60
+            return Date.now() / 1000 >= expiresAtSec - bufferSeconds
+        }
+        const token = this.getAccessToken()
+        return !token || this.isTokenExpired(token)
+    }
+
     /**
      * Returns the SLAS access token or an empty string if the access token
      * is not found in local store or if SFRA wants PWA to trigger refresh token login.
@@ -680,33 +706,43 @@ class Auth {
     private handleTokenResponse(res: TokenResponse, isGuest: boolean) {
         // Delete the SFRA auth token cookie if it exists
         this.clearSFRAAuthToken()
-        this.set('access_token', res.access_token)
+
         this.set('customer_id', res.customer_id)
         this.set('enc_user_id', res.enc_user_id)
         this.set('expires_in', `${res.expires_in}`)
         this.set('id_token', res.id_token)
-        this.set('idp_access_token', res.idp_access_token)
         this.set('token_type', res.token_type)
         this.set('customer_type', isGuest ? 'guest' : 'registered')
 
-        const refreshTokenKey = isGuest ? 'refresh_token_guest' : 'refresh_token_registered'
         const refreshTokenTTLValue = this.getRefreshTokenCookieTTLValue(
             res.refresh_token_expires_in,
             isGuest
         )
-        if (res.access_token) {
-            const {uido} = this.parseSlasJWT(res.access_token)
-            this.set('uido', uido)
-        }
-        const expiresDate = this.convertSecondsToDate(refreshTokenTTLValue)
         this.set('refresh_token_expires_in', refreshTokenTTLValue.toString())
-        this.set(refreshTokenKey, res.refresh_token, {
-            expires: expiresDate
-        })
+        const expiresDate = this.convertSecondsToDate(refreshTokenTTLValue)
+        this.set('usid', res.usid ?? '', {expires: expiresDate})
 
-        this.set('usid', res.usid, {
-            expires: expiresDate
-        })
+        if (this.useHttpOnlySessionCookies) {
+            const uidoFromCookie = this.stores['cookie'].get('uido')
+            if (uidoFromCookie) this.set('uido', uidoFromCookie)
+        } else {
+            this.set('access_token', res.access_token)
+            this.set('idp_access_token', res.idp_access_token)
+            if (res.access_token) {
+                const {uido} = this.parseSlasJWT(res.access_token)
+                this.set('uido', uido)
+            }
+            const refreshTokenKey = isGuest ? 'refresh_token_guest' : 'refresh_token_registered'
+            this.set(refreshTokenKey, res.refresh_token, {expires: expiresDate})
+        }
+        if (
+            res &&
+            typeof res === 'object' &&
+            'access_token_expires_at' in res &&
+            res.access_token_expires_at != null
+        ) {
+            this.set('access_token_expires_at', String(res.access_token_expires_at))
+        }
     }
 
     async refreshAccessToken() {
@@ -747,7 +783,7 @@ class Auth {
 
         // refresh flow for TAOB
         const accessToken = this.getAccessToken()
-        if (accessToken && this.isTokenExpired(accessToken)) {
+        if (this.isAccessTokenExpired()) {
             try {
                 const {isGuest, usid, loginId, isAgent} = this.parseSlasJWT(accessToken)
                 if (isAgent) {
@@ -888,8 +924,7 @@ class Auth {
             return await this.pendingToken
         }
 
-        const accessToken = this.getAccessToken()
-        if (accessToken && !this.isTokenExpired(accessToken)) {
+        if (!this.isAccessTokenExpired()) {
             return this.data
         }
 

packages/commerce-sdk-react/src/provider.test.tsx

@@ -89,4 +89,64 @@ describe('provider', () => {
         const authInstance = (Auth as jest.Mock).mock.instances[0]
         expect(authInstance.ready).toHaveBeenCalledTimes(1)
     })
+
+    test('passes useHttpOnlySessionCookies to Auth constructor', () => {
+        renderWithProviders(<h1>HttpOnly cookies enabled!</h1>, {
+            useHttpOnlySessionCookies: true
+        })
+        expect(screen.getByText('HttpOnly cookies enabled!')).toBeInTheDocument()
+        expect(Auth).toHaveBeenCalledTimes(1)
+        expect(Auth).toHaveBeenCalledWith(
+            expect.objectContaining({
+                useHttpOnlySessionCookies: true
+            })
+        )
+    })
+
+    test('defaults fetchOptions.credentials to same-origin when useHttpOnlySessionCookies is true', () => {
+        renderWithProviders(<h1>test</h1>, {
+            useHttpOnlySessionCookies: true
+        })
+        expect(Auth).toHaveBeenCalledWith(
+            expect.objectContaining({
+                fetchOptions: expect.objectContaining({credentials: 'same-origin'})
+            })
+        )
+    })
+
+    test('overrides fetchOptions.credentials from omit to same-origin when useHttpOnlySessionCookies is true', () => {
+        renderWithProviders(<h1>test</h1>, {
+            useHttpOnlySessionCookies: true,
+            fetchOptions: {credentials: 'omit'}
+        })
+        expect(Auth).toHaveBeenCalledWith(
+            expect.objectContaining({
+                fetchOptions: expect.objectContaining({credentials: 'same-origin'})
+            })
+        )
+    })
+
+    test('keeps fetchOptions.credentials as include when useHttpOnlySessionCookies is true', () => {
+        renderWithProviders(<h1>test</h1>, {
+            useHttpOnlySessionCookies: true,
+            fetchOptions: {credentials: 'include'}
+        })
+        expect(Auth).toHaveBeenCalledWith(
+            expect.objectContaining({
+                fetchOptions: expect.objectContaining({credentials: 'include'})
+            })
+        )
+    })
+
+    test('does not modify fetchOptions.credentials when useHttpOnlySessionCookies is false', () => {
+        renderWithProviders(<h1>test</h1>, {
+            useHttpOnlySessionCookies: false,
+            fetchOptions: {credentials: 'omit'}
+        })
+        expect(Auth).toHaveBeenCalledWith(
+            expect.objectContaining({
+                fetchOptions: expect.objectContaining({credentials: 'omit'})
+            })
+        )
+    })
 })

packages/commerce-sdk-react/src/provider.tsx

@@ -48,6 +48,8 @@ export interface CommerceApiProviderProps extends ApiClientConfigParams {
     apiClients?: ApiClients
     disableAuthInit?: boolean
     hybridAuthEnabled?: boolean
+    /** When true, proxy returns tokens in HttpOnly cookies. */
+    useHttpOnlySessionCookies?: boolean
 }
 
 /**
@@ -145,12 +147,20 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         refreshTokenGuestCookieTTL,
         apiClients,
         disableAuthInit = false,
-        hybridAuthEnabled = false
+        hybridAuthEnabled = false,
+        useHttpOnlySessionCookies = false
     } = props
 
     // Set the logger based on provided configuration, or default to the console object if no logger is provided
     const configLogger = logger || console
 
+    // When HttpOnly cookies are enabled, ensure fetch credentials allow cookies to be sent.
+    // Override 'omit' or unset to 'same-origin'; keep 'same-origin' or 'include' as-is.
+    const effectiveFetchOptions =
+        useHttpOnlySessionCookies && (!fetchOptions?.credentials || fetchOptions.credentials === 'omit')
+            ? {...fetchOptions, credentials: 'same-origin' as RequestCredentials}
+            : fetchOptions
+
     const auth = useMemo(() => {
         return new Auth({
             clientId,
@@ -160,7 +170,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             proxy,
             redirectURI,
             headers,
-            fetchOptions,
+            fetchOptions: effectiveFetchOptions,
             fetchedToken,
             enablePWAKitPrivateClient,
             privateClientProxyEndpoint,
@@ -171,7 +181,8 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             passwordlessLoginCallbackURI,
             refreshTokenRegisteredCookieTTL,
             refreshTokenGuestCookieTTL,
-            hybridAuthEnabled
+            hybridAuthEnabled,
+            useHttpOnlySessionCookies
         })
     }, [
         clientId,
@@ -181,7 +192,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         proxy,
         redirectURI,
         headers,
-        fetchOptions,
+        effectiveFetchOptions,
         fetchedToken,
         enablePWAKitPrivateClient,
         privateClientProxyEndpoint,
@@ -193,7 +204,8 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         refreshTokenRegisteredCookieTTL,
         refreshTokenGuestCookieTTL,
         apiClients,
-        hybridAuthEnabled
+        hybridAuthEnabled,
+        useHttpOnlySessionCookies
     ])
 
     const dwsid = auth.get(DWSID_COOKIE_NAME)
@@ -212,7 +224,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
             throwOnBadResponse: true,
             fetchOptions: {
                 ...options.fetchOptions,
-                ...fetchOptions
+                ...effectiveFetchOptions
             }
         }
     }
@@ -252,7 +264,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
                 currency
             },
             throwOnBadResponse: true,
-            fetchOptions
+            fetchOptions: effectiveFetchOptions
         }
 
         return {
@@ -279,7 +291,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         shortCode,
         siteId,
         proxy,
-        fetchOptions,
+        effectiveFetchOptions,
         locale,
         currency,
         headers?.['correlation-id'],

packages/pwa-kit-dev/bin/pwa-kit-dev.js

@@ -257,12 +257,12 @@ const main = async () => {
             // This mimics how MRT sets the system environment variable
             const config = getConfig() || {}
             const disableHttpOnlySessionCookies =
-                config.ssrParameters?.disableHttpOnlySessionCookies || true
+                config.ssrParameters?.disableHttpOnlySessionCookies ?? true
             execSync(`${babelNode} ${inspect ? '--inspect' : ''} ${babelArgs} ${entrypoint}`, {
                 env: {
                     ...process.env,
                     ...(noHMR ? {HMR: 'false'} : {}),
-                    MRT_DISABLE_HTTPONLY_SESSION_COOKIES: disableHttpOnlySessionCookies
+                    MRT_DISABLE_HTTPONLY_SESSION_COOKIES: String(disableHttpOnlySessionCookies)
                 }
             })
         })

packages/pwa-kit-runtime/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## v3.17.0-dev
 - Add Node 24 support. Migrate deprecated Node.js `url.parse()` and `url.format()` to the WHATWG `URL` [#3652](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3652)
+- Add HttpOnly session cookies for SLAS private client proxy: when `MRT_DISABLE_HTTPONLY_SESSION_COOKIES` is not `'true'`, token responses are intercepted and session tokens are set as HttpOnly cookies; token fields (access_token, idp_access_token, refresh_token) are stripped from the response body. The client continues to get expires_in and refresh_token_expires_in from the response body. This runs before `onSLASPrivateProxyRes`; custom callbacks receive the sanitized response and should read from response headers (e.g. Set-Cookie) rather than the body when using HttpOnly session cookies. An error is thrown if `siteId` is missing in commerce API parameters.
 
 ## v3.16.0 (Feb 12, 2026)
 - Migrate AWS SDK from v2 to v3 [#3566](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3566)