docs: correct the bot-score claims behind the browser poller #99

2026-08-12T09:29:51+07:00

sulthan commented

2026-08-12 09:29:51 +07:00

Docs only. No code changes - git diff origin/main --stat touches five Markdown files and adds one research note.

What was wrong

Several docs explained Cloudflare challenges as a "bot score" that our request rate could worsen. That mechanism does not exist on these sites.

Researched live on 2026-08-12 against Cloudflare's own documentation and blog plus RFC 9309 - 22 primary pages, every claim carrying a source URL and read date, seven areas explicitly marked Not publicly documented. The note is docs/research/cloudflare-bot-scoring-and-poll-cadence.md.

The 1-99 bot score is Enterprise Bot Management only. A free-plan zone has no score at all; it gets Bot Fight Mode, which matches signatures (headless browsers, cloud-hosting IPs).
No per-IP request rate is documented as an input to challenge issuance. Volume is policed by Rate Limiting Rules, a separate opt-in product: one rule, IP-only counting, 10-second windows on Free. Published DDoS thresholds are ~1,000 errors/sec.
cf_clearance defaults to 30 minutes, so every cadence at or above 1 hour re-solves the challenge anyway. Cadence changes how many ~4s solves happen per day and nothing else.
The documented risk is fingerprint quality, which this repo already solved (real Chrome, stock UA, non-UTC clock).

What changed

File	Correction
`AGENTS.md`	The block is per-zone configuration plus request fingerprint, not IP reputation. comix.to turning its gate on 2026-08-12 is the worked example. Residential egress avoids the cloud-hosting-IP signature rather than earning a better score. The UTC measurement stands; its mechanism is now marked undocumented.
`backend/AGENTS.md`	Says why `_BROWSER_COOLDOWN` is longer: cost, not safety.
`docs/adr/0003`	Dated correction - the sites do not "bot-score" the VPS IP. Decision stands on its sweep-depth argument.
`docs/adr/0006`	Dated correction - no score to be better at. Decision stands on VPS memory.
`DEPLOY.md`	A red kagane smoke run means the Site's settings or this Chrome's fingerprint moved, not "Cloudflare's scoring".

ADRs got dated Corrected 2026-08-12: paragraphs rather than silent rewrites - the record of what was decided stays intact, only the wrong mechanism is retracted.

Deliberately not in this PR

The 6h browser cooldown is unchanged. I had lowered it to 1h and reverted that; cadence is a behaviour change and belongs with the comix work in #98, not in a docs correction.
Two code comments still carry the myth: backend/main.go:83-84 ("a hammer against sites that are already bot-scoring us"). Left alone to keep this diff docs-only.

Related: #98.

Docs only. No code changes - `git diff origin/main --stat` touches five Markdown files and adds one research note. ## What was wrong Several docs explained Cloudflare challenges as a "bot score" that our request rate could worsen. That mechanism does not exist on these sites. Researched live on 2026-08-12 against Cloudflare's own documentation and blog plus RFC 9309 - 22 primary pages, every claim carrying a source URL and read date, seven areas explicitly marked `Not publicly documented`. The note is `docs/research/cloudflare-bot-scoring-and-poll-cadence.md`. - The 1-99 bot score is **Enterprise Bot Management only**. A free-plan zone has no score at all; it gets Bot Fight Mode, which matches *signatures* (headless browsers, cloud-hosting IPs). - **No per-IP request rate is documented as an input to challenge issuance.** Volume is policed by Rate Limiting Rules, a separate opt-in product: one rule, IP-only counting, 10-second windows on Free. Published DDoS thresholds are ~1,000 errors/sec. - **`cf_clearance` defaults to 30 minutes**, so every cadence at or above 1 hour re-solves the challenge anyway. Cadence changes how many ~4s solves happen per day and nothing else. - The documented risk is **fingerprint quality**, which this repo already solved (real Chrome, stock UA, non-UTC clock). ## What changed | File | Correction | |---|---| | `AGENTS.md` | The block is per-zone configuration plus request fingerprint, not IP reputation. comix.to turning its gate on 2026-08-12 is the worked example. Residential egress avoids the cloud-hosting-IP *signature* rather than earning a better score. The UTC measurement stands; its mechanism is now marked undocumented. | | `backend/AGENTS.md` | Says why `_BROWSER_COOLDOWN` is longer: cost, not safety. | | `docs/adr/0003` | Dated correction - the sites do not "bot-score" the VPS IP. Decision stands on its sweep-depth argument. | | `docs/adr/0006` | Dated correction - no score to be better at. Decision stands on VPS memory. | | `DEPLOY.md` | A red kagane smoke run means the Site's settings or this Chrome's fingerprint moved, not "Cloudflare's scoring". | ADRs got dated `Corrected 2026-08-12:` paragraphs rather than silent rewrites - the record of what was decided stays intact, only the wrong mechanism is retracted. ## Deliberately not in this PR - **The 6h browser cooldown is unchanged.** I had lowered it to 1h and reverted that; cadence is a behaviour change and belongs with the comix work in #98, not in a docs correction. - **Two code comments still carry the myth**: `backend/main.go:83-84` ("a hammer against sites that are already bot-scoring us"). Left alone to keep this diff docs-only. Related: #98.

sulthan added 1 commit 2026-08-12 09:29:52 +07:00

docs: correct the bot-score claims behind the browser poller 1f5d0695ad

Every doc statement that explained a Cloudflare challenge as a "score"
was wrong. Researched against Cloudflare's own docs on 2026-08-12
(docs/research/cloudflare-bot-scoring-and-poll-cadence.md, 22 primary
pages plus RFC 9309): the 1-99 bot score is Enterprise Bot Management
only, free-plan zones get Bot Fight Mode signature matching and no score
at all, and no per-IP request rate is documented as an input to
challenge issuance. cf_clearance also expires in 30 minutes, so every
cadence at or above 1h re-solves the challenge regardless.

Docs only - no behaviour change. The 6h browser cooldown stays; its
justification is now cost (a serialized single-tab solve costs seconds,
a plain read costs one request), not a risk reduction nothing documents.

- AGENTS.md: the block is per-zone configuration plus request
  fingerprint, not IP reputation; comix.to turning its gate on
  2026-08-12 is the example. Residential egress avoids the
  cloud-hosting-IP signature rather than earning a better score. The UTC
  measurement stands but its mechanism is marked undocumented.
- backend/AGENTS.md: states why the browser cooldown is longer.
- ADR-0003, ADR-0006: dated corrections rather than rewrites. Both
  decisions stand on their other arguments (sweep depth, VPS memory).
- DEPLOY.md: a red smoke run means the Site's settings or this Chrome's
  fingerprint moved, not that "Cloudflare's scoring" did.

sulthan merged commit 17ee0bd3f8 into main

2026-08-12 09:32:08 +07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sulthan/mangaBookmark#99