frontend/specs/001-google-oauth-auth/spec.md

Feature Specification: Google OAuth Authentication Screen

Feature Branch: 001-google-oauth-auth Created: 2026-01-29 Status: Draft Input: User description: "реализовать экран авторизации для того чтобы начать пользоваться инструментом, авторизация должна быть через кнопку google oauth"

Clarifications

Session 2026-01-29

• Q: Which OAuth flow type should be used (popup vs redirect)? → A: Redirect flow (full page redirect to Google, then back)
• Q: Post-login redirect behavior for deep links? → A: Return to originally requested page (preserve intended destination)

User Scenarios & Testing (mandatory)

User Story 1 - First-Time User Sign In (Priority: P1)

A new user visits the ThumbPreview tool for the first time. Before accessing the main functionality (thumbnail preview tool), they are presented with a clean authentication screen. The user clicks the "Sign in with Google" button, completes the Google OAuth flow via full-page redirect to Google and back, and upon successful authentication is automatically redirected to the tool page.

Why this priority: This is the core functionality - without authentication, users cannot access the tool. It gates the entire application experience.

Independent Test: Can be fully tested by visiting the app as a logged-out user, clicking the Google sign-in button, completing OAuth, and verifying access to the tool page is granted.

Acceptance Scenarios:

1. Given a user is not authenticated, When they navigate to any protected page, Then they are redirected to the authentication screen
2. Given a user is on the authentication screen, When they click "Sign in with Google", Then the Google OAuth consent flow initiates
3. Given a user completes Google OAuth successfully, When the callback is processed, Then the user is redirected to their originally requested page (or /tool by default) with an active session

---

User Story 2 - Returning User Session (Priority: P2)

A previously authenticated user returns to the application. If their session is still valid, they bypass the authentication screen and go directly to the tool. If the session has expired, they are shown the authentication screen to sign in again.

Why this priority: Provides a seamless experience for returning users while maintaining security through session management.

Independent Test: Can be tested by authenticating, closing the browser, returning within session validity period, and verifying automatic access without re-authentication.

Acceptance Scenarios:

1. Given a user has an active session, When they navigate to the application, Then they are taken directly to the tool page without seeing the auth screen
2. Given a user's session has expired, When they navigate to the application, Then they are redirected to the authentication screen

---

User Story 3 - User Sign Out (Priority: P3)

An authenticated user wants to sign out of the application. They can access a sign-out option which clears their session and returns them to the authentication screen.

Why this priority: Essential for security and multi-user scenarios, but secondary to the core sign-in flow.

Independent Test: Can be tested by signing in, clicking sign out, and verifying the session is cleared and the user is returned to the auth screen.

Acceptance Scenarios:

1. Given a user is authenticated, When they click the sign-out option, Then their session is terminated and they are redirected to the authentication screen
2. Given a user has signed out, When they try to access the tool page directly, Then they are redirected to the authentication screen

---

Edge Cases

• What happens when Google OAuth is cancelled or fails mid-flow? User should remain on the auth screen with an error message indicating the sign-in was not completed.
• What happens when a user's Google account is deactivated or access is revoked? Session should be invalidated and user redirected to auth screen on next request.
• What happens if the network connection is lost during OAuth? User should see an appropriate error message and be able to retry.
• What happens if user denies Google permissions? User remains on auth screen with a message explaining that permissions are required.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST display an authentication screen to unauthenticated users before allowing access to the tool
• FR-002: System MUST provide a "Sign in with Google" button on the authentication screen
• FR-003: System MUST initiate Google OAuth 2.0 authorization flow when the sign-in button is clicked
• FR-004: System MUST create a user session upon successful Google OAuth callback
• FR-005: System MUST redirect authenticated users to their originally requested page after successful sign-in (defaulting to /tool if no prior destination)
• FR-006: System MUST persist user sessions to allow returning users to bypass authentication
• FR-007: System MUST provide a sign-out mechanism that terminates the user session
• FR-008: System MUST protect all tool routes, redirecting unauthenticated requests to the auth screen
• FR-009: System MUST display appropriate error messages when authentication fails
• FR-010: System MUST store basic user profile information from Google (name, email, profile picture) for display purposes

Key Entities

• User: Represents an authenticated user. Key attributes: unique identifier, Google ID, email address, display name, profile picture URL, created timestamp, last login timestamp.
• Session: Represents an active authentication session. Key attributes: session identifier, associated user, creation time, expiration time, validity status.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can complete the full sign-in flow (from auth screen to tool access) in under 30 seconds
• SC-002: 95% of authentication attempts complete successfully on first try (excluding user-cancelled flows)
• SC-003: Returning users with valid sessions access the tool without seeing the auth screen
• SC-004: All tool pages are inaccessible to unauthenticated users
• SC-005: Sign-out action fully terminates the session, preventing access without re-authentication

Assumptions

• Google Cloud OAuth credentials will be configured as part of implementation
• Session validity period follows industry standard (reasonable default: 7 days with refresh capability)
• The landing page (/) remains publicly accessible; only the tool page (/tool) requires authentication
• User data stored is limited to what Google provides in the standard OAuth profile scope
• Email verification is handled by Google (only verified Google accounts can sign in)