@particle-academy/gmail-inbox-js 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -12,6 +12,34 @@ derived — somebody has to write what changed — but writing it in the
 provider repo would be a hand-edit that `.weaver.json` flags and the next
 sync destroys.
 
+## [0.4.0] — 2026-11-08
+
+### Added
+
+- **One Google consent grant, shared by every Google connector** (`oauth.grant:
+  "google"`), for an org-level Google connection: one OAuth client, one consent
+  and one refresh token per person, with each feature's scopes asked for when it
+  is first used. Declared in the manifest, the `-ui` package's OAuth constant,
+  the README and the registry index:
+  - `authorizeParams`: `access_type=offline` and `include_granted_scopes=true`.
+    A refresh token comes back only on the FIRST code exchange, so keep the stored
+    one when an exchange returns none.
+  - `revoke`: POST `https://oauth2.googleapis.com/revoke` with `token`, and
+    `scope: "grant"`. **Revoking removes the person's WHOLE Google grant, every
+    Google connector**, so a per-feature disconnect stops using that feature's
+    scopes locally and only a full Google disconnect revokes.
+  - `identity`: identify the account by the id_token's `sub` (request `openid`;
+    issuer `https://accounts.google.com` or `accounts.google.com`; audience is
+    the `clientId`), never by email, which Google says is neither unique nor
+    permanent.
+  `restrictedScopes` is `gmail.readonly`: Google verifies per OAuth client, so
+  sharing one client with the other Google connectors puts every feature behind
+  the annual CASA assessment, and a separate client keeps it here alone. The
+  `clientId` help now states that trade-off instead of forbidding a shared client.
+
+  Nothing a request sends has changed; this is what a host needs to run the
+  connection.
+
 ## [0.3.0] — 2026-11-08
 
 ### Added

package/README.md

@@ -41,7 +41,7 @@ A Gmail Inbox connection holds 6 values.
 
 | Field | Scope | Secret | Where it comes from |
 |---|---|---|---|
-| **OAuth client ID** | per installation | not secret | A DIFFERENT OAuth app than `gmail`'s, from Google Cloud Console -> APIs & Services -> Credentials. This one requests a restricted scope and carries Google's annual CASA assessment; `gmail`'s does not. Do not reuse the same client for both. |
+| **OAuth client ID** | per installation | not secret | From Google Cloud Console -> APIs & Services -> Credentials. ONE value for the whole installation. This connector requests a RESTRICTED scope, and Google verifies per OAuth client: sharing one client with the other Google connectors (one consent, one grant) puts every Google feature behind the annual CASA assessment; a separate client for this connector keeps it here alone, at the cost of a second consent. Your choice. |
 | **OAuth client secret** | per installation | **secret** | The client secret for the same OAuth app. One value for the whole installation. |
 | **Access token** | per connected account | **secret** | Per connected Google account, and it expires after ONE HOUR. The host refreshes it with the refresh token. |
 | **Refresh token** | per connected account | **secret** | Per connected Google account. Google issues one only when the consent request asks for offline access; without it the connection dies within the hour. |
@@ -57,6 +57,13 @@ Gmail Inbox uses OAuth2 (authorization_code). The package DECLARES the exchange;
 - **Scopes** — `https://www.googleapis.com/auth/gmail.readonly`
 - **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
 
+**One consent grant, shared** (`grant: "google"`). Every connector declaring the same grant can run on ONE OAuth client, with one consent and one refresh token per person.
+
+- **Authorize with** `access_type=offline`, `include_granted_scopes=true`. Ask for a feature's scopes when it is first used; the new token covers every scope granted before. A refresh token comes back only on the FIRST exchange, so keep the stored one when an exchange returns none.
+- **Revoke** — POST https://oauth2.googleapis.com/revoke with `token`. **It removes the WHOLE grant**: every connector sharing it, not only this one. A per-feature disconnect stops using that feature's scopes locally; only a full disconnect revokes.
+- **Identify the account by `sub`**: request `openid`, then verify the token response's id_token (issuer `https://accounts.google.com` or `accounts.google.com`, keys at https://www.googleapis.com/oauth2/v3/certs, audience = `clientId`). Never key a connection by email.
+- **Restricted scopes**: `https://www.googleapis.com/auth/gmail.readonly`. Verification is per OAuth client, so sharing one client with the rest of the grant puts every feature behind the provider's restricted-scope assessment; a separate client keeps it on this connector alone.
+
 The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
 
 ### The estate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/gmail-inbox-js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Gmail Inbox for Node — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP on @particle-academy/fancy-connector-core; no vendor SDK.",
   "repository": {
     "type": "git",
@@ -54,7 +54,7 @@
   },
   "peerDependencies": {
     "@particle-academy/fancy-flow": ">=0.47.1 <2.0",
-    "@particle-academy/gmail-inbox-ui": ">=0.3.0 <0.4.0"
+    "@particle-academy/gmail-inbox-ui": ">=0.4.0 <0.5.0"
   },
   "peerDependenciesMeta": {
     "@particle-academy/fancy-flow": {