From 7606e5367b869523c50566ac2d68a6707d04dd10 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Sun, 23 Oct 2022 23:58:48 +0100
Subject: [PATCH 01/25] MSC3916: Authentication for media

---
 proposals/3916-authentication-for-media.md | 224 +++++++++++++++++++++
 1 file changed, 224 insertions(+)
 create mode 100644 proposals/3916-authentication-for-media.md

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
new file mode 100644
index 0000000000..ad05778e35
--- /dev/null
+++ b/proposals/3916-authentication-for-media.md
@@ -0,0 +1,224 @@
+# MSC3916: Authentication for media access, and new endpoint names
+
+Currently, access to media in Matrix has a number of problems including the following:
+ 
+* The only protection for media is the obscurity of the URL, and URLs are
+  easily leaked (eg accidental sharing, access
+  logs). [synapse#2150](https://github.com/matrix-org/synapse/issues/2150)
+* Anybody (including non-matrix users) can cause a homeserver to copy media
+  into its local
+  store. [synapse#2133](https://github.com/matrix-org/synapse/issues/2133)
+* When a media event is redacted, the media it used remains visible to all.
+  [synapse#1263](https://github.com/matrix-org/synapse/issues/1263)
+* There is currently no way to delete
+  media. [matrix-spec#226](https://github.com/matrix-org/matrix-spec/issues/226)
+* If a user requests GDPR erasure, their media remains visible to all.
+* When all users leave a room, their media is not deleted from the server.
+
+These problems are all difficult to address currently, because access to media
+is entirely unauthenticated. The first step for a solution is to require user
+authentication. Once that is done, it will be possible to impose authorization
+requirements to address the problems mentioned above. (See, for example,
+[MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911) which
+builds on top of this MSC.)
+
+This proposal supercedes [MSC1902](https://github.com/matrix-org/matrix-spec-proposals/pull/1902).
+
+## Proposal
+
+1. New endpoints
+
+   The existing `/_matrix/media/v3/` endpoints are to be deprecated, and replaced
+   by new endpoints under the `/_matrix/client` and `/_matrix/federation`
+   hierarchies.
+
+   The table below shows a mapping between old and new endpoint:
+
+   | Old                                                                                                                                                              | Client-Server                                                             | Federation                                                          |
+   | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+   | [`GET /_matrix/media/v3/preview_url`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3preview_url) | `GET /_matrix/client/v1/media/preview_url` | - |
+   | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
+   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
+   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
+   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | `GET /_matrix/federation/v1/media/thumbnail/{serverName}/{mediaId}` |
+
+   **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.4/client-server-api/#post_matrixmediav3upload)
+   is **not** modified by this MSC: it is intended that it be brought into line with the other
+   endpoints by a future MSC, such as [[MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
+
+2. Removal of `allow_remote` parameter from `/download`
+
+   The current `/download` and `/thumbnail` enpoints take an `allow_remote`
+   query parameter, indicating whether the server should request remote media
+   from other servers. This is redundant with the new endpoints, so will not be
+   supported.
+
+   Servers should never return remote media from `GET
+   /_matrix/federation/v1/media/download` or `GET
+   /_matrix/federation/v1/media/thumbnail`; indeed, the `serverName` is
+   included in the URI only for consistency with the CS-API.
+
+   `/_matrix/client/v1/media/download/` and
+   `/_matrix/client/v1/media/thumnbnail` should return remote media as normal.
+   
+3. Authentication on all endpoints
+
+   Currently, the `/download` and `/thumbnail` endpoints have no authentication
+   requirements. Under this proposal, the new endpoints will be authenticated
+   the same way as other endpoints: they will require an `Authorization` header
+   which must be `Bearer {accessToken}` for `/_matrix/client`, or the signature
+   for `/_matrix/federation`.
+
+4. Updated response format
+
+   * For the new `/_matrix/client` endpoints, the response format is the same as
+     the corresponding original endpoints.
+
+   * To enable future expansion, for the new `/_matrix/federation` endpoints,
+     the response is
+     [`multipart/mixed`](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)
+     content with two parts: the first must be a JSON object (and should have a
+     `Content-type: application/json` header), and the second is the media item
+     as per the original endpoints.
+
+     No properties are yet specified for the JSON object to be returned.
+
+     An example response:
+
+     ```
+     Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     Content-Type: application/json
+
+     {}
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     Content-Type: text/plain
+
+     This media is plain text. Maybe somebody used it as a paste bin.
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     ```
+     
+5. Backwards compatibility mechanisms
+
+   a. Backwards compatibility with older servers: if a client or requesting
+   server receives a 404 error with a non-JSON response, or a 400 or 404 error with
+   `{"errcode": "M_UNRECOGNIZED"}`, in response to a request to one of the new
+   endpoints, they may retry the request using the original endpoint.
+   
+   b. Backwards compatibility with older clients and federating servers:
+   servers may for a short time choose to allow unauthenticated access via the
+   deprecated endpoints.
+
+### Effects on client applications
+
+Naturally, implementations will be required to provide `Authorization` headers
+when accessing the new endpoints. This will be simple in some cases, but rather
+more involved in others. This section considers some of those cases.
+
+#### IRC/XMPP bridges
+
+Possibly the largest impact will be on IRC and XMPP bridges.  Since IRC and
+XMPP have no media repository of their own, these bridges currently transform
+`mxc:` URIs into `https://<server>/_matrix/media/v3/download/` URIs and forward
+those links to the remote platform. This will no longer be a viable option.
+
+One potential solution is for the bridges to provide a proxy.
+
+In this scenario, the bridge would have a secret HMAC key. When it
+receives a matrix event referencing a piece of media, it should create a new URI
+referencing the media, include an HMAC to prevent tampering. For example:
+
+```
+https://<bridge_server>/media/{originServerName}/{mediaId}?mac={hmac}
+```
+
+When the bridge later receives a request to that URI, it checks the hmac,
+and proxies the request to the homeserver, using its AS access
+token in the `Authorization` header.
+
+The bridge might also choose to embed information such as the room that
+referenced the media, and the time that the link was generated, in the URL.
+Such mechanisms would allow the bridge to impose controls such as:
+
+* Limiting the time a media link is valid for. Doing so would help prevent
+  visibility to users who weren't participating in the chat.
+
+* Rate-limiting the amount of media being shared in a particular room (in other
+  words, avoiding the use of Matrix as a Warez distribution system).
+
+#### Icons for "social login" flows
+
+When a server supports multiple login providers, it provides the client with
+icons for the login providers as `mxc:` media URIs. These must be accessible
+without authentication (because the client has no access token at the time the
+icons are displayed).
+
+This remains a somewhat unsolved problem. Possibly the clients can continue
+to call the legacy `/_matrix/media/v3/download` URI for now: ultimately this
+problem will be solved by the transition to OIDC. Alternatively, we may need
+to provide an alternative `/_matrix/client/v3/login/sso/icon/{idpId}` API
+specifically for access to these icon.
+
+(This was previously discussed in
+[MSC2858](https://github.com/matrix-org/matrix-spec-proposals/pull/2858#discussion_r543513811).)
+
+## Potential issues
+
+* Setting the `Authorization` header is going to be annoying for web clients. Service workers
+  might be needed.
+
+* Users will be unable to copy links to media from web clients to share out of
+  band. This is considered a feature, not a bug.
+
+## Alternatives
+
+* Allow clients to upload media which does not require authentication (for
+  example via a `public=true` query parameter). This might be particularly
+  useful for IRC/XMPP bridges, which could upload any media they encounter to
+  the homeserver's repository.
+
+  The danger with this is that is that there's little stopping clients
+  continuing to upload media as "public", negating all of the benefits in this
+  MSC. It might be ok if media upload it was restricted to certain privileged
+  users.
+
+* We could simply require that `Authorization` headers be given when calling
+  the existing endpoints. However, doing so would make it harder to evaluate
+  the proportion of clients which have been updated, and it is a good
+  opportunity to bring these endpoints into line with the rest of the
+  client-server and federation APIs.
+  
+* There's no real need to rename `GET /_matrix/media/v3/preview_url` and `GET
+  /_matrix/media/v3/config` at present, and we could just leave them in
+  place. However, changing them at the same time makes the API more consistent.
+
+  Conversely, we should make sure to rename `POST
+  /_matrix/media/v3/upload`. The reason to delay doing so is because MSC3911
+  will make more substantial changes to this endpoint, requiring another
+  rename, and it is expected that both proposals will be mergeed at the same
+  time (so a double rename will be confusing and unnecessary). However, if
+  MSC3911 is delayed or rejected, we should reconsider this.
+
+* Rather than messing with multipart content, have a separate endpoint for
+  servers to get the metadata for a media item. That would mean two requests,
+  but might make more sense than both `/thumbnail` and `/download` providing
+  the info.
+
+## Unstable prefix
+
+While this proposal is in development, the new endpoints should be named as follows:
+
+* GET /_matrix/client/unstable/org.matrix.msc3916/media/preview_url
+* GET /_matrix/client/unstable/org.matrix.msc3916/media/config
+* GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}
+* GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}
+* GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}
+* GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}
+* GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}
+
+## Dependencies
+
+None at present.

From 3076de0a19345b43868e05cd65a4bb956441d6dd Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 24 Oct 2022 00:07:34 +0100
Subject: [PATCH 02/25] minor edits

---
 proposals/3916-authentication-for-media.md | 33 ++++++++++++----------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index ad05778e35..eab7c7b27a 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -22,7 +22,7 @@ requirements to address the problems mentioned above. (See, for example,
 [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911) which
 builds on top of this MSC.)
 
-This proposal supercedes [MSC1902](https://github.com/matrix-org/matrix-spec-proposals/pull/1902).
+This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-proposals/pull/1902).
 
 ## Proposal
 
@@ -44,22 +44,25 @@ This proposal supercedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.4/client-server-api/#post_matrixmediav3upload)
    is **not** modified by this MSC: it is intended that it be brought into line with the other
-   endpoints by a future MSC, such as [[MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
+   endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
 2. Removal of `allow_remote` parameter from `/download`
 
-   The current `/download` and `/thumbnail` enpoints take an `allow_remote`
-   query parameter, indicating whether the server should request remote media
-   from other servers. This is redundant with the new endpoints, so will not be
-   supported.
+   The current
+   [`/download`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaid)
+   and
+   [`/thumbnail`]((https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
+   endpoints take an `allow_remote` query parameter, indicating whether the
+   server should request remote media from other servers. This is redundant
+   with the new endpoints, so will not be supported.
 
    Servers should never return remote media from `GET
    /_matrix/federation/v1/media/download` or `GET
    /_matrix/federation/v1/media/thumbnail`; indeed, the `serverName` is
    included in the URI only for consistency with the CS-API.
 
-   `/_matrix/client/v1/media/download/` and
-   `/_matrix/client/v1/media/thumnbnail` should return remote media as normal.
+   `/_matrix/client/v1/media/download` and
+   `/_matrix/client/v1/media/thumbnail` should return remote media as normal.
    
 3. Authentication on all endpoints
 
@@ -211,13 +214,13 @@ specifically for access to these icon.
 
 While this proposal is in development, the new endpoints should be named as follows:
 
-* GET /_matrix/client/unstable/org.matrix.msc3916/media/preview_url
-* GET /_matrix/client/unstable/org.matrix.msc3916/media/config
-* GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}
-* GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}
-* GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}
-* GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}
-* GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}
+* `GET /_matrix/client/unstable/org.matrix.msc3916/media/preview_url`
+* `GET /_matrix/client/unstable/org.matrix.msc3916/media/config`
+* `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
+* `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}`
+* `GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
+* `GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
+* `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
 
 ## Dependencies
 

From 55303b5cb35c1916013cc36871b408e82f8a9588 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 10 Mar 2023 12:45:39 +0000
Subject: [PATCH 03/25] fix some links

---
 proposals/3916-authentication-for-media.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index eab7c7b27a..eed48e9c2b 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -36,22 +36,22 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
    | Old                                                                                                                                                              | Client-Server                                                             | Federation                                                          |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-   | [`GET /_matrix/media/v3/preview_url`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3preview_url) | `GET /_matrix/client/v1/media/preview_url` | - |
-   | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
-   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
-   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
-   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | `GET /_matrix/federation/v1/media/thumbnail/{serverName}/{mediaId}` |
+   | [`GET /_matrix/media/v3/preview_url`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3preview_url) | `GET /_matrix/client/v1/media/preview_url` | - |
+   | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
+   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
+   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
+   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | `GET /_matrix/federation/v1/media/thumbnail/{serverName}/{mediaId}` |
 
-   **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.4/client-server-api/#post_matrixmediav3upload)
+   **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    is **not** modified by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
 2. Removal of `allow_remote` parameter from `/download`
 
    The current
-   [`/download`](https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3downloadservernamemediaid)
+   [`/download`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)
    and
-   [`/thumbnail`]((https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
+   [`/thumbnail`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
    endpoints take an `allow_remote` query parameter, indicating whether the
    server should request remote media from other servers. This is redundant
    with the new endpoints, so will not be supported.

From d601637eb0a92bd6e6ba5289e85d9e12d5ee0649 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 5 Apr 2024 16:51:21 -0600
Subject: [PATCH 04/25] Prevent further spread of unauthenticated media

---
 proposals/3916-authentication-for-media.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index eed48e9c2b..f8816a3853 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -1,7 +1,7 @@
 # MSC3916: Authentication for media access, and new endpoint names
 
 Currently, access to media in Matrix has a number of problems including the following:
- 
+
 * The only protection for media is the obscurity of the URL, and URLs are
   easily leaked (eg accidental sharing, access
   logs). [synapse#2150](https://github.com/matrix-org/synapse/issues/2150)
@@ -46,6 +46,12 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    is **not** modified by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
+   After this proposal is released in a stable version of the specification, servers
+   which support the new `download` and `thumbnail` endpoints should cease to serve
+   newly uploaded media from the unauthenticated versions. This includes media
+   uploaded by local users and requests for not-yet-cached remote media. This is
+   done with a 404 `M_NOT_FOUND` error, as though the media doesn't exist.
+
 2. Removal of `allow_remote` parameter from `/download`
 
    The current
@@ -63,7 +69,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
    `/_matrix/client/v1/media/download` and
    `/_matrix/client/v1/media/thumbnail` should return remote media as normal.
-   
+
 3. Authentication on all endpoints
 
    Currently, the `/download` and `/thumbnail` endpoints have no authentication
@@ -103,14 +109,14 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
      --gc0p4Jq0M2Yt08jU534c0p
      ```
-     
+
 5. Backwards compatibility mechanisms
 
    a. Backwards compatibility with older servers: if a client or requesting
    server receives a 404 error with a non-JSON response, or a 400 or 404 error with
    `{"errcode": "M_UNRECOGNIZED"}`, in response to a request to one of the new
    endpoints, they may retry the request using the original endpoint.
-   
+
    b. Backwards compatibility with older clients and federating servers:
    servers may for a short time choose to allow unauthenticated access via the
    deprecated endpoints.
@@ -193,7 +199,7 @@ specifically for access to these icon.
   the proportion of clients which have been updated, and it is a good
   opportunity to bring these endpoints into line with the rest of the
   client-server and federation APIs.
-  
+
 * There's no real need to rename `GET /_matrix/media/v3/preview_url` and `GET
   /_matrix/media/v3/config` at present, and we could just leave them in
   place. However, changing them at the same time makes the API more consistent.

From c2ae25e32eae27ce53397f7ff6ca074869fbb9d5 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 22 Apr 2024 15:57:24 -0600
Subject: [PATCH 05/25] Address review feedback

---
 proposals/3916-authentication-for-media.md | 86 ++++++++++++++++------
 1 file changed, 63 insertions(+), 23 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index f8816a3853..ec1410b0d6 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -28,13 +28,14 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
 1. New endpoints
 
-   The existing `/_matrix/media/v3/` endpoints are to be deprecated, and replaced
-   by new endpoints under the `/_matrix/client` and `/_matrix/federation`
-   hierarchies.
+   The existing `/_matrix/media/v3/` endpoints become deprecated, and new
+   endpoints under the `/_matrix/client` and `/_matrix/federation`
+   hierarchies are introduced. Removal of the deprecated endpoints would be a
+   later MSC under [the deprecation policy](https://spec.matrix.org/v1.10/#deprecation-policy).
 
-   The table below shows a mapping between old and new endpoint:
+   The following table below shows a mapping between deprecated and new endpoint:
 
-   | Old                                                                                                                                                              | Client-Server                                                             | Federation                                                          |
+   | Deprecated                                                                                                                                                       | Client-Server                                                             | Federation                                                          |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
    | [`GET /_matrix/media/v3/preview_url`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3preview_url) | `GET /_matrix/client/v1/media/preview_url` | - |
    | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
@@ -45,12 +46,21 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    is **not** modified by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
+   It is subsequently **not** deprecated either.
+
+   The new `/download` and `/thumbnail` endpoints additionally drop the `?allow_redirect`
+   query parameters. Instead, the endpoints behave as though `allow_redirect=true` was
+   set, regardless of actual value. See [this comment on MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860/files#r1005176480)
+   for details.
 
    After this proposal is released in a stable version of the specification, servers
-   which support the new `download` and `thumbnail` endpoints should cease to serve
+   which support the new `download` and `thumbnail` endpoints SHOULD cease to serve
    newly uploaded media from the unauthenticated versions. This includes media
    uploaded by local users and requests for not-yet-cached remote media. This is
-   done with a 404 `M_NOT_FOUND` error, as though the media doesn't exist.
+   done with a 404 `M_NOT_FOUND` error, as though the media doesn't exist. Servers
+   SHOULD consider their local ecosystem impact before freezing the endpoints. For
+   example, ensuring that common bridges and clients will continue to work, and
+   encouraging updates to those affected projects as needed.
 
 2. Removal of `allow_remote` parameter from `/download`
 
@@ -78,6 +88,8 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    which must be `Bearer {accessToken}` for `/_matrix/client`, or the signature
    for `/_matrix/federation`.
 
+   **Note**: This fixes [matrix-spec#313](https://github.com/matrix-org/matrix-spec/issues/313).
+
 4. Updated response format
 
    * For the new `/_matrix/client` endpoints, the response format is the same as
@@ -86,11 +98,12 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    * To enable future expansion, for the new `/_matrix/federation` endpoints,
      the response is
      [`multipart/mixed`](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)
-     content with two parts: the first must be a JSON object (and should have a
-     `Content-type: application/json` header), and the second is the media item
+     content with exactly two parts: the first MUST be a JSON object (and should have a
+     `Content-type: application/json` header), and the second MUST be the media item
      as per the original endpoints.
 
-     No properties are yet specified for the JSON object to be returned.
+     No properties are yet specified for the JSON object to be returned. One
+     possible use is described by [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
      An example response:
 
@@ -112,14 +125,18 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
 5. Backwards compatibility mechanisms
 
-   a. Backwards compatibility with older servers: if a client or requesting
-   server receives a 404 error with a non-JSON response, or a 400 or 404 error with
-   `{"errcode": "M_UNRECOGNIZED"}`, in response to a request to one of the new
-   endpoints, they may retry the request using the original endpoint.
+   a. Backwards compatibility with older servers: if a client or requesting server
+   receives a 404 error with `M_UNRECOGNIZED` error code in response to a request
+   using the new endpoints, they may retry the request using the deprecated
+   endpoint. Servers and clients should note the [`M_UNRECOGNIZED`](https://spec.matrix.org/v1.10/client-server-api/#common-error-codes)
+   error code semantics.
 
-   b. Backwards compatibility with older clients and federating servers:
-   servers may for a short time choose to allow unauthenticated access via the
-   deprecated endpoints.
+   b. Backwards compatibility with older clients and federating servers: mentioned
+   in Part 1 of this proposal, servers *may* freeze unauthenticated media access
+   once stable authenticated endpoints are available. This may lead to client and
+   server errors for new media. Both clients and servers are strongly encouraged
+   to update as soon as possible, before servers freeze unauthenticated media
+   access.
 
 ### Effects on client applications
 
@@ -176,12 +193,35 @@ specifically for access to these icon.
 
 ## Potential issues
 
-* Setting the `Authorization` header is going to be annoying for web clients. Service workers
-  might be needed.
+* Setting the `Authorization` header is particularly annoying for web clients.
+  Service workers are seemingly the best option, though other options include
+  locally-cached `blob:` URIs. Clients should note that caching media can lead
+  to significant memory usage, particularly for large media. Service workers by
+  comparison allow for proxy-like behaviour.
 
 * Users will be unable to copy links to media from web clients to share out of
   band. This is considered a feature, not a bug.
 
+* Over federation, the use of the `Range` request header on `/download` becomes
+  unclear as it could affect either or both parts of the response. There does not
+  appear to be formal guidance in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#field.range)
+  either. There are arguments for affecting both and either part equally. Typically,
+  such a header would be used to resume failed downloads, though servers are
+  already likely to discard received data and fail the associated client requests
+  when the federation request fails. Therefore, servers are unlikely to use `Range`
+  at all. As such, this proposal does not make a determination on how `Range`
+  should be handled, and leaves it as an HTTP specification interpretation problem
+  instead.
+
+* [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860)-style
+  redirects are harder to implement for the federation endpoints. It's presumed
+  that CDNs can either cache the multipart type (later to be combined with linked
+  media authentication, like [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911)),
+  or the CDN can be somehow told the parameters it needs to return. For example,
+  `Location: https://cdn.example.org/media?mx_json={}`. Popular CDN providers
+  support this sort of request rewriting. Relatedly, [MSC4097](https://github.com/matrix-org/matrix-spec-proposals/pull/4097)
+  may be of interest to readers.
+
 ## Alternatives
 
 * Allow clients to upload media which does not require authentication (for
@@ -192,7 +232,7 @@ specifically for access to these icon.
   The danger with this is that is that there's little stopping clients
   continuing to upload media as "public", negating all of the benefits in this
   MSC. It might be ok if media upload it was restricted to certain privileged
-  users.
+  users, or applied after the fact by a server administrator.
 
 * We could simply require that `Authorization` headers be given when calling
   the existing endpoints. However, doing so would make it harder to evaluate
@@ -207,9 +247,9 @@ specifically for access to these icon.
   Conversely, we should make sure to rename `POST
   /_matrix/media/v3/upload`. The reason to delay doing so is because MSC3911
   will make more substantial changes to this endpoint, requiring another
-  rename, and it is expected that both proposals will be mergeed at the same
-  time (so a double rename will be confusing and unnecessary). However, if
-  MSC3911 is delayed or rejected, we should reconsider this.
+  rename, and it is expected that both proposals will be mergeed near to the same
+  time as each other (so a double rename will be confusing and unnecessary). However,
+  if MSC3911 is delayed or rejected, we should reconsider this.
 
 * Rather than messing with multipart content, have a separate endpoint for
   servers to get the metadata for a media item. That would mean two requests,

From 8351ebeb2822fca143a5a8bec5937bf2d24972c6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 22 Apr 2024 16:02:08 -0600
Subject: [PATCH 06/25] Drop federation thumbnails

---
 proposals/3916-authentication-for-media.md | 23 +++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index ec1410b0d6..51deec5ab1 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -41,13 +41,17 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
-   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | `GET /_matrix/federation/v1/media/thumbnail/{serverName}/{mediaId}` |
+   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    is **not** modified by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
    It is subsequently **not** deprecated either.
 
+   **Note**: `/thumbnail` does not have a federation endpoint. It appears as though
+   no servers request thumbnails over federation, and so it is not supported here.
+   A later MSC may introduce such an endpoint.
+
    The new `/download` and `/thumbnail` endpoints additionally drop the `?allow_redirect`
    query parameters. Instead, the endpoints behave as though `allow_redirect=true` was
    set, regardless of actual value. See [this comment on MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860/files#r1005176480)
@@ -72,13 +76,11 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    server should request remote media from other servers. This is redundant
    with the new endpoints, so will not be supported.
 
-   Servers should never return remote media from `GET
-   /_matrix/federation/v1/media/download` or `GET
-   /_matrix/federation/v1/media/thumbnail`; indeed, the `serverName` is
-   included in the URI only for consistency with the CS-API.
+   Servers MUST never return remote media from `GET /_matrix/federation/v1/media/download`;
+   indeed, the `serverName` is included in the URI only for consistency with the CS-API.
 
    `/_matrix/client/v1/media/download` and
-   `/_matrix/client/v1/media/thumbnail` should return remote media as normal.
+   `/_matrix/client/v1/media/thumbnail` return remote media as normal.
 
 3. Authentication on all endpoints
 
@@ -253,8 +255,7 @@ specifically for access to these icon.
 
 * Rather than messing with multipart content, have a separate endpoint for
   servers to get the metadata for a media item. That would mean two requests,
-  but might make more sense than both `/thumbnail` and `/download` providing
-  the info.
+  but might make more sense than `/download` providing the info directly.
 
 ## Unstable prefix
 
@@ -266,7 +267,11 @@ While this proposal is in development, the new endpoints should be named as foll
 * `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}`
 * `GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
 * `GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
-* `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
+
+In a prior version of this proposal, the federation API included a thumbnail endpoint.
+It was removed due to lack of perceived usage. Servers which implemented the unstable
+version will have done so under `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`.
+The client-server thumbnail endpoint is unaffected by this change.
 
 ## Dependencies
 

From 106ce553937766e4537173135d66b588fb9b88b4 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 22 Apr 2024 21:21:35 -0600
Subject: [PATCH 07/25] Add comparisons

---
 proposals/3916-authentication-for-media.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 51deec5ab1..54da7d5981 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -257,6 +257,26 @@ specifically for access to these icon.
   servers to get the metadata for a media item. That would mean two requests,
   but might make more sense than `/download` providing the info directly.
 
+### Compared to MSC3796 (MSC701)
+
+[MSC701/3796](https://github.com/matrix-org/matrix-spec-proposals/issues/3796)
+introduces a concept of "content tokens" which have authentication tie-in to
+prevent anonymous users from accessing media. This is a similar problem space
+to this proposal, though deals more in the event-to-media linking space instead.
+Although the MSC is an early sketch, it's unclear if the problems noted on the
+MSC itself are feasibly resolvable.
+
+### Compared to MSC2461
+
+[MSC2461](https://github.com/matrix-org/matrix-spec-proposals/pull/2461) adds
+authentication to the existing media endpoints, which as noted here in the
+Alternatives is not likely to roll out quickly and leaves an inconsistency in
+the spec. MSC2461 also introduces a client-visible flag for which kinds of media
+may require authentication, making it similar to the alternative listed above
+where on the federation side we could have two endpoints: one for information
+and one for the media itself. MSC2461 simply makes the information client-visible
+instead of server-visible.
+
 ## Unstable prefix
 
 While this proposal is in development, the new endpoints should be named as follows:

From a14c4afed85d5311163f930f1b9f4bc77fba9d33 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 14 May 2024 13:15:54 -0600
Subject: [PATCH 08/25] Clarify that query string auth is forbidden

---
 proposals/3916-authentication-for-media.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 54da7d5981..050e369309 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -90,6 +90,11 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    which must be `Bearer {accessToken}` for `/_matrix/client`, or the signature
    for `/_matrix/federation`.
 
+   The query string `?access_token` approach is not supported on the new endpoints,
+   as it is [deprecated](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4126-deprecate-query-string-auth.md)
+   and [pending removal](https://github.com/matrix-org/matrix-spec-proposals/pull/4127).
+   See those MSCs for details.
+
    **Note**: This fixes [matrix-spec#313](https://github.com/matrix-org/matrix-spec/issues/313).
 
 4. Updated response format

From 92eba2c114009a518b2c36448bc4b0461e4e8267 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 21 May 2024 13:45:20 -0600
Subject: [PATCH 09/25] Document `/create` changing namespace too

---
 proposals/3916-authentication-for-media.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 050e369309..1ad8b8ea75 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -42,6 +42,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
    | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
+   | [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create) | `GET /_matrix/client/v1/media/create` | - |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    is **not** modified by this MSC: it is intended that it be brought into line with the other

From a76d97f21a84e2fa4729aabfc4128878a1a42904 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 21 May 2024 13:45:34 -0600
Subject: [PATCH 10/25] Clarify what is happening to `/upload`

---
 proposals/3916-authentication-for-media.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 1ad8b8ea75..aaf85a81ed 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -45,9 +45,8 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create) | `GET /_matrix/client/v1/media/create` | - |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
-   is **not** modified by this MSC: it is intended that it be brought into line with the other
+   is **not** modified or deprecated by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
-   It is subsequently **not** deprecated either.
 
    **Note**: `/thumbnail` does not have a federation endpoint. It appears as though
    no servers request thumbnails over federation, and so it is not supported here.

From 8bb5159da0d4ccaaf97ce1d860b0ea07df1f1b76 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 21 May 2024 13:46:18 -0600
Subject: [PATCH 11/25] Minor wording clarifications, primarily around using
 HTTPS for idp icons

---
 proposals/3916-authentication-for-media.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index aaf85a81ed..b6b5ad5316 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -191,9 +191,9 @@ icons are displayed).
 
 This remains a somewhat unsolved problem. Possibly the clients can continue
 to call the legacy `/_matrix/media/v3/download` URI for now: ultimately this
-problem will be solved by the transition to OIDC. Alternatively, we may need
-to provide an alternative `/_matrix/client/v3/login/sso/icon/{idpId}` API
-specifically for access to these icon.
+problem will be solved by the transition to OIDC. Alternatively, a dedicated
+API could be provided or permission to use HTTP(S) URLs to access the icons.
+This support would come from a different MSC.
 
 (This was previously discussed in
 [MSC2858](https://github.com/matrix-org/matrix-spec-proposals/pull/2858#discussion_r543513811).)
@@ -300,4 +300,4 @@ The client-server thumbnail endpoint is unaffected by this change.
 
 ## Dependencies
 
-None at present.
+None.

From e1e8a6a7b6d4ec917950d08c7bcc792b715f3487 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 21 May 2024 13:46:38 -0600
Subject: [PATCH 12/25] Drop `serverName` in new federation download endpoint

---
 proposals/3916-authentication-for-media.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index b6b5ad5316..07e7c59daf 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -39,7 +39,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
    | [`GET /_matrix/media/v3/preview_url`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3preview_url) | `GET /_matrix/client/v1/media/preview_url` | - |
    | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
-   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`  |
+   | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{mediaId}`  |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
    | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
    | [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create) | `GET /_matrix/client/v1/media/create` | - |
@@ -76,8 +76,9 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    server should request remote media from other servers. This is redundant
    with the new endpoints, so will not be supported.
 
-   Servers MUST never return remote media from `GET /_matrix/federation/v1/media/download`;
-   indeed, the `serverName` is included in the URI only for consistency with the CS-API.
+   Servers MUST NOT return remote media from `GET /_matrix/federation/v1/media/download`. The
+   `serverName` is omitted from the endpoint's path to strongly enforce this - the `mediaId` in
+   a request is assumed to be scoped to the target server.
 
    `/_matrix/client/v1/media/download` and
    `/_matrix/client/v1/media/thumbnail` return remote media as normal.
@@ -291,7 +292,13 @@ While this proposal is in development, the new endpoints should be named as foll
 * `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
 * `GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}`
 * `GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
-* `GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
+* `GET /_matrix/federation/unstable/org.matrix.msc3916.v2/media/download/{mediaId}`
+  * **Note**: This endpoint has a `.v2` in its unstable identifier due to the MSC changing after
+    initial implementation. The original unstable endpoint has a `serverName` and may still be
+    supported by some servers: `GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}`
+
+    The `serverName` was later dropped in favour of explicit scoping. See `allow_remote` details
+    in the MSC body for details.
 
 In a prior version of this proposal, the federation API included a thumbnail endpoint.
 It was removed due to lack of perceived usage. Servers which implemented the unstable

From 71b8db4e6fd42c2f227a2b22f24735d2770d1d5d Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 28 May 2024 16:42:10 -0600
Subject: [PATCH 13/25] Move `/create` to unmodified

---
 proposals/3916-authentication-for-media.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 07e7c59daf..8ea2bcb7cf 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -42,10 +42,10 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{mediaId}`  |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
    | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
-   | [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create) | `GET /_matrix/client/v1/media/create` | - |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
-   is **not** modified or deprecated by this MSC: it is intended that it be brought into line with the other
+   and [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create)
+   are **not** modified or deprecated by this MSC: it is intended that it be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
    **Note**: `/thumbnail` does not have a federation endpoint. It appears as though

From 1c864a38980abb4fe9fbece4f2d15fb9c6ee5220 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 28 May 2024 16:51:32 -0600
Subject: [PATCH 14/25] Mention cookies

---
 proposals/3916-authentication-for-media.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 8ea2bcb7cf..625ff72207 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -207,6 +207,11 @@ This support would come from a different MSC.
   to significant memory usage, particularly for large media. Service workers by
   comparison allow for proxy-like behaviour.
 
+  Cookies are a plausible mechanism for sharing session information between
+  requests without having to set headers, though would be a relatively bespoke
+  authentication method for Matrix. Additionally, many Matrix users have cookies
+  disabled due to the advertising and tracking use cases common across the web.
+
 * Users will be unable to copy links to media from web clients to share out of
   band. This is considered a feature, not a bug.
 

From e5c931664786a986d7f6bc850f4dc1cbf95ac838 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 28 May 2024 17:16:15 -0600
Subject: [PATCH 15/25] Forgot a mention of `/create`

---
 proposals/3916-authentication-for-media.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 625ff72207..b552cdf272 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -258,11 +258,12 @@ This support would come from a different MSC.
   place. However, changing them at the same time makes the API more consistent.
 
   Conversely, we should make sure to rename `POST
-  /_matrix/media/v3/upload`. The reason to delay doing so is because MSC3911
-  will make more substantial changes to this endpoint, requiring another
-  rename, and it is expected that both proposals will be mergeed near to the same
-  time as each other (so a double rename will be confusing and unnecessary). However,
-  if MSC3911 is delayed or rejected, we should reconsider this.
+  /_matrix/media/v3/upload` and `GET /_matrix/media/v3/create`. The reason to
+  delay doing so is because MSC3911 will make more substantial changes to these
+  endpoints, requiring another rename, and it is expected that both proposals
+  will be mergeed near to the same time as each other (so a double rename will
+  be confusing and unnecessary). However, if MSC3911 is delayed or rejected, we
+  should reconsider this.
 
 * Rather than messing with multipart content, have a separate endpoint for
   servers to get the metadata for a media item. That would mean two requests,

From 41d2aa2ab3e0136f763a14223411bbe513770351 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 28 May 2024 17:16:32 -0600
Subject: [PATCH 16/25] Add `Location` header support to federation `/download`

---
 proposals/3916-authentication-for-media.md | 67 +++++++++++++++++++---
 1 file changed, 59 insertions(+), 8 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index b552cdf272..b2fc3fc568 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -131,6 +131,41 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
      --gc0p4Jq0M2Yt08jU534c0p
      ```
 
+     The second part (media item bytes) MAY include a [`Location` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
+     to point to the raw media object instead of having bytes itself. Servers
+     SHOULD NOT cache the `Location` header's value as the responding server may
+     have applied time limits on its validity. Servers which don't immediately
+     download the media from the provided URL should re-request the media and
+     metadata from the `/download` endpoint when ready for the media bytes.
+
+     The `Location` header's URL does *not* require authentication, as it will
+     typically be served by a CDN or other non-matrix server (thus being unable
+     to verify any `X-Matrix` signatures, for example).
+
+     An example response with a `Location` redirect would be:
+
+     ```
+     Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     Content-Type: application/json
+
+     {}
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     Content-Type: text/plain
+     Location: https://cdn.example.org/ab/c1/2345.txt
+
+     --gc0p4Jq0M2Yt08jU534c0p
+     ```
+
+     If the server were to `curl https://cdn.example.org/ab/c1/2345.txt`, it'd
+     get:
+
+     ```
+     This media is plain text. Maybe somebody used it as a paste bin.
+     ```
+
 5. Backwards compatibility mechanisms
 
    a. Backwards compatibility with older servers: if a client or requesting server
@@ -146,6 +181,16 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    to update as soon as possible, before servers freeze unauthenticated media
    access.
 
+6. Removal of `allow_redirect` parameter from `/download` and `/thumbnail`
+
+   Clients MUST expect a 307 or 308 redirect when calling the new `/download`
+   and `/thumbnail` Client-Server API endpoints.
+
+   Servers MUST expect the `Location` header in the media part of the new Server-Server
+   API `/download` endpoint. Servers MUST NOT respond with a 307 or 308 redirect at
+   the top level for the endpoint - they can only redirect within the media part
+   itself.
+
 ### Effects on client applications
 
 Naturally, implementations will be required to provide `Authorization` headers
@@ -226,14 +271,11 @@ This support would come from a different MSC.
   should be handled, and leaves it as an HTTP specification interpretation problem
   instead.
 
-* [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860)-style
-  redirects are harder to implement for the federation endpoints. It's presumed
-  that CDNs can either cache the multipart type (later to be combined with linked
-  media authentication, like [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911)),
-  or the CDN can be somehow told the parameters it needs to return. For example,
-  `Location: https://cdn.example.org/media?mx_json={}`. Popular CDN providers
-  support this sort of request rewriting. Relatedly, [MSC4097](https://github.com/matrix-org/matrix-spec-proposals/pull/4097)
-  may be of interest to readers.
+* The `Location` header support on the new `/download` endpoint could add a bit
+  of complexity to servers, though given the alternative of supporting CDNs and
+  similar is to place complexity into "edge workers" to mutate the response value.
+  Though the Matrix spec would be "simpler", the edge worker setup would be
+  fragmented where we have an opportunity for a common standard.
 
 ## Alternatives
 
@@ -269,6 +311,15 @@ This support would come from a different MSC.
   servers to get the metadata for a media item. That would mean two requests,
   but might make more sense than `/download` providing the info directly.
 
+  This is a plausible approach with no significant upsides or downsides when
+  compared to multipart responses.
+
+  Similarly, custom headers could be used to carry the metadata on the response,
+  though again, there are no significant upsides or downsides to doing so.
+
+  Readers may wish to refer to [this thread](https://github.com/matrix-org/matrix-spec-proposals/pull/3916/files#r1586878787)
+  on the MSC which covers the majority of the pros and cons for all 3 approaches.
+
 ### Compared to MSC3796 (MSC701)
 
 [MSC701/3796](https://github.com/matrix-org/matrix-spec-proposals/issues/3796)

From d73025bb5784a0407075fc21c679d1fc0c8c4c26 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 28 May 2024 23:37:09 -0600
Subject: [PATCH 17/25] Update proposals/3916-authentication-for-media.md

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
---
 proposals/3916-authentication-for-media.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index b2fc3fc568..6045469553 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -45,7 +45,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    and [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create)
-   are **not** modified or deprecated by this MSC: it is intended that it be brought into line with the other
+   are **not** modified or deprecated by this MSC: it is intended that they be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
    **Note**: `/thumbnail` does not have a federation endpoint. It appears as though

From 656dfb8f22dcefa0b6c1c3537a8d62ea3709c597 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 08:36:24 -0600
Subject: [PATCH 18/25] Update proposals/3916-authentication-for-media.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 proposals/3916-authentication-for-media.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 6045469553..a076624c41 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -303,7 +303,7 @@ This support would come from a different MSC.
   /_matrix/media/v3/upload` and `GET /_matrix/media/v3/create`. The reason to
   delay doing so is because MSC3911 will make more substantial changes to these
   endpoints, requiring another rename, and it is expected that both proposals
-  will be mergeed near to the same time as each other (so a double rename will
+  will be merged near to the same time as each other (so a double rename will
   be confusing and unnecessary). However, if MSC3911 is delayed or rejected, we
   should reconsider this.
 

From 87c08e0842623ad5a98d6515b2fbec2f6c92c9c6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 13:44:15 -0600
Subject: [PATCH 19/25] Move allow_redirect behaviour fully into dedicated
 point

---
 proposals/3916-authentication-for-media.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index a076624c41..d41c3d6bad 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -52,11 +52,6 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    no servers request thumbnails over federation, and so it is not supported here.
    A later MSC may introduce such an endpoint.
 
-   The new `/download` and `/thumbnail` endpoints additionally drop the `?allow_redirect`
-   query parameters. Instead, the endpoints behave as though `allow_redirect=true` was
-   set, regardless of actual value. See [this comment on MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860/files#r1005176480)
-   for details.
-
    After this proposal is released in a stable version of the specification, servers
    which support the new `download` and `thumbnail` endpoints SHOULD cease to serve
    newly uploaded media from the unauthenticated versions. This includes media
@@ -191,6 +186,9 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    the top level for the endpoint - they can only redirect within the media part
    itself.
 
+   See [this comment on MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860/files#r1005176480)
+   for further context on this change.
+
 ### Effects on client applications
 
 Naturally, implementations will be required to provide `Authorization` headers

From 1fe8d71a1c81baedfdb3d0aad1f3891ac05d40af Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 14:29:01 -0600
Subject: [PATCH 20/25] Clarify backwards compatibilty/freezing

---
 proposals/3916-authentication-for-media.md | 66 +++++++++++++++-------
 1 file changed, 45 insertions(+), 21 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index d41c3d6bad..372a471719 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -52,15 +52,6 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    no servers request thumbnails over federation, and so it is not supported here.
    A later MSC may introduce such an endpoint.
 
-   After this proposal is released in a stable version of the specification, servers
-   which support the new `download` and `thumbnail` endpoints SHOULD cease to serve
-   newly uploaded media from the unauthenticated versions. This includes media
-   uploaded by local users and requests for not-yet-cached remote media. This is
-   done with a 404 `M_NOT_FOUND` error, as though the media doesn't exist. Servers
-   SHOULD consider their local ecosystem impact before freezing the endpoints. For
-   example, ensuring that common bridges and clients will continue to work, and
-   encouraging updates to those affected projects as needed.
-
 2. Removal of `allow_remote` parameter from `/download`
 
    The current
@@ -163,18 +154,51 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
 
 5. Backwards compatibility mechanisms
 
-   a. Backwards compatibility with older servers: if a client or requesting server
-   receives a 404 error with `M_UNRECOGNIZED` error code in response to a request
-   using the new endpoints, they may retry the request using the deprecated
-   endpoint. Servers and clients should note the [`M_UNRECOGNIZED`](https://spec.matrix.org/v1.10/client-server-api/#common-error-codes)
-   error code semantics.
-
-   b. Backwards compatibility with older clients and federating servers: mentioned
-   in Part 1 of this proposal, servers *may* freeze unauthenticated media access
-   once stable authenticated endpoints are available. This may lead to client and
-   server errors for new media. Both clients and servers are strongly encouraged
-   to update as soon as possible, before servers freeze unauthenticated media
-   access.
+   Servers SHOULD *stop* serving new media as unauthenticated within 1 spec release
+   of this proposal being released itself using a standard `404 M_NOT_FOUND` response.
+   Existing media should continue to be served from the unauthenticated endpoints
+   indefinitely for backwards compatibility. For example, if this proposal is
+   released in Matrix 1.11, then by Matrix 1.12 servers should freeze the old
+   unauthenticated endpoints by only serving media known to exist from before the
+   freeze.
+
+   "New media" is any media which local users upload after the freeze is put in
+   place, and any remote media which becomes cached after the freeze as well. This
+   could be marked by a configuration option within the server software, or as part
+   of a scheduled/dedicated release which enacts the freeze for everyone who updates
+   to that version.
+
+   This freeze schedule will have some undesirable side effects, particularly for
+   clients and servers which are slow to update or support the new endpoints. Newly
+   uploaded images, files, avatars, etc may appear "broken" or missing to users on
+   older software. Existing media should continue to work, however, reducing the
+   impact from 100% of media to a smaller percentage.
+
+   Servers SHOULD consider whether their users' typical clients will break as
+   part of the freeze before enacting the freeze. Clients SHOULD update as soon
+   as reasonably possible to support authenticated media, particularly following
+   the spec release containing this MSC. Other considerations may include bridges,
+   deployment-specific use cases, and patch availability.
+
+   It is worth noting that the matrix.org homeserver plans to freeze media relatively
+   quickly following this proposal's release in the specification. Details will be
+   published to the matrix.org blog closer to the spec release date.
+
+   The following are specific backwards compatibility cases:
+
+   a. New clients & servers with older servers: The [`M_UNRECOGNIZED`](https://spec.matrix.org/v1.10/client-server-api/#common-error-codes)
+      error behaviour should be followed to indicate that the server does not
+      support the new endpoints, particularly when partnered with a 404 HTTP status
+      code. Clients and servers should use the unauthenticated endpoints in this
+      case. The endpoints will not be frozen by the server, so should work for
+      'new' media.
+
+   b. Older clients & servers with newer servers: Mentioned above, servers are
+      strongly encouraged to freeze unauthenticated media access within a relatively
+      quick timeframe. Though media before the freeze should remain accessible,
+      clients and older federating servers may still see errors when accessing
+      new media, leading to client UI feeling "broken" or missing avatars. The
+      various considerations above are meant to reduce the impact of this case.
 
 6. Removal of `allow_redirect` parameter from `/download` and `/thumbnail`
 

From aac190920f1d7a3ab6aea940eada7811c2e1f55c Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 14:30:33 -0600
Subject: [PATCH 21/25] Clarify that access token auth is permitted, but not
 recommended

---
 proposals/3916-authentication-for-media.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 372a471719..d0de8c243a 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -77,10 +77,9 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    which must be `Bearer {accessToken}` for `/_matrix/client`, or the signature
    for `/_matrix/federation`.
 
-   The query string `?access_token` approach is not supported on the new endpoints,
-   as it is [deprecated](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4126-deprecate-query-string-auth.md)
-   and [pending removal](https://github.com/matrix-org/matrix-spec-proposals/pull/4127).
-   See those MSCs for details.
+   Clients SHOULD NOT use the [deprecated](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4126-deprecate-query-string-auth.md)
+   `?access_token` query string authentication mechanism. The method is [pending removal](https://github.com/matrix-org/matrix-spec-proposals/pull/4127)
+   and is generally unsafe. See those MSCs for further details.
 
    **Note**: This fixes [matrix-spec#313](https://github.com/matrix-org/matrix-spec/issues/313).
 

From 0b4f2c9d4d03752e8b57159f099712634427d862 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 14:36:42 -0600
Subject: [PATCH 22/25] Clarify header behaviour around Location

---
 proposals/3916-authentication-for-media.md | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index d0de8c243a..83ab67b39e 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -92,8 +92,10 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
      the response is
      [`multipart/mixed`](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)
      content with exactly two parts: the first MUST be a JSON object (and should have a
-     `Content-type: application/json` header), and the second MUST be the media item
-     as per the original endpoints.
+     `Content-type: application/json` header), and the second MUST be the media item.
+     The media item may be served inline, as shown in the first example below, or
+     be a pointer to a URL containing the media item's bytes instead, represented
+     by the `Location` header described further below.
 
      No properties are yet specified for the JSON object to be returned. One
      possible use is described by [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
@@ -127,6 +129,11 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
      typically be served by a CDN or other non-matrix server (thus being unable
      to verify any `X-Matrix` signatures, for example).
 
+     Note that all other headers besides `Location` for the media item part are
+     ignored when `Location` is present. The `Content-Type`, `Content-Disposition`,
+     etc headers will be served from the `Location`'s URL instead. Similarly,
+     the body for the media item part is ignored and SHOULD be empty.
+
      An example response with a `Location` redirect would be:
 
      ```
@@ -138,16 +145,17 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
      {}
 
      --gc0p4Jq0M2Yt08jU534c0p
-     Content-Type: text/plain
      Location: https://cdn.example.org/ab/c1/2345.txt
 
      --gc0p4Jq0M2Yt08jU534c0p
      ```
 
      If the server were to `curl https://cdn.example.org/ab/c1/2345.txt`, it'd
-     get:
+     get something similar to the following:
 
      ```
+     Content-Type: text/plain
+
      This media is plain text. Maybe somebody used it as a paste bin.
      ```
 

From f1777c22f35b303a406abab265bf3845131a1cb7 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 29 May 2024 14:40:30 -0600
Subject: [PATCH 23/25] Fix social sign-on icons

---
 proposals/3916-authentication-for-media.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 83ab67b39e..a3c5ed633c 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -264,11 +264,14 @@ icons for the login providers as `mxc:` media URIs. These must be accessible
 without authentication (because the client has no access token at the time the
 icons are displayed).
 
-This remains a somewhat unsolved problem. Possibly the clients can continue
-to call the legacy `/_matrix/media/v3/download` URI for now: ultimately this
-problem will be solved by the transition to OIDC. Alternatively, a dedicated
-API could be provided or permission to use HTTP(S) URLs to access the icons.
-This support would come from a different MSC.
+Servers MAY flag the media as exceptions to the freeze described in part 5 of
+this proposal ("Backwards compatibility mechanisms"). Clients SHOULD continue to
+use the unauthenticated media download/thumbnail endpoints to access these icons
+until a future MSC can improve the situation.
+
+The proposal author expects that the spec's transition to OIDC will ultimately
+replace this mechanism, or that an MSC could be opened to allow HTTP(S) URLs in
+place of `mxc:` URIs.
 
 (This was previously discussed in
 [MSC2858](https://github.com/matrix-org/matrix-spec-proposals/pull/2858#discussion_r543513811).)

From 4fe23e57a566566915c8a805c13c793e069cb69f Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 30 May 2024 14:34:16 -0600
Subject: [PATCH 24/25] Update proposals/3916-authentication-for-media.md

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
---
 proposals/3916-authentication-for-media.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index a3c5ed633c..03ad6c7b6d 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -44,7 +44,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
-   and [`GET /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create)
+   and [`POST /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create)
    are **not** modified or deprecated by this MSC: it is intended that they be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 

From db90b92352fe5377845587a34efd92ef450e0da7 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 3 Jun 2024 16:31:39 -0600
Subject: [PATCH 25/25] Reintroduce federation /thumnail

---
 proposals/3916-authentication-for-media.md | 40 ++++++++++++----------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/proposals/3916-authentication-for-media.md b/proposals/3916-authentication-for-media.md
index 03ad6c7b6d..faf026bf2b 100644
--- a/proposals/3916-authentication-for-media.md
+++ b/proposals/3916-authentication-for-media.md
@@ -41,18 +41,14 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    | [`GET /_matrix/media/v3/config`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3config) | `GET /_matrix/client/v1/media/config` | - |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)            | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`            | `GET /_matrix/federation/v1/media/download/{mediaId}`  |
    | [`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaidfilename) | `GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}` | -                                                                 |
-   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | - |
+   | [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)          | `GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`           | `GET /_matrix/federation/v1/media/thumbnail/{mediaId}` |
 
    **Note**: [`POST /_matrix/media/v3/upload`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixmediav3upload)
    and [`POST /_matrix/media/v1/create`](https://spec.matrix.org/v1.10/client-server-api/#post_matrixmediav1create)
    are **not** modified or deprecated by this MSC: it is intended that they be brought into line with the other
    endpoints by a future MSC, such as [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911).
 
-   **Note**: `/thumbnail` does not have a federation endpoint. It appears as though
-   no servers request thumbnails over federation, and so it is not supported here.
-   A later MSC may introduce such an endpoint.
-
-2. Removal of `allow_remote` parameter from `/download`
+2. Removal of `allow_remote` parameter from `/download` and `/thumbnail`
 
    The current
    [`/download`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)
@@ -62,9 +58,10 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    server should request remote media from other servers. This is redundant
    with the new endpoints, so will not be supported.
 
-   Servers MUST NOT return remote media from `GET /_matrix/federation/v1/media/download`. The
-   `serverName` is omitted from the endpoint's path to strongly enforce this - the `mediaId` in
-   a request is assumed to be scoped to the target server.
+   Servers MUST NOT return remote media from `GET /_matrix/federation/v1/media/download` or
+   `GET /_matrix/federation/v1/media/thumbnail`. The `serverName` is omitted from
+   the endpoint's path to strongly enforce this - the `mediaId` in a request is
+   assumed to be scoped to the target server.
 
    `/_matrix/client/v1/media/download` and
    `/_matrix/client/v1/media/thumbnail` return remote media as normal.
@@ -159,6 +156,9 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
      This media is plain text. Maybe somebody used it as a paste bin.
      ```
 
+     **Note**: For clarity, the above applies to the federation `/thumbnail` endpoint
+     as well as `/download`.
+
 5. Backwards compatibility mechanisms
 
    Servers SHOULD *stop* serving new media as unauthenticated within 1 spec release
@@ -213,7 +213,7 @@ This proposal supersedes [MSC1902](https://github.com/matrix-org/matrix-spec-pro
    and `/thumbnail` Client-Server API endpoints.
 
    Servers MUST expect the `Location` header in the media part of the new Server-Server
-   API `/download` endpoint. Servers MUST NOT respond with a 307 or 308 redirect at
+   API `/download` and `/thumbnail` endpoints. Servers MUST NOT respond with a 307 or 308 redirect at
    the top level for the endpoint - they can only redirect within the media part
    itself.
 
@@ -292,7 +292,7 @@ place of `mxc:` URIs.
 * Users will be unable to copy links to media from web clients to share out of
   band. This is considered a feature, not a bug.
 
-* Over federation, the use of the `Range` request header on `/download` becomes
+* Over federation, the use of the `Range` request header on the federation endpoints becomes
   unclear as it could affect either or both parts of the response. There does not
   appear to be formal guidance in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#field.range)
   either. There are arguments for affecting both and either part equally. Typically,
@@ -303,7 +303,7 @@ place of `mxc:` URIs.
   should be handled, and leaves it as an HTTP specification interpretation problem
   instead.
 
-* The `Location` header support on the new `/download` endpoint could add a bit
+* The `Location` header support on the new federation endpoints could add a bit
   of complexity to servers, though given the alternative of supporting CDNs and
   similar is to place complexity into "edge workers" to mutate the response value.
   Though the Matrix spec would be "simpler", the edge worker setup would be
@@ -331,8 +331,8 @@ place of `mxc:` URIs.
   /_matrix/media/v3/config` at present, and we could just leave them in
   place. However, changing them at the same time makes the API more consistent.
 
-  Conversely, we should make sure to rename `POST
-  /_matrix/media/v3/upload` and `GET /_matrix/media/v3/create`. The reason to
+  Conversely, we should make sure to rename `POST /_matrix/media/v3/upload`
+  and `GET /_matrix/media/v3/create`. The reason to
   delay doing so is because MSC3911 will make more substantial changes to these
   endpoints, requiring another rename, and it is expected that both proposals
   will be merged near to the same time as each other (so a double rename will
@@ -341,7 +341,7 @@ place of `mxc:` URIs.
 
 * Rather than messing with multipart content, have a separate endpoint for
   servers to get the metadata for a media item. That would mean two requests,
-  but might make more sense than `/download` providing the info directly.
+  but might make more sense than the federation endpoints providing the info directly.
 
   This is a plausible approach with no significant upsides or downsides when
   compared to multipart responses.
@@ -388,11 +388,13 @@ While this proposal is in development, the new endpoints should be named as foll
 
     The `serverName` was later dropped in favour of explicit scoping. See `allow_remote` details
     in the MSC body for details.
+* `GET /_matrix/federation/unstable/org.matrix.msc3916.v2/media/thumbnail/{mediaId}`
+  * **Note**: This endpoint has a `.v2` in its unstable identifier due to the MSC changing after
+    initial implementation. The original unstable endpoint has a `serverName` and may still be
+    supported by some servers: `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`
 
-In a prior version of this proposal, the federation API included a thumbnail endpoint.
-It was removed due to lack of perceived usage. Servers which implemented the unstable
-version will have done so under `GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}`.
-The client-server thumbnail endpoint is unaffected by this change.
+    The `serverName` was later dropped in favour of explicit scoping. See `allow_remote` details
+    in the MSC body for details.
 
 ## Dependencies