MSC3316: Add timestamp massaging to the spec

proposals/3316-appservice-timestamp-massaging.md

@@ -0,0 +1,51 @@
+# Proposal to add timestamp massaging to the spec
+Bridges often want to override message timestamps to preserve the timestamps from
+the remote network. The spec used to have a concept of [timestamp massaging], but
+it was excluded from the release due to not being properly specified. Synapse
+still implements it and it is widely used in bridges.
+
+[MSC2716] was originally going to add timestamp massaging to the spec, but it
+pivoted to focusing solely on batch sending history. This MSC simply copies the
+proposed `ts` query param from the [original MSC2716].
+
+[timestamp massaging]: https://matrix.org/docs/spec/application_service/r0.1.2#timestamp-massaging
+[MSC2716]: https://github.com/matrix-org/matrix-doc/pull/2716
+[original MSC2716]: https://github.com/matrix-org/matrix-doc/blob/94514392b118dfae8ee6840b13b83d2f8ce8fcfc/proposals/2716-importing-history-into-existing-rooms.md
+
+## Proposal
+As per the original version of MSC2716:
+
+> We let the AS API override ('massage') the `origin_server_ts` timestamp
+> applied to sent events. We do this by adding a `ts` querystring parameter on
+> the `PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}`
+> and `PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}`
+> endpoints, specifying the value to apply to `origin_server_ts` on the event
+> (UNIX epoch milliseconds).
+>
+> 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.
+
+The spec should also make it clear that the `ts` query param won't affect DAG
+ordering, and MSC2716's batch sending should be used when the intention is to
+insert history somewhere else than the end of the room.
+
+## Potential issues
+None.
+
+## Alternatives
+The new MSC2716 could technically be considered an alternative, but it can only
+be used for history, while this proposal also supports overriding timestamps of
+new messages. In practice, bridges will likely use both: Batch sending for
+filling history and timestamp massaging for new messages.
+
+## 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
+`org.matrix.msc3316.ts` may be used as the query parameter. However, the `ts`
+parameter is already used in production for the `/send` endpoint, which means
+the unstable prefix should only be used for the `/state` endpoint.