matrix-spec-proposals/proposals/3551-extensible-events-files.md

MSC3551: Extensible Events - Files

MSC1767 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's system, a new m.file event type is introduced to describe generic file uploads (PDFs, documents, etc).

An example is:

{
  "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.

• 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 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.