# CORS Configuration Guide

This document explains how to configure Cross-Origin Resource Sharing (CORS) for the Talk2Me application.

## Overview

CORS is configured using Flask-CORS to enable secure cross-origin usage of the API endpoints. This allows the Talk2Me application to be embedded in other websites or accessed from different domains while maintaining security.

## Environment Variables

### `CORS_ORIGINS`

Controls which domains are allowed to access the API endpoints.

- **Default**: `*` (allows all origins - use only for development)
- **Production Example**: `https://yourdomain.com,https://app.yourdomain.com`
- **Format**: Comma-separated list of allowed origins

```bash
# Development (allows all origins)
export CORS_ORIGINS="*"

# Production (restrict to specific domains)
export CORS_ORIGINS="https://talk2me.example.com,https://app.example.com"
```

### `ADMIN_CORS_ORIGINS`

Controls which domains can access admin endpoints (more restrictive).

- **Default**: `http://localhost:*` (allows all localhost ports)
- **Production Example**: `https://admin.yourdomain.com`
- **Format**: Comma-separated list of allowed admin origins

```bash
# Development
export ADMIN_CORS_ORIGINS="http://localhost:*"

# Production
export ADMIN_CORS_ORIGINS="https://admin.talk2me.example.com"
```

## Configuration Details

The CORS configuration includes:

- **Allowed Methods**: GET, POST, OPTIONS
- **Allowed Headers**: Content-Type, Authorization, X-Requested-With, X-Admin-Token
- **Exposed Headers**: Content-Range, X-Content-Range
- **Credentials Support**: Enabled (supports cookies and authorization headers)
- **Max Age**: 3600 seconds (preflight requests cached for 1 hour)

## Endpoints

All endpoints have CORS enabled with the following configuration:

### Regular API Endpoints
- `/api/*`
- `/transcribe`
- `/translate`
- `/translate/stream`
- `/speak`
- `/get_audio/*`
- `/check_tts_server`
- `/update_tts_config`
- `/health/*`

### Admin Endpoints (More Restrictive)
- `/admin/*` - Uses `ADMIN_CORS_ORIGINS` instead of general `CORS_ORIGINS`

## Security Best Practices

1. **Never use `*` in production** - Always specify exact allowed origins
2. **Use HTTPS** - Always use HTTPS URLs in production CORS origins
3. **Separate admin origins** - Keep admin endpoints on a separate, more restrictive origin list
4. **Review regularly** - Periodically review and update allowed origins

## Example Configurations

### Local Development
```bash
export CORS_ORIGINS="*"
export ADMIN_CORS_ORIGINS="http://localhost:*"
```

### Staging Environment
```bash
export CORS_ORIGINS="https://staging.talk2me.com,https://staging-app.talk2me.com"
export ADMIN_CORS_ORIGINS="https://staging-admin.talk2me.com"
```

### Production Environment
```bash
export CORS_ORIGINS="https://talk2me.com,https://app.talk2me.com"
export ADMIN_CORS_ORIGINS="https://admin.talk2me.com"
```

### Mobile App Integration
```bash
# Include mobile app schemes if needed
export CORS_ORIGINS="https://talk2me.com,https://app.talk2me.com,capacitor://localhost,ionic://localhost"
```

## Testing CORS Configuration

You can test CORS configuration using curl:

```bash
# Test preflight request
curl -X OPTIONS https://your-api.com/api/transcribe \
  -H "Origin: https://allowed-origin.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -v

# Test actual request
curl -X POST https://your-api.com/api/transcribe \
  -H "Origin: https://allowed-origin.com" \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}' \
  -v
```

## Troubleshooting

### CORS Errors in Browser Console

If you see CORS errors:

1. Check that the origin is included in `CORS_ORIGINS`
2. Ensure the URL protocol matches (http vs https)
3. Check for trailing slashes in origins
4. Verify environment variables are set correctly

### Common Issues

1. **"No 'Access-Control-Allow-Origin' header"**
   - Origin not in allowed list
   - Check `CORS_ORIGINS` environment variable

2. **"CORS policy: The request client is not a secure context"**
   - Using HTTP instead of HTTPS
   - Update to use HTTPS in production

3. **"CORS policy: Credentials flag is true, but Access-Control-Allow-Credentials is not 'true'"**
   - This should not occur with current configuration
   - Check that `supports_credentials` is True in CORS config

## Additional Resources

- [MDN CORS Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
- [Flask-CORS Documentation](https://flask-cors.readthedocs.io/)