# Story 2.3: Authz Service - Authorization & RBAC

## Metadata
- **Story ID**: 2.3
- **Title**: Authz Service - Authorization & RBAC
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 10-12 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7, 2.2

## Goal
Implement Authz Service as an independent microservice for permission resolution and authorization checks. The service exposes a gRPC server, manages its own database connection with Role and Permission entities, and registers with Consul service registry.

## Description
This story implements the Authz Service as a separate, independently deployable microservice. It includes permission resolution, RBAC/ABAC authorization checks, role-permission management, and user-role assignment via gRPC. The service has its own entry point, database connection with Role and Permission entity schemas, and service registration.

## Deliverables

### 1. Service Entry Point (`cmd/authz-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- Register with Consul service registry
- Start gRPC server on configured port (default: 8083)
- Graceful shutdown with service deregistration

### 2. gRPC Service Definition (`api/proto/authz.proto`)
- `AuthorizeRequest` / `AuthorizeResponse` - Check if user has permission
- `HasPermissionRequest` / `HasPermissionResponse` - Boolean permission check
- `GetUserPermissionsRequest` / `GetUserPermissionsResponse` - Get all user permissions
- `GetUserRolesRequest` / `GetUserRolesResponse` - Get user roles
- `AuthzService` gRPC service definition

### 3. gRPC Server Implementation (`services/authz/internal/api/server.go`)
- gRPC server implementation
- Handlers for authorization operations
- Integration with Authz Service business logic

### 4. Authz Service Implementation (`services/authz/internal/service/authz_service.go`)
- Permission resolution from user roles
- RBAC authorization checks
- Permission caching (Redis)
- Uses `IdentityServiceClient` to get user roles
- Permission inheritance via roles

### 5. Permission System (`pkg/perm/perm.go`)
- `Permission` type (string format: "module.resource.action")
- Core permission constants
- Permission validation utilities

### 6. Database Connection and Schema (`services/authz/ent/schema/`)
- Authz Service database connection (schema: `authz`)
- Role entity schema: ID, name, description, created_at
- Permission entity schema: ID, name (format: "module.resource.action")
- RolePermission entity (many-to-many relationship)
- UserRole entity (many-to-many, references Identity Service users)
- Migration support
- Per-service connection pool

### 7. Service Client Integration
- Uses `IdentityServiceClient` to get user roles
- Uses `AuditServiceClient` to log authorization checks
- Service discovery via Consul

### 8. Service Registration
- Register with Consul on startup
- Health check endpoint for Consul
- Service metadata (name: `authz-service`, port: 8083)
- Deregister on shutdown

## Acceptance Criteria
- [x] Authz Service is independently deployable
- [x] Service entry point exists at `cmd/authz-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8083)
- [x] Authorize RPC checks if user has permission
- [x] HasPermission RPC returns boolean permission check
- [x] GetUserPermissions RPC returns all user permissions
- [x] Users inherit permissions through roles
- [x] Permission checks are cached (Redis)
- [x] Service has its own database connection (authz schema)
- [x] Role and Permission entity schemas are defined and migrated
- [x] Service uses IdentityServiceClient to get user roles
- [x] Service uses AuditServiceClient for logging
- [x] Service can be discovered by other services via Consul
- [x] Health check endpoint works for Consul

## Related ADRs
- [ADR-0019: Permission DSL Format](../../adr/0019-permission-dsl-format.md)
- [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 Authz Service
go test ./services/authz/...

# Test service startup
go run cmd/authz-service/main.go

# Test gRPC service
grpcurl -plaintext localhost:8083 list
grpcurl -plaintext -d '{"user_id":"123","permission":"blog.post.create"}' \
  localhost:8083 authz.AuthzService/Authorize
```

## Files to Create/Modify
- `cmd/authz-service/main.go` - Service entry point
- `api/proto/authz.proto` - gRPC service definition
- `services/authz/internal/api/server.go` - gRPC server implementation
- `services/authz/internal/service/authz_service.go` - Authz service logic
- `services/authz/ent/schema/role.go` - Role entity schema
- `services/authz/ent/schema/permission.go` - Permission entity schema
- `services/authz/ent/schema/role_permission.go` - Relationship schema
- `pkg/perm/perm.go` - Permission types
- `config/default.yaml` - Add authz service configuration