Harmonise UTD codes across Web and EX for reporting and user messages

[andybalaam]

We categorise UTDs (unable to decrypt messages) in both Element Web + matrix-js-sdk and Element X + matrix-rust-sdk. In both cases, this categorisation has 2 uses: showing a message to the user, and reporting stats to PostHog.

We should use the same categories and handle them the same on both platforms. This task is to figure out:

• one correct list of enum values that cover all the cases we need,
• one mapping of those enum values to user messages displayed on a timeline item, and
• one mapping of those enum values to PostHog keys to report UTDs

and then to implement those things in PostHog, matrix-js-sdk, matrix-rust-sdk, Element Web, Element X iOS and Element X Android.

As far as possible given the platform constraints, the enum values, localisation keys and posthog keys should be identical on all platforms.

In addition, we should check that what we're doing makes sense, especially when a UTD is UNexpected, but we still understand it. Currently, we seem to be grouping all unexpected UTDs into one category, when it could definitely help us (and maybe the user too) to expose the information we have. For example, a UTD because a message is historical, but our backup is working, so the key should have been found there, is very different from a UTD from a recent message.

Current state: Element Web

The main enum is DecryptionFailureCode:

DecryptionFailureCode
    HISTORICAL_MESSAGE_BACKUP_UNCONFIGURED
    HISTORICAL_MESSAGE_NO_KEY_BACKUP
    HISTORICAL_MESSAGE_USER_NOT_JOINED
    HISTORICAL_MESSAGE_WORKING_BACKUP
    MEGOLM_KEY_WITHHELD
    MEGOLM_KEY_WITHHELD_FOR_UNVERIFIED_DEVICE
    MEGOLM_UNKNOWN_INBOUND_SESSION_ID
    OLM_UNKNOWN_MESSAGE_INDEX
    SENDER_IDENTITY_PREVIOUSLY_VERIFIED
    UNKNOWN_ERROR
    UNKNOWN_SENDER_DEVICE
    UNSIGNED_SENDER_DEVICE

(Plus these deprecated values, only used in legacy crypto: MEGOLM_BAD_ROOM, MEGOLM_MISSING_FIELDS, OLM_DECRYPT_GROUP_MESSAGE_ERROR, OLM_BAD_ENCRYPTED_MESSAGE, OLM_BAD_RECIPIENT, OLM_BAD_RECIPIENT_KEY, OLM_BAD_ROOM, OLM_BAD_SENDER_CHECK_FAILED, OLM_BAD_SENDER, OLM_FORWARDED_MESSAGE, OLM_MISSING_CIPHERTEXT, OLM_NOT_INCLUDED_IN_RECIPIENTS, UNKNOWN_ENCRYPTION_ALGORITHM.)

We interpret these for the user in DecryptionFailureBody.getErrorMessage:

DecryptionFailureReason
    HISTORICAL_MESSAGE_BACKUP_UNCONFIGURED && unverified => historical_event_unverified_device
    HISTORICAL_MESSAGE_NO_KEY_BACKUP => historical_event_no_key_backup
    HISTORICAL_MESSAGE_USER_NOT_JOINED => historical_event_user_not_joined
    MEGOLM_KEY_WITHHELD_FOR_UNVERIFIED_DEVICE => blocked
    SENDER_IDENTITY_PREVIOUSLY_VERIFIED => sender_identity_previously_verified
    UNSIGNED_SENDER_DEVICE => sender_unsigned_device
    else unable_to_decrypt

We report them to PostHog in DecryptionFailureTracker's global instance:

DecryptionFailureReason
    HISTORICAL_MESSAGE_NO_KEY_BACKUP => HISTORICAL_MESSAGE_BACKUP_UNCONFIGURED
    HISTORICAL_MESSAGE_USER_NOT_JOINED => ExpectedDueToMembership
    HISTORICAL_MESSAGE_WORKING_BACKUP => HistoricalMessage
    MEGOLM_KEY_WITHHELD_FOR_UNVERIFIED_DEVICE => RoomKeysWithheldForUnverifiedDevice
    MEGOLM_UNKNOWN_INBOUND_SESSION_ID | MEGOLM_KEY_WITHHELD => OlmKeysNotSentError
    OLM_UNKNOWN_MESSAGE_INDEX => OlmIndexError
    SENDER_IDENTITY_PREVIOUSLY_VERIFIED => ExpectedVerificationViolation
    UNSIGNED_SENDER_DEVICE => ExpectedSentByInsecureDevice
    else UnknownError

Current state: Element X

The main enum is UtdCause:

UtdCause
    HistoricalMessageAndBackupIsDisabled
    HistoricalMessageAndDeviceIsUnverified
    SentBeforeWeJoined
    Unknown
    UnknownDevice
    UnsignedDevice
    VerificationViolation
    WithheldBySender
    WithheldForUnverifiedOrInsecureDevice

On iOS we interpret these for the user in RoomTimelineItemFactory:

UtdCause
    historicalMessage => timelineDecryptionFailureHistoricalEventNoKeyBackup
    sentBeforeWeJoined => commonUnableToDecryptNoAccess
    unknown => commonWaitingForDecryptionKey
    unsignedDevice | unknownDevice => commonUnableToDecryptInsecureDevice
    verificationViolation => commonUnableToDecryptVerificationViolation
    withheldBySender => timelineDecryptionFailureUnableToDecrypt
    withheldForUnverifiedOrInsecureDevice => timelineDecryptionFailureWithheldUnverified

On iOS we report them to PostHog in UserSessionFlowCoordinator.setupObservers:

UtdCause
    historicalMessage => HistoricalMessage
    sentBeforeWeJoined => ExpectedDueToMembership
    unknownDevice => ExpectedSentByInsecureDevice
    unknown => OlmKeysNotSentError
    unsignedDevice => ExpectedSentByInsecureDevice
    verificationViolation => ExpectedVerificationViolation
    withheldBySender => OlmKeysNotSentError
    withheldForUnverifiedOrInsecureDevice => RoomKeysWithheldForUnverifiedDevice

On Android we interpret these for the user in TimelineItemEncryptedView:

UtdCause
    HistoricalMessage => timeline_decryption_failure_historical_event_no_key_backup
    SentBeforeWeJoined => common_unable_to_decrypt_no_access
    UnsignedDevice | UnknownDevice => common_unable_to_decrypt_insecure_device
    VerificationViolation => common_unable_to_decrypt_verification_violation
    WithheldBySender => timeline_decryption_failure_unable_to_decrypt
    WithheldUnverifiedOrInsecureDevice => timeline_decryption_failure_withheld_unverified
    else common_waiting_for_decryption_key

On iOS we report them to PostHog in UtdTracker:

UtdCause
    HISTORICAL_MESSAGE => HistoricalMessage
    SENT_BEFORE_WE_JOINED => ExpectedDueToMembership
    UNKNOWN => OlmKeysNotSentError
    UNSIGNED_DEVICE | UNKNOWN_DEVICE => ExpectedSentByInsecureDevice
    VERIFICATION_VIOLATION => ExpectedVerificationViolation
    WITHHELD_BY_SENDER => Error.Name.OlmKeysNotSentError
    WITHHELD_FOR_UNVERIFIED_OR_INSECURE_DEVICE => RoomKeysWithheldForUnverifiedDevice