diff --git a/proposals/3998-join-timestamp-massaging.md b/proposals/3998-join-timestamp-massaging.md new file mode 100644 index 00000000000..2b41440e231 --- /dev/null +++ b/proposals/3998-join-timestamp-massaging.md @@ -0,0 +1,106 @@ +# MSC3998: Add timestamp massaging to `/join` and `/knock` + +As mentioned in the original +[MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316) for timestamp +massaging, + +> We consciously don't support the `ts` parameter on the various helper +> syntactic-sugar APIs like `/kick` and `/ban`. If a bridge/bot is smart enough to +> be faking history, it is already in the business of dealing with raw events, +> and should not be using the syntactic sugar APIs. + +While it's possible to mimic a join/invite/knock for a room that the server already +knows about, this falls apart for a federated action for a room that the server doesn't +know about since it's not possible to specify any `via` servers with the `/state` +endpoint. Currently, if you try with Synapse, it will throw a `404` with the following +error response body: + +```json +{ + "errcode": "M_UNKNOWN", + "error": "Can't join remote room because no servers that are in the room have been provided." +} +``` + +When writing end-to-end tests, it's useful to have your room appear as though it was +created back in time before your messages were sent and to have stable/consistent +timestamps. If you start using timestamp massaging when sending messages, it can appear +as though those events occurred before the `m.room.member` events used to join federated +rooms. We specifically run into this with the [Matrix Public +Archive](https://github.com/matrix-org/matrix-public-archive/) end-to-end tests. + +In real-life scenarios, practically, this hasn't mattered much for content because the +DAG is ordered topologically and not by timestamp but is a semantic inconsistency that +is becoming more important with API's like `/timestamp_to_event` which find events by +their `origin_server_ts`. And makes things tricky for the Matrix Public Archive to +navigate history by date seamlessly assuming good intentions. + + +## Proposal + +Add timestamp massaging to the `/join` and `/knock` endpoints to be able to override the +`origin_server_ts` of sent events. We do this by adding a `ts` querystring parameter +that specifies the value to apply to `origin_server_ts` on the event (UNIX epoch +milliseconds). + + - `POST /_matrix/client/v3/join/{roomId}?ts=123` + - `POST /_matrix/client/v3/knock/{roomIdOrAlias}?ts=123` + +This functionality is restricted to the application service (AS) API to be consistent +with [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). There +could be future considerations to opening this up to any client as it's kinda arbitrary +to restrict it this way and just seems like friction to try to get only people with good +intentions using it. + +--- + +Also related: [MSC3997](https://github.com/matrix-org/matrix-spec-proposals/pull/3997) +proposes adding a `ts` querystring parameter to the `/createRoom` endpoint but for +different reasons. + + +## Potential issues + +*None surmised so far* + + +## Alternatives + +We could alternatively add `via` server parameters to the `/send` and `/state` endpoints +so the server knows how to find the room in question. + + +## Security considerations + +Timestamps should already be considered untrusted over federation, and application +services are trusted server components, so allowing appservices to override timestamps +does not create any new security considerations. + + +## Unstable prefix + +While this feature is in development, the `ts` querystring parameter can be used as +`org.matrix.msc3998.ts` + +### While the MSC is unstable + +During this period, to detect server support clients should check for the presence of +the `org.matrix.msc3998` flag in `unstable_features` on `/versions`. Clients are also +required to use the unstable prefixes (see [unstable prefix](#unstable-prefix)) during +this time. + +### Once the MSC is merged but not in a spec version + +Once this MSC is merged, but is not yet part of the spec, clients should rely on the +presence of the `org.matrix.msc3998.stable` flag in `unstable_features` to determine +server support. If the flag is present, clients are required to use stable prefixes (see +[unstable prefix](#unstable-prefix)). + +### Once the MSC is in a spec version + +Once this MSC becomes a part of a spec version, clients should rely on the presence of +the spec version, that supports the MSC, in `versions` on `/versions`, to determine +support. Servers are encouraged to keep the `org.matrix.msc3998.stable` flag around for +a reasonable amount of time to help smooth over the transition for clients. "Reasonable" +is intentionally left as an implementation detail, however the MSC process currently +recommends *at most* 2 months from the date of spec release.