@rubytech/create-maxy-code 0.1.473 → 0.1.475

package/payload/platform/plugins/google/references/auth.md

@@ -1,467 +1,431 @@
 # Google Auth Reference
 
-## Status: Phase 0 gate CLOSED — token-verified 2026-07-18
+The `google` plugin connects one Google Calendar per registered Google account,
+using a **Desktop (installed app)** OAuth client whose id and secret ship in
+brand config. This file is the decision record and the vendor runbook.
 
-The round-trip was run against the live `sitedesk-code` client and succeeded. Recorded
-outcome (values themselves deliberately not recorded):
-
-| Check | Result |
-|---|---|
-| Calendar scope granted via browser consent | **yes** — `scope=https://www.googleapis.com/auth/calendar` returned on the redirect and echoed in the token response |
-| Refresh token issued (`access_type=offline`, `prompt=consent`) | **yes** — `refresh_token` present |
-| Access-token lifetime | `expires_in: 3599` (1 hour) |
-| Refresh-token lifetime in **Testing** | `refresh_token_expires_in: 604799` — **6.99 days**, confirming the predicted 7-day Testing cap empirically |
-| Device-code refusal (Verdict 1) | not run empirically; rests on Google's published allowlist. Optional, changes no decision (see the live-test section) |
-
-The 604799 figure is the concrete argument for completing brand verification: in Testing,
-every connected account silently re-consents weekly. Verification removes it.
-
-The flow below is the ORIGINAL Phase 0 verdict and is retained for its evidence.
-It has since been superseded on two points: the vendor app is a
-Desktop client whose secret ships in brand config, and the redirect is loopback
-rather than a hosted HTTPS callback. Read the Desktop sections further down as
-authoritative where the two differ.
-
-## Original spike verdict (documentation-backed, now confirmed)
-
-This is the Phase 0 deliverable: the OAuth-flow verdict for a per-account
-**Google Calendar** plugin on a headless install where the operator consents from a phone
-over WhatsApp, with no browser on the box.
-
-Scope note: this plugin is **calendar-only**. Mail stays on the `email` plugin's IMAP/SMTP
-path; there is no Gmail API surface. That choice is deliberate and it is what keeps this
-plugin out of Google's restricted-scope security review (see
-["Verification"](#verification-the-light-kind-not-the-security-assessment)). Contacts
-(People API, read-only) is a possible later addition on the same footing but is not in this
-plugin.
-
-Every claim below is grounded in Google's **published** behaviour, cited inline. What is
-**not** yet done is the live token test the task requires: a real token issued (or refused)
-by an actual Google OAuth client for the Calendar scope. Until that runs
-(["Live test that closes the Phase 0 gate"](#live-test-that-closes-the-phase-0-gate)),
-this document is a prediction, not a proof. Do **not** build the register/register-poll
-path against it before the live test confirms the verdict.
-
-What is decided from published behaviour:
-
-- The **device-authorization grant is rejected** for this plugin. Google's device flow
-  serves only a fixed allowlist of scopes; Calendar is not on it.
-- The flow is therefore an **operator-assisted authorization-code (PKCE) flow**, and it
-  needs a redirect method, because Google's out-of-band ("paste the code") flow is fully
-  blocked.
-- The redirect method recommended at the time was a hosted HTTPS callback on the
-  brand's Cloudflare tunnel domain (a "Web application" client). **Superseded by
-  the recent decision**: the fallback named here — a Desktop client with a loopback redirect
-  and a manual code relay — is what shipped, because only an installed-app secret
-  can be distributed to customer devices.
-- **Verification is the light kind.** Calendar is a *sensitive* scope, not a *restricted*
-  one, so a brand's app needs only OAuth brand/consent-screen verification, never the
-  annual third-party security assessment.
-
-This diverges from Outlook on one axis: Outlook's device-code flow is secret-less, and the
-recommended Google flow holds a per-brand client secret. That divergence is forced by
-Google, not chosen; the reasoning is below.
+Decided 2026-07-18, superseding the earlier hosted-HTTPS-callback model. That model is gone from the tree; see
+["What was removed"](#what-was-removed) for what to expect on an old device.
 
 ---
 
-## Verdict 1: device-code is rejected (scope allowlist)
-
-Outlook uses Microsoft's `/devicecode` grant so the operator enters a code on their own
-phone and never needs a browser on the box. The first question for Google was whether the
-same grant works.
-
-It does not, for the Calendar scope. Google's OAuth 2.0 flow for TV and limited-input
-devices is supported only for a fixed allowlist. Verbatim from Google's documentation
-([OAuth 2.0 for TV and Limited-Input Device Applications](https://developers.google.com/identity/protocols/oauth2/limited-input-device)):
-
-> The OAuth 2.0 flow for devices is supported only for the following scopes:
->
-> **OpenID Connect, Google Sign-In:** `email`, `openid`, `profile`
-> **Drive API:** `https://www.googleapis.com/auth/drive.appdata`, `https://www.googleapis.com/auth/drive.file`
-> **YouTube API:** `https://www.googleapis.com/auth/youtube`, `https://www.googleapis.com/auth/youtube.readonly`
+## Vendor runbook: creating the client (one-time per brand)
+
+Not an end-user step. Run once per brand; each brand is a separate provisioning
+follow-up, mirroring Outlook 1479/1485.
+
+1. Sign in to the [Google Cloud console](https://console.cloud.google.com) with
+   the brand's Google account and select the brand's **existing** project — not
+   a new one, so the consent screen and any verification progress carry over.
+   For `sitedesk-code` that project is `Sitedesk Calendar`.
+2. Enable the **Google Calendar API** (APIs & Services → Library). It is the
+   only API this plugin calls.
+3. Configure the **OAuth consent screen**: user type **External**, app name and
+   support email set to the brand's, and the single scope from
+   ["Scope"](#scope) below. Publishing status starts at **Testing**.
+4. **Add test users** while the app is in Testing. Consent is refused for anyone
+   not on that list, including the operator, and the refusal renders as an
+   access-denied screen that reads like a flow bug.
+5. **Credentials → Create credentials → OAuth client ID**, application type
+   **Desktop app**, named for the brand. Register redirect `http://127.0.0.1`.
+6. Copy the **Client ID** and **Client secret** into that brand's `brand.json`:
 
-The Calendar scope (`https://www.googleapis.com/auth/calendar`) is absent. A device-flow
-authorization request that includes it is refused. The device-code grant cannot represent
-this plugin's calendar.
+   ```jsonc
+   // brands/<brand>/brand.json
+   "googleClientId": "<the client id>",
+   "googleClientSecret": "<the client secret>"
+   ```
 
-**The live test still owes the verbatim refusal.** The task's gate is a real refusal from a
-real client, not this allowlist. The live test below issues a `/device/code` request for
-the Calendar scope against a real client of type "TV and Limited Input" and records the
-exact error body. Expected: a `403`/`invalid_scope`-class refusal naming the scope. The
-allowlist above is the reason to expect it; the recorded response is the proof.
+7. **Run the loopback pre-flight below before publishing.** It is the only step
+   that catches a wrong client type, and it costs seconds.
+8. Re-bundle and publish the installer. No file is placed on any device by hand.
 
-## Verdict 2: OOB ("paste a code") is dead — a redirect is mandatory
+### Pre-flight: confirm the client accepts loopback
 
-The other headless-friendly pattern is out-of-band: Google shows the operator a code on a
-web page, the operator pastes it back, no redirect URI. That flow is gone. Google blocked
-new OOB use on 28 Feb 2022 and blocked all existing clients on 31 Jan 2023
-([OOB migration guide](https://developers.google.com/identity/protocols/oauth2/resources/oob-migration);
-[Google Developers Blog](https://developers.googleblog.com/making-google-oauth-interactions-safer-by-using-more-secure-oauth-flows/)).
-A `redirect_uri=urn:ietf:wg:oauth:2.0:oob` request is refused.
+The failure this catches is a **Web** client pasted in where a Desktop one
+belongs. Nothing else in the chain notices: the brand bundles, the installer
+stamps, the plugin boots reporting both values configured, and the consent URL
+builds. The first symptom is a customer completing consent and hitting
+`redirect_uri_mismatch`, which reads as an expired code rather than a wrong
+client type.
 
-So consent must land on a real `redirect_uri`. For an installed/desktop app Google's named
-replacement is the **loopback IP redirect** (`http://127.0.0.1:<port>` or
-`http://localhost:<port>`), and it "requires you to be listening on a local web server
-... to receive the authorization code" (OOB migration guide). Google's migration guidance
-covers mobile, Chrome, web, and desktop clients; it gives **no** cross-device pattern for
-a headless box where consent happens on a separate phone. That gap is the design problem
-this plugin has to solve itself.
+The discriminator is that a genuine Desktop client accepts a loopback redirect
+**without any redirect being registered on it**, because RFC 8252 §7.3 makes the
+port irrelevant for the `127.0.0.1` literal. A client that refuses loopback is
+therefore not a usable Desktop client, whatever the console labels it.
 
-## Verdict 3: the flow — operator-assisted authorization-code (PKCE)
+Sends the client id only, never the secret. Non-mutating.
 
-Because the operator's browser is on a phone and the plugin is on the box, the redirect
-that carries the `code` and the process that exchanges it live on different machines. Two
-concrete flows bridge that. The recommendation is Option B primary, Option A as the
-secret-less fallback.
+```bash
+CID=$(node -e 'console.log(JSON.parse(require("fs").readFileSync("brands/<brand>/brand.json","utf8")).googleClientId.trim())')
+curl -s -D - -o /dev/null \
+  "https://accounts.google.com/o/oauth2/v2/auth?client_id=${CID}&redirect_uri=http%3A%2F%2F127.0.0.1%3A8571&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar" \
+  | grep -i '^location:' | grep -q 'authError' && echo REJECTED || echo ACCEPTED
+```
 
-### Option B (SUPERSEDED): hosted HTTPS callback on the brand tunnel domain
+The two words report **what Google did with the redirect**, not whether you have
+a problem. Which of them is the good news depends on which redirect you sent, so
+read them against the table below rather than by tone.
 
-Client type **Web application**. A stable authorized redirect URI on the install's existing
-Cloudflare **public** host, served by the always-running `platform/ui` server (the same
-process that runs the Outlook auto-poll dispatcher):
+`ACCEPTED` means Google took the redirect and moved the browser to the sign-in
+flow. `REJECTED` means it bounced to an error page; decode the `authError`
+payload to see which error:
 
-```
-https://<brand-public-host>/api/google/oauth/callback
+```bash
+# ...append to the curl above instead of the grep chain
+| sed -E 's/.*authError=([^&]*).*/\1/' | tr '_-' '/+' | base64 -d | head -c 200
 ```
 
-**The `/api/` prefix is mandatory, not cosmetic.** The public host is not a general web
-server: it admits only an allowlist of path prefixes and 404s everything else
-(`platform/ui/server/public-host-gate.ts`, `PUBLIC_ALLOWED_PREFIXES`). A bare
-`/google/oauth/callback` would 404 before reaching any route. Phase 2 must add
-`/api/google/` to that allowlist in the same commit as the callback route.
+- `redirect_uri_mismatch` — the client will not take a loopback redirect. It is
+  a Web client, or a Desktop client whose configuration was altered. Create a
+  **Desktop app** client and use that pair.
+- `invalid_request` — the redirect in the probe itself is malformed. Check the
+  URL-encoding rather than the client.
 
-The public host is also the correct *class* of host, and there is an exact in-repo
-precedent. QuickBooks already solved this identical problem, and the allowlist records why:
+**Both outcomes return HTTP 302**, so the status code is not the signal and a
+probe that checks it reports success on a broken client. The `authError`
+parameter is the signal.
 
-> QuickBooks OAuth consent callback. Intuit redirects the operator's browser here with no
-> admin cookie; the route authenticates by validating the OAuth `state` nonce, not the
-> remote-auth gate (same model as `/api/telegram/`).
+Run the probe **twice**, and read the pair:
 
-Google's redirect has the same shape: the client's phone browser arrives with no admin
-cookie, so the route authenticates on the `state` nonce rather than the remote-auth gate.
-Mirror `/api/quickbooks/` rather than inventing a new pattern.
+| Run | Redirect sent | Required result | What it establishes |
+|---|---|---|---|
+| Subject | `http://127.0.0.1:8571` | `ACCEPTED` | The client takes loopback, so it is a usable Desktop client |
+| Control | `https://example.invalid/cb` | `REJECTED` (`invalid_request`) | The probe can still detect a rejection |
 
-```
-operator (phone)                     plugin / platform-ui (box)                 Google
-   |                                        |                                     |
-   | google-account-register                |                                     |
-   |--------------------------------------->| build PKCE (verifier+challenge),    |
-   |                                        | state; write pending-oauth.enc      |
-   |                                        | build consent URL (access_type=     |
-   |                                        |   offline, prompt=consent, calendar |
-   |                                        |   scope, redirect=<tunnel>/cb)      |
-   | { status:"pending", consentUrl }       |                                     |
-   |<---------------------------------------|                                     |
-   | open consentUrl on phone, sign in,     |                                     |
-   | consent ------------------------------------------------------------------->  |
-   |                                        | GET /api/google/oauth/callback?code&state <-- redirect
-   |                                        | verify state, exchange code+verifier |
-   |                                        |   (+client secret) --------------->  |
-   |                                        | < tokens (access+refresh)            |
-   |                                        | GET userinfo → account email/id      |
-   |                                        | encrypt → accounts/<id>/tokens.enc   |
-   |                                        | clear pending                        |
-   | google-account-register-poll → { registered, email }                          |
-   |<---------------------------------------|                                     |
-```
+`REJECTED` on the control is the **expected and required** outcome — it is not a
+fault, and nothing about the client needs changing when you see it. Its only job
+is to prove the probe is still measuring something.
 
-The operator sees a clean "connected, return to WhatsApp" page; the code is captured
-server-side, never relayed by hand. `register-poll` reports success from local state,
-exactly like Outlook's poll. This is the better ergonomic match for a non-technical
-operator on WhatsApp, which is the whole reason device-code was wanted.
+The failure mode it guards against is a probe that has silently stopped
+measuring: if the `grep` chain breaks — Google renames the error parameter, or
+stops emitting a `location:` header — the command still exits cleanly and still
+prints `ACCEPTED`. Silent green. `ACCEPTED` on **both** runs means the probe is
+dead and the subject run proves nothing; fix the probe before trusting it.
 
-Cost: a Web-application client carries a **real client secret** and a per-brand authorized
-redirect URI. The secret is confidential and lives in the brand/account secret store, never
-bundled into the installer. This is the one divergence from Outlook.
+Never act on the control run alone. Reading its `REJECTED` as a verdict on the
+client would send you to replace a credential that is working.
 
-### Option A (fallback): loopback client + manual code relay
+Trailing whitespace on a pasted id is a real and silent failure; nothing in the
+chain trims it. The `.trim()` above is for the probe only, so the probe can pass
+while the shipped value is broken. Confirm the stored value is clean:
 
-Client type **Desktop app**, redirect `http://127.0.0.1:<port>`. No hosted endpoint, no
-per-brand redirect URI beyond the fixed loopback, and the installed-app secret Google
-issues for desktop clients is documented as non-confidential.
+```bash
+node -e 'const v=JSON.parse(require("fs").readFileSync("brands/<brand>/brand.json","utf8")).googleClientId; console.log(v===v.trim()?"clean":"WHITESPACE")'
+```
 
-The operator opens the consent URL on the phone and consents; Google redirects the phone
-browser to `http://localhost:<port>/?code=...`, which fails to load (nothing listens on the
-phone). The operator copies the `code` value out of the address bar of the failed page and
-sends it back via a `google-account-register-submit` tool; the plugin exchanges it with the
-stored PKCE verifier.
+**The client secret is shown exactly once.** The console displays only the last
+four characters afterwards ("Viewing and downloading client secrets is no longer
+available"). Capture it at creation straight into `brand.json`, or plan to
+rotate — rotation is free and has no downtime: **Add secret**, store the new
+one, delete the old. Never paste it into a chat transcript or a shell command
+that lands in history.
 
-Cost: extracting a `code` from a failed-load address bar on a phone is fragile — some mobile
-browsers hide the URL of a failed navigation. Use this only where a brand has no usable
-hosted callback. The live test measures whether this UX is acceptable before it is relied on.
+Confirm the stamp took from the boot line, which reports presence and never
+values:
+
+```bash
+grep -m1 'google-mcp. boot' ~/.<brand>-code/logs/server.log
+# ... clientIdConfigured=true clientSecretConfigured=true
+```
 
-### Why the recommendation, and what the live test decides
+Either reading `false` on a brand that ships both is the mis-stamp signature.
 
-Option B wins on operator UX and robustness at the cost of a per-brand secret. Option A
-keeps provisioning minimal and secret-light at the cost of a fragile mobile step. The live
-test resolves the open question — that Option B's hosted callback round-trips a real token
-for the Calendar scope — before any register code is built. If the tunnel-hosted callback
-is not viable for a given brand, Option A is the recorded fallback.
+### Connecting an account, once the brand ships a client
+
+`google-account-register` returns a consent URL. The user opens it on any device
+and approves. What happens next depends on **where** they approved, and both
+paths are supported.
+
+**On the install's own machine.** Register binds a single-shot listener on
+`127.0.0.1` at an OS-assigned port and puts that port in the consent URL, so
+Google's redirect reaches it. The listener verifies `state`, completes the
+exchange in-process, and renders a page naming the connected account. Nothing is
+pasted. The page asks the user to return to the chat and say so, because the
+agent has no callback and learns the outcome from
+`google-account-register-poll`.
+
+**On another device.** A phone cannot route to the install's loopback, so the
+redirect fails to load exactly as before. The user copies the whole address-bar
+URL and passes it to `google-account-register-submit`, which exchanges it
+in-process. This path is not a degraded mode; it is the designed route for the
+Pi deployment, where the admin always consents from a phone.
+
+That failed-page step remains a real UX cost on the cross-device path, priced
+and accepted: some mobile browsers hide the URL of a failed navigation. It is
+the price of a client type whose secret can legitimately ship to customer
+devices, and it cannot be removed — the phone has no route to the install.
+
+**The port is no longer fixed**, and the consent URL is no longer deterministic.
+RFC 8252 §7.3 is what permits this: Google ignores the port when matching a
+loopback redirect, so binding `:0` is free. It also retires a latent collision,
+since a fixed port is shared by every brand and two co-resident brands would
+contend for it. `http://127.0.0.1:8571` survives as the fallback when the bind
+fails, which keeps an install that cannot bind working exactly as it did before.
+
+Because the port varies per registration, the pending entry stores the redirect
+it issued and the exchange sends that stored value back. Google compares the two
+byte for byte, so a registration whose listener bound a port cannot be completed
+against the constant.
 
 ---
 
-## Client-id / secret model per brand
+## Why this shape
 
-One vendor-owned Google Cloud OAuth client per brand serves every install and every account
-on that brand, exactly as `outlookClientId` does. The client id ships as the brand default
-`brands/<brand>/brand.json#googleClientId`, stamped onto the session-manager unit env as
-`GOOGLE_CLIENT_ID` and inherited down the spawn chain (manager unit env → PTY → MCP child).
+### Device-code is rejected (scope allowlist)
 
-Divergence from Outlook: the recommended Web-application flow (Option B) also needs a
-**client secret**, which ships in `brand.json` (the house-only file this
-once described is withdrawn). A brand that ships `googleClientId` empty has the plugin inert with an
-actionable signal (`clientIdConfigured=false`), register refuses, and no operator action
-makes it work until the vendor client exists — mirroring Outlook's inert behaviour.
+Outlook uses Microsoft's `/devicecode` grant, so the operator never needs a
+browser on the box. That grant does not work for Calendar. Google's flow for TV
+and limited-input devices serves only a fixed allowlist. Verbatim from
+[OAuth 2.0 for TV and Limited-Input Device Applications](https://developers.google.com/identity/protocols/oauth2/limited-input-device):
 
-### The vendor app is a Desktop client, and its secret ships in brand config
+> The OAuth 2.0 flow for devices is supported only for the following scopes:
+>
+> **OpenID Connect, Google Sign-In:** `email`, `openid`, `profile`
+> **Drive API:** `https://www.googleapis.com/auth/drive.appdata`, `https://www.googleapis.com/auth/drive.file`
+> **YouTube API:** `https://www.googleapis.com/auth/youtube`, `https://www.googleapis.com/auth/youtube.readonly`
 
-Decided 2026-07-18, superseding the house-only file this section
-used to describe. That model required placing a secret by hand on every install,
-which cannot reach a customer device and contradicts installer-only doctrine.
+The Calendar scope is absent, so a device-flow request carrying it is refused.
+The flow is therefore authorization-code + PKCE.
 
-There is no secret-free alternative: Google requires `client_secret` at the
-token endpoint for **every** client type, including Web clients using PKCE.
+### Out-of-band is dead, so a redirect is mandatory
 
-So the vendor app is a **Desktop (installed app)** client, because Google
-explicitly sanctions embedding that secret in distributed software — "the client
-secret is obviously not treated as a secret". `brand.json` therefore carries
-both values and the installer stamps them onto the session-manager unit:
+Google blocked new out-of-band use on 28 Feb 2022 and all existing clients on
+31 Jan 2023 ([OOB migration guide](https://developers.google.com/identity/protocols/oauth2/resources/oob-migration)).
+A `redirect_uri=urn:ietf:wg:oauth:2.0:oob` request is refused. Consent must land
+on a real redirect URI.
 
-```jsonc
-// brands/<brand>/brand.json
-"googleClientId": "<the client id>",
-"googleClientSecret": "<the client secret>"
-```
+### The secret cannot be avoided, so the client type must sanction shipping it
+
+Google requires `client_secret` at the token endpoint for **every** client type,
+including Web clients using PKCE. There is no public-client path, so any install
+performing its own exchange holds one.
 
-They stamp **together or not at all**. A client id without its secret builds a
-consent URL the user can complete but an exchange that cannot, which fails later
-and less legibly than not offering the flow.
+A Desktop client is the one type where Google explicitly sanctions embedding
+that secret in distributed software — "the client secret is obviously not
+treated as a secret". `brand.json` is therefore a legitimate carrier, and the
+installer stamps `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` **together or
+not at all**. A client id without its secret builds a consent URL the user can
+complete but an exchange that cannot, which fails later and less legibly than
+not offering the flow.
 
 The secret ships to a **public** npm registry. That is the accepted trade: the
 residual risk is app impersonation and quota abuse against the brand's client
-id, not token theft, because PKCE still binds each code to its verifier.
+id, **not** token theft, because PKCE still binds each code to its verifier.
 
 Rejected, each once and for a reason:
 
-- **Customer-owned apps** (the QuickBooks pattern, where the operator registers
-  their own app). Unlike Intuit, Google demands app verification for the
-  sensitive Calendar scope — homepage, privacy policy, domain ownership, demo
-  video — which the target customer cannot produce.
-- **A vendor-hosted exchange broker**, where the install posts the code to a
-  brand-operated endpoint. Best security and best UX, but it means operating a
-  credential-bearing service for every customer.
+- **Customer-owned apps** (the QuickBooks pattern at `quickbooks/PLUGIN.md:71`,
+  where the operator registers their own app). Unlike Intuit, Google demands app
+  verification for the sensitive Calendar scope — homepage, privacy policy,
+  domain ownership, demo video — which the target customer cannot produce.
+- **A vendor-hosted exchange broker.** Best security and best UX, but it means
+  operating a credential-bearing service for every customer.
 - **A Web client with the secret shipped anyway.** A Web-app secret is genuinely
   confidential in Google's model; publishing it would be a real credential leak
   rather than a sanctioned embed.
+- **A house-only secret file** (`platform/config/google-house.env`, the earlier
+  hosted-callback model). Requires a manual placement per install, so it cannot reach a
+  customer device and contradicts installer-only doctrine.
 
 ### The redirect is loopback, and the IP literal is mandatory
 
 Desktop clients permit only loopback redirects. `https` is rejected outright and
 custom URI schemes are withdrawn ("no longer supported due to the risk of app
-impersonation"), so this is the entire option space.
+impersonation"), so this is the entire option space:
 
 ```
 http://127.0.0.1:8571
 ```
 
 **Never `localhost`.** RFC 8252 §7.3 makes the port irrelevant when matching a
-loopback redirect, but only for the IP literals `127.0.0.1` and `::1`; strict
-servers match the hostname literally. Register `http://127.0.0.1` on the client.
-
-Nothing listens on that port, by design. The consenting browser is the user's
-own phone, so the redirect fails to load and the user copies the code out of the
-address bar and pastes it back to `google-account-register-submit`. The port is
-fixed so consent URLs are deterministic and one register's logs compare with
-another's.
+loopback redirect, but only for the IP literals `127.0.0.1` and `::1`; the
+hostname is matched literally. Register `http://127.0.0.1` on the client.
 
-This is why the hosted HTTPS callback that the earlier plugin built is gone, along with
-its allowlist entry and its refresh route: a Desktop client cannot use it.
+The port is fixed and arbitrary. Google ignores it for loopback and nothing
+listens on it, so a constant keeps consent URLs deterministic and one register's
+logs comparable with another's.
 
-### Vendor runbook: creating the Desktop client
+---
 
-1. In the **existing** Cloud project for the brand — not a new one, so the
-   consent screen and any verification progress carry over — go to
-   **Credentials → Create credentials → OAuth client ID**.
-2. Application type **Desktop app**. Name it for the brand.
-3. Copy the **Client ID** and **Client secret** into that brand's `brand.json`
-   as `googleClientId` and `googleClientSecret`.
-4. Re-bundle and publish. No file is placed on any device by hand.
+## Scope
 
-Confirm it took from the boot line, which reports presence and never values:
+One scope, chosen to match the Outlook calendar tool surface (read plus create,
+update, cancel, respond, free-busy), no broader:
 
-```bash
-grep -m1 'google-mcp. boot' ~/.<brand>-code/logs/server.log
-# ... clientIdConfigured=true clientSecretConfigured=true
-```
+| Purpose | Scope | Class |
+|---|---|---|
+| Calendar read + event create/update/cancel/respond/free-busy | `https://www.googleapis.com/auth/calendar` | sensitive |
 
-Either reading `false` on a brand that ships both is the mis-stamp signature.
+The account's email is read from `GET /calendars/primary` (whose id is the
+address) rather than by requesting `openid`/`email`/`profile`, so consent stays
+minimal.
 
----
+A refresh token requires `access_type=offline` plus `prompt=consent` on the
+consent URL; those are request parameters, not scopes.
 
-## Vendor provisioning runbook (one-time per brand)
-
-Run once per brand to mint the client whose id goes in that brand's `brand.json` and whose
-secret goes in the brand secret store. Not an end-user step. Each brand is a separate
-follow-up once the plugin lands (mirroring Outlook 1479/1485).
-
-1. Sign in to the [Google Cloud console](https://console.cloud.google.com) with the brand's
-   Google account. Create (or select) one project named for the brand and its Google
-   integration, e.g. `SiteDesk Google`.
-2. Enable the **Google Calendar API** (APIs & Services → Library). That is the only API this
-   plugin calls.
-3. Configure the **OAuth consent screen**: user type **External**, app name and support
-   email set to the brand's, and add the single scope below. Publishing status starts at
-   **Testing** and moves to **In production** once brand verification is done (see below).
-4. Create the **OAuth client**:
-   - **Option B (recommended):** application type **Web application**. Add the authorized
-     redirect URI `https://<brand-public-host>/api/google/oauth/callback` (the `/api/`
-     prefix is required — see Option B above). Copy the **Client ID**
-     (→ `brand.json#googleClientId`).
-
-     **The client secret is shown exactly once and cannot be retrieved afterwards.** The
-     console displays only the last four characters from then on ("Viewing and downloading
-     client secrets is no longer available. If you have lost the secret below, please add a
-     new one."). Capture it at creation into its final destination, or plan to rotate. It is
-     never pasted into a chat transcript, a shell command that lands in history, or the repo.
-     Rotation is free and has no downtime: **Add secret**, store the new one, delete the old.
-     It ships in `brand.json` as `googleClientSecret` — see the Desktop sections above.
-   - **Option A (fallback):** application type **Desktop app**. Copy the **Client ID**.
-5. Set `googleClientId` in the brand's `brand.json` and re-bundle:
-   ```jsonc
-   // brands/<brand>/brand.json
-   "googleClientId": "<the Client ID copied above>"
-   ```
+The narrower alternative is `calendar.events` + `calendar.readonly` +
+`calendar.freebusy`. It has never been exercised. All Calendar scopes are
+*sensitive*, not *restricted*, so narrowing would not change the verification
+path.
 
-### Scope
+## Verification: the light kind, not the security assessment
 
-One scope, chosen to match the Outlook calendar tool surface (read plus create, update,
-cancel, respond, free-busy), no broader:
+Calendar is a **sensitive** scope, not a restricted one. A production app using
+it needs only OAuth **brand/consent-screen verification** (own the domain;
+Google reviews app name, logo, and scope justification). It does **not** need
+the annual third-party security assessment, which applies only to *restricted*
+scopes such as the Gmail read/modify family. Dropping the Gmail surface is
+exactly what keeps a brand off that review — mail runs on the `email` plugin's
+IMAP/SMTP path instead.
 
-| Purpose | Scope | Class |
-|---|---|---|
-| Identity (email address, sign-in) | `openid`, `email`, `profile` | non-sensitive |
-| Calendar read + event create/update/cancel/respond/free-busy | `https://www.googleapis.com/auth/calendar` | sensitive |
+The two publishing states, and what each costs:
 
-Notes:
+- **Testing** (no verification): works immediately for up to **100 named test
+  accounts**, each seeing the unverified-app warning and re-consenting about
+  every 7 days. Fine for a pilot.
+- **In production + brand-verified** (no cost, no security firm, typically days
+  to a couple of weeks): the 100-account cap lifts, the warning is gone, and
+  refresh tokens are long-lived. This is the real deployment state and the
+  target for each brand. Start it early, because Google's review is the slow
+  part.
 
-- `calendar` (full) is the simplest choice for read plus all the control operations. The
-  narrower alternative is `calendar.events` + `calendar.readonly` + `calendar.freebusy`; the
-  live test can confirm the narrower set is sufficient before Phase 2 fixes it. All Calendar
-  scopes are *sensitive*, not *restricted*, so the narrower choice does not change the
-  verification path.
-- A refresh token requires `access_type=offline` plus `prompt=consent` on the consent URL;
-  this is a request parameter, not a scope.
+The 7-day Testing cap is measured, not predicted — see below. It is Google
+forcing re-consent until the brand is verified, **not** a refresh failure, and
+the health signal names it distinctly.
 
-### Verification: the light kind, not the security assessment
+### Recorded round-trip (2026-07-18)
 
-The Calendar scope is **sensitive**, not restricted. Google requires a production app that
-uses sensitive scopes to pass OAuth **brand/consent-screen verification** (own the domain,
-Google reviews the app name, logo, and scope justification). It does **not** require the
-annual third-party security assessment — that applies only to *restricted* scopes such as
-the Gmail read/modify family, which this plugin does not use. Dropping the Gmail surface is
-exactly what keeps a brand off the expensive review.
+Run against the since-retired `sitedesk-code` Web client. The client type has
+changed, but these facts are properties of the Calendar scope and the consent
+screen, not of the client type, so they carry forward. Values deliberately not
+recorded.
 
-The two publishing states, and what each costs:
+| Check | Result |
+|---|---|
+| Calendar scope granted via browser consent | **yes** — `scope=https://www.googleapis.com/auth/calendar` returned on the redirect and echoed in the token response |
+| Refresh token issued (`access_type=offline`, `prompt=consent`) | **yes** — `refresh_token` present |
+| Access-token lifetime | `expires_in: 3599` (1 hour) |
+| Refresh-token lifetime in **Testing** | `refresh_token_expires_in: 604799` — **6.99 days**, confirming the 7-day Testing cap empirically |
+| Device-code refusal | not run empirically; rests on Google's published allowlist above. Changes no decision |
 
-- **Testing** (no verification): works immediately for up to **100 named test accounts**,
-  each of which sees the unverified-app warning and re-consents about **every 7 days**
-  (Google caps refresh-token lifetime while an app is in Testing). Fine for a pilot,
-  including the first `sitedesk-code` account.
-- **In production + brand-verified** (the light verification, no cost, no security firm,
-  typically days to a couple of weeks): the 100-account cap lifts, the warning is gone, and
-  refresh tokens are long-lived. This is the real deployment state and the target for each
-  brand. Start it early per brand, because Google's review is the slow part.
+The 604799 figure is the concrete argument for completing brand verification: in
+Testing, every connected account silently re-consents weekly.
 
 ---
 
-## Token store and pending-state layout (informs Phase 1/2, not built here)
+## Token store and pending-state layout
 
-The store mirrors Outlook's per-account encrypted layout: one AES-256-CBC `.key` per
-account, `tokens.enc` under `accounts/<id>/`, mode 0700 dirs and 0600 files, atomic
-temp+rename writes. This plugin is one Google account per registration, so there is no
-multi-mailbox nesting to mirror.
+Mirrors Outlook's per-account encrypted layout: one AES-256-CBC `.key` per
+account, `tokens.enc` under `accounts/<id>/`, mode 0700 dirs and 0600 files,
+atomic temp+rename writes.
 
 ```
 data/accounts/<accountId>/secrets/google/
 ├── .key                          # 32 random bytes, base64 — per-account AES-256-CBC key
 ├── accounts/
 │   └── <userId>/tokens.enc       # AES-256-CBC token JSON blob per registered Google account
-└── pending-oauth.enc             # transient: PKCE verifier + state between register and callback/submit
+└── pending-oauth.enc             # transient: PKCE verifier between register and submit
 ```
 
-Two divergences from Outlook are required and must be honoured in Phase 2:
+Two divergences from Outlook are load-bearing:
 
-- **Pending state is a PKCE verifier + `state`, not a device code.** Register writes it;
-  the callback (Option B) or `register-submit` (Option A) reads and clears it. Single-slot
-  per account, refuses a second concurrent register with an `in-progress` signal, cleared
-  on any terminal outcome.
-- **The concurrent-refresh race must not be reproduced.** Outlook's token writer used a
-  fixed `.tmp` name and could wipe valid tokens when two refreshes raced. The
-  Google writer uses a unique temp name per write and a refresh catch that never clears
-  valid tokens on an IO error. A losing concurrent writer must not wipe credentials.
+- **Pending state is a PKCE verifier, not a device code.** Register writes it;
+  `register-submit` reads and clears it. Single-slot per account, refuses a
+  second concurrent register with an `in-progress` signal, cleared on any
+  terminal outcome.
+- **The concurrent-refresh race is not reproduced.** Outlook's token writer used
+  a fixed `.tmp` name and could wipe valid tokens when two refreshes raced. The
+  Google writer uses a unique temp name per write, and its refresh catch never
+  clears valid tokens on an IO error. A losing concurrent writer must not wipe
+  credentials.
 
-Refresh triggers automatically within 5 minutes of access-token expiry, mirroring Outlook.
-The 7-day Testing-status refresh-token expiry above is separate: it is Google forcing
-re-consent until the brand is verified, not a refresh failure, and the health signal must
-name it distinctly.
+Refresh runs **in-process** against Google, within 5 minutes of access-token
+expiry. No `platform/ui` code mints, exchanges or refreshes a credential; its
+only Google surface is the standing pending audit below, which reads the age of
+`pending-oauth.enc` and never decrypts it.
 
 ---
 
-## Live test that closes the Phase 0 gate
-
-Run this once a real Google OAuth client exists, before building the register path. It
-converts the predictions above into recorded facts.
-
-**Prerequisite: add test users.** A newly created client sits in **Testing**, where consent
-is refused for anyone not on the consent screen's test-user list — including the operator.
-Add the testing Google account (and any client account used for the trial) before attempting
-step 2, or consent dead-ends with an access-denied screen that looks like a flow bug.
-
-**The round-trip does not require the callback route to exist.** The route is Phase 2 code,
-and Phase 0 must not build it. Google still redirects the browser to the callback URL with
-`?code=...` in the query string; the page 404s (the allowlist entry is not added yet) but
-the address bar carries the code. Copying it from there and exchanging it by hand proves
-everything the gate asks about, with no plugin code written.
-
-1. **Authorization-code round-trip (Verdict 3, Option B) — the load-bearing step.** With the
-   Web-application client, open the consent URL for the Calendar scope with
-   `access_type=offline` and `prompt=consent`, consent as a listed test user, then copy the
-   `code` value from the address bar of the 404'd callback page. Exchange it against
-   `https://oauth2.googleapis.com/token` with the client id, client secret, the same
-   `redirect_uri`, and `grant_type=authorization_code`. Confirm the response carries a
-   **refresh token** and the granted `scope` includes the Calendar scope. Run this on the
-   device, where the client secret already lives; never paste the secret into a transcript.
-   Record the granted scope and the presence of a refresh token (never the tokens
-   themselves).
-2. **Device-code refusal (Verdict 1) — optional, confirmatory only.** Verdict 1 already
-   rests on Google's published allowlist, which does not list any Calendar scope. Confirming
-   it empirically needs a *second*, throwaway client of type "TV and Limited Input", since a
-   Web-application client cannot exercise the device grant. Worth doing only if the recorded
-   refusal is wanted for the file; it changes no decision, because step 1 succeeding already
-   establishes the flow being built.
-3. **Narrow-scope check (optional).** Repeat step 1 with `calendar.events` +
-   `calendar.readonly` + `calendar.freebusy` instead of `calendar`, and confirm event
-   create/update/cancel/respond/free-busy all work, to decide the narrower scope for Phase 2.
-
-Paste the recorded outcome into this section. Once step 1 is recorded, the Phase 0 gate is
-met and Phases 1–2 (the plugin build) proceed against the confirmed flow.
+## Standing audits
+
+Both states these cover are unobservable by any event: an abandoned registration
+fires nothing, and a refresh token expiring is a date passing, not an action.
+`runAccountRegisterPoll` emits `op=pending-stranded` only when somebody polls —
+and the case worth catching is the one nobody polls.
+
+- **Stranded pending.** In-process in `platform/ui`
+  (`server/google-pending-audit.ts`), every 5 minutes, over every account uuid
+  under `data/accounts`. Any `pending-oauth.enc` at or past
+  `PENDING_LIFETIME_SEC` (600s) emits
+  `[google-oauth] op=pending-stranded account=<id> ageSec=<N>`. It runs in-process
+  rather than in the spawned script precisely so the signal does not depend on a
+  spawn being healthy — the same rationale as Outlook's `devicecode-stranded`
+  audit. A pending file that vanishes mid-scan (a concurrent submit clearing it)
+  is skipped per-account; it must never abort the cycle, because that would
+  suppress the heartbeat and read as the audit being dead.
+- **Refresh TTL.** Spawned `mcp/dist/scripts/account-audit.js`, hourly, one
+  `[google-account-audit] account=<id> email=<addr> refreshTtlDays=<D> status=<…>`
+  per connected Google account. It is a spawned script, not in-process, because
+  classifying a token means decrypting the blob with the per-account AES key and
+  `TokenStore` is the only holder of that contract. An unreadable blob is skipped,
+  never fatal — one corrupt store must not blind the audit to every other account.
+
+**Heartbeats, and why they are not optional.** Each audit emits a heartbeat every
+cycle, including empty ones. Without it, an audit that has stopped running looks
+exactly like an audit reporting all-clear, and the operator learns nothing until
+an account has already fallen off. The absence of a heartbeat across more than
+one interval is the failure signal. A pending cycle that throws logs
+`op=pending-audit-error` — a deliberately distinct token, so a broken cycle is
+never miscounted as a healthy heartbeat by a reader grepping `op=pending-audit`.
+
+**What `refreshTtlDays` is, exactly.** Days remaining on Google's 180-day
+inactivity revocation clock, computed as `180 - daysSince(lastRefresh)` and
+clamped so a clock that ran ahead cannot report more than 180. `TokenBlob` stores
+no refresh-token expiry because Google issues none, so this inactivity clock is
+the only bounded quantity available locally. It does **not** predict the other
+revocation causes — the user revoking access, a password change, the app being
+unpublished — none of which are visible from disk. `refreshToken: null` is
+reported `expired` with zero days however recently it was written, since such a
+connection dies with its access token about an hour out.
+
+Diagnostic path:
 
-### Provisioned clients
+```
+~/<brand>-code/platform/scripts/logs-read.sh --tail server 200 \
+  | grep -E '\[google-oauth\]|\[google-account-audit\]'
+```
 
-| Brand | Client type | Redirect URI | Client ID | Status |
-|---|---|---|---|---|
-| `sitedesk-code` | ~~Web application~~ **RETIRED** | ~~`https://public.sitedesk.online/api/google/oauth/callback`~~ | `1032860640027-…` | **Do not use.** A Web client cannot register a loopback redirect, so this id fails `redirect_uri_mismatch` under the Desktop flow. Cleared from `brand.json`; delete the client in the console and revoke its secret. |
-| `sitedesk-code` | Desktop app | `http://127.0.0.1` | *(not yet created)* | Awaiting provisioning in the **existing** `Sitedesk Calendar` project, so consent-screen and verification progress carry over. |
+---
 
-The public host was confirmed live and routing to the `platform/ui` server (it serves the
-brand's public page). No secret or token is recorded here. The Web client's secret was exposed to shell history during the manual round-trip.
-That client is retired rather than rotated: delete it in the console, which
-revokes the secret with it.
+## What was removed
+
+The earlier hosted-callback model built a hosted HTTPS callback at
+`https://<brand-public-host>/api/google/oauth/callback`, served by the
+`platform/ui` server, plus a refresh route and a house-only secret file. A
+Desktop client cannot register an HTTPS redirect, so all of it is deleted:
+`platform/ui/server/routes/google-oauth.ts` and its test, the
+`/api/google/oauth/callback` allowlist entry, the mount in `server/index.ts`,
+and the `MAXY_UI_INTERNAL_PORT` dependency. No OAuth surface remains in
+`platform/ui` — no route, no exchange, no credential — and a test asserts the
+public host still refuses that path. The one `platform/ui` file that mentions
+Google is `server/google-pending-audit.ts`, which reads the age of a pending file
+and is not reachable over HTTP at all.
+
+**Devices touched by the earlier plugin may still hold
+`platform/config/google-house.env`, containing the retired Web client's live
+secret.** Nothing reads it and nothing removes it. Delete it on each such
+device.
 
-**Devices touched by the earlier plugin may still hold `platform/config/google-house.env`
-containing that live Web-client secret.** Nothing reads it any more and nothing
-removes it. Delete it on each such device as part of retiring the Web client.
+### Provisioned clients
 
-Per-brand next step for `sitedesk-code`: start **brand/consent-screen verification** to lift
-the 100-test-user cap and the 7-day re-consent measured above. That review is the slow part;
-everything else is minutes.
+| Brand | Client type | Redirect URI | Client ID | Status |
+|---|---|---|---|---|
+| `sitedesk-code` | ~~Web application~~ **RETIRED** | ~~`https://public.sitedesk.online/api/google/oauth/callback`~~ | `1032860640027-…` | **Do not use.** A Web client cannot register a loopback redirect, so this id fails `redirect_uri_mismatch` under the Desktop flow. Cleared from `brand.json`. Delete the client in the console, which revokes its secret with it — it was exposed to shell history during the manual round-trip, so it is retired rather than rotated. |
+| `sitedesk-code` | Desktop app | `http://127.0.0.1` | *(not yet created)* | Awaiting provisioning in the **existing** `Sitedesk Calendar` project. |
+
+No brand currently ships a populated `googleClientId`/`googleClientSecret`; the
+plugin is inert everywhere until one does. Per-brand next step for
+`sitedesk-code`: create the Desktop client per the runbook above, then start
+**brand/consent-screen verification** to lift the 100-test-user cap and the
+7-day re-consent. That review is the slow part; everything else is minutes.