Add authenticated media (MSC3916) (#1858)

* 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

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

@@ -217,7 +217,20 @@ paths:
         - Media
   "/media/v3/download/{serverName}/{mediaId}":
     get:
+      deprecated: true
       summary: Download content from the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContent
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -254,11 +267,24 @@ paths:
         - Media
   "/media/v3/download/{serverName}/{mediaId}/{fileName}":
     get:
+      deprecated: true
       summary: Download content from the content repository overriding the file name
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename)
+        (requires authentication).
+        {{% /boxes/note %}}
+
         This will download content from the content repository (same as
         the previous endpoint) but replace the target file name with the one
         provided by the caller.
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContentOverrideName
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -304,10 +330,23 @@ paths:
         - Media
   "/media/v3/thumbnail/{serverName}/{mediaId}":
     get:
+      deprecated: true
       summary: Download a thumbnail of content from the content repository
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
         Download a thumbnail of content from the content repository.
         See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContentThumbnail
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -455,8 +494,13 @@ paths:
         - Media
   /media/v3/preview_url:
     get:
+      deprecated: true
       summary: Get information about a URL for a client
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url).
+        {{% /boxes/note %}}
+
         Get information about a URL for the client. Typically this is called when a
         client sees a URL in a message and wants to render a preview for the user.
 
@@ -525,8 +569,13 @@ paths:
         - Media
   /media/v3/config:
     get:
+      deprecated: true
       summary: Get the configuration for the content repository.
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig).
+        {{% /boxes/note %}}
+
         This endpoint allows clients to retrieve the configuration of the content
         repository, such as upload limitations.
         Clients SHOULD use this as a guide when using content repository endpoints.
@@ -625,7 +674,7 @@ components:
         Indicates to the server that it should not attempt to fetch the media if
         it is deemed remote. This is to prevent routing loops where the server
         contacts itself.
-        
+
         Defaults to `true` if not provided.
       example: false
       schema: