MSC4352: Customizable HTTPS permalink base URLs via server discovery

[DonPrus]

Summary

This MSC proposes to generalize HTTPS permalinks by introducing a generic Matrix link resolver (drop-in replacement for matrix.to) and a standardized way for clients to discover a resolver base URL via /.well-known/matrix/client. This enables organizations to use branded resolver domains while keeping the existing matrix.to path/query grammar intact.

Motivation

• Spec currently hardcodes matrix.to in the "matrix.to navigation" section, making custom resolvers non-standard.
• The matrix: URI scheme is standard, but HTTPS permalinks are still required for email/web contexts.
• Fragmentation already exists (Element permalinkPrefix, Synapse client_base_url) without a protocol-level knob.

What this MSC introduces

• A resolver-agnostic concept for HTTPS permalinks (same grammar as matrix.to).
• Discovery precedence: user setting → /.well-known/matrix/client → fallback to https://matrix.to.
• Unstable key: org.matrix.msc4352.permalink_base_url → Stable key: m.permalink_base_url.

File

• proposals/4352-customizable-permalink-base-url.md (this PR assigns the MSC number)

References

• Spec process & how MSC IDs / filenames work; proposal template & checklist.
• Spec: matrix: URI scheme and matrix.to navigation (Appendices/URIs).
• Prior art in the ecosystem:
  • Element Web permalinkPrefix (docs/historical config.md)
  • Synapse client_base_url for emails (notification links defaulting to https://matrix.to)

Rendered Markdown

Rendered: proposals/4352-customizable-permalink-base-url.md

• Client (qualifying): iamb — discovery of org.matrix.msc4352.permalink_base_url,
  :permalink for outside-of-Matrix sharing, and automatic linkify to matrix: URIs on send.
  Tracking PR: MSC4352 (unstable): discover org.matrix.msc4352.permalink_base_url; share via :permalink; linkify resolver HTTPS to matrix: on send ulyssa/iamb#512

Author

Author: @DonPrus
idea : element-hq/element-meta#2399

[tulir]

Implementation requirements:

• Client

[tulir]

Please wrap lines to ~120 characters

[tulir]

This part sounds suspicious. Does the MSC suggest that custom permalink prefixes should be used in-app too instead of only outside the app? If so, how would a client on another homeserver detect that it's a matrix.to-equivalent link?

Element web used to have (or still has? not sure, I hope it was fixed) a bug/anti-feature where permalinkPrefix was applied in @mentions and such in messages too. The result was that mentions, room links and other permalinks were broken for everyone on other clients. I'd be strongly opposed to codifying such a broken feature in the spec.

Even if it's not intended to be used in-app, if a "share" button gives out such links, there's a risk users will send them in-app, leading to worse UX for everyone on other servers (because the app wouldn't be able to route the links internally). If the spec wants to standardize allowing custom links, it might also need to mandate some kind of automatic conversion to matrix: URIs when sending such links in-app. For example, when the user sends https://custom.permalink.to/#/#room:example.com, the client could linkify it before sending and produce <a href="matrix:r/room:example.com">https://custom.permalink.to/#/#room:example.com</a>, which would work in all clients

[DonPrus]

Thanks for the detailed feedback — I fully agree with the risks. MSC4352 does not intend to use a custom HTTPS
resolver for in‑app navigation. The goal is only to generate shareable links for outside‑Matrix contexts
(email/social/other messengers/etc.), while matrix: URIs remain the in‑app priority.

To remove ambiguity, here are normative clarifications I propose to add:

1. In‑app usage (normative):
   Clients MUST NOT use a resolver-based HTTPS permalink for in‑app links (mentions, room/event links,
   or any navigation shown to Matrix users).
   Clients MUST prefer the matrix: URI scheme (or native navigation) for all in‑app UX.
2. Sending links in Matrix (normative):
   If a user pastes a https:///#/[/][?...] link, the client SHOULD keep the visible text but
   MUST emit a link whose href is the equivalent matrix: URI in formatted_body, so it works in all clients.
   The plain‑text body may keep the original text; clickability is provided by formatted_body.
   No network calls to the resolver are needed, and no domain is imposed on other clients.
3. Receiving (non‑breaking):
   Clients MUST support matrix: URIs.
   Clients MAY additionally recognise HTTPS permalinks that match the matrix.to navigation grammar regardless of
   hostname, but this is not required by MSC4352.
   This means MSC4352 does not require clients to parse arbitrary domains; matrix: URIs provide the compatibility path.
4. Editorial tweak to “Generation algorithm”:
   State that the algorithm applies to share/copy for outside‑Matrix contexts, not in‑app navigation.
   Add an explicit preference for matrix: URIs for any in‑app scenarios.

If the MUST/SHOULD/MAY wording looks reasonable, I can update the MSC

[famfo]

The goal is only to generate shareable links for outside‑Matrix contexts
(email/social/other messengers/etc.), while matrix: URIs remain the in‑app priority.

What are the requirements for a web service? Should it be something like the matrix.to server hosted alongside a homeserver?

Why another URI scheme (which will inevitably suffer from linkrot when homeservers disappear again)? The Matrix URI is both a registered URI scheme with the iana and is a safelisted schema for HTML5, so it can be used outside of Matrix clients already. Wouldn't it preferable to improve client support for the matrix URI scheme to not have the centralization around resolver servers while still having the trust of "this is an official URI scheme my client understands"?