#[non_exhaustive]pub enum DeRecEvent {
Show 33 variants
PairingCompleted {
channel_id: ChannelId,
pairing_channel_id: ChannelId,
kind: SenderKind,
peer_communication_info: HashMap<String, String>,
},
ReplicaPaired {
channel_id: ChannelId,
peer_replica_id: u64,
},
ShareStored {
channel_id: ChannelId,
version: u32,
replica_id: Option<u64>,
},
ReplicaSecretReceived {
channel_id: ChannelId,
from_replica_id: u64,
secret_id: u64,
version: u32,
secret: Secret,
shares: Vec<ChannelShare>,
},
ReplicaSecretAcked {
channel_id: ChannelId,
from_replica_id: u64,
secret_id: u64,
version: u32,
status: i32,
memo: String,
},
ShareConfirmed {
channel_id: ChannelId,
version: u32,
},
ShareRejected {
channel_id: ChannelId,
version: u32,
status: i32,
memo: String,
},
SharingComplete {
version: u32,
confirmed_count: usize,
failed_count: usize,
threshold_met: bool,
},
ShareVerified {
channel_id: ChannelId,
version: u32,
},
SecretsDiscovered {
channel_id: ChannelId,
secrets: Vec<SecretVersionEntry>,
},
RecoveryShareReceived {
channel_id: ChannelId,
shares_received: usize,
},
RecoveryShareError {
channel_id: ChannelId,
shares_received: usize,
error: String,
},
SecretRecovered {
secret: Secret,
},
ActionRequired {
channel_id: ChannelId,
action: PendingAction,
},
AutoAccepted {
channel_id: ChannelId,
action_kind: PendingActionKind,
},
Unpaired {
channel_id: ChannelId,
},
UnpairRejected {
channel_id: ChannelId,
status: i32,
memo: String,
},
PrePairRejected {
channel_id: ChannelId,
status: i32,
memo: String,
},
ChannelInfoUpdated {
channel_id: ChannelId,
},
ChannelInfoUpdateRejected {
channel_id: ChannelId,
status: i32,
memo: String,
},
NoOp,
PairingStarted {
channel_id: ChannelId,
kind: SenderKind,
},
DiscoveryStarted {
channel_id: ChannelId,
},
DiscoveryFailed {
channel_id: ChannelId,
error: String,
},
ProtectSecretStarted {
channel_id: ChannelId,
version: u32,
},
ProtectSecretFailed {
channel_id: ChannelId,
version: u32,
error: String,
},
VerifySharesStarted {
channel_id: ChannelId,
version: u32,
},
VerifySharesFailed {
channel_id: ChannelId,
version: u32,
error: String,
},
RecoverSecretStarted {
channel_id: ChannelId,
version: u32,
},
RecoverSecretFailed {
channel_id: ChannelId,
version: u32,
error: String,
},
UnpairStarted {
channel_id: ChannelId,
},
UpdateChannelInfoStarted {
channel_id: ChannelId,
},
UpdateChannelInfoFailed {
channel_id: ChannelId,
error: String,
},
}Expand description
Events emitted by super::DeRecProtocol::process.
The application reacts to these instead of routing raw messages manually.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
PairingCompleted
Pairing completed — the shared key for channel_id is now persisted.
kind is the local party’s role in the pairing, also persisted as
crate::protocol::types::Channel::role and consulted by the orchestrator on
every subsequent flow start and inbound message. Applications use it
to decide what to do next:
SenderKind::Owner— the Owner completed pairing with a Helper. Callsuper::DeRecProtocol::startwithDeRecFlow::ProtectSecretto distribute shares, orDeRecFlow::Discoveryto ask the Helper which secrets it holds (e.g. after a recovery re-pairing).SenderKind::Helper— the Helper side completed pairing; no additional action is required (the Helper waits for incoming messages).SenderKind::ReplicaSource/SenderKind::ReplicaDestination— a replica pairing completed; the application may use the channel as needed (Source pushes viaProtectSecret, Destination receives viaSelf::ReplicaSecretReceived).
Fields
channel_id: ChannelIdLong-term channel_id both peers atomically rotated to at the
end of the handshake. All post-pairing traffic and library
state for this relationship keys on this value.
pairing_channel_id: ChannelIdThe transient channel_id used only during the pairing
handshake — the one that traveled on the ContactMessage and
the pairing envelopes. Already replaced with channel_id in
library state; the library will refuse messages routed to it
from this point on. Provided so applications that persisted
the pairing id (e.g. displayed it in a UI or mirrored it to
their own store) can rekey their own records.
kind: SenderKindReplicaPaired
A replica-mode pair handshake completed. Fires alongside
Self::PairingCompleted on replica channels.
Under the unidirectional replica model, the local side’s role
(ReplicaSource or ReplicaDestination) is already on
crate::protocol::types::Channel::role — this event just adds the
peer’s replica_id, which the app needs as a from_replica_id
when subsequent secret syncs arrive or when targeting the peer via
ProtectSecret.
Fields
A share was accepted and stored locally (Helper side).
replica_id is the stable per-device identifier of the writer,
copied from the inbound StoreShareRequestMessage.replica_id.
None indicates the writer was a non-replica Owner. The field
is metadata for the application; see
crate::protocol::DeRecShareStore::save for the storage
disambiguation contract that makes concurrent writes from
distinct replicas coexist.
ReplicaSecretReceived
A ReplicaSource peer pushed a secret sync on a ReplicaDestination
channel. The library has already auto-acked the inbound
StoreShareRequest and decoded the ReplicaSecretPayload into
typed fields — the application can install secret directly,
optionally using shares to verify or to take over the recovery
flow toward each helper.
Recovery transitivity: secret.helpers[i].shared_key lets
the receiver authenticate as the Source toward each helper. For
replica-to-replica traffic, all replicas share a single
group-wide channel key (see
crate::protocol::types::ReplicaSecretPayload for the handover
protocol) — the receiver’s own
crate::protocol::DeRecSecretStore entry for this channel
holds that group key, so impersonating the Source toward another
destination is just a normal channel-key load. Treat the
receiving device accordingly — see
crate::protocol::types::ReplicaInfo for the security note.
Fields
secret: SecretDecoded full secret — same shape the sender wrote. The
helpers, replicas, secrets, and owner_replica_id
fields carry the canonical roster snapshot for this version.
Per-helper VSS share map. Each entry pairs a helper’s
channel_id with the serialized CommittedDeRecShare bytes
the helper received — sufficient material for the receiver
to drive a recovery against those helpers if needed.
ReplicaSecretAcked
A replica peer’s StoreShareResponse to a secret sync we sent
earlier. Fires on the replica channel, mirroring
Self::ShareConfirmed / Self::ShareRejected on the helper
side.
status and memo come straight from the peer’s
StoreShareResponseMessage.result. Apps decide whether to retry,
rebroadcast, or surface the failure to the user.
Fields
A Helper confirmed it stored our share (Owner side).
A Helper rejected or failed to store our share (Owner side).
The protocol absorbs sharing failures and converts them to events
so the application can display per-participant progress. status and
memo come from the Helper’s response (or are synthetic for timeouts).
SharingComplete
A sharing round has completed (all participants responded or timed out).
Emitted once per DeRecFlow::ProtectSecret flow after every targeted
Helper has either confirmed, rejected, or timed out.
Fields
A Helper’s verification proof checked out (Owner side).
SecretsDiscovered
A Helper reported all secrets it currently stores for this channel (Owner side).
Emitted after the Owner calls super::DeRecProtocol::start with
DeRecFlow::Discovery and the Helper responds. Each
SecretVersionEntry carries a secret_id and a list of
(version, description) pairs for every share the Helper holds.
The application should persist this list and, once enough Helpers have
responded, call super::DeRecProtocol::start with
DeRecFlow::RecoverSecret for the desired (secret_id, version).
Fields
secrets: Vec<SecretVersionEntry>All secrets and their stored versions the Helper holds for this channel.
A recovery share response was received from a Helper but reconstruction cannot succeed yet — more shares are needed to meet the threshold.
channel_ididentifies the Helper that sent this share response.shares_receivedis the total number of share responses collected so far for this(secret_id, version)recovery context.
A recovery share response was received but reconstruction failed for a reason other than insufficient shares (e.g. corrupted share, version mismatch, decode error).
channel_ididentifies the Helper that sent this share response.shares_receivedis the total number of share responses collected so far.errordescribes the failure cause.
SecretRecovered
Recovery completed — the reconstructed
crate::protocol::types::Secret is returned exactly once.
The variant mirrors Self::ReplicaSecretReceived: the
inner secret carries the full typed snapshot
— secrets: Vec<UserSecret> (the user-facing entries the
owner originally protected) plus the roster snapshot
(helpers, replicas, owner_replica_id) captured at
distribution time. Apps that only care about the user-facing
entries read secret.secrets; the roster fields are useful
when the recovering owner wants to know who held the shares,
re-pair with the same helpers, or sync replicas after the
recovery completes.
The library decodes the two-layer (DeRecSecret → Secret)
protobuf wrapping internally; a decode failure surfaces as
Self::RecoveryShareError for that final share, not as
SecretRecovered with bogus contents.
Pass secret to super::DeRecProtocol::restore on a fresh
protocol instance to commit canonical helper / replica state
and wipe the throwaway recovery-mode channels.
ActionRequired
An incoming request requires application confirmation before the library responds.
Emitted by super::DeRecProtocol::process for every incoming request
that is not opted into auto-accept by AutoAcceptPolicy.
The application must call super::DeRecProtocol::accept or
super::DeRecProtocol::reject to complete the flow.
AutoAccepted
The library auto-accepted an incoming request because the
configured AutoAcceptPolicy opted in to its flow.
Emitted by super::DeRecProtocol::process in place of
Self::ActionRequired for the auto-accepted flow, followed
(in the same event vec) by the same flow events a manual
accept(action) would have produced (e.g. ShareStored,
PairingCompleted, Unpaired). Applications use this event
for observability / audit logging — no further action is
required from the caller.
Fields
action_kind: PendingActionKindThe action’s discriminant. The original
PendingAction payload is consumed by the internal
accept and is not surfaced here; routing on the kind is
enough for observability since the flow-completion events
that follow carry the per-flow details.
Unpaired
The local channel state for channel_id has been dropped as the
result of an unpair flow.
Surfaces on both sides of the flow:
- Initiator: emitted when (a)
UnpairAck::NotRequiredand the request has just been sent, (b)UnpairAck::Requiredand the peer acknowledged withOk, or (c)UnpairAck::Requiredand the configured timeout elapsed without a response. - Responder: emitted by
super::DeRecProtocol::acceptafter the channel/share/secret state for the requesting peer has been removed.
UnpairRejected
The peer answered an outbound unpair request with a non-Ok status.
The initiator’s local state is not dropped — the application decides what to do (retry, escalate, or force-delete locally).
Fields
PrePairRejected
The contact creator answered our PrePairRequest with a non-Ok
status (scanner side, HashedKeys flow).
The scanner cannot proceed to a normal PairRequest because the
public keys were never published. Distinct from
crate::primitives::pairing::PairingError::PrePairHashMismatch,
which fires when keys were published but failed the binding-hash
check — a cryptographic failure surfaced as Err, not an event.
Fields
ChannelInfoUpdated
The stored crate::protocol::types::Channel for channel_id has been updated
with new communication info and/or transport endpoint.
Surfaces on both sides of the flow:
- Responder: emitted by
super::DeRecProtocol::acceptafter the update has been persisted to the local channel store. - Initiator: emitted by
super::DeRecProtocol::processwhen the peer’sOkresponse arrives.
The new communication_info / transport_protocol values are
already on the local
crate::protocol::types::Channel by the time the event fires;
applications that care about the post-update state read it from
the channel store directly.
ChannelInfoUpdateRejected
The peer answered an outbound UpdateChannelInfo request with a
non-Ok status. The peer’s stored state is unchanged. The initiator’s
own state is also unaffected.
Fields
NoOp
Well-formed message with no actionable effect (e.g. an ACK).
PairingStarted
A pairing flow was initiated for channel_id with the local
role kind. Emitted synchronously from
super::DeRecProtocol::start when the PairRequest (or
PrePairRequest for HashedKeys / NoKeys modes) was
dispatched successfully. Followed by
Self::PairingCompleted (or a failure variant) once the peer
responds. On a local send failure, start returns Err instead
— no PairingStarted is emitted.
Fields
kind: SenderKindThe local party’s role in the pairing (same value that will
appear on Self::PairingCompleted::kind and be persisted
as crate::protocol::types::Channel::role).
DiscoveryStarted
A discovery request was dispatched to channel_id. Emitted per
targeted channel by super::DeRecProtocol::start. Followed by
Self::SecretsDiscovered once the helper responds.
DiscoveryFailed
A discovery request could not be dispatched to channel_id.
Emitted per targeted channel by super::DeRecProtocol::start
when the outbound send (or per-channel preparation) failed. The
remaining channels in the same fan-out are unaffected.
ProtectSecretStarted
A share-storage request was dispatched to channel_id for
version. Emitted per targeted helper (and per targeted replica
destination) by super::DeRecProtocol::start. Followed by
Self::ShareStored / Self::ShareConfirmed /
Self::ShareRejected as the peer responds; the whole round
finishes with Self::SharingComplete.
ProtectSecretFailed
A share-storage request could not be dispatched to channel_id
for version. Remaining fan-out targets are unaffected.
A verify-share challenge was dispatched to channel_id for
version. Followed by Self::ShareVerified once the helper
responds.
A verify-share challenge could not be dispatched to channel_id
for version.
RecoverSecretStarted
A recovery share request was dispatched to channel_id for
version. Followed by Self::RecoveryShareReceived /
Self::RecoveryShareError / Self::SecretRecovered as
helper responses arrive.
RecoverSecretFailed
A recovery share request could not be dispatched to channel_id
for version.
UnpairStarted
An unpair request was dispatched to channel_id. Followed by
Self::Unpaired once the peer acknowledges (or, under
UnpairAck::NotRequired, emitted in the same event vec
immediately after UnpairStarted).
UpdateChannelInfoStarted
An update-channel-info request was dispatched to channel_id.
Followed by Self::ChannelInfoUpdated once the peer responds.
UpdateChannelInfoFailed
An update-channel-info request could not be dispatched to
channel_id.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for DeRecEvent
impl RefUnwindSafe for DeRecEvent
impl Send for DeRecEvent
impl Sync for DeRecEvent
impl Unpin for DeRecEvent
impl UnsafeUnpin for DeRecEvent
impl UnwindSafe for DeRecEvent
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more