# Story 2.2: Identity Management System

## Metadata
- **Story ID**: 2.2
- **Title**: Identity Management System
- **Epic**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.2, 2.1

## Goal
Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.

## Description
This story implements the complete user identity management system including user registration, email verification, password reset, password change, and user profile management. All operations are secured and audited.

## Deliverables

### 1. Identity Interfaces (`pkg/identity/identity.go`)
- `UserRepository` interface for user data access
- `UserService` interface for user business logic
- User domain models

### 2. User Repository (`internal/identity/user_repo.go`)
- CRUD operations using Ent
- Password hashing (bcrypt or argon2)
- Email uniqueness validation
- User lookup by ID and email
- User search and pagination

### 3. User Service (`internal/identity/user_service.go`)
- User registration with email verification token generation
- Email verification flow
- Password reset flow (token-based, time-limited)
- Password change with old password verification
- User profile updates
- User deletion (soft delete option)

### 4. User Management API Endpoints
- `POST /api/v1/users` - Register new user
- `GET /api/v1/users/:id` - Get user profile (authorized)
- `PUT /api/v1/users/:id` - Update user profile (authorized)
- `DELETE /api/v1/users/:id` - Delete user (admin only)
- `POST /api/v1/users/verify-email` - Verify email with token
- `POST /api/v1/users/reset-password` - Request password reset
- `POST /api/v1/users/change-password` - Change password

### 5. gRPC Server (Microservices)
- Expose gRPC server for identity service
- gRPC service definition in `api/proto/identity.proto`
- gRPC server implementation in `internal/identity/grpc/server.go`
- Service registration in service registry

### 6. Integration
- Integration with email notification system (Epic 5 placeholder)
- Integration with audit logging
- Integration with authentication system
- Identity service is an independent service that can be deployed separately

## Acceptance Criteria
- [ ] Users can register with email and password
- [ ] Passwords are securely hashed
- [ ] Email verification tokens are generated and validated
- [ ] Password reset flow works end-to-end
- [ ] Users can update their profiles
- [ ] User operations require proper authentication
- [ ] All user actions are audited
- [ ] Email uniqueness is enforced

## Related ADRs
- [ADR-0018: Password Hashing](../../adr/0018-password-hashing.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)

## Files to Create/Modify
- `pkg/identity/identity.go` - Identity interfaces
- `internal/identity/user_repo.go` - User repository
- `internal/identity/user_service.go` - User service
- `internal/identity/handler.go` - User handlers
- `internal/di/providers.go` - Add identity providers