Extensible Events - Files
parent
86fb65a4bd
commit
fb9491b054
@ -0,0 +1,161 @@
|
|||||||
|
# MSC0000: 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 non-text messaging types. This MSC covers just file
|
||||||
|
uploads, which is further used as a base for images, videos, etc.
|
||||||
|
|
||||||
|
*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 images
|
||||||
|
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` primary
|
||||||
|
event type is introduced to describe generic file uploads (PDFs, documents, etc).
|
||||||
|
|
||||||
|
An example is:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"type": "m.file",
|
||||||
|
"content": {
|
||||||
|
"m.text": "Upload: foo.pdf (12 KB)", // or other m.message-like event
|
||||||
|
"m.file": {
|
||||||
|
"url": "mxc://example.org/abcd1234",
|
||||||
|
"name": "foo.pdf",
|
||||||
|
"mimetype": "application/pdf",
|
||||||
|
"size": 12345
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This incorporates the intended schema for the [`m.file`](https://spec.matrix.org/v1.1/client-server-api/#mfile)
|
||||||
|
`msgtype` (minus the spurious thumbnail schema).
|
||||||
|
|
||||||
|
Note that a file event requires a text fallback of `m.text`, `m.html`, or other `m.message`-compatible
|
||||||
|
event.
|
||||||
|
|
||||||
|
An encrypted file would appear as such:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"type": "m.file",
|
||||||
|
"content": {
|
||||||
|
"m.text": "Upload: foo.pdf (12 KB)", // or other m.message-like event
|
||||||
|
"m.file": {
|
||||||
|
"url": "mxc://example.org/abcd1234",
|
||||||
|
"name": "foo.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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The presence of a `key` JWT denotes the file is encrypted.
|
||||||
|
|
||||||
|
## Potential issues
|
||||||
|
|
||||||
|
The schema duplicates some of the information into the text fallback, though this is unavoidable.
|
||||||
|
|
||||||
|
## Alternatives
|
||||||
|
|
||||||
|
No significant alternatives known.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
The same considerations which currently apply to files and extensible events also apply here.
|
||||||
|
|
||||||
|
## Transition
|
||||||
|
|
||||||
|
The same transition introduced by extensible events is also applied here:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"type": "m.room.message",
|
||||||
|
"content": {
|
||||||
|
"msgtype": "m.file",
|
||||||
|
"body": "foo.pdf",
|
||||||
|
"info": {
|
||||||
|
"size": 774,
|
||||||
|
"mimetype": "application/pdf"
|
||||||
|
},
|
||||||
|
"file": {
|
||||||
|
"url": "mxc://example.org/f91dce7b060ed4c8f094cd3ecb498aa621bbe242",
|
||||||
|
"key": {
|
||||||
|
"kty": "oct",
|
||||||
|
"key_ops": ["encrypt", "decrypt"],
|
||||||
|
"alg": "A256CTR",
|
||||||
|
"k": "TLlG_OpX807zzQuuwv4QZGJ21_u7weemFGYJFszMn9A",
|
||||||
|
"ext": true
|
||||||
|
},
|
||||||
|
"iv": "S22dq3NAX8wAAAAAAAAAAA",
|
||||||
|
"hashes": {
|
||||||
|
"sha256": "aWOHudBnDkJ9IwaR1Nd8XKoI7DOrqDTwt6xDPfVGN6Q"
|
||||||
|
},
|
||||||
|
"v": "v2"
|
||||||
|
},
|
||||||
|
|
||||||
|
// Extensible Events
|
||||||
|
"m.text": "foo.pdf",
|
||||||
|
"m.file": {
|
||||||
|
"url": "mxc://example.org/f91dce7b060ed4c8f094cd3ecb498aa621bbe242",
|
||||||
|
"name": "foo.pdf",
|
||||||
|
"mimetype": "application/pdf",
|
||||||
|
"size": 774,
|
||||||
|
"key": {
|
||||||
|
"kty": "oct",
|
||||||
|
"key_ops": ["encrypt", "decrypt"],
|
||||||
|
"alg": "A256CTR",
|
||||||
|
"k": "TLlG_OpX807zzQuuwv4QZGJ21_u7weemFGYJFszMn9A",
|
||||||
|
"ext": true
|
||||||
|
},
|
||||||
|
"iv": "S22dq3NAX8wAAAAAAAAAAA",
|
||||||
|
"hashes": {
|
||||||
|
"sha256": "aWOHudBnDkJ9IwaR1Nd8XKoI7DOrqDTwt6xDPfVGN6Q"
|
||||||
|
},
|
||||||
|
"v": "v2"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The event details are copied and quite verbose, however this is best to ensure compatibility with the
|
||||||
|
extensible events format.
|
||||||
|
|
||||||
|
## Unstable prefix
|
||||||
|
|
||||||
|
While this MSC is not considered stable, implementations should use `org.matrix.msc1767.file` in place
|
||||||
|
of `m.file` throughout this proposal. Note that this uses the namespace of the parent MSC rather than
|
||||||
|
the namespace of this MSC - this is deliberate.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"type": "org.matrix.msc1767.file",
|
||||||
|
"content": {
|
||||||
|
"org.matrix.msc1767.text": "Upload: foo.pdf (12 KB)", // or other org.matrix.msc1767.message-like event
|
||||||
|
"org.matrix.msc1767.file": {
|
||||||
|
"url": "mxc://example.org/abcd1234",
|
||||||
|
"name": "foo.pdf",
|
||||||
|
"mimetype": "application/pdf",
|
||||||
|
"size": 12345
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
Loading…
Reference in New Issue