Repository navigation
feat(email): connect a Gmail mailbox on the tenant's own Google app (EA-2) - #636
Open
privatejoel wants to merge 1 commit into
Open
privatejoel wants to merge 1 commit into
privatejoel wants to merge 1 commit into
Conversation
…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]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Oct 23, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:gmail.readonlyonly.gmail.metadatais narrower, but it is also a restricted scope and it cannot useq. With the same review burden, the narrower scope gives no benefit.format=metadatawith 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.historyIdfromprofilefirst, then listsafter:<since> (in:inbox OR in:sent). A message that arrives during the list is found by the next history read.history.listwithhistoryTypes=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.historyIdthat is too old (404) is a checkpoint error. The runner clears it and lists again, from 1 hour before the last success.rateLimitExceededor a 429 is a throttle. A 403dailyLimitExceededorquotaExceededis a quota error: the mailbox pauses until 00:00 UTC and the admin gets an alert. Any other 403 is an access problem and givesreauth_required./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.jsregistersgmail.GET /api/email/connectionsnow reportsproviders: { 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
https://www.googleapis.com/auth/gmail.readonly.{PUBLIC_APP_URL}/api/email/connect/callback.PUT /api/email/google_app { client_id, client_secret }.@gmail.comaccounts 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.historyIdbefore the list, uses a boundedq, reads metadata only, and saves{ historyId }.Dateand frominternalDate.historyIdforward.historyId: it is cleared. The next run lists again from 1 hour before the last success.profileagain.reauth_required, no mail is read, and the alert does not contain the provider text.userRateLimitExceededis retried 2 times, then the mailbox pauses.dailyLimitExceededpauses the mailbox until 00:00 UTC without a retry, and sends an alert.gmail.readonly, offline access and consent. The callback stores the mailbox with the address fromprofile.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.jsnow expectsgmail: falsein 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
historyIdis 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;profileis read on every list page; the first sync is not bounded; the Google secret is stored in plaintext;google_appis 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 rewrotedocs/RBAC_AUDIT.mdanddocs/WRITE_PATH_AUDIT.mdwith 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.main, so this stacked PR gets no CI run until its base changes tomain.Not covered
#all/<id>) is not documented by Google.@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.hasAttachmentscomes frommultipart/mixed, because the metadata format has no list of parts. EA-5 treats a false negative as ambiguous, never as verified.🤖 Generated with Claude Code