@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4397.1.9a65481757

package/src/modules/communication_channels/lib/route-mutation-guard.ts

@@ -0,0 +1,68 @@
+import type { AwilixContainer } from 'awilix'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+  type CrudMutationGuardValidationResult,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+
+type RouteAuth = {
+  sub?: string | null
+  tenantId?: string | null
+  orgId?: string | null
+}
+
+type RouteMutationGuardInput = {
+  resourceKind: string
+  resourceId: string
+  operation?: 'create' | 'update' | 'delete' | 'custom'
+  mutationPayload?: Record<string, unknown> | null
+}
+
+export type RouteMutationGuardContext = {
+  result: CrudMutationGuardValidationResult | null
+  afterSuccess: () => Promise<void>
+}
+
+export async function validateRouteMutationGuard(params: {
+  container: AwilixContainer
+  req: Request
+  auth: RouteAuth
+  input: RouteMutationGuardInput
+}): Promise<RouteMutationGuardContext | { response: Response }> {
+  const { auth, container, input, req } = params
+  if (!auth.sub || !auth.tenantId) {
+    return { result: null, afterSuccess: async () => undefined }
+  }
+
+  const base = {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId ?? null,
+    userId: auth.sub,
+    resourceKind: input.resourceKind,
+    resourceId: input.resourceId,
+    operation: input.operation ?? 'custom',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  } as const
+
+  const result = await validateCrudMutationGuard(container, {
+    ...base,
+    mutationPayload: input.mutationPayload ?? null,
+  })
+  if (result && !result.ok) {
+    return {
+      response: Response.json(result.body, { status: result.status }),
+    }
+  }
+
+  return {
+    result,
+    afterSuccess: async () => {
+      if (!result?.ok || !result.shouldRunAfterSuccess) return
+      await runCrudMutationGuardAfterSuccess(container, {
+        ...base,
+        metadata: result.metadata ?? null,
+      })
+    },
+  }
+}

package/src/modules/communication_channels/lib/sanitize-channel-html.ts

@@ -0,0 +1,129 @@
+import sanitizeHtml from 'sanitize-html'
+
+/**
+ * HTML sanitizer for channel-supplied payloads (email MIME, Slack rich-text, future channel types).
+ *
+ * The hub owns this helper; every widget that renders channel HTML — in the hub itself or in
+ * downstream provider packages — imports it. The Messages module's `channel-payload-renderer`
+ * widget calls this before any `dangerouslySetInnerHTML`-style render.
+ *
+ * Implementation note: backed by `sanitize-html` (CommonJS, server-friendly) rather than
+ * DOMPurify so the same code runs in Jest without ESM transform gymnastics. SPEC-045d §4.6
+ * specifies "DOMPurify or equivalent" — `sanitize-html` is an allowlist-based equivalent
+ * widely used for the same sanitization shape.
+ *
+ * Allowlist is tuned for email + chat HTML:
+ *   - Preserves typical email layout primitives (table-based layouts, inline images, basic typography).
+ *   - Strips `<script>`, `<style>`, `<iframe>`, all event-handler attributes (`on*`).
+ *   - Blocks `javascript:` and `data:` URLs except `data:image/*;base64,…` (inline base64 images, common in email).
+ */
+
+const ALLOWED_TAGS = [
+  'a',
+  'img',
+  'table',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'td',
+  'th',
+  'p',
+  'br',
+  'hr',
+  'ul',
+  'ol',
+  'li',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'strong',
+  'em',
+  'b',
+  'i',
+  'u',
+  's',
+  'blockquote',
+  'code',
+  'pre',
+  'span',
+  'div',
+]
+
+const ALLOWED_SCHEMES = ['http', 'https', 'mailto', 'tel']
+const ALLOWED_SCHEMES_BY_TAG = {
+  img: ['http', 'https', 'data'],
+}
+
+/**
+ * Safe CSS color value shapes only: hex (#rgb / #rgba / #rrggbb / #rrggbbaa),
+ * rgb()/rgba(), hsl()/hsla(), and bare named colors (`red`, `transparent`,
+ * `currentcolor`, …). Deliberately rejects any value containing `url(` or
+ * `expression(` so a `color`/`background-color` declaration can never smuggle a
+ * CSS-based tracking beacon or legacy-IE script expression past the sanitizer.
+ */
+const SAFE_CSS_COLOR =
+  /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$|^rgba?\(\s*[\d.,\s%]+\)$|^hsla?\(\s*[\d.,\s%]+\)$|^[a-z]+$/i
+
+const SANITIZE_OPTIONS: sanitizeHtml.IOptions = {
+  allowedTags: ALLOWED_TAGS,
+  allowedAttributes: {
+    a: ['href', 'title', 'class'],
+    img: ['src', 'alt', 'title', 'class', 'width', 'height'],
+    '*': ['class', 'style', 'colspan', 'rowspan', 'width', 'height'],
+  },
+  allowedSchemes: ALLOWED_SCHEMES,
+  allowedSchemesByTag: ALLOWED_SCHEMES_BY_TAG,
+  allowedSchemesAppliedToAttributes: ['href', 'src'],
+  allowProtocolRelative: false,
+  // disable inline scripts in style attributes
+  allowedStyles: {
+    '*': {
+      'background-color': [SAFE_CSS_COLOR],
+      color: [SAFE_CSS_COLOR],
+      'text-align': [/^left$|^right$|^center$|^justify$/i],
+      'font-size': [/^\d+(?:\.\d+)?(?:px|em|rem|%)$/],
+      'font-weight': [/^\d{3}$|^bold$|^normal$/],
+      'font-style': [/^italic$|^normal$/],
+      'text-decoration': [/^underline$|^line-through$|^none$/],
+      padding: [/^[\d\s.]+(?:px|em|rem|%)?$/],
+      margin: [/^[\d\s.]+(?:px|em|rem|%)?$/],
+      border: [/^[\d\s\w.]+$/],
+      'border-radius': [/^\d+(?:\.\d+)?(?:px|em|rem|%)$/],
+      // Permit only `display:none` so the hidden thread-token footer span
+      // (`buildBodyFooter`) stays hidden when a sent email body is re-rendered.
+      // Every other display value is stripped.
+      display: [/^none$/],
+    },
+  },
+  /**
+   * data:image/<mime>;base64,... URLs in <img src=...> are explicitly allowed so inline
+   * email images render. sanitize-html validates the base64 payload shape; if a future
+   * payload tries to smuggle a non-image MIME type via data URL we strip it.
+   */
+  exclusiveFilter: (frame) => {
+    if (frame.tag === 'img' && frame.attribs?.src) {
+      const src = frame.attribs.src
+      if (src.startsWith('data:') && !/^data:image\/(?:png|jpe?g|gif|webp);base64,/i.test(src)) {
+        return true
+      }
+    }
+    return false
+  },
+}
+
+/**
+ * Sanitize an HTML string for safe rendering.
+ *
+ * @param html Raw HTML — may originate from an external channel (email body, Slack mrkdwn rendered to HTML, …).
+ * @returns Sanitized HTML safe for `dangerouslySetInnerHTML`.
+ */
+export function sanitizeChannelHtml(html: string): string {
+  if (!html) return ''
+  return sanitizeHtml(html, SANITIZE_OPTIONS)
+}
+
+export default sanitizeChannelHtml

package/src/modules/communication_channels/lib/send-as-user.ts

@@ -0,0 +1,284 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  ChannelThreadMapping,
+  CommunicationChannel,
+  ExternalConversation,
+  MessageChannelLink,
+} from '../data/entities'
+import { ChannelMutationBlockedError, guardOutboundCreate } from './mutation-guards'
+import { COMMUNICATION_CHANNELS_QUEUES, getCommunicationChannelsQueue } from './queue'
+import type { OutboundDeliveryPayload } from '../workers/outbound-delivery'
+import { htmlToText } from './email-mime'
+
+export type SendAsUserActor = {
+  userId: string
+  tenantId: string
+  organizationId: string | null
+  /** Forwarded as the messages compose command `ctx.auth`. */
+  auth?: unknown
+}
+
+export type SendAsUserInput = {
+  userChannelId: string
+  to: string[]
+  cc?: string[]
+  bcc?: string[]
+  subject: string
+  body: { plain?: string; html?: string }
+  inReplyTo?: string
+  references?: string[]
+  /**
+   * Open Mercato `messages.message` id of the message being replied to. When
+   * set, the composed message joins that message's thread (the messages module
+   * derives `threadId` from the parent), so a CRM reply continues the existing
+   * conversation instead of starting a new thread. Optional — omitted for new
+   * threads.
+   */
+  parentMessageId?: string
+  /**
+   * Free-form metadata persisted on the resulting MessageChannelLink. Used by
+   * downstream subscribers (e.g. the customers module's link-channel-message
+   * subscriber) to anchor the sent message back to a CRM Person or honor a
+   * caller-specified visibility flag. The hub does not interpret these keys.
+   */
+  channelMetadata?: Record<string, unknown>
+}
+
+export type SendAsUserResult =
+  | {
+      ok: true
+      messageId: string
+      threadId: string
+      channelId: string
+      providerKey: string
+    }
+  | { ok: false; status: number; error: string; fieldErrors?: Record<string, string> }
+
+/**
+ * In-process send-as-user facade.
+ *
+ * Validates the actor owns `userChannelId`, composes the Message via the
+ * messages module command, persists the outbound MessageChannelLink + thread
+ * mapping, and enqueues delivery. Returns a discriminated result instead of an
+ * HTTP Response so it can be invoked both by the `/send-as-user` route and by
+ * other modules via DI (`container.resolve('communicationChannelsSendAsUser')`)
+ * — no HTTP self-call required.
+ */
+export async function sendAsUser(
+  container: AppContainer,
+  actor: SendAsUserActor,
+  input: SendAsUserInput,
+): Promise<SendAsUserResult> {
+  if (!input.body.plain && !input.body.html) {
+    return { ok: false, status: 422, error: 'Either body.plain or body.html is required' }
+  }
+  // Re-validate here (not only in the HTTP route's zod schema) because this
+  // facade is also reachable via DI; `input.to[0]` below would otherwise become
+  // `undefined` for an empty recipient list.
+  if (!Array.isArray(input.to) || input.to.length === 0) {
+    return { ok: false, status: 422, error: 'At least one recipient is required' }
+  }
+
+  const em = (container.resolve('em') as EntityManager).fork()
+  const { tenantId } = actor
+  const organizationId = actor.organizationId
+  const dscope = { tenantId, organizationId }
+
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    { id: input.userChannelId, tenantId, organizationId, deletedAt: null },
+    undefined,
+    dscope,
+  )
+  if (!channel) return { ok: false, status: 404, error: 'Channel not found' }
+  if (channel.userId !== actor.userId) {
+    return { ok: false, status: 403, error: 'You can only send through channels you own' }
+  }
+
+  // Hub mutation guard: map known non-deliverable states (`requires_reauth`,
+  // `disconnected`) to a 422 with field-level errors; other transitional states
+  // fall through to the 409 below.
+  try {
+    await guardOutboundCreate(em, { channelId: channel.id, scope: dscope })
+  } catch (err) {
+    if (err instanceof ChannelMutationBlockedError) {
+      return { ok: false, status: 422, error: err.message, fieldErrors: err.errors }
+    }
+    throw err
+  }
+  if (!channel.isActive || channel.status !== 'connected') {
+    return {
+      ok: false,
+      status: 409,
+      error: `Channel is in status '${channel.status}' (not connected)`,
+    }
+  }
+
+  // Create the Message via the messages module compose command. The outbound
+  // subscriber picks it up via `messages.message.sent` and routes through the
+  // adapter chain.
+  const commandBus = container.resolve('commandBus') as CommandBus
+  const messageBody = input.body.plain ?? htmlToText(input.body.html ?? '')
+  const composeInput = {
+    type: `channel.${channel.providerKey}`,
+    visibility: 'public' as const,
+    sourceEntityType: 'communication_channels.send_as_user',
+    sourceEntityId: channel.id,
+    externalEmail: input.to[0],
+    externalName: input.subject,
+    recipients: [],
+    subject: input.subject,
+    body: messageBody,
+    bodyFormat: 'text' as const,
+    priority: 'normal' as const,
+    sendViaEmail: false,
+    parentMessageId: input.parentMessageId,
+    isDraft: false,
+    tenantId,
+    organizationId,
+    userId: actor.userId,
+  }
+  let result
+  try {
+    result = await commandBus.execute<typeof composeInput, { id: string; threadId: string | null }>(
+      'messages.messages.compose',
+      {
+        input: composeInput,
+        ctx: {
+          container,
+          auth: actor.auth as never,
+          organizationScope: null,
+          selectedOrganizationId: organizationId,
+          organizationIds: organizationId ? [organizationId] : null,
+        },
+      },
+    )
+  } catch (err) {
+    console.error('[communication_channels] send-as-user compose failed', err)
+    return { ok: false, status: 500, error: '[internal] compose failed' }
+  }
+
+  const messageId = result.result.id
+  const messageThreadId = result.result.threadId ?? messageId
+  const externalThreadRef = `outbound:${messageThreadId}`
+
+  // Persist the conversation, thread mapping, and channel link as one unit. The
+  // conversation's id is DB-generated (`gen_random_uuid()`), so it must be
+  // flushed before the mapping/link can reference it — hence the eager flushes
+  // rather than `withAtomicFlush` (single trailing flush). `em.transactional`
+  // wraps the whole sequence so a mid-way failure rolls back all three writes
+  // instead of leaving an orphaned conversation row.
+  await em.transactional(async () => {
+    let conversation = await findOneWithDecryption(
+      em,
+      ExternalConversation,
+      {
+        channelId: channel.id,
+        externalConversationId: externalThreadRef,
+        tenantId,
+        organizationId,
+      },
+      undefined,
+      dscope,
+    )
+    if (!conversation) {
+      conversation = em.create(ExternalConversation, {
+        channelId: channel.id,
+        externalConversationId: externalThreadRef,
+        subject: input.subject,
+        assignedUserId: actor.userId,
+        tenantId,
+        organizationId,
+        lastMessageAt: new Date(),
+      })
+      em.persist(conversation)
+      await em.flush()
+    } else {
+      conversation.subject = conversation.subject ?? input.subject
+      conversation.assignedUserId = conversation.assignedUserId ?? actor.userId
+      conversation.lastMessageAt = new Date()
+      // Flush the scalar updates BEFORE the ChannelThreadMapping lookup below: a
+      // find/findOne on the same EntityManager between a scalar mutation and flush
+      // can silently drop the pending UPDATE (core AGENTS.md → Entity Update Safety).
+      await em.flush()
+    }
+
+    const existingMapping = await findOneWithDecryption(
+      em,
+      ChannelThreadMapping,
+      {
+        externalConversationId: conversation.id,
+        tenantId,
+        organizationId,
+      },
+      undefined,
+      dscope,
+    )
+    if (!existingMapping) {
+      const mapping = em.create(ChannelThreadMapping, {
+        externalConversationId: conversation.id,
+        messageThreadId,
+        channelId: channel.id,
+        providerKey: channel.providerKey,
+        externalThreadRef,
+        assignedUserId: actor.userId,
+        tenantId,
+        organizationId,
+      })
+      em.persist(mapping)
+    }
+
+    const channelLink = em.create(MessageChannelLink, {
+      messageId,
+      externalConversationId: conversation.id,
+      providerKey: channel.providerKey,
+      channelType: channel.channelType,
+      direction: 'outbound',
+      deliveryStatus: 'pending',
+      channelPayload: {
+        text: input.body.plain ?? messageBody,
+        ...(input.body.html ? { html: input.body.html } : {}),
+      },
+      channelContentType: input.body.html ? 'text/html' : 'text/plain',
+      channelMetadata: {
+        // Caller-supplied pass-through metadata merged FIRST so the validated
+        // routing fields below always win — a caller cannot override the
+        // recipients/subject/threading headers via `channelMetadata`.
+        ...(input.channelMetadata ?? {}),
+        to: input.to,
+        cc: input.cc ?? [],
+        bcc: input.bcc ?? [],
+        subject: input.subject,
+        inReplyTo: input.inReplyTo ?? null,
+        references: input.references ?? [],
+      },
+      tenantId,
+      organizationId,
+    })
+    em.persist(channelLink)
+    await em.flush()
+  })
+
+  const queue = getCommunicationChannelsQueue(COMMUNICATION_CHANNELS_QUEUES.outbound)
+  const deliveryJob: OutboundDeliveryPayload = {
+    messageId,
+    scope: dscope,
+    attempt: 1,
+  }
+  await queue.enqueue(deliveryJob as unknown as Record<string, unknown>)
+
+  return {
+    ok: true,
+    messageId,
+    threadId: messageThreadId,
+    channelId: channel.id,
+    providerKey: channel.providerKey,
+  }
+}
+
+/** DI service type for cross-module callers (resolve `communicationChannelsSendAsUser`). */
+export type SendAsUserService = typeof sendAsUser

package/src/modules/communication_channels/lib/system-user.ts

@@ -0,0 +1,74 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Sentinel UUID — used as a last-resort `senderUserId` for inbound channel
+ * messages when no per-tenant system user is available. Matches the pattern
+ * in `inbox_ops/lib/messagesIntegration.ts`.
+ */
+export const COMMUNICATION_CHANNELS_SYSTEM_USER_ID = '00000000-0000-0000-0000-000000000000'
+
+/**
+ * Configurable email pattern for per-tenant channel-bot users. Implementations
+ * (provider packages, onboarding scripts) may create a real `auth.user` row
+ * matching this convention so inbound channel messages get a meaningful sender
+ * display name in the unified inbox.
+ *
+ * Format: `system+communication_channels@<tenantId>.local`
+ */
+export function systemUserEmail(tenantId: string): string {
+  return `system+communication_channels@${tenantId}.local`
+}
+
+/**
+ * Resolve a tenant-scoped system user id to attribute inbound channel messages to.
+ *
+ * Lookup order:
+ *   1. Per-tenant channel-bot user (by convention email — see `systemUserEmail`).
+ *   2. (Optional, caller-supplied) seed fallback — a specific override id.
+ *   3. Sentinel UUID (`00000000-...`) — backward-compatible default.
+ *
+ * The function is fail-soft: when the lookup throws, it falls back to the
+ * sentinel. The inbound-processor must never refuse to ingest a message
+ * because the channel-bot user doesn't exist.
+ *
+ * @param em            EntityManager scoped to the tenant.
+ * @param tenantId      Tenant id for which to resolve the system user.
+ * @param fallbackId    Optional caller-supplied fallback (e.g., the channel's
+ *                      assigned user) used when the channel-bot lookup misses.
+ */
+export async function resolveCommunicationChannelsSystemUserId(
+  em: EntityManager,
+  tenantId: string,
+  fallbackId?: string | null,
+): Promise<string> {
+  try {
+    const expectedEmail = systemUserEmail(tenantId)
+    // Untyped QB by design — the helper is intentionally cross-module
+    // (resolving an `auth.user` from the hub) and must not pull the User
+    // entity class. MikroORM v7's typed builder requires an entity ref;
+    // we keep the lookup table-name-driven so the helper compiles without
+    // a cross-module import. The mocks in `__tests__/system-user.test.ts`
+    // exercise this code path through a duck-typed `createQueryBuilder` stub.
+    type RawQueryBuilder = {
+      select: (fields: string[]) => RawQueryBuilder
+      where: (cond: Record<string, unknown>) => RawQueryBuilder
+      limit: (count: number) => RawQueryBuilder
+      execute: (mode: string) => Promise<unknown>
+    }
+    const qb = (
+      em as unknown as { createQueryBuilder: (table: string, alias: string) => RawQueryBuilder }
+    ).createQueryBuilder('auth.users', 'u')
+    const row = await qb
+      .select(['u.id'])
+      .where({ email: expectedEmail, tenant_id: tenantId })
+      .limit(1)
+      .execute('get')
+      .catch(() => null)
+    const id = (row as { id?: string } | null)?.id
+    if (typeof id === 'string' && id.length > 0) return id
+  } catch {
+    // ignore — fall through to fallback
+  }
+  if (typeof fallbackId === 'string' && fallbackId.length > 0) return fallbackId
+  return COMMUNICATION_CHANNELS_SYSTEM_USER_ID
+}

package/src/modules/communication_channels/lib/test-seed.ts

@@ -0,0 +1,140 @@
+import type {
+  ChannelAdapter,
+  ChannelCapabilities,
+  ChannelNativeContent,
+  ConvertOutboundInput,
+  GetMessageStatusInput,
+  InboundMessage,
+  MessageStatus,
+  NormalizedInboundMessage,
+  SendMessageInput,
+  SendMessageResult,
+  ValidateCredentialsInput,
+  ValidateCredentialsResult,
+  VerifyWebhookInput,
+} from './adapter'
+import { baseEmailCapabilities } from './email-capabilities'
+import { hasChannelAdapter, registerChannelAdapter } from './adapter-registry-singleton'
+
+/**
+ * Test-only channel seeding support.
+ *
+ * The ephemeral integration harness cannot connect a REAL email channel:
+ *   - IMAP/SMTP `validateCredentials` performs a live LOGIN against a mail server
+ *     (none exists in CI), so `POST /channels/connect/credentials` returns 422.
+ *   - Even with a connected channel, the outbound delivery worker calls the real
+ *     SMTP adapter, which fails with no server — so `communication_channels.message.sent`
+ *     never fires and the customers link subscriber never runs.
+ *
+ * To make the compose → deliver → `.sent` → CRM-link → cross-user-visibility chain
+ * (TC-CRM-EMAIL-001) and the inbound auto-link chain (TC-CRM-EMAIL-002..005) runnable
+ * end-to-end against real Postgres, this module provides a network-free stub adapter
+ * that is registered ONLY when `OM_ENABLE_TEST_CHANNEL_SEEDING` is set.
+ *
+ * Production safety: the registration is gated by {@link isTestChannelSeedingEnabled};
+ * when the env flag is unset (the production default) the adapter is never registered
+ * and the `__test_seed__` provider key resolves to no adapter — so the connect route
+ * returns 404 `no_adapter` exactly as it would for any unknown provider. The dedicated
+ * test-seed API route enforces the same gate independently (fail-closed 404 in prod).
+ */
+
+/** Provider key for the network-free test stub adapter. */
+export const TEST_SEED_PROVIDER_KEY = '__test_seed__'
+
+/** Env flag that unlocks test-only channel seeding. Off in production. */
+export const TEST_CHANNEL_SEEDING_ENV = 'OM_ENABLE_TEST_CHANNEL_SEEDING'
+
+/**
+ * True only when the test-seeding env flag is explicitly enabled. Accepts the
+ * usual truthy tokens (`1`, `true`, `yes`, `on`) so the harness can opt in via a
+ * plain `=true`. Any other value (including unset) is treated as disabled.
+ */
+export function isTestChannelSeedingEnabled(): boolean {
+  const raw = process.env[TEST_CHANNEL_SEEDING_ENV]
+  if (typeof raw !== 'string') return false
+  return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase())
+}
+
+/**
+ * Capabilities for the stub: an email channel that supports neither reactions,
+ * edit/delete, nor conversation history — so the strict registry validator
+ * (`validateAdapterCapabilities`) requires only the core method surface.
+ */
+const testSeedCapabilities: ChannelCapabilities = {
+  ...baseEmailCapabilities,
+  conversationHistory: false,
+  realtimePush: false,
+}
+
+/**
+ * A `ChannelAdapter` whose `sendMessage` reports a successful send WITHOUT any
+ * network I/O. Used exclusively by the integration harness to let the outbound
+ * delivery worker reach its success path and emit `communication_channels.message.sent`.
+ */
+class TestSeedChannelAdapter implements ChannelAdapter {
+  readonly providerKey = TEST_SEED_PROVIDER_KEY
+  readonly channelType = 'email'
+  readonly capabilities = testSeedCapabilities
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    // Synthesize a deterministic-looking RFC2822-style message id; never touches
+    // the network. The delivery worker persists this as the external message id.
+    const externalMessageId = `test-seed-${Date.now()}-${Math.random().toString(16).slice(2, 10)}@test-seed.local`
+    return {
+      externalMessageId,
+      conversationId: input.conversationId,
+      status: 'sent',
+      metadata: { testSeed: true },
+    }
+  }
+
+  async verifyWebhook(_input: VerifyWebhookInput): Promise<InboundMessage> {
+    // No real webhook — return the inert event so the generic webhook route 202s
+    // without enqueuing tenant-scoped work (mirrors the IMAP adapter contract).
+    return { raw: {}, eventType: 'other', metadata: { reason: 'test-seed-no-webhook' } }
+  }
+
+  async getStatus(_input: GetMessageStatusInput): Promise<MessageStatus> {
+    return { status: 'sent' }
+  }
+
+  async convertOutbound(input: ConvertOutboundInput): Promise<ChannelNativeContent> {
+    return {
+      content: {
+        text: input.body,
+        bodyFormat: input.bodyFormat,
+      },
+      metadata: input.channelMetadata ?? {},
+    }
+  }
+
+  async normalizeInbound(_raw: InboundMessage): Promise<NormalizedInboundMessage> {
+    // The test-seed inbound path seeds MessageChannelLink rows directly and emits
+    // the hub event, so this adapter never normalizes a raw inbound payload.
+    throw new Error('[internal] TestSeedChannelAdapter.normalizeInbound is not used by the seed harness')
+  }
+
+  async validateCredentials(_input: ValidateCredentialsInput): Promise<ValidateCredentialsResult> {
+    // No real server to authenticate against — accept any credentials so the
+    // connect command persists a connected channel.
+    return { ok: true }
+  }
+}
+
+let cachedTestSeedAdapter: TestSeedChannelAdapter | null = null
+
+function getTestSeedChannelAdapter(): TestSeedChannelAdapter {
+  if (!cachedTestSeedAdapter) cachedTestSeedAdapter = new TestSeedChannelAdapter()
+  return cachedTestSeedAdapter
+}
+
+/**
+ * Register the test-seed adapter exactly once, but ONLY when the env flag is set.
+ * Idempotent and safe to call from every container creation (`di.register`) — a
+ * no-op when seeding is disabled or the adapter is already registered.
+ */
+export function ensureTestSeedAdapterRegistered(): void {
+  if (!isTestChannelSeedingEnabled()) return
+  if (hasChannelAdapter(TEST_SEED_PROVIDER_KEY)) return
+  registerChannelAdapter(getTestSeedChannelAdapter())
+}