Bot and inflation strategy

1. Where the checks run

browser ── sdk.js ── GET /v1/c (challenge) ── POST /v1/e (event) ──> edge Caddy ──> gateway
                                                                                   │
                                     JetStream WEB_EVENTS <── checks pass ─────────┘
                                             │
                                          replayer ──> Umami POST /api/send (isbot runs here)

2. Umami’s isbot on the original user agent

3. Server-issued challenge and proof

• Once per page load the tracker calls GET /v1/c?w=<site id>. The gateway answers {w, iat, salt, bits, tag}: iat is server time, salt 16 random bytes, bits the current PROOF_BITS, and tag = HMAC-SHA256(proof_key, w|iat|salt|bits) with a daily key held in the memory KV bucket edge_secrets.
• The tracker finds a nonce such that SHA-256(w|iat|salt|nonce) has at least bits leading zero bits (WebCrypto, batches of 64) and attaches the proof to every event of that page load. The challenge stays in page memory: no cookie, no browser storage.
• The gateway refuses a proof older than ChallengeTTL (6 hours of server time), more than MaxClockSkew (30 seconds) in the future, with bits above MaxProofBits (24), with a wrong tag (which also covers a proof issued for another site, since the tag covers w), or with too little work. The previous day’s key is still accepted inside the 6 hour window.
• PROOF_BITS is 12. It is the highest tested value whose median solve time stays under 150 ms at a 6x CPU slowdown in Chromium, Firefox and WebKit. Because difficulty and time come from the server, difficulty can be raised without a tracker release.

4. Origin and fetch-metadata checks

• Origin. The Origin header must equal one of the site’s registered origins (1 to 20 bare origins under the site’s domain, https only except localhost and 127.0.0.1 for testing). Proved by TestCheckOrigin, TestValidOriginPattern (internal/gateway/origin_test.go) and TestEventChecks subtest wrong origin is 403.
• Fetch metadata. The tracker’s fetch (keepalive, credentials: 'omit', text/plain, no custom headers) produces Sec-Fetch-Site: cross-site (or same-site when the tenant shares the base domain), Sec-Fetch-Mode: cors and Sec-Fetch-Dest: empty in Chromium 156, Firefox 157 and WebKit 27.2 (tests/e2e/specs/headers.spec.ts, recorded in browser-proof.md). The SignalsChecker (internal/gateway/signals.go) refuses any of these headers that is present with another value or repeated. It refuses missing headers only when the user agent claims an engine known to send all three (Chromium 80 or later, Firefox 90 or later, Safari 16.4 or later) and GATEWAY_SECURE_TRANSPORT is true. Android WebViews and non-Safari iOS browsers (; wv), CriOS/, FxiOS/, EdgiOS/, OPiOS/) and EdgeHTML were not measured, so they are never refused for missing headers. Proved by TestSignals and TestSendsFetchMetadata (internal/gateway/signals_test.go).

5. Replay limit

• The limit is per node and in memory. With three edge nodes, one proof can be used up to 3 x PROOF_REPLAY_LIMIT (150) times in total.
• A proof pushed out of the table by 200,000 newer ones starts counting again (internal/gateway/proof.go, NewProofVerifier).
• A gateway restart forgets the table.

6. Same-IP skepticism and quarantine bands

• Fingerprint. The visitor token is vt = hex(HMAC-SHA256(daily_secret, site_id || 0x00 || ip || 0x00 || user_agent)). Distinct user agents from one address, or distinct addresses in one prefix, give distinct tokens.
• Key. Per site and per keyed hash of the truncated address (IPv4 /24, IPv6 /48) under a second daily secret. The network itself is never sent or stored.
• Window and threshold. IPClusterWindow is one hour. When the set for a key reaches IPCLUSTER_THRESHOLD distinct tokens (default 20), the event that brings it to 20 and every later event for that key go to the quarantine band, until one window has passed since the threshold was last reached (internal/gateway/ipcluster.go).
• Across nodes. Each gateway publishes every token that is new to it on the NATS core subject edge.ipcluster (at most IPCLUSTER_THRESHOLD messages per key and window) and merges what peers publish, so all three nodes count the same set. At most 200,000 keys per node (clusterKeys), least recently used evicted. Nothing is persisted.
• Bands. Every site has two Umami websites: the primary (id equals the site id) and a quarantine website. Quarantined events go to the quarantine website. They are never deleted and never mixed into primary numbers. Tenants open the quarantine view through GET /api/sso/umami?site=<id>&view=quarantine, and the per-site counters include quarantined.

False positives on shared addresses

• Carrier-grade NAT. Mobile carriers and some home ISPs put thousands of subscribers behind a few addresses.
• VPN exits and privacy relays.
• Offices and campuses behind one NAT.

One visitor’s volume

7. Rate limits

8. Visibility

9. Limits, stated plainly

• The proof does not prove browser execution. A scripted non-browser client can fetch a challenge, solve 12 bits in milliseconds, and forge Origin, Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest and User-Agent. The gateway then accepts its events. This is tested on purpose: TestEventChecks subtest scripted client with forged headers is accepted (tests/gateway/checks_test.go) posts from a Go client and expects 202. The proof raises the cost of forged traffic and catches naive server posts. It cannot stop a determined actor.
• Real browsers on residential proxies pass every layer. A headless or real browser with an ordinary user agent runs the real tracker, so the proof, Origin and fetch metadata are genuine; isbot does not match; and spreading the traffic over many residential addresses in different prefixes keeps each prefix under IPCLUSTER_THRESHOLD and the prefix rate limit.
• Replay is per node and in memory: up to 3 x PROOF_REPLAY_LIMIT events per proof across three nodes, more if the table evicts the entry or a gateway restarts. Only queued events count; an event refused by a later check gives its use back.
• Volume per visitor is bounded, not stopped. One address and one user agent can send VISITOR_EVENTS_PER_HOUR (600) events an hour per node into the primary band, three times that across three nodes, before the rest go to quarantine (section 6). Page views, custom events and session duration can therefore still be raised by one client within that bound, while visitors stay at 1. A client that rotates its user agent becomes several visitors and then meets same-IP skepticism instead.
• Same-IP skepticism has false positives on shared addresses (section 6) and false negatives for traffic spread over many prefixes.
• API metrics are self-reported. OTLP data comes from the tenant’s own servers; the collector can rate limit and cap cardinality but cannot verify that requests happened (threat-model.md section 3.3).
• No first-party proxy. A tenant must not proxy events through its own server: every event would then be a server-side post from one address, which the proof and same-IP checks treat as suspicious (plan 4.4 step 17).