Session Coherence

The session coherence checker validates the Referer header against the visitor's navigation history. Real browsers send a Referer header on every non-navigational same-origin request, and the referer matches the page the user was on when they triggered the request. Bots that scrape pages or probe endpoints typically construct URLs directly, which either produces no referer or a referer that does not match the expected navigation path.

This checker runs in the heavy phase and reads from the session cache keyed by canary cookie.

How It Works

The checker stores the current request path in the session cache after evaluating each request. On the next request from the same canary cookie, it reads the previously stored path and compares it to the Referer header in the new request.

The following conditions each apply their own penalty:

Missing referer: The Referer header is absent on a request that originated from the same origin. Legitimate browsers always send a referer on same-origin navigation.

Domain mismatch: The referer's hostname does not match the server's hostname. This indicates the request came from an external origin that was not expected, or that a script assembled the request manually with a wrong referer.

Path mismatch: The referer's path does not match the previously stored request path. This indicates the visitor jumped to the current URL without visiting the previous page, which bots do when they scrape a list of URLs directly.

Invalid referer: The Referer header contains a value that cannot be parsed as a valid URL.

Configuration

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableSessionCoherence: {
      enable: true,
      penalties: {
        pathMismatch: 10,
        missingReferer: 20,
        domainMismatch: 30,
      },
    },
  },
})

All weights live inside the penalties: {} sub-object.

Reason Codes