Skip to content

feat(email): connect a Gmail mailbox on the tenant's own Google app (EA-2) - #636

Open
privatejoel wants to merge 1 commit into
claude/email-ea1-outlook-syncfrom
claude/email-ea2-gmail
Open

privatejoel wants to merge 1 commit into
claude/email-ea1-outlook-syncfrom
claude/email-ea2-gmail

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

EA-2 of the email accountability plan (#634, section 5.2). A user can connect a Gmail mailbox. The adapter has the same interface as Outlook, so the runner, the budget, the retries and the alerts of EA-1 apply without a change.

Stacked on #635 (EA-1), which is stacked on #619. Merge in this order: #619, #635, this PR.

  • _lib/mail/gmail.js:
    • Scope: gmail.readonly only. gmail.metadata is narrower, but it is also a restricted scope and it cannot use q. With the same review burden, the narrower scope gives no benefit.
    • Every message read uses format=metadata with a fixed list of headers: Message-ID, In-Reply-To, References, From, To, Cc, Subject, Date, Auto-Submitted, List-Unsubscribe and Precedence. No body is read.
    • First sync: the adapter reads the historyId from profile first, then lists after:<since> (in:inbox OR in:sent). A message that arrives during the list is found by the next history read.
    • Later syncs: history.list with historyTypes=messageAdded. The adapter reads only messages that have the INBOX or SENT label, so it does not spend requests on drafts, spam or chats. One checkpoint ({ historyId }) covers both directions.
    • A historyId that is too old (404) is a checkpoint error. The runner clears it and lists again, from 1 hour before the last success.
    • A message that is deleted between the history read and the message read (404) is skipped. It is not a failure.
    • A 403 rateLimitExceeded or a 429 is a throttle. A 403 dailyLimitExceeded or quotaExceeded is a quota error: the mailbox pauses until 00:00 UTC and the admin gets an alert. Any other 403 is an access problem and gives reauth_required.
    • Google does not rotate the refresh token, so the stored refresh token stays.
    • The page size is 20, because each message is one request. A page then fits inside one tick.
  • /api/email/google_app (admin only) stores the tenant's own Google OAuth client. The secret is encrypted. GET never returns the secret. The client must be an Internal app in the customer's Google Workspace (decision ED-3). Google then needs no app verification and no CASA assessment.
  • adapters.js registers gmail. GET /api/email/connections now reports providers: { outlook, gmail }.

No migration: migration 267 (EA-1) already has the two google_oauth_* columns. No new npm package. The Gmail API has no charge inside its quota.

Deploy notes

  1. Merge fix(secrets): own IV per stored credential, no plaintext fallback, https Tally bridge #619 and feat(email): connect a user's Outlook mailbox and poll Inbox and Sent (EA-1) #635 first, and apply migration 267.
  2. For each customer that uses Gmail, a Workspace admin does these steps in the Google Cloud console of that Workspace:
    1. Create a project.
    2. Enable the Gmail API.
    3. On the OAuth consent screen, set the user type to Internal.
    4. Add the scope https://www.googleapis.com/auth/gmail.readonly.
    5. Create an OAuth client of type Web application, with the redirect URI {PUBLIC_APP_URL}/api/email/connect/callback.
  3. An Anvil admin stores that client with PUT /api/email/google_app { client_id, client_secret }.
  4. Consumer @gmail.com accounts are not supported. An External app in Testing status gets refresh tokens that expire after 7 days. A published External app needs Google verification and a yearly CASA assessment, which costs money.

Tests

src/v3-app/api-mail-gmail-sync.test.js (15 tests). Gmail and the token endpoint are mocked, and no live credential is used.

  • First sync: the adapter reads historyId before the list, uses a bounded q, reads metadata only, and saves { historyId }.
  • Normalise: the test checks the headers, the labels, the decoded snippet, and the times from Date and from internalDate.
  • History: the adapter reads only INBOX and SENT messages, reads a message that appears in two records once, and moves historyId forward.
  • Deleted message: a message deleted after the history read is skipped, and the run does not fail.
  • [13] Invalid historyId: it is cleared. The next run lists again from 1 hour before the last success.
  • [13] Long first list: the list continues on the next page and does not read profile again.
  • [14] Refresh: the adapter refreshes through Google's token endpoint and keeps the refresh token that Google did not rotate.
  • [14] Revoked grant: the mailbox goes to reauth_required, no mail is read, and the alert does not contain the provider text.
  • [14] Other 403: a 403 for missing permissions is an access problem.
  • [16] Rate limit: userRateLimitExceeded is retried 2 times, then the mailbox pauses.
  • [17] Quota: dailyLimitExceeded pauses the mailbox until 00:00 UTC without a retry, and sends an alert.
  • [17] Budget: the budget stops the run inside a page, and the checkpoint of that page does not move.
  • Connect: the authorize URL asks only for gmail.readonly, offline access and consent. The callback stores the mailbox with the address from profile.
  • google_app: only an admin can use it, the client ID format is checked, the secret is stored encrypted and is never returned, and the change is audited.

api-email-connections.test.js now expects gmail: false in the provider list.

Mutation check: I broke each rule, ran the three mail test files, and saw a failure. Then I restored the code. All 14 mutations failed the tests: history fetches every label; full format; a deleted message is a failure; the historyId is not kept after the list; quota treated as a throttle; any other 403 treated as a throttle; no consent prompt; a wider scope; the unrotated refresh token is dropped; profile is read on every list page; the first sync is not bounded; the Google secret is stored in plaintext; google_app is open to non-admins; the SENT label is ignored for the direction.

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors. The new files add no warnings.
  • npm run build: pass.
  • npm run verify: pass. It rewrote docs/RBAC_AUDIT.md and docs/WRITE_PATH_AUDIT.md with changes that are not from this PR, so I restored them.
  • npm run eval:golden: pass.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 627 files, 7,499 tests, all pass.
  • GitHub CI runs only on PRs into main, so this stacked PR gets no CI run until its base changes to main.

Not covered

  • Not tested on a live Gmail mailbox. The URL of the Gmail web link (#all/<id>) is not documented by Google.
  • shortcut: the address parser takes each token that contains @ in a header. A display name that contains @ would add a false address. Upgrade to an RFC 5322 parser if a real header shows this problem.
  • shortcut: hasAttachments comes from multipart/mixed, because the metadata format has no list of parts. EA-5 treats a false negative as ambiguous, never as verified.
  • shortcut: messages are read one at a time, with no multipart batch endpoint. A page is 20 messages.
  • No UI for the Google client or for the connect button. EA-7 adds them.

🤖 Generated with Claude Code

…EA-2)

Gmail adapter on the same interface as Outlook: gmail.readonly only,
format=metadata, one historyId checkpoint for Inbox and Sent, a bounded
first list read after the historyId, a deleted message skipped, and 403
reasons mapped to throttle, quota or access. Admin endpoint for the
tenant's Internal Google OAuth client (secret encrypted).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 22, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 22, 2026 3:09am UTC

This branch was successfully deployed

1 active deployment
Preview — af5fc3ea Deployed Oct 22, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant