ADR-0003. Tạm bỏ qua authorization trên route read License

Trường	Giá trị
Status	Accepted
Date	2026-04-15
Deciders	Phat Nguyen
Supersedes	-

Bối cảnh

• LicenseController được dựng từ ControllerFactory.defineCrudController với permission authorize riêng cho từng route (License.find, License.findById, License.count, License.findOne).
• Authorization của Casbin diễn ra theo từng merchant (domain = x-merchant-id). Nhưng một license lại được truy vấn theo entity (một User hoặc Merchant) trước khi merchant được chọn - ví dụ trong giai đoạn onboarding, user chưa có domain merchant nào đang hoạt động.
• Khi bật authz theo merchant, các thao tác đọc này sẽ trả về 403 cho những luồng hợp lệ chạy trước khi có merchant (onboarding dùng thử miễn phí, tra cứu license theo entity).
• Các route ghi (create, updateById, deleteById, deleteBy) và các hành động vòng đời không bị ảnh hưởng - chúng vẫn giữ cổng kiểm tra permission.

Quyết định

Chúng ta sẽ đặt authorize: { skip: true } trên bốn route đọc License (find, findById, count, findOne), khiến chúng chỉ yêu cầu authenticate (JWT hoặc Basic). Các dòng authorize gốc được giữ lại dưới dạng comment ngay tại chỗ để có thể khôi phục khi thiết kế scoping theo merchant ("option B") hoàn tất.

Đây rõ ràng là giải pháp tạm thời và được đánh dấu TEMP(authz-skip) trong mã nguồn.

Hệ quả

Ưu	Nhược
Các luồng onboarding trước khi có merchant chạy được, không bị 403	Các thao tác đọc License được authenticate nhưng không authorize - bất kỳ caller nào đã đăng nhập đều đọc được các bản ghi license
Không cần thay đổi IGNIS / ControllerFactory	Để lại một dấu nợ bảo mật cần phải trả về sau
Có thể đảo ngược - các permission để dạng comment đã ghi lại trạng thái đích	Dễ quên; chỉ dựa vào comment TEMP + ADR này để theo dõi

Phương án đã cân nhắc

Phương án	Ưu	Nhược	Vì sao loại
Giữ authz trên các route đọc	Kiểm soát đầy đủ	Làm hỏng onboarding trước khi có merchant (không có domain để scope)	Chặn một luồng cốt lõi
Thêm một route "tra cứu theo entity" riêng, không cần xác thực	Bề mặt hẹp	Thêm route + schema mới; trùng lặp với CRUD	Nhiều code cho một trạng thái tạm
Hiện thực authz theo entity (không theo merchant) ngay bây giờ	Đúng về dài hạn	Thiết kế lớn hơn ("option B"); chưa sẵn sàng	Hoãn lại, không phải từ bỏ

Tham chiếu

• licensing/src/controllers/license/license.controller.ts - routes.{find,findById,count,findOne}.authorize.skip + comment TEMP(authz-skip)
• Xem user memory: bật lại authorization theo merchant (Casbin domains, x-merchant-id)