syntax = "proto3";

import "harmonytypes/v1/types.proto";

package protocol.auth.v1;

option go_package = "github.com/harmony-development/legato/gen/auth/v1";

// Used in `BeginAuth` endpoint.
message BeginAuthRequest {}

// BeginAuthResponse
// The return type of BeginAuth, containing the
// auth_id that will be used for the authentication
// section
message BeginAuthResponse {
  // auth_id: the ID of this auth session
  string auth_id = 1;
}

// Session
// Session contains the information for a new session;
// the user_id you logged in as and the session_token
// which should be passed to authorisation
message Session {
  // user_id: the ID of the user you logged in as
  uint64 user_id = 1;
  // session_token: the session token to use in authorization
  string session_token = 2;
}

// AuthStep
// A step in the authentication process
// Contains a variety of different types of views
// It is recommended to have a fallback_url specified
// For non-trivial authentication procedures (such as captchas)
message AuthStep {
  // Choice
  // A step which allows the user to choose from a range of options
  // Allows you to show a heading by specifying title
  message Choice {
    // title: the title of the list of choices
    string title = 1;
    // options: a list of choices, one of these
    // should be sent in nextstep
    repeated string options = 2;
  }

  // Form
  // A step which requires the user to input information
  // Allows you to show a heading by specifying title
  message Form {
    // FormField
    // A field in the form, containing information on how it should
    // be rendered
    // Here is a list of form types that need to be supported:
    // email: a field type that has to contain a valid email
    // password: a field type that has to contain a password
    // new-password: a field type for new passwords
    // text: a field type that has to contain text
    // number: a field type that has to contain a number
    message FormField {
      // name: the identifier for the form field
      string name = 1;
      // type: the type of the form field, as documented above
      string type = 2;
    }

    // title: the title of this form
    string title = 1;

    // fields: all the fields in this form
    repeated FormField fields = 2;
  }

  // Waiting
  // A step which requires the user to perform an external action
  // The title and description should explain to the user
  // what they should do to complete this step
  message Waiting {
    // title: the title of this waiting screen
    string title = 1;
    // description: the explanation of what's being waited on
    string description = 2;
  }

  // fallback_url: unused
  string fallback_url = 1;
  // can_go_back: whether or not the client can request the
  // server to send the previous step
  bool can_go_back = 2;

  // step: the current step
  oneof step {
    // choice: the user must pick a thing out of a list of options
    Choice choice = 3;
    // form: the user must complete a form
    Form form = 4;
    // session: you've completed auth, and have a session
    Session session = 5;
    // waiting: you're waiting on something
    Waiting waiting = 6;
  }
}

// NextStepRequest
// contains the client's response to the server's challenge
// This needs to be called first with no arguments to
// receive the first step
message NextStepRequest {
  // auth_id: the authentication session you want
  // the next step of
  string auth_id = 1;

  // A simple choice string indicating which option the user chose
  message Choice {
    // choice: the choice the user picked
    string choice = 1;
  }

  // Form fields can either be bytes, string, or int64.
  message FormFields {
    // field: the data for a form field
    oneof field {
      // bytes: the form field's data is a byte array
      bytes bytes = 1;
      // string: the form field's data is a string
      string string = 2;
      // number: the form field's data is a number
      int64 number = 3;
    }
  }

  // An array of form fields, in the same order they came in from the server
  message Form {
    // fields: the fields the user filled out
    repeated FormFields fields = 1;
  }

  // step: the user's response to a step
  oneof step {
    // choice: the choice the user picked
    Choice choice = 2;
    // form: the form the user filled out
    Form form = 3;
  }
}

// Used in `NextStep` endpoint.
message NextStepResponse {
  // step: the next step in the authentication process
  AuthStep step = 1;
}

// StepBackRequest
// A request to go back 1 step
message StepBackRequest {
  // auth_id: the authentication session the user
  // wants to go back in
  string auth_id = 1;
}
// Used in `StepBack` endpoint.
message StepBackResponse {
  // step: the previous step in the authentication process
  AuthStep step = 1;
}

// StreamStepsRequest
// Required to be initiated by all authenticating clients
// Allows the server to send steps
message StreamStepsRequest {
  // auth_id: the authorization session
  // who's steps you want to stream
  string auth_id = 1;
}
// Used in `StreamSteps` endpoint.
message StreamStepsResponse {
  // step: the next step in the authentication process
  AuthStep step = 1;
}

// The request to federate with a foreign server.
message FederateRequest {
  // The server ID foreign server you want to federate with
  string server_id = 1;
}

// The reply to a successful federation request,
// containing the token you need to present to the
// foreign server.
message FederateResponse {
  // A `harmonytypes.v1.Token` whose `data` field is a serialized `TokenData` message.
  // It is signed with the homeserver's private key.
  harmonytypes.v1.Token token = 1;
}

// Used in `Key` endpoint.
message KeyRequest {}

// Contains a key's bytes.
message KeyResponse {
  // key: the bytes of the public key.
  bytes key = 1;
}

// Log into a foreignserver using a token
// from your homeserver, obtained through a FederateRequest
message LoginFederatedRequest {
  // A `harmonytypes.v1.Token` whose `data` field is a serialized `TokenData` message.
  // It is signed with the homeserver's private key.
  harmonytypes.v1.Token auth_token = 1;
  // The server ID of the homeserver that the auth token is from
  string server_id = 2;
}

// Used in `LoginFederated` endpoint.
message LoginFederatedResponse {
  // The user's session.
  Session session = 1;
}

// Information sent by a client's homeserver, in a `harmonytypes.v1.Token`.
// It will be sent to a foreignserver by the client.
message TokenData {
  // The client's user ID on the homeserver.
  uint64 user_id = 1;
  // The foreignserver's server ID.
  string server_id = 2;
  // The username of the client.
  string username = 3;
  // The avatar of the client.
  optional string avatar = 4;
}

// Used in `CheckLoggedIn` endpoint.
message CheckLoggedInRequest {}
// Used in `CheckLoggedIn` endpoint.
message CheckLoggedInResponse {}

// # Federation
//
// Servers should generate and persist an Ed25519 public and private
// key. These will be referred to later on simply as the public
// and private keys of the server.
//
// Federate is the core of Harmony's federation model.
// The client sends the server name of the foreignserver
// to its homeserver using the Federate method.
//
// The homeserver generates a `harmonytypes.v1.Token`, where the `data` field
// contains a serialized `TokenData` message.
// The private key used to sign is the homeserver's private key.
//
// The target should be the foreignserver's server name.
// The user ID should be the client's user ID on the homeserver.
// The username and avatar should be the client's username and avatar,
// so the foreignserver knows what username and avatar to give them.
//
// The client will use this token in a LoginFederatedRequest request
// and send it to the foreignserver as the auth_token field, with the
// domain field filled out to the server name of the homeserver.
//
// TODO: finish

// The service containing authorization/entication methods
service AuthService {
  // Federate with a foreignserver, obtaining a token
  // you can use to call LoginFederated on it
  rpc Federate(FederateRequest) returns (FederateResponse);
  // Present a token to a foreignserver from a Federate call
  // on your homeserver in order to login
  rpc LoginFederated(LoginFederatedRequest) returns (LoginFederatedResponse);
  // Returns the public key of this server
  rpc Key(KeyRequest) returns (KeyResponse);
  // Begins an authentication session
  rpc BeginAuth(BeginAuthRequest) returns (BeginAuthResponse);
  // Goes to the next step of the authentication session,
  // possibly presenting user input
  rpc NextStep(NextStepRequest) returns (NextStepResponse);
  // Goes to the previous step of the authentication session
  // if possible
  rpc StepBack(StepBackRequest) returns (StepBackResponse);
  // Consume the steps of an authentication session
  // as a stream
  rpc StreamSteps(StreamStepsRequest) returns (stream StreamStepsResponse);
  // Check whether or not you're logged in and the session is valid
  rpc CheckLoggedIn(CheckLoggedInRequest) returns (CheckLoggedInResponse) {
    option (harmonytypes.v1.metadata).requires_authentication = true;
    option (harmonytypes.v1.metadata).requires_permission_node = "";
  }
}