From 1ca90d2d6f9035328806774c1fcde14851c32e3e Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:40:25 -0600 Subject: [PATCH] docs(connections): record Nov 17 Google Workspace progress in memory, checklist and plan (#22007) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The built-in Google Workspace connector is going through Google's restricted-scope review > - Three docs track that work: the working memory, the production checklist and the code-fix plan > - Four pull requests merged on November 17 and one more is open, so the docs are out of date > - This pull request updates the three docs to match the merged work and the Cloud audit results > - The benefit is one current place for decisions, scopes, shipped work and open questions ## Linked Issues or Issue Description Refs #21996, #21998, #21999, #22000, #22001 **Issue type** Outdated documentation. **Where is the issue?** `doc/memory/google-connector-memory.md`, `doc/plans/2026-11-17-google-workspace-production-checklist.md` and `doc/plans/2026-11-17-google-workspace-code-fixes.md`. **What's wrong?** The docs describe fixes 1 to 4 as not done. They plan a new npm package for the REST tool set, but the tool set is a folder inside the server. The scope table is in two files. The docs do not record the Cloud broker audit or where Google content is kept. **Suggested fix** Record what shipped, add the new decisions, keep one scope table, add the broker and data-retention findings (marked as reported), and tick the checklist items that are now true. ## What Changed - Working memory: three new decisions (no new npm packages, the scope handling contract, agents merge their PRs on the coordinator's approval at green checks and Greptile 5/5). - Working memory: new "What has shipped" table (#21996, #21998, #21999, #22001 and #22000, with merged commits). - Working memory: the single copy of the 14-scope table. "Known mismatches" now lists only what is still true after #22001. - Working memory: new "Cloud broker (paperclip-cloud)" and "Where Google content is kept" sections, from the November 17 read-only audit, marked as reported and not re-verified. - Working memory: how to create the staging tester, its two obstacles, and two new open decisions with a recommendation. - Working memory: the privacy policy draft location and what it must also cover (the OpenRouter screening model and the picker's retention statement). - Working memory: a note that the ponytail reviewer flagged the summary of Google's reply. The summary stays. - Checklist: the scope table is now one sentence with a link. Four product items are ticked with date and PR link. Items that are not fully true stay unticked. - Code-fix plan: fixes 1 to 4 marked done with PR links. Section 9 layout is now the folder inside the server. Two one-line lessons. Section 10 lists the broker changes and the deploy order. ## Verification - Each fact was checked against `gh pr view` for #21996, #21998, #21999, #22000 and #22001, and against `packages/shared/src/google-workspace-connectors.ts` and `server/src/services/tool-access/oauth/grant-refresh.ts` on `origin/master`. - The broker and data-retention facts come from an audit that this PR does not re-verify. The docs say so. - Searched the changed files for client IDs, secrets and project numbers: none. - Docs only. No tests apply. ## Risks - Low risk. Docs only. No code or behavior changes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use (shell, file edits, GitHub CLI). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- doc/memory/google-connector-memory.md | 106 ++++++++++-- .../2026-11-17-google-workspace-code-fixes.md | 151 ++++++++++++------ ...7-google-workspace-production-checklist.md | 40 +++-- 3 files changed, 221 insertions(+), 76 deletions(-) diff --git a/doc/memory/google-connector-memory.md b/doc/memory/google-connector-memory.md index 8c8bc1a299f..20910c7dfee 100644 --- a/doc/memory/google-connector-memory.md +++ b/doc/memory/google-connector-memory.md @@ -12,7 +12,7 @@ Related: [production checklist](../plans/2026-11-17-google-workspace-production- [code-fix plan](../plans/2026-11-17-google-workspace-code-fixes.md), [connector doc](../connections/GOOGLE-WORKSPACE.md). -Last updated: November 17, 2026. +Last updated: November 17, 2026 (evening). ## Decisions @@ -22,14 +22,34 @@ Last updated: November 17, 2026. | Nov 17 | **Launch on our own tools over Google's REST APIs** | Google's hosted Workspace MCP servers are still Developer Preview and cannot be offered to the public. We build our own tool set for agents that have this connector. | | Nov 17 | **The REST tool set must be swappable for Google's MCP later** | Same tool names, inputs and results as Google's MCP tools, so switching back is a change of endpoint, not a rewrite. | | Nov 17 | **The REST tool set lives in its own folder** | Nothing Google-REST-specific leaks into shared code; removing it later means deleting the folder and flipping one registration. Follow the boundary-discipline principle and `rules/module-boundaries.mdc`. | +| Nov 17 | **No new npm packages** | The REST tool set is a folder inside the server, `server/src/google-workspace-rest-tools/`, not a new package. The server is published, so a new package in its dependencies would also have to be published. | | Nov 17 | **Engineering test instance moves to staging** | Create `googletester.staging.paperclip.app`; staging is far easier to deploy to. | | Nov 17 | **Scopes must line up everywhere** | What the picker asks for, what the code accepts, what the Cloud broker allows, and what the Google Console declares are the same 14 scopes. | +| Nov 17 | **Scope handling contract** | What we **request** is strict: a request with a scope outside the 14 is rejected. What Google **reports** on a saved grant is capped to the 14 and to the saved selection, and the grant keeps working. Only a grant with nothing inside the 14 (or no scope evidence at all) needs reconnecting. | | Nov 17 | **Assessment prep starts before Google asks** | Run the scans and fix findings now; the formal assessment starts on Google's notice. | +| Nov 17 | **Agents that prepare PRs merge them** | On the coordinator's approval, once required checks pass and Greptile is 5/5. | + +## What has shipped + +| PR | What it does | Merged commit | +| --- | --- | --- | +| [#21996](https://github.com/paperclipai/paperclip/pull/21996) | Plan docs: this file, the production checklist and the code-fix plan. | `12cb18e17d` | +| [#21998](https://github.com/paperclipai/paperclip/pull/21998) | Data-use disclosure in the service picker, shown just before Google consent. Every Google Workspace sign-in start goes through the picker, including four sign-in paths on the app page (Reconnect, Connect as me, Connect organization identity, dedicated-agent connect). The Gmail read & write line says Google's screen also mentions sending and that Paperclip does not send. | `b124ad0674` | +| [#21999](https://github.com/paperclipai/paperclip/pull/21999) | Prompt-injection screening now also covers resource reads through a named gateway, the one path that was not screened. Applies to every connector, not only Google. | `65eac24876` | +| [#22001](https://github.com/paperclipai/paperclip/pull/22001) | Scope lock. `GOOGLE_WORKSPACE_SUBMITTED_SCOPES` is the hand-written list of 14, and `workspace.all` uses it. Paperclip-managed Google methods outside the 14 (Gmail archive, Chat, People, Workspace Search) are no longer offered for new setup or reconnect through Paperclip's Google app; saved ones keep refreshing and running. | `66ac5d7aa0` | +| [#22000](https://github.com/paperclipai/paperclip/pull/22000) | REST tool set part 1: the folder `server/src/google-workspace-rest-tools/` with Gmail `get_message`, `search_threads` and `create_draft`. Nothing calls it yet; the switch comes in a later PR. | `a29658b5b7` | ## Still open - **What we send to the reviewers.** Not decided: the new staging tester or something else. Whatever it is must use the separate Google app (below). +- **How reviewers reach the separate Google app.** The broker cannot point one + workspace at a different Google client (see "Environments"). + Recommendation: add a per-workspace client override to the broker so + reviewers see the real flow. +- **Reviewer login on staging.** The scoped reviewer password login is + hard-coded to the production tester. The client override above does not fix + this; how to enable the login on staging is still undecided. - **Privacy policy edits** (see "Privacy policy" below). - Which security lab to use, and the budget. - Whether Google accepts the AI-agent client setting on a client that calls @@ -44,6 +64,20 @@ Last updated: November 17, 2026. | Test 02 | In the private handoff | Staging stack used for the October proof. Holds Dotta's own Gmail grant, so not for reviewers. | | Reviewer destination | Undecided | See "Still open". | +Creating the staging tester (as reported by the Nov 17 read-only audit; not yet +done): + +1. On the staging account site, create an organization with the slug + `googletester`. That gives `googletester.staging.paperclip.app`. +2. Pin its app version with the Cloud repository's deploy-stack command. +3. Turn on `enableGoogleWorkspaceConnector`. + +Two obstacles (reported): + +- The broker cannot point one workspace at the separate Google app. Every + workspace in an environment uses that environment's one Google client. +- The scoped reviewer password login is hard-coded to the production tester. + Reviewer login: Google's reviewers could not use our normal sign-in, so we gave them **a custom password** for the Paperclip login. Any reviewer environment needs that again. The password itself goes only through the review @@ -66,9 +100,13 @@ channel. ## Scopes +This is the one copy of the scope table. Other docs link here. + One connection, three groups, **14 scopes** across all modes (9 for the default all-read-and-write selection, 8 for all read-only). Prefix: -`https://www.googleapis.com/auth/`. +`https://www.googleapis.com/auth/`. In code the list is +`GOOGLE_WORKSPACE_SUBMITTED_SCOPES` in +`packages/shared/src/google-workspace-connectors.ts`. | Group | Read only | Read & write | | --- | --- | --- | @@ -82,15 +120,55 @@ default all-read-and-write selection, 8 for all read-only). Prefix: our tool list has no send action. Never say the scope itself prevents sending. - **Out of scope:** Chat, Contacts, Directory, cross-service Search. Not in the picker, the request, the tools, the docs or the submission. +- Target: nothing outside this table is requested, declared in the Console, + or shown in the demo. The app side is done; the broker and Console are not + (below). -Known mismatches to clean up: +Known mismatches to clean up (after #22001 the app side matches the 14): -- The `workspace.all` profile in code is still the 21-scope legacy union, and - the server accepts any subset of it. -- The standalone Gmail card offers a Paperclip-managed "Read & archive" option - that requests `gmail.modify` (restricted, not in the submission). -- What the Cloud broker allows and what the Google Console declares have not - been compared with the 14 yet. +- The Cloud broker still accepts the 21-scope legacy union for `workspace.all`. +- Production still enables the legacy Chat, People and Workspace Search + profiles on our Google client. The app no longer offers them for new setup. +- The Google Console declaration has not been compared with the 14. + +## Cloud broker (paperclip-cloud) + +As reported by a read-only audit on November 17. Not re-verified here. + +- The profile registry is at `src/connections/providers.ts`. +- One Google client per environment, shared by all profile groups. Staging's + client differs from production's. +- `workspace.all` is enabled on staging only. +- There is no `gmail.archive` profile. +- A revoke endpoint exists, but every Google profile has revocation turned off. +- There is no per-workspace client override. + +Changes needed in the broker: + +| Change | Why | +| --- | --- | +| Limit `workspace.all` to the 14 | It still accepts the 21-scope union. | +| On refresh and claim, cap reported scopes to the 14 instead of failing | Matches the app's scope handling contract; saved grants keep working. | +| Keep accepting the old 21-scope refresh binding until older app versions are gone | Older apps still sign 21 scopes on refresh. | +| Stop offering Chat, People and Search for new sessions on the verified client | They are outside the 14. Keep refresh for saved grants. | +| Do not merge the branch that adds a Gmail archive profile | `gmail.modify` is restricted and not in the submission. | + +Deploy order: **app first, then broker.** If the broker narrows first, refresh +from app versions that still sign 21 scopes fails. + +## Where Google content is kept + +As reported by the same November 17 audit. Not re-verified here. + +| Place | What is kept | How long | +| --- | --- | --- | +| Tool-call audit record | About 4,000 characters of each result | No retention limit. Survives task deletion and connection removal. | +| Run transcripts | Full content | No delete path. | +| Stored run-log files | Run output | Company deletion removes database rows; the audit found no deletion of these files. | +| Optional model check for injection screening | If a company turns it on, the full tool result is sent to an OpenRouter model | Not covered by the audit. | +| Connection removal | Deletes tokens locally | Does not revoke at Google. | + +Planned fix: a "delete data read through this connection" action. ## Google review history @@ -106,13 +184,21 @@ Known mismatches to clean up: - The older videos and replies describe separate per-service connectors and removed services. Do not reuse them. +Note: on #21996 the ponytail reviewer flagged the October 7 summary above as +review correspondence in a public repository. We kept the summary. + ## Privacy policy - Lives in the `paperclip-website` repository at `web/app/privacy/page.tsx`, published at . Last updated July 23, 2026. - It already has what Google looks for first: a Google user data section (4.1) with the Limited Use statement and links to Google's policy. -- Gaps found November 17, not yet fixed: +- The draft edits are in paperclipai/paperclip-website PR 197 (draft, awaiting + Dotta's sign-off on the wording). It must also: + - cover the OpenRouter model used by the optional injection-screening check; + - match the picker's statement that results stay in task and run history + until deleted. +- Gaps found November 17, to be fixed by that PR: - It does not say that Google content is sent to AI model providers to carry out tasks. It only names "cloud hosting and infrastructure providers". - It says connected-account data is kept only while the connection is active. diff --git a/doc/plans/2026-11-17-google-workspace-code-fixes.md b/doc/plans/2026-11-17-google-workspace-code-fixes.md index 528e570cbde..469fedffbe6 100644 --- a/doc/plans/2026-11-17-google-workspace-code-fixes.md +++ b/doc/plans/2026-11-17-google-workspace-code-fixes.md @@ -6,28 +6,35 @@ land. It covers section 2 of the Based on a read of master at `56654adecd`. Items marked **confirmed** were seen in the code. Items marked **to check** are suspected gaps that need a look -before any change. Nothing here has been implemented. +before any change. Fixes 1 to 4 landed on November 17. Work on fixes 9 and +10 has started. Fixes 5 to 8 are not started. -Each fix is its own pull request with a failing test first. Work that changes -what the Cloud broker accepts ships broker first, then the app. +Each fix is its own pull request with a failing test first. For the scope +change in fix 2, the deploy order is app first, then broker (see fix 10). ## Order -| # | Fix | Size | Blocks submission | -| --- | --- | --- | --- | -| 1 | Data-use disclosure in the picker | Small | Yes | -| 2 | Lock the managed scope set to 14 | Small to medium | Yes | -| 3 | Take `gmail.modify` off the Paperclip-managed client | Small | Yes | -| 4 | Confirm injection screening on Google results | Check, then small | Yes | -| 5 | Revoke at Google on last disconnect | Medium | Likely | -| 6 | Retention and deletion of Google content | Audit, then unknown | Yes | -| 7 | Security scan findings | Unknown | Yes (assessment) | -| 8 | Remove the experimental gate | Small | No, release step | -| 9 | REST-backed tool set | Large | Yes | -| 10 | Scope cleanup across code, Cloud and Console | Medium | Yes | +| # | Fix | Size | Blocks submission | Status | +| --- | --- | --- | --- | --- | +| 1 | Data-use disclosure in the picker | Small | Yes | Done, [#21998](https://github.com/paperclipai/paperclip/pull/21998) | +| 2 | Lock the managed scope set to 14 | Small to medium | Yes | Done in the app, [#22001](https://github.com/paperclipai/paperclip/pull/22001) | +| 3 | Take `gmail.modify` off the Paperclip-managed client | Small | Yes | Done, [#22001](https://github.com/paperclipai/paperclip/pull/22001) | +| 4 | Confirm injection screening on Google results | Check, then small | Yes | Done, [#21999](https://github.com/paperclipai/paperclip/pull/21999) | +| 5 | Revoke at Google on last disconnect | Medium | Likely | Not started | +| 6 | Retention and deletion of Google content | Audit, then unknown | Yes | Audit reported; fix not started | +| 7 | Security scan findings | Unknown | Yes (assessment) | Not started | +| 8 | Remove the experimental gate | Small | No, release step | Not started | +| 9 | REST-backed tool set | Large | Yes | Part 1 merged Nov 17, [#22000](https://github.com/paperclipai/paperclip/pull/22000) | +| 10 | Scope cleanup across code, Cloud and Console | Medium | Yes | App done; broker and Console open | ## 1. Data-use disclosure in the picker +**Done** (Nov 17, [#21998](https://github.com/paperclipai/paperclip/pull/21998)). +Every Google Workspace sign-in start now goes through the picker, including +four sign-in paths on the app page. The Gmail read & write line says Google's +screen also mentions sending and that Paperclip does not send. The plan below +is kept for reference. + **Confirmed gap.** `ServicePicker` in `ui/src/features/connections/GoogleWorkspaceServices.tsx` shows three service rows and Cancel / Continue. Its only description is screen-reader text. Google @@ -58,6 +65,12 @@ the wording. ## 2. Lock the managed scope set to 14 +**Done in the app** (Nov 17, [#22001](https://github.com/paperclipai/paperclip/pull/22001)). +`GOOGLE_WORKSPACE_SUBMITTED_SCOPES` is the hand-written list of 14 and +`workspace.all` uses it. Requests outside the 14 are rejected; scopes Google +reports on a saved grant are capped to the 14 instead of failing it. The +broker change is in fix 10. The plan below is kept for reference. + **Confirmed.** The selector derives scopes from `GOOGLE_WORKSPACE_SERVICE_GROUPS` in `packages/shared/src/google-workspace-connectors.ts`, which yields 14 scopes @@ -77,10 +90,16 @@ and `isGoogleWorkspaceScopeGrant` accepts any subset of those 21. stable for the broker contract). If so, add a separate 14-scope constant and leave the legacy definition for old grants. - Companion change in the Cloud broker registry so the production client - cannot be asked for the other 7. Broker first, then app. + cannot be asked for the other 7. App first, then broker (fix 10). ## 3. Take `gmail.modify` off the Paperclip-managed client +**Done** (Nov 17, [#22001](https://github.com/paperclipai/paperclip/pull/22001)). +Gmail archive, Chat, People and Workspace Search managed methods are no longer +offered for new setup or reconnect; saved connections keep refreshing and +running. The broker has no `gmail.archive` profile. The plan below is kept for +reference. + **Confirmed.** `packages/shared/src/app-definitions/gmail.json` has a `paperclip-archive` method ("Connect with Paperclip", profile `gmail.archive`) that requests `gmail.modify`, a restricted scope that is not in the @@ -103,6 +122,12 @@ client requests an undeclared restricted scope. ## 4. Confirm injection screening on Google results +**Done** (Nov 17, [#21999](https://github.com/paperclipai/paperclip/pull/21999)). +Every path was traced and tested. The one unscreened path, resource reads +through a named gateway, is now screened for every connector. What screening +does and does not cover is in `doc/prompt-injection-prevention.md`. The plan +below is kept for reference. + **To check.** Tool-result screening exists (`doc/prompt-injection-prevention.md`): built-in detection is always on, and a model check is optional per company. Not yet confirmed that every Google @@ -140,6 +165,10 @@ comments, run history, tool results and attachments. Disconnecting does not delete any of it. Google requires that users can delete their data and that we document how. +Audit findings (Nov 17, as reported) are in the working memory under "Where +Google content is kept". The planned fix is a "delete data read through this +connection" action. + - Inventory where Google tool results are stored and for how long. - Confirm that deleting a task or a workspace removes them. - Decide with the privacy owner whether an explicit "delete data from this @@ -169,8 +198,10 @@ document how. Decision: launch on our own tools over Google's REST APIs, designed so we can switch to Google's hosted MCP servers later, kept in one folder so it can be -deleted cleanly. This is a design to confirm against the dispatch code before -building; the dispatch path has not been traced yet. +deleted cleanly. Part 1 is +[#22000](https://github.com/paperclipai/paperclip/pull/22000) (merged Nov 17): the +folder and Gmail `get_message`, `search_threads` and `create_draft`. Its README +records the dispatch trace and the recommended in-process seam. ### The seam @@ -188,39 +219,42 @@ registry returns. ### Layout -One new package, following `packages/google-sheets-mcp-server`: +One folder inside the existing server, not a new package. No new dependency, +workspace or release change. ``` -packages/google-workspace-rest-tools/ - src/ - index.ts the only export: create the server / handle a call - server.ts MCP wiring (list tools, call tool); thin - google-http.ts the one place that calls googleapis.com: auth header, - errors mapped to MCP errors, retry rules - gmail/ one file per tool: args in, REST request out, - drive/ REST response in, MCP result out (pure functions) - docs/ - sheets/ - slides/ - calendar/ - schemas/ tool definitions copied from Google's MCP reference +server/src/google-workspace-rest-tools/ + index.ts the only entry point: create the server / handle a call + server.ts MCP wiring (list tools, call tool); thin + google-http.ts the one place that calls googleapis.com: auth header, + allowed hosts, errors mapped to MCP errors, retry rules + tools.ts, tool.ts the tool list and the shared tool shape + errors.ts + README.md boundary rules, dispatch trace, differences from Google + gmail/ one file per tool, plus schemas and helpers + drive/ (later) args in, REST request out, + docs/ REST response in, MCP result out + sheets/ + slides/ + calendar/ ``` ### Boundary rules - **One switch.** The registry gains a transport choice per service (`google_mcp` or `paperclip_rest`). That choice, plus registering the - package, is the only Google-REST knowledge outside the folder. -- **No REST types leave the package.** Its public surface is MCP tool - definitions and MCP results. -- **Nothing in the package knows about Paperclip.** No company, connection, + folder, is the only Google-REST knowledge outside the folder. +- **No REST types leave the folder.** Its public surface is MCP tool + definitions and MCP results. A boundary test limits its imports to its own + files, Node built-ins, the MCP SDK and `zod`. +- **Nothing in the folder knows about Paperclip.** No company, connection, grant, policy or audit code. It receives a tool name, arguments and an access token, and returns a result. Authorization, scope checks, approval, audit and injection screening stay with their current owners in the gateway. - **It stores nothing.** No tokens, no content, no cache. - **The allowlist stays where it is.** `toolScopes` in `google-workspace-connectors.ts` remains the single list of allowed tools; - the package implements exactly that list, and a test fails if the two differ. + the folder implements exactly that list, and a test fails if the two differ. - **Removal test.** Deleting the folder and setting the switch to `google_mcp` leaves a build that passes. Add this as a checklist item for the removal PR. @@ -231,15 +265,16 @@ packages/google-workspace-rest-tools/ listing from Google's servers (we can record it on our enrolled internal account). - Where REST cannot match an MCP tool's behavior exactly, write the difference - in the package README rather than hiding it. + in the folder's README rather than hiding it. ### Order of work -1. Trace the dispatch path and confirm the seam (in-process handler or a - loopback HTTP endpoint; whichever the gateway already supports). -2. Package skeleton, `google-http.ts`, the switch, and Gmail `get_message`, - `search_threads` and `create_draft`, end to end on the staging tester. - The demo depends on Gmail. +1. Trace the dispatch path and confirm the seam. Traced in #22000's README: + an in-process call, because the egress guard refuses a loopback address on + public deployments. +2. Folder skeleton, `google-http.ts`, and Gmail `get_message`, + `search_threads` and `create_draft` (#22000, merged). Then the switch, end to + end on the staging tester. The demo depends on Gmail. 3. Rest of Gmail, then Calendar, Drive, Docs, Sheets, Slides. 4. Contract and removal tests. @@ -247,26 +282,44 @@ Tools to build (36): Gmail 9, Drive 8, Docs 2, Sheets 6, Slides 2, Calendar 9. ### To check -- Whether the gateway can call an in-process MCP handler or needs an address. - Whether a Google client marked for AI agents may call the REST APIs. - Each Cloud project needs the six REST APIs enabled. - Speed: this sits in the tool-call path, so measure added time per call. +### Lessons + +- **Address parsing:** patching a split-on-commas parser case by case kept + breaking (comments, groups, IPv6 literals); write one RFC 5322 tokenizer with + table-driven tests from the start. +- **No new package:** the server is published, so a new package it depends on + would also need publishing; a folder inside the server avoids that. + ## 10. Scope cleanup across code, Cloud and Console Decision (November 17): what we ask for, what the code accepts, what the Cloud broker allows and what the Console declares must be the same 14 scopes. -Fixes 2 and 3 cover this repository. Also needed: +Fixes 2 and 3 cover this repository and are done. Still needed in the Cloud +broker (`paperclip-cloud`, registry at `src/connections/providers.ts`, as +reported by the Nov 17 audit): + +- Limit `workspace.all` to the 14. +- On refresh and claim, cap reported scopes to the 14 instead of failing, and + keep accepting the old 21-scope refresh binding until older app versions are + gone. +- Stop offering Chat, People and Search for new sessions on the verified + client. +- Do not merge the branch that adds a Gmail archive profile. +- Deploy order: app first, then broker. + +Also needed: -- Compare the broker's profile registry in `paperclip-cloud` with the 14 and - remove or fence the rest for the Paperclip-managed client. - Compare the Console declaration for both Google apps with the 14 (needs the project owner's sign-in). -- One table in the working memory showing all four side by side, kept current. +- Keep the working memory's "Scopes" and "Cloud broker" sections current. ## Not code, but needed by these fixes - Published privacy policy and Limited Use statement URLs (fix 1). - Sign-off on disclosure wording (fix 1). -- Broker changes in the Cloud repository (fixes 2, 3, 5). +- Broker changes in the Cloud repository (fixes 5 and 10). - Current broker profile settings for staging and production (fixes 2, 3). diff --git a/doc/plans/2026-11-17-google-workspace-production-checklist.md b/doc/plans/2026-11-17-google-workspace-production-checklist.md index f3bf9a43c3b..f8b53a309d3 100644 --- a/doc/plans/2026-11-17-google-workspace-production-checklist.md +++ b/doc/plans/2026-11-17-google-workspace-production-checklist.md @@ -21,16 +21,10 @@ operator handoff, never here. ## The scope contract -One connection, three groups, 14 scopes in total across all modes. All have -the prefix `https://www.googleapis.com/auth/`. Nothing outside this table is -requested, declared in the Console, or shown in the demo. - -| Group | Read only | Read & write | Google category | -| --- | --- | --- | --- | -| Gmail | `gmail.readonly` | `gmail.readonly`, `gmail.compose` | Restricted | -| Drive | `drive.readonly` | `drive.readonly`, `drive.file` | `drive.readonly` restricted | -| Docs, Sheets, Slides | `documents.readonly`, `spreadsheets.readonly`, `presentations.readonly` | `documents`, `spreadsheets`, `presentations` | Sensitive | -| Calendar | `calendar.calendarlist.readonly`, `calendar.events.readonly`, `calendar.events.freebusy` | `calendar.calendarlist.readonly`, `calendar.events` | Sensitive | +One connection, 14 scopes; the table is in the working memory's +[Scopes](../memory/google-connector-memory.md#scopes) section. The target is +that nothing outside it is requested, declared in the Console, or shown in the +demo. ## 0. Decisions (Dotta) @@ -52,7 +46,7 @@ Decisions and the details behind them are kept in the ## 1. Baseline (needs the Google project owner's sign-in) - [ ] Verification Center: is the case pending, waiting on us, or closed? -- [ ] Record the scopes declared in the Console and compare with the table above. +- [ ] Record the scopes declared in the Console and compare with the 14. - [ ] Every OAuth client that calls Workspace MCP is marked as an AI-agent client; note any that missed the November cutoff and need replacing. - [ ] Separate QA project is External and In Production, with user count noted. @@ -64,16 +58,25 @@ Decisions and the details behind them are kept in the ## 2. Product and code (see the code-fix plan) -- [ ] Data-use disclosure shown in the picker immediately before Google consent. +- [x] Data-use disclosure shown in the picker immediately before Google consent + (Nov 17, [#21998](https://github.com/paperclipai/paperclip/pull/21998)). - [ ] Limited Use statement published and linked from the picker. - [ ] Help page: how to disconnect and how to delete stored Google data. -- [ ] Paperclip-managed Google sign-in can only ever request the 14 scopes. -- [ ] `gmail.modify` is not reachable through the Paperclip-managed client. -- [ ] Prompt-injection screening confirmed on every Google tool result. +- [x] Paperclip-managed Google sign-in can only request the 14 scopes for the + unified connection (Nov 17, + [#22001](https://github.com/paperclipai/paperclip/pull/22001)). The Cloud + broker still accepts more; see the working memory. +- [x] `gmail.modify` is not reachable through the Paperclip-managed client + (Nov 17, [#22001](https://github.com/paperclipai/paperclip/pull/22001)). +- [x] Prompt-injection screening confirmed on every Google tool result + (Nov 17, [#21999](https://github.com/paperclipai/paperclip/pull/21999)). - [ ] Disconnecting the last Google connection revokes the grant at Google. - [ ] Retention and deletion of Google content in tasks, runs and files audited. -- [ ] REST-backed tool set for all 36 actions, in its own folder, with the same - tool names and shapes as Google's MCP tools. +- [ ] REST-backed tool set for all 36 actions, in its own folder inside the + server, with the same tool names and shapes as Google's MCP tools + (part 1, three Gmail tools: + [#22000](https://github.com/paperclipai/paperclip/pull/22000), merged + Nov 17; not yet called by the gateway). - [ ] Scopes identical in the picker, the server, the Cloud broker and the Google Console. - [ ] `googletester.staging.paperclip.app` created and wired to the new Google @@ -152,6 +155,9 @@ The policy is in the `paperclip-website` repository - [ ] Console declaration updated to the 14 scopes. - [ ] Point-by-point reply to Google's October 7 message drafted. + Note: the ponytail reviewer flagged the summary of Google's reply in the + working memory's review history as review correspondence; we kept the + summary. - [ ] Reviewer login and steps tested by someone who has not seen the app. - [ ] Dotta approves sending. - [ ] Console update submitted once and reply sent in the existing case.