La chiamata dal tuo server

Prima dell'azione protetta, il tuo server chiede a Bot Protection un parere sulla richiesta e applica l'action della risposta. Usa un timeout breve e lascia passare il visitatore in caso di qualsiasi errore: questo è il fail-open, e significa che Bot Protection non potrà mai mandare giù la tua registrazione.

La richiesta

curl -s -X POST https://korzen.dev/v1/decide \
  -H "Authorization: Bearer $KORZEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Korzen-Deadline-Ms: 200" \
  -d '{"ip":"203.0.113.10","user_agent":"Mozilla/5.0 …",
       "headers":{"accept":"text/html,…","accept-language":"en-US","sec-ch-ua":"…","sec-fetch-site":"same-origin"},
       "token":"<the _kz cookie>","path":"/signup","method":"POST"}'

Ogni campo è facoltativo, e più ne invii più Bot Protection vede. Un campo che Bot Protection non conosce, come requireToken al posto di require_token, viene rifiutato con 400 unknown_field, che lo nomina: un errore di battitura non passa mai per un valore predefinito.

In headers, invia questi come li ha inviati il browser del visitatore, con il nome in minuscolo, e tralascia quelli che la richiesta non porta: accept, accept-encoding, accept-language, sec-ch-ua, sec-ch-ua-mobile, sec-ch-ua-platform, sec-fetch-dest, sec-fetch-mode, sec-fetch-site e upgrade-insecure-requests. Ogni copia di una stessa build di browser invia gli stessi valori, quindi uno script che copia lo User-Agent di un browser ma non il resto si nota. Gli SDK e il codice qui sotto inviano questa lista.

Da Node, invia anche header_order: i nomi degli header della richiesta nell'ordine in cui sono arrivati, in minuscolo (una voce sì e una no di req.rawHeaders), come ["host", "user-agent", "accept"]. Uno script copia i valori degli header di un browser più spesso del loro ordine. Dove l'ordine si perde (il net/http di Go, gli Headers della Fetch API, un Cloudflare Worker), lascialo fuori; un valore che non è una lista di nomi di header viene ignorato, mai rifiutato.

Un valore più lungo di quanto Bot Protection conserva viene tagliato, mai rifiutato: 512 byte dello User-Agent, del path e di ogni header, 32 header (i primi per nome), 256 byte del token. Gli SDK li tagliano prima di inviare la chiamata; una chiamata tua può inviarli interi. Il corpo viene letto fino a 256 KiB, in cui una chiamata entro quei limiti sta sempre; oltre, vengono giudicati i campi arrivati interi entro 256 KiB, quindi un header enorme scritto da un visitatore non costa una decisione.

L'IP del visitatore

Dietro un proxy o una CDN, invia l'IP del visitatore così come lo riporta il tuo proxy o la tua CDN (CF-Connecting-IP su Cloudflare, l'indirizzo che il tuo load balancer ha aggiunto a X-Forwarded-For), non uno che il visitatore potrebbe aver scritto in un header.

Un indirizzo che non è su Internet (10.x, 172.16–31.x, 192.168.x, 100.64–127.x, fc00::/7, fe80::/10) è della tua rete: di un load balancer, di un proxy, di un container. Non è mai quello di un visitatore, quindi Bot Protection giudica quella decisione come una inviata senza IP, e vede molto meno. È ciò che invia un server che legge l'indirizzo della connessione dietro un load balancer. Quando la maggior parte delle tue decisioni ne porta uno, la pagina Configurazione lo segnala. 127.0.0.1 e ::1, mentre provi sulla tua macchina, vanno bene. Dietro un proxy sullo stesso host (il proxy_pass di nginx verso localhost) sono quelli del proxy per ogni visitatore, e anche questo la pagina Configurazione lo segnala appena il tag mostra che le tue pagine non sono su localhost.

Un indirizzo di un edge di una CDN (di Cloudflare, di Fastly, di CloudFront, secondo gli intervalli che ognuno pubblica) è della CDN, lo stesso per ogni visitatore dietro di essa: il tuo server ha inviato l'indirizzo da cui veniva la sua stessa richiesta. Anche questa decisione Bot Protection la giudica come una inviata senza IP e, quando la maggior parte delle tue decisioni ne porta uno, la pagina Configurazione lo segnala.

La risposta

{
  "request_id": "AQEAo3k9Zx4VbQ…",
  "class": "bot",
  "bot_score": 72,
  "human_score": 0,
  "reasons": ["behaviour", "inconsistency"],
  "rules": [],
  "step_up": false,
  "action": "allow",
  "intended_action": "challenge",
  "mode": "monitor",
  "challenge": { "url": null, "passed": false },
  "token_required": false,
  "seen_before": 0,
  "crawler": null
}

Ogni membro è sempre presente: un oggetto che non ha nulla da dire è null, una lista vuota è [], mai null.

Errori

Qualsiasi status diverso da 200 (una chiave sbagliata, il limite del mese raggiunto, un disservizio) significa: lascia passare il visitatore. Il body di un errore è un problem RFC 9457, application/problem+json, il cui code dice cosa è andato storto:

{
  "type": "https://korzen.dev/bot-protection/docs/server-call#unknown_field",
  "title": "A field is not known",
  "status": 400,
  "code": "unknown_field",
  "detail": "unknown field `requireToken`, expected one of `ip`, `user_agent`, …",
  "request_id": "rq_01a15441820577808ce489c291023c16"
}

Ogni risposta porta Korzen-Request-Id, lo stesso del request_id del problem: indicalo quando ci chiedi di una chiamata. Decide, events e feedback portano gli header RateLimit-Policy e RateLimit dell'IETF per le decisioni del tuo account: "month";q=50000 e "month";r=41234;t=86400 dicono che restano 41.234 delle 50.000 del mese e che il mese finisce tra un giorno (nella prova gratuita, "trial"). Registrali se vuoi, e non aspettarli mai. Gli SDK li passano entrambi a onAnswer (in Go, OnAnswer) dopo ogni chiamata.

Cosa sa il tuo server

I fatti che il tuo server ha verificato da sé rendono la risposta più sicura. Inviali in claims, tutti facoltativi:

"claims": {"account_age_days": 420, "known_instrument": true, "device_attested": false, "contact_verified": true}

Insieme a un feedback che dice che il visitatore è un buon cliente, known_instrument o device_attested è ciò che alza una risposta a human_high. Invia solo quello che hai verificato: un claim è un indizio di una persona.

Latenza e timeout

Bot Protection gira a Falkenstein, in Germania. Una decisione richiede il round trip di rete dal tuo server più qualche millisecondo, su una connessione che il tuo server tiene aperta; una nuova connessione aggiunge l'handshake TLS, uno o due round trip in più. Usa un solo client HTTP per tutto il processo, come negli esempi qui sotto, e scegli il timeout in base a dove gira il tuo server. Invialo come Korzen-Deadline-Ms, quanto attende in tutto la tua chiamata: Bot Protection ne prende metà per la decisione, tra 10 e 1.000 ms (200 ms senza l'header), e lascia l'altra metà alla rete. Una decisione non presa entro la sua metà riceve subito 503 deadline, e non viene contata. Gli SDK inviano il loro timeout per te.

Un timeout troppo breve per la distanza lascia passare ogni visitatore, e quelle chiamate contano comunque come decisioni.

// lib/korzen.js: call before creating the account, in a route handler or server action.
import { cookies, headers } from "next/headers";

// The headers Bot Protection reads: those one browser build sends alike, and Accept-Language.
const FORWARDED = ["accept", "accept-encoding", "accept-language", "sec-ch-ua", "sec-ch-ua-mobile", "sec-ch-ua-platform",
  "sec-fetch-dest", "sec-fetch-mode", "sec-fetch-site", "upgrade-insecure-requests"];

export async function decide(path) {
  const h = await headers();
  try {
    const res = await fetch("https://korzen.dev/v1/decide", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.KORZEN_API_KEY}`, "Content-Type": "application/json",
        "Korzen-Deadline-Ms": "200", // how long this call waits: the decision takes half
      },
      body: JSON.stringify({
        ip: h.get("x-forwarded-for")?.split(",")[0].trim(), // Vercel sets it; elsewhere, your proxy's header
        user_agent: h.get("user-agent"),
        headers: Object.fromEntries(FORWARDED.filter((n) => h.has(n)).map((n) => [n, h.get(n)])),
        token: (await cookies()).get("_kz")?.value,
        path, method: "POST",
      }),
      signal: AbortSignal.timeout(200),
    });
    return res.ok ? (await res.json()).action : "allow";
  } catch {
    return "allow"; // fail open
  }
}

// The headers Bot Protection reads: those one browser build sends alike, and Accept-Language.
const FORWARDED = ["accept", "accept-encoding", "accept-language", "sec-ch-ua", "sec-ch-ua-mobile", "sec-ch-ua-platform",
  "sec-fetch-dest", "sec-fetch-mode", "sec-fetch-site", "upgrade-insecure-requests"];

app.post("/signup", async (req, res) => {
  let action = "allow";
  try {
    const r = await fetch("https://korzen.dev/v1/decide", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.KORZEN_API_KEY}`, "Content-Type": "application/json",
        "Korzen-Deadline-Ms": "200", // how long this call waits: the decision takes half
      },
      body: JSON.stringify({
        ip: req.ip, user_agent: req.get("user-agent"), token: req.cookies?._kz, path: "/signup", method: "POST",
        headers: Object.fromEntries(FORWARDED.filter((n) => req.get(n) !== undefined).map((n) => [n, req.get(n)])),
        header_order: req.rawHeaders.filter((_, i) => i % 2 === 0).map((n) => n.toLowerCase()), // the order they came in
      }),
      signal: AbortSignal.timeout(200),
    });
    if (r.ok) action = (await r.json()).action;
  } catch {} // fail open
  if (action === "block") return res.status(400).send("We could not create your account.");
  // "challenge": your CAPTCHA or email check here. Then create the account.
});

// forwarded are the headers Bot Protection reads: those one browser build sends alike, and
// Accept-Language. net/http keeps no header order, so header_order is left out.
var forwarded = []string{"accept", "accept-encoding", "accept-language", "sec-ch-ua", "sec-ch-ua-mobile", "sec-ch-ua-platform",
	"sec-fetch-dest", "sec-fetch-mode", "sec-fetch-site", "upgrade-insecure-requests"}

func decide(r *http.Request, path string) string {
	var token string
	if c, err := r.Cookie("_kz"); err == nil {
		token = c.Value
	}
	headers := map[string]string{}
	for _, name := range forwarded {
		if v := r.Header.Get(name); v != "" {
			headers[name] = v
		}
	}
	body, _ := json.Marshal(map[string]any{
		"ip": clientIP(r), "user_agent": r.UserAgent(), "headers": headers, "token": token, "path": path, "method": r.Method,
	})
	ctx, cancel := context.WithTimeout(r.Context(), 200*time.Millisecond)
	defer cancel()
	req, _ := http.NewRequestWithContext(ctx, "POST", "https://korzen.dev/v1/decide", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KORZEN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Korzen-Deadline-Ms", "200") // how long this call waits: the decision takes half
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return "allow" // fail open
	}
	defer res.Body.Close()
	var ans struct{ Action string `json:"action"` }
	if res.StatusCode != 200 || json.NewDecoder(res.Body).Decode(&ans) != nil {
		return "allow"
	}
	return ans.Action
}

// clientIP is the visitor's address as your edge reports it. Trust only a header your own proxy
// or CDN sets: CF-Connecting-IP behind Cloudflare, the last X-Forwarded-For entry your load
// balancer appended; with none, the connection's address.
func clientIP(r *http.Request) string {
	if ip := r.Header.Get("CF-Connecting-IP"); ip != "" {
		return ip
	}
	host, _, _ := net.SplitHostPort(r.RemoteAddr)
	return host
}

import os, requests

korzen = requests.Session()  # one per process: it keeps the connection open

# The headers Bot Protection reads: those one browser build sends alike, and Accept-Language.
FORWARDED = ["accept", "accept-encoding", "accept-language", "sec-ch-ua", "sec-ch-ua-mobile", "sec-ch-ua-platform",
             "sec-fetch-dest", "sec-fetch-mode", "sec-fetch-site", "upgrade-insecure-requests"]

def decide(request, path):
    try:
        r = korzen.post("https://korzen.dev/v1/decide", timeout=0.2,
            headers={"Authorization": f"Bearer {os.environ['KORZEN_API_KEY']}",
                     "Korzen-Deadline-Ms": "200"},  # how long this call waits: the decision takes half
            json={"ip": request.remote_addr, "user_agent": request.headers.get("User-Agent"),
                  "headers": {h: request.headers[h] for h in FORWARDED if h in request.headers},
                  "token": request.cookies.get("_kz"), "path": path, "method": "POST"})
        return r.json()["action"] if r.status_code == 200 else "allow"
    except Exception:
        return "allow"  # fail open