@open-mercato/core 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/ecommerce/lib/brandingStyles.ts

@@ -0,0 +1,215 @@
+export type EcommerceBrandingFont = {
+  id: string
+  label: string
+  stack: string
+  googleFamily: string | null
+}
+
+export const ECOMMERCE_BRANDING_FONTS: readonly EcommerceBrandingFont[] = [
+  {
+    id: 'system-sans',
+    label: 'System sans-serif',
+    stack: "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+    googleFamily: null,
+  },
+  { id: 'system-serif', label: 'System serif', stack: "Georgia, 'Times New Roman', Times, serif", googleFamily: null },
+  {
+    id: 'system-mono',
+    label: 'System monospace',
+    stack: "ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace",
+    googleFamily: null,
+  },
+  { id: 'inter', label: 'Inter', stack: "'Inter', sans-serif", googleFamily: 'Inter' },
+  { id: 'roboto', label: 'Roboto', stack: "'Roboto', sans-serif", googleFamily: 'Roboto' },
+  { id: 'open-sans', label: 'Open Sans', stack: "'Open Sans', sans-serif", googleFamily: 'Open Sans' },
+  { id: 'lato', label: 'Lato', stack: "'Lato', sans-serif", googleFamily: 'Lato' },
+  { id: 'montserrat', label: 'Montserrat', stack: "'Montserrat', sans-serif", googleFamily: 'Montserrat' },
+  { id: 'poppins', label: 'Poppins', stack: "'Poppins', sans-serif", googleFamily: 'Poppins' },
+  { id: 'dm-sans', label: 'DM Sans', stack: "'DM Sans', sans-serif", googleFamily: 'DM Sans' },
+  { id: 'merriweather', label: 'Merriweather', stack: "'Merriweather', serif", googleFamily: 'Merriweather' },
+  {
+    id: 'playfair-display',
+    label: 'Playfair Display',
+    stack: "'Playfair Display', serif",
+    googleFamily: 'Playfair Display',
+  },
+]
+
+export const ecommerceBrandingFontIds: readonly string[] = ECOMMERCE_BRANDING_FONTS.map((font) => font.id)
+
+export function findEcommerceBrandingFont(id: string): EcommerceBrandingFont | null {
+  return ECOMMERCE_BRANDING_FONTS.find((font) => font.id === id) ?? null
+}
+
+const NUMBER_PATTERN = '(\\d+(?:\\.\\d+)?|\\.\\d+)'
+const OKLCH_PATTERN = new RegExp(
+  `^oklch\\(\\s*${NUMBER_PATTERN}(%?)\\s+${NUMBER_PATTERN}(%?)\\s+${NUMBER_PATTERN}(deg)?\\s*(?:\\/\\s*${NUMBER_PATTERN}(%?)\\s*)?\\)$`,
+)
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/
+const BORDER_RADIUS_PATTERN = /^(\d+(?:\.\d+)?|\.\d+)(rem|px)$/
+
+const OKLCH_CHROMA_MAX = 0.5
+const OKLCH_HUE_MAX = 360
+const BORDER_RADIUS_REM_MAX = 5
+const BORDER_RADIUS_PX_MAX = 80
+
+function withinBounds(raw: string, percent: boolean, numericMax: number): boolean {
+  const value = Number(raw)
+  if (!Number.isFinite(value) || value < 0) return false
+  return percent ? value <= 100 : value <= numericMax
+}
+
+export function isValidOklchColor(value: string): boolean {
+  return normalizeOklchColor(value) !== null
+}
+
+function normalizeOklchColor(value: string): string | null {
+  const match = OKLCH_PATTERN.exec(value)
+  if (!match) return null
+  const [, lightness, lightnessPercent, chroma, chromaPercent, hue, hueUnit, alpha, alphaPercent] = match
+  if (!withinBounds(lightness, lightnessPercent === '%', 1)) return null
+  if (!withinBounds(chroma, chromaPercent === '%', OKLCH_CHROMA_MAX)) return null
+  if (!withinBounds(hue, false, OKLCH_HUE_MAX)) return null
+  if (alpha !== undefined && !withinBounds(alpha, alphaPercent === '%', 1)) return null
+  const alphaPart = alpha === undefined ? '' : ` / ${alpha}${alphaPercent}`
+  return `oklch(${lightness}${lightnessPercent} ${chroma}${chromaPercent} ${hue}${hueUnit ?? ''}${alphaPart})`
+}
+
+export function isValidBrandingColor(value: string): boolean {
+  return HEX_COLOR_PATTERN.test(value) || isValidOklchColor(value)
+}
+
+export function normalizeBrandingColor(value: string): string | null {
+  if (HEX_COLOR_PATTERN.test(value)) return value.toLowerCase()
+  return normalizeOklchColor(value)
+}
+
+export function isValidBorderRadius(value: string): boolean {
+  if (value === '0') return true
+  const match = BORDER_RADIUS_PATTERN.exec(value)
+  if (!match) return false
+  const amount = Number(match[1])
+  if (!Number.isFinite(amount)) return false
+  return match[2] === 'rem' ? amount <= BORDER_RADIUS_REM_MAX : amount <= BORDER_RADIUS_PX_MAX
+}
+
+export const ECOMMERCE_BRANDING_COLOR_KEYS = [
+  'primaryColor',
+  'primaryForeground',
+  'accentColor',
+  'accentForeground',
+  'backgroundColor',
+  'foregroundColor',
+] as const
+
+export const ECOMMERCE_BRANDING_FONT_KEYS = ['fontFamilyBase', 'fontFamilyHeading'] as const
+
+export type EcommerceBrandingColorKey = (typeof ECOMMERCE_BRANDING_COLOR_KEYS)[number]
+export type EcommerceBrandingFontKey = (typeof ECOMMERCE_BRANDING_FONT_KEYS)[number]
+export type EcommerceBrandingTokenKey = EcommerceBrandingColorKey | 'borderRadius' | EcommerceBrandingFontKey
+
+export type EcommerceBrandingDeclaration = {
+  property: string
+  value: string
+}
+
+const BRANDING_PROPERTY_BY_KEY: Readonly<Record<EcommerceBrandingTokenKey, string>> = {
+  primaryColor: '--primary',
+  primaryForeground: '--primary-foreground',
+  accentColor: '--accent',
+  accentForeground: '--accent-foreground',
+  backgroundColor: '--background',
+  foregroundColor: '--foreground',
+  borderRadius: '--radius',
+  fontFamilyBase: '--font-base',
+  fontFamilyHeading: '--font-heading',
+}
+
+const BRANDING_TOKEN_ORDER: readonly EcommerceBrandingTokenKey[] = [
+  'primaryColor',
+  'primaryForeground',
+  'accentColor',
+  'accentForeground',
+  'backgroundColor',
+  'foregroundColor',
+  'borderRadius',
+  'fontFamilyBase',
+  'fontFamilyHeading',
+]
+
+export const ECOMMERCE_BRANDING_CSS_PROPERTIES: readonly string[] = BRANDING_TOKEN_ORDER.map(
+  (key) => BRANDING_PROPERTY_BY_KEY[key],
+)
+
+const DEFAULT_FONT_BASE_ID = 'inter'
+const HEADING_INHERITS_BASE = 'var(--font-base)'
+
+export const ECOMMERCE_BRANDING_DEFAULTS: Readonly<Record<EcommerceBrandingColorKey | 'borderRadius', string>> = {
+  primaryColor: 'oklch(0.205 0 0)',
+  primaryForeground: 'oklch(0.985 0 0)',
+  accentColor: 'oklch(0.97 0 0)',
+  accentForeground: 'oklch(0.205 0 0)',
+  backgroundColor: 'oklch(1 0 0)',
+  foregroundColor: 'oklch(0.145 0 0)',
+  borderRadius: '0.625rem',
+}
+
+const NONCE_PATTERN = /^[A-Za-z0-9+/_-]{8,128}={0,2}$/
+
+function readOwnString(source: unknown, key: string): string | null {
+  if (typeof source !== 'object' || source === null) return null
+  if (!Object.prototype.hasOwnProperty.call(source, key)) return null
+  const value = (source as Record<string, unknown>)[key]
+  return typeof value === 'string' ? value : null
+}
+
+function resolveColor(source: unknown, key: EcommerceBrandingColorKey): string {
+  const raw = readOwnString(source, key)
+  return (raw === null ? null : normalizeBrandingColor(raw)) ?? ECOMMERCE_BRANDING_DEFAULTS[key]
+}
+
+function resolveBorderRadius(source: unknown): string {
+  const raw = readOwnString(source, 'borderRadius')
+  return raw !== null && isValidBorderRadius(raw) ? raw : ECOMMERCE_BRANDING_DEFAULTS.borderRadius
+}
+
+function resolveFontStack(source: unknown, key: EcommerceBrandingFontKey): string | null {
+  const raw = readOwnString(source, key)
+  const font = raw === null ? null : findEcommerceBrandingFont(raw)
+  return font ? font.stack : null
+}
+
+export function buildBrandingDeclarations(branding: unknown): EcommerceBrandingDeclaration[] {
+  const baseStack =
+    resolveFontStack(branding, 'fontFamilyBase') ?? findEcommerceBrandingFont(DEFAULT_FONT_BASE_ID)?.stack ?? 'sans-serif'
+  const headingStack = resolveFontStack(branding, 'fontFamilyHeading') ?? HEADING_INHERITS_BASE
+  const values: Record<EcommerceBrandingTokenKey, string> = {
+    primaryColor: resolveColor(branding, 'primaryColor'),
+    primaryForeground: resolveColor(branding, 'primaryForeground'),
+    accentColor: resolveColor(branding, 'accentColor'),
+    accentForeground: resolveColor(branding, 'accentForeground'),
+    backgroundColor: resolveColor(branding, 'backgroundColor'),
+    foregroundColor: resolveColor(branding, 'foregroundColor'),
+    borderRadius: resolveBorderRadius(branding),
+    fontFamilyBase: baseStack,
+    fontFamilyHeading: headingStack,
+  }
+  return BRANDING_TOKEN_ORDER.map((key) => ({ property: BRANDING_PROPERTY_BY_KEY[key], value: values[key] }))
+}
+
+export function renderBrandingRootRule(branding: unknown): string {
+  const body = buildBrandingDeclarations(branding)
+    .map((declaration) => `${declaration.property}:${declaration.value}`)
+    .join(';')
+  return `:root{${body}}`
+}
+
+export type BrandingStyleBlockOptions = {
+  nonce?: string | null
+}
+
+export function renderBrandingStyleBlock(branding: unknown, options: BrandingStyleBlockOptions = {}): string {
+  const nonce = typeof options.nonce === 'string' && NONCE_PATTERN.test(options.nonce) ? options.nonce : null
+  const attributes = nonce ? ` nonce="${nonce}"` : ''
+  return `<style data-ecommerce-branding${attributes}>${renderBrandingRootRule(branding)}</style>`
+}

package/src/modules/ecommerce/lib/buyerContext.ts

@@ -0,0 +1,401 @@
+import { createHash } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  hashEffectiveScope,
+  intersectScopes,
+  type AssortmentScope,
+  type EffectiveAssortmentScope,
+} from '@open-mercato/shared/lib/catalog-visibility'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { CustomerUser } from '@open-mercato/core/modules/customer_accounts/data/entities'
+import { CatalogPriceKind } from '@open-mercato/core/modules/catalog/data/entities'
+import type { CustomerGroupsService } from '@open-mercato/core/modules/customer_groups/services/customerGroupsService'
+import type { EcommercePriceDisplayMode } from '../data/validators'
+import { emitEcommerceEvent } from '../events'
+import { buyerContextCache, ecommerceResolutionCache, type CacheContainer } from './cacheKeys'
+import { StorefrontResolutionError, type ResolvedStore } from './storeContext'
+import type { BuyerContext, StoreContext } from './types'
+
+/**
+ * Buyer layer of storefront resolution (SPEC-029 v4.6 §4.1 step 6, §6, §6.0, §6.1, §6.1a, §8).
+ *
+ * The portal session only proves WHO is asking; identity ids are read fresh from
+ * `customer_accounts.CustomerUser` (D3), never from JWT claims. A session issued for another
+ * tenant or organization answers `401` (D4). The buyer layer is locale-independent and cached
+ * for 60 s per (store, customerUserId | anonymous); `digest` is computed per request by
+ * `composeStoreContext` because it includes the effective locale.
+ */
+
+export type BuyerContextContainer = CacheContainer
+
+export const ASSORTMENT_EMPTY_THROTTLE_MS = 3_600_000
+
+const DIGEST_LENGTH = 16
+const NULL_SEGMENT = '-'
+
+const logger = createLogger('ecommerce').child({ component: 'buyer-context' })
+
+type BuyerIdentity = Pick<BuyerContext, 'customerUserId' | 'customerId' | 'companyId' | 'customerIds' | 'isAuthenticated'>
+
+type CustomerOverlayDatabase = {
+  catalog_product_variant_prices: {
+    customer_id: string | null
+    tenant_id: string
+    organization_id: string
+  }
+}
+
+const ANONYMOUS_IDENTITY: BuyerIdentity = {
+  customerUserId: null,
+  customerId: null,
+  companyId: null,
+  customerIds: [],
+  isAuthenticated: false,
+}
+
+function tryResolve<T>(container: BuyerContextContainer, name: string): T | null {
+  try {
+    const resolved = container.resolve(name) as T | null | undefined
+    return resolved ?? null
+  } catch {
+    return null
+  }
+}
+
+function requireService<T>(container: BuyerContextContainer, name: string): T {
+  const service = tryResolve<T>(container, name)
+  if (!service) throw new Error(`[internal] ecommerce buyer context requires the DI service ${name}`)
+  return service
+}
+
+function sha256Truncated(segments: string[]): string {
+  return createHash('sha256').update(segments.join('|')).digest('hex').slice(0, DIGEST_LENGTH)
+}
+
+export function computePriceScopeKey(input: {
+  channelId: string
+  currencyCode: string
+  priceKindId: string | null
+  customerGroupIds: string[]
+}): string {
+  const sortedGroupIds = [...input.customerGroupIds].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+  return sha256Truncated([
+    input.channelId,
+    input.currencyCode,
+    input.priceKindId ?? NULL_SEGMENT,
+    sortedGroupIds.join(','),
+  ])
+}
+
+export function computeStoreContextDigest(input: {
+  storeId: string
+  effectiveLocale: string
+  taxMode: EcommercePriceDisplayMode
+  priceScopeKey: string
+  assortmentScopeHash: string
+  customerOverlayId: string | null
+}): string {
+  return sha256Truncated([
+    input.storeId,
+    input.effectiveLocale,
+    input.taxMode,
+    input.priceScopeKey,
+    input.assortmentScopeHash,
+    input.customerOverlayId ?? NULL_SEGMENT,
+  ])
+}
+
+export function buyerIdentityFromCustomerUser(user: {
+  id: string
+  personEntityId?: string | null
+  customerEntityId?: string | null
+}): BuyerIdentity {
+  const personId = user.personEntityId ?? null
+  const companyId = user.customerEntityId ?? null
+  const customerIds = Array.from(
+    new Set([personId, companyId].filter((id): id is string => typeof id === 'string' && id.length > 0)),
+  )
+  return {
+    customerUserId: user.id,
+    customerId: personId ?? companyId,
+    companyId,
+    customerIds,
+    isAuthenticated: true,
+  }
+}
+
+async function loadBuyerIdentity(em: EntityManager, customerUserId: string, store: ResolvedStore): Promise<BuyerIdentity> {
+  const scope = { tenantId: store.tenantId, organizationId: store.organizationId }
+  const user = await findOneWithDecryption(
+    em,
+    CustomerUser,
+    { id: customerUserId, ...scope, isActive: true, deletedAt: null },
+    undefined,
+    scope,
+  )
+  if (!user) {
+    logger.debug('Portal session points at a missing or inactive customer user', { storeId: store.store.id })
+    throw new StorefrontResolutionError(401, 'portal_session_invalid')
+  }
+  return buyerIdentityFromCustomerUser(user)
+}
+
+export function taxModeFromPriceKindDisplayMode(displayMode: string | null | undefined): EcommercePriceDisplayMode | null {
+  if (displayMode === 'excluding-tax') return 'net'
+  if (displayMode === 'including-tax') return 'gross'
+  return null
+}
+
+async function resolveTaxMode(
+  em: EntityManager,
+  priceKindId: string | null,
+  store: ResolvedStore,
+): Promise<EcommercePriceDisplayMode> {
+  const fallback = store.store.settings.display.priceDisplayModeDefault
+  if (!priceKindId) return fallback
+  const scope = { tenantId: store.tenantId, organizationId: store.organizationId }
+  const priceKind = await findOneWithDecryption(
+    em,
+    CatalogPriceKind,
+    {
+      id: priceKindId,
+      tenantId: store.tenantId,
+      deletedAt: null,
+      $or: [{ organizationId: null }, { organizationId: store.organizationId }],
+    },
+    undefined,
+    scope,
+  )
+  return taxModeFromPriceKindDisplayMode(priceKind?.displayMode) ?? fallback
+}
+
+async function resolveCustomerOverlayId(
+  em: EntityManager,
+  customerIds: string[],
+  store: ResolvedStore,
+): Promise<string | null> {
+  if (customerIds.length === 0) return null
+  const rows = await em
+    .getKysely<CustomerOverlayDatabase>()
+    .selectFrom('catalog_product_variant_prices')
+    .select('customer_id')
+    .distinct()
+    .where('customer_id', 'in', customerIds)
+    .where('tenant_id', '=', store.tenantId)
+    .where('organization_id', '=', store.organizationId)
+    .execute()
+  const withOwnRows = new Set(rows.map((row) => row.customer_id).filter((id): id is string => typeof id === 'string'))
+  const overlayIds = customerIds.filter((id) => withOwnRows.has(id))
+  return overlayIds.length > 0 ? overlayIds.join(',') : null
+}
+
+/**
+ * Effective assortment for this buyer: the customer-groups OR-list (groups plus the customer's
+ * own override) AND-ed with the channel scope.
+ */
+async function resolveEffectiveAssortment(
+  service: CustomerGroupsService,
+  tenantId: string,
+  channelAssortmentScope: AssortmentScope | null,
+  identity: BuyerIdentity,
+): Promise<EffectiveAssortmentScope> {
+  const buyerScope = await service.resolveAssortmentScope({
+    customerId: identity.customerId,
+    customerIds: identity.customerIds,
+    tenantId,
+  })
+  return intersectScopes(channelAssortmentScope, buyerScope.scope)
+}
+
+/**
+ * The effective assortment an anonymous buyer gets on a channel, resolved exactly as
+ * `resolveBuyerContext` resolves it: a channel that requires authentication is deny-all (`[]`),
+ * otherwise the channel scope intersected with the default customer group's scope. Lets the admin
+ * assortment count reuse the storefront's resolution instead of re-deriving it.
+ */
+export async function resolveAnonymousAssortmentScope(
+  container: BuyerContextContainer,
+  input: { tenantId: string; channelAssortmentScope: AssortmentScope | null; requireAuthentication: boolean },
+): Promise<EffectiveAssortmentScope> {
+  if (input.requireAuthentication) return []
+  const service = requireService<CustomerGroupsService>(container, 'customerGroupsService')
+  return resolveEffectiveAssortment(service, input.tenantId, input.channelAssortmentScope, ANONYMOUS_IDENTITY)
+}
+
+async function reportEmptyAssortment(
+  container: BuyerContextContainer,
+  store: ResolvedStore,
+  assortmentScopeHash: string,
+): Promise<void> {
+  const cache = ecommerceResolutionCache(container)
+  const key = ['assortment-empty', store.store.id, store.channel.channelBindingId, assortmentScopeHash]
+  const alreadyReported = await cache.get<{ reportedAt: string }>(key)
+  if (alreadyReported) return
+  await cache.set(key, { reportedAt: new Date().toISOString() }, { ttlMs: ASSORTMENT_EMPTY_THROTTLE_MS })
+  logger.warn('Authenticated buyer resolved to an empty assortment', {
+    storeId: store.store.id,
+    channelBindingId: store.channel.channelBindingId,
+    assortmentScopeHash,
+  })
+  try {
+    await emitEcommerceEvent(
+      'ecommerce.assortment.empty_detected',
+      {
+        id: store.store.id,
+        storeId: store.store.id,
+        channelBindingId: store.channel.channelBindingId,
+        assortmentScopeHash,
+        tenantId: store.tenantId,
+        organizationId: store.organizationId,
+      },
+      { persistent: true, tenantId: store.tenantId, organizationId: store.organizationId },
+    )
+  } catch (error) {
+    logger.warn('Failed to emit empty assortment event', { storeId: store.store.id, err: error })
+    getTelemetryRuntime()?.reportError(error, {
+      module: 'ecommerce',
+      code: 'ecommerce.assortment_empty_emit_failed',
+      attributes: { storeId: store.store.id },
+    })
+  }
+}
+
+type BuyerGroupLayer = {
+  customerGroupIds: string[]
+  priceKindId: string | null
+  allowPurchaseOnAccount: boolean
+  approvalRequiredAbove: number | null
+  assortmentScope: EffectiveAssortmentScope
+}
+
+function isClosedToBuyer(store: ResolvedStore, identity: BuyerIdentity): boolean {
+  return store.channel.requireAuthentication && !identity.isAuthenticated
+}
+
+async function resolveBuyerGroupLayer(
+  container: BuyerContextContainer,
+  store: ResolvedStore,
+  identity: BuyerIdentity,
+): Promise<BuyerGroupLayer> {
+  if (isClosedToBuyer(store, identity)) {
+    return {
+      customerGroupIds: [],
+      priceKindId: store.channel.priceKindId ?? null,
+      allowPurchaseOnAccount: false,
+      approvalRequiredAbove: null,
+      assortmentScope: [],
+    }
+  }
+  const service = requireService<CustomerGroupsService>(container, 'customerGroupsService')
+  const groups = await service.resolveGroups({
+    customerId: identity.customerId,
+    customerIds: identity.customerIds,
+    tenantId: store.tenantId,
+  })
+  const terms = await service.resolveTerms({
+    customerId: identity.customerId,
+    customerIds: identity.customerIds,
+    tenantId: store.tenantId,
+    groupIds: groups.groupIds,
+  })
+  return {
+    customerGroupIds: groups.groupIds,
+    priceKindId: terms.priceKindId ?? store.channel.priceKindId ?? null,
+    allowPurchaseOnAccount: terms.allowPurchaseOnAccount,
+    approvalRequiredAbove: terms.approvalRequiredAbove,
+    assortmentScope: await resolveEffectiveAssortment(
+      service,
+      store.tenantId,
+      store.channel.assortmentScope,
+      identity,
+    ),
+  }
+}
+
+async function buildBuyerContext(
+  container: BuyerContextContainer,
+  store: ResolvedStore,
+  identity: BuyerIdentity,
+): Promise<BuyerContext> {
+  const em = requireService<EntityManager>(container, 'em')
+  const { customerGroupIds, priceKindId, allowPurchaseOnAccount, approvalRequiredAbove, assortmentScope } =
+    await resolveBuyerGroupLayer(container, store, identity)
+  const taxMode = await resolveTaxMode(em, priceKindId, store)
+  const assortmentScopeHash = hashEffectiveScope(assortmentScope)
+  if (identity.isAuthenticated && Array.isArray(assortmentScope) && assortmentScope.length === 0) {
+    await reportEmptyAssortment(container, store, assortmentScopeHash)
+  }
+  const customerOverlayId = await resolveCustomerOverlayId(em, identity.customerIds, store)
+  return {
+    ...identity,
+    customerGroupIds,
+    taxMode,
+    priceKindId,
+    allowPurchaseOnAccount,
+    approvalRequiredAbove,
+    assortmentScope,
+    assortmentScopeHash,
+    priceScopeKey: computePriceScopeKey({
+      channelId: store.channel.salesChannelId,
+      currencyCode: store.currencyCode,
+      priceKindId,
+      customerGroupIds,
+    }),
+    customerOverlayId,
+  }
+}
+
+async function readPortalSession(request: Request) {
+  const { getCustomerAuthFromRequest } = await import('@open-mercato/core/modules/customer_accounts/lib/customerAuth')
+  return getCustomerAuthFromRequest(request)
+}
+
+export async function resolveBuyerContext(
+  container: BuyerContextContainer,
+  store: ResolvedStore,
+  request: Request | null,
+): Promise<BuyerContext> {
+  const auth = request ? await readPortalSession(request) : null
+  if (auth && (auth.tenantId !== store.tenantId || auth.orgId !== store.organizationId)) {
+    logger.debug('Portal session scope does not match the resolved store', { storeId: store.store.id })
+    throw new StorefrontResolutionError(401, 'portal_session_scope_mismatch')
+  }
+  const customerUserId = auth?.sub ?? null
+  const cache = buyerContextCache(container, { tenantId: store.tenantId, storeId: store.store.id })
+  const cached = await cache.get(customerUserId)
+  if (cached && cached.customerUserId === customerUserId) return cached
+  const identity = customerUserId
+    ? await loadBuyerIdentity(requireService<EntityManager>(container, 'em'), customerUserId, store)
+    : ANONYMOUS_IDENTITY
+  const buyer = await buildBuyerContext(container, store, identity)
+  await cache.set(buyer)
+  return buyer
+}
+
+export function composeStoreContext(store: ResolvedStore, buyer: BuyerContext): StoreContext {
+  return {
+    store: store.store,
+    tenantId: store.tenantId,
+    organizationId: store.organizationId,
+    channel: {
+      channelBindingId: store.channel.channelBindingId,
+      salesChannelId: store.channel.salesChannelId,
+      priceKindId: store.channel.priceKindId,
+      priceSortFallback: store.channel.priceSortFallback,
+    },
+    buyer,
+    effectiveLocale: store.effectiveLocale,
+    requestedLocale: store.requestedLocale,
+    currencyCode: store.currencyCode,
+    digest: computeStoreContextDigest({
+      storeId: store.store.id,
+      effectiveLocale: store.effectiveLocale,
+      taxMode: buyer.taxMode,
+      priceScopeKey: buyer.priceScopeKey,
+      assortmentScopeHash: buyer.assortmentScopeHash,
+      customerOverlayId: buyer.customerOverlayId,
+    }),
+  }
+}