mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
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:
1 parent
01451fae5b
commit
7f1f0eef67
12 files changed
+251
-56
No files matched your search
@@ -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") }]);
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Reference in new issue
Block a user