Authentication v1.0.0

Source: src/services/authentication.service.ts

The identity service extends IssuerApplication — it signs JWTs with ES256 (ECDSA P-256) via JWKSIssuerTokenService and publishes the public key set at /jw-certs. All other services extend VerifierApplication and verify tokens by fetching this public key.

Dependencies

Sign-In

Flow

Validation Steps

Step	Check	Error
1	UserIdentifier exists by (scheme, identifier)	404 — identifier not found
2	userIdentifier.verified === true	403 — not verified
3	User exists with status: ACTIVATED	404 — user not found
4	User has credential for the scheme	403 — no credentials
5	Bun.password.verify() matches	401 — invalid credential

Only BASIC (password) credential scheme is implemented. Others (2fa, oauth, oauth2) throw 400 Unsupported credential scheme.

JWT Token Payload

Field	Type	Source
userId	string	User Snowflake ID
roles	Array<{id, identifier, priority}>	PolicyDefinition GROUP (USER→ROLE)
clientId	string	From sign-in request (optional)
organizerIds	string	Comma-separated, from PolicyDefinition GROUP (USER→ORGANIZER)
merchantIds	string	Comma-separated, from PolicyDefinition GROUP (USER→MERCHANT)
iat / exp	number	Added by IGNIS

Response

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

Sign-Up

Flow

Key Behaviors

• All sign-up users → status: ACTIVATED + OWNER role (priority 500, identifier 500_organizer-owner). (Marked as TODO — temporary default)
• Email verification on sign-up is commented out — not sent currently.
• The sign-up flow does not emit any event (no WebSocket broadcast, no queue enqueue). The client must explicitly call the Commerce onboarding endpoint (POST /organizers/on-boarding) after sign-up to create the merchant hierarchy.

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
}

Change Password

Rule	Detail
Self-only	currentUser.userId must match request userId (admin bypass is TODO)
Old password check	Bun.password.verify() against stored hash
New password hash	Bun.password.hash() (Argon2id)
Error codes	404 credential not found, 401 old password wrong, 401 unauthorized

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	Auto-Verified	Can Sign-In
USERNAME	username	Yes	Yes
EMAIL	email	No	After verification
PHONE_NUMBER	phone_number	No	After verification
NX_AUTH	nx_auth	—	Internal use
USER_NUMBER	user_number	—	Internal use

Credential Schemes

Scheme	Value	Status
BASIC	basic	Implemented — Bun.password (Argon2id)
TWO_FA	2fa	Defined only
OAUTH	oauth	Defined only
OAUTH2	oauth2	Defined only

Validation Rules

Source: src/common/validations.ts

Rule	Value
Username length	4–80 characters
Password length	4–80 characters
Password pattern	^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$ (1 upper + 1 lower + 1 digit)
Phone format	^\+?[1-9]\d{1,14}$ (E.164)
String length	1–255 characters

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)

JWKS Flow (Cross-Service)

Related Pages

• User Management — UserService.create() details
• RBAC — Role hierarchy, PolicyDefinition
• MFA & OTP — OTP-based authentication (email/phone sign-in, forgot password)
• Identity Overview — Architecture, components