Hey all,

We’ve just released the milestone Matrix 1.11 update for the protocol. It’s been almost exactly 3 months since the last release, Matrix 1.10, keeping us on track for our once-a-quarter release schedule.

There are 9 MSCs released in Matrix 1.11 today, but there’s one specific MSC we’d like to draw your attention to: MSC3916 - Authenticated Media. Until today, Matrix had a design flaw which allows a user to access media unauthenticated if they knew the URL. This has been used to share files in social media posts, link images outside of chats, and generally imply that a homeserver is a CDN for the internet. Some of these use cases are legitimate, though many are not. This is fixed with MSC3916.

This post covers MSC3916 and its implementation guidelines in more detail, but the full changelog for Matrix 1.11 is available at the end, as always.

MSC3916: Authenticated Media

The Trust & Safety team has been hard at work fixing the design flaw in media mentioned above, taking MSC3916 under their wing and bringing it to release here. The goal has been to roll out the feature as fast as possible, and that’s culminated in the following plan after consultations with us on the Spec Core Team.

Servers are encouraged to freeze unauthenticated media access (i.e. only allow historical media to be accessed without auth) before Matrix 1.12 is released, which we anticipate will happen in about August 2024. Any media which is cached or uploaded before that freeze will remain accessible on the unauthenticated endpoints indefinitely to avoid breaking existing links in social media, external chats, etc. Media which is cached or uploaded after the freeze takes place will only be accessible through the new authenticated endpoints - callers will receive a 404 error on the unauthenticated side.

The MSC has a bit more detail about the side effects of this approach, and more on the considerations leading to this proposed plan. Implementations might choose to support a config flag to enable/disable the freeze as needed, or simply release a version which freezes unauthenticated media on startup. Either are effective approaches for improving user safety and privacy.

Each homeserver should additionally consider its local ecosystem before freezing unauthenticated media by ensuring bridges and the popular clients among users are ready for authenticated media in particular. Ideally, users should see no visible impact to this change being rolled out. To help encourage this, the matrix.org homeserver will be rolling out authenticated media relatively quickly itself - watch for news on the blog next week for specific timelines.

Client and server developers are encouraged to support authenticated media as soon as they can to help server admins make the switch. Servers have a bit more work to do than clients, unfortunately, but both should have a reasonably easy time adding in the relevant support. The T&S team have made themselves available in #matrix-client-developers:matrix.org and #matrix-homeserver-developers:matrix.org to help developers implement this new feature - feel free to visit the respective room for your project and ask questions.

Below is some implementation guidance for developers, though is not a replacement for the spec. Where this post and the spec differ, please prefer the spec. :)

Client implementation guidance

Thankfully, supporting authenticated media should be relatively trivial for most clients. When the homeserver declares support for Matrix 1.11 through /versions, the client should use the new /_matrix/client/v1/media/* endpoints, noting that they now require authentication. The user’s access token can be supplied using the Authorization header. (Note that using the query string ?access_token method is not recommended, and deprecated in Matrix 1.11 for all endpoints.)

If the server doesn’t support Matrix 1.11, the existing /_matrix/media/* endpoints should continue to be used.

This may end up looking something like the following in a client:

const specVersions = doRequest('GET', '/_matrix/client/versions', accessToken);
if (specVersions.versions.includes("v1.11")) {
	return doRequest('GET', `/_matrix/client/v1/media/download/${serverName}/${mediaId}`, accessToken);
} else {
	return doRequest('GET', `/_matrix/media/v3/download/${serverName}/${mediaId}`, null);
}

Clients which rely on a web browser may have to use a Service Worker to append the required header, particularly for img tags and similar.

Clients should additionally note that, as well as /_matrix/media/v3/download/{serverName}/{mediaId}, the following other endpoints have moved to the /_matrix/client/v1/media/* namespace:

The media /upload, /upload/{serverName}/{mediaId}, and /create endpoints have not yet moved; they are expected to make the switch in a future spec version.

Server implementation guidance

As mentioned above, servers are a bit more tricky. The Client-Server API endpoints are relatively straightforward: they are the exact same as the previous endpoints, just with authentication added and at a new path. The Federation API endpoints are a bit more challenging. Most server projects have already started implementation, but for those which haven’t (or need a bit of guidance), there’s some information here.

Server authors are also encouraged to review the client guidance above to gain a better understanding of what their connected clients will be looking for and doing.

Up next in Matrix 1.12 and beyond

Over the next 2-3 months, we’ll be focusing on the following MSCs:

  • Early review of Matrix 2.0 features as they become ready.
    • Sliding sync - MSC3575, or its Simplified variation, and applicable extensions.
    • Group VoIP - Exact MSCs to be determined, as they may change following implementation.
    • OIDC Authentication - primarily MSC3861.
    • Encryption stability - primarily MSC4153.
  • Pre-implementation review of Trust & Safety MSCs as required.
    • Exact MSCs to be determined. Likely to include some “reporting v2” work.
  • Extensible Events and Custom Emoji/Stickers unblocking as required and able.

Additionally, we’ll be continuing to define the expectations of a Spec Core Team member, particularly as it relates to the Governing Board of the Foundation. This exercise has been extremely valuable to us so far, and will help identify areas the Foundation and SCT may need support from each other.

The full changelog

Read on for full details of what’s in Matrix 1.11:

Client-Server API

Deprecations

  • Authentication using a query string is now deprecated, as per MSC4126. The Authorization header should be used instead. (#1808)
  • Use of the /_matrix/media/* endpoints is now deprecated. New, authenticated, endpoints are available instead. (#1858)

New Endpoints

Backwards Compatible Changes

  • Add support for muting in VoIP calls, as per MSC3291. (#1755)
  • Add optional animated query string option to GET /thumbnail, as per MSC2705. (#1757)
  • Specify terms of services at registration, as per MSC1692. (#1812)
  • Add support for mathematical messages, as per MSC2191. (#1816)
  • Do not require UIA when first uploading cross-signing keys, as per MSC3967. (#1828)
  • Add the new unsigned.membership property to events, as per MSC4115. (#1847)
  • Media downloads and thumbnails are now authenticated, as per MSC3916. (#1858)
  • Some media endpoints are now consistently under /_matrix/client/{version}/media/* instead of /_matrix/media/*, as per MSC3916. (#1858)

Spec Clarifications

  • Add /logout and clarify the endpoints which do not take a JSON request body. (#1644)
  • Clarify that the type of the POST /login request must be one of the types returned by the GET /login response. (#1776)
  • Link to existing grammar where possible in types. (#1813)
  • Rename "recovery key" to "backup decryption key". (#1819)
  • Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). (#1829)
  • Fix various typos throughout the specification. (#1832, #1841, #1852, #1853)
  • Specify the encoding to be used when generating QR codes for device verification. (#1839)
  • Clarify that an access token is optional on the POST /account/password and POST /account/deactivate endpoints. (#1843)
  • Use RFC 2119 keywords more consistently. (#1846, #1861)
  • Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. (#1850)
  • Clarify that relations recursion should be capped at a certain depth. (#1854)
  • Add missing secrets, third-party invites and room tagging modules to feature profiles table. (#1860)
  • Clarify when server name is used and link to the definition. (#1862)
  • Clarify where keys reside when checking an m.room.encrypted event. (#1863)
  • Clarify that /media/v3/upload/{serverName}/{mediaId} requires authentication. (#1872)

Server-Server API

Deprecations

  • Use of the Client-Server API /_matrix/media/* endpoints is now deprecated. New, authenticated, endpoints are available instead. (#1858)

New Endpoints

Backwards Compatible Changes

  • Media downloads and thumbnails are now authenticated, as per MSC3916. (#1858, #1869)

Spec Clarifications

  • Link to existing grammar where possible in types. (#1813)
  • Clarify that whitespace around commas is allowed in the X-Matrix Authorization header value params list. (#1818)
  • Clarify that the event field of the /v2/send_join response is only required when the event is signed by the resident server. (#1834, #1840)
  • Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. (#1844)
  • Fix various typos throughout the specification. (#1877)

Application Service API

Spec Clarifications

  • Clarify that appservices should be notified of events relating to the sender_localpart user. (#1810)

Identity Service API

Deprecations

  • Authentication using a query string is now deprecated, as per MSC4126. The Authorization header should be used instead. (#1808)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

  • Clarify that redaction events are still subject to all applicable auth rules. (#1824)
  • Fix various typos throughout the specification. (#1827, #1848)
  • Fix the rendering of the event format for room versions 1 and 2. (#1883)
  • Generate the Table of Contents with Hugo rather than JavaScript. (#1884)

Appendices

Deprecations

  • Deprecate linking to events in rooms identified by alias, as per MSC4132. (#1823)

Spec Clarifications

  • Define 'Opaque Identifier Grammar'. (#1791)
  • Define common cryptographic key representation. (#1819)
  • Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. (#1850)

Internal Changes/Tooling

Spec Clarifications

  • Update the spec release process and related documentation. (#1759)
  • Fix npm release script for @matrix-org/spec. (#1765)
  • Formatting fixes in CONTRIBUTING.rst. (#1769)
  • Improve rendering on mobile devices. (#1770, #1771)
  • Fix the OpenAPI definition of the security schemes. (#1772)
  • Simplify uses of resolve-refs partial. (#1773)
  • Fix Hugo warnings. (#1775, #1788)
  • Fix github-labels.rst. (#1781)
  • Update dependencies. (#1786, #1803, #1804)
  • Solve allOf recursively in OpenAPI and JSON Schemas. (#1787)
  • Fix property type resolution in render-object-table partial. (#1789)
  • Factor out common definition of Tag type. (#1793)
  • Update the version of Hugo used to render the spec to v0.124.1. (#1794)
  • Add support for pattern formats for patternProperties. (#1796)
  • Clean up unnecessary allOfs in OpenAPI definitions. (#1797)
  • Show information about "Additional Properties" in object tables. (#1798)
  • Fix anchors for schemas under oneOf. (#1799)
  • Use reference to OneTimeKeys schema in OpenAPI definitions. (#1800)
  • Do not use the title of objects containing only additionalProperties or patternProperties. (#1801)
  • Add anchors in definition shortcode. (#1802)
  • Set python version for the Towncrier CI job. (#1805)
  • Replace set-output with environment files in CI. (#1806)
  • Render response headers. (#1809)
  • Use patternProperties in more places with supported formats. (#1813)
  • Add support for rendering string formats. (#1814)
  • Refactor the OpenAPI definitions of the content repository endpoints. (#1822)
  • Clean up pull request template. (#1831)
  • Do not add empty arrays to examples. (#1849)
  • Generate the Table of Contents with Hugo rather than JavaScript. (#1851, #1885)
  • Fix syntax errors in the spec release issue template. (#1856)
  • Use environment variables for Netlify build job. (#1865)
  • Render added/changed in info on request and response content types. (#1876)
  • Fix validation errors in generated HTML. (#1880)
  • Ensure most generated HTML IDs are unique. (#1881)
  • Allow to specify a prefix for generated HTML IDs of API endpoints. (#1882)

The Foundation needs you

The Matrix.org Foundation is a non-profit and only relies on donations to operate. Its core mission is to maintain the Matrix Specification, but it does much more than that.

It maintains the matrix.org homeserver and hosts several bridges for free. It fights for our collective rights to digital privacy and dignity.

Support us