Kiến trúc plugin-auth

Tổng quan

@digiforce-nc/plugin-auth xây dựng trên nền AuthManager của core @digiforce-nc/auth. Plugin cung cấp:

• Storer — cache và quản lý danh sách authenticator từ DB
• BasicAuth — phương thức xác thực email/password mặc định
• TokenController — quản lý vòng đời JWT (cấp phát, gia hạn JTI, xóa session hết hạn)
• TokenBlacklistService — revoke token bằng DB + Redis Bloom filter

Vòng đời khởi tạo (Lifecycle)

Plugin khởi tạo theo thứ tự:

Chi tiết từng giai đoạn

Giai đoạn	Phương thức	Công việc
afterAdd	app.on('afterLoad')	Tạo cache auth-token-controller, khởi tạo TokenController, đọc tokenControlConfig từ DB
beforeLoad	beforeLoad()	Đăng ký AuthModel vào database
load	load()	Tạo Storer, TokenBlacklistService, đăng ký BasicAuth, bind actions, cấu hình ACL
install	install()	Tạo authenticator basic mặc định, tạo token policy config mặc định

Phân cấp class (Class hierarchy)

Middleware pipeline

Mỗi HTTP request đi qua AuthManager.middleware():

Trong auth.check(), TokenController kiểm tra:

1. Decode JWT, lấy jti (JSON Token Identifier)
2. Tìm jti trong bảng issuedTokens
3. Kiểm tra signInTime + sessionExpirationTime chưa quá hạn
4. Nếu issuedTime + tokenExpirationTime đã quá hạn nhưng còn trong expiredTokenRenewLimit → renew JTI, trả header x-new-token
5. Nếu token bị blacklist → reject

Storer pattern

Storer cache danh sách authenticator đã bật vào memory cache dưới dạng object { [name]: AuthModel }.

Invalidation tự động:

• authenticators.afterSave → nếu enabled, cập nhật cache; nếu không, xóa khỏi cache
• authenticators.afterDestroy → xóa khỏi cache

renderJsonTemplate: Trước khi cache, Storer gọi app.environment.renderJsonTemplate() trên trường options để thay thế biến môi trường. Các key trong optionsKeysNotAllowedInEnv (như emailContentText, emailContentHTML, emailSubject của BasicAuth) được bỏ qua, không render template.

// Ví dụ options trong DB có thể chứa biến env
{
  "public": { "allowSignUp": true },
  "clientId": "$env.OIDC_CLIENT_ID",
  "clientSecret": "$env.OIDC_CLIENT_SECRET"
}
// Sau renderJsonTemplate, biến env được thay bằng giá trị thực

Extension points

Plugin khác có thể mở rộng hệ thống auth qua AuthManager:

Phương thức	Mục đích
registerTypes(authType, config)	Đăng ký loại authenticator mới (OIDC, LDAP, SAML, SMS...)
setStorer(storer)	Thay thế Storer mặc định
setTokenBlacklistService(service)	Thay thế blacklist service (ví dụ chỉ dùng Redis)
setTokenControlService(service)	Thay thế token controller

Đăng ký authenticator type mới

// Trong plugin.load() của plugin khác
this.app.authManager.registerTypes('oidc', {
  auth: MyOIDCAuth,           // Class kế thừa BaseAuth
  title: 'OIDC Login',
  getPublicOptions: (options) => {
    // Trả về options an toàn cho client
    return { issuer: options.issuer };
  },
});

AuthConfig bao gồm:

Thuộc tính	Kiểu	Mô tả
auth	AuthExtend<Auth>	Class xác thực, kế thừa BaseAuth
title	string	Tên hiển thị trên UI
getPublicOptions	(options) => object	Hàm lọc options trả về cho trang login (publicList)

ACL snippets

Plugin đăng ký các ACL snippet sau:

Snippet	Phạm vi
pm.<plugin-name>.authenticators	Toàn bộ action trên resource authenticators
pm.security.token-policy	Toàn bộ action trên tokenControlConfig

Các action public (không cần đăng nhập): signIn, signUp, lostPassword, resetPassword, checkResetToken, authenticators:publicList.

Các action yêu cầu đăng nhập: check, signOut, changePassword.