// Copyright 2026 MOIA GmbH

syntax = "proto3";

package moia.trip.authentication.v1;

option go_package = "./authenticationv1";
option java_multiple_files = false;
option java_outer_classname = "BoardingAuthenticationServiceV1";
option java_package = "io.moia.protos.trip.authentication.v1";

// The BoardingAuthenticationService offers functionality to authenticate for autonomous trips ordered via the TripStateService.
service BoardingAuthenticationService {
  // Lists boarding authentication methods available on the vehicle assigned to the trip.
  // Only relevant for autonomous vehicles.
  //
  // This is a customer-scoped endpoint.
  // The ID of the customer on behalf of whom the operation is requested needs to be provided in the request header (`"Customer-Id: <your-customer-id>"`).
  //
  // Fails with `PERMISSION_DENIED` with the following reasons:
  // * `CUSTOMER_ID_MISSING` if the customer ID is not present in the request header.
  // * `CUSTOMER_UNAUTHENTICATED` if the trip does not belong to the provided customer or the customer does not exist.
  //
  // Fails with `INVALID_ARGUMENT` with the following reasons:
  // * `INVALID_PAGE_SIZE` if the `page_size` is less than zero.
  // * `INVALID_PAGE_TOKEN` if the `page_token` does not match previous requests.
  //
  // Fails with `NOT_FOUND` with the reason `TRIP_NOT_FOUND` if there is no trip for the requested trip ID.
  rpc ListBoardingAuthenticationMethods(ListBoardingAuthenticationMethodsRequest) returns (ListBoardingAuthenticationMethodsResponse);
  // Authenticates the customer for boarding the vehicle.
  // Only relevant for autonomous vehicles and the boarding authentication method `ApiBoardingAuthentication`.
  //
  // This is a customer-scoped endpoint.
  // The ID of the customer on behalf of whom the operation is requested needs to be provided in the request header (`"Customer-Id: <your-customer-id>"`).
  //
  // Fails with `PERMISSION_DENIED` with the following reasons:
  // * `CUSTOMER_ID_MISSING` if the customer ID is not present in the request header.
  // * `CUSTOMER_UNAUTHENTICATED` if the trip does not belong to the provided customer or the customer does not exist.
  //
  // Fails with `NOT_FOUND` with the reason `TRIP_NOT_FOUND` if there is no trip for the requested trip ID.
  //
  // Fails with `FAILED_PRECONDITION` with the reason `TRIP_STATE_INVALID` if the trip is not in `StateInFulfillment.PHASE_READY_FOR_BOARDING_AUTHENTICATION`.
  rpc AuthenticateForBoarding(AuthenticateForBoardingRequest) returns (AuthenticateForBoardingResponse);
}

// Request message for listing the boarding authentication methods available on the vehicle assigned to the trip.
message ListBoardingAuthenticationMethodsRequest {
  // The ID of the trip for which to list the boarding authentication methods.
  string trip_id = 1;
  // The maximum number of boarding authentication methods to return.
  // The service may return fewer than this value.
  // If unspecified or set to zero, at most 50 boarding authentication methods will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  // Negative values won't be accepted.
  optional int32 page_size = 2;
  // A page token, received from a previous `ListBoardingAuthenticationMethods` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListBoardingAuthenticationMethods` must match
  // the call that provided the page token.
  optional string page_token = 3;
}

// Returns boarding authentication methods available on the vehicle assigned to the trip.
message ListBoardingAuthenticationMethodsResponse {
  // List of boarding authentication methods from which one needs to be chosen to authenticate for boarding.
  repeated BoardingAuthenticationMethod boarding_authentication_methods = 1;
  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  optional string next_page_token = 2;
}

// Request message for authenticating the customer for boarding an autonomous vehicle.
message AuthenticateForBoardingRequest {
  // The ID of the trip the customer wants to authenticate for.
  string trip_id = 1;
  // The boarding authentication token provided on the vehicle.
  string token = 2;
}

// Response to a successful boarding authentication request.
message AuthenticateForBoardingResponse {}

// A method for authenticating when boarding an autonomous vehicle.
message BoardingAuthenticationMethod {
  // The boarding authentication method is one of the following methods.
  oneof boarding_authentication_method {
    // API boarding authentication is always available as a fallback boarding authentication method.
    ApiBoardingAuthentication api_boarding_authentication = 1;
  }
}

// The boarding authentication method where a token is displayed on the vehicle.
// The customer authenticates by sending the token via the Trip API using the `AuthenticateForBoarding` RPC.
message ApiBoardingAuthentication {}