# GoodGo Platform Payment Module - Security Review File Inventory

## Overview
Comprehensive file listing for the Order & Escrow entities security review in the payments module.
Location: `/Users/velikho/Desktop/WORKING/goodgo-platform-ai/apps/api/src/modules/payments/`

---

## 1. DOMAIN LAYER - ENTITIES

### Core Entities
| File | Description |
|------|-------------|
| `domain/entities/order.entity.ts` | **ORDER ENTITY** - Manages order lifecycle with state machine (CREATED→PAYMENT_PENDING→PAYMENT_CONFIRMED→ESCROW_HELD→SHIPPED→DELIVERED→ESCROW_RELEASED→COMPLETED). Validates transitions. Emits events: OrderCreatedEvent, OrderPaidEvent, OrderCancelledEvent. Critical fields: buyerId, sellerId, listingId, amount (Money VO), platformFee, sellerPayout. |
| `domain/entities/escrow.entity.ts` | **ESCROW ENTITY** - Manages escrow lifecycle (PENDING→HELD→RELEASED/DISPUTED/REFUNDED). Stores escrow amount, fee, and calculated netPayout. Emits: EscrowHeldEvent, EscrowReleasedEvent, EscrowDisputedEvent. Validates state transitions. |
| `domain/entities/payment.entity.ts` | **PAYMENT ENTITY** - Manages payment transactions (PENDING→PROCESSING→COMPLETED/FAILED/REFUNDED). Stores userId, provider (VNPAY/MOMO/ZALOPAY), type, amount, callbackData, idempotencyKey. Emits: PaymentCreatedEvent, PaymentCompletedEvent, PaymentFailedEvent, PaymentRefundedEvent. |

### Value Objects
| File | Description |
|------|-------------|
| `domain/value-objects/money.vo.ts` | **MONEY VALUE OBJECT** - Wraps amounts as bigint in VND. Validates: amount > 0, max limit 999_999_999_999. Used for all financial amounts. |
| `domain/value-objects/platform-fee.vo.ts` | **PLATFORM FEE VALUE OBJECT** - Calculates 5% platform fee. Methods: `fromOrderAmount()` (auto-calc 5%), `create()` (explicit amount). Validates fee >= 0. |

---

## 2. DOMAIN LAYER - REPOSITORIES (Interfaces)

| File | Description |
|------|-------------|
| `domain/repositories/order.repository.ts` | **ORDER REPOSITORY INTERFACE** - Defines CRUD + query methods: findById, findByIdempotencyKey, findByBuyerId, findBySellerId, save, update. Idempotency protection. |
| `domain/repositories/escrow.repository.ts` | **ESCROW REPOSITORY INTERFACE** - Defines: findById, findByOrderId, save, update. One escrow per order relationship. |
| `domain/repositories/payment.repository.ts` | **PAYMENT REPOSITORY INTERFACE** - Defines: findById, findByProviderTxId, findByIdempotencyKey, findByUserId, save, update, **updateIfStatus** (atomic conditional update for race condition handling). |

---

## 3. DOMAIN LAYER - EVENTS

| File | Description |
|------|-------------|
| `domain/events/order-created.event.ts` | Emitted when order created - contains orderId, buyerId, sellerId, listingId, amount |
| `domain/events/order-paid.event.ts` | Emitted when payment confirmed - contains orderId, buyerId, amount |
| `domain/events/order-cancelled.event.ts` | Emitted when order cancelled - contains orderId, buyerId, sellerId |
| `domain/events/escrow-held.event.ts` | Emitted when escrow held - contains escrowId, orderId, amount |
| `domain/events/escrow-released.event.ts` | Emitted when escrow released - contains escrowId, orderId, netPayout |
| `domain/events/escrow-disputed.event.ts` | Emitted when escrow disputed - contains escrowId, orderId, reason |
| `domain/events/payment-created.event.ts` | Emitted when payment created - contains paymentId, userId, provider, amount |
| `domain/events/payment-completed.event.ts` | Emitted when payment completes - contains paymentId, userId, provider |
| `domain/events/payment-failed.event.ts` | Emitted when payment fails - contains paymentId, userId, provider |
| `domain/events/payment-refunded.event.ts` | Emitted when payment refunded - contains paymentId, userId, provider, amount |

---

## 4. INFRASTRUCTURE LAYER - REPOSITORIES (Implementations)

| File | Description |
|------|-------------|
| `infrastructure/repositories/prisma-order.repository.ts` | **ORDER REPOSITORY IMPL** - Prisma ORM implementation. Stores: id, buyerId, sellerId, listingId, status, amountVND, platformFeeVND, sellerPayoutVND, idempotencyKey, metadata. Handles order persistence. |
| `infrastructure/repositories/prisma-escrow.repository.ts` | **ESCROW REPOSITORY IMPL** - Prisma ORM implementation. Stores: id, orderId, amountVND, feeVND, status, heldAt, releasedAt, disputeReason, disputedAt. Handles escrow persistence. |
| `infrastructure/repositories/prisma-payment.repository.ts` | **PAYMENT REPOSITORY IMPL** - Prisma ORM. Stores: id, userId, transactionId, provider, type, amountVND, status, providerTxId, callbackData, idempotencyKey. **CRITICAL: `updateIfStatus()` uses conditional WHERE clause for atomic race condition prevention** (Line 84-109). |

---

## 5. INFRASTRUCTURE LAYER - PAYMENT GATEWAY SERVICES

### Payment Gateway Interface
| File | Description |
|------|-------------|
| `infrastructure/services/payment-gateway.interface.ts` | **GATEWAY INTERFACE** - Defines IPaymentGateway contract: createPaymentUrl(), verifyCallback(), refund(). CallbackVerifyResult includes: isValid, orderId, providerTxId, isSuccess, rawData. Sensitive for security. |

### VNPay Service
| File | Description |
|------|-------------|
| `infrastructure/services/vnpay.service.ts` | **VNPAY PAYMENT GATEWAY** - Implements IPaymentGateway. **CALLBACK VERIFICATION (Line 72-105)**: Extracts secure hash, removes it from data, sorts params, generates HMAC-SHA512, uses crypto.timingSafeEqual() for constant-time comparison. Amount multiplied by 100 for VND cents. Returns isValid, orderId (vnp_TxnRef), providerTxId (vnp_TransactionNo), isSuccess (responseCode === '00'). Refund support. |

### MoMo Service
| File | Description |
|------|-------------|
| `infrastructure/services/momo.service.ts` | **MOMO PAYMENT GATEWAY** - Implements IPaymentGateway. **CALLBACK VERIFICATION (Line 102-147)**: Extracts signature from data, rebuilds raw signature with accessKey, amount, extraData, IPN/redirect URLs, orderId, etc. Uses HMAC-SHA256, constant-time comparison via crypto.timingSafeEqual(). Success check: resultCode === '0'. Refund support. Amount as Number (not bigint in API). |

### ZaloPay Service
| File | Description |
|------|-------------|
| `infrastructure/services/zalopay.service.ts` | **ZALOPAY PAYMENT GATEWAY** - Implements IPaymentGateway. **CALLBACK VERIFICATION (Line 98-144)**: Data passed as JSON string in 'data' field. MAC verified via HMAC-SHA256 with key2. Parses JSON data to extract app_trans_id and zp_trans_id. **SECURITY NOTE**: Catches JSON parse errors gracefully. Uses constant-time comparison. Refund support (key1). |

### Payment Gateway Factory
| File | Description |
|------|-------------|
| `infrastructure/services/payment-gateway.factory.ts` | **GATEWAY FACTORY** - Returns appropriate gateway instance (VNPay/MoMo/ZaloPay) based on provider enum. |

---

## 6. APPLICATION LAYER - COMMANDS

### Order Commands
| File | Description |
|------|-------------|
| `application/commands/create-order/create-order.command.ts` | **CREATE ORDER COMMAND** - Input: buyerId, sellerId, listingId, amountVND, idempotencyKey. Payload object. |
| `application/commands/create-order/create-order.handler.ts` | **CREATE ORDER HANDLER** - Idempotency check via findByIdempotencyKey. Validates amount (Money VO). Calculates platform fee (5%) and seller payout. Creates OrderEntity + EscrowEntity (PENDING status). Saves both. Emits events. |
| `application/commands/cancel-order/cancel-order.command.ts` | **CANCEL ORDER COMMAND** - Input: orderId, userId, reason. |
| `application/commands/cancel-order/cancel-order.handler.ts` | **CANCEL ORDER HANDLER** - Verifies user owns order, validates state transition via entity.markCancelled(), saves, emits events. |

### Escrow Commands
| File | Description |
|------|-------------|
| `application/commands/hold-escrow/hold-escrow.command.ts` | **HOLD ESCROW COMMAND** - Input: orderId. Admin-only operation. |
| `application/commands/hold-escrow/hold-escrow.handler.ts` | **HOLD ESCROW HANDLER (Line 23-67)** - Fetches order + escrow by orderId. Calls escrow.hold() state transition. Updates both entities. Emits EscrowHeldEvent. **SECURITY NOTE**: No Redis lock - potential race condition if multiple concurrent requests. |
| `application/commands/release-escrow/release-escrow.command.ts` | **RELEASE ESCROW COMMAND** - Input: orderId. Admin-only operation. |
| `application/commands/release-escrow/release-escrow.handler.ts` | **RELEASE ESCROW HANDLER (Line 24-45)** - Fetches order + escrow by orderId. Calls escrow.release() state transition. Updates both entities. Emits EscrowReleasedEvent with netPayout. **SECURITY NOTE**: No Redis lock - potential race condition. |

### Payment Commands
| File | Description |
|------|-------------|
| `application/commands/create-payment/create-payment.command.ts` | **CREATE PAYMENT COMMAND** - Input: userId, provider, type, amountVND, description, returnUrl, ipAddress, transactionId, idempotencyKey. |
| `application/commands/create-payment/create-payment.handler.ts` | **CREATE PAYMENT HANDLER** - Idempotency check. Validates amount (Money VO). Gets payment gateway. Calls createPaymentUrl(). Creates PaymentEntity (PENDING status). Saves. Emits PaymentCreatedEvent. Returns paymentUrl for frontend redirect. |
| `application/commands/refund-payment/refund-payment.command.ts` | **REFUND PAYMENT COMMAND** - Input: paymentId, reason, userId. Admin command. |
| `application/commands/refund-payment/refund-payment.handler.ts` | **REFUND PAYMENT HANDLER** - Verifies payment exists, calls gateway.refund() with provider-specific args, updates payment status to REFUNDED, emits PaymentRefundedEvent. |

### Callback Handler (CRITICAL)
| File | Description |
|------|-------------|
| `application/commands/handle-callback/handle-callback.command.ts` | **HANDLE CALLBACK COMMAND** - Input: provider (PaymentProvider enum), callbackData (Record<string, string>). |
| `application/commands/handle-callback/handle-callback.handler.ts` | **HANDLE CALLBACK HANDLER (Line 32-110)** - **CRITICAL SECURITY FILE**. Gets gateway, calls verifyCallback() (validates signature). If invalid: throws ValidationException. If valid: **Uses `paymentRepo.updateIfStatus()` with conditional WHERE ['PENDING', 'PROCESSING']** (Line 48-55) - atomic update to prevent duplicate processing. If update returns null: checks if payment exists (already processed - idempotent response). If success: calls payment.emitCompleted(), else payment.emitFailed(). Publishes events. **STRONG RACE CONDITION PROTECTION via conditional update**. |

---

## 7. APPLICATION LAYER - QUERIES

| File | Description |
|------|-------------|
| `application/queries/get-order-status/get-order-status.query.ts` | Query: Input orderId, userId (for authorization). |
| `application/queries/get-order-status/get-order-status.handler.ts` | Fetches order, verifies ownership (buyer/seller), returns status + details. |
| `application/queries/get-payment-status/get-payment-status.query.ts` | Query: Input paymentId, userId. |
| `application/queries/get-payment-status/get-payment-status.handler.ts` | Fetches payment, verifies ownership, returns status + details. |
| `application/queries/list-transactions/list-transactions.query.ts` | Query: Input userId, status (optional), limit, offset. |
| `application/queries/list-transactions/list-transactions.handler.ts` | Lists payments for user with pagination, filters by status if provided. |

---

## 8. PRESENTATION LAYER - CONTROLLERS

| File | Description |
|------|-------------|
| `presentation/controllers/orders.controller.ts` | **ORDERS CONTROLLER** - Routes: POST / (create order), GET /:id (status), POST /:id/cancel (cancel), POST /:id/escrow/hold (admin), POST /:id/escrow/release (admin). Auth: JwtAuthGuard, RolesGuard for admin ops. Converts DTO to commands. |
| `presentation/controllers/payments.controller.ts` | **PAYMENTS CONTROLLER** - Routes: POST / (create payment), POST /callback/:provider (webhook - **Throttle + EndpointRateLimit**), GET /:id (status), GET (list), POST /:id/refund (admin refund). **CRITICAL: Callback endpoint has rate limiting (Throttle + EndpointRateLimitGuard)** - prevents callback flooding. |

---

## 9. PRESENTATION LAYER - DTOs

| File | Description |
|------|-------------|
| `presentation/dto/create-order.dto.ts` | DTO: sellerId, listingId, amountVND (string), idempotencyKey (optional). |
| `presentation/dto/cancel-order.dto.ts` | DTO: reason (string). |
| `presentation/dto/create-payment.dto.ts` | DTO: provider (enum), type (enum), amountVND (string), description, returnUrl, transactionId (optional), idempotencyKey (optional). |
| `presentation/dto/refund-payment.dto.ts` | DTO: reason (string). |
| `presentation/dto/list-transactions.dto.ts` | DTO: status (optional), limit, offset. |

---

## 10. MODULE & TEST FILES

| File | Description |
|------|-------------|
| `payments.module.ts` | **MODULE SETUP** - Registers repositories, services, handlers, controllers. |
| `index.ts` (module level) | Exports public API. |
| `infrastructure/repositories/index.ts` | Exports repository implementations. |
| `infrastructure/services/index.ts` | Exports gateway services. |
| `application/index.ts` | Exports command/query handlers. |
| `domain/repositories/index.ts` | Exports repository interfaces. |
| `domain/entities/index.ts` | Exports entities. |
| `domain/value-objects/index.ts` | Exports VOs. |
| `domain/events/index.ts` | Exports domain events. |
| `presentation/controllers/index.ts` | Exports controllers. |
| `presentation/dto/index.ts` | Exports DTOs. |

### Test Files
| File | Description |
|------|-------------|
| `domain/__tests__/order.entity.spec.ts` | Order entity unit tests - state machine, transitions |
| `domain/__tests__/escrow.entity.spec.ts` | Escrow entity unit tests - hold, release, dispute, refund |
| `domain/__tests__/payment.entity.spec.ts` | Payment entity unit tests |
| `domain/__tests__/money.vo.spec.ts` | Money VO validation tests |
| `domain/__tests__/platform-fee.vo.spec.ts` | Platform fee calculation tests |
| `domain/__tests__/payment-events.spec.ts` | Domain event emission tests |
| `application/__tests__/create-order.handler.spec.ts` | Create order handler tests |
| `application/__tests__/create-payment.handler.spec.ts` | Create payment handler tests |
| `application/__tests__/handle-callback.handler.spec.ts` | Callback handling tests |
| `application/__tests__/handle-callback-edge-cases.handler.spec.ts` | Callback edge cases (race conditions, idempotency) |
| `application/__tests__/get-payment-status.handler.spec.ts` | Payment status query tests |
| `application/__tests__/refund-payment.handler.spec.ts` | Refund command tests |
| `application/__tests__/list-transactions.handler.spec.ts` | List transactions query tests |
| `infrastructure/__tests__/vnpay.service.spec.ts` | VNPay gateway tests - signature verification |
| `infrastructure/__tests__/momo.service.spec.ts` | MoMo gateway tests - HMAC-SHA256 verification |
| `infrastructure/__tests__/zalopay.service.spec.ts` | ZaloPay gateway tests - JSON parsing + MAC verification |
| `infrastructure/__tests__/payment-gateway.factory.spec.ts` | Factory pattern tests |

---

## SECURITY FINDINGS SUMMARY

### ✅ STRONG SECURITY MEASURES
1. **Callback Signature Verification**: All 3 providers (VNPay, MoMo, ZaloPay) verify HMAC signatures using `crypto.timingSafeEqual()` for constant-time comparison
2. **Atomic Race Condition Prevention**: `paymentRepo.updateIfStatus()` uses conditional WHERE clause to atomically update only if in PENDING/PROCESSING state
3. **Idempotency Protection**: Orders + Payments check idempotencyKey to prevent duplicate operations
4. **Rate Limiting**: Callback endpoint has Throttle + EndpointRateLimit decorators
5. **Authorization**: All endpoints require JwtAuthGuard; admin operations require RolesGuard
6. **Amount Validation**: Money VO validates: 0 < amount ≤ 999_999_999_999 VND
7. **State Machine Validation**: Order + Escrow enforce valid status transitions

### ⚠️ SECURITY CONCERNS (NEEDS REVIEW)
1. **Hold/Release Escrow Race Conditions**: No Redis lock on hold-escrow/release-escrow handlers - concurrent requests could cause state inconsistencies
2. **No Distributed Lock Mechanism**: Escrow operations not protected against simultaneous requests from different servers
3. **Callback Processing Idempotency**: While paymentRepo.updateIfStatus() prevents double-processing, idempotency check doesn't verify callback signature consistency
4. **Payment Provider Secrets**: Keys loaded from ConfigService - verify env variable encryption at rest
5. **Refund Authorization**: Only ADMIN role check - no business logic validation (e.g., refund window, max refund amount)
6. **Order/Escrow Update Race**: While holds are atomic for payments, order + escrow updates in handlers are done sequentially (2 DB calls), not atomically

---

## FILES NOT FOUND / NOT IN SCOPE
- ❌ **Redis Lock Usage**: No Redis locks found in payments module. CONCERN: Critical for escrow hold/release.
- ❌ **Shared Payment Utilities**: No external payment utility modules referenced
- ❌ **Encryption for Payment Data**: No field-level encryption for sensitive payment data (though field-encryption service exists in shared module)