Skip to content

docs(web): clarify google oauth popup cancellation behavior #1525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tyler-dane merged 1 commit into from
Mar 7, 2026
Merged

docs(web): clarify google oauth popup cancellation behavior #1525

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/feature-file-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ Use this document to find the first files to inspect for common Compass changes.

- Session initialization and SuperTokens wiring: `packages/web/src/auth/session/SessionProvider.tsx`
- User profile bootstrap: `packages/web/src/auth/context/UserProvider.tsx`
- Google OAuth app flow: `packages/web/src/auth/hooks/oauth/useGoogleAuth.ts`, `packages/web/src/auth/hooks/oauth/useGoogleAuthWithOverlay.ts`
- Google OAuth provider wrapper: `packages/web/src/components/oauth/google/useGoogleLogin.ts`
- Popup-cancel classification for Google OAuth: `packages/web/src/auth/google/google-oauth-error.util.ts`
- Auth schemas: `packages/web/src/auth/schemas/auth.schemas.ts`
- Backend auth routes: `packages/backend/src/auth/auth.routes.config.ts`
- Backend auth controllers/services: `packages/backend/src/auth/controllers`, `packages/backend/src/auth/services`
Expand Down
24 changes: 24 additions & 0 deletions docs/frontend-runtime-flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,30 @@ Once a user has ever authenticated, the app records that fact in local auth-stat

When a user re-authenticates with Google, auth-state utilities also clear any in-memory "Google revoked" flag so normal remote sync can resume.

## Google OAuth Popup Cancellation Semantics

Files:

- `packages/web/src/auth/hooks/oauth/useGoogleAuth.ts`
- `packages/web/src/components/oauth/google/useGoogleLogin.ts`
- `packages/web/src/auth/google/google-oauth-error.util.ts`

The web auth flow intentionally treats popup-close outcomes as cancellation, not authentication failure.

Cancellation detection (`isGooglePopupClosedError`) returns true when any of these match:

- `type === "popup_closed"`
- `error`, `error_description`, or `message` equals `"popup_closed"` (case-insensitive)
- `error`, `error_description`, or `message` contains `"popup window closed"` (case-insensitive)

When cancellation is detected in the auth hooks:

- auth state is reset (`resetAuth`)
- import overlay/progress flags are cleared (`setIsImportPending(false)`, `importing(false)`)
- generic auth failure state is not dispatched for that event

For non-cancellation errors, normal auth-failure handling still applies.

## User Bootstrap

File:
Expand Down