libsession-util/proto/SessionProtos.proto

// iOS - since we use a modern proto-compiler, we must specify the legacy proto format.
syntax = "proto2";

// iOS - package name determines class prefix
package SessionProtos;

option java_package = "org.session.protos";
option optimize_for = LITE_RUNTIME;

message Envelope {

  enum Type {
    SESSION_MESSAGE      = 6;
    CLOSED_GROUP_MESSAGE = 7;
  }

  // @required
  required Type   type            = 1;
  optional string source          = 2;
  optional uint32 sourceDevice    = 7;
  // @required
  required uint64 timestamp       = 5;
  optional bytes  content         = 8;
  optional uint64 serverTimestamp = 10;
  optional bytes  proSig          = 11;
}

message TypingMessage {

    enum Action {
        STARTED = 0;
        STOPPED = 1;
    }

    // @required
    required uint64 timestamp = 1;
    // @required
    required Action action    = 2;
}

message UnsendRequest {
    // @required
    required uint64 timestamp = 1;
    // @required
    required string author    = 2;
}

message MessageRequestResponse {
  // @required
  required bool                      isApproved                = 1; // Whether the request was approved
  optional bytes                     profileKey                = 2;
  optional LokiProfile               profile                   = 3;
}

message Content {

  enum ExpirationType {
    UNKNOWN           = 0;
    DELETE_AFTER_READ = 1;
    DELETE_AFTER_SEND = 2;
  }

  // reserved 7, 11, 15;
  // reserved "configurationMessage", "sharedConfigMessage", "lastDisappearingMessageChangeTimestamp";

  optional DataMessage                dataMessage                            = 1;
  optional CallMessage                callMessage                            = 3;
  optional ReceiptMessage             receiptMessage                         = 5;
  optional TypingMessage              typingMessage                          = 6;
  optional DataExtractionNotification dataExtractionNotification             = 8;
  optional UnsendRequest              unsendRequest                          = 9;
  optional MessageRequestResponse     messageRequestResponse                 = 10;
  optional SharedConfigMessage        sharedConfigMessage                    = 11;
  optional ExpirationType             expirationType                         = 12;
  optional uint32                     expirationTimer                        = 13;

  // NOTE: This timestamp was added to address the issue with 1o1 message envelope timestamps were
  // unauthenticated because 1o1 messages encrypt the Content not the envelope. In Groups, the
  // entire envelope is encrypted and hence can be trusted.
  optional uint64                     sigTimestamp                           = 15;
  optional ProMessage                 proMessage                             = 16;

  // NOTE: Temporary transition field to include the pro-signature into Content for community
  // messages to use.
  //
  // Community messages are currently sent and received as plaintext Content. We call this state of
  // the network v0.
  //
  // We will continue to send Community messages using the Content structure, but, now enhanced with
  // the optional `proSigForCommunityMessageOnly` field which contains the pro signature. We call
  // this network v1. The new clients running v1 will pack the pro-signature into the payload. We
  // maintain forwards compatibility with clients on v0 as we are still sending content
  // on the wire, they skip the new pro data.
  //
  // Simultaneously in v1 the responsibility of parsing the open groups messages will go into
  // libsession. Libsession will be setup to try and parse the open groups message as a `Content`
  // message at first, if that fails it will try to read the community message as an `Envelope`.
  // In summary in a v1 network:
  //
  //   v0 will still receive messages from v1 as they send `Content` community messages.
  //
  //   v1 accepts v0 (`Content`) and v1 (`Envelope`) on the wire for community messages. v1 sends
  //   `Content` community messages so that there's compatibility with v0.
  //
  // After a defined transitionary period, we create a new release and update libsession to stop
  // sending `Content` for communities and transition to sending `Envelope` for messages. We mark
  // this as a v2 network:
  //
  //   v0 will still receive messages from v1 (`Content`) but not v2 (`Envelope`) community
  //   messages.
  //
  //   v1 accepts v0 (`Content`) and v1 (`Envelope`) on the wire for community messages. v1 sends
  //   `Content` community messages so that there's compatibility with v0.
  //
  //   v2 swaps the parsing order. it tries parsing v1 (`envelope`) then v0 (`content`) from a
  //   community message. v2 sends `envelope` community messages so compatbility is maintained with
  //   v1 but not v0.
  //
  // After a final transitionary period, v3, remove parsing content entirely from libsession for
  // community messages and removes the pro-signature from `content`. in this final stage, v2 and v3
  // are the final set of clients that can continue to talk to each other.
  //
  // +---------+----------------+-------------+------------------+-------------+-------------+
  // | Version | Sends          | Receives v0 | Receives v1      | Receives v2 | Receives v3 |
  // |         |                | (Content)   | (Content+ProSig) | (Envelope)  | (Envelope)  |
  // +---------+----------------+-------------+------------------+-------------+-------------+
  // | v0      | Content        | Yes         | Yes              | No          | No          |
  // +---------+----------------+-------------+------------------+-------------+-------------+
  // | v1      | Content+ProSig | Yes         | Yes              | Yes         | Yes         |
  // +---------+----------------+-------------+------------------+-------------+-------------+
  // | v2      | Envelope       | Yes         | Yes              | Yes         | Yes         |
  // +---------+----------------+-------------+------------------+-------------+-------------+
  // | v3      | Envelope       | No          | No               | Yes         | Yes         |
  // +---------+----------------+-------------+------------------+-------------+-------------+
  optional bytes                      proSigForCommunityMessageOnly          = 17;
}

message CallMessage {

    enum Type {
      PRE_OFFER          = 6;
      OFFER              = 1;
      ANSWER             = 2;
      PROVISIONAL_ANSWER = 3;
      ICE_CANDIDATES     = 4;
      END_CALL           = 5;
    }

    // Multiple ICE candidates may be batched together for performance

    // @required
    required Type   type            = 1;
    repeated string sdps            = 2;
    repeated uint32 sdpMLineIndexes = 3;
    repeated string sdpMids         = 4;
    // @required
    required string uuid            = 5;
}

message KeyPair {
  // @required
  required bytes publicKey  = 1;
  // @required
  required bytes privateKey = 2;
}

message DataExtractionNotification {

  enum Type {
    SCREENSHOT  = 1;
    MEDIA_SAVED = 2; // timestamp
  }

  // @required
  required Type   type      = 1;
  optional uint64 timestamp = 2;
}

message LokiProfile {
  optional string displayName = 1;
  optional string profilePicture = 2;
  optional uint64 lastUpdateSeconds = 3; // Timestamp of the last profile update
}

message DataMessage {

  enum Flags {
    EXPIRATION_TIMER_UPDATE = 2;
  }

  message Quote {

    message QuotedAttachment {

      enum Flags {
        VOICE_MESSAGE = 1;
      }

      optional string            contentType = 1;
      optional string            fileName    = 2;
      optional AttachmentPointer thumbnail   = 3;
      optional uint32            flags       = 4;
    }

    // @required
    required uint64            id          = 1;
    // @required
    required string            author      = 2;
    optional string            text        = 3;
    repeated QuotedAttachment  attachments = 4;
  }

  message Preview {
    // @required
    required string            url   = 1;
    optional string            title = 2;
    optional AttachmentPointer image = 3;
  }

  message Reaction {
    enum Action {
        REACT = 0;
        REMOVE = 1;
    }
    // @required
    required uint64 id        = 1; // Message timestamp
    // @required
    required string author    = 2;
    optional string emoji     = 3;
    // @required
    required Action action    = 4;
  }

  message OpenGroupInvitation {
    // @required
    required string url = 1;
    // @required
    required string name = 3;
  }


  //  reserved 3;
  //  reserved "group";
  // reserved 104;
  // reserved "closedGroupControlMessage";

  optional string                    body                           = 1;
  repeated AttachmentPointer         attachments                    = 2;
  optional uint32                    flags                          = 4;
  // optional uint32                 expireTimer                    = 5;  // No longer used
  optional bytes                     profileKey                     = 6;
  optional uint64                    timestamp                      = 7;
  optional Quote                     quote                          = 8;
  repeated Preview                   preview                        = 10;
  optional Reaction                  reaction                       = 11;
  optional LokiProfile               profile                        = 101;
  optional OpenGroupInvitation       openGroupInvitation            = 102;
  optional string                    syncTarget                     = 105;
  optional bool                      blocksCommunityMessageRequests = 106;
  optional GroupUpdateMessage        groupUpdateMessage             = 120;
}

message ReceiptMessage {

  enum Type {
    DELIVERY = 0;
    READ     = 1;
  }

  // @required
  required Type   type      = 1;
  repeated uint64 timestamp = 2;
}

message AttachmentPointer {

  enum Flags {
    VOICE_MESSAGE = 1;
  }

  // @required
  required fixed64 id          = 1;
  optional string  contentType = 2;
  optional bytes   key         = 3;
  optional uint32  size        = 4;
  optional bytes   thumbnail   = 5;
  optional bytes   digest      = 6;
  optional string  fileName    = 7;
  optional uint32  flags       = 8;
  optional uint32  width       = 9;
  optional uint32  height      = 10;
  optional string  caption     = 11;
  optional string  url         = 101;
}

message SharedConfigMessage {
    enum Kind {
        USER_PROFILE            = 1;
        CONTACTS                = 2;
        CONVO_INFO_VOLATILE     = 3;
        USER_GROUPS             = 4;
    }

    // @required
    required Kind   kind        = 1;
    // @required
    required int64  seqno       = 2;
    // @required
    required bytes  data        = 3;
}

// Group Update Messages

message GroupUpdateMessage {
  optional GroupUpdateInviteMessage                  inviteMessage                 = 1;
  optional GroupUpdateInfoChangeMessage              infoChangeMessage             = 2;
  optional GroupUpdateMemberChangeMessage            memberChangeMessage           = 3;
  optional GroupUpdatePromoteMessage                 promoteMessage                = 4;
  optional GroupUpdateMemberLeftMessage              memberLeftMessage             = 5;
  optional GroupUpdateInviteResponseMessage          inviteResponse                = 6;
  optional GroupUpdateDeleteMemberContentMessage     deleteMemberContent           = 7;
  optional GroupUpdateMemberLeftNotificationMessage  memberLeftNotificationMessage = 8;
}

message GroupUpdateInviteMessage {
  // @required
  required string         groupSessionId         = 1; // The `groupIdentityPublicKey` with a `03` prefix
  // @required
  required string         name                   = 2;
  // @required
  required bytes          memberAuthData         = 3;
  // @required
  required bytes          adminSignature         = 4;
}

message GroupUpdatePromoteMessage {
  // @required
  required bytes          groupIdentitySeed       = 1;
  // @required
  required string         name                    = 2;
}

message GroupUpdateInfoChangeMessage {
  enum Type {
    NAME                  = 1;
    AVATAR                = 2;
    DISAPPEARING_MESSAGES = 3;
  }

  // @required
  required Type     type              = 1;
  optional string   updatedName       = 2;
  optional uint32   updatedExpiration = 3;
  // @required
  required bytes    adminSignature    = 4;
}

message GroupUpdateMemberChangeMessage {
  enum Type {
    ADDED    = 1;
    REMOVED  = 2;
    PROMOTED = 3;
  }

  // @required
  required Type   type               = 1;
  repeated string memberSessionIds   = 2;
  optional bool   historyShared      = 3;
  // @required
  required bytes  adminSignature     = 4;
}

message GroupUpdateMemberLeftMessage {
  // the pubkey of the member left is included as part of the closed group encryption logic (senderIdentity on desktop)
}

message GroupUpdateMemberLeftNotificationMessage {
  // the pubkey of the member left is included as part of the closed group encryption logic (senderIdentity on desktop)
}

message GroupUpdateInviteResponseMessage {
  // @required
  required bool                      isApproved                = 1; // Whether the request was approved
}

message GroupUpdateDeleteMemberContentMessage {
  repeated string memberSessionIds   = 1;
  repeated string messageHashes      = 2;
  optional bytes  adminSignature     = 3;
}

message ProProof {
  optional uint32 version           = 1;
  optional bytes  revocationTag      = 2; // Opaque identifier of this proof produced by the Session Pro backend
  optional bytes  rotatingPublicKey = 3; // Public key whose signatures is authorised to entitle messages with Session Pro
  optional uint64 expiryUnixTs      = 4; // Epoch timestamps in milliseconds
  optional bytes  sig               = 5; // Signature produced by the Session Pro Backend signing over the hash of the proof
}

message ProMessage {
  optional ProProof proof          = 1;
  optional uint64   profileBitset  = 2;
  optional uint64   msgBitset      = 3;
}