Introduce new 'withheld' code for unshared sessions

proposals/4268-encrypted-history-sharing.md

@@ -45,7 +45,7 @@ The keys are assembled into a JSON object with the following structure:
   "withheld": [
     {
       "algorithm": "m.megolm.v1.aes-sha2",
-      "code": "m.unauthorised",
+      "code": "m.history_not_shared",
       "reason": "History not shared",
       "room_id": "!Cuyf34gef24t:localhost",
       "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
@@ -72,8 +72,9 @@ The properties in the object are defined as:
 
  * `withheld`: an array of objects with the same format as the content of an
    [`m.room_key.withheld`](https://spec.matrix.org/v1.14/client-server-api/#mroom_keywithheld)
-   message, usually with code `m.unauthorised` to indicate that the recipient
-   isn't allowed to receive the key.
+   message, usually with code `m.history_not_shared` (see
+   [below](#new-withheld-code)) to indicate that the recipient isn't allowed to
+   receive the key.
 
 A single session MUST NOT appear in both the `room_keys` and `withheld` sections.
 
@@ -219,6 +220,44 @@ For example:
 In all cases, an absent or non-boolean `shared_history` property is treated the same as
 `shared_history: false`.
 
+### New "withheld" code
+
+The spec currently
+[defines](https://spec.matrix.org/v1.14/client-server-api/#mroom_keywithheld) a
+number of "withheld" codes which are used to indicate that a client is
+deliberately *not* sharing a megolm session key with another. Normally these
+codes are used in `m.room_key.withheld` to-device events; as the text above
+specifies, we will now also use them in the `withheld` section of the room key bundle.
+
+This MSC proposes the addition of a new withheld code, `m.history_not_shared`,
+which is used specifically to indicate that the megolm session in question does not
+have the `shared_history` flag set (which means that the creator of that
+session believed that the room history visibility did not allow new members to
+access history).
+
+* Aside: the spec currently contains a definition for a `withheld` code
+  `m.unauthorised`. However, its semantics are unclear: the spec defines it as
+  meaning "the user/device is not allowed to have the key", but is unclear
+  about why this might happen. (Arguably, `m.blacklisted` and `m.unverified`
+  are also cases of "the user/device is not allowed to have the key".)
+
+  In practice, modern Element clients (including Element Web and the classic
+  mobile clients, since the port to the Rust crypto stack), do not send this
+  withheld code at all. Further, the example given in the spec, "the
+  user/device was not in the room when the original message was sent", is
+  somewhat similar to this usecase.
+
+  It is therefore somewhat tempting to repurpose `m.unauthorised` to suit this
+  usecase. However, `m.unauthorised` has been used for other purposes in the
+  past (for example, [Element Android
+  Classic](https://github.com/element-hq/element-android/blob/v1.6.5/matrix-sdk-android/src/kotlinCrypto/java/org/matrix/android/sdk/internal/crypto/IncomingKeyRequestManager.kt#L276)
+  used to use it as a general-purpose refusal to respond to key requests from
+  other users), and we have little insight as to how `m.unauthorised` might be
+  used in non-Element clients.
+
+  In short, a new code is likely to cause less confusion than repurposing
+  `m.unauthorised`,
+
 ### Actions as a receiving client
 
 When Bob's client receives an `m.room_key_bundle` event from Alice, there are two possibilities:
@@ -307,8 +346,9 @@ Until this MSC is accepted, the following identifiers should be used:
    property in `BackedUpSessionData` and `ExportedSessionData` indicating that
    the key can be shared with new members.
 
+ * `io.element.msc4268.history_not_shared` instead of `m.history_not_shared` as
+   the withheld code for sessions which are not marked as `shared_history`.
 
 ## Dependencies
 
 This MSC depends on [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147), which has recently been accepted into the spec.
-