// # 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.
//
// ## Threema Custom URI Scheme
//
// The following maps application flavours to custom URI schemes and the result
// is defined as the _Custom URI Scheme_:
//
// - Consumer: `threema://`
// - Work: `threemawork://`
// - Green: `threemagreen://`
// - Blue: `threemablue://`
// - OnPrem: `threemaonprem://`
//
// _OnPrem_ flavoured applications (including the _White-Labeled OnPrem_
// flavour) share the same custom URI regardless of which OnPrem server they
// use.
//
// Note: In general, deep links should have a fallback URL using the custom URI
// scheme. However, some usages of custom URIs do intentionally not provide a
// deep link variant.

syntax = "proto3";

package url;

option java_package = "ch.threema.protobuf.url";
option java_multiple_files = true;
option php_namespace = "Threema\\Protocols\\Url";

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

// 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:
//
// 1. Return the concatenation of the following strings¹:
//    - the _Custom URI Scheme_,
//    - the path `'device-group', and
//    - the URL fragment `#<url-safe-base64(DeviceGroupJoinRequestOrOffer)>`.
//
// ¹: For example, for the _Consumer_ application flavour the result could be
// `'threema://device-group/join#00112233..'`.
//
// When processing an offer or request to join the device group:
//
// 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.
  d2d_rendezvous.RendezvousInit rendezvous_init = 3;
}

// Conference invitiation URL to join a conference call.
//
// The following steps define the _Conference Call Base URL_:
//
// 1. If the application is built for the _Consumer_ or _Work_ flavour, return
//    the URL `https://conference.threema.ch/join`.
// 2. If the application is built for the _Green_ or _Blue_ flavour, return the
//    URL `https://conference.test.threema.ch/join`.
// 3. If the application is built for the _OnPrem_ flavour, return the URL
//    defined by the OPPF configuration (if any).
//
// When creating a new conference invitiation:
//
// 1. Let `conference-url` be the _Conference Call URL_.
// 2. If `conference-url` is not defined, disallow creation and abort these
//    steps.
// 3. Return `conference-url` concatenated with the URL fragment
//    `#<url-safe-base64(ConferenceCallInvite)>` (i.e. the URL-safe Base64
//    encoded `ConferenceCallInvite` in the URL fragment).
//
// The following steps are defined as the _Conference Call URL Transformation
// Steps_ and should be run when a URI is encountered in a message text:
//
// 1. Let `uri` be the URI to analyse.
// 2. Let `conference-url` be the _Conference Call URL_.
// 3. If `conference-url` is not defined, return that no conference call URL was
//    detected and abort these steps.¹
// 4. Let `conference-fallback-url` be the concatenation of the _Custom URI
//    Scheme_ and the path `'conference/join'` (e.g.
//    `'threema://conference/join'` for _Consumer_ builds).
// 5. Let `uri-without-fragment` be `uri` including all URI components but the
//    fragment prefix (i.e. `#`) and the fragment itself.
// 6. If `uri-without-fragment` does not equal `conference-url` and does not
//    equal `conference-fallback-url, return that no conference call URL was
//    detected and abort these steps.
// 7. Decode the Base64 encoded `ConferenceCallInvite` message contained in
//    `uri`s fragment and let `invite` be that message. If it cannot be decoded,
//    return that the conference call URL is faulty and abort these steps.
// 8. If the hostname of `invite.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, return that the conference call URL is faulty and abort
//    these steps.
// 9. Return a transformation containing all necessary data based on `uri` and
//    `invite` for the UI to produce a special conference call hypertext from
//    it, so the user can _join_ and _peek_ the conference call.
//
// ¹: This intentionally disregards potential matches of the fallback URL since
// lack of presence of the _Conference Call Base URL_ indicates that conference
// calls are not supported.
//
// Note: The universal URL is generally preferred but the website that is
// hosting conference calls for external guest participants will also present
// the non-universal URL with the Threema custom URI scheme as a fallback
// solution to open the conference call in a Threema application without deep
// link support. Both variants should be processed and transformed equally in
// the clients.
message ConferenceCallInvite {
  // Protocol version used for this conference call. The current version number
  // is `1`.
  uint32 protocol_version = 1;

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

  // The public key associated to the Group Call Moderator Message Key (`GCMMK`) used for moderation
  // of this call.
  bytes gcmmk_public = 3;

  // The policy to apply to guest participants (i.e. non-Threema users).
  //
  // IMPORTANT: The concrete numeric values defined here are used to derive the Group Call ID and
  // must remain stable!
  enum GuestPolicy {
    // Guest participants are not allowed.
    DENY_GUESTS = 0;

    // Guest participants are allowed without any restrictions.
    ALLOW_GUESTS = 1;
  }
  GuestPolicy guest_policy = 4;

  // The join policy to apply to newly joining participants.
  //
  // IMPORTANT: The concrete numeric values defined here are used to derive the Group Call ID and
  // must remain stable!
  enum JoinPolicy {
    // New participants may participate immediately without any restrictions.
    UNRESTRICTED = 0;

    // New participants that do not have moderator priviledges need to wait for approval of a
    // moderator to participate. Moderators may participate immediately (so long they announce
    // themselves as moderators).
    REQUIRES_MODERATOR_APPROVAL= 1;
  }
  JoinPolicy join_policy = 5;

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