Merge 4349abc4de into d6edcbd946

proposals/3551-extensible-events-files.md

@@ -0,0 +1,109 @@
+# MSC3551: Extensible Events - Files
+
+[MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail,
+though deliberately does not include schemas for some messaging types. This MSC covers only regular
+file uploads.
+
+*Rationale*: Splitting the MSCs down into individual parts makes it easier to implement and review in
+stages without blocking other pieces of the overall idea. For example, an issue with the way files
+are represented should not block the overall schema from going through.
+
+## Proposal
+
+Using [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767)'s system, a new `m.file`
+event type is introduced to describe generic file uploads (PDFs, documents, etc).
+
+An example is:
+
+```json5
+{
+  "type": "m.file",
+  "content": {
+    "m.text": [
+      // Format of the fallback is not defined, but should have enough information for a text-only
+      // client to do something with the file.
+      {"body": "matrix.pdf (12 KB) https://example.org/_matrix/media/v3/download/example.org/abcd1234"}
+    ],
+    "m.file": {
+      "url": "mxc://example.org/abcd1234",
+      "name": "matrix.pdf",
+      "mimetype": "application/pdf",
+      "size": 12345,
+
+      // These are all from EncryptedFile: https://spec.matrix.org/v1.1/client-server-api/#sending-encrypted-attachments
+      "key": {
+        "kty": "oct",
+        "key_ops": ["encrypt", "decrypt"],
+        "alg": "A256CTR",
+        "k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0",
+        "ext": true
+      },
+      "iv": "w+sE15fzSc0AAAAAAAAAAA",
+      "hashes": {
+        "sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
+      },
+      "v": "v2"
+    },
+    "m.caption": { // optional - goes above/below file
+      "m.text": [{"body": "Look at this cool Matrix document"}]
+    },
+  }
+}
+```
+
+The reusable `m.file` content block describes the actual file, with the following properties:
+
+* `uri` - Required MXC URI for the file itself.
+* `name` - Required name of the file, with extension (if applicable).
+* `mimetype` - Optional (but recommended) mimetype for the file that was uploaded.
+* `size` - Optional (but recommended) size in bytes for the file that was uploaded.
+
+If the file is encrypted, the following fields additionally apply. All fields are to support the
+`EncryptedFile` object described by the [encryption module](https://spec.matrix.org/v1.1/client-server-api/#sending-encrypted-attachments).
+
+* `key` - Required JSON Web Key. The presence of this field indicates the file is encrypted.
+* `iv` - Required serialized initialization vector.
+* `hashes` - Required hashes object.
+* `v` - Required version string.
+
+This structure covers the existing [`m.file`](https://spec.matrix.org/v1.1/client-server-api/#mfile)
+`msgtype` (minus the spurious thumbnail schema).
+
+Additionally, the following content blocks are defined:
+
+* `m.caption` - A message to place above or below the rendered content (in this case, a file).
+  Currently requires an `m.text` content block to be nested within it.
+
+Together with content blocks from other proposals, an `m.file` is described as:
+
+* **Required** - An `m.text` block to act as a fallback for clients which can't process files.
+* **Required** - An `m.file` to describe the actual file.
+* **Optional** - An `m.caption` block to represent any text that should be shown above or below the
+  file. Currently this MSC does not describe a way to pick whether the text goes above or below,
+  leaving this as an implementation detail. A future MSC may investigate ways of representing this,
+  if needed.
+
+The above describes the minimum requirements for sending an `m.file` event. Senders can add additional
+blocks, however as per the extensible events system, receivers which understand file events should not
+honour them.
+
+## Potential issues
+
+The schema duplicates some of the information into the text fallback, though this is unavoidable
+and intentional for fallback considerations.
+
+## Alternatives
+
+No significant alternatives known.
+
+## Security considerations
+
+The same considerations which currently apply to files and extensible events also apply here.
+
+## Unstable prefix
+
+While this MSC is not considered stable, implementations should use `org.matrix.msc1767.*` as a prefix in
+place of `m.*` throughout this proposal. Note that this uses the namespace of the parent MSC rather than
+the namespace of this MSC - this is deliberate.
+
+Note that extensible events should only be used in an appropriate room version as well.