@aepstore-dev/contracts 1.2.0 → 1.3.0

package/gen/auth.ts

@@ -34,32 +34,16 @@ export interface RegisterRequest {
   ip: string;
 }
 
-/** Standard tokens-plus-user payload returned by Login / Register / RefreshToken. */
-export interface AuthResponse {
-  accessToken: string;
-  refreshToken: string;
-  user: AuthUser | undefined;
-}
-
-export interface AuthUser {
-  id: string;
-  email: string;
-  username: string;
-  /** primary role for backwards compat ("User" / "Administrator" / "Moderator") */
-  role: string;
-}
-
-/** Code types: '2fa', 'reset', 'confirm', 'totp' (legacy strings preserved as-is). */
+/** type ∈ { twofa, reset, totp_generate, totp_activate, confirm } (legacy strings) */
 export interface CreateCodeRequest {
   email: string;
   type: string;
 }
 
-export interface CreateCodeResponse {
-  ok: boolean;
-}
-
-/** `new_password` is only used by the 'reset' flow. */
+/**
+ * type ∈ { twofa, twofa_deactivate, reset, totp, totp_deactivate, backup, confirm }
+ * new_password is only used by the 'reset' flow.
+ */
 export interface VerifyCodeRequest {
   email: string;
   code: string;
@@ -68,29 +52,10 @@ export interface VerifyCodeRequest {
   newPassword: string;
 }
 
-/**
- * Some verification flows (e.g. confirm-on-register) issue tokens immediately;
- * others just return ok=true.
- */
-export interface VerifyCodeResponse {
-  ok: boolean;
-  /** optional */
-  accessToken: string;
-  /** optional */
-  refreshToken: string;
-}
-
 export interface CheckTokenRequest {
   token: string;
 }
 
-export interface CheckTokenResponse {
-  valid: boolean;
-  userId: string;
-  /** populated when valid=false */
-  reason: string;
-}
-
 export interface RefreshTokenRequest {
   refreshToken: string;
   /** optional */
@@ -103,24 +68,54 @@ export interface Get2faStatusRequest {
   username: string;
 }
 
-export interface Get2faStatusResponse {
-  enabled: boolean;
-  type: TwoFactorType;
-}
-
 export interface GetProfileRequest {
   userId: string;
 }
 
-export interface UserProfileResponse {
+export interface AuthUser {
   id: string;
-  email: string;
   username: string;
-  fullName: string;
+  email: string;
+  avatarUrl: string;
+  bannerUrl: string;
+  roles: string[];
+  /** primary role (roles[0]) */
+  role: string;
   isVerified: boolean;
+  twoFactorType: TwoFactorType;
   twoFactorEnabled: boolean;
+  /** Decimal as string (D7) */
+  balance: string;
+}
+
+/**
+ * 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 + requires_2fa + two_factor_type + user (no tokens)
+ *   - totp_generate → secret + otpauth + qr (+ user)
+ *   - totp_activate → backup_codes (+ tokens/user)
+ */
+export interface AuthResult {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+  user: AuthUser | undefined;
+  message: string;
+  requires2fa: boolean;
   twoFactorType: TwoFactorType;
-  roles: string[];
+  /** TOTP setup extras */
+  secret: string;
+  otpauth: string;
+  /** data URL (PNG) */
+  qr: string;
+  backupCodes: string[];
+}
+
+export interface TwoFactorStatusResponse {
+  twoFactorType: TwoFactorType;
+  has2fa: boolean;
+  isVerified: boolean;
 }
 
 export interface Empty {
@@ -130,64 +125,60 @@ export const AUTH_V1_PACKAGE_NAME = "auth.v1";
 
 /**
  * Ported from legacy auth-service (@MessagePattern → @GrpcMethod).
- * All tokens are HMAC primitives minted by @aepstore-dev/passport;
- * the access token only carries `userId`. Username / roles / 2FA state
- * must be looked up via Prisma or RbacService on the consumer side.
+ * 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.
  */
 
 export interface AuthServiceClient {
-  login(request: LoginRequest): Observable<AuthResponse>;
+  login(request: LoginRequest): Observable<AuthResult>;
 
-  register(request: RegisterRequest): Observable<AuthResponse>;
+  register(request: RegisterRequest): Observable<AuthResult>;
 
-  createCode(request: CreateCodeRequest): Observable<CreateCodeResponse>;
+  createCode(request: CreateCodeRequest): Observable<AuthResult>;
 
-  verifyCode(request: VerifyCodeRequest): Observable<VerifyCodeResponse>;
+  verifyCode(request: VerifyCodeRequest): Observable<AuthResult>;
 
-  checkToken(request: CheckTokenRequest): Observable<CheckTokenResponse>;
+  checkToken(request: CheckTokenRequest): Observable<AuthUser>;
 
-  refreshToken(request: RefreshTokenRequest): Observable<AuthResponse>;
+  refreshToken(request: RefreshTokenRequest): Observable<AuthResult>;
 
-  get2FaStatus(request: Get2faStatusRequest): Observable<Get2faStatusResponse>;
+  get2FaStatus(request: Get2faStatusRequest): Observable<TwoFactorStatusResponse>;
 
-  getProfile(request: GetProfileRequest): Observable<UserProfileResponse>;
+  getProfile(request: GetProfileRequest): Observable<AuthUser>;
 
   cleanupExpiredTotpSetups(request: Empty): Observable<Empty>;
 }
 
 /**
  * Ported from legacy auth-service (@MessagePattern → @GrpcMethod).
- * All tokens are HMAC primitives minted by @aepstore-dev/passport;
- * the access token only carries `userId`. Username / roles / 2FA state
- * must be looked up via Prisma or RbacService on the consumer side.
+ * 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.
  */
 
 export interface AuthServiceController {
-  login(request: LoginRequest): Promise<AuthResponse> | Observable<AuthResponse> | AuthResponse;
+  login(request: LoginRequest): Promise<AuthResult> | Observable<AuthResult> | AuthResult;
 
-  register(request: RegisterRequest): Promise<AuthResponse> | Observable<AuthResponse> | AuthResponse;
+  register(request: RegisterRequest): Promise<AuthResult> | Observable<AuthResult> | AuthResult;
 
-  createCode(
-    request: CreateCodeRequest,
-  ): Promise<CreateCodeResponse> | Observable<CreateCodeResponse> | CreateCodeResponse;
+  createCode(request: CreateCodeRequest): Promise<AuthResult> | Observable<AuthResult> | AuthResult;
 
-  verifyCode(
-    request: VerifyCodeRequest,
-  ): Promise<VerifyCodeResponse> | Observable<VerifyCodeResponse> | VerifyCodeResponse;
+  verifyCode(request: VerifyCodeRequest): Promise<AuthResult> | Observable<AuthResult> | AuthResult;
 
-  checkToken(
-    request: CheckTokenRequest,
-  ): Promise<CheckTokenResponse> | Observable<CheckTokenResponse> | CheckTokenResponse;
+  checkToken(request: CheckTokenRequest): Promise<AuthUser> | Observable<AuthUser> | AuthUser;
 
-  refreshToken(request: RefreshTokenRequest): Promise<AuthResponse> | Observable<AuthResponse> | AuthResponse;
+  refreshToken(request: RefreshTokenRequest): Promise<AuthResult> | Observable<AuthResult> | AuthResult;
 
   get2FaStatus(
     request: Get2faStatusRequest,
-  ): Promise<Get2faStatusResponse> | Observable<Get2faStatusResponse> | Get2faStatusResponse;
+  ): Promise<TwoFactorStatusResponse> | Observable<TwoFactorStatusResponse> | TwoFactorStatusResponse;
 
-  getProfile(
-    request: GetProfileRequest,
-  ): Promise<UserProfileResponse> | Observable<UserProfileResponse> | UserProfileResponse;
+  getProfile(request: GetProfileRequest): Promise<AuthUser> | Observable<AuthUser> | AuthUser;
 
   cleanupExpiredTotpSetups(request: Empty): Promise<Empty> | Observable<Empty> | Empty;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aepstore-dev/contracts",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Protobuf definitions for aepstore microservices",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/proto/auth.proto

@@ -3,21 +3,33 @@ syntax = "proto3";
 package auth.v1;
 
 // Ported from legacy auth-service (@MessagePattern → @GrpcMethod).
-// All tokens are HMAC primitives minted by @aepstore-dev/passport;
-// the access token only carries `userId`. Username / roles / 2FA state
-// must be looked up via Prisma or RbacService on the consumer side.
+// 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 (AuthResponse);
-    rpc Register(RegisterRequest) returns (AuthResponse);
-    rpc CreateCode(CreateCodeRequest) returns (CreateCodeResponse);
-    rpc VerifyCode(VerifyCodeRequest) returns (VerifyCodeResponse);
-    rpc CheckToken(CheckTokenRequest) returns (CheckTokenResponse);
-    rpc RefreshToken(RefreshTokenRequest) returns (AuthResponse);
-    rpc Get2faStatus(Get2faStatusRequest) returns (Get2faStatusResponse);
-    rpc GetProfile(GetProfileRequest) returns (UserProfileResponse);
+    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);
 }
 
+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;
@@ -32,31 +44,14 @@ message RegisterRequest {
     string ip = 4; // optional, attached by gateway from req
 }
 
-// Standard tokens-plus-user payload returned by Login / Register / RefreshToken.
-message AuthResponse {
-    string access_token = 1;
-    string refresh_token = 2;
-    AuthUser user = 3;
-}
-
-message AuthUser {
-    string id = 1;
-    string email = 2;
-    string username = 3;
-    string role = 4; // primary role for backwards compat ("User" / "Administrator" / "Moderator")
-}
-
-// Code types: '2fa', 'reset', 'confirm', 'totp' (legacy strings preserved as-is).
+// type ∈ { twofa, reset, totp_generate, totp_activate, confirm } (legacy strings)
 message CreateCodeRequest {
     string email = 1;
     string type = 2;
 }
 
-message CreateCodeResponse {
-    bool ok = 1;
-}
-
-// `new_password` is only used by the 'reset' flow.
+// type ∈ { twofa, twofa_deactivate, reset, totp, totp_deactivate, backup, confirm }
+// new_password is only used by the 'reset' flow.
 message VerifyCodeRequest {
     string email = 1;
     string code = 2;
@@ -64,24 +59,10 @@ message VerifyCodeRequest {
     string new_password = 4; // optional
 }
 
-// Some verification flows (e.g. confirm-on-register) issue tokens immediately;
-// others just return ok=true.
-message VerifyCodeResponse {
-    bool ok = 1;
-    string access_token = 2;  // optional
-    string refresh_token = 3; // optional
-}
-
 message CheckTokenRequest {
     string token = 1;
 }
 
-message CheckTokenResponse {
-    bool valid = 1;
-    string user_id = 2;
-    string reason = 3; // populated when valid=false
-}
-
 message RefreshTokenRequest {
     string refresh_token = 1;
     string user_agent = 2; // optional
@@ -92,30 +73,55 @@ message Get2faStatusRequest {
     string username = 1;
 }
 
-message Get2faStatusResponse {
-    bool enabled = 1;
-    TwoFactorType type = 2;
-}
-
-enum TwoFactorType {
-    NONE = 0;
-    APP = 1;
-    EMAIL = 2;
-}
-
 message GetProfileRequest {
     string user_id = 1;
 }
 
-message UserProfileResponse {
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
+message AuthUser {
     string id = 1;
-    string email = 2;
-    string username = 3;
-    string full_name = 4;
-    bool is_verified = 5;
-    bool two_factor_enabled = 6;
+    string username = 2;
+    string email = 3;
+    string avatar_url = 4;
+    string banner_url = 5;
+    repeated string roles = 6;
+    string role = 7; // primary role (roles[0])
+    bool is_verified = 8;
+    TwoFactorType two_factor_type = 9;
+    bool two_factor_enabled = 10;
+    string balance = 11; // Decimal as string (D7)
+}
+
+// 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 + requires_2fa + 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;
+    bool requires_2fa = 6;
     TwoFactorType two_factor_type = 7;
-    repeated string roles = 8;
+
+    // TOTP setup extras
+    string secret = 8;
+    string otpauth = 9;
+    string qr = 10; // data URL (PNG)
+    repeated string backup_codes = 11;
+}
+
+message TwoFactorStatusResponse {
+    TwoFactorType two_factor_type = 1;
+    bool has_2fa = 2;
+    bool is_verified = 3;
 }
 
 message Empty {}