CORS

CORSConfig — all fields

Where CORS lives

CORS is configured per project, directly under the project object:

projects:
  - id: main
    cors:
      allowedOrigins: ["https://app.example.com"]
      # ...

There is no global CORS config — each project sets its own policy. This lets you lock down a frontend project to your app's domain while keeping a backend project unrestricted (no CORS headers at all).

The admin HTTP server (adminServer) does not share the project CORS config. If you expose an admin UI in a browser context, restrict it via network/firewall rather than CORS.

Origin matching rules

eRPC matches the request's Origin header against each entry in allowedOrigins in order:

• Exact match: "https://app.example.com" matches only that origin.
• Wildcard subdomain: "https://*.example.com" matches https://app.example.com, https://staging.example.com, etc. The * matches exactly one label — https://a.b.example.com does NOT match https://*.example.com.
• Wildcard all origins: "*" matches every origin. Only safe when allowCredentials: false.

If no entry matches, eRPC returns the response without any Access-Control-* headers. The browser then blocks the response for cross-origin JS callers (standards-compliant behavior — the server never hard-drops the request).

Preflight (OPTIONS) handling

Browsers send an OPTIONS preflight before any cross-origin request that is not a "simple request" (e.g. uses POST with Content-Type: application/json, or custom headers). eRPC automatically handles the OPTIONS preflight when the origin matches — it returns 200 OK with the Access-Control-* headers and does not forward the preflight to an upstream.

Always include "OPTIONS" in allowedMethods if you want preflights to succeed.

Full example — browser frontend + multi-project

projects:
  # Browser dApp — tight CORS, no credentials
  - id: frontend
    cors:
      allowedOrigins:
        - "https://app.example.com"
        - "https://*.app.example.com"
      allowedMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowedHeaders:
        - "Content-Type"
      exposedHeaders:
        - "X-Request-ID"
      allowCredentials: false
      maxAge: 3600
    upstreams:
      - endpoint: alchemy://${ALCHEMY_KEY}
 
  # Backend indexer — no CORS needed (server-to-server)
  - id: indexer
    upstreams:
      - endpoint: ${ARCHIVE_NODE_URL}

Common pitfalls

• allowCredentials: true with allowedOrigins: ["*"] — browsers refuse the response with a CORS error. You must list explicit origins when credentials are enabled.
• Missing "OPTIONS" in allowedMethods — preflight is answered without the methods header; browsers block the actual request.
• maxAge above the browser cap — Chrome silently caps at 7200 s, Firefox at 86400 s. Setting a higher value has no effect and may mislead you about cache TTL.
• Case sensitivity of header names — allowedHeaders entries are matched case-insensitively by eRPC, but list them in their canonical form (e.g. Content-Type, not content-type) for clarity.
• Wildcard subdomain too broad — https://*.example.com also matches https://evil.example.com if an attacker can create a subdomain. Combine with auth strategies for production frontends.
• No CORS on the admin server — admin endpoints (:9090/admin/...) do not inherit project CORS. Do not expose the admin port publicly; restrict via network rules.