Database Schema

Sơ đồ quan hệ (ER Diagram)

Chi tiết từng bảng

authenticators

Lưu trữ các phương thức xác thực đã cấu hình. Model: AuthModel (extends Model, implements Authenticator).

Cột	Kiểu	Ràng buộc	Mô tả
id	bigInt	PK, autoIncrement	Khóa chính
name	string	unique, not null	Tên định danh (ví dụ: basic, oidc-google)
authType	string	not null	Loại xác thực, map với registerTypes() (ví dụ: Email/Password)
title	string	nullable	Tên hiển thị, hỗ trợ translation
description	string	not null, default ''	Mô tả
options	json	not null, default {}	Cấu hình tùy chỉnh theo authType
enabled	boolean	default false	Bật/tắt authenticator
sort	bigInt	sortable	Thứ tự hiển thị
createdById	bigInt	FK	Người tạo
updatedById	bigInt	FK	Người cập nhật
createdAt	date		Thời gian tạo
updatedAt	date		Thời gian cập nhật

Quan hệ: belongsToMany tới users qua bảng trung gian usersAuthenticators, với sourceKey: 'name', foreignKey: 'authenticator', targetKey: 'id', otherKey: 'userId'. onDelete: CASCADE.

Cấu trúc options (BasicAuth):

{
  "public": {
    "allowSignUp": true,
    "enableResetPassword": true,
    "signupForm": [
      { "field": "username", "show": true, "required": true },
      { "field": "email", "show": true, "required": false }
    ]
  },
  "notificationChannel": "email-channel-name",
  "emailSubject": "Reset password for $systemSettings.title",
  "emailContentType": "html",
  "emailContentHTML": "<p>Click <a href='$resetLink'>here</a> to reset</p>",
  "resetTokenExpiresIn": 20
}

---

usersAuthenticators

Bảng trung gian M2M giữa authenticators và users. Lưu thông tin user theo từng phương thức xác thực (SSO uuid, avatar từ provider, metadata).

Cột	Kiểu	Ràng buộc	Mô tả
uuid	string	not null	ID duy nhất của user trong auth provider (ví dụ: Google OpenID, số điện thoại)
displayname	string	not null, default ''	Tên hiển thị từ provider
avatar	string	not null, default ''	Avatar URL từ provider
meta	json	default {}	Metadata bổ sung (tokens, profile data...)
authenticator	string	FK → authenticators.name	Tên authenticator
userId	bigInt	FK → users.id	ID user trong hệ thống
createdById	bigInt	FK	Người tạo
updatedById	bigInt	FK	Người cập nhật
createdAt	date		Thời gian tạo
updatedAt	date		Thời gian cập nhật

AuthModel sử dụng bảng này qua các phương thức:

• findUser(uuid) — tìm user qua through.where: { uuid }
• newUser(uuid, values) — tạo user mới kèm record trong bảng này
• findOrCreateUser(uuid, values) — tìm hoặc tạo mới

---

issuedTokens

Theo dõi các JWT đã cấp, dùng cho token renewal và session management.

Cột	Kiểu	Ràng buộc	Mô tả
id	uuid	PK	Khóa chính (giá trị ban đầu = jti)
jti	uuid	not null, indexed	JSON Token Identifier hiện tại
signInTime	bigInt	not null	Timestamp (ms) khi user đăng nhập (không đổi khi renew)
issuedTime	bigInt	not null	Timestamp (ms) lần cấp/renew gần nhất
userId	bigInt	not null	ID user
createdAt	date		Thời gian tạo record
updatedAt	date		Thời gian cập nhật record

Cách hoạt động:

• Khi signIn: TokenController.add() tạo record với jti = randomUUID(), signInTime = issuedTime = Date.now()
• Khi renew: TokenController.renew(oldJti) cập nhật jti thành UUID mới và issuedTime thành Date.now()
• Session hết hạn: removeSessionExpiredTokens() xóa record có signInTime < now - sessionExpirationTime

---

tokenBlacklist

Lưu các token bị revoke (signOut, resetPassword đã dùng).

Cột	Kiểu	Ràng buộc	Mô tả
token	string	indexed	Nội dung token JWT
expiration	date		Thời điểm token hết hạn tự nhiên

TokenBlacklistService sử dụng 2 tầng kiểm tra:

1. Redis Bloom filter (nếu có Redis): kiểm tra nhanh O(1), false positive rate 0.1%, capacity 1 triệu token
2. Database query: xác nhận chính xác nếu Bloom filter trả true

Khi thêm token vào blacklist (add), service cũng gọi deleteExpiredTokens() để dọn dẹp token đã hết hạn tự nhiên.

---

tokenControlConfig

Cấu hình token policy cho toàn hệ thống.

Cột	Kiểu	Ràng buộc	Mô tả
key	string	PK, not null	Khóa cấu hình, mặc định 'token-policy-config'
config	json	not null, default {}	Object chứa cấu hình policy
createdById	bigInt	FK	Người tạo
updatedById	bigInt	FK	Người cập nhật
createdAt	date		Thời gian tạo
updatedAt	date		Thời gian cập nhật

Cấu trúc config:

{
  "tokenExpirationTime": "1d",
  "sessionExpirationTime": "7d",
  "expiredTokenRenewLimit": "1d"
}

Giá trị dùng format ms (1d = 86400000ms, 2h = 7200000ms). Khi save, event tokenControlConfig.afterSave tự động gọi tokenController.setConfig() để cập nhật cache.

---

Migration history

Migration	Mô tả
20230506152253-basic-authenticator	Tạo bảng authenticators và usersAuthenticators
20230607174500-update-basic	Cập nhật cấu hình authenticator basic
20231218132032-fix-allow-signup	Sửa option allowSignUp
20241229080941-create-token-policy-config	Tạo bảng tokenControlConfig