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

<Steps>
  <Step title="Load the SDK">
    Your page imports `t.js` and calls `Foil.start()`. The SDK opens an encrypted session and begins collecting signals immediately.
  </Step>

  <Step title="Collect signals">
    The SDK runs environment probes, fingerprinting, and behavioral observation. All data is encrypted and streamed to Foil's servers in real time.
  </Step>

  <Step title="Freeze the fingerprint">
    Once enough data is collected, the SDK freezes a durable device fingerprint. The browser learns that fingerprinting is ready, but never receives the fingerprint itself.
  </Step>

  <Step title="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 }`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/detection-categories) — deeper look at each signal family
* [Verdicts & scoring](/verdicts-and-scoring) — how scores map to verdicts
* [Browser SDK](/browser-sdk) — the client-side API