@open-mercato/core 0.6.7-develop.6795.1.8a3f27921c → 0.6.7-develop.6824.1.21fff90682

package/src/modules/business_rules/lib/action-executor.ts

@@ -1,5 +1,12 @@
+import type { EntityManager as PostgreSqlEntityManager } from '@mikro-orm/postgresql'
 import type { EvaluationContext } from './expression-evaluator'
 import { getNestedValue, resolveSpecialValue } from './value-resolver'
+import {
+  findOpenMercatoEndpointOption,
+  getCurrentOpenMercatoEndpointOptions,
+  resolveOpenMercatoApiKeyProfile,
+} from './openmercato-call-options'
+import type { OpenMercatoEndpointOption } from './openmercato-call-options-types'
 
 /**
  * Action definition
@@ -19,6 +26,11 @@ export interface ActionContext extends EvaluationContext {
   data?: any
   ruleId?: string
   ruleName?: string
+  tenantId?: string
+  organizationId?: string
+  executedBy?: string | null
+  em?: PostgreSqlEntityManager
+  openMercatoEndpointOptions?: OpenMercatoEndpointOption[]
   [key: string]: any
 }
 
@@ -85,6 +97,19 @@ export interface CallWebhookResult {
   status: 'pending'
 }
 
+export interface CallOpenMercatoResult {
+  type: 'CALL_OPEN_MERCATO'
+  endpoint: string
+  method: string
+  apiKeyId: string
+  status: number
+  statusText: string
+  body: any
+  authenticated: true
+  tenantId: string
+  organizationId: string
+}
+
 export interface EmitEventResult {
   type: 'EMIT_EVENT'
   event: string
@@ -104,6 +129,7 @@ export type ActionHandlerResult =
   | NotifyResult
   | SetFieldResult
   | CallWebhookResult
+  | CallOpenMercatoResult
   | EmitEventResult
 
 /**
@@ -219,6 +245,7 @@ function getActionHandler(actionType: string): ActionHandler {
     NOTIFY: handleNotify,
     SET_FIELD: handleSetField,
     CALL_WEBHOOK: handleCallWebhook,
+    CALL_OPEN_MERCATO: handleCallOpenMercato,
     EMIT_EVENT: handleEmitEvent,
   }
 
@@ -397,6 +424,119 @@ async function handleCallWebhook(
   }
 }
 
+/**
+ * CALL_OPEN_MERCATO action handler
+ */
+async function handleCallOpenMercato(
+  action: Action,
+  context: ActionContext
+): Promise<CallOpenMercatoResult> {
+  const endpoint = String(action.config?.endpoint ?? '').trim()
+  const method = String(action.config?.method ?? '').trim().toUpperCase()
+  const apiKeyId = String(action.config?.apiKeyId ?? '').trim()
+
+  if (!endpoint) {
+    throw new Error('CALL_OPEN_MERCATO action requires an endpoint')
+  }
+  if (!method) {
+    throw new Error('CALL_OPEN_MERCATO action requires an HTTP method')
+  }
+  if (!apiKeyId) {
+    throw new Error('CALL_OPEN_MERCATO action requires an API key profile')
+  }
+
+  const endpointOptions = context.openMercatoEndpointOptions ?? await getCurrentOpenMercatoEndpointOptions()
+  const endpointOption = findOpenMercatoEndpointOption(
+    endpoint,
+    method,
+    endpointOptions,
+  )
+  if (!endpointOption) {
+    throw new Error('CALL_OPEN_MERCATO action requires a currently available /api/* endpoint')
+  }
+
+  const em = context.em
+  if (!em) {
+    throw new Error('CALL_OPEN_MERCATO action requires an EntityManager in action context')
+  }
+
+  const tenantId = context.tenantId ?? context.tenant?.id
+  const organizationId = context.organizationId ?? context.organization?.id
+  if (!tenantId || !organizationId) {
+    throw new Error('CALL_OPEN_MERCATO action requires tenant and organization context')
+  }
+
+  const apiKeyProfile = await resolveOpenMercatoApiKeyProfile(em, apiKeyId, {
+    tenantId,
+    organizationId,
+  })
+  if (!apiKeyProfile) {
+    throw new Error('CALL_OPEN_MERCATO action requires an active API key profile in scope')
+  }
+
+  const roleIds = Array.isArray(apiKeyProfile.rolesJson)
+    ? apiKeyProfile.rolesJson.filter((roleId): roleId is string => typeof roleId === 'string' && roleId.length > 0)
+    : []
+  if (roleIds.length === 0) {
+    throw new Error('CALL_OPEN_MERCATO action requires an API key profile with at least one role')
+  }
+
+  const { withOnetimeApiKey } = await import('../../api_keys/services/apiKeyService')
+  const fullUrl = buildOpenMercatoApiUrl(endpointOption.path)
+  const requestBody = method === 'GET'
+    ? undefined
+    : normalizeOpenMercatoRequestBody(action.config?.body, context)
+
+  return await withOnetimeApiKey(
+    em,
+    {
+      name: `__business_rule_${context.ruleId || 'unknown'}__`,
+      description: `One-time key for business rule ${context.ruleId || 'unknown'}`,
+      tenantId,
+      organizationId,
+      roles: roleIds,
+      createdBy: null,
+      expiresAt: null,
+    },
+    async (apiKeySecret) => {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'Authorization': `apikey ${apiKeySecret}`,
+        'X-Tenant-Id': tenantId,
+        'X-Organization-Id': organizationId,
+      }
+      if (context.ruleId) headers['X-Business-Rule-Id'] = context.ruleId
+      if (context.ruleName) headers['X-Business-Rule-Name'] = context.ruleName
+      if (context.entityType) headers['X-Business-Rule-Entity-Type'] = context.entityType
+      if (context.entityId) headers['X-Business-Rule-Entity-Id'] = context.entityId
+
+      const response = await fetch(fullUrl, {
+        method,
+        headers,
+        body: requestBody === undefined ? undefined : JSON.stringify(requestBody),
+      })
+
+      const responseBody = await parseOpenMercatoResponseBody(response)
+      if (!response.ok) {
+        throwOpenMercatoResponseError(response.status)
+      }
+
+      return {
+        type: 'CALL_OPEN_MERCATO',
+        endpoint: endpointOption.path,
+        method,
+        apiKeyId,
+        status: response.status,
+        statusText: response.statusText,
+        body: responseBody,
+        authenticated: true,
+        tenantId,
+        organizationId,
+      }
+    },
+  )
+}
+
 /**
  * EMIT_EVENT action handler
  */
@@ -454,3 +594,61 @@ function resolveValue(value: any, context: ActionContext): any {
 
   return value
 }
+
+function buildOpenMercatoApiUrl(endpoint: string): string {
+  if (!endpoint.startsWith('/api/')) {
+    throw new Error(`CALL_OPEN_MERCATO only supports /api/* paths, got: ${endpoint}`)
+  }
+  const appUrl = (process.env.APP_URL || 'http://localhost:3000').replace(/\/$/, '')
+  return `${appUrl}${endpoint}`
+}
+
+function normalizeOpenMercatoRequestBody(value: any, context: ActionContext): any {
+  if (value === undefined || value === null || value === '') return undefined
+  const interpolated = interpolateActionValue(value, context)
+  if (typeof interpolated !== 'string') return interpolated
+
+  const trimmed = interpolated.trim()
+  if (!trimmed) return undefined
+
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    return interpolated
+  }
+}
+
+function interpolateActionValue(value: any, context: ActionContext): any {
+  if (typeof value === 'string') {
+    return interpolateMessage(value, context)
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => interpolateActionValue(item, context))
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, interpolateActionValue(entry, context)]),
+    )
+  }
+  return value
+}
+
+async function parseOpenMercatoResponseBody(response: Response): Promise<any> {
+  const contentType = response.headers.get('content-type')
+  try {
+    if (contentType && contentType.includes('application/json')) {
+      return await response.json()
+    }
+    return await response.text()
+  } catch {
+    return null
+  }
+}
+
+function throwOpenMercatoResponseError(status: number): never {
+  const error: Error & { retriable?: boolean } = new Error(`CALL_OPEN_MERCATO request failed with status ${status}`)
+  if (status >= 500) {
+    error.retriable = true
+  }
+  throw error
+}

package/src/modules/business_rules/lib/openmercato-call-options-types.ts

@@ -0,0 +1,31 @@
+export const OPENMERCATO_CALL_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+
+export type OpenMercatoCallMethod = (typeof OPENMERCATO_CALL_METHODS)[number]
+
+export type OpenMercatoEndpointOption = {
+  id: string
+  path: string
+  method: OpenMercatoCallMethod
+  label: string
+  summary: string | null
+  operationId: string | null
+}
+
+export type OpenMercatoApiKeyRoleOption = {
+  id: string
+  name: string | null
+}
+
+export type OpenMercatoApiKeyOption = {
+  id: string
+  name: string
+  keyPrefix: string
+  organizationId: string | null
+  organizationName: string | null
+  roles: OpenMercatoApiKeyRoleOption[]
+}
+
+export type OpenMercatoCallOptionsResponse = {
+  endpoints: OpenMercatoEndpointOption[]
+  apiKeys: OpenMercatoApiKeyOption[]
+}

package/src/modules/business_rules/lib/openmercato-call-options.ts

@@ -0,0 +1,297 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  getApiRouteManifests,
+  type ApiRouteManifestEntry,
+  type Module,
+} from '@open-mercato/shared/modules/registry'
+import { getModules } from '@open-mercato/shared/lib/modules/registry'
+import { buildOpenApiDocument } from '@open-mercato/shared/lib/openapi'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { ApiKey } from '../../api_keys/data/entities'
+import { Role } from '../../auth/data/entities'
+import { Organization } from '../../directory/data/entities'
+import {
+  OPENMERCATO_CALL_METHODS,
+  type OpenMercatoApiKeyOption,
+  type OpenMercatoCallMethod,
+  type OpenMercatoEndpointOption,
+} from './openmercato-call-options-types'
+
+export type OpenMercatoCallScope = {
+  tenantId: string
+  organizationId?: string | null
+}
+
+const METHOD_ORDER = new Map<string, number>(
+  OPENMERCATO_CALL_METHODS.map((method, index) => [method, index]),
+)
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+function isOpenMercatoCallMethod(value: string): value is OpenMercatoCallMethod {
+  return OPENMERCATO_CALL_METHODS.includes(value as OpenMercatoCallMethod)
+}
+
+function hasPathSegment(path: string, segment: string): boolean {
+  return path.split('/').some((part) => part === segment)
+}
+
+function shouldExposeEndpoint(path: string, method: string, operation: Record<string, any>): boolean {
+  if (!isOpenMercatoCallMethod(method.toUpperCase())) return false
+  if (!path.startsWith('/api/')) return false
+  if (path.includes('{')) return false
+  if (path.includes('[')) return false
+  if (path.startsWith('/api/docs')) return false
+  if (hasPathSegment(path, 'options')) return false
+  if (path === '/api/business_rules/openmercato-call-options') return false
+  if (operation.deprecated === true) return false
+  return true
+}
+
+export function dedupeOpenMercatoEndpointOptions(
+  options: OpenMercatoEndpointOption[],
+): OpenMercatoEndpointOption[] {
+  const deduped = new Map<string, OpenMercatoEndpointOption>()
+
+  for (const option of options) {
+    const existing = deduped.get(option.id)
+    if (!existing) {
+      deduped.set(option.id, option)
+      continue
+    }
+
+    if ((!existing.summary && option.summary) || (!existing.operationId && option.operationId)) {
+      deduped.set(option.id, {
+        ...existing,
+        label: option.label,
+        summary: option.summary ?? existing.summary,
+        operationId: option.operationId ?? existing.operationId,
+      })
+    }
+  }
+
+  return Array.from(deduped.values())
+}
+
+function sortEndpointOptions(options: OpenMercatoEndpointOption[]): OpenMercatoEndpointOption[] {
+  return dedupeOpenMercatoEndpointOptions(options).sort((a, b) => {
+    const pathCompare = a.path.localeCompare(b.path)
+    if (pathCompare !== 0) return pathCompare
+    return (METHOD_ORDER.get(a.method) ?? 99) - (METHOD_ORDER.get(b.method) ?? 99)
+  })
+}
+
+export function collectOpenMercatoEndpointOptionsFromDocument(doc: { paths?: Record<string, any> }): OpenMercatoEndpointOption[] {
+  const options: OpenMercatoEndpointOption[] = []
+
+  for (const [path, methods] of Object.entries(doc.paths ?? {})) {
+    for (const [rawMethod, operation] of Object.entries(methods ?? {})) {
+      const method = rawMethod.toUpperCase()
+      if (!operation || typeof operation !== 'object') continue
+      if (!shouldExposeEndpoint(path, method, operation as Record<string, any>)) continue
+
+      const typedMethod = method as OpenMercatoCallMethod
+      const summary = typeof (operation as any).summary === 'string' ? (operation as any).summary : null
+      const operationId = typeof (operation as any).operationId === 'string' ? (operation as any).operationId : null
+
+      options.push({
+        id: `${typedMethod} ${path}`,
+        path,
+        method: typedMethod,
+        label: summary ? `${typedMethod} ${path} - ${summary}` : `${typedMethod} ${path}`,
+        summary,
+        operationId,
+      })
+    }
+  }
+
+  return sortEndpointOptions(options)
+}
+
+export function collectOpenMercatoEndpointOptions(modules: Module[]): OpenMercatoEndpointOption[] {
+  return collectOpenMercatoEndpointOptionsFromDocument(buildOpenApiDocument(modules))
+}
+
+function normalizeManifestPath(path: string): string {
+  const prefixed = path.startsWith('/api/') ? path : `/api${path.startsWith('/') ? path : `/${path}`}`
+  return prefixed.replace(/\/+$/, '') || '/api'
+}
+
+function getRouteMethodDoc(routeDoc: OpenApiRouteDoc | undefined, method: OpenMercatoCallMethod): OpenApiMethodDoc | undefined {
+  return routeDoc?.methods?.[method]
+}
+
+async function collectOpenMercatoEndpointOptionsFromApiRouteManifests(
+  routes: ApiRouteManifestEntry[],
+): Promise<OpenMercatoEndpointOption[]> {
+  const options: OpenMercatoEndpointOption[] = []
+
+  for (const route of routes) {
+    const path = normalizeManifestPath(route.path)
+    const candidateMethods = route.methods
+      .map((method) => method.toUpperCase())
+      .filter(isOpenMercatoCallMethod)
+    if (candidateMethods.length === 0) continue
+    if (!path.startsWith('/api/')) continue
+    if (path.includes('[')) continue
+    if (path.startsWith('/api/docs')) continue
+    if (hasPathSegment(path, 'options')) continue
+    if (path === '/api/business_rules/openmercato-call-options') continue
+
+    let routeDoc: OpenApiRouteDoc | undefined
+    try {
+      const routeModule = await route.load()
+      routeDoc = routeModule.openApi as OpenApiRouteDoc | undefined
+    } catch {
+      routeDoc = undefined
+    }
+
+    for (const typedMethod of candidateMethods) {
+      const methodDoc = getRouteMethodDoc(routeDoc, typedMethod)
+      const operation = methodDoc ?? {}
+      if (!shouldExposeEndpoint(path, typedMethod, operation as Record<string, any>)) continue
+
+      const summary = typeof methodDoc?.summary === 'string' ? methodDoc.summary : null
+      const operationId = typeof methodDoc?.operationId === 'string' ? methodDoc.operationId : null
+      options.push({
+        id: `${typedMethod} ${path}`,
+        path,
+        method: typedMethod,
+        label: summary ? `${typedMethod} ${path} - ${summary}` : `${typedMethod} ${path}`,
+        summary,
+        operationId,
+      })
+    }
+  }
+
+  return sortEndpointOptions(options)
+}
+
+export async function getCurrentOpenMercatoEndpointOptions(): Promise<OpenMercatoEndpointOption[]> {
+  try {
+    const moduleOptions = collectOpenMercatoEndpointOptions(getModules())
+    if (moduleOptions.length > 0) return moduleOptions
+  } catch {
+    // The runtime app route registry is the source of truth when modules were not
+    // registered in this package instance.
+  }
+
+  const apiRoutes = getApiRouteManifests()
+  if (apiRoutes.length === 0) return []
+  return collectOpenMercatoEndpointOptionsFromApiRouteManifests(apiRoutes)
+}
+
+export function findOpenMercatoEndpointOption(
+  endpoint: string,
+  method: string,
+  options: OpenMercatoEndpointOption[],
+): OpenMercatoEndpointOption | null {
+  const normalizedMethod = method.trim().toUpperCase()
+  if (!endpoint.startsWith('/api/')) return null
+  if (!isOpenMercatoCallMethod(normalizedMethod)) return null
+  return options.find((option) => option.path === endpoint && option.method === normalizedMethod) ?? null
+}
+
+export async function listOpenMercatoApiKeyOptions(
+  em: EntityManager,
+  scope: OpenMercatoCallScope,
+): Promise<OpenMercatoApiKeyOption[]> {
+  const filters: Record<string, any> = {
+    tenantId: scope.tenantId,
+    deletedAt: null,
+  }
+  if (scope.organizationId) {
+    filters.organizationId = scope.organizationId
+  }
+
+  const keys = (await em.find(ApiKey, filters, { orderBy: { name: 'asc' } })) as ApiKey[]
+  const now = Date.now()
+  const activeKeys = keys.filter((key) => !key.expiresAt || key.expiresAt.getTime() > now)
+
+  const roleIds = new Set<string>()
+  const organizationIds = new Set<string>()
+  for (const key of activeKeys) {
+    if (key.organizationId) organizationIds.add(String(key.organizationId))
+    if (Array.isArray(key.rolesJson)) {
+      for (const roleId of key.rolesJson) roleIds.add(String(roleId))
+    }
+  }
+
+  const [roles, organizations] = await Promise.all([
+    roleIds.size > 0 ? em.find(Role, { id: { $in: Array.from(roleIds) }, deletedAt: null }) : [],
+    organizationIds.size > 0 ? em.find(Organization, { id: { $in: Array.from(organizationIds) } }) : [],
+  ])
+  const roleMap = new Map((roles as Role[]).map((role) => [String(role.id), role.name ?? null]))
+  const orgMap = new Map((organizations as Organization[]).map((org) => [String(org.id), org.name ?? null]))
+
+  return activeKeys.map((key) => ({
+    id: key.id,
+    name: key.name,
+    keyPrefix: key.keyPrefix,
+    organizationId: key.organizationId ?? null,
+    organizationName: key.organizationId ? orgMap.get(String(key.organizationId)) ?? null : null,
+    roles: Array.isArray(key.rolesJson)
+      ? key.rolesJson.map((roleId) => ({
+          id: String(roleId),
+          name: roleMap.get(String(roleId)) ?? null,
+        }))
+      : [],
+  }))
+}
+
+export async function resolveOpenMercatoApiKeyProfile(
+  em: EntityManager,
+  apiKeyId: string,
+  scope: OpenMercatoCallScope,
+): Promise<ApiKey | null> {
+  if (!apiKeyId || typeof apiKeyId !== 'string') return null
+  if (!UUID_RE.test(apiKeyId)) return null
+  const filters: Record<string, any> = {
+    id: apiKeyId,
+    tenantId: scope.tenantId,
+    deletedAt: null,
+  }
+  if (scope.organizationId) {
+    filters.organizationId = scope.organizationId
+  }
+
+  const key = await em.findOne(ApiKey, filters)
+  if (!key) return null
+  if (key.expiresAt && key.expiresAt.getTime() <= Date.now()) return null
+  return key
+}
+
+export async function validateOpenMercatoCallActions(
+  em: EntityManager,
+  actions: unknown,
+  scope: OpenMercatoCallScope,
+  endpointOptions?: OpenMercatoEndpointOption[],
+): Promise<string[]> {
+  if (!Array.isArray(actions) || actions.length === 0) return []
+
+  const errors: string[] = []
+  let availableEndpointOptions = endpointOptions
+  for (const [index, action] of actions.entries()) {
+    if (!action || typeof action !== 'object') continue
+    const typedAction = action as { type?: string; config?: Record<string, any> }
+    if (typedAction.type !== 'CALL_OPEN_MERCATO') continue
+    availableEndpointOptions ??= await getCurrentOpenMercatoEndpointOptions()
+
+    const config = typedAction.config ?? {}
+    const endpoint = typeof config.endpoint === 'string' ? config.endpoint : ''
+    const method = typeof config.method === 'string' ? config.method : ''
+    const apiKeyId = typeof config.apiKeyId === 'string' ? config.apiKeyId : ''
+
+    if (!findOpenMercatoEndpointOption(endpoint, method, availableEndpointOptions)) {
+      errors.push(`Action ${index + 1}: selected OpenMercato endpoint is not available`)
+    }
+
+    const apiKey = await resolveOpenMercatoApiKeyProfile(em, apiKeyId, scope)
+    if (!apiKey) {
+      errors.push(`Action ${index + 1}: selected API key profile is not available`)
+    } else if (!Array.isArray(apiKey.rolesJson) || apiKey.rolesJson.length === 0) {
+      errors.push(`Action ${index + 1}: selected API key profile has no roles`)
+    }
+  }
+
+  return errors
+}

package/src/modules/business_rules/lib/rule-engine.ts

@@ -523,6 +523,10 @@ export async function executeSingleRule(
           data: context.data,
           ruleId: rule.ruleId,
           ruleName: rule.ruleName,
+          tenantId: context.tenantId,
+          organizationId: context.organizationId,
+          executedBy: context.executedBy ?? context.user?.id ?? null,
+          em: em as any,
         }
 
         // Execute actions

package/src/modules/communication_channels/api/post/webhook/[provider]/route.ts

@@ -12,6 +12,7 @@ import type { InboundMessage } from '../../../../lib/adapter'
 import type { InboundProcessorPayload } from '../../../../workers/inbound-processor'
 import type { ReactionInboundJob } from '../../../../lib/reaction-processor-types'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { readBoundedRequestBody, WebhookBodyTooLargeError } from '@open-mercato/shared/lib/webhooks'
 
 const logger = createLogger('communication_channels').child({ component: 'inbound-webhook' })
 
@@ -60,7 +61,15 @@ export async function POST(req: Request, { params }: RouteContext): Promise<Resp
     )
   }
 
-  const rawBody = await req.text()
+  let rawBody: string
+  try {
+    rawBody = await readBoundedRequestBody(req)
+  } catch (error) {
+    if (error instanceof WebhookBodyTooLargeError) {
+      return NextResponse.json({ error: 'Webhook payload too large' }, { status: 413 })
+    }
+    throw error
+  }
   const headers: Record<string, string> = {}
   req.headers.forEach((value, key) => {
     headers[key] = value
@@ -222,6 +231,7 @@ export const openApi = {
       responses: [
         { status: 202, description: 'Webhook accepted for async processing' },
         { status: 401, description: 'Signature verification failed against every candidate channel' },
+        { status: 413, description: 'Webhook payload too large' },
         { status: 404, description: 'Unknown provider' },
       ],
     },

package/src/modules/communication_channels/api/post/webhooks/gmail/route.ts

@@ -13,6 +13,7 @@ import {
   GmailPubSubJwtError,
 } from '../../../../lib/gmail-pubsub-jwt'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { readBoundedRequestBody, WebhookBodyTooLargeError } from '@open-mercato/shared/lib/webhooks'
 
 const logger = createLogger('communication_channels').child({ component: 'gmail-webhook' })
 
@@ -24,13 +25,14 @@ const logger = createLogger('communication_channels').child({ component: 'gmail-
  * header, which we verify against Google's public certs.
  *
  * Validation pipeline:
- *   1. Verify JWT signature, audience (`OM_GMAIL_PUBSUB_AUDIENCE`), and
+ *   1. Bound the raw request body before cryptographic work.
+ *   2. Verify JWT signature, audience (`OM_GMAIL_PUBSUB_AUDIENCE`), and
  *      email claim (`OM_GMAIL_PUBSUB_SERVICE_ACCOUNT_EMAIL`).
- *   2. Decode the Pub/Sub envelope → `{ emailAddress, historyId }`.
- *   3. Look up every active Gmail channel matching `emailAddress`. Multiple
+ *   3. Decode the Pub/Sub envelope → `{ emailAddress, historyId }`.
+ *   4. Look up every active Gmail channel matching `emailAddress`. Multiple
  *      tenants may have the same mailbox connected — we enqueue one sync
  *      job per matching channel (each tenant sees their own data).
- *   4. Return `204 No Content` even when no channels match — returning 4xx
+ *   5. Return `204 No Content` even when no channels match — returning 4xx
  *      would cause Pub/Sub to retry forever on a permanently-orphaned
  *      registration.
  */
@@ -58,6 +60,16 @@ export async function POST(req: Request): Promise<Response> {
     return NextResponse.json({ error: 'webhook not configured' }, { status: 503 })
   }
 
+  let rawBody: string
+  try {
+    rawBody = await readBoundedRequestBody(req)
+  } catch (error) {
+    if (error instanceof WebhookBodyTooLargeError) {
+      return NextResponse.json({ error: 'Webhook payload too large' }, { status: 413 })
+    }
+    return NextResponse.json({ error: 'unreadable_body' }, { status: 400 })
+  }
+
   const verifier = getGmailPubSubVerifier()
   try {
     await verifier.verify({
@@ -76,13 +88,6 @@ export async function POST(req: Request): Promise<Response> {
     throw err
   }
 
-  let rawBody: string
-  try {
-    rawBody = await req.text()
-  } catch {
-    return NextResponse.json({ error: 'unreadable_body' }, { status: 400 })
-  }
-
   let payload: { emailAddress: string; historyId: string | number }
   try {
     payload = decodeGmailPubSubBody(rawBody)
@@ -153,6 +158,7 @@ export const openApi = {
         { status: 400, description: 'Body not a valid Pub/Sub envelope' },
         { status: 401, description: 'Invalid JWT or email claim' },
         { status: 403, description: 'Wrong audience' },
+        { status: 413, description: 'Webhook payload too large' },
         { status: 503, description: 'Webhook not configured / Google certs unreachable' },
       ],
     },