Core Module (Auth, Users, KYC)

Overview

The Core Module is the foundational module of the IWM Platform, responsible for identity management, authentication, authorization, and KYC (Know Your Customer) verification. All other modules depend on Core for user identity and access control.

Responsibilities

• User registration and account management
• Authentication (email/password, OAuth providers)
• Two-factor authentication (2FA)
• Session management (JWT tokens)
• KYC verification workflow
• Role-based access control (RBAC)
• Password security and account protection

---

Domain Entities

User

The central identity entity representing a platform user.

Field	Type	Description
id	UUID	Primary identifier
email	VARCHAR(255)	Unique email address
phone	VARCHAR(20)	Optional phone number (unique)
password_hash	VARCHAR(255)	Bcrypt hashed password
status	ENUM	Account status
email_verified_at	TIMESTAMP	Email verification timestamp
phone_verified_at	TIMESTAMP	Phone verification timestamp
last_login_at	TIMESTAMP	Last successful login
created_at	TIMESTAMP	Account creation time
updated_at	TIMESTAMP	Last modification time

UserProfile

Extended user information for personalization and compliance.

Field	Type	Description
id	UUID	Primary identifier
user_id	UUID	Reference to User
first_name	VARCHAR(100)	Legal first name
last_name	VARCHAR(100)	Legal last name
middle_name	VARCHAR(100)	Middle name (patronymic)
date_of_birth	DATE	Birth date for KYC
avatar_url	VARCHAR(500)	Profile image URL
language	VARCHAR(10)	Preferred language code
timezone	VARCHAR(50)	User timezone

Session

Active user sessions for authentication state.

Field	Type	Description
id	UUID	Session identifier
user_id	UUID	Reference to User
refresh_token_hash	VARCHAR(255)	Hashed refresh token
device_fingerprint	VARCHAR(255)	Device identification
ip_address	INET	Client IP address
user_agent	TEXT	Browser/client info
expires_at	TIMESTAMP	Session expiration
revoked_at	TIMESTAMP	Manual revocation time

KycVerification

KYC verification process state and data.

Field	Type	Description
id	UUID	Verification identifier
user_id	UUID	Reference to User
status	ENUM	Verification status
level	ENUM	Verification level achieved
personal_info	JSONB	Encrypted personal data
submitted_at	TIMESTAMP	Submission time
reviewed_at	TIMESTAMP	Review completion time
reviewed_by	UUID	Admin who reviewed
rejection_reason	TEXT	Reason if rejected
expires_at	TIMESTAMP	Verification expiry

KycDocument

Documents uploaded for KYC verification.

Field	Type	Description
id	UUID	Document identifier
verification_id	UUID	Reference to KycVerification
document_type	ENUM	Type of document
file_key	VARCHAR(500)	S3/storage key
file_name	VARCHAR(255)	Original filename
mime_type	VARCHAR(100)	File MIME type
status	ENUM	Document status
ocr_data	JSONB	Extracted OCR data
rejection_reason	TEXT	Reason if rejected

---

User Lifecycle States

Users progress through defined states during their lifecycle:

Status Definitions

Status	Description	Allowed Actions
PENDING_VERIFICATION	Account created, awaiting email verification	Resend verification, view limited content
ACTIVE	Fully verified and operational account	All platform features
SUSPENDED	Temporarily restricted due to policy violation	View only, submit appeal
BANNED	Permanently banned from platform	None

---

Authentication Methods

Email/Password Authentication

Primary authentication method using email and password:

1. Registration: User provides email and password
2. Password Hashing: bcrypt with cost factor 12
3. Email Verification: Unique token sent via email
4. Login: Email + password verification
5. Session Creation: JWT access token + refresh token issued

OAuth Providers

Supported social login providers:

Provider	Type	Identifier
Google	GOOGLE	provider_user_id from Google
Facebook	FACEBOOK	provider_user_id from Facebook
Apple	APPLE	provider_user_id from Apple ID
Telegram	TELEGRAM	provider_user_id from Telegram

OAuth Flow:

1. User initiates OAuth with provider
2. Provider redirects with authorization code
3. Backend exchanges code for tokens
4. User profile fetched from provider
5. Account linked or created
6. Platform session issued

---

Two-Factor Authentication (2FA)

TOTP (Time-based One-Time Password)

Primary 2FA method using authenticator apps:

Configuration:

• Algorithm: SHA-1
• Digits: 6
• Period: 30 seconds
• Secret: 32 bytes, base32 encoded

SMS Backup

Fallback 2FA method via SMS:

1. User requests SMS backup
2. System sends 6-digit code to verified phone
3. Code valid for 5 minutes
4. Maximum 3 attempts per code

---

Session Management

Token Architecture

The platform uses a dual-token system:

Access Token (JWT)

Claim	Description
sub	User ID (UUID)
email	User email
roles	Array of role codes
iat	Issued at timestamp
exp	Expiration timestamp

Concurrent Sessions

• Users can have multiple active sessions
• Each device/browser creates a separate session
• Sessions tracked with device fingerprint
• User can view and revoke individual sessions
• Security: Suspicious activity triggers session review

Session Revocation

Sessions can be revoked:

• Manually by user (logout, security settings)
• Automatically on password change
• Automatically on security incident
• By admin action

---

KYC Workflow

Verification Levels

Level	Requirements	Unlocked Features
NONE	No verification	View only, limited actions
BASIC	Email + phone verified	Basic purchases, limited investments
STANDARD	ID document verified	Full platform access
ENHANCED	Address proof + selfie	High-value transactions

KYC Status Flow

Document Types

Type	Required For	Description
PASSPORT	STANDARD	Government-issued passport
ID_CARD	STANDARD	National ID card
DRIVER_LICENSE	STANDARD	Driver's license with photo
UTILITY_BILL	ENHANCED	Address proof (recent)
BANK_STATEMENT	ENHANCED	Financial address proof
SELFIE	ENHANCED	Live selfie with document

---

Security Features

Password Security

• Hashing: bcrypt with cost factor 12
• Requirements: Minimum 8 characters, mixed case, numbers
• History: Last 5 passwords cannot be reused
• Expiry: Optional forced rotation (configurable)

Brute-Force Protection

Thresholds:

• 5 failed attempts: 5-minute delay
• 10 failed attempts: 15-minute lockout
• 20 failed attempts: Account locked, email verification required

Rate Limiting

Endpoint	Limit	Window
POST /auth/login	10 requests	1 minute
POST /auth/register	5 requests	1 minute
POST /auth/forgot-password	3 requests	5 minutes
POST /auth/verify-2fa	5 requests	1 minute

---

Events Published

The Core Module publishes the following domain events for inter-module communication:

Event	Trigger	Payload
UserRegistered	New user registration	userId, email, referralCode
UserVerified	Email verification complete	userId, email
UserStatusChanged	Account status change	userId, fromStatus, toStatus, reason
UserProfileUpdated	Profile information changed	userId, changedFields
UserLoggedIn	Successful login	userId, ipAddress, userAgent
UserLoggedOut	User logout	userId, sessionId
SessionRevoked	Session manually revoked	userId, sessionId, reason
TwoFactorEnabled	2FA activated	userId, method
TwoFactorDisabled	2FA deactivated	userId, method
KycStatusChanged	KYC status transition	userId, fromStatus, toStatus, level
KycDocumentUploaded	Document uploaded for KYC	userId, verificationId, documentType
KycApproved	KYC verification approved	userId, level, approvedBy
KycRejected	KYC verification rejected	userId, reason, rejectedBy
PasswordChanged	User changed password	userId, changedAt
PasswordResetRequested	Password reset initiated	userId, email

---

Business Rules and Invariants

User Rules

1. Email must be unique across all users
2. Phone number, if provided, must be unique
3. User cannot be deleted if they have active orders or investments
4. Status transitions must follow defined state machine
5. Only ACTIVE users can perform transactions

Session Rules

1. Access token lifetime: 15 minutes (non-configurable)
2. Refresh token lifetime: 7 days
3. Maximum concurrent sessions per user: 10
4. Session must be revoked on password change
5. Inactive sessions auto-expire after refresh token expiry

KYC Rules

1. KYC verification expires after 1 year (for ENHANCED level)
2. User cannot submit new KYC while previous is UNDER_REVIEW
3. Rejected KYC allows resubmission after 24 hours
4. ENHANCED level requires STANDARD level first
5. KYC data must be encrypted at rest

---

Integration Points

Provides to Other Modules

Interface	Consumers	Purpose
IUserLookupService	MLM, Commerce, Investment	Fetch user profile data
IKycStatusService	Investment, MLM	Check KYC verification status
IAuthenticationService	All modules	Validate tokens, get current user
IRoleService	Admin	Check user permissions

Consumes from Other Modules

The Core Module is foundational and does not consume services from other business modules.

---

Related Documents

• Core Schema
• Module Architecture
• API Structure