feat: CATALYST-1664 add graphql proxy in middleware

Author: chanceaclark

.changeset/foo-bar-baz.md

@@ -0,0 +1,118 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Add GraphQL proxy middleware to enable client-side GraphQL requests through the storefront. This middleware proxies authenticated GraphQL requests from allowed clients (such as checkout-sdk-js) to the BigCommerce Storefront API, automatically handling customer authentication and channel resolution.
+
+## Migration
+
+### Step 1
+
+Create a new file `core/middlewares/with-graphql-proxy.ts`:
+
+```ts
+import { NextResponse, URLPattern } from 'next/server';
+
+import { auth } from '~/auth';
+import { getChannelIdFromLocale } from '~/channels.config';
+import { client } from '~/client';
+
+import { type MiddlewareFactory } from './compose-middlewares';
+
+const ALLOWED_REQUESTERS = ['checkout-sdk-js'];
+const graphqlPathPattern = new URLPattern({ pathname: '/graphql' });
+
+export const withGraphqlProxy: MiddlewareFactory = (next) => {
+  return async (request, event) => {
+    // Only handle /graphql path
+    if (!graphqlPathPattern.test(request.nextUrl.toString())) {
+      return next(request, event);
+    }
+
+    const requester = request.headers.get('x-catalyst-graphql-proxy-requester');
+
+    // Validate required header
+    if (!requester || !ALLOWED_REQUESTERS.includes(requester)) {
+      return next(request, event);
+    }
+
+    // Only handle POST requests
+    if (request.method !== 'POST') {
+      return new NextResponse('Method not allowed', { status: 405 });
+    }
+
+    // Wrap in auth to get customer access token
+    return auth(async (req) => {
+      try {
+        // Parse incoming GraphQL request body
+        const body = await req.json();
+        const { query, variables } = body;
+
+        if (!query) {
+          return NextResponse.json({ error: 'Missing query' }, { status: 400 });
+        }
+
+        // Resolve channel ID from locale header (set by withChannelId middleware)
+        const locale = req.headers.get('x-bc-locale') ?? '';
+        const channelId = getChannelIdFromLocale(locale) ?? undefined;
+
+        // Get customer access token if authenticated
+        const customerAccessToken = req.auth?.user?.customerAccessToken;
+
+        // Forward IP address for personalization
+        const ipAddress = req.headers.get('X-Forwarded-For');
+
+        // Proxy the request using the existing client
+        const response = await client.fetch({
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          document: query,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          variables,
+          customerAccessToken,
+          channelId,
+          fetchOptions: {
+            next: { revalidate: 0 }, // Don't cache, but avoid triggering headers() in beforeRequest
+            headers: ipAddress
+              ? { 'X-Forwarded-For': ipAddress, 'True-Client-IP': ipAddress }
+              : undefined,
+          },
+        });
+
+        return NextResponse.json(response);
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(error);
+
+        return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+      }
+      // @ts-expect-error The return of `auth(() => ...) is overloaded to expect `return next(req, event)` to be the valid middleware type
+      // however we are returning NextResponse directly here because we want to proxy GraphQL requests. This is fine to ignore.
+    })(request, event);
+  };
+};
+```
+
+### Step 2
+
+Update `core/middleware.ts` to include the new middleware in the composition chain:
+
+```diff
+  import { composeMiddlewares } from './middlewares/compose-middlewares';
+  import { withAnalyticsCookies } from './middlewares/with-analytics-cookies';
+  import { withAuth } from './middlewares/with-auth';
+  import { withChannelId } from './middlewares/with-channel-id';
++ import { withGraphqlProxy } from './middlewares/with-graphql-proxy';
+  import { withIntl } from './middlewares/with-intl';
+  import { withRoutes } from './middlewares/with-routes';
+
+  export const middleware = composeMiddlewares(
+    withAuth,
+    withIntl,
+    withAnalyticsCookies,
+    withChannelId,
++   withGraphqlProxy,
+    withRoutes,
+  );
+```
+
+The `withGraphqlProxy` middleware should be placed after `withChannelId` (to access the resolved locale) and before `withRoutes` in the middleware chain.

core/middleware.ts

@@ -2,6 +2,7 @@ import { composeMiddlewares } from './middlewares/compose-middlewares';
 import { withAnalyticsCookies } from './middlewares/with-analytics-cookies';
 import { withAuth } from './middlewares/with-auth';
 import { withChannelId } from './middlewares/with-channel-id';
+import { withGraphqlProxy } from './middlewares/with-graphql-proxy';
 import { withIntl } from './middlewares/with-intl';
 import { withRoutes } from './middlewares/with-routes';
 
@@ -10,6 +11,7 @@ export const middleware = composeMiddlewares(
   withIntl,
   withAnalyticsCookies,
   withChannelId,
+  withGraphqlProxy,
   withRoutes,
 );
 

core/middlewares/with-graphql-proxy.ts

@@ -0,0 +1,79 @@
+import { NextResponse, URLPattern } from 'next/server';
+
+import { auth } from '~/auth';
+import { getChannelIdFromLocale } from '~/channels.config';
+import { client } from '~/client';
+
+import { type MiddlewareFactory } from './compose-middlewares';
+
+const ALLOWED_REQUESTERS = ['checkout-sdk-js'];
+const graphqlPathPattern = new URLPattern({ pathname: '/graphql' });
+
+export const withGraphqlProxy: MiddlewareFactory = (next) => {
+  return async (request, event) => {
+    // Only handle /graphql path
+    if (!graphqlPathPattern.test(request.nextUrl.toString())) {
+      return next(request, event);
+    }
+
+    const requester = request.headers.get('x-catalyst-graphql-proxy-requester');
+
+    // Validate required header
+    if (!requester || !ALLOWED_REQUESTERS.includes(requester)) {
+      return next(request, event);
+    }
+
+    // Only handle POST requests
+    if (request.method !== 'POST') {
+      return new NextResponse('Method not allowed', { status: 405 });
+    }
+
+    // Wrap in auth to get customer access token
+    return auth(async (req) => {
+      try {
+        // Parse incoming GraphQL request body
+        const body = await req.json();
+        const { query, variables } = body;
+
+        if (!query) {
+          return NextResponse.json({ error: 'Missing query' }, { status: 400 });
+        }
+
+        // Resolve channel ID from locale header (set by withChannelId middleware)
+        const locale = req.headers.get('x-bc-locale') ?? '';
+        const channelId = getChannelIdFromLocale(locale) ?? undefined;
+
+        // Get customer access token if authenticated
+        const customerAccessToken = req.auth?.user?.customerAccessToken;
+
+        // Forward IP address for personalization
+        const ipAddress = req.headers.get('X-Forwarded-For');
+
+        // Proxy the request using the existing client
+        const response = await client.fetch({
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          document: query,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          variables,
+          customerAccessToken,
+          channelId,
+          fetchOptions: {
+            next: { revalidate: 0 }, // Don't cache, but avoid triggering headers() in beforeRequest
+            headers: ipAddress
+              ? { 'X-Forwarded-For': ipAddress, 'True-Client-IP': ipAddress }
+              : undefined,
+          },
+        });
+
+        return NextResponse.json(response);
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(error);
+
+        return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+      }
+      // @ts-expect-error The return of `auth(() => ...) is overloaded to expect `return next(req, event)` to be the valid middleware type
+      // however we are returning NextResponse directly here because we want to proxy GraphQL requests. This is fine to ignore.
+    })(request, event);
+  };
+};