pos-system/analysis/iam-architecture.md

# IAM Service Architecture Analysis

## Overview / Tổng quan

**Service**: `iam-service` - Enterprise-Grade Identity & Access Management
**TypeScript Files**: 176 files
**Status**: Production Ready (95% implementation)
**Last Updated**: Jan 4, 2026

## Module Structure / Cấu trúc Module

### Production Modules (14 modules)

```
src/modules/
├── common/          # Shared utilities, base classes
├── feature/         # Feature flags (inherited from template)
├── health/          # Health check endpoints
├── metrics/         # Prometheus metrics
├── auth/            # Core authentication (login, register, logout)
├── rbac/            # Role-Based Access Control
├── token/           # JWT & Refresh token management
├── session/         # Session management with device tracking
├── mfa/             # Multi-Factor Authentication (TOTP)
├── social/          # Social OAuth (Google, Facebook, GitHub)
├── oidc/            # OpenID Connect (Provider + Client)
├── identity/        # Identity management (users, profiles, orgs)
├── access/          # Access management (requests, reviews, analytics)
└── governance/      # Governance & compliance (reports, policies, risk)
```

### Module Breakdown

#### Core Authentication Modules

##### 1. Auth Module
**Purpose**: Core authentication flows
**Key Features**:
- Email/password registration & login
- Password reset & change
- Bcrypt hashing (cost factor 12)
- JWT token generation
- CSRF protection

**Endpoints**:
```
POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
POST /api/v1/auth/change-password
GET  /api/v1/auth/me
```

##### 2. Token Module
**Purpose**: JWT and refresh token management
**Features**:
- Access tokens (15min lifetime)
- Refresh tokens (7 days lifetime)
- Token rotation with family tracking
- Secure HTTP-only cookies
- Token blacklisting (on logout)

##### 3. Session Module
**Purpose**: User session management
**Features**:
- Device fingerprinting
- IP address tracking
- Location analysis
- Multiple concurrent sessions
- Session listing & termination

**Endpoints**:
```
GET    /api/v1/sessions           # List user sessions
DELETE /api/v1/sessions/:id       # Terminate specific session
DELETE /api/v1/sessions/all       # Terminate all sessions
```

##### 4. MFA Module
**Purpose**: Multi-Factor Authentication
**Features**:
- TOTP (Time-based One-Time Password)
- QR code generation
- Backup codes
- Device management
- Recovery procedures

**Endpoints**:
```
POST /api/v1/mfa/totp/enable
POST /api/v1/mfa/totp/verify
POST /api/v1/mfa/totp/validate
POST /api/v1/mfa/totp/disable
GET  /api/v1/mfa/devices
```

##### 5. Social Module
**Purpose**: Social OAuth integration
**Supported Providers**:
- Google OAuth 2.0
- Facebook Login
- GitHub OAuth

**Flow**:
```
User → Redirect to Provider → Callback → Create/Link Account → JWT Token
```

**Endpoints**:
```
GET /api/v1/auth/social/google
GET /api/v1/auth/social/facebook
GET /api/v1/auth/social/github
GET /api/v1/auth/social/google/callback
GET /api/v1/auth/social/facebook/callback
GET /api/v1/auth/social/github/callback
```

##### 6. OIDC Module
**Purpose**: OpenID Connect Provider & Client
**Features**:
- OIDC Provider implementation
- OIDC Client for SSO
- Discovery endpoint
- UserInfo endpoint
- Token introspection

#### Authorization Modules

##### 7. RBAC Module
**Purpose**: Role-Based Access Control
**Permission Model**: `resource:action:scope`
**Features**:
- Role management (CRUD)
- Permission management
- User-role assignments (with expiration)
- User-permission overrides (direct permissions)
- Permission caching (5min TTL)
- Group-based permissions

**Key Entities**:
- **Role**: Named collection of permissions (e.g., ADMIN, MANAGER, USER)
- **Permission**: Granular access (e.g., `users:create:org`, `posts:delete:own`)
- **UserRole**: User-role assignment (can expire)
- **UserPermission**: Direct permission grants (override roles)

**Endpoints**:
```
GET    /api/v1/rbac/roles
POST   /api/v1/rbac/roles
GET    /api/v1/rbac/permissions
POST   /api/v1/users/:id/roles
DELETE /api/v1/users/:id/roles/:roleId
POST   /api/v1/users/:id/permissions
```

**Permission Check Flow**:
```
Request → Check Direct Permissions → Check Role Permissions → Check Group Permissions → Allow/Deny
```

#### Identity Management Modules

##### 8. Identity Module
**Purpose**: User lifecycle & profile management
**Features**:
- User CRUD operations
- Extended user profiles
- Email/phone/document verification
- Multi-tenant organizations
- Groups with hierarchical structure
- Bulk user import/export
- User deactivation/reactivation

**Database Models**:
- `User` - Core user accounts
- `UserProfile` - Extended user information
- `Organization` - Multi-tenant organizations
- `Group` - User groups within orgs
- `GroupMember` - Group membership
- `IdentityVerification` - Verification records

**Endpoints**:
```
GET    /api/v1/identity/users
POST   /api/v1/identity/users
GET    /api/v1/identity/users/:id
PUT    /api/v1/identity/users/:id
POST   /api/v1/identity/users/:id/deactivate
POST   /api/v1/identity/users/:id/reactivate
GET    /api/v1/identity/users/:id/profile
PUT    /api/v1/identity/users/:id/profile
POST   /api/v1/identity/users/:id/avatar
```

#### Access Management Modules

##### 9. Access Module
**Purpose**: Access request workflows & reviews
**Features**:
- Access request workflows with multi-person approval
- Access reviews & certification campaigns
- Access analytics & usage reporting
- Anomaly detection
- Just-In-Time (JIT) access
- Temporary access grants

**Database Models**:
- `AccessRequest` - Access request workflows
- `AccessRequestApprover` - Multi-person approval chains
- `AccessReview` - Access certification campaigns
- `AccessReviewItem` - Individual review items

**Endpoints**:
```
POST /api/v1/access/requests
GET  /api/v1/access/requests
POST /api/v1/access/requests/:id/approve
POST /api/v1/access/requests/:id/reject
POST /api/v1/access/reviews
GET  /api/v1/access/reviews
POST /api/v1/access/reviews/:id/items/:itemId/review
GET  /api/v1/access/analytics/usage
```

##### 10. Governance Module
**Purpose**: Compliance & governance reporting
**Features**:
- GDPR compliance reporting
- SOC2 compliance reporting
- ISO27001 compliance reporting
- HIPAA compliance support
- Policy templates & versioning
- Risk scoring & management
- Audit log analysis

**Database Models**:
- `ComplianceReport` - Compliance reports (GDPR, SOC2, ISO27001, HIPAA)
- `PolicyTemplate` - Reusable policy templates
- `RiskScore` - User risk scoring

**Endpoints**:
```
POST /api/v1/governance/compliance/reports
GET  /api/v1/governance/compliance/reports
POST /api/v1/governance/compliance/reports/:id/generate
GET  /api/v1/governance/risk/scores
POST /api/v1/governance/risk/calculate
GET  /api/v1/governance/policies/templates
```

## Core Services / Core Services

### 1. Multi-Layer Cache Service
**Location**: `src/core/cache/`
**Pattern**: L1 (Memory) → L2 (Redis) → L3 (Database)

**Implementation**:
- **L1 Cache**: NodeCache (in-memory), 60s TTL, 10k keys max
- **L2 Cache**: Redis, 5-15min TTL, distributed
- **L3**: Prisma with connection pooling

**Cached Data**:
| Data Type | L1 TTL | L2 TTL | Use Case |
|-----------|--------|--------|----------|
| User Data | 60s | 15min | Profile, permissions |
| Permissions | 60s | 5min | Authorization checks |
| User Roles | 60s | 5min | Role assignments |
| Token Validation | N/A | Token lifetime | JWT blacklist |

**Cache Invalidation**:
```typescript
// Pattern-based invalidation
await cacheService.invalidatePattern('user:123:*');

// Event-driven invalidation
onUserUpdate → invalidateCache('user:${userId}')
onPermissionChange → invalidateCache('user:${userId}:permissions')
```

### 2. Audit Service (Event Sourcing)
**Location**: `src/core/events/`
**Purpose**: Complete audit trail for compliance

**Features**:
- Event sourcing for all authentication and authorization events
- 7-year retention for compliance (GDPR, SOC2)
- Correlation ID tracking
- Event replay capability

**Event Types**:
```typescript
enum AuditEventType {
  LOGIN_SUCCESS = 'LOGIN_SUCCESS',
  LOGIN_FAILURE = 'LOGIN_FAILURE',
  LOGOUT = 'LOGOUT',
  TOKEN_REFRESH = 'TOKEN_REFRESH',
  PASSWORD_CHANGE = 'PASSWORD_CHANGE',
  ROLE_ASSIGNED = 'ROLE_ASSIGNED',
  PERMISSION_GRANTED = 'PERMISSION_GRANTED',
  ACCESS_DENIED = 'ACCESS_DENIED',
  SESSION_CREATED = 'SESSION_CREATED',
  SESSION_TERMINATED = 'SESSION_TERMINATED',
  MFA_ENABLED = 'MFA_ENABLED',
  // ... many more
}
```

**Database Model**:
```prisma
model AuthEvent {
  id            String   @id @default(cuid())
  eventType     String   // AuditEventType
  userId        String?
  email         String?
  ipAddress     String?
  userAgent     String?
  success       Boolean
  metadata      Json?
  correlationId String?
  createdAt     DateTime @default(now())
  
  @@index([userId, createdAt])
  @@index([eventType, createdAt])
  @@index([correlationId])
}
```

### 3. Security Service (Zero-Trust Validator)
**Location**: `src/core/security/`
**Purpose**: Zero-trust security validation

**Features**:
- Device fingerprinting
- IP address analysis
- Location validation
- Behavioral analysis
- Risk-based authentication
- Anomaly detection

**Zero-Trust Checks**:
```
1. Valid JWT token? ✓
2. Token not blacklisted? ✓
3. Session still active? ✓
4. Device fingerprint matches? ✓
5. IP address in allowed range? ✓
6. No suspicious behavior detected? ✓
→ ALLOW REQUEST
```

### 4. Encryption Service
**Location**: `src/core/security/encryption.service.ts`
**Algorithm**: AES-256-GCM
**Purpose**: Encrypt PII at rest

**Features**:
- Symmetric encryption for sensitive data
- IV (Initialization Vector) per encryption
- Authentication tag for integrity
- Key rotation support

**Usage**:
```typescript
// Encrypt sensitive data
const encrypted = encryptionService.encrypt(ssn);
// Store: "iv:tag:ciphertext"

// Decrypt when needed
const ssn = encryptionService.decrypt(encrypted);
```

## Middleware Stack / Stack Middleware

```typescript
// Execution Order (from main.ts)
1. Helmet                      // Security headers
2. CORS                        // Cross-origin config
3. Rate Limiting               // Dynamic rate limiting (by role)
4. Correlation ID              // Request tracing
5. Request Logger              // Structured logging
6. Zero-Trust Validator        // Security validation
7. Body Parsers                // JSON, URL-encoded
8. Cookie Parser               // Parse cookies
9. Metrics                     // Prometheus instrumentation
10. Routes                     // API routes
11. Not Found Handler          // 404 handling
12. Error Handler              // Global error handling (LAST)
```

### Dynamic Rate Limiting
**Implementation**: Redis-backed distributed rate limiting

**Limits by Role**:
```typescript
const rateLimitsByRole = {
  anonymous: { windowMs: 15 * 60 * 1000, max: 50 },      // 50 req/15min
  user: { windowMs: 15 * 60 * 1000, max: 100 },          // 100 req/15min
  moderator: { windowMs: 15 * 60 * 1000, max: 300 },     // 300 req/15min
  admin: { windowMs: 15 * 60 * 1000, max: 500 },         // 500 req/15min
  superadmin: { windowMs: 15 * 60 * 1000, max: 1000 },   // 1000 req/15min
};
```

**Login-Specific Limit**:
```typescript
const loginLimiter = {
  windowMs: 15 * 60 * 1000,
  max: 5,  // 5 login attempts per 15 minutes
  message: 'Too many login attempts, please try again later',
};
```

## Database Schema / Schema Database

**Database**: PostgreSQL 14+
**ORM**: Prisma
**Total Models**: 30+

### Core Models

#### Authentication
- `User` - User accounts (email, password, MFA status)
- `Session` - Active sessions (device, IP, location)
- `RefreshToken` - Refresh tokens (with family tracking)
- `AuthEvent` - Audit log (event sourcing)
- `SocialAccount` - Linked OAuth accounts
- `MFADevice` - TOTP and WebAuthn devices

#### Authorization
- `Role` - Named roles (ADMIN, MANAGER, USER)
- `Permission` - Granular permissions (`resource:action:scope`)
- `UserRole` - User-role assignments (with expiration)
- `RolePermission` - Role-permission mappings
- `UserPermission` - Direct user permissions (override roles)
- `Policy` - ABAC policies (JSON Logic conditions)

#### Identity
- `Organization` - Multi-tenant organizations
- `Group` - User groups within organizations
- `GroupMember` - Group membership (with roles)
- `UserProfile` - Extended user information
- `IdentityVerification` - Email/phone/document verification

#### Access Management
- `AccessRequest` - Access request workflows
- `AccessRequestApprover` - Multi-person approval chains
- `AccessReview` - Access certification campaigns
- `AccessReviewItem` - Individual review items

#### Governance
- `ComplianceReport` - GDPR, SOC2, ISO27001, HIPAA reports
- `PolicyTemplate` - Reusable policy templates
- `RiskScore` - User risk scores

## API Surface / Bề mặt API

**Total Endpoints**: 50+
**Base Path**: `/api/v1`

### Endpoint Categories

| Category | Endpoints | Module |
|----------|-----------|--------|
| Authentication | 10+ | auth, token, session |
| Social Auth | 6 | social |
| OIDC | 5+ | oidc |
| MFA | 5 | mfa |
| RBAC | 8 | rbac |
| Identity | 12+ | identity |
| Access | 8+ | access |
| Governance | 6+ | governance |
| Health | 3 | health |
| Metrics | 1 | metrics |

## Security Features / Tính năng Bảo mật

### Defense-in-Depth Layers

1. **Network Layer**:
   - HTTPS/TLS enforcement
   - CORS configuration
   - Rate limiting (distributed)

2. **Application Layer**:
   - Helmet (security headers)
   - Input validation (Zod)
   - SQL injection prevention (Prisma ORM)
   - XSS prevention (CSP)

3. **Authentication Layer**:
   - Bcrypt (cost factor 12)
   - JWT with short lifetime (15min)
   - Refresh token rotation
   - MFA (TOTP)
   - Social OAuth

4. **Authorization Layer**:
   - RBAC (role-based)
   - ABAC (attribute-based)
   - Direct permissions (override roles)
   - Permission caching

5. **Data Layer**:
   - AES-256-GCM encryption for PII
   - Token hashing (SHA-256)
   - Password hashing (bcrypt)

6. **Audit Layer**:
   - Event sourcing
   - Correlation IDs
   - 7-year retention
   - Compliance reporting

## Performance Optimizations / Tối ưu Hiệu suất

### Caching Strategy
- **Cache Hit Rate**: 80-90% for permissions
- **Response Time**: P95 < 100ms
- **Token Validation**: < 1ms (L1 cache hit)
- **Permission Check**: < 5ms (L2 cache hit)

### Database Optimizations
- Connection pooling (Prisma default: 10)
- Indexed queries (25+ indexes)
- Selective field fetching
- Batch operations where possible

### Redis Optimizations
- Connection pooling
- Pipeline operations
- Pub/Sub for cache invalidation
- Distributed rate limiting

## Observability / Khả năng quan sát

### Metrics (Prometheus)
- HTTP request duration (by endpoint, status)
- HTTP request count
- Active sessions (gauge)
- Cache hit/miss ratio
- Database query duration
- Authentication success/failure rate
- Authorization checks (allow/deny)

### Logging (Winston)
- Structured JSON logs
- Correlation IDs in every log
- Request/response logging
- Error stack traces (dev only)
- Audit event logging

### Tracing (OpenTelemetry + Jaeger)
- HTTP request spans
- Database query spans
- Cache operation spans
- External API call spans
- Authentication flow spans

### Health Checks
- `/health/live` - Liveness (is process running?)
- `/health/ready` - Readiness (can serve traffic? checks DB + Redis)
- `/health` - Full health (with dependency status)

## Production Readiness / Sẵn sàng Production

- ✅ Multi-layer caching (L1/L2/L3)
- ✅ Zero-trust architecture
- ✅ Device fingerprinting
- ✅ Dynamic rate limiting
- ✅ Event sourcing for audit
- ✅ Compliance reporting (GDPR, SOC2, ISO27001, HIPAA)
- ✅ Multi-factor authentication
- ✅ Social OAuth integration
- ✅ OpenID Connect
- ✅ RBAC + ABAC authorization
- ✅ Encryption for PII
- ✅ Comprehensive logging
- ✅ Prometheus metrics
- ✅ Jaeger tracing
- ✅ Health checks (K8s compatible)
- ✅ Docker deployment
- ✅ Kubernetes manifests
- ✅ Graceful shutdown
- ✅ Connection pooling

## Comparison with Template / So sánh với Template

| Feature | Template | IAM Service |
|---------|----------|-------------|
| **Modules** | 4 | 14 |
| **TypeScript Files** | 38 | 176 |
| **Database Models** | 1 (example) | 30+ |
| **API Endpoints** | 5 (example) | 50+ |
| **Authentication** | ❌ | ✅ (7 methods) |
| **Authorization** | ❌ | ✅ (RBAC + ABAC) |
| **Caching** | ❌ | ✅ (3-layer) |
| **Rate Limiting** | ❌ | ✅ (Dynamic by role) |
| **Audit Logging** | Basic | ✅ (Event sourcing) |
| **Security** | Basic (Helmet) | ✅ (Zero-trust) |
| **MFA** | ❌ | ✅ (TOTP) |
| **Social OAuth** | ❌ | ✅ (3 providers) |
| **OIDC** | ❌ | ✅ (Provider + Client) |
| **Compliance** | ❌ | ✅ (4 frameworks) |
| **Encryption** | ❌ | ✅ (AES-256-GCM) |

## Summary / Tóm tắt

`iam-service` is an **enterprise-grade IAM platform** built on top of the `_template` foundation, demonstrating:

- **Complete authentication system** (password, social, OIDC, MFA)
- **Advanced authorization** (RBAC + ABAC + direct permissions)
- **Zero-trust security** (device fingerprinting, behavioral analysis)
- **High performance** (multi-layer caching, 80-90% cache hit rate)
- **Compliance-ready** (GDPR, SOC2, ISO27001, HIPAA reporting)
- **Production-hardened** (95% implementation complete)

It showcases **real-world patterns** for:
- Distributed caching
- Event sourcing
- Zero-trust architecture
- Multi-tenant support
- Access governance
- Compliance automation