goodgo-platform/docs/security/PAYMENT_SECURITY_CHECKLIST.md

GoodGo Platform - Danh Sách Kiểm Tra Bảo Mật Mô-đun Thanh Toán

Các Tệp Quan Trọng Cần Xem Xét Bảo Mật

🔴 ƯU TIÊN CAO NHẤT (Xem Xét Trước)

1. Xác Minh Chữ Ký Callback

Các tệp:

• infrastructure/services/vnpay.service.ts (dòng 72-105)
• infrastructure/services/momo.service.ts (dòng 102-147)
• infrastructure/services/zalopay.service.ts (dòng 98-144)

Danh sách kiểm tra bảo mật:

• Xác minh rằng crypto.timingSafeEqual() được sử dụng cho tất cả các so sánh HMAC
• Xác nhận khóa xác minh chữ ký là chính xác
• Kiểm tra rằng thuật toán băm khớp với đặc tả của nhà cung cấp (VNPay: SHA512, MoMo/ZaloPay: SHA256)
• Xác minh rằng việc tái tạo dữ liệu chữ ký khớp chính xác với tài liệu của nhà cung cấp
• Kiểm tra các kịch bản tấn công phát lại - các callback cũ có bị từ chối không?
• Xác nhận thứ tự tham số trong chữ ký là đúng
• Kiểm tra tấn công timing - tất cả các triển khai đều sử dụng so sánh thời gian không đổi
• Xác minh rằng việc ghi nhật ký rawData không làm lộ dữ liệu chữ ký nhạy cảm

---

2. Bảo Vệ Race Condition - Callback Thanh Toán

Tệp:

• application/commands/handle-callback/handle-callback.handler.ts (dòng 32-110)
• infrastructure/repositories/prisma-payment.repository.ts (dòng 84-109)

Danh sách kiểm tra bảo mật:

• Xác nhận updateIfStatus() sử dụng mệnh đề WHERE với mảng status IN
• Xác minh Prisma trả về null khi xảy ra lỗi P2025 một cách đúng đắn
• Kiểm tra các kịch bản callback đồng thời cho cùng một thanh toán
• Xác minh phản hồi idempotent cho các thanh toán đã được xử lý
• Xác nhận rằng sự kiện chỉ được phát một lần cho mỗi callback duy nhất
• Kiểm tra rằng trạng thái PROCESSING được sử dụng như trạng thái trung gian
• Xác minh không có race condition giữa kiểm tra null và xuất bản sự kiện

---

3. Bảo Vệ Race Condition - Thao Tác Ký Quỹ (Escrow)

Các tệp:

• application/commands/hold-escrow/hold-escrow.handler.ts (dòng 23-67)
• application/commands/release-escrow/release-escrow.handler.ts (dòng 24-45)

Danh sách kiểm tra bảo mật:

• ❌ NGHIÊM TRỌNG: Không có khóa Redis - các yêu cầu đồng thời có thể gây hỏng trạng thái
• Kiểm tra xem có nhiều thao tác giữ đồng thời trong nhật ký không
• Xác minh rằng không có lệnh/ký quỹ nào có thể ở hai trạng thái cùng lúc
• Kiểm tra: điều gì xảy ra nếu giữ và giải phóng được gọi đồng thời?
• Kiểm tra: điều gì xảy ra nếu giữ được gọi hai lần liên tiếp nhanh?
• Triển khai: Khóa phân tán Redis cho các thao tác ký quỹ
• Tài liệu: Hành vi mong đợi khi truy cập đồng thời

---

4. Xác Thực Số Tiền Tài Chính

Các tệp:

• domain/value-objects/money.vo.ts (dòng 1-21)
• domain/value-objects/platform-fee.vo.ts (dòng 1-31)

Danh sách kiểm tra bảo mật:

• Xác minh giới hạn tối đa 999_999_999_999 VND được áp dụng
• Xác nhận số tiền bằng không/âm bị từ chối
• Kiểm tra: số tiền có thể được đặt thành âm thông qua SQL injection không?
• Xác minh tính toán phí nền tảng: (amount * 5) / 100 = đúng
• Kiểm tra: tính toán phí có xử lý làm tròn đúng không?
• Kiểm tra: trường hợp biên của lệnh 1 VND - phí có đúng không?
• Xác minh tính toán tiền thanh toán cho người bán: amount - fee ≥ 0
• Kiểm tra: tiền thanh toán cho người bán có thể âm không?

---

🟠 ƯU TIÊN CAO

5. Máy Trạng Thái Lệnh/Ký Quỹ

Các tệp:

• domain/entities/order.entity.ts (dòng 22-32 định nghĩa máy trạng thái)
• domain/entities/escrow.entity.ts (dòng 74-148 chuyển đổi trạng thái)

Danh sách kiểm tra bảo mật:

• Xác minh danh sách trắng VALID_TRANSITIONS là đầy đủ và đúng
• Kiểm tra: có thể xảy ra bất kỳ chuyển đổi không hợp lệ nào không?
• Kiểm tra: PAYMENT_PENDING → ESCROW_HELD mà không có PAYMENT_CONFIRMED?
• Xác minh trạng thái DISPUTE có thể chuyển sang ESCROW_RELEASED hoặc REFUNDED
• Kiểm tra: điều gì xảy ra nếu lệnh cố chuyển sang trạng thái không hợp lệ?
• Kiểm tra: tất cả các thay đổi trạng thái có được lưu trữ nguyên tử không?
• Xác minh: các trường dấu thời gian được cập nhật đúng cho mỗi lần chuyển đổi
• Kiểm tra: callback không theo thứ tự không làm hỏng trạng thái

---

6. Bảo Vệ Idempotency

Các tệp:

• application/commands/create-order/create-order.handler.ts (dòng 32-38)
• application/commands/create-payment/create-payment.handler.ts (handler chưa hiển thị đầy đủ)
• infrastructure/repositories/prisma-order.repository.ts (dòng 18-22)
• infrastructure/repositories/prisma-payment.repository.ts (dòng 24-29)

Danh sách kiểm tra bảo mật:

• Xác minh idempotencyKey là duy nhất theo user/request
• Kiểm tra: các yêu cầu trùng lặp với cùng khóa trả về cùng lệnh
• Kiểm tra: các yêu cầu trùng lặp với cùng khóa không bị tính phí hai lần
• Kiểm tra: idempotencyKey có được lưu trữ trong cơ sở dữ liệu không?
• Xác minh: ràng buộc duy nhất trên idempotencyKey trong cơ sở dữ liệu
• Kiểm tra: điều gì xảy ra nếu callback đến trước khi lệnh được tạo?
• Kiểm tra: điều gì xảy ra nếu thanh toán được tạo nhưng callback bị mất?
• Kiểm tra: TTL trên các khóa idempotency để tránh phình to

---

7. Xác Thực Ủy Quyền & Quyền Sở Hữu

Các tệp:

• presentation/controllers/orders.controller.ts (dòng 44-116)
• presentation/controllers/payments.controller.ts (dòng 52-139)

Danh sách kiểm tra bảo mật:

• Xác minh JwtAuthGuard trên tất cả các endpoint người dùng
• Kiểm tra: người dùng có thể xem lệnh/thanh toán của người dùng khác không?
• Xác minh: ủy quyền người mua được kiểm tra trong truy vấn lệnh
• Xác minh: chỉ người bán/người mua mới có thể truy cập giao dịch của họ
• Kiểm tra: lỗ hổng IDOR - người dùng A truy cập lệnh của người dùng B
• Kiểm tra: các endpoint chỉ dành cho admin sử dụng RolesGuard
• Kiểm tra: người dùng không phải admin không thể gọi giữ/giải phóng ký quỹ
• Xác minh: user.sub (JWT subject) được trích xuất đúng cách

---

8. Bảo Mật Hoàn Tiền

Các tệp:

• application/commands/refund-payment/refund-payment.handler.ts (chưa hiển thị đầy đủ)
• infrastructure/services/vnpay.service.ts (dòng 107-169)
• infrastructure/services/momo.service.ts (dòng 149-202)
• infrastructure/services/zalopay.service.ts (dòng 146-197)

Danh sách kiểm tra bảo mật:

• Chỉ vai trò ADMIN mới có thể khởi tạo hoàn tiền
• Xác minh: số tiền hoàn tiền ≤ số tiền thanh toán gốc
• Kiểm tra: số tiền hoàn tiền có thể âm không?
• Kiểm tra: thanh toán có thể được hoàn tiền nhiều lần không?
• Xác minh: theo dõi trạng thái hoàn tiền trong thực thể Payment
• Kiểm tra: xác thực phản hồi hoàn tiền từ nhà cung cấp
• Kiểm tra: hoàn tiền từng phần - nhiều lần hoàn tiền có được theo dõi không?
• Xác minh: tiền thực sự được gửi lại cho khách hàng (không phải cho ứng dụng)

---

9. Giới Hạn Tốc Độ Trên Callback

Tệp:

• presentation/controllers/payments.controller.ts (dòng 75-89)

Danh sách kiểm tra bảo mật:

• Xác nhận: decorator @Throttle với 20 yêu cầu trên 60 giây
• Kiểm tra: @EndpointRateLimit với 100 yêu cầu trên 60 giây
• Xác minh: khóa giới hạn tốc độ dựa trên IP
• Kiểm tra: tấn công ngập lụt callback được giảm thiểu?
• Kiểm tra: bỏ qua admin đã bị vô hiệu hóa cho callback
• Xác minh: cơ chế lưu trữ giới hạn tốc độ (trong bộ nhớ? Redis?)
• Kiểm tra: các đợt bùng phát callback hợp lệ (nhà cung cấp thanh toán thử lại)
• Kiểm tra: lỗi giới hạn tốc độ được ghi nhật ký phù hợp

---

🟡 ƯU TIÊN TRUNG BÌNH

10. Quản Lý Cấu Hình & Bí Mật

Các tệp:

• infrastructure/services/vnpay.service.ts (dòng 27-32)
• infrastructure/services/momo.service.ts (dòng 27-31)
• infrastructure/services/zalopay.service.ts (dòng 27-30)

Danh sách kiểm tra bảo mật:

• Xác minh: tất cả bí mật được tải từ ConfigService (không được mã hóa cứng)
• Kiểm tra: tệp .env có trong .gitignore không
• Xác nhận: bí mật không được ghi nhật ký ở bất kỳ đâu
• Xác minh: bí mật băm có độ dài phù hợp (khuyến nghị 32+ ký tự)
• Kiểm tra: URL sandbox/production được phân tách theo môi trường
• Kiểm tra: thiếu cấu hình gây ra lỗi sớm (không phải khi thanh toán)
• Xác minh: cơ chế xoay bí mật tồn tại hoặc được lên kế hoạch
• Kiểm tra: biến môi trường được mã hóa khi lưu trữ trong CI/CD

---

11. Ràng Buộc Cơ Sở Dữ Liệu

Các tệp:

• Kiểm tra schema Prisma cho các mô hình order/escrow/payment

Danh sách kiểm tra bảo mật:

• Xác minh: ràng buộc duy nhất trên idempotencyKey theo user
• Kiểm tra: ràng buộc NOT NULL trên các trường quan trọng
• Xác minh: quan hệ ONE-TO-ONE order ↔ escrow
• Kiểm tra: ràng buộc khóa ngoại ngăn chặn dữ liệu mồ côi
• Xác minh: các trường trạng thái có ràng buộc CHECK hoặc enum
• Kiểm tra: các trường số tiền có kiểu số đúng (không phải chuỗi)
• Xác minh: không có ID do người dùng cung cấp trực tiếp được sử dụng mà không qua xác thực
• Kiểm tra: chỉ mục cơ sở dữ liệu trên các trường được truy vấn thường xuyên

---

12. Xử Lý Lỗi & Tiết Lộ Thông Tin

Các tệp:

• Tất cả các handler bắt lỗi và ghi nhật ký phù hợp

Danh sách kiểm tra bảo mật:

• Xác minh: thông báo lỗi không làm lộ dữ liệu nhạy cảm
• Kiểm tra: stack trace không bị lộ cho client
• Xác minh: thông báo lỗi chung cho các thao tác thất bại
• Kiểm tra: mã lỗi được tài liệu hóa (ví dụ: OrderNotFound)
• Kiểm tra: số tiền không hợp lệ hiển thị lỗi phù hợp
• Xác minh: callback thất bại được ghi nhật ký với ngữ cảnh nhà cung cấp
• Kiểm tra: lỗi hoàn tiền không lộ cơ chế thử lại
• Xác minh: không có truy vấn SQL nào bị lộ trong thông báo lỗi

---

13. Ghi Nhật Ký & Dấu Vết Kiểm Toán

Các tệp:

• Tất cả các handler sử dụng logger.log() và logger.error()

Danh sách kiểm tra bảo mật:

• Xác minh: các thao tác quan trọng được ghi nhật ký (thanh toán, hoàn tiền, thay đổi ký quỹ)
• Kiểm tra: nhật ký bao gồm ngữ cảnh người dùng (userId, orderId, v.v.)
• Xác minh: nhật ký bao gồm dấu thời gian và chuyển đổi trạng thái
• Kiểm tra: không có dữ liệu nhạy cảm nào được ghi nhật ký (bí mật thanh toán, thông tin CC đầy đủ)
• Xác minh: xoay nhật ký được cấu hình
• Kiểm tra: nhật ký được bảo vệ khỏi giả mạo (ký/băm)
• Kiểm tra: dấu vết kiểm toán cho thấy vòng đời lệnh/thanh toán đầy đủ
• Xác minh: callback không hợp lệ được ghi nhật ký với thông tin chi tiết để điều tra

---

🟢 ƯU TIÊN THẤP HƠN

14. Độ Bao Phủ Kiểm Thử

Các tệp:

• application/__tests__/handle-callback-edge-cases.handler.spec.ts (các trường hợp biên)
• Tất cả các tệp __tests__

Danh sách kiểm tra bảo mật:

• Kiểm tra: độ bao phủ kiểm thử cho xác minh chữ ký callback
• Xác minh: kiểm thử cho các kịch bản race condition
• Kiểm tra: kiểm thử cho các trường hợp biên idempotency
• Xác minh: kiểm thử cho các chuyển đổi trạng thái không hợp lệ
• Kiểm tra: kiểm thử cho các lỗi ủy quyền
• Xác minh: kiểm thử cho các thao tác ký quỹ đồng thời
• Kiểm tra: kiểm thử cho các trường hợp biên xác thực số tiền
• Xác minh: kiểm thử cho các kịch bản nhà cung cấp thất bại

---

15. Tài Liệu API

Các tệp:

• Các decorator của Controller (@ApiOperation, @ApiResponse)

Danh sách kiểm tra bảo mật:

• Xác minh: các endpoint được tài liệu hóa với các yêu cầu bảo mật
• Kiểm tra: schema phản hồi không bao gồm bí mật
• Xác minh: giới hạn tốc độ được tài liệu hóa
• Kiểm tra: yêu cầu ủy quyền được nêu rõ ràng
• Xác minh: các phản hồi lỗi được tài liệu hóa
• Kiểm tra: xác minh chữ ký webhook được giải thích
• Xác minh: hành vi thử lại callback được tài liệu hóa
• Kiểm tra: sự khác biệt hành vi theo từng nhà cung cấp được ghi chú

---

Các Kịch Bản Tấn Công Cần Kiểm Thử

Kịch Bản 1: Ngập Lụt Callback

Tấn công: Gửi 1000 callback mỗi giây
Mong đợi: Bộ giới hạn tốc độ chặn sau 100 trên 60 giây
Mong đợi: Trạng thái thanh toán không thay đổi sau callback thành công đầu tiên
Kiểm tra: Không bị tính phí hai lần

Kịch Bản 2: Tấn Công Phát Lại

Tấn công: Gửi lại callback thành công cũ
Mong đợi: Thanh toán đã ở trạng thái cuối cùng, phản hồi idempotent
Mong đợi: Không bị tính phí hai lần
Kiểm tra: Nhật ký cho thấy lần thử phát lại

Kịch Bản 3: Giải Phóng Ký Quỹ Đồng Thời

Tấn công: Gọi /orders/{id}/escrow/release hai lần đồng thời
Mong đợi: Một thành công, một thất bại với ESCROW_INVALID_STATE
Rủi ro hiện tại: ⚠️ Có thể thành công hai lần nếu không có khóa Redis

Kịch Bản 4: Callback Giả Mạo

Tấn công: Gửi callback với chữ ký HMAC không hợp lệ
Mong đợi: Ngoại lệ xác thực, thanh toán bị từ chối
Kiểm tra: Xác minh chữ ký sử dụng so sánh thời gian không đổi

Kịch Bản 5: Mất Đồng Bộ Trạng Thái Lệnh/Ký Quỹ

Tấn công: Lệnh ở trạng thái PAYMENT_CONFIRMED, Ký quỹ ở trạng thái RELEASED
Mong đợi: Trạng thái máy không hợp lệ - không nên xảy ra
Kiểm tra: Cập nhật lệnh + ký quỹ có nguyên tử không?

Kịch Bản 6: Tràn Số Nguyên

Tấn công: Gửi thanh toán cho 999_999_999_999 VND
Mong đợi: Money VO từ chối (giới hạn tối đa)
Tấn công: Gửi tính toán phí cho số tiền lớn
Mong đợi: Không tràn số nguyên, phí 5% được tính đúng

Kịch Bản 7: Bỏ Qua Ủy Quyền

Tấn công: Lấy ID lệnh của người dùng khác, gọi /orders/{theirID}
Mong đợi: 404 hoặc Forbidden (không tìm thấy để ngăn chặn liệt kê)
Kiểm tra: Quyền sở hữu được xác minh trong query handler

Kịch Bản 8: Hoàn Tiền Hai Lần

Tấn công: Gọi /payments/{id}/refund hai lần
Mong đợi: Lần gọi thứ hai thất bại (thanh toán đã REFUNDED)
Kiểm tra: Máy trạng thái ngăn chặn chuyển đổi không hợp lệ

---

Số Liệu Bảo Mật

Số liệu	Trạng thái	Mục tiêu
Tất cả callback xác minh chữ ký HMAC	✅ CÓ	100%
Race condition được bảo vệ bằng khóa/nguyên tử	⚠️ TỪNG PHẦN	100% (các thao tác ký quỹ cần khóa)
Khóa idempotency được áp dụng	✅ CÓ	100%
Ủy quyền trên tất cả endpoint	✅ CÓ	100%
Xác thực số tiền (min/max)	✅ CÓ	100%
Giới hạn tốc độ trên callback	✅ CÓ	100%
Thông báo lỗi không làm lộ bí mật	⚠️ CẦN XEM XÉT	100%
Ghi nhật ký dấu vết kiểm toán	✅ CÓ	100%
Độ bao phủ kiểm thử bảo mật	⚠️ TỪNG PHẦN	>80%
Ràng buộc cơ sở dữ liệu	⚠️ CẦN XÁC MINH	100%

---

Các Hành Động Được Khuyến Nghị

NGHIÊM TRỌNG (Thực Hiện Trước Khi Đưa Lên Sản Xuất)

1. Triển khai khóa phân tán Redis cho các thao tác giữ/giải phóng ký quỹ

   • Sử dụng @nestjs/common hoặc dịch vụ khóa bên ngoài
   • Ngăn chặn các đột biến trạng thái đồng thời

2. Thêm xác thực ràng buộc cơ sở dữ liệu

   • Xác minh schema Prisma có các ràng buộc phù hợp
   • Thêm chỉ mục duy nhất trên (userId, idempotencyKey)

3. Kiểm toán tất cả thông báo lỗi

   • Đảm bảo không có bí mật nào bị rò rỉ trong phản hồi
   • Kiểm tra thủ công các trường hợp lỗi

CAO (Trước Lần Triển Khai Đầu Tiên)

4. Thêm bộ kiểm thử toàn diện

   • Kiểm thử race condition
   • Kiểm thử phát lại callback
   • Kiểm thử IDOR

5. Kiểm toán bí mật

   • Xác minh không có giá trị được mã hóa cứng
   • Kiểm tra .env/.gitignore
   • Tài liệu quy trình xoay bí mật

6. Kiểm thử tải callback

   • Mô phỏng các đợt thử lại từ nhà cung cấp
   • Xác minh giới hạn tốc độ hoạt động

TRUNG BÌNH (Ngắn Hạn)

7. Thêm ghi nhật ký kiểm toán chi tiết hơn

   • Chuyển đổi trạng thái thanh toán
   • Các lần thử callback thất bại
   • Yêu cầu/phê duyệt hoàn tiền

8. Tạo sổ tay ứng phó sự cố

   • Phát hiện thanh toán trùng lặp
   • Phục hồi lệnh bị kẹt
   • Vấn đề tích hợp nhà cung cấp

TỐT NẾU CÓ

9. Mã hóa cấp trường cho dữ liệu nhạy cảm

   • Dữ liệu callback thanh toán
   • ID giao dịch của nhà cung cấp

10. Giám sát xác minh chữ ký webhook

    • Cảnh báo khi xác minh thất bại
    • Theo dõi các lần thử phát lại của nhà cung cấp