Authentication v1.0.0

Source: src/services/authentication.service.ts

Dịch vụ identity kế thừa từ IssuerApplication — nó ký JWT bằng ES256 (ECDSA P-256) thông qua JWKSIssuerTokenService và công bố bộ khóa công khai tại /jw-certs. Tất cả các dịch vụ khác kế thừa từ VerifierApplication và xác minh token bằng cách lấy public key này.

Phụ thuộc

Sign-In

Luồng

Các Bước Validation

Bước	Kiểm tra	Lỗi
1	UserIdentifier tồn tại theo (scheme, identifier)	404 — identifier không tìm thấy
2	userIdentifier.verified === true	403 — chưa được xác minh
3	User tồn tại với status: ACTIVATED	404 — user không tìm thấy
4	User có credential cho scheme	403 — không có credentials
5	Bun.password.verify() khớp	401 — credential không hợp lệ

Chỉ scheme credential BASIC (password) được triển khai. Các scheme khác (2fa, oauth, oauth2) sẽ throw 400 Unsupported credential scheme.

JWT Token Payload

Field	Type	Nguồn
userId	string	Snowflake ID của User
roles	Array<{id, identifier, priority}>	PolicyDefinition GROUP (USER→ROLE)
clientId	string	Từ request sign-in (tùy chọn)
organizerIds	string	Cách nhau bởi dấu phẩy, từ PolicyDefinition GROUP (USER→ORGANIZER)
merchantIds	string	Cách nhau bởi dấu phẩy, từ PolicyDefinition GROUP (USER→MERCHANT)
iat / exp	number	Được IGNIS tự thêm

Response

{
  userId: string,
  roles: Array<{ id: string, identifier: string, priority: number }>,
  token: { value: string, type: 'Bearer' }
}

Sign-Up

Luồng

Hành vi Chính

• Tất cả người dùng sign-up → status: ACTIVATED + role OWNER (priority 500, identifier 500_organizer-owner). (Đánh dấu là TODO — mặc định tạm thời)
• Xác minh email khi sign-up đã được comment — hiện không gửi.
• Luồng sign-up không phát sự kiện nào (không broadcast WebSocket, không enqueue queue). Client phải gọi rõ ràng endpoint Commerce onboarding (POST /organizers/on-boarding) sau khi sign-up để tạo cây phân cấp merchant.

Request Schema

SignUpRequest {
  username:   string    // 4–80 chars, required
  credential: string    // 4–80 chars, must match PASSWORD_PATTERN, required
  emails:     string[]  // min 1, valid email format
  phones:     string[]  // min 1, E.164 format
  firstName:  string    // 1–255 chars
  lastName:   string    // 1–255 chars
  birthday?:  string    // ISO date
  locale?:    string
}

Đổi Mật khẩu

Quy tắc	Chi tiết
Chỉ tự đổi	currentUser.userId phải khớp với userId trong request (admin bypass là TODO)
Kiểm tra mật khẩu cũ	Bun.password.verify() so với hash đã lưu
Hash mật khẩu mới	Bun.password.hash() (Argon2id)
Mã lỗi	404 không tìm thấy credential, 401 mật khẩu cũ sai, 401 không có quyền

Request Schema

ChangePasswordRequest {
  scheme:        string  // e.g., 'basic'
  oldCredential: string  // 4–80 chars, PASSWORD_PATTERN
  newCredential: string  // 4–80 chars, PASSWORD_PATTERN
  userId:        string
}

Identifier Schemes

Source: src/common/constants.ts — UserIdentifierSchemes

Scheme	Value	Tự Verify	Có thể Sign-In
USERNAME	username	Có	Có
EMAIL	email	Không	Sau khi xác minh
PHONE_NUMBER	phone_number	Không	Sau khi xác minh
NX_AUTH	nx_auth	—	Sử dụng nội bộ
USER_NUMBER	user_number	—	Sử dụng nội bộ

Credential Schemes

Scheme	Value	Trạng thái
BASIC	basic	Đã triển khai — Bun.password (Argon2id)
TWO_FA	2fa	Chỉ định nghĩa
OAUTH	oauth	Chỉ định nghĩa
OAUTH2	oauth2	Chỉ định nghĩa

Quy tắc Validation

Source: src/common/validations.ts

Quy tắc	Giá trị
Độ dài Username	4–80 ký tự
Độ dài Password	4–80 ký tự
Pattern Password	^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$ (1 chữ hoa + 1 chữ thường + 1 chữ số)
Định dạng SĐT	^\+?[1-9]\d{1,14}$ (E.164)
Độ dài chuỗi	1–255 ký tự

Auth Endpoints

Method	Path	Auth	Request	Response
POST	/auth/sign-in	—	SignInRequest	SignInResponse
POST	/auth/sign-up	—	SignUpRequest	SignUpResponse
POST	/auth/change-password	JWT	ChangePasswordRequest	{ message }
GET	/auth/user-information	JWT	—	{} (placeholder)

Luồng JWKS (Cross-Service)

Trang Liên quan

• User Management — Chi tiết UserService.create()
• RBAC — Phân cấp role, PolicyDefinition
• MFA & OTP — Xác thực OTP (đăng nhập email/SĐT, quên mật khẩu)
• Identity Overview — Kiến trúc, components