"/auth/forgot":
    post:
        tags: [Password]
        operationId: handleForgotPasswordRequest
        summary: Send a password-reset email
        description: |
            Issues a password-reset email to the supplied address. Always
            returns `200` whether or not the address is registered — the
            client must not be able to enumerate accounts by error
            response. In `dev_local` / test environments only, the
            generated `resetPasswordToken` is echoed in the body for
            integration tests.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [email]
                        properties:
                            email: { type: string, format: email }
        responses:
            "200":
                description: Reset email queued (or no-op if the address is unknown).
                content:
                    application/json:
                        schema:
                            type: object
                            required: [result]
                            properties:
                                result: { type: string, example: OK }
                                resetPasswordToken:
                                    type: string
                                    description: |
                                        Only present in `dev_local` / test
                                        environments — never in production.
            "401": { $ref: "../auth-api.yaml#/components/responses/Unauthorized" }

"/auth/reset/{resetPasswordToken}":
    parameters:
        - in: path
          name: resetPasswordToken
          required: true
          schema: { type: string }
    get:
        tags: [Password]
        operationId: verifyResetPasswordToken
        summary: Verify a password-reset token
        description: |
            Confirms the supplied token is valid (issued, unconsumed, not
            expired). Used by the reset UI to gate the password form.
        responses:
            "200":
                description: Token is valid.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [message]
                            properties:
                                message: { type: string, example: OK }
            "401": { $ref: "../auth-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: Token is unknown, consumed, or expired.
                content:
                    application/json:
                        schema: { $ref: "../auth-api.yaml#/components/schemas/Error" }

"/auth/reset":
    post:
        tags: [Password]
        operationId: handleResetPassword
        summary: Reset password
        description: |
            Sets a new password on the account behind the supplied
            `token`. Token is consumed on success.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [token, password]
                        properties:
                            token:
                                type: string
                                description: |
                                    The reset token from the
                                    `/auth/forgot` email — same value
                                    as the URL-path parameter on
                                    `/auth/reset/{resetPasswordToken}`.
                            password: { type: string, format: password }
        responses:
            "200":
                description: Password reset.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [message]
                            properties:
                                message: { type: string, example: OK }
            "401":
                description: Hash failed or update failed.
                content:
                    application/json:
                        schema: { $ref: "../auth-api.yaml#/components/schemas/Error" }
            "404":
                description: Token unknown / consumed / expired.
                content:
                    application/json:
                        schema: { $ref: "../auth-api.yaml#/components/schemas/Error" }
            "422":
                description: Validation failed (missing token, weak password).
                content:
                    application/json:
                        schema:
                            type: object
                            additionalProperties: true

"/auth/resend":
    get:
        tags: [Password]
        operationId: resendEmailVerificationTicket
        summary: Resend the email-verification email
        description: |
            Resends the email-verification message to the address on the
            authenticated account. Required because brand-new accounts may
            misplace the original. In `dev_local` only, the generated
            confirmation token is echoed under `data.emailConfirmToken`
            for integration tests.
        responses:
            "200":
                description: Verification email queued.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [message]
                            properties:
                                message: { type: string, example: OK }
                                data:
                                    type: object
                                    description: Only present in `dev_local`.
                                    properties:
                                        emailConfirmToken: { type: string }
            "401": { $ref: "../auth-api.yaml#/components/responses/Unauthorized" }
