// # 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). All URLs should have a trailing slash.
//
// 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";

// 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:
//
//     https://threema.group/join#<url-safe-base64(GroupInvite)>/
//
// Example:
//
//     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 family.
//
// When generated by an existing or a new device, the URL is formed using the
// `threema` scheme in the following way:
//
//     threema://device-family/join#<url-safe-base64(DeviceFamilyJoinRequestOrOffer)>/
message DeviceFamilyJoinRequestOrOffer {
  // Variant (_offer_ or _request_)
  message Variant {
    oneof type {
      // A device intends to join the (multi-)device family. `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 family.
      // `data` is to be handled according to the _Device Join Protocol_ with
      // `ED` being the initiator.
      common.Unit offer_to_join = 2;
    }
  }
  Variant variant = 1;

  // The 32-byte random salt used for deriving the user's passphrase (`PSK`)
  // as defined by the Device Join Protocol.
  bytes psk_salt = 2;

  // Contains rendezvous data (`rendezvous.RendezvousInit`) encrypted by a
  // random nonce and the key derived from the user's passphrase (`PSK`) as
  // defined by the Device Join Protocol. The final result is encoded in an
  // `extra.crypto.encrypted-data-with-nonce-ahead` struct.
  //
  //     Box(PSK.secret)
  //       .encrypt(data=<rendezvous.RendezvousInit>, nonce=<random>)
  bytes encrypted_rendezvous_data = 3;
}
