post:
  operationId: login
  summary: Login with username and password
  description: |
    **Step 1 of 2-step login flow.**

    Validates the server-signed `tracking_id_jwt`, username and password,
    then verifies the client-signed `confirm_jwt` using `public_key`.
    On success the server creates a session and returns `user_id`,
    `session_id`, and `two_fa_status`:

    - `VERIFIED` — account has 2FA active; call `validate2FACode` to complete login.
    - `NOT_CONFIGURED` — account has no 2FA set up; redirect to the
      Setup 2FA screen.

    The client must not send a standalone tracking ID.
  tags: [staffManagement]
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/LoginRequest"
        example:
          username: "admin@example.com"
          password: "P@ssw0rd123"
          public_key:
            kty: "OKP"
            crv: "Ed25519"
            x: "..."
          confirm_jwt: "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
          tracking_id_jwt: "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
  responses:
    "200":
      description: Credentials valid — partial session info returned.
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/LoginResponse"
          example:
            is_valid: true
            user_id: "usr_staff_001"
            session_id: "665ff12a4b5c6d0012e34abc"
            role: "ADMIN"
            two_fa_status: "VERIFIED"
            failed_login_attempts: 0
            locked_login_expires_at: null
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"