Everything the bot does today is reactive: Mastodon creates the account,
the account.created webhook arrives, we classify the signup IP and email
domain, and then we block the range and suspend what already exists.
POST /api/reputation is the pre-emptive half. A caller asks about an IP
and/or email domain; we classify it, record the answer, register the
matching Admin::IpBlock / EmailDomainBlock, and only then return. A
caller that runs its own block lookup immediately afterwards therefore
finds a block that did not exist when its request started. The intended
caller is Mastodon's signup path, which does exactly that.
It writes, so unlike /api/blocks it is authenticated and refuses to serve
without a key (REPUTATION_API_KEY): an unauthenticated endpoint that
installs IP blocks is a denial-of-service lever, so there is no open mode.
Notes on the pieces that aren't obvious:
- REPUTATION_API_MAX_LOOKUPS_PER_HOUR caps *fresh* provider lookups. The
caller hits this on every view of the signup form, not just on
submission, so without a ceiling a crawler walking /auth/sign_up from a
new range each time would set our ipapi.is bill. Over budget we answer
"unknown" and install nothing -- never "flagged". Cache hits are free
and uncounted, and the webhook path never spends from this budget.
- Blocks installed here are recorded in their own table, keyed by the
CIDR/domain rather than by account (there is no account yet), and are
folded into /api/blocks and the reconcile pass so neither one
under-reports as blocking shifts to the pre-signup path. The published
entry shape is unchanged; a range blocked before anyone signed up from
it simply reads "signups": 0.
- A repeat query for an already-installed block skips the Mastodon round
trip. This runs on a live signup request, so that is saved latency.
Publishes the IP ranges and email domains the bot has auto-blocked as
JSON: GET /api/blocks, /api/blocks/ip-ranges, /api/blocks/email-domains,
each taking an optional ?limit=N.
The endpoints are unauthenticated, so BLOCKS_API_ENABLED gates them and
defaults to false — with it unset the paths 404 as if they didn't exist.
Publishing which ranges are already blocked also tells a spam signup
which ones to avoid, so opting in is a per-deployment call; yttrx.com
sets it true in the box's .env.
Responses assert only that a block exists: the blocked range/domain, a
signups count, and first/last seen. No account identifiers, and none of
the ipapi.is or check-mail.org classification that drove the decision —
republishing a paid reputation feed's verdicts on an open endpoint would
be redistributing their data rather than ours.
Supporting changes:
- signup_ip gains a block_cidr column (migrated in place on open) so the
API reports the network actually blocked rather than the signup IP.
Rows predating it fall back to that IP's /32 or /128, which is exactly
what was registered before range-blocking started 2026-07-15.
- register_ip_block / register_email_domain_block now return whether the
block landed, and the caller only marks it registered on success, so a
failed POST is no longer published as a block that exists.