st-peter-client/proto/st-peter-auth.proto

syntax = "proto3";
package st_peter.auth;
option go_package = "nandie.com/pkg/;auth_service";
import "google/protobuf/timestamp.proto";

service AuthService {
  rpc RegisterUser (RegisterUserRequest) returns (RegisterUserResponse);
  rpc VerifyRegisterUser (VerifyRegisterUserRequest) returns (AuthenticationResponse);
  rpc Login (LoginRequest) returns (AuthenticationResponse);
  rpc Logout (LogoutRequest) returns (LogoutResponse);
  rpc VerifyToken (VerifyTokenRequest) returns (AuthenticationResponse);
  rpc VerifyAuthClaimToken (VerifyAuthClaimTokenRequest) returns (AuthenticationResponse);
  rpc InitiateTwoFactor (InitiateTwoFactorRequest) returns (InitiateTwoFactorResponse);
  rpc VerifyTwoFactor (VerifyTwoFactorRequest) returns (AuthenticationResponse);
  rpc InitiatePasswordReset (InitiatePasswordResetRequest) returns (PasswordResetTokenResponse);
  rpc VerifyPasswordResetToken (VerifyPasswordResetTokenRequest) returns (PasswordResetTokenResponse);
  rpc ResetPassword (ResetPasswordRequest) returns (AuthenticationResponse);
  rpc ResendVerificationCode (ResendVerificationRequest) returns (ResendVerificationResponse);
  rpc UpdateUserInfo (UpdateUserInfoRequest) returns (UpdateUserInfoResponse);
  rpc ChangeIdentityField (ChangeIdentityFieldRequest) returns (ChangeIdentityFieldResponse);
  rpc VerifyIdentityField (VerifyIdentityFieldRequest) returns (VerifyIdentityFieldResponse);
  rpc ResendIdentifierChangeCode(ResendIdentityFieldRequest) returns (ChangeIdentityFieldResponse);
  rpc UpdateUserPreference (UpdateUserPreferenceRequest) returns (OperationResponse);
  rpc GetUserPreferenceByCode (GetUserPreferenceByCodeRequest) returns (GetUserPreferenceByCodeResponse);
  rpc GetUserSessions(GetUserSessionsRequest) returns (GetUserSessionsResponse);
  rpc ClearUserSessions(ClearUserSessionsRequest) returns (ClearUserSessionsResponse);

  // Social login - Mobile flow (validates ID token from native SDK)
  rpc SocialLogin(SocialLoginRequest) returns (SocialLoginResponse);
  // Social login - Web OAuth flow
  rpc InitiateOAuth(InitiateOAuthRequest) returns (InitiateOAuthResponse);
  rpc CompleteOAuth(OAuthCallbackRequest) returns (SocialLoginResponse);
  // Account linking
  rpc LinkSocialAccount(LinkSocialAccountRequest) returns (OperationResponse);
  rpc UnlinkSocialAccount(UnlinkSocialAccountRequest) returns (OperationResponse);
  rpc GetLinkedAccounts(GetLinkedAccountsRequest) returns (GetLinkedAccountsResponse);

  // API Keys
  rpc CreateApiKey(CreateApiKeyRequest) returns (CreateApiKeyResponse);
  rpc ListApiKeys(ListApiKeysRequest) returns (ListApiKeysResponse);
  rpc RevokeApiKey(RevokeApiKeyRequest) returns (OperationResponse);
  rpc VerifyApiKey(VerifyApiKeyRequest) returns (AuthenticationResponse);

  // Password policy (public, no auth required)
  rpc GetPasswordPolicy(GetPasswordPolicyRequest) returns (GetPasswordPolicyResponse);

  // Metrics
  rpc GetMetrics(GetMetricsRequest) returns (GetMetricsResponse);

  // User lookup by identifier (email, phone, or handle) — any authenticated user
  rpc LookupUser(LookupUserRequest) returns (LookupUserResponse);
}

message Date {
  int32 year = 1;
  uint32 month = 2;
  uint32 day = 3;
}

enum ResultCode {
  RESULT_CODE_SUCCESS = 0;
  RESULT_CODE_NOT_FOUND = 1;
  RESULT_CODE_INTERNAL_SERVER_ERROR = 2;
  RESULT_CODE_BAD_REQUEST = 3;
  RESULT_CODE_NOT_AUTHORIZED = 4;
  RESULT_CODE_FORBIDDEN = 5;
  RESULT_CODE_VALIDATION_ERRORS = 6;
  RESULT_CODE_PASSCODE_REQUIRED = 7;
  RESULT_CODE_TOO_MANY_REQUESTS = 9;
  RESULT_CODE_INVALID_CREDENTIALS = 8;
  RESULT_CODE_INACTIVE_USER = 10;
  RESULT_CODE_IDENTITY_IN_USE = 11;
  RESULT_CODE_NEXT_STEP = 12;

}

enum ChannelType {
  CHANNEL_TYPE_UNSPECIFIED = 0;
  CHANNEL_TYPE_EMAIL = 1;
  CHANNEL_TYPE_SMS = 2;
}

enum VerificationCodeType {
  VERIFICATION_CODE_TYPE_UNSPECIFIED = 0;
  VERIFICATION_CODE_TYPE_REGISTER = 1;
  VERIFICATION_CODE_TYPE_PASSWORD_RESET = 2;
  VERIFICATION_CODE_TYPE_OTP_LOGIN = 3;
}

message User {
  string id = 1;
  string email = 2;
  string phone = 3;
  string first_names = 4;
  string last_name = 5;
  string profile_picture_url = 6;
  optional string handle = 7;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;
  google.protobuf.Timestamp deleted_at = 12;
  google.protobuf.Timestamp last_login = 13;
  bool is_active = 20;
  bool is_email_verified = 21;
  bool is_phone_verified = 22;
  Date date_of_birth = 23;
  int64 version = 24;
  repeated SocialAccount social_accounts = 30;
}

message UserPreference {
  string id = 1;
  string user_id = 2;
  string preference_code = 3;
  string preference_value_type = 4;
  string preference_value = 5;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;

}

message Role {
  string id = 1;
  string code = 2;
  string description = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp updated_at = 5;
}

message SocialAccount {
  string provider = 1;
  string provider_user_id = 2;
  string access_token = 3;
  google.protobuf.Timestamp expires_at = 4;
  string email = 5;
  string name = 6;
  string profile_picture_url = 7;
  bool email_verified = 8;
}

// OAuth Provider enumeration
enum OAuthProvider {
  OAUTH_PROVIDER_UNSPECIFIED = 0;
  OAUTH_PROVIDER_GOOGLE = 1;
  OAUTH_PROVIDER_APPLE = 2;
  OAUTH_PROVIDER_FACEBOOK = 3;
  OAUTH_PROVIDER_MICROSOFT = 4;
}

// Mobile flow - validate ID token from native SDK
message SocialLoginRequest {
  OAuthProvider provider = 1;
  string id_token = 2;           // JWT from Google/Apple SDK
  string access_token = 3;       // For Facebook
  DeviceInfo device_info = 4;
  string nonce = 5;              // For Apple Sign-In security
}

message SocialLoginResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  AuthenticatedUser authenticated_user = 4;
  bool is_new_user = 5;
  bool was_auto_linked = 6;
  repeated ValidationError validation_errors = 7;
}

// Web flow - initiate OAuth redirect
message InitiateOAuthRequest {
  OAuthProvider provider = 1;
  string redirect_uri = 2;
  string state = 3;              // Client-provided state for additional verification
}

message InitiateOAuthResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string authorization_url = 4;
  string state = 5;              // Server-generated state token
}

// Web flow - handle callback
message OAuthCallbackRequest {
  OAuthProvider provider = 1;
  string code = 2;
  string state = 3;
  DeviceInfo device_info = 4;
}

// Account linking
message LinkSocialAccountRequest {
  string actor_id = 1;
  string actor_token = 2;
  OAuthProvider provider = 3;
  string id_token = 4;
  string access_token = 5;
  string nonce = 6;              // For Apple Sign-In
}

message UnlinkSocialAccountRequest {
  string actor_id = 1;
  string actor_token = 2;
  OAuthProvider provider = 3;
}

message GetLinkedAccountsRequest {
  string actor_id = 1;
  string actor_token = 2;
}

message GetLinkedAccountsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated SocialAccount accounts = 4;
}

message RegisterUserRequest {
  string user_identifier = 1;
  string password = 2;
  string first_names = 4;
  string last_name = 5;
  string app_hash = 6;
  DeviceInfo device_info = 7;
}

message RegisterUserResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string registration_id = 4;
  repeated ValidationError validation_errors = 5;
}


message VerifyRegisterUserRequest {
  string user_identifier = 1; // Can be either email or phone
  string registration_id = 2;
  string token = 3;       //Token has a redirect to encoded in it.
  DeviceInfo device_info = 4;
}

message UserResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  User user = 4;
}

message DeviceInfo {
  string application_name = 1; // e.g., 'web', 'mobile'
  string application_version = 2; //e.g., '1.0.0'
  string device_name = 3; // e.g., 'iPhone X', 'Pixel 2'
  string device_type = 4; //  -- e.g., 'desktop', 'mobile'
  string device_os = 5; // e.   g., 'iOS', 'Android', 'Windows'
  string device_os_version = 6; // e.g., '10', '11.4.1'
  string device_id = 7; // e.g., 'imei:1234567890', 'serial:1234567890'
}

message LoginRequest {
  string user_identifier = 1; // Can be either email or phone
  string password = 2;
  string app_hash = 3;
  DeviceInfo device_info = 4;
}

message AuthenticationResponse {
  bool success = 1;
  bool pass_code_required = 2;
  string two_factor_id = 3;
  ResultCode result_code = 8;
  string message = 9;
  AuthenticatedUser authenticated_user = 10;
}

message AuthenticatedUser {
  User user = 1;
  string token = 2;
  string session_id = 3;
  google.protobuf.Timestamp expires_at = 4;
  repeated UserPreference user_preferences = 5;
  repeated AssignedUserRole user_roles = 11;
}

message AssignedUserRole {
  string id = 1;
  string user_id = 2;
  string role_id = 3;
  string role_name = 4;
  string scope_code = 5;
  string target_id = 6;
}

message VerifyTokenRequest {
  string token = 1;
  bool include_user_roles = 2;
  repeated string role_scopes = 3;
  repeated string role_names = 4;
}

message VerifyAuthClaimTokenRequest {
  string claim = 2;
}

message InitiateTwoFactorResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string two_factor_id = 4;
  ChannelType channel = 5;
  string user_id = 7;
  repeated ValidationError validation_errors = 6;
}

message VerifyTwoFactorResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated ValidationError validation_errors = 4;
}

message InitiateTwoFactorRequest {
  optional string user_id = 1;
  optional string user_identifier = 5; // Can be either email or phone
  ChannelType channel = 2;
  string app_hash = 3;
  DeviceInfo device_info = 4;
}

message VerifyTwoFactorRequest {
  string two_factor_id = 1;
  string code = 2;
  DeviceInfo device_info = 3;
}

message InitiatePasswordResetRequest {
  string user_identifier = 1; // Can be either email or phone
  string app_hash = 2;
  DeviceInfo device_info = 4;
  string new_password = 5;
}

message OperationResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
}

message VerifyPasswordResetTokenRequest {
  string user_id = 1;
  string password_reset_id = 2;
  string passcode = 3;
}

message PasswordResetTokenResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string password_reset_id = 4;
}

message ResetPasswordRequest {
  string user_id = 1;
  string password_reset_id = 2;
  string passcode = 3;
  DeviceInfo device_info = 4;
}

enum IdentityField {
  IDENTITY_FIELD_UNSPECIFIED = 0;
  IDENTITY_FIELD_EMAIL = 1;
  IDENTITY_FIELD_phone = 2;
  IDENTITY_FIELD_PASSWORD = 3;
  IDENTITY_FIELD_HANDLE = 4;
}

message ChangeIdentityFieldRequest {
  string user_id = 1;
  string user_token = 2;
  ChannelType channel = 3;
  string new_value = 4;
  IdentityField field_type = 5;
  string app_hash = 6;
  DeviceInfo device_info = 7;
}

message ChangeIdentityFieldResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;

  string challenge_id = 4;
  int32 passcode_size = 5;
  string user_identifier = 6;
  ChannelType channel = 7;
  repeated ValidationError validation_errors = 8;
}

message VerifyIdentityFieldRequest {
  string user_id = 1;
  string user_token = 2;
  string challenge_id = 4;
  string verification_code = 5;

  string app_hash = 6;
  DeviceInfo device_info = 7;
}

message ResendIdentityFieldRequest {
  string user_id = 1;
  string user_token = 2;
  string challenge_id = 4;

  string app_hash = 6;
  DeviceInfo device_info = 7;
}


message VerifyIdentityFieldResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;

  bool requires_verification = 8;
  string challenge_id = 4;
  int32 passcode_size = 5;
  string user_identifier = 6;
  ChannelType channel = 7;

  repeated ValidationError validation_errors = 9;
}

message UpdateUserInfoRequest {
  string user_id = 1;
  string user_token = 2;
  optional string first_names = 3;
  optional string last_name = 4;
  optional string profile_picture_id = 6;
  Date date_of_birth = 5;
  optional string handle = 7; // Optional unique handle (e.g., @username)
}

message UpdateUserInfoResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;

  User user = 4;
}

message LogoutRequest {
  string token = 1;
}

message LogoutResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
}

message ValidationError {
  string field = 1;
  string message = 2;
}

message Scope {
  string code = 1;
  string description = 2;
  optional string parent_code = 3;
  bool is_active = 4;
}

message UpdateUserPreferenceRequest {
    string actor_id = 1;
    string actor_token = 2;
    string preference_key = 3;
    string preference_value = 4;
}

message GetUserPreferenceByCodeRequest {
    string actor_id = 1;
    string actor_token = 2;
    string preference_code = 3;
}

message GetUserPreferenceByCodeResponse {
    bool success = 1;
    ResultCode result_code = 2;
    string message = 3;
    string value = 4;
}

message ResendVerificationRequest {
  string user_identifier = 1;
  VerificationCodeType verification_code_type = 2;
  string app_hash = 3;
  string verification_code_id = 4;
  DeviceInfo device_info = 19;
}

message ResendVerificationResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string verification_code_id = 4;
}

message UserSession {
  string id = 1;
  string user_id = 2;
  DeviceInfo device_info = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp expires_at = 5;
  google.protobuf.Timestamp last_activity = 6;
  bool is_active = 7;
  string ip_address = 8;
  string user_agent = 9;
}

message GetUserSessionsRequest {
  string actor_id = 1;
  string actor_token = 2;
  int32 page = 3;
  int32 size = 4;
}

message GetUserSessionsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated UserSession sessions = 4;
  int32 total = 5;
}

message ClearUserSessionsRequest {
  string actor_id = 1;
  string actor_token = 2;
  repeated string session_ids = 3; // If empty, clears all sessions except current
}

message ClearUserSessionsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  int32 cleared_count = 4;
}

// Metrics
message GetMetricsRequest {
  string bearer_token = 1;
}

message GetMetricsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string metrics = 4; // Prometheus text format
}

// API Key messages
message CreateApiKeyRequest {
  string token = 1;       // existing session token for auth
  string name = 2;
  repeated string scopes = 3;
  int64 expires_at = 4;   // 0 = never
}

message CreateApiKeyResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  string api_key = 4;     // full key, shown ONCE
  string key_id = 5;
  string key_prefix = 6;
}

message ListApiKeysRequest {
  string token = 1;
}

message ListApiKeysResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated ApiKeyInfo keys = 4;
}

message ApiKeyInfo {
  string id = 1;
  string name = 2;
  string key_prefix = 3;
  repeated string scopes = 4;
  int64 last_used_at = 5;
  int64 expires_at = 6;
  int64 created_at = 7;
  bool is_active = 8;
}

message RevokeApiKeyRequest {
  string token = 1;
  string key_id = 2;
}

message VerifyApiKeyRequest {
  string api_key = 1;
}

// Password policy
message GetPasswordPolicyRequest {}

message GetPasswordPolicyResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  uint32 min_length = 4;
  bool requires_uppercase = 5;
  bool requires_special_character = 6;
}

// Lookup user by exact identifier (email, phone number, or handle)
message LookupUserRequest {
  string user_id = 1;
  string user_token = 2;
  string identifier = 3; // email, phone number, or handle
}

message LookupUserResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  optional User user = 4;
}