Build it. Ship it. Keep it yours.
antiRea is a server-side TypeScript library that meters dataset access per identity and flags coordinated bot abuse - bulk extraction crews, scheduler-driven herds, seat squatting. Advisory only: it flags, you decide.
Website - Threat model - Limitations - Changelog
English - Tiếng Việt - 中文 - Español
Cloning tools can watch your app's pages, bundles and traffic, then rebuild what they saw. You cannot hide code a browser has already received - so antiRea defends the other side: the data itself.
Unprotected. Anyone with an account can take your data home. In our tests, one account walked away with the entire 10,000-record dataset in under 200 requests. Quietly. Nothing unusual in the logs.
Protected. Real users notice nothing. Each identity can only ever receive a capped slice - 20% of the dataset in our test setup - so copying stops being an export and becomes an identity problem. Split the work across many accounts, and the herd detector flags the coordination.
- The run that took everything with 1 account was stopped at 5%.
- A scripted crew that insisted on finishing needed 25 identities and about 19 minutes - and was flagged on the way.
Unprotected, your data leaves whole, free and invisible. Protected, it leaves in slices, at a cost, and on the record.
Full numbers: Measured results.
npm install @dannyphan190/anti-reaNode.js 20+. Zero runtime dependencies. Also available via GitHub Release.
Request quotas cap speed. A record budget caps how much of the dataset one identity can ever receive, however politely it asks.
import { createRecordBudget, createHerdDetector } from "@dannyphan190/anti-rea";
// One identity receives at most 2,000 distinct records per day.
const budget = createRecordBudget({ maxDistinctPerWindow: 2_000 });
const herd = createHerdDetector({
onFlag: snap => { /* snap.band: "budget_cut_supported" | "graduated_only" */ },
});
// Check before the handler runs:
if (!budget.check("account:123", 1).allowed) { /* return 429 */ }
// Then record what the response actually served:
budget.consume("account:123", recordIdsServed);
herd.observe({ type: "list", identity: "account:123", ip: serverSeenIp, recordIds: recordIdsServed });Use the same identity string (account:<id>) in both, and a herd
flag can feed straight into a budget cut via applyHerdLadder().
Five groups. Start at the top; each layer is independent.
| Group | What it does, in plain words | Main pieces | Honest limit |
|---|---|---|---|
| Meter | Caps how much data any one identity can ever receive, and how fast | Record budget (createRecordBudget), quota and pagination guard (createQuotaGuard), priced exports (createExportGuard), session cursors (mintCursor / verifyCursor), flow scoring (createFlowScorer) |
Attackers can rotate identities - pair with real signup cost on your side |
| Surface | Controls WHAT may cross the boundary: fields a response never declared (the password hash in a profile payload) and fields a request was never offered (the role in a profile update) |
Field guard, both directions (createSurfaceGuard) - built-in sensitive/privileged denylists plus per-route schema allowlists; advisory by default, strip or block only when the host says so |
Sees field names, not values or ownership - a declared field filled with someone else's data is still your authorization logic's job |
| Ownership | Spots one identity sweeping through other people's objects (the BOLA/IDOR walk - sequential ids, random ids, or a slow spread over hours) and reports it with evidence | Ownership probe (createOwnershipProbe) - per-identity distinct-owner ratio over rolling windows (1 h by default, add 6 h for slow sweeps), public routes exempt, incremental state with O(1) verdict reads; advisory only |
A flag is a shape, not proof - authorization stays your job, and a sweep under the floors or concentrated on few owners is out of reach |
| Watch | Spots coordination: many identities quietly tiling your dataset, probing decoys, or crowding a room | Herd detector (createHerdDetector + applyHerdLadder), phase signals (createHerdPhaseSignal, createActivityPhaseSignal), room guard (createRoomGuard), canary traps and decoys (handleCanaryTrapRequest, createCanaryMaze, createDecoyMirage), automation telemetry (detectAutomationSignals), source-map hygiene (verify-build.py / run-audit.cjs), volume-rank rule (applyVolumeRankRule), empirical-mix calibration (selectEmpMixThreshold), session-timing features (computeHoldTypeFeatures / createHoldTypeScorer), early-minimal occupancy signal (createOccupancyEarlyMinimalSignal) |
Detection is not enforcement - low-tiling herds get a graduated response, and one adaptive herd was flagged yet still finished |
| Prove | Pins down what a verdict means: which config produced it, who actually signed, what may ground a consequence | Config provenance (createConfigProvenance), Web Bot Auth verification (createWebBotAuthVerifier), step-up proofs (issueStepUpProof, createStepUpProofVerifier), step-up consequence shaping (createStepUp402Responder), evidence roles (evidentiaryRoleOf, auditEvidencePack, decorateSignalResult) |
A verified signature is identity, not authorization - your auth checks stay exactly as they are |
| Trace | Optional client-side aids for leaks and replay | Context-bound envelopes (encryptPayload / decryptPayload, createInMemoryReplayGuard), forensic watermark (mountForensicWatermark), preference declaration log (createDeclarationLog) |
Traceability, not access control - overlays can be cropped, and the browser holds its own context |
Recommended order: quota guard first (see below), then the record budget, then herd detection.
Method, in short. We test against Ledgerly, a synthetic SaaS
holding 10,000 records behind 120 accounts, run twice: unprotected,
and the same app with antiRea wired in. Attack runs are driven by
REA 6.8.0 (rea-agents) and by general-purpose agents following the
standard clone workflow; polite-user runs measure the cost to
legitimate traffic. An independent benchmark was published in
issue #1 - most claims
held up, and the gaps it found are fixed and in the changelog.
Full method and per-layer table: docs/EVIDENCE.md.
| Layer | Headline result |
|---|---|
| No protection (baseline) | The full 10,000-record dataset leaves in 160-193 requests |
| Record budget | One identity is capped at exactly 20% of the dataset |
| Herd detector + CUSUM evidence | REA-style identity rotation stopped at 5%; an adaptive crew needed 25 identities and ~19 minutes |
| Declared cohort ceiling | The cohort union stopped at exactly 600 records, zero served past the cap |
| Legitimate users | Declared team 1,200/1,200 with zero friction; polite users zero consequences |
| Action budget (lab) | Feature-abuse herd completed 16/80 operations (20%); ordinary users 48/48, zero consequences |
| Advisory signals (lab) | Five slow-shape signals: 0-1.67% false flags on legitimate traffic - per-signal numbers in the full table |
What this adds up to. The casual one-shot clone is gone. Bulk extraction becomes an identity problem: every extra slice costs another account and more visibility. It does not stop a determined, well-resourced rebuilder - and the real price of an identity (signup friction, verified accounts, payment) is set by you, which is why budgets are per identity and herd flags distinguish "cut the budget" from "step up scrutiny".
antiRea ships an official MCP server for AI agents:
@dannyphan190/anti-rea-mcp
(source), built on the
official @modelcontextprotocol/sdk, speaking MCP over stdio.
It exposes the library's eight advisory signal kinds as six tools -
list_signals, create_signal, observe, observe_reference,
evaluate, close_signal - so an agent can open a signal session,
feed it events and read the verdict.
{
"mcpServers": {
"anti-rea": {
"command": "npx",
"args": ["-y", "@dannyphan190/anti-rea-mcp"]
}
}
}It is an evaluation and demo channel. Production protection still belongs in-process, in your own app.
Three fixes harden the bulk capability keys, and the entire remaining PASS-LAB backlog graduates. All new modules are opt-in; no default changes.
- GATEKEY fixes (
createBulkAccessKeyAuthority): claiming a key is now idempotent - keys minted into a fresh identity during a refill were previously stranded (measured: 6 of 6 stranded claims never received a token; 0 of 6 after the fix). The anonymous queue lane now fails closed when no step-up proof verifier is configured: before the fix any non-empty proof string was accepted, and proof sybils took all 6 anonymous keys per day while honest waiters starved. The epoch permutation now draws from a counter-mode HMAC stream instead of a 32-bit seed - a full 2^32 scan rebuilt all 67 blocks from one observed block before the fix (0 of 67 after). The step-up gate insidemintkeeps its documented default, pinned by the frozen GK-G6 cell. - 107 PASS-LAB candidates built: the whole measured backlog ships as opt-in modules across 14 families (MGH, WDN, NHS, RSP, ABE, ABS, ABP, AC, LCP, ABG, CS, MISC, R14, RECOMB), each under its frozen registration and false-positive budget, several in deliberately restricted forms where the lab form failed a house rule. Three candidates were excluded after genuine upgrade attempts, with the measurements printed in the changelog: RSP-13, AC-10 and AC-17.
- Held for farm validation (not in this release): AN-02, RECOMB-01, RECOMB-03 and C26 are built but stay out until the farm holdout validation resolves them; no numbers are claimed for them yet.
1661 tests: 1659 passed, none failed, 2 skipped.
Earlier releases: see the Changelog.
Server-side quotas and pagination bounds, enforced per account,
API key and IP. Returns HTTP 429 with Retry-After, and logs
structured events for operators.
import { createExpressQuotaMiddleware } from "@dannyphan190/anti-rea";
app.use("/api/", createExpressQuotaMiddleware({
trustedIpHeader: "cf-connecting-ip",
tiers: {
anonymous: { maxRequests: 30, windowMs: 60_000, maxPageSize: 25, maxPage: 5 },
free: { maxRequests: 60, windowMs: 60_000, maxPageSize: 50, maxPage: 20 },
pro: { maxRequests: 300, windowMs: 60_000, maxPageSize: 200, maxPage: 100 },
},
resolveIdentity: req => ({
accountId: req.headers.get("x-verified-account") ?? undefined, // from your server auth
apiKeyId: req.headers.get("x-verified-key-id") ?? undefined,
tier: "free",
}),
onQuotaExceeded: event => {
console.warn("[quota-exceeded]", event);
},
}));- Canary endpoints - trap routes that log abnormal probing, with path canonicalization so variants cannot slip past. Runnable example: examples/node-canary-server.cjs.
- Signed agents - verify Web Bot Auth (RFC 9421) signatures and key quota policy on a stable identity. Runnable end-to-end demo: examples/web-bot-auth-verify.cjs.
- Python / FastAPI - the quota guard ported with identical
tiers,
429semantics and pagination bounds, held to the same test contract: examples/python-fastapi. - Shared cohort ceilings and the CUSUM evidence engine - transactional reservation across a whole declared cohort, with protected cohorts whose telemetry accrues but never draws a consequence: semantics in docs/LIMITATIONS.md.
- Declared-cohort union budget - the single-process form of the
same law: one
createRecordBudgetkeyed by a host-declared cohort id, so identity rotation inside a declared cohort stops diluting the cap. Pattern with runnable verification: examples/declared-cohort-budget. - Watermark and envelopes - see the Trace group above; never embed a person's email, IP or raw user ID in watermark pixels.
- It cannot hide code delivered to a browser, or prevent anyone from inspecting what their own browser downloaded.
- It cannot stop a determined, well-resourced rebuilder. It makes bulk copying slow, costly and visible instead.
- The evidence engine's built-in tables were fitted on lab traces,
not a real user population, and are labelled
uncalibrated: truewherever they are mentioned. See the calibration pilot below. - Client-side pieces are traceability aids, not access control.
- No client-side bot-blocking tricks and no prompt injections: they do not hold up, and they are not ethical controls. See docs/REFERENCES.md.
Full list: docs/LIMITATIONS.md.
The repo ships a Playwright harness that runs a synthetic SaaS
(Northstar: dashboard, customer search, lead creation, CSV
export, chart views) in baseline (:4173) and protected (:4174)
modes, across Chromium, Firefox and WebKit.
npm install
npm run build && npm run benchmark:build-sdk
python -m pip install playwright
python -m playwright install chromium firefox webkit
python benchmark/run_all.py --browsers chromium,firefox,webkit --iterations 5Working on the repo itself: npm run check compiles, runs 1661
automated tests (1659 passing, none failing, 2 skipped) and
performs static checks. Scan a public build before deploying with
node scripts/run-audit.cjs /path/to/dist or
python3 scripts/verify-build.py /path/to/dist.
The one thing this project cannot generate for itself is real
traffic. If you run antiRea (or are evaluating it), run the CUSUM
tripwire in mode: "observe" - crossings are logged, nothing is
restricted - and share the anonymised aggregate snapshots it
emits: cohort sizes, scores, union-record counts.
No raw user data, no record contents, no identifiers. Review and
strip a snapshot before sending; if a field looks identifying,
leave it out and say so. The first real snapshot set is how the
uncalibrated label comes off.
Interested, or want the snapshot format first? Email dannyphan190@gmail.com.
- Threat model - what antiRea assumes about attackers
- Limitations - what it does not do
- Evidence - full measured results and method
- Legal and privacy notes
- Deep dives: v2.9.0 - v2.8.1 - v2.8.0
- v2.9.1 deep dive
- v2.9.2 deep dive
- Changelog
Read CONTRIBUTING.md and SECURITY.md before opening a pull request or a vulnerability report.
Project funding: Support the maintainer (optional; never necessary to use).