motovaultpro/docs/security.md

Security Architecture

Authentication & Authorization

Current State (MVP / Dev)

• Backend uses a Fastify authentication plugin that injects a mock user for development/test.
• JWT validation via Auth0 is not yet enabled on the backend; the frontend Auth0 flow works independently.

Intended Production Behavior

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 request rate limiting (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