# OAuth2 Social Login — {{provider}}

## Overview
Implement OAuth2 social login via {{provider}} with secure token handling and session management lasting {{session_duration}} seconds.

## Acceptance Criteria

### AC-1: OAuth Authorization Flow
- Redirect users to {{provider}} authorization endpoint with correct scopes
- Handle the callback at {{callback_path}} and exchange code for tokens
- Validate the `state` parameter to prevent CSRF attacks

### AC-2: User Account Linking
- Create a new user account if the OAuth identity does not exist
- Link the OAuth identity to an existing account if the email matches
- Store the provider, provider user ID, and access token securely

### AC-3: Session Management
- Issue a signed session token valid for {{session_duration}} seconds after successful login
- Invalidate session on explicit logout
- Refresh session silently when less than 10% of lifetime remains

### AC-4: Error Handling
- Return clear errors when the user denies authorization
- Handle provider API outages with a user-friendly fallback message
- Log all authentication failures with anonymized user identifiers

## Technical Notes
- Never store OAuth access tokens in client-accessible cookies
- Use PKCE (Proof Key for Code Exchange) when supported by the provider
- Implement rate limiting on the callback endpoint to prevent abuse
