# Story 2.4: Role Management (Part of Authz Service)

## Metadata
- **Story ID**: 2.4
- **Title**: Role Management (Part of Authz Service)
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 2.3

## Goal
Extend Authz Service with role management gRPC endpoints for creating, updating, and deleting roles, assigning permissions to roles, and assigning roles to users.

## Description
This story extends the Authz Service (implemented in Story 2.3) with role management capabilities. It adds gRPC endpoints for role CRUD operations, permission assignment to roles, and role assignment to users. The service uses IdentityServiceClient to manage user-role relationships.

## Deliverables

### 1. gRPC Service Extensions (`api/proto/authz.proto`)
Extend Authz Service proto with role management RPCs:

- `CreateRoleRequest` / `CreateRoleResponse` - Create new role
- `GetRoleRequest` / `GetRoleResponse` - Get role details
- `ListRolesRequest` / `ListRolesResponse` - List all roles (with pagination)
- `UpdateRoleRequest` / `UpdateRoleResponse` - Update role
- `DeleteRoleRequest` / `DeleteRoleResponse` - Delete role
- `AssignPermissionToRoleRequest` / `AssignPermissionToRoleResponse` - Assign permission to role
- `RemovePermissionFromRoleRequest` / `RemovePermissionFromRoleResponse` - Remove permission from role
- `AssignRoleToUserRequest` / `AssignRoleToUserResponse` - Assign role to user (via IdentityServiceClient)
- `RemoveRoleFromUserRequest` / `RemoveRoleFromUserResponse` - Remove role from user (via IdentityServiceClient)

### 2. Role Repository (`services/authz/internal/repository/role_repo.go`)
- CRUD operations for roles using Ent
- Assign permissions to roles (many-to-many via RolePermission entity)
- List roles with permissions
- Integration with Authz Service database (authz schema)

### 3. Role Service (`services/authz/internal/service/role_service.go`)
- Role management business logic
- Permission assignment to roles
- Role assignment to users (via IdentityServiceClient)
- Input validation
- Error handling

### 4. gRPC Server Extensions (`services/authz/internal/api/server.go`)
- Add role management handlers to existing Authz Service gRPC server
- Integration with Role Service
- Authorization checks (admin only for role management)

### 5. Service Client Integration
- Uses `IdentityServiceClient` to manage user-role relationships
- Uses `AuditServiceClient` to log role management operations

## Acceptance Criteria
- [x] CreateRole RPC creates new roles
- [x] GetRole/ListRoles RPCs retrieve role data
- [x] UpdateRole/DeleteRole RPCs modify roles
- [x] AssignPermissionToRole RPC assigns permissions to roles
- [x] AssignRoleToUser RPC assigns roles to users (via IdentityServiceClient)
- [x] Role changes affect user permissions immediately (cache invalidation)
- [x] All role operations are audited via AuditServiceClient
- [x] Role management RPCs are protected with proper permissions
- [x] Service uses IdentityServiceClient for user-role relationships

## Related ADRs
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)

## Testing
```bash
# Test role management
go test ./services/authz/...

# Test gRPC service
grpcurl -plaintext localhost:8083 list
grpcurl -plaintext -d '{"name":"admin","description":"Administrator role"}' \
  localhost:8083 authz.AuthzService/CreateRole
```

## Files to Create/Modify
- `api/proto/authz.proto` - Add role management RPCs
- `services/authz/internal/repository/role_repo.go` - Role repository
- `services/authz/internal/service/role_service.go` - Role service logic
- `services/authz/internal/api/server.go` - Add role management handlers