Merge pull request #3411 from SalesforceCommerceCloud/feature/slas-proxy-extensibility

Adds support for SLAS proxy req/res callbacks

Author: clavery

packages/pwa-kit-runtime/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## v3.14.0-dev (Sep 26, 2025)
 - Replace aws-serverless-express with @h4ad/serverless-adapter [#3325](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3325)
+- Add extensibility hooks for SLAS private client proxy with `onSLASPrivateProxyReq` and `onSLASPrivateProxyRes` callbacks [#3411](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3411)
 
 ## v3.13.0 (Sep 25, 2025)
 

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

@@ -157,7 +157,19 @@ export const RemoteServerFactory = {
             // To allow additional SLAS endpoints, users can override this value in
             // their project's ssr.js.
             applySLASPrivateClientToEndpoints:
-                /\/oauth2\/(token|passwordless\/(login|token)|password\/(reset|action))/
+                /\/oauth2\/(token|passwordless\/(login|token)|password\/(reset|action))/,
+
+            // Custom callback to modify the SLAS private client proxy request. This callback is invoked
+            // after the built-in proxy request handling. Users can provide additional
+            // request modifications (e.g., custom headers).
+            // Signature: (proxyRequest, incomingRequest, res) => void
+            onSLASPrivateProxyReq: undefined,
+
+            // Custom callback to modify the SLAS private client proxy response. This callback is invoked
+            // after the built-in proxy response handling. Users can modify or replace
+            // the response buffer.
+            // Signature: (responseBuffer, proxyRes, req, res) => Buffer
+            onSLASPrivateProxyRes: undefined
         }
 
         options = Object.assign({}, defaults, options)
@@ -930,8 +942,23 @@ export const RemoteServerFactory = {
                         // purpose so we don't want to overwrite the header for those calls.
                         proxyRequest.setHeader('Authorization', `Basic ${encodedSlasCredentials}`)
                     }
+
+                    // Allow users to apply additional custom modifications to the proxy request
+                    if (typeof options.onSLASPrivateProxyReq === 'function') {
+                        try {
+                            options.onSLASPrivateProxyReq(proxyRequest, incomingRequest, res)
+                        } catch (error) {
+                            logger.error('Error in custom onSLASPrivateProxyReq callback', {
+                                namespace: '_setupSlasPrivateClientProxy',
+                                additionalProperties: {
+                                    error: error
+                                }
+                            })
+                        }
+                    }
                 },
                 onProxyRes: responseInterceptor((responseBuffer, proxyRes, req, res) => {
+                    let workingBuffer = responseBuffer
                     try {
                         // If the passwordless login endpoint returns a 404, which corresponds to a user
                         // email not being found, we mask it with a 200 OK response so that it is not
@@ -946,15 +973,43 @@ export const RemoteServerFactory = {
 
                             // When a /passwordless/login endpoint response returns 200, it has no body
                             // so we return an empty body here to match an actual 200 response.
-                            return Buffer.from('', 'utf8')
+                            workingBuffer = Buffer.from('', 'utf8')
                         }
-                        return responseBuffer
+
+                        // Allow users to apply additional custom modifications to the proxy response
+                        if (typeof options.onSLASPrivateProxyRes === 'function') {
+                            try {
+                                const customBuffer = options.onSLASPrivateProxyRes(
+                                    workingBuffer,
+                                    proxyRes,
+                                    req,
+                                    res
+                                )
+                                // Only use the custom buffer if it was returned
+                                if (customBuffer !== undefined) {
+                                    workingBuffer = customBuffer
+                                }
+                            } catch (error) {
+                                logger.error(
+                                    'Error in custom onSLASPrivateProxyRes callback',
+                                    /* istanbul ignore next */
+                                    {
+                                        namespace: '_setupSlasPrivateClientProxy',
+                                        additionalProperties: {
+                                            error: error
+                                        }
+                                    }
+                                )
+                            }
+                        }
+
+                        return workingBuffer
                     } catch (error) {
                         console.error(
                             'There is an error processing the response from SLAS. Returning original response.',
                             error
                         )
-                        return responseBuffer
+                        return workingBuffer
                     }
                 })
             })
@@ -1319,6 +1374,16 @@ export const RemoteServerFactory = {
      * @param {Boolean} [options.allowCookies] - This boolean value indicates
      * whether or not we strip cookies from requests and block setting of cookies. Defaults
      * to 'false'.
+     * @param {Boolean} [options.useSLASPrivateClient=false] - Enable the SLAS private client
+     * proxy handler. Requires PWA_KIT_SLAS_CLIENT_SECRET environment variable.
+     * @param {RegExp} [options.applySLASPrivateClientToEndpoints] - A regex pattern to match
+     * SLAS endpoints where the Authorization header should be injected.
+     * @param {function} [options.onSLASPrivateProxyReq] - Custom callback to modify SLAS private client
+     * proxy requests. Called after built-in request handling. Signature: (proxyRequest, incomingRequest, res) => void.
+     * Use this to add custom headers or modify the proxy request.
+     * @param {function} [options.onSLASPrivateProxyRes] - Custom callback to modify SLAS private client
+     * proxy responses. Called after built-in response handling. Signature: (responseBuffer, proxyRes, req, res) => Buffer.
+     * Should return the modified buffer or undefined to use the existing buffer.
      */
     createHandler(options, customizeApp) {
         process.on('unhandledRejection', catchAndLog)

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

@@ -156,3 +156,190 @@ describe('isBinary function', () => {
         expect(isBinary(headers)).toBe(false)
     })
 })
+
+describe('SLAS private proxy', () => {
+    let request
+    let mockExpress
+
+    beforeEach(() => {
+        // Mock express application
+        mockExpress = require('express')
+        request = require('supertest')
+    })
+
+    afterEach(() => {
+        // Clean up environment variables
+        delete process.env.PWA_KIT_SLAS_CLIENT_SECRET
+    })
+
+    test('returns 404 when useSLASPrivateClient is false', async () => {
+        const app = mockExpress()
+        const options = {
+            useSLASPrivateClient: false,
+            mobify: {
+                app: {
+                    commerceAPI: {
+                        parameters: {
+                            shortCode: 'test',
+                            clientId: 'test-client-id'
+                        }
+                    }
+                }
+            }
+        }
+
+        RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+        // Attempt to access the SLAS private proxy path
+        const response = await request(app).get('/mobify/slas/private/shopper/auth/v1/oauth2/token')
+
+        expect(response.status).toBe(404)
+    })
+
+    test('returns 501 when useSLASPrivateClient is true but no secret is set', async () => {
+        const app = mockExpress()
+        const options = RemoteServerFactory._configure({
+            useSLASPrivateClient: true,
+            mobify: {
+                app: {
+                    commerceAPI: {
+                        parameters: {
+                            shortCode: 'test',
+                            organizationId: 'f_ecom_test',
+                            clientId: 'test-client-id'
+                        }
+                    }
+                }
+            }
+        })
+
+        RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+        const response = await request(app).get('/mobify/slas/private/shopper/auth/v1/oauth2/token')
+
+        expect(response.status).toBe(501)
+    })
+
+    test('returns 403 for non-SLAS auth paths', async () => {
+        const app = mockExpress()
+        const options = RemoteServerFactory._configure({
+            useSLASPrivateClient: true,
+            mobify: {
+                app: {
+                    commerceAPI: {
+                        parameters: {
+                            shortCode: 'test',
+                            organizationId: 'f_ecom_test',
+                            clientId: 'test-client-id'
+                        }
+                    }
+                }
+            }
+        })
+
+        process.env.PWA_KIT_SLAS_CLIENT_SECRET = 'test-secret'
+
+        RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+        const response = await request(app).get('/mobify/slas/private/shopper/products/v1')
+
+        expect(response.status).toBe(403)
+    })
+
+    test('returns 403 for trusted-system paths', async () => {
+        const app = mockExpress()
+        const options = RemoteServerFactory._configure({
+            useSLASPrivateClient: true,
+            mobify: {
+                app: {
+                    commerceAPI: {
+                        parameters: {
+                            shortCode: 'test',
+                            organizationId: 'f_ecom_test',
+                            clientId: 'test-client-id'
+                        }
+                    }
+                }
+            }
+        })
+
+        process.env.PWA_KIT_SLAS_CLIENT_SECRET = 'test-secret'
+
+        RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+        const response = await request(app).post(
+            '/mobify/slas/private/shopper/auth/v1/oauth2/trusted-system/token'
+        )
+
+        expect(response.status).toBe(403)
+    })
+
+    test('invokes onSLASPrivateProxyReq callback and onSLASPrivateProxyRes callback', async () => {
+        // Create a mock SLAS endpoint for the http-proxy to consume
+        const mockSlasServer = mockExpress()
+        mockSlasServer.post('/shopper/auth/v1/oauth2/token', (req, res) => {
+            // Reflect the custom header back in the response to verify it was set
+            res.status(200).json({
+                access_token: 'mock-token',
+                reflected_header: req.headers['x-custom-request-header']
+            })
+        })
+
+        const mockSlasServerInstance = mockSlasServer.listen(0)
+        const mockSlasPort = mockSlasServerInstance.address().port
+
+        try {
+            const onSLASPrivateProxyReqMock = jest.fn((proxyRequest) => {
+                proxyRequest.setHeader('X-Custom-Request-Header', 'CustomRequestValue')
+            })
+
+            const onSLASPrivateProxyResMock = jest.fn((responseBuffer, proxyRes, req, res) => {
+                // Add a custom response header
+                res.setHeader('X-Custom-Response-Header', 'CustomResponseValue')
+                return responseBuffer
+            })
+
+            const app = mockExpress()
+            const options = RemoteServerFactory._configure({
+                useSLASPrivateClient: true,
+                slasTarget: `http://localhost:${mockSlasPort}`,
+                onSLASPrivateProxyReq: onSLASPrivateProxyReqMock,
+                onSLASPrivateProxyRes: onSLASPrivateProxyResMock,
+                mobify: {
+                    app: {
+                        commerceAPI: {
+                            parameters: {
+                                shortCode: 'test',
+                                organizationId: 'f_ecom_test',
+                                clientId: 'test-client-id'
+                            }
+                        }
+                    }
+                }
+            })
+
+            process.env.PWA_KIT_SLAS_CLIENT_SECRET = 'test-secret'
+
+            RemoteServerFactory._setupSlasPrivateClientProxy(app, options)
+
+            const response = await request(app).post(
+                '/mobify/slas/private/shopper/auth/v1/oauth2/token'
+            )
+
+            // Verify the request was successful
+            expect(response.status).toBe(200)
+
+            // Verify the callbacks were invoked
+            expect(onSLASPrivateProxyReqMock).toHaveBeenCalled()
+            expect(onSLASPrivateProxyResMock).toHaveBeenCalled()
+
+            // Verify the custom request header was added (reflected back in response)
+            expect(response.body.reflected_header).toBe('CustomRequestValue')
+
+            // Verify the custom response header was added
+            expect(response.headers['x-custom-response-header']).toBe('CustomResponseValue')
+        } finally {
+            mockSlasServerInstance.close()
+        }
+    })
+})