Signal-Server/service/src/main/proto/RegistrationService.proto

syntax = "proto3";

option java_multiple_files = true;

package org.signal.registration.rpc;

service RegistrationService {
  /**
   * Create a new registration session for a given destination phone number.
   */
  rpc create_session (CreateRegistrationSessionRequest) returns (CreateRegistrationSessionResponse) {}

  /**
   * Sends a verification code to a destination phone number within the context
   * of a previously-created registration session.
   */
  rpc send_verification_code (SendVerificationCodeRequest) returns (SendVerificationCodeResponse) {}

  /**
   * Checks a client-provided verification code for a given registration
   * session.
   */
  rpc check_verification_code (CheckVerificationCodeRequest) returns (CheckVerificationCodeResponse) {}
}

message CreateRegistrationSessionRequest {
  /**
   * The phone number for which to create a new registration session.
   */
  uint64 e164 = 1;
}

message CreateRegistrationSessionResponse {
  oneof response {
    /**
     * Metadata for the newly-created session.
     */
    RegistrationSessionMetadata session_metadata = 1;

    /**
     * A response explaining why a session could not be created as requested.
     */
    CreateRegistrationSessionError error = 2;
  }
}

message RegistrationSessionMetadata {
  /**
   * An opaque sequence of bytes that uniquely identifies the registration
   * session associated with this registration attempt.
   */
  bytes session_id = 1;

  /**
   * Indicates whether a valid verification code has been submitted in the scope
   * of this session.
   */
  bool verified = 2;
}

message CreateRegistrationSessionError {
  /**
   * The type of error that prevented a session from being created.
   */
  CreateRegistrationSessionErrorType error_type = 1;

  /**
   * Indicates that this error may succeed if retried without modification after
   * a delay indicated by `retry_after_seconds`. If false, callers should not
   * retry the request without modification.
   */
  bool may_retry = 2;

  /**
   * If this error may be retried,, indicates the duration in seconds from the
   * present after which the request may be retried without modification. This
   * value has no meaning otherwise.
   */
  uint64 retry_after_seconds = 3;
}

enum CreateRegistrationSessionErrorType {
  CREATE_REGISTRATION_SESSION_ERROR_TYPE_UNSPECIFIED = 0;

  /**
   * Indicates that a session could not be created because too many requests to
   * create a session for the given phone number have been received in some
   * window of time. Callers should wait and try again later.
   */
  CREATE_REGISTRATION_SESSION_ERROR_TYPE_RATE_LIMITED = 1;

  /**
   * Indicates that the provided phone number could not be parsed.
   */
  CREATE_REGISTRATION_SESSION_ERROR_TYPE_ILLEGAL_PHONE_NUMBER = 2;
}

message SendVerificationCodeRequest {

  reserved 1;

  /**
   * The message transport to use to send a verification code to the destination
   * phone number.
   */
  MessageTransport transport = 2;

  /**
   * A prioritized list of languages accepted by the destination; should be
   * provided in the same format as the value of an HTTP Accept-Language header.
   */
  string accept_language = 3;

  /**
   * The type of client requesting a verification code.
   */
  ClientType client_type = 4;

  /**
   * The ID of a session within which to send (or re-send) a verification code.
   */
  bytes session_id = 5;

  /**
   * If provided, always attempt to use the specified sender to send
   * this message.
   */
  string sender_name = 6;
}

enum MessageTransport {
  MESSAGE_TRANSPORT_UNSPECIFIED = 0;
  MESSAGE_TRANSPORT_SMS = 1;
  MESSAGE_TRANSPORT_VOICE = 2;
}

enum ClientType {
  CLIENT_TYPE_UNSPECIFIED = 0;
  CLIENT_TYPE_IOS = 1;
  CLIENT_TYPE_ANDROID_WITH_FCM = 2;
  CLIENT_TYPE_ANDROID_WITHOUT_FCM = 3;
}

message SendVerificationCodeResponse {
  /**
   * An opaque sequence of bytes that uniquely identifies the registration
   * session associated with this registration attempt.
   */
  bytes session_id = 1;

  /**
   * Metadata for the named session. May be absent if the session could not be
   * found or has expired.
   */
  RegistrationSessionMetadata session_metadata = 2;

  /**
   * If a code could not be sent, explains the underlying error. Will be absent
   * if a code was sent successfully. Note that both an error and session
   * metadata may be present in the same response because the session metadata
   * may include information helpful for resolving the underlying error (i.e.
   * "next attempt" times).
   */
  SendVerificationCodeError error = 3;
}

message SendVerificationCodeError {
  /**
   * The type of error that prevented a verification code from being sent.
   */
  SendVerificationCodeErrorType error_type = 1;

  /**
   * Indicates that this error may succeed if retried without modification after
   * a delay indicated by `retry_after_seconds`. If false, callers should not
   * retry the request without modification.
   */
  bool may_retry = 2;

  /**
   * If this error may be retried,, indicates the duration in seconds from the
   * present after which the request may be retried without modification. This
   * value has no meaning otherwise.
   */
  uint64 retry_after_seconds = 3;
}

enum SendVerificationCodeErrorType {
  SEND_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;

  /**
   * The sender received and understood the request to send a verification code,
   * but declined to do so (i.e. due to rate limits or suspected fraud).
   */
  SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_REJECTED = 1;

  /**
   * The sender could not process or would not accept some part of a request
   * (e.g. a valid phone number that cannot receive SMS messages).
   */
  SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_ILLEGAL_ARGUMENT = 2;

  /**
   * A verification could could not be sent via the requested channel due to
   * timing/rate restrictions. The response object containing this error should
   * include session metadata that indicates when the next attempt is allowed.
   */
  SEND_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 3;

  /**
   * No session was found with the given ID.
   */
  SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 4;

  /**
   * A new verification could could not be sent because the session has already
   * been verified.
   */
  SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_ALREADY_VERIFIED = 5;
}

message CheckVerificationCodeRequest {
  /**
   * The session ID returned when sending a verification code.
   */
  bytes session_id = 1;

  /**
   * The client-provided verification code.
   */
  string verification_code = 2;
}

message CheckVerificationCodeResponse {
  /**
   * The outcome of the verification attempt; true if the verification code
   * matched the expected code or false otherwise.
   */
  bool verified = 1;

  /**
   * Metadata for the named session. May be absent if the session could not be
   * found or has expired.
   */
  RegistrationSessionMetadata session_metadata = 2;

  /**
   * If a code could not be checked, explains the underlying error. Will be
   * absent if no error occurred. Note that both an error and session
   * metadata may be present in the same response because the session metadata
   * may include information helpful for resolving the underlying error (i.e.
   * "next attempt" times).
   */
  CheckVerificationCodeError error = 3;
}

message CheckVerificationCodeError {
  /**
   * The type of error that prevented a verification code from being checked.
   */
  CheckVerificationCodeErrorType error_type = 1;

  /**
   * Indicates that this error may succeed if retried without modification after
   * a delay indicated by `retry_after_seconds`. If false, callers should not
   * retry the request without modification.
   */
  bool may_retry = 2;

  /**
   * If this error may be retried,, indicates the duration in seconds from the
   * present after which the request may be retried without modification. This
   * value has no meaning otherwise.
   */
  uint64 retry_after_seconds = 3;
}

enum CheckVerificationCodeErrorType {
  CHECK_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;

  /**
   * The caller has made too many incorrect guesses within the scope of this
   * session and may not make any further guesses.
   */
  CHECK_VERIFICATION_CODE_ERROR_TYPE_ATTEMPTS_EXHAUSTED = 1;

  /**
   * The caller has attempted to submit a verification code even though no
   * verification codes have been sent within the scope of this session. The
   * caller must issue a "send code" request before trying again.
   */
  CHECK_VERIFICATION_CODE_ERROR_TYPE_NO_CODE_SENT = 2;

  /**
   * The caller has made too many guesses within some period of time. Callers
   * should wait for the duration prescribed in the session metadata object
   * elsewhere in the response before trying again.
   */
  CHECK_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 3;

  /**
   * The session identified in this request could not be found (possibly due to
   * session expiration).
   */
  CHECK_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 4;
}