pipework 0.252.0 → 0.253.0

package/src/infra/email/mail.ts

@@ -0,0 +1,517 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { pipeSystem } from '../../data/db/db.js'
+import { insert, remove } from '../../data/write/index.js'
+import { schema } from '../../data/schema/namespace.js'
+import { fitting } from '../../request/di/index.js'
+import { Builder } from '../../request/di/builder.js'
+import { and, eq } from '../../data/query/index.js'
+import { getContext } from '../../request/context/store.js'
+import { ValidationError } from '../../core/errors/index.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import type { Queue } from '../../async/jobs/queue.js'
+import type { Handler } from '../../request/di/types.js'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import { auditEmail } from './audit.js'
+import type { MailProvider } from './providers.js'
+import { unscopedExecutor, requireUnscopedExecutor } from '../../auth/tenant/scoped-db.js'
+import { describeError } from '../../core/logging/error-chain.js'
+import { emailUnsubscribes } from './schema.js'
+import { LIST_RE, MIN_UNSUBSCRIBE_SECRET, signUnsubscribeToken, unsubscribeLink, verifyUnsubscribeToken } from './unsubscribe.js'
+
+/** What a template renders: the subject and the text body, optionally an HTML body. */
+export interface RenderedEmail {
+  readonly subject: string
+  readonly text: string
+  readonly html?: string
+}
+
+/** What a template learns about the message it renders, as its second argument. */
+export interface EmailRenderMeta {
+  /** The message's one-click unsubscribe link (the same one its `List-Unsubscribe` header carries); null for a message with no `list`. */
+  readonly unsubscribeUrl: string | null
+}
+
+/** The app's templates: a function per name from the data (and the render meta) to the rendered message. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- each template has its own data type; `send` checks it per name
+export type EmailTemplates = Record<string, (data: any, meta: EmailRenderMeta) => RenderedEmail>
+
+export interface MailConfig<T extends EmailTemplates> {
+  readonly provider: MailProvider
+  readonly templates: T
+  /** The From address, e.g. `Verity <no-reply@mail.verity.pub>`. */
+  readonly from: string
+  /** The app's job queue; its worker surface must run `mail.jobs`. */
+  readonly queue: Queue
+  readonly configurationSet?: string
+  /** The app's environment. `devStandIn` is refused when this is `production`. */
+  readonly environment?: string
+  /** Seconds after which a message left `sending` by a crashed run may be sent again. Default 600. */
+  readonly sendingStaleSeconds?: number
+  /** The queue priority of this module's delivery jobs; higher is claimed first. Default: the queue's (0). */
+  readonly priority?: number
+  /**
+   * One-click unsubscribe for mail sent with a `list`. `url` is the absolute https URL of the route `unsubscribeHttp()`
+   * serves (http is allowed outside production); `secret` signs the links, at least 32 characters and the same in every
+   * process. A `send` with a `list` throws when this is unset.
+   */
+  readonly unsubscribe?: { readonly url: string; readonly secret: string }
+}
+
+export interface SendInput<T extends EmailTemplates, K extends keyof T & string> {
+  readonly to: string
+  readonly template: K
+  readonly data: Parameters<T[K]>[0]
+  /** Idempotency key: a second send with the same key sends nothing. */
+  readonly key: string
+  /**
+   * Puts the message in a conversation, so a reply to it threads there (the provider's message id
+   * is matched against `References`/`In-Reply-To` of received mail). Default: the conversation of `inReplyTo`.
+   */
+  readonly conversationId?: string
+  /**
+   * The id of a received message (`ReceivedEmail.id`) this one answers: the sent message carries
+   * `In-Reply-To: <its Message-ID>` and `References` with its references plus its Message-ID (at most 20 ids).
+   */
+  readonly inReplyTo?: string
+  /** The queue priority of this message's delivery job; higher is claimed first. Default: the module's `priority`. */
+  readonly priority?: number
+  /**
+   * Data computed when the message is delivered, never stored: `name` is a function registered with
+   * `registerLateData`, `ref` the reference it receives. Its result is merged over `data` for rendering only.
+   * The stored row holds `name` and `ref` under the reserved data key `__late`. Delivery fails if `name` is not registered.
+   */
+  readonly lateData?: { readonly name: string; readonly ref: string }
+  /**
+   * Puts the message on a list, e.g. `'notice-digest'` (letters, digits, `.`, `_`, `-`; at most 64). It then carries
+   * RFC 8058 `List-Unsubscribe` and `List-Unsubscribe-Post` headers, and is skipped at delivery (status `unsubscribed`,
+   * no provider call) when the address has opted out of that list. Needs `MailConfig.unsubscribe`. Leave it off for
+   * transactional mail: that is never affected by an opt-out.
+   */
+  readonly list?: string
+}
+
+/** Computes the template data a message gets at delivery from the reference stored with it. */
+export type LateData = (db: DB, ref: string) => Promise<Record<string, unknown>>
+
+export interface SendResult {
+  readonly messageId: string
+  /** False when the key was already used; `messageId` is then the earlier message. */
+  readonly queued: boolean
+}
+
+/** A message as `mail.sentTo` reads it. `rendered` is null when its template is gone or throws. */
+export interface SentMail {
+  readonly id: string
+  readonly template: string
+  readonly status: string
+  /** The data stored with the message, without the `__late` reference. */
+  readonly data: unknown
+  readonly createdAt: Date
+  readonly rendered: RenderedEmail | null
+}
+
+export interface Mail<T extends EmailTemplates> {
+  /**
+   * Records the message and enqueues its send in `db`, so the caller's rollback drops both.
+   * The same `key` twice gives one message, one job and one delivery.
+   */
+  send<K extends keyof T & string>(db: DB, input: SendInput<T, K>): Promise<SendResult>
+  /**
+   * For tests and support tools: the messages to an address (any case), oldest first, optionally of one template,
+   * each rendered from its stored data (late data resolved) as delivery would render it.
+   */
+  sentTo(db: DB, address: string, options?: { readonly template?: keyof T & string }): Promise<readonly SentMail[]>
+  /**
+   * Records that `address` (any case) opted out of `list`; a second call changes nothing. Later sends on that list to
+   * that address are skipped; mail on other lists and mail with no list is unaffected. Writes through `pipe.insert`
+   * (needs a Flow), so it is audited when the calling step declares a touch on `pipework_email_unsubscribes`.
+   */
+  unsubscribe(db: DB, address: string, list: string): Promise<void>
+  /** True when `address` (any case) has opted out of `list`. */
+  unsubscribed(db: DB, address: string, list: string): Promise<boolean>
+  /** Removes the opt-out of `address` from `list`, so its mail is delivered again. Writes like `unsubscribe`. */
+  resubscribe(db: DB, address: string, list: string): Promise<void>
+  /**
+   * The routes behind the unsubscribe link, at the path of `MailConfig.unsubscribe.url`: GET shows a confirm page
+   * with a form, POST (the mail provider's one-click, form-urlencoded, multipart or empty body, never read) records
+   * the opt-out. A token that is not valid for this secret is a 400 page. Public, no tenant; the address is
+   * escaped on the page and never logged. Mount it on the HTTP surface like `alerts.http`. Throws without `unsubscribe` config.
+   */
+  unsubscribeHttp(): Handler<Record<string, unknown>, unknown>[]
+  /** Registers (or replaces) a late-data function by name; see `SendInput.lateData`. Used by other pipework modules. */
+  registerLateData(name: string, fn: LateData): void
+  /** Job handlers for the send job; spread into the worker surface's `jobs`. */
+  readonly jobs: readonly Handler<Record<string, unknown>, unknown>[]
+}
+
+export const SEND_JOB = 'pipework.email.send'
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const MAX_REFERENCES = 20
+const MAX_REFERENCES_CHARS = 900
+const ADDRESS_RE = /^[^\s@<>,;"]+@[^\s@<>,;"]+$/
+
+/** The reply headers for a message answering a received one: In-Reply-To, and References capped to 20 ids and the provider's header length. */
+export function replyHeaders(messageId: string, references: readonly string[]): Record<string, string> {
+  const ids = [...references, messageId].filter(id => /^[\x21-\x7e]+$/.test(id) && !/[<>]/.test(id))
+  const unique = ids.filter((id, i) => ids.lastIndexOf(id) === i).slice(-MAX_REFERENCES)
+  while (unique.length > 1 && unique.map(i => `<${i}>`).join(' ').length > MAX_REFERENCES_CHARS) unique.shift()
+  return { 'In-Reply-To': `<${messageId}>`, 'References': unique.map(i => `<${i}>`).join(' ') }
+}
+
+function lateReference(data: unknown): { name: string; ref: string } | null {
+  if (typeof data !== 'object' || data === null) return null
+  const late = (data as Record<string, unknown>)['__late']
+  if (typeof late !== 'object' || late === null) return null
+  const { name, ref } = late as Record<string, unknown>
+  return typeof name === 'string' && typeof ref === 'string' ? { name, ref } : null
+}
+
+function storedData(input: { data?: unknown; lateData?: { name: string; ref: string } }): unknown {
+  if (input.lateData === undefined) return input.data ?? null
+  const base = typeof input.data === 'object' && input.data !== null ? input.data : {}
+  return { ...base, __late: { name: input.lateData.name, ref: input.lateData.ref } }
+}
+
+export function normalizeAddress(address: string): string {
+  return address.trim().toLowerCase()
+}
+
+/**
+ * Creates the transactional email interface.
+ *
+ * `send(db, { to, template, data, key })` writes a `pipework_email_messages` row and
+ * enqueues a `pipework.email.send` job in the caller's transaction. The job renders the
+ * app's template and sends through the provider, at most once per key, skipping an
+ * address on the suppression list (status `suppressed`, no provider call), and a message on a `list` whose address opted out of it (status `unsubscribed`, no provider call). The
+ * provider call is a trace step and `Email:sent` / `Email:suppressed` / `Email:unsubscribed` / `Email:failed`
+ * audit records are written under it, in the trace of the flow that called `send`.
+ *
+ * Needs blueprint `email: {}` (tables `pipework_email_messages`, `pipework_email_suppressions`, `pipework_email_inbound`, `pipework_email_unsubscribes`).
+ * A provider error returns the message to `queued` with `error` set and rethrows, so the
+ * queue retries (set `maxAttempts` on the queue); if the queue gives up the row keeps the error.
+ * A run claims the message with a conditional update (`status` `queued`, or `sending` for longer than
+ * `sendingStaleSeconds`), so a re-run of a job whose first run is still in flight does not call the provider.
+ * Residual window: a crash mid-send leaves the message `sending` for the stale window, after which a retry
+ * may send it once more; likewise if the provider accepted it and the process died before the row was marked `sent`. SES v2 has no idempotency token to close it.
+ * With `conversationId` / `inReplyTo` the message joins a conversation and carries reply headers (see `SendInput`).
+ * Message bodies and template data are never logged.
+ */
+export function createMail<T extends EmailTemplates>(config: MailConfig<T>): Mail<T> {
+  if (config.provider.name === 'dev-stand-in' && config.environment === 'production') {
+    throw new Error(
+      '[pipework] mail.devStandIn is refused in production.\n\n' +
+      '  The stand-in writes messages to files instead of sending them.\n' +
+      '  Configure a real provider, e.g. mail.ses({ region, credentials }).\n',
+    )
+  }
+
+  const unsubscribe = config.unsubscribe
+  if (unsubscribe !== undefined) validateUnsubscribe(unsubscribe, config.environment)
+
+  const staleSeconds = config.sendingStaleSeconds ?? 600
+  const lateFns = new Map<string, LateData>()
+
+  async function isUnsubscribed(db: DB, address: string, list: string): Promise<boolean> {
+    const rows = await db.execute(sql`SELECT 1 FROM pipework_email_unsubscribes WHERE address = ${normalizeAddress(address)} AND list = ${list}`)
+    return rows.length > 0
+  }
+
+  /** What a template is told: the signed link for a list message, null for any other. */
+  function renderMeta(messageId: string, to: string, list: string | null): EmailRenderMeta {
+    if (list === null) return { unsubscribeUrl: null }
+    if (unsubscribe === undefined) {
+      throw new Error(`[pipework] Email message ${messageId} is on list "${list}" but mail config has no unsubscribe: { url, secret }; it is not sent without an unsubscribe link.`)
+    }
+    return { unsubscribeUrl: unsubscribeLink(unsubscribe.url, signUnsubscribeToken(unsubscribe.secret, normalizeAddress(to), list)) }
+  }
+
+  /** The stored data with its late data computed and merged over it; throws when the named function is not registered. */
+  async function withLateData(db: DB, stored: unknown, messageId: string): Promise<unknown> {
+    const lateRef = lateReference(stored)
+    if (lateRef === null) return stored
+    const fn = lateFns.get(lateRef.name)
+    if (fn === undefined) throw new Error(`[pipework] Email message ${messageId}: no late-data function named "${lateRef.name}" is registered.`)
+    const rest = { ...(stored as Record<string, unknown>) }
+    delete rest['__late']
+    return { ...rest, ...(await fn(db, lateRef.ref)) }
+  }
+
+  const deliver = __flowStep({ ref: 'pipework/email:deliver' }, async (messageId: string): Promise<{ status: string }> => {
+    const db = pipeSystem()
+    const rows = await db.execute(sql`SELECT * FROM pipework_email_messages WHERE id = ${messageId}::uuid`)
+    const row = rows[0]
+    if (row === undefined) throw new Error(`[pipework] Email message ${messageId} does not exist.`)
+    const status = row['status'] as string
+    if (status === 'sent' || status === 'suppressed' || status === 'unsubscribed' || status === 'failed') return { status }
+
+    const environment = getContext()?.instance.config.environment
+    if (config.provider.name === 'dev-stand-in' && environment === 'production') {
+      throw new Error('[pipework] mail.devStandIn is refused in production.')
+    }
+
+    const to = row['to_address'] as string
+    const suppressed = await db.execute(sql`SELECT reason FROM pipework_email_suppressions WHERE address = ${normalizeAddress(to)}`)
+    if (suppressed.length > 0) {
+      await db.execute(sql`UPDATE pipework_email_messages SET status = 'suppressed' WHERE id = ${messageId}::uuid`)
+      await auditEmail('suppressed', messageId, { reason: suppressed[0]!['reason'] })
+      getBaseLogger().info({ event: 'email suppressed send', messageId }, 'email skipped: address is suppressed')
+      return { status: 'suppressed' }
+    }
+
+    const list = (row['list'] as string | null | undefined) ?? null
+    if (list !== null && await isUnsubscribed(db, to, list)) {
+      await db.execute(sql`UPDATE pipework_email_messages SET status = 'unsubscribed' WHERE id = ${messageId}::uuid`)
+      await auditEmail('unsubscribed', messageId, { list })
+      getBaseLogger().info({ event: 'email unsubscribed send', messageId, list }, 'email skipped: address has opted out of the list')
+      return { status: 'unsubscribed' }
+    }
+    const meta = renderMeta(messageId, to, list)
+
+    let headers: Record<string, string> | undefined
+    const inReplyToInbound = row['in_reply_to_inbound'] as string | null
+    if (inReplyToInbound !== null) {
+      const parent = (await db.execute(sql`SELECT message_id_header, "references" FROM pipework_email_inbound WHERE id = ${inReplyToInbound}::uuid`))[0]
+      const parentId = (parent?.['message_id_header'] as string | null | undefined) ?? null
+      if (parentId !== null) headers = replyHeaders(parentId, (parent!['references'] as string[] | null) ?? [])
+    }
+
+    if (meta.unsubscribeUrl !== null) {
+      headers = { ...headers, 'List-Unsubscribe': `<${meta.unsubscribeUrl}>`, 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click' }
+    }
+
+    const templateName = row['template'] as string
+    const lateRef = lateReference(row['data'])
+    let templateData: unknown
+    try {
+      templateData = await withLateData(db, row['data'], messageId)
+    } catch (err) {
+      if (lateRef !== null) {
+        const message = `no late-data function named "${lateRef.name}" is registered`
+        getBaseLogger().error({ event: 'email failed', messageId }, `email not sent: ${message}`)
+      }
+      throw err
+    }
+    const template = config.templates[templateName]
+    let rendered: RenderedEmail | null = null
+    let renderError = ''
+    if (template === undefined) {
+      renderError = `no template named "${templateName}"`
+    } else {
+      try {
+        rendered = template(templateData, meta)
+      } catch (err) {
+        renderError = `template "${templateName}" threw: ${describeError(err).message}`
+      }
+    }
+    if (rendered === null) {
+      await db.execute(sql`UPDATE pipework_email_messages SET status = 'failed', failed_at = now(), error = ${renderError} WHERE id = ${messageId}::uuid`)
+      await auditEmail('failed', messageId, { error: renderError })
+      getBaseLogger().error({ event: 'email failed', messageId }, `email not sent: ${renderError}`)
+      return { status: 'failed' }
+    }
+
+    const claimed = await db.execute(sql`
+      UPDATE pipework_email_messages SET status = 'sending', sending_at = now()
+      WHERE id = ${messageId}::uuid
+        AND (status = 'queued' OR (status = 'sending' AND sending_at < now() - make_interval(secs => ${staleSeconds})))
+      RETURNING id`)
+    if (claimed.length === 0) {
+      getBaseLogger().info({ event: 'email send held elsewhere', messageId }, 'email not sent: another run holds the message or it is finished')
+      return { status: 'held' }
+    }
+    try {
+      const sent = await config.provider.send({
+        messageId, from: config.from, to,
+        subject: rendered.subject, text: rendered.text,
+        ...(rendered.html !== undefined ? { html: rendered.html } : {}),
+        ...(config.configurationSet !== undefined ? { configurationSet: config.configurationSet } : {}),
+        ...(headers !== undefined ? { headers } : {}),
+      })
+      await db.execute(sql`
+        UPDATE pipework_email_messages
+        SET status = 'sent', sending_at = NULL, provider_message_id = ${sent.providerMessageId}, sent_at = now(), error = NULL
+        WHERE id = ${messageId}::uuid`)
+      await auditEmail('sent', messageId, { provider: config.provider.name, providerMessageId: sent.providerMessageId })
+      return { status: 'sent' }
+    } catch (err) {
+      const message = describeError(err).message
+      await db.execute(sql`UPDATE pipework_email_messages SET status = 'queued', sending_at = NULL, error = ${message} WHERE id = ${messageId}::uuid`)
+      await auditEmail('failed', messageId, { error: message, willRetry: true })
+      throw err
+    }
+  })
+
+  const sendJob = fitting.use().job(SEND_JOB)
+    .input(schema.check.object({ messageId: schema.check.string() }))
+    .fit(async ({ input }: { input: { messageId: string } }) => deliver(input.messageId))
+
+  async function optOut(_db: DB, address: string, list: string): Promise<void> {
+    requireList(list)
+    await insert(emailUnsubscribes).values({ address: normalizeAddress(address), list }).onConflictDoNothing()
+  }
+
+  return {
+    async send(handle, input) {
+      const db = unscopedExecutor(handle).db
+      if (config.templates[input.template] === undefined) {
+        throw new ValidationError(
+          { template: [`no template named "${input.template}" (have: ${Object.keys(config.templates).join(', ')})`] },
+          `mail.send: unknown template "${input.template}".`,
+        )
+      }
+      if (!ADDRESS_RE.test(input.to.trim())) {
+        throw new ValidationError({ to: ['is not an email address'] }, 'mail.send: "to" is not an email address.')
+      }
+      if (input.key.trim() === '') {
+        throw new ValidationError({ key: ['must not be empty'] }, 'mail.send: "key" must not be empty.')
+      }
+      if (input.conversationId !== undefined && !UUID_RE.test(input.conversationId)) {
+        throw new ValidationError({ conversationId: ['must be a UUID'] }, 'mail.send: "conversationId" must be a UUID.')
+      }
+      if (input.list !== undefined) {
+        if (typeof input.list !== 'string' || !LIST_RE.test(input.list)) {
+          throw new ValidationError({ list: ['must be letters, digits, ".", "_" or "-", starting with a letter or digit, at most 64 characters'] }, 'mail.send: "list" is not a valid list name.')
+        }
+        if (unsubscribe === undefined) {
+          throw new Error('[pipework] mail.send with a list needs mail config unsubscribe: { url, secret }')
+        }
+      }
+      const priority = input.priority ?? config.priority
+      if (priority !== undefined && !Number.isInteger(priority)) {
+        throw new ValidationError({ priority: ['must be an integer'] }, 'mail.send: "priority" must be an integer.')
+      }
+      let conversationId = input.conversationId ?? null
+      if (input.inReplyTo !== undefined) {
+        if (!UUID_RE.test(input.inReplyTo)) {
+          throw new ValidationError({ inReplyTo: ['must be a received message id'] }, 'mail.send: "inReplyTo" must be a received message id.')
+        }
+        const parent = (await db.execute(sql`SELECT conversation_id FROM pipework_email_inbound WHERE id = ${input.inReplyTo}::uuid`))[0]
+        if (parent === undefined) {
+          throw new ValidationError({ inReplyTo: ['no received message has this id'] }, `mail.send: no received message ${input.inReplyTo}.`)
+        }
+        conversationId ??= (parent['conversation_id'] as string | null) ?? null
+      }
+      const traceId = getContext()?.trace?.id ?? null
+      const inserted = await db.execute(sql`
+        INSERT INTO pipework_email_messages (key, to_address, template, data, trace_id, conversation_id, in_reply_to_inbound, list, created_at)
+        VALUES (${input.key}, ${input.to.trim()}, ${input.template}, ${JSON.stringify(storedData(input))}::jsonb, ${traceId}::uuid,
+          ${conversationId}::uuid, ${input.inReplyTo ?? null}::uuid, ${input.list ?? null}, clock_timestamp())
+        ON CONFLICT (key) DO NOTHING
+        RETURNING id`)
+      if (inserted.length === 0) {
+        const existing = await db.execute(sql`SELECT id FROM pipework_email_messages WHERE key = ${input.key}`)
+        return { messageId: existing[0]!['id'] as string, queued: false }
+      }
+      const messageId = inserted[0]!['id'] as string
+      await config.queue.enqueue(handle, { type: SEND_JOB, payload: { messageId }, continueFlow: true, ...(priority !== undefined ? { priority } : {}) })
+      return { messageId, queued: true }
+    },
+    async sentTo(handle, address, options) {
+      const db = requireUnscopedExecutor(handle, 'mail.sentTo()', 'it reads every tenant\'s messages to the address')
+      const rows = await db.execute(sql`
+        SELECT id::text, to_address, template, status, data, list, created_at FROM pipework_email_messages
+        WHERE lower(btrim(to_address)) = ${normalizeAddress(address)}${options?.template === undefined ? sql`` : sql` AND template = ${options.template}`}
+        ORDER BY created_at, id`)
+      const out: SentMail[] = []
+      for (const row of rows) {
+        const id = row['id'] as string
+        const template = row['template'] as string
+        const stored = row['data']
+        let rendered: RenderedEmail | null = null
+        try {
+          const fn = config.templates[template]
+          if (fn !== undefined) rendered = fn(await withLateData(db, stored, id), renderMeta(id, row['to_address'] as string, (row['list'] as string | null) ?? null))
+        } catch { rendered = null }
+        let data = stored
+        if (lateReference(stored) !== null) {
+          const rest = { ...(stored as Record<string, unknown>) }
+          delete rest['__late']
+          data = rest
+        }
+        out.push({ id, template, status: row['status'] as string, data, createdAt: new Date(row['created_at'] as string | Date), rendered })
+      }
+      return out
+    },
+    unsubscribe: optOut,
+    async unsubscribed(handle, address, list) {
+      requireList(list)
+      return isUnsubscribed(requireUnscopedExecutor(handle, 'mail.unsubscribed()', 'an opt-out is not tenant data'), address, list)
+    },
+    async resubscribe(_db, address, list) {
+      requireList(list)
+      await remove(emailUnsubscribes).where(and(eq(emailUnsubscribes.address, normalizeAddress(address)), eq(emailUnsubscribes.list, list))!)
+    },
+    unsubscribeHttp() {
+      if (unsubscribe === undefined) {
+        throw new Error('[pipework] mail.unsubscribeHttp needs mail config unsubscribe: { url, secret }')
+      }
+      return unsubscribeRoutes(unsubscribe, (address, list) => optOut(pipeSystem(), address, list))
+    },
+    registerLateData(name, fn) { lateFns.set(name, fn) },
+    jobs: [sendJob as unknown as Handler<Record<string, unknown>, unknown>],
+  }
+}
+
+function requireList(list: string): void {
+  if (typeof list !== 'string' || !LIST_RE.test(list)) {
+    throw new ValidationError({ list: ['is not a valid list name'] }, 'mail: "list" is not a valid list name.')
+  }
+}
+
+function validateUnsubscribe(options: { readonly url: string; readonly secret: string }, environment: string | undefined): void {
+  let parsed: URL | null = null
+  try { parsed = new URL(options.url) } catch { /* reported below */ }
+  const allowed = environment === 'production' ? ['https:'] : ['https:', 'http:']
+  if (typeof options.url !== 'string' || parsed === null || !allowed.includes(parsed.protocol)) {
+    throw new Error(`[pipework] mail.create: unsubscribe.url must be an absolute ${environment === 'production' ? 'https' : 'https (or http outside production)'} URL, got ${JSON.stringify(options.url)}.`)
+  }
+  if (typeof options.secret !== 'string' || options.secret.length < MIN_UNSUBSCRIBE_SECRET) {
+    throw new Error(`[pipework] mail.create: unsubscribe.secret must be at least ${String(MIN_UNSUBSCRIBE_SECRET)} characters; use a long random value, the same in every process.`)
+  }
+}
+
+const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+function htmlPage(title: string, body: string): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">` +
+    `<meta name="robots" content="noindex"><title>${escapeHtml(title)}</title>` +
+    `<style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;line-height:1.5}button{font:inherit;padding:.5rem 1rem}</style>` +
+    `</head><body><h1>${escapeHtml(title)}</h1>${body}</body></html>`
+}
+
+const INVALID_PAGE = htmlPage('Link not valid', '<p>This unsubscribe link is not valid. Use the link in the most recent email.</p>')
+
+function unsubscribeRoutes(
+  options: { readonly url: string; readonly secret: string },
+  record: (address: string, list: string) => Promise<void>,
+): Handler<Record<string, unknown>, unknown>[] {
+  const path = new URL(options.url).pathname
+  const any = schema.check.unknown()
+  const tokenOf = (query: unknown): unknown => (query as Record<string, unknown> | null | undefined)?.['t']
+  const base = () => new Builder().public().request().response().query(any).params(any)
+  const answer = (response: { header(name: string, value: string): void }, status: number, html: string) => {
+    response.header('content-type', 'text/html; charset=utf-8')
+    response.header('cache-control', 'no-store')
+    response.header('referrer-policy', 'no-referrer')
+    response.header('content-security-policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'")
+    return { status, body: html }
+  }
+  const get = base().route('GET', path).fit(({ query, response }) => {
+    const named = verifyUnsubscribeToken(options.secret, tokenOf(query))
+    if (named === null) return Promise.resolve(answer(response, 400, INVALID_PAGE))
+    return Promise.resolve(answer(response, 200, htmlPage('Unsubscribe',
+      `<p>Stop receiving <strong>${escapeHtml(named.list)}</strong> email at <strong>${escapeHtml(named.address)}</strong>?</p>` +
+      `<form method="post" action="${escapeHtml(path)}?t=${escapeHtml(encodeURIComponent(String(tokenOf(query))))}">` +
+      `<input type="hidden" name="List-Unsubscribe" value="One-Click"><button type="submit">Unsubscribe</button></form>`)))
+  })
+  const post = base().ignoreBody().route('POST', path).fit(async ({ query, response }) => {
+    const named = verifyUnsubscribeToken(options.secret, tokenOf(query))
+    if (named === null) return answer(response, 400, INVALID_PAGE)
+    await record(named.address, named.list)
+    return answer(response, 200, htmlPage('Unsubscribed',
+      `<p>You will no longer receive <strong>${escapeHtml(named.list)}</strong> email at <strong>${escapeHtml(named.address)}</strong>.</p>`))
+  })
+  return [get, post] as unknown as Handler<Record<string, unknown>, unknown>[]
+}