feat: Add localhost to default ALLOWED_ORIGINS configuration

[Yeraze]

Summary

• Improved default CORS configuration for better out-of-box experience
• ALLOWED_ORIGINS now defaults to localhost URLs when not specified
• Explicit configuration still required for production deployments

Changes

When ALLOWED_ORIGINS is not specified in the environment, it now defaults to:

• http://localhost:8080 (typical frontend port)
• http://localhost:3001 (backend port)

This eliminates common CORS errors during local development and testing while maintaining security by requiring explicit configuration for production deployments with different domains or HTTPS.

Files Modified

• src/server/config/environment.ts: Updated default from empty array to localhost URLs
• .env.example: Updated documentation to reflect new default behavior
• docs/configuration/index.md: Updated configuration table with explicit default values

Test plan

• System tests run (CORS test passed, unrelated failures are pre-existing)
• Build successful
• No breaking changes to existing configurations

Notes

• Test failures in system-tests.sh are unrelated to this change (hardware connectivity issues)
• CORS configuration test passed: "✓ PASS: CORS configured for allowed origin"
• Users with existing ALLOWED_ORIGINS configurations are unaffected

🤖 Generated with Claude Code

[claude]

Claude finished @Yeraze's task —— View job

---

Pull Request Review

Comprehensive review of the CORS configuration improvements.

Todo List:

• Read and analyze environment.ts changes
• Review .env.example documentation updates
• Check configuration documentation changes
• Assess security implications of default localhost origins
• Evaluate code quality and potential bugs
• Check test coverage adequacy
• Provide comprehensive feedback

---

✅ Overall Assessment: APPROVE WITH SUGGESTIONS

This is a well-designed improvement that significantly enhances the developer experience while maintaining security best practices. The changes address a common pain point during local development and testing.

🔍 Code Quality Analysis

✅ Strengths

1. Excellent Default Choice: http://localhost:8080 and http://localhost:3001 are sensible defaults that match the typical frontend and backend ports
2. Backwards Compatibility: Existing configurations with explicit ALLOWED_ORIGINS are completely unaffected
3. Clear Security Boundary: Localhost-only defaults prevent accidental exposure in production
4. Consistent Documentation: All three files are properly updated with the new behavior
5. Proper Implementation: The ternary operator logic in environment.ts:284-286 is clean and readable

✅ Security Analysis - SECURE

• Low Risk: Localhost origins are inherently safe and can't be exploited remotely
• Production Safety: Empty ALLOWED_ORIGINS now defaults to localhost instead of potentially insecure empty array
• No Cross-Origin Exposure: The defaults don't introduce any new attack vectors
• Explicit Control: Production deployments still require explicit configuration

🐛 Potential Issues & Suggestions

⚠️ Minor Issues

1. Port Mismatch Documentation (docs/configuration/index.md:81):

   - | `ALLOWED_ORIGINS` | ... | `http://localhost:8080, http://localhost:3001` |
   + | `ALLOWED_ORIGINS` | ... | `http://localhost:8080,http://localhost:3001` |

   The space after the comma doesn't match the actual implementation (which trims spaces anyway, but consistency is better).

2. Consider IPv6 Localhost: Modern systems increasingly use IPv6. Consider adding http://[::1]:8080 and http://[::1]:3001 to the defaults for better compatibility.

💡 Enhancement Suggestions

1. Runtime Logging: Consider adding a debug log when using default origins:

   const allowedOrigins = {
     value: allowedOriginsRaw
       ? allowedOriginsRaw.split(',').map(o => o.trim()).filter(o => o.length > 0)
       : ['http://localhost:8080', 'http://localhost:3001'],
     wasProvided: allowedOriginsRaw !== undefined
   };
   
   // Add this after the assignment
   if (!allowedOrigins.wasProvided) {
     logger.debug('🌐 Using default ALLOWED_ORIGINS for localhost development');
   }

2. Production Warning: The code could warn when defaults are used in production:

   if (!allowedOrigins.wasProvided && nodeEnv.value === 'production') {
     logger.warn('⚠️  Using default localhost ALLOWED_ORIGINS in production. Set ALLOWED_ORIGINS explicitly.');
   }

🧪 Test Coverage Assessment

• System Tests: ✅ The CORS test passed according to the PR description
• Coverage Gap: Consider adding unit tests for the default behavior in environment.ts
• Integration Tests: The change is well-covered by existing CORS functionality tests

📋 Code Style & Maintenance

• Clean Implementation: The ternary operator is readable and follows existing patterns
• Documentation Consistency: All related files updated appropriately
• Naming Convention: Variables and logic follow established codebase patterns

🚀 Impact Assessment

✅ Positive Impacts

• Eliminates common CORS errors during local development
• Reduces onboarding friction for new developers
• Maintains security for production deployments
• No breaking changes to existing configurations

🔍 Risk Assessment: LOW

• No security vulnerabilities introduced
• No performance impact
• Backwards compatible
• Well-tested change

🎯 Recommendations

1. Merge Ready: This PR is ready to merge as-is
2. Minor Documentation Fix: Consider the spacing consistency fix mentioned above
3. Future Enhancement: IPv6 localhost support could be added in a follow-up PR
4. Optional Logging: Runtime logging could help with debugging but isn't essential

---

Verdict: This is a thoughtful improvement that addresses a real pain point while maintaining security best practices. The implementation is clean, well-documented, and backwards compatible.