Quelle  url-payloads.proto  Sprache: unbekannt

// # 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 share the same URI scheme regardless of which
// OnPrem server they use.
//
// A _White-Labeled OnPrem_ flavour must define a custom URI scheme that
// **MUST** fulfill the following rules:
//
// - It must be a valid URI scheme.
// - It shall not use any of the [IANA registered URI
//   schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml).
// - It shall not contain the string `threema`, nor shall it contain a string
//   resembling the name _Threema_ (e.g. `threeema`, `thr33m4`, etc).
// - It is recommended to further read and understand [RFC 7595, sec
//   3.8](https://datatracker.ietf.org/doc/html/rfc7595#section-3.8) when
//   picking a custom URI scheme.
//
// 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 in the
// following way:
//
// 1. Return the concatenation of the following strings¹:
//    - the _Custom URI Scheme_,
//    - the path `'device-group/join'`, 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 invitation URL to join a conference call.
//
// The following steps define the _Conference Call 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 (including the
//    _White-Labeled OnPrem_ flavour), return the URL defined by the OPPF
//    configuration (if any).
//
// When creating a new conference invitation:
//
// 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's 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 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 privileges 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;
}