openwork/docs/google-workspace-oauth-verification.md

Google Workspace OAuth Verification

Project

• Google Cloud project: OpenWork Google Workspace
• Project ID: noted-victory-497500-f9
• OAuth app name: OpenWork
• Support email: team@openworklabs.com
• Homepage: https://openworklabs.com
• Privacy policy: https://openworklabs.com/privacy
• Terms: https://openworklabs.com/terms
• Authorized domain: openworklabs.com
• Desktop OAuth client ID: 929071212606-pmkqimjhm2tnp68kbklnout0irllj99h.apps.googleusercontent.com

Phase 1 Scopes

openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/gmail.compose

Opt-In Scopes (Custom OAuth Client Only)

These scopes are never requested by the built-in OpenWork OAuth client. They are only requested when the user supplies their own Google OAuth client and explicitly enables the matching permission in Settings -> Extensions -> Google Workspace -> Advanced:

https://www.googleapis.com/auth/gmail.readonly        (Read Gmail)
https://www.googleapis.com/auth/drive                 (Full Google Drive access)
https://www.googleapis.com/auth/calendar.events       (Create calendar events)
https://www.googleapis.com/auth/chat.spaces.readonly  (Google Chat)
https://www.googleapis.com/auth/chat.messages.readonly
https://www.googleapis.com/auth/chat.messages.create

Each opt-in permission is enforced per account at runtime: extension actions that need a scope return a 403 (google_gmail_read_not_granted, google_calendar_write_not_granted, google_chat_not_granted) when the connected account did not grant it.

Scope Justifications

openid, userinfo.email, userinfo.profile

OpenWork uses these scopes to identify the connected Google account in the app, display the signed-in account email to the user, and help users confirm they connected the intended Google account.

calendar.readonly

OpenWork uses this scope to read upcoming Google Calendar events when the user asks for meeting context or meeting preparation. OpenWork does not modify calendars with this scope. The initial Google Workspace integration uses calendar data to show event title, time, attendees, and linked resources so the user can prepare for upcoming meetings.

drive.file

OpenWork uses this scope to access only the specific Google Drive files that the user selects, opens, or creates with OpenWork. OpenWork does not request broad Drive read access in Phase 1. This lets the user ask OpenWork to summarize or use a selected document while keeping the rest of the user's Drive outside the app's access.

gmail.compose

OpenWork uses this scope to create Gmail drafts for the user to review in Gmail. Phase 1 does not expose an automatic send-email tool. Draft creation is used for workflows like drafting a meeting follow-up after the user asks for it. Users remain in control and send messages themselves from Gmail.

Data Use Statement

OpenWork uses Google Workspace data only to provide user-requested features, such as reading calendar context, reading explicitly selected Drive files, and creating Gmail drafts. OpenWork does not sell Google user data, use Google user data for advertising, or use Google user data to train generalized AI models. Desktop OAuth tokens are stored locally using encrypted OS storage when available.

Deployment Mode

The default desktop flow uses a Google Desktop OAuth client with PKCE and a loopback redirect. The desktop app exchanges authorization codes directly with Google and stores user tokens locally in encrypted OS storage.

For installed desktop apps, Google may provide both a client_id and client_secret. In this context, the client_secret is client metadata, not a confidential backend secret, because any value shipped in a desktop binary can be extracted. It is acceptable for official OpenWork desktop builds to include the OpenWork-owned Google Desktop OAuth client metadata, while user access tokens and refresh tokens must remain protected and must never be committed.

For local development, pass OPENWORK_GOOGLE_WORKSPACE_OAUTH_CLIENT_SECRET from the Google Cloud desktop client metadata instead of committing it to source. This keeps source checkouts and forks from accidentally reusing the official OpenWork OAuth client metadata unless they opt in explicitly.

Demo Video Script

Google's verification video should show the OAuth consent flow and each requested sensitive/restricted scope in use.

1. Start OpenWork Desktop with the Google Workspace desktop OAuth client metadata:

   OPENWORK_GOOGLE_WORKSPACE_OAUTH_CLIENT_ID="929071212606-pmkqimjhm2tnp68kbklnout0irllj99h.apps.googleusercontent.com" \
   OPENWORK_GOOGLE_WORKSPACE_OAUTH_CLIENT_SECRET="<desktop-client-secret-from-google-cloud>" \
   pnpm dev
   

2. Open Settings -> Extensions -> Google Workspace.

3. Show the extension panel describing Phase 1 capabilities:

   • Calendar read.
   • Gmail drafts.
   • Selected Drive files.

4. Click Connect with Google.

5. Show the Google OAuth consent screen, including the app name OpenWork and requested scopes.

6. Approve access with a test account.

7. Return to OpenWork and show the connected account email.

8. Click Test connection and show profile + Calendar read access verified.

9. Click Run scope smoke test and show the success state, including the created Drive file and Gmail draft IDs. This verifies all requested Phase 1 scopes:

   • Calendar read through the Calendar API.
   • Drive selected/app-created file access by creating and reading OpenWork Google Workspace smoke test.txt.
   • Gmail compose access by creating OpenWork Google Workspace smoke test draft in Gmail drafts.

10. Open Google Drive and show the created smoke-test file.

11. Open Gmail drafts and show the created smoke-test draft. State that OpenWork created a draft only and did not send email automatically.

12. Click Disconnect in OpenWork and state that OpenWork revokes the Google OAuth token and removes the local encrypted token vault entry.

Daytona Recording Plan

Use Daytona for a clean, repeatable Electron recording:

bash .devcontainer/test-on-daytona.sh feature/google-workspace-phase-1 --record-video --recording-name google-workspace-oauth-phase-1

Then open the noVNC URL printed by the script, sign in to the Google test account when the OAuth browser opens, and complete the script above while recording.

If the sandbox does not have the Google OAuth client metadata in the environment, restart Electron with:

OPENWORK_GOOGLE_WORKSPACE_OAUTH_CLIENT_ID="929071212606-pmkqimjhm2tnp68kbklnout0irllj99h.apps.googleusercontent.com" \
OPENWORK_GOOGLE_WORKSPACE_OAUTH_CLIENT_SECRET="<desktop-client-secret-from-google-cloud>" \
bash /opt/openwork-daytona/start-daytona-electron.sh --detach

Current Verification Blockers

• gmail.compose is a restricted Gmail scope. Google may require restricted-scope verification and possibly additional security review.
• The privacy policy source includes Google Workspace data-use language, but it must be deployed publicly before submitting verification.