From f915ff4f20bc1e15b55bfda92345ef3d528a55c1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 23 Feb 2019 21:30:29 -0700 Subject: [PATCH 1/4] Proposal to split the media repo into s2s and c2s parts --- proposals/1902-split-media-c2s-s2s.md | 58 +++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 proposals/1902-split-media-c2s-s2s.md diff --git a/proposals/1902-split-media-c2s-s2s.md b/proposals/1902-split-media-c2s-s2s.md new file mode 100644 index 00000000000..1de48ea44d5 --- /dev/null +++ b/proposals/1902-split-media-c2s-s2s.md @@ -0,0 +1,58 @@ +## Splitting the media repo into a client-side and server-side component + +Currently Matrix relies on media being pulled from servers using the same set +of endpoints which clients use. This has so far meant that media repository +implementations cannot reliably enforce auth on given resources. + +### Proposal + +In order to remain backwards compatible with all existing clients, servers, and +media repository implementations it is proposed that nothing changes namespace +and instead the version used in the URL be the difference between c2s and s2s +endpoints. + +Servers shall use `/_matrix/media/v1` to access the media repository, adding +applicable headers for any federation request they would normally do. The media +repository must validate the request. + +Clients shall use `/_matrix/media/r0` to access the media repository, providing +an access token as it normally would. More detailed access control for media is +left as a task for [MSC701](https://github.com/matrix-org/matrix-doc/issues/701). + +Besides auth, the endpoints covered by the media repository are left otherwise +untouched. For example, the way to download a file is still a request to +`GET /_matrix/media/{version}/download/remote.example.org/mediaid`. + +### Changes required by known implementations + +**Clients**: +* Actually provide an access token to download media, thumbnails, etc. Currently + clients generally don't do this, which is a bit problematic. Media repository + implementations should consider this before locking down the endpoints if this + proposal is to be accepted. +* Potentially change how they download files. Currently many just stick the URL + into an `` (or equivalent) and hope for the best, however this + opens up the user to risk if the access token were to be passed via the query + string: users would more often be accidentally handing out their access token to + people. Instead, clients should consider downloading media via other means and + using blobs to populate img elements (or whatever their equivalent is for their + chosen platform). +* Actually use the `r0` route if they aren't already. The author of this proposal + believes most clients already do this. + +**Servers / Media repository implementations**: +* Mature server implementations currently require no changes here: they already + make requests to the `v1` route and sign the request appropriately. +* Less mature implementations (such as the author's own media repository impl) will + need to verify they make requests to the right place, and sign requests where + appropriate. +* All implementations will need to verify the request is correctly signed for `v1` + endpoints, and access token restrictions on `r0` endpoints. + + +### References + +* [MSC701](https://github.com/matrix-org/matrix-doc/issues/701) - Access control and + GDPR for the media repo. +* [matrix-doc#1341](https://github.com/matrix-org/matrix-doc/issues/1341) - Concerns + with servers using the client-server endpoints to download media over federation. From 557c266013270430a4d4982bc833c9f044ca462c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 20 Mar 2019 14:31:25 -0600 Subject: [PATCH 2/4] Move client media access to the client namespace --- proposals/1902-split-media-c2s-s2s.md | 33 +++++++++++++-------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/proposals/1902-split-media-c2s-s2s.md b/proposals/1902-split-media-c2s-s2s.md index 1de48ea44d5..49ac9e37e0a 100644 --- a/proposals/1902-split-media-c2s-s2s.md +++ b/proposals/1902-split-media-c2s-s2s.md @@ -6,30 +6,28 @@ implementations cannot reliably enforce auth on given resources. ### Proposal -In order to remain backwards compatible with all existing clients, servers, and -media repository implementations it is proposed that nothing changes namespace -and instead the version used in the URL be the difference between c2s and s2s -endpoints. - Servers shall use `/_matrix/media/v1` to access the media repository, adding applicable headers for any federation request they would normally do. The media repository must validate the request. -Clients shall use `/_matrix/media/r0` to access the media repository, providing -an access token as it normally would. More detailed access control for media is -left as a task for [MSC701](https://github.com/matrix-org/matrix-doc/issues/701). +Clients shall use `/_matrix/client/{version}/media` to access the media repository, +providing an access token as it normally would. More detailed access control for +media is left as a task for [MSC701](https://github.com/matrix-org/matrix-doc/issues/701). +Currently, `{version}` may only be `r0` (or `unstable` for testing purposes). Besides auth, the endpoints covered by the media repository are left otherwise -untouched. For example, the way to download a file is still a request to -`GET /_matrix/media/{version}/download/remote.example.org/mediaid`. +untouched. For example, the way to download a file from a server is still a request +to `GET /_matrix/media/{version}/download/remote.example.org/mediaid`. The similar +client endpoint would be `GET /_matrix/client/{version}/media/download/remote.example.org/mediaid`. ### Changes required by known implementations **Clients**: -* Actually provide an access token to download media, thumbnails, etc. Currently - clients generally don't do this, which is a bit problematic. Media repository - implementations should consider this before locking down the endpoints if this - proposal is to be accepted. +* Use the new endpoint, supplying required auth. Historically clients have used + `/_matrix/media/` to download media unauthenticated, and media repository + implementations should consider this before locking down the endpoint for servers + only. Servers are encouraged to respect a reasonable transition period for clients + to adopt the new spec, once landed. * Potentially change how they download files. Currently many just stick the URL into an `` (or equivalent) and hope for the best, however this opens up the user to risk if the access token were to be passed via the query @@ -37,8 +35,9 @@ untouched. For example, the way to download a file is still a request to people. Instead, clients should consider downloading media via other means and using blobs to populate img elements (or whatever their equivalent is for their chosen platform). -* Actually use the `r0` route if they aren't already. The author of this proposal - believes most clients already do this. +* Actually use the `r0` route if they aren't already. Some clients use the `v1` + endpoints to show media to users, which is incorrect. Likewise, clients should + not be using the `unstable` editions of these in released versions. **Servers / Media repository implementations**: * Mature server implementations currently require no changes here: they already @@ -47,7 +46,7 @@ untouched. For example, the way to download a file is still a request to need to verify they make requests to the right place, and sign requests where appropriate. * All implementations will need to verify the request is correctly signed for `v1` - endpoints, and access token restrictions on `r0` endpoints. + endpoints, and access token restrictions on the new `r0` endpoints. ### References From ee31e81fb8515bff4fb8cddc243c11d9a5cc0d4e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Jul 2020 19:54:53 -0600 Subject: [PATCH 3/4] Update for modern standards --- proposals/1902-split-media-c2s-s2s.md | 100 +++++++++++++------------- 1 file changed, 51 insertions(+), 49 deletions(-) diff --git a/proposals/1902-split-media-c2s-s2s.md b/proposals/1902-split-media-c2s-s2s.md index 49ac9e37e0a..1ae8199b0ea 100644 --- a/proposals/1902-split-media-c2s-s2s.md +++ b/proposals/1902-split-media-c2s-s2s.md @@ -1,55 +1,57 @@ -## Splitting the media repo into a client-side and server-side component +# Splitting the media repo into a client-side and server-side component Currently Matrix relies on media being pulled from servers using the same set of endpoints which clients use. This has so far meant that media repository -implementations cannot reliably enforce auth on given resources. - -### Proposal - -Servers shall use `/_matrix/media/v1` to access the media repository, adding -applicable headers for any federation request they would normally do. The media -repository must validate the request. - -Clients shall use `/_matrix/client/{version}/media` to access the media repository, -providing an access token as it normally would. More detailed access control for -media is left as a task for [MSC701](https://github.com/matrix-org/matrix-doc/issues/701). -Currently, `{version}` may only be `r0` (or `unstable` for testing purposes). - -Besides auth, the endpoints covered by the media repository are left otherwise -untouched. For example, the way to download a file from a server is still a request -to `GET /_matrix/media/{version}/download/remote.example.org/mediaid`. The similar -client endpoint would be `GET /_matrix/client/{version}/media/download/remote.example.org/mediaid`. - -### Changes required by known implementations - -**Clients**: -* Use the new endpoint, supplying required auth. Historically clients have used - `/_matrix/media/` to download media unauthenticated, and media repository - implementations should consider this before locking down the endpoint for servers - only. Servers are encouraged to respect a reasonable transition period for clients - to adopt the new spec, once landed. -* Potentially change how they download files. Currently many just stick the URL - into an `` (or equivalent) and hope for the best, however this - opens up the user to risk if the access token were to be passed via the query - string: users would more often be accidentally handing out their access token to - people. Instead, clients should consider downloading media via other means and - using blobs to populate img elements (or whatever their equivalent is for their - chosen platform). -* Actually use the `r0` route if they aren't already. Some clients use the `v1` - endpoints to show media to users, which is incorrect. Likewise, clients should - not be using the `unstable` editions of these in released versions. - -**Servers / Media repository implementations**: -* Mature server implementations currently require no changes here: they already - make requests to the `v1` route and sign the request appropriately. -* Less mature implementations (such as the author's own media repository impl) will - need to verify they make requests to the right place, and sign requests where - appropriate. -* All implementations will need to verify the request is correctly signed for `v1` - endpoints, and access token restrictions on the new `r0` endpoints. - - -### References +implementations cannot reliably enforce auth on given resources, and implementations +are left confused/concerned about the lack of split in the endpoints. + +## Proposal + +Instead of using `/_matrix/media` for both servers and clients, servers must now use +`/_matrix/federation/v1/remote_media` and clients must use `/_matrix/client/r0/media`. + +To support backwards compatibility and logical usage of the media repo, only downloads +and thumbnails will be available over the new federation prefix. The remaining endpoints +will only be available through the client-server API. + +The mapping of each endpoint would look like: + +| Old | Client-Server | Federation | +|-----|---------------|------------| +| `/_matrix/media/:version/download/:origin/:mediaId` | `/_matrix/client/r0/media/download/:origin/:mediaId` | `/_matrix/federation/v1/remote_media/download/:origin/:mediaId` | +| `/_matrix/media/:version/thumbnail/:origin/:mediaId` | `/_matrix/client/r0/media/thumbnail/:origin/:mediaId` | `/_matrix/federation/v1/remote_media/thumbnail/:origin/:mediaId` | +| `/_matrix/media/:version/upload` | `/_matrix/client/r0/media/upload` | N/A | +| `/_matrix/media/:version/preview_url` | `/_matrix/client/r0/media/preview_url` | N/A | +| `/_matrix/media/:version/config` | `/_matrix/client/r0/media/config` | N/A | + +No schema changes are proposed to the endpoints, aside from the obvious pathing differences. + +### Federation endpoints + +Because media is not (currently) actively federated, the endpoint is named "remote_media" +to imply it is not a resource the target server is expected to have. + +The federation endpoints will require standard [request authentication](https://matrix.org/docs/spec/server_server/r0.1.4#request-authentication). + +### Client-server endpoints + +With the exception of `/download` and `/thumbnail`, all media endpoints require authentication. +We could require access tokens on media, however [MSC701](https://github.com/matrix-org/matrix-doc/issues/701) +and similar are better positioned to handle the problem. + +## Changes required by known implementations + +Clients and servers will have to adopt the new endpoints entirely. It is expected that +existing implementations will continue to use the legacy routes for a short time while +these changes gain popularity in the ecosystem. + +In a prior version of this proposal it was suggested to use `/_matrix/media/v1` for +server-server communication with the authentication requirements described here, however +due to some clients still using `/_matrix/media/v1` (despite the endpoint changing to be +`/_matrix/media/r0` some versions ago) it is not feasible to support backwards compatibility +with the authenticated endpoints. + +## References * [MSC701](https://github.com/matrix-org/matrix-doc/issues/701) - Access control and GDPR for the media repo. From 1c54f6a33801f33ac3f98aee5561bbd558c6e21c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Jul 2020 20:00:21 -0600 Subject: [PATCH 4/4] Add unstable prefix --- proposals/1902-split-media-c2s-s2s.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/1902-split-media-c2s-s2s.md b/proposals/1902-split-media-c2s-s2s.md index 1ae8199b0ea..4b22fba3acd 100644 --- a/proposals/1902-split-media-c2s-s2s.md +++ b/proposals/1902-split-media-c2s-s2s.md @@ -57,3 +57,9 @@ with the authenticated endpoints. GDPR for the media repo. * [matrix-doc#1341](https://github.com/matrix-org/matrix-doc/issues/1341) - Concerns with servers using the client-server endpoints to download media over federation. + +## Unstable prefix + +While this MSC is not in a released version of the spec, use `unstable/org.matrix.msc1902` in place +of the version. For example, `/_matrix/client/r0/media/config` becomes +`/_matrix/client/unstable/org.matrix.msc1902/media/config`.