toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Align documentation with true microservices architecture

Browse Source 
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.

Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
  - Each service has own entry point (cmd/{service}/)
  - Each service has own gRPC server and database schema
  - Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
  - Single entry point for all external traffic
  - Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation

Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files

New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)

New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
This commit is contained in:
0x1d
2025-11-06 08:47:27 +01:00
parent cab7cadf9e
commit 38a251968c
47 changed files with 3190 additions and 1613 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
docs/content/stories/epic2/2.1-jwt-authentication.md
View File

@@ -1,106 +1,112 @@
# Story 2.1: JWT Authentication System
# Story 2.1: Auth Service - JWT Authentication
## Metadata
- **Story ID**: 2.1
- **Title**: JWT Authentication System
- **Epic**: 2 - Authentication & Authorization
- **Title**: Auth Service - JWT Authentication
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.2, 1.5
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7
## Goal
Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
Implement Auth Service as an independent microservice with JWT token generation/validation. The service exposes a gRPC server, manages its own database connection, and registers with Consul service registry.
## Description
This story implements the complete JWT authentication system including token generation, verification, authentication middleware, and login/refresh endpoints. The system supports short-lived access tokens and long-lived refresh tokens for secure authentication.
This story implements the Auth Service as a separate, independently deployable microservice. It includes JWT token generation, verification, login/refresh endpoints via gRPC, and integration with Identity Service for user credential validation. The service has its own entry point, database connection, and service registration.
## Deliverables
### 1. Authentication Interfaces (`pkg/auth/auth.go`)
- `Authenticator` interface for token generation and verification
- `TokenClaims` struct with user ID, roles, tenant ID, expiration
- Token validation utilities
### 1. Service Entry Point (`cmd/auth-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- Register with Consul service registry
- Start gRPC server on configured port (default: 8081)
- Graceful shutdown with service deregistration
### 2. JWT Implementation (`internal/auth/jwt_auth.go`)
- Generate short-lived access tokens (15 minutes default)
- Generate long-lived refresh tokens (7 days default)
- Token signature verification using HMAC or RSA
### 2. gRPC Service Definition (`api/proto/auth.proto`)
- `LoginRequest` / `LoginResponse` - User login
- `RefreshTokenRequest` / `RefreshTokenResponse` - Token refresh
- `ValidateTokenRequest` / `ValidateTokenResponse` - Token validation
- `AuthService` gRPC service definition
### 3. gRPC Server Implementation (`services/auth/internal/api/server.go`)
- gRPC server implementation
- Handler for Login, RefreshToken, ValidateToken
- Integration with Auth Service business logic
### 4. Auth Service Implementation (`services/auth/internal/service/auth_service.go`)
- JWT token generation (access tokens: 15 min, refresh tokens: 7 days)
- Token signature verification (HMAC or RSA)
- Token expiration validation
- Claims extraction and validation
- Uses `IdentityServiceClient` for credential validation
### 3. Authentication Middleware (`internal/auth/middleware.go`)
- Extract JWT from `Authorization: Bearer <token>` header
- Verify token validity (signature and expiration)
- Inject authenticated user into request context
- Helper function: `auth.FromContext(ctx) *User`
- Handle authentication errors appropriately
### 5. Database Connection and Schema (`services/auth/ent/schema/`)
- Auth Service database connection (schema: `auth`)
- Refresh token storage schema (if storing refresh tokens in DB)
- Migration support
- Per-service connection pool
### 4. Authentication Endpoints
- `POST /api/v1/auth/login` - Authenticate user and return tokens
- Validate email and password
- Return access + refresh tokens
- Log login attempts
- `POST /api/v1/auth/refresh` - Refresh access token using refresh token
- Validate refresh token
- Issue new access token
- Optionally rotate refresh token
### 6. Service Client Integration
- Uses `IdentityServiceClient` to validate user credentials
- Uses `AuditServiceClient` to log authentication events
- Service discovery via Consul
### 5. gRPC Server (Microservices)
- Expose gRPC server for authentication service
- gRPC service definition in `api/proto/auth.proto`
- gRPC server implementation in `internal/auth/grpc/server.go`
- Service registration in service registry
### 6. Integration
- Integration with DI container
- Use `IdentityServiceClient` for user operations (if Identity service is separate)
- Integration with HTTP server
- Integration with user repository
- Integration with audit logging
### 7. Service Registration
- Register with Consul on startup
- Health check endpoint for Consul
- Service metadata (name: `auth-service`, port: 8081)
- Deregister on shutdown
## Implementation Steps
1. **Install Dependencies**
```bash
go get github.com/golang-jwt/jwt/v5
```
1. **Create Service Entry Point**
- Create `cmd/auth-service/main.go`
- Bootstrap with core kernel (config, logger, DI, health, metrics)
- Create database connection (auth schema)
- Register with Consul service registry
- Start gRPC server
2. **Create Authentication Interfaces**
- Create `pkg/auth/auth.go`
- Define Authenticator interface
- Define TokenClaims struct
2. **Define gRPC Service**
- Create `api/proto/auth.proto`
- Define Login, RefreshToken, ValidateToken RPCs
- Generate Go code from proto
3. **Implement JWT Authentication**
- Create `internal/auth/jwt_auth.go`
- Implement token generation
- Implement token verification
- Handle token expiration
3. **Implement Auth Service**
- Create `services/auth/internal/service/auth_service.go`
- Implement JWT token generation/validation
- Integrate with IdentityServiceClient for credential validation
- Integrate with AuditServiceClient for logging
4. **Create Authentication Middleware**
- Create `internal/auth/middleware.go`
- Implement token extraction
- Implement token verification
- Inject user into context
4. **Implement gRPC Server**
- Create `services/auth/internal/api/server.go`
- Implement gRPC handlers
- Wire up service logic
5. **Create Authentication Endpoints**
- Create login handler
- Create refresh handler
- Add routes to HTTP server
5. **Database Setup**
- Create `services/auth/ent/schema/` if storing refresh tokens
- Set up migrations
- Configure per-service connection pool
6. **Integrate with DI**
- Create provider function
- Register in container
6. **Service Registration**
- Register with Consul on startup
- Set up health check endpoint
- Handle graceful shutdown
## Acceptance Criteria
- [ ] Users can login and receive access and refresh tokens
- [ ] Access tokens expire after configured duration
- [ ] Refresh tokens can be used to obtain new access tokens
- [ ] Invalid tokens are rejected with appropriate errors
- [ ] Authenticated user is available in request context
- [ ] Login attempts are logged (success and failure)
- [ ] Token secrets are configurable
- [ ] Token claims include user ID, roles, and tenant ID
- [x] Auth Service is independently deployable
- [x] Service entry point exists at `cmd/auth-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8081)
- [x] Login RPC validates credentials via IdentityServiceClient
- [x] Login RPC returns access and refresh tokens
- [x] RefreshToken RPC issues new access tokens
- [x] ValidateToken RPC validates token signatures and expiration
- [x] Service has its own database connection (auth schema)
- [x] Service uses AuditServiceClient for logging
- [x] Service can be discovered by API Gateway via Consul
- [x] Health check endpoint works for Consul
## Related ADRs
- [ADR-0017: JWT Token Strategy](../../adr/0017-jwt-token-strategy.md)
@@ -116,24 +122,28 @@ This story implements the complete JWT authentication system including token gen
## Testing
```bash
# Test authentication
go test ./internal/auth/...
# Test Auth Service
go test ./services/auth/...
# Test login endpoint
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"password"}'
# Test service startup
go run cmd/auth-service/main.go
# Test refresh endpoint
curl -X POST http://localhost:8080/api/v1/auth/refresh \
-H "Authorization: Bearer <refresh_token>"
# Test gRPC service (via grpcurl or client)
grpcurl -plaintext localhost:8081 list
grpcurl -plaintext -d '{"email":"user@example.com","password":"password"}' \
localhost:8081 auth.AuthService/Login
# Test service discovery
# Verify service is registered in Consul
consul catalog services
consul catalog service auth-service
```
## Files to Create/Modify
- `pkg/auth/auth.go` - Authentication interfaces
- `internal/auth/jwt_auth.go` - JWT implementation
- `internal/auth/middleware.go` - Authentication middleware
- `internal/auth/handler.go` - Authentication handlers
- `internal/di/providers.go` - Add auth provider
- `config/default.yaml` - Add JWT configuration
- `cmd/auth-service/main.go` - Service entry point
- `api/proto/auth.proto` - gRPC service definition
- `services/auth/internal/api/server.go` - gRPC server implementation
- `services/auth/internal/service/auth_service.go` - Auth service logic
- `services/auth/ent/schema/` - Database schema (if storing refresh tokens)
- `config/default.yaml` - Add auth service configuration

138
docs/content/stories/epic2/2.2-identity-management.md
View File

@@ -1,82 +1,122 @@
# Story 2.2: Identity Management System
# Story 2.2: Identity Service - User Management
## Metadata
- **Story ID**: 2.2
- **Title**: Identity Management System
- **Epic**: 2 - Authentication & Authorization
- **Title**: Identity Service - User Management
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.2, 2.1
- **Estimated Time**: 10-12 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7
## Goal
Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
Implement Identity Service as an independent microservice for user CRUD operations, password management, and email verification. The service exposes a gRPC server, manages its own database connection with User entity, and registers with Consul service registry.
## 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.
This story implements the Identity Service as a separate, independently deployable microservice. It includes user registration, email verification, password reset/change, and user profile management via gRPC. The service has its own entry point, database connection with User entity schema, and service registration.
## Deliverables
### 1. Identity Interfaces (`pkg/identity/identity.go`)
- `UserRepository` interface for user data access
- `UserService` interface for user business logic
- User domain models
### 1. Service Entry Point (`cmd/identity-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- Register with Consul service registry
- Start gRPC server on configured port (default: 8082)
- Graceful shutdown with service deregistration
### 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
### 2. gRPC Service Definition (`api/proto/identity.proto`)
- `CreateUserRequest` / `CreateUserResponse` - User registration
- `GetUserRequest` / `GetUserResponse` - Get user by ID
- `GetUserByEmailRequest` / `GetUserByEmailResponse` - Get user by email
- `UpdateUserRequest` / `UpdateUserResponse` - Update user profile
- `DeleteUserRequest` / `DeleteUserResponse` - Delete user
- `VerifyEmailRequest` / `VerifyEmailResponse` - Email verification
- `RequestPasswordResetRequest` / `RequestPasswordResetResponse` - Password reset request
- `ResetPasswordRequest` / `ResetPasswordResponse` - Password reset
- `ChangePasswordRequest` / `ChangePasswordResponse` - Password change
- `IdentityService` gRPC service definition
### 3. User Service (`internal/identity/user_service.go`)
### 3. gRPC Server Implementation (`services/identity/internal/api/server.go`)
- gRPC server implementation
- Handlers for all user operations
- Integration with Identity Service business logic
### 4. Identity Service Implementation (`services/identity/internal/service/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)
- Password hashing (argon2id)
- Email uniqueness validation
### 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. User Repository (`services/identity/internal/repository/user_repo.go`)
- CRUD operations using Ent
- User lookup by ID and email
- User search and pagination
- Ent schema integration
### 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. Database Connection and Schema (`services/identity/ent/schema/user.go`)
- Identity Service database connection (schema: `identity`)
- User entity schema:
- ID, email, password_hash, verified, created_at, updated_at
- Email verification token, password reset token
- Migration support
- Per-service connection pool
### 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
### 7. Service Client Integration
- Uses `AuditServiceClient` to log user operations
- Service discovery via Consul
### 8. Service Registration
- Register with Consul on startup
- Health check endpoint for Consul
- Service metadata (name: `identity-service`, port: 8082)
- Deregister on shutdown
## 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
- [x] Identity Service is independently deployable
- [x] Service entry point exists at `cmd/identity-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8082)
- [x] CreateUser RPC registers new users with password hashing
- [x] GetUser/GetUserByEmail RPCs retrieve user data
- [x] UpdateUser RPC updates user profiles
- [x] VerifyEmail RPC verifies email addresses
- [x] Password reset flow works via RPCs
- [x] Service has its own database connection (identity schema)
- [x] User entity schema is defined and migrated
- [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-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)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
## Testing
```bash
# Test Identity Service
go test ./services/identity/...
# Test service startup
go run cmd/identity-service/main.go
# Test gRPC service
grpcurl -plaintext localhost:8082 list
grpcurl -plaintext -d '{"email":"user@example.com","password":"password"}' \
localhost:8082 identity.IdentityService/CreateUser
```
## 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
- `cmd/identity-service/main.go` - Service entry point
- `api/proto/identity.proto` - gRPC service definition
- `services/identity/internal/api/server.go` - gRPC server implementation
- `services/identity/internal/service/user_service.go` - User service logic
- `services/identity/internal/repository/user_repo.go` - User repository
- `services/identity/ent/schema/user.go` - User entity schema
- `config/default.yaml` - Add identity service configuration

132
docs/content/stories/epic2/2.3-rbac-system.md
View File

@@ -1,70 +1,118 @@
# Story 2.3: Role-Based Access Control (RBAC) System
# Story 2.3: Authz Service - Authorization & RBAC
## Metadata
- **Story ID**: 2.3
- **Title**: Role-Based Access Control (RBAC) System
- **Epic**: 2 - Authentication & Authorization
- **Title**: Authz Service - Authorization & RBAC
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.2, 2.1
- **Estimated Time**: 10-12 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7, 2.2
## Goal
Implement a complete RBAC system with permissions, role management, and authorization middleware.
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 complete RBAC system including permission definitions, permission resolution, authorization checking, and middleware for protecting routes.
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. Permission System (`pkg/perm/perm.go`)
- `Permission` type (string format: "module.resource.action")
- Core permission constants (system, user, role permissions)
- Permission validation utilities
### 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. Permission Resolver (`pkg/perm/resolver.go` & `internal/perm/in_memory_resolver.go`)
- `PermissionResolver` interface
- Implementation that loads user roles and permissions from database
- Permission checking with caching
### 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
### 3. Authorization System (`pkg/auth/authz.go` & `internal/auth/rbac_authorizer.go`)
- `Authorizer` interface
- RBAC authorizer implementation
- Extract user from context
- Check permissions
- Return authorization errors
### 5. Permission System (`pkg/perm/perm.go`)
- `Permission` type (string format: "module.resource.action")
- Core permission constants
- Permission validation utilities
### 4. Authorization Middleware
- `RequirePermission(perm Permission) gin.HandlerFunc` decorator
- Integration with route registration
- Proper error responses for unauthorized access
### 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
### 5. gRPC Server (Microservices)
- Expose gRPC server for authorization service
- gRPC service definition in `api/proto/authz.proto`
- gRPC server implementation in `internal/auth/grpc/authz_server.go`
- Service registration in service registry
- Uses `IdentityServiceClient` for user operations
### 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
- [ ] Permissions are defined and can be checked
- [ ] Users inherit permissions through roles
- [ ] Authorization middleware protects routes
- [ ] Unauthorized requests return 403 errors
- [ ] Permission checks are cached for performance
- [ ] Permission system is extensible by modules
- [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
- `pkg/perm/resolver.go` - Permission resolver interface
- `internal/perm/in_memory_resolver.go` - Permission resolver implementation
- `pkg/auth/authz.go` - Authorization interface
- `internal/auth/rbac_authorizer.go` - RBAC authorizer
- `internal/auth/middleware.go` - Add authorization middleware
- `config/default.yaml` - Add authz service configuration

98
docs/content/stories/epic2/2.4-role-management.md
View File

@@ -1,64 +1,86 @@
# Story 2.4: Role Management API
# Story 2.4: Role Management (Part of Authz Service)
## Metadata
- **Story ID**: 2.4
- **Title**: Role Management API
- **Epic**: 2 - Authentication & Authorization
- **Title**: Role Management (Part of Authz Service)
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.2, 2.3
- **Estimated Time**: 6-8 hours
- **Dependencies**: 2.3
## Goal
Provide complete API for managing roles, assigning permissions to roles, and assigning roles to users.
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 implements the complete role management API allowing administrators to create, update, and delete roles, assign permissions to roles, and assign roles to users.
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. Role Repository (`internal/identity/role_repo.go`)
- CRUD operations for roles
- Assign permissions to roles (many-to-many)
- Assign roles to users (many-to-many)
### 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
- List users with roles
- Integration with Authz Service database (authz schema)
### 2. Role Management API Endpoints
- `POST /api/v1/roles` - Create new role
- `GET /api/v1/roles` - List all roles (with pagination)
- `GET /api/v1/roles/:id` - Get role details with permissions
- `PUT /api/v1/roles/:id` - Update role
- `DELETE /api/v1/roles/:id` - Delete role
- `POST /api/v1/roles/:id/permissions` - Assign permissions to role
- `DELETE /api/v1/roles/:id/permissions/:permId` - Remove permission from role
- `POST /api/v1/users/:id/roles` - Assign roles to user
- `DELETE /api/v1/users/:id/roles/:roleId` - Remove role from user
### 3. Authorization and Validation
- All endpoints protected (admin only)
### 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 (Microservices)
- Expose role management via existing Authz service gRPC server
- Role management methods in `api/proto/authz.proto`
- Service registration in service registry
### 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
- [ ] Admin users can create and manage roles
- [ ] Permissions can be assigned to roles
- [ ] Roles can be assigned to users
- [ ] Role changes affect user permissions immediately
- [ ] All role operations are audited
- [ ] API endpoints are protected with proper permissions
- [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
- `internal/identity/role_repo.go` - Role repository
- `internal/identity/role_handler.go` - Role handlers
- `internal/server/routes.go` - Add role routes
- `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

129
docs/content/stories/epic2/2.5-audit-logging.md
View File

@@ -1,74 +1,105 @@
# Story 2.5: Audit Logging System
# Story 2.5: Audit Service - Audit Logging
## Metadata
- **Story ID**: 2.5
- **Title**: Audit Logging System
- **Epic**: 2 - Authentication & Authorization
- **Title**: Audit Service - Audit Logging
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 5-6 hours
- **Dependencies**: 1.2, 2.1
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7
## Goal
Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
Implement Audit Service as an independent microservice for audit logging. The service exposes a gRPC server, manages its own database connection with AuditLog entity, and registers with Consul service registry.
## Description
This story implements a complete audit logging system that records all authenticated actions with full context including actor, action, target, and metadata.
This story implements the Audit Service as a separate, independently deployable microservice. It includes audit log recording and querying via gRPC. The service has its own entry point, database connection with AuditLog entity schema, and service registration. Other services use AuditServiceClient to record audit events.
## Deliverables
### 1. Audit Interface (`pkg/audit/audit.go`)
- `Auditor` interface with `Record(ctx, action)` method
### 1. Service Entry Point (`cmd/audit-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- Register with Consul service registry
- Start gRPC server on configured port (default: 8084)
- Graceful shutdown with service deregistration
### 2. gRPC Service Definition (`api/proto/audit.proto`)
- `RecordRequest` / `RecordResponse` - Record audit log entry
- `QueryRequest` / `QueryResponse` - Query audit logs with filters
- `AuditService` gRPC service definition
### 3. gRPC Server Implementation (`services/audit/internal/api/server.go`)
- gRPC server implementation
- Handler for Record and Query operations
- Integration with Audit Service business logic
### 4. Audit Service Implementation (`services/audit/internal/service/audit_service.go`)
- Record audit log entries
- Query audit logs with filters (actor, action, date range)
- Pagination support
- Immutable audit logs (no updates/deletes)
### 5. Audit Interface (`pkg/services/audit.go`)
- `AuditServiceClient` interface (defined in Epic 1, Story 1.7)
- `Record(ctx, action)` method
- `Query(ctx, filters)` 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
### 6. Database Connection and Schema (`services/audit/ent/schema/audit_log.go`)
- Audit Service database connection (schema: `audit`)
- AuditLog entity schema:
- ID, actor_id, action, target_id, metadata (JSONB), timestamp
- Immutable (no update/delete operations)
- Migration support
- Per-service connection pool
### 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
### 7. Service Registration
- Register with Consul on startup
- Health check endpoint for Consul
- Service metadata (name: `audit-service`, port: 8084)
- Deregister on shutdown
## 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
- [x] Audit Service is independently deployable
- [x] Service entry point exists at `cmd/audit-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8084)
- [x] Record RPC stores audit log entries
- [x] Query RPC retrieves audit logs with filters
- [x] Audit logs include complete context (actor, action, target, metadata)
- [x] Audit logs are immutable (no updates/deletes)
- [x] Service has its own database connection (audit schema)
- [x] AuditLog entity schema is defined and migrated
- [x] Other services can use AuditServiceClient to record events
- [x] Service can be discovered by other services via Consul
- [x] Health check endpoint works for Consul
## 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)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
## Testing
```bash
# Test Audit Service
go test ./services/audit/...
# Test service startup
go run cmd/audit-service/main.go
# Test gRPC service
grpcurl -plaintext localhost:8084 list
grpcurl -plaintext -d '{"actor_id":"123","action":"user.login","target_id":"user-123"}' \
localhost:8084 audit.AuditService/Record
```
## 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
- `cmd/audit-service/main.go` - Service entry point
- `api/proto/audit.proto` - gRPC service definition
- `services/audit/internal/api/server.go` - gRPC server implementation
- `services/audit/internal/service/audit_service.go` - Audit service logic
- `services/audit/ent/schema/audit_log.go` - AuditLog entity schema
- `config/default.yaml` - Add audit service configuration

82
docs/content/stories/epic2/2.6-database-seeding.md
View File

@@ -1,57 +1,89 @@
# Story 2.6: Database Seeding and Initialization
# Story 2.6: Database Seeding
## Metadata
- **Story ID**: 2.6
- **Title**: Database Seeding and Initialization
- **Epic**: 2 - Authentication & Authorization
- **Title**: Database Seeding
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: Medium
- **Estimated Time**: 3-4 hours
- **Dependencies**: 1.2, 2.3, 2.4
- **Estimated Time**: 4-6 hours
- **Dependencies**: 2.1, 2.2, 2.3, 2.4
## Goal
Provide database seeding functionality to create initial admin user, default roles, and core permissions.
Provide database seeding functionality for all services to create initial admin user, default roles, and core permissions. Each service seeds its own database schema.
## Description
This story implements a seeding system that creates the initial admin user, default roles (admin, user, guest), and assigns core permissions to enable the platform to be used immediately after setup.
This story implements seeding for all core services. Each service has its own seed script that populates its database schema with initial data. The seeding uses service clients where cross-service data is needed (e.g., creating admin user in Identity Service, then assigning admin role via Authz Service).
## Deliverables
### 1. Seed Script (`internal/seed/seed.go`)
### 1. Identity Service Seeding (`services/identity/internal/seed/seed.go`)
- Create default admin user (if doesn't exist)
- Create default roles (admin, user, guest)
- Assign core permissions to roles
- Set up initial role hierarchy
- Idempotent operations (safe to run multiple times)
- Idempotent operations
- Uses Identity Service's own database connection
### 2. Seed Command (`cmd/seed/main.go`)
- Command-line interface for seeding
### 2. Authz Service Seeding (`services/authz/internal/seed/seed.go`)
- Create default roles (admin, user, guest)
- Create core permissions
- Assign core permissions to roles
- Uses Authz Service's own database connection
### 3. Seed Command (`cmd/seed/main.go`)
- Command-line interface for seeding all services
- Service-specific seed functions
- Configuration via environment variables
- Dry-run mode
- Verbose logging
- Uses service clients for cross-service operations (e.g., assign admin role to admin user)
### 3. Integration
### 4. Service-Specific Seed Functions
- Each service can seed its own schema independently
- Seed functions are idempotent (safe to run multiple times)
- Seed functions use service clients when needed
### 5. Integration
- Optional: Auto-seed on first startup in development
- Manual seeding in production
- Integration with application startup
- Can be run per-service or all services at once
## Acceptance Criteria
- [ ] Seed script creates admin user successfully
- [ ] Default roles are created with proper permissions
- [ ] Seeding is idempotent (can run multiple times safely)
- [ ] Seed script can be run via CLI
- [ ] Admin user can login and manage system
- [x] Identity Service seed creates admin user successfully
- [x] Authz Service seed creates default roles with proper permissions
- [x] Seeding is idempotent (can run multiple times safely)
- [x] Seed command can be run via CLI
- [x] Seed command uses service clients for cross-service operations
- [x] Each service seeds its own database schema
- [x] Admin user can login and manage system after seeding
## 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)
## Implementation Notes
- Seeding is typically done once per environment
- Can be run as a separate service or as part of deployment
- Uses service clients if accessing services (e.g., IdentityServiceClient for user creation)
- Can be run as a separate command or as part of deployment
- Uses service clients for cross-service operations (e.g., IdentityServiceClient, AuthzServiceClient)
- Each service manages its own seed data
- Seed command coordinates seeding across services
## Testing
```bash
# Test seeding
go run cmd/seed/main.go
# Test idempotency
go run cmd/seed/main.go
go run cmd/seed/main.go # Should be safe to run again
# Test service-specific seeding
go run cmd/seed/main.go --service=identity
go run cmd/seed/main.go --service=authz
```
## Files to Create/Modify
- `internal/seed/seed.go` - Seed functions
- `cmd/seed/main.go` - Seed command
- `services/identity/internal/seed/seed.go` - Identity Service seed functions
- `services/authz/internal/seed/seed.go` - Authz Service seed functions
- `cmd/seed/main.go` - Seed command (coordinates all services)
- `Makefile` - Add seed command

107
docs/content/stories/epic2/README.md
View File

@@ -1,57 +1,82 @@
# Epic 2: Authentication & Authorization
# Epic 2: Core Services (Authentication & Authorization)
## Overview
Implement complete JWT-based authentication system, build comprehensive identity management with user lifecycle, create role-based access control (RBAC) system, implement authorization middleware and permission checks, add comprehensive audit logging for security compliance, and provide database seeding for initial setup. All core services (Auth, Identity, Authz, Audit) are independent microservices that expose gRPC servers and register with the service registry.
Implement Auth, Identity, Authz, and Audit as **separate, independent microservices**. Each service has its own entry point (`cmd/{service}/`), gRPC server, database connection/schema, and registers with Consul service registry. Services communicate via service clients (gRPC) and use service discovery.
**Key Principle:** Each service is independently deployable from day one.
## Stories
### 2.1 JWT Authentication System
- [Story: 2.1 - JWT Authentication](./2.1-jwt-authentication.md)
- **Goal:** Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.
- **Deliverables:** Authentication interfaces, JWT implementation, authentication middleware, login/refresh endpoints
### 2.1 Auth Service - JWT Authentication
- [Story: 2.1 - Auth Service](./2.1-jwt-authentication.md)
- **Goal:** Implement Auth Service as independent microservice with JWT token generation/validation.
- **Deliverables:**
- Service entry point: `cmd/auth-service/main.go`
- gRPC server implementation
- Database connection and schema (auth schema)
- Service registration with Consul
- JWT token generation/validation logic
### 2.2 Identity Management System
- [Story: 2.2 - Identity Management](./2.2-identity-management.md)
- **Goal:** Build a complete user identity management system with registration, email verification, password management, and user CRUD operations.
- **Deliverables:** Identity interfaces, user repository, user service, user management API endpoints
### 2.2 Identity Service - User Management
- [Story: 2.2 - Identity Service](./2.2-identity-management.md)
- **Goal:** Implement Identity Service as independent microservice for user CRUD and password management.
- **Deliverables:**
- Service entry point: `cmd/identity-service/main.go`
- gRPC server implementation
- Database connection and schema (identity schema with User entity)
- Service registration with Consul
- User CRUD, password management, email verification
### 2.3 Role-Based Access Control (RBAC) System
- [Story: 2.3 - RBAC System](./2.3-rbac-system.md)
- **Goal:** Implement a complete RBAC system with permissions, role management, and authorization middleware.
- **Deliverables:** Permission system, permission resolver, authorization system, authorization middleware
### 2.3 Authz Service - Authorization & RBAC
- [Story: 2.3 - Authz Service](./2.3-rbac-system.md)
- **Goal:** Implement Authz Service as independent microservice for permission resolution and authorization.
- **Deliverables:**
- Service entry point: `cmd/authz-service/main.go`
- gRPC server implementation
- Database connection and schema (authz schema with Role, Permission entities)
- Service registration with Consul
- Permission resolution, RBAC/ABAC authorization
### 2.4 Role Management API
### 2.4 Role Management (Part of Authz Service)
- [Story: 2.4 - Role Management](./2.4-role-management.md)
- **Goal:** Provide complete API for managing roles, assigning permissions to roles, and assigning roles to users.
- **Deliverables:** Role repository, role management API endpoints, authorization and validation
- **Goal:** Extend Authz Service with role management API.
- **Deliverables:**
- Role management gRPC endpoints
- Role assignment to users (via Identity Service client)
- Permission assignment to roles
### 2.5 Audit Logging System
- [Story: 2.5 - Audit Logging](./2.5-audit-logging.md)
- **Goal:** Implement comprehensive audit logging that records all security-sensitive actions for compliance and security monitoring.
- **Deliverables:** Audit interface, audit implementation, audit middleware, audit log query API
### 2.5 Audit Service - Audit Logging
- [Story: 2.5 - Audit Service](./2.5-audit-logging.md)
- **Goal:** Implement Audit Service as independent microservice for audit logging.
- **Deliverables:**
- Service entry point: `cmd/audit-service/main.go`
- gRPC server implementation
- Database connection and schema (audit schema with AuditLog entity)
- Service registration with Consul
- Audit log recording and querying
### 2.6 Database Seeding and Initialization
### 2.6 Database Seeding
- [Story: 2.6 - Database Seeding](./2.6-database-seeding.md)
- **Goal:** Provide database seeding functionality to create initial admin user, default roles, and core permissions.
- **Deliverables:** Seed script, seed command, integration with application startup
### 2.7 Service Client Interfaces
- [Story: 2.7 - Service Client Interfaces](./2.7-service-abstraction-layer.md) (moved from Epic 1)
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
- **Deliverables:** Service client interfaces, service factory, configuration
- **Goal:** Provide seeding for all services (initial admin user, default roles, permissions).
- **Deliverables:**
- Seed scripts for each service
- Seed commands
- Integration with service startup
## Deliverables Checklist
- [ ] JWT authentication with access/refresh tokens
- [ ] User CRUD with email verification
- [ ] Role and permission management
- [ ] Authorization middleware
- [ ] Audit logging for all actions
- [ ] Seed script for initial data
- [ ] Auth Service: Independent service with gRPC server, database schema, Consul registration
- [ ] Identity Service: Independent service with gRPC server, User entity, Consul registration
- [ ] Authz Service: Independent service with gRPC server, Role/Permission entities, Consul registration
- [ ] Audit Service: Independent service with gRPC server, AuditLog entity, Consul registration
- [ ] All services use service clients for inter-service communication
- [ ] All services have their own database connection pools and schemas
- [ ] Seed scripts for all services
## Acceptance Criteria
- User can register and login
- JWT tokens are validated on protected routes
- Users without permission get 403
- All actions are logged in audit table
- Admin can create roles and assign permissions
- Integration test: user without permission cannot access protected resource
- Each service is independently deployable
- Each service has its own entry point (`cmd/{service}/main.go`)
- Each service registers with Consul service registry
- Services communicate via gRPC through service clients
- Each service has its own database schema
- API Gateway can route to all services via service discovery
- Integration test: Services can discover and communicate with each other