Clearance

A clearance is one signed record of a probe, or of a probe and the ceremony that followed it. It is a JWT signed with Ed25519 under a key pair that belongs to your site. Your server or edge verifies it with the site’s public key from GET /v1/clearance/keys; Heretic is never in the request path. Heretic signs what it measured, including a contradicted verdict, and never withholds or reads back the token. The token is 900 to 1,200 bytes as a cookie value. Issuing one counts as one probe plus, when a ceremony is minted, one challenge against your plan.

Hosted page

Redirect an uncleared request to the hosted page. It runs the probe, escalates per the site’s clearance settings, and returns to your URL with heretic_clearance=<jwt> appended to the query.

https://heretic.tech/clearance?sitekey=hrtc_live_…&return=https://shop.example/account

return must be https://, or loopback http://, on the site’s registered domain. Any other value is refused on the page and never redirected. Your gate verifies the token, sets its cookie, and redirects to strip the parameter.

import { createRemoteJWKSet, jwtVerify } from 'jose';

const SITE_KEY = 'hrtc_live_…';
const DOMAIN = 'shop.example';
const JWKS = createRemoteJWKSet(new URL(`https://heretic.tech/v1/clearance/keys/${SITE_KEY}`));

async function verify(jwt) {
  const { payload } = await jwtVerify(jwt, JWKS, {
    issuer: 'https://heretic.tech', audience: DOMAIN, algorithms: ['EdDSA'],
  });
  return payload;
}

export default {
  async fetch(request) {
    const url = new URL(request.url);
    const returned = url.searchParams.get('heretic_clearance');
    url.searchParams.delete('heretic_clearance');
    if (returned && await verify(returned).catch(() => null)) {
      return new Response(null, { status: 303, headers: {
        location: url.toString(),
        'set-cookie': `heretic_clearance=${returned}; Path=/; Secure; HttpOnly; SameSite=Lax`,
      } });
    }
    const cookie = (request.headers.get('cookie') || '').match(/(?:^|;\s*)heretic_clearance=([^;]+)/)?.[1];
    const payload = cookie ? await verify(cookie).catch(() => null) : null;
    if (payload && allowed(payload, request)) return fetch(request);
    const to = new URL('https://heretic.tech/clearance');
    to.searchParams.set('sitekey', SITE_KEY);
    to.searchParams.set('return', url.toString());
    return Response.redirect(to.toString(), 302);
  },
};

allowed is your rule.

Background

Load guard.js with data-clearance="true". The embed runs without interaction and data-clearance-callback receives the JWT. Post it to your own endpoint, which verifies it and sets the cookie for the next request.

<script src="https://heretic.tech/guard.js" async defer></script>

<div class="heretic-guard"
     data-sitekey="hrtc_live_0123456789abcdef01234567"
     data-clearance="true"
     data-clearance-callback="onClearance"></div>

<script>
  function onClearance(jwt) {
    fetch('/heretic/clearance', { method: 'POST', body: jwt, credentials: 'same-origin' });
  }
</script>

heretic.getClearance(id) reads the JWT of a widget rendered with the script API.

Guarded action

A form keeps the five-minute proof and siteverify. Apply the same gate check to the form post, so a cleared visitor is not probed again there. Configure the widget on the challenge widget page.

What the token contains

Header: alg is EdDSA, typ is JWT, and kid is site_<id>/<version>.

{
  "iss": "https://heretic.tech",
  "aud": "shop.example",
  "sub": "0123456789abcdef0123456789abcdef",
  "jti": "<32 hex, random>",
  "iat": 1757300000,
  "exp": 1757386400,
  "heretic": {
    "v": 1,
    "site_id": "site_…",
    "site_key": "hrtc_live_…",
    "verdict": "uncontradicted",
    "concealed": false,
    "challenged": false,
    "outcome": null,
    "probe": {
      "request_id": "0123456789abcdef0123456789abcdef",
      "measured_at": 1757299990000,
      "client_ip": "203.0.113.7",
      "network": { "asn": 133481, "country": "TH", "class": "access" },
      "identity": { "version": 3, "instance": "<64 hex>", "machine": "<64 hex>" }
    },
    "challenge": null
  }
}

Field	Meaning
`iss`	Always `https://heretic.tech`.
`aud`	The site’s registered domain. A gate on `www.` or a subdomain compares against the registered domain.
`sub`	The probe `request_id`, or the challenge id when no probe was read.
`jti`	Random, 32 hex.
`iat`, `exp`	Seconds. `exp` is `iat` plus the site’s TTL. Your gate may require a shorter age from `iat`.
`heretic.v`	`1`.
`heretic.site_id`, `heretic.site_key`	The site the token was issued for.
`heretic.verdict`	`uncontradicted`, `contradicted`, or `refused`. `refused` with `probe: null` when the widget could not read the probe.
`heretic.concealed`	`true` when the probe reported any concealment indicator. It never changes the verdict.
`heretic.challenged`, `heretic.outcome`	`true` and `passed`, `contradicted`, or `not_completed` when a ceremony ran. Otherwise `false` and `null`.
`heretic.probe.request_id`	Keys `GET /v1/verdict`.
`heretic.probe.measured_at`	Milliseconds.
`heretic.probe.client_ip`, `heretic.probe.network`	The measured address, and its `asn`, `country`, and `class`.
`heretic.probe.identity`	`version`, `instance`, and `machine`. Each hash is 64 hex or `null`.
`heretic.challenge`	The ceremony when one ran. Otherwise `null`.

When a ceremony ran:

"challenge": {
  "id": "chg_…",
  "completed_at": 1757300100000,
  "device": {
    "request_id": "<32 hex>",
    "client_ip": "198.51.100.9",
    "network": { "asn": 5617, "country": "PL", "class": "access" },
    "identity": { "version": 3, "scope": "challenge-tenant-v1", "instance": "<64 hex>", "machine": "<64 hex>" }
  }
}

device is the device the ceremony cleared: the desktop in a QR hand-off, otherwise the phone. Its identity hashes are in the challenge scope. Compare them only with other ceremony devices, never with probe.identity.

Your rule

Verify the signature, iss, aud, and exp, then apply your own rule. This example accepts an uncontradicted probe without concealment, or a passed ceremony, and requires the live request to come from the measured address and network. It is this site’s rule, not a Heretic threshold.

function allowed(payload, request) {
  const { verdict, concealed, challenged, outcome, probe } = payload.heretic;
  if (challenged ? outcome !== 'passed' : verdict !== 'uncontradicted' || concealed) return false;
  if (!probe) return false;
  return probe.client_ip === request.headers.get('cf-connecting-ip')
    && probe.network.asn === request.cf.asn;
}

Facts

The hosted page is the only placement that gates the first request. It costs one wait of a few seconds per visitor per TTL. A client that does not run the collector is never cleared. That includes search crawlers. What happens to an uncleared request is your rule. Findings and concealment indicators are not in the token. The visitor can read the token. Read them with your secret key at GET /v1/verdict/{request_id}.

Dashboard settings

On the site’s panel in the dashboard:

Setting	Meaning
TTL	Token lifetime. Default 86,400 s. 300 s to 30 days.
Escalation	Which probe results run a ceremony on the hosted page. `contradicted` (default), `refused`, `always`, `never`, as for `data-escalate`.
Challenge concealed	Also runs a ceremony when the probe reports concealment indicators. Default off.
Rotate signing key	Issues a new key version. See rotation.

Verifiers

The server examples include node/clearance.mjs, python/clearance.py, php/Clearance.php, and a Cloudflare Worker gate at examples/cloudflare-worker/clearance-gate.js.

Get started

Collector

Challenge widget

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Clearance

Hosted page

Background

Guarded action

What the token contains

Your rule

Facts

Dashboard settings

Verifiers

​Hosted page

​Background

​Guarded action

​What the token contains

​Your rule

​Facts

​Dashboard settings

​Verifiers

Hosted page

Background

Guarded action

What the token contains

Your rule

Facts

Dashboard settings

Verifiers