# CORS Configuration

This application implements environment-aware Cross-Origin Resource Sharing (CORS) policies to protect your API endpoints while still supporting Capacitor mobile apps.

## Overview

The CORS configuration is split between:
- **Development**: Permissive (allows all origins for convenience)
- **Production**: Strict (only allows explicitly configured origins + Capacitor app origins)

## Configuration

### Environment Variables

Set the `ALLOWED_ORIGINS` environment variable with a comma-separated list of allowed origins:

```bash
# .env or environment configuration
ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
```

### Default Allowed Origins

The following origins are **always allowed** to support Capacitor mobile apps:

- `capacitor://localhost` (iOS Capacitor apps)
- `ionic://localhost` (Ionic/Capacitor apps)
- `http://localhost` (Android WebView, also matches `http://localhost:*` with any port)

## How It Works

### Development Mode

When `NODE_ENV=development`:
- All origins are allowed (`Access-Control-Allow-Origin: *`)
- Credentials are supported
- Maximum convenience for local development

### Production Mode

When `NODE_ENV=production`:
- Only origins listed in `ALLOWED_ORIGINS` are allowed
- Capacitor app origins are always allowed
- Credentials are supported for authenticated requests
- Unauthorized origins are blocked and logged

### Middleware

The `/server/middleware/cors.ts` middleware:
1. Intercepts all `/api/**` requests
2. Checks the request's `Origin` header
3. Validates against allowed origins
4. Sets appropriate CORS headers if allowed
5. Handles preflight (`OPTIONS`) requests
6. Logs unauthorized attempts in production

## Security Benefits

1. **CSRF Protection**: Prevents Cross-Site Request Forgery attacks by limiting which domains can make requests
2. **Unauthorized Access Prevention**: Only explicitly allowed origins can access your API
3. **Audit Trail**: Unauthorized CORS attempts are logged in production
4. **Environment Isolation**: Different security policies for development vs production

## Mobile App Support

Capacitor apps work seamlessly because:
1. They use special protocol origins (`capacitor://`, `ionic://`)
2. These origins are whitelisted by default
3. Android WebView uses `http://localhost` which is also whitelisted
4. Some Capacitor requests may not include an `Origin` header, which is handled safely

## Testing

### Test CORS in Development

```bash
# Start dev server
npm run dev

# Make a request from any origin - should work
curl -H "Origin: https://any-domain.com" http://localhost:3000/api/version
```

### Test CORS in Production

```bash
# Set allowed origins
export ALLOWED_ORIGINS=https://yourapp.com
export NODE_ENV=production

# Start production server
npm run build
npm run start

# Allowed origin - should work
curl -H "Origin: https://yourapp.com" http://localhost:3000/api/version

# Unauthorized origin - should be blocked
curl -H "Origin: https://evil.com" http://localhost:3000/api/version
```

## Troubleshooting

### "CORS policy: No 'Access-Control-Allow-Origin' header"

**Cause**: Your web app's origin is not in the allowed list.

**Solution**: Add your domain to the `ALLOWED_ORIGINS` environment variable:

```bash
ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
```

### Capacitor App Gets CORS Errors

**Possible causes**:
1. You're testing in a browser instead of a real device/emulator
2. Custom Capacitor server configuration changed the origin

**Solution**: 
1. Test on a real device or emulator
2. Check your Capacitor configuration for custom server settings
3. Add your custom origin to `ALLOWED_ORIGINS` if needed

### How to Allow Additional Origins

1. Edit your environment configuration:
   ```bash
   ALLOWED_ORIGINS=https://domain1.com,https://domain2.com,https://domain3.com
   ```

2. Restart your application

3. Verify the origin is allowed by checking the response headers

## Files

- `/nuxt.config.ts` - CORS configuration for dev server and Vite
- `/server/middleware/cors.ts` - Production CORS validation middleware
- Environment variables - `ALLOWED_ORIGINS` configuration

