diff --git a/proposals/4383-client-server-info.md b/proposals/4383-client-server-info.md new file mode 100644 index 00000000000..5ef8cf693aa --- /dev/null +++ b/proposals/4383-client-server-info.md @@ -0,0 +1,91 @@ +# MSC4383: Client-Server Discovery of Server Version + +### Motivation + +Client applications utilizing the Matrix SDK[^6], a Client-Server[^7] library, have been observed +making requests to `GET /_matrix/federation/v1/version`[^2]. It is the only known example of a +cross-interface request made by an implementation[^3]. The purpose is valid: informing logs +used for crash reports of the server specifics; often essential for efficient triage and robust +patching of client software. This proposal reestablises the proper partition between client and +federation interfaces while retaining the value added by the de facto misuse. + +Such cross-interface requests are 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. + +This proposal reestablishes the partition between client-server and server-server by simply offering +the same version data over both. With the adoption of this proposal, no need for cross-interface +requests will be known to remain. + +### 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" + ] +} +``` + +##### Unstable prefix + +| Stable identifier | Purpose | Unstable identifier | +| --- | --- | ---| +| `server` | Server information | `net.zemos.msc4383.server` | + +### Alternatives + +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 + +[^6]: https://github.com/matrix-org/matrix-rust-sdk + +[^7]: https://spec.matrix.org/v1.16/client-server-api/