fix(google-workspace): request free/busy with read & write Calendar, and update connector docs (#22026)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The built-in Google Workspace connector gives agents Gmail, Drive
and Calendar through one connection, behind an experimental setting
> - The user picks each service as read only or read & write. Paperclip
then requests only scopes from a fixed list of 14
> - Read & write Calendar requested `calendar.calendarlist.readonly` and
`calendar.events`. Our code assumed `calendar.events` also covers
free/busy lookups
> - Google's REST `freeBusy.query` does not accept `calendar.events`. So
the REST `suggest_time` tool cannot read free/busy on a read & write
grant, and falls back to reading each attendee's events
> - This pull request adds `calendar.events.freebusy` (already one of
the 14) to the read & write Calendar selection of the unified
connection, and stops treating `calendar.events` as implying free/busy
> - The benefit is that `suggest_time` on REST can see coworkers who
share only free/busy, and the stored grant no longer claims a permission
that Google did not give. It also brings three Google connector planning
docs up to date

## Linked Issues or Issue Description

Refs #22016, #22017, #22010, #22014

**What happened?**

The read & write Calendar selection of the unified Google Workspace
connection requests `calendar.calendarlist.readonly` and
`calendar.events`. `toolScopes.calendar.suggest_time` lists
`calendar.events` as sufficient, and `googleWorkspaceEffectiveScopes`
treats `calendar.events` as implying `calendar.events.freebusy`.

Google's two references differ:

- REST
[`freeBusy.query`](https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query),
checked 2026-11-17: "This request allows authorization with at least one
of the following scopes:" `calendar.readonly`, `calendar`,
`calendar.events.freebusy`, `calendar.freebusy`. `calendar.events` is
not in the list.
- Google's hosted Calendar MCP
[`suggest_time`](https://developers.google.com/workspace/calendar/api/v3/reference/mcp/tools_list/suggest_time),
checked 2026-11-17: "Requires one of the following OAuth scopes:"
`calendar`, `calendar.readonly`, `calendar.events`,
`calendar.events.freebusy`, `calendar.freebusy`. Here `calendar.events`
is accepted.

So `calendar.events` is enough for Google's MCP tool but not for the
REST endpoint that our REST `suggest_time` uses.

**Expected behavior**

A user who picks read & write Calendar gets a grant that allows
`freeBusy.query`. A grant that does not have the free/busy permission is
not recorded as having it. Grants made before this change keep working
as read & write.

**Steps to reproduce**

1. Call `googleWorkspaceSelectedScopes({ calendar: "write" })`. It
returns two scopes, without `calendar.events.freebusy`.
2. Call `googleWorkspaceEffectiveScopes(readOnlyCalendarScopes,
[calendar.events])`. It returns `calendar.events.freebusy`, which Google
did not grant.
3. With Calendar on the REST transport, `suggest_time` on a read & write
grant gets an insufficient-scope answer from `freeBusy.query` and uses
the events fallback.

## What Changed

- `packages/shared/src/google-workspace-connectors.ts`:
- `googleWorkspaceSelectedScopes` adds selection-level scopes from a new
`SELECTION_ADDED_SCOPES` map. Read & write Calendar adds
`calendar.events.freebusy`. The per-service `calendar.write` profile
(`SERVICE_PROFILES["calendar.write"]`) is unchanged, because the Cloud
broker matches legacy profiles by exact scope set.
- `googleWorkspaceEffectiveScopes` no longer expands `calendar.events`
to `calendar.events.freebusy`. `calendar.events` still implies
`calendar.events.readonly`. `calendar.readonly` still implies free/busy,
which Google's reference allows.
- `googleWorkspaceSelectionForScopes` is unchanged. It needs the legacy
write profile's scopes, so a two-scope grant and a three-scope grant
both read back as read & write.
- `toolScopes.calendar.suggest_time` is unchanged. It still accepts
`calendar.events`: Google's MCP tool accepts it, and on REST the tool
has an events-based fallback that names attendees it cannot read.
- Counts: default all-read-and-write selection is now 10 scopes (was 9);
all read-only stays 8; the union of all 27 selections stays exactly the
14.
- Tests (written first and seen failing on `master`):
- `packages/shared/src/google-workspace-connectors.test.ts`: scopes for
read and for read & write Calendar; the legacy `calendar.write` profile
keeps two scopes; default count 10 and read-only count 8; old two-scope
grant, new three-scope grant and partial consent (user declines
free/busy) all round-trip as read & write and keep `list_calendars`,
`list_events`, `suggest_time`, `create_event` and `delete_event`; no
recorded free/busy that Google did not grant. The existing exhaustive
test still checks that no selection requests a scope outside the 14.
- `server/src/__tests__/tool-access-service.test.ts`: customer-owned
Workspace OAuth with read & write Calendar asks Google for all three
scopes. With and without free/busy in Google's answer, the connection is
active, the Calendar tools are listed, the grant stores exactly what
Google granted, and it reads back as read & write.
- Stale tests on `master` fixed: `#22014` made Gmail 9 of 9 in the REST
tool set while `#22016` still expected 3 Gmail REST tools.
`google-workspace-rest-dispatch.test.ts` and
`google-workspace-rest-transport.test.ts` now derive the Gmail list from
the allowlist and use Chat as the service with no REST tools.
- Docs: `doc/connections/GOOGLE-WORKSPACE.md`,
`doc/connections/GOOGLE-WORKSPACE-SERVICE-CONSENT.md` and
`doc/connections/tool-method-permission-reviews.json` say ten scopes and
explain the Calendar change.
- Docs: `doc/memory/google-connector-memory.md` (shipped PRs #22010,
#22014, #22016, #22017; three Nov 17 decisions; "Where Google content is
kept" replaced with #22010's inventory, what deletion keeps and its
limits; Scopes section; REST tools status table; still-open list),
`doc/plans/2026-11-17-google-workspace-production-checklist.md` (help
page and retention audit ticked with #22010; REST tool progress),
`doc/plans/2026-11-17-google-workspace-code-fixes.md` (fix 6 done with
limits; section 9 status table; fix 10 note).
- `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for
the changed shared files.

Not changed:

- `server/src/google-workspace-rest-tools/**`. Another change owns that
folder. Its README open question about this scope is now resolved and
can be removed there.
- The picker disclosure (`googleWorkspaceDisclosure.ts`). Read & write
Calendar already says agents "can see your calendars, events and
free/busy times". With this change that line is accurate on REST too.

Behavior for existing grants: a saved read & write grant without
free/busy still reads back as read & write, keeps every Calendar tool,
and refreshes without change. Nothing prompts the user to reconnect. A
user who chooses read & write Calendar in the picker is asked for the
new scope. An account-page reconnect without a new choice still restores
the exact saved request, as before.

Cloud broker and Google Console: no change needed.
`calendar.events.freebusy` is one of the 14 in `workspace.all`, the
broker accepts any nonempty subset of `workspace.all`
(`doc/connections/GOOGLE-WORKSPACE-SERVICE-CONSENT.md`), and the legacy
`calendar.write` profile's exact scope set did not change.

## Verification

- `cd packages/shared && npx vitest run
src/google-workspace-connectors.test.ts src/app-definitions.test.ts`: 55
passed. On `master` the new shared tests fail (3 failed).
- `cd server && npx vitest run src/__tests__/tool-access-service.test.ts
-t "free/busy"`: 2 passed. With `master`'s
`google-workspace-connectors.ts`: 2 failed.
- `cd server && npx vitest run
src/__tests__/google-workspace-rest-transport.test.ts
src/services/google-workspace-rest-dispatch.test.ts`: 29 passed (4
failed on `master` before this change).
- `cd ui && npx vitest run
src/features/connections/GoogleWorkspaceServices.test.tsx
src/pages/apps/AppDetail.test.tsx`: 115 passed.
- `cd packages/shared && npx tsc --noEmit -p .`: clean.
- `pnpm verify` exits 2 (a global CI input changed), so required CI
supplies the broad coverage.
- Docs facts checked against `gh pr view` for #22010, #22014, #22016,
#22017, the code, and paperclipai/paperclip-website PR 197 (still a
draft; does not mention OpenRouter).

## Risks

- Low risk. The submitted set of 14 does not change, and the broker
contract does not change.
- New read & write Calendar grants record `calendar.events.freebusy`
next to `calendar.events`. Code that reads stored scopes sees one more
scope. All consumers (callback, refresh, discovery, picker pre-fill) are
covered by the tests above.
- A read-only Calendar request on an account that Google reports only
`calendar.events` for no longer records free/busy. That matches what
Google granted; `suggest_time` is then not offered on that grant.

> 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, via Claude Code with
tool use, web fetch and code execution.

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-17 16:40:58 +00:00
1 parent 01451fae5b
commit 7f1f0eef67
12 files changed
+251 -56

No files matched your search

@@ -18,7 +18,10 @@ consent preview → Production picker**. Storybook callbacks do not grant access
The `workspaceServices` input accepts only nonempty combinations of `gmail`,
`drive`, and `calendar`, each `read` or `write`. The server derives exact scopes
from the shared closed registry. Default write access requests nine scopes.
from the shared closed registry. Default write access requests ten scopes.
Read & write Calendar adds `calendar.events.freebusy` to the per-service
`calendar.write` profile's two scopes, so free/busy lookups work over REST.
Grants made before that change still count as read & write Calendar.
Drive file creation is limited to app-opened/app-created files; Docs, Sheets,
and Slides have their respective editor scopes. Gmail uses `gmail.compose`
for draft creation; Google permits sending under that scope, but Paperclip's
+10 -4
View File
@@ -16,7 +16,7 @@ Turn the setting on in **Settings → Experimental** to test the built-in connec
The combined connection has one credential grant, capability catalog, policy
profile, audit trail and reconnect lifecycle. It requests only the selected
groups' scopes (nine scopes for the default selection), not the legacy full
groups' scopes (ten scopes for the default selection), not the legacy full
union. Google's consent screen also lets users decline
permissions; discovery skips services without grants and excludes unsupported
actions. The gateway checks actual grant scopes again before each call, including
@@ -299,9 +299,15 @@ Docs, Sheets, and Slides request only their service's read-only scope in the
read profile and its read/write scope in the write profile. They do not also
request `drive.readonly` or `drive.file`: those are authorization alternatives,
not additional requirements. Drive and Workspace Search retain their separate
Drive permissions. Calendar write requests `calendar.calendarlist.readonly`
and `calendar.events`; the latter also authorizes `suggest_time`. Calendar read
retains `calendar.events.freebusy` alongside list/event read-only access.
Drive permissions. The per-service Calendar write profile requests
`calendar.calendarlist.readonly` and `calendar.events`; Google's MCP
`suggest_time` accepts `calendar.events`. Calendar read retains
`calendar.events.freebusy` alongside list/event read-only access. The combined
connection's read & write Calendar selection also requests
`calendar.events.freebusy` (2026-11-17), because Google's REST
[`freeBusy.query`](https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query)
does not accept `calendar.events`. The per-service profile keeps its exact
scope set for the Cloud broker.
References: Google's [Docs read](https://developers.google.com/workspace/docs/api/reference/mcp/tools_list/read_doc)
and [update](https://developers.google.com/workspace/docs/api/reference/mcp/tools_list/update_doc),
@@ -24,7 +24,7 @@
"https://www.googleapis.com/auth/calendar.events"
],
"capability": "write",
"supportedActions": "One grant for selected Gmail, Drive (Docs, Sheets, Slides), and Calendar services. The list is the read/write selection allowlist, not the default request; default write selections request nine scopes. Chat, People, and Search are excluded. Gmail sending remains unsupported.",
"supportedActions": "One grant for selected Gmail, Drive (Docs, Sheets, Slides), and Calendar services. The list is the read/write selection allowlist, not the default request; default write selections request ten scopes. Chat, People, and Search are excluded. Gmail sending remains unsupported.",
"evidence": [
"https://developers.google.com/workspace/guides/configure-mcp-servers",
"https://developers.google.com/identity/protocols/oauth2/resources/granular-permissions"
@@ -54,7 +54,7 @@
"https://www.googleapis.com/auth/calendar.events"
],
"capability": "write",
"supportedActions": "One grant for selected Gmail, Drive (Docs, Sheets, Slides), and Calendar services. The list is the read/write selection allowlist, not the default request; default write selections request nine scopes. Chat, People, and Search are excluded. Gmail sending remains unsupported.",
"supportedActions": "One grant for selected Gmail, Drive (Docs, Sheets, Slides), and Calendar services. The list is the read/write selection allowlist, not the default request; default write selections request ten scopes. Chat, People, and Search are excluded. Gmail sending remains unsupported.",
"evidence": [
"https://developers.google.com/workspace/guides/configure-mcp-servers",
"https://developers.google.com/identity/protocols/oauth2/resources/granular-permissions"
+85 -17
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 (evening).
Last updated: November 17, 2026 (late evening).
## Decisions
@@ -28,6 +28,10 @@ Last updated: November 17, 2026 (evening).
| 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. |
| Nov 17 | **Merges are gated on green CI and Greptile 5/5 only** | Not on the ponytail review bot. |
| Nov 17 | **`delete_event` never deletes a whole recurring series in this release** | A series ID is refused; the agent must pass one occurrence's ID. |
| Nov 17 | **A health probe may only use a request the granted scopes permit** | Each service lists cheap reads with the scopes that allow each; the probe uses the first one the grant allows. |
| Nov 17 | **Read & write Calendar also requests free/busy** | See "Scopes". |
## What has shipped
@@ -38,22 +42,50 @@ Last updated: November 17, 2026 (evening).
| [#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` |
| [#22010](https://github.com/paperclipai/paperclip/pull/22010) | Users can delete the data Paperclip stored from a connection's tool calls: "Delete data" on the connection's page, or a checkbox when removing it. Live for every connector, not only Google. Help page: `docs/guides/board-operator/deleting-connection-data.md`. | `d1b5cfe038` |
| [#22017](https://github.com/paperclipai/paperclip/pull/22017) | Nine Calendar tools in the REST tool set (Calendar 9 of 9). | `c41ca4a992` |
| [#22016](https://github.com/paperclipai/paperclip/pull/22016) | Per-service transport switch (`GOOGLE_WORKSPACE_TOOL_TRANSPORT`) and in-process dispatch to the REST tools. Every service is still on Google's MCP. Discovery and health run a scope-aware probe for a service on REST. | `c652c813bc` |
| [#22014](https://github.com/paperclipai/paperclip/pull/22014) | The remaining six Gmail read tools in the REST tool set (Gmail 9 of 9). | `1d3b4201e3` |
In progress: the Drive, Docs and Slides, and Sheets REST tools.
### REST tools status
| Service | Implemented | Switched on |
| --- | --- | --- |
| Gmail | 9 of 9 | No |
| Calendar | 9 of 9 | No |
| Drive | 0 of 8 | No |
| Docs | 0 of 2 | No |
| Sheets | 0 of 6 | No |
| Slides | 0 of 2 | No |
"Switched on" means the service is `paperclip_rest` in
`GOOGLE_WORKSPACE_TOOL_TRANSPORT`. Today every service is `google_mcp`.
## 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.
- **How the staging tester reaches 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).
- **AI-agent client and REST.** Whether an OAuth client marked for AI agents
may call the REST APIs rather than MCP. To check before the staging tester is
wired.
- **Three Gmail tools are inferred.** Google's MCP reference does not list
`get_draft`, `list_threads` and `search_messages`; their schemas copy the
sibling tools (#22014).
- **Privacy policy.** paperclipai/paperclip-website PR 197 is a draft waiting
on Dotta's sign-off. It does not yet mention the OpenRouter model used by
the optional injection-screening check; it must (see "Privacy policy").
- **The "no review correspondence" rule.** Narrow it or keep it (see "Google
review history").
- 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
@@ -102,7 +134,7 @@ channel.
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
One connection, three groups, **14 scopes** across all modes (10 for the
default all-read-and-write selection, 8 for all read-only). Prefix:
`https://www.googleapis.com/auth/`. In code the list is
`GOOGLE_WORKSPACE_SUBMITTED_SCOPES` in
@@ -112,7 +144,7 @@ default all-read-and-write selection, 8 for all read-only). Prefix:
| --- | --- | --- |
| 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` |
| Calendar | `calendar.calendarlist.readonly`, `calendar.events.readonly`, `calendar.events.freebusy` | `calendar.calendarlist.readonly`, `calendar.events`, `calendar.events.freebusy` |
- **Restricted (trigger the security assessment):** `gmail.readonly`,
`gmail.compose`, `drive.readonly`.
@@ -120,6 +152,18 @@ 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.
- **Read & write Calendar asks for free/busy** (Nov 17, [#22026](https://github.com/paperclipai/paperclip/pull/22026)). Google's
REST `freeBusy.query` accepts only `calendar.readonly`, `calendar`,
`calendar.events.freebusy` and `calendar.freebusy`, not `calendar.events`
(<https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query>).
Google's MCP `suggest_time` does accept `calendar.events`. So read & write
Calendar now also requests `calendar.events.freebusy`, already one of the
14. The per-service `calendar.write` profile keeps its two scopes, because
the broker matches legacy profiles by exact scope set. Grants made before
this change still count as read & write and keep `suggest_time`; on REST it
falls back to reading attendees' events and names anyone it cannot read.
Nothing prompts them to reconnect; choosing read & write Calendar again in
the picker asks for the new scope.
- 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).
@@ -158,17 +202,41 @@ 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.
From #22010's store inventory. The earlier audit understated it: it missed the
second audit table, approval cards, results passed to later runs, app views,
nested run answers and migrated log originals.
| Place | What is kept | How long |
| Place | What is kept | Removed by "Delete data" |
| --- | --- | --- |
| 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. |
| Tool-call records (`tool_invocations`, `tool_call_events`) | About 4,000 characters of each request and result | Yes. Size and fingerprint kept. |
| Connection audit history (`tool_access_audit_events`) | Argument preview | Yes. Decision, IDs, size and fingerprint kept. |
| Approval requests and their approval cards in the task | Preview, arguments and the executed result | Yes, for settled requests. |
| Results passed to a later run (run context and wake payload) | Approved action results | Yes, for settled runs and wakes. |
| App views | Tool input, result and shared context | Yes, rows deleted. |
| Run transcripts: the run log in every copy (object journal, archive, original local file and its S3 mirror), run events, output excerpts and answer text at any depth of the run result | Full content | Yes, the whole transcript of every settled run that called the connection or received an approved result. |
| Comments, documents, files and chat messages agents wrote into tasks | Whatever the agent copied | No, by design. The user edits or deletes them, or the task. |
| Transcripts of later runs that read an app view's shared context | Shared context | No. Nothing records which runs read it. |
| Questions a provider asked a person; provider tool and skill definitions | Not tool results | No. |
| Raw provider traces | Full traffic | No. Admin opt-in, encrypted, expire within 24 hours. |
| Feedback exports already sent | Run logs the user chose to share | No. Already outside Paperclip. |
| Optional model check for injection screening | If a company turns it on, the full tool result is sent to an OpenRouter model | Not stored by Paperclip. |
| Connection removal | Deletes tokens locally | Does not revoke at Google. |
Planned fix: a "delete data read through this connection" action.
What "Delete data" keeps: the record that each call happened (time, tool,
agent, outcome, size, fingerprint), and activity entries with counts only.
Limits:
- Runs still in progress are skipped and counted; delete again after they
finish.
- Deleting a task or a company does not yet run the same cleanup.
- A local log file on another server's disk stays until that server is
replaced; its S3 mirror is deleted.
- On versioned buckets, earlier object versions stay until the bucket's
lifecycle rule removes them.
The deletion is a durable request. It resumes after a restart and retries a
failed step until every step succeeds.
## Google review history
@@ -6,8 +6,8 @@ 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. Fixes 1 to 4 landed on November 17. Work on fixes 9 and
10 has started. Fixes 5 to 8 are not started.
before any change. Fixes 1 to 4 and 6 landed on November 17. Work on fixes 9
and 10 has started. Fixes 5, 7 and 8 are not started.
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).
@@ -21,10 +21,10 @@ change in fix 2, the deploy order is app first, then broker (see fix 10).
| 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 |
| 6 | Retention and deletion of Google content | Audit, then unknown | Yes | Done with limits, [#22010](https://github.com/paperclipai/paperclip/pull/22010) |
| 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) |
| 9 | REST-backed tool set | Large | Yes | Gmail and Calendar done, switch merged, none switched on; Drive, Docs, Sheets, Slides in progress |
| 10 | Scope cleanup across code, Cloud and Console | Medium | Yes | App done; broker and Console open |
## 1. Data-use disclosure in the picker
@@ -160,6 +160,17 @@ reasoning mostly goes away, and reviewers expect disconnect to end access.
## 6. Retention and deletion of Google content
**Done, with limits** (Nov 17, [#22010](https://github.com/paperclipai/paperclip/pull/22010)).
Any connection's page has "Delete data", and removing a connection offers the
same. It clears previews, approval cards, results passed to later runs, app
views and the whole transcript of each settled run that used the connection.
It keeps call records without content. Limits: content agents wrote into
tasks stays; deleting a task or a company does not yet run the same cleanup;
runs in progress are skipped. The help page is
`docs/guides/board-operator/deleting-connection-data.md`. The inventory is in
the working memory under "Where Google content is kept". Revoking at Google is
fix 5. The plan below is kept for reference.
**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
@@ -203,6 +214,22 @@ deleted cleanly. Part 1 is
folder and Gmail `get_message`, `search_threads` and `create_draft`. Its README
records the dispatch trace and the recommended in-process seam.
Status (Nov 17, late evening):
| Service | Implemented | Switched on | PRs |
| --- | --- | --- | --- |
| Gmail | 9 of 9 | No | [#22000](https://github.com/paperclipai/paperclip/pull/22000), [#22014](https://github.com/paperclipai/paperclip/pull/22014) |
| Calendar | 9 of 9 | No | [#22017](https://github.com/paperclipai/paperclip/pull/22017) |
| Drive | 0 of 8 | No | In progress |
| Docs | 0 of 2 | No | In progress |
| Sheets | 0 of 6 | No | In progress |
| Slides | 0 of 2 | No | In progress |
The per-service switch and in-process dispatch landed in
[#22016](https://github.com/paperclipai/paperclip/pull/22016). Every service is
still on Google's MCP. The gateway calls the REST tools in process, as the
trace in #22000 recommended.
### The seam
Today the unified connection sends each tool call, with the user's Google
@@ -317,6 +344,10 @@ Also needed:
project owner's sign-in).
- Keep the working memory's "Scopes" and "Cloud broker" sections current.
Read & write Calendar now also requests `calendar.events.freebusy` (Nov 17).
It is one of the 14 and the broker accepts any nonempty subset of
`workspace.all`, so neither the broker nor the Console needs a change for it.
## Not code, but needed by these fixes
- Published privacy policy and Limited Use statement URLs (fix 1).
@@ -61,7 +61,9 @@ Decisions and the details behind them are kept in the
- [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.
- [x] Help page: how to disconnect and how to delete stored Google data
(Nov 17, [#22010](https://github.com/paperclipai/paperclip/pull/22010):
`docs/guides/board-operator/deleting-connection-data.md`).
- [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
@@ -71,12 +73,22 @@ Decisions and the details behind them are kept in the
- [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.
- [x] Retention and deletion of Google content in tasks, runs and files audited
(Nov 17, [#22010](https://github.com/paperclipai/paperclip/pull/22010)
store inventory; summary in the working memory's "Where Google content
is kept"). Users can now delete it per connection. Content agents wrote
into tasks stays, and task or company deletion does not yet run the same
cleanup.
- [ ] 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).
server, with the same tool names and shapes as Google's MCP tools.
18 of 36 so far: Gmail 9 of 9
([#22000](https://github.com/paperclipai/paperclip/pull/22000),
[#22014](https://github.com/paperclipai/paperclip/pull/22014)) and
Calendar 9 of 9
([#22017](https://github.com/paperclipai/paperclip/pull/22017)). The
per-service switch exists
([#22016](https://github.com/paperclipai/paperclip/pull/22016)); no
service is switched on yet.
- [ ] 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
@@ -7,7 +7,7 @@ import {
googleWorkspaceSelectedScopes, googleWorkspaceEffectiveScopes, GOOGLE_WORKSPACE_DEFAULT_SELECTION,
googleWorkspaceDraftRequestedScopes, GOOGLE_WORKSPACE_SERVICE_GROUPS, GOOGLE_WORKSPACE_SUBMITTED_SCOPES,
GOOGLE_WORKSPACE_CONNECTOR_PROFILE_IDS, googleWorkspaceProfileWithinSubmittedScopes,
GOOGLE_WORKSPACE_TOOL_TRANSPORT, googleWorkspaceServiceToolNames,
GOOGLE_WORKSPACE_TOOL_TRANSPORT, googleWorkspaceServiceToolNames, googleWorkspaceSelectionForScopes,
type GoogleWorkspaceServiceSelection,
} from "./google-workspace-connectors.js";
@@ -30,7 +30,8 @@ describe("combined Google Workspace consent", () => {
it("defaults to Gmail, combined Drive, and Calendar write scopes without Chat or People", () => {
const selected = googleWorkspaceSelectedScopes(GOOGLE_WORKSPACE_DEFAULT_SELECTION);
expect(selected).toHaveLength(9);
expect(selected).toHaveLength(10);
expect(googleWorkspaceSelectedScopes({ gmail: "read", drive: "read", calendar: "read" })).toHaveLength(8);
expect(selected).toContain(scope("gmail.compose"));
expect(selected.some(value => /chat|contacts|directory|userinfo/.test(value))).toBe(false);
expect(googleWorkspaceSelectedScopes({})).toEqual([]);
@@ -46,6 +47,38 @@ describe("combined Google Workspace consent", () => {
expect(isGoogleWorkspaceToolGranted("docs__read_doc", effective)).toBe(true);
expect(googleWorkspaceEffectiveScopes([scope("documents")], [scope("documents.readonly")])).toEqual([scope("documents.readonly")]);
});
it("requests the free/busy permission with read and write Calendar access", () => {
expect(googleWorkspaceSelectedScopes({ calendar: "read" })).toEqual([
scope("calendar.calendarlist.readonly"), scope("calendar.events.freebusy"), scope("calendar.events.readonly"),
]);
expect(googleWorkspaceSelectedScopes({ calendar: "write" })).toEqual([
scope("calendar.calendarlist.readonly"), scope("calendar.events"), scope("calendar.events.freebusy"),
]);
expect([...profiles["calendar.write"].scopes]).toEqual([scope("calendar.calendarlist.readonly"), scope("calendar.events")]);
});
it("keeps Calendar read and write access for grants made before and after free/busy was requested", () => {
const before = [scope("calendar.calendarlist.readonly"), scope("calendar.events")];
const after = googleWorkspaceSelectedScopes({ calendar: "write" });
for (const [requested, granted] of [[before, before], [after, after], [after, before]]) {
const effective = googleWorkspaceEffectiveScopes(requested!, granted!);
expect(effective).toEqual(granted);
expect(googleWorkspaceSelectionForScopes(effective)).toEqual({ calendar: "write" });
for (const tool of ["list_calendars", "list_events", "suggest_time", "create_event", "delete_event"]) {
expect(isGoogleWorkspaceToolGranted(`calendar__${tool}`, effective), tool).toBe(true);
}
}
expect(googleWorkspaceSelectionForScopes(googleWorkspaceSelectedScopes({ calendar: "read" }))).toEqual({ calendar: "read" });
});
it("does not record a free/busy permission that Google did not grant", () => {
const write = googleWorkspaceSelectedScopes({ calendar: "write" });
expect(googleWorkspaceEffectiveScopes(write, [scope("calendar.events")])).toEqual([scope("calendar.events")]);
expect(googleWorkspaceEffectiveScopes(googleWorkspaceSelectedScopes({ calendar: "read" }), [scope("calendar.events")]))
.toEqual([scope("calendar.events.readonly")]);
expect(googleWorkspaceEffectiveScopes([scope("calendar.events")], write)).toEqual([scope("calendar.events")]);
});
it("limits every selectable service combination to the 14 scopes submitted for Google verification", () => {
const submitted = [
"gmail.readonly", "gmail.compose",
@@ -19,7 +19,10 @@ export const GOOGLE_WORKSPACE_SERVICE_GROUPS = [
export function googleWorkspaceSelectedScopes(selection: GoogleWorkspaceServiceSelection): string[] {
return [...new Set(GOOGLE_WORKSPACE_SERVICE_GROUPS.flatMap(group => {
const access = selection[group.id];
return access ? group[access].flatMap(profile => GOOGLE_WORKSPACE_CONNECTOR_PROFILES[profile].scopes) : [];
return access ? [
...group[access].flatMap(profile => GOOGLE_WORKSPACE_CONNECTOR_PROFILES[profile].scopes),
...(SELECTION_ADDED_SCOPES[group.id]?.[access] ?? []),
] : [];
}))].sort();
}
@@ -28,7 +31,7 @@ export function googleWorkspaceEffectiveScopes(requested: readonly string[], gra
const implies: Record<string, string[]> = {
documents: ["documents.readonly"], spreadsheets: ["spreadsheets.readonly"],
presentations: ["presentations.readonly"],
"calendar.events": ["calendar.events.readonly", "calendar.events.freebusy"],
"calendar.events": ["calendar.events.readonly"],
"calendar.readonly": ["calendar.calendarlist.readonly", "calendar.events.readonly", "calendar.events.freebusy"],
};
const expand = (scopes: readonly string[]) => new Set(scopes.flatMap(scope => [scope, ...(implies[scope.replace("https://www.googleapis.com/auth/", "")] ?? []).map(value => `https://www.googleapis.com/auth/${value}`)]));
@@ -75,6 +78,10 @@ export function googleWorkspaceDraftRequestedScopes(
const auth = (scope: string) => `https://www.googleapis.com/auth/${scope}`;
const SELECTION_ADDED_SCOPES: Partial<Record<keyof GoogleWorkspaceServiceSelection, Partial<Record<"read" | "write", readonly string[]>>>> = {
calendar: { write: [auth("calendar.events.freebusy")] },
};
const SERVICE_PROFILES: Readonly<Record<Exclude<GoogleWorkspaceConnectorProfileId, "workspace.all">, {
appSlug: string;
serverUrl: string;
@@ -6,7 +6,7 @@ import {
toolAccessAuditEvents, toolActionRequests, toolInvocations,
} from "@paperclipai/db";
import {
GOOGLE_WORKSPACE_DEFAULT_SELECTION, GOOGLE_WORKSPACE_TOOL_TRANSPORT,
GOOGLE_WORKSPACE_DEFAULT_SELECTION, GOOGLE_WORKSPACE_TOOL_TRANSPORT, googleWorkspaceServiceToolNames,
type GoogleWorkspaceService, type GoogleWorkspaceToolTransport,
} from "@paperclipai/shared";
import * as restDispatch from "../services/google-workspace-rest-dispatch.js";
@@ -17,6 +17,9 @@ import { initializeRunIdentity } from "../services/run-identity.js";
import type { PaperclipCloudConnector } from "../services/paperclip-cloud-connector.js";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
const gmailCatalog = (write: boolean) => ["docs__read_doc", ...googleWorkspaceServiceToolNames("gmail")
.filter((name) => write || name !== "create_draft").map((name) => `gmail__${name}`)].sort();
vi.mock("../services/google-workspace-rest-dispatch.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("../services/google-workspace-rest-dispatch.js")>();
return {
@@ -197,14 +200,14 @@ const support = await getEmbeddedPostgresTestSupport();
it("discovers the REST tools under the same names, filtered by granted scopes, after one profile probe", async () => {
useTransport("gmail", "paperclip_rest");
const f = await connectWorkspace();
expect(f.catalog.map((entry) => entry.toolName).sort()).toEqual(["docs__read_doc", "gmail__create_draft", "gmail__get_message", "gmail__search_threads"]);
expect(f.catalog.map((entry) => entry.toolName).sort()).toEqual(gmailCatalog(true));
expect(f.catalog.find((entry) => entry.toolName === "gmail__create_draft")?.riskLevel).toBe("write");
expect(f.mcpRequests.some((request) => request.startsWith("gmailmcp."))).toBe(false);
expect(f.mcpRequests).toContain("docsmcp.googleapis.com tools/list");
expect(f.gmailRequests).toEqual([expect.objectContaining({ method: "GET", path: "/gmail/v1/users/me/profile", authorization: "Bearer workspace-access-1" })]);
const readOnly = await connectWorkspace({ permissions: ["gmail.readonly", "documents.readonly"] });
expect(readOnly.catalog.map((entry) => entry.toolName).sort()).toEqual(["docs__read_doc", "gmail__get_message", "gmail__search_threads"]);
expect(readOnly.catalog.map((entry) => entry.toolName).sort()).toEqual(gmailCatalog(false));
});
it("runs a Gmail read in process with the caller's token, screens it, and audits it", async () => {
@@ -336,7 +339,7 @@ const support = await getEmbeddedPostgresTestSupport();
await expect(f.call("docs__read_doc", { documentId: "doc1" })).resolves.toMatchObject({ status: "completed" });
f.setGmail(undefined);
const recovered = await f.service.refreshCatalog(f.connectionId, f.actor);
expect(recovered.catalog.map((entry) => entry.toolName).sort()).toEqual(["docs__read_doc", "gmail__create_draft", "gmail__get_message", "gmail__search_threads"]);
expect(recovered.catalog.map((entry) => entry.toolName).sort()).toEqual(gmailCatalog(true));
});
it("asks for reconnection when Google keeps rejecting the token after a refresh during discovery", async () => {
@@ -66,6 +66,8 @@ import {
GOOGLE_WORKSPACE_CONNECTOR_PROFILES,
googleWorkspaceProfileWithinSubmittedScopes,
googleWorkspaceSelectedScopes,
googleWorkspaceGrantedScopes,
googleWorkspaceSelectionForScopes,
GOOGLE_WORKSPACE_DEFAULT_SELECTION,
getAvailableConnectionMethod,
getConnectableAppDefinition,
@@ -2993,6 +2995,42 @@ describeEmbeddedPostgres("tool access service", () => {
})).rejects.toMatchObject({ status: 400 });
});
it.each([
["with", ["calendar.calendarlist.readonly", "calendar.events", "calendar.events.freebusy"]],
["without", ["calendar.calendarlist.readonly", "calendar.events"]],
] as const)("asks for free/busy with read and write Calendar and keeps Calendar working %s it", async (_label, granted) => {
const company = await createCompany(db);
const userId = `workspace-calendar-${randomUUID()}`;
await grantBoardUser(db, company.id, userId, [], "owner");
const actor = { actorType: "user" as const, actorId: userId };
const service = createTestToolAccessService(db);
const connected = await service.connectGalleryApp(company.id, {
galleryKey: "google-workspace", connectionMethodKey: "customer-workspace-oauth", grantKind: "user",
oauthClient: { clientId: "test-workspace-client", clientSecret: "test-workspace-secret" },
}, actor);
const redirectUri = "https://paperclip.example.test/api/tools/oauth/callback";
const started = await service.startOAuth(company.id, connected.connectionId, { redirectUri, actor, workspaceServices: { calendar: "write" } });
const authorization = new URL(started.authorizationUrl);
const google = (value: string) => `https://www.googleapis.com/auth/${value}`;
expect(authorization.searchParams.get("scope")?.split(" "))
.toEqual(["calendar.calendarlist.readonly", "calendar.events", "calendar.events.freebusy"].map(google));
const tools = ["list_calendars", "list_events", "suggest_time", "create_event"];
vi.spyOn(globalThis, "fetch").mockImplementation(async (url) => {
if (String(url) === "https://oauth2.googleapis.com/token") return Response.json({
access_token: "fixture-calendar-access", refresh_token: "fixture-calendar-refresh", expires_in: 3600, token_type: "Bearer",
scope: granted.map(google).join(" "),
});
expect(String(url)).toBe("https://calendarmcp.googleapis.com/mcp/v1");
return mcpHttpResponse({ jsonrpc: "2.0", id: "paperclip-catalog-refresh", result: { tools: tools.map(name => ({ name })) } });
});
const completed = await service.completeOAuthCallback({ state: authorization.searchParams.get("state")!, code: "fixture-code", redirectUri, actor });
expect(completed.connection.status).toBe("active");
expect(completed.catalog.map((entry) => entry.toolName).sort()).toEqual(tools.map(name => `calendar__${name}`).sort());
const [grant] = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connected.connectionId));
expect(googleWorkspaceGrantedScopes(grant!)).toEqual([...granted].map(google).sort());
expect(googleWorkspaceSelectionForScopes(googleWorkspaceGrantedScopes(grant!))).toEqual({ calendar: "write" });
});
it.each(["https://www.googleapis.com/auth/documents.readonly", undefined, "", "https://www.googleapis.com/auth/gmail.send"])(
"requires explicit reviewed partial consent for customer Workspace OAuth (%s)", async (scope) => {
const company = await createCompany(db);
@@ -3,7 +3,6 @@ import { describe, expect, it, vi } from "vitest";
import {
callGoogleWorkspaceRest,
googleWorkspaceRestTransportGaps,
listGoogleWorkspaceRest,
probeGoogleWorkspaceRest,
} from "./google-workspace-rest-dispatch.js";
@@ -12,19 +11,14 @@ describe("Google Workspace REST transport eligibility", () => {
expect(googleWorkspaceRestTransportGaps()).toEqual([]);
});
it("finds Calendar fully implemented and Gmail not yet", () => {
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, calendar: "paperclip_rest" })).toEqual([]);
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, gmail: "paperclip_rest" }).map((gap) => gap.service)).toEqual(["gmail"]);
it("finds Gmail and Calendar fully implemented and Chat not", () => {
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, gmail: "paperclip_rest", calendar: "paperclip_rest" })).toEqual([]);
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, chat: "paperclip_rest" }).map((gap) => gap.service)).toEqual(["chat"]);
});
it("names the missing tools of a partially implemented or unimplemented service", () => {
const flipped = { ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, gmail: "paperclip_rest" as const, chat: "paperclip_rest" as const };
const implemented = new Set(listGoogleWorkspaceRest("gmail").map((tool) => tool.name));
const gaps = googleWorkspaceRestTransportGaps(flipped);
expect(gaps.map((gap) => gap.service)).toEqual(["gmail", "chat"]);
expect(gaps[0]!.missing).toEqual(googleWorkspaceServiceToolNames("gmail").filter((name) => !implemented.has(name)));
expect(gaps[0]!.missing.length).toBeGreaterThan(0);
expect(gaps[1]!.missing).toEqual(googleWorkspaceServiceToolNames("chat"));
it("names every missing tool of a service with no REST tools", () => {
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, chat: "paperclip_rest" }))
.toEqual([{ service: "chat", missing: googleWorkspaceServiceToolNames("chat") }]);
});
});
@@ -260,8 +260,8 @@
"packages/shared/src/github-connectors.ts": "b8448b1eddac9a9d1308b94e4d136c761cbd4a00",
"packages/shared/src/github-skill-repository.ts": "b00a9963472723bcb7fcd433aae442f75d7a138b",
"packages/shared/src/gitignore-runtime.test.ts": "e334ab0eca8faeab5807171983ec9102a3f1c734",
"packages/shared/src/google-workspace-connectors.test.ts": "a441ae50fb0545e81a9a4b0bf8900dddd1f6137f",
"packages/shared/src/google-workspace-connectors.ts": "6ce5b91fc043302062a94a8ece4c3b305c366c48",
"packages/shared/src/google-workspace-connectors.test.ts": "07467b028d6c50b80171239b4a4850d4225be5ce",
"packages/shared/src/google-workspace-connectors.ts": "3adffe189f0eaf9cf258dd5193c1e89cb0305208",
"packages/shared/src/grok-bot.ts": "9de68f00e7926c397729ff62bf8e277f5a41c525",
"packages/shared/src/heartbeat-inbox.ts": "227dc89705c20460ca02194091cb162e11503186",
"packages/shared/src/home-paths.test.ts": "81235c17c376224e1be3abd3f034a8400f079c66",