matrix-mxc-proxy v1.0.5

Matrix MXC proxy

To bridge another platform to Matrix, you must deal with attachments uploaded in that platform. The usual approach is to request the file and pipe the response to your Matrix homeserver's upload endpoint. Now, if you have quite some resources for your homeserver, then that's not really a problem. But what if:

• You don't want to have the files in your homeserver.
  • Note that a homeserver will only request a remote file if a user explicitly asks for it, when eg. a client needs to render the attachment, etc.
• You don't want to record the bindings between remote attachments and local MXC URIs.
• You want to reduce exposure to the files.
  • In most situations (although not mandated by the spec), a remote homeserver will allow you to redirect the media request to somewhere else.
• You want to have some sort of data forgetfulness.
  • Matrix does not delete media attached to a deleted message (at least for now, if MSC3911 will ever be implemented), but many other platforms do. Given that large homeservers likely purge remote media cache regularly, a deleted media will likely be forgotten for large parts of Matrix gradually.

This library creates a media proxy that converts MXC URIs to URLs, so that the homeservers can obtain the file directly from the URL.

WARNING

I need not to explain how an unsecured arbitrary proxy is a bad idea, so the scope of the proxy should be sufficiently restrictive!!!

Usage

import mxcProxy from 'matrix-mxc-proxy';

const port = 8080; // port to listen on
const domain = 'myproxy.example.com'; // name of the "homeserver"
const getUrl = (id: string) => {
    // eg. if a MXC URI is "mxc://myproxy.example.com/abcdefg"
    // then the id is "abcdefg"
    return `https://cdn.example.org/${id}`; // where the file is
    // return null if an URL cannot be determined
};

mxcProxy(port, domain, getUrl);

A reverse proxy for the domain with TLS should forward to the port.

API

There are two endpoints:

GET /.well-known/matrix/server

Returns the domain, plus :443. See Matrix spec.

GET /_matrix/media/v3/download/{serverName}/{mediaId}

See Matrix spec. Regarding this implementation:

• The serverName MUST be the same domain as where the proxy is reachable at. Otherwise, error code ME.AUSTINHUANG.MXC_PROXY.NOT_SUPPORTED will be thrown with status code 403.
• Given the specified getUrl function, if getUrl(mediaId) returns null, error code ME.AUSTINHUANG.MXC_PROXY.CANNOT_CONVERT will be thrown with status code 400.
• The allow_redirect query parameter is respected. If true, a 308 redirect to the output of getUrl(mediaId) will be given. Otherwise, the file will be proxied which, if failed, will throw error code ME.AUSTINHUANG.MXC_PROXY.PROXY_ERROR with status code 504.
• The allow_remote query parameter is ignored; the server acts as if it is always false, given its purpose, as well as expected homeserver behaviour.
• The timeout_ms query parameter is respected as specified.