diff --git a/config.sample.yaml b/config.sample.yaml index 83797959..27d1a1a2 100644 --- a/config.sample.yaml +++ b/config.sample.yaml @@ -548,7 +548,18 @@ plugins: # Sections of this config might disappear or be added over time. By default all # features are disabled in here and must be explicitly enabled to be used. featureSupport: - # No unstable features are currently supported. + # MSC3916 enables linking media to events, allowing the associated media to be + # deleted when the event is (fully) deleted. MSC3916 support is always enabled + # and requires changes to either the homeserver or how the homeserver is deployed + # to work. + MSC3916: + # How long a "restricted" item of media can exist before it is automatically + # purged from the server. Defaults to 10 minutes. + maxRestrictedAgeMinutes: 10 + + # The maximum number of media items that can be attached to a single event. + # Defaults to 20. + maxAttachEvent: 20 # Support for redis as a cache mechanism # diff --git a/docs/msc3911.md b/docs/msc3911.md new file mode 100644 index 00000000..353208bd --- /dev/null +++ b/docs/msc3911.md @@ -0,0 +1,65 @@ +# [MSC3911](https://github.com/matrix-org/matrix-spec-proposals/pull/3911) API + +*Note*: These docs may change as the MSC progresses towards stability. + +This document describes MMR's API requirements for supporting MSC3911. + +## Authentication + +Servers making requests to MMR's MSC3911 APIs *MUST* include an `Authorization` header containing a `Bearer` token supplied +in the MMR config. This is a per-server token used to identify the sending server. + +Requests lacking this authentication will receive a standard Matrix error response of `{"errcode":"M_UNAUTHORIZED"}` and +status code 401. If the request had authentication, but the server making the request does not have appropriate ability +to affect the given resource, `{"errcode":"M_FORBIDDEN"}` and status code 403 is returned. For example, a server trying +to clean up a user belonging to another server. + +Additionally, the `Host` header received by MMR *MUST* match the requesting server's name, like with all other MMR endpoints. +The server name is the name used in user IDs. + +## Event sending + +The [`PUT /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}`](https://spec.matrix.org/v1.8/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) +and [`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](https://spec.matrix.org/v1.8/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) +endpoints support a new `attach_media` repeated parameter under MSC3911. While unstable, this new parameter is `org.matrix.msc3911.attach_media`. + +The MMR API to associate an event ID with the user-specified media is `POST /_mmr/v1/attach/event/{eventId}` with JSON body +being the list of associated MXC URIs. If unsuccessful, MMR will return a standard Matrix error response consistent with +MSC3911: `{"errcode":"M_INVALID_PARAM"}` and 400 status code. + +## User profiles + +Similar to event sending, [`PUT /_matrix/client/v3/profile/{userId}/avatar_url`](https://spec.matrix.org/v1.8/client-server-api/#put_matrixclientv3profileuseridavatar_url) +automatically supports attaching to the user's profile. + +The MMR API to associate that media with the user's profile is `POST /_mmr/v1/attach/user/{userId}` with JSON body being +a list of associated MXC URIs (should normally be a single entry). If unsuccessful, MMR will return a standard Matrix +error response consistent with MSC3911: `{"errcode":"M_INVALID_PARAM"}` and 400 status code. + +## Redactions + +When a redaction occurs, the server should hit `POST /_mmr/v1/cleanup/event/{eventId}` with an empty JSON object for a body. + +MMR will return `{"deleted":2}` to denote how many pieces of media were removed. If there were no linked media items, +`deleted: 0` will be returned. + +## User deactivations + +When a user is deactivated, the server should hit `POST /_mmr/v1/cleanup/user/{userId}` with an empty JSON object for a +body. + +MMR will return `{"deleted":2}` to denote how many pieces of media were removed. If there were no linked media items, +`deleted: 0` will be returned. + +## Visibility check + +When MMR needs to ensure a given user or server can see a particular event or profile, it will use the following endpoints: + +* `GET /_mmr-upstream/v1/visibility/event/{targetEventId}/user/{viewingUserId}` with no request body. +* `GET /_mmr-upstream/v1/visibility/event/{targetEventId}/server/{viewingServerName}` with no request body. +* `GET /_mmr-upstream/v1/visibility/profile/{targetUserId}/user/{viewingUserId}` with no request body. +* `GET /_mmr-upstream/v1/visibility/profile/{targetUserId}/server/{viewingServerName}` with no request body. + +In all cases, a `404 M_NOT_FOUND` error should be returned if visibility is not possible or the parameters are malformed. +If the server does not support the endpoints, it *MUST* return `404 M_UNRECOGNIZED` per the Matrix specification on unknown +endpoints. If visibility is permitted, a 200 status code is returned. MMR will discard the response body on 200 OK.