User Management v1.0.0

Source: src/services/user.service.ts

Data Model

PolicyDefinition Usage

Purpose	variant	subjectType	targetType
Assign role to user	assign_role	User	Role
Map user to organizer	join_domain	User	Organizer
Map user to merchant	join_domain	User	Merchant
Grant permission to role	grant	Role	Permission
Grant permission to user	grant	User	Permission

PolicyDefinition replaces the legacy UserRole and UserMapping tables with a single Casbin-style linking model.

UserService Dependencies

Dependency	Purpose
JWKSIssuerTokenService	JWT token operations
UserConfigurationService	Post-create default configs
UserRepository	User CRUD, transactions
UserCredentialRepository	Password storage
UserIdentifierRepository	Identifier uniqueness + CRUD
UserProfileRepository	Profile CRUD
PolicyDefinitionRepository	Role/org/merchant assignments

User Creation Flow

Identifier Verification on Creation

Scheme	verified	Can Sign-In Immediately
USERNAME	true	Yes
EMAIL	false	No - requires verification
PHONE_NUMBER	false	No - requires verification

Credential Handling

• If credential is provided → hashed with Bun.password.hash() (Argon2id), stored as BASIC scheme
• If credential is omitted → step skipped entirely (e.g., customers without login)

User Update Flow

Updates are transactional with parallel sub-operations:

Identifier Update Logic

Action	Detail
Add	New identifiers not in DB → create with verified: false
Remove	DB identifiers not in request → soft-delete
Username	Not updatable via this method

Role Update Logic

Diff-based against PolicyDefinition records:

1. Fetch current assign_role (USER→ROLE) policies
2. Add: roleIds in request but not in DB → create new policies
3. Remove: policies in DB but roleId not in request → soft-delete

Employee Management

Source: src/services/employee.service.ts

Create Employee

Validation	Check	Error
Organizer access	CurrentUser has PolicyDef mapping to organizerId	403
Merchant ownership	All merchantIds belong to the organizer	403

Update Employee

• Delegates user fields to UserService.updateById()
• Merchant mappings: delete-all-then-recreate strategy via PolicyDefinitionRepository

Request Schemas

CreateEmployeeRequest = CreateUserRequest + { organizerId, merchantIds[] }

UpdateByIdEmployeeRequest = UpdateByIdUserRequest + { merchantIds[]? } (all partial)

Employee Controller Authorization

All operations are scoped via UserRepository.findIdsByPoliciesForCurrentUser():

Method	Scoping
find / count / findOne	Filter by policy-scoped employee IDs + optional organizerId/merchantIds query params
findById / deleteById	Verify ID is in policy-scoped set
create	Validates organizer ownership in EmployeeService
updateById	Validates organizer ownership in EmployeeService

User Controller

Route	Method	Description
/users	GET	List users (paginated)
/users/:id	GET	Get by ID
/users	POST	Create → UserService.create()
/users/:id	PATCH	Update → UserService.updateById()
/users/:id	DELETE	Soft-delete
/users/count	GET	Count
/users/profile	GET	Current user's profile
/users/profile	PATCH	Update current user's profile

Request Schemas

CreateUserRequest

Field	Type	Required	Validation
username	string	No	4-80 chars
credential	string	No	4-80 chars, PASSWORD_PATTERN
emails	string[]	Yes	min 1, valid email
phones	string[]	Yes	min 1, E.164
status	enum	Yes	ACTIVATED · DEACTIVATED · BLOCKED · UNKNOWN · ARCHIVED
profile	object	Yes	firstName, lastName, birthday?, locale?
roleIds	string[]	Yes	min 1

UpdateByIdUserRequest (all fields .partial())

Field	Type	Validation
emails	string[]	min 1 if provided
phones	string[]	min 1 if provided
status	enum	optional
profile	object	partial update
roleIds	string[]	min 1 if provided

UpdateUserProfileRequest (for PATCH /profile)

Field	Type
emails	string[]?
phones	string[]?
status	enum?
profile	{ firstName?, lastName?, birthday?, locale?, metadata? }

UserConfiguration Service

Source: src/services/user-configuration.service.ts

Called during _postCreate() after user creation:

UserConfiguration Controller

Method	Path	Description
CRUD	/user-configurations	Standard operations
POST	/user-configurations/views	Create config from template (validates code/name uniqueness per user)

Repositories

UserRepository

findIdsByPoliciesForCurrentUser(opts: {
  currentUserId: string;
  organizerId?: string;
  merchantIds?: string[];
  roleIdentifiers?: string[];
  transaction?: ITransaction;
}): Promise<string[]>

SQL logic: PolicyDefinition (currentUser → Organizer) → JOIN PolicyDefinition (other users → same Organizer), optional merchant/role filters → distinct User IDs.

UserIdentifierRepository

validateIdentifierUniqueness(opts: {
  identifiers: string[];
  scheme?: string;
  userId?: string;  // exclude own identifiers during update
  transaction?: ITransaction;
}): Promise<void>  // throws if duplicates found

Related Pages

• Authentication - Sign-in/up flow
• Customer Management - Customer-specific CRUD
• RBAC - PolicyDefinition model, role hierarchy
• Identity Overview - Architecture, components