talk2me/CORS_CONFIG.md

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

# 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

# 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

export CORS_ORIGINS="*"
export ADMIN_CORS_ORIGINS="http://localhost:*"

Staging Environment

export CORS_ORIGINS="https://staging.talk2me.com,https://staging-app.talk2me.com"
export ADMIN_CORS_ORIGINS="https://staging-admin.talk2me.com"

Production Environment

export CORS_ORIGINS="https://talk2me.com,https://app.talk2me.com"
export ADMIN_CORS_ORIGINS="https://admin.talk2me.com"

Mobile App Integration

# 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:

# 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
• Flask-CORS Documentation