State
in package
Per-connection DAVE E2EE state.
Owns the MLS session lifetime, protocol version, passthrough mode, and all key-ratchet / decryptor / encryptor handles. Destruction ordering matters: encryptor/decryptors must be destroyed before key-ratchets, before the session (enforced by close() and __destruct()).
State machine summary: prepareProtocolVersion() → passthroughMode=true (waiting for transition) executeTransition() → passthroughMode=false (media E2EE active) resetProtocolState() → passthroughMode=true (all handles freed)
Table of Contents
Properties
- $decryptFailureCount : int
- $encryptFailureCount : int
- $encryptor : EncryptorHandle|null
- $epoch : int|null
- $externalSenderPackage : string|null
- $groupId : int|null
- $keyPackageSent : bool
- $lastReceivedSequence : int|null
- $latestPreparedTransitionVersion : int|null
- $passthroughMode : bool
- $pendingProtocolVersion : int|null
- $pendingTransitionId : int|null
- $proposalFailureCount : int
- Consecutive proposal-processing failures for the current epoch.
- $protocolVersion : int
- $selfUserId : string|null
- $session : SessionHandle|null
- $decryptors : array<string, DecryptorHandle>
- $keyRatchets : array<string, KeyRatchetHandle>
- $recognizedUserIds : array<string, bool>
- $selfKeyRatchet : KeyRatchetHandle|null
Methods
- __destruct() : mixed
- Frees every native handle in the correct order (see {@see close()}).
- addRecognizedUsers() : void
- clearDecryptors() : void
- Destroys and drops every per-user decryptor.
- clearKeyRatchets() : void
- Destroys and drops every key ratchet, including this client's own.
- close() : void
- Destroys every native handle in dependency order: encryptor and decryptors, then key ratchets, then the session.
- executeTransition() : void
- Applies the pending transition when `$transitionId` matches, promoting the staged protocol version.
- getAllDecryptors() : array<string, DecryptorHandle>
- getDecryptor() : DecryptorHandle|null
- The {@see DecryptorHandle} for `$userId`, or null.
- getKeyRatchet() : KeyRatchetHandle|null
- The {@see KeyRatchetHandle} for `$userId`, or null.
- getSelfKeyRatchet() : KeyRatchetHandle|null
- This client's own {@see KeyRatchetHandle}, or null.
- incrementDecryptFailures() : void
- Bumps the consecutive media-decrypt failure counter.
- incrementEncryptFailures() : void
- Bumps the consecutive media-encrypt failure counter.
- incrementProposalFailures() : void
- Bumps the consecutive proposal-processing failure counter for the current epoch.
- markKeyPackageSent() : void
- Marks that this client has published its MLS key package.
- prepareEpoch() : void
- Records the MLS epoch id the next group operations belong to.
- prepareProtocolVersion() : void
- Stages a protocol version for an upcoming transition; keeps passthrough on until media E2EE was already active.
- prepareTransition() : void
- Records a pending transition id and (optionally) the protocol version it will move to.
- recognizedUsers() : array<int, string>
- recognizedUsersIncludingSelf() : array<int, string>
- recordExternalSender() : void
- Stores the group's external-sender package (public key + credential).
- recordGatewaySequence() : void
- Stores the last gateway sequence number seen, for `seq_ack` on heartbeats/resume. Ignores null.
- removeRecognizedUser() : void
- Forgets `$userId` and destroys its decryptor and key ratchet.
- replaceEncryptor() : void
- Swaps in a new {@see EncryptorHandle}, destroying the previous one.
- replaceSession() : void
- Swaps in a new MLS {@see SessionHandle}, destroying the previous one.
- resetProposalFailures() : void
- Clears the proposal-processing failure counter.
- resetProtocolState() : void
- Frees all handles and returns the state to a fresh passthrough baseline (version 0).
- setDecryptor() : void
- Sets (or, with null, removes and destroys) the per-user {@see DecryptorHandle} for `$userId`.
- setIdentity() : void
- Records this connection's own user id and MLS group id.
- setKeyRatchet() : void
- Sets (or, with null, removes and destroys) the per-user {@see KeyRatchetHandle} for `$userId`.
- setProtocolVersion() : void
- Sets the active DAVE protocol version and derives passthrough mode (`version <= 0` means passthrough).
- setSelfKeyRatchet() : void
- Sets this client's own {@see KeyRatchetHandle}, destroying the previous one.
Properties
$decryptFailureCount
public
int
$decryptFailureCount
= 0
$encryptFailureCount
public
int
$encryptFailureCount
= 0
$encryptor
public
EncryptorHandle|null
$encryptor
= null
$epoch
public
int|null
$epoch
= null
$externalSenderPackage
public
string|null
$externalSenderPackage
= null
$groupId
public
int|null
$groupId
= null
$keyPackageSent
public
bool
$keyPackageSent
= false
$lastReceivedSequence
public
int|null
$lastReceivedSequence
= null
$latestPreparedTransitionVersion
public
int|null
$latestPreparedTransitionVersion
= null
$passthroughMode
public
bool
$passthroughMode
= true
$pendingProtocolVersion
public
int|null
$pendingProtocolVersion
= null
$pendingTransitionId
public
int|null
$pendingTransitionId
= null
$proposalFailureCount
Consecutive proposal-processing failures for the current epoch.
public
int
$proposalFailureCount
= 0
$protocolVersion
public
int
$protocolVersion
= 0
$selfUserId
public
string|null
$selfUserId
= null
$session
public
SessionHandle|null
$session
= null
$decryptors
private
array<string, DecryptorHandle>
$decryptors
= []
$keyRatchets
private
array<string, KeyRatchetHandle>
$keyRatchets
= []
$recognizedUserIds
private
array<string, bool>
$recognizedUserIds
= []
$selfKeyRatchet
private
KeyRatchetHandle|null
$selfKeyRatchet
= null
Methods
__destruct()
Frees every native handle in the correct order (see {@see close()}).
public
__destruct() : mixed
addRecognizedUsers()
public
addRecognizedUsers(array<string|int, int|string> $userIds) : void
Parameters
- $userIds : array<string|int, int|string>
clearDecryptors()
Destroys and drops every per-user decryptor.
public
clearDecryptors() : void
clearKeyRatchets()
Destroys and drops every key ratchet, including this client's own.
public
clearKeyRatchets() : void
close()
Destroys every native handle in dependency order: encryptor and decryptors, then key ratchets, then the session.
public
close() : void
executeTransition()
Applies the pending transition when `$transitionId` matches, promoting the staged protocol version.
public
executeTransition(int $transitionId) : void
Parameters
- $transitionId : int
getAllDecryptors()
public
getAllDecryptors() : array<string, DecryptorHandle>
Return values
array<string, DecryptorHandle>getDecryptor()
The {@see DecryptorHandle} for `$userId`, or null.
public
getDecryptor(int|string $userId) : DecryptorHandle|null
Parameters
- $userId : int|string
Return values
DecryptorHandle|nullgetKeyRatchet()
The {@see KeyRatchetHandle} for `$userId`, or null.
public
getKeyRatchet(int|string $userId) : KeyRatchetHandle|null
Parameters
- $userId : int|string
Return values
KeyRatchetHandle|nullgetSelfKeyRatchet()
This client's own {@see KeyRatchetHandle}, or null.
public
getSelfKeyRatchet() : KeyRatchetHandle|null
Return values
KeyRatchetHandle|nullincrementDecryptFailures()
Bumps the consecutive media-decrypt failure counter.
public
incrementDecryptFailures() : void
incrementEncryptFailures()
Bumps the consecutive media-encrypt failure counter.
public
incrementEncryptFailures() : void
incrementProposalFailures()
Bumps the consecutive proposal-processing failure counter for the current epoch.
public
incrementProposalFailures() : void
markKeyPackageSent()
Marks that this client has published its MLS key package.
public
markKeyPackageSent() : void
prepareEpoch()
Records the MLS epoch id the next group operations belong to.
public
prepareEpoch(int $epoch) : void
Parameters
- $epoch : int
prepareProtocolVersion()
Stages a protocol version for an upcoming transition; keeps passthrough on until media E2EE was already active.
public
prepareProtocolVersion(int $version) : void
Parameters
- $version : int
prepareTransition()
Records a pending transition id and (optionally) the protocol version it will move to.
public
prepareTransition(int $transitionId[, int|null $protocolVersion = null ]) : void
Parameters
- $transitionId : int
- $protocolVersion : int|null = null
recognizedUsers()
public
recognizedUsers() : array<int, string>
Return values
array<int, string>recognizedUsersIncludingSelf()
public
recognizedUsersIncludingSelf() : array<int, string>
Return values
array<int, string>recordExternalSender()
Stores the group's external-sender package (public key + credential).
public
recordExternalSender(string $senderPackage) : void
Parameters
- $senderPackage : string
recordGatewaySequence()
Stores the last gateway sequence number seen, for `seq_ack` on heartbeats/resume. Ignores null.
public
recordGatewaySequence(int|null $sequence) : void
Parameters
- $sequence : int|null
removeRecognizedUser()
Forgets `$userId` and destroys its decryptor and key ratchet.
public
removeRecognizedUser(int|string $userId) : void
Parameters
- $userId : int|string
replaceEncryptor()
Swaps in a new {@see EncryptorHandle}, destroying the previous one.
public
replaceEncryptor(EncryptorHandle|null $encryptor) : void
Parameters
- $encryptor : EncryptorHandle|null
replaceSession()
Swaps in a new MLS {@see SessionHandle}, destroying the previous one.
public
replaceSession(SessionHandle|null $session) : void
Parameters
- $session : SessionHandle|null
resetProposalFailures()
Clears the proposal-processing failure counter.
public
resetProposalFailures() : void
resetProtocolState()
Frees all handles and returns the state to a fresh passthrough baseline (version 0).
public
resetProtocolState() : void
setDecryptor()
Sets (or, with null, removes and destroys) the per-user {@see DecryptorHandle} for `$userId`.
public
setDecryptor(int|string $userId, DecryptorHandle|null $decryptor) : void
Parameters
- $userId : int|string
- $decryptor : DecryptorHandle|null
setIdentity()
Records this connection's own user id and MLS group id.
public
setIdentity(int|string $selfUserId, int|string|null $groupId) : void
Parameters
- $selfUserId : int|string
- $groupId : int|string|null
setKeyRatchet()
Sets (or, with null, removes and destroys) the per-user {@see KeyRatchetHandle} for `$userId`.
public
setKeyRatchet(int|string $userId, KeyRatchetHandle|null $keyRatchet) : void
Parameters
- $userId : int|string
- $keyRatchet : KeyRatchetHandle|null
setProtocolVersion()
Sets the active DAVE protocol version and derives passthrough mode (`version <= 0` means passthrough).
public
setProtocolVersion(int $version) : void
Parameters
- $version : int
setSelfKeyRatchet()
Sets this client's own {@see KeyRatchetHandle}, destroying the previous one.
public
setSelfKeyRatchet(KeyRatchetHandle|null $keyRatchet) : void
Parameters
- $keyRatchet : KeyRatchetHandle|null