matrix_sdk/encryption/recovery/types.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
// Copyright 2023 The Matrix.org Foundation C.I.C.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
use matrix_sdk_base::crypto::store::RoomKeyCounts;
use ruma::{
events::{EventContent, GlobalAccountDataEventType},
exports::ruma_macros::EventContent,
};
use serde::{Deserialize, Serialize};
use thiserror::Error;
use zeroize::{Zeroize, ZeroizeOnDrop};
#[cfg(doc)]
use crate::encryption::{
backups::Backups,
recovery::{futures::Enable, Recovery},
};
/// Result type alias for the [`Recovery`] subsystem.
pub type Result<A, E = RecoveryError> = std::result::Result<A, E>;
/// Error type for the [`Recovery`] subsystem.
#[derive(Debug, Error)]
pub enum RecoveryError {
/// A backup already exists on the homeserver, the recovery subsystem does
/// not allow backups to be overwritten, disable recovery first.
#[error(
"A backup already exists on the homeserver and the method does not allow to overwrite it"
)]
BackupExistsOnServer,
/// A typical SDK error.
#[error(transparent)]
Sdk(#[from] crate::Error),
/// Error in the secret storage subsystem.
#[error(transparent)]
SecretStorage(#[from] crate::encryption::secret_storage::SecretStorageError),
}
/// Enum describing the states the [`Recovery::enable()`] method can be in.
#[derive(Debug, Default, Clone, Zeroize, ZeroizeOnDrop)]
pub enum EnableProgress {
/// The client is just starting the process of enabling recovery, this is
/// the initial state.
#[default]
Starting,
/// The client is creating a new server-side key backup.
CreatingBackup,
/// The client is creating a new recovery key and uploading all the locally
/// cached secrets to the homeserver.
CreatingRecoveryKey,
/// The client is currently backing up room keys to the server-side key
/// backup. This state may be emitted multiple times until all room keys
/// have been backed up.
#[zeroize(skip)]
BackingUp(RoomKeyCounts),
/// The client encountered an error while trying to upload all room keys to
/// the server-side key backup.
///
/// Not all room keys may have been backed up, the client will try to back
/// them up again at a later point. If you'd like to wait for the backup
/// to finish again you can use the [`Backups::wait_for_steady_state()`]
/// method.
RoomKeyUploadError,
/// Recovery has been successfully enabled, this is the final state.
Done {
/// The newly created recovery key.
// TODO: Can I remove this from here? It seems a bit dumb.
recovery_key: String,
},
}
/// The states the recovery subsystem can be in.
///
/// You can listen on the state of the recovery mechanism using the
/// [`Recovery::state_stream()`] method.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum RecoveryState {
/// We didn't yet inform ourselves about the state of things.
#[default]
Unknown,
/// Secret storage is set up and we have all the secrets locally.
Enabled,
/// No default secret storage key exists or it is disabled explicitly using
/// the account data event.
Disabled,
/// Secret storage is set up but we're missing some secrets.
Incomplete,
}
/// A hack to allow the `m.secret_storage.default_key` event to be "deleted".
///
/// This allows us to set the `m.secret_storage.default_key` event to an empty
/// JSON object, which means that the event will be invalid.
#[derive(Clone, Debug, Default, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "m.secret_storage.default_key", kind = GlobalAccountData)]
pub(super) struct SecretStorageDisabledContent {}
/// A custom global account data event which tells us that a new backup should
/// not be automatically created.
#[derive(Clone, Debug, Default, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "m.org.matrix.custom.backup_disabled", kind = GlobalAccountData)]
pub(super) struct BackupDisabledContent {
pub disabled: bool,
}
impl BackupDisabledContent {
/// Get the event type of the [`BackupDisabledContent`] global account data
/// event.
pub(super) fn event_type() -> GlobalAccountDataEventType {
// This is dumb, there's got to be a better way to get to the event type?
Self { disabled: false }.event_type()
}
}