> ## 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.

# How it works

> See how Foil detects AI-controlled browsers and automation: 350+ signals across seven scoring categories, server-side scoring, and backend verification of sealed tokens.

Foil detects AI-controlled browsers, stealth automation, and anti-detect tools by combining hundreds of signals collected in the browser with server-side cross-validation. The browser never sees the results - your backend makes the decisions.

## The pipeline

**1. Load the SDK**

Your page imports `t.js` and calls `Foil.start()`. The SDK opens an encrypted session and begins collecting signals immediately.

**2. Collect signals**

The SDK runs environment probes, fingerprinting, and behavioral observation. All data is encrypted and streamed to Foil's servers in real time.

**3. Freeze the fingerprint**

Once enough data is collected, the SDK freezes a device fingerprint. The browser learns that fingerprinting is ready, but never receives the fingerprint itself.

**4. Get a session handoff**

When the user performs a sensitive action, your code calls `getSession()`. Foil flushes pending observations, evaluates the session, and returns `{ sessionId, sealedToken }`.

**5. Verify on your backend**

Your server verifies the sealed token (locally, no network call) or fetches the full session from the API. Then it applies your policy.

## What gets scored

Foil combines 350+ signals across seven scoring categories, with a server-side **anti-tamper** layer that cross-validates them:

| Category | What it detects | Examples |
| - | - | - |
| **Environment** | Automation frameworks, headless browsers | `navigator.webdriver`, Playwright globals, stealth artifacts |
| **Fingerprint** | Spoofed or manipulated device profiles | WebGL anomalies, canvas noise, anti-detect patterns |
| **Event trust** | Synthetic vs real user events | `isTrusted === false`, clicks without mousemove |
| **Mouse** | Automated mouse movement | Linear paths, teleported cursor, Fitts' Law violations |
| **Keyboard** | Automated typing | Uniform timing, paste-only input, missing rollover |
| **Timing** | Inhuman speed patterns | Sub-50ms first interaction, >800 CPM form entry |
| **Touch** | Synthetic touch events | On mobile: speed variance, multi-touch ratios |

On top of the seven scored categories, **anti-tamper** runs server-side: it compares client claims against signals the browser can't forge - UA vs TLS (JA4) fingerprint, HTTP headers vs JS claims - and feeds the result back into scoring.

## Why scoring is server-side

Foil intentionally keeps all scoring logic off the browser:

* **Thresholds stay server-side** - nothing in the browser reveals scoring logic
* **Observations are encrypted** - binary payloads, not readable JSON
* **Server cross-validates** - compares browser claims against TLS fingerprint, IP context, and request headers
* **The browser never sees results** - no verdicts, scores, or visitor IDs leak to the page
* **Your backend is the policy point** - you decide what to do, not the browser

## Evaluation phases

| Phase | When it runs | What it uses | Confidence |
| - | - | - | - |
| **Snapshot** | Immediately | Environment, fingerprint, anti-tamper | Catches obvious automation fast |
| **Behavioral** | After user interaction | Mouse, keyboard, touch, timing | Higher confidence for ambiguous sessions |

Most sessions get a snapshot result within 200ms of `getSession()`. If the user has interacted with the page, the behavioral phase adds significantly stronger signals.

## What's next

* [Detection categories](https://usefoil.com/docs/detection-categories.md) - deeper look at each signal family
* [Verdicts & scoring](https://usefoil.com/docs/verdicts-and-scoring.md) - how Foil turns a score and its evidence into a verdict
* [Browser SDK](https://usefoil.com/docs/browser-sdk.md) - the client-side API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.