st-peter-client/proto/st-peter-admin.proto

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

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

service AuthAdminService {
  rpc GetUser (GetUserRequest) returns (UserResponse);
  rpc GetUsers (GetUsersRequest) returns (UsersResponse);
  // System-token-authed minimal lookup: id + display name ONLY (no PII).
  // Auth is the shared system token alone (no actor) — internal services only,
  // so viewing content (e.g. history) can't be used to harvest user info.
  rpc GetUsersData (GetUsersDataRequest) returns (GetUsersDataResponse);
  rpc GetUsersByUsernames(GetUsersByUsernamesRequest) returns (UsersResponse);
  rpc DeleteUser (DeleteUserRequest) returns (OperationResponse);
  rpc RestoreUser (RestoreUserRequest) returns (OperationResponse);
  rpc AssignRoleToUser (AssignRoleRequest) returns (GetUserWithRolesResponse);
  rpc UnassignRoleFromUser (UnassignRoleRequest) returns (GetUserWithRolesResponse);
  rpc GetRoleDetails (GetRoleDetailsRequest) returns (GetRoleDetailsResponse);
  rpc GetRole(GetRoleRequest) returns (GetRoleResponse);
  rpc GetUserRole(GetUserRoleRequest) returns (GetUserRoleResponse);
  rpc SearchUsers (SearchUsersRequest) returns (SearchUsersResponse);
  rpc CountUsers (CountUsersRequest) returns (CountUsersResponse);
  rpc SearchRoles (SearchRolesRequest) returns (SearchRolesResponse);
  rpc GetRoleScopes (GetRoleScopesRequest) returns (GetRoleScopesResponse);
  rpc GetUserWithRoles (GetUserWithRolesRequest) returns (GetUserWithRolesResponse);
  rpc GetAssignableRoles (GetAssignableRolesRequest) returns (GetAssignableRolesResponse);
  rpc UpdateUserInfo (UpdateUserInfoRequest) returns (UpdateUserInfoResponse);
  rpc GetScopeAncestors (GetScopeAncestorsRequest) returns (GetScopeAncestorsResponse);
  rpc GetScopeDescendants (GetScopeDescendantsRequest) returns (GetScopeDescendantsResponse);
  rpc GetAssignableTargets (GetAssignableTargetsRequest) returns (GetAssignableTargetsResponse);
  rpc GetUsersByRole (GetUsersByRoleRequest) returns (GetUsersByRoleResponse);
  rpc CreateUser (CreateUserRequest) returns (CreateUserResponse);
  rpc GetUserSessions (GetUserSessionsRequest) returns (GetUserSessionsResponse);
  rpc ClearUserSessions (ClearUserSessionsRequest) returns (ClearUserSessionsResponse);
}

enum ResultCode {
  RESULT_CODE_SUCCESS = 0;
  RESULT_CODE_BAD_INPUT = 1;
  RESULT_CODE_NOT_FOUND = 2;
  RESULT_CODE_INTERNAL_SERVER_ERROR = 3;
  RESULT_CODE_NOT_AUTHORIZED = 4; // User is not authenticated
  RESULT_CODE_FORBIDDEN = 5; // User is authenticated but lacks required permissions
}

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

message RegisterUserRequest {
  string email = 1;
  string password = 2;
  string phone = 3;
  string first_name = 4;
  string last_name = 5;
}

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

message LoginRequest {
  string email = 1;
  string password = 2;
}

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

message GetUserRequest {
  string user_id = 1;

  string actor_id = 11;
  string actor_token = 12;
}

message GetUsersByUsernamesRequest {
  repeated string email_addresses = 2;
  repeated string phone_numbers = 3;
  string actor_id = 11;
  string actor_token = 12;
}

message DeleteUserRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 3;
  string reason = 4;
  string user_agent = 5;
  bool unassign_roles = 6;
}

message RestoreUserRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 3;
  string reason = 4;
  string user_agent = 5;
  bool restore_roles = 6;
}

message AssignRoleRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 5;
  string role_id = 6;
  string scope_code = 7;
  optional string target_id = 8;
  google.protobuf.Timestamp expires_at = 9;
  string session_id = 10;
}

message UnassignRoleRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 5;
  string user_role_id = 6;
  string reason = 7;
}

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

message SearchUsersRequest {
  string actor_id = 1;
  string actor_token = 2;

  optional string email = 3;
  optional string phone = 4;
  optional string search = 11;

  int32 page = 12;
  int32 page_size = 13;
  bool include_inactive = 14;
}

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

message TimeSeriesStatistic {
  uint32 count = 1;
  int64 year = 3;
  uint32 month = 4;
  uint32 day = 5;
  uint32 hour = 6;
}

message CountUsersResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  uint32 grand_total = 4;
  Date current_date = 7;
  repeated TimeSeriesStatistic daily = 5; // 30 past days
  repeated TimeSeriesStatistic monthly = 6; // 12 months
}

message SearchUsersResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated User users = 4;
  int32 total = 5;
}


message SearchRolesRequest {
  string actor_id = 1;
  string actor_token = 2;

  string search = 11;
  int32 page = 12;
  int32 page_size = 13;
}


message SearchRolesResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated Role roles = 4;
  int32 total = 5;
}

message GetRoleScopesRequest {
  string actor_id = 1;
  string actor_token = 2;
  optional string role_id = 3;
  optional string scope_code = 4;
}

message GetRoleScopesResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated RoleScope role_scopes = 4;
  map<string, Role> roles = 5;
}

message Lookup {
  string code = 1;
  string name = 2;
  string description = 3;
}

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

message GetUserWithRolesRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 3;
  bool include_inactive = 4;
  repeated string scope_codes = 5;
  repeated string role_names = 6;
}

message GetUserWithRolesResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  User user = 4;
  map<string, Role> roles = 5;
  repeated UserRole assigned_roles = 6;
  map<string, Scope> scopes = 7;
  map<string, User> actors = 8;
}

message UserRole {
  string id =1;
  string user_id = 2;
  string role_id = 3;
  string scope_code = 4;
  optional string target_id = 5;
  bool is_active = 6;

  google.protobuf.Timestamp created_at = 11;
  string created_by = 12;
  google.protobuf.Timestamp updated_at = 13;
  string updated_by = 14;
  google.protobuf.Timestamp expires_at = 15;
  google.protobuf.Timestamp deleted_at = 16;
  optional string deleted_by = 17;
}

message GetUsersRequest {
  string actor_id = 1;
  string actor_token = 2;
  repeated string user_ids = 3;
}

message UsersResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated User users = 4;
}

// GetUsersData — system-token-only, returns the MINIMUM for display: id + a
// resolved display name. Deliberately omits email/phone/PII so even a trusted
// internal caller can't harvest contact info through it.
message GetUsersDataRequest {
  string system_token = 1;
  repeated string user_ids = 2;
}

message UserData {
  string id = 1;
  string name = 2;
}

message GetUsersDataResponse {
  bool success = 1;
  repeated UserData users = 2;
}

message GetAssignableRolesRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_id = 3;
}

message ScopeList {
  repeated string scope_codes = 1;
}

message GetAssignableRolesResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated RoleScopeTarget roles = 4;
  repeated Scope scopes = 5;
  map<string, ScopeList> role_scopes = 6;
}

message RoleScopeTarget {
  Role role = 1;
  Scope scope = 2;
  string target_id = 3;
  google.protobuf.Timestamp expires_at = 7;
}

message GetRoleDetailsRequest{
  string actor_id = 1;
  string actor_token = 2;
  string role_id = 3;
}

message RoleScope {
  string id = 1;
  string role_id = 2;
  string scope_code = 3;
  bool is_active = 4;
}

message GetRoleDetailsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  Role role = 4;
  repeated UserRole assigned_roles = 5;
  repeated Scope scopes = 6;
  repeated User actors = 7;
  repeated RoleScope role_scopes = 8;
}

message GetRoleRequest {
  string actor_id = 1;
  string actor_token = 2;
  string role_id = 3;
}

message GetRoleResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  Role role = 4;
}

message GetUserRoleRequest {
  string actor_id = 1;
  string actor_token = 2;
  string user_role_id = 3;
}

message GetUserRoleResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  UserRole user_role = 4;
  Role role = 5;
  Scope scope = 6;
}

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

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

  User user = 4;
}

message GetScopeAncestorsRequest {
  string actor_id = 1;
  string actor_token = 2;
  string scope_code = 3;
}

message GetScopeAncestorsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated Scope ancestors = 4;
}

message GetScopeDescendantsRequest {
  string actor_id = 1;
  string actor_token = 2;
  string scope_code = 3;
}

message GetScopeDescendantsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated Scope descendants = 4;
}

message GetAssignableTargetsRequest {
  string actor_id = 1;
  string actor_token = 2;
  string scope_code = 3;
}

message GetAssignableTargetsResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated string target_ids = 4;
  bool all_targets_permissible = 5;
}

message GetUsersByRoleRequest {
  string actor_id = 1;
  string actor_token = 2;
  string role_id = 3;
  optional string scope_code = 4;
  optional string target_id = 5;
  bool include_inactive = 6;
}

message GetUsersByRoleResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  repeated User users = 4;
  int32 total = 5;
}

message CreateUserRequest {
  string actor_id = 1;
  string actor_token = 2;

  optional string email = 3;
  optional string phone = 4;
  string first_names = 5;
  string last_name = 6;
  string profile_picture_url = 7;
  optional string password = 8; // Optional, if not provided, a random password will be generated and returned.
  optional Date date_of_birth = 9;
  optional string handle = 10; // Optional unique handle (e.g., @username)
}
message CreateUserResponse {
  bool success = 1;
  ResultCode result_code = 2;
  string message = 3;
  User user = 4;
  optional string password = 5; // Only returned if a new password was generated
}

message DeviceInfo {
  string application_name = 1;
  string application_version = 2;
  string device_name = 3;
  string device_type = 4;
  string device_os = 5;
  string device_os_version = 6;
  string device_id = 7;
}

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;
  string user_id = 3; // The user whose sessions to retrieve
  int32 page = 4;
  int32 size = 5;
}

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;
  string user_id = 3; // The user whose sessions should be cleared
  repeated string session_ids = 4; // If empty, clears all sessions for the user
}

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