> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Content Security Policy

> Configure Content Security Policy directives for the Foil browser SDK, including the script-src, connect-src, worker-src, and frame-src values you need.

If your site sets a `Content-Security-Policy` header, you need to allow the Foil SDK to load, execute WebAssembly, spawn inline workers, create probe iframes, and communicate with the Foil API.

## Required directives

### `script-src`

The SDK is loaded as an ESM module from the Foil CDN. It also contains an embedded WebAssembly module that requires `'wasm-unsafe-eval'` to instantiate.

```text theme={"dark"}
script-src 'self' https://cdn.usefoil.com 'wasm-unsafe-eval';
```

| Value                     | Why                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `https://cdn.usefoil.com` | Loads the SDK bundle (`/t.js`)                                                                                            |
| `'wasm-unsafe-eval'`      | Instantiates the embedded WebAssembly module used for device fingerprinting, behavioral analysis, and environment probing |

<Note>
  Some older browsers require `'wasm-unsafe-eval'` while newer ones support the more restrictive `'wasm-eval'`. Use `'wasm-unsafe-eval'` for broadest compatibility.
</Note>

### `connect-src`

The SDK sends encrypted observation data and receives scoring results from the Foil API. It also opens a WebSocket for network identity cross-validation (VPN/proxy detection).

```text theme={"dark"}
connect-src 'self' https://api.usefoil.com wss://api.usefoil.com;
```

| Value                     | Why                                                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `https://api.usefoil.com` | All collect endpoints: session creation, observation batches, fingerprint freezing, sealed token minting, network checks, and RTT pings |
| `wss://api.usefoil.com`   | WebSocket connection for VPN/proxy network identity cross-validation                                                                    |

### `worker-src`

The SDK creates inline Web Workers from blob URLs for cross-thread environment validation and debugger detection.

```text theme={"dark"}
worker-src 'self' blob:;
```

| Value   | Why                                                                                                                                           |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `blob:` | Inline workers are constructed via `new Blob()` + `URL.createObjectURL()` for runtime integrity checks that must execute in a separate thread |

### `frame-src`

The SDK creates temporary hidden same-origin iframes for realm isolation probes, CSP bypass detection, and font measurement.

```text theme={"dark"}
frame-src 'self';
```

| Value    | Why                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `'self'` | Hidden `<iframe>` elements are appended to the DOM to obtain a clean JavaScript realm for tamper-resistant API probing |

## Full example

A minimal CSP that supports Foil alongside your own assets:

```text theme={"dark"}
default-src 'self';
script-src 'self' https://cdn.usefoil.com 'wasm-unsafe-eval';
connect-src 'self' https://api.usefoil.com wss://api.usefoil.com;
worker-src 'self' blob:;
frame-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
object-src 'none';
base-uri 'self';
```

<Note>
  Foil itself needs no `font-src` — it measures font metrics in place and fetches no external fonts. Add `font-src` only for your own web fonts.
</Note>

If you use a meta tag instead of a response header:

```html theme={"dark"}
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' https://cdn.usefoil.com 'wasm-unsafe-eval'; connect-src 'self' https://api.usefoil.com wss://api.usefoil.com; worker-src 'self' blob:; frame-src 'self';"
/>
```

## Graceful degradation

The SDK is designed to degrade gracefully. If a CSP directive blocks a specific probe (e.g., workers or iframes), the SDK will skip that signal and continue with the remaining detection surface. However, missing signals reduce coverage and may affect verdict confidence. For best results, allow all directives listed above.

## What Foil does NOT need

| Directive   | Why not needed                                |
| ----------- | --------------------------------------------- |
| `media-src` | No audio or video resources are loaded        |
| `child-src` | Covered by `worker-src` and `frame-src` above |

## Troubleshooting

Check the browser DevTools console for CSP violation errors. Common failures:

| Error message                                             | Fix                                            |
| --------------------------------------------------------- | ---------------------------------------------- |
| Refused to load the script `https://cdn.usefoil.com/t.js` | Add `https://cdn.usefoil.com` to `script-src`  |
| Refused to compile or instantiate WebAssembly module      | Add `'wasm-unsafe-eval'` to `script-src`       |
| Refused to connect to `https://api.usefoil.com`           | Add `https://api.usefoil.com` to `connect-src` |
| Refused to create a worker from `blob:`                   | Add `blob:` to `worker-src`                    |
| Refused to frame (same-origin iframe blocked)             | Add `'self'` to `frame-src`                    |

<Tip>
  If you use a CSP reporting endpoint (`report-uri` or `report-to`), deploy in report-only mode first with `Content-Security-Policy-Report-Only` to catch violations without breaking the page.
</Tip>