// # URL Payloads
//
// These payloads are part of universal URLs (e.g. group invite links). After
// serializing the protobuf messages, they are encoded in URL safe Base64
// (according to RFC 3548).
//
// Note: Be aware that there is no canonical representation of a URL if it
// contains a protobuf message.

syntax = "proto3";

package url;

option java_package = "ch.threema.protobuf.url_payloads";
option java_multiple_files = true;

import "common.proto";
import "md-d2d-rendezvous.proto";

// Group invitation containing information to request joining a group.
//
// Generated by the administrator of a group. The resulting URL can be shared
// freely with anyone. The invitation can be invalidated by the administrator
// at any point.
//
// The URL is formed using the `threema.group` domain in the following way:
//
// ```text
// https://threema.group/join#<url-safe-base64(GroupInvite)>
// ```
//
// Example:
//
// ```text
// https://threema.group/join#CghFQ0hPRUNITxIQaNbxfd3QsToW0c_668fXUhobQSBuaWNlIGxpdHRsZSBUaHJlZW1hIGdyb3Vw
// ```
message GroupInvite {
  // The admin's Threema ID (8 bytes ASCII)
  string admin_identity = 1;

  // A random 16-byte token
  bytes token = 2;

  // The invite confirmation mode
  enum ConfirmationMode {
    // The admin will auto-accept join requests.
    AUTOMATIC = 0;
    // The admin needs to manually confirm each join request. The user
    // interface should ask the user to pass a message along (e.g. for
    // identification purposes).
    MANUAL = 1;
  }
  ConfirmationMode confirmation_mode = 3;

  // The group name
  string group_name = 4;
}

// Offer or request to join the (multi-)device group.
//
// When generated by an existing or a new device, the URL is formed using the
// `threema` scheme in the following way:
//
// ```text
// threema://device-group/join#<url-safe-base64(DeviceGroupJoinRequestOrOffer)>
// ```
//
// When receiving this message:
//
// 1. If `version` or `variant` is not supported, abort these steps.
// 2. Follow the description of `RendezvousInit` to continue.
message DeviceGroupJoinRequestOrOffer {
  // Device join protocol version used by the device.
  enum Version {
    // Initial version.
    V1_0 = 0;
  }
  Version version = 1;

  // D2D protocol version (`d2d.ProtocolVersion`) used by the device
  //
  // If `0`, assume V0.1 (`0x0001`).
  uint32 d2d_protocol_version = 4;

  // Variant (_offer_ or _request_)
  message Variant {
    oneof type {
      // A device intends to join the (multi-)device group. `data` is to be
      // handled according to the _Device Join Protocol_ with `ND` being the
      // initiator.
      common.Unit request_to_join = 1;

      // A device intends to let another device join the (multi-)device group.
      // `data` is to be handled according to the _Device Join Protocol_ with
      // `ED` being the initiator.
      common.Unit offer_to_join = 2;
    }
  }
  Variant variant = 2;

  // Data necessary to initialise a 1:1 connection between two devices.
  rendezvous.RendezvousInit rendezvous_init = 3;
}