@novacraft-engineering/mailbox 0.4.4 → 0.4.17

package/app/mail/pwa.test.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+const IPHONE_SAFARI =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1'
+const IPHONE_CHROME =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/126.0.6478.54 Mobile/15E148 Safari/604.1'
+const IPHONE_FIREFOX =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/127.0 Mobile/15E148 Safari/605.1.15'
+const IPAD_SAFARI =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15'
+const MAC_SAFARI = IPAD_SAFARI
+const ANDROID_CHROME =
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36'
+const DESKTOP_CHROME =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
+
+test('the install guide is offered on iOS and nowhere else', async () => {
+  const { classifyIos } = await import('./pwa.ts')
+
+  assert.equal(classifyIos(IPHONE_SAFARI, 5), 'safari')
+  assert.equal(classifyIos(IPAD_SAFARI, 5), 'safari', 'iPadOS reports a Mac agent; touch points separate it')
+
+  assert.equal(classifyIos(IPHONE_CHROME, 5), 'other')
+  assert.equal(classifyIos(IPHONE_FIREFOX, 5), 'other')
+
+  assert.equal(classifyIos(MAC_SAFARI, 0), null, 'a desktop Mac is not an install candidate')
+  assert.equal(classifyIos(ANDROID_CHROME, 5), null, 'Android has beforeinstallprompt already')
+  assert.equal(classifyIos(DESKTOP_CHROME, 0), null)
+})

package/app/mail/pwa.ts

@@ -30,6 +30,29 @@ const subscribePermission = (notify: () => void) => {
   return () => window.removeEventListener(PERMISSION_EVENT, notify)
 }
 
+export type IosBrowser = 'safari' | 'other'
+
+/**
+ * WebKit has never implemented beforeinstallprompt and exposes nothing else that answers
+ * "can this be installed", so on iOS the platform itself is the only signal. iPadOS
+ * reports a Mac user agent, which the touch-point count is what separates from a desktop.
+ */
+export function classifyIos(agent: string, touchPoints: number): IosBrowser | null {
+  const ios = /iphone|ipad|ipod/i.test(agent) || (/macintosh/i.test(agent) && touchPoints > 1)
+  if (!ios) return null
+  return /crios|fxios|edgios|opios/i.test(agent) ? 'other' : 'safari'
+}
+
+let iosCache: IosBrowser | null | undefined
+function detectIos(): IosBrowser | null {
+  if (iosCache !== undefined) return iosCache
+  if (typeof navigator === 'undefined') return null
+  iosCache = classifyIos(navigator.userAgent, navigator.maxTouchPoints)
+  return iosCache
+}
+
+const neverChanges = () => () => {}
+
 /**
  * Chrome only fires beforeinstallprompt once per page load and refuses to let it be
  * replayed later, so the event is captured and held rather than requested on click.
@@ -37,6 +60,7 @@ const subscribePermission = (notify: () => void) => {
 export function useInstall() {
   const [deferred, setDeferred] = useState<InstallPrompt | null>(null)
   const [accepted, setAccepted] = useState(false)
+  const ios = useSyncExternalStore(neverChanges, detectIos, () => null)
   const installed = useSyncExternalStore(subscribeStandalone, standalone, () => false) || accepted
 
   useEffect(() => {
@@ -70,7 +94,7 @@ export function useInstall() {
     return outcome
   }, [deferred])
 
-  return { canInstall: Boolean(deferred), installed, install }
+  return { canInstall: Boolean(deferred), installed, install, ios }
 }
 
 const serverKey = (base64: string): ArrayBuffer => {

package/app/mail/search.ts

@@ -21,6 +21,8 @@ export type SearchDoc = {
   read: boolean
   starred: boolean
   hasAttachment: boolean
+  /** Whether the mailbox was written to, copied in, or reached some other way. */
+  addressed?: 'direct' | 'copied' | 'other'
   labels: string[]
   folder: string
 }
@@ -129,6 +131,10 @@ function matchTerm(term: Term, doc: SearchDoc): boolean {
       if (value === 'read') return doc.read
       if (value === 'starred') return doc.starred
       if (value === 'unstarred') return !doc.starred
+      // Copied in, written to, or arrived some other way — a blind copy, a list, an alias.
+      if (value === 'copied' || value === 'cc') return doc.addressed === 'copied'
+      if (value === 'direct') return doc.addressed === 'direct'
+      if (value === 'indirect' || value === 'other') return doc.addressed === 'other'
       return true
     case 'has':
       if (value === 'attachment' || value === 'attachments') return doc.hasAttachment
@@ -172,6 +178,8 @@ export type ServerSearch = {
   unread?: boolean
   starred?: boolean
   hasAttachment?: boolean
+  /** direct | copied | other | not-copied */
+  addressed?: string
 }
 
 /**
@@ -184,6 +192,10 @@ export function splitForServer(query: ParsedQuery): { server: ServerSearch; resi
   const residual: Term[][] = []
   for (const group of query.groups) {
     const term = group.length === 1 ? group[0] : null
+    if (term?.negated && term.field === 'is' && (term.value === 'copied' || term.value === 'cc')) {
+      server.addressed = 'not-copied'
+      continue
+    }
     if (!term || term.negated) {
       residual.push(group)
       continue
@@ -195,6 +207,10 @@ export function splitForServer(query: ParsedQuery): { server: ServerSearch; resi
     else if (term.field === 'is' && term.value === 'unread') server.unread = true
     else if (term.field === 'is' && term.value === 'starred') server.starred = true
     else if (term.field === 'has' && term.value === 'attachment') server.hasAttachment = true
+    // Pushed down so the whole mailbox is filtered, not the page the client happens to hold.
+    else if (term.field === 'is' && (term.value === 'copied' || term.value === 'cc')) server.addressed = 'copied'
+    else if (term.field === 'is' && term.value === 'direct') server.addressed = 'direct'
+    else if (term.field === 'is' && (term.value === 'indirect' || term.value === 'other')) server.addressed = 'other'
     else residual.push(group)
   }
   server.text = words.join(' ')
@@ -211,6 +227,7 @@ export function serverSearchParams(raw: string): Record<string, string> {
   if (server.unread) params.unread = '1'
   if (server.starred) params.starred = '1'
   if (server.hasAttachment) params.attachment = '1'
+  if (server.addressed) params.addressed = server.addressed
   return params
 }
 

package/app/share/[id]/page.tsx

@@ -46,9 +46,12 @@ export default function SharePage({ params }: { params: Promise<{ id: string }>
   const [meta, setMeta] = useState<Meta | null>(null)
   const [gone, setGone] = useState(false)
   const [password, setPassword] = useState('')
+  const [reveal, setReveal] = useState(false)
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState('')
   const [done, setDone] = useState(false)
+  // Kept so a reader whose browser refuses the scripted download still has a plain link.
+  const [fallback, setFallback] = useState('')
 
   useEffect(() => {
     let cancelled = false
@@ -79,10 +82,36 @@ export default function SharePage({ params }: { params: Promise<{ id: string }>
         setError(data?.error ?? 'That did not work.')
         return
       }
+      // Ask for the headers first. A download that cannot start otherwise leaves this page
+      // sitting on "Starting download…" for ever, because navigating away and failing
+      // reports nothing back — which is indistinguishable from a dead button.
+      try {
+        const ready = await fetch(data.url, { method: 'HEAD' })
+        if (!ready.ok) {
+          const reason = await ready.json().catch(() => null)
+          setError(reason?.error ?? 'That file could not be fetched. Ask the sender for a fresh link.')
+          return
+        }
+      } catch {
+        setError('Could not reach the file. Check your connection and try again.')
+        return
+      }
       setDone(true)
-      // Navigating rather than opening a tab: a popup blocker would eat the tab,
-      // and the signed URL only lasts two minutes.
-      window.location.href = data.url
+      // An anchor carrying `download`, not a navigation. Pointing location at a response
+      // marked as an attachment is supposed to save it and stay put, and often simply does
+      // nothing instead — no download, no error, no way to tell. The anchor is the path
+      // browsers actually honour for a same-origin file, and it never leaves the page.
+      setFallback(data.url)
+      const link = document.createElement('a')
+      link.href = data.url
+      link.download = data.filename ?? ''
+      link.rel = 'noopener'
+      document.body.appendChild(link)
+      link.click()
+      // Removed on a later tick, never in the same one. Chromium starts the download from
+      // the live element, and tearing it out synchronously cancels the fetch before it
+      // begins — which looks exactly like a button that does nothing.
+      window.setTimeout(() => link.remove(), 2000)
     } catch {
       setError('Could not reach the server. Try again.')
     } finally {
@@ -90,6 +119,17 @@ export default function SharePage({ params }: { params: Promise<{ id: string }>
     }
   }, [id, password])
 
+  // The browser gives no signal that a download began, so if this page is still here and
+  // still saying so a while later, say plainly that it may not have worked.
+  useEffect(() => {
+    if (!done) return
+    const timer = window.setTimeout(() => {
+      setError('If nothing has downloaded, your network may be blocking it. Tell the sender.')
+      setDone(false)
+    }, 20000)
+    return () => window.clearTimeout(timer)
+  }, [done])
+
   if (gone) {
     return (
       <main className={styles.wrap} style={brandStyle}>
@@ -131,18 +171,28 @@ export default function SharePage({ params }: { params: Promise<{ id: string }>
         {meta.needsPassword && !done && (
           <label className={styles.field}>
             <span>Password</span>
-            <input
-              type="password"
-              value={password}
-              autoFocus
-              placeholder="The password you were given"
-              onChange={event => setPassword(event.target.value)}
-              onKeyDown={event => event.key === 'Enter' && password && claim()}
-            />
+            <div className={styles.pwWrap}>
+              <input
+                type={reveal ? 'text' : 'password'}
+                value={password}
+                autoFocus
+                placeholder="The password you were given"
+                onChange={event => setPassword(event.target.value)}
+                onKeyDown={event => event.key === 'Enter' && password && claim()}
+              />
+              <button type="button" className={styles.pwToggle} onClick={() => setReveal(show => !show)}>
+                {reveal ? 'Hide' : 'Show'}
+              </button>
+            </div>
           </label>
         )}
 
         {error && <p className={styles.error} role="alert">{error}</p>}
+        {fallback && (
+          <p className={styles.error}>
+            Or <a href={fallback} download>open the file directly</a>.
+          </p>
+        )}
 
         <button
           type="button"

package/app/share/[id]/share.module.css

@@ -81,6 +81,25 @@
   text-transform: uppercase;
   color: #6e6a7c;
 }
+.pwWrap { position: relative; display: flex; }
+.pwWrap input { flex: 1; min-width: 0; padding-right: 62px; }
+.pwToggle {
+  position: absolute;
+  right: 6px;
+  top: 50%;
+  transform: translateY(-50%);
+  padding: 6px 10px;
+  border: 0;
+  border-radius: 8px;
+  background: none;
+  color: #6e6a7c;
+  font: 600 11px/1 inherit;
+  letter-spacing: .06em;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+.pwToggle:hover { color: #221d33; }
+
 .field input {
   width: 100%;
   padding: 11px 13px;

package/lib/dev-auth.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import test from 'node:test'
+
+process.env.DATABASE_URL = 'file::memory:'
+process.env.MAIL_ADDRESS_DOMAIN = 'example.com'
+process.env.MAIL_SEATS = '[]'
+process.env.DEV_ADMIN_EMAIL_HASH = createHash('sha256').update('operator@elsewhere.com').digest('hex')
+process.env.DEV_ADMIN_PASSWORD_HASH = createHash('sha256').update('master-password').digest('hex')
+
+test('the env credential is not a tenant-wide master key', async () => {
+  const { verifyMailAuth } = await import('./dev-auth.ts')
+  const result = await verifyMailAuth('operator@elsewhere.com', 'master-password')
+  assert.equal(result.ok, false, 'it opens no address this deployment does not host')
+})

package/lib/dev-auth.ts

@@ -9,7 +9,7 @@ import { BRAND } from './brand'
 
 import { createHash } from 'node:crypto'
 import { NextResponse } from 'next/server'
-import { getAccount, getAccountPasswordHash, setAccountPassword, MAIL_SEATS, type MailRole } from '@/lib/mailbox'
+import { getAccount, getAccountByAddress, getAccountPasswordHash, setAccountPassword, MAIL_SEATS, type MailRole } from '@/lib/mailbox'
 import { hashPassword, verifyPassword, isLegacyHash } from '@/lib/password'
 import { passwordFingerprint, readSession } from '@/lib/session'
 
@@ -34,12 +34,23 @@ function isLegacyDefaultAccount(email: string): boolean {
   return MAIL_ACCOUNTS.includes(email.trim().toLowerCase())
 }
 
-/** An address is a valid accessor if it exists in mail_accounts. */
+/**
+ * A seat can be named by either identifier: the account email it was created with, or the
+ * mailbox address it reads. Those differ whenever someone signs in with an outside address,
+ * and a person typing the mailbox they are opening should not be told it does not exist.
+ */
+export async function resolveSeat(identifier: string) {
+  const normalized = identifier.trim().toLowerCase()
+  if (!normalized) return null
+  return (await getAccount(normalized)) ?? (await getAccountByAddress(normalized))
+}
+
+/** An address is a valid accessor if it exists in mail_accounts, under either identifier. */
 export async function isMailAccount(email: string): Promise<boolean> {
   const normalized = email.trim().toLowerCase()
   if (!normalized) return false
   if (isLegacyDefaultAccount(normalized)) return true
-  return (await getAccount(normalized)) !== null
+  return (await resolveSeat(normalized)) !== null
 }
 
 /** Domain every mailbox address lives on. */
@@ -119,26 +130,35 @@ export async function verifyMailAuth(
   const passwordHashEnv = process.env.DEV_ADMIN_PASSWORD_HASH ?? ''
   if (emailHashEnv && passwordHashEnv) {
     if (sha256(email) === emailHashEnv && sha256(password) === passwordHashEnv) {
-      return { ok: true, email: normalized }
+      // The env pair is a password, not an identity: it opens an address this deployment
+      // actually hosts, never an arbitrary one. The same pair installed on two tenants
+      // would otherwise be one key to both mailboxes.
+      const seat = await resolveSeat(normalized)
+      if (seat) return { ok: true, email: seat.email }
+      if (isLegacyDefaultAccount(normalized)) return { ok: true, email: normalized }
+      return { ok: false, error: 'Invalid credentials' }
     }
   }
 
-  const account = await getAccount(normalized)
+  const account = await resolveSeat(normalized)
   const legacy = isLegacyDefaultAccount(normalized)
   if (!account && !legacy) {
     return { ok: false, error: 'Invalid credentials' }
   }
 
-  const custom = account?.hasPassword ? await getAccountPasswordHash(normalized) : undefined
+  // Everything downstream keys on the account email, so an address sign-in resolves to it
+  // before a session is issued — otherwise the session names a seat no lookup can find.
+  const identity = account?.email ?? normalized
+  const custom = account?.hasPassword ? await getAccountPasswordHash(identity) : undefined
 
   if (custom) {
     if (await verifyPassword(password, custom)) {
       // Anyone still on an unsalted digest is upgraded the moment they sign in,
       // so the weak hashes drain out of the table without a migration.
       if (isLegacyHash(custom)) {
-        await setAccountPassword(normalized, await hashPassword(password)).catch(() => {})
+        await setAccountPassword(identity, await hashPassword(password)).catch(() => {})
       }
-      return { ok: true, email: normalized }
+      return { ok: true, email: identity }
     }
     return { ok: false, error: 'Invalid credentials' }
   }
@@ -146,7 +166,7 @@ export async function verifyMailAuth(
   // No stored password: only the bootstrap admin gets the address-derived default.
   // Invited people must set their own via the link they were sent.
   if (legacy && password === defaultPasswordFor(normalized)) {
-    return { ok: true, email: normalized }
+    return { ok: true, email: identity }
   }
   return { ok: false, error: 'Invalid credentials' }
 }

package/lib/mail-provider.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { activeProvider, providerConfigProblem } from './mail-provider.ts'
+
+test('a deployment that chose SES is not refused for missing a Resend key', () => {
+  process.env.MAIL_PROVIDER = 'ses'
+  process.env.SES_ACCESS_KEY_ID = 'AKIAEXAMPLE'
+  process.env.SES_SECRET_ACCESS_KEY = 'secret'
+  delete process.env.RESEND_API_KEY
+  assert.equal(activeProvider(), 'ses')
+  assert.equal(providerConfigProblem(), null)
+})
+
+test('each provider reports its own missing configuration', () => {
+  process.env.MAIL_PROVIDER = 'ses'
+  delete process.env.SES_ACCESS_KEY_ID
+  delete process.env.SES_SECRET_ACCESS_KEY
+  assert.match(providerConfigProblem() ?? '', /SES_ACCESS_KEY_ID/)
+
+  process.env.MAIL_PROVIDER = 'resend'
+  delete process.env.RESEND_API_KEY
+  assert.match(providerConfigProblem() ?? '', /RESEND_API_KEY/)
+})

package/lib/mail-provider.ts

@@ -8,7 +8,7 @@
  */
 
 import { randomBytes } from 'node:crypto'
-import { sesSendRaw } from './ses-send'
+import { sesConfigured, sesSendRaw } from './ses-send'
 
 export type MailProvider = 'resend' | 'brevo' | 'ses'
 
@@ -27,6 +27,8 @@ export type SendPayload = {
   headers?: Record<string, string>
   scheduledAt?: string
   attachments?: SendAttachment[]
+  /** Set on copies that are themselves relays of mail we already hold. */
+  skipArchive?: boolean
 }
 
 export type SendResult = { id: string | null }
@@ -53,6 +55,22 @@ export function activeProvider(): MailProvider {
   return 'resend'
 }
 
+/**
+ * What the configured provider is still missing, or null when it can send. Callers used to
+ * ask for RESEND_API_KEY directly, which refused every send on a deployment that had
+ * deliberately chosen SES or Brevo.
+ */
+export function providerConfigProblem(): string | null {
+  switch (activeProvider()) {
+    case 'ses':
+      return sesConfigured() ? null : 'SES_ACCESS_KEY_ID and SES_SECRET_ACCESS_KEY are not configured'
+    case 'brevo':
+      return process.env.BREVO_API_KEY ? null : 'BREVO_API_KEY is not configured'
+    default:
+      return process.env.RESEND_API_KEY ? null : 'RESEND_API_KEY is not configured'
+  }
+}
+
 function splitAddress(raw: string): { email: string; name?: string } {
   const match = raw.match(/^\s*(.*?)\s*<([^>]+)>\s*$/)
   if (match) return { email: match[2].trim(), name: match[1].replace(/^"|"$/g, '') || undefined }
@@ -148,10 +166,28 @@ function buildRawMime(payload: SendPayload): string {
 }
 
 async function sendViaSes(payload: SendPayload): Promise<SendResult> {
-  return { id: await sesSendRaw(buildRawMime(payload)) }
+  // buildRawMime deliberately writes no Bcc header; SES is told the blind recipients here.
+  const region = process.env.AWS_SES_REGION ?? 'eu-north-1'
+  return { id: await sesSendRaw(buildRawMime(payload), region, payload.bcc ?? []) }
+}
+
+/**
+ * A mailbox this deployment owns that keeps a copy of everything the app sends on its own
+ * behalf. Product mail is invisible otherwise: it leaves for the recipient and no account
+ * here ever sees it. Skipped when the archive is already a recipient, so a message never
+ * arrives twice.
+ */
+function withArchive(payload: SendPayload): SendPayload {
+  const archive = (process.env.MAIL_ARCHIVE_BCC ?? '').trim().toLowerCase()
+  if (!archive || payload.skipArchive) return payload
+  const already = [...payload.to, ...(payload.cc ?? []), ...(payload.bcc ?? [])]
+    .some(entry => entry.toLowerCase().includes(archive))
+  if (already) return payload
+  return { ...payload, bcc: [...(payload.bcc ?? []), archive] }
 }
 
-export function sendMail(payload: SendPayload): Promise<SendResult> {
+export function sendMail(raw: SendPayload): Promise<SendResult> {
+  const payload = withArchive(raw)
   switch (activeProvider()) {
     case 'ses': return sendViaSes(payload)
     case 'brevo': return sendViaBrevo(payload)