openapi: 3.0.3
info:
  title: Mock Nafath Authentication API
  description: Mock API for Nafath authentication process simulation during development
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: http://localhost:8000/api/v1/auth/nafath/mock
    description: Local development server
  - url: https://api.example.com/api/v1/auth/nafath/mock
    description: Production server

tags:
  - name: Authentication
    description: Nafath authentication endpoints

paths:
  /start:
    post:
      tags:
        - Authentication
      summary: Start Nafath authentication
      description: Initialize a new Nafath authentication attempt (supports both OIDC and MFA flows)
      operationId: startAuthentication
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  enum: [ar, en]
                  default: ar
                  description: Preferred language locale
                national_id:
                  type: string
                  pattern: '^[1234569]\d{9}$'
                  description: National ID for MFA flow (optional for OIDC flow)
              example:
                locale: ar
                national_id: "1234567890"
      responses:
        '201':
          description: Authentication attempt created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StartResponse'
              examples:
                oidc:
                  summary: OIDC Flow Response
                  value:
                    data:
                      attempt_id: "550e8400-e29b-41d4-a716-446655440000"
                      attempt_token: "abc123xyz456def789ghi012jkl345mno678pqr901stu234vwx567yz"
                      authorization_url: "http://localhost:8000/api/v1/auth/nafath/mock/callback?state=550e8400-e29b-41d4-a716-446655440000"
                      expires_at: "2025-01-01T12:00:00+00:00"
                mfa:
                  summary: MFA Flow Response
                  value:
                    data:
                      attempt_id: "550e8400-e29b-41d4-a716-446655440000"
                      attempt_token: "abc123xyz456def789ghi012jkl345mno678pqr901stu234vwx567yz"
                      random: "123456"
                      expires_at: "2025-01-01T12:00:00+00:00"
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /status/{attempt_id}:
    get:
      tags:
        - Authentication
      summary: Check authentication status
      description: Check the current status of a Nafath authentication attempt
      operationId: getStatus
      parameters:
        - name: attempt_id
          in: path
          required: true
          description: The authentication attempt ID
          schema:
            type: string
            format: uuid
        - name: X-Nafath-Attempt-Token
          in: header
          required: true
          description: The attempt token received from start endpoint
          schema:
            type: string
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StatusResponse'
              examples:
                pending:
                  summary: Pending Status
                  value:
                    data:
                      attempt_id: "550e8400-e29b-41d4-a716-446655440000"
                      status: pending
                      provider_status: PENDING
                      message: null
                      token_ready: false
                      user: null
                authenticated:
                  summary: Authenticated Status
                  value:
                    data:
                      attempt_id: "550e8400-e29b-41d4-a716-446655440000"
                      status: authenticated
                      provider_status: COMPLETED
                      message: null
                      token_ready: true
                      user:
                        id: 1
                        national_id: "1234567890"
                        name: Mock User
                        arabic_name: "مستخدم تجريبي"
                        english_name: Mock User
                        preferred_locale: ar
                        nationality: SA
                        gender: M
                        assurance_level: 3
                        last_auth_method: nafath
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /callback:
    post:
      tags:
        - Authentication
      summary: Complete OIDC authentication
      description: Simulate Nafath callback for OIDC flow authentication
      operationId: completeCallback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - state
              properties:
                state:
                  type: string
                  description: The state parameter (attempt ID)
                auto_complete:
                  type: boolean
                  default: true
                  description: Automatically complete the authentication
              example:
                state: "550e8400-e29b-41d4-a716-446655440000"
                auto_complete: true
      responses:
        '200':
          description: Callback completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  attempt_id:
                    type: string
                  redirect_to:
                    type: string
              example:
                success: true
                message: Mock authentication completed successfully
                attempt_id: "550e8400-e29b-41d4-a716-446655440000"
                redirect_to: "http://localhost:8000/dashboard"
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /complete-mfa:
    post:
      tags:
        - Authentication
      summary: Complete MFA authentication
      description: Simulate MFA completion for mobile flow authentication
      operationId: completeMfa
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - attempt_id
              properties:
                attempt_id:
                  type: string
                  description: The authentication attempt ID
              example:
                attempt_id: "550e8400-e29b-41d4-a716-446655440000"
      responses:
        '200':
          description: MFA completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  attempt_id:
                    type: string
              example:
                success: true
                message: Mock MFA completed successfully
                attempt_id: "550e8400-e29b-41d4-a716-446655440000"
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /token/{attempt_id}:
    post:
      tags:
        - Authentication
      summary: Get API token
      description: Exchange authenticated attempt for API token
      operationId: getToken
      parameters:
        - name: attempt_id
          in: path
          required: true
          description: The authenticated attempt ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - attempt_token
                - device_name
              properties:
                attempt_token:
                  type: string
                  description: The attempt token
                device_name:
                  type: string
                  maxLength: 100
                  description: Device name for the token
              example:
                attempt_token: "abc123xyz456def789ghi012jkl345mno678pqr901stu234vwx567yz"
                device_name: "Test Device"
      responses:
        '200':
          description: Token issued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TokenResponse'
              example:
                data:
                  token: "plain-api-token-string"
                  token_type: Bearer
                  expires_at: "2025-01-01T13:00:00+00:00"
                  user:
                    id: 1
                    national_id: "1234567890"
                    name: Mock User
                    arabic_name: "مستخدم تجريبي"
                    english_name: Mock User
                    preferred_locale: ar
                    nationality: SA
                    gender: M
                    assurance_level: 3
                    last_auth_method: nafath
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Authentication not complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Nafath authentication is not complete.
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  schemas:
    StartResponse:
      type: object
      properties:
        attempt_id:
          type: string
          format: uuid
          description: Unique authentication attempt ID
        attempt_token:
          type: string
          minLength: 64
          maxLength: 64
          description: Secure token for this attempt
        authorization_url:
          type: string
          description: OAuth authorization URL (OIDC flow only)
        random:
          type: string
          pattern: '^\d{6}$'
          description: 6-digit random code (MFA flow only)
        expires_at:
          type: string
          format: date-time
          description: Expiration timestamp

    StatusResponse:
      type: object
      properties:
        attempt_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, processing, authenticated, failed, expired]
        provider_status:
          type: string
          enum: [PENDING, PROCESSING, COMPLETED, FAILED]
        message:
          type: string
          nullable: true
        token_ready:
          type: boolean
        user:
          $ref: '#/components/schemas/User'

    TokenResponse:
      type: object
      properties:
        token:
          type: string
          description: Plain API token
        token_type:
          type: string
          enum: [Bearer]
        expires_at:
          type: string
          format: date-time
          nullable: true
        user:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id:
          type: integer
        national_id:
          type: string
          pattern: '^\d{10}$'
        name:
          type: string
        arabic_name:
          type: string
        english_name:
          type: string
        preferred_locale:
          type: string
          enum: [ar, en]
        nationality:
          type: string
        gender:
          type: string
          enum: [M, F]
        assurance_level:
          type: integer
          minimum: 1
          maximum: 3
        last_auth_method:
          type: string

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
          example:
            message: Login attempt not found.

    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
          example:
            message: Too many attempts. Please try again later.
