@aepstore-dev/contracts 1.102.0 → 1.104.0

package/proto/auth.proto

@@ -1,20 +1,20 @@
-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);
+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);
@@ -25,45 +25,53 @@ service AuthService {
     rpc DeletePasskey(DeletePasskeyRequest) returns (DeletePasskeyResponse);
     rpc GeneratePasskeyAuthenticationOptions(GeneratePasskeyAuthenticationOptionsRequest) returns (PasskeyOptionsResponse);
     rpc VerifyPasskeyAuthentication(VerifyPasskeyAuthenticationRequest) returns (AuthResult);
-
-    // 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).
+
+    // 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);
+
+    // 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
+    // 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;
@@ -71,13 +79,13 @@ message RegisterRequest {
     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;
-}
-
+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.
@@ -95,21 +103,21 @@ message VerifyCodeRequest {
     // 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 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;
 }
@@ -142,9 +150,10 @@ message DeletePasskeyRequest {
 }
 
 message GeneratePasskeyAuthenticationOptionsRequest {
-    // Username or email. V1 requires an existing account identifier and does
-    // not implement passkey-first/account-discovery registration.
-    string credentials = 1;
+    reserved 1;
+    reserved "credentials";
+    string user_agent = 2;
+    string ip = 3;
 }
 
 message VerifyPasskeyAuthenticationRequest {
@@ -154,11 +163,94 @@ message VerifyPasskeyAuthenticationRequest {
     string user_agent = 3;
     string ip = 4;
 }
-
-// ---------------------------------------------------------------------------
-// Responses
-// ---------------------------------------------------------------------------
-
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
 message AuthUser {
     string id = 1;
     string username = 2;
@@ -166,39 +258,39 @@ message AuthUser {
     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
+    // 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;
+
+// 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;
@@ -206,26 +298,26 @@ message AuthResult {
     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 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
@@ -265,33 +357,33 @@ message ListPasskeysResponse {
 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;
-}
+
+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;
+}

package/proto/mail.proto

@@ -1,54 +1,54 @@
-syntax = "proto3";
-
-package mail.v1;
-
-// Legacy mail-service used @EventPattern (fire-and-forget). In the new gRPC
-// stack each becomes a unary RPC that returns an Ack. Callers ignore the
-// response if they don't care about delivery.
-service MailService {
-    rpc SendReg(SendRegRequest) returns (MailAck);
-    rpc Send2fa(Send2faRequest) returns (MailAck);
-    rpc SendPasswordReset(SendPasswordResetRequest) returns (MailAck);
-    rpc SendRegistrationConfirm(SendRegistrationConfirmRequest) returns (MailAck);
-
-    // GDPR data-export delivery — tasks-service fires after the JSON dump
-    // lands in S3; mail-service sends the signed URL with a sensible TTL note.
-    rpc SendDataExportReady(SendDataExportReadyRequest) returns (MailAck);
-}
-
-message MailAck {
-    bool queued = 1;
-}
-
-message SendRegRequest {
-    string user_id = 1;
-    string email = 2;
-    string username = 3;
-    string full_name = 4;
-}
-
-message Send2faRequest {
-    string email = 1;
-    string code = 2;
-    string username = 3;
-}
-
-message SendPasswordResetRequest {
-    string email = 1;
-    string code = 2;
-    string username = 3;
-}
-
-message SendRegistrationConfirmRequest {
-    string email = 1;
-    string code = 2;
-    string username = 3;
-}
-
-message SendDataExportReadyRequest {
-    string email = 1;
-    string username = 2;
-    string file_url = 3;     // signed S3 URL
-    int32 url_ttl_hours = 4; // for the message body
-    int32 file_size = 5;
-}
+syntax = "proto3";
+
+package mail.v1;
+
+// Legacy mail-service used @EventPattern (fire-and-forget). In the new gRPC
+// stack each becomes a unary RPC that returns an Ack. Callers ignore the
+// response if they don't care about delivery.
+service MailService {
+    rpc SendReg(SendRegRequest) returns (MailAck);
+    rpc Send2fa(Send2faRequest) returns (MailAck);
+    rpc SendPasswordReset(SendPasswordResetRequest) returns (MailAck);
+    rpc SendRegistrationConfirm(SendRegistrationConfirmRequest) returns (MailAck);
+
+    // GDPR data-export delivery — tasks-service fires after the JSON dump
+    // lands in S3; mail-service sends the signed URL with a sensible TTL note.
+    rpc SendDataExportReady(SendDataExportReadyRequest) returns (MailAck);
+}
+
+message MailAck {
+    bool queued = 1;
+}
+
+message SendRegRequest {
+    string user_id = 1;
+    string email = 2;
+    string username = 3;
+    string full_name = 4;
+}
+
+message Send2faRequest {
+    string email = 1;
+    string code = 2;
+    string username = 3;
+}
+
+message SendPasswordResetRequest {
+    string email = 1;
+    string code = 2;
+    string username = 3;
+}
+
+message SendRegistrationConfirmRequest {
+    string email = 1;
+    string code = 2;
+    string username = 3;
+}
+
+message SendDataExportReadyRequest {
+    string email = 1;
+    string username = 2;
+    string file_url = 3;     // signed S3 URL
+    int32 url_ttl_hours = 4; // for the message body
+    int32 file_size = 5;
+}