@open-mercato/channel-imap 0.6.4

package/src/modules/channel_imap/lib/convert-outbound.ts

@@ -0,0 +1,79 @@
+import type {
+  ChannelNativeContent,
+  ConvertOutboundInput,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  htmlToText,
+  referencesFromMeta,
+  sanitizeHeaderValue,
+  stringOrUndefined,
+  toAddressList,
+} from '@open-mercato/core/modules/communication_channels/lib/email-mime'
+
+/**
+ * Convert a hub-canonical outbound payload to an email-shaped `ChannelNativeContent`.
+ *
+ * Subject and threading headers come from `channelMetadata` populated by the hub:
+ *   - `subject` (string)
+ *   - `to` / `cc` / `bcc` (string | string[])
+ *   - `inReplyTo` (string)
+ *   - `references` (string[])
+ *
+ * Body format:
+ *   - `'html'` keeps the HTML body as-is, derives plain-text via a naive strip.
+ *   - `'text'` produces text-only.
+ *   - `'markdown'` is not supported by email; we treat it as text (the hub limits
+ *     `supportedBodyFormats` to ['text','html'] so this should not occur in practice).
+ */
+
+export async function convertOutboundForEmail(
+  input: ConvertOutboundInput,
+): Promise<ChannelNativeContent> {
+  const meta = (input.channelMetadata ?? {}) as Record<string, unknown>
+  // Defense-in-depth: strip CR/LF/tab from every header-shaped field so a crafted
+  // subject or recipient cannot smuggle an extra header (e.g. a hidden Bcc),
+  // instead of relying solely on the downstream SMTP composer to neutralize it.
+  const sanitizeOptionalHeader = (value: string | undefined): string | undefined =>
+    value === undefined ? undefined : sanitizeHeaderValue(value)
+  const subject = sanitizeOptionalHeader(stringOrUndefined(meta.subject))
+  const to = toAddressList(meta.to).map(sanitizeHeaderValue)
+  if (to.length === 0) {
+    throw new Error('Email outbound conversion requires at least one recipient (channelMetadata.to)')
+  }
+  const cc = toAddressList(meta.cc).map(sanitizeHeaderValue)
+  const bcc = toAddressList(meta.bcc).map(sanitizeHeaderValue)
+  const inReplyTo = sanitizeOptionalHeader(stringOrUndefined(meta.inReplyTo))
+  const references = referencesFromMeta(meta.references)?.map(sanitizeHeaderValue)
+  const messageId = sanitizeOptionalHeader(stringOrUndefined(meta.messageId))
+
+  const html = input.bodyFormat === 'html' ? input.body : undefined
+  const text = input.bodyFormat === 'html' ? htmlToText(input.body) : input.body
+
+  const native: ChannelNativeContent = {
+    content: {
+      text,
+      html,
+      bodyFormat: input.bodyFormat,
+      attachments: input.attachments,
+      raw: {
+        subject,
+        to,
+        cc,
+        bcc,
+        inReplyTo,
+        references,
+        messageId,
+      },
+    },
+    metadata: {
+      subject,
+      to,
+      cc,
+      bcc,
+      inReplyTo,
+      references,
+      messageId,
+    },
+  }
+  return native
+}

package/src/modules/channel_imap/lib/credentials.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+
+/**
+ * SSRF guard: reject hostnames that resolve to internal networks. Operators
+ * configure their own IMAP/SMTP server, so the host string is attacker-controlled
+ * in a per-user-channel context. Blocking these prevents the credential-validation
+ * flow from acting as a port scanner or leaking the platform's outbound IP to
+ * internal infrastructure (cloud metadata endpoints, kube-apiserver, RDS, etc).
+ *
+ * The check is string-based: it rejects literal internal IPs, `localhost`, and
+ * the obfuscated encodings that exist to evade such filters (IPv4-mapped IPv6,
+ * decimal/hex/octal/short-form IPv4, bracketed and expanded IPv6). It does NOT
+ * by itself catch a public hostname that resolves — or is DNS-rebound — to a
+ * private address; that gap is closed at connect time by `resolveSafeHostAddress`
+ * (`host-pinning.ts`), which resolves the host, rejects any internal resolved
+ * address, and pins the connection to the validated IP. Operators with a
+ * genuinely private IMAP host set `OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS=true`.
+ */
+const FORBIDDEN_HOST_NAMES = new Set([
+  'localhost',
+  'localhost6',
+  'ip6-localhost',
+  'ip6-loopback',
+  'metadata.google.internal',
+])
+
+const PRIVATE_IPV4_PATTERNS: RegExp[] = [
+  /^(127|10)\./,                                    // 127/8 loopback, 10/8 private
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,                  // 172.16/12 private
+  /^192\.168\./,                                    // 192.168/16 private
+  /^169\.254\./,                                    // link-local + cloud metadata (169.254.169.254)
+  /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./, // CGNAT 100.64/10
+  /^0\./,                                           // 0.0.0.0/8 reserved
+]
+
+const PRIVATE_IPV6_PATTERNS: RegExp[] = [
+  /^::$/,                                            // unspecified
+  /^::1$/,                                           // loopback
+  /^::ffff:/,                                        // IPv4-mapped (hex-group form; dotted form is unwrapped first)
+  /^(fc|fd)[0-9a-f]{0,2}:/,                          // unique-local fc00::/7
+  /^fe80:/,                                          // link-local
+  /^(0{1,4}:){7}0{0,3}1$/,                           // fully-expanded loopback
+  /^(0{1,4}:){7}0{1,4}$/,                            // fully-expanded unspecified
+]
+
+function isDottedDecimalQuad(host: string): boolean {
+  const parts = host.split('.')
+  return parts.length === 4 && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * True when `host` is an obfuscated IPv4 encoding — decimal integer
+ * (`2130706433`), hex (`0x7f.0.0.1`), octal (`0177.0.0.1`) or short form
+ * (`127.1`). These forms exist almost exclusively to bypass SSRF string filters,
+ * so we reject them outright; legitimate operators use a hostname or a standard
+ * dotted-decimal quad.
+ */
+function isObfuscatedIpv4(host: string): boolean {
+  if (host.includes(':')) return false
+  if (/^\d+$/.test(host)) return true
+  if (/(^|\.)0x[0-9a-f]+/.test(host)) return true
+  const labels = host.split('.')
+  if (!labels.every((label) => /^[0-9a-f]+$/.test(label))) return false
+  if (isDottedDecimalQuad(host) && !labels.some((label) => label.length > 1 && label.startsWith('0'))) return false
+  return true
+}
+
+function normalizeHost(raw: string): string {
+  let host = raw.trim().toLowerCase()
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1)
+  const mappedIpv4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
+  if (mappedIpv4) return mappedIpv4[1]
+  return host
+}
+
+/**
+ * Classify a host as internal/loopback/metadata, ignoring the operator escape
+ * hatch. Exported so the SSRF guard can be asserted directly in unit tests.
+ */
+export function isInternalHost(rawHost: string): boolean {
+  const host = normalizeHost(rawHost)
+  if (!host) return false
+  if (FORBIDDEN_HOST_NAMES.has(host) || host.endsWith('.localhost')) return true
+  if (host.includes(':')) return PRIVATE_IPV6_PATTERNS.some((pattern) => pattern.test(host))
+  if (isObfuscatedIpv4(host)) return true
+  // Only treat the private-range patterns as internal for a real dotted-decimal
+  // quad. Otherwise a hostname whose first label merely looks like a private
+  // range (e.g. `0.mx.example.com`, `10.example.com`) is wrongly rejected.
+  // Obfuscated/short IPv4 forms were already caught above, so anything reaching
+  // here is either a quad or a genuine hostname.
+  return isDottedDecimalQuad(host) && PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(host))
+}
+
+function assertSafeHost(host: string, ctx: { addIssue: (issue: { code: 'custom'; message: string }) => void }): void {
+  if (parseBooleanWithDefault(process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS, false)) return
+  if (!host.trim()) return
+  if (isInternalHost(host)) {
+    ctx.addIssue({
+      code: 'custom',
+      message:
+        'Host appears to point at a private or loopback address. If this is intentional, an operator must set OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS=true.',
+    })
+  }
+}
+
+function hostnameSchema(label: 'IMAP' | 'SMTP') {
+  return z
+    .string()
+    .min(1, `${label} host required`)
+    .max(253, `${label} host too long`)
+    .superRefine((value, ctx) => assertSafeHost(value, ctx))
+}
+
+/**
+ * Per-user IMAP+SMTP credentials. Validated whenever a user connects a new
+ * channel (`POST /api/communication_channels/channels/connect/credentials`) and
+ * before every outbound send / inbound poll.
+ *
+ * The hub persists this blob inside `IntegrationCredentials.credentials` (encrypted
+ * at rest). Do not log credential values; the adapter logs `<redacted>` for any
+ * password-shaped key.
+ */
+export const imapCredentialsSchema = z
+  .object({
+    imapHost: hostnameSchema('IMAP'),
+    imapPort: z.coerce
+      .number()
+      .int()
+      .min(1, 'IMAP port must be a positive integer')
+      .max(65535, 'IMAP port must be <= 65535'),
+    imapTls: z.enum(['tls', 'starttls', 'none']),
+    imapUser: z.string().min(1, 'IMAP username required'),
+    imapPassword: z.string().min(1, 'IMAP password required'),
+
+    smtpHost: hostnameSchema('SMTP'),
+    smtpPort: z.coerce
+      .number()
+      .int()
+      .min(1, 'SMTP port must be a positive integer')
+      .max(65535, 'SMTP port must be <= 65535'),
+    smtpTls: z.enum(['tls', 'starttls', 'none']),
+    smtpUser: z.string().min(1, 'SMTP username required'),
+    smtpPassword: z.string().min(1, 'SMTP password required'),
+
+    fromAddress: z.string().email('From address must be a valid email'),
+  })
+  // `.passthrough()` (not `.strict()`) so the connect-credential-channel command
+  // can stash bookkeeping fields like `userId` alongside the user-entered
+  // credentials. Strict was rejecting any extra key with "Unrecognized key" and
+  // blocking outbound SMTP after a real user connected via the per-user flow.
+  .passthrough()
+
+export type ImapCredentials = z.infer<typeof imapCredentialsSchema>
+
+/**
+ * Internal poll-state stored on `CommunicationChannel.channelState` so we can
+ * resume polling without re-scanning the entire mailbox each tick.
+ *
+ *   uidValidity — IMAP UIDVALIDITY for INBOX; if it changes we must full-resync.
+ *   uidNext     — UIDNEXT for INBOX; subsequent polls fetch `<previous uidNext>:*`.
+ */
+export const imapChannelStateSchema = z
+  .object({
+    uidValidity: z.union([z.number(), z.string()]).optional(),
+    uidNext: z.union([z.number(), z.string()]).optional(),
+    lastFolder: z.string().optional(),
+  })
+  .partial()
+  .passthrough()
+
+export type ImapChannelState = z.infer<typeof imapChannelStateSchema>

package/src/modules/channel_imap/lib/health.ts

@@ -0,0 +1,70 @@
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { imapCredentialsSchema } from './credentials'
+import { credentialsToConnection, getImapClient } from './imap-client'
+
+export type HealthCheckStatus = 'healthy' | 'degraded' | 'unhealthy'
+
+export interface HealthCheckResult {
+  status: HealthCheckStatus
+  message?: string
+  details?: Record<string, unknown>
+}
+
+/**
+ * Liveness probe for the IMAP/SMTP integration. The hub resolves it by the
+ * service name declared in `integration.ts` (`channelImapHealthCheck`) and
+ * passes the tenant/user-scoped `IntegrationCredentials` row — the full
+ * IMAP+SMTP connection blob.
+ *
+ * Unlike the OAuth channels, IMAP credentials carry everything needed for a
+ * real probe, so we do a cheap LOGIN: open the IMAP connection, read
+ * capabilities, log out. We deliberately probe IMAP only (the inbound side) and
+ * skip the SMTP `verify` round-trip to keep the check cheap. The probe passes a
+ * tighter 8s connect/greeting timeout (below the hub's 10s health-check budget)
+ * so a slow/unreachable host fails fast as `unhealthy` here with an actionable
+ * reason, rather than losing the race to the hub's generic timeout; polling is
+ * unaffected (it uses the default 15s connect + 60s socket timeouts).
+ * Auth/connection failures surface as `unhealthy`; a clean LOGIN is `healthy`.
+ */
+export const channelImapHealthCheck = {
+  async check(
+    credentials: Record<string, unknown> | null,
+    _scope: IntegrationScope,
+  ): Promise<HealthCheckResult> {
+    const parsed = imapCredentialsSchema.safeParse(credentials ?? {})
+    if (!parsed.success) {
+      const first = parsed.error.issues[0]
+      return {
+        status: 'unhealthy',
+        message: `IMAP credentials invalid: ${first?.message ?? 'unknown validation error'}`,
+        details: { reason: 'invalid_credentials' },
+      }
+    }
+    try {
+      const result = await getImapClient().connectAndValidate({
+        ...credentialsToConnection(parsed.data),
+        connectTimeoutMs: 8_000,
+      })
+      return {
+        status: 'healthy',
+        message: 'IMAP login succeeded',
+        details: { capabilities: result.capabilities },
+      }
+    } catch (error) {
+      const raw = error instanceof Error ? error.message : 'IMAP login failed'
+      // Strip the internal-only marker so a policy/diagnostic string never
+      // reaches an operator-facing health message, and distinguish a
+      // transport-policy rejection (cleartext not opted in) from a real login
+      // failure so operators get an actionable reason code.
+      const message = raw.replace(/^\[internal\]\s*/, '')
+      const isTransportPolicy = /cleartext transport/i.test(message)
+      return {
+        status: 'unhealthy',
+        message: isTransportPolicy
+          ? `IMAP transport not allowed: ${message}`
+          : `IMAP login failed: ${message}`,
+        details: { reason: isTransportPolicy ? 'insecure_transport' : 'imap_login_failed' },
+      }
+    }
+  },
+}

package/src/modules/channel_imap/lib/host-pinning.ts

@@ -0,0 +1,59 @@
+import { lookup as dnsLookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { isInternalHost } from './credentials'
+
+export type HostLookup = (hostname: string) => Promise<Array<{ address: string; family: number }>>
+
+const INTERNAL_RESOLVED_MESSAGE =
+  'Host resolves to a private or loopback address. If this is intentional, an operator must set OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS=true.'
+
+const UNRESOLVABLE_MESSAGE = 'Host did not resolve to any address.'
+
+function stripBrackets(host: string): string {
+  return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+}
+
+/**
+ * Resolve `host` to an IP and assert every resolved address is public, then pin
+ * the connection to that IP. Closes the DNS-rebinding gap the string-only SSRF
+ * guard (`isInternalHost`) leaves open: a public hostname that resolves — or is
+ * rebound between validation and connect — to an internal address is rejected
+ * here, and the returned IP is what the caller actually connects to (no second
+ * lookup the attacker could race).
+ *
+ * - Literal IPs (already SSRF-checked by the credential schema) are returned
+ *   unchanged with no `servername`.
+ * - Hostnames are resolved to every A/AAAA record; if ANY resolved address is
+ *   internal the call throws. The validated IP is returned as `host` and the
+ *   original hostname as `servername`, so TLS SNI + certificate hostname
+ *   verification still target the real host even though we dial the IP.
+ * - Honors `OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS`: when set, resolution is
+ *   skipped and the host is used verbatim (operators with a genuinely internal
+ *   mail server).
+ */
+export async function resolveSafeHostAddress(
+  host: string,
+  options: { lookup?: HostLookup } = {},
+): Promise<{ host: string; servername?: string }> {
+  const trimmed = host.trim()
+  if (parseBooleanWithDefault(process.env.OM_CHANNEL_IMAP_ALLOW_INTERNAL_HOSTS, false)) {
+    return { host: trimmed }
+  }
+  if (isIP(stripBrackets(trimmed)) !== 0) {
+    if (isInternalHost(trimmed)) throw new Error(`[internal] ${INTERNAL_RESOLVED_MESSAGE}`)
+    return { host: trimmed }
+  }
+  const resolve =
+    options.lookup ?? ((hostname: string) => dnsLookup(hostname, { all: true, verbatim: true }))
+  const records = await resolve(trimmed)
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new Error(`[internal] ${UNRESOLVABLE_MESSAGE}`)
+  }
+  for (const record of records) {
+    if (isInternalHost(record.address)) {
+      throw new Error(`[internal] ${INTERNAL_RESOLVED_MESSAGE}`)
+    }
+  }
+  return { host: records[0].address, servername: trimmed }
+}