wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add authenticated media (MSC3916) (#1858)

Browse source 
* C2S: Deprecate now-legacy endpoints

* C2S: Fix MXC URI code block while we're here

* C2S: Describe the authentication and deprecation requirements

* C2S: Intro the upload/download endpoints differently

* C2S: Literally copy/paste the `content-repo.yaml` spec

* C2S: Drop `/upload` and `/create` because we aren't replacing them today

* C2S: Fix notes while we're here

* C2S: Update metadata for new endpoints

* C2S: Add authentication to new endpoints

* C2S: Drop `allow_remote` and `allow_redirect` on new endpoints

* C2S: Append backwards compatibility notes

* C2S: Decorate old media endpoints with pointers to the new ones

The server-server spec might have a harder time linking to these, but that can be fixed with verbiage.

* C2S: Annotate IdP icon spec with media auth implications

* S2S: Modernize section text

* S2S: Create content repository API

This is largely a copy/paste of the new authed content repo API in the Client-Server API, though some keywords (like "client") have been changed. Paths and response formats have also been changed to support the federation-specific requirements.

* C2S & S2S: Add plethora of changelogs

* Reference RFC 1341

* Upgrade keywords in changed text

* Mention caching

* Cross-reference IdP icons

* Update content/client-server-api/modules/content_repo.md
This commit is contained in:
Travis Ralston 2024-06-13 12:08:27 -06:00 • committed by GitHub
parent 4a280bcd87
commit 7a51ae879c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 967 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

5
content/client-server-api/_index.md
View file

@ -37,9 +37,8 @@ The exceptions are:
which take an empty request body.
Similarly, all endpoints require the server to return a JSON object,
with the exception of 200 responses to
[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid)
and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid).
with the exception of 200 responses to the media download endpoints in the
[Content Repository module](#content-repository).
Servers must include a `Content-Type` header of `application/json` for all JSON responses.
All JSON data, in requests or responses, must be encoded using UTF-8.

58
content/client-server-api/modules/content_repo.md
View file

@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a
interacting with the media repository.
{{% /boxes/added-in-paragraph %}}
{{% boxes/added-in-paragraph %}}
{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been
deprecated in favour of newer, authenticated, ones. This change includes updating
the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`,
with the exception of the `/upload` and `/create` endpoints. The upload/create
endpoints are expected to undergo a similar transition in a later version of the
specification.
{{% /boxes/added-in-paragraph %}}
#### Matrix Content (`mxc://`) URIs
Content locations are represented as Matrix Content (`mxc://`) URIs. They
look like:
mxc://<server-name>/<media-id>
```
mxc://<server-name>/<media-id>
<server-name> : The name of the homeserver where this content originated, e.g. matrix.org
<media-id> : An opaque ID which identifies the content.
<server-name> : The name of the homeserver where this content originated, e.g. matrix.org
<media-id> : An opaque ID which identifies the content.
```
#### Client behaviour
#### Client behaviour {id="content-repo-client-behaviour"}
Clients can upload and download content using the following HTTP APIs.
Clients can access the content repository using the following endpoints.
{{% boxes/added-in-paragraph %}}
{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints
described below. Instead, they SHOULD use the new endpoints which require authentication.
{{% /boxes/added-in-paragraph %}}
{{% boxes/warning %}}
By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
to prevent newly-uploaded media from being downloaded. This SHOULD mean that any
media uploaded *before* the freeze remains accessible via the deprecated endpoints,
and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible
through the new, authenticated, endpoints. For remote media, "newly-uploaded" is
determined by the date the cache was populated. This may mean the media is older
than the freeze, but because the server had to re-download it, it is now considered
"new".
Clients SHOULD update to support the authenticated endpoints before servers freeze
unauthenticated access.
Servers SHOULD consider their local ecosystem impact before enacting a freeze.
This could mean ensuring their users' typical clients support the new endpoints
when available, or updating bridges to start using media proxies.
In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema)
from the freeze. See the `m.login.sso` flow schema for details.
An *example* timeline for a server may be:
* Matrix 1.11 release: Clients begin supporting authenticated media.
* Matrix 1.12 release: Servers freeze unauthenticated media access.
* Media uploaded prior to this point still works with the deprecated endpoints.
* Newly uploaded (or cached) media *only* works on the authenticated endpoints.
Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter.
{{% /boxes/warning %}}
{{% http-api spec="client-server" api="authed-content-repo" %}}
{{% http-api spec="client-server" api="content-repo" %}}