@novacraft-engineering/mailbox 0.1.0

package/.env.example

@@ -0,0 +1,110 @@
+# ─── Tenant identity ────────────────────────────────────────────────────────
+# Every mailbox address lives on this domain.
+MAIL_ADDRESS_DOMAIN=example.com
+MAIL_FROM="Example <info@example.com>"
+MAIL_SUPPORT_EMAIL=info@example.com
+
+# The origin used for links that go out in email (password resets, the open pixel).
+# Never derived from the request: the Host header is caller-controlled.
+MAIL_PUBLIC_URL=https://mail.example.com
+
+# ─── Branding (server) ──────────────────────────────────────────────────────
+BRAND_NAME=Example
+BRAND_LEGAL_NAME=Example Limited
+BRAND_WEBSITE=www.example.com
+BRAND_LOGO_URL=
+BRAND_MARK_URL=
+BRAND_ADDRESS=
+BRAND_TEL=
+BRAND_REGULATORY=
+BRAND_DISCLAIMER=
+BRAND_COLOR_ACCENT=rgb(109, 40, 217)
+BRAND_COLOR_LINK=rgb(17, 85, 204)
+BRAND_COLOR_MUTED=rgb(107, 114, 128)
+
+# ─── Branding (client, inlined at build time) ───────────────────────────────
+NEXT_PUBLIC_BRAND_NAME=Example
+NEXT_PUBLIC_MAIL_DOMAIN=example.com
+NEXT_PUBLIC_BRAND_WEBSITE=www.example.com
+NEXT_PUBLIC_MAIL_PUBLIC_URL=https://mail.example.com
+NEXT_PUBLIC_BRAND_MARK_URL=
+NEXT_PUBLIC_BRAND_ACCENT="#6d28d9"
+# Comma-separated seed addresses offered on the sign-in screen.
+NEXT_PUBLIC_MAIL_ADDRESSES=info@example.com
+
+# ─── Seats ──────────────────────────────────────────────────────────────────
+# JSON. The first admin owns the shared inbox. Seeded on first boot only.
+MAIL_SEATS=[{"email":"info@example.com","address":"info@example.com","name":"Example","role":"admin"}]
+# JSON. Delivery aliases: mail for the key is stored in the value's box.
+MAIL_ADDRESS_ALIASES={}
+
+# ─── Store ──────────────────────────────────────────────────────────────────
+# Local SQLite on a mounted volume (recommended):
+TURSO_DATABASE_URL=file:/data/mail.sqlite
+TURSO_AUTH_TOKEN=
+# Falls back to Cloudflare D1 when TURSO_DATABASE_URL is unset.
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_D1_TOKEN=
+D1_DATABASE_ID=
+
+# Signs the session cookie. Without it every request falls back to sending the
+# password on each call, so set it. Rotating the value signs everybody out.
+MAIL_SESSION_SECRET=
+
+# ─── Sending ────────────────────────────────────────────────────────────────
+# ses | resend | brevo
+MAIL_PROVIDER=ses
+SES_ACCESS_KEY_ID=
+SES_SECRET_ACCESS_KEY=
+AWS_SES_REGION=eu-north-1
+RESEND_API_KEY=
+RESEND_WEBHOOK_SECRET=
+
+# Optional: copy inbound mail to an outside address. Leave empty to forward
+# nothing — pointing this at an address this app receives would loop.
+MAIL_FORWARD_TO=
+
+# ─── Attachments (S3-compatible, e.g. Cloudflare R2) ────────────────────────
+R2_S3_ENDPOINT=
+R2_BUCKET=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+BLOB_READ_WRITE_TOKEN=
+
+# ─── Optional extras ────────────────────────────────────────────────────────
+SAFE_BROWSING_API_KEY=
+VAPID_PUBLIC_KEY=
+VAPID_PRIVATE_KEY=
+VAPID_SUBJECT=mailto:info@example.com
+NEXT_PUBLIC_BRAND_LEGAL_NAME=Example Limited
+MAIL_ADDRESS_DOMAINS=
+MAIL_DEFAULT_ADDRESS_DOMAIN=
+NEXT_PUBLIC_MAIL_ADDRESS_DOMAINS=
+BRAND_ICON_URL=
+BRAND_APPLE_ICON_URL=
+BRAND_ACCENT_HEX="#6d28d9"
+
+# Per-tenant looks that must not carry over between brands.
+# Mark drawn in the app chrome (alpha-only PNG, CSS-masked). A path under public/ or a full URL.
+BRAND_CHROME_MARK_URL=/brand/mark.png
+NEXT_PUBLIC_BRAND_CHROME_MARK_URL=/brand/mark.png
+# Frame around the mark in email signatures: none, accent, or any CSS colour. Radius in px.
+BRAND_SIGNATURE_MARK_BORDER=none
+BRAND_SIGNATURE_MARK_RADIUS=0
+NEXT_PUBLIC_BRAND_SIGNATURE_MARK_BORDER=none
+NEXT_PUBLIC_BRAND_SIGNATURE_MARK_RADIUS=0
+# The browser builds the house signature too, so the fields it prints need public twins.
+NEXT_PUBLIC_BRAND_ADDRESS=
+NEXT_PUBLIC_BRAND_TEL=
+NEXT_PUBLIC_BRAND_REGULATORY=
+NEXT_PUBLIC_BRAND_DISCLAIMER=
+NEXT_PUBLIC_BRAND_COLOR_ACCENT=rgb(109, 40, 217)
+NEXT_PUBLIC_BRAND_COLOR_LINK=rgb(17, 85, 204)
+NEXT_PUBLIC_BRAND_COLOR_MUTED=rgb(107, 114, 128)
+
+# Tenant images live on the volume, never in the repository. See public/brand/README.md.
+BRAND_ASSET_DIR=/data/brand
+
+# Outside production the app seeds test@$MAIL_ADDRESS_DOMAIN as an admin, password the
+# same as the address, so a fresh checkout can be signed into. Never seeded when
+# NODE_ENV=production.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novacraft Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# Mailbox
+
+A shared webmail app: one codebase, one deployment per mailbox. Inbox and
+threads, a rich composer with signatures and templates, attachments on
+S3-compatible storage, sharing links, full-text search, web push, PWA install,
+multi-accessor accounts with roles, and password reset.
+
+Every tenant-specific value — name, domain, colours, signature copy, artwork —
+lives in configuration. Nothing in this repository names or pictures any one
+business, and nothing added to it should.
+
+## Deploying — read this first
+
+**Never deploy, and never `git push`, unless the person you are working with asks
+for it in that same request.** This is a standing rule for every agent and every
+session. A granted deploy covers that one deploy only; it is not permission for
+the next one.
+
+Here, pushing *is* deploying. Coolify auto-deploys `master` on push, and a single
+push updates **every** live mailbox at once, not just the one you are working on.
+Finish the work, commit locally, leave it unpushed, and say plainly that it is
+waiting.
+
+## Standing up a new mailbox
+
+1. Copy `.env.example` and fill it in. Nothing is hardcoded to a tenant.
+2. Put three images on the volume at `BRAND_ASSET_DIR` — see `public/brand/README.md`.
+3. Point `TURSO_DATABASE_URL` at a SQLite file on a mounted volume.
+4. Deploy. The schema is created on first boot and migrates itself forward.
+
+## Trying it locally
+
+Outside production the app seeds one account for you — `test@<MAIL_ADDRESS_DOMAIN>`,
+an admin whose password is the address itself — so a fresh checkout can be signed
+into without configuring seats. It is never seeded when `NODE_ENV=production`.
+
+`node --experimental-strip-types scripts/seed-dev.mjs` then fills that mailbox with
+enough traffic to exercise the list, search, paging and attachments. Create the schema
+first by starting the app once, or by calling `ensureMailSchema()`.
+
+The attachments are real files, not records: a PDF, a photo, a short video, a
+spreadsheet and a Word document, generated on the spot and uploaded once. Pictures and
+video need `ffmpeg` and the document needs `zip`; whatever is missing is skipped. With
+no bucket configured the seed still runs and writes the records alone, as it always
+did.
+
+## Configuration
+
+`lib/brand.ts` is the single server-side source of tenant identity — name,
+domain, signature copy, colours, seats, aliases. `lib/brand.client.ts` is the
+browser half, read from `NEXT_PUBLIC_*` and inlined at build time, so a rebuild
+is required to change client-visible branding.
+
+Seats are JSON in `MAIL_SEATS` and seed on first boot only; afterwards accounts
+are managed in the app. `MAIL_ADDRESS_ALIASES` redirects delivery for a seat
+whose mail someone else now reads.
+
+## Storage
+
+`TURSO_DATABASE_URL` takes precedence; without it the app falls back to
+Cloudflare D1, so moving between the two needs no coordinated redeploy. A
+`file:` URL uses local SQLite, which is what a single box wants.
+
+Attachments go to any S3-compatible bucket via the `R2_*` variables.
+
+## Sending
+
+`MAIL_PROVIDER` selects `ses`, `resend` or `brevo` behind one seam. SES is
+signed in-process; no SDK.
+
+## Tests
+
+```
+npx tsx --test lib/*.test.ts
+```

package/app/api/mail/accessors/route.ts

@@ -0,0 +1,197 @@
+import { BRAND, ADDRESS_DOMAINS as BRAND_ADDRESS_DOMAINS } from '@/lib/brand'
+import { randomBytes } from 'node:crypto'
+import { NextResponse } from 'next/server'
+import { Resend } from 'resend'
+import { mailAuthGuard, resolveAccount } from '@/lib/dev-auth'
+import {
+  listAccounts,
+  getAccount,
+  getAccountByAddress,
+  createAccount,
+  updateAccount,
+  deleteAccount,
+  createResetToken,
+  recordSentMeta,
+  type MailRole,
+} from '@/lib/mailbox'
+
+export const runtime = 'nodejs'
+
+const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000
+// Personal addresses live on the already-verified (sending + receiving) Resend domain.
+const ADDRESS_DOMAIN = BRAND.domain
+
+/**
+ * Every suffix an accessor mailbox may use. Only list domains whose MX actually points at
+ * our inbound webhook — a domain we can send as but not receive on would look like a working
+ * mailbox and silently drop replies. The default domain always stays first.
+ */
+const ADDRESS_DOMAINS: string[] = BRAND_ADDRESS_DOMAINS
+
+function resolveDomain(requested?: string): string | null {
+  if (!requested) return ADDRESS_DOMAIN
+  const wanted = requested.trim().toLowerCase().replace(/^@/, '')
+  return ADDRESS_DOMAINS.includes(wanted) ? wanted : null
+}
+
+async function requireAdmin(req: Request): Promise<NextResponse | null> {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+  const account = await resolveAccount(req)
+  if (account.role !== 'admin') {
+    return NextResponse.json({ ok: false, error: 'Admin access required' }, { status: 403 })
+  }
+  return null
+}
+
+function slugifyHandle(raw: string): string {
+  return raw
+    .trim()
+    .toLowerCase()
+    .replace(/@.*/, '')
+    .replace(/[^a-z0-9.]+/g, '.')
+    .replace(/^\.+|\.+$/g, '')
+    .slice(0, 40)
+}
+
+async function uniqueAddress(handle: string, domain: string = ADDRESS_DOMAIN): Promise<string> {
+  const base = slugifyHandle(handle) || 'user'
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    const candidate = `${attempt === 0 ? base : `${base}${attempt + 1}`}@${domain}`
+    if (!(await getAccountByAddress(candidate))) return candidate
+  }
+  return `${base}.${randomBytes(3).toString('hex')}@${domain}`
+}
+
+export async function GET(req: Request) {
+  const denied = await requireAdmin(req)
+  if (denied) return denied
+  const accessors = await listAccounts()
+  return NextResponse.json({ ok: true, accessors, domain: ADDRESS_DOMAIN, domains: ADDRESS_DOMAINS })
+}
+
+export async function POST(req: Request) {
+  const denied = await requireAdmin(req)
+  if (denied) return denied
+  const inviter = await resolveAccount(req)
+
+  let body: { email?: string; name?: string; role?: MailRole; handle?: string; domain?: string }
+  try {
+    body = await req.json()
+  } catch {
+    return NextResponse.json({ ok: false, error: 'Invalid JSON' }, { status: 400 })
+  }
+
+  const email = (body.email ?? '').trim().toLowerCase()
+  if (!email || !email.includes('@')) {
+    return NextResponse.json({ ok: false, error: 'A valid email is required' }, { status: 400 })
+  }
+  const existing = await getAccount(email)
+  if (existing && existing.status === 'active') {
+    return NextResponse.json({ ok: false, error: 'That person already has an account' }, { status: 409 })
+  }
+
+  const role: MailRole = body.role === 'admin' ? 'admin' : 'member'
+  const name = body.name?.trim() || null
+  const domain = resolveDomain(body.domain)
+  if (!domain) return NextResponse.json({ ok: false, error: 'That mail domain is not available' }, { status: 400 })
+  const address = existing?.address ?? (await uniqueAddress(body.handle || name || email, domain))
+
+  await createAccount({ email, address, role, name, status: 'pending', invitedBy: inviter.email })
+
+  const token = randomBytes(32).toString('hex')
+  await createResetToken(email, token, Date.now() + INVITE_TTL_MS)
+
+  const apiKey = process.env.RESEND_API_KEY
+  if (apiKey) {
+    const from = (process.env.RESEND_FROM ?? BRAND.supportEmail).replace(/^.*<|>$/g, '')
+    const origin = process.env.MAIL_PUBLIC_URL?.replace(/\/$/, '') || new URL(req.url).origin
+    const inviteUrl = `${origin}/mail/reset?token=${token}&invite=1`
+    const resend = new Resend(apiKey)
+    try {
+      const { data } = await resend.emails.send({
+        from: `${BRAND.name} Mail <${from}>`,
+        to: [email],
+        subject: `You've been invited to ${BRAND.name} Mail`,
+        text: `${inviter.email} invited you to ${BRAND.name} Mail.\n\nSet your password to get started: ${inviteUrl}\n\nThis link expires in 7 days.`,
+        html: `<div style="font-family:Arial,Helvetica,sans-serif;font-size:15px;line-height:1.6;color:#1A1030;">
+          <p style="margin:0 0 12px;color:${BRAND.colors.accent};font-weight:600;">You've been invited to ${BRAND.name} Mail</p>
+          <p style="margin:0 0 16px;">${name ? `Hi ${name}, ` : ''}you've been given access to ${BRAND.name} Mail. Set a password to get started.</p>
+          <a href="${inviteUrl}" style="display:inline-block;background:${BRAND.colors.accent};color:#fff;text-decoration:none;font-weight:600;padding:11px 20px;border-radius:8px;">Set your password</a>
+          <p style="margin:16px 0 0;color:#8E84A8;font-size:13px;">This invite link expires in 7 days.</p>
+        </div>`,
+      })
+      if (data?.id) await recordSentMeta(data.id, null, true).catch(() => {})
+    } catch (err) {
+      console.warn('[mail] invite email failed:', err)
+    }
+  }
+
+  return NextResponse.json({ ok: true, email, address, role })
+}
+
+export async function PATCH(req: Request) {
+  const denied = await requireAdmin(req)
+  if (denied) return denied
+  let body: { email?: string; role?: MailRole; name?: string | null; handle?: string; domain?: string }
+  try {
+    body = await req.json()
+  } catch {
+    return NextResponse.json({ ok: false, error: 'Invalid JSON' }, { status: 400 })
+  }
+  const email = (body.email ?? '').trim().toLowerCase()
+  if (!email) return NextResponse.json({ ok: false, error: 'email is required' }, { status: 400 })
+  const patch: { role?: MailRole; name?: string | null; address?: string } = {}
+  if (body.role) patch.role = body.role === 'admin' ? 'admin' : 'member'
+  if (body.name !== undefined) patch.name = body.name?.trim() || null
+
+  if (body.handle !== undefined || body.domain !== undefined) {
+    const current = (await getAccount(email))?.address ?? ''
+    const handle = slugifyHandle(body.handle ?? current.split('@')[0])
+    if (!handle) return NextResponse.json({ ok: false, error: 'Mailbox name is not valid' }, { status: 400 })
+    const domain = resolveDomain(body.domain ?? current.split('@')[1])
+    if (!domain) return NextResponse.json({ ok: false, error: 'That mail domain is not available' }, { status: 400 })
+    const address = `${handle}@${domain}`
+    const holder = await getAccountByAddress(address)
+    if (holder && holder.email !== email) {
+      return NextResponse.json({ ok: false, error: `${address} is already taken` }, { status: 409 })
+    }
+    patch.address = address
+  }
+
+  // Never demote the last remaining admin.
+  if (patch.role === 'member') {
+    const admins = (await listAccounts()).filter(acc => acc.role === 'admin')
+    if (admins.length <= 1 && admins.some(acc => acc.email === email)) {
+      return NextResponse.json({ ok: false, error: 'At least one admin is required' }, { status: 400 })
+    }
+  }
+  await updateAccount(email, patch)
+  return NextResponse.json({ ok: true })
+}
+
+export async function DELETE(req: Request) {
+  const denied = await requireAdmin(req)
+  if (denied) return denied
+  const admin = await resolveAccount(req)
+  let body: { email?: string }
+  try {
+    body = await req.json()
+  } catch {
+    return NextResponse.json({ ok: false, error: 'Invalid JSON' }, { status: 400 })
+  }
+  const email = (body.email ?? '').trim().toLowerCase()
+  if (!email) return NextResponse.json({ ok: false, error: 'email is required' }, { status: 400 })
+  if (email === admin.email.toLowerCase()) {
+    return NextResponse.json({ ok: false, error: "You can't remove your own access" }, { status: 400 })
+  }
+  const target = await getAccount(email)
+  if (target?.role === 'admin') {
+    const admins = (await listAccounts()).filter(acc => acc.role === 'admin')
+    if (admins.length <= 1) {
+      return NextResponse.json({ ok: false, error: 'At least one admin is required' }, { status: 400 })
+    }
+  }
+  await deleteAccount(email)
+  return NextResponse.json({ ok: true })
+}

package/app/api/mail/attachments/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server'
+import { mailAuthGuard, resolveAccount } from '@/lib/dev-auth'
+import { listInboundWithAttachments } from '@/lib/mailbox'
+
+// The attachment list is found with a LIKE over the mailbox, which no index can serve:
+// every row the owner has is examined on each call, and Turso meters every one of
+// them. A warm instance answers repeat callers from memory for five minutes.
+const FILES_TTL_MS = 5 * 60 * 1000
+type FileRows = Awaited<ReturnType<typeof listInboundWithAttachments>>
+const filesCache = new Map<string, { at: number; value: FileRows }>()
+async function cachedFiles(owner: string | null): Promise<FileRows> {
+  const key = owner ?? ''
+  const hit = filesCache.get(key)
+  if (hit && Date.now() - hit.at < FILES_TTL_MS) return hit.value
+  const value = await cachedFiles(owner)
+  filesCache.set(key, { at: Date.now(), value })
+  return value
+}
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+  const account = await resolveAccount(req)
+  if (!account.email) return NextResponse.json({ ok: false, error: 'Not signed in.' }, { status: 401 })
+
+  // Null would list every mailbox's files; the Files panel shows the signed-in one.
+  const owner = account.address ?? account.email
+  const rows = await listInboundWithAttachments(owner)
+  // Bytes have lived under `key` since they moved to our own bucket; only the oldest rows
+  // still carry a provider `url`. Filtering on url alone hid nearly everything here, and
+  // handed out a link this app cannot serve inline.
+  const files = rows.flatMap(row =>
+    row.attachments
+      .map((file, index) => ({ file, index }))
+      .filter(({ file }) => (typeof file.key === 'string' && file.key) || (typeof file.url === 'string' && file.url))
+      .map(({ file, index }) => ({
+        messageId: row.id,
+        filename: String(file.filename ?? 'attachment'),
+        size: Number(file.size ?? 0),
+        contentType: file.contentType ? String(file.contentType) : undefined,
+        url:
+          typeof file.key === 'string' && file.key
+            ? `/api/mail/inbox/attachments/download?id=${encodeURIComponent(row.id)}&index=${index}`
+            : String(file.url),
+        subject: row.subject,
+        from: row.from,
+        at: row.receivedAt,
+      })),
+  )
+  return NextResponse.json({ ok: true, files })
+}

package/app/api/mail/company-signature/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server'
+import { mailAuthGuard, resolveAccount } from '@/lib/dev-auth'
+import { getSettings, setSettings } from '@/lib/mailbox'
+
+export const runtime = 'nodejs'
+
+/** Not an address anyone can sign in as, so it can never collide with a person's settings. */
+const COMPANY = '__company__'
+
+export async function GET(req: Request) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+  const stored = await getSettings(COMPANY)
+  return NextResponse.json({
+    ok: true,
+    signature: typeof stored.signature === 'string' ? stored.signature : '',
+    logo: typeof stored.logo === 'string' ? stored.logo : '',
+  })
+}
+
+export async function PUT(req: Request) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+  const account = await resolveAccount(req)
+  if (account.role !== 'admin') return NextResponse.json({ ok: false, error: 'Admin access required' }, { status: 403 })
+  let body: { signature?: unknown; logo?: unknown }
+  try {
+    body = await req.json()
+  } catch {
+    return NextResponse.json({ ok: false, error: 'Invalid JSON' }, { status: 400 })
+  }
+  const signature = typeof body.signature === 'string' ? body.signature : ''
+  const logo = typeof body.logo === 'string' ? body.logo : ''
+  await setSettings(COMPANY, { signature, logo })
+  return NextResponse.json({ ok: true })
+}

package/app/api/mail/contacts/route.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from 'next/server'
+import { mailAuthGuard } from '@/lib/dev-auth'
+import { searchContacts } from '@/lib/mailbox'
+
+export const runtime = 'nodejs'
+
+export async function GET(req: Request) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+  const query = new URL(req.url).searchParams.get('q') ?? ''
+  const contacts = await searchContacts(query)
+  return NextResponse.json({ ok: true, contacts })
+}

package/app/api/mail/emails/[id]/attachments/download/route.ts

@@ -0,0 +1,69 @@
+import { NextResponse } from 'next/server'
+import { mailAuthGuard } from '@/lib/dev-auth'
+import { getSentAttachments } from '@/lib/mailbox'
+import { getObject } from '@/lib/r2'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+/**
+ * Streams an attachment off a message we sent, through this domain.
+ *
+ * The provider hands out links on a host of its own, and on the networks the office
+ * uses that host does not resolve — the message opens and the file does not. The
+ * reader already reached this origin to load the page.
+ */
+export async function GET(req: Request, context: { params: Promise<{ id: string }> }) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+
+  const { id } = await context.params
+  const params = new URL(req.url).searchParams
+  const index = Number(params.get('index') ?? 0)
+  const inline = params.get('inline') === '1'
+  const position = Number.isFinite(index) ? index : 0
+
+  const stored = (await getSentAttachments(id).catch(() => []))[position]
+  if (stored?.key) {
+    const object = await getObject(stored.key)
+    if (object?.body) {
+      const name = (stored.filename || 'attachment').replace(/["\\]/g, '')
+      return new Response(object.body, {
+        headers: {
+          'content-type': stored.contentType ?? object.headers.get('content-type') ?? 'application/octet-stream',
+          'content-disposition': `${inline ? 'inline' : 'attachment'}; filename="${name}"`,
+          ...(object.headers.get('content-length') ? { 'content-length': object.headers.get('content-length')! } : {}),
+          'cache-control': 'private, max-age=3600',
+        },
+      })
+    }
+  }
+
+  const apiKey = process.env.RESEND_API_KEY
+  if (!apiKey) return NextResponse.json({ ok: false, error: 'Sending is not configured.' }, { status: 503 })
+
+  const listing = await fetch(`https://api.resend.com/emails/${encodeURIComponent(id)}/attachments`, {
+    headers: { authorization: `Bearer ${apiKey}` },
+  }).catch(() => null)
+  if (!listing?.ok) return NextResponse.json({ ok: false, error: 'That file could not be read.' }, { status: 502 })
+
+  const payload = (await listing.json()) as { data?: Array<Record<string, unknown>> }
+  const entry = (payload.data ?? [])[position]
+  const source = entry?.download_url ? String(entry.download_url) : ''
+  if (!source) return NextResponse.json({ ok: false, error: 'That file is no longer available.' }, { status: 404 })
+
+  const file = await fetch(source).catch(() => null)
+  if (!file?.ok || !file.body) {
+    return NextResponse.json({ ok: false, error: 'That file could not be read.' }, { status: 502 })
+  }
+
+  const filename = String(entry.filename ?? 'attachment').replace(/["\\]/g, '')
+  return new Response(file.body, {
+    headers: {
+      'content-type': String(entry.content_type ?? file.headers.get('content-type') ?? 'application/octet-stream'),
+      'content-disposition': `${inline ? 'inline' : 'attachment'}; filename="${filename}"`,
+      ...(file.headers.get('content-length') ? { 'content-length': file.headers.get('content-length')! } : {}),
+      'cache-control': 'private, max-age=3600',
+    },
+  })
+}

package/app/api/mail/emails/[id]/attachments/forward/route.ts

@@ -0,0 +1,65 @@
+import { randomBytes } from 'node:crypto'
+import { NextResponse } from 'next/server'
+import { mailAuthGuard } from '@/lib/dev-auth'
+import { getSentAttachments } from '@/lib/mailbox'
+import { getObject, putObject } from '@/lib/r2'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+/**
+ * Copies the files on a message we sent into a fresh outgoing key, so it can be
+ * forwarded.
+ *
+ * Anything sent since we started recording keys is already in our bucket and is copied
+ * from there. Older messages only exist at the provider, so those are pulled back and
+ * stored on the way through — which also means the next forward of the same message no
+ * longer depends on the provider still having it.
+ */
+export async function POST(req: Request, context: { params: Promise<{ id: string }> }) {
+  const guard = await mailAuthGuard(req)
+  if (guard) return guard
+
+  const { id } = await context.params
+  const copied: Array<{ filename: string; size: number; contentType?: string; key: string }> = []
+
+  const mint = (filename: string) =>
+    `outgoing/${randomBytes(9).toString('hex')}/${filename.replace(/[^\w.\- ]+/g, '_').slice(0, 120)}`
+
+  const ours = await getSentAttachments(id).catch(() => [])
+  for (const entry of ours) {
+    if (!entry.key) continue
+    const object = await getObject(entry.key)
+    if (!object) continue
+    const bytes = Buffer.from(await object.arrayBuffer())
+    const key = mint(entry.filename)
+    if (!(await putObject(key, bytes, entry.contentType))) continue
+    copied.push({ filename: entry.filename, size: bytes.length, contentType: entry.contentType, key })
+  }
+  if (copied.length) return NextResponse.json({ ok: true, attachments: copied })
+
+  // Nothing of ours recorded: this predates that, so fall back to the provider.
+  const apiKey = process.env.RESEND_API_KEY
+  if (!apiKey) return NextResponse.json({ ok: true, attachments: [] })
+
+  const listing = await fetch(`https://api.resend.com/emails/${encodeURIComponent(id)}/attachments`, {
+    headers: { authorization: `Bearer ${apiKey}` },
+  }).catch(() => null)
+  if (!listing?.ok) return NextResponse.json({ ok: true, attachments: [] })
+
+  const payload = (await listing.json()) as { data?: Array<Record<string, unknown>> }
+  for (const entry of payload.data ?? []) {
+    const source = entry.download_url ? String(entry.download_url) : ''
+    if (!source) continue
+    const file = await fetch(source).catch(() => null)
+    if (!file?.ok) continue
+    const bytes = Buffer.from(await file.arrayBuffer())
+    const filename = String(entry.filename ?? 'attachment')
+    const contentType = entry.content_type ? String(entry.content_type) : undefined
+    const key = mint(filename)
+    if (!(await putObject(key, bytes, contentType))) continue
+    copied.push({ filename, size: bytes.length, contentType, key })
+  }
+
+  return NextResponse.json({ ok: true, attachments: copied })
+}