diff --git a/proposals/4481-matrix.to-encoding.md b/proposals/4481-matrix.to-encoding.md new file mode 100644 index 00000000000..891f170a2e4 --- /dev/null +++ b/proposals/4481-matrix.to-encoding.md @@ -0,0 +1,78 @@ +# MSC4481: Use Matrix URI-style type segments in matrix.to + +The spec defines [matrix.to navigation](https://spec.matrix.org/v1.18/appendices/#matrixto-navigation) NOT as a service +on the web, but instead as a namespace URI piggybacking on the `https:` scheme before the `matrix:` scheme was +registered. +The intention is to have a clearly defined format to link to Matrix room aliases, room IDs, messages within rooms, and +user IDs. Clients are supposed to parse and handle this format internally to navigate between the aforementioned Matrix +entities similarly to links between pages on the web. + +Since it is based on HTTP URLs, the spec explicitly defines matrix.to as based on RFC 3986, including URL encoding. +For the purpose of this MSC, note this applies particularly to the special characters ("sigils" of the [different types +of Matrix IDs](https://spec.matrix.org/latest/appendices/#common-identifier-format)) in the URL fragment. +At the same time, the spec recommends clients also support matrix.to URLs "which are not fully encoded" for +compatibility to the more "human readable form" that some clients produced historically and continue to do today. +This includes the web service provided by the Foundation, which coincidentally sits at and can +resolve URLs in the matrix.to shape as a kind of fallback functionality on the web. + +Besides being technically incorrect, the unencoded fragments are known to cause practical issues, which are documented +and discussed across numerous issues in the ecosystem: + +- +- +- + +Issues commonly center around URI parsing libraries failing to interpret URLs as intended by the user sharing links +outside of Matrix due to incorrect encoding. This is particularly prevalent where the `#` character has another assigned +meaning, such as across most social media. For example, the Foundation's own YouTube video descriptions used to +unwittingly contain improperly encoded matrix.to links copied from common client implementations, which broke when +YouTube introduced hashtags to the platform, including a parser that prefers to detect the second `#` as start of a +hashtag rather than the technically incorrect contents of the URL fragment. + +## Proposal + +The spec also defines the Matrix URI scheme , +which uses a different format to differentiate between the different types of ID: + +- `#` -> `r/` +- `!` -> `roomid/` +- `$` -> `e/` +- `@` -> `u/` + +This MSC proposes to deprecate the current use of sigils in matrix.to's fragment, entirely eliminating the question +around encoding. Instead, the same `type` `segment-nz` as defined for `matrix:` (see the list above) SHALL be used. + +For example: + +- +- +- +- + +Additionally, clients are advised to continue to support parsing the now-deprecated format using URL percent encoding as +well as incompletely encoded fragments for backwards compatibility. Clients SHOULD further prefer the new format over +the now-deprecated format when generating such URLs fully automatically, and reasonably convert URLs in the +now-deprecated format to the new format under circumstances not undermining user intention, e.g. when auto-completing. +It would generally be reasonable for clients to handle matrix.to URLs they cannot interpret correctly as regular HTTP +URLs instead, so users automatically fall back to the web service, regardless of its official +relationship regarding the spec. + +## Potential issues + +Needs to be implemented in first to ensure fallback support. + +## Alternatives + +Disallowing unencoded matrix.to URLs. + +## Security considerations + +None known. + +## Unstable prefix + +Not needed. + +## Dependencies + +Needs to be implemented in first.