Matrix Decentralised HTTP Linking: Spec

March 26, 2023

Decentralised linking from the Web (HTTP contexts) to a matrix user or room.

Status: This is a proposed, draft specification for consideration by the matrix development community. This version was initially posted before any discussion or feedback.

Overview and rationale: matrix-decentralised-http-linking-about
The (proposed) specification: matrix-decentralised-http-linking-spec (this document)
Discussion (matrix room): #matrix.to:matrix.org

Abstract

A decentralised Web-to-Matrix linking protocol for the DNS-based types of matrix resource id (@user:server.tld, #room-alias:server.tld).

Principle:

A matrix server may implement and advertise an HTTP(S) end-point that provides a service similar to a self-hosted copy of matrix.to
Clients should use that URL when they generate a link to a room-alias or user on that server. (Note: ‘room-alias’, which is based on DNS authority [^4]; not ‘room-id’ which is out of scope.)
There is a way for a matrix-aware app to recognise and parse such a URL itself, as there is with matrix.to URLs.

Introduction

This specification defines decentralised linking from HTTP contexts to matrix resources such as @user and #room-alias that are based on DNS authority [^4] (clarified later).

For each such resource, this specification defines an HTTP(S) URL in which the authority part is the matrix server-name of the resource identifier.

To resolve such a URL, a client or user in a generic Web/HTTP context will connect directly to the authority responsible for the resource, following standard HTTP linking semantics.

This is in contrast to the use of “public” reception services such as the commonly used matrix.to, where a client or user in a generic Web/HTTP context will connect first to that centralised service and so must rely on the operator of that service for integrity and availability.

Because a client resolves the URL through the DNS domain corresponding to the resource’s matrix server-name, the resolution is decentralised and not dependent on any central/public resource such as matrix.to.

Notes

Authority of a Room-Alias

This specification supports linking to a matrix room-alias. (For room-id, see subsection ‘[Out of Scope]’.)

In matrix, a room-alias is a non-unique pointer to a room, and is mutable: it can be changed to point at a different room, or it be removed. The DNS domain in the server-name part of a room-alias has the authority [^4] over the room-alias: the operator of this domain has control over what the room-alias points to. Linking to a room-alias therefore inherently means we authorise the matrix server named in it to resolve the room-alias to a room. It would be wrong to trust any other authority to do so, without verifying in some way against the correct authority. We can avoid always querying that authority if we cache the result for some (unspecified) period.

Examples

Examples often assume the following matrix server-name:

example.net

Scope

DNS-Authority Resources

This specification defines decentralised linking from HTTP contexts to matrix resources that use DNS authority (user, room-alias).

The following kinds of matrix resource identifier are based on a DNS domain name which acts as the authority [^4] over the resource.

We call any such identifier a DNS-MXID [^3].

@user:server-name — a matrix “user”
#room:server-name — a matrix “room alias”

The identifier grammar, and in particular the server-name part, is defined in the matrix spec. The server-name is commonly a DNS domain name. The wording and examples in this specification generally assume it is a DNS domain name.

Non-DNS Server-Names

The specification can also work with the other defined variants of server-name (an IP address, an optional port number). *(TODO: Refine the specification to clarify use with these variants, and add examples.)*

Out of Scope

This proposal does not intend to define a new method for addressing non-DNS-based identifiers, such as matrix decentralised room-ids (!room-id-hash) and any future non-DNS naming system(s) for users/rooms/spaces.

The matrix room-id (!room-id-hash) is out of scope. Although a :server-name part is sometimes present, it does not act as an authority in this kind of identifier.

Other forms of server-name, or of the whole identifiers, may be defined in future. For example, public-key-based identifiers for p2p-matrix. These are out of scope.

Specification

Reception Service

A matrix server MAY offer its own reception service, by advertising an end-point for it in .well-known/matrix/client (see ‘Well-known Advertisement’ section).

Examples of an advertised end-point:

https://example.net/ https://example.net/to/ https://example.net/contact/ https://example.net/matrix/to/

The first example may suit the case where the main purpose of the domain is as a matrix server. The other examples may better suit the case where the domain is mainly used for other purposes.

The reception service is available on the advertised end-point. It serves a web-app that takes that represents a DNS-based matrix identifier (DNS-MXID) that the user wishes to resolve.

The input is passed to the web-app in the URL “fragment” part, after /#/, as in matrix.to. Unlike with matrix.to, however, there may be no privacy reason to do so.

Examples of a complete URL:

https://our.org/contact/#/@user:our.org https://some-messenger.com/#/#room:some-messenger.com

Note: The functionality so far could be provided by a self-hosted instance of matrix.to.

Server-name suffix is optional for a DNS-MXID that matches this server-name. These two examples mean the same:

https://example.net/to/#/#room https://example.net/to/#/#room:example.net

The no-suffix form is intended to be preferred where humans will read or write the reference.

(TODO: Maybe allow only one form. Don’t allow too much flexibility. KISS.)

Well-known Advertisement

The reception service end-point is available if advertised in https://example.net/.well-known/matrix/client. The advertisement is a key:value pair where the key is (TODO:foo.reception.path?) and the value is the path of the API endpoint. Example:

{
  "foo.reception.path": "/to"
}

The meaning of this example is that the end-point would be at https://example.net/to.

(TODO: specify precisely... path starts with ‘/‘ and ends with no ‘/‘...)

(TODO: perhaps specify a flag that advertises whether server name-suffix is mandatory/optional/forbidden, if we decide more than one form is possible)

Client Behaviour

Generating a Link

For constructing a link to a DNS-MXID, a matrix client SHOULD discover and use the reception service corresponding to the id, if one is advertised. For any other form of matrix id, or if no such service is advertised, the matrix client may use any suitable reception service for constructing the link.

Example: (TODO)

Validating or Displaying a Link

When parsing text that may contain links, a matrix client may wish to recognise, parse and treat specially any URL that is a DNS-MXID link.

Use the following procedure to determine whether a URL is in fact a DNS-MXID link:

parse the URL, extracting at least the domain-part, path-part and fragment-part;
check the fragment-part matches one of the allowed forms (such as /#/@user:server-name or /#/#room:server-name) and its :server-name part matches the URL domain part;
from that URL’s domain, retrieve the well-known advertisement for a reception service (consider caching);
check the URL’s path part matches the path of the advertised reception service.

Following a Link

When asked to follow a URL that may be a DNS-MXID link: a client SHOULD attempt the validation above, and if successful then use any method to resolve the resource from that identifier.

Example: given URL https://example.net/butterfly/#/@user, a client SHOULD fetch https://example.net/.well-known/matrix/client and extract the advertised foo.reception.path field, and if that matches /butterfly then it can assume the URL is indeed a DNS-MXID link to @user:example.net, and use any method to resolve that.

Security Considerations

Privacy concern about confirmation of receipt, if a client pings unknown URLs before the user asks it to. A similar issue to that of “link previews”. Mitigations: Recognising (“pillifying”) links before the user clicks them is entirely optional. A client could parse (“pillify”) all the links where it already recognises the server (cached from previous interactions). For a link it doesn't recognise, it could display it as a generic URL, and only if and when the user clicks on it then check it. Consider also possibilities around server-side processing, like for link previews.
Cross-site scripting (XSS) and similar concerns when a 'reception service' must be hosted on the matrix server-name domain (where another web service might well be running). Note that the 'reception service' need not be complex. One of the benefits of a distributed architecture is each player can run a variant that suits their needs. For a server where the users are in a managed environment (like staff in a business), it could be a simple single-purpose redirector to a particular client. Alternatively in the general case the reception service hosted on the matrix server-name domain could provide a simple redirect, implemented in just a few lines of javascript for example, to a more feature-rich service like matrix.to running on a different domain.

Terminology

DNS-MXID: “DNS-based matrix identifier”: a matrix identifier anchored to a DNS domain name. Includes the identifier forms @user:domain, #room:domain, +space:domain. Does not include the form !room-id:domain (as the domain there is not anchoring the id).

reception service: an HTTP web service that, given a matrix id, helps the user to resolve and access the corresponding resource, such as by opening a matrix client with “deep linking” to the resource. Examples: matrix.to and other instances of the matrix.to software.

References

[MATRIX]: The matrix.org project’s web site has the tag line “An open network for secure, decentralized communication” (emphasis mine). [M.TO-SITE]: The singular matrix.to domain and the web-service it provides. [M.TO-CODE]: The reception service software that runs matrix.to and can also be deployed on other domains. [M.TO-SYNTAX]: The use of matrix.to URLs as a special syntax intended to recognised by matrix-aware software, as specified in [SPEC-TO]. [SPEC-ID]: Matrix spec v1.6: Identifier Grammar [SPEC-URI]: Matrix spec v1.6: Matrix URI scheme [SPEC-TO]: Matrix spec v1.6: matrix.to navigation [^3]: In some other contexts, the term ‘MXID’ may imply only user identifiers. [^4]: The term “authority” is used in the DNS sense of meaning.

TODO:

make and advertise a discussion room
Security Considerations: non-dependence on matrix.to (a positive), spoofing...
add section: Alternatives Considered
event-id (allow as part of #room-id/$event-id; but any :server-name in event-id is not special, same as for a room-id)
initial implementations, and references to them
Seamless opening the link in the user's preferred client is dependent on deferring to an installed client supporting matrix-URI, unless a browser-accessible preference-sharing solution is found that works across different sites. (open question in Overview:Examples)
Add a note: spec [SPEC-ID] is not precise about “authority”, it says things like “server that created the id or resource”.
More about distinguishing room-id from room-alias in client software and user understanding. (Overview doc: “DNS naming”) (Long-standing issue: Permalinks cannot be routed by room ID, and aliases are not permanent. #355)
mention “pills”, the colloquial name for visually distinguishing user/room identifiers, for searchability.

Feedback

For engaging with discussion and development of the topic, please prefer the room linked here, rather than the blog comments facility:

Discussion (matrix room): #matrix.to:matrix.org

Follow/Feedback/Contact: RSS feed · Fedi follow this blog: @julian@wrily.foad.me.uk · use the Cactus Comments box above · matrix me · Fedi follow me · email me · julian.foad.me.uk Donate: via Liberapay All posts © Julian Foad and licensed CC-BY-ND except quotes, translations, or where stated otherwise