Module google 

Google’s calendars and contacts, over its CalDAV and CardDAV, signed in with OAuth 2.0 as native apps should be (RFC 8252): your browser opens on Google’s page, Google sends the answer back to this computer (a loopback address, a port chosen at random), PKCE (RFC 7636) proves it is the same program asking. The OAuth client is Sioul’s own when the build was given one (SIOUL_GOOGLE_CLIENT_ID and SIOUL_GOOGLE_CLIENT_SECRET at build time: a key registered once for Sioul, as Thunderbird has its own), else yours, made once in your Google Cloud project (docs/google.md). What stays: the client and the refresh token, in the system keyring; the access token, in memory.

Mail (IMAP and SMTP over SASL XOAUTH2, sasl.rs) is signed in apart, with a grant of its own (Purpose::Mail): Gmail’s scope is restricted, given only to a key of your own until Sioul’s has passed Google’s review.

Structs

Grant

Your OAuth client, and what it was given; kept in the keyring as JSON.

SignIn

A sign-in under way: the page to open, and the door Google comes back to.

Enums

Purpose

What a sign-in is for. Each has its own grant, so that the mail’s restricted scope stays apart from the calendars’, and either can be removed alone.

Constants

AUTHORIZE 🔒

CARDDAV_START

IN_TESTING

The same, about a week after signing in with your own key: Google ended it because your project is still in testing, and says it will again.

MAIL_SCOPE

Gmail over IMAP and SMTP: Google’s one scope for them, a restricted one (docs/google.md, “Mail”).

MAIL_SCOPES

What the mail’s sign-in asks: who you are, and your mail.

REVOKE 🔒

SCOPES

What Sioul asks, all at once (Google adds none later to a desktop app): who you are, your calendars, your contacts, your tasks.

SIGN_IN_AGAIN

What a refused refresh token says (SyncError::Login): the account must be signed in again.

TOKEN 🔒

Statics

ACCESS 🔒

Access tokens, by grant (its keyring name: purpose and address), until about when they end; in memory only.

Functions

access_token

An access token for an address’s calendars, contacts and tasks (access_token_for).

access_token_for

An access token for an address, for a purpose: the one in memory while it lasts, else a new one from the refresh token. fresh asks a new one (after a refusal).

begin

Opens the door on this computer and makes the page to open: PKCE’s challenge (SHA-256 of a random verifier) and a random state.

begin_for

begin, for a purpose: its scopes asked, its grant kept apart.

built_in

Sioul’s own OAuth client, when the build was given one: a desktop client whose secret is no secret (Google says so of installed applications), the same for everyone. None: each person uses a key of their own.

caldav_start

Where Google’s calendars and address books are found.

decode 🔒

email_of 🔒

The e-mail the ID token says, from its payload (it came straight from Google over TLS).

encode 🔒

ended 🔒

A refused refresh token about seven days after signing in with a key of your own: Google’s limit for projects left in testing, said as such.

finish

Waits for Google’s answer (five minutes at most, or until stop), trades its code for tokens, checks it is the address you gave (and, for mail, that its access was left ticked on Google’s page), and keeps the grant in the keyring.

give_back 🔒

A token given back to Google, unless the address’s other part keeps a grant of the same key: Google ends a key’s access to an account as a whole, and would end that one too.

grant

The grant kept for an address’s calendars, contacts and tasks.

grant_for

The grant kept for an address, for a purpose.

own_key

A key of your own kept on this device for an address, to sign in with again or for its other part: the mail’s, else the calendars’ unless it is Sioul’s own (which cannot read mail).

post 🔒

query 🔒

random 🔒

refreshed 🔒

A new access token traded for a grant’s refresh token at endpoint (Google’s, or a stand-in in tests), and how long it lasts, in seconds.

remember 🔒

remembered 🔒

The access token kept in memory under a grant’s name, while it lasts.

revoke

Gives the calendars’ access back to Google and forgets it here (revoke_for).

revoke_for

Gives an access back to Google and forgets it here (its account is removed). Google is not asked when the address’s other part keeps a grant of the same key: it would end that one too.

wait_for_code 🔒

The answer Google’s page sends back to this computer: its code, checked against the state. stop ends the wait (Cancel).