pipework 0.252.0 → 0.252.1

package/src/infra/email/mime.ts

@@ -0,0 +1,447 @@
+// A hand-written MIME parser for received mail. Pure: bytes in, a plain object out.
+// It never throws; malformed input degrades to the best reading. Internal to the
+// inbound pipeline (not public API); exported for its tests.
+//
+// The message is held as a latin1 string (one char per byte) while it is split, so
+// offsets are byte offsets and slices convert back losslessly; charsets are decoded
+// only on the final text of a header or body.
+
+export interface ParsedAddress {
+  readonly address: string
+  readonly name: string
+}
+
+export interface ParsedAttachment {
+  readonly filename: string | null
+  readonly mediaType: string
+  readonly size: number
+  readonly contentId: string | null
+  readonly inline: boolean
+  readonly content: Buffer
+}
+
+export interface ParsedMessage {
+  /** Message-ID without angle brackets, or null. */
+  readonly messageId: string | null
+  /** The first In-Reply-To id without angle brackets, or null. */
+  readonly inReplyTo: string | null
+  /** In-Reply-To ids (first) then References ids, without angle brackets, duplicates removed. */
+  readonly threadIds: readonly string[]
+  /** References ids without angle brackets, in order. */
+  readonly references: readonly string[]
+  /** The author, or null when there is no readable From or the author is ambiguous (see `fromProblem`). */
+  readonly from: ParsedAddress | null
+  /**
+   * Why `from` is null for a message that had a From: several From fields, or several mailboxes in one.
+   * Null otherwise. RFC 7489 section 6.6.1: verifiers differ in which one they judge, so none is named.
+   */
+  readonly fromProblem: 'several-from-fields' | 'several-mailboxes' | null
+  readonly to: readonly ParsedAddress[]
+  readonly cc: readonly ParsedAddress[]
+  readonly replyTo: readonly ParsedAddress[]
+  readonly subject: string
+  readonly date: Date | null
+  readonly text: string | null
+  readonly html: string | null
+  readonly attachments: readonly ParsedAttachment[]
+}
+
+const MAX_DEPTH = 20
+
+interface Header { readonly name: string; readonly value: string }
+
+interface Entity {
+  readonly headers: readonly Header[]
+  /** Body, still transfer-encoded, as latin1. */
+  readonly body: string
+}
+
+function header(entity: Entity, name: string): string | undefined {
+  return entity.headers.find(h => h.name === name)?.value
+}
+
+function headers(entity: Entity, name: string): string[] {
+  return entity.headers.filter(h => h.name === name).map(h => h.value)
+}
+
+function splitEntity(raw: string): Entity {
+  let at = -1
+  let bodyAt = 0
+  if (raw.startsWith('\r\n')) { at = 0; bodyAt = 2 } else if (raw.startsWith('\n')) { at = 0; bodyAt = 1 } else {
+    const m = /\r?\n\r?\n/.exec(raw)
+    if (m !== null) { at = m.index; bodyAt = m.index + m[0].length }
+  }
+  const head = at < 0 ? raw : raw.slice(0, at)
+  const body = at < 0 ? '' : raw.slice(bodyAt)
+  const headers: Header[] = []
+  let current: { name: string; value: string } | null = null
+  for (const line of head.split(/\r?\n/)) {
+    if (/^[ \t]/.test(line)) {
+      if (current !== null) current.value += ` ${line.trim()}`
+      continue
+    }
+    const colon = line.indexOf(':')
+    if (colon <= 0 || /[\s\x00-\x1f]/.test(line.slice(0, colon))) { current = null; continue }
+    current = { name: line.slice(0, colon).toLowerCase(), value: line.slice(colon + 1).trim() }
+    headers.push(current)
+  }
+  // A header with 8-bit bytes is UTF-8 when it is valid UTF-8, otherwise latin1 as read.
+  return { headers: headers.map(h => ({ name: h.name, value: decodeRawHeader(h.value) })), body }
+}
+
+function decodeRawHeader(value: string): string {
+  if (!/[^\x00-\x7f]/.test(value)) return value
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(value, 'latin1'))
+  } catch {
+    return value
+  }
+}
+
+function decodeCharset(bytes: Buffer, charset: string | undefined): string {
+  const label = (charset ?? 'utf-8').trim().replace(/^"|"$/g, '').toLowerCase()
+  try {
+    return new TextDecoder(label === '' ? 'utf-8' : label).decode(bytes)
+  } catch {
+    return new TextDecoder('utf-8').decode(bytes)
+  }
+}
+
+// ---- RFC 2047 encoded words ----
+
+function decodeQ(text: string): Buffer {
+  const bytes: number[] = []
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!
+    if (c === '_') bytes.push(0x20)
+    else if (c === '=' && /^[0-9a-fA-F]{2}$/.test(text.slice(i + 1, i + 3))) { bytes.push(parseInt(text.slice(i + 1, i + 3), 16)); i += 2 } else bytes.push(c.charCodeAt(0) & 0xff)
+  }
+  return Buffer.from(bytes)
+}
+
+const ENCODED_WORD = /=\?([^?\s]+)\?([bBqQ])\?([^?\s]*)\?=/g
+
+/** Decodes RFC 2047 encoded words in `text`. Adjacent words are joined without the whitespace between them, and words in the same charset are decoded together so a multibyte character split across words survives. */
+export function decodeWords(text: string): string {
+  if (!text.includes('=?')) return text
+  const out: string[] = []
+  let run: { charset: string; bytes: Buffer[] } | null = null
+  const flush = (): void => {
+    if (run !== null) out.push(decodeCharset(Buffer.concat(run.bytes), run.charset))
+    run = null
+  }
+  let last = 0
+  for (const m of text.matchAll(ENCODED_WORD)) {
+    const between = text.slice(last, m.index)
+    if (run !== null && between.trim() === '') {
+      // whitespace between adjacent encoded words is dropped
+    } else {
+      flush()
+      out.push(between)
+    }
+    const charset = m[1]!.split('*')[0]!.toLowerCase()
+    const bytes = m[2]!.toLowerCase() === 'b' ? Buffer.from(m[3]!, 'base64') : decodeQ(m[3]!)
+    if (run !== null && (run as { charset: string }).charset !== charset) flush()
+    if (run === null) run = { charset, bytes: [] }
+    ;(run as { bytes: Buffer[] }).bytes.push(bytes)
+    last = m.index + m[0].length
+  }
+  flush()
+  out.push(text.slice(last))
+  return out.join('')
+}
+
+// ---- structured header values ----
+
+function unquote(text: string): string {
+  const t = text.trim()
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) return t.slice(1, -1).replace(/\\(.)/g, '$1')
+  return t
+}
+
+interface Structured { readonly value: string; readonly params: ReadonlyMap<string, string> }
+
+function splitTop(text: string, separator: string): string[] {
+  const parts: string[] = []
+  let cur = ''
+  let quoted = false
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!
+    if (quoted) {
+      cur += c
+      if (c === '\\' && i + 1 < text.length) cur += text[++i]!
+      else if (c === '"') quoted = false
+      continue
+    }
+    if (c === '"') { quoted = true; cur += c; continue }
+    if (c === separator) { parts.push(cur); cur = ''; continue }
+    cur += c
+  }
+  parts.push(cur)
+  return parts
+}
+
+function percentBytes(text: string): Buffer {
+  const bytes: number[] = []
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '%' && /^[0-9a-fA-F]{2}$/.test(text.slice(i + 1, i + 3))) { bytes.push(parseInt(text.slice(i + 1, i + 3), 16)); i += 2 } else bytes.push(text.charCodeAt(i) & 0xff)
+  }
+  return Buffer.from(bytes)
+}
+
+/** Parses `value; name=param; name*=utf-8''enc; name*0*=...` and resolves RFC 2231 extended and continued parameters. */
+function parseStructured(text: string | undefined): Structured {
+  if (text === undefined) return { value: '', params: new Map() }
+  const [first, ...rest] = splitTop(text, ';')
+  const plain = new Map<string, string>()
+  const groups = new Map<string, { n: number; ext: boolean; value: string }[]>()
+  for (const part of rest) {
+    const eq = part.indexOf('=')
+    if (eq <= 0) continue
+    const key = part.slice(0, eq).trim().toLowerCase()
+    const value = unquote(part.slice(eq + 1))
+    const m = /^([^*]+)(?:\*(\d+))?(\*)?$/.exec(key)
+    if (m === null || (m[2] === undefined && m[3] === undefined)) { plain.set(key, value); continue }
+    const list = groups.get(m[1]!) ?? []
+    list.push({ n: m[2] === undefined ? 0 : Number(m[2]), ext: m[3] !== undefined, value })
+    groups.set(m[1]!, list)
+  }
+  const params = new Map(plain)
+  for (const [name, list] of groups) {
+    list.sort((a, b) => a.n - b.n)
+    let charset: string | undefined
+    const chunks: Buffer[] = []
+    list.forEach((seg, i) => {
+      let v = seg.value
+      if (i === 0 && seg.ext) {
+        const m = /^([^']*)'[^']*'(.*)$/s.exec(v)
+        if (m !== null) { charset = m[1] === '' ? undefined : m[1]; v = m[2]! }
+      }
+      chunks.push(seg.ext ? percentBytes(v) : Buffer.from(v, 'latin1'))
+    })
+    params.set(name, decodeCharset(Buffer.concat(chunks), charset))
+  }
+  return { value: (first ?? '').trim(), params }
+}
+
+// ---- addresses ----
+
+/** Parses an address list (RFC 5322 mailboxes, groups, quoted names, comments, encoded words). */
+export function parseAddresses(text: string | undefined): ParsedAddress[] {
+  if (text === undefined || text.trim() === '') return []
+  const mailboxes: string[] = []
+  let cur = ''
+  let quoted = false
+  let angle = false
+  let comment = 0
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!
+    if (quoted) {
+      cur += c
+      if (c === '\\' && i + 1 < text.length) cur += text[++i]!
+      else if (c === '"') quoted = false
+      continue
+    }
+    if (comment > 0) {
+      cur += c
+      if (c === '\\' && i + 1 < text.length) cur += text[++i]!
+      else if (c === '(') comment++
+      else if (c === ')') comment--
+      continue
+    }
+    if (c === '"') { quoted = true; cur += c; continue }
+    if (c === '(') { comment = 1; cur += c; continue }
+    if (c === '<') angle = true
+    else if (c === '>') angle = false
+    if (!angle && c === ':') { cur = ''; continue } // group name
+    if (!angle && (c === ',' || c === ';')) { mailboxes.push(cur); cur = ''; continue }
+    cur += c
+  }
+  mailboxes.push(cur)
+
+  const result: ParsedAddress[] = []
+  for (const box of mailboxes) {
+    const parsed = parseMailbox(box)
+    if (parsed !== null) result.push(parsed)
+  }
+  return result
+}
+
+function stripComments(text: string): { text: string; comments: string[] } {
+  const comments: string[] = []
+  let out = ''
+  let depth = 0
+  let quoted = false
+  let current = ''
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!
+    if (quoted) {
+      out += c
+      if (c === '\\' && i + 1 < text.length) out += text[++i]!
+      else if (c === '"') quoted = false
+      continue
+    }
+    if (depth > 0) {
+      if (c === '\\' && i + 1 < text.length) { current += text[++i]!; continue }
+      if (c === '(') depth++
+      else if (c === ')') { depth--; if (depth === 0) { comments.push(current); current = ''; continue } }
+      current += c
+      continue
+    }
+    if (c === '"') { quoted = true; out += c; continue }
+    if (c === '(') { depth = 1; continue }
+    out += c
+  }
+  return { text: out, comments }
+}
+
+function parseMailbox(box: string): ParsedAddress | null {
+  const { text, comments } = stripComments(box)
+  const t = text.trim()
+  if (t === '') return null
+  const lt = t.lastIndexOf('<')
+  const gt = t.lastIndexOf('>')
+  if (lt >= 0 && gt > lt) {
+    const address = t.slice(lt + 1, gt).trim().replace(/^.*:/, '')
+    const name = decodeWords(unquote(t.slice(0, lt)))
+    return address === '' ? null : { address, name }
+  }
+  const address = unquote(t)
+  if (!address.includes('@')) return null
+  return { address, name: comments.length > 0 ? decodeWords(comments[0]!.trim()) : '' }
+}
+
+function idsOf(text: string | undefined): string[] {
+  if (text === undefined) return []
+  return [...text.matchAll(/<([^<>\s]+)>/g)].map(m => m[1]!)
+}
+
+// ---- bodies ----
+
+function decodeTransfer(body: string, encoding: string | undefined): Buffer {
+  const e = (encoding ?? '7bit').trim().toLowerCase()
+  if (e === 'base64') return Buffer.from(body.replace(/[^A-Za-z0-9+/=_-]/g, ''), 'base64')
+  if (e === 'quoted-printable') {
+    const joined = body.replace(/[ \t]+(?=\r?\n)/g, '').replace(/=\r?\n/g, '')
+    const bytes: number[] = []
+    for (let i = 0; i < joined.length; i++) {
+      const c = joined[i]!
+      if (c === '=' && /^[0-9a-fA-F]{2}$/.test(joined.slice(i + 1, i + 3))) { bytes.push(parseInt(joined.slice(i + 1, i + 3), 16)); i += 2 } else bytes.push(joined.charCodeAt(i) & 0xff)
+    }
+    return Buffer.from(bytes)
+  }
+  return Buffer.from(body, 'latin1')
+}
+
+function splitMultipart(body: string, boundary: string): string[] {
+  const delim = `--${boundary}`
+  const parts: string[] = []
+  let start = -1
+  let pos = 0
+  for (;;) {
+    const idx = body.indexOf(delim, pos)
+    if (idx < 0) break
+    pos = idx + 1
+    if (idx > 0 && body[idx - 1] !== '\n') continue
+    const after = idx + delim.length
+    const eol = body.indexOf('\n', after)
+    const rest = body.slice(after, eol < 0 ? body.length : eol)
+    const closing = rest.startsWith('--')
+    if (!closing && !/^[ \t]*\r?$/.test(rest)) continue
+    if (start >= 0) {
+      let end = idx
+      if (body[end - 1] === '\n') end--
+      if (body[end - 1] === '\r') end--
+      parts.push(body.slice(start, Math.max(start, end)))
+      start = -1
+    }
+    if (closing || eol < 0) return parts
+    start = eol + 1
+    pos = start
+  }
+  if (start >= 0) parts.push(body.slice(start)) // no closing boundary
+  return parts
+}
+
+interface Collected {
+  text: string | null
+  html: string | null
+  attachments: ParsedAttachment[]
+}
+
+function walk(entity: Entity, depth: number, out: Collected): void {
+  const type = parseStructured(header(entity, 'content-type'))
+  const mediaType = (type.value === '' ? 'text/plain' : type.value).toLowerCase()
+  const disposition = parseStructured(header(entity, 'content-disposition'))
+  const disp = disposition.value.toLowerCase()
+  const contentId = idsOf(header(entity, 'content-id'))[0] ?? null
+
+  if (mediaType.startsWith('multipart/') && depth < MAX_DEPTH) {
+    const boundary = type.params.get('boundary')
+    if (boundary !== undefined && boundary !== '') {
+      for (const part of splitMultipart(entity.body, boundary)) walk(splitEntity(part), depth + 1, out)
+      return
+    }
+  }
+
+  const rawName = disposition.params.get('filename') ?? type.params.get('name')
+  const filename = rawName === undefined ? null : decodeWords(rawName)
+  const isText = mediaType === 'text/plain' || mediaType === 'text/html'
+  const attached = disp === 'attachment' || filename !== null || !isText || mediaType.startsWith('multipart/')
+
+  const content = decodeTransfer(entity.body, header(entity, 'content-transfer-encoding'))
+  if (!attached) {
+    const decoded = decodeCharset(content, type.params.get('charset'))
+    if (mediaType === 'text/html') { if (out.html === null) out.html = decoded } else if (out.text === null) out.text = decoded
+    return
+  }
+  out.attachments.push({
+    filename,
+    mediaType: mediaType.startsWith('multipart/') ? 'application/octet-stream' : mediaType,
+    size: content.length,
+    contentId,
+    inline: disp === 'inline' || (disp === '' && contentId !== null),
+    content,
+  })
+}
+
+const EMPTY: ParsedMessage = {
+  messageId: null, inReplyTo: null, threadIds: [], references: [], from: null, fromProblem: null, to: [], cc: [], replyTo: [],
+  subject: '', date: null, text: null, html: null, attachments: [],
+}
+
+/** Parses a raw RFC 5322 message. Never throws; unreadable input yields as much as could be read. */
+export function parseMime(raw: Buffer): ParsedMessage {
+  try {
+    const entity = splitEntity(raw.toString('latin1'))
+    const out: Collected = { text: null, html: null, attachments: [] }
+    walk(entity, 0, out)
+    const inReplyToIds = idsOf(header(entity, 'in-reply-to'))
+    const references = idsOf(header(entity, 'references'))
+    const threadIds = [...new Set([...inReplyToIds, ...references])]
+    const date = header(entity, 'date')
+    const parsedDate = date === undefined ? null : new Date(date)
+    const fromFields = headers(entity, 'from')
+    const fromMailboxes = fromFields.length === 1 ? parseAddresses(fromFields[0]) : []
+    const fromProblem = fromFields.length > 1 ? 'several-from-fields' as const
+      : fromMailboxes.length > 1 ? 'several-mailboxes' as const : null
+    return {
+      messageId: idsOf(header(entity, 'message-id'))[0] ?? null,
+      inReplyTo: inReplyToIds[0] ?? null,
+      threadIds,
+      references,
+      from: fromProblem === null ? fromMailboxes[0] ?? null : null,
+      fromProblem,
+      to: parseAddresses(header(entity, 'to')),
+      cc: parseAddresses(header(entity, 'cc')),
+      replyTo: parseAddresses(header(entity, 'reply-to')),
+      subject: decodeWords(header(entity, 'subject') ?? ''),
+      date: parsedDate === null || Number.isNaN(parsedDate.getTime()) ? null : parsedDate,
+      text: out.text,
+      html: out.html,
+      attachments: out.attachments,
+    }
+  } catch {
+    return EMPTY
+  }
+}

package/src/infra/email/namespace.ts

@@ -0,0 +1,22 @@
+import { createMail } from './mail.js'
+import { ses, devStandIn } from './providers.js'
+import { snsWebhook } from './sns.js'
+import { createInbound, sesReceipt, inboundFolder } from './inbound.js'
+
+/** Mail namespace — email through a job queue, SES v2 or a dev stand-in, bounce and complaint suppression, and receiving. */
+export const mail = {
+  /** Creates the mail interface: `send(db, { to, template, data, key })` in the caller's transaction, and the `jobs` that deliver. */
+  create: createMail,
+  /** Amazon SES v2 provider, SigV4-signed without the AWS SDK. */
+  ses,
+  /** Development provider that writes each message to a file instead of sending; refused in production. */
+  devStandIn,
+  /** Inbound handler for SES bounce and complaint events delivered through SNS; suppresses the address. */
+  snsWebhook,
+  /** Receiving email: `inbound({ source, queue, onMessage, ... })` returns `{ webhook, jobs, scan, sweep, get }`; messages arrive parsed, threaded into conversations, attachments stored as tenant files. */
+  inbound: createInbound,
+  /** Inbound source: SES receipt rule storing raw messages in S3 and notifying a signed SNS topic. */
+  sesReceipt,
+  /** Inbound development source: `.eml` files dropped in a folder, received by `scan()`; refused in production. */
+  inboundFolder,
+} as const

package/src/infra/email/providers.ts

@@ -0,0 +1,111 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { signV4, type AwsCredentials } from '../aws/sigv4.js'
+import { awsCredentials } from '../aws/credentials.js'
+
+/** One rendered message handed to a provider. */
+export interface OutgoingMessage {
+  /** The message row id; unique per message. */
+  readonly messageId: string
+  readonly from: string
+  readonly to: string
+  readonly subject: string
+  readonly text: string
+  readonly html?: string
+  readonly configurationSet?: string
+  /** Extra headers, e.g. `In-Reply-To` and `References` for a reply. */
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+/** Sends one rendered message. A throw means it was not accepted and may be retried. */
+export interface MailProvider {
+  readonly name: string
+  send(message: OutgoingMessage): Promise<{ providerMessageId: string }>
+}
+
+export interface SesConfig {
+  readonly region: string
+  /** Called for every send. Default: `awsCredentials()` (environment, ECS task role, EC2 instance role). */
+  readonly credentials?: () => Promise<AwsCredentials>
+  readonly configurationSet?: string
+  /** Base URL instead of `https://email.<region>.amazonaws.com`; for tests against a local server. */
+  readonly endpoint?: string
+}
+
+/**
+ * Amazon SES v2 provider. Posts to `/v2/email/outbound-emails`, signed with SigV4
+ * (no AWS SDK). Credentials default to `awsCredentials()`.
+ * A non-2xx answer throws with the status and AWS's message.
+ */
+export function ses(config: SesConfig): MailProvider {
+  const getCredentials = config.credentials ?? awsCredentials()
+  const base = (config.endpoint ?? `https://email.${config.region}.amazonaws.com`).replace(/\/+$/, '')
+  return {
+    name: 'ses',
+    async send(message) {
+      const set = message.configurationSet ?? config.configurationSet
+      const headerList = Object.entries(message.headers ?? {}).map(([Name, Value]) => ({ Name, Value }))
+      const body = JSON.stringify({
+        FromEmailAddress: message.from,
+        Destination: { ToAddresses: [message.to] },
+        Content: {
+          Simple: {
+            Subject: { Data: message.subject, Charset: 'UTF-8' },
+            ...(headerList.length > 0 ? { Headers: headerList } : {}),
+            Body: {
+              Text: { Data: message.text, Charset: 'UTF-8' },
+              ...(message.html !== undefined ? { Html: { Data: message.html, Charset: 'UTF-8' } } : {}),
+            },
+          },
+        },
+        ...(set !== undefined ? { ConfigurationSetName: set } : {}),
+      })
+      const url = `${base}/v2/email/outbound-emails`
+      const headers = signV4({
+        method: 'POST', url, headers: { 'content-type': 'application/json' }, body,
+        region: config.region, service: 'ses', credentials: await getCredentials(),
+      })
+      const res = await fetch(url, { method: 'POST', headers, body })
+      const raw = await res.text()
+      let parsed: Record<string, unknown> = {}
+      try { parsed = JSON.parse(raw) as Record<string, unknown> } catch { /* not JSON */ }
+      if (!res.ok) {
+        const detail = String(parsed['message'] ?? parsed['Message'] ?? raw.slice(0, 200))
+        throw new Error(`[pipework] SES refused the message: HTTP ${res.status} ${res.headers.get('x-amzn-errortype') ?? ''} ${detail}`.replace(/ +/g, ' '))
+      }
+      const id = parsed['MessageId']
+      if (typeof id !== 'string') throw new Error('[pipework] SES answered without a MessageId.')
+      return { providerMessageId: id }
+    },
+  }
+}
+
+/**
+ * Development stand-in: writes each rendered message to `<dir>/<messageId>.json`
+ * (from, to, subject, text, html, and headers when there are any) and logs one line, sending nothing.
+ * The file appears only once it is complete. `mail.create` refuses it when the environment is production.
+ */
+export function devStandIn(config: { readonly dir: string }): MailProvider {
+  return {
+    name: 'dev-stand-in',
+    async send(message) {
+      await mkdir(config.dir, { recursive: true })
+      const file = join(config.dir, `${message.messageId}.json`)
+      const { from, to, subject, text, html, headers } = message
+      const tmp = join(config.dir, `.${message.messageId}.json.tmp`)
+      try {
+        await writeFile(tmp, JSON.stringify({
+          from, to, subject, text, ...(html !== undefined ? { html } : {}),
+          ...(headers !== undefined && Object.keys(headers).length > 0 ? { headers } : {}),
+        }, null, 2))
+        await rename(tmp, file)
+      } catch (err) {
+        await rm(tmp, { force: true }).catch(() => {})
+        throw err
+      }
+      getBaseLogger().info({ event: 'email dev stand-in', to, file }, 'email written to file instead of sent')
+      return { providerMessageId: `dev-${message.messageId}` }
+    },
+  }
+}

package/src/infra/email/schema.ts

@@ -0,0 +1,96 @@
+// The tables behind `mail`. Enabled with `email: {}` in the blueprint;
+// `pipework generate` then emits them into the default database's migrations,
+// IF NOT EXISTS. Not tenant-scoped: a bounce notification arrives with no
+// tenant, and a suppressed address is suppressed for every tenant. The same holds
+// for `pipework_email_unsubscribes`: the one-click POST arrives from a mail
+// provider with no tenant, and an opt-out names an address and a list, not a tenant.
+
+import { define } from '../../data/domain/index.js'
+import { field } from '../../data/domain/field.js'
+import { schema } from '../../data/schema/namespace.js'
+import { index, unique } from '../../data/db/idx/index.js'
+
+export const EMAIL_TABLE_NAMES: ReadonlySet<string> = new Set([
+  'pipework_email_messages', 'pipework_email_suppressions', 'pipework_email_inbound', 'pipework_email_unsubscribes',
+])
+
+export const EMAIL_STATUSES = ['queued', 'sending', 'sent', 'suppressed', 'unsubscribed', 'failed'] as const
+export const INBOUND_STATUSES = ['received', 'processed', 'failed'] as const
+export const INBOUND_SOURCES = ['ses', 'folder'] as const
+export const SUPPRESSION_REASONS = ['bounce', 'complaint'] as const
+
+export const emailMessages = define('pipework_email_messages', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  key: field.text(),
+  toAddress: field.text(),
+  template: field.text(),
+  data: field.jsonb(schema.check.json()),
+  status: field.enum(EMAIL_STATUSES).default('queued'),
+  providerMessageId: field.text().nullable(),
+  error: field.text().nullable(),
+  traceId: field.uuid().nullable(),
+  createdAt: field.timestamp().default('now'),
+  sentAt: field.timestamp().nullable(),
+  sendingAt: field.timestamp().nullable(),
+  failedAt: field.timestamp().nullable(),
+  conversationId: field.uuid().nullable(),
+  inReplyToInbound: field.uuid().nullable(),
+  list: field.text().nullable(),
+}, {
+  indexes: (t) => ({
+    byKey: unique('pipework_email_messages_key_key').on(t['key']),
+    byProviderId: index('idx_pipework_email_messages_provider_id').on(t['providerMessageId']),
+    byConversation: index('idx_pipework_email_messages_conversation').on(t['conversationId']),
+  }),
+})
+
+export const emailSuppressions = define('pipework_email_suppressions', {
+  address: field.text().primaryKey(),
+  reason: field.enum(SUPPRESSION_REASONS),
+  detail: field.jsonb(schema.check.json()).nullable(),
+  createdAt: field.timestamp().default('now'),
+})
+
+// One row per (address, list) that opted out of a list's mail. Address lowercased.
+export const emailUnsubscribes = define('pipework_email_unsubscribes', {
+  address: field.text(),
+  list: field.text(),
+  createdAt: field.timestamp().default('now'),
+}, {
+  primaryKey: ['address', 'list'],
+})
+
+// One row per received message. Bodies are not stored here: the raw message is
+// the copy (in the receipt bucket or the stand-in's `received/` folder) and is
+// deleted after `raw_expires_at`. Not tenant-scoped: the row exists before a
+// tenant is known; `tenant_id` is set once the app's resolver names one.
+export const emailInbound = define('pipework_email_inbound', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  sourceId: field.text(),
+  source: field.enum(INBOUND_SOURCES),
+  rawLocation: field.jsonb(schema.check.json()),
+  rawExpiresAt: field.timestamp(),
+  rawDeletedAt: field.timestamp().nullable(),
+  status: field.enum(INBOUND_STATUSES).default('received'),
+  error: field.text().nullable(),
+  messageIdHeader: field.text().nullable(),
+  inReplyTo: field.text().nullable(),
+  references: field.jsonb(schema.check.json()).nullable(),
+  fromAddress: field.text().nullable(),
+  subject: field.text().nullable(),
+  conversationId: field.uuid().nullable(),
+  tenantId: field.uuid().nullable(),
+  verdicts: field.jsonb(schema.check.json()).nullable(),
+  recipients: field.jsonb(schema.check.json()).nullable(),
+  attachmentFiles: field.jsonb(schema.check.json()).nullable(),
+  receivedAt: field.timestamp().default('now'),
+  processedAt: field.timestamp().nullable(),
+  failedAt: field.timestamp().nullable(),
+  traceId: field.uuid().nullable(),
+}, {
+  indexes: (t) => ({
+    bySource: unique('pipework_email_inbound_source_id_key').on(t['sourceId']),
+    byMessageId: index('idx_pipework_email_inbound_message_id').on(t['messageIdHeader']),
+    byExpiry: index('idx_pipework_email_inbound_raw_expires').on(t['rawExpiresAt']),
+  }),
+})