Start designing API and config for MSC3911

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
 #

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.