mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 00:53:46 +01:00
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:
1 parent
3293700448
commit
1ca90d2d6f
3 files changed
+221
-76
No files matched your search
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user