# CORS Configuration

The server can be [configured](Config.md) to use CORS - Cross-Origin Resource Sharing (CORS), 

## Summary of CORS

CORS is a browser security feature that restricts web pages from making requests to a different domain than the one that served the web page. This prevents malicious websites from accessing sensitive data from other sites.

### Key Concepts

* **Origin:** Defined by the protocol (e.g., `http`, `https`), domain (e.g., `example.com`), and port (e.g., `:80`, `:443`). Two URLs have the same origin only if all three components match exactly.
* **Cross-Origin Request:** A request made from a script running on one origin to a resource on a different origin.
* **Preflight Request (OPTIONS):** For certain "complex" requests (e.g., using HTTP methods other than `GET`, `HEAD`, or `POST` with certain content types), the browser sends a preliminary `OPTIONS` request to the server to check if the actual request is allowed.
* **HTTP Headers:** CORS relies on specific HTTP headers exchanged between the browser and the server.

### Common CORS-related Headers

**Request Headers (Browser -> Server):**

* `Origin`: Indicates the origin of the request.

**Response Headers (Server -> Browser):**

* `Access-Control-Allow-Origin`: Specifies the origin(s) that are allowed to access the resource (can be `*` for any origin, but this is generally not recommended for security reasons).
* `Access-Control-Allow-Methods`: Specifies the allowed HTTP methods (e.g., `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`).
* `Access-Control-Allow-Headers`: Specifies which request headers can be used when making the actual request.
* `Access-Control-Expose-Headers`: Specifies which response headers can be accessed by the client-side script.
* `Access-Control-Allow-Credentials`: Indicates whether the actual request can include user credentials like cookies or authorization headers (`true` or `false`).
* `Access-Control-Max-Age`: Specifies the duration (in seconds) for which the preflight request can be cached.

### How CORS Works (Simplified)

1.  The browser makes a cross-origin request.
2.  The server responds with CORS-related headers.
3.  The browser checks these headers.
4.  If the headers indicate that the request is allowed based on the origin, method, and headers, the browser allows the response to be processed by the client-side script. Otherwise, the browser blocks the request or the processing of the response.

### Why is CORS Important?

CORS is a crucial security mechanism that helps protect users from cross-site scripting (XSS) and other malicious attacks by preventing unauthorized access to resources.


## CORS within Plugin Server
The plugin server uses a middleware to control CORS headers. If enabled the OPTIONS request for the preflight check by browsers is handled and if the connecting host is in the origin_url list the request can be satisfied.

### Configuration of CORS 
CORS is implemented in the plugin server with a few [configuration](Config.md) key,value pairs under [CORS}

| Key           | Value/Usage
|---------------|------------
| enabled       | `bool:true` Enable cors
| origin_url	   | `list:https://host1.domain1.tld https://host2.domain2.tld`

The minimal requirement is for enabled to be true and origin url to be populated.