@aepstore-dev/contracts 1.1.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/gen/upload.ts

@@ -10,84 +10,203 @@ import { Observable } from "rxjs";
 
 export const protobufPackage = "upload.v1";
 
-export interface FileChunk {
-  filename: string;
-  data: Uint8Array;
+/**
+ * Determines the object key prefix (and future ACL/privacy policy).
+ * ATTACHMENT = paid product deliverable (private; presigned GET only after purchase).
+ * MEDIA / AVATAR / BANNER = preview assets.
+ */
+export enum UploadKind {
+  UPLOAD_KIND_UNSPECIFIED = 0,
+  UPLOAD_KIND_ATTACHMENT = 1,
+  UPLOAD_KIND_MEDIA = 2,
+  UPLOAD_KIND_AVATAR = 3,
+  UPLOAD_KIND_BANNER = 4,
+  UNRECOGNIZED = -1,
+}
+
+export interface Ok {
+  ok: boolean;
+}
+
+export interface CreateMultipartUploadRequest {
+  fileName: string;
   mimeType: string;
-  isLast: boolean;
-  chunkIndex: number;
+  fileSize: number;
+  kind: UploadKind;
+  /** user initiating, for key namespacing + audit */
+  ownerId: string;
+}
+
+export interface CreateMultipartUploadResponse {
+  /** S3 multipart UploadId */
   uploadId: string;
+  /** object key this service generated */
+  fileKey: string;
+  /** recommended part size (bytes) the client should slice with */
+  partSize: number;
+  /** number of parts for file_size at part_size */
+  partCount: number;
 }
 
-export interface UploadResponse {
-  fileUrl: string;
-  success: boolean;
-  message: string;
+export interface SignPartRequest {
+  fileKey: string;
   uploadId: string;
+  /** 1-based */
+  partNumber: number;
+}
+
+export interface SignPartResponse {
+  /** presigned PUT URL for this single part */
+  url: string;
+  expiresIn: number;
+}
+
+export interface CompletedPart {
+  partNumber: number;
+  /** ETag the client received in the S3 PUT response header for this part */
+  etag: string;
+}
+
+export interface CompleteMultipartUploadRequest {
+  fileKey: string;
+  uploadId: string;
+  parts: CompletedPart[];
+}
+
+export interface CompleteMultipartUploadResponse {
+  fileKey: string;
+  /** final object location (internal reference) */
+  location: string;
   fileSize: number;
 }
 
-export interface UploadStatusRequest {
+export interface AbortMultipartUploadRequest {
+  fileKey: string;
   uploadId: string;
 }
 
-export interface UploadStatusResponse {
-  status: string;
-  progressPercent: number;
-  message: string;
+export interface CreateUploadUrlRequest {
+  fileName: string;
+  mimeType: string;
+  kind: UploadKind;
+  ownerId: string;
+}
+
+export interface CreateUploadUrlResponse {
+  /** presigned PUT URL (client PUTs the whole file) */
+  url: string;
+  fileKey: string;
+  expiresIn: number;
 }
 
 export interface SignedUrlRequest {
   fileKey: string;
+  /** optional, default 3600 */
   expiresIn: number;
+  /** optional: forces Content-Disposition attachment filename */
+  downloadFileName: string;
 }
 
 export interface SignedUrlResponse {
   signedUrl: string;
-  success: boolean;
-  message: string;
+  expiresIn: number;
+}
+
+export interface DeleteObjectRequest {
+  fileKey: string;
 }
 
 export const UPLOAD_V1_PACKAGE_NAME = "upload.v1";
 
 /**
- * Ported from legacy libs/shared/src/proto/upload.proto.
- * Bumped package to upload.v1 for consistency with the rest of the new stack.
+ * Thin signing service. File bytes NEVER pass through this service — clients
+ * upload/download directly to/from S3 (Yandex Object Storage) using presigned
+ * URLs this service mints. Memory/bandwidth flat regardless of file size.
+ *
+ * Large files (product deliverables, up to ~1GB) use the multipart flow:
+ *   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+ *   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+ *
+ * Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+ *
+ * Downloads are gated elsewhere (products-service verifies purchase, then calls
+ * GenerateSignedUrl). This service does not know about purchases.
  */
 
 export interface UploadServiceClient {
-  uploadFile(request: Observable<FileChunk>): Observable<UploadResponse>;
+  createMultipartUpload(request: CreateMultipartUploadRequest): Observable<CreateMultipartUploadResponse>;
+
+  signPart(request: SignPartRequest): Observable<SignPartResponse>;
+
+  completeMultipartUpload(request: CompleteMultipartUploadRequest): Observable<CompleteMultipartUploadResponse>;
+
+  abortMultipartUpload(request: AbortMultipartUploadRequest): Observable<Ok>;
 
-  getUploadStatus(request: UploadStatusRequest): Observable<UploadStatusResponse>;
+  createUploadUrl(request: CreateUploadUrlRequest): Observable<CreateUploadUrlResponse>;
 
   generateSignedUrl(request: SignedUrlRequest): Observable<SignedUrlResponse>;
+
+  deleteObject(request: DeleteObjectRequest): Observable<Ok>;
 }
 
 /**
- * Ported from legacy libs/shared/src/proto/upload.proto.
- * Bumped package to upload.v1 for consistency with the rest of the new stack.
+ * Thin signing service. File bytes NEVER pass through this service — clients
+ * upload/download directly to/from S3 (Yandex Object Storage) using presigned
+ * URLs this service mints. Memory/bandwidth flat regardless of file size.
+ *
+ * Large files (product deliverables, up to ~1GB) use the multipart flow:
+ *   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+ *   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+ *
+ * Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+ *
+ * Downloads are gated elsewhere (products-service verifies purchase, then calls
+ * GenerateSignedUrl). This service does not know about purchases.
  */
 
 export interface UploadServiceController {
-  uploadFile(request: Observable<FileChunk>): Promise<UploadResponse> | Observable<UploadResponse> | UploadResponse;
+  createMultipartUpload(
+    request: CreateMultipartUploadRequest,
+  ): Promise<CreateMultipartUploadResponse> | Observable<CreateMultipartUploadResponse> | CreateMultipartUploadResponse;
+
+  signPart(request: SignPartRequest): Promise<SignPartResponse> | Observable<SignPartResponse> | SignPartResponse;
+
+  completeMultipartUpload(
+    request: CompleteMultipartUploadRequest,
+  ):
+    | Promise<CompleteMultipartUploadResponse>
+    | Observable<CompleteMultipartUploadResponse>
+    | CompleteMultipartUploadResponse;
 
-  getUploadStatus(
-    request: UploadStatusRequest,
-  ): Promise<UploadStatusResponse> | Observable<UploadStatusResponse> | UploadStatusResponse;
+  abortMultipartUpload(request: AbortMultipartUploadRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  createUploadUrl(
+    request: CreateUploadUrlRequest,
+  ): Promise<CreateUploadUrlResponse> | Observable<CreateUploadUrlResponse> | CreateUploadUrlResponse;
 
   generateSignedUrl(
     request: SignedUrlRequest,
   ): Promise<SignedUrlResponse> | Observable<SignedUrlResponse> | SignedUrlResponse;
+
+  deleteObject(request: DeleteObjectRequest): Promise<Ok> | Observable<Ok> | Ok;
 }
 
 export function UploadServiceControllerMethods() {
   return function (constructor: Function) {
-    const grpcMethods: string[] = ["getUploadStatus", "generateSignedUrl"];
+    const grpcMethods: string[] = [
+      "createMultipartUpload",
+      "signPart",
+      "completeMultipartUpload",
+      "abortMultipartUpload",
+      "createUploadUrl",
+      "generateSignedUrl",
+      "deleteObject",
+    ];
     for (const method of grpcMethods) {
       const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
       GrpcMethod("UploadService", method)(constructor.prototype[method], method, descriptor);
     }
-    const grpcStreamMethods: string[] = ["uploadFile"];
+    const grpcStreamMethods: string[] = [];
     for (const method of grpcStreamMethods) {
       const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
       GrpcStreamMethod("UploadService", method)(constructor.prototype[method], method, descriptor);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aepstore-dev/contracts",
-  "version": "1.1.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 {}

package/proto/upload.proto

@@ -2,48 +2,134 @@ syntax = "proto3";
 
 package upload.v1;
 
-// Ported from legacy libs/shared/src/proto/upload.proto.
-// Bumped package to upload.v1 for consistency with the rest of the new stack.
+// Thin signing service. File bytes NEVER pass through this service — clients
+// upload/download directly to/from S3 (Yandex Object Storage) using presigned
+// URLs this service mints. Memory/bandwidth flat regardless of file size.
+//
+// Large files (product deliverables, up to ~1GB) use the multipart flow:
+//   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+//   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+//
+// Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+//
+// Downloads are gated elsewhere (products-service verifies purchase, then calls
+// GenerateSignedUrl). This service does not know about purchases.
 service UploadService {
-    rpc UploadFile(stream FileChunk) returns (UploadResponse);
-    rpc GetUploadStatus(UploadStatusRequest) returns (UploadStatusResponse);
+    rpc CreateMultipartUpload(CreateMultipartUploadRequest) returns (CreateMultipartUploadResponse);
+    rpc SignPart(SignPartRequest) returns (SignPartResponse);
+    rpc CompleteMultipartUpload(CompleteMultipartUploadRequest) returns (CompleteMultipartUploadResponse);
+    rpc AbortMultipartUpload(AbortMultipartUploadRequest) returns (Ok);
+
+    rpc CreateUploadUrl(CreateUploadUrlRequest) returns (CreateUploadUrlResponse);
+
     rpc GenerateSignedUrl(SignedUrlRequest) returns (SignedUrlResponse);
+
+    rpc DeleteObject(DeleteObjectRequest) returns (Ok);
 }
 
-message FileChunk {
-    string filename = 1;
-    bytes data = 2;
-    string mime_type = 3;
-    bool is_last = 4;
-    int32 chunk_index = 5;
-    string upload_id = 6;
+// Determines the object key prefix (and future ACL/privacy policy).
+// ATTACHMENT = paid product deliverable (private; presigned GET only after purchase).
+// MEDIA / AVATAR / BANNER = preview assets.
+enum UploadKind {
+    UPLOAD_KIND_UNSPECIFIED = 0;
+    UPLOAD_KIND_ATTACHMENT = 1;
+    UPLOAD_KIND_MEDIA = 2;
+    UPLOAD_KIND_AVATAR = 3;
+    UPLOAD_KIND_BANNER = 4;
 }
 
-message UploadResponse {
-    string file_url = 1;
-    bool success = 2;
-    string message = 3;
-    string upload_id = 4;
-    int64 file_size = 5;
+message Ok {
+    bool ok = 1;
 }
 
-message UploadStatusRequest {
-    string upload_id = 1;
+// ---------------------------------------------------------------------------
+// Multipart upload (large files)
+// ---------------------------------------------------------------------------
+
+message CreateMultipartUploadRequest {
+    string file_name = 1;
+    string mime_type = 2;
+    int64 file_size = 3;
+    UploadKind kind = 4;
+    string owner_id = 5; // user initiating, for key namespacing + audit
 }
 
-message UploadStatusResponse {
-    string status = 1;
-    int32 progress_percent = 2;
-    string message = 3;
+message CreateMultipartUploadResponse {
+    string upload_id = 1; // S3 multipart UploadId
+    string file_key = 2;  // object key this service generated
+    int64 part_size = 3;  // recommended part size (bytes) the client should slice with
+    int32 part_count = 4; // number of parts for file_size at part_size
 }
 
-message SignedUrlRequest {
+message SignPartRequest {
     string file_key = 1;
+    string upload_id = 2;
+    int32 part_number = 3; // 1-based
+}
+
+message SignPartResponse {
+    string url = 1;       // presigned PUT URL for this single part
     int32 expires_in = 2;
 }
 
+message CompletedPart {
+    int32 part_number = 1;
+    string etag = 2; // ETag the client received in the S3 PUT response header for this part
+}
+
+message CompleteMultipartUploadRequest {
+    string file_key = 1;
+    string upload_id = 2;
+    repeated CompletedPart parts = 3;
+}
+
+message CompleteMultipartUploadResponse {
+    string file_key = 1;
+    string location = 2; // final object location (internal reference)
+    int64 file_size = 3;
+}
+
+message AbortMultipartUploadRequest {
+    string file_key = 1;
+    string upload_id = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Single-PUT upload (small files)
+// ---------------------------------------------------------------------------
+
+message CreateUploadUrlRequest {
+    string file_name = 1;
+    string mime_type = 2;
+    UploadKind kind = 3;
+    string owner_id = 4;
+}
+
+message CreateUploadUrlResponse {
+    string url = 1;      // presigned PUT URL (client PUTs the whole file)
+    string file_key = 2;
+    int32 expires_in = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Download
+// ---------------------------------------------------------------------------
+
+message SignedUrlRequest {
+    string file_key = 1;
+    int32 expires_in = 2;          // optional, default 3600
+    string download_file_name = 3; // optional: forces Content-Disposition attachment filename
+}
+
 message SignedUrlResponse {
     string signed_url = 1;
-    bool success = 2;
-    string message = 3;
+    int32 expires_in = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Cleanup
+// ---------------------------------------------------------------------------
+
+message DeleteObjectRequest {
+    string file_key = 1;
 }