# Story 2.5: Audit Logging System

## Metadata
- **Story ID**: 2.5
- **Title**: Audit Logging System
- **Phase**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.2, 2.1

## Goal
Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.

## Description
This story implements a complete audit logging system that records all authenticated actions with full context including actor, action, target, and metadata.

## Deliverables

### 1. Audit Interface (`pkg/audit/audit.go`)
- `Auditor` interface with `Record(ctx, action)` method
- `AuditAction` struct with actor, action, target, metadata

### 2. Audit Implementation (`internal/audit/ent_auditor.go`)
- Write audit logs to `audit_log` table
- Capture actor from request context
- Include request metadata (ID, IP, user agent, timestamp)
- Store action details and target information
- Support JSON metadata for flexible logging

### 3. Audit Middleware
- Intercept all authenticated requests
- Record action (HTTP method + path)
- Extract user and request context
- Store audit log entry

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

### 5. Integration
- Integration with authentication endpoints
- Log login attempts (success and failure)
- Log password changes
- Log role assignments and removals
- Log permission changes
- Log user registration

### 5. Audit Log Query API
- `GET /api/v1/audit-logs` - Query audit logs with filters (admin only)
- Support filtering by actor, action, date range
- Pagination support

## Acceptance Criteria
- [ ] All authenticated actions are logged
- [ ] Audit logs include complete context (actor, action, target, metadata)
- [ ] Audit logs are immutable (no updates/deletes)
- [ ] Audit logs can be queried and filtered
- [ ] Audit logging has minimal performance impact
- [ ] Audit logs are stored securely

## Related ADRs
- [ADR-0020: Audit Logging Storage](../../adr/0020-audit-logging-storage.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/audit/audit.go` - Audit interface
- `internal/audit/ent_auditor.go` - Audit implementation
- `internal/audit/middleware.go` - Audit middleware
- `internal/audit/handler.go` - Audit query handler