session-desktop/protos/SignalService.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 optimize_for = LITE_RUNTIME;

message Envelope {
  reserved "sourceDevice", "serverTimestamp";
  reserved 7, 10;

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

  // @required
  required Type   type            = 1;
  optional string source          = 2;
  // @required
  required uint64 timestamp       = 5;
  optional bytes  content         = 8;
  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 {
  reserved 7, 11, 14;
  reserved "configurationMessage", "sharedConfigMessage", "lastDisappearingMessageChangeTimestamp";

  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 ExpirationType             expirationType                         = 12;
  optional uint32                     expirationTimer                        = 13;
  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 DataExtractionNotification {

  enum Type {
    SCREENSHOT  = 1; // no way to know this on Desktop
    MEDIA_SAVED = 2; // timestamp
  }

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

message LokiProfile {
    optional string displayName = 1;
    optional string profilePicture = 2;
    /**
     * The timestamp of the last profile update.
     * This is used to prioritize the correct profile info based on multiple and outdated incoming messages.
     * Note: this is in seconds.
     */
    optional uint64 lastProfileUpdateSeconds = 3;
  }

message DataMessage {

  enum Flags {
    EXPIRATION_TIMER_UPDATE = 2;
  }

  message Quote {
    reserved 3, 4;
    reserved "text", "attachments";

    // @required
    required uint64            id          = 1;
    // @required
    required string            author      = 2;
  }

  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;
  }

  // 7 = timestamp unused and should not be used
  reserved 7;
  reserved "timestamp";

  // 5 = expireTimer unused and should not be used (in contentMessage now)
  reserved 5;
  reserved "expireTimer";

  // 104 = legacy group control message
  reserved 104;
  reserved "closedGroupControlMessage";
  // 3 = group (GroupContext) legacy group
  reserved 3;
  reserved "group";

  optional string                    body                           = 1;
  repeated AttachmentPointer         attachments                    = 2;
  optional uint32                    flags                          = 4;
  optional bytes                     profileKey                     = 6;
  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 {
    READ     = 1;
  }

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

message AttachmentPointer {
  reserved "thumbnail";
  reserved 5;

  enum Flags {
    VOICE_MESSAGE = 1;
  }

  // @required
  required fixed64 deprecated_id = 1;
  optional string  contentType   = 2;
  optional bytes   key           = 3;
  optional uint32  size          = 4;
  optional bytes   digest        = 6;
  optional string  fileName      = 7;
  optional uint32  flags         = 8;
  optional uint32  width         = 9;
  optional uint32  height        = 10;
  optional string  caption       = 11;
  /**
   * This field can be just an url to the file, or have a fragment appended to it that can contain:
   * - `p=<server_pubkey_hex>` // hex encoded pubkey of the file server
   * - `d=` // if the file is deterministically encrypted, this field is present, otherwise it is not
   * If needed, those fields are a &, and can be parsed/built with the usual URLSearchParams logic
   */
  optional string  url           = 101;
}

// 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 group encryption logic (senderIdentity on desktop)
}

message GroupUpdateMemberLeftNotificationMessage {
  // the pubkey of the member left is included as part of the 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  genIndexHash      = 2;
  optional bytes  rotatingPublicKey = 3;
  optional uint64 expireAtMs        = 4; // Epoch timestamp in milliseconds
  optional bytes  sig               = 5;
}

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

message WebSocketRequestMessage {
  optional string verb    = 1;
  optional string path    = 2;
  optional bytes  body    = 3;
  repeated string headers = 5;
  optional uint64 id      = 4;
}


message WebSocketMessage {
  enum Type {
      UNKNOWN  = 0;
      REQUEST  = 1;
      RESPONSE = 2;
  }

  optional Type                     type     = 1;
  optional WebSocketRequestMessage  request  = 2;
}