WIP: Specify Content-Disposition and Content-Type semantics on /download and /thumbnail

content/client-server-api/modules/content_repo.md

@@ -119,3 +119,40 @@ Homeservers have additional content-specific concerns:
 -   Clients or remote homeservers may try to upload malicious files
     targeting vulnerabilities in either the homeserver thumbnailing or
     the client decoders.
+
+##### Serving inline content
+
+Clients with insecure configurations may be vulnerable to Cross-Site Scripting
+attacks when served media with a `Content-Disposition` of `inline`. Clients
+SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver
+to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to
+one of the following values when serving content with `Content-Disposition: inline`:
+
+* `text/css`
+* `text/plain`
+* `text/csv`
+* `application/json`
+* `application/ld+json`
+* `image/jpeg`
+* `image/gif`
+* `image/png`
+* `image/apng`
+* `image/webp`
+* `image/avif`
+* `video/mp4`
+* `video/webm`
+* `video/ogg`
+* `video/quicktime`
+* `audio/mp4`
+* `audio/webm`
+* `audio/aac`
+* `audio/mpeg`
+* `audio/ogg`
+* `audio/wave`
+* `audio/wav`
+* `audio/x-wav`
+* `audio/x-pn-wav`
+* `audio/flac`
+* `audio/x-flac`
+
+These types are unlikely to cause Cross-Site Scripting issues within clients.

data/api/client-server/content-repo.yaml

@@ -637,8 +637,22 @@ paths:
         "200":
           description: A thumbnail of the requested content.
           headers:
+            Content-Disposition:
+              x-addedInMatrixVersion: "1.10"
+              description: |
+                **Required**. The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
+                of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`).
+
+                Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content),
+                as these limitations imply which formats should be used for thumbnail generation.
+              schema:
+                type: string
+                example: "inline; filename=\"thumbnail.png\""
             Content-Type:
-              description: The content type of the thumbnail.
+              x-changedInMatrixVersion:
+                "1.10": |
+                  This header became required in order to support `Content-Disposition`.
+              description: "**Required**. The content type of the thumbnail."
               schema:
                 type: string
                 enum: