feat(signalling): add CORS support to web server (#387)

Adds an optional CORS middleware to WebServer so browser-based clients
hosted on a different origin can call the REST API and other routes.
Wilbur exposes --cors plus --cors_allowed_origins, --cors_allowed_methods,
--cors_allowed_headers, and --cors_credentials, and reads matching keys
from config.json. Default is off; when on, an empty origin list allows
any origin.

Author: mcottontensor

.changeset/cors-signalling-api.md

@@ -0,0 +1,6 @@
+---
+"@epicgames-ps/lib-pixelstreamingsignalling-ue5.7": minor
+"@epicgames-ps/wilbur": minor
+---
+
+Add CORS support to the signalling web server. A new `IWebServerConfig.cors` option registers the `cors` Express middleware before the rate limiter and any route handlers, so that custom frontends hosted on a different origin can call the REST API (`--rest_api`) or any other route mounted on the app. Wilbur exposes this through a `--cors` CLI flag (default off) plus `--cors_allowed_origins`, `--cors_allowed_methods`, `--cors_allowed_headers`, and `--cors_credentials`. All four sub-options accept comma-separated values and read matching `cors*` keys from `config.json`. When `--cors` is set without an explicit origin list, all origins are allowed.

Signalling/package.json

@@ -20,6 +20,7 @@
     "license": "MIT",
     "devDependencies": {
         "@eslint/js": "^9.20.0",
+        "@types/cors": "^2.8.17",
         "@types/express": "^5.0.0",
         "@types/node": "^22.14.0",
         "@types/ws": "^8.5.14",
@@ -36,6 +37,7 @@
     },
     "dependencies": {
         "body-parser": "^1.20.4",
+        "cors": "^2.8.5",
         "express": "^4.22.1",
         "express-rate-limit": "^8.2.2",
         "helmet": "^8.0.0",

Signalling/src/WebServer.ts

@@ -5,12 +5,40 @@ import fs from 'fs';
 import http from 'http';
 import https from 'https';
 import helmet from 'helmet';
+import cors from 'cors';
 import { Logger } from './Logger';
 import RateLimit from 'express-rate-limit';
 
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
 const hsts = require('hsts');
 
+/**
+ * Options for configuring CORS on the Express app. When `enabled` is true the
+ * `cors` middleware is registered so that browser-based clients hosted on a
+ * different origin (e.g. a custom frontend) can call the REST API or other
+ * routes mounted on the app. Use `allowedOrigins` to restrict which origins
+ * are accepted; an empty / unset list means "allow all origins" (`*`).
+ */
+export interface ICorsConfig {
+    // If false (or unset) no CORS headers are added. Defaults to false.
+    enabled?: boolean;
+
+    // List of origins to allow. If empty/unset, all origins are allowed.
+    allowedOrigins?: string[];
+
+    // List of HTTP methods to allow. Defaults to the `cors` package default
+    // (`GET,HEAD,PUT,PATCH,POST,DELETE`).
+    allowedMethods?: string[];
+
+    // List of request headers to allow. If unset, the `cors` package mirrors
+    // the request's `Access-Control-Request-Headers` header.
+    allowedHeaders?: string[];
+
+    // Whether the request can include credentials (cookies, auth headers).
+    // Defaults to false.
+    credentials?: boolean;
+}
+
 /**
  * An interface that describes the possible options to pass to
  * WebServer.
@@ -45,6 +73,11 @@ export interface IWebServerConfig {
     // registered by other subsystems, such as a REST API, remain reachable),
     // but no static files are served.
     serveStatic?: boolean;
+
+    // Optional CORS configuration. When `cors.enabled` is true the cors
+    // middleware is registered before the rate limiter and any route handlers,
+    // so that all routes mounted on the app respond with CORS headers.
+    cors?: ICorsConfig;
 }
 
 /**
@@ -117,6 +150,33 @@ export class WebServer {
             }
         }
 
+        if (config.cors?.enabled) {
+            const corsOptions: cors.CorsOptions = {};
+
+            if (config.cors.allowedOrigins && config.cors.allowedOrigins.length > 0) {
+                corsOptions.origin = config.cors.allowedOrigins;
+            }
+            if (config.cors.allowedMethods && config.cors.allowedMethods.length > 0) {
+                corsOptions.methods = config.cors.allowedMethods;
+            }
+            if (config.cors.allowedHeaders && config.cors.allowedHeaders.length > 0) {
+                corsOptions.allowedHeaders = config.cors.allowedHeaders;
+            }
+            if (config.cors.credentials) {
+                corsOptions.credentials = true;
+            }
+
+            // Register cors before the rate limiter so that preflight (OPTIONS)
+            // requests are answered with CORS headers even when an origin is
+            // close to the rate limit, and before any route handlers so the
+            // homepage, static files, and the REST API all respond uniformly.
+            app.use(cors(corsOptions));
+
+            Logger.info(
+                `CORS enabled. Allowed origins: ${corsOptions.origin ? JSON.stringify(corsOptions.origin) : '*'}`
+            );
+        }
+
         const limiter = RateLimit({
             windowMs: 60 * 1000, // 1 minute
             max: config.perMinuteRateLimit ? config.perMinuteRateLimit : 3000

SignallingWebServer/config.json

@@ -14,6 +14,11 @@
 	"ssl_cert_path": "certificates/client-cert.pem",
 	"https_redirect": true,
 	"rest_api": false,
+	"cors": false,
+	"cors_allowed_origins": "",
+	"cors_allowed_methods": "",
+	"cors_allowed_headers": "",
+	"cors_credentials": false,
 	"reverse_proxy": false,
 	"reverse_proxy_num_proxies": 1,
 	"peer_options": "",

SignallingWebServer/src/index.ts

@@ -145,6 +145,31 @@ program
         'Enables the rest API interface that can be accessed at <server_url>/api/api-definition',
         config_file.rest_api || false
     )
+    .option(
+        '--cors',
+        'Enables CORS headers on the webserver. Required for browser-based clients hosted on a different origin to call routes such as the REST API.',
+        config_file.cors || false
+    )
+    .option(
+        '--cors_allowed_origins <origins>',
+        'Comma-separated list of allowed origins (e.g. "https://example.com,https://other.example.com"). If omitted, all origins are allowed.',
+        config_file.cors_allowed_origins || ''
+    )
+    .option(
+        '--cors_allowed_methods <methods>',
+        'Comma-separated list of allowed HTTP methods. Defaults to the cors middleware default if omitted.',
+        config_file.cors_allowed_methods || ''
+    )
+    .option(
+        '--cors_allowed_headers <headers>',
+        "Comma-separated list of allowed request headers. If omitted, the request's Access-Control-Request-Headers value is mirrored.",
+        config_file.cors_allowed_headers || ''
+    )
+    .option(
+        '--cors_credentials',
+        'Allow credentials (cookies, authorization headers) on cross-origin requests.',
+        config_file.cors_credentials || false
+    )
     .addOption(
         new Option(
             '--peer_options <json-string>',
@@ -257,6 +282,24 @@ if (shouldServerStart) {
         serveStatic: options.serve
     };
 
+    if (options.cors) {
+        const splitCsv = (value: unknown): string[] => {
+            if (typeof value !== 'string' || value.length === 0) return [];
+            return value
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        };
+
+        webserverOptions.cors = {
+            enabled: true,
+            allowedOrigins: splitCsv(options.cors_allowed_origins),
+            allowedMethods: splitCsv(options.cors_allowed_methods),
+            allowedHeaders: splitCsv(options.cors_allowed_headers),
+            credentials: !!options.cors_credentials
+        };
+    }
+
     if (options.serve) {
         Logger.info('Static file serving enabled.');
     } else if (options.rest_api) {