Allowed Opaque Origins

By default, Stellate handles CORS (Cross-Origin Resource Sharing) automatically for standard web origins. However, certain environments use opaque origins that cannot be parsed as standard tuple origins by URL parsers. This causes Stellate to fall back to wildcard (*) CORS headers, which breaks credentialed requests.

The allowedOpaqueOrigins configuration option allows you to explicitly permit specific opaque origins, enabling proper CORS handling for browser extensions, hybrid mobile apps, and other non-standard environments.

What are Opaque Origins?

Opaque origins are non-standard origin schemes that browsers and hybrid app frameworks use internally. Unlike tuple origins (e.g., https://example.com), opaque origins cannot be parsed into the standard scheme://host:port format.

Common opaque origins include:

The Problem

When a request arrives with an opaque origin, Stellate’s URL parser cannot process it as a tuple origin. The current behavior falls back to returning Access-Control-Allow-Origin: * in the response.

While * allows the request to complete, it prevents credentialed requests (requests with cookies or authorization headers) from working. Browsers require the exact origin to be echoed back for credentialed requests to succeed.

Configuration

Add the allowedOpaqueOrigins property to your Stellate configuration to specify which opaque origins should be allowed.

import { Config } from 'stellate'
 
const config: Config = {
  config: {
    name: 'my-service',
    originUrl: 'https://my-api.example.com/graphql',
    allowedOpaqueOrigins: [
      'chrome-extension://*',   // All Chrome extensions
      'moz-extension://*',      // All Firefox extensions
      'capacitor://localhost',  // Capacitor apps (exact)
    ],
  },
}
export default config

Behavior

The following table shows how different origins are handled based on your configuration:

Use Cases

Browser Extensions

Chrome and Firefox extensions that make GraphQL requests to your Stellate service need their origins explicitly allowed:

const config: Config = {
  config: {
    name: 'my-service',
    originUrl: 'https://api.example.com/graphql',
    allowedOpaqueOrigins: [
      'chrome-extension://*',  // Allow all Chrome extensions
      'moz-extension://*',     // Allow all Firefox extensions
    ],
  },
}

If you want to restrict access to specific extensions, use exact matches:

allowedOpaqueOrigins: [
  'chrome-extension://abcdefghijklmnop',  // Only your extension
]

Capacitor/Ionic Apps

Hybrid mobile apps built with Capacitor  or Ionic  use the capacitor:// protocol:

const config: Config = {
  config: {
    name: 'my-service',
    originUrl: 'https://api.example.com/graphql',
    allowedOpaqueOrigins: [
      'capacitor://localhost',  // Standard Capacitor origin
      'capacitor://*',          // Or allow all Capacitor origins
    ],
  },
}

Electron Apps

Desktop applications built with Electron may use custom protocol schemes:

const config: Config = {
  config: {
    name: 'my-service',
    originUrl: 'https://api.example.com/graphql',
    allowedOpaqueOrigins: [
      'app://*',      // Custom Electron protocol
      'electron://*', // Alternative Electron protocol
    ],
  },
}

Security Considerations

Recommendations:

• For public APIs: Wildcard patterns are generally acceptable since any client can already access your API.
• For private APIs: Consider using exact matches for specific extension IDs or app identifiers you control.
• For sensitive operations: Combine this feature with other security measures like rate limiting and authentication.