From 12cb18e17d0a7ee24ba90d325a8eacaba44c59dc Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 17 Nov 2026 06:57:30 -0600 Subject: [PATCH] docs(connections): Google Workspace approval checklist, code-fix plan and working memory (#21996) 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 lets agents read and write Gmail, Drive, Docs, Sheets, Slides and Calendar data > - The connector stays behind an experimental setting until Google approves its data access and the security assessment is accepted > - The approval work has many steps, and the decisions behind them were spread across chats and private notes > - This pull request adds one checklist, one code-fix plan and one temporary working-memory file for that effort > - The benefit is that contributors and agents share one source for the scope contract, the decisions and the remaining work ## Linked Issues or Issue Description **Type of issue** Missing documentation for an in-progress effort. **Description** The Google Workspace connector needs Google approval before it can go to all users. There is no single document that lists what "approved and released" means, which code changes must land before submission, or the decisions taken so far (launch transport, owner, test instance, 14-scope contract). **Proposed change** Add a production and approval checklist, a code-fix plan for section 2 of that checklist, and a temporary working-memory file. Keep identifiers, credentials and review correspondence out of the public repository. ## What Changed - Added `doc/plans/2026-11-17-google-workspace-production-checklist.md`: the "done means" criteria, the 14-scope contract, and checklists for decisions, baseline, product and code, policy, security assessment, reviewer environment, live acceptance, demo video, submission, release and ongoing work. - Added `doc/plans/2026-11-17-google-workspace-code-fixes.md`: ten ordered code fixes (disclosure in the picker, scope lock to 14, `gmail.modify` removal from the managed client, injection screening check, revoke on last disconnect, retention audit, scan findings, gate removal, REST-backed tool set, scope cleanup). Each item is marked confirmed or to check. - Added `doc/memory/google-connector-memory.md`: a temporary file with decisions, open questions, environments, Google app layout, scopes, review history and privacy-policy gaps. It says to delete it once the connector is released. ## Verification - Docs only. No code, schema or test changes. - Read all three files before the push and confirmed that they contain no passwords, client IDs, client secrets, project numbers or review login codes. - Relative links between the three files and to `doc/connections/GOOGLE-WORKSPACE.md` resolve in the repository. - CI checks on this PR. ## Risks - Low risk. Documentation only. - The plans describe intended work. Some items are marked "to check" and can change after the code is traced. - The working-memory file is temporary and must be deleted after release. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`, Anthropic), used through Claude Code with tool use (shell, git, GitHub CLI) to commit the files and open this PR. ## 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 - [ ] All Paperclip CI gates are green - [ ] 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 | 134 +++++++++ .../2026-11-17-google-workspace-code-fixes.md | 272 ++++++++++++++++++ ...7-google-workspace-production-checklist.md | 173 +++++++++++ 3 files changed, 579 insertions(+) create mode 100644 doc/memory/google-connector-memory.md create mode 100644 doc/plans/2026-11-17-google-workspace-code-fixes.md create mode 100644 doc/plans/2026-11-17-google-workspace-production-checklist.md diff --git a/doc/memory/google-connector-memory.md b/doc/memory/google-connector-memory.md new file mode 100644 index 00000000000..8c8bc1a299f --- /dev/null +++ b/doc/memory/google-connector-memory.md @@ -0,0 +1,134 @@ +# Google connector working memory + +Temporary. Holds the decisions and details we keep needing while the built-in +Google Workspace connector goes through Google approval and into production. +Delete this file once the connector is approved and released. + +This repository is public. Keep passwords, client IDs and secrets, project +numbers, review login codes and review correspondence out of this file; they +live in the private operator handoff. + +Related: [production checklist](../plans/2026-11-17-google-workspace-production-checklist.md), +[code-fix plan](../plans/2026-11-17-google-workspace-code-fixes.md), +[connector doc](../connections/GOOGLE-WORKSPACE.md). + +Last updated: November 17, 2026. + +## Decisions + +| Date | Decision | Detail | +| --- | --- | --- | +| Nov 17 | **Owner for everything is Dotta** | Submission, security, privacy and release. | +| 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 | **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 | **Assessment prep starts before Google asks** | Run the scans and fix findings now; the formal assessment starts on Google's notice. | + +## 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). +- **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 + the REST APIs rather than MCP. To check before the staging tester is wired. + +## Environments + +| Name | Address | Notes | +| --- | --- | --- | +| Earlier tester | `googletester.paperclip.app` (company prefix `GOO`) | On **production**. Used for earlier tests. Hard to deploy to; do not build on it further. | +| New tester | `googletester.staging.paperclip.app` | **To be created** on staging. Engineering qualification happens here. | +| 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". | + +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 +channel. + +## Google apps (Cloud projects) + +| App | Purpose | State | +| --- | --- | --- | +| Original production app | The one under Google verification | It was released to more than 100 users while unverified and hit Google's 100-user cap. **Nobody new can sign in or sign up with it** until it is verified. | +| New app for us and the tester | Created so we and Google's reviewers can sign in at all | Separate Cloud project, set to In Production. Google asked for exactly this in its October 7 message. The reviewer environment must use this app's client. | + +- The client labelled "managed staging" belongs to the original production + app, despite the name. A flow that used it does not satisfy Google's + separate-project request. +- Verification is of the original production app; the new app only gives + reviewers a way in. +- With the REST transport, each project needs the Gmail, Drive, Docs, Sheets, + Slides and Calendar APIs enabled, not the MCP APIs. + +## Scopes + +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/`. + +| Group | Read only | Read & write | +| --- | --- | --- | +| Gmail | `gmail.readonly` | `gmail.readonly`, `gmail.compose` | +| Drive, Docs, Sheets, Slides | `drive.readonly`, `documents.readonly`, `spreadsheets.readonly`, `presentations.readonly` | `drive.readonly`, `drive.file`, `documents`, `spreadsheets`, `presentations` | +| Calendar | `calendar.calendarlist.readonly`, `calendar.events.readonly`, `calendar.events.freebusy` | `calendar.calendarlist.readonly`, `calendar.events` | + +- **Restricted (trigger the security assessment):** `gmail.readonly`, + `gmail.compose`, `drive.readonly`. +- **Gmail write means drafts only.** `gmail.compose` would let an app send; + 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. + +Known mismatches to clean up: + +- 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. + +## Google review history + +- September 30: we sent a revised submission. +- October 7: Google replied. Reviewers could not sign in because of the + 100-user cap, and the video did not show `gmail.readonly` working end to end. + They asked for a separate test project set to In Production, working reviewer + login, and a new video showing a full email in Paperclip and then the same + email in Gmail. +- No newer message from Google as of November 15. +- Branding was verified at the last Console check; data access was still under + review. Not rechecked since. +- The older videos and replies describe separate per-service connectors and + removed services. Do not reuse them. + +## 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: + - 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. + In the product, email and file content that an agent read stays in task and + run history after disconnect. + - It says "read or send access to Gmail". We create drafts and do not send. + - It names `connect.paperclip.ing` as the sign-in path; check that this + matches the current flow. + - It gives no steps or timeline for deleting data. + +## Other things to remember + +- Security assessment: Google assigns the tier, we choose and pay the lab, + and it repeats every 12 months. +- The connector is behind the default-off `enableGoogleWorkspaceConnector` + experimental setting until Google approves. +- The synthetic test email has the marker `PAPERCLIP-QA-BODY-20261028`. +- The October 31 live evidence predates many changes to the sign-in code and + must be redone. diff --git a/doc/plans/2026-11-17-google-workspace-code-fixes.md b/doc/plans/2026-11-17-google-workspace-code-fixes.md new file mode 100644 index 00000000000..528e570cbde --- /dev/null +++ b/doc/plans/2026-11-17-google-workspace-code-fixes.md @@ -0,0 +1,272 @@ +# Google Workspace connector: code fixes before submission + +Started November 17, 2026. Temporary working plan; delete it once the items +land. It covers section 2 of the +[production checklist](2026-11-17-google-workspace-production-checklist.md). + +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. + +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. + +## 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 | + +## 1. Data-use disclosure in the picker + +**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 +requires a disclosure inside the app, immediately before consent, that says +what data is accessed and how it is used and shared; a privacy-policy link +alone does not count. + +- Add a short visible block above the footer, built from the current selection: + what Paperclip will be able to read and change for the chosen services, that + agents send this content to the model provider configured for the workspace + to do the tasks they are given, that it is not used to train general models, + and where results are stored. +- Link the privacy policy and the Limited Use statement. +- The copy changes with the selection (read only versus read & write; Gmail + write says "create drafts", never "send"). +- Show it for new setup and for reconnect, in both the Apps flow and the + task-hosted flow (both use `GoogleWorkspaceServicesDialog`). +- Tests in `GoogleWorkspaceServices.test.tsx`: disclosure present for each + selection, absent wording for unselected services, links present. +- Update the Storybook story under + `ui/storybook/stories/connection-setup/google-workspace-services.stories.tsx`. +- Follow `DESIGN.md` (tokens only, form footer rules). + +Link to (section 4.1 holds the Limited Use +statement). The disclosure wording must agree with that policy, so the policy +edits listed in the working memory land first or together. Dotta signs off +the wording. + +## 2. Lock the managed scope set to 14 + +**Confirmed.** The selector derives scopes from +`GOOGLE_WORKSPACE_SERVICE_GROUPS` in +`packages/shared/src/google-workspace-connectors.ts`, which yields 14 scopes +across all modes. But the `workspace.all` profile is still the 21-scope legacy +union (Chat, Contacts, Directory, profile and `calendar.readonly` included), +and `isGoogleWorkspaceScopeGrant` accepts any subset of those 21. + +- Add a test that the union of every selectable combination equals an explicit + list of the 14 scopes, so a new scope cannot slip in unnoticed. Today's tests + pin 9 (default) and 21 (legacy) only. +- Add a server test that an authorization request for the unified connection + carrying any scope outside the 14 is rejected, for both the managed and the + customer-owned path. +- Narrow `isGoogleWorkspaceScopeGrant` for the unified connection to the 14. + **To check first:** whether saved grants or the broker's sealed envelopes + depend on the 21-scope definition (the code comment says the union is kept + 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. + +## 3. Take `gmail.modify` off the Paperclip-managed client + +**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 +submission. If the production broker ever enables that profile, the verified +client requests an undeclared restricted scope. + +- Remove the `paperclip-archive` method, or gate it so it can never use the + Paperclip-managed client. Keep `customer-archive-oauth` (the customer's own + Google client is outside our verification). +- Keep `server/src/services/gmail-archive-tool-policy.ts` working for saved + connections. +- **To check:** whether any saved connection uses `paperclip-archive`, and + whether the production or staging broker has `gmail.archive` enabled. +- Do the same inventory for every other "Connect with Paperclip" Google method + in `packages/shared/src/app-definitions/google-*.json` and `gmail.json` + (Chat, People, Workspace Search and the per-service cards): each one that can + reach the managed client either stays within the 14 scopes or loses its + managed method. +- Test: no app definition with the managed strategy lists a scope outside the 14. + +## 4. Confirm injection screening on Google results + +**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 +Workspace tool result passes through it, in particular email bodies and file +content fetched through the unified connection. + +- Trace a `gmail__get_message` and a `drive__read_file_content` call from the + gateway to the runner and confirm the guard runs on the result. +- Add a test with an injected instruction inside an email body and inside a + document, expecting `prompt_injection_blocked`. +- Fix any path that skips the guard. +- Write two paragraphs for the submission describing what the screening does + and does not protect against. + +## 5. Revoke at Google on last disconnect + +**Confirmed behavior, likely gap.** Removing a managed Google connection is +local only, because Google's revoke ends every grant for that user on the +client and would break their other Google connections +(`doc/connections/GOOGLE-WORKSPACE.md`). With one unified connection that +reasoning mostly goes away, and reviewers expect disconnect to end access. + +- When a user removes their last grant on the Paperclip-managed Google client, + call Google's revoke endpoint through the broker. +- If other grants for the same Google account remain, stay local and say so in + the confirmation text. +- Tests: last grant revokes; one of two does not; a revoke failure still + removes the local credential and reports the failure. +- Needs a broker endpoint; broker first. + +## 6. Retention and deletion of Google content + +**To check.** Email and file content returned by tools is stored in task +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. + +- 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 + connection" action is needed. If the answer is yes, that becomes its own plan. +- Write the user help page either way. + +## 7. Security scan findings + +- Run the static and dynamic scans used for the CASA self-assessment against + the server, the broker and the reviewer instance. +- Triage findings into fix now, accepted with reason, and not applicable. +- One pull request per finding class. + +## 8. Remove the experimental gate (release step, last) + +**Confirmed.** `enableGoogleWorkspaceConnector` defaults to off +(`packages/shared/src/validators/instance.ts`, set on the app definition in +`google-workspace.json`, enforced in `tool-gateway.ts`, +`connection-intents.ts` and `setup-policy.ts`). + +- After Google approves: default it on, or remove the key and its checks. +- Update `doc/connections/GOOGLE-WORKSPACE.md` and the release notes. +- Decide what happens to the aggregator Google apps that appear while the gate + is off. + +## 9. REST-backed tool set (chosen November 17) + +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. + +### The seam + +Today the unified connection sends each tool call, with the user's Google +access token, to a Google MCP endpoint chosen by a closed registry in +`packages/shared/src/google-workspace-connectors.ts` (`serverUrl` per service). +Everything above that point (picker, scopes, grant checks, allowlist, approval, +audit, injection screening) only knows tool names and required scopes. + +So the replacement is **an MCP server of our own that exposes the same tools +as Google's**: same names, same input fields, same result shape, backed by +REST. The rest of the system keeps speaking MCP to it and cannot tell the +difference. Switching to Google's MCP later is changing which endpoint the +registry returns. + +### Layout + +One new package, following `packages/google-sheets-mcp-server`: + +``` +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 +``` + +### 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, + 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. +- **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. + +### Parity + +- Tool names and schemas come from Google's published MCP tool reference, not + from our guess. A contract test compares our definitions with a recorded + 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. + +### 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. +3. Rest of Gmail, then Calendar, Drive, Docs, Sheets, Slides. +4. Contract and removal tests. + +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. + +## 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: + +- 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. + +## 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). +- 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 new file mode 100644 index 00000000000..f3bf9a43c3b --- /dev/null +++ b/doc/plans/2026-11-17-google-workspace-production-checklist.md @@ -0,0 +1,173 @@ +# Google Workspace connector: production and Google approval checklist + +Started November 17, 2026. This is the north star for getting the built-in +Google Workspace connector approved by Google and released to all users. Tick +items only when the evidence exists; add the date and a link next to the tick. + +Background: [approval handoff](https://github.com/paperclipai/paperclip/blob/codex/google-workspace-draft-resume/doc/plans/2026-11-15-google-workspace-approval-handoff.md), +[connector doc](../connections/GOOGLE-WORKSPACE.md), +[code-fix plan](2026-11-17-google-workspace-code-fixes.md). +Account identifiers, credentials and review correspondence stay in the private +operator handoff, never here. + +## Done means + +- [ ] Google has explicitly approved data access for the exact scopes we request. +- [ ] The security assessment letter is accepted by Google. +- [ ] The connector is on for all users in production without the experimental + setting, on a transport Google allows for public use. +- [ ] A new user can connect, run a task that reads and writes Google data, and + disconnect, on production. + +## 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 | + +## 0. Decisions (Dotta) + +Decisions and the details behind them are kept in the +[working memory](../memory/google-connector-memory.md). + +- [x] **Launch transport** (Nov 17): our own tools over Google's REST APIs, + built so we can switch to Google's MCP servers later. +- [x] **Owner** (Nov 17): Dotta owns submission, security, privacy and release. +- [x] **Engineering test instance** (Nov 17): create + `googletester.staging.paperclip.app`. +- [ ] What we send to the reviewers (the staging tester or something else), + including the custom reviewer password. +- [ ] Privacy policy edits approved. +- [ ] Security lab and budget. +- [ ] Email the Developer Preview team asking for permission to offer the MCP + integration publicly (optional now, still cheap). + +## 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. +- [ ] 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. +- [ ] Reviewer callback URL is registered on the QA client. +- [ ] Branding preflight: homepage, privacy policy on the app domain and on the + consent screen, verified domain, staffed support and developer contacts. +- [ ] Record the revision served by the reviewer environment. +- [ ] Check whether the daily OAuth monitor is still scheduled. + +## 2. Product and code (see the code-fix plan) + +- [ ] Data-use disclosure shown in the picker immediately before Google consent. +- [ ] 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. +- [ ] 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. +- [ ] 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 + app. + +## 3. Policy and privacy + +The policy is in the `paperclip-website` repository +(`web/app/privacy/page.tsx`, ). + +- [x] Policy has a Google user data section with the Limited Use statement. +- [x] Policy states that Google data is not used to train general models. +- [ ] Policy says Google content is sent to AI model providers to carry out + tasks, and names them or the category. +- [ ] Policy's retention wording matches the product (content read by agents + stays in task and run history after disconnect), or the product changes. +- [ ] Policy says Gmail drafts, not "send". +- [ ] Policy gives the steps and timeline for deleting data. +- [ ] Policy's description of the sign-in path matches the current flow. +- [ ] Model-provider terms and settings checked against that statement. +- [ ] Data-flow inventory written: Google, broker, server, runner, model + provider, storage, support and diagnostics. +- [ ] Scope justification written for each of the 14 scopes, including why a + narrower scope does not work. + +## 4. Security assessment (CASA) + +- [ ] Run static and dynamic scans against the CASA requirements ourselves. +- [ ] Fix or document every finding. +- [ ] Draft the self-assessment questionnaire. +- [ ] Choose a Google-authorized lab and get a quote. +- [ ] Google's assessment notice received (tier recorded). +- [ ] Lab validation passed. +- [ ] Letter of Assessment sent to Google. +- [ ] Renewal date and owner recorded (every 12 months). + +## 5. Reviewer environment + +- [ ] Instance deployed on a current build and wired to the separate QA project. +- [ ] Confirmed from a real authorization request that the QA client is the one + used. +- [ ] Dedicated test Google account with synthetic mail, files and events. +- [ ] Reviewer login works without phone, payment or other blockers. +- [ ] Fresh reviewer can connect and run their own model-backed task. +- [ ] No access from the reviewer account to anyone else's connections, tasks + or results. +- [ ] Access details ready to send through the review channel only. + +## 6. Live acceptance on the reviewer environment + +- [ ] First use: defaults, deliberate selection, Cancel, retry, reload, no + duplicate connection. +- [ ] Consent: Gmail only, Drive group only, Calendar only, read only versus + read & write, and partial consent on Google's screen. +- [ ] Reads: full email body, Drive search and file content, Doc, Sheet values, + Slides, calendar list, events, free/busy. +- [ ] Writes: Gmail draft (unsent), file create and copy, Doc, Sheet and Slides + edits, event create, update, delete and respond; each shown in Google. +- [ ] Lifecycle: reconnect, token refresh during a real run, revoked access, + reduced access, clear recovery message. +- [ ] Denials: a real call to an unselected service, a write on a read-only + grant, and a cross-company attempt, each refused with no change in Google. +- [ ] Each of the 14 scopes mapped to a passing test. + +## 7. Demo video + +- [ ] Real browser with the address bar and OAuth client ID readable. +- [ ] Consent screen in English with all permissions expanded. +- [ ] Email shown in full in Paperclip, then the same email in Gmail. +- [ ] Every scope shown in use, with a chapter per scope. +- [ ] Task automation and the direction of data flow explained. +- [ ] No private data visible; plays for someone outside the team. +- [ ] Uploaded to YouTube as Unlisted. + +## 8. Submission + +- [ ] Console declaration updated to the 14 scopes. +- [ ] Point-by-point reply to Google's October 7 message drafted. +- [ ] 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. +- [ ] Reviewer environment, test data and model access kept running during review. +- [ ] Each Google finding tracked with owner, date and resolution. + +## 9. Release (after explicit approval) + +- [ ] Approval captured with the project, clients and scopes it covers. +- [ ] Production broker enables the unified profile with matching scopes. +- [ ] Canary on one production workspace: connect, read, write, disconnect. +- [ ] Experimental setting removed; connector on by default. +- [ ] Release notes and user help published. + +## 10. Ongoing + +- [ ] Alerts for sign-in, refresh and Google denial failures. +- [ ] Annual security reassessment scheduled. +- [ ] Rule recorded: any new scope, client or data use goes back to Google first.