matrix-spec-proposals/proposals/3442-move-prev-content.md

MSC3442: move the prev_content key to unsigned

Background: the Client-Server API specification documents a prev_content property to be included on state events. It gives the content of the previous state event with the same type and state_key.

This property does not form part of the "raw" event as sent to federating homeservers via the Server-Server API; it is added to events served over the Client-Server API as a service to those clients.

Adding properties at the top level of the event in this way is confusing: it makes it difficult to understand which properties are part of the raw event, and which added retrospectively.

It is also inconsistent with other properties which are added by the local homeserver such as age, redacted_because and transaction_id, which are returned under unsigned: see https://matrix.org/docs/spec/client_server/r0.6.1#room-event-fields.

Further background information

1. The specification for the GET /_matrix/client/r0/notifications API is unusual in that it requires prev_content to be returned under unsigned.

2. In general, in addition to returning prev_content at the top level as specified, Synapse also returns it under unsigned, as proposed here.

   The exceptions to this are GET /notifications and GET /sync, where Synapse returns prev_content only under unsigned. As noted above, this is compliant with the spec for /notifications, but appears to be a spec violation for /sync.

3. Dendrite returns prev_content only under unsigned (and is therefore theoretically in violation of the spec).

Proposal

It is proposed that the specification be updated to move the prev_content property to the unsigned object, bringing it in line with age, redacted_because and transaction_id.

This will affect:

• Events returned by the Client-Server API.
• Events sent to Application Services by the Application Services API.

Potential issues

The proposed change may break compatibility with existing clients and Application Services.

In practice, any client supporting Dendrite or /sync requests via Synapse must already support the new location, so this is not a breaking change for such clients. There may be Application Services which rely on prev_content at the top level; however these can be safely updated to use the new location, since Synapse populates both locations.

The problem can be further mitigated by homeservers populating the key at both locations for as long as they support older versions of the specification, as Synapse does today.

Alternatives

1. We could double-down on the existing situation and require that prev_content always be populated at the top level (possibly including /notifications). That is unattractive for the reasons set out in the introduction to this proposal. Furthermore, in practice it will introduce more compatibility problems, due to the implementations which currently do not comply with the spec.

2. We could require that homeservers populate the property at both locations. However, setting aside the added complexity for homeserver implementations, it also increases the chances of a situation as follows:

   • Some clients use one property, some use another.
   • A homeserver developer tests against a subset of clients, all of which use one property.
   • In consequence, some clients are incompatible with some homeservers.

Security considerations

When an event is sent over federation, the sending homeserver can freely add properties to the unsigned object, without them being covered by the hashes or signatures. Some homeserver implementations (including Synapse) will then pass any such properties on to clients and application services.

In principle then, a malicious or buggy homeserver implementation could add an incorrect prev_content property under unsigned, and send it over federation. A receiving homeserver, implementing the current specification, might pass that property straight through to a client, and the receiving client would be unable to tell that it was actually incorrectly populated by the remote homeserver.

This is a more general problem that exists today, and which requires a more general solution to unsigned objects - see https://github.com/matrix-org/synapse/issues/11080. This proposal does not materially affect the problem.

Unstable prefix

No unstable prefix is required, since the behaviour proposed is already implemented by both Synapse and Dendrite.