frontend/specs/001-google-oauth-auth/contracts/auth-api.yaml

openapi: 3.0.3
info:
  title: ThumbPreview Auth API
  description: Authentication endpoints for Google OAuth integration
  version: 1.0.0

servers:
  - url: /api/auth
    description: Auth API base path

paths:
  /google:
    get:
      summary: Initiate Google OAuth flow
      description: Redirects user to Google consent screen. Called via browser navigation (not AJAX).
      operationId: initiateGoogleAuth
      tags:
        - OAuth
      responses:
        '302':
          description: Redirect to Google OAuth consent screen
          headers:
            Location:
              schema:
                type: string
              description: Google OAuth authorization URL

  /google/callback:
    get:
      summary: Google OAuth callback
      description: |
        Handles Google OAuth callback. Creates/updates user, issues tokens,
        redirects to frontend with access token.
      operationId: googleCallback
      tags:
        - OAuth
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
          description: OAuth authorization code from Google
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: OAuth state parameter (CSRF protection)
      responses:
        '302':
          description: Redirect to frontend with access token
          headers:
            Location:
              schema:
                type: string
              description: Frontend callback URL with token parameter
            Set-Cookie:
              schema:
                type: string
              description: HttpOnly refresh token cookie
        '401':
          description: OAuth validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /refresh:
    post:
      summary: Refresh access token
      description: |
        Uses refresh token from HttpOnly cookie to issue new access token.
        Rotates refresh token on each use.
      operationId: refreshToken
      tags:
        - Session
      security: []
      responses:
        '200':
          description: New tokens issued
          headers:
            Set-Cookie:
              schema:
                type: string
              description: New HttpOnly refresh token cookie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /me:
    get:
      summary: Get current user
      description: Returns the authenticated user's profile information
      operationId: getCurrentUser
      tags:
        - User
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /logout:
    post:
      summary: Sign out user
      description: |
        Revokes current refresh token and clears cookie.
        Access token remains valid until expiration (short-lived).
      operationId: logout
      tags:
        - Session
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully logged out
          headers:
            Set-Cookie:
              schema:
                type: string
              description: Cleared refresh token cookie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token in Authorization header

  schemas:
    AuthResponse:
      type: object
      required:
        - accessToken
        - user
      properties:
        accessToken:
          type: string
          description: JWT access token (15 min expiry)
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        user:
          $ref: '#/components/schemas/UserResponse'

    UserResponse:
      type: object
      required:
        - id
        - email
        - displayName
      properties:
        id:
          type: string
          format: uuid
          description: User unique identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
        displayName:
          type: string
          description: User display name
          example: John Doe
        avatarUrl:
          type: string
          format: uri
          nullable: true
          description: User profile picture URL
          example: https://lh3.googleusercontent.com/a/...

    MessageResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Success message
          example: Successfully logged out

    ErrorResponse:
      type: object
      required:
        - statusCode
        - message
      properties:
        statusCode:
          type: integer
          description: HTTP status code
          example: 401
        message:
          type: string
          description: Error message
          example: Invalid or expired token
        error:
          type: string
          description: Error type
          example: Unauthorized

tags:
  - name: OAuth
    description: Google OAuth authentication flow
  - name: Session
    description: Token management and session operations
  - name: User
    description: User profile operations