Skip to content
dankezoPublic

About

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.

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

200 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

antiRea logo

antiRea

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.

License: MIT npm version CI tests: 1661 total

Website - Threat model - Limitations - Changelog

English - Tiếng Việt - 中文 - Español


The problem, in 30 seconds

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.

Install

npm install @dannyphan190/anti-rea

Node.js 20+. Zero runtime dependencies. Also available via GitHub Release.

Quick start

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().

What's inside

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.

Does it work? Measured results

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".

Also speaks MCP

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.

Latest release

v3.1.0 - GATEKEY hardening and the full PASS-LAB backlog

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 inside mint keeps 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.

First step: the quota guard

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);
  },
}));

More patterns

  • 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, 429 semantics 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 createRecordBudget keyed 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.

Honest limits

  • 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: true wherever 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.

Reproduce the numbers

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 5

Working 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.

Help calibrate it

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.

Documentation

Contributing and security

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).

Featured on antiRea on LaunchNest

About

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.

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages