auth.proto

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 {
  // If provided, this is the guest token
  // for the account being upgraded from
  // a guest account to a full account
  // during the auth flow.
  //
  // This token is provided by the server
  // at the end of the auth flow that
  // created the guest account.
  optional string for_guest_token = 1;
}

// 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 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;
  // A token allowing for this account to be upgraded to a
  // "full" account by beginning an auth session and providing
  // this token.
  //
  // The guest token only exists to upgrade a guest account to a full
  // account, and does not permit logging in with a guest account
  // on more than one session.
  //
  // A "guest token" MAY be provided to BeginAuth to begin
  // an authorization process that will upgrade the guest account
  // to a full account if completed successfully.
  // This MUST only affect now being able to log
  // into the account with more than one session, and MUST not
  // change other information about the account, such as username
  // and password.
  optional string guest_token = 3;
}

// 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 {
  // 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;
  }

  // A step which requires the user to input information
  // Allows you to show a heading by specifying title.
  message Form {
    // 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;
  }
}

// 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;
}

// 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;
}

// 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. This must be a HMC that points to an image.
  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 = "";
  }
}