@novacraft-engineering/mailbox 0.1.0

package/lib/password.ts

@@ -0,0 +1,71 @@
+import { brandSlug } from './brand'
+import { createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+
+// promisify picks the 3-arg overload; this deployment passes scrypt options too.
+const scryptAsync = promisify(scrypt) as (
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  options: { N: number },
+) => Promise<Buffer>
+
+const KEY_LENGTH = 64
+const COST = 16384
+
+/**
+ * Stored form is `scrypt$<cost>$<salt-hex>$<key-hex>`. Anything else is read as one of the
+ * bare SHA-256 digests this app wrote before, so existing passwords keep working and get
+ * rewritten to scrypt the next time their owner successfully signs in.
+ */
+export async function hashPassword(plain: string): Promise<string> {
+  const salt = randomBytes(16)
+  const key = await scryptAsync(plain, salt, KEY_LENGTH, { N: COST })
+  return `scrypt$${COST}$${salt.toString('hex')}$${key.toString('hex')}`
+}
+
+export function isLegacyHash(stored: string): boolean {
+  return /^[a-f0-9]{64}$/i.test(stored)
+}
+
+function equals(left: Buffer, right: Buffer): boolean {
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+export async function verifyPassword(plain: string, stored: string): Promise<boolean> {
+  if (!stored) return false
+
+  if (isLegacyHash(stored)) {
+    const digest = createHash('sha256').update(plain).digest()
+    return equals(digest, Buffer.from(stored, 'hex'))
+  }
+
+  const [scheme, cost, salt, key] = stored.split('$')
+  if (scheme !== 'scrypt' || !cost || !salt || !key) return false
+
+  try {
+    const derived = (await scryptAsync(plain, Buffer.from(salt, 'hex'), KEY_LENGTH, {
+      N: Number(cost),
+    }))
+    return equals(derived, Buffer.from(key, 'hex'))
+  } catch {
+    return false
+  }
+}
+
+/** Rejects the passwords an attacker tries first, without imposing character-class theatre. */
+export function passwordProblem(password: string, email: string): string | null {
+  if (password.length < 10) return 'Password must be at least 10 characters'
+  if (password.length > 200) return 'Password must be under 200 characters'
+
+  const lowered = password.toLowerCase()
+  const localPart = email.trim().toLowerCase().split('@')[0]
+  if (lowered === email.trim().toLowerCase()) return 'Password cannot be your email address'
+  if (localPart && lowered.includes(localPart)) return 'Password cannot contain your address'
+  if (/^(.)\1+$/.test(password)) return 'Password cannot be a single repeated character'
+
+  const WEAK = ['password', '12345678', 'qwerty', 'letmein', 'changeme', brandSlug]
+  if (WEAK.some(entry => lowered.includes(entry))) return 'Password is too easy to guess'
+
+  return null
+}

package/lib/public-url.ts

@@ -0,0 +1,14 @@
+/**
+ * The Host header is caller-controlled, so deriving a link from req.url lets an attacker
+ * point a password-reset email at their own domain. Anything that ends up in an email
+ * must use the configured origin; req.url is only a local-development fallback.
+ */
+export function publicOrigin(req: Request): string {
+  const configured = process.env.MAIL_PUBLIC_URL?.trim().replace(/\/$/, '')
+  if (configured) return configured
+
+  const vercel = process.env.VERCEL_PROJECT_PRODUCTION_URL?.trim()
+  if (vercel) return `https://${vercel.replace(/^https?:\/\//, '').replace(/\/$/, '')}`
+
+  return new URL(req.url).origin
+}

package/lib/push.ts

@@ -0,0 +1,37 @@
+import { BRAND } from './brand'
+import webpush from 'web-push'
+import { deletePushSubscription, listPushSubscriptions } from './mailbox'
+
+export type PushPayload = { title: string; body: string; tag?: string; url?: string }
+
+let configured = false
+function configure(): boolean {
+  const publicKey = process.env.VAPID_PUBLIC_KEY
+  const privateKey = process.env.VAPID_PRIVATE_KEY
+  if (!publicKey || !privateKey) return false
+  if (!configured) {
+    webpush.setVapidDetails(BRAND.vapidSubject, publicKey, privateKey)
+    configured = true
+  }
+  return true
+}
+
+/** Pushes to every device the owner has registered; a device the browser has dropped is forgotten. */
+export async function sendPush(owner: string, payload: PushPayload): Promise<number> {
+  if (!configure()) return 0
+  const subscriptions = await listPushSubscriptions(owner)
+  let delivered = 0
+  await Promise.all(
+    subscriptions.map(async subscription => {
+      try {
+        await webpush.sendNotification(subscription, JSON.stringify(payload), { TTL: 3600 })
+        delivered += 1
+      } catch (err) {
+        const status = (err as { statusCode?: number }).statusCode
+        if (status === 404 || status === 410) await deletePushSubscription(subscription.endpoint).catch(() => {})
+        else console.warn('[push] send failed', status ?? err)
+      }
+    }),
+  )
+  return delivered
+}

package/lib/r2.ts

@@ -0,0 +1,157 @@
+/**
+ * R2 over the S3 API, signed with SigV4 by hand.
+ *
+ * No SDK: @aws-sdk/client-s3 is megabytes for the three operations this needs, and
+ * every dependency here is one more thing to vet. Node's crypto already has
+ * everything SigV4 wants.
+ *
+ * Objects are written private. A recipient never touches the bucket directly —
+ * they come through the app, which checks the password and then hands out a
+ * presigned URL that expires. A world-readable bucket with a password page in
+ * front of it protects nothing, because the object URL is the whole secret.
+ */
+
+import { createHash, createHmac } from 'node:crypto'
+
+const SERVICE = 's3'
+// R2 ignores the region but SigV4 requires one in the scope; AWS S3 needs the real one.
+const REGION = process.env.R2_REGION ?? process.env.S3_REGION ?? 'auto'
+
+type Config = { endpoint: string; bucket: string; accessKeyId: string; secretAccessKey: string }
+
+function config(): Config {
+  const endpoint = process.env.R2_S3_ENDPOINT
+  const bucket = process.env.R2_BUCKET
+  const accessKeyId = process.env.R2_ACCESS_KEY_ID
+  const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY
+  if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {
+    throw new Error('R2_S3_ENDPOINT, R2_BUCKET, R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY must be configured')
+  }
+  return { endpoint: endpoint.replace(/\/+$/, ''), bucket, accessKeyId, secretAccessKey }
+}
+
+const sha256 = (value: string) => createHash('sha256').update(value, 'utf8').digest('hex')
+const hmac = (key: Buffer | string, value: string) => createHmac('sha256', key).update(value, 'utf8').digest()
+
+/** Each path segment is encoded, but the slashes between them are not. */
+function encodeKey(key: string): string {
+  return key.split('/').map(segment => encodeURIComponent(segment)).join('/')
+}
+
+function signingKey(secret: string, date: string): Buffer {
+  return hmac(hmac(hmac(hmac(`AWS4${secret}`, date), REGION), SERVICE), 'aws4_request')
+}
+
+/**
+ * A URL that carries its own authorisation and stops working when it expires.
+ * `method` is PUT for an upload, GET for a download.
+ */
+export function presign(
+  key: string,
+  method: 'PUT' | 'GET' | 'DELETE',
+  expiresInSeconds = 900,
+  extraQuery: Record<string, string> = {},
+): string {
+  const { endpoint, bucket, accessKeyId, secretAccessKey } = config()
+  const url = new URL(`${endpoint}/${bucket}/${encodeKey(key)}`)
+
+  const now = new Date()
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '')
+  const dateStamp = amzDate.slice(0, 8)
+  const scope = `${dateStamp}/${REGION}/${SERVICE}/aws4_request`
+
+  const query: Record<string, string> = {
+    'X-Amz-Algorithm': 'AWS4-HMAC-SHA256',
+    'X-Amz-Credential': `${accessKeyId}/${scope}`,
+    'X-Amz-Date': amzDate,
+    'X-Amz-Expires': String(Math.min(Math.max(expiresInSeconds, 1), 604800)),
+    'X-Amz-SignedHeaders': 'host',
+    ...extraQuery,
+  }
+
+  // SigV4 requires the query sorted by key, with both halves percent-encoded.
+  const canonicalQuery = Object.keys(query)
+    .sort()
+    .map(name => `${encodeURIComponent(name)}=${encodeURIComponent(query[name])}`)
+    .join('&')
+
+  const canonicalRequest = [
+    method,
+    `/${bucket}/${encodeKey(key)}`,
+    canonicalQuery,
+    `host:${url.host}\n`,
+    'host',
+    'UNSIGNED-PAYLOAD',
+  ].join('\n')
+
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    amzDate,
+    scope,
+    sha256(canonicalRequest),
+  ].join('\n')
+
+  const signature = createHmac('sha256', signingKey(secretAccessKey, dateStamp))
+    .update(stringToSign, 'utf8')
+    .digest('hex')
+
+  return `${url.origin}${url.pathname}?${canonicalQuery}&X-Amz-Signature=${signature}`
+}
+
+/** Deletes an object. Used when an upload is abandoned or a share is revoked. */
+export async function deleteObject(key: string): Promise<boolean> {
+  // The method is signed, so the URL must be presigned for DELETE itself.
+  const response = await fetch(presign(key, 'DELETE', 60), { method: 'DELETE' }).catch(() => null)
+  return Boolean(response?.ok)
+}
+
+/**
+ * Whether the object is actually in the bucket. A share row can outlive its object:
+ * an upload that failed after the record was written, or a key removed from the
+ * bucket directly. Without this the recipient is redirected to R2 and reads a raw
+ * NoSuchKey XML document, which tells them nothing and looks broken.
+ */
+export async function objectExists(key: string): Promise<boolean> {
+  // A ranged GET rather than a HEAD: the method is part of the signature, so a
+  // URL signed for GET is refused when sent as HEAD. One byte is enough to tell
+  // a present object (206) from an absent one (404).
+  const response = await fetch(presign(key, 'GET', 60), {
+    headers: { range: 'bytes=0-0' },
+  }).catch(() => null)
+  return response?.status === 206 || response?.status === 200
+}
+
+/** Writes bytes to the bucket. Returns false rather than throwing so one failed file cannot lose a message. */
+export async function putObject(key: string, body: Buffer | Uint8Array, contentType?: string): Promise<boolean> {
+  let reason = ''
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const response = await fetch(presign(key, 'PUT', 900), {
+        method: 'PUT',
+        headers: contentType ? { 'content-type': contentType } : {},
+        body: body as BodyInit,
+      })
+      if (response.ok) return true
+      reason = `HTTP ${response.status}`
+      if (response.status < 500) break
+    } catch (err) {
+      reason = String((err as { cause?: unknown })?.cause ?? err)
+    }
+  }
+  console.warn(`[r2] put failed for ${key}: ${reason}`)
+  return false
+}
+
+/** Streams an object back out, for serving through our own domain instead of a bucket URL. */
+export async function getObject(key: string): Promise<Response | null> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const response = await fetch(presign(key, 'GET', 300))
+      if (response.ok) return response
+      if (response.status < 500) return null
+    } catch (err) {
+      if (attempt) console.warn(`[r2] get failed for ${key}: ${String((err as { cause?: unknown })?.cause ?? err)}`)
+    }
+  }
+  return null
+}

package/lib/rate-limit.ts

@@ -0,0 +1,43 @@
+import { NextResponse } from 'next/server'
+
+type Bucket = { count: number; resetAt: number }
+
+// ponytail: per-instance memory, so a serverless fan-out multiplies the real ceiling by the
+// number of warm lambdas. Enough to stop a single-host credential stuffer; move to Turso or
+// Upstash if the limit ever needs to be exact.
+const buckets = new Map<string, Bucket>()
+
+export function clientKey(req: Request, scope: string): string {
+  const forwarded = req.headers.get('x-forwarded-for') ?? ''
+  const address = forwarded.split(',')[0].trim() || req.headers.get('x-real-ip') || 'unknown'
+  return `${scope}:${address}`
+}
+
+/** Returns a 429 when the caller is over budget, otherwise null. */
+export function rateLimit(key: string, limit: number, windowMs: number): NextResponse | null {
+  const now = Date.now()
+
+  if (buckets.size > 5000) {
+    for (const [entry, bucket] of buckets) if (bucket.resetAt <= now) buckets.delete(entry)
+  }
+
+  const bucket = buckets.get(key)
+  if (!bucket || bucket.resetAt <= now) {
+    buckets.set(key, { count: 1, resetAt: now + windowMs })
+    return null
+  }
+
+  bucket.count += 1
+  if (bucket.count > limit) {
+    const retryAfter = Math.ceil((bucket.resetAt - now) / 1000)
+    return NextResponse.json(
+      { ok: false, error: 'Too many attempts. Try again shortly.' },
+      { status: 429, headers: { 'Retry-After': String(retryAfter) } },
+    )
+  }
+  return null
+}
+
+export function clearRateLimit(key: string): void {
+  buckets.delete(key)
+}

package/lib/session.test.ts

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict'
+import { issueSession, readSession, passwordFingerprint, SESSION_COOKIE } from './session.ts'
+
+const asRequest = (cookie: string) => new Request('https://mail.example.com/', { headers: { cookie } })
+const withToken = (token: string) => asRequest(`${SESSION_COOKIE}=${token}`)
+
+process.env.MAIL_SESSION_SECRET = 'test-secret-value'
+
+const fingerprint = passwordFingerprint('scrypt$16384$abc$def')
+const token = issueSession('Info@Example.com', fingerprint)
+assert.ok(token, 'a secret is configured, so a token is issued')
+
+const session = readSession(withToken(token!))
+assert.equal(session?.email, 'info@example.com', 'the address round-trips, lowercased')
+assert.equal(session?.fingerprint, fingerprint)
+
+// A flipped character in the signature must not verify.
+const tampered = token!.slice(0, -1) + (token!.endsWith('A') ? 'B' : 'A')
+assert.equal(readSession(withToken(tampered)), null, 'a tampered signature is rejected')
+
+// Re-signing a different address with the same length must not verify either.
+const swapped = token!.split('.')
+swapped[0] = Buffer.from('other@mailbox.com').toString('base64url')
+assert.equal(readSession(withToken(swapped.join('.'))), null, 'a swapped payload is rejected')
+
+// An expired token is rejected even though its signature is genuine.
+const expired = (() => {
+  const parts = issueSession('info@example.com', fingerprint)!.split('.')
+  parts[1] = String(Date.now() - 1000)
+  return parts.join('.')
+})()
+assert.equal(readSession(withToken(expired)), null, 'an edited expiry breaks the signature')
+
+// A password change moves the fingerprint, which is what retires old cookies.
+assert.notEqual(passwordFingerprint('scrypt$16384$abc$def'), passwordFingerprint('scrypt$16384$abc$xyz'))
+
+assert.equal(readSession(asRequest('other=1')), null, 'no cookie, no session')
+
+delete process.env.MAIL_SESSION_SECRET
+assert.equal(issueSession('info@example.com', fingerprint), null, 'no secret, no token')
+assert.equal(readSession(withToken(token!)), null, 'no secret, nothing verifies')
+
+console.log('session self-check passed')

package/lib/session.ts

@@ -0,0 +1,80 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import type { NextResponse } from 'next/server'
+
+export const SESSION_COOKIE = 'mp_mail_session'
+
+const MAX_AGE_SECONDS = 14 * 24 * 60 * 60
+
+function secret(): string | null {
+  return process.env.MAIL_SESSION_SECRET?.trim() || null
+}
+
+/**
+ * Binding the token to a digest of the stored password hash is what makes a password
+ * change revoke every session that was issued before it, without keeping a session table.
+ */
+export function passwordFingerprint(passwordHash: string | undefined): string {
+  return createHash('sha256').update(passwordHash ?? '').digest('hex').slice(0, 16)
+}
+
+function sign(payload: string, key: string): string {
+  return createHmac('sha256', key).update(payload).digest('base64url')
+}
+
+export function issueSession(email: string, fingerprint: string): string | null {
+  const key = secret()
+  if (!key) return null
+  const expires = Date.now() + MAX_AGE_SECONDS * 1000
+  const payload = `${Buffer.from(email).toString('base64url')}.${expires}.${fingerprint}`
+  return `${payload}.${sign(payload, key)}`
+}
+
+export function readSession(req: Request): { email: string; fingerprint: string } | null {
+  const key = secret()
+  if (!key) return null
+
+  const cookies = req.headers.get('cookie') ?? ''
+  const raw = cookies
+    .split(';')
+    .map(entry => entry.trim())
+    .find(entry => entry.startsWith(`${SESSION_COOKIE}=`))
+    ?.slice(SESSION_COOKIE.length + 1)
+  if (!raw) return null
+
+  const parts = raw.split('.')
+  if (parts.length !== 4) return null
+  const [encodedEmail, expires, fingerprint, signature] = parts
+
+  const expected = sign(`${encodedEmail}.${expires}.${fingerprint}`, key)
+  if (signature.length !== expected.length) return null
+  try {
+    if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) return null
+  } catch {
+    return null
+  }
+
+  if (!Number(expires) || Number(expires) <= Date.now()) return null
+
+  const email = Buffer.from(encodedEmail, 'base64url').toString('utf8').trim().toLowerCase()
+  if (!email.includes('@')) return null
+  return { email, fingerprint }
+}
+
+export function attachSession(response: NextResponse, token: string | null): NextResponse {
+  if (!token) return response
+  response.cookies.set({
+    name: SESSION_COOKIE,
+    value: token,
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: process.env.NODE_ENV === 'production' || Boolean(process.env.VERCEL),
+    path: '/',
+    maxAge: MAX_AGE_SECONDS,
+  })
+  return response
+}
+
+export function clearSession(response: NextResponse): NextResponse {
+  response.cookies.set({ name: SESSION_COOKIE, value: '', httpOnly: true, path: '/', maxAge: 0 })
+  return response
+}

package/lib/signature.ts

@@ -0,0 +1,28 @@
+import { BRAND, signatureMarkStyle } from './brand'
+
+export type SignatureIdentity = { name: string; email: string; mobile?: string }
+
+export const SIGNATURE_LOGO_URL = BRAND.markUrl
+
+const escape = (value: string) => value.replace(/[&<>"]/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[char] ?? char)
+
+export function signatureLogoHtml(url: string): string {
+  return `<p><img src="${escape(url)}" alt="${escape(BRAND.name)}" width="200" style="${signatureMarkStyle(200)}"></p>`
+}
+
+/** The company signature, personalised. Editable in the signature editor, so plain paragraphs and spans only. */
+export function companySignatureHtml(identity: SignatureIdentity, options: { logo?: boolean } = {}): string {
+  const { accent, link, muted } = BRAND.colors
+  const phones = [BRAND.tel ? `Tel: ${BRAND.tel}` : '', identity.mobile ? `Mobile: ${identity.mobile}` : ''].filter(Boolean).join(', ')
+  const line2 = [BRAND.address, phones].filter(Boolean).join(' | ')
+  return [
+    options.logo ? signatureLogoHtml(SIGNATURE_LOGO_URL) : '',
+    `<p><span style="font-size: 10pt; color: ${accent}"><strong>${escape(identity.name)} | ${escape(BRAND.legalName)}</strong></span></p>`,
+    line2 ? `<p><span style="font-size: 10pt; color: ${accent}">${escape(line2)}</span></p>` : '',
+    `<p><span style="font-size: 8pt; color: ${accent}">Email: <a href="mailto:${escape(identity.email)}"><span style="color: ${link}"><u>${escape(identity.email)}</u></span></a></span></p>`,
+    `<p><span style="font-size: 8pt; color: ${accent}">Website: <a href="${escape(BRAND.websiteUrl)}/"><span style="color: ${link}">${escape(BRAND.website)}</span></a></span></p>`,
+    BRAND.regulatory ? `<p><span style="font-size: 8pt; color: rgb(0, 0, 0)"><strong>${escape(BRAND.regulatory)}</strong></span></p>` : '',
+    '<hr>',
+    `<p><span style="font-size: 8pt; color: ${muted}">${escape(BRAND.disclaimer)}</span></p>`,
+  ].join('')
+}

package/lib/threads.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict'
+import { applyThreadFlagDeltas } from './threads.ts'
+
+type Counts = {
+  threadId: string
+  unreadCount: number
+  starredCount: number
+  inboxCount: number
+  archivedCount: number
+  trashedCount: number
+}
+
+type Message = {
+  id: string
+  threadId: string | null
+  read: boolean
+  starred: boolean
+  archived: boolean
+  trashed: boolean
+}
+
+function thread(over: Partial<Counts> = {}): Counts {
+  return {
+    threadId: 't1',
+    unreadCount: 6,
+    starredCount: 0,
+    inboxCount: 9,
+    archivedCount: 0,
+    trashedCount: 0,
+    ...over,
+  }
+}
+
+function message(id: string, over: Partial<Message> = {}): Message {
+  return {
+    id,
+    threadId: 't1',
+    read: false,
+    starred: false,
+    archived: false,
+    trashed: false,
+    ...over,
+  }
+}
+
+// Opening a conversation marks its unread members read: the row must stop being bold now,
+// not on the next poll ninety seconds later.
+const opened = applyThreadFlagDeltas(
+  [thread()],
+  [message('a'), message('b'), message('c', { read: true })],
+  ['a', 'b', 'c'],
+  { read: true },
+)
+assert.equal(opened[0].unreadCount, 4, 'only the two that were actually unread come off the count')
+
+// Only the loaded members move the figure, and the ones not loaded are not invented: a
+// recount would have reported this nine-message conversation as holding one.
+const partial = applyThreadFlagDeltas([thread()], [message('a')], ['a'], { read: true })
+assert.equal(partial[0].unreadCount, 5)
+assert.equal(partial[0].inboxCount, 9, 'a bucket the change does not touch is left alone')
+
+// Archiving takes the conversation out of the inbox list and into the archive one.
+const archived = applyThreadFlagDeltas([thread({ inboxCount: 1 })], [message('a')], ['a'], { archived: true })
+assert.equal(archived[0].inboxCount, 0)
+assert.equal(archived[0].archivedCount, 1)
+
+// Trashing pulls the message out of unread and starred too, because the server's summary
+// counts both only outside the bin.
+const trashed = applyThreadFlagDeltas(
+  [thread({ unreadCount: 1, starredCount: 1, inboxCount: 1 })],
+  [message('a', { starred: true })],
+  ['a'],
+  { trashed: true },
+)
+assert.deepEqual(
+  {
+    unread: trashed[0].unreadCount,
+    starred: trashed[0].starredCount,
+    inbox: trashed[0].inboxCount,
+    binned: trashed[0].trashedCount,
+  },
+  { unread: 0, starred: 0, inbox: 0, binned: 1 },
+)
+
+// A count can never be talked below zero by a message the summary did not know about.
+const floored = applyThreadFlagDeltas([thread({ unreadCount: 0 })], [message('a')], ['a'], { read: true })
+assert.equal(floored[0].unreadCount, 0)
+
+// Another conversation's message, an unthreaded one, and an id outside the change all
+// leave the row exactly as it was.
+const rows = [thread()]
+assert.equal(applyThreadFlagDeltas(rows, [message('a', { threadId: 't2' })], ['a'], { read: true })[0], rows[0])
+assert.equal(applyThreadFlagDeltas(rows, [message('a', { threadId: null })], ['a'], { read: true })[0], rows[0])
+assert.equal(applyThreadFlagDeltas(rows, [message('b')], ['a'], { read: true })[0], rows[0])
+
+console.log('threads: ok')

package/lib/threads.ts

@@ -0,0 +1,72 @@
+export function normalizeSubject(subject: string): string {
+  return subject
+    .replace(/^\s*((re|fwd?|fw)\s*:\s*)+/i, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase()
+}
+
+export const THREAD_GAP_MS = 30 * 24 * 60 * 60 * 1000
+
+export function subjectKey(subject: string): string {
+  return normalizeSubject(subject)
+}
+
+/** Readable and deterministic: the normalised subject plus the day the thread began. */
+export function threadIdFor(key: string, firstAt: string, messageId: string): string {
+  return key ? `${key}#${firstAt.slice(0, 10)}` : `msg:${messageId}`
+}
+
+export type ThreadFlags = { read?: boolean; starred?: boolean; archived?: boolean; trashed?: boolean }
+
+type FlaggedMessage = { id: string; threadId?: string | null } & Required<ThreadFlags>
+
+type ThreadCounts = {
+  threadId: string
+  unreadCount: number
+  starredCount: number
+  inboxCount: number
+  archivedCount: number
+  trashedCount: number
+}
+
+const bucketsFor = (row: Required<ThreadFlags>) => ({
+  unreadCount: !row.read && !row.trashed ? 1 : 0,
+  starredCount: row.starred && !row.trashed ? 1 : 0,
+  inboxCount: !row.archived && !row.trashed ? 1 : 0,
+  archivedCount: row.archived && !row.trashed ? 1 : 0,
+  trashedCount: row.trashed ? 1 : 0,
+})
+
+const BUCKETS = ['unreadCount', 'starredCount', 'inboxCount', 'archivedCount', 'trashedCount'] as const
+
+export function applyThreadFlagDeltas<Row extends ThreadCounts>(
+  threads: Row[],
+  messages: FlaggedMessage[],
+  ids: string[],
+  flags: ThreadFlags,
+): Row[] {
+  const changing = new Set(ids)
+  const deltas = new Map<string, Record<(typeof BUCKETS)[number], number>>()
+  for (const message of messages) {
+    if (!message.threadId || !changing.has(message.id)) continue
+    const before = bucketsFor(message)
+    const after = bucketsFor({ ...message, ...flags })
+    for (const bucket of BUCKETS) {
+      if (after[bucket] === before[bucket]) continue
+      const entry =
+        deltas.get(message.threadId) ??
+        { unreadCount: 0, starredCount: 0, inboxCount: 0, archivedCount: 0, trashedCount: 0 }
+      entry[bucket] += after[bucket] - before[bucket]
+      deltas.set(message.threadId, entry)
+    }
+  }
+  if (deltas.size === 0) return threads
+  return threads.map(thread => {
+    const delta = deltas.get(thread.threadId)
+    if (!delta) return thread
+    const next = { ...thread }
+    for (const bucket of BUCKETS) next[bucket] = Math.max(0, thread[bucket] + delta[bucket])
+    return next
+  })
+}