Merge 3a7b8963f4 into ecf996389f

proposals/2706-IPFS.md

@@ -0,0 +1,77 @@
+# MSC2706: IPFS as a media repository
+
+The current media/content repository in Matrix is somewhat reliant on the origin server staying
+online indefinitely to serve the media, which is not always the case. Some servers may be bandwidth
+constrained (don't want to be dealing with thousands of people requesting media from them) or simply
+go down for maintenance/indefinite closure. When this happens, it would be useful to have media
+stored on other nodes and have a way to contact them.
+
+We could invent our own system for finding out which other servers have a copy of the given media
+and gossip it, or we could rely on a solution that has solved this problem.
+
+[IPFS](https://ipfs.io/) describes itself as a peer-to-peer hypermedia protocol and fits perfectly
+within Matrix's vision of an open, secure, and decentralised world. It handles media distribution
+for free (from our perspective) and is easily integrated into Matrix.
+
+## Proposal
+
+If not obvious by now, the proposal is to use IPFS within Matrix for media handling. Unfortunately
+this proposal does not recommend using `ipfs://` URIs in place of `mxc://` for backwards compatibility
+reasons, however is sufficient adoption is achieved then Matrix could easily switch over to that.
+For now, clients and servers *should* handle `ipfs://` URIs if they see them however this proposal
+mostly focuses on introducing IPFS in a backwards compatible manner.
+
+**TODO: Decide if not using `ipfs://` is a mistake.**
+
+IPFS uses "content IDs" (or "cid") to reference media which are compatible with Matrix's media IDs (**TODO: CONFIRM**),
+making the process even easier to migrate. To support backwards compatability with older clients
+and servers, the media ID is proposed to be formatted as `ipfs:<cid>` for IPFS-hosted media. This
+will allow legacy servers and clients to contact their homeserver and resolve it to an IPFS gateway
+to be served while indicating to supporting implementations that they do not need to contact the
+origin server and can instead use IPFS directly to retrieve the media.
+
+For completeness, an example IPFS-styled MXC URI would be `mxc://example.org/ipfs:cidgoeshere`.
+
+Because clients can embed an IPFS node into themselves or [access IPFS from the browser](https://github.com/ipfs/in-web-browsers/blob/master/ADDRESSING.md),
+it would be extremely useful to allow the client to bypass the `/upload` endpoint and publish its
+own MXC URI after having used a local IPFS node. Considering `ipfs://` support is not proposed here,
+clients will need to get a homeserver name/origin to put into the `mxc://` URI. They'll also need to
+know if the server even supports IPFS to be able to bypass `/upload` entirely.
+
+To permit the bypass of `/upload`, a new capability is proposed: `m.ipfs`. When present, this indicates
+to the client that the server's media repo is IPFS-capable and thus can be bypassed. Clients will still
+need to know an origin to provide in the MXC URI however. Clients should use the following steps to
+determine an appropriate origin:
+
+1. The one they were explicitly provided (in the case of a user wanting to use a particular gateway).
+2. The origin specified by the optional `preferred_origin` in the `m.ipfs` capability.
+3. The domain name for the user's ID, as a default option.
+
+----
+
+This proposal does encourage that client implementation embed IPFS support to avoid having to contact
+the homeserver for content. Clients might still wish to use functionality like thumbnails from the
+server, however if specified well enough by other MSCs a client could feasibly use the `thumbnail_uri`
+provided by the sending client to display appropriate content without ever having to contact the
+homeserver.
+
+## Potential issues
+
+**TODO: Investigate ways to mitigate.**
+
+* Retention and redaction, erasure.
+* Spam, abuse, etc
+* Quarantining content (not currently specified, but should be considered).
+
+## Alternatives
+
+**TODO: Find other solutions than IPFS and explain why they're bad.**
+
+## Security considerations
+
+**TODO: This.**
+
+## Unstable prefix
+
+While this MSC is not in a released version of the spec, `io.t2bot.ipfs` should be used in place of
+`m.ipfs`. No special endpoints, version flags, or other prefixes are required for this MSC.