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

package/src/modules/communication_channels/lib/gmail-pubsub-jwt.ts

@@ -0,0 +1,278 @@
+import crypto from 'node:crypto'
+
+/**
+ * Spec C § Phase C2 — Verify a Gmail Pub/Sub push request.
+ *
+ * Pub/Sub push subscriptions authenticate with a Google-signed RS256 JWT
+ * passed in the `Authorization: Bearer …` header. The token's claims contain
+ *   - `iss`: `https://accounts.google.com`
+ *   - `aud`: the configured audience (typically the webhook URL)
+ *   - `email`: the publishing service-account address (e.g.
+ *     `gmail-api-push@system.gserviceaccount.com` for Gmail watch)
+ *   - `email_verified: true`
+ *
+ * The default verifier downloads Google's public x509 certs and caches them
+ * for an hour. Tests inject a mock verifier via `setGmailPubSubVerifier(...)`.
+ */
+
+const GOOGLE_CERTS_URL = 'https://www.googleapis.com/oauth2/v1/certs'
+const CERT_CACHE_TTL_MS = 60 * 60 * 1000
+const CERT_FETCH_TIMEOUT_MS = 5000
+// Google mints OIDC tokens with one of these two issuer strings.
+const GOOGLE_ACCEPTED_ISSUERS = new Set(['https://accounts.google.com', 'accounts.google.com'])
+
+export interface GmailPubSubJwtClaims {
+  iss: string
+  aud: string | string[]
+  email?: string
+  emailVerified?: boolean
+  exp: number
+  iat: number
+  sub?: string
+}
+
+export interface GmailPubSubVerifyInput {
+  authorizationHeader: string | null | undefined
+  expectedAudience: string
+  expectedEmail: string
+}
+
+export interface GmailPubSubVerifier {
+  verify(input: GmailPubSubVerifyInput): Promise<GmailPubSubJwtClaims>
+}
+
+export class GmailPubSubJwtError extends Error {
+  readonly code: 'missing_token' | 'invalid_format' | 'invalid_signature' | 'expired' | 'wrong_issuer' | 'wrong_audience' | 'wrong_email' | 'fetch_certs_failed'
+  constructor(message: string, code: GmailPubSubJwtError['code']) {
+    super(message)
+    this.name = 'GmailPubSubJwtError'
+    this.code = code
+  }
+}
+
+interface CertCacheEntry {
+  certs: Record<string, string>
+  fetchedAt: number
+}
+
+class FetchGmailPubSubVerifier implements GmailPubSubVerifier {
+  private certCache: CertCacheEntry | null = null
+
+  async verify(input: GmailPubSubVerifyInput): Promise<GmailPubSubJwtClaims> {
+    const token = extractBearer(input.authorizationHeader)
+    if (!token) throw new GmailPubSubJwtError('Missing Authorization bearer token', 'missing_token')
+
+    const parts = token.split('.')
+    if (parts.length !== 3) {
+      throw new GmailPubSubJwtError('JWT must have three dot-separated parts', 'invalid_format')
+    }
+    const [headerB64, payloadB64, signatureB64] = parts
+    let header: Record<string, unknown>
+    let claims: GmailPubSubJwtClaims
+    try {
+      header = JSON.parse(Buffer.from(headerB64, 'base64url').toString('utf-8')) as Record<string, unknown>
+      claims = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf-8')) as GmailPubSubJwtClaims
+    } catch {
+      throw new GmailPubSubJwtError('JWT header/payload not parseable', 'invalid_format')
+    }
+    const kid = typeof header.kid === 'string' ? header.kid : null
+    const alg = typeof header.alg === 'string' ? header.alg : null
+    if (!kid || alg !== 'RS256') {
+      throw new GmailPubSubJwtError(`Unsupported JWT alg/kid: alg=${alg ?? '?'} kid=${kid ?? '?'}`, 'invalid_format')
+    }
+
+    const certs = await this.getCerts()
+    const cert = certs[kid]
+    if (!cert) {
+      // Cert rotated; refetch once and retry.
+      this.certCache = null
+      const refreshed = await this.getCerts()
+      const fresh = refreshed[kid]
+      if (!fresh) throw new GmailPubSubJwtError(`No cert for kid=${kid}`, 'invalid_signature')
+      verifySignature(`${headerB64}.${payloadB64}`, signatureB64, fresh)
+    } else {
+      verifySignature(`${headerB64}.${payloadB64}`, signatureB64, cert)
+    }
+
+    validateClaims(claims, input)
+    return claims
+  }
+
+  private async getCerts(): Promise<Record<string, string>> {
+    if (this.certCache && Date.now() - this.certCache.fetchedAt < CERT_CACHE_TTL_MS) {
+      return this.certCache.certs
+    }
+    let res: Response
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), CERT_FETCH_TIMEOUT_MS)
+    try {
+      res = await fetch(GOOGLE_CERTS_URL, { signal: controller.signal })
+    } catch (err) {
+      throw new GmailPubSubJwtError(
+        `Failed to fetch Google certs: ${err instanceof Error ? err.message : String(err)}`,
+        'fetch_certs_failed',
+      )
+    } finally {
+      clearTimeout(timer)
+    }
+    if (!res.ok) {
+      throw new GmailPubSubJwtError(`Google certs endpoint returned ${res.status}`, 'fetch_certs_failed')
+    }
+    let parsed: unknown
+    try {
+      parsed = await res.json()
+    } catch (err) {
+      throw new GmailPubSubJwtError(
+        `Google certs endpoint returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        'fetch_certs_failed',
+      )
+    }
+    const certs = toCertMap(parsed)
+    if (!certs) {
+      // Never cache an empty/malformed payload — a single bad 200 would otherwise
+      // disable Gmail push verification for the whole CERT_CACHE_TTL_MS window.
+      throw new GmailPubSubJwtError('Google certs endpoint returned an unexpected shape', 'fetch_certs_failed')
+    }
+    this.certCache = { certs, fetchedAt: Date.now() }
+    return certs
+  }
+}
+
+/**
+ * Validates that a parsed Google certs response is a non-empty `kid → PEM` map.
+ * Returns the typed map on success, or `null` when the shape is unusable so the
+ * caller can fail closed instead of caching garbage.
+ */
+function toCertMap(value: unknown): Record<string, string> | null {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return null
+  const entries = Object.entries(value as Record<string, unknown>)
+  if (entries.length === 0) return null
+  const certs: Record<string, string> = {}
+  for (const [kid, pem] of entries) {
+    if (typeof pem !== 'string' || pem.length === 0) return null
+    certs[kid] = pem
+  }
+  return certs
+}
+
+function extractBearer(header: string | null | undefined): string | null {
+  if (!header) return null
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim())
+  return match ? match[1].trim() : null
+}
+
+function verifySignature(input: string, signatureB64: string, cert: string): void {
+  const verifier = crypto.createVerify('RSA-SHA256')
+  verifier.update(input)
+  verifier.end()
+  const signature = Buffer.from(signatureB64, 'base64url')
+  const ok = verifier.verify(cert, signature)
+  if (!ok) {
+    throw new GmailPubSubJwtError('JWT signature verification failed', 'invalid_signature')
+  }
+}
+
+function validateClaims(claims: GmailPubSubJwtClaims, input: GmailPubSubVerifyInput): void {
+  const now = Math.floor(Date.now() / 1000)
+  // Fail closed: a token without a numeric `exp` has no expiry, so a captured
+  // push JWT could otherwise be replayed indefinitely. Require `exp` and reject
+  // anything already past it (with a small clock-skew allowance).
+  if (typeof claims.exp !== 'number' || claims.exp < now - 5) {
+    throw new GmailPubSubJwtError('JWT expired or missing exp', 'expired')
+  }
+  // Reject a future-dated `iat` beyond the clock-skew allowance: a token
+  // "issued" in the future signals a forged token or a badly-skewed clock.
+  // Reuses the `expired` code (both are temporal-validity failures → 401).
+  if (typeof claims.iat === 'number' && claims.iat > now + 5) {
+    throw new GmailPubSubJwtError('JWT issued in the future', 'expired')
+  }
+  // Verify the issuer is Google (defense-in-depth alongside the signature +
+  // service-account email checks; the file header documents this requirement).
+  if (typeof claims.iss !== 'string' || !GOOGLE_ACCEPTED_ISSUERS.has(claims.iss)) {
+    throw new GmailPubSubJwtError(
+      `JWT issuer not accepted (got ${typeof claims.iss === 'string' ? claims.iss : 'none'})`,
+      'wrong_issuer',
+    )
+  }
+  const audOk = Array.isArray(claims.aud)
+    ? claims.aud.includes(input.expectedAudience)
+    : claims.aud === input.expectedAudience
+  if (!audOk) {
+    throw new GmailPubSubJwtError(
+      `JWT audience mismatch (expected ${input.expectedAudience})`,
+      'wrong_audience',
+    )
+  }
+  // Google uses `email_verified` in the wire format; our type uses camelCase.
+  // Accept either to be defensive.
+  const emailVerified =
+    claims.emailVerified === true ||
+    (claims as unknown as { email_verified?: boolean }).email_verified === true
+  if (!emailVerified || claims.email !== input.expectedEmail) {
+    throw new GmailPubSubJwtError(
+      `JWT email mismatch (expected ${input.expectedEmail})`,
+      'wrong_email',
+    )
+  }
+}
+
+let cachedVerifier: GmailPubSubVerifier | null = null
+
+export function getGmailPubSubVerifier(): GmailPubSubVerifier {
+  if (!cachedVerifier) cachedVerifier = new FetchGmailPubSubVerifier()
+  return cachedVerifier
+}
+
+export function setGmailPubSubVerifier(verifier: GmailPubSubVerifier | null): void {
+  cachedVerifier = verifier
+}
+
+/**
+ * Decode a Pub/Sub envelope from the webhook body.
+ *
+ * Shape: `{ message: { data: base64<JSON>, messageId, publishTime, attributes }, subscription }`.
+ *
+ * Gmail's payload (`data` field) decodes to `{ emailAddress, historyId }`.
+ */
+export interface PubSubEnvelope {
+  message: {
+    data: string
+    messageId: string
+    publishTime?: string
+    attributes?: Record<string, string>
+  }
+  subscription?: string
+}
+
+export interface GmailPushPayload {
+  emailAddress: string
+  historyId: string | number
+}
+
+export function decodeGmailPubSubBody(rawBody: string): GmailPushPayload {
+  let envelope: PubSubEnvelope
+  try {
+    envelope = JSON.parse(rawBody) as PubSubEnvelope
+  } catch {
+    throw new GmailPubSubJwtError('Body is not valid JSON', 'invalid_format')
+  }
+  if (!envelope.message?.data) {
+    throw new GmailPubSubJwtError('Envelope missing message.data', 'invalid_format')
+  }
+  let payloadText: string
+  try {
+    payloadText = Buffer.from(envelope.message.data, 'base64').toString('utf-8')
+  } catch {
+    throw new GmailPubSubJwtError('message.data not base64 decodable', 'invalid_format')
+  }
+  let payload: GmailPushPayload
+  try {
+    payload = JSON.parse(payloadText) as GmailPushPayload
+  } catch {
+    throw new GmailPubSubJwtError('message.data JSON not parseable', 'invalid_format')
+  }
+  if (!payload.emailAddress || payload.historyId === undefined) {
+    throw new GmailPubSubJwtError('message.data missing emailAddress or historyId', 'invalid_format')
+  }
+  return payload
+}

package/src/modules/communication_channels/lib/mutation-guards.ts

@@ -0,0 +1,215 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  CommunicationChannel,
+  ExternalConversation,
+  ExternalMessage,
+  MessageChannelLink,
+} from '../data/entities'
+
+/**
+ * Hub-side mutation guards (Phase 4 of the email integration spec).
+ *
+ * These guards are plain functions that any caller (CRUD route, command,
+ * subscriber) can invoke to enforce hub invariants before mutating state.
+ * They throw `ChannelMutationBlockedError` on violations so the caller can
+ * map the error to an HTTP 4xx (typically 422) without leaking internals.
+ *
+ * Why functions, not the generic `validateCrudMutationGuard`:
+ *   The hub's writes are channel-shaped rather than entity-shaped — "deleting a
+ *   channel with unread inbound" is not a per-entity invariant the generic
+ *   CRUD guard layer can express. These functions encode hub semantics directly
+ *   and stay invocation-site agnostic.
+ */
+
+export type ChannelMutationGuardReason =
+  | 'channel_has_inbound_history'
+  | 'channel_requires_reauth'
+  | 'channel_disconnected'
+  | 'channel_not_found'
+  /**
+   * @deprecated Use `channel_has_inbound_history`. Kept for one minor release
+   * so external callers/tests catch a transition window. Round-2 F8 rename.
+   */
+  | 'channel_has_unread_inbound'
+
+export class ChannelMutationBlockedError extends Error {
+  readonly reason: ChannelMutationGuardReason
+  readonly channelId: string
+  /** Field-level error message keyed by `channelId` — for `createCrudFormError`. */
+  readonly errors: Record<string, string>
+
+  constructor(reason: ChannelMutationGuardReason, channelId: string, message: string) {
+    super(message)
+    this.name = 'ChannelMutationBlockedError'
+    this.reason = reason
+    this.channelId = channelId
+    this.errors = { channelId: message }
+  }
+}
+
+export interface ChannelScope {
+  tenantId: string
+  organizationId?: string | null
+}
+
+export interface GuardChannelDeleteInput {
+  channelId: string
+  scope: ChannelScope
+  /** Bypass the unread-inbound check; used by admin "force delete" actions. */
+  force?: boolean
+}
+
+/**
+ * Guard `channel.delete`.
+ *
+ * Blocks when the channel still has ANY inbound `MessageChannelLink` rows.
+ * Implementation note: the hub doesn't track per-message read state — that
+ * lives on the messages module's `MessageRecipient.read_at`. Counting unread
+ * across the module boundary would require either raw cross-module SQL
+ * (forbidden by AGENTS.md) or a QueryEngine round-trip per delete. We pick
+ * the simpler safety contract: block delete when ANY inbound link exists,
+ * with `force: true` as the escape hatch.
+ *
+ * Pass `force: true` to bypass — exposed to admins so they can hard-delete a
+ * channel whose mailbox they no longer care about (e.g. ex-employee
+ * offboarding).
+ */
+export async function guardChannelDelete(
+  em: EntityManager,
+  input: GuardChannelDeleteInput,
+): Promise<void> {
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id: input.channelId,
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+      deletedAt: null,
+    },
+    undefined,
+    input.scope,
+  )
+  if (!channel) {
+    throw new ChannelMutationBlockedError(
+      'channel_not_found',
+      input.channelId,
+      'Channel not found in this tenant scope.',
+    )
+  }
+  if (input.force) return
+
+  const inboundCount = await countInboundLinksForChannel(em, input.channelId, input.scope)
+  if (inboundCount > 0) {
+    throw new ChannelMutationBlockedError(
+      'channel_has_inbound_history',
+      input.channelId,
+      `Channel has ${inboundCount} inbound message${inboundCount === 1 ? '' : 's'} in history. Pass force=true to delete anyway.`,
+    )
+  }
+}
+
+export interface GuardOutboundCreateInput {
+  channelId: string
+  scope: ChannelScope
+}
+
+/**
+ * Guard `message.create` for outbound sends.
+ *
+ * Blocks when the target channel is in `requires_reauth` or `disconnected` —
+ * outbound sends through a re-auth-needed channel will fail at the provider
+ * anyway, and blocking here gives a deterministic 422 with a field-level error
+ * instead of an opaque 500. The hub's `mark_channel_requires_reauth` command
+ * sets the status when refresh fails (slice 3b).
+ */
+export async function guardOutboundCreate(
+  em: EntityManager,
+  input: GuardOutboundCreateInput,
+): Promise<void> {
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id: input.channelId,
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+      deletedAt: null,
+    },
+    undefined,
+    input.scope,
+  )
+  if (!channel) {
+    throw new ChannelMutationBlockedError(
+      'channel_not_found',
+      input.channelId,
+      'Channel not found in this tenant scope.',
+    )
+  }
+  if (channel.status === 'requires_reauth') {
+    throw new ChannelMutationBlockedError(
+      'channel_requires_reauth',
+      input.channelId,
+      'This channel needs reconnection before it can send messages. Open Profile -> Communication channels to reconnect.',
+    )
+  }
+  if (channel.status === 'disconnected') {
+    throw new ChannelMutationBlockedError(
+      'channel_disconnected',
+      input.channelId,
+      'This channel is disconnected and cannot send messages.',
+    )
+  }
+}
+
+/**
+ * Returns the count of inbound `MessageChannelLink` rows the bridge created for
+ * this channel. Used as the safety check before allowing a channel delete.
+ *
+ * Path: `external_conversations` (by channelId) → `message_channel_links` (by
+ * externalConversationId, direction='inbound'). Both tables are hub-owned, so
+ * we stay on the right side of the cross-module isolation rule. No raw SQL.
+ *
+ * Round-2 F8 rename (2026-05-26): was `countUnreadInboundForChannel`, but the
+ * function never counted "unread" — it always counted all inbound links. The
+ * old name is preserved as a `@deprecated` alias for one minor version.
+ */
+export async function countInboundLinksForChannel(
+  em: EntityManager,
+  channelId: string,
+  scope: ChannelScope,
+): Promise<number> {
+  const conversations = await findWithDecryption(
+    em,
+    ExternalConversation,
+    {
+      channelId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId ?? null,
+    },
+    { fields: ['id'] },
+    scope,
+  )
+  if (conversations.length === 0) return 0
+  const conversationIds = (conversations as Array<{ id: string }>).map((c) => c.id)
+  const count = await em.count(
+    MessageChannelLink,
+    {
+      externalConversationId: { $in: conversationIds },
+      direction: 'inbound',
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId ?? null,
+    },
+  )
+  return typeof count === 'number' ? count : 0
+}
+
+/**
+ * @deprecated Use `countInboundLinksForChannel`. Kept for one minor release so
+ * external callers catch the rename window. Removed in the next minor.
+ */
+export const countUnreadInboundForChannel = countInboundLinksForChannel
+
+// Re-export entity types so callers can keep their typing tight.
+export type { CommunicationChannel, ExternalMessage, MessageChannelLink }

package/src/modules/communication_channels/lib/oauth-client-config.ts

@@ -0,0 +1,79 @@
+/**
+ * Minimal shape of the integrations credentials service `resolve` we depend on.
+ * Declared locally so this helper compiles even when the integrations module is
+ * disabled in a downstream app.
+ */
+type CredentialsResolver = {
+  resolve: (
+    integrationId: string,
+    scope: { tenantId: string; organizationId: string; userId?: string | null },
+  ) => Promise<Record<string, unknown> | null>
+}
+
+export type OAuthClientCredentialsScope = {
+  tenantId: string
+  organizationId: string | null
+}
+
+/**
+ * Resolve a provider's tenant-level OAuth *client application* credentials
+ * (clientId / clientSecret / scopes) configured by an admin under the
+ * `channel_<provider>` integration in the Integrations UI.
+ *
+ * Why `channel_<provider>` and NOT `oauth_<provider>`: each provider package
+ * registers its OAuth client-credential fields on the `channel_<provider>`
+ * integration — that is the row the admin edits and the health check reads.
+ * Earlier code resolved a phantom `oauth_<provider>` id that nothing ever
+ * writes, so every connect / code-exchange / refresh failed with
+ * "Invalid … OAuth client credentials: expected string, received undefined"
+ * even while the integration showed as configured and healthy.
+ *
+ * Scoping: the client app config is stored at TENANT scope (`userId = null`),
+ * distinct from the per-user OAuth *tokens* that live under the SAME
+ * `channel_<provider>` id at USER scope. We therefore always resolve at
+ * `userId: null`, trying the caller's organization first and then the
+ * organization-agnostic (`organizationId: null`) row, so a single platform /
+ * tenant OAuth app can serve every organization (and so a config saved while
+ * the admin had no active organization is still found).
+ *
+ * Returns `null` when no usable client row exists — callers MUST surface an
+ * actionable "provider not configured" error instead of handing an empty
+ * object to the adapter.
+ */
+export async function resolveOAuthClientCredentials(
+  credentialsService: CredentialsResolver | null | undefined,
+  providerKey: string,
+  scope: OAuthClientCredentialsScope,
+): Promise<Record<string, unknown> | null> {
+  if (!credentialsService) return null
+  const integrationId = `channel_${providerKey}`
+  const organizations: Array<string | null> = [scope.organizationId, null]
+  const tried = new Set<string | null>()
+  for (const organizationId of organizations) {
+    if (tried.has(organizationId)) continue
+    tried.add(organizationId)
+    let row: Record<string, unknown> | null = null
+    try {
+      // `organizationId` may be `null` to match the organization-agnostic row;
+      // the credentials filter translates `null` into a SQL `IS NULL` match.
+      row = await credentialsService.resolve(integrationId, {
+        tenantId: scope.tenantId,
+        organizationId: organizationId as unknown as string,
+        userId: null,
+      })
+    } catch (resolveErr) {
+      // A resolve error (e.g. a transient DB issue) for this org scope shouldn't
+      // abort the lookup — fall through to the next scope — but surface it so a
+      // real misconfiguration isn't silently swallowed.
+      console.warn(
+        '[internal] [communication_channels] resolveOAuthClientCredentials: credential resolve failed for an org scope:',
+        resolveErr instanceof Error ? resolveErr.message : resolveErr,
+      )
+      row = null
+    }
+    if (row && typeof row.clientId === 'string' && row.clientId.length > 0) {
+      return row
+    }
+  }
+  return null
+}