docs(connections): record Nov 17 Google Workspace progress in memory, checklist and plan (#22007)

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-17 08:40:25 -06:00
1 parent 3293700448
commit 1ca90d2d6f
3 files changed
+221 -76

No files matched your search

+96 -10
View File
@@ -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 <https://paperclip.ing/privacy>. 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.
@@ -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).
@@ -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.