Gmail: setup guide, honest reconnect status, key-clobber fix, labels API

[hilash]

What

Four related Gmail improvements, born from a real break: Mailroom fell back to demo mode because the stored App Password could no longer be decrypted, while Integrations still said "Connected".

1. Root cause + fix: encryption-key clobbering

The stored App Password is AES-256-GCM encrypted under a per-install secret in .cabinet.env. getKeySecret() generated-and-persisted a fresh secret whenever a process booted without it in process.env — so a sibling process (Next app vs daemon vs a Turbopack dev worker) could overwrite the persisted secret and orphan every stored password. Confirmed by decrypting the live DB row offline: no available key matched.

Fix: the on-disk secret is now the durable source of truth — encryption prefers it over process.env, and after generating a fresh secret we re-read the file to adopt a concurrent sibling's write. Decrypt already tries env + file + legacy keys, so user-set env overrides still work. Co-located crypto.test.ts (node:test) covers round-trip, fresh-IV, and tamper rejection.

2. /api/gmail/status no longer lies

It only checked that a credentials row existed, so it reported connected: true while every real call 500'd. It now attempts decryption and returns needsReconnect: true; the Integrations panel shows an amber "Reconnect needed" banner with the saved email pre-filled.

3. Setup guide with mockups

Integrations → Gmail now has a Telegram/Slack-style numbered setup guide for Google's 2-Step Verification → App passwords flow, drawn as stylized theme-aware mockups (GmailArt, shared setup-art primitives — no screenshots, no personal data). Brand color switched from Gmail red (read as a danger button) to Google blue. /api/gmail/connect now strips whitespace from pasted App Passwords (Google displays them as xxxx xxxx xxxx xxxx; a verbatim paste failed IMAP auth).

4. Gmail labels API

GET/POST /api/gmail/labels and POST /api/gmail/label (apply = IMAP copy into the label's mailbox; message stays in inbox), with label-name validation at the trust boundary. Powers the Mailroom label controls.

Verification

• npx tsc --noEmit clean; npm run lint 0 errors
• npx tsx --test src/lib/gmail/crypto.test.ts — 3/3 pass
• Live: GET /api/gmail/status on the affected install now returns {"connected":false,"needsReconnect":true,...} for the orphaned credential
• Labels routes live-tested (validation errors pre-IMAP; full apply pending reconnect)

🤖 Generated with Claude Code