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

518
data/api/client-server/authed-content-repo.yaml Normal file
View file

@ -0,0 +1,518 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019-2024 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
title: Matrix Client-Server (Authenticated) Content Repository API
version: 1.0.0
paths:
"/media/download/{serverName}/{mediaId}":
get:
x-addedInMatrixVersion: "1.11"
summary: Download content from the content repository.
description: |-
{{% boxes/note %}}
Clients SHOULD NOT generate or use URLs which supply the access token in
the query string. These URLs may be copied by users verbatim and provided
in a chat message to another user, disclosing the sender's access token.
{{% /boxes/note %}}
Clients MAY be redirected using the 307/308 responses below to download
the request object. This is typical when the homeserver uses a Content
Delivery Network (CDN).
operationId: getContentAuthed
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- $ref: '#/components/parameters/serverName'
- $ref: '#/components/parameters/mediaId'
- $ref: '#/components/parameters/timeout_ms'
responses:
"200":
description: The content that was previously uploaded.
headers:
Content-Type:
$ref: '#/components/headers/downloadContentType'
Content-Disposition:
description: The name of the file that was previously uploaded, if set.
schema:
type: string
content:
application/octet-stream:
schema:
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
"307":
$ref: '#/components/responses/downloadRedirect'
"308":
$ref: '#/components/responses/downloadRedirect'
"429":
$ref: '#/components/responses/rateLimited'
"502":
$ref: '#/components/responses/downloadTooLarge'
"504":
$ref: '#/components/responses/notYetUploaded'
tags:
- Media
"/media/download/{serverName}/{mediaId}/{fileName}":
get:
x-addedInMatrixVersion: "1.11"
summary: Download content from the content repository overriding the file name.
description: |-
This will download content from the content repository (same as
the previous endpoint) but replaces the target file name with the one
provided by the caller.
{{% boxes/note %}}
Clients SHOULD NOT generate or use URLs which supply the access token in
the query string. These URLs may be copied by users verbatim and provided
in a chat message to another user, disclosing the sender's access token.
{{% /boxes/note %}}
Clients MAY be redirected using the 307/308 responses below to download
the request object. This is typical when the homeserver uses a Content
Delivery Network (CDN).
operationId: getContentOverrideNameAuthed
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- $ref: '#/components/parameters/serverName'
- $ref: '#/components/parameters/mediaId'
- in: path
name: fileName
required: true
description: A filename to give in the `Content-Disposition` header.
example: filename.jpg
schema:
type: string
- $ref: '#/components/parameters/timeout_ms'
responses:
"200":
description: The content that was previously uploaded.
headers:
Content-Type:
$ref: '#/components/headers/downloadContentType'
Content-Disposition:
description: |-
The `fileName` requested or the name of the file that was previously
uploaded, if set.
schema:
type: string
content:
application/octet-stream:
schema:
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
"307":
$ref: '#/components/responses/downloadRedirect'
"308":
$ref: '#/components/responses/downloadRedirect'
"429":
$ref: '#/components/responses/rateLimited'
"502":
$ref: '#/components/responses/downloadTooLarge'
"504":
$ref: '#/components/responses/notYetUploaded'
tags:
- Media
"/media/thumbnail/{serverName}/{mediaId}":
get:
x-addedInMatrixVersion: "1.11"
summary: Download a thumbnail of content from the content repository
description: |-
Download a thumbnail of content from the content repository.
See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
{{% boxes/note %}}
Clients SHOULD NOT generate or use URLs which supply the access token in
the query string. These URLs may be copied by users verbatim and provided
in a chat message to another user, disclosing the sender's access token.
{{% /boxes/note %}}
Clients MAY be redirected using the 307/308 responses below to download
the request object. This is typical when the homeserver uses a Content
Delivery Network (CDN).
operationId: getContentThumbnailAuthed
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- $ref: '#/components/parameters/serverName'
- $ref: '#/components/parameters/mediaId'
- in: query
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may be
larger than the size specified.
example: 64
schema:
type: integer
- in: query
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may be
larger than the size specified.
example: 64
schema:
type: integer
- in: query
name: method
description: |-
The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails)
section for more information.
example: scale
schema:
type: string
enum:
- crop
- scale
- $ref: '#/components/parameters/timeout_ms'
- in: query
name: animated
x-addedInMatrixVersion: "1.11"
required: false
description: |
Indicates preference for an animated thumbnail from the server, if possible. Animated
thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
`image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
content types.
When `true`, the server SHOULD return an animated thumbnail if possible and supported.
When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
return an animated thumbnail.
Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
server should behave as though `animated` is `false`.
example: false
schema:
type: boolean
responses:
"200":
description: A thumbnail of the requested content.
headers:
Content-Type:
description: The content type of the thumbnail.
schema:
type: string
enum:
- image/jpeg
- image/png
- image/apng
- image/gif
- image/webp
content:
image/jpeg:
schema:
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
image/png:
schema:
x-changedInMatrixVersion:
"1.11": The PNG may be of the APNG variety if animation is supported and requested.
description: |
**Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
format if `animated=true`.
image/apng:
schema:
x-addedInMatrixVersion: "1.11"
description: "**Required.** The bytes for the *animated* thumbnail."
image/gif:
schema:
x-addedInMatrixVersion: "1.11"
description: "**Required.** The bytes for the *animated* thumbnail."
image/webp:
schema:
x-addedInMatrixVersion: "1.11"
description: "**Required.** The bytes for the *animated* thumbnail."
"307":
$ref: '#/components/responses/thumbnailRedirect'
"308":
$ref: '#/components/responses/thumbnailRedirect'
"400":
description: |-
The request does not make sense to the server, or the server cannot thumbnail
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN",
"error": "Cannot generate thumbnails for the requested content"
}
"413":
description: The local content is too large for the server to thumbnail.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
"429":
$ref: '#/components/responses/rateLimited'
"502":
description: The remote content is too large for the server to thumbnail.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
"504":
$ref: '#/components/responses/notYetUploaded'
tags:
- Media
/media/preview_url:
get:
x-addedInMatrixVersion: "1.11"
summary: Get information about a URL for a client
description: |-
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.
{{% boxes/note %}}
Clients should consider avoiding this endpoint for URLs posted in encrypted
rooms. Encrypted rooms often contain more sensitive information the users
do not want to share with the homeserver, and this can mean that the URLs
being shared should also not be shared with the homeserver.
{{% /boxes/note %}}
operationId: getUrlPreviewAuthed
security:
- accessTokenQuery: []
- accessTokenBearer: []
parameters:
- in: query
name: url
description: The URL to get a preview of.
required: true
example: https://matrix.org
schema:
type: string
format: uri
- in: query
name: ts
description: |-
The preferred point in time to return a preview for. The server may
return a newer version if it does not have the requested version
available.
example: 1510610716656
schema:
type: integer
format: int64
responses:
"200":
description: |-
The OpenGraph data for the URL, which may be empty. Some values are
replaced with matrix equivalents if they are provided in the response.
The differences from the OpenGraph protocol are described here.
content:
application/json:
schema:
type: object
properties:
matrix:image:size:
type: integer
format: int64
description: The byte-size of the image. Omitted if there is no image attached.
og:image:
type: string
format: uri
description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
the image. Omitted if there is no image.
examples:
response:
value: {
"og:title": "Matrix Blog Post",
"og:description": "This is a really cool blog post from matrix.org",
"og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
"og:image:type": "image/png",
"og:image:height": 48,
"og:image:width": 48,
"matrix:image:size": 102400
}
"429":
$ref: '#/components/responses/rateLimited'
tags:
- Media
/media/config:
get:
x-addedInMatrixVersion: "1.11"
summary: Get the configuration for the content repository.
description: |-
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.
All values are intentionally left optional. Clients SHOULD follow
the advice given in the field description when the field is not available.
{{% boxes/note %}}
Both clients and server administrators should be aware that proxies
between the client and the server may affect the apparent behaviour of content
repository APIs, for example, proxies may enforce a lower upload size limit
than is advertised by the server on this endpoint.
{{% /boxes/note %}}
operationId: getConfigAuthed
security:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: The public content repository configuration for the matrix server.
content:
application/json:
schema:
type: object
properties:
m.upload.size:
type: integer
format: int64
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.
examples:
response:
value: {
"m.upload.size": 50000000
}
"429":
$ref: '#/components/responses/rateLimited'
tags:
- Media
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer
parameters:
serverName:
in: path
name: serverName
required: true
description: |
The server name from the `mxc://` URI (the authority component).
example: matrix.org
schema:
type: string
format: mx-server-name
mediaId:
in: path
name: mediaId
required: true
description: |
The media ID from the `mxc://` URI (the path component).
example: ascERGshawAWawugaAcauga
schema:
type: string
timeout_ms:
in: query
name: timeout_ms
x-addedInMatrixVersion: "1.7"
description: |
The maximum number of milliseconds that the client is willing to wait to
start receiving data, in the case that the content has not yet been
uploaded. The default value is 20000 (20 seconds). The content
repository can and should impose a maximum value for this parameter. The
content repository may also choose to respond before the timeout.
example: 5000
schema:
type: integer
format: int64
default: 20000
responses:
rateLimited:
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
notYetUploaded:
description: |-
The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_YET_UPLOADED",
"error": "Content has not yet been uploaded"
}
downloadRedirect:
description: A redirect to the requested content.
headers:
Location:
description: The URL of the content.
schema:
type: string
format: uri
downloadTooLarge:
description: The content is too large for the server to serve.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
thumbnailRedirect:
description: A redirect to the thumbnail of the requested content.
headers:
Location:
description: The URL of the thumbnail content.
schema:
type: string
format: uri
headers:
downloadContentType:
description: The content type of the file that was previously uploaded.
schema:
type: string

51
data/api/client-server/content-repo.yaml
View file

@ -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:

12
data/api/client-server/definitions/sso_login_flow.yaml
View file

@ -53,6 +53,18 @@ properties:
description: |-
Optional `mxc://` URI to provide an image/icon representing the IdP.
Intended to be shown alongside the `name` if provided.
{{% boxes/note %}}
Clients SHOULD use the deprecated [`/download`](/client-server-api/#get_matrixmediav3downloadservernamemediaid)
and [`/thumbnail`](/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
endpoints to retrieve this media item because clients will not have
an access token they can authenticate with yet. Servers SHOULD ensure
media used for IdP icons is excluded from the freeze described by the
[Content Repository module's Client Behaviour section](/client-server-api/#content-repo-client-behaviour).
This may be addressed in the future with proposals like [MSC4148](https://github.com/matrix-org/matrix-spec-proposals/pull/4148),
or removed entirely through the transition to OIDC.
{{% /boxes/note %}}
example: "mxc://example.org/abc123"
brand:
type: string