[feature] Self-serve email change for users (#2957)

* [feature] Email change

* frontend stuff for changing email

* docs

* tests etc

* differentiate more clearly between local user+account and account

* populate user

docs/api/swagger.yaml

@@ -2713,6 +2713,77 @@ definitions:
         type: object
         x-go-name: Theme
         x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
+    user:
+        properties:
+            admin:
+                description: User is an admin.
+                example: false
+                type: boolean
+                x-go-name: Admin
+            approved:
+                description: User was approved by an admin.
+                example: true
+                type: boolean
+                x-go-name: Approved
+            confirmation_sent_at:
+                description: Time when the last "please confirm your email address" email was sent, if at all. (ISO 8601 Datetime)
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: ConfirmationSentAt
+            confirmed_at:
+                description: Time at which the email given in the `email` field was confirmed, if at all. (ISO 8601 Datetime)
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: ConfirmedAt
+            created_at:
+                description: Time this user was created. (ISO 8601 Datetime)
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: CreatedAt
+            disabled:
+                description: User's account is disabled.
+                example: false
+                type: boolean
+                x-go-name: Disabled
+            email:
+                description: Confirmed email address of this user, if set.
+                example: someone@example.org
+                type: string
+                x-go-name: Email
+            id:
+                description: Database ID of this user.
+                example: 01FBVD42CQ3ZEEVMW180SBX03B
+                type: string
+                x-go-name: ID
+            last_emailed_at:
+                description: Time at which this user was last emailed, if at all. (ISO 8601 Datetime)
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: LastEmailedAt
+            moderator:
+                description: User is a moderator.
+                example: false
+                type: boolean
+                x-go-name: Moderator
+            reason:
+                description: Reason for sign-up, if provided.
+                example: Please! Pretty please!
+                type: string
+                x-go-name: Reason
+            reset_password_sent_at:
+                description: Time when the last "please reset your password" email was sent, if at all. (ISO 8601 Datetime)
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: ResetPasswordSentAt
+            unconfirmed_email:
+                description: Unconfirmed email address of this user, if set.
+                example: someone.else@somewhere.else.example.org
+                type: string
+                x-go-name: UnconfirmedEmail
+        title: User models fields relevant to one user.
+        type: object
+        x-go-name: User
+        x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
     wellKnownResponse:
         description: See https://webfinger.net/
         properties:
@@ -8636,6 +8707,77 @@ paths:
             summary: See public statuses that use the given hashtag (case insensitive).
             tags:
                 - timelines
+    /api/v1/user:
+        get:
+            operationId: getUser
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: The requested user.
+                    schema:
+                        $ref: '#/definitions/user'
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "403":
+                    description: forbidden
+                "406":
+                    description: not acceptable
+                "500":
+                    description: internal error
+            security:
+                - OAuth2 Bearer:
+                    - read:user
+            summary: Get your own user model.
+            tags:
+                - user
+    /api/v1/user/email_change:
+        post:
+            consumes:
+                - application/json
+                - application/xml
+                - application/x-www-form-urlencoded
+            operationId: userEmailChange
+            parameters:
+                - description: User's current password, for verification.
+                  in: formData
+                  name: password
+                  required: true
+                  type: string
+                  x-go-name: Password
+                - description: Desired new email address.
+                  in: formData
+                  name: new_email
+                  required: true
+                  type: string
+                  x-go-name: NewEmail
+            produces:
+                - application/json
+            responses:
+                "202":
+                    description: 'Accepted: email change is processing; check your inbox to confirm new address.'
+                    schema:
+                        $ref: '#/definitions/user'
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "403":
+                    description: forbidden
+                "406":
+                    description: not acceptable
+                "409":
+                    description: 'Conflict: desired email address already in use'
+                "500":
+                    description: internal error
+            security:
+                - OAuth2 Bearer:
+                    - write:user
+            summary: Request changing the email address of authenticated user.
+            tags:
+                - user
     /api/v1/user/password_change:
         post:
             consumes:

docs/user_guide/settings.md

@@ -133,11 +133,13 @@ See the [Custom CSS](./custom_css.md) page for some tips on writing custom CSS f
 !!! tip
     Any custom CSS you add in this box will be applied *after* your selected theme, so you can pick a preset theme that you like and then make your own tweaks!
 
-## Post Settings
+## Settings
 
-![Screenshot of the user settings section, providing drop-down menu's to select default post settings, and form fields to change your password](../assets/user-settings-post-settings.png)
+![Screenshot of the settings section](../assets/user-settings-settings.png)
 
-In the 'Settings' section, you can set various defaults for new posts.
+In the 'Settings' section, you can set various defaults for new posts, and change your password / email address.
+
+### Post Settings
 
 The default post language setting allows you to indicate to other fediverse users which language your posts are usually written in. This is helpful for fediverse users who speak (for example) Korean, and would prefer to filter out posts written in other languages.
 
@@ -151,12 +153,18 @@ The markdown setting indicates that your posts should be parsed as Markdown, whi
 
 When you are finished updating your post settings, remember to click the `Save post settings` button at the bottom of the section to save your changes.
 
-## Password Change
+### Password Change
 
-You can use the Password Change section of the User Settings Panel to set a new password for your account.
+You can use the Password Change section of the panel to set a new password for your account. For security reasons, you must provide your current password to validate the change.
 
 For more information on the way GoToSocial manages passwords, please see the [Password management document](./password_management.md).
 
+### Email Change
+
+You can use the Email Change section of the panel to change the email address for your account. For security reasons, you must provide your current password to validate the change.
+
+Once a new email address has been entered, and you have clicked "Change email address", you must open the inbox of the new email address and confirm your address via the link provided. Once you've done that, your email address change will be confirmed, and you should use the new email address to log in.
+
 ## Migration
 
 In the migration section you can manage settings related to aliasing and/or migrating your account to another account.