Design, not product. From the architecture plan of 16 November 2026. Schemas, thresholds and footprints are proposals. The wire contract is the OpenAPI spec; where this page and the spec differ, the spec wins.
Components
| Component | Does | Runs | Licence | First build |
|---|---|---|---|---|
Browser SDK @botrampart/browser | Solves proof-of-work in a Web Worker, collects interaction counts, renders challenges, retries a request after one. Target under 15 kB compressed, no dependencies. | Visitor's browser, served from your origin | Apache-2.0 | yes |
| Backend SDK | Issues and verifies the session token, keeps budgets and mint buckets, evaluates policy, mounts /_br, syncs with Core. | Inside your app process | Apache-2.0 | Node Python, Java |
| Core | Challenge service, sync API, hot rollups, replay cache, policy store, state builder, decision client. | Cloudflare Workers, or one container | AGPL-3.0, commercial licence available | yes |
| Lake | Rollups, decisions, challenges, states, answers, directives, policy versions. | Your R2, S3, MinIO, GCS or Azure Blob | Open formats | yes |
| Agent | Explains decisions, reports, later proposes policy changes. Slack, email, console. | One container in your infrastructure | AGPL-3.0 | explain + digest |
| Console | Policy, path costs, live budgets, decision search, keys, audit log. | Static app served by Core | AGPL-3.0 | read-only |
CLI br | Generates install files, checks an install, replays a session against a policy, rotates keys. | Your machine or CI | Apache-2.0 | init, doctor |
| Log pack | Vector configurations for nginx, ingress-nginx, ALB, CloudFront and Cloudflare logs; cohort rollups for traffic that never reaches the SDK. | Vector in your infrastructure | Apache-2.0 | later |
Core is AGPL-3.0 because it runs as a separate service, so copyleft rarely touches your code, while a provider that hosts a modified Core must publish its changes. Whether Apache-2.0 throughout would serve adoption better is an open decision.
The request path
Requests travel browser, edge, app server exactly as today. The backend SDK is a framework filter in your process; vendors ship the same thing as a "server-side module". What BotRampart avoids is the network call per request that most of them make:
| Product | Server-side check | Documented failure behaviour |
|---|---|---|
| Cloudflare Turnstile | POST the token to siteverify; valid 300 seconds, intended for single use1 | The integrator's choice |
| DataDome | Module sends request metadata to the Protection API | Missing response header: treated as allowed2 |
| HUMAN (Akamai EdgeWorker enforcer) | Decrypts its risk cookie; may call the Risk API | Risk API timeout, 1,000 ms by default, then the request passes3 |
| Vercel BotID | checkBotId() on routes declared in the client | An undeclared route fails the check4 |
| BotRampart (proposed) | Verifies the cookie in memory; tier 2 attestations with Core's public key | Keeps enforcing the last synced policy; per-route open or closed if the SDK itself errors |
Session token
Set-Cookie: __br_s=br1.<payload>.<signature>; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=604800
payload (base64url JSON)
{ "v": 1, "sid": "k3Jv9s0QxT2mA7cR1uYb5w", // 128 random bits, the only identifier
"iat": 1794823500, "exp": 1794825300, // 30-minute token, renewed on use
"ses": 1795428300, // session ends after 7 days at most
"tier": 1, "tx": { "2": 1794827100 }, // highest tier held, expiry of higher tiers
"bind": { "ua": "chrome-131", "net": "AS64512" }, // soft binding: a mismatch drops to tier 0
"uid": "9f2c…", "kid": "s3" } // keyed hash of login ID; signing key id
signature = HMAC-SHA256(site_secret[kid], "br1." + payload)
Soft binding records the browser family and the network's ASN. A mismatch does not block; it asks for a new proof-of-work. Binding to the exact IP would break mobile users who roam. A session seen from many networks in a short window raises its risk score.
Sync
The only regular conversation between your app and Core. Each instance posts counters and events; Core answers with policy, directives, revocations and the combined mint pressure.
One sync exchangesyncInstance
POST /v1/sync
Authorization: Bearer <instance key>
{ "instance": "app-7d9f", "policy_version": 12, "since": 1794823500,
"sessions": [ { "sid": "7c1e09a4b2d3", "path_class": "search", "n": 41, "cost": 205, "s2xx": 40, "s4xx": 1, "tier": 1, "credits": 12 } ],
"events": [ { "ts": 1794823561, "type": "decision", "ref": "BR-7F3K2Q", "action": "challenge", "tier": "human", "rule": "over-budget" } ],
"mint": [ { "key": "prefix:203.0.113.0/24", "n": 14 } ] }
200 OK
{ "policy": null,
"directives": [ { "id": "d_01JD…", "match": { "asn_class": "hosting", "session_age": "under_10m", "path_class": "search" },
"set": { "ai.attack": 0.96, "ai.intent": "content_scraping", "ai.action": "human_check", "ai.confidence": 0.64 },
"answer": "a_01JD7K…", "expires": 1794827400 } ],
"revoked": [ "a41b77c2d9e0" ],
"mint_pressure": [ { "key": "prefix:203.0.113.0/24", "multiplier": 4 } ],
"spent": [ { "sid": "7c1e09a4b2d3", "total": 1240 } ],
"next_sync_ms": 5000 }
Core and hosting
Core's load follows sessions and sync ticks, not your request volume, because tokens are verified in your app. For a site with 100 million requests a month, our estimate is about 3 million calls to Core: 2.6 million syncs from 10 instances every 10 seconds, about 0.3 million for escalated challenges, and log rollup copies. That fits inside the 10 million requests the $5 Workers Paid plan includes.5 The session count and escalation rate are assumptions to replace with measurements.
Core is written against Web-standard Request and Response on Hono, with storage behind small interfaces ("ports"), so it runs in three places:
| Need | Port | On Cloudflare | In one container |
|---|---|---|---|
| Configuration, keys, policy versions | ConfigStore | D1, KV as read cache | SQLite or Postgres |
| Hot rollups, baselines, replay cache, mint counters | SiteShard | SQLite-backed Durable Objects, one shard per site | SQLite file or Valkey |
| Lake writes | S3 API only | R2 | S3, MinIO, GCS |
| Ingest buffer | enqueue(batch) | Queues | In-process queue |
| Five-minute loop | onWindowClose() | Cron Trigger | Timer |
| Decision model | DecisionProvider | HTTPS | HTTPS or a local model |
Design rules: no storage write per request, no instance-field state in Durable Objects, idempotent consumers and windows, and no Analytics Engine or Pipelines. A third target is OpenOrange, an Apache-2.0 project from Rivet that runs Cloudflare Workers projects on Node.js in other clouds;6 Core uses only the bindings it marks drop-in, so the same build can move into a customer's own AWS, Google Cloud or Azure account. The plain container stays the default self-hosted distribution because it has the fewest moving parts.
Data layout
s3://<your-bucket>/br/v1/
session_rollup_1m/site=<id>/dt=2026-11-16/hour=10/part-*.parquet from the backend SDK, through Core
challenges/site=<id>/dt=…/part-*.parquet issued, passed, failed, solve time, tier
decisions/site=<id>/dt=…/part-*.parquet every non-allow decision, with its reference
ui_signals/site=<id>/dt=…/part-*.parquet one row per session and per challenge
state_5m/site=<id>/dt=…/<window>-<scope>.json the exact state, numbers and bands
answers/site=<id>/dt=…/<answer_id>.json the exact model answer and cache status
directives/site=<id>/dt=…/part-*.parquet what was published, when it expired
policy/site=<id>/v000012.yaml immutable versions, with approver
| Table | Key columns | Retention (proposed) |
|---|---|---|
| session_rollup_1m | minute, sid_hash, uid_hash, path_class, requests, cost, s2xx, s4xx, s5xx, tier, credits_end, prefix, asn, country | 90 days |
| decisions | ts, ref, sid_hash, action, tier, rule_id, policy_version, risk_score, credits, cost, path_class, ai_answer_id, outcome | 13 months |
| challenges | ts, sid_hash, tier, method, difficulty, solve_ms, result, grant | 13 months |
| ui_signals | sid_hash, event counts, first_input_ms, automation_flag, viewport_class | 30 days |
The lake holds a hash of the session ID and a keyed hash of the login ID, never the cookie. Networks are stored as prefix, ASN and country, not the address. Writing every minute makes many small files, so one scheduled job compacts each closed hour into one file per table and is the only writer. Keeping 1 TB on R2 costs about $15 a month at $0.015 per GB-month, with no egress charge.7
Decision model contract
Core sends the bands of a br.state.v1 state as text with four typed questions, and stores the answer unchanged as br.answer.v1:
{ "attack": { "type": "noul", "noul": 0.96, "confidence": 0.96 },
"risk_level": { "type": "score", "score": 3.1, "confidence": 0.58 },
"intent": { "type": "choice", "choice": "content_scraping", "confidence": 0.88 },
"action": { "type": "choice", "choice": "human_check", "confidence": 0.64 } }
- Inputs are closed. Only named bands and enums, no identifiers, no strings a visitor wrote.
- Outputs are fields.
ai.*with an expiry of at most 60 minutes. The model can raise a tier or lower a budget, never block or allow. - Hysteresis. Escalate when two windows agree; step down after three calm windows.
- Cache.
sha256(site | scope | policy_version | questions_version | model | bands), one hour. A changed band is a new question. - Providers. One interface,
decide(input, questions) → answers: Gemini Decision 1 by default in the cloud, or a self-hosted model so nothing leaves the network. - First build. Shadow mode only.
The agent
| Tool | Does | Guardrail |
|---|---|---|
explain_decision first build | Rule, inputs, budget and model answer behind a reference, session or login ID | Fixed query |
session_timeline first build | Minute-by-minute spend, tiers and challenges for one session | Fixed query |
replay | Runs a policy version against a session's rollups | Same evaluator as the SDKs |
metric later | Named queries: top spenders, pass rates, spend by path class | Curated list |
sql later | Read-only SQL for the rest | One SELECT, row, size and time caps |
propose_policy_change later | A pending diff with a reason and a simulation | A named person approves; separate credential |
The agent reads the lake through DuckDB with a key scoped read-only to br/v1/, uses your own model key or a local model, inherits the asking person's role, and attaches the query, row count, window, policy version and answer ID to every answer. In Slack it runs as an app each customer creates in their own workspace from a shipped manifest, over Socket Mode, so no inbound URL is exposed.
Threats and what remains
| Threat | Control | What remains |
|---|---|---|
| Clients minting new sessions | Tier 0 allowance; mint buckets per IP, prefix and ASN; harder puzzles under pressure | Large residential proxy pools |
| Solved cookies handed to other clients | Budget is per session, so sharing a cookie shares one budget; soft binding; 30-minute tokens | Reuse within one network and browser family until the budget is spent |
| Paid solvers | Credit, not clearance; halving grants; daily ceiling | Bounded throughput per session for an operator who pays |
| Native proof-of-work solvers | Memory-hard puzzles, difficulty from risk; proof-of-work treated as a minting cost only | Still cheap for a funded attacker |
| Real browsers under automation | Budgets apply whoever drives the browser | Indistinguishable from a person until the budget runs out, which is the intent |
| Prompt injection into the model or agent | No visitor text in the state; closed outputs; rules hold the gate; agent cannot write | Traffic shaped to look like an organic spike; baselines are clamped so they cannot be walked up quickly |
| Compromised script delivery | First-party hosting, integrity hash, signed releases8 | Compromise of your own origin |
| Stolen site secret | Key IDs, overlapping rotation, separate keys per purpose | Tokens minted until rotation |
| Core outage | Core is not in the request path; static mode keeps tier 1, budgets and rules | No escalation above tier 1 while Core is down |
First build and after
| Phase | Builds | Proves |
|---|---|---|
| 0 · Decide, 2 weeks | Hosting spike (container against OpenOrange), decision-provider bake-off, proof-of-work format measured on phones, licence and trademark, benchmark harness skeleton. | The open technical choices are made on evidence |
| 1 · First build, 8 weeks | Browser SDK; Node SDK with tokens, budgets, mint buckets, policy file, observe and enforce; Core on Cloudflare and as one container; tiers 0 to 2; decision log; model in shadow; agent explanations and digest in Slack; init and doctor. | Request economics works on a real site, and "why was this user challenged" is answered from Slack |
| 2 · Complete the loops, 8 weeks | Model answers enforced; log pack; Python and Java with the conformance suite; console policies page with simulation; step-up methods; agent metrics, SQL, proposals, email. | The five-minute loop changes outcomes without raising false challenges |
| 3 · Go to market, 12 weeks | Open benchmark; cloud billing; white-label and enterprise features; signed-agent verification; edge adapters and mobile by demand. | Paying customers in the mid-market band |
Exit targets for the first build (proposals): every non-browser tool in the benchmark harness held at tier 0 on costly paths; median tier-1 solve time at base difficulty of 300 ms or less on a mid-range phone; the backend SDK adds under 1 ms at the 99th percentile; fewer than 1 in 200 human sessions sees anything beyond tier 1; under 15 minutes from init to first data; three design partners in observe mode, one enforcing. Durations are planning assumptions for two or three engineers.
We measured the cheapest part of that path on 18 November 2026: verifying the signed cookie and charging the budget in Node took about 1.79 µs per request at the median and 2.58 µs at the 99th percentile, over 300,000 requests across 10,000 sessions on an Apple M4 Pro Mac mini, far inside the 1 ms target; a forged cookie was rejected.9 The benchmark and its output are in the repository; it measures our reference code, not a shipped SDK.
Sources
Every figure from someone else on this page, with the words it rests on. Checked on the date shown; the full ledger is claims.yaml.
- Cloudflare Turnstile docs: Validate the token.
Each token is valid for 300 seconds (5 minutes) after generation. Tokens are intended for single use.
Checked 2026-11-18. - DataDome docs: Protection API (Validate Request).
Fail-open Header missing Ignore it Treat the request as allowed (200) to avoid blocking legitimate traffic due to system errors.
Checked 2026-11-18. - HUMAN docs: Akamai EdgeWorker v4 configuration.
The total time in milliseconds that the Enforcer will wait for the Risk API request to return before timing out and passing the request.
Checked 2026-11-18. - Vercel docs: Get started with BotID.
Not adding the protected route to <BotIdClient /> will result in checkBotId() failing.
Checked 2026-11-18. - Cloudflare docs: Workers pricing.
minimum charge of $5 USD per month for an account
Checked 2026-11-18. - GitHub: rivet-dev/open-orange.
Run Cloudflare Workers anywhere: AWS, Google Cloud, Azure, or your own servers.
Checked 2026-11-18. - Cloudflare docs: R2 pricing.
There are no charges for egress bandwidth for any storage class.
Checked 2026-11-18. - Sansec: Polyfill supply chain attack hits 100K+ sites.
The new Chinese owner of the popular Polyfill JS project injects malware into more than 100 thousand sites.
Checked 2026-11-18. - BotRampart experiment 1: verify and charge (experiments/verify-bench.json in this repository).
"verify_p99_us": 2.58,
Checked 2026-11-18.