import imap: Gmail as a Workspace service account (--google-key) #45

Merged
jcoffey-dev merged 1 commits from feat/google-service-account into main 2026-10-30 21:43:13 +00:00
Owner

Roadmap item 13, Google. Gmail could only be read with a token fetched by hand. --google-key key.json --auth-user {email} signs in as a Workspace service account with domain-wide delegation, acting for that user, so a whole domain moves in a plan with no one's password.

  • src/google.rs loads the JSON key and signs a JWT (RS256) with rustls' aws-lc-rs signer, so the program gets no new dependency. It exchanges the JWT at the token endpoint (RFC 7523) and caches the token per user, renewing it with under five minutes left. Every IMAP connection signs in through it, so a run longer than an hour takes a fresh token on reconnect.
  • ImapAuth::Google signs in with XOAUTH2, as --auth-bearer does. unauthorized_client errors carry a hint about domain-wide delegation.
  • Docs: Cloud and Admin-console setup, keeping the key private, and deleting it when done.

Tests: the mock makes an RSA key, and its fake token endpoint verifies the assertion's signature and claims (iss, sub, scope, aud). The fake IMAP server checks the XOAUTH2 payload, and both connections share one token. There are also CLI tests. aws-lc-rs is a dev-dependency only; the lock gains that one line.

Not tried against a real Workspace: I have none. Calendars and contacts from Google, and a single Gmail user without Workspace, are not in this PR.

Roadmap item 13, Google. Gmail could only be read with a token fetched by hand. `--google-key key.json --auth-user {email}` signs in as a Workspace service account with domain-wide delegation, acting for that user, so a whole domain moves in a plan with no one's password. - `src/google.rs` loads the JSON key and signs a JWT (RS256) with rustls' aws-lc-rs signer, so the program gets no new dependency. It exchanges the JWT at the token endpoint (RFC 7523) and caches the token per user, renewing it with under five minutes left. Every IMAP connection signs in through it, so a run longer than an hour takes a fresh token on reconnect. - `ImapAuth::Google` signs in with XOAUTH2, as `--auth-bearer` does. `unauthorized_client` errors carry a hint about domain-wide delegation. - Docs: Cloud and Admin-console setup, keeping the key private, and deleting it when done. Tests: the mock makes an RSA key, and its fake token endpoint verifies the assertion's signature and claims (iss, sub, scope, aud). The fake IMAP server checks the XOAUTH2 payload, and both connections share one token. There are also CLI tests. `aws-lc-rs` is a dev-dependency only; the lock gains that one line. Not tried against a real Workspace: I have none. Calendars and contacts from Google, and a single Gmail user without Workspace, are not in this PR.
jcoffey-dev added 1 commit 2026-10-30 21:39:04 +00:00
import imap: Gmail as a Workspace service account (--google-key)
ci / test (pull_request) Skipped
github/ci (branch) GitHub Actions
ci / github (pull_request) Successful in 3m52s
ci / announce (pull_request) Skipped
b6dfeb21e0
A Google Workspace service account with domain-wide delegation acts for
the user --auth-user names: a JWT naming the user, signed RS256 with the
account's key through rustls' aws-lc-rs signer, is exchanged for an
access token (RFC 7523), which signs in with XOAUTH2. Each connection
takes the cached token, or a new one when it has under five minutes
left, so long runs renew on reconnect. A whole domain moves in a plan
with one key file and --auth-user {email}.

The mock test makes an RSA key, checks the assertion's signature and
claims at a fake token endpoint, and the XOAUTH2 payload at a fake IMAP
server. aws-lc-rs is a dev-dependency only, already in the tree for
rustls.
jcoffey-dev merged commit 7b595a66d8 into main 2026-10-30 21:43:13 +00:00
jcoffey-dev deleted branch feat/google-service-account 2026-10-30 21:43:13 +00:00
Sign in to join this conversation.