MSC4383: Client-Server Discovery of Server Version

Author: jevolk

proposals/4383-client-server-info.md

@@ -0,0 +1,74 @@
+# MSC4383: Client-Server Discovery of Server Version
+
+### Proposal
+
+An object is added to the top-level of `GET /_matrix/client/versions`[^1] named `server` with
+parity to the eponymous object returned by `GET /_matrix/federation/v1/version`[^2].
+
+Example of the `server` object:
+
+```
+  "server": {
+    "name": "My_Homeserver_Implementation",
+    "version": "ArbitraryVersionNumber"
+  }
+```
+
+Example of a full response:
+```
+{
+  "server": {
+    "name": "My_Homeserver_Implementation",
+    "version": "ArbitraryVersionNumber"
+  },
+  "unstable_features": {
+    "org.example.my_feature": true
+  },
+  "versions": [
+    "r0.0.1",
+    "v1.1"
+  ]
+}
+```
+
+### Alternatives
+
+The status quo requires a client to query the federation version endpoint. It is the only known
+example of a cross-boundary request to have any use[^5] to an implementation[^3], motivating
+this proposal to reestablish a clean partition. This status quo alternative is problematic: the
+partition in the `/_matrix` URL hierarchy is understood by site-administrators to allow for distinct
+middleware configurations. Sites commonly employ WAF rules covering the client and federation
+hierarchies with source and destination assumptions. Some sites disable the entire federation
+portion, rendering the status quo as unreliable.
+
+MSC2301[^4] enriches the discovery information, including some identifying information about the
+server, though specific formal vendor and semantic version information appears avoided
+(see: potential issues).
+
+### Potential Issues
+
+Server vendor and version information has been considered counter-productive to the motivations
+of Matrix as a unifying communication standard. Matrix believes any use of implementation
+knowledge as a condition in its applications always represents an accidental failure of its
+implementations or the standard binding them; the solution to such problems is thus found in
+cooperation, community and conformity, precluding the need for bug-for-bug conditions and
+workarounds. This MSC has the option of including a normative statement which inhibits the use
+of vendor information to determine functionality.
+
+### Security Concerns
+
+The federation endpoint is the only location which presently reveals this information.
+Site-administrators which have taken some measure to hide, or obscure, or modify it (i.e. with a
+proxy) will have to note their implementation's new exposure of it when upgrading.
+
+
+[^1]: https://spec.matrix.org/v1.16/client-server-api/#api-versions
+
+[^2]: https://spec.matrix.org/v1.16/server-server-api/#server-implementation
+
+[^3]: https://github.com/matrix-org/matrix-rust-sdk/blob/d228bde8ef51a98da10a6b7d4b9f3e5b8f49ad3c/crates/matrix-sdk/src/client/mod.rs#L581-L616
+
+[^4]: https://github.com/matrix-org/matrix-spec-proposals/pull/2301
+
+[^5]: Server version information can provide useful context in logs and may be essential for
+effective crash reports.