From a7297cf2d03b5cfd6f18b00b81b23317f934ff46 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 11:27:19 +0000 Subject: [PATCH 1/4] feat(sources): Gmail and Google Workspace as an email sensor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q --- CHANGELOG.md | 6 + README.md | 11 +- docs/activity.md | 3 +- docs/authentication.md | 3 + docs/processing.md | 42 ++- docs/sensors.md | 2 +- fastapi_backend/app/api/v1/routes/external.py | 29 +- fastapi_backend/app/api/v1/routes/sources.py | 30 +- fastapi_backend/app/domain/external_login.py | 13 +- fastapi_backend/app/domain/feeds.py | 118 ++++++- fastapi_backend/app/domain/gmail.py | 325 ++++++++++++++++++ fastapi_backend/app/domain/google_auth.py | 280 +++++++++++++++ fastapi_backend/app/domain/sources.py | 50 ++- fastapi_backend/app/schemas/sources.py | 10 +- .../tests/api/test_gmail_source.py | 273 +++++++++++++++ fastapi_backend/tests/fake_google.py | 219 ++++++++++++ fastapi_backend/tests/fake_imap.py | 18 +- nextjs-frontend/app/openapi-client/index.ts | 5 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 19 + .../app/openapi-client/types.gen.ts | 36 +- .../components/library/source-labels.ts | 1 + .../components/library/sources-strip.tsx | 1 + .../components/sources/source-icons.tsx | 1 + .../components/sources/source-model.ts | 4 + .../components/sources/watch-editor.tsx | 2 +- .../components/storage/file-store.ts | 2 +- nextjs-frontend/openapi.json | 47 ++- threat-model.json | 18 +- threat-model.md | 5 +- threat-model.yaml | 15 +- 30 files changed, 1512 insertions(+), 76 deletions(-) create mode 100644 fastapi_backend/app/domain/gmail.py create mode 100644 fastapi_backend/app/domain/google_auth.py create mode 100644 fastapi_backend/tests/api/test_gmail_source.py create mode 100644 fastapi_backend/tests/fake_google.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d7513f7c..60a63441a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **Gmail and Google Workspace as a sensor.** A new kind of email source reads a Gmail or Google Workspace mailbox + through Google's Gmail API (read only) or over IMAP. It signs in with Google as a person, through the Google client + already set up for signing in to Lens, or as a Workspace service account with domain-wide delegation, so nobody has + to sign in. Labels are its folders, and a watch follows Gmail's history: it reads only what arrived, and one that + leaves what's there reads nothing old. The connection dialog's Gmail option is in progress; until it lands, add one + through the API ([Gmail and Google Workspace](docs/processing.md#gmail-and-google-workspace)). - **The assistant always answers.** When a question used up its tool steps (`ai.max_steps`), the assistant used to stop with "I ran out of steps before finishing". Now it's asked to answer from what it found, with the tools off, and says what it didn't get to check; a reply with nothing in it is asked again the same way. It also knows its step budget up diff --git a/README.md b/README.md index a1c189969..0438ea585 100644 --- a/README.md +++ b/README.md @@ -80,11 +80,12 @@ Everything below is built and merged. Work that is still in a pull request is li ([Extending the assistant](docs/assistant.md#extending-the-assistant-tools-skills-hooks-and-plugins), [the MCP runner](docs/assistant.md#the-mcp-runner)) - **Bring in everything.** Watched folders on S3, Dropbox, Google Drive, OneDrive, SFTP, SMB, WebDAV or local disks - (a local folder in four clicks); IMAP mail and iCal calendars; a built-in MQTT broker, syslog and webhook streams; - import webhooks for scanners and phone shortcuts. Upload audio, video, PDFs, Office files, photos, JSON and zip or - tar archives, and, with an Apache Tika server (an opt-in extra), documents nothing else here can read; capture web - pages one at a time, from a link list or a bookmarks file, by API or by asking the assistant, from private networks - you allow in Settings too; and import videos and podcasts by their address (off by default). + (a local folder in four clicks); IMAP mail, Gmail and Google Workspace, and iCal calendars; a built-in MQTT broker, + syslog and webhook streams; import webhooks for scanners and phone shortcuts. Upload audio, video, PDFs, Office + files, photos, JSON and zip or tar archives, and, with an Apache Tika server (an opt-in extra), documents nothing + else here can read; capture web pages one at a time, from a link list or a bookmarks file, by API or by asking the + assistant, from private networks you allow in Settings too; and import videos and podcasts by their address (off by + default). ([Sensors](docs/sensors.md), [processing](docs/processing.md), [Apache Tika](docs/configuration.md#apache-tika), [import webhooks](docs/api.md#import-webhooks)) - **Clip from the browser.** The Lens web clipper for Chrome, Edge, Firefox and Safari turns a page, a selection or a diff --git a/docs/activity.md b/docs/activity.md index 2aece1914..bb8a3eec6 100644 --- a/docs/activity.md +++ b/docs/activity.md @@ -22,7 +22,8 @@ its namespace, its pipeline and the routine. A request counts for the resources /api/v1/routines/3` is `routine:3`), for what a `POST` made (from the `id` in its reply), and for who sent it. Besides the resources, a row has its kind (`in`, `out` or `run`), what it was (`POST /api/v1/routines/{rid}`, -`model.chat`, `embeddings`, `decision`, `notify.webhook`, `tool.http`, `job.succeeded`, `routine.done`), the model, +`model.chat`, `embeddings`, `decision`, `notify.webhook`, `tool.http`, `google.token`, `gmail.list`, `job.succeeded`, +`routine.done`), the model, tokens in and out, the estimated cost in USD, how long it took, and how it ended (an error's type or HTTP status, never its message). It never holds prompt, reply, transcript or file content. diff --git a/docs/authentication.md b/docs/authentication.md index f9de67554..936df9b8a 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -75,6 +75,9 @@ has a "Continue with ..." button for each provider that's turned on. accounts have no password and no roles until someone adds them. * **Profile and sign-in › Connected accounts** connects one while signed in and disconnects one (not your only way in: with no passkey and no password it stays). With a connected account, your last passkey can go. +* **Gmail sources sign in with it too.** The Google provider's client also signs Gmail and Google Workspace sources in + to Google ([Gmail and Google Workspace](processing.md#gmail-and-google-workspace)), through the same redirect URI, + so nothing else is registered at Google; it works for that while signing in to Lens with Google is turned off. * **How it's checked.** The code flow with PKCE, a `state` used once within ten minutes, and a cookie set on the browser that started it, so a sign-in someone else started can't be finished in your browser. The code is swapped for the profile at the provider's token and userinfo endpoints (server to server). The callback ends on the web diff --git a/docs/processing.md b/docs/processing.md index adbfa7260..af84b4758 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -289,7 +289,7 @@ A folder scan and a routine run are each claimed first, so several processes doi ## Storage sources Admins add sources in the app (`/api/v1/sources`): S3 or S3-compatible, Dropbox, Google Drive, OneDrive, SFTP, SMB, -WebDAV, or a folder on this machine; or an email account (IMAP) or a calendar feed (iCal), below. A watched folder maps a path on a source to a namespace, with include/exclude +WebDAV, or a folder on this machine; or an email account (IMAP, or Gmail and Google Workspace) or a calendar feed (iCal), below. A watched folder maps a path on a source to a namespace, with include/exclude patterns, audio and/or transcripts, a polling interval, how long a file must be unchanged before it is picked up, and whether files already there are imported (backfill). New audio is queued for the full pipeline; new transcripts are imported and analysed. Audio stays where it is: it is copied to a cache for processing and streamed from the source for @@ -335,6 +335,7 @@ importing chosen ones and watching work as above. exists (rules never create one); mail for a namespace deleted since goes to the watch's. Rules apply to messages that arrive after they're saved. `POST /api/v1/watches/routes/preview` shows where the latest messages would go before saving, and a scan's stats count the messages `routed` elsewhere. +- **Gmail and Google Workspace**: see [below](#gmail-and-google-workspace). - **Calendar feed (iCal)**: the calendar's iCal address (`https://` or `webcal://`; a user and password if it asks for one). The address is kept encrypted like a password and never shown again, since a private calendar's address is all it takes to read it. It is fetched the way web pages are captured: public addresses only (and the networks in @@ -346,6 +347,45 @@ importing chosen ones and watching work as above. or its size) is read again into the resource it already is, rather than made a second one. - `.eml` and `.ics` files in any source, and uploaded through Import, can be read as text this way too. +### Gmail and Google Workspace + +A Gmail or Google Workspace mailbox (type `gmail`) is read through Google's Gmail API, read only (`gmail.readonly`), +or over IMAP (`via: imap`). For a personal Gmail account, an email (IMAP) connection with an app password works too, +with nothing to set up at Google. A Gmail source signs in one of two ways: + +- **Sign in with Google.** **Sign in with Google** on the connection sends you to Google, which asks you to let Lens + read your mail, then brings you back to the sensor's page (`POST /api/v1/sources/{id}/google` starts it, from a + signed-in browser). Lens keeps the refresh token Google gives, encrypted like a password, and the address you signed + in with. It uses the Google client set up for signing in to Lens (Settings › Sign-in, its client id and secret, and + its redirect URI; signing in to Lens with Google can stay off), so nothing else is registered at Google. In Google + Cloud, turn on the Gmail API in that client's project and add the Gmail scope to its consent screen. Google reviews + apps that read Gmail before people outside your Workspace domain can use them without a warning: an app in testing + works for its test users, whose sign-ins Google ends after seven days (sign in again), and an unreviewed app in + production shows a warning page people can click through. Unticking the mail permission on Google's page leaves the + source unconnected, and says so. +- **A service account** (Google Workspace). Upload the service account's JSON key and enter the address of the person + whose mail Lens reads; nobody signs in. A Workspace admin lets the account's client id use + `https://www.googleapis.com/auth/gmail.readonly` (or `https://mail.google.com/` to read over IMAP) under Admin + console › Security › API controls › Domain-wide delegation. One source reads one person's mailbox. +- An agent can give a source a token it already has instead: the `token` secret as JSON with `refresh_token`, + `client_id` and `client_secret`. + +Labels are the folders: the inbox, sent, starred, important, the inbox's categories (Primary, Social, Promotions, +Updates, Forums) and your own labels. A message is a file `