Package moe.kyokobot.libdave

Interface Session

All Superinterfaces:
AutoCloseable
public interface Session extends AutoCloseable
Represents a session for Discord's Audio/Video End-to-End Encryption (DAVE) protocol.

This class manages the Messaging Layer Security (MLS) group state, handling key exchanges, group membership changes (proposals, commits, welcomes), and per-sender key ratchets. It serves as the central coordination point for E2EE in a media session.

  • Method Details

    • init

      void init(int version, long groupId, String selfUserId)
      Initializes the session with initial parameters.
      Parameters:
      version - The DAVE protocol version to use.
      groupId - The ID of the group (e.g., channel ID or call ID).
      selfUserId - The user ID of the current participant.

    • reset

      void reset()
      Resets the session state.

      This clears the current MLS group state and resets the session to its initial state. Used when the session needs to be restarted, for example, after a hard failure or re-connection.

    • setProtocolVersion

      void setProtocolVersion(int version)
      Sets the protocol version for the session.
      Parameters:
      version - The protocol version to set.

    • getProtocolVersion

      int getProtocolVersion()
      Gets the current protocol version of the session.
      Returns:
      The current protocol version.

    • getLastEpochAuthenticator

      byte[] getLastEpochAuthenticator()
      Retrieves the authenticator for the last processed epoch.

      This can be used to verify the integrity and authenticity of the current group state.

      Returns:
      A byte array containing the epoch authenticator.

    • setExternalSender

      void setExternalSender(byte[] externalSender)
      Sets the external sender for the session.

      The external sender is typically the Voice Gateway, which facilitates group changes.

      Parameters:
      externalSender - The binary representation of the external sender's public key/info.

    • processProposals

      byte[] processProposals(byte @NotNull [] proposals, @NotNull @NotNull String[] recognizedUserIds)
      Processes a list of MLS proposals.

      Proposals are changes to the group (add, remove, update) that are not yet committed.

      Parameters:
      proposals - The binary encoded proposals.
      recognizedUserIds - An array of user IDs that are recognized/expected in the session.
      Returns:
      A byte array containing the result of processing the proposals (e.g., a commit message to be sent), or null/empty if no action is needed immediately.

    • processCommit

      @NotNull @NotNull CommitResult processCommit(byte @NotNull [] commit)
      Processes an MLS commit message.

      A commit finalizes proposals and transitions the group to a new epoch.

      Parameters:
      commit - The binary encoded commit message.
      Returns:
      A CommitResult indicating the outcome (success, failure, ignored) and containing the roster changes.

    • processWelcome

      @Nullable @Nullable RosterMap processWelcome(byte @NotNull [] welcome, @NotNull @NotNull String[] recognizedUserIds)
      Processes an MLS welcome message.

      A welcome message is received when joining an existing group. It contains the initial group state.

      Parameters:
      welcome - The binary encoded welcome message.
      recognizedUserIds - An array of user IDs that are recognized/expected.
      Returns:
      A RosterMap containing the initial set of participants and their keys, or null on failure.

    • getMarshalledKeyPackage

      byte[] getMarshalledKeyPackage()
      Generates a marshalled key package for the current user.

      This package is used to publish the user's initial key material so they can be added to the MLS group.

      Returns:
      A byte array containing the marshalled key package.

    • getKeyRatchet

      @Nullable @Nullable KeyRatchet getKeyRatchet(String userId)
      Retrieves the key ratchet for a specific user.

      The key ratchet contains the sequence of keys used to decrypt media from that user (or encrypt for self).

      Parameters:
      userId - The ID of the user whose ratchet is requested.
      Returns:
      A KeyRatchet instance.

    • getPairwiseFingerprint

      CompletableFuture<byte[]> getPairwiseFingerprint(int version, String userId)
      Computes a pairwise fingerprint for verification with another user asynchronously.

      The returned fingerprint can be compared out-of-band to verify that no man-in-the-middle attack is occurring.

      Parameters:
      version - The protocol version.
      userId - The ID of the other user.
      Returns:
      A CompletableFuture that will complete with the computed fingerprint as a byte array, or complete exceptionally if the computation failed.

    • close

      void close()
      Closes the session and releases native resources.
      Specified by:
      close in interface AutoCloseable