// ## End-to-End Encrypted Messages (Supplementary)
//
// This is a supplementary section to the corresponding structbuf section
// with newer messages that use protobuf instead of structbuf. All defined
// messages here follow the same logic.

syntax = "proto3";

package csp_e2e;

option java_package = "ch.threema.protobuf.csp.e2e";
option java_multiple_files = true;

import "common.proto";

// Metadata sent within a CSP payload `message-with-meta` struct.
message MessageMetadata {
  // Padding that is ignored by the receiver.
  // Recommended to be chosen such that the total length of padding + nickname
  // is at least 16 bytes. May be empty if the nickname is long enough.
  bytes padding = 1;

  // The nickname associated to the sender's Threema ID. Recommended to not
  // exceed 32 graphemes.
  string nickname = 2;

  // Unique message ID. Must match the message ID of the outer struct
  // (i.e. `message-with-metadata-box.message-id`).
  fixed64 message_id = 3;

  // Unix-ish timestamp in milliseconds for when the message has been created.
  //
  // Messages sent in a group must have the same timestamp for each group
  // member.
  uint64 created_at = 4;
}

// Announces and immediately starts a group call.
//
// **Flags:**
//   - `0x01`: Send push notification.
//
// **Delivery receipts:** Automatic: No. Manual: No.
//
// **Reflect:** Incoming: Yes. Outgoing: Yes.
//
// When creating this message to start a call within the group:
//
// 1. Run the _Group Call Refresh Steps_ and let `chosen-call` be the result.
// 2. If `chosen-call` is defined, abort these steps. (`chosen-call` will be
//    joined instead.)
// 3. Create the message but don't send it yet:
//    1. Generate a random GCK and set `gck` appropriately.
//    2. Set `sfu_base_url` to the _SFU Base URL_ obtained from the Directory
//       Server API.
// 4. Join the call matching the Call ID of the created message and wait until
//    the SFU sent the initial `Hello` message via the associated data channel.
//    Let `hello` be that message. This is an asynchronous process.
//
//    If this step has been cancelled by the _Group Call Refresh Steps_
//    determining another `chosen-call` in the meantime, cancel the call we have
//    started to create and abort these steps. (`chosen-call` will be joined
//    instead.)
// 5. If `hello.participants` is not an empty list, exceptionally abort the call
//    and these steps.
// 6. Send the message to the group.
// 7. Add the created call to the list of group calls that are currently
//    considered running.
// 8. Trigger the _Group Call Refresh Steps_ again (to start displaying the call
//    in the UI and starting the refresh timer).
//
// When receiving this message:
//
// 1. Run the [_Common Group Receive Steps_](ref:e2e#receiving). If the received
//    message has been discarded, abort these steps.
// 2. If the hostname of `sfu_base_url` does not use the scheme `https` or does
//    not end with one of the set of _Allowed SFU Hostname Suffixes_, log a
//    warning, discard the message and abort these steps.
// 3. Let `running` be the list of group calls that are currently considered
//    running within the group.
// 4. If another call with the same GCK exists in `running`, log a warning,
//    discard the message and abort these steps.
// 5. Add the received call to the list of group calls that are currently
//    considered running (even if `protocol_version` is unsupported; this is to
//    allow the user to join an ongoing call after an app update where support
//    for `protocol_version` has been added).
// 6. Run the _Group Call Refresh Steps_ and let `chosen-call` be the result.
//    (`chosen-call` will be joined if the user is currently participating in a
//    group call of this group.)
message GroupCallStart {
  // Protocol version used for group calls of this group. The current version
  // number is `1`.
  //
  // Note: This is a _major_ version and may only be increased in case of
  // breaking changes due to the significant UX impact this has when running the
  // _Common Group Receive Steps_ (i.e. only calls with supported protocol
  // versions can be _chosen_).
  uint32 protocol_version = 1;

  // The secret Group Call Key (`GCK`) used for this call.
  bytes gck = 2;

  // The base URL of the SFU, used to join or peek the call.
  string sfu_base_url = 3;
}

// Request joining a group.
//
// This message is sent to the administrator of a group. The required
// information is provided by a `GroupInvite` URL payload.
//
// **Flags:**
//   - `0x01`: Send push notification.
//
// **Delivery receipts:** Automatic: No. Manual: No.
//
// **Reflect:** Incoming: Yes. Outgoing: Yes.
//
// When receiving this message:
//
// 1. Look up the corresponding group invitation by the token.
// 2. If the group invitation could not be found, discard the message and abort
//    these steps.
// 3. If the sender is already part of the group, send an accept response and
//    then respond as if the sender had sent a `group-sync-request` (i.e. send
//    a `group-setup`, `group-name`, etc.). Finally, abort these steps.
// 4. If the group name does not match the name in the originally sent group
//    invitation, discard the message and abort these steps.
// 5. If the group invitation has expired, send the respective response and
//    abort these steps.
// 6. If the group invitation requires the admin to accept the request, show
//    this information in the user interface and pause these steps until the
//    admin manually confirmed of rejected the request. Note that the date of
//    the decision is allowed to extend beyond the expiration date of the
//    group invitation. Continue with the following sub-steps once the admin
//    made a decision on the request:
//     1. If the admin manually rejected the request, send the respective
//        response and abort these steps.
// 7. If the group is full, send the respective response and abort these steps.
// 8. Send an accept response.
// 9. Add the sender of the group invitation request to the group and follow
//    the group protocol from there.
message GroupJoinRequest {
  // The group invite token, 16 bytes
  bytes token = 1;

  // The group name from the group invite URL
  string group_name = 2;

  // A message for the group administrator, e.g. for identification purposes
  //
  // The message helps the administrator to decide whether or not to accept a
  // join request.
  //
  // Should be requested by the user interface for invitations that require
  // manual confirmation by the administrator. Should not be requested in case
  // the invitation will be automatically accepted.
  string message = 3;
}

// Response sent by the admin of a group towards a sender of a valid group join
// request.
//
// **Flags:** None.
//
// **Delivery receipts:** Automatic: No. Manual: No.
//
// **Reflect:** Incoming: Yes. Outgoing: Yes.
//
// When receiving this message:
//
// 1. Look up the corresponding group join request by the token and the
//    sender's Threema ID as the administrator's Threema ID.
// 2. If the group join request could not be found, discard the message and
//    abort these steps.
// 3. Mark the group join request as accepted or (automatically) rejected by
//    the given response type.
// 4. If the group join request has been accepted, remember the group id in
//    order to be able to map an incoming `group-setup` to the group.
message GroupJoinResponse {
  // The group invite token, 16 bytes
  bytes token = 1;

  // Response of the admin
  message Response {
    // Accept a group invite request
    message Accept {
      // Group ID (little-endian) as chosen by the group creator
      // Note: Combined with the Threema ID of the administrator, this forms
      //       the `GroupIdentity`.
      fixed64 group_id = 1;
    }

    oneof response {
      // Accept a group invite request
      Accept accept = 1;
      // Token of a group invitation expired
      common.Unit expired = 2;
      // Group invitation cannot be accepted due to the group being full
      common.Unit group_full = 3;
      // The administrator explicitly rejects the invitation request
      common.Unit reject = 4;
    }
  }
  Response response = 2;
}
