@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4393.1.de282b5dfd

package/src/modules/communication_channels/api/post/test-seed/route.ts

@@ -0,0 +1,267 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { ExternalConversation, MessageChannelLink } from '../../../data/entities'
+import {
+  COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID,
+  type ConnectCredentialChannelInput,
+  type ConnectCredentialChannelResult,
+} from '../../../commands/connect-credential-channel'
+import { emitCommunicationChannelsEvent } from '../../../events'
+import {
+  TEST_SEED_PROVIDER_KEY,
+  ensureTestSeedAdapterRegistered,
+  isTestChannelSeedingEnabled,
+} from '../../../lib/test-seed'
+
+/**
+ * TEST-ONLY channel seeding endpoint.
+ *
+ * Gated by `OM_ENABLE_TEST_CHANNEL_SEEDING` — when the flag is unset (the
+ * production default) every request returns 404, so this route is invisible and
+ * inert in production. See `lib/test-seed.ts` for the full rationale.
+ *
+ * Two actions, both scoped to the caller's tenant/org:
+ *   - `connect-channel`: connect a network-free `__test_seed__` channel owned by
+ *     the caller (delegates to the real connect-credential command so the channel
+ *     persists credentials + lands in `status='connected'`). Enables the outbound
+ *     compose → deliver → `.sent` chain to complete in CI.
+ *   - `emit-inbound`: insert an inbound `MessageChannelLink` (+ a `messages.message`
+ *     row for threading) and emit `communication_channels.message.received` so the
+ *     customers link-channel-message subscriber runs against real Postgres. Enables
+ *     the inbound auto-link tests (TC-CRM-EMAIL-002..005).
+ */
+export const metadata = {
+  path: '/communication_channels/test-seed',
+  POST: {
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_user_channel'],
+  },
+}
+
+const addressObjectSchema = z.object({ address: z.string(), name: z.string().optional() })
+const addressFieldSchema = z.union([
+  z.string(),
+  addressObjectSchema,
+  z.array(z.union([z.string(), addressObjectSchema])),
+])
+
+const connectChannelSchema = z.object({
+  action: z.literal('connect-channel'),
+  displayName: z.string().min(1).max(255).optional(),
+  externalIdentifier: z.string().min(1).max(255).optional(),
+})
+
+const emitInboundSchema = z.object({
+  action: z.literal('emit-inbound'),
+  /** Channel that owns the inbound message; controls authorUserId + default visibility. */
+  channelId: z.string().uuid(),
+  /** Provider key persisted on the link (defaults to the stub provider). */
+  providerKey: z.string().min(1).max(64).optional(),
+  /** Normalized inbound addresses (stored under channelPayload). */
+  from: addressFieldSchema.optional(),
+  to: addressFieldSchema.optional(),
+  cc: addressFieldSchema.optional(),
+  subject: z.string().max(500).optional(),
+  bodyText: z.string().max(200_000).optional(),
+  /** RFC2822 Message-ID of this inbound message (for In-Reply-To matching). */
+  messageId: z.string().max(500).optional(),
+  /** RFC2822 In-Reply-To header (threading-inheritance fallback). */
+  inReplyTo: z.string().max(500).optional(),
+  references: z.array(z.string().max(500)).max(50).optional(),
+  /**
+   * Open Mercato `messages.message` thread id this inbound message belongs to.
+   * When set, a `messages.message` row is created with this `threadId` so the
+   * hub-thread inheritance join can resolve a Person from a sibling message.
+   */
+  messageThreadId: z.string().uuid().optional(),
+})
+
+const bodySchema = z.discriminatedUnion('action', [connectChannelSchema, emitInboundSchema])
+
+export async function POST(req: Request): Promise<Response> {
+  // Fail-closed: invisible in production. Mirrors an unknown route (404) rather
+  // than 403 so the surface leaks nothing when the flag is off.
+  if (!isTestChannelSeedingEnabled()) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: z.infer<typeof bodySchema>
+  try {
+    body = bodySchema.parse(await readJsonSafe(req, null))
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Invalid request body' },
+      { status: 422 },
+    )
+  }
+
+  const container = await createRequestContainer()
+  // Defensive: make sure the stub adapter is registered for this process even if
+  // a worker-only node skipped module di registration.
+  ensureTestSeedAdapterRegistered()
+
+  const tenantId = auth.tenantId as string
+  const organizationId = (auth as { orgId?: string | null }).orgId ?? null
+  const userId = auth.sub as string
+
+  if (body.action === 'connect-channel') {
+    const stamp = Date.now()
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const input: ConnectCredentialChannelInput = {
+      providerKey: TEST_SEED_PROVIDER_KEY,
+      displayName: body.displayName ?? `Test Seed Channel ${stamp}`,
+      credentials: {
+        username: body.externalIdentifier ?? `test-seed-${stamp}@test-seed.local`,
+        fromAddress: body.externalIdentifier ?? `test-seed-${stamp}@test-seed.local`,
+      },
+      userId,
+      scope: { tenantId, organizationId },
+    }
+    const { result } = await commandBus.execute<
+      ConnectCredentialChannelInput,
+      ConnectCredentialChannelResult
+    >(COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID, {
+      input,
+      ctx: {
+        container,
+        auth: auth as never,
+        organizationScope: null,
+        selectedOrganizationId: organizationId,
+        organizationIds: organizationId ? [organizationId] : null,
+      },
+    })
+    if (result.status !== 'connected') {
+      return NextResponse.json(
+        { error: '[internal] test-seed connect failed', detail: result },
+        { status: 500 },
+      )
+    }
+    return NextResponse.json(
+      { channelId: result.channelId, externalIdentifier: result.externalIdentifier },
+      { status: 201 },
+    )
+  }
+
+  // action === 'emit-inbound'
+  const em = (container.resolve('em') as EntityManager).fork()
+  const providerKey = body.providerKey ?? TEST_SEED_PROVIDER_KEY
+
+  // A MessageChannelLink requires a non-null external_conversation_id (FK) and
+  // message_id. Create a synthetic conversation + (optionally threaded) message
+  // so the link is shaped like a real inbound row the subscriber can consume.
+  const conversation = em.create(ExternalConversation, {
+    channelId: body.channelId,
+    externalConversationId: `inbound-seed:${Date.now()}:${Math.random().toString(16).slice(2, 8)}`,
+    subject: body.subject ?? null,
+    tenantId,
+    organizationId,
+    lastMessageAt: new Date(),
+  })
+  em.persist(conversation)
+  await em.flush()
+
+  // Insert the platform `messages.message` row via raw SQL rather than importing
+  // the messages module's entity class (cross-module ORM coupling rule). Only
+  // `thread_id` matters for the hub-thread inheritance join (TC-CRM-EMAIL-005);
+  // the rest satisfy NOT NULL constraints.
+  const messageRows = (await em.getConnection().execute(
+    `INSERT INTO messages
+       (type, thread_id, sender_user_id, subject, body, body_format, priority, status,
+        is_draft, sent_at, visibility, source_entity_type, source_entity_id,
+        tenant_id, organization_id, created_at, updated_at)
+     VALUES
+       (?, ?, ?, ?, ?, 'text', 'normal', 'sent',
+        false, now(), 'public', 'communication_channels.test_seed_inbound', ?,
+        ?, ?, now(), now())
+     RETURNING id`,
+    [
+      `channel.${providerKey}`,
+      body.messageThreadId ?? null,
+      userId,
+      body.subject ?? '(no subject)',
+      body.bodyText ?? '',
+      body.channelId,
+      tenantId,
+      organizationId,
+    ],
+  )) as Array<{ id: string }>
+  const messageId = messageRows[0]?.id
+  if (!messageId) {
+    return NextResponse.json({ error: '[internal] failed to seed message row' }, { status: 500 })
+  }
+
+  const link = em.create(MessageChannelLink, {
+    messageId,
+    externalConversationId: conversation.id,
+    providerKey,
+    channelType: 'email',
+    direction: 'inbound',
+    deliveryStatus: 'delivered',
+    channelPayload: {
+      ...(body.from !== undefined ? { from: body.from } : {}),
+      ...(body.to !== undefined ? { to: body.to } : {}),
+      ...(body.cc !== undefined ? { cc: body.cc } : {}),
+      ...(body.subject !== undefined ? { subject: body.subject } : {}),
+      ...(body.bodyText !== undefined ? { text: body.bodyText } : {}),
+      ...(body.inReplyTo !== undefined ? { inReplyTo: body.inReplyTo } : {}),
+      ...(body.references !== undefined ? { references: body.references } : {}),
+    },
+    channelContentType: 'text/plain',
+    channelMetadata: {
+      ...(body.messageId !== undefined ? { messageId: body.messageId } : {}),
+    },
+    tenantId,
+    organizationId,
+  })
+  em.persist(link)
+  await em.flush()
+
+  // Emit the hub event through the real event bus so the persistent customers
+  // link-channel-message-received subscriber is enqueued to the `events` queue.
+  await emitCommunicationChannelsEvent(
+    'communication_channels.message.received',
+    {
+      channelLinkId: link.id,
+      channelId: body.channelId,
+      providerKey,
+      direction: 'inbound',
+      tenantId,
+      organizationId,
+    },
+    { persistent: true },
+  )
+
+  return NextResponse.json(
+    { channelLinkId: link.id, messageId, conversationId: conversation.id },
+    { status: 201 },
+  )
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Test-only: seed a connected channel or emit an inbound message (env-gated)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 201, description: 'Channel seeded / inbound message emitted' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Test channel seeding disabled (production default)' },
+        { status: 422, description: 'Invalid request body' },
+        { status: 500, description: 'Seed failed' },
+      ],
+    },
+  },
+}
+
+export default POST

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

@@ -0,0 +1,227 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CommunicationChannel } from '../../../../data/entities'
+import { getChannelAdapterRegistry } from '../../../../lib/adapter-registry-singleton'
+import {
+  COMMUNICATION_CHANNELS_QUEUES,
+  getCommunicationChannelsQueue,
+} from '../../../../lib/queue'
+import type { InboundMessage } from '../../../../lib/adapter'
+import type { InboundProcessorPayload } from '../../../../workers/inbound-processor'
+import type { ReactionInboundJob } from '../../../../lib/reaction-processor-types'
+
+/**
+ * Inbound webhook endpoint for the communication_channels hub.
+ *
+ * One endpoint per provider — provider key in the path. The hub iterates all
+ * candidate `CommunicationChannel` rows for `(provider_key, is_active=true,
+ * deleted_at IS NULL)` across tenants and asks each adapter to verify the
+ * signature with that channel's credentials. The first successful verification
+ * pins the request to that channel's tenant scope; we then enqueue an inbound
+ * processor job and return 202.
+ *
+ * Fail-closed: if no candidate verifies, we return 401 — never 200. This mirrors
+ * the per-tenant authentication model used by `shipping_carriers/api/webhook/[provider]`
+ * and the security note in SPEC-045d §13.
+ *
+ * No auth required at the route level — signature verification IS the auth.
+ */
+export const metadata = {
+  path: '/communication_channels/webhook/[provider]',
+  POST: {
+    requireAuth: false,
+    // Unauthenticated by design (signature verification IS the auth), but the
+    // handler fans out an O(N) cross-tenant candidate scan, so bound per-IP
+    // request volume to limit abuse. Generous enough for real provider traffic;
+    // the dedicated gmail route carries its own matching limits.
+    rateLimit: { points: 120, duration: 60, keyPrefix: 'cc_webhook_inbound' },
+  },
+}
+
+type RouteContext = {
+  params: Promise<{ provider: string }> | { provider: string }
+}
+
+export async function POST(req: Request, { params }: RouteContext): Promise<Response> {
+  const resolvedParams = await params
+  const providerKey = resolvedParams.provider
+
+  const registry = getChannelAdapterRegistry()
+  const adapter = registry?.get(providerKey)
+  if (!adapter) {
+    return NextResponse.json(
+      { error: `No ChannelAdapter for provider: ${providerKey}` },
+      { status: 404 },
+    )
+  }
+
+  const rawBody = await req.text()
+  const headers: Record<string, string> = {}
+  req.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+
+  type CredentialsServiceLike = {
+    resolve: (
+      providerOrIntegrationId: string,
+      scope: { organizationId: string; tenantId: string; userId?: string | null },
+    ) => Promise<Record<string, unknown> | null>
+  }
+  let credentialsService: CredentialsServiceLike | null = null
+  try {
+    credentialsService = container.resolve<CredentialsServiceLike>('integrationCredentialsService')
+  } catch {
+    credentialsService = null
+  }
+
+  try {
+    // The webhook is unauthenticated. The TENANT MUST be derived from a channel whose
+    // per-tenant credentials successfully verify the inbound signature — NEVER from
+    // attacker-controlled payload headers or unsigned retries.
+    const candidates = await findWithDecryption(
+      em,
+      CommunicationChannel,
+      {
+        providerKey,
+        isActive: true,
+        deletedAt: null,
+      },
+      { orderBy: { createdAt: 'desc' } },
+    )
+
+    let matchedChannel: CommunicationChannel | null = null
+    let matchedScope: { tenantId: string; organizationId: string } | null = null
+    let event: InboundMessage | null = null
+    let lastVerificationError: unknown = null
+
+    for (const candidate of candidates as CommunicationChannel[]) {
+      const candidateScope = {
+        tenantId: candidate.tenantId,
+        organizationId: candidate.organizationId ?? candidate.tenantId,
+      }
+      // Per-user credential lookup: each candidate channel has its own user
+      // and therefore its own credentials row. See review R2-C1 / N1.
+      const credentialsLookupScope = {
+        ...candidateScope,
+        userId: candidate.userId ?? null,
+      }
+      let credentials: Record<string, unknown> = {}
+      if (candidate.credentialsRef && credentialsService) {
+        try {
+          credentials =
+            (await credentialsService.resolve(`channel_${providerKey}`, credentialsLookupScope)) ?? {}
+        } catch {
+          credentials = {}
+        }
+      }
+      try {
+        event = await adapter.verifyWebhook({
+          rawBody,
+          headers,
+          credentials,
+          scope: candidateScope,
+        })
+        matchedChannel = candidate
+        matchedScope = candidateScope
+        break
+      } catch (error: unknown) {
+        lastVerificationError = error
+      }
+    }
+
+    if (!event || !matchedChannel || !matchedScope) {
+      throw (
+        lastVerificationError ?? new Error('Webhook verification failed: no matching channel')
+      )
+    }
+
+    // Dispatch by event type:
+    //   - 'message' (default) → inbound-processor (slice 2b)
+    //   - 'reaction'           → reaction-processor (slice 2d)
+    //   - 'status_update' / 'other' → 202 not handled (future slice)
+    if (event.eventType === 'reaction') {
+      if (typeof adapter.normalizeInboundReaction !== 'function') {
+        return NextResponse.json(
+          {
+            received: true,
+            queued: false,
+            reason: `adapter '${providerKey}' does not implement normalizeInboundReaction`,
+          },
+          { status: 202 },
+        )
+      }
+      const reactionEvent = await adapter.normalizeInboundReaction(event)
+      const reactionJob: ReactionInboundJob = {
+        kind: 'inbound',
+        providerKey,
+        channelId: matchedChannel.id,
+        channelType: matchedChannel.channelType,
+        event: reactionEvent,
+        // Use the channel's REAL org (null when null), matching the poll and
+        // dedicated gmail webhook path — `candidateScope` falls org
+        // back to tenantId for credential/verify lookups, which must not leak
+        // into the ingest scope (it would diverge dedup for null-org channels).
+        scope: { tenantId: matchedScope.tenantId, organizationId: matchedChannel.organizationId ?? null },
+        attempt: 1,
+      }
+      const reactionsQueue = getCommunicationChannelsQueue(COMMUNICATION_CHANNELS_QUEUES.reactions)
+      await reactionsQueue.enqueue(reactionJob as unknown as Record<string, unknown>)
+      return NextResponse.json({ received: true, queued: true, kind: 'reaction' }, { status: 202 })
+    }
+
+    if (event.eventType && event.eventType !== 'message') {
+      return NextResponse.json(
+        {
+          received: true,
+          queued: false,
+          reason: `event ${event.eventType} not yet handled`,
+        },
+        { status: 202 },
+      )
+    }
+
+    const queue = getCommunicationChannelsQueue(COMMUNICATION_CHANNELS_QUEUES.inbound)
+    const jobPayload: InboundProcessorPayload = {
+      providerKey,
+      channelId: matchedChannel.id,
+      channelType: matchedChannel.channelType,
+      raw: event,
+      // Ingest scope uses the channel's REAL org (null when null) so dedup matches
+      // the poll + dedicated webhook paths; see the reaction branch above.
+      scope: { tenantId: matchedScope.tenantId, organizationId: matchedChannel.organizationId ?? null },
+    }
+    await queue.enqueue(jobPayload as unknown as Record<string, unknown>)
+
+    return NextResponse.json({ received: true, queued: true, kind: 'message' }, { status: 202 })
+  } catch (error: unknown) {
+    // Do not echo adapter/verification internals to an unauthenticated caller;
+    // log the detail server-side and return a fixed, minimal message.
+    console.warn(
+      '[communication_channels] inbound webhook verification failed:',
+      error instanceof Error ? error.message : error,
+    )
+    return NextResponse.json({ error: 'verification_failed' }, { status: 401 })
+  }
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  summary: 'Receive a communication channel webhook',
+  methods: {
+    POST: {
+      summary: 'Process an inbound channel webhook (Slack, WhatsApp, Email, ...)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 202, description: 'Webhook accepted for async processing' },
+        { status: 401, description: 'Signature verification failed against every candidate channel' },
+        { status: 404, description: 'Unknown provider' },
+      ],
+    },
+  },
+}
+export default POST

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

@@ -0,0 +1,161 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CommunicationChannel } from '../../../../data/entities'
+import {
+  COMMUNICATION_CHANNELS_QUEUES,
+  getCommunicationChannelsQueue,
+} from '../../../../lib/queue'
+import {
+  decodeGmailPubSubBody,
+  getGmailPubSubVerifier,
+  GmailPubSubJwtError,
+} from '../../../../lib/gmail-pubsub-jwt'
+
+/**
+ * Spec C § Phase C2 — Gmail Pub/Sub push webhook.
+ *
+ * Auth model: NOT authenticated via the platform's session cookie. Pub/Sub
+ * authenticates with a Google-signed JWT in the `Authorization: Bearer …`
+ * header, which we verify against Google's public certs.
+ *
+ * Validation pipeline:
+ *   1. 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
+ *      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
+ *      would cause Pub/Sub to retry forever on a permanently-orphaned
+ *      registration.
+ */
+export const metadata = {
+  path: '/communication_channels/webhooks/gmail',
+  // Unauthenticated at the platform layer (a Google-signed JWT is the auth).
+  // Rate-limited so a caller can't drive unbounded JWT-verification +
+  // cert-fetch work before the signature gate rejects them.
+  POST: { requireAuth: false, rateLimit: { points: 120, duration: 60, keyPrefix: 'cc_webhook_gmail' } },
+}
+
+type GmailHistorySyncJobPayload = {
+  channelId: string
+  scope: { tenantId: string; organizationId: string | null }
+  notification: { emailAddress: string; historyId: string }
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const expectedAudience = process.env.OM_GMAIL_PUBSUB_AUDIENCE
+  const expectedEmail = process.env.OM_GMAIL_PUBSUB_SERVICE_ACCOUNT_EMAIL
+  if (!expectedAudience || !expectedEmail) {
+    // Misconfiguration is operator-facing; log and 503 so Pub/Sub retries
+    // briefly and the operator notices.
+    console.error(
+      '[gmail-webhook] OM_GMAIL_PUBSUB_AUDIENCE / OM_GMAIL_PUBSUB_SERVICE_ACCOUNT_EMAIL not set',
+    )
+    return NextResponse.json({ error: 'webhook not configured' }, { status: 503 })
+  }
+
+  const verifier = getGmailPubSubVerifier()
+  try {
+    await verifier.verify({
+      authorizationHeader: req.headers.get('authorization'),
+      expectedAudience,
+      expectedEmail,
+    })
+  } catch (err) {
+    if (err instanceof GmailPubSubJwtError) {
+      const status =
+        err.code === 'wrong_audience' ? 403 :
+        err.code === 'fetch_certs_failed' ? 503 :
+        401
+      return NextResponse.json({ error: err.code, message: err.message }, { status })
+    }
+    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)
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'invalid_payload' },
+      { status: 400 },
+    )
+  }
+
+  // Channel lookup is intentionally NOT tenant-scoped here — we don't have a
+  // tenant signal beyond the email address. We enumerate matching channels
+  // across all tenants and enqueue one sync job per match. Each job carries
+  // its own tenant scope, so downstream ingest stays tenant-isolated.
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  const channels = await findWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      providerKey: 'gmail',
+      externalIdentifier: payload.emailAddress,
+      isActive: true,
+      deletedAt: null,
+    },
+  )
+  if (channels.length === 0) {
+    // Return 204 anyway — see route header comment.
+    return new NextResponse(null, { status: 204 })
+  }
+
+  const queue = getCommunicationChannelsQueue(
+    COMMUNICATION_CHANNELS_QUEUES.gmailHistorySync,
+  )
+  for (const channel of channels) {
+    const job: GmailHistorySyncJobPayload = {
+      channelId: channel.id,
+      scope: {
+        tenantId: channel.tenantId,
+        organizationId: channel.organizationId ?? null,
+      },
+      notification: {
+        emailAddress: payload.emailAddress,
+        historyId: String(payload.historyId),
+      },
+    }
+    try {
+      await queue.enqueue(job as unknown as Record<string, unknown>)
+    } catch (err) {
+      console.error(
+        `[gmail-webhook] failed to enqueue history-sync for channel ${channel.id}:`,
+        err,
+      )
+    }
+  }
+
+  return new NextResponse(null, { status: 204 })
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Gmail Pub/Sub push notification webhook (Spec C § Phase C2)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 204, description: 'Notification verified + history-sync job enqueued' },
+        { status: 400, description: 'Body not a valid Pub/Sub envelope' },
+        { status: 401, description: 'Invalid JWT or email claim' },
+        { status: 403, description: 'Wrong audience' },
+        { status: 503, description: 'Webhook not configured / Google certs unreachable' },
+      ],
+    },
+  },
+}
+
+export default POST