docs: document Phase 0.5 CORS configuration and production security
Add comprehensive CORS configuration section to CLAUDE.md including: - Implementation patterns with From<CorsSettings> trait - Development and production configuration examples - Security constraints and fail-safe defaults - Test coverage documentation (15 tests) - Updated project structure showing CORS-related files - Updated technology stack and active specification list Updated tasks.md to reflect Phase 0.5 completion (T009-T016). Phase: 0.5 - CORS Configuration & Production Security (Complete)
This commit is contained in:
92
README.md
92
README.md
@@ -12,7 +12,7 @@ STA will provide a modern web interface for controlling Modbus-compatible relay
|
||||
|
||||
## Current Status
|
||||
|
||||
**Phase 1 Complete - Foundation:**
|
||||
### Phase 1 Complete - Foundation
|
||||
- ✅ Monorepo structure (backend + frontend at root)
|
||||
- ✅ Rust web server with Poem 3.1 framework
|
||||
- ✅ Configuration system (YAML + environment variables)
|
||||
@@ -20,21 +20,36 @@ STA will provide a modern web interface for controlling Modbus-compatible relay
|
||||
- ✅ Health check and metadata API endpoints
|
||||
- ✅ OpenAPI documentation with Swagger UI
|
||||
- ✅ Rate limiting middleware
|
||||
- ✅ CORS middleware (configurable for production)
|
||||
- ✅ SQLite schema and repository for relay labels
|
||||
- ✅ Vue 3 + TypeScript frontend scaffolding with Vite
|
||||
- ✅ Type-safe API client generation from OpenAPI specs
|
||||
|
||||
**Phase 0.5 In Progress - CORS Configuration:**
|
||||
- ✅ T009: CorsSettings tests written (TDD)
|
||||
- ✅ T010: CorsSettings struct implemented with fail-safe defaults
|
||||
- 🚧 T011-T016: YAML configuration and middleware integration
|
||||
### Phase 0.5 Complete - CORS Configuration & Production Security
|
||||
- ✅ T009: CorsSettings struct with comprehensive unit tests (5 tests)
|
||||
- ✅ T010: CorsSettings implementation with restrictive fail-safe defaults
|
||||
- ✅ T011: Development YAML configuration with permissive CORS
|
||||
- ✅ T012: Production YAML configuration with restrictive CORS
|
||||
- ✅ T013: From<CorsSettings> for Cors trait unit tests (6 tests)
|
||||
- ✅ T014: From<CorsSettings> for Cors implementation with security validation
|
||||
- ✅ T015: Middleware chain integration using From trait
|
||||
- ✅ T016: Integration tests for CORS headers (9 comprehensive tests)
|
||||
|
||||
**Phase 2 Planned - Domain Layer:**
|
||||
#### Key CORS Features Implemented
|
||||
- Environment-specific CORS configuration (development vs production)
|
||||
- Wildcard origin support for development (`allowed_origins: ["*"]`)
|
||||
- Multiple specific origins for production
|
||||
- Credentials support for Authelia authentication
|
||||
- Security validation (prevents wildcard + credentials)
|
||||
- Configurable preflight cache duration
|
||||
- Hardcoded secure methods and headers
|
||||
- Structured logging for CORS configuration
|
||||
- Comprehensive test coverage (15 tests total)
|
||||
|
||||
### Phase 2 Planned - Domain Layer
|
||||
- 📋 Domain types with Type-Driven Development (RelayId, RelayState, RelayLabel)
|
||||
- 📋 100% test coverage for domain layer
|
||||
|
||||
**Planned - Phases 3-8:**
|
||||
### Planned - Phases 3-8
|
||||
- 📋 Modbus TCP client with tokio-modbus (Phase 3)
|
||||
- 📋 Mock controller for testing (Phase 3)
|
||||
- 📋 Health monitoring service (Phase 3)
|
||||
@@ -52,7 +67,8 @@ See [tasks.md](specs/001-modbus-relay-control/tasks.md) for detailed implementat
|
||||
- **Backend**: Rust 2024 with Poem web framework
|
||||
- **Configuration**: YAML-based with environment variable overrides
|
||||
- **API**: RESTful HTTP with OpenAPI documentation
|
||||
- **CORS**: Configurable middleware for production security
|
||||
- **CORS**: Production-ready configurable middleware with security validation
|
||||
- **Middleware Chain**: Rate Limiting → CORS → Data injection
|
||||
|
||||
**Planned:**
|
||||
- **Modbus Integration**: tokio-modbus for Modbus TCP communication
|
||||
@@ -90,7 +106,7 @@ bacon test # test watcher
|
||||
|
||||
### Configuration
|
||||
|
||||
Edit `settings/base.yaml` for Modbus device settings:
|
||||
Edit `backend/settings/base.yaml` for Modbus device settings:
|
||||
|
||||
```yaml
|
||||
modbus:
|
||||
@@ -110,35 +126,50 @@ APP__MODBUS__HOST=192.168.1.100 cargo run
|
||||
|
||||
#### CORS Configuration
|
||||
|
||||
For development with frontend on `localhost:5173`:
|
||||
**Development Mode** (frontend on `localhost:5173`):
|
||||
|
||||
```yaml
|
||||
# backend/settings/development.yaml
|
||||
cors:
|
||||
allowed_origins:
|
||||
- "*"
|
||||
allow_credentials: false
|
||||
- "*" # Permissive for local development
|
||||
allow_credentials: false # MUST be false with wildcard
|
||||
max_age_secs: 3600
|
||||
```
|
||||
|
||||
For production with frontend on Cloudflare Pages:
|
||||
**Production Mode** (frontend on Cloudflare Pages):
|
||||
|
||||
```yaml
|
||||
# backend/settings/production.yaml
|
||||
cors:
|
||||
allowed_origins:
|
||||
- "https://sta.example.com"
|
||||
- "https://sta.yourdomain.com" # Specific origin only
|
||||
allow_credentials: true # Required for Authelia authentication
|
||||
max_age_secs: 3600
|
||||
```
|
||||
|
||||
**Security Notes:**
|
||||
- Wildcard `"*"` origin is **only allowed with `allow_credentials: false`**
|
||||
- Production **must** use specific origins (e.g., `https://sta.example.com`)
|
||||
- Multiple origins are supported as a list
|
||||
- Credentials must be enabled for Authelia authentication to work
|
||||
|
||||
**Hardcoded Security Defaults:**
|
||||
- **Methods**: GET, POST, PUT, PATCH, DELETE, OPTIONS (all required methods)
|
||||
- **Headers**: content-type, authorization (minimum for API + auth)
|
||||
|
||||
**Fail-Safe Defaults:**
|
||||
- `allowed_origins: []` (restrictive - no origins allowed)
|
||||
- `allow_credentials: false`
|
||||
- `max_age_secs: 3600` (1 hour)
|
||||
|
||||
See [CORS Configuration Guide](docs/cors-configuration.md) for complete documentation.
|
||||
|
||||
## API Documentation
|
||||
|
||||
The server provides OpenAPI documentation via Swagger UI:
|
||||
- Swagger UI: `http://localhost:3100/`
|
||||
- OpenAPI Spec: `http://localhost:3100/openapi.json`
|
||||
- OpenAPI Spec: `http://localhost:3100/specs`
|
||||
|
||||
**Current Endpoints:**
|
||||
- `GET /api/health` - Health check endpoint
|
||||
@@ -161,7 +192,9 @@ sta/ # Repository root
|
||||
│ │ ├── lib.rs - Library entry point
|
||||
│ │ ├── main.rs - Binary entry point
|
||||
│ │ ├── startup.rs - Application builder and server config
|
||||
│ │ ├── settings.rs - Configuration management
|
||||
│ │ ├── settings/ - Configuration module
|
||||
│ │ │ ├── mod.rs - Settings aggregation
|
||||
│ │ │ └── cors.rs - CORS configuration (NEW in Phase 0.5)
|
||||
│ │ ├── telemetry.rs - Logging and tracing setup
|
||||
│ │ ├── domain/ - Business logic (planned Phase 2)
|
||||
│ │ │ └── relay/ - Relay domain types and repository traits
|
||||
@@ -175,7 +208,11 @@ sta/ # Repository root
|
||||
│ │ └── middleware/ - Custom middleware
|
||||
│ │ └── rate_limit.rs
|
||||
│ ├── settings/ - YAML configuration files
|
||||
│ │ ├── base.yaml - Base configuration
|
||||
│ │ ├── development.yaml - Development overrides (NEW in Phase 0.5)
|
||||
│ │ └── production.yaml - Production overrides (NEW in Phase 0.5)
|
||||
│ └── tests/ - Integration tests
|
||||
│ └── cors_test.rs - CORS integration tests (NEW in Phase 0.5)
|
||||
├── src/ # Frontend source (Vue/TypeScript)
|
||||
│ └── api/ - Type-safe API client
|
||||
├── docs/ # Project documentation
|
||||
@@ -187,7 +224,7 @@ sta/ # Repository root
|
||||
│ ├── spec.md - Feature specification
|
||||
│ ├── plan.md - Implementation plan
|
||||
│ ├── tasks.md - Task breakdown (102 tasks)
|
||||
│ └── research-cors.md - CORS configuration research
|
||||
│ └── research-cors.md - CORS configuration research (NEW in Phase 0.5)
|
||||
├── package.json - Frontend dependencies
|
||||
├── vite.config.ts - Vite build configuration
|
||||
└── justfile - Build commands
|
||||
@@ -215,6 +252,25 @@ sta/ # Repository root
|
||||
- Vite build tool
|
||||
- openapi-typescript (type-safe API client generation)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Phase 0.5 CORS Testing:**
|
||||
- **Unit Tests**: 11 tests in `backend/src/settings/cors.rs`
|
||||
- CorsSettings deserialization (5 tests)
|
||||
- From<CorsSettings> for Cors trait (6 tests)
|
||||
- Security validation (wildcard + credentials check)
|
||||
- **Integration Tests**: 9 tests in `backend/tests/cors_test.rs`
|
||||
- Preflight OPTIONS requests
|
||||
- Actual request CORS headers
|
||||
- Max-age configuration
|
||||
- Credentials handling
|
||||
- Allowed methods verification
|
||||
- Wildcard origin behavior
|
||||
- Multiple origins support
|
||||
- Unauthorized origin rejection
|
||||
|
||||
**Test Coverage Achieved**: 15 comprehensive tests covering all CORS scenarios
|
||||
|
||||
## Documentation
|
||||
|
||||
### Configuration Guides
|
||||
|
||||
@@ -64,7 +64,7 @@
|
||||
|
||||
---
|
||||
|
||||
## Phase 0.5: CORS Configuration & Production Security (0.5 days)
|
||||
## Phase 0.5: CORS Configuration & Production Security (0.5 days) DONE
|
||||
|
||||
**Purpose**: Replace permissive `Cors::new()` with configurable production-ready CORS
|
||||
|
||||
|
||||
Reference in New Issue
Block a user