[feature] Add token review / delete to backend + settings panel (#3845)

3 files changed, 167 insertions, 0 deletions

diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml
index c8b263afe..25b23770c 100644
--- a/docs/api/swagger.yaml
+++ b/docs/api/swagger.yaml
@@ -3369,6 +3369,37 @@ definitions:
         type: object
         x-go-name: ThreadContext
         x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
+    tokenInfo:
+        description: The actual access token itself will never be sent via the API.
+        properties:
+            application:
+                $ref: '#/definitions/application'
+            created_at:
+                description: When the token was created (ISO 8601 Datetime).
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: CreatedAt
+            id:
+                description: Database ID of this token.
+                example: 01JMW7QBAZYZ8T8H73PCEX12XG
+                type: string
+                x-go-name: ID
+            last_used:
+                description: |-
+                    Approximate time (accurate to within an hour) when the token was last used (ISO 8601 Datetime).
+                    Omitted if token has never been used, or it is not known when it was last used (eg., it was last used before tracking "last_used" became a thing).
+                example: "2021-07-30T09:20:25+00:00"
+                type: string
+                x-go-name: LastUsed
+            scope:
+                description: OAuth scopes granted by the token, space-separated.
+                example: read write admin
+                type: string
+                x-go-name: Scope
+        title: TokenInfo represents metadata about one user-level access token.
+        type: object
+        x-go-name: TokenInfo
+        x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
     user:
         properties:
             admin:
@@ -11642,6 +11673,124 @@ paths:
             summary: See public statuses that use the given hashtag (case insensitive).
             tags:
                 - timelines
+    /api/v1/tokens:
+        get:
+            description: |-
+                The items will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
+
+                The returned Link header can be used to generate the previous and next queries when paging up or down.
+
+                Example:
+
+                ```
+                <https://example.org/api/v1/tokens?limit=20&max_id=01FC3GSQ8A3MMJ43BPZSGEG29M>; rel="next", <https://example.org/api/v1/tokens?limit=20&min_id=01FC3KJW2GYXSDDRA6RWNDM46M>; rel="prev"
+                ````
+            operationId: tokensInfoGet
+            parameters:
+                - description: Return only items *OLDER* than the given max status ID. The item with the specified ID will not be included in the response.
+                  in: query
+                  name: max_id
+                  type: string
+                - description: Return only items *newer* than the given since status ID. The item with the specified ID will not be included in the response.
+                  in: query
+                  name: since_id
+                  type: string
+                - description: Return only items *immediately newer* than the given since status ID. The item with the specified ID will not be included in the response.
+                  in: query
+                  name: min_id
+                  type: string
+                - default: 20
+                  description: Number of items to return.
+                  in: query
+                  name: limit
+                  type: integer
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: Array of token info entries.
+                    headers:
+                        Link:
+                            description: Links to the next and previous queries.
+                            type: string
+                    schema:
+                        items:
+                            $ref: '#/definitions/tokenInfo'
+                        type: array
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+            security:
+                - OAuth2 Bearer:
+                    - read:accounts
+            summary: See info about tokens created for/by your account.
+            tags:
+                - tokens
+    /api/v1/tokens/{id}:
+        get:
+            operationId: tokenInfoGet
+            parameters:
+                - description: The id of the requested token.
+                  in: path
+                  name: id
+                  required: true
+                  type: string
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: The requested token.
+                    schema:
+                        $ref: '#/definitions/tokenInfo'
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "404":
+                    description: not found
+                "406":
+                    description: not acceptable
+                "500":
+                    description: internal server error
+            security:
+                - OAuth2 Bearer:
+                    - read:accounts
+            summary: Get information about a single token.
+            tags:
+                - tokens
+    /api/v1/tokens/{id}/invalidate:
+        post:
+            operationId: tokenInvalidatePost
+            parameters:
+                - description: The id of the target token.
+                  in: path
+                  name: id
+                  required: true
+                  type: string
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: Info about the invalidated token.
+                    schema:
+                        $ref: '#/definitions/tokenInfo'
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "404":
+                    description: not found
+                "406":
+                    description: not acceptable
+                "500":
+                    description: internal server error
+            security:
+                - OAuth2 Bearer:
+                    - write:accounts
+            summary: Invalidate the target token, removing it from the database and making it unusable.
+            tags:
+                - tokens
     /api/v1/user:
         get:
             operationId: getUser
diff --git a/docs/overrides/public/user-settings-access-tokens.png b/docs/overrides/public/user-settings-access-tokens.png
new file mode 100644
index 000000000..a710bdd23
--- /dev/null
+++ b/docs/overrides/public/user-settings-access-tokens.png
diff --git a/docs/user_guide/settings.md b/docs/user_guide/settings.md
index 691181cb9..7e85e0ed8 100644
--- a/docs/user_guide/settings.md
+++ b/docs/user_guide/settings.md
@@ -269,3 +269,21 @@ Both merge and overwrite operations are idempotent, which basically means that d
 
 !!! warning
     The CSV format for mutes does not contain expiration data, so temporary mutes are exported (and imported) as permanent mutes.
+
+## Access Tokens
+
+In the access tokens section, you can review and invalidate [OAuth access tokens](https://www.oauth.com/oauth2-servers/access-tokens/) owned by applications that you have authorized to access your account and/or perform actions on your behalf.
+
+![The access tokens page.](../public/user-settings-access-tokens.png)
+
+In cases where you've logged in with an application multiple times, or logged in with multiple devices or browsers, you may see multiple tokens with the same application name. This is normal! For example, say you have logged in with Pinafore on both your phone and your laptop browser, you will see two different tokens owned by Pinafore.
+
+You can invalidate a token by clicking on the "Invalidate token" button under a token. This will remove the token from the database. The application that was authorized to access your account with that token will then no longer be authorized to do so, and you will need to log out and/or log in again with that application.
+
+Logging out of an application does not necessarily remove the token from the GoToSocial database, so old tokens may linger from applications you used a long time ago. So, feel free to invalidate tokens that have never been used, or haven't been used in a long time; it's good security practice to keep only the tokens that you need, and it's fun to click the big red button.
+
+!!! danger
+    If you see any tokens from applications that you do not recognize, or do not remember authorizing to access your account, then you should invalidate them, and consider changing your password as soon as possible.
+
+!!! note
+    Token "Last used" time is approximate and may be off by an hour in either direction.