Chuyển tới nội dung chính

Module Auth và Sessions

Overview​

Xử lý toàn bộ vòng đời danh tính: đăng ký, xác thực OTP, đăng nhập (mật khẩu và Google), cấp và làm mới token, quản lý phiên theo thiết bị, đổi hoặc đặt lại mật khẩu, và xóa tài khoản có thời gian chờ. sessions là module nhỏ đi kèm, lưu và quản lý các phiên.

Responsibilities​

  • Cấp access token (JWT, trả trong body) và refresh token (JWT, đặt trong cookie refresh_token).
  • Lưu phiên, giới hạn 5 phiên đồng thời, xoay vòng refresh token.
  • Xác thực email bằng OTP, chống đoán mã.
  • Kiểm tra trạng thái tài khoản ở mọi request.

Architecture​

Thành phầnFileVai trò
Controllerauth.controller.ts17 route dưới /api/v1/auth
Facadeauth.service.tsỦy quyền cho 5 service con
Phiên và tokenauth-session.service.tsTạo, làm mới, hủy phiên, đặt cookie
Thông tin đăng nhậpauth-credentials.service.tsKiểm tra mật khẩu, đổi, đặt, quên mật khẩu
Xác thực emailauth-verification.service.tsSinh, gửi, kiểm tra OTP
Googleauth-google.service.tsXác minh ID token Google
Xóa tài khoảnauth-account-deletion.service.tsĐặt lịch, hủy, token hủy
Passportpassport/Ba chiến lược: local, jwt, jwt-refresh
Guardguards/JwtAuthGuard, LocalAuthGuard, JwtRefreshGuard
Sessionssessions.service.tsTruy cập collection sessions

Dependencies​

auth import users, sessions (xem module-dependencies). Dùng thêm MailService để gửi OTP và email xóa tài khoản, Redis cho OTP, và AccountDeletionQueueService để lên lịch xóa.

Business Rules​

Chủ đềQuy tắcNguồn
OTP6 chữ số ngẫu nhiên bằng crypto.randomInt. Lưu HMAC-SHA256 trong Redis otp:value:<email> hiệu lực 300 giâyotp.utils.ts, verification service
Chống đoán OTPĐếm otp:attempts:<email>, từ 5 lần sai trở lên bị 403. Chờ 60 giây giữa hai lần gửi (otp:cooldown:<email>)verification service
Access tokenKý bằng JWT_ACCESS_TOKEN_SECRET, thời hạn JWT_ACCESS_EXPIRES_IN. Trả trong body phản hồisession service
Refresh tokenKý bằng JWT_REFRESH_TOKEN_SECRET, đặt cookie refresh_token: httpOnly, secure khi NODE_ENV=production, sameSite=strict, maxAge theo JWT_REFRESH_EXPIRES_INsetRefreshCookie
Lưu phiênChỉ lưu HMAC-SHA256 của refresh token, không lưu token thôsessions.service.ts
Xoay vòngMỗi lần làm mới: xóa phiên cũ rồi tạo phiên mới với refresh token mớirefreshAccessToken
Giới hạn phiênTối đa 5, xóa phiên có lastUsedAt cũ nhấtenforceSessionLimit
Trạng thái tài khoảnMỗi request kiểm tra isActive, isLocked, isDeleted, scheduledDeletionAtassert-authenticated-account-state.util.ts
GoogleXác minh ID token với GOOGLE_CLIENT_ID, yêu cầu email_verifiedauth-google.service.ts
Xóa tài khoảnChờ 30 ngày. Trong thời gian chờ, đăng nhập bị 403 trừ khi hủydeletion service

JwtStrategy.validate tải người dùng từ database ở mỗi request để kiểm tra trạng thái (jwt.strategy.ts). Nhờ đó khóa tài khoản có hiệu lực ngay cả khi access token chưa hết hạn, đổi lại mỗi request có thêm một lần truy vấn.

Data Model​

Collection users và sessions. OTP lưu ở Redis, không ở MongoDB.

API​

Chi tiết từng route: 05-api/endpoints/auth.md (Phase 3). Giới hạn riêng bằng @Throttle (ghi đè throttler default, hai throttler burst 5/giây và sustained 20/10 giây khai báo ở AppModule vẫn áp dụng):

RouteGiới hạn default
POST /auth/login, POST /auth/verify, POST /auth/google/login10 lần mỗi 5 phút
POST /auth/resend-code, POST /auth/change-password, POST /auth/set-password, POST /auth/reset-password, POST /auth/account/cancel-deletion, POST /auth/account/cancel-deletion-by-token5 lần mỗi 5 phút
POST /auth/register5 lần mỗi giờ
DELETE /auth/account3 lần mỗi giờ
POST /auth/forgot-passwordKhông có giới hạn riêng, chỉ chịu throttler toàn cục

Bảng ghép theo từng handler, đọc từ auth.controller.ts.

Processing Flow​

Sequence đăng nhập, làm mới token và xác thực OTP nằm ở 06-workflows/sequences/refresh-token.md và 06-workflows/use-cases/authentication.md (Phase 3).

Error Handling​

Tình huốngPhản hồi
Chưa kích hoạt khi đăng nhập400 "Tài khoản chưa được kích hoạt"
Bị khóa, bị xóa, hoặc vô hiệu401
Đang chờ xóa403
OTP sai400 kèm số lần còn lại
OTP quá 5 lần sai403
Gửi lại OTP khi còn cooldown400 kèm số giây phải chờ

Known Limitation​

Vấn đềChi tiết
Token đặt lại mật khẩu và hủy xóa tài khoản lưu qua CACHE_MANAGERCACHE_MANAGER chạy trong bộ nhớ (đã kiểm chứng), nên các link này mất hiệu lực khi backend khởi động lại và không dùng được giữa nhiều instance. Xem data-flow
Index trùng ở sessionsTTL của expiresAt có thể không tồn tại, xem sessions
Truy vấn người dùng mỗi requestChi phí đổi lấy khóa tài khoản có hiệu lực tức thì
Hủy xóa tài khoản bằng đăng nhập không dùng đượcPOST /auth/account/cancel-deletion yêu cầu JWT, nhưng JwtStrategy.validate gọi assertAuthenticatedAccountState(user, 'access') và ném 403 khi scheduledDeletionAt còn ở tương lai. Người dùng đang chờ xóa vì vậy không qua được guard để hủy. Đường còn lại là POST /auth/account/cancel-deletion-by-token, nhưng token nằm trong CACHE_MANAGER (bộ nhớ), mất khi backend khởi động lại. Kết luận từ đọc mã (jwt.strategy.ts, assert-authenticated-account-state.util.ts, auth-account-deletion.service.ts), chưa chạy thử vì cần MongoDB. Service có test riêng nhưng không bao quát đường đi qua guard

Testing​

9 file test trong src/auth/ và 1 trong src/sessions/, gồm các service con, util trạng thái tài khoản và bộ dữ liệu test dùng chung (auth-test-data.ts). Chưa ghi nhận phạm vi bao phủ chi tiết.

Source References​

src/auth/, src/sessions/, jwt-auth.guard.ts.