Modernize email: Gmail OAuth2 sending, configured under Settings

Retire env-var SMTP basic-auth and send the contact form through Gmail over
OAuth2 (SMTP XOAUTH2), configured in Admin -> Settings -> Email via an in-app
"Connect Gmail" consent flow. Reuses the existing google SSO OAuth client; the
captured refresh token is stored AES-GCM-encrypted (write-only over the API,
never returned), mirroring the auth-provider and Discord-bot secret patterns.

- schema: new email_config singleton table (mirrors bot_config)
- model: emailConfig.{db,model} with encrypted refresh token + getSafe/getWithSecret
- mailer: nodemailer OAuth2 transport (client id/secret from the google provider
  row), contact recipient = contact_email setting, mailto: fallback preserved,
  plus sendTest()
- routes/controller: /admin/email config, connect start+callback (ssoState CSRF
  + PKCE), test, disconnect
- client: EmailDelivery section on the Settings page + api methods; Settings copy
  now spells out that contact_email is the delivery recipient
- docs/env: drop SMTP_*/CONTACT_TO from env examples; update README/BACKEND_DESIGN
- tests: emailConfig.model + mailer suites (8 new; full suite 142 pass)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XKeCQEJZr1AFJN4Bgcmvh3

server/src/model/emailConfig/emailConfig.db.js

@@ -0,0 +1,28 @@
+const { query } = require('../../utils/db')
+
+const COLS =
+  'id, provider, enabled, sender_email, sender_name, refresh_token_enc, status, status_detail, last_verified_at, updated_by, created_at, updated_at'
+
+// Singleton row (id = 1). Returns null until the admin connects Gmail for the first time.
+async function get() {
+  const rows = await query(`SELECT ${COLS} FROM email_config WHERE id = 1 LIMIT 1`)
+  return rows[0] || null
+}
+
+// Upsert the singleton row. `fields` are column values already prepared by the
+// model (refresh token pre-encrypted). Only the provided columns are written/updated.
+async function upsert(fields) {
+  const cols = Object.keys(fields)
+  const vals = cols.map((c) => fields[c])
+  const insertCols = ['id', ...cols].map((c) => `\`${c}\``).join(', ')
+  const placeholders = ['1', ...cols.map(() => '?')].join(', ')
+  const updates = cols.map((c) => `\`${c}\` = VALUES(\`${c}\`)`).join(', ')
+  await query(
+    `INSERT INTO email_config (${insertCols}) VALUES (${placeholders})
+     ON DUPLICATE KEY UPDATE ${updates}`,
+    vals,
+  )
+  return get()
+}
+
+module.exports = { get, upsert }

server/src/model/emailConfig/emailConfig.model.js

@@ -0,0 +1,92 @@
+// Outbound email config store (Gmail OAuth2). Mirrors the botConfig model split:
+// the DB layer only ever sees ciphertext, and only getWithSecret() (used by the
+// mailer at send time) decrypts the refresh token. The admin-facing getSafe()
+// never includes it — callers see only `hasRefreshToken`.
+
+const db = require('./emailConfig.db')
+const secretBox = require('../../utils/secretBox')
+
+function toSafe(row) {
+  if (!row) {
+    return {
+      provider: 'gmail_oauth2',
+      enabled: false,
+      senderEmail: null,
+      senderName: null,
+      hasRefreshToken: false,
+      status: 'unconfigured',
+      statusDetail: null,
+      lastVerifiedAt: null,
+    }
+  }
+  return {
+    provider: row.provider || 'gmail_oauth2',
+    enabled: Boolean(row.enabled),
+    senderEmail: row.sender_email || null,
+    senderName: row.sender_name || null,
+    hasRefreshToken: Boolean(row.refresh_token_enc),
+    status: row.status || 'unconfigured',
+    statusDetail: row.status_detail || null,
+    lastVerifiedAt: row.last_verified_at || null,
+  }
+}
+
+async function getSafe() {
+  return toSafe(await db.get())
+}
+
+// Decrypted refresh token included — server-side only (building the mailer's
+// OAuth2 transport). Returns null when no row exists yet.
+async function getWithSecret() {
+  const row = await db.get()
+  if (!row) return null
+  return {
+    ...toSafe(row),
+    refreshToken: row.refresh_token_enc ? secretBox.decrypt(row.refresh_token_enc) : null,
+  }
+}
+
+// Save admin-supplied / connect-flow config. `refreshToken` undefined or '' means
+// "leave the existing token unchanged" (same convention as botConfig.save).
+async function save({ senderEmail, senderName, refreshToken, enabled, status, statusDetail, updatedBy }) {
+  const fields = {}
+  if (senderEmail !== undefined) fields.sender_email = senderEmail
+  if (senderName !== undefined) fields.sender_name = senderName
+  if (refreshToken) fields.refresh_token_enc = secretBox.encrypt(refreshToken)
+  if (enabled !== undefined) fields.enabled = enabled ? 1 : 0
+  if (status !== undefined) fields.status = status
+  if (statusDetail !== undefined) fields.status_detail = statusDetail
+  if (updatedBy !== undefined) fields.updated_by = updatedBy
+  const row = await db.upsert(fields)
+  return toSafe(row)
+}
+
+// Clear the stored credential and disable sending (admin "Disconnect").
+async function disconnect(updatedBy) {
+  const row = await db.upsert({
+    refresh_token_enc: null,
+    sender_email: null,
+    enabled: 0,
+    status: 'unconfigured',
+    status_detail: null,
+    last_verified_at: null,
+    updated_by: updatedBy ?? null,
+  })
+  return toSafe(row)
+}
+
+// Record the outcome of the last send / verification so the admin panel has
+// something to show. `lastVerifiedAt` may arrive as a Date or ISO string.
+async function recordStatus({ status, statusDetail, lastVerifiedAt } = {}) {
+  const fields = {}
+  if (status !== undefined) fields.status = status
+  if (statusDetail !== undefined) fields.status_detail = statusDetail ? String(statusDetail).slice(0, 500) : null
+  if (lastVerifiedAt !== undefined) {
+    fields.last_verified_at = lastVerifiedAt ? new Date(lastVerifiedAt) : null
+  }
+  if (Object.keys(fields).length === 0) return getSafe()
+  const row = await db.upsert(fields)
+  return toSafe(row)
+}
+
+module.exports = { getSafe, getWithSecret, save, disconnect, recordStatus }