@aepstore-dev/contracts 1.107.0 → 1.108.1

package/proto/auth.proto

@@ -1,417 +1,417 @@
-syntax = "proto3";
-
-package auth.v1;
-
-// Ported from legacy auth-service (@MessagePattern → @GrpcMethod).
-// Tokens are HMAC primitives from @aepstore-dev/passport:
-//   - access token: short TTL, carries userId; the gateway validates it
-//     locally via PassportAuthGuard (no round-trip here).
-//   - refresh token: long TTL HMAC + a RefreshToken DB row (device list +
-//     revocation). Refresh verifies the HMAC AND that the row still exists.
-service AuthService {
-    rpc Login(LoginRequest) returns (AuthResult);
-    rpc Register(RegisterRequest) returns (AuthResult);
-    rpc CreateCode(CreateCodeRequest) returns (AuthResult);
-    rpc VerifyCode(VerifyCodeRequest) returns (AuthResult);
-    rpc CheckToken(CheckTokenRequest) returns (AuthUser);
-    rpc RefreshToken(RefreshTokenRequest) returns (AuthResult);
-    rpc Get2faStatus(Get2faStatusRequest) returns (TwoFactorStatusResponse);
-    rpc GetProfile(GetProfileRequest) returns (AuthUser);
-    rpc CleanupExpiredTotpSetups(Empty) returns (Empty);
-    rpc ResetUserTwoFactor(ResetUserTwoFactorRequest) returns (ResetUserTwoFactorResponse);
-    rpc GeneratePasskeyRegistrationOptions(GeneratePasskeyRegistrationOptionsRequest) returns (PasskeyOptionsResponse);
-    rpc VerifyPasskeyRegistration(VerifyPasskeyRegistrationRequest) returns (PasskeyRegistrationResponse);
-    rpc ListPasskeys(ListPasskeysRequest) returns (ListPasskeysResponse);
-    rpc DeletePasskey(DeletePasskeyRequest) returns (DeletePasskeyResponse);
-    rpc GeneratePasskeyAuthenticationOptions(GeneratePasskeyAuthenticationOptionsRequest) returns (PasskeyOptionsResponse);
-    rpc VerifyPasskeyAuthentication(VerifyPasskeyAuthenticationRequest) returns (AuthResult);
-
-    // First-party OAuth 2.0 provider. Authorization codes use PKCE S256;
-    // access/refresh tokens are opaque, scoped and independently revocable.
-    rpc ValidateOAuthAuthorizationRequest(ValidateOAuthAuthorizationRequestInput) returns (OAuthAuthorizationRequestInfo);
-    rpc CreateOAuthAuthorizationCode(CreateOAuthAuthorizationCodeRequest) returns (CreateOAuthAuthorizationCodeResponse);
-    rpc ExchangeOAuthToken(ExchangeOAuthTokenRequest) returns (OAuthTokenResponse);
-    rpc GetOAuthUserInfo(OAuthResourceRequest) returns (OAuthUserInfoResponse);
-    rpc ListOAuthProducts(OAuthResourceRequest) returns (OAuthProductsResponse);
-    rpc ListOAuthAuthorizations(ListOAuthAuthorizationsRequest) returns (ListOAuthAuthorizationsResponse);
-    rpc RevokeOAuthAuthorization(RevokeOAuthAuthorizationRequest) returns (RevokeOAuthAuthorizationResponse);
-
-    // Logout — kill refresh tokens. LogoutCurrent kills only the one whose
-    // HMAC matches; LogoutAll wipes every row for the user.
-    rpc LogoutCurrent(LogoutCurrentRequest) returns (LogoutResponse);
-    rpc LogoutAll(LogoutAllRequest) returns (LogoutResponse);
-
-    // Self-service restore. Verifies credentials + password against a
-    // soft-deleted user, clears deletedAt/scheduledForHardDelete, and issues
-    // fresh tokens — the one auth path that DOES read deletedAt accounts.
-    rpc RestoreLogin(RestoreLoginRequest) returns (AuthResult);
-
-    // Login history. Read-only audit feed for the settings page; rows come
-    // from LoginEvent. Internal alternative: tasks-service GC.
-    rpc ListLoginHistory(ListLoginHistoryRequest) returns (ListLoginHistoryResponse);
-}
-
-enum TwoFactorType {
-    NONE = 0;
-    APP = 1;
-    EMAIL = 2;
-}
-
-// ---------------------------------------------------------------------------
-// Requests
-// ---------------------------------------------------------------------------
-
-// Login by username OR email (one of the two must be set).
-message LoginRequest {
-    string password = 1;
-    string credentials = 2; // username OR email — resolved by the service
-    // Gateway-supplied audit context. LoginEvent rows for LOGIN /
-    // PASSWORD_FAIL get the same ip/user-agent that REFRESH and RESTORE
-    // already carry; the gRPC layer has no transport-level access to
-    // either, so the gateway extracts them from the HTTP request.
-    string user_agent = 3;
-    string ip = 4;
-    string trusted_device_token = 5;
-}
-
-message RegisterRequest {
-    string email = 1;
-    string username = 2;
-    string password = 3;
-    string ip = 4; // optional, attached by gateway from req
-    string user_agent = 5; // optional, attached by gateway from req
-}
-
-// type ∈ { twofa, reset, totp_generate, confirm } (legacy strings)
-message CreateCodeRequest {
-    string email = 1;
-    string type = 2;
-}
-
-// type ∈ { twofa, twofa_activate, twofa_deactivate, reset, totp, totp_activate,
-//          totp_deactivate, backup, regenerate_backup, confirm }
-// regenerate_backup expects a current TOTP code, not an existing backup code.
-// new_password is only used by the 'reset' flow.
-message VerifyCodeRequest {
-    string email = 1;
-    string code = 2;
-    string type = 3;
-    string new_password = 4; // optional
-    string challenge_id = 5;
-    bool remember_device = 6;
-    string user_agent = 7;
-    string ip = 8;
-    // Internal service-to-service confirmation for sensitive account actions.
-    // Public login completions must use challenge_id instead.
-    bool account_verification = 9;
-}
-
-message CheckTokenRequest {
-    string token = 1;
-}
-
-message RefreshTokenRequest {
-    string refresh_token = 1;
-    string user_agent = 2; // optional
-    string ip = 3;         // optional
-}
-
-message Get2faStatusRequest {
-    string username = 1;
-}
-
-message GetProfileRequest {
-    string user_id = 1;
-}
-
-message ResetUserTwoFactorRequest {
-    string target_user_id = 1;
-    string admin_id = 2;
-    string reason = 3;
-}
-
-message GeneratePasskeyRegistrationOptionsRequest {
-    string user_id = 1;
-}
-
-message VerifyPasskeyRegistrationRequest {
-    string user_id = 1;
-    string challenge_id = 2;
-    // Raw JSON returned by @simplewebauthn/browser startRegistration().
-    string response_json = 3;
-    string name = 4;
-}
-
-message ListPasskeysRequest {
-    string user_id = 1;
-}
-
-message DeletePasskeyRequest {
-    string user_id = 1;
-    string passkey_id = 2;
-}
-
-message GeneratePasskeyAuthenticationOptionsRequest {
-    reserved 1;
-    reserved "credentials";
-    string user_agent = 2;
-    string ip = 3;
-}
-
-message VerifyPasskeyAuthenticationRequest {
-    string challenge_id = 1;
-    // Raw JSON returned by @simplewebauthn/browser startAuthentication().
-    string response_json = 2;
-    string user_agent = 3;
-    string ip = 4;
-}
-
-message CreateOAuthAuthorizationCodeRequest {
-    string user_id = 1;
-    string response_type = 2;
-    string client_id = 3;
-    string redirect_uri = 4;
-    repeated string scopes = 5;
-    string code_challenge = 6;
-    string code_challenge_method = 7;
-}
-
-message ValidateOAuthAuthorizationRequestInput {
-    string response_type = 1;
-    string client_id = 2;
-    string redirect_uri = 3;
-    repeated string scopes = 4;
-    string code_challenge = 5;
-    string code_challenge_method = 6;
-}
-
-message OAuthAuthorizationRequestInfo {
-    string client_id = 1;
-    string client_name = 2;
-    string redirect_uri = 3;
-    repeated string scopes = 4;
-}
-
-message CreateOAuthAuthorizationCodeResponse {
-    string code = 1;
-    string redirect_uri = 2;
-    int32 expires_in = 3;
-}
-
-message ExchangeOAuthTokenRequest {
-    string grant_type = 1;
-    string code = 2;
-    string refresh_token = 3;
-    string client_id = 4;
-    string client_secret = 5;
-    string redirect_uri = 6;
-    string code_verifier = 7;
-}
-
-message OAuthTokenResponse {
-    string access_token = 1;
-    string token_type = 2;
-    int32 expires_in = 3;
-    string refresh_token = 4;
-    string scope = 5;
-}
-
-message OAuthResourceRequest {
-    string access_token = 1;
-}
-
-message OAuthPremiumInfo {
-    bool active = 1;
-    string expires_at = 2;
-}
-
-message OAuthUserInfoResponse {
-    string id = 1;
-    string email = 2;
-    string username = 3;
-    string full_name = 4;
-    string avatar_url = 5;
-    OAuthPremiumInfo premium = 6;
-}
-
-message OAuthProduct {
-    string id = 1;
-    string name = 2;
-    string description = 3;
-    string preview = 4;
-    string price = 5;
-    string currency = 6;
-    string public_url = 7;
-    string moderation_status = 8;
-}
-
-message OAuthProductsResponse {
-    repeated OAuthProduct items = 1;
-}
-
-message ListOAuthAuthorizationsRequest {
-    string user_id = 1;
-}
-
-message OAuthAuthorization {
-    string client_id = 1;
-    string client_name = 2;
-    repeated string scopes = 3;
-    string granted_at = 4;
-    string last_used_at = 5;
-}
-
-message ListOAuthAuthorizationsResponse {
-    repeated OAuthAuthorization items = 1;
-}
-
-message RevokeOAuthAuthorizationRequest {
-    string user_id = 1;
-    string client_id = 2;
-}
-
-message RevokeOAuthAuthorizationResponse {
-    bool revoked = 1;
-    int32 revoked_tokens = 2;
-}
-
-// ---------------------------------------------------------------------------
-// Responses
-// ---------------------------------------------------------------------------
-
-message AuthUser {
-    string id = 1;
-    string username = 2;
-    string email = 3;
-    string avatar_url = 4;
-    string banner_url = 5;
-    repeated string roles = 6;
-    // Reserved: 7=role, 8=is_verified, 9=two_factor_type, 10=two_factor_enabled,
-    // 11=balance. Dropped in contracts 1.51.0 — clients read 2FA flags from
-    // AuthResult / /account/settings, balance from /payments/wallet.
-    reserved 7, 8, 9, 10, 11;
-    reserved "role", "is_verified", "two_factor_type", "two_factor_enabled", "balance";
-    string avatar_border = 12;
-}
-
-// Unified result for login/register/createCode/verifyCode/refresh. Which fields
-// are populated depends on the flow:
-//   - fully authenticated → access_token + refresh_token + expires_in + user
-//   - 2FA required / pending confirm → message + two_factor_required + two_factor_type + user (no tokens)
-//   - totp_generate → secret + otpauth + qr (+ user)
-//   - totp_activate → backup_codes (+ tokens/user)
-message AuthResult {
-    string access_token = 1;
-    string refresh_token = 2;
-    int32 expires_in = 3;
-    AuthUser user = 4;
-
-    string message = 5;
-    // Renamed from `requires_2fa` in 1.52.0: the digit-after-underscore broke
-    // the grpc proto-loader's camelCase pass (`_2` isn't `_<letter>`), so the
-    // wire key stayed snake_case and never matched the camelCase handler output
-    // → always serialised false. `two_factor_required` camelCases cleanly to
-    // `twoFactorRequired` on every layer. Field number 6 is unchanged (wire-
-    // compatible).
-    bool two_factor_required = 6;
-    TwoFactorType two_factor_type = 7;
-
-    // TOTP setup extras
-    string secret = 8;
-    string otpauth = 9;
-    string qr = 10; // data URL (PNG)
-    repeated string backup_codes = 11;
-    string challenge_id = 12;
-    string trusted_device_token = 13;
-    string trusted_device_expires_at = 14;
-    bool security_setup_required = 15;
-}
-
-message TwoFactorStatusResponse {
-    TwoFactorType two_factor_type = 1;
-    bool has_2fa = 2;
-    bool is_verified = 3;
-}
-
-message Empty {}
-
-message LogoutCurrentRequest {
-    string refresh_token = 1;
-}
-
-message LogoutAllRequest {
-    string user_id = 1;
-    // Current session's refresh token — excluded from the wipe so "log out
-    // everywhere" keeps THIS device signed in. Empty = revoke every session.
-    string refresh_token = 2;
-}
-
-message LogoutResponse {
-    bool ok = 1;
-    int32 removed = 2; // number of refresh-token rows deleted
-}
-
-message ResetUserTwoFactorResponse {
-    bool ok = 1;
-    TwoFactorType previous_type = 2;
-    int32 revoked_sessions = 3;
-}
-
-message PasskeyOptionsResponse {
-    // PublicKeyCredentialCreationOptionsJSON or PublicKeyCredentialRequestOptionsJSON.
-    string options_json = 1;
-    string challenge_id = 2;
-}
-
-message PasskeyInfo {
-    string id = 1;
-    string name = 2;
-    string created_at = 3;
-    string last_used_at = 4;
-    string device_type = 5;
-    bool backed_up = 6;
-    repeated string transports = 7;
-}
-
-message PasskeyRegistrationResponse {
-    bool ok = 1;
-    PasskeyInfo passkey = 2;
-}
-
-message ListPasskeysResponse {
-    repeated PasskeyInfo items = 1;
-}
-
-message DeletePasskeyResponse {
-    bool ok = 1;
-}
-
-message RestoreLoginRequest {
-    string credentials = 1; // email or username
-    string password = 2;
-    string user_agent = 3;
-    string ip = 4;
-}
-
-message ListLoginHistoryRequest {
-    string user_id = 1;
-    int32 page = 2;
-    int32 limit = 3;
-}
-
-message LoginEventRow {
-    string id = 1;
-    string type = 2;       // LOGIN | LOGOUT | REFRESH | TWO_FA_FAIL | PASSWORD_FAIL | BLOCKED | RESTORE
-    bool success = 3;
-    string reason = 4;
-    string ip = 5;
-    string user_agent = 6;
-    string created_at = 7;
-}
-
-message ListLoginHistoryResponse {
-    repeated LoginEventRow items = 1;
-    int32 total = 2;
-    int32 page = 3;
-    int32 limit = 4;
-}
+syntax = "proto3";
+
+package auth.v1;
+
+// Ported from legacy auth-service (@MessagePattern → @GrpcMethod).
+// Tokens are HMAC primitives from @aepstore-dev/passport:
+//   - access token: short TTL, carries userId; the gateway validates it
+//     locally via PassportAuthGuard (no round-trip here).
+//   - refresh token: long TTL HMAC + a RefreshToken DB row (device list +
+//     revocation). Refresh verifies the HMAC AND that the row still exists.
+service AuthService {
+    rpc Login(LoginRequest) returns (AuthResult);
+    rpc Register(RegisterRequest) returns (AuthResult);
+    rpc CreateCode(CreateCodeRequest) returns (AuthResult);
+    rpc VerifyCode(VerifyCodeRequest) returns (AuthResult);
+    rpc CheckToken(CheckTokenRequest) returns (AuthUser);
+    rpc RefreshToken(RefreshTokenRequest) returns (AuthResult);
+    rpc Get2faStatus(Get2faStatusRequest) returns (TwoFactorStatusResponse);
+    rpc GetProfile(GetProfileRequest) returns (AuthUser);
+    rpc CleanupExpiredTotpSetups(Empty) returns (Empty);
+    rpc ResetUserTwoFactor(ResetUserTwoFactorRequest) returns (ResetUserTwoFactorResponse);
+    rpc GeneratePasskeyRegistrationOptions(GeneratePasskeyRegistrationOptionsRequest) returns (PasskeyOptionsResponse);
+    rpc VerifyPasskeyRegistration(VerifyPasskeyRegistrationRequest) returns (PasskeyRegistrationResponse);
+    rpc ListPasskeys(ListPasskeysRequest) returns (ListPasskeysResponse);
+    rpc DeletePasskey(DeletePasskeyRequest) returns (DeletePasskeyResponse);
+    rpc GeneratePasskeyAuthenticationOptions(GeneratePasskeyAuthenticationOptionsRequest) returns (PasskeyOptionsResponse);
+    rpc VerifyPasskeyAuthentication(VerifyPasskeyAuthenticationRequest) returns (AuthResult);
+
+    // First-party OAuth 2.0 provider. Authorization codes use PKCE S256;
+    // access/refresh tokens are opaque, scoped and independently revocable.
+    rpc ValidateOAuthAuthorizationRequest(ValidateOAuthAuthorizationRequestInput) returns (OAuthAuthorizationRequestInfo);
+    rpc CreateOAuthAuthorizationCode(CreateOAuthAuthorizationCodeRequest) returns (CreateOAuthAuthorizationCodeResponse);
+    rpc ExchangeOAuthToken(ExchangeOAuthTokenRequest) returns (OAuthTokenResponse);
+    rpc GetOAuthUserInfo(OAuthResourceRequest) returns (OAuthUserInfoResponse);
+    rpc ListOAuthProducts(OAuthResourceRequest) returns (OAuthProductsResponse);
+    rpc ListOAuthAuthorizations(ListOAuthAuthorizationsRequest) returns (ListOAuthAuthorizationsResponse);
+    rpc RevokeOAuthAuthorization(RevokeOAuthAuthorizationRequest) returns (RevokeOAuthAuthorizationResponse);
+
+    // Logout — kill refresh tokens. LogoutCurrent kills only the one whose
+    // HMAC matches; LogoutAll wipes every row for the user.
+    rpc LogoutCurrent(LogoutCurrentRequest) returns (LogoutResponse);
+    rpc LogoutAll(LogoutAllRequest) returns (LogoutResponse);
+
+    // Self-service restore. Verifies credentials + password against a
+    // soft-deleted user, clears deletedAt/scheduledForHardDelete, and issues
+    // fresh tokens — the one auth path that DOES read deletedAt accounts.
+    rpc RestoreLogin(RestoreLoginRequest) returns (AuthResult);
+
+    // Login history. Read-only audit feed for the settings page; rows come
+    // from LoginEvent. Internal alternative: tasks-service GC.
+    rpc ListLoginHistory(ListLoginHistoryRequest) returns (ListLoginHistoryResponse);
+}
+
+enum TwoFactorType {
+    NONE = 0;
+    APP = 1;
+    EMAIL = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+// Login by username OR email (one of the two must be set).
+message LoginRequest {
+    string password = 1;
+    string credentials = 2; // username OR email — resolved by the service
+    // Gateway-supplied audit context. LoginEvent rows for LOGIN /
+    // PASSWORD_FAIL get the same ip/user-agent that REFRESH and RESTORE
+    // already carry; the gRPC layer has no transport-level access to
+    // either, so the gateway extracts them from the HTTP request.
+    string user_agent = 3;
+    string ip = 4;
+    string trusted_device_token = 5;
+}
+
+message RegisterRequest {
+    string email = 1;
+    string username = 2;
+    string password = 3;
+    string ip = 4; // optional, attached by gateway from req
+    string user_agent = 5; // optional, attached by gateway from req
+}
+
+// type ∈ { twofa, reset, totp_generate, confirm } (legacy strings)
+message CreateCodeRequest {
+    string email = 1;
+    string type = 2;
+}
+
+// type ∈ { twofa, twofa_activate, twofa_deactivate, reset, totp, totp_activate,
+//          totp_deactivate, backup, regenerate_backup, confirm }
+// regenerate_backup expects a current TOTP code, not an existing backup code.
+// new_password is only used by the 'reset' flow.
+message VerifyCodeRequest {
+    string email = 1;
+    string code = 2;
+    string type = 3;
+    string new_password = 4; // optional
+    string challenge_id = 5;
+    bool remember_device = 6;
+    string user_agent = 7;
+    string ip = 8;
+    // Internal service-to-service confirmation for sensitive account actions.
+    // Public login completions must use challenge_id instead.
+    bool account_verification = 9;
+}
+
+message CheckTokenRequest {
+    string token = 1;
+}
+
+message RefreshTokenRequest {
+    string refresh_token = 1;
+    string user_agent = 2; // optional
+    string ip = 3;         // optional
+}
+
+message Get2faStatusRequest {
+    string username = 1;
+}
+
+message GetProfileRequest {
+    string user_id = 1;
+}
+
+message ResetUserTwoFactorRequest {
+    string target_user_id = 1;
+    string admin_id = 2;
+    string reason = 3;
+}
+
+message GeneratePasskeyRegistrationOptionsRequest {
+    string user_id = 1;
+}
+
+message VerifyPasskeyRegistrationRequest {
+    string user_id = 1;
+    string challenge_id = 2;
+    // Raw JSON returned by @simplewebauthn/browser startRegistration().
+    string response_json = 3;
+    string name = 4;
+}
+
+message ListPasskeysRequest {
+    string user_id = 1;
+}
+
+message DeletePasskeyRequest {
+    string user_id = 1;
+    string passkey_id = 2;
+}
+
+message GeneratePasskeyAuthenticationOptionsRequest {
+    reserved 1;
+    reserved "credentials";
+    string user_agent = 2;
+    string ip = 3;
+}
+
+message VerifyPasskeyAuthenticationRequest {
+    string challenge_id = 1;
+    // Raw JSON returned by @simplewebauthn/browser startAuthentication().
+    string response_json = 2;
+    string user_agent = 3;
+    string ip = 4;
+}
+
+message CreateOAuthAuthorizationCodeRequest {
+    string user_id = 1;
+    string response_type = 2;
+    string client_id = 3;
+    string redirect_uri = 4;
+    repeated string scopes = 5;
+    string code_challenge = 6;
+    string code_challenge_method = 7;
+}
+
+message ValidateOAuthAuthorizationRequestInput {
+    string response_type = 1;
+    string client_id = 2;
+    string redirect_uri = 3;
+    repeated string scopes = 4;
+    string code_challenge = 5;
+    string code_challenge_method = 6;
+}
+
+message OAuthAuthorizationRequestInfo {
+    string client_id = 1;
+    string client_name = 2;
+    string redirect_uri = 3;
+    repeated string scopes = 4;
+}
+
+message CreateOAuthAuthorizationCodeResponse {
+    string code = 1;
+    string redirect_uri = 2;
+    int32 expires_in = 3;
+}
+
+message ExchangeOAuthTokenRequest {
+    string grant_type = 1;
+    string code = 2;
+    string refresh_token = 3;
+    string client_id = 4;
+    string client_secret = 5;
+    string redirect_uri = 6;
+    string code_verifier = 7;
+}
+
+message OAuthTokenResponse {
+    string access_token = 1;
+    string token_type = 2;
+    int32 expires_in = 3;
+    string refresh_token = 4;
+    string scope = 5;
+}
+
+message OAuthResourceRequest {
+    string access_token = 1;
+}
+
+message OAuthPremiumInfo {
+    bool active = 1;
+    string expires_at = 2;
+}
+
+message OAuthUserInfoResponse {
+    string id = 1;
+    string email = 2;
+    string username = 3;
+    string full_name = 4;
+    string avatar_url = 5;
+    OAuthPremiumInfo premium = 6;
+}
+
+message OAuthProduct {
+    string id = 1;
+    string name = 2;
+    string description = 3;
+    string preview = 4;
+    string price = 5;
+    string currency = 6;
+    string public_url = 7;
+    string moderation_status = 8;
+}
+
+message OAuthProductsResponse {
+    repeated OAuthProduct items = 1;
+}
+
+message ListOAuthAuthorizationsRequest {
+    string user_id = 1;
+}
+
+message OAuthAuthorization {
+    string client_id = 1;
+    string client_name = 2;
+    repeated string scopes = 3;
+    string granted_at = 4;
+    string last_used_at = 5;
+}
+
+message ListOAuthAuthorizationsResponse {
+    repeated OAuthAuthorization items = 1;
+}
+
+message RevokeOAuthAuthorizationRequest {
+    string user_id = 1;
+    string client_id = 2;
+}
+
+message RevokeOAuthAuthorizationResponse {
+    bool revoked = 1;
+    int32 revoked_tokens = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
+message AuthUser {
+    string id = 1;
+    string username = 2;
+    string email = 3;
+    string avatar_url = 4;
+    string banner_url = 5;
+    repeated string roles = 6;
+    // Reserved: 7=role, 8=is_verified, 9=two_factor_type, 10=two_factor_enabled,
+    // 11=balance. Dropped in contracts 1.51.0 — clients read 2FA flags from
+    // AuthResult / /account/settings, balance from /payments/wallet.
+    reserved 7, 8, 9, 10, 11;
+    reserved "role", "is_verified", "two_factor_type", "two_factor_enabled", "balance";
+    string avatar_border = 12;
+}
+
+// Unified result for login/register/createCode/verifyCode/refresh. Which fields
+// are populated depends on the flow:
+//   - fully authenticated → access_token + refresh_token + expires_in + user
+//   - 2FA required / pending confirm → message + two_factor_required + two_factor_type + user (no tokens)
+//   - totp_generate → secret + otpauth + qr (+ user)
+//   - totp_activate → backup_codes (+ tokens/user)
+message AuthResult {
+    string access_token = 1;
+    string refresh_token = 2;
+    int32 expires_in = 3;
+    AuthUser user = 4;
+
+    string message = 5;
+    // Renamed from `requires_2fa` in 1.52.0: the digit-after-underscore broke
+    // the grpc proto-loader's camelCase pass (`_2` isn't `_<letter>`), so the
+    // wire key stayed snake_case and never matched the camelCase handler output
+    // → always serialised false. `two_factor_required` camelCases cleanly to
+    // `twoFactorRequired` on every layer. Field number 6 is unchanged (wire-
+    // compatible).
+    bool two_factor_required = 6;
+    TwoFactorType two_factor_type = 7;
+
+    // TOTP setup extras
+    string secret = 8;
+    string otpauth = 9;
+    string qr = 10; // data URL (PNG)
+    repeated string backup_codes = 11;
+    string challenge_id = 12;
+    string trusted_device_token = 13;
+    string trusted_device_expires_at = 14;
+    bool security_setup_required = 15;
+}
+
+message TwoFactorStatusResponse {
+    TwoFactorType two_factor_type = 1;
+    bool has_2fa = 2;
+    bool is_verified = 3;
+}
+
+message Empty {}
+
+message LogoutCurrentRequest {
+    string refresh_token = 1;
+}
+
+message LogoutAllRequest {
+    string user_id = 1;
+    // Current session's refresh token — excluded from the wipe so "log out
+    // everywhere" keeps THIS device signed in. Empty = revoke every session.
+    string refresh_token = 2;
+}
+
+message LogoutResponse {
+    bool ok = 1;
+    int32 removed = 2; // number of refresh-token rows deleted
+}
+
+message ResetUserTwoFactorResponse {
+    bool ok = 1;
+    TwoFactorType previous_type = 2;
+    int32 revoked_sessions = 3;
+}
+
+message PasskeyOptionsResponse {
+    // PublicKeyCredentialCreationOptionsJSON or PublicKeyCredentialRequestOptionsJSON.
+    string options_json = 1;
+    string challenge_id = 2;
+}
+
+message PasskeyInfo {
+    string id = 1;
+    string name = 2;
+    string created_at = 3;
+    string last_used_at = 4;
+    string device_type = 5;
+    bool backed_up = 6;
+    repeated string transports = 7;
+}
+
+message PasskeyRegistrationResponse {
+    bool ok = 1;
+    PasskeyInfo passkey = 2;
+}
+
+message ListPasskeysResponse {
+    repeated PasskeyInfo items = 1;
+}
+
+message DeletePasskeyResponse {
+    bool ok = 1;
+}
+
+message RestoreLoginRequest {
+    string credentials = 1; // email or username
+    string password = 2;
+    string user_agent = 3;
+    string ip = 4;
+}
+
+message ListLoginHistoryRequest {
+    string user_id = 1;
+    int32 page = 2;
+    int32 limit = 3;
+}
+
+message LoginEventRow {
+    string id = 1;
+    string type = 2;       // LOGIN | LOGOUT | REFRESH | TWO_FA_FAIL | PASSWORD_FAIL | BLOCKED | RESTORE
+    bool success = 3;
+    string reason = 4;
+    string ip = 5;
+    string user_agent = 6;
+    string created_at = 7;
+}
+
+message ListLoginHistoryResponse {
+    repeated LoginEventRow items = 1;
+    int32 total = 2;
+    int32 page = 3;
+    int32 limit = 4;
+}