From c796f3528004d292298486c3959cef9e9ee625ab Mon Sep 17 00:00:00 2001 From: Hagen Echzell Date: Mon, 22 Jun 2026 15:33:31 +0200 Subject: [PATCH 1/4] Spec for MSC4402: Consistent redirects for .well-known-files Signed-off-by: Hagen Echzell --- content/client-server-api/_index.md | 4 +++- data/api/client-server/wellknown.yaml | 7 ++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index ed7e1e9f..c97b1b37 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -429,6 +429,7 @@ Instead, they can be reached via HTTPS on the [server name](/appendices/#server- Servers hosting the `.well-known` JSON file SHOULD offer CORS headers, as per the [CORS](#web-browser-clients) section in this specification. +Servers SHOULD also ensure that each 30x redirect, if any, offers such CORS headers. {{% /boxes/note %}} The flow for auto-discovery is as follows: @@ -436,7 +437,8 @@ The flow for auto-discovery is as follows: 1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the Matrix ID at the first colon. 2. Extract the hostname from the server name as described by the [grammar](/appendices/#server-name). -3. Make a GET request to `https://hostname/.well-known/matrix/client`. +3. Make a GET request to `https://hostname/.well-known/matrix/client`. 30x redirects should be followed, + however redirection loops should be avoided. 1. If the returned status code is 404, then `IGNORE`. 2. If the returned status code is not 200, or the response body is empty, then `FAIL_PROMPT`. diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 4e2383bf..028d5d63 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -1,4 +1,5 @@ # Copyright 2018 New Vector Ltd +# Copyright 2026 Hagen Echzell # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -20,7 +21,11 @@ paths: get: summary: Gets Matrix server discovery information about the domain. description: |- - Gets discovery information about the domain. The file may include + Gets discovery information about the domain. Clients should follow 30x + redirects, carefully avoiding redirect loops, and use normal X.509 + certificate validation. + + The file may include additional keys, which MUST follow the Java package naming convention, e.g. `com.example.myapp.property`. This ensures property names are suitably namespaced for each application and reduces the risk of From 2a8064172ce8476a9512ea49422641178a117bad Mon Sep 17 00:00:00 2001 From: Hagen Echzell Date: Tue, 23 Jun 2026 10:55:49 +0200 Subject: [PATCH 2/4] Add changelog file Signed-off-by: Hagen Echzell --- changelogs/client_server/newsfragments/2404.breaking | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2404.breaking diff --git a/changelogs/client_server/newsfragments/2404.breaking b/changelogs/client_server/newsfragments/2404.breaking new file mode 100644 index 00000000..c65e396b --- /dev/null +++ b/changelogs/client_server/newsfragments/2404.breaking @@ -0,0 +1 @@ +Clients are now supposed to follow 30x redirects from `/.well-known/matrix/client` as per [MSC4402](https://github.com/matrix-org/matrix-spec-proposals/pull/4402). \ No newline at end of file From 60df211b7a38f66c75bf65d6ff761df409a35eda Mon Sep 17 00:00:00 2001 From: Hagen Echzell Date: Thu, 25 Jun 2026 15:52:20 +0200 Subject: [PATCH 3/4] Indicate spec version for changes Signed-off-by: Hagen Echzell --- content/client-server-api/_index.md | 6 +++--- data/api/client-server/wellknown.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c97b1b37..a9231b28 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -429,7 +429,7 @@ Instead, they can be reached via HTTPS on the [server name](/appendices/#server- Servers hosting the `.well-known` JSON file SHOULD offer CORS headers, as per the [CORS](#web-browser-clients) section in this specification. -Servers SHOULD also ensure that each 30x redirect, if any, offers such CORS headers. +{{% added-in v="1.19" %}} Servers SHOULD also ensure that each 30x redirect, if any, offers such CORS headers. {{% /boxes/note %}} The flow for auto-discovery is as follows: @@ -437,8 +437,8 @@ The flow for auto-discovery is as follows: 1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the Matrix ID at the first colon. 2. Extract the hostname from the server name as described by the [grammar](/appendices/#server-name). -3. Make a GET request to `https://hostname/.well-known/matrix/client`. 30x redirects should be followed, - however redirection loops should be avoided. +3. Make a GET request to `https://hostname/.well-known/matrix/client`. + {{% added-in v="1.19" %}} 30x redirects should be followed, however redirection loops should be avoided. 1. If the returned status code is 404, then `IGNORE`. 2. If the returned status code is not 200, or the response body is empty, then `FAIL_PROMPT`. diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 028d5d63..82cc5130 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -21,9 +21,9 @@ paths: get: summary: Gets Matrix server discovery information about the domain. description: |- - Gets discovery information about the domain. Clients should follow 30x - redirects, carefully avoiding redirect loops, and use normal X.509 - certificate validation. + Gets discovery information about the domain. + {{% added-in v="1.19" %}} Clients should follow 30x redirects, carefully + avoiding redirect loops, and use normal X.509 certificate validation. The file may include additional keys, which MUST follow the Java package naming convention, From f33aaa1be4fc6f1356eca29f9ca1d9e7b7b4e83b Mon Sep 17 00:00:00 2001 From: Hagen Echzell Date: Thu, 25 Jun 2026 15:54:14 +0200 Subject: [PATCH 4/4] Capitalize some `should`s Signed-off-by: Hagen Echzell --- content/client-server-api/_index.md | 2 +- data/api/client-server/wellknown.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index a9231b28..5b24fcc1 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -438,7 +438,7 @@ The flow for auto-discovery is as follows: Matrix ID at the first colon. 2. Extract the hostname from the server name as described by the [grammar](/appendices/#server-name). 3. Make a GET request to `https://hostname/.well-known/matrix/client`. - {{% added-in v="1.19" %}} 30x redirects should be followed, however redirection loops should be avoided. + {{% added-in v="1.19" %}} 30x redirects SHOULD be followed, however redirection loops should be avoided. 1. If the returned status code is 404, then `IGNORE`. 2. If the returned status code is not 200, or the response body is empty, then `FAIL_PROMPT`. diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 82cc5130..2bc695d3 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -22,7 +22,7 @@ paths: summary: Gets Matrix server discovery information about the domain. description: |- Gets discovery information about the domain. - {{% added-in v="1.19" %}} Clients should follow 30x redirects, carefully + {{% added-in v="1.19" %}} Clients SHOULD follow 30x redirects, carefully avoiding redirect loops, and use normal X.509 certificate validation. The file may include