Skip to content

feat(sources): Connect with Google for Google Calendar connections - #407

Merged
adeelahmad merged 11 commits into
mainfrom
claude/project-thread-4kmlnn
Oct 15, 2026
Merged

adeelahmad merged 11 commits into
mainfrom
claude/project-thread-4kmlnn

Conversation

@adeelahmad

@adeelahmad adeelahmad commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Description

Before: a Google Calendar connection could sign in as a Google account only by pasting an OAuth client's authorized user JSON made with gcloud.

After: the Google account option has a Connect with Google button. It saves the connection (creating it first if it is new) and opens Google's consent screen for read-only calendar access. Google then sends the browser back to Sources, where the account is connected, its address shows on the connection ("as mara@…"), and its calendars open so you can pick one to watch. If connecting fails, a red toast appears and the connection opens again.

The OAuth client is the Google sign-in provider's (Settings › Sign-in) when there is one, otherwise an earlier Google connection's. If there is neither, the form asks for a client ID and secret and shows the redirect URI to register, the same address Google sign-in uses. A connection whose Google sign-in stopped working shows Connect Google account on its row, which goes straight to Google. Pasting the JSON still works, folded under "Or paste an authorized user JSON".

How:

  • Flow: reuses external sign-in's flow table, cookie and callback (/api/v1/auth/external/google/callback) with mode: source. google_auth.connect_start / connect_finish do PKCE S256, access_type=offline and prompt=consent.
  • Saving the account: the refresh token is kept only when the read-only scope was granted. The account's email comes from the id token, straight from Google's token endpoint.
  • Routes:
    • GET /api/v1/sources/google-client says which client would be used and gives the redirect URI.
    • POST /api/v1/sources/{id}/google (optional body: client ID and secret) returns the consent address.
      • It works from the web app only: API tokens get a 403, because the consent comes back to the browser that asked. An agent instead saves an authorized user JSON it already has as token.
      • The callback re-checks that whoever started the flow is still an admin. Each connection is audited as source.google_connect.
  • One flow for every Google source: the Gmail (feat(sources): Gmail and Google Workspace as an email sensor #405) and Drive threads agreed to build on this flow instead of their own. A type joins with its module's SCOPES (a tuple, or SCOPES(params)) and ACCOUNT, the parameter that records the address (default account).

Motivation and Context

Adeel asked for Google Calendar as a sensor, by OAuth and by service account. #399 shipped both sign-ins; this PR turns the OAuth one into a button instead of a gcloud command.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (ruff, prettier, eslint, mypy, tsc clean).
  • I added or updated tests:
    • test_connecting_a_google_account_in_the_browser runs against the fake Google's consent and code exchange, including the API-token 403 and the admin re-check.
    • test_scopes_by_type.
    • __tests__/add-connection.test.tsx "connecting a Google account".
    • __tests__/sources-model.test.ts.
  • My change requires documentation updates, and I have updated docs/ accordingly (docs/processing.md, docs/authentication.md).
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: Google Calendar by OAuth is now one click. Merging on green.
  • Agents: an agent creates and edits the source and saves an authorized user JSON as token through the API. The consent step itself has to be a person's in a browser, so the route refuses API tokens and says why.
  • Zero setup: nothing to install. When Google sign-in is set up, there is nothing to enter at all.
  • Fewest clicks: one click to Google and one Allow there; the calendars open on return.
  • Configurable: the client comes from Settings › Sign-in or from the form. Nothing was added to the setup wizard.
  • Light: a few HTTPS calls.
  • Private and secure:
    • Admin only, re-checked on return.
    • Single-use hashed state bound to the browser, plus PKCE.
    • The client secret and the refresh token are sealed.
    • Read-only scope.
    • The threat model has a "Connect with Google" entry.
  • Cost: no model calls. The code exchange is a google.token row in the activity ledger.
  • User decides: nothing connects until an admin clicks and consents. Defaults are unchanged.
  • Upgrades: n/a. No change to the shape of stored data; the new account parameter defaults to empty.
  • Honest: the docs say which client is used, and that Google ends tokens after 7 days while the consent screen is in Testing.
  • Tested and documented: tests, docs and generated files are updated (make openapi).
  • Open: OAuth 2.0, PKCE, OpenID Connect id token.
  • Reported: the result is reported with evidence. Refine later: after consent, rename a new connection to include the account ("Google Calendar · mara@…").

🤖 Generated with Claude Code

https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64


Generated by Claude Code

A Google Calendar connection signs in to a Google account from a button:
Lens saves the connection, opens Google's consent screen for read-only
calendar access, and Google sends the browser back to Sources with the
account connected and its calendars open. The OAuth client is the Google
sign-in provider's, an earlier connection's, or one entered in the form,
which shows the redirect URI to register. A connection whose sign-in
stopped working gets "Connect Google account" on its row.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
…urces/{id}/google

Matches the Gmail source's route and rules so both types share one flow:
API tokens are refused (the consent comes back to the browser that
asked), the admin who started it must still be one when Google sends
them back, a type's SCOPES can depend on its settings, and a type names
the parameter that records the connected account (ACCOUNT).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
The journey failed now and then (on main too) with a 20 s timeout: an entity
is in the graph once something links it twice, which takes import-file's
episode as well, and a slow runner can still be reading it. The same wait as
in #396, not counted.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RrY2byt5BHVeBXJUyfwWpb

Copy link
Copy Markdown
Owner Author

Clicks and keystrokes per feature failed on graph-merge with a 20 s locator timeout. This PR doesn't touch the graph, and the same check is red on main's last push (run 38727734860).

I ported the fix from #397 (test(clicks): graph-merge waits for the imports' jobs to finish) as 6b5fa11. Once #397 merges, that commit changes nothing.


Generated by Claude Code

@adeelahmad
adeelahmad marked this pull request as draft October 15, 2026 11:52
@adeelahmad
adeelahmad marked this pull request as ready for review October 15, 2026 11:57
adeelahmad pushed a commit that referenced this pull request Oct 15, 2026
… its own

Calendar's Connect with Google (#407) brings the browser consent for Google
sources; Gmail joins it in the next pull request. This one keeps the source:
a connected account's token, or a Workspace service account, read through
the Gmail API or over IMAP. The wording says to connect the Google account
again, as Calendar's does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
adeelahmad added a commit that referenced this pull request Oct 15, 2026
* feat(sources): Gmail and Google Workspace as an email sensor

A new "gmail" source reads a Gmail or Google Workspace mailbox, by the
Gmail API (read only) or by IMAP with XOAUTH2. It signs in as a person
with the Google client from Settings › Sign-in (OAuth, refresh token
sealed on the source), or as a Workspace service account with
domain-wide delegation. Watches follow Gmail's history ids, so a first
scan of a big mailbox reads nothing and later scans read only new mail.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

* fix(sources): bring Google sign-in back to Sources

Sources live at /sources; /sensors/{id} is a different thing with its own
ids, so a Gmail source signed in there landed on the wrong page.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

* test(clicks): graph-merge waits for the imports' jobs to finish

Ported from #397: the journey fails now and then on main too with a 20 s
timeout while a slow runner is still reading import-file's episode.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

* refactor(sources): Gmail signs in through the shared Google flow, not its own

Calendar's Connect with Google (#407) brings the browser consent for Google
sources; Gmail joins it in the next pull request. This one keeps the source:
a connected account's token, or a Workspace service account, read through
the Gmail API or over IMAP. The wording says to connect the Google account
again, as Calendar's does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

---------

Co-authored-by: Adeel Ahmad <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGVfwJfXV4MiUhSyusia64
@adeelahmad
adeelahmad merged commit 2ce02f8 into main Oct 15, 2026
11 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-4kmlnn branch October 15, 2026 14:25
adeelahmad added a commit that referenced this pull request Oct 15, 2026
… with Google (#420)

* feat(sources): connect Gmail from the connection dialog, with Connect with Google

Add connection › Gmail connects the account through the same consent flow
as Google Calendar (#407): Google asks to read mail (all of Gmail for
IMAP), the account's address becomes the source's user, and its labels
open. A Workspace service account takes its key and the address it acts
for, and says which client id and scope an admin must allow. A Gmail row
whose sign-in stopped working offers Connect Google account.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

* chore(api): regenerate the OpenAPI client for the Google connect route's wording

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q

---------

Co-authored-by: Adeel Ahmad <noreply@anthropic.com>
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.

2 participants