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