Bot defence

Score the sign-in, sign-up, reset and invite doors in process, challenge or refuse bots with a proof-of-work, and stop SMS and WhatsApp pumping before a message is paid for.

bots:
  mode: enforce
  doors:
    sign-up: { challenge: 30, deny: 80, disposable-email: deny }
    contact: { path: /api/contact, form: true }
  challenge: { driver: pow }
  pumping: { per-prefix: { max: 10, per: 1h }, countries: [IN] }
  crawlers: [googlebot]
  block: [198.51.100.0/24]

import { bots } from "mainsdk/bots";

// a hidden token and a honeypot field for a contact form; the door is declared in main.yaml
const { html } = bots.formFields();

// before you send a code yourself
await bots.guardSend("+91 98765 43210");   // throws MAIN-BOT-0007 (429) when refused

bots:
  driver: pow

Quick start

bots:
  mode: enforce
  doors:
    sign-up: { challenge: 30, deny: 80, disposable-email: deny }
    contact: { path: /api/contact, form: true }
  challenge: { driver: pow }
  pumping: { per-prefix: { max: 10, per: 1h }, countries: [IN] }
  crawlers: [googlebot]
  block: [198.51.100.0/24]

import { bots } from "mainsdk/bots";

// a hidden token and a honeypot field for a contact form; the door is declared in main.yaml
const { html } = bots.formFields();

// before you send a code yourself
await bots.guardSend("+91 98765 43210");   // throws MAIN-BOT-0007 (429) when refused

Configuration

A request to a door is scored from 0 (person) to 100 (bot). Below the door's challenge score it goes through. At or above it, the answer is 403 MAIN-BOT-0001 with a challenge member; the browser solves it with mainsdk/bots/client (fetchWithChallenge does this and retries once). At or above deny, it is 403 MAIN-BOT-0002. The reasons are in the log and the bot.challenged or bot.denied security event, never in the response.

The built-in doors are sign-in, sign-up, reset, whatsapp and invite, mapped onto the auth routes. Declare your own with doors.<name>.path. mode: observe lets every request through and logs what would have happened. With no bots section, nothing is scored.

Calls

Drivers

What you get

• A request is scored from its headers, a form token and counters in process, with no cookie, no script and no fingerprint
• A refusal never says why; the reasons are in the log and the security event
• No raw address, email or phone number is stored, and each counter holds at most 10,000 keys
• A store outage never blocks a sign-in; the counters fall back to local

Errors and checks

Each code's cause and fix is in check codes. mainsdk check runs the bots gate.

Swapping drivers

challenge.driver is pow (the default), turnstile or hcaptcha. A provider needs sitekey and a secret:NAME reference for its secret; the page's CSP lists the provider's hosts only when the driver is set, and the token is verified through http.fetch with a 2 s timeout and no retry. If the provider does not answer, the built-in challenge is used instead of letting the request through.

bots:
  challenge:
    driver: turnstile
    turnstile: { sitekey: 0x4AAAA, secret: "secret:TURNSTILE_SECRET" }

Testing

Call bots.check(new Request(url, { method: "POST", headers })) and read action, score and reasons. Set mode: observe first in a real app. The proof-of-work helpers solveChallenge and encodeSolution from mainsdk/bots solve a challenge in a test.

Next

• Use bot defence in your app
• Sign-in and sessions