Very minimal MVP

docs/security.md

@@ -0,0 +1,77 @@
+# Security Architecture
+
+## Authentication & Authorization
+
+### Protected Endpoints
+All vehicle CRUD operations require JWT authentication via Auth0:
+- `POST /api/vehicles` - Create vehicle
+- `GET /api/vehicles` - Get user vehicles  
+- `GET /api/vehicles/:id` - Get specific vehicle
+- `PUT /api/vehicles/:id` - Update vehicle
+- `DELETE /api/vehicles/:id` - Delete vehicle
+
+### Unauthenticated Endpoints
+
+#### Vehicle Dropdown Data API
+The following endpoints are intentionally unauthenticated to support form population before user login:
+
+```
+GET /api/vehicles/dropdown/makes
+GET /api/vehicles/dropdown/models/:make
+GET /api/vehicles/dropdown/transmissions
+GET /api/vehicles/dropdown/engines
+GET /api/vehicles/dropdown/trims
+```
+
+**Security Considerations:**
+- **Data Exposure**: Only exposes public NHTSA vPIC vehicle specification data
+- **No User Data**: Contains no sensitive user information or business logic
+- **Read-Only**: All endpoints are GET requests with no mutations
+- **Caching**: 7-day Redis caching reduces external API abuse
+- **Error Handling**: Generic error responses prevent system information disclosure
+
+**Known Risks:**
+1. **API Abuse**: No rate limiting allows unlimited calls
+2. **Resource Consumption**: Could exhaust NHTSA API rate limits
+3. **Cache Poisoning**: Limited input validation on make parameter
+4. **Information Disclosure**: Exposes system capabilities to unauthenticated users
+
+**Recommended Mitigations for Production:**
+1. **Rate Limiting**: Implement express-rate-limit (e.g., 100 requests/hour per IP)
+2. **Input Validation**: Sanitize make parameter in controller
+3. **CORS Restrictions**: Limit to application domain
+4. **Monitoring**: Add abuse detection logging
+5. **API Gateway**: Consider moving to API gateway with built-in rate limiting
+
+**Risk Assessment**: ACCEPTABLE for MVP
+- Low risk due to public data exposure only
+- UX benefits outweigh security concerns
+- Mitigations can be added incrementally
+
+## Data Security
+
+### VIN Handling
+- VIN validation using industry-standard check digit algorithm
+- VIN decoding via NHTSA vPIC API
+- Cached VIN decode results (30-day TTL)
+- No VIN storage in logs (masked in logging middleware)
+
+### Database Security
+- User data isolation via userId foreign keys
+- Soft deletes for audit trail
+- No cascading deletes to prevent data loss
+- Encrypted connections to PostgreSQL
+
+## Infrastructure Security
+
+### Docker Security
+- Development containers run as non-root users
+- Network isolation between services
+- Environment variable injection for secrets
+- No hardcoded credentials in images
+
+### API Client Security
+- Separate authenticated/unauthenticated HTTP clients
+- Request/response interceptors for error handling
+- Timeout configurations to prevent hanging requests
+- Auth token handling via Auth0 wrapper