@novacraft-engineering/mailbox 0.4.5 → 0.4.17

package/lib/receive.test.ts

@@ -1,13 +1,25 @@
 import assert from 'node:assert/strict'
+
+process.env.MAIL_ADDRESS_DOMAIN = 'metroperilinsbrokers.com'
+process.env.MAIL_ADDRESS_DOMAINS = 'metroperilinsbrokers.com'
+
 import test from 'node:test'
 
-process.env.MAIL_ADDRESS_DOMAIN = 'contact.example.com'
-process.env.MAIL_ADDRESS_DOMAINS = 'example.com,contact.example.com'
+test('only mail addressed to a hosted domain is ingested', async () => {
+  const { addressedToUs } = await import('./receive.ts')
+
+  assert.equal(addressedToUs(['info@metroperilinsbrokers.com']), true)
+  assert.equal(addressedToUs(['O. Komolafe <okomolafe@metroperilinsbrokers.com>']), true, 'a display name does not hide the domain')
+  assert.equal(addressedToUs(['someone@example.com', 'info@metroperilinsbrokers.com']), true, 'one of ours is enough')
+
+  // The leak: one provider account held several tenants' domains and posted all of their
+  // mail to this one webhook, which filed it to the shared inbox because no local account
+  // matched. 360 of another tenant's messages became readable here.
+  assert.equal(addressedToUs(['hello@contact.novacraft.africa']), false)
+  assert.equal(addressedToUs(['admin@jakstoc.com', 'info@podzyme.com']), false)
+  assert.equal(addressedToUs([]), false, 'no recipient is not our recipient')
+  // A domain that merely ends with ours is a different domain.
+  assert.equal(addressedToUs(['x@evil-metroperilinsbrokers.com']), false)
+  assert.equal(addressedToUs(['x@metroperilinsbrokers.com.evil.net']), false)
 
-test('every domain we receive on is refused as a forward target, not just the primary one', async () => {
-  const { ADDRESS_DOMAINS } = await import('./brand.ts')
-  const loops = (address: string) => ADDRESS_DOMAINS.includes(address.split('@')[1] ?? '')
-  assert.equal(loops('hosting@example.com'), true, 'a secondary domain we receive on would loop')
-  assert.equal(loops('hello@contact.example.com'), true, 'the primary domain would loop')
-  assert.equal(loops('someone@gmail.com'), false, 'an outside address is a real destination')
 })

package/lib/receive.ts

@@ -2,9 +2,20 @@ import { BRAND, ADDRESS_DOMAINS } from '@/lib/brand'
 import { sendPush } from '@/lib/push'
 import { stripOwnPixel } from '@/lib/email-html'
 import { FORWARD_RECIPIENTS, MAIL_DOMAIN } from '@/lib/dev-auth'
-import { ADDRESS_ALIASES, appendInbound, getAccountByAddress, inboundExists, recordContact, recordSentMeta } from '@/lib/mailbox'
+import { ADDRESS_ALIASES, appendInbound, judgeMessage, noteSender, senderStanding, senderDomainOf, getAccountByAddress, inboundExists, recordContact, recordSentMeta, repairInbound } from '@/lib/mailbox'
 import { sendMail } from '@/lib/mail-provider'
 
+/**
+ * Where the receiving API lives. The Resend SDK reads RESEND_BASE_URL for sending, so a
+ * deployment pointed at another Resend-compatible host sends there — these calls are hand
+ * rolled and have to honour the same variable, or receiving silently talks to a host that
+ * has never seen the message and every body arrives empty.
+ */
+function receivingBase(): string {
+  const configured = (process.env.RESEND_BASE_URL ?? '').trim().replace(/\/+$/, '')
+  return configured || 'https://api.resend.com'
+}
+
 // The address we send from, and the inbox that owns mail addressed to nobody specific.
 const MAIL_FROM = (process.env.MAIL_FROM ?? process.env.RESEND_FROM ?? BRAND.supportEmail).replace(/^.*<|>$/g, '').trim()
 const SHARED_ADDRESS = MAIL_FROM.toLowerCase()
@@ -24,6 +35,22 @@ export async function attributeOwner(recipients: string[]): Promise<string> {
   return SHARED_ADDRESS
 }
 
+/**
+ * Whether any recipient is on a domain this deployment hosts. One provider account can
+ * hold several tenants' domains and posts every message it receives to the one webhook it
+ * is configured with, so a deployment is offered other tenants' mail as a matter of course
+ * — and a signature check proves only that the provider sent it, not that it is ours.
+ */
+export function addressedToUs(recipients: string[]): boolean {
+  const hosted = new Set([...ADDRESS_DOMAINS, MAIL_DOMAIN].map(domain => domain.trim().toLowerCase()).filter(Boolean))
+  return recipients.some(raw => {
+    const match = raw?.match(/<([^>]+)>/)
+    const address = (match ? match[1] : raw ?? '').trim().toLowerCase()
+    const domain = address.split('@')[1] ?? ''
+    return domain !== '' && hosted.has(domain)
+  })
+}
+
 export function parseSender(raw: string): { email: string; name: string | null } {
   const match = raw.match(/^\s*(.*?)\s*<([^>]+)>\s*$/)
   if (match) return { name: match[1].replace(/^"|"$/g, '') || null, email: match[2].trim() }
@@ -57,7 +84,7 @@ export type ReceivedEmail = {
 // lives on Resend and must be pulled from the receiving endpoint, or the inbox stores blanks.
 export async function fetchReceivedEmail(emailId: string, apiKey: string): Promise<ReceivedEmail | null> {
   try {
-    const response = await fetch(`https://api.resend.com/emails/receiving/${encodeURIComponent(emailId)}`, {
+    const response = await fetch(`${receivingBase()}/emails/receiving/${encodeURIComponent(emailId)}`, {
       headers: { Authorization: `Bearer ${apiKey}` },
     })
     if (!response.ok) return null
@@ -118,7 +145,7 @@ async function rehostAttachments(
 
 async function fetchAttachmentBytes(emailId: string, apiKey: string): Promise<SendAttachment[]> {
   try {
-    const response = await fetch(`https://api.resend.com/emails/receiving/${encodeURIComponent(emailId)}/attachments`, {
+    const response = await fetch(`${receivingBase()}/emails/receiving/${encodeURIComponent(emailId)}/attachments`, {
       headers: { Authorization: `Bearer ${apiKey}` },
     })
     if (!response.ok) return []
@@ -135,8 +162,13 @@ async function fetchAttachmentBytes(emailId: string, apiKey: string): Promise<Se
         size: Number(entry.size ?? 0) || undefined,
       }
       try {
-        const binary = url ? await fetch(url) : null
-        if (binary?.ok) file.content = Buffer.from(await binary.arrayBuffer()).toString('base64')
+        // Inline base64 when the host sends the bytes with the listing; a download_url is
+        // fetched only when it doesn't.
+        if (entry.content) file.content = String(entry.content)
+        else {
+          const binary = url ? await fetch(url) : null
+          if (binary?.ok) file.content = Buffer.from(await binary.arrayBuffer()).toString('base64')
+        }
       } catch (err) {
         console.warn(`[mail] attachment pull failed for ${emailId}/${file.filename}:`, err)
       }
@@ -180,6 +212,8 @@ export async function forwardToAccounts(
       to: [recipient],
       replyTo: inbound.from || undefined,
       subject: inbound.subject.startsWith('Fwd:') ? inbound.subject : `Fwd: ${inbound.subject}`,
+      // The archive already holds the message this forwards; a second copy is noise.
+      skipArchive: true,
       text: inbound.text?.trim() || snippet(inbound.html, inbound.text) || ' ',
       ...(inbound.html ? { html: `${header}${stripOwnPixel(inbound.html)}` } : {}),
       ...(attachments.length ? { attachments } : {}),
@@ -199,14 +233,65 @@ export async function forwardToAccounts(
 export async function ingestReceived(
   emailId: string,
   data: Record<string, unknown> = {},
+  /**
+   * Repairing a message already in the mailbox: fill in the body and attachments it was
+   * stored without, and stop there. The owner was notified and the copy forwarded when it
+   * first arrived, so doing either again would be a second delivery of old mail.
+   */
+  mode: 'store' | 'repair' = 'store',
 ): Promise<{ owner: string; subject: string; from: string }> {
   const apiKey = process.env.RESEND_API_KEY
   // The webhook payload has no body — pull the full email (html/text/attachments) from Resend.
   const full = apiKey ? await fetchReceivedEmail(emailId, apiKey) : null
 
   const payloadAttachments = Array.isArray(data.attachments) ? (data.attachments as Array<Record<string, unknown>>) : []
+  // The sender's own domain answers these, and the provider scans for spam and viruses
+  // before we ever see the message. Where the webhook does not carry a verdict, the
+  // Authentication-Results header the receiving server wrote does.
+  const authHeader = String(
+    (full?.headers as Record<string, unknown> | undefined)?.['authentication-results'] ?? '',
+  ).toLowerCase()
+  const fromHeader = (mech: string): string | null => authHeader.match(new RegExp(`${mech}=(\\w+)`))?.[1] ?? null
+
+  // Who this is for has to be settled before the message can be judged: standing is what
+  // this mailbox has done with this sender, and a different mailbox may have done the
+  // opposite. Resolved once here and reused below.
+  const recipients = [
+    ...(Array.isArray(full?.to) ? full!.to : []),
+    ...(Array.isArray(data.to) ? (data.to as string[]) : [String(data.to ?? '')]),
+    ...(Array.isArray(full?.cc) ? full!.cc : []),
+    ...(Array.isArray(data.cc) ? (data.cc as string[]) : []),
+    ...(Array.isArray(full?.bcc) ? full!.bcc : []),
+    ...(Array.isArray(data.bcc) ? (data.bcc as string[]) : []),
+  ].filter(Boolean)
+  const owner = await attributeOwner(recipients)
+  const fromAddress = full?.from || String(data.from ?? '')
+  const senderDomain = senderDomainOf(fromAddress)
+  const standing = await senderStanding(owner, senderDomain)
+
+  const verdicts = judgeMessage({
+    spam: data.spam == null ? null : String(data.spam),
+    virus: data.virus == null ? null : String(data.virus),
+    // Where no provider hands us a verdict — a deployment reading its mail through Resend,
+    // say — the receiving server's own Authentication-Results header carries the same answer.
+    spf: data.spf == null ? fromHeader('spf') : String(data.spf),
+    dkim: data.dkim == null ? fromHeader('dkim') : String(data.dkim),
+    dmarc: data.dmarc == null ? fromHeader('dmarc') : String(data.dmarc),
+    from: full?.from || String(data.from ?? ''),
+    replyTo: full?.replyTo ?? (Array.isArray(data.reply_to) ? (data.reply_to as string[]) : []),
+    subject: full?.subject || String(data.subject ?? ''),
+    text: full?.text ?? (data.text ? String(data.text) : null),
+  }, standing)
+  if (verdicts.risk !== 'clean') {
+    console.warn(`[mail] ${verdicts.risk} inbound ${emailId}:`, verdicts.reasons.join('; '))
+  }
+
   const inbound = {
     id: emailId,
+    risk: verdicts.risk,
+    riskReasons: verdicts.reasons,
+    // Held out of the inbox, not merely labelled, once the weight passes the threshold.
+    spam: verdicts.quarantine,
     from: full?.from || String(data.from ?? ''),
     to: full?.to ?? (Array.isArray(data.to) ? (data.to as string[]) : [String(data.to ?? '')]),
     cc: full?.cc ?? (Array.isArray(data.cc) ? (data.cc as string[]) : []),
@@ -229,19 +314,31 @@ export async function ingestReceived(
     // Attribute (and therefore forward) to the accessor actually addressed — to, cc, OR bcc.
     // Anything not matching a member's personal address stays in the shared (admin) inbox,
     // so a member never receives mail they aren't a party to.
-    owner: await attributeOwner([
-      ...(Array.isArray(full?.to) ? full!.to : []),
-      ...(Array.isArray(data.to) ? (data.to as string[]) : [String(data.to ?? '')]),
-      ...(full?.cc ?? []),
-      ...(full?.bcc ?? []),
-    ]),
+    owner,
   }
+  // Refuse mail that was never addressed to this mailbox, before a copy is stored, pushed
+  // or forwarded. Without this, every message the provider account receives for any tenant
+  // lands in whichever deployment holds the webhook, filed to its shared inbox because no
+  // local account matches — one tenant reading another's mail.
+  const envelope = [...inbound.to, ...inbound.cc, ...inbound.bcc]
+  if (!addressedToUs(envelope)) {
+    throw new Error(`refusing ${emailId}: addressed to ${envelope.join(', ') || 'nobody'}, which is not a domain this mailbox hosts`)
+  }
+
   // Pull the bytes once: they become our stored copy and the forward's attachments.
   const files = apiKey ? await fetchAttachmentBytes(emailId, apiKey) : []
   if (files.length) inbound.attachments = await rehostAttachments(emailId, files)
   const forwardable = files.filter(file => file.content)
 
+  if (mode === 'repair') {
+    if (!full) throw new Error('provider returned no body; nothing to repair with')
+    const filled = await repairInbound(inbound)
+    if (!filled) throw new Error('no such message in this mailbox')
+    return { owner: inbound.owner, subject: inbound.subject, from: inbound.from }
+  }
+
   await appendInbound(inbound)
+  await noteSender(owner, senderDomain, 'received').catch(() => {})
   const sender = parseSender(inbound.from)
   await recordContact(sender.email, sender.name)
   await sendPush(inbound.owner, {
@@ -283,7 +380,7 @@ export async function listReceived(apiKey: string, since: Date): Promise<Receive
   for (let page = 0; page < 200; page += 1) {
     const params = new URLSearchParams({ limit: '50' })
     if (after) params.set('after', after)
-    const response = await fetch(`https://api.resend.com/emails/receiving?${params}`, {
+    const response = await fetch(`${receivingBase()}/emails/receiving?${params}`, {
       headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
     })
     if (!response.ok) throw new Error(`provider list failed (${response.status})`)

package/lib/scheduled.ts

@@ -0,0 +1,168 @@
+import { randomUUID } from 'node:crypto'
+import { db, ensureMailSchema, recordContact, recordPixel, recordSentMeta, recordSentMessage } from '@/lib/mailbox'
+import { sendMail, type SendPayload } from '@/lib/mail-provider'
+
+/**
+ * A message written now and carried later. Everything the send needs is prepared before it
+ * is parked, so dispatch is only ever "hand this to the provider" — the tracking pixel, the
+ * threading headers and the recipient list cannot drift between writing and sending.
+ */
+export type ScheduledSend = {
+  payload: SendPayload
+  owner: string
+  pixelId: string | null
+  subject: string
+  from: string
+  recipients: string[]
+  cc: string[]
+  bcc: string[]
+  replyTo: string[]
+  inReplyTo: string | null
+  storedAttachments: Array<{ filename: string; key: string }>
+}
+
+export type ScheduledRow = {
+  id: string
+  owner: string
+  sendAfter: string
+  status: string
+  subject: string
+  to: string[]
+  createdAt: string
+  lastError: string | null
+}
+
+const parse = (value: unknown): ScheduledSend | null => {
+  try {
+    return JSON.parse(String(value)) as ScheduledSend
+  } catch {
+    return null
+  }
+}
+
+export async function scheduleSend(owner: string, sendAfter: string, send: ScheduledSend): Promise<string> {
+  await ensureMailSchema()
+  const id = randomUUID()
+  await db()`
+    INSERT INTO mail_scheduled (id, owner, send_after, status, payload, created_at)
+    VALUES (${id}, ${owner.toLowerCase()}, ${sendAfter}, 'pending', ${JSON.stringify(send)}, ${new Date().toISOString()})`
+  return id
+}
+
+export async function listScheduled(owner: string | null): Promise<ScheduledRow[]> {
+  await ensureMailSchema()
+  const sql = db()
+  const rows = owner
+    ? await sql`SELECT * FROM mail_scheduled WHERE status = 'pending' AND lower(owner) = ${owner.toLowerCase()} ORDER BY send_after`
+    : await sql`SELECT * FROM mail_scheduled WHERE status = 'pending' ORDER BY send_after`
+  return rows.map(row => {
+    const send = parse(row.payload)
+    return {
+      id: String(row.id),
+      owner: String(row.owner),
+      sendAfter: String(row.send_after),
+      status: String(row.status),
+      subject: send?.subject ?? '(no subject)',
+      to: send?.recipients ?? [],
+      createdAt: String(row.created_at),
+      lastError: row.last_error == null ? null : String(row.last_error),
+    }
+  })
+}
+
+/** Cancelling is only ever the owner's to do, and only while it is still waiting. */
+export async function cancelScheduled(id: string, owner: string): Promise<boolean> {
+  await ensureMailSchema()
+  const rows = await db()`
+    UPDATE mail_scheduled SET status = 'cancelled'
+    WHERE id = ${id} AND lower(owner) = ${owner.toLowerCase()} AND status = 'pending'
+    RETURNING id`
+  return rows.length > 0
+}
+
+/** The bookkeeping an immediate send does, so a delayed one lands in the same places. */
+export async function recordSend(send: ScheduledSend, id: string | null): Promise<void> {
+  await Promise.all([
+    ...[...send.recipients, ...send.cc, ...send.bcc].map(address => recordContact(address, null).catch(() => {})),
+    send.pixelId && id
+      ? recordPixel(send.pixelId, id, send.recipients[0] ?? '', send.subject).catch(() => {})
+      : Promise.resolve(),
+    id ? recordSentMeta(id, send.owner, false, send.inReplyTo).catch(() => {}) : Promise.resolve(),
+    id
+      ? recordSentMessage({
+          id,
+          from: send.from,
+          to: send.recipients,
+          cc: send.cc,
+          bcc: send.bcc,
+          replyTo: send.replyTo,
+          subject: send.subject,
+          html: send.payload.html ?? null,
+          text: send.payload.text ?? null,
+          createdAt: new Date().toISOString(),
+          attachments: send.storedAttachments,
+        }).catch(() => {})
+      : Promise.resolve(),
+  ])
+}
+
+/** Moving the time is only the owner's to do, and only while it is still waiting. */
+export async function rescheduleSend(id: string, owner: string, sendAfter: string): Promise<boolean> {
+  await ensureMailSchema()
+  const rows = await db()`
+    UPDATE mail_scheduled SET send_after = ${sendAfter}
+    WHERE id = ${id} AND lower(owner) = ${owner.toLowerCase()} AND status = 'pending'
+    RETURNING id`
+  return rows.length > 0
+}
+
+const MAX_ATTEMPTS = 5
+
+/**
+ * Hands over every message whose time has come. Each row is claimed with a conditional
+ * update before it is sent, so two runners overlapping cannot send the same mail twice.
+ */
+export async function dispatchDue(limit = 25): Promise<{ due: number; sent: number; failed: number }> {
+  await ensureMailSchema()
+  const sql = db()
+  const now = new Date().toISOString()
+  const due = await sql`
+    SELECT id, payload, attempts FROM mail_scheduled
+    WHERE status = 'pending' AND send_after <= ${now}
+    ORDER BY send_after LIMIT ${limit}`
+
+  let sent = 0
+  let failed = 0
+  for (const row of due) {
+    const id = String(row.id)
+    const claimed = await sql`
+      UPDATE mail_scheduled SET status = 'sending' WHERE id = ${id} AND status = 'pending' RETURNING id`
+    if (!claimed.length) continue
+
+    const send = parse(row.payload)
+    if (!send) {
+      await sql`UPDATE mail_scheduled SET status = 'failed', last_error = 'unreadable payload' WHERE id = ${id}`
+      failed += 1
+      continue
+    }
+
+    try {
+      // scheduledAt is deliberately dropped: the wait already happened here.
+      const { scheduledAt: _ignored, ...payload } = send.payload
+      const result = await sendMail(payload)
+      await recordSend(send, result?.id ?? null)
+      await sql`
+        UPDATE mail_scheduled SET status = 'sent', sent_id = ${result?.id ?? null}, last_error = NULL WHERE id = ${id}`
+      sent += 1
+    } catch (err) {
+      const attempts = Number(row.attempts ?? 0) + 1
+      const reason = err instanceof Error ? err.message : String(err)
+      await sql`
+        UPDATE mail_scheduled
+        SET status = ${attempts >= MAX_ATTEMPTS ? 'failed' : 'pending'}, attempts = ${attempts}, last_error = ${reason}
+        WHERE id = ${id}`
+      failed += 1
+    }
+  }
+  return { due: due.length, sent, failed }
+}

package/lib/ses-send.ts

@@ -7,14 +7,26 @@ export function sesConfigured(): boolean {
   return Boolean(process.env.SES_ACCESS_KEY_ID && process.env.SES_SECRET_ACCESS_KEY)
 }
 
-export async function sesSendRaw(raw: string, region = process.env.AWS_SES_REGION ?? 'eu-north-1'): Promise<string | null> {
+/**
+ * `blindCopies` are envelope recipients only. A Bcc header inside the MIME would be handed
+ * to everyone the message reaches, so the address is named to SES instead of written down
+ * where the recipient can read it.
+ */
+export async function sesSendRaw(
+  raw: string,
+  region = process.env.AWS_SES_REGION ?? 'eu-north-1',
+  blindCopies: string[] = [],
+): Promise<string | null> {
   const id = process.env.SES_ACCESS_KEY_ID
   const secret = process.env.SES_SECRET_ACCESS_KEY
   if (!id || !secret) throw new Error('SES_ACCESS_KEY_ID and SES_SECRET_ACCESS_KEY must be configured')
 
   const host = `email.${region}.amazonaws.com`
   const path = '/v2/email/outbound-emails'
-  const body = JSON.stringify({ Content: { Raw: { Data: Buffer.from(raw, 'utf8').toString('base64') } } })
+  const body = JSON.stringify({
+    Content: { Raw: { Data: Buffer.from(raw, 'utf8').toString('base64') } },
+    ...(blindCopies.length ? { Destination: { BccAddresses: blindCopies } } : {}),
+  })
   const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '')
   const stamp = amzDate.slice(0, 8)
   const payloadHash = sha256(body)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novacraft-engineering/mailbox",
-  "version": "0.4.5",
+  "version": "0.4.17",
   "description": "A shared webmail app: one codebase, one deployment per mailbox. Threads, a rich composer with signatures, attachments on S3-compatible storage, sharing links, full-text search, web push and PWA install.",
   "keywords": [
     "webmail",