@rubytech/create-maxy-code 0.1.472 → 0.1.474

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

@@ -1,450 +1,352 @@
 # 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.
-
-Phases 1–2 may now proceed against the flow below. Client-secret storage is decided:
-house-only at `${PLATFORM_ROOT}/config/google-house.env` (see below).
-
-## 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 recommended redirect method is a **hosted HTTPS callback on the brand's existing
-  Cloudflare tunnel domain** (a "Web application" client), with a **loopback + manual
-  code relay** (a "Desktop app" client) as the secret-less fallback.
-- **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)
+## 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`:
 
-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.
+   ```jsonc
+   // brands/<brand>/brand.json
+   "googleClientId": "<the client id>",
+   "googleClientSecret": "<the client secret>"
+   ```
 
-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)):
+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.
 
-> 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`
+### Pre-flight: confirm the client accepts loopback
+
+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.
 
-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.
+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.
 
-**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.
+Sends the client id only, never the secret. Non-mutating.
 
-## Verdict 2: OOB ("paste a code") is dead — a redirect is mandatory
+```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
+```
 
-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 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.
 
-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.
+`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:
 
-## Verdict 3: the flow — operator-assisted authorization-code (PKCE)
+```bash
+# ...append to the curl above instead of the grep chain
+| sed -E 's/.*authError=([^&]*).*/\1/' | tr '_-' '/+' | base64 -d | head -c 200
+```
 
-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.
+- `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.
 
-### Option B (recommended): hosted HTTPS callback on the brand tunnel domain
+**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.
 
-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):
+Run the probe **twice**, and read the pair:
 
-```
-https://<brand-public-host>/api/google/oauth/callback
-```
+| 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 |
 
-**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.
+`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 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:
+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.
 
-> 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/`).
+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.
 
-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.
+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:
 
-```
-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 }                          |
-   |<---------------------------------------|                                     |
+```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 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 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: 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.
+Confirm the stamp took from the boot line, which reports presence and never
+values:
 
-### Option A (fallback): loopback client + manual code relay
-
-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
+grep -m1 'google-mcp. boot' ~/.<brand>-code/logs/server.log
+# ... clientIdConfigured=true clientSecretConfigured=true
+```
 
-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.
+Either reading `false` on a brand that ships both is the mis-stamp signature.
 
-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.
+### Connecting an account, once the brand ships a client
 
-### Why the recommendation, and what the live test decides
+`google-account-register` returns a consent URL. The user opens it on any
+device and approves. Google redirects to `http://127.0.0.1:8571/?code=…`, which
+**fails to load by design** — nothing listens there, and the consenting browser
+is the user's own phone. The user copies the `code` value out of the address bar
+of that failed page and passes it to `google-account-register-submit`, which
+exchanges it in-process. `google-account-register-poll` reports the outcome at
+any point.
 
-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.
+That failed-page step is a real UX cost, 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.
 
 ---
 
-## 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 lives house-only at `${PLATFORM_ROOT}/config/google-house.env`
-(decided; see below). 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):
 
-### Installing the secret on a device (operator step, once per install)
+> 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`
 
-Nothing automates this and nothing can: the secret cannot ship in the npm
-package, so it is placed by hand after the install exists. Until it is, the
-plugin's tools load and `google-account-register` refuses with a message naming
-this file — the refusal is deliberate and happens *before* the user consents,
-so nobody burns a consent on a flow that cannot complete.
+The Calendar scope is absent, so a device-flow request carrying it is refused.
+The flow is therefore authorization-code + PKCE.
 
-On the device, with the values from the brand's Google Cloud OAuth client:
+### Out-of-band is dead, so a redirect is mandatory
 
-```bash
-INSTALL=~/<brand>-code                 # e.g. ~/sitedesk-code
-( umask 077; mkdir -p "$INSTALL/platform/config" )
-( umask 077; cat > "$INSTALL/platform/config/google-house.env" <<'EOF'
-GOOGLE_CLIENT_ID=<the client id>
-GOOGLE_CLIENT_SECRET=<the client secret>
-EOF
-)
-chmod 600 "$INSTALL/platform/config/google-house.env"
-```
+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.
 
-Then restart the install's UI service so the route picks it up.
+### The secret cannot be avoided, so the client type must sanction shipping it
 
-Confirm it took without printing the secret — the boot line reports presence
-only:
+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.
 
-```bash
-grep -m1 'google-mcp. boot' ~/.<brand>-code/logs/server.log
-# ... houseSecretPresent=true
-```
+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.
 
-`houseSecretPresent=false` on an install whose brand ships a `googleClientId`
-is the mis-provision signature. The secret is never echoed, never logged, and
-never read by the MCP process — only its presence is checked.
+Rejected, each once and for a reason:
 
-### Client-secret storage: house-only (decided 2026-07-18)
+- **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.
 
-An earlier draft of this file said the secret is "held in the brand's secret store, the same
-way Cloudflare tokens are held". That was wrong — no brand-level secret store exists. The
-decision, mirroring the Cloudflare master token exactly:
+### 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:
 
 ```
-${PLATFORM_ROOT}/config/google-house.env      # mode 600, parent 700
-GOOGLE_CLIENT_ID=…
-GOOGLE_CLIENT_SECRET=…
+http://127.0.0.1:8571
 ```
 
-Written once per install by the operator, never echoed, never in a project tree.
-`platform/plugins/cloudflare/references/api.md` already establishes this pattern for
-multi-client installs and names SiteDesk as the case: an account-wide credential inside a
-sub-account's secrets file lets that sub-account reach every other client's resources, so
-the master lives house-only at `${PLATFORM_ROOT}/config/cloudflare-house.env`, "a location
-no sub-account spawn sources". `google-house.env` is that file's twin.
-
-Rejected, with reasons:
-
-- **`brands/<brand>/brand.json`** ships inside the published npm package. It carries
-  `googleClientId` (public, exactly like `outlookClientId`, and the value the inert check
-  reads) and never the secret.
-- **`~/<brand>-code/data/accounts/<accountId>/secrets`** is wrong-scoped twice: the secret is
-  per-brand not per-account, so replicating it multiplies exposure for no benefit, and on a
-  multi-tenant install it drops a brand-wide credential into a client sub-account's own
-  directory.
-- **A Desktop-type client** (installed-app secret, documented non-confidential) would remove
-  the storage question but forces the loopback redirect and its copy-the-code-off-a-404 flow
-  on a phone, and discards the already-provisioned, verified Web-application client.
-
-House-only is sufficient here rather than merely tidier, because the token exchange runs in
-the `/api/google/oauth/callback` route inside the always-running `platform/ui` server, which
-is house-scoped. The secret never needs to reach a per-account MCP spawn.
-
-**It is a boundary of intent, not of permission.** Every account's session runs as the same
-unix user and the house path is deterministic, so an agent holding `Bash` can read the file
-regardless; OS user separation was costed and declined. Never cite house-only placement as
-proof a sub-account cannot reach the secret.
+**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`; the
+hostname is matched literally. Register `http://127.0.0.1` on the client.
 
----
+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 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 lives house-only at `${PLATFORM_ROOT}/config/google-house.env` — see 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>"
-   ```
+---
 
-### Scope
+## Scope
 
-One scope, chosen to match the Outlook calendar tool surface (read plus create, update,
-cancel, respond, free-busy), no broader:
+One scope, chosen to match the Outlook calendar tool surface (read plus create,
+update, cancel, respond, free-busy), no broader:
 
 | 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 |
 
-Notes:
+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.
 
-- `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 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.
 
-### Verification: the light kind, not the security assessment
+## Verification: the light kind, not the security assessment
 
-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.
+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.
 
 The two publishing states, and what each costs:
 
-- **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.
+- **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.
+
+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.
+
+### Recorded round-trip (2026-07-18)
+
+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.
+
+| 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 |
+
+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. Nothing in `platform/ui` participates.
 
 ---
 
-## 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.
+## 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. There is zero Google surface in
+`platform/ui`, and a test asserts the public host still refuses that path.
+
+**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.
 
 ### Provisioned clients
 
 | Brand | Client type | Redirect URI | Client ID | Status |
 |---|---|---|---|---|
-| `sitedesk-code` | Web application | `https://public.sitedesk.online/api/google/oauth/callback` | `1032860640027-p61l59fnog4mad5o7grginpaps9jnu8c.apps.googleusercontent.com` | **Testing** — round-trip verified 2026-07-18; brand verification not started; secret pending rotation into its Phase 1 home |
-
-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 secret minted at creation was
-exposed to shell history during the manual round-trip and should be rotated (**Add secret** →
-store → delete old) when Phase 1 decides where it lives.
-
-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.
+| `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.