@strav/mail 1.0.0-alpha.25

package/README.md

@@ -0,0 +1,112 @@
+# @strav/mail
+
+Outbound communication for Strav 1.0. Mail layer covers sync send + queued delivery + three production HTTP transports:
+
+- `Message` + `MailRecipient` + `MailAddress` + `MessageAttachment` — the plain-data envelope.
+- `Transport` interface — what every backend implements (`send`, optional `close`).
+- `ArrayTransport` — in-memory recorder for tests.
+- `LogTransport` — writes `mail.sent` records to a `Logger` channel; local-dev default.
+- `ResendTransport` + `SendGridTransport` + `MailgunTransport` + `AlibabaDmTransport` — production HTTP transports. Pure-fetch, no SDK deps, no `nodemailer`. Alibaba Cloud DirectMail covers China + SEA deliverability.
+- `MailTransportError` — typed `StravError` raised by transports on send failure; carries `provider` / `status` / `retryable` / `providerError` in `context`.
+- `PostmarkInboundParser` + `MailgunInboundParser` — normalize provider webhooks to `ParsedInboundMail`. Mailgun verifies HMAC-SHA256 + timestamp; Postmark relies on HTTP-level auth (Basic / IP allow-list).
+- `isAutoGeneratedMessage` — mail-loop guard. Honour it before auto-responding.
+- `MailInboundError` — raised when an inbound webhook payload is malformed.
+- `MailManager` — multi-transport orchestration with default-`from` substitution + Mailable-aware `send` overload + lazy/cached transport build.
+- `MailProvider` — wires `config.mail` into the container.
+- `Mailable<TPayload>` — typed `Job` subclass; override `build(payload)`, dispatch via `queue.dispatch(YourMailable, payload)` for async delivery with retries / dead-letter.
+
+> **Status:** 1.0.0-alpha — outbound mail layer + Resend + SendGrid + Mailgun + Alibaba DirectMail transports shipped, plus Postmark + Mailgun inbound webhook parsers. Multi-channel fan-out lives in `@strav/notification`. No SMTP transport — see `docs/mail/README.md` for the rationale.
+
+## Install
+
+```bash
+bun add @strav/mail
+```
+
+Peer: `@strav/kernel`.
+
+## Minimal example
+
+```ts
+// config/mail.ts
+import type { MailConfig } from '@strav/mail'
+
+export default {
+  default: 'array',                       // or 'log' in dev, 'smtp' once it ships
+  from: { email: 'noreply@acme.com', name: 'Acme' },
+  transports: {
+    array: { driver: 'array' },
+    log: { driver: 'log', channel: 'mail' },
+  },
+} satisfies MailConfig
+```
+
+```ts
+// in a controller or service
+@inject()
+class SignupController {
+  constructor(private readonly mail: MailManager) {}
+
+  async send(email: string): Promise<void> {
+    await this.mail.send({
+      to: email,
+      subject: 'Welcome',
+      html: '<h1>Welcome</h1>',
+      text: 'Welcome',
+    })
+  }
+}
+```
+
+## Test integration
+
+```ts
+await mail.send({ to: 'a@x', subject: 'hi', text: 'h' })
+expect((mail.via() as ArrayTransport).messages[0]?.subject).toBe('hi')
+```
+
+`ArrayTransport.messages` is a frozen view of every send since the last `clear()`.
+
+## Mailable + queue
+
+```ts
+import { Mailable, type Message } from '@strav/mail'
+
+class WelcomeEmail extends Mailable<{ name: string }> {
+  static override readonly jobName = 'mail.welcome'
+  build(payload: { name: string }): Message {
+    return { to: `${payload.name}@x`, subject: 'Welcome', text: `Hi ${payload.name}` }
+  }
+}
+
+// Register with JobRegistry (same as any other Job).
+registry.register(WelcomeEmail)
+
+// Dispatch:
+await queue.dispatch(WelcomeEmail, { name: 'Alice' })  // async, retried
+await mail.send(WelcomeEmail, { name: 'Alice' })       // sync, inline
+```
+
+Mailables participate in the full `@strav/queue` lifecycle (retries, backoff, `strav_failed_jobs` dead-letter).
+
+## Inbound webhooks
+
+```ts
+import { MailgunInboundParser, PostmarkInboundParser } from '@strav/mail'
+
+const postmark = new PostmarkInboundParser()
+const mailgun = new MailgunInboundParser({ webhookSigningKey: env.MAILGUN_SIGNING_KEY })
+
+// In your HTTP handler — pass the raw body + lowercased headers:
+const mail = await mailgun.parse({ body: rawBody, headers: req.headers })
+if (mail.isAutoGenerated) return        // mail-loop guard — must honor.
+await onIncoming(mail)
+```
+
+The parsed shape (`ParsedInboundMail`) is identical across providers: `from`/`to`/`cc`/`bcc`, `subject`/`text`/`html`, RFC-5322 `messageId` / `inReplyTo` / `references`, decoded `attachments` as `Buffer`, and `isAutoGenerated` derived from `Auto-Submitted` / `Precedence` / `X-Auto-Response-Suppress`.
+
+## What's NOT here yet
+- Notifications + channel drivers (in `@strav/notification`).
+- Broadcast pub/sub + SSE handler.
+
+Full reference: [`docs/mail/api.md`](../../docs/mail/api.md).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@strav/mail",
+  "version": "1.0.0-alpha.25",
+  "description": "Strav signal layer — mail (core + array/log transports + Mailable + queue-dispatch); notifications + SSE + broadcast follow in later slices",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.25",
+    "@strav/queue": "1.0.0-alpha.25"
+  },
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
+  },
+  "devDependencies": null
+}

package/src/inbound/loop_guard.ts

@@ -0,0 +1,18 @@
+/**
+ * Detect auto-generated messages the application must not auto-respond to.
+ *
+ * Without this check, an auto-reply to an auto-reply creates an infinite mail
+ * loop. RFC 3834 (Auto-Submitted) and common practice (Precedence,
+ * X-Auto-Response-Suppress) are the universally-honored signals.
+ */
+export function isAutoGeneratedMessage(headers: Record<string, string>): boolean {
+  const autoSubmitted = headers['auto-submitted']?.toLowerCase().trim()
+  if (autoSubmitted && autoSubmitted !== 'no') return true
+
+  const precedence = headers['precedence']?.toLowerCase().trim()
+  if (precedence === 'bulk' || precedence === 'junk' || precedence === 'list') return true
+
+  if (headers['x-auto-response-suppress']) return true
+
+  return false
+}

package/src/inbound/mailgun_parser.ts

@@ -0,0 +1,218 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { AuthError, ConfigError } from '@strav/kernel'
+import { MailInboundError } from '../inbound_error.ts'
+import { isAutoGeneratedMessage } from './loop_guard.ts'
+import type {
+  InboundWebhookInput,
+  InboundWebhookParser,
+  MailgunInboundConfig,
+  ParsedInboundAddress,
+  ParsedInboundAttachment,
+  ParsedInboundMail,
+} from './types.ts'
+
+type DecodedForm = Awaited<ReturnType<Response['formData']>>
+
+/**
+ * Parse a Mailgun Routes inbound webhook payload.
+ *
+ * Mailgun POSTs `multipart/form-data` to the route URL. Authentication uses
+ * HMAC-SHA256 over `(timestamp + token)` with the dashboard's webhook signing
+ * key. Signature verification is mandatory here — call it through an HTTP
+ * route that passes the raw body and `content-type` header unchanged.
+ *
+ * Throws `AuthError` on signature mismatch or stale timestamp,
+ * `MailInboundError` on malformed payloads,
+ * `ConfigError` when constructed without a signing key.
+ *
+ * @see https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/
+ */
+export class MailgunInboundParser implements InboundWebhookParser {
+  private readonly signingKey: string
+  private readonly maxAgeSeconds: number
+
+  constructor(config: MailgunInboundConfig) {
+    if (!config.webhookSigningKey) {
+      throw new ConfigError('MailgunInboundParser requires webhookSigningKey')
+    }
+    this.signingKey = config.webhookSigningKey
+    this.maxAgeSeconds = config.maxAgeSeconds ?? 300
+  }
+
+  async parse(input: InboundWebhookInput): Promise<ParsedInboundMail> {
+    const contentType = input.headers['content-type'] ?? ''
+    if (!contentType.toLowerCase().includes('multipart/')) {
+      throw new MailInboundError(
+        `Mailgun inbound webhook: expected multipart/form-data, got: ${contentType || '(none)'}`,
+        { context: { provider: 'mailgun', contentType } },
+      )
+    }
+
+    const form = await this.decodeMultipart(input.body, contentType)
+
+    const signature = getField(form, 'signature')
+    const token = getField(form, 'token')
+    const timestamp = getField(form, 'timestamp')
+    if (!signature || !token || !timestamp) {
+      throw new AuthError('Mailgun webhook missing signature/token/timestamp')
+    }
+    this.verifyTimestamp(timestamp)
+    this.verifySignature(timestamp, token, signature)
+
+    const headers = parseMessageHeaders(getField(form, 'message-headers'))
+
+    const from = parseAddress(getField(form, 'from')) ?? {
+      address: getField(form, 'sender') ?? '',
+    }
+    const to = parseAddressList(getField(form, 'recipient'))
+    const cc = parseAddressList(headers['cc'])
+    const replyTo = parseAddress(headers['reply-to'])
+
+    return {
+      from,
+      to,
+      cc,
+      bcc: [],
+      replyTo,
+      subject: getField(form, 'subject') ?? '',
+      text: getField(form, 'body-plain') || undefined,
+      html: getField(form, 'body-html') || undefined,
+      date: headers['date'] ? new Date(headers['date']) : undefined,
+      headers,
+      attachments: await extractAttachments(form),
+      messageId: stripAngles(headers['message-id']),
+      inReplyTo: stripAngles(headers['in-reply-to']),
+      references: parseReferences(headers['references']),
+      isAutoGenerated: isAutoGeneratedMessage(headers),
+    }
+  }
+
+  private async decodeMultipart(body: string | Buffer, contentType: string): Promise<DecodedForm> {
+    try {
+      const payload =
+        typeof body === 'string'
+          ? body
+          : new Uint8Array(body.buffer, body.byteOffset, body.byteLength)
+      const response = new Response(payload, { headers: { 'content-type': contentType } })
+      return await response.formData()
+    } catch (err) {
+      throw new MailInboundError(
+        `Mailgun inbound webhook: invalid multipart payload — ${(err as Error).message}`,
+        { context: { provider: 'mailgun' }, cause: err },
+      )
+    }
+  }
+
+  private verifySignature(timestamp: string, token: string, signature: string): void {
+    const expected = createHmac('sha256', this.signingKey)
+      .update(timestamp + token)
+      .digest('hex')
+
+    // Constant-time compare — requires equal length, else timingSafeEqual throws.
+    if (expected.length !== signature.length) {
+      throw new AuthError('Mailgun webhook signature mismatch')
+    }
+    const ok = timingSafeEqual(
+      new Uint8Array(Buffer.from(expected, 'utf-8')),
+      new Uint8Array(Buffer.from(signature, 'utf-8')),
+    )
+    if (!ok) throw new AuthError('Mailgun webhook signature mismatch')
+  }
+
+  private verifyTimestamp(timestamp: string): void {
+    const ts = Number(timestamp)
+    if (!Number.isFinite(ts)) {
+      throw new AuthError('Mailgun webhook: invalid timestamp')
+    }
+    const nowSec = Math.floor(Date.now() / 1000)
+    if (Math.abs(nowSec - ts) > this.maxAgeSeconds) {
+      throw new AuthError('Mailgun webhook: timestamp outside allowed window')
+    }
+  }
+}
+
+function getField(form: DecodedForm, name: string): string | undefined {
+  const value = form.get(name)
+  if (value === null || value === undefined) return undefined
+  return typeof value === 'string' ? value : undefined
+}
+
+function parseMessageHeaders(raw: string | undefined): Record<string, string> {
+  if (!raw) return {}
+  try {
+    const pairs = JSON.parse(raw) as unknown
+    if (!Array.isArray(pairs)) return {}
+    const out: Record<string, string> = {}
+    for (const entry of pairs) {
+      if (!Array.isArray(entry) || entry.length < 2) continue
+      const [name, value] = entry
+      if (typeof name === 'string' && typeof value === 'string') {
+        out[name.toLowerCase()] = value
+      }
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+async function extractAttachments(form: DecodedForm): Promise<ParsedInboundAttachment[]> {
+  const count = Number(form.get('attachment-count') ?? 0)
+  if (!Number.isFinite(count) || count <= 0) return []
+
+  const result: ParsedInboundAttachment[] = []
+  for (let i = 1; i <= count; i++) {
+    const file = form.get(`attachment-${i}`)
+    if (!file || typeof file === 'string') continue
+    const content = Buffer.from(await file.arrayBuffer())
+    result.push({
+      filename: file.name || `attachment-${i}`,
+      contentType: file.type || 'application/octet-stream',
+      content,
+      size: content.length,
+    })
+  }
+  return result
+}
+
+function parseAddress(raw: string | undefined): ParsedInboundAddress | undefined {
+  if (!raw) return undefined
+  const trimmed = raw.trim()
+  if (!trimmed) return undefined
+
+  const match = trimmed.match(/^\s*(?:"?([^"<]*?)"?\s*)?<([^<>\s]+@[^<>\s]+)>\s*$/)
+  if (match) {
+    const name = match[1]?.trim()
+    const address = match[2]!
+    return name ? { address, name } : { address }
+  }
+  if (/^[^<>\s]+@[^<>\s]+$/.test(trimmed)) return { address: trimmed }
+  return undefined
+}
+
+function parseAddressList(raw: string | undefined): ParsedInboundAddress[] {
+  if (!raw) return []
+  // Mailgun delivers To / recipient as a comma-separated list.
+  return raw
+    .split(',')
+    .map((part) => parseAddress(part))
+    .filter((v): v is ParsedInboundAddress => v !== undefined)
+}
+
+function parseReferences(value: string | undefined): string[] {
+  if (!value) return []
+  return value
+    .split(/\s+/)
+    .map((r) => stripAngles(r))
+    .filter((v): v is string => Boolean(v))
+}
+
+function stripAngles(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  if (trimmed.startsWith('<') && trimmed.endsWith('>')) {
+    const inner = trimmed.slice(1, -1).trim()
+    return inner || undefined
+  }
+  return trimmed || undefined
+}

package/src/inbound/postmark_parser.ts

@@ -0,0 +1,159 @@
+import { MailInboundError } from '../inbound_error.ts'
+import { isAutoGeneratedMessage } from './loop_guard.ts'
+import type {
+  InboundWebhookInput,
+  InboundWebhookParser,
+  ParsedInboundAddress,
+  ParsedInboundAttachment,
+  ParsedInboundMail,
+} from './types.ts'
+
+/**
+ * Parse a Postmark Inbound webhook payload into `ParsedInboundMail`.
+ *
+ * Postmark does NOT sign inbound webhooks with HMAC. Authenticate the request
+ * at the HTTP layer — Basic Auth on the webhook URL and/or IP allow-listing —
+ * before handing the body to this parser.
+ *
+ * @see https://postmarkapp.com/developer/user-guide/inbound/parse-an-email
+ */
+export class PostmarkInboundParser implements InboundWebhookParser {
+  async parse(input: InboundWebhookInput): Promise<ParsedInboundMail> {
+    const payload = this.decode(input.body)
+    const headers = this.extractHeaders(payload.Headers ?? [])
+
+    const from = this.mapAddress(payload.FromFull) ?? {
+      address: payload.From ?? '',
+      ...(payload.FromName ? { name: payload.FromName } : {}),
+    }
+
+    const to = mapList(payload.ToFull, (a) => this.mapAddress(a))
+    const cc = mapList(payload.CcFull, (a) => this.mapAddress(a))
+    const bcc = mapList(payload.BccFull, (a) => this.mapAddress(a))
+    const replyTo = payload.ReplyTo ? { address: payload.ReplyTo } : undefined
+
+    return {
+      from,
+      to,
+      cc,
+      bcc,
+      replyTo,
+      subject: payload.Subject ?? '',
+      text: payload.TextBody || undefined,
+      html: payload.HtmlBody || undefined,
+      date: payload.Date ? new Date(payload.Date) : undefined,
+      headers,
+      attachments: this.mapAttachments(payload.Attachments ?? []),
+      messageId: stripAngles(headers['message-id']),
+      inReplyTo: stripAngles(headers['in-reply-to']),
+      references: parseReferences(headers['references']),
+      isAutoGenerated: isAutoGeneratedMessage(headers),
+      providerMessageId: payload.MessageID,
+    }
+  }
+
+  private decode(body: string | Buffer): PostmarkInboundPayload {
+    try {
+      const text = typeof body === 'string' ? body : body.toString('utf-8')
+      return JSON.parse(text) as PostmarkInboundPayload
+    } catch (err) {
+      throw new MailInboundError(
+        `Postmark inbound webhook: invalid JSON payload — ${(err as Error).message}`,
+        { context: { provider: 'postmark' }, cause: err },
+      )
+    }
+  }
+
+  private mapAddress(addr?: PostmarkAddress): ParsedInboundAddress | undefined {
+    if (!addr?.Email) return undefined
+    return addr.Name ? { address: addr.Email, name: addr.Name } : { address: addr.Email }
+  }
+
+  private extractHeaders(headers: PostmarkHeader[]): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const h of headers) {
+      if (h.Name) result[h.Name.toLowerCase()] = h.Value
+    }
+    return result
+  }
+
+  private mapAttachments(atts: PostmarkAttachment[]): ParsedInboundAttachment[] {
+    return atts.map((a) => {
+      const cid = a.ContentID ? stripAngles(a.ContentID) : undefined
+      return {
+        filename: a.Name,
+        contentType: a.ContentType,
+        content: Buffer.from(a.Content, 'base64'),
+        size: a.ContentLength,
+        ...(cid ? { cid } : {}),
+      }
+    })
+  }
+}
+
+interface PostmarkAddress {
+  Email: string
+  Name?: string
+  MailboxHash?: string
+}
+
+interface PostmarkHeader {
+  Name: string
+  Value: string
+}
+
+interface PostmarkAttachment {
+  Name: string
+  ContentType: string
+  Content: string
+  ContentLength: number
+  ContentID?: string | null
+}
+
+interface PostmarkInboundPayload {
+  From?: string
+  FromName?: string
+  FromFull?: PostmarkAddress
+  To?: string
+  ToFull?: PostmarkAddress[]
+  Cc?: string
+  CcFull?: PostmarkAddress[]
+  Bcc?: string
+  BccFull?: PostmarkAddress[]
+  ReplyTo?: string
+  Subject?: string
+  MessageID?: string
+  Date?: string
+  TextBody?: string
+  HtmlBody?: string
+  Headers?: PostmarkHeader[]
+  Attachments?: PostmarkAttachment[]
+}
+
+function mapList<T, R>(list: T[] | undefined, fn: (item: T) => R | undefined): NonNullable<R>[] {
+  if (!list) return []
+  const out: NonNullable<R>[] = []
+  for (const item of list) {
+    const mapped = fn(item)
+    if (mapped !== undefined && mapped !== null) out.push(mapped as NonNullable<R>)
+  }
+  return out
+}
+
+function stripAngles(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  if (trimmed.startsWith('<') && trimmed.endsWith('>')) {
+    const inner = trimmed.slice(1, -1).trim()
+    return inner || undefined
+  }
+  return trimmed || undefined
+}
+
+function parseReferences(value: string | undefined): string[] {
+  if (!value) return []
+  return value
+    .split(/\s+/)
+    .map((ref) => stripAngles(ref))
+    .filter((v): v is string => Boolean(v))
+}

package/src/inbound/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Inbound mail types.
+ *
+ * Provider webhooks (Postmark / Mailgun) — and any future driver — all
+ * normalize to `ParsedInboundMail` so application code can consume inbound
+ * mail from any source uniformly.
+ */
+
+export interface ParsedInboundAddress {
+  address: string
+  name?: string
+}
+
+export interface ParsedInboundAttachment {
+  filename: string
+  contentType: string
+  content: Buffer
+  size: number
+  /** Content-ID for inline images, angle brackets stripped. */
+  cid?: string
+}
+
+export interface ParsedInboundMail {
+  from: ParsedInboundAddress
+  to: ParsedInboundAddress[]
+  cc: ParsedInboundAddress[]
+  bcc: ParsedInboundAddress[]
+  replyTo?: ParsedInboundAddress
+  subject: string
+  text?: string
+  html?: string
+  date?: Date
+  /**
+   * Lowercased header name → value. Duplicate headers keep the last value;
+   * widen to `string | string[]` if a future driver needs to preserve duplicates.
+   */
+  headers: Record<string, string>
+  attachments: ParsedInboundAttachment[]
+  /** RFC 5322 Message-ID of the inbound message, angle brackets stripped. */
+  messageId?: string
+  /** In-Reply-To header value, angle brackets stripped. */
+  inReplyTo?: string
+  /** References header parsed into a list, angle brackets stripped. */
+  references: string[]
+  /**
+   * True if the message looks auto-generated (auto-reply, vacation, bulk, list).
+   * Applications must not auto-respond when this is true — skipping this check
+   * causes mail loops.
+   */
+  isAutoGenerated: boolean
+  /** Provider's own message identifier (e.g. Postmark MessageID), if any. */
+  providerMessageId?: string
+}
+
+export interface InboundWebhookInput {
+  /**
+   * Raw request body. `Buffer` preferred so signature checks see the exact
+   * bytes the provider signed.
+   */
+  body: string | Buffer
+  /** Request headers. Keys must be lowercased by the caller. */
+  headers: Record<string, string | undefined>
+}
+
+export interface InboundWebhookParser {
+  parse(input: InboundWebhookInput): Promise<ParsedInboundMail>
+}
+
+// -- Mailgun Routes webhook ---------------------------------------------------
+
+export interface MailgunInboundConfig {
+  /**
+   * Mailgun "HTTP webhook signing key" from the dashboard — distinct from the
+   * sending API key. Rotating it in the dashboard requires rotating here too.
+   */
+  webhookSigningKey: string
+  /**
+   * Reject signatures whose timestamp is older than N seconds. Default 300
+   * (5 minutes). Tightens replay protection; widen only if clock skew is an issue.
+   */
+  maxAgeSeconds?: number
+}

package/src/inbound_error.ts

@@ -0,0 +1,22 @@
+/**
+ * `MailInboundError` — typed error raised by inbound webhook parsers when
+ * the payload itself is malformed (bad JSON, wrong content-type, missing
+ * required fields).
+ *
+ * For signature / signing-key failures, parsers throw `AuthError` from
+ * `@strav/kernel`. For misconfiguration at construction time, they throw
+ * `ConfigError`.
+ *
+ * Carry the upstream provider's HTTP status (the one the parser would
+ * return to the provider's webhook delivery system) under `context.status`.
+ * The error's own `status` is fixed at 400 — the inbound webhook delivered
+ * something we could not parse.
+ */
+
+import { StravError, type StravErrorOptions } from '@strav/kernel'
+
+export class MailInboundError extends StravError {
+  constructor(message: string, options: StravErrorOptions = {}) {
+    super(message, { code: 'mail-inbound-error', status: 400 }, options)
+  }
+}