@faststore/core 4.10.1-dev.4 → 4.10.1-dev.6

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.10.1-dev.6](https://github.com/vtex/faststore/compare/v4.10.1-dev.5...v4.10.1-dev.6) (2026-10-28)
+
+### Bug Fixes
+
+- **core:** document that gallery scope keys reach the request URL ([dc61bdf](https://github.com/vtex/faststore/commit/dc61bdf2411b88ac15d29066a668a26f521785de))
+- **core:** hash the B2B contract scope sent with gallery queries ([f8bfac9](https://github.com/vtex/faststore/commit/f8bfac9f5dd4fbda848982a701e54eb1f3d2c14b))
+- **core:** refetch PLP first page for B2B buyers so the contract assortment applies ([72ddfdf](https://github.com/vtex/faststore/commit/72ddfdf06b7cc7a74aca7036cce37c400fef2cc0))
+- **core:** tell B2B buyers apart by org unit in the gallery cache key ([c7fe237](https://github.com/vtex/faststore/commit/c7fe237088515c40a49f34b46297022279c57f93))
+- **core:** widen the B2B contract scope hash to 53 bits ([f05f556](https://github.com/vtex/faststore/commit/f05f556c135b914af7c1058633ca50144a41669c))
+
+## [4.10.1-dev.5](https://github.com/vtex/faststore/compare/v4.10.1-dev.4...v4.10.1-dev.5) (2026-10-28)
+
+### Bug Fixes
+
+- **core:** bypass refresh-token flow on WebOps preview hosts ([0c8db36](https://github.com/vtex/faststore/commit/0c8db363b2f62ff054e3f3524cd15951b3aafe91))
+- **core:** detect preview hosts from x-forwarded-host on the server ([ec5d8a7](https://github.com/vtex/faststore/commit/ec5d8a7c70eca06c90153fe7cb5b58aa192bfb46))
+
 ## [4.10.1-dev.4](https://github.com/vtex/faststore/compare/v4.10.1-dev.3...v4.10.1-dev.4) (2026-10-28)
 
 **Note:** Version bump only for package @faststore/core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.10.1-dev.4",
+  "version": "4.10.1-dev.6",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/api": "4.10.1-dev.4",
-    "@faststore/diagnostics": "4.10.1-dev.4",
-    "@faststore/lighthouse": "4.10.1-dev.4",
-    "@faststore/sdk": "4.10.1-dev.4",
-    "@faststore/ui": "4.10.1-dev.4"
+    "@faststore/api": "4.10.1-dev.6",
+    "@faststore/lighthouse": "4.10.1-dev.6",
+    "@faststore/diagnostics": "4.10.1-dev.6",
+    "@faststore/ui": "4.10.1-dev.6",
+    "@faststore/sdk": "4.10.1-dev.6"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/pages/api/graphql.ts

@@ -1,5 +1,6 @@
 import {
   BadRequestError,
+  type CacheControl,
   UnauthorizedError,
   isFastStoreError,
   stringifyCacheControl,
@@ -10,7 +11,7 @@ import type { NextApiHandler, NextApiRequest } from 'next'
 import discoveryConfig from 'discovery.config'
 import { getJWTAutCookie } from 'src/utils/getCookie'
 import { getRequestHostname } from 'src/utils/getRequestHostname'
-import { isLocalHost } from 'src/utils/isLocalHost'
+import { shouldBypassRefreshTokenForRequest } from 'src/utils/shouldBypassRefreshToken'
 import {
   isHostAllowed,
   removeCookieDomain,
@@ -260,6 +261,87 @@ const respondToUnexpectedError = (
   response.status(500).end()
 }
 
+/**
+ * With `experimental.refreshToken` on, rejects a ValidateSession with 401 when
+ * the token needs a refresh, so the client runs the refresh-token flow first.
+ *
+ * Skipped on localhost and WebOps previews: neither proxies VTEX ID, so the
+ * refresh would fail and log out a manually injected auth cookie.
+ */
+const assertValidateSessionTokenIsFresh = ({
+  request,
+  operationName,
+  sessionRefreshAfter,
+}: {
+  request: NextApiRequest
+  operationName: string | undefined
+  sessionRefreshAfter: string | null | undefined
+}) => {
+  if (
+    operationName !== 'ValidateSession' ||
+    !discoveryConfig.experimental?.refreshToken ||
+    shouldBypassRefreshTokenForRequest(request.headers)
+  ) {
+    return
+  }
+
+  const jwt = getJWTAutCookie({
+    headers: request.headers,
+    account: discoveryConfig.api.storeId,
+  })
+
+  if (shouldForceRefreshTokenForValidateSession({ jwt, sessionRefreshAfter })) {
+    throw new UnauthorizedError(
+      'Unauthorized: Token expired. Please login again or refresh the page.'
+    )
+  }
+}
+
+/**
+ * Cache-Control for a successful response: the directives collected while
+ * executing the operation when there are any, otherwise a default
+ * `s-maxage`/`stale-while-revalidate` for GET queries and `no-store` for
+ * everything else.
+ */
+const getSuccessCacheControl = ({
+  request,
+  operationName,
+  cacheControl,
+  hasAuthCookie,
+}: {
+  request: NextApiRequest
+  operationName: string | undefined
+  cacheControl: CacheControl | undefined
+  hasAuthCookie: boolean
+}) => {
+  if (cacheControl) {
+    return stringifyCacheControl(cacheControl, hasAuthCookie)
+  }
+
+  if (
+    request.method !== 'GET' ||
+    !operationName?.toLowerCase()?.endsWith('query')
+  ) {
+    return 'no-cache, no-store'
+  }
+
+  const graphqlCacheControl = discoveryConfig?.experimental?.graphqlCacheControl
+
+  const maxAge =
+    graphqlCacheControl?.maxAge && graphqlCacheControl.maxAge > 0
+      ? graphqlCacheControl.maxAge
+      : DEFAULT_MAX_AGE // 5 minutes
+
+  const staleWhileRevalidate =
+    graphqlCacheControl?.staleWhileRevalidate &&
+    graphqlCacheControl.staleWhileRevalidate > 0
+      ? graphqlCacheControl.staleWhileRevalidate
+      : DEFAULT_STALE_WHILE_REVALIDATE // 1 hour
+
+  const scope = hasAuthCookie ? 'private' : 'public'
+  return `${scope}, s-maxage=${maxAge}, stale-while-revalidate=${staleWhileRevalidate}`
+}
+
 const handler: NextApiHandler = async (request, response) => {
   if (request.method !== 'POST' && request.method !== 'GET') {
     response.status(405).end()
@@ -286,29 +368,11 @@ const handler: NextApiHandler = async (request, response) => {
       operation?.__meta__?.operationHash
     )
 
-    const isLocal = isLocalHost(getRequestHostname(request.headers.host))
-
-    if (
-      !isLocal &&
-      operation.__meta__.operationName === 'ValidateSession' &&
-      discoveryConfig.experimental?.refreshToken
-    ) {
-      const jwt = getJWTAutCookie({
-        headers: request.headers,
-        account: discoveryConfig.api.storeId,
-      })
-
-      const shouldRefreshToken = shouldForceRefreshTokenForValidateSession({
-        jwt,
-        sessionRefreshAfter: variables?.session?.refreshAfter,
-      })
-
-      if (shouldRefreshToken) {
-        throw new UnauthorizedError(
-          'Unauthorized: Token expired. Please login again or refresh the page.'
-        )
-      }
-    }
+    assertValidateSessionTokenIsFresh({
+      request,
+      operationName: operation.__meta__.operationName,
+      sessionRefreshAfter: variables?.session?.refreshAfter,
+    })
 
     // Prevents to call ValidateSession or ValidateCartMutation without session (required) and get GraphQLError
     const doNotRun =
@@ -338,39 +402,15 @@ const handler: NextApiHandler = async (request, response) => {
 
     const hasAuthCookie = hasVtexIdclientAutCookie(request)
 
-    if (extensions.cacheControl) {
-      const cacheControl = stringifyCacheControl(
-        extensions.cacheControl,
-        hasAuthCookie
-      )
-      response.setHeader('cache-control', cacheControl)
-    } else if (
-      request.method === 'GET' &&
-      operation.__meta__.operationName?.toLowerCase()?.endsWith('query')
-    ) {
-      const maxAge =
-        discoveryConfig?.experimental?.graphqlCacheControl?.maxAge &&
-        discoveryConfig?.experimental?.graphqlCacheControl?.maxAge > 0
-          ? discoveryConfig.experimental.graphqlCacheControl.maxAge
-          : DEFAULT_MAX_AGE // 5 minutes
-
-      const staleWhileRevalidate =
-        discoveryConfig?.experimental?.graphqlCacheControl
-          ?.staleWhileRevalidate &&
-        discoveryConfig?.experimental?.graphqlCacheControl
-          ?.staleWhileRevalidate > 0
-          ? discoveryConfig.experimental.graphqlCacheControl
-              .staleWhileRevalidate
-          : DEFAULT_STALE_WHILE_REVALIDATE // 1 hour
-
-      const scope = hasAuthCookie ? 'private' : 'public'
-      response.setHeader(
-        'cache-control',
-        `${scope}, s-maxage=${maxAge}, stale-while-revalidate=${staleWhileRevalidate}`
-      )
-    } else {
-      response.setHeader('cache-control', 'no-cache, no-store')
-    }
+    response.setHeader(
+      'cache-control',
+      getSuccessCacheControl({
+        request,
+        operationName: operation.__meta__.operationName,
+        cacheControl: extensions.cacheControl,
+        hasAuthCookie,
+      })
+    )
 
     const setCookieValues = Array.from(extensions.cookies.values())
     if (setCookieValues.length > 0 && !hasErrors) {

package/src/pages/pvt/account/403.tsx

@@ -24,8 +24,7 @@ import PageProvider from 'src/sdk/overrides/PageProvider'
 import { execute } from 'src/server'
 import { injectGlobalSections } from 'src/server/cms/global'
 import { fetchMyAccountPageContent } from 'src/server/cms/fetchMyAccountPageContent'
-import { getRequestHostname } from 'src/utils/getRequestHostname'
-import { isLocalHost } from 'src/utils/isLocalHost'
+import { shouldBypassRefreshTokenForRequest } from 'src/utils/shouldBypassRefreshToken'
 import { withLocaleValidationSSR } from 'src/utils/localization/withLocaleValidation'
 import { getMyAccountRedirect } from 'src/utils/myAccountRedirect'
 
@@ -137,14 +136,16 @@ const getServerSidePropsBase: GetServerSideProps<
 
     const statusCode: number = (account.errors[0] as any)?.extensions?.status
 
-    const isLocal = isLocalHost(getRequestHostname(context.req.headers.host))
+    const bypassRefreshToken = shouldBypassRefreshTokenForRequest(
+      context.req.headers
+    )
 
     return {
       props: {
         globalSections: globalSectionsResult,
         pageSections: pageContent.sections,
         needsRefreshToken:
-          !isLocal &&
+          !bypassRefreshToken &&
           (statusCode === 401 || statusCode === 403) &&
           storeConfig.experimental?.refreshToken,
         fromPage,

package/src/sdk/account/useRefreshToken.ts

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { isLocalHostBrowser } from 'src/utils/isLocalHost'
+import { shouldBypassRefreshTokenBrowser } from 'src/utils/shouldBypassRefreshToken'
 import { logoutAndClearSession, sessionStore } from '../session'
 import { isRefreshTokenSuccessful, refreshTokenRequest } from './refreshToken'
 
@@ -13,13 +13,12 @@ export const useRefreshToken = (
     const handleRefreshTokenAndUpdateSession = async () => {
       if (!needsRefreshToken) return
 
-      // The refresh-token endpoint lives on the production origin and relies on
-      // the `vid_rt` cookie scoped to that origin. From localhost the request is
-      // cross-origin, so the cookie is not sent and the refresh always fails —
-      // which would also wipe the manually injected `VtexIdclientAutCookie_<account>`
+      // The refresh-token endpoint relies on VTEX ID, which neither localhost
+      // nor WebOps previews proxy, so the refresh always fails there — which
+      // would also wipe the manually injected `VtexIdclientAutCookie_<account>`
       // via `logoutAndClearSession`. Bail out and fall back to the static 403
       // view so developers can keep testing logged-in flows.
-      if (isLocalHostBrowser()) {
+      if (shouldBypassRefreshTokenBrowser()) {
         setShouldShow403(true)
         return
       }

package/src/sdk/product/usePageProductsQuery.ts

@@ -69,6 +69,69 @@ export const query = gql(`
 
 const getKey = (object: any) => JSON.stringify(object)
 
+const isDeliveryPromiseEnabled = storeConfig.deliveryPromise?.enabled ?? false
+
+/**
+ * Cache-only keys that scope gallery pages to the shopper context. They make
+ * the local cache comparison (and the SWR key) miss when a page was loaded for
+ * another context (e.g. the anonymous SSG page). They are not declared by the
+ * operation, so the API ignores them, but they are still sent with the
+ * variables, which go in the URL because this query is a GET operation.
+ * - `_postalCode`: pages are invalidated on region change. Only applied when
+ *   deliveryPromise is enabled to avoid unnecessary cache fragmentation.
+ * - `_contract`: the B2B contract assortment is applied server-side from the
+ *   session cookie, so it never shows up in the query variables. Keyed off
+ *   the presence of a `b2b` session (not `customerId`'s value) because
+ *   `customerId` can resolve to an empty string for a legitimate B2B buyer
+ *   (see `buildB2bSession` in `@faststore/api`). The fallback chain still
+ *   forces the re-fetch for them: the real `customerId`, when present, keeps
+ *   invalidating the cache on contract switch; otherwise the organizational
+ *   unit (`unitId`) tells buyers of different units apart; a generic marker is
+ *   the last resort. Since the value ends up in the URL, it is hashed so the
+ *   raw contract or unit id is not written to access, CDN or RUM logs as is.
+ *   These ids are not secrets (the session already hands them to the
+ *   browser), so the hash is cosmetic, not a privacy control: it is unkeyed
+ *   and a guessable id can be recovered from it. The URL still differs per
+ *   contract, so a contract page is never served from the anonymous page's
+ *   cache entry.
+ */
+const getShopperScope = ({
+  postalCode,
+  contract,
+}: {
+  postalCode?: string | null
+  contract?: string | null
+}) => ({
+  ...(isDeliveryPromiseEnabled && { _postalCode: postalCode ?? '' }),
+  ...(contract && { _contract: hashContractScope(contract) }),
+})
+
+/** The id a B2B session is scoped by, or `null` outside a B2B session. */
+const getContractScope = (
+  b2b?: { customerId?: string | null; unitId?: string | null } | null
+) => (b2b ? b2b.customerId || b2b.unitId || 'b2b' : null)
+
+/**
+ * 53-bit string hash (cyrb53): wide enough that two contracts in the same
+ * browser never share a cache key in practice, without exposing the raw id.
+ */
+export function hashContractScope(value: string) {
+  let h1 = 0xdeadbeef
+  let h2 = 0x41c6ce57
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0
+    h1 = Math.imul(h1 ^ code, 2654435761)
+    h2 = Math.imul(h2 ^ code, 1597334677)
+  }
+  h1 =
+    Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^
+    Math.imul(h2 ^ (h2 >>> 13), 3266489909)
+  h2 =
+    Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^
+    Math.imul(h1 ^ (h1 >>> 13), 3266489909)
+  return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36)
+}
+
 interface UseCreateUseGalleryPageProps {
   initialPages: ClientManyProductsQueryWithSearchIdQuery
   serverManyProductsVariables: ClientManyProductsQueryWithSearchIdQueryVariables
@@ -82,21 +145,17 @@ export const useCreateUseGalleryPage = (
 ) => {
   const initialPages = params?.initialPages?.search ? [params.initialPages] : []
 
-  // Seed the cache with the same region-aware key shape that useGalleryPage uses,
-  // so hasSameVariables correctly matches on first mount and avoids an unnecessary
-  // re-fetch of the SSR-loaded page.
-  const isDeliveryPromiseEnabled = storeConfig.deliveryPromise?.enabled ?? false
+  // Seed the cache with the same key shape that useGalleryPage uses, so
+  // hasSameVariables matches on first mount and avoids an unnecessary re-fetch
+  // of the SSR-loaded page. The SSG page is built without a buyer, so it is
+  // seeded without a contract: B2B buyers re-fetch it with their assortment.
   const { postalCode } = useSession()
   const initialVariables = params?.serverManyProductsVariables
     ? [
-        getKey(
-          isDeliveryPromiseEnabled
-            ? {
-                ...params.serverManyProductsVariables,
-                _postalCode: postalCode ?? '',
-              }
-            : params.serverManyProductsVariables
-        ),
+        getKey({
+          ...params.serverManyProductsVariables,
+          ...getShopperScope({ postalCode }),
+        }),
       ]
     : []
 
@@ -113,7 +172,7 @@ export const useCreateUseGalleryPage = (
       itemsPerPage,
     } = useSearch()
 
-    const { postalCode, isValidating: isSessionValidating } = useSession()
+    const { postalCode, b2b, isValidating: isSessionValidating } = useSession()
 
     const localizedVariables = useLocalizedVariables({
       first: itemsPerPage,
@@ -123,15 +182,15 @@ export const useCreateUseGalleryPage = (
       selectedFacets,
     })
 
-    // Include postalCode in the cache key so pages are invalidated on region change.
-    // _postalCode is not sent to the API — it only affects the local cache comparison.
-    // Only applied when deliveryPromise is enabled to avoid unnecessary cache fragmentation.
+    // Keyed on the contract id, not the `b2b` object, which is rebuilt on
+    // every session update.
+    const contract = getContractScope(b2b)
     const localizedVariablesWithRegion = useMemo(
-      () =>
-        isDeliveryPromiseEnabled
-          ? { ...localizedVariables, _postalCode: postalCode ?? '' }
-          : localizedVariables,
-      [localizedVariables, postalCode]
+      () => ({
+        ...localizedVariables,
+        ...getShopperScope({ postalCode, contract }),
+      }),
+      [localizedVariables, postalCode, contract]
     )
 
     const hasSameVariables = deepEquals(

package/src/sdk/session/index.ts

@@ -8,7 +8,7 @@ import type {
   ValidateSessionMutationVariables,
 } from '@generated/graphql'
 import deepEqual from 'fast-deep-equal'
-import { isLocalHostBrowser } from 'src/utils/isLocalHost'
+import { shouldBypassRefreshTokenBrowser } from 'src/utils/shouldBypassRefreshToken'
 import { filterChannel } from 'src/utils/utilities'
 import storeConfig from '../../../discovery.config'
 import {
@@ -109,6 +109,43 @@ async function handleRefreshToken(session: Session): Promise<Session | null> {
   return null
 }
 
+/**
+ * The refresh-token flow runs only when `experimental.refreshToken` is on and
+ * the host can reach VTEX ID: localhost and WebOps previews do not proxy it.
+ */
+function canRefreshToken(): boolean {
+  return (
+    !!storeConfig.experimental?.refreshToken &&
+    !shouldBypassRefreshTokenBrowser()
+  )
+}
+
+/**
+ * With deliveryPromise on and no postalCode in the session, fills it from the
+ * B2B saved address or from the shopper location.
+ */
+async function syncDeliveryPromisePostalCode(session: Session) {
+  if (
+    !storeConfig.deliveryPromise?.enabled ||
+    (session.postalCode &&
+      session.postalCode !== storeConfig.session.postalCode)
+  ) {
+    return
+  }
+
+  // Case B2B: If a B2B shopper is logged in and a saved address is available, the postalCode field is automatically updated with the postal code from that address by the B2B session apps (shopper-session and profile-session).
+  if (session.b2b?.savedPostalCode) {
+    sessionStore.set({
+      ...session,
+      postalCode: session.b2b.savedPostalCode,
+    })
+    return
+  }
+
+  const sessionWithLocation = await getPostalCode(session)
+  !!sessionWithLocation && sessionStore.set(sessionWithLocation)
+}
+
 function isRefreshAfterExpired(session: Session): boolean {
   return (
     !!session.refreshAfter &&
@@ -126,12 +163,8 @@ export const validateSession = async (session: Session) => {
   // If the refreshToken is enabled and the refreshAfter is expired, refresh the token.
   // On success, continue to the validation flow with the refreshed session.
   // On failure (logoutAndClearSession already triggered), bail out.
-  // Skipped in local environments where the refresh token infrastructure is unavailable.
-  if (
-    !isLocalHostBrowser() &&
-    storeConfig.experimental?.refreshToken &&
-    isRefreshAfterExpired(session)
-  ) {
+  // Skipped on localhost and WebOps previews, where the refresh token infrastructure is unavailable.
+  if (canRefreshToken() && isRefreshAfterExpired(session)) {
     const refreshed = await handleRefreshToken(session)
     if (!refreshed) {
       return null
@@ -139,23 +172,7 @@ export const validateSession = async (session: Session) => {
     session = refreshed
   }
 
-  // If deliveryPromise is enabled and there is no postalCode in the session
-  if (
-    storeConfig.deliveryPromise?.enabled &&
-    (!session.postalCode ||
-      session.postalCode === storeConfig.session.postalCode)
-  ) {
-    // Case B2B: If a B2B shopper is logged in and a saved address is available, the postalCode field is automatically updated with the postal code from that address by the B2B session apps (shopper-session and profile-session).
-    if (session.b2b && session.b2b?.savedPostalCode) {
-      sessionStore.set({
-        ...session,
-        postalCode: session.b2b.savedPostalCode,
-      })
-    } else {
-      const sessionWithLocation = await getPostalCode(session)
-      !!sessionWithLocation && sessionStore.set(sessionWithLocation)
-    }
-  }
+  await syncDeliveryPromisePostalCode(session)
 
   try {
     // Prevents to call ValidateSession without session (required) and get Error
@@ -173,12 +190,7 @@ export const validateSession = async (session: Session) => {
 
     return data.validateSession
   } catch (error) {
-    const shouldRefreshToken =
-      !isLocalHostBrowser() &&
-      error?.status === 401 &&
-      storeConfig.experimental?.refreshToken
-
-    if (shouldRefreshToken) {
+    if (error?.status === 401 && canRefreshToken()) {
       const refreshed = await handleRefreshToken(session)
       if (refreshed) {
         sessionStore.set(refreshed)

package/src/utils/isLocalHost.ts

@@ -1,9 +1,5 @@
 /**
  * Hostnames that represent a local development environment.
- *
- * These are the only hosts where the FastStore app skips the refresh-token
- * flow so developers can drive the app with a manually injected
- * `VtexIdclientAutCookie_<account>` cookie regardless of feature flags.
  */
 const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1'])
 
@@ -11,9 +7,8 @@ const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1'])
  * Returns `true` when the given hostname corresponds to a local development
  * environment (`localhost` / `127.0.0.1`).
  *
- * Refresh-token and other production-only flows MUST be bypassed on these
- * hostnames so that developers can test logged-in scenarios with manually
- * injected cookies, independent of any experimental flag.
+ * To decide whether to skip the refresh-token flow, use
+ * `shouldBypassRefreshToken`, which also covers WebOps preview hosts.
  *
  * The input MUST be a bare hostname (no port). Use {@link getRequestHostname}
  * on server-side request headers before calling this helper.
@@ -22,12 +17,3 @@ export function isLocalHost(hostname: string | null | undefined): boolean {
   if (!hostname) return false
   return LOCAL_HOSTNAMES.has(hostname.toLowerCase())
 }
-
-/**
- * Browser-side wrapper that reads `window.location.hostname`. Returns `false`
- * when `window` is not available (SSR/Node).
- */
-export function isLocalHostBrowser(): boolean {
-  if (typeof window === 'undefined') return false
-  return isLocalHost(window.location.hostname)
-}

package/src/utils/shouldBypassRefreshToken.ts

@@ -0,0 +1,63 @@
+import { getRequestHostname } from './getRequestHostname'
+import { isLocalHost } from './isLocalHost'
+import { isHostAllowed, singleForwardedHost } from './trustedForwardedHost'
+
+/**
+ * WebOps preview deployments are served under `<preview>.preview.vtex.app`.
+ *
+ * Only this subdomain is matched: `{account}.vtex.app` is a production default
+ * domain and MUST keep the refresh-token flow.
+ */
+const PREVIEW_HOST_SUFFIXES = ['.preview.vtex.app']
+
+/**
+ * Returns `true` when the refresh-token flow must be skipped for the given
+ * hostname: local development (`localhost` / `127.0.0.1`) and WebOps previews.
+ *
+ * Neither environment proxies VTEX ID, so `/api/vtexid/refreshtoken/webstore`
+ * always fails there and the resulting logout wipes a manually injected
+ * `VtexIdclientAutCookie_<account>` cookie. Skipping the flow lets developers
+ * test logged-in scenarios with that cookie alone.
+ *
+ * The input MUST be a bare hostname (no port). Use {@link getRequestHostname}
+ * on server-side request headers before calling this helper. A trailing dot
+ * (fully qualified name) is ignored.
+ */
+export function shouldBypassRefreshToken(
+  hostname: string | null | undefined
+): boolean {
+  if (!hostname) return false
+  const normalizedHostname = hostname.toLowerCase().replace(/\.$/, '')
+  return (
+    isLocalHost(normalizedHostname) ||
+    isHostAllowed(normalizedHostname, PREVIEW_HOST_SUFFIXES)
+  )
+}
+
+/**
+ * Server-side check from the request headers. Behind the WebOps preview
+ * ingress the browser host arrives in `x-forwarded-host` rather than `Host`
+ * (see `normalizeSetCookieDomain` in `pages/api/graphql.ts`), so both are
+ * checked. Both are client-controlled: a forged value only skips the forced
+ * refresh, which grants nothing since the JWT is still validated upstream.
+ */
+export function shouldBypassRefreshTokenForRequest(headers: {
+  host?: string
+  'x-forwarded-host'?: string | string[]
+}): boolean {
+  return (
+    shouldBypassRefreshToken(getRequestHostname(headers.host)) ||
+    shouldBypassRefreshToken(
+      getRequestHostname(singleForwardedHost(headers['x-forwarded-host']))
+    )
+  )
+}
+
+/**
+ * Browser-side wrapper that reads `window.location.hostname`. Returns `false`
+ * when `window` is not available (SSR/Node).
+ */
+export function shouldBypassRefreshTokenBrowser(): boolean {
+  if (globalThis.window === undefined) return false
+  return shouldBypassRefreshToken(globalThis.window.location.hostname)
+}