Kiến trúc
1. System Context (C4 L1)
Identity là trust root — mọi JWT trong nền tảng đều được service này ký. JWKS tại
/jw-certslà endpoint công khai mà các sister service dùng để xác minh chữ ký.
2. Container View (C4 L2)
3. Component View (C4 L3) — Phân lớp nội bộ
| Lớp | Trách nhiệm |
|---|---|
| Routes | 12 base path trong RestPaths |
| Controllers | Auth gate (JWT / BASIC) + permission |
| Services | Business logic (auth + RBAC + OTP + quản lý user) |
| Repositories | Truy vấn Drizzle; lookup theo identifier |
| Components | Mail / SMS / WebSocket |
| Token service | JWKSIssuerTokenService từ @nx/core (ES256 signer) |
4. Máy trạng thái
Identity có rất ít state-machine; phần lớn flow là chuỗi validation thay vì máy trạng thái persistent.
| Entity | Trạng thái | Ghi chú |
|---|---|---|
User.status | ACTIVATED / DEACTIVATED / LOCKED | guard cho sign-in |
UserIdentifier.verified | false → true | xác thực qua OTP/token |
Role.type | SYSTEM / CUSTOM / UNKNOWN | Bản ghi SYSTEM bất biến |
5. Kịch bản Runtime
5.1 Đăng nhập (BASIC scheme)
5.2 Đăng ký
5.3 Email OTP — Flow xác thực Email
5.4 Sister Service xác minh JWKS
6. Vấn đề xuyên suốt
| Vấn đề | Cách service xử lý |
|---|---|
| Ký token | ES256 qua JWKSIssuerTokenService (từ @nx/core); private key từ environment / secure config |
| Xác minh token | KHÔNG thực hiện ở đây — sister service pull JWKS qua HTTP và xác minh tại chỗ |
| Lưu trữ mật khẩu | Bun.password hashing (kiểu argon2, mặc định nội bộ) |
| Lưu trữ OTP | Redis với TTL — mã đã hash + bộ đếm số lần thử + cooldown + hạn ngạch hàng ngày |
| i18n | Templates Mail/SMS có EN + VI; locale của user quyết định khi gửi |
| Logging | IGNIS structured (key: %s); request-id được truyền xuyên suốt |
| AuthZ | Casbin + cạnh PolicyDefinition; permissions cache trong Redis |
| Soft-delete | SoftDeletableRepository — deletedAt; tính duy nhất của identifier giới hạn ở deletedAt IS NULL |
| IDs | Snowflake qua IdGenerator, worker 1 |