BotRampart

Docs · Architecture

Components, contracts and the reasons behind them.

The reference for people who will build or operate BotRampart: what each component does, where it runs, what crosses each boundary, how data is laid out, and what the first build includes.

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

ComponentDoesRunsLicenceFirst build
Browser SDK @botrampart/browserSolves 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 originApache-2.0yes
Backend SDKIssues and verifies the session token, keeps budgets and mint buckets, evaluates policy, mounts /_br, syncs with Core.Inside your app processApache-2.0Node Python, Java
CoreChallenge service, sync API, hot rollups, replay cache, policy store, state builder, decision client.Cloudflare Workers, or one containerAGPL-3.0, commercial licence availableyes
LakeRollups, decisions, challenges, states, answers, directives, policy versions.Your R2, S3, MinIO, GCS or Azure BlobOpen formatsyes
AgentExplains decisions, reports, later proposes policy changes. Slack, email, console.One container in your infrastructureAGPL-3.0explain + digest
ConsolePolicy, path costs, live budgets, decision search, keys, audit log.Static app served by CoreAGPL-3.0read-only
CLI brGenerates install files, checks an install, replays a session against a policy, rotates keys.Your machine or CIApache-2.0init, doctor
Log packVector configurations for nginx, ingress-nginx, ALB, CloudFront and Cloudflare logs; cohort rollups for traffic that never reaches the SDK.Vector in your infrastructureApache-2.0later

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:

ProductServer-side checkDocumented failure behaviour
Cloudflare TurnstilePOST the token to siteverify; valid 300 seconds, intended for single use1The integrator's choice
DataDomeModule sends request metadata to the Protection APIMissing response header: treated as allowed2
HUMAN (Akamai EdgeWorker enforcer)Decrypts its risk cookie; may call the Risk APIRisk API timeout, 1,000 ms by default, then the request passes3
Vercel BotIDcheckBotId() on routes declared in the clientAn undeclared route fails the check4
BotRampart (proposed)Verifies the cookie in memory; tier 2 attestations with Core's public keyKeeps 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:

NeedPortOn CloudflareIn one container
Configuration, keys, policy versionsConfigStoreD1, KV as read cacheSQLite or Postgres
Hot rollups, baselines, replay cache, mint countersSiteShardSQLite-backed Durable Objects, one shard per siteSQLite file or Valkey
Lake writesS3 API onlyR2S3, MinIO, GCS
Ingest bufferenqueue(batch)QueuesIn-process queue
Five-minute looponWindowClose()Cron TriggerTimer
Decision modelDecisionProviderHTTPSHTTPS 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
TableKey columnsRetention (proposed)
session_rollup_1mminute, sid_hash, uid_hash, path_class, requests, cost, s2xx, s4xx, s5xx, tier, credits_end, prefix, asn, country90 days
decisionsts, ref, sid_hash, action, tier, rule_id, policy_version, risk_score, credits, cost, path_class, ai_answer_id, outcome13 months
challengests, sid_hash, tier, method, difficulty, solve_ms, result, grant13 months
ui_signalssid_hash, event counts, first_input_ms, automation_flag, viewport_class30 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

ToolDoesGuardrail
explain_decision first buildRule, inputs, budget and model answer behind a reference, session or login IDFixed query
session_timeline first buildMinute-by-minute spend, tiers and challenges for one sessionFixed query
replayRuns a policy version against a session's rollupsSame evaluator as the SDKs
metric laterNamed queries: top spenders, pass rates, spend by path classCurated list
sql laterRead-only SQL for the restOne SELECT, row, size and time caps
propose_policy_change laterA pending diff with a reason and a simulationA 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

ThreatControlWhat remains
Clients minting new sessionsTier 0 allowance; mint buckets per IP, prefix and ASN; harder puzzles under pressureLarge residential proxy pools
Solved cookies handed to other clientsBudget is per session, so sharing a cookie shares one budget; soft binding; 30-minute tokensReuse within one network and browser family until the budget is spent
Paid solversCredit, not clearance; halving grants; daily ceilingBounded throughput per session for an operator who pays
Native proof-of-work solversMemory-hard puzzles, difficulty from risk; proof-of-work treated as a minting cost onlyStill cheap for a funded attacker
Real browsers under automationBudgets apply whoever drives the browserIndistinguishable from a person until the budget runs out, which is the intent
Prompt injection into the model or agentNo visitor text in the state; closed outputs; rules hold the gate; agent cannot writeTraffic shaped to look like an organic spike; baselines are clamped so they cannot be walked up quickly
Compromised script deliveryFirst-party hosting, integrity hash, signed releases8Compromise of your own origin
Stolen site secretKey IDs, overlapping rotation, separate keys per purposeTokens minted until rotation
Core outageCore is not in the request path; static mode keeps tier 1, budgets and rulesNo escalation above tier 1 while Core is down

First build and after

PhaseBuildsProves
0 · Decide, 2 weeksHosting 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 weeksBrowser 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 weeksModel 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 weeksOpen 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.

  1. 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.
  2. 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.
  3. 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.
  4. Vercel docs: Get started with BotID. Not adding the protected route to <BotIdClient /> will result in checkBotId() failing. Checked 2026-11-18.
  5. Cloudflare docs: Workers pricing. minimum charge of $5 USD per month for an account Checked 2026-11-18.
  6. GitHub: rivet-dev/open-orange. Run Cloudflare Workers anywhere: AWS, Google Cloud, Azure, or your own servers. Checked 2026-11-18.
  7. Cloudflare docs: R2 pricing. There are no charges for egress bandwidth for any storage class. Checked 2026-11-18.
  8. 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.
  9. BotRampart experiment 1: verify and charge (experiments/verify-bench.json in this repository). "verify_p99_us": 2.58, Checked 2026-11-18.