Wildcard CORS Support #

XyPriss now supports wildcard patterns in CORS origin configurations, making it easier to handle multiple domains and ports during development and production.

Overview #

The wildcard CORS feature allows developers to specify flexible origin patterns instead of listing every possible URL. This is particularly useful for:

• Development environments with multiple ports
• Microservices running on different ports
• Subdomain-based applications
• Dynamic port allocation in containerized environments

Supported Patterns #

Port Wildcards #

• localhost:* - Matches any port on localhost
• 127.0.0.1:* - Matches any port on 127.0.0.1
• ::1:* - Matches any port on IPv6 localhost

Subdomain Wildcards #

• *.example.com - Matches any subdomain of example.com
• *.api.myapp.com - Matches any subdomain of api.myapp.com

Usage Examples #

Basic Configuration #

import { createServer } from "xypriss";

const app = createServer({
    security: {
        cors: {
            origin: [
                "localhost:*",        // Allow any localhost port
                "127.0.0.1:*",       // Allow any 127.0.0.1 port
                "*.myapp.com"        // Allow any subdomain
            ]
        }
    }
});

Development vs Production #

const isDevelopment = process.env.NODE_ENV === 'development';

const app = createServer({
    security: {
        cors: {
            origin: isDevelopment 
                ? [
                    "localhost:*",
                    "127.0.0.1:*",
                    "::1:*"
                  ]
                : [
                    "https://app.mycompany.com",
                    "https://admin.mycompany.com"
                  ]
        }
    }
});

Mixed Patterns #

const app = createServer({
    security: {
        cors: {
            origin: [
                "localhost:*",              // Development
                "https://app.example.com",  // Exact production URL
                "*.staging.example.com"     // Staging subdomains
            ]
        }
    }
});

Pattern Matching Rules #

URL Processing #

• Full URLs are parsed to extract host:port
• Default ports are handled automatically (80 for HTTP, 443 for HTTPS)
• IPv6 addresses are properly processed (brackets removed for matching)

Examples of Matches #

Advanced Configuration #

With Credentials and Methods #

const app = createServer({
    security: {
        cors: {
            origin: ["localhost:*", "*.myapp.com"],
            credentials: true,
            methods: ["GET", "POST", "PUT", "DELETE"],
            allowedHeaders: ["Content-Type", "Authorization"]
        }
    }
});

Using Middleware API #

import { createServer } from "xypriss";

const app = createServer();

app.middleware({
    cors: {
        origin: ["localhost:*", "127.0.0.1:*"],
        credentials: true
    }
});

Security Considerations #

Production Best Practices #

1. Be Specific: Use exact domains in production when possible
2. Avoid Overly Broad Patterns: * allows all origins - use specific wildcards
3. Validate Subdomains: Ensure you control all subdomains when using *.domain.com

Development vs Production #

// ✅ Good - Specific patterns
const corsConfig = {
    origin: process.env.NODE_ENV === 'production' 
        ? ["https://app.mycompany.com", "https://admin.mycompany.com"]
        : ["localhost:*", "127.0.0.1:*"]
};

// ❌ Avoid - Too permissive for production
const corsConfig = {
    origin: "*" // Allows ALL origins
};

Implementation Details #

Automatic Detection #

XyPriss automatically detects when wildcard patterns are used in the origin array and switches to custom pattern matching.

Performance #

• Pattern compilation is done once during server initialization
• Regex matching is optimized for common patterns
• No performance impact when wildcards aren't used

Backward Compatibility #

• Existing exact-match origins continue to work unchanged
• Mixed arrays (exact + wildcard) are fully supported
• Standard CORS options remain the same

Testing #

Unit Tests #

The wildcard functionality includes comprehensive tests covering:

• Port wildcard matching
• Subdomain wildcard matching
• IPv6 address handling
• Default port handling
• Edge cases and error conditions

Integration Testing #

// Test wildcard CORS in your application
describe('CORS Wildcard', () => {
    test('should allow localhost with any port', async () => {
        const response = await request(app)
            .options('/api/test')
            .set('Origin', 'http://localhost:3000')
            .expect(200);
            
        expect(response.headers['access-control-allow-origin'])
            .toBe('http://localhost:3000');
    });
});

Migration Guide #

From Exact Origins #

Before:

cors: {
    origin: [
        "http://localhost:3000",
        "http://localhost:3001", 
        "http://localhost:8080"
    ]
}

After:

cors: {
    origin: ["localhost:*"]
}

From Permissive CORS #

Before:

cors: {
    origin: true  // Allows all origins
}

After:

cors: {
    origin: [
        "localhost:*",
        "127.0.0.1:*", 
        "*.yourdomain.com"
    ]
}

Troubleshooting #

Common Issues #

1. Pattern Not Matching

   • Ensure the pattern syntax is correct
   • Check if the origin includes protocol (http/https)
   • Verify IPv6 addresses are properly formatted

2. Still Getting CORS Errors

   • Check browser developer tools for the exact origin being sent
   • Verify the pattern matches the origin format
   • Ensure credentials settings match your request

Debug Mode #

Enable debug logging to see CORS pattern matching:

const app = createServer({
    logging: {
        level: 'debug'
    },
    security: {
        cors: {
            origin: ["localhost:*"]
        }
    }
});

Changelog #

Version 2.3.4 #

• ✅ Added wildcard pattern support for CORS origins
• ✅ Support for port wildcards (localhost:*, 127.0.0.1:*, ::1:*)
• ✅ Support for subdomain wildcards (*.example.com)
• ✅ Automatic pattern detection and switching
• ✅ Comprehensive test coverage
• ✅ Full backward compatibility

Related Documentation #

• Security Configuration
• CORS Configuration
• Development Setup